commit 05fcd08057c828bf6a912c6a87d594531e048ff1
Author: wehub-resource-sync <resource-sync@wehub.local>
Date:   Mon Jul 13 12:21:01 2026 +0800

    chore: import upstream snapshot with attribution

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..5b921cd
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,32 @@
+# VCS
+.git
+**/.git
+
+# Editor
+.vscode
+**/.vscode
+
+# Dependencies and build output
+node_modules
+.next
+out
+build
+dist
+coverage
+
+# Runtime data and logs
+data
+logs
+
+# Local env files (inject at runtime via --env-file or -e)
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Debug logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..6ed8f81
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,41 @@
+# 9Router environment contract
+# This file reflects actual runtime usage in the current codebase.
+
+# Required
+JWT_SECRET=change-me-to-a-long-random-secret
+INITIAL_PASSWORD=change-me
+DATA_DIR=/var/lib/9router
+
+# Recommended runtime variables
+PORT=20128
+NODE_ENV=production
+
+# Recommended security and ops variables
+API_KEY_SECRET=endpoint-proxy-api-key-secret
+MACHINE_ID_SALT=endpoint-proxy-salt
+ENABLE_REQUEST_LOGS=false
+OBSERVABILITY_ENABLED=true
+AUTH_COOKIE_SECURE=false
+REQUIRE_API_KEY=false
+
+# Cloud sync variables
+# Must point to this running instance so internal sync jobs can call /api/sync/cloud.
+# Server-side preferred variables:
+BASE_URL=http://localhost:20128
+CLOUD_URL=https://9router.com
+# Backward-compatible/public variables:
+NEXT_PUBLIC_BASE_URL=http://localhost:20128
+NEXT_PUBLIC_CLOUD_URL=https://9router.com
+
+# Optional outbound proxy variables for upstream provider calls
+# Lowercase variants are also supported: http_proxy, https_proxy, all_proxy, no_proxy
+# HTTP_PROXY=http://127.0.0.1:7890
+# HTTPS_PROXY=http://127.0.0.1:7890
+# ALL_PROXY=socks5://127.0.0.1:7890
+# NO_PROXY=localhost,127.0.0.1
+
+# Optional SearXNG endpoint for the built-in unauthenticated web-search provider.
+# SEARXNG_URL=http://searxng:8080/search
+
+# Currently unused by application runtime (kept as reference)
+# INSTANCE_NAME=9router
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..e180032
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,2 @@
+version: 2
+updates: []
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
new file mode 100644
index 0000000..e8ef957
--- /dev/null
+++ b/.github/workflows/docker-publish.yml
@@ -0,0 +1,60 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+env:
+  GHCR_IMAGE: ghcr.io/${{ github.repository }}
+  DOCKERHUB_IMAGE: decolua/9router
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ env.GHCR_IMAGE }}
+            ${{ env.DOCKERHUB_IMAGE }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=registry,ref=${{ env.GHCR_IMAGE }}:buildcache
+          cache-to: type=registry,ref=${{ env.GHCR_IMAGE }}:buildcache,mode=max
+          platforms: linux/amd64,linux/arm64
+          provenance: false
+          sbom: false
diff --git a/.github/workflows/gitbook-pages.yml b/.github/workflows/gitbook-pages.yml
new file mode 100644
index 0000000..797e1dc
--- /dev/null
+++ b/.github/workflows/gitbook-pages.yml
@@ -0,0 +1,50 @@
+name: Deploy GitBook to 9router.github.io
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - "gitbook/**"
+      - ".github/workflows/gitbook-pages.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: gitbook-pages
+  cancel-in-progress: true
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: gitbook
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Install deps
+        run: npm install --no-audit --no-fund
+
+      - name: Build static export
+        run: npm run build
+        env:
+          NODE_ENV: production
+          NEXT_PUBLIC_BASE_PATH: ""
+
+      - name: Add .nojekyll
+        run: touch out/.nojekyll
+
+      - name: Deploy to 9router.github.io
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          deploy_key: ${{ secrets.GH_PAGES_DEPLOY_KEY }}
+          external_repository: 9router/9router.github.io
+          publish_branch: main
+          publish_dir: gitbook/out
+          force_orphan: true
+          user_name: github-actions[bot]
+          user_email: github-actions[bot]@users.noreply.github.com
+          commit_message: "deploy: ${{ github.sha }}"
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..dd7c67f
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,80 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/.next-cli-build/
+/out/
+cli/.build-home/
+product
+# production
+/build
+.idea/
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+.bin/*
+data/
+logs/*
+source/*
+.cursor/*
+docs/*
+!docs/ARCHITECTURE.md
+test/*
+open-sse/test/*
+RM.vn.md
+RM.md
+cursor/*
+PUBLIC.md
+Thanks.md
+PUBLIC.en.md
+PR/*
+package-lock.json
+
+
+#Ignore vscode AI rules
+.github/instructions/codacy.instructions.md
+README1.md
+deploy*.sh
+ecosystem.config.*
+
+scripts/agSniffer/*
+gitbooks/*
+gitbook/README.md
+
+# Refactor backup reference (do not bundle/lint)
+open-sse.old/
+.graphifyignore
+graphify-out/*
+.next-analyze/*
diff --git a/.npmignore b/.npmignore
new file mode 100644
index 0000000..24e8f32
--- /dev/null
+++ b/.npmignore
@@ -0,0 +1,31 @@
+# Database files - NEVER publish
+data/
+**/data/
+**/db.json
+
+# Development
+src/
+docs/
+test/
+agents/
+scripts/
+worker/
+shared-sse/
+copilot-api/
+CLIProxyAPI/
+
+# Config files
+*.md
+!README.md
+.gitignore
+.env*
+jsconfig.json
+eslint.config.mjs
+postcss.config.mjs
+next.config.mjs
+tsconfig.json
+
+# Build artifacts that shouldn't be published
+.next/cache/
+.next/standalone/data/
+
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..8e3d0f1
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,20 @@
+{
+  "css.lint.unknownAtRules": "ignore",
+  "sonarlint.rules": {
+    "css:S4662": {
+      "level": "off"
+    },
+    "javascript:S6747": {
+      "level": "off"
+    },
+    "javascript:S7764": {
+      "level": "off"
+    },
+    "javascript:S6772": {
+      "level": "off"
+    },
+    "javascript:S3776": {
+      "level": "off"
+    }
+  }
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..c6ba213
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,380 @@
+# v0.5.30 (2026-07-10)
+
+## Features
+- **Perplexity**: add Agent API provider (#2492)
+- **Grok CLI**: add Grok CLI / Grok Build provider with OAuth device-code flow (#2502)
+- **Featherless**: add OpenAI-compatible provider presets
+- **SearXNG**: configure endpoint via SEARXNG_URL env (#2499)
+- **Providers**: add max thinking level for gpt-5.6-sol (#2500)
+- **Headroom**: add extras detection and install UI (#2403)
+- **Headroom**: activate/uninstall extras + fix interpreter detection
+- **PXPipe**: PXPIPE token saver — multimodal prompt compression (#2465)
+- **Proxy-Pools**: auto-rotate strategy for no-auth providers (#2409)
+
+## Fixes
+- **Cloudflare-AI**: support accountId in bulk key import (#2449)
+- **DB**: backup on schema change, MCP child cleanup, codex models, usage providers OOM
+- **Codex**: avoid bare-email OAuth dedup (#2477)
+- **CLI**: allow staged app bundle builds (#2479)
+- **Headroom**: compress Kiro conversation state (#2488)
+- **Gemini-CLI**: raise output floor for thinking and add validated toolConfig (#2486)
+- **GitHub**: label Copilot profiles by account identity (#2498)
+- **OpenAI-to-Claude**: unwrap bare {function:{…}} tools without parent type (#2473)
+- **Translator**: clamp thinking effort max->xhigh for OpenAI format (#2466)
+- **RTK/find**: detect and group Windows backslash-style find output (#2448)
+- **Codex**: handle fast tier and capacity SSE (#2452)
+- **Volcengine-ark**: clamp Kimi max_tokens to 32768 endpoint cap
+- **Antigravity**: align provider fingerprint with IDE Desktop 2.1.1 (#2389)
+- **Pricing**: update Claude/Codex model rates and add new models
+
+## Improvements
+- **i18n(zh-CN)**: complete Chinese translations for all UI strings (#2436)
+- **API**: caching for tunnel and version status endpoints
+- **Perf**: faster dev startup and lighter bundle
+
+# v0.5.20 (2026-07-07)
+
+## Features
+- **Thinking**: per-model thinking level picker on provider page — appends `(level)` suffix to copied model names for forced reasoning effort across all formats (openai, claude, gemini, deepseek, kimi, qwen, zai, minimax, hunyuan, step)
+- **RTK**: add JS-native git-log filter (#2423)
+- **Caveman**: add targeted upstream-aligned style rules (#2424)
+- **i18n**: add Farsi (fa) language support (#2385)
+
+## Fixes
+- **Thinking**: strip `(level)` suffix from upstream `body.model` so providers no longer reject requests
+- **Translator**: preserve developer instructions in openai-responses conversion (#2434)
+- **count_tokens**: count structured Anthropic blocks (#2419)
+- **Volcengine-ark**: clamp GLM-5 max_tokens to model output ceiling (#2428)
+- **Kimi**: normalize reasoning_effort to backend enum (#2427)
+- **Claude**: reconcile max_tokens vs thinking budget and lift per-model ceiling (#2381)
+- **Kiro**: deliver system prompt natively, add Opus 4.5/4.7/4.8, tolerate dash version ids (#2366)
+- **Headroom**: proxy dashboard through app (#2372)
+- **MITM**: recover from stale lock file on server start
+
+# v0.5.18 (2026-07-03)
+
+## Features
+- **Usage**: track cached tokens + correct input/output/cache cost (#2209) — hodtien
+- **Codex**: show reset credit expiry details (#2290) — Rafli Ahmad Zulfikar
+- **NVIDIA**: add new models and capabilities — decolua
+- **ClinePass**: add provider support — sternelee
+
+## Fixes
+- **Usage**: dedupe streaming request-details log entries — Qin Li
+- **Claude**: drop foreign thinking signatures in passthrough — decolua
+- Prevent non-SSE stream pipe crash and cross-IdP account overwrites (#2244) — KunN-21
+- **Kiro**: route IdC auth to regional CodeWhisperer surface (#2297) — Volodymyr Saakian
+- **Kiro**: add Claude Sonnet 5 model support (#2264) — Edison42
+- **Xiaomi-tokenplan**: region selector, key validation, multi-connection (#2251) — MiQieR
+- **Translator**: strict Anthropic content block compliance (#2225) — Sahrul Ramadhan Hardiansyah
+- **Kimchi**: strip reasoning_content echo to bound multi-turn input tokens — KunN-21
+- **Kimchi**: bump User-Agent to kimchi/0.1.40 (#2256) — Ansh7473
+- **Codebuddy-cn**: strip empty tool_calls arrays to preserve reasoning — zmf
+- **Antigravity**: preserve Claude tool delta index (#2223) — Sutarto Jordan Chrisfivo
+- **MITM**: generate root CA on server startup (#2228) — Sutarto Jordan Chrisfivo
+
+# v0.5.15 (2026-06-29)
+
+## Features
+- Add Kimchi OAuth provider — Nant361
+- Refine Qwen vision/video + thinking model patterns — decolua
+- Opt-in Codex auto-ping quota keep-alive — Emirhan
+
+## Fixes
+- **Responses**: handle response.done terminal events (#2142) — rifuki
+- **Headroom**: skip unsafe responses tool history (#2132) — Sutarto Jordan Chrisfivo
+- **Translator**: map mid-conversation system message to user (claude→openai) — decolua
+- **Gemini**: normalize contents to prevent 400 invalid_argument (#2192) — warelik
+- **Gemini**: backfill thoughtSignature + suppress stream done sentinel — WARELIK
+- **Alicode**: preserve cache_control for DashScope providers (#2069) — Rex
+- **Antigravity**: strip deprecated/readOnly/writeOnly from tool schemas — iletai, Yudhistira-Official
+- **CodeBuddy CN**: show bonus packs as one-time, not monthly-replenishing — whale9820
+- **Kiro**: strip leaked <thinking> tags from content stream (#2158) — hamsa0x7
+- **Tray**: make Windows context menu DPI-aware — Emirhan
+- **Kilocode**: expose full gateway catalog in combo model picker — jellylarper
+- **OpenCode**: fix Go GLM — decolua
+
+# v0.5.12 (2026-06-26)
+
+## Features
+- Add token-saver dashboard page — decolua
+- Add bulk delete for provider connections — teddytkz
+- Resolve GitHub Copilot model catalog from upstream — caiqinzhou
+- Add Venice AI provider — Brokenc0de
+- Add Kiro external_idp import for Microsoft SSO (CLIProxyAPI) — Stevanus Pangau
+- Overhaul Blackbox provider catalog + WebUI test support — suryacagur
+
+## Fixes
+- Provider thinking compatibility (DeepSeek/Gemini) — Mink Nguyen
+- Stop double-counting streaming usage at source — decolua
+- Usage logging dedupe to reduce stats churn — Mink Nguyen
+- Prevent non-JSON SSE lines / duplicate [DONE] from breaking clients (PR #2046) — qianze
+- Resolve Gemini TTS models from catalog — nguyenha935
+- Support Kiro IDC (organization) token import — quanturbo
+- Preserve forced streaming for JSON clients (#2031) — Joseph Yaksich
+- Preserve Responses text format (Codex) — tenglong
+- Support Gemini native TTS generateContent endpoint — nguyenha935
+- Add missing zh-CN endpoint key label (i18n) — weimaozhen
+- CodeBuddy: only send reasoning params when client requests reasoning (#2071) — Rex
+- CodeBuddy CN: show one-shot bonus packs as expiring, not monthly-replenishing
+- Show custom provider models in combo picker — Sapto
+- Docker: add docker-compose.yml with headroom enabled by default — nitsuahlabs
+- Clarify token diagnostics vs provider billing (headroom, #1998) — Sutarto Jordan Chrisfivo
+- Translate openai-responses input through OpenAI for compression (#1998) — Ankit
+- Kiro: report 1M context window for claude-opus-4.8 — EdisonPVE
+- Avoid stale redirects after auth changes (#2100) — Emirhan
+- Mark Claude Opus 4.7 (dashed id) as 1M context — Brokenc0de
+- Preserve reasoning effort through Codex translations — ntdung6868
+- Token-saver: full width card layout — decolua
+- Antigravity: retry transient upstream failures — Sutarto Jordan Chrisfivo
+- Param-support: handle strip rules without match/drop (#1960) — Joseph Yaksich
+- Translator: resolve custom provider prefix in debug endpoint (#1083) — hamsa0x7
+
+# v0.5.8 (2026-06-21)
+
+## Features
+- **Antigravity**: native image generation support (image models tagged kind:image, hiển thị trong media-providers UI)
+- **CodeBuddy CN**: API key auth + credit quota tracker
+- **CodeBuddy CN**: short model prefix alias "cbcn"
+
+## Fixes
+- **MiniMax-M3**: enable vision capability
+- **Headroom**: support Docker sidecar proxy
+- **Antigravity**: image executor fixes
+- **mimo-free**: Chrome User-Agent rotation to bypass anti-abuse gate
+- **cloudflare-ai**: flatten content-part arrays to string to avoid oneOf 400 (#1926)
+- **Translator**: normalize tools to Anthropic-native shape for non-Anthropic providers
+- **CLI**: handle Next.js 16 nested standalone output path (#1940)
+- **Codex**: preserve custom tools during request normalization
+- **next.config**: add new route for responses endpoint to API
+
+# v0.5.6 (2026-06-20)
+
+## Features
+- **Ponytail**: minimalist code generation feature
+- **Headroom**: proxy lifecycle management + dashboard UI (one-click start/stop, install detection, status probing, token saver, claude↔openai shape conversion)
+- **CodeBuddy CN**: new OAuth provider (copilot.tencent.com) — 15-model catalog, /v2 inference, forced streaming, OpenAI-style reasoning
+- **OpenCode-Go**: align models with official endpoints; route Qwen 3.7 MiniMax via /v1/messages, GLM/Kimi/DeepSeek/MiMo via /chat/completions
+
+## Fixes
+- **Anthropic-compatible validation**: use POST /v1/messages (GET /models not spec, false "invalid" for valid keys)
+- **CLI tools**: tolerate JSONC configs in all 8 settings routes (opencode, openclaw, kilo, droid, cowork, copilot, claude, cline)
+- **Gemini/Antigravity**: preserve 'pattern' in tool schema translation (glob/grep)
+- **Combo/Fusion**: flatten Anthropic-style tool messages in panel calls (prevent 503)
+- **Models**: store provider custom models by provider scope
+- **Perplexity**: use /v1/models endpoint for key validation
+
+# v0.5.4 (2026-06-18)
+
+## Fixes
+- **Kiro**: honor thinking effort budgets
+- **AG/Kiro/Xiaomi**: provider fixes
+- **Combo/Fusion**: flatten tool history in panel calls to prevent 503
+- **LLM selector**: show custom vision models in selector and model list
+- **Image**: prevent compatible nodes from shadowing provider aliases
+
+# v0.5.2 (2026-06-17)
+
+## Features
+- **Combo Fusion strategy** — fans the prompt out to all member models in parallel, then a configurable judge model synthesizes one final answer (quorum-grace, anonymized sources, graceful degradation)
+- **Per-combo strategy selector** — pick `fallback` / `round-robin` / `fusion` / `capacity` per combo (replaces the old round-robin toggle), with a judge picker for fusion
+- **Capacity auto-switch** — reorders models per request so images/PDFs route to capable models first
+- **Kiro headless API-key auth** (`ksk_`) + direct `claude↔kiro` route that avoids the lossy OpenAI two-hop pivot
+- **Claude auto-ping** — warms the 5h quota window right after reset so a fresh window starts immediately (per-connection toggle)
+
+## Fixes
+- **Claude 429**: stop hammering the OAuth usage endpoint — cache resetAt, throttle quota refresh to 3 min, cool down after a 429 (chat unaffected)
+- **Usage logs always empty**: missing `await` on `getAdapter()` in `getRecentLogs` made `/api/usage/logs` & `/api/usage/request-logs` return nothing
+- **Executors**: strip params unsupported by the provider/model (drops deprecated `temperature` for claude-opus-4 → Anthropic 400)
+- **Translator**: derive deterministic tool_call ids for gemini/antigravity → OpenAI so function call/response pair correctly (fixes tool-pairing 400s)
+- **Antigravity**: strip `optional` from tool schemas before sending to Gemini
+- **Claude-to-OpenAI**: handle OpenAI-format responses in the non-streaming path (e.g. xiaomi-tokenplan)
+- **Usage views**: show edited connection names consistently across Providers & Quota Tracker
+- **Security**: hardened reverse-proxy local-access trust
+- **Security**: SSRF hardening on web fetch
+
+## Internal
+- Large **open-sse / translator refactor** (~40 commits): unified provider/model registry (LiteLLM-style `models[]` + `kind` field, 100 co-located registry files), single-sourced media/OAuth/refresh/token URLs, registry-based dispatch for usage & token-refresh, DRY translator concerns (buildUsage, encodeDataUri, finishReasonMap, chunkBuilder, reasoningDelta…), ESM-safe registry init, large-file splits, dead-code removal, and golden/no-regression test gates
+
+# v0.4.80 (2026-06-13)
+
+## Features
+- Vercel AI Gateway: support embeddings, images and credit usage (#1183)
+- Add MiMo Free no-auth provider (#1789)
+- Vertex: support ADC `authorized_user` credential
+- Cowork: re-enable Claude Cowork with preset-only stdio MCP
+- Codex: bulk add accounts via JSON (#1719)
+- Kiro: enable multi-endpoint failover for GenerateAssistantResponse (#1722)
+
+## Fixes
+- Security: re-auth on DB export/import + SSRF guard on web fetch
+- Auth: real client IP rate-limiting + remote default-password guard
+- Cerebras/Mistral: strip unsupported `client_metadata` from downstream requests (#1742)
+- SiliconFlow: update baseUrl `.cn` -> `.com` + curate verified model list (#1760)
+- Gemini-to-OpenAI: route unsigned thought parts to `reasoning_content` (#1752)
+- Claude-to-OpenAI: strip Anthropic billing header from system prompt (#1765)
+- Anthropic-compatible: send Bearer auth for third-party gateways (#1795)
+- Usage-stats: avoid partial stats on initial SSE race (#1767)
+- Proxy: use `export default` in proxy.js for Next.js 16 middleware detection
+- Claude passthrough: add body normalization
+- GitHub Copilot: refresh missing/expired token on models discovery (#1727) + add mappable gpt-5-mini/gpt-5.4-nano slots for Copilot MITM (#1653)
+- Kiro: auto-resolve profileArn to prevent 403 on IDC login, enhance profile ARN resolution, update endpoint to `runtime.us-east-1.kiro.dev` (#1713)
+- Tunnel: detect system-installed Tailscale via dual-socket probe (#1723) + non-blocking probes to prevent UI freeze
+- CommandCode: force `stream=true` in transformRequest (#1706)
+- Qoder: increase timeouts for reasoning models and improve stream handling
+- Dashboard: show provider node name instead of connection name in topology (#1770) + show explicit `kind="llm"` combos on combos page (#1684)
+
+## Docs
+- README: add Indonesian 9Router tutorial video (#1709)
+
+# v0.4.71 (2026-06-06)
+
+## Features
+- Caveman: add wenyan classical Chinese levels and sync upstream prompts; locale-based visibility on endpoint page
+- i18n: endpoint exposure notice across multiple languages + Russian README
+- Antigravity: add gemini-3.5-flash-extra-low (Low) model
+- xiaomi-tokenplan: add Claude-native MiMo V2.5 Pro alias via dedicated executor
+- Qoder: fetch latest model + dashboard import-model button (#1642)
+- MiniMax: add MiniMax-M3 + update Quota Tracker coding/CN (#1631)
+
+## Fixes
+- Codex: harden streaming timeouts (stall/connect raised to 60s, configurable per-provider), accept `response.done` event, and always emit a terminal `response.failed` + `[DONE]` for Responses passthrough when a stream closes, stalls, or aborts before a terminal event — prevents codex clients from hanging (#1648, #1680, #1688, #1618)
+- Codex: durable OAuth refresh lifecycle (#1664)
+- Tunnel: skip virtual interfaces to prevent false netchange watchdog
+- Claude: fix forced tool_choice 400 on cc/ OAuth route (#1592)
+- Proxy: raise Next client body limit to 128MB via `NINEROUTER_PROXY_CLIENT_MAX_BODY_SIZE` (#1529, #1572)
+- MiniMax: echo `reasoning_content` on follow-up turns to avoid 400 (#1543)
+- Kiro: handle 400 on tool-bearing history without client tools; add mappable "auto" model slot; fix binary EventStream crash + add models & TTS tool filtering
+- Antigravity: passthrough tab-autocomplete + mark default agent slot mandatory
+- Qoder: allow `qmodel_latest` model key (#1638)
+- Providers: restore one-connection guard for compatible/embedding nodes
+- Model-test: route image/STT probes to their real endpoints, harden STT ping; add opencode-go + xiaomi-tokenplan to connection test (#1576, #1628)
+
+## Improvements
+- Dashboard: reorganize menu actions across sidebar/header/profile
+- Translator: add data-driven coverage, bug-exposing cases, and real provider smoke tests
+
+# v0.4.66 (2026-05-29)
+
+## Features
+- Add Qoder provider: device-flow OAuth, COSY signing, WAF-bypass body encoding, live model catalog, dashboard quota tracker, 11 models (#1372)
+- Add new models: Claude Opus 4.8 (Claude Code), GPT 5.4 Mini (Codex)
+
+## Fixes
+- DeepSeek thinking mode: echo `reasoning_content` back on follow-up/tool-call turns so OpenCode-free and custom providers no longer 400 with "reasoning_content must be passed back" (#1543)
+- Reasoning injector: match deepseek/kimi model ids case-insensitively (covers custom providers using capitalized model names)
+- OpenCode suggested-models: include free models without the `-free` suffix, e.g. `big-pickle` (#1535)
+
+## Improvements
+- Codex: trim sunset models, keep gpt-5.5 / gpt-5.4 / gpt-5.3-codex family, add gpt-5.4-mini
+- volcengine-ark: refresh model list (add DeepSeek-V4-Flash/Pro, drop EOL entries)
+- Lower stream stall timeout 35s → 30s for faster hang detection
+
+# v0.4.63 (2026-05-26)
+
+## Fixes
+- GitHub Copilot: never route Gemini/Claude models to the `/responses` endpoint; prevents misleading "does not support Responses API" 400s (#1062)
+- proxyFetch: restore missing `Readable` import causing runtime `ReferenceError` in DNS-bypass fetch path
+
+## Improvements
+- Lower stream stall timeout from 60s → 35s for faster hang detection
+
+# v0.4.62 (2026-05-26)
+
+## Fixes
+- Codex: auto-retry when upstream drops mid-stream (no more hangs)
+- Codex: fix random 400/404 errors, tool-calling failures, and unstable prompt cache
+- MITM: support Antigravity 2.x 
+- Sanitize Read tool args to prevent retry loops from non-Anthropic models (#1144)
+- Implement json_schema fallback for OpenAI-compatible providers without native Structured Output (#1343)
+- Strip empty Read pages argument in OpenAI-to-Claude translator (#1354)
+- Forward Gemini output dimensions for embeddings (#1366)
+- Resolve setState-in-effect errors in dashboard components (#1362)
+- Gemini CLI: reuse stored OAuth project IDs for quota checks and show clearer setup guidance when the project is missing (#1271, #1428)
+
+## Features
+- Add Cloudflare Workers proxy deployer and pool integration (#1360)
+- Add Deno Deploy relays support and improved proxy pools dashboard layout (#1437)
+
+## Improvements
+- Refactor Tunnel into dedicated Cloudflare and Tailscale manager modules
+- Refactor tokenRefresh service with in-flight dedup to prevent refresh_token_reused errors
+
+# v0.4.59 (2026-05-21)
+
+## Fixes
+- OAuth: fix login flow on Windows
+
+# v0.4.58 (2026-05-21)
+
+## Features
+- xAI Grok provider (OAuth, API key, image)
+- Provider limits: paginated accounts with page size controls
+
+## Fixes
+- Tailscale: fix connection status on Windows (#1300)
+- Tunnel: fix false "checking" when tunnel URL is reachable
+- Stream: fix pipe errors on client disconnect/abort
+
+# v0.4.55 (2026-05-18)
+
+## Features
+- Xiaomi MiMo Token Plan: region selector (Singapore / China / Europe) — keys are cluster-specific
+- Antigravity: risk confirmation dialog before first connection
+- Gemini CLI: surface upstream retry delay on 429 errors
+
+## Fixes
+- MITM: cannot kill process on macOS under sudo (lsof not found in PATH)
+- Stream: false-positive stall timeout on Claude reasoning / Kiro responses
+- Tunnel: cannot re-enable after disable (stuck state)
+- Tunnel: cloudflared error messages now include log tail for easier debugging
+- Language switcher: applies selected locale immediately on close (#1234)
+- Antigravity OAuth: metadata now matches the official client
+
+## Improvements
+- Gemini CLI: bump engine to 0.34.0
+- Re-hide `qwen` (OAuth EOL) and `iflow` (not ready) providers
+
+# v0.4.52 (2026-05-17)
+
+## Features
+- Add Vercel AI Gateway provider support (#1183)
+- rtk: Kiro format tool result compression — handle conversationState.history & currentMessage, preserve error results, ~13.6% savings (#1194)
+
+## Fixes
+- openclaw: normalize agent.model object form `{primary, fallbacks}` before .startsWith → fix TypeError & 'not configured' status (#1216)
+- Usage Details pagination: stay inside mobile viewport <640px (#1218)
+- Fix test model error
+- Fix MIMO provider in Codex
+- Disable log file creation when using MITM AG
+
+# v0.4.50 (2026-05-16)
+
+## Fixes
+- Fix duplicate tray icon on macOS when hiding to tray
+- Fix tray not showing in background mode on macOS
+- Fix hide to tray broken on Windows/Linux
+- Fix Shutdown button in web UI not working
+
+# v0.4.49 (2026-05-16)
+
+## Features
+- Add Kiro provider support: full request/response translation, live model listing, reasoning content support
+- Add `buildOutput` RTK filter with autodetect for npm/yarn/cargo build logs
+- Add MITM warning notification in tray and dashboard
+
+## Improvements
+- Add modalities (input/output) to model configuration for OpenCode
+- Fix tray hide-to-tray: keep current process alive instead of spawning detached child (fixes macOS NSStatusItem ghost icon)
+- Fix tray kill: graceful shutdown with SIGTERM/SIGKILL escalation
+- Fix SIGHUP handling so macOS terminal close doesn't kill tray process
+- Hide deprecated providers (qwen, iflow, antigravity)
+- Update i18n across 32 languages
+
+## Fixes
+- Fix model check (test-models) blocked by dashboardGuard: pass machineId-based CLI token in internal self-calls
+
+# v0.4.46 (2026-05-15)
+
+## Breaking Changes
+- Tunnel public URL changed — old tunnel links no longer work, please reconnect to get the new URL
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d7c2134
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+9Router (`9router-app`) — a local AI routing gateway + Next.js dashboard. It exposes one OpenAI-compatible endpoint (`/v1/*`) and routes traffic across 40+ upstream providers with format translation, model-combo fallback, multi-account fallback, OAuth/API-key credential management, token refresh, quota/usage tracking, and optional cloud sync.
+
+Two published artifacts live in this one repo:
+- The **dashboard + gateway** (root `package.json`, `9router-app`) — the Next.js server that does the actual routing.
+- The **CLI launcher** (`cli/`, published to npm as `9router`) — a separate package that installs/starts the server and manages the tray. It has its own `package.json`, version, and build.
+
+The code lives in `src/` (Next.js app + dashboard/compat APIs), `open-sse/` (the provider-agnostic routing/translation engine), `cli/` (the launcher package), and `tests/`.
+
+## Commands
+
+Dashboard/gateway (run from repo root):
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev   # dev (webpack, port 20127 by default via next dev)
+npm run build && PORT=20128 HOSTNAME=0.0.0.0 npm run start           # production
+```
+- Bun variants: `npm run dev:bun` / `build:bun` / `start:bun`.
+- Default runtime port is **20128** (dashboard at `/dashboard`, API at `/v1`).
+- Lint: `npx eslint .` (config `eslint.config.mjs`, extends `eslint-config-next`).
+
+CLI package (`cli/`):
+```bash
+npm run cli:pack       # build + npm pack from root
+cd cli && npm run dev  # nodemon watch
+```
+
+Tests (vitest, in `tests/`, an **independent** ESM package — not wired into root `npm test`):
+```bash
+npm install                             # ROOT deps first — tests import from src/ which needs `open`, `undici`, etc.
+cd tests && npm install                 # then tests' own deps (vitest) → tests/node_modules (allowed by tests/.gitignore)
+npx vitest run                          # all tests; auto-discovers tests/vitest.config.js
+npx vitest run unit/capabilities.test.js   # single file (path relative to tests/)
+```
+> The committed `tests/package.json` `test` script hardcodes Unix paths (`NODE_PATH=/tmp/node_modules …`) — a shared-install workaround from upstream. On Windows (or anywhere), ignore it and use the `npx vitest` form above; `vitest.config.js` resolves the `open-sse`/`@/` aliases from the repo root regardless of where vitest lives.
+>
+> **The suite is NOT expected to be all-green on a plain checkout.** ~938 pass, ~64 fail. Judge regressions with `tests/__baseline__/verify-no-regression.mjs`, not a raw run. Expected red:
+> - 26 catalogued in `tests/__baseline__/known-fails.txt` (rtk, oauth-cursor-auto-import, translator-request-normalization, …).
+> - `unit/embeddings.cloud.test.js` imports `cloud/src/handlers/embeddings.js` — the `cloud/` worker dir is **not in this repo**, so it always fails here.
+> - `unit/xai-oauth-service.test.js` times out (5s) when the xAI endpoint-discovery fetch isn't reachable/mocked.
+> - `real/*.real.test.js` make live provider calls — need credentials, skip otherwise.
+- `*.real.test.js` under `tests/translator/real/` make live provider calls — skip unless credentials are set.
+- Regression baselines: `tests/__baseline__/verify-*.mjs` compare against committed snapshots (providers, aliases, OAuth URLs). Run these after touching provider registry / alias logic.
+
+## Architecture
+
+Two authoritative docs already exist — read them before working in these areas rather than re-deriving:
+- `docs/ARCHITECTURE.md` — full system: request lifecycle, combo/account fallback, OAuth + token refresh, cloud sync, data model.
+- `open-sse/AGENTS.md` — the routing/translation engine's own conventions and "how to add a provider/executor/translator". **Read this before editing anything under `open-sse/`.**
+
+### Request flow (the thing to understand first)
+`src/app/api/v1/*` route (Next rewrite maps `/v1/*` → `/api/v1/*` in `next.config.mjs`)
+→ `src/sse/handlers/chat.js` (parse, combo expansion, account-selection loop)
+→ `open-sse/handlers/chatCore.js` (detect source format, translate request, dispatch to executor, retry/refresh, stream setup)
+→ `open-sse/executors/*` (per-provider upstream call; `default.js` handles any OpenAI-compatible provider)
+→ `open-sse/translator/*` (client format ↔ provider format)
+→ SSE back to client.
+
+`src/sse/` is the app-side entry glue; `open-sse/` is the provider-agnostic engine (also usable standalone). Cross that boundary consciously.
+
+### Translator engine (`open-sse/translator/`)
+- Pivots through **OpenAI as the intermediate format**. A translator registered on an exact `source:target` pair (e.g. `claude:kiro`) runs as a **direct route**, skipping the lossy double-hop. Prefer a direct route for fragile pairs (thinking blocks, tool ids, non-base64 images, `is_error`).
+- Translators **self-register** via `register(from, to, reqFn, resFn)` as an import side effect — a new translator file MUST be imported in `open-sse/translator/index.js` or it never runs.
+- Never hardcode role/block/model strings — use `open-sse/translator/schema/` and `open-sse/config/` constants. Config-driven and DRY is enforced by convention here.
+
+### Provider registry (`open-sse/providers/registry/*`)
+- One file per provider. `providers/registry/index.js` is an **auto-generated** static import list — regenerate it with `scripts/migrate-registry.mjs` / `injectDisplayToRegistry.mjs`, don't hand-edit.
+- Add a provider: copy `providers/REGISTRY_TEMPLATE.js`, add models to `config/providerModels.js`. Only add an executor for non-OpenAI-compatible upstreams.
+
+### Persistence — IMPORTANT (ARCHITECTURE.md is stale here)
+State is **no longer `db.json`**. It's a SQLite layer under `src/lib/db/` with an adapter fallback chain (`driver.js`): `bun:sqlite` → `better-sqlite3` (optional native dep) → `node:sqlite` (Node ≥22.5) → `sql.js` (pure-JS fallback, always works). `better-sqlite3` is deliberately in `optionalDependencies` so install never fails without build tools.
+- `src/lib/localDb.js` is a **backward-compat shim** re-exporting `src/lib/db/index.js`. New code should import from `@/lib/db/index.js`; per-entity logic lives in `src/lib/db/repos/*`. Schema/migrations in `src/lib/db/migrations/`.
+- DB file location resolves via `src/lib/db/paths.js` (`DATA_DIR`, else `~/.9router/`).
+- Usage/logs (`src/lib/usageDb.js`, `usage.json` + `log.txt`) still live under `~/.9router` and do **not** follow `DATA_DIR`.
+
+### RTK token saver (`open-sse/rtk/`)
+Pre-translate hooks that compress `tool_result` content in-place to cut tokens. **Fail-open**: any error returns null and leaves the body untouched — never throw out of them. Skips `is_error`/`status:"error"` results to preserve traces.
+
+## Conventions & gotchas
+
+- Plain JavaScript (ESM), no TypeScript. `@/*` path alias → `src/*` (`jsconfig.json`).
+- `custom-server.js` wraps the Next standalone server to derive client IP from the TCP socket and strip attacker-controlled `X-Forwarded-For` — trusting forwarding headers only from a loopback reverse proxy. Preserve this when touching request/IP/rate-limit code.
+- Security-sensitive env: `JWT_SECRET` (session cookie), `INITIAL_PASSWORD` (default `123456` — must override), `API_KEY_SECRET`, `MACHINE_ID_SALT`. Full env contract in `.env.example` and ARCHITECTURE.md's env matrix.
+- Binary/protobuf upstreams (kiro EventStream, cursor protobuf, commandcode NDJSON) don't round-trip through OpenAI — they're handled inside their own executor, not the translator.
+- Versioning: root and `cli/` are versioned independently; changes are logged in `CHANGELOG.md`. Commit style is Conventional Commits (`fix(translator): …`, `feat(...)`).
diff --git a/DOCKER.md b/DOCKER.md
new file mode 100644
index 0000000..1f280d9
--- /dev/null
+++ b/DOCKER.md
@@ -0,0 +1,132 @@
+# Docker
+
+Run 9Router in a container. Published image: [`decolua/9router`](https://hub.docker.com/r/decolua/9router) — multi-platform `linux/amd64` + `linux/arm64`.
+
+---
+
+# 👤 For Users
+
+## Quick start
+
+```bash
+docker run -d \
+  -p 20128:20128 \
+  -v "$HOME/.9router:/app/data" \
+  -e DATA_DIR=/app/data \
+  --name 9router \
+  decolua/9router:latest
+```
+
+App listens on port `20128`. Open: http://localhost:20128
+
+## Manage container
+
+```bash
+docker logs -f 9router        # view logs
+docker stop 9router           # stop
+docker start 9router          # start again
+docker rm -f 9router          # remove
+```
+
+## Data persistence
+
+```bash
+-v "$HOME/.9router:/app/data" \
+-e DATA_DIR=/app/data
+```
+
+Without `DATA_DIR`, the app falls back to `~/.9router/` (macOS/Linux) or `%APPDATA%\9router\` (Windows). In the container, `DATA_DIR=/app/data` makes the bind mount work.
+
+Data layout under `$DATA_DIR/`:
+
+```text
+$DATA_DIR/
+├── db/
+│   ├── data.sqlite       # main SQLite database
+│   └── backups/          # auto backups
+└── ...                   # certs, logs, runtime configs
+```
+
+Host path: `$HOME/.9router/db/data.sqlite`
+Container path: `/app/data/db/data.sqlite`
+
+## Optional env vars
+
+```bash
+docker run -d \
+  -p 20128:20128 \
+  -v "$HOME/.9router:/app/data" \
+  -e DATA_DIR=/app/data \
+  -e PORT=20128 \
+  -e HOSTNAME=0.0.0.0 \
+  -e DEBUG=true \
+  --name 9router \
+  decolua/9router:latest
+```
+
+## Optional Headroom sidecar
+
+The 9Router image does not bundle Python or Headroom. To use Headroom in Docker, run it as a separate service and point 9Router at that proxy:
+
+```yaml
+services:
+  9router:
+    image: decolua/9router:latest
+    ports:
+      - "20128:20128"
+    volumes:
+      - "$HOME/.9router:/app/data"
+    environment:
+      DATA_DIR: /app/data
+      HEADROOM_URL: http://headroom:8787
+    depends_on:
+      - headroom
+
+  headroom:
+    image: ghcr.io/chopratejas/headroom:latest
+    ports:
+      - "8787:8787"
+```
+
+In the dashboard, open `Endpoint` → `Token Saver` → `Headroom`, confirm the URL is `http://headroom:8787`, recheck status, then enable Headroom.
+
+If Headroom runs on the Docker host instead of as a sidecar, use `http://host.docker.internal:8787` on macOS/Windows. On Linux, add `--add-host=host.docker.internal:host-gateway` or the equivalent compose `extra_hosts` entry.
+
+## Update to latest
+
+```bash
+docker pull decolua/9router:latest
+docker rm -f 9router
+# re-run the quick start command
+```
+
+---
+
+# 🛠 For Developers
+
+## Build image locally (test)
+
+```bash
+cd app && docker build -t 9router .
+
+docker run --rm -p 20128:20128 \
+  -v "$HOME/.9router:/app/data" \
+  -e DATA_DIR=/app/data \
+  9router
+```
+
+## Publish (automatic via CI)
+
+Push a git tag `v*` → GitHub Actions builds multi-platform (amd64+arm64) and pushes to:
+- `ghcr.io/decolua/9router:v{version}` + `:latest`
+- `decolua/9router:v{version}` + `:latest`
+
+```bash
+# Use scripts/release.js (recommended)
+node scripts/release.js "Release title" "Notes"
+
+# Or manually
+git tag v0.4.x && git push origin v0.4.x
+```
+
+Workflow: `app/.github/workflows/docker-publish.yml`
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..5abe1f2
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,53 @@
+# syntax=docker/dockerfile:1.7
+ARG NODE_IMAGE=node:22-alpine
+FROM ${NODE_IMAGE} AS base
+WORKDIR /app
+
+FROM base AS builder
+
+RUN apk --no-cache upgrade && apk --no-cache add python3 make g++ linux-headers
+
+COPY package.json ./
+RUN --mount=type=cache,target=/root/.npm \
+  npm install
+
+COPY . ./
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+FROM ${NODE_IMAGE} AS runner
+WORKDIR /app
+
+LABEL org.opencontainers.image.title="9router"
+
+ENV NODE_ENV=production
+ENV PORT=20128
+ENV HOSTNAME=0.0.0.0
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV DATA_DIR=/app/data
+
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/custom-server.js ./custom-server.js
+COPY --from=builder /app/open-sse ./open-sse
+# Next file tracing can omit sibling files; MITM runs server.js as a separate process.
+COPY --from=builder /app/src/mitm ./src/mitm
+# Standalone node_modules may omit deps only required by the MITM child process.
+COPY --from=builder /app/node_modules/node-forge ./node_modules/node-forge
+# Ensure `next` is available at runtime in case tracing did not include it.
+COPY --from=builder /app/node_modules/next ./node_modules/next
+
+RUN mkdir -p /app/data && chown -R node:node /app && \
+  mkdir -p /app/data-home && chown node:node /app/data-home && \
+  ln -sf /app/data-home /root/.9router 2>/dev/null || true
+
+# Fix permissions at runtime (handles mounted volumes)
+RUN apk --no-cache upgrade && apk --no-cache add su-exec && \
+  printf '#!/bin/sh\nchown -R node:node /app/data /app/data-home 2>/dev/null\nexec su-exec node "$@"\n' > /entrypoint.sh && \
+  chmod +x /entrypoint.sh
+
+EXPOSE 20128
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["node", "custom-server.js"]
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..9219235
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 decolua and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b6cd76b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,1444 @@
+<div align="center">
+  <img src="./images/9router.png?1" alt="9Router Dashboard" width="800"/>
+  
+  # 9Router - FREE AI Router & Token Saver
+  
+  **Never stop coding. Save 20-40% tokens with RTK + auto-fallback to FREE & cheap AI models.**
+  
+  **Connect All AI Code Tools (Claude Code, Cursor, Antigravity, Copilot, Codex, Gemini, OpenCode, Cline, OpenClaw...) to 40+ AI Providers & 100+ Models.**
+  
+  [![npm](https://img.shields.io/npm/v/9router.svg)](https://www.npmjs.com/package/9router)
+  [![Downloads](https://img.shields.io/npm/dm/9router.svg)](https://www.npmjs.com/package/9router)
+  [![Docker Pulls](https://img.shields.io/docker/pulls/decolua/9router.svg?logo=docker&label=Docker%20pulls)](https://hub.docker.com/r/decolua/9router)
+  [![GHCR](https://img.shields.io/badge/GHCR-decolua%2F9router-blue?logo=github)](https://github.com/decolua/9router/pkgs/container/9router)
+  [![License](https://img.shields.io/npm/l/9router.svg)](https://github.com/decolua/9router/blob/main/LICENSE)
+
+<a href="https://trendshift.io/repositories/22628" target="_blank"><img src="https://trendshift.io/api/badge/repositories/22628" alt="decolua%2F9router | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+
+[🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [📖 Setup](#-setup-guide) • [🌐 Website](https://9router.com)
+
+[🇻🇳 Tiếng Việt](./i18n/README.vi.md) • [🇨🇳 中文](./i18n/README.zh-CN.md) • [🇯🇵 日本語](./i18n/README.ja-JP.md) • [🇷🇺 Русский](./i18n/README.ru.md)
+
+</div>
+
+---
+
+## 🤔 Why 9Router?
+
+**Stop wasting money, tokens and hitting limits:**
+
+- ❌ Subscription quota expires unused every month
+- ❌ Rate limits stop you mid-coding
+- ❌ Tool outputs (git diff, grep, ls...) burn tokens fast
+- ❌ Expensive APIs ($20-50/month per provider)
+- ❌ Manual switching between providers
+
+**9Router solves this:**
+
+- ✅ **RTK Token Saver** - Auto-compress tool_result content, save 20-40% tokens per request
+- ✅ **Maximize subscriptions** - Track quota, use every bit before reset
+- ✅ **Auto fallback** - Subscription → Cheap → Free, zero downtime
+- ✅ **Multi-account** - Round-robin between accounts per provider
+- ✅ **Universal** - Works with Claude Code, Codex, Cursor, Cline, any CLI tool
+
+---
+
+## 🔄 How It Works
+
+```
+┌─────────────┐
+│  Your CLI   │  (Claude Code, Codex, OpenClaw, Cursor, Cline...)
+│   Tool      │
+└──────┬──────┘
+       │ http://localhost:20128/v1
+       ↓
+┌─────────────────────────────────────────────┐
+│           9Router (Smart Router)            │
+│  • RTK Token Saver (cut tool_result tokens) │
+│  • Format translation (OpenAI ↔ Claude)     │
+│  • Quota tracking                           │
+│  • Auto token refresh                       │
+└──────┬──────────────────────────────────────┘
+       │
+       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, GitHub Copilot
+       │   ↓ quota exhausted
+       ├─→ [Tier 2: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
+       │   ↓ budget limit
+       └─→ [Tier 3: FREE] Kiro, OpenCode Free, Vertex ($300 credits)
+
+Result: Never stop coding, minimal cost + 20-40% token savings via RTK
+```
+
+---
+
+## ⚡ Quick Start
+
+**1. Install globally:**
+
+```bash
+npm install -g 9router
+9router
+```
+
+🎉 Dashboard opens at `http://localhost:20128`
+
+**2. Connect a FREE provider (no signup needed):**
+
+Dashboard → Providers → Connect **Kiro AI** (free Claude unlimited) or **OpenCode Free** (no auth) → Done!
+
+**3. Use in your CLI tool:**
+
+```
+Claude Code/Codex/OpenClaw/Cursor/Cline Settings:
+  Endpoint: http://localhost:20128/v1
+  API Key: [copy from dashboard]
+  Model: kr/claude-sonnet-4.5
+```
+
+**That's it!** Start coding with FREE AI models.
+
+**Alternative: run from source (this repository):**
+
+This repository package is private (`9router-app`), so source/Docker execution is the expected local development path.
+
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+Production mode:
+
+```bash
+npm run build
+PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start
+```
+
+Default URLs:
+
+- Dashboard: `http://localhost:20128/dashboard`
+- OpenAI-compatible API: `http://localhost:20128/v1`
+
+---
+
+## Video Guides
+
+<div align="center">
+
+<table>
+  <tr>
+  <td align="center" width="320">
+  <a href="https://www.youtube.com/watch?v=X69n5Lm06Yw">
+    <img src="https://img.youtube.com/vi/X69n5Lm06Yw/maxresdefault.jpg" alt="Tiết kiệm chi phí LLM với 9Router" width="300"/>
+  </a><br/>
+  <b>🇻🇳 Tiếng Việt</b><br/>
+  <sub>Tiết kiệm chi phí LLM cho OpenClaw với 9Router<br/>by <a href="https://www.youtube.com/c/M%C3%ACAIblog">Mì AI</a></sub>
+</td>
+<td align="center" width="320">
+      <a href="https://youtu.be/VQAw612S27Y">
+        <img src="https://img.youtube.com/vi/VQAw612S27Y/maxresdefault.jpg" alt="9Router + Claude Code FREE Unlimited Setup" width="300"/>
+      </a><br/>
+      <b>🇵🇰 اردو / हिन्दी</b><br/>
+      <sub>9Router + Claude Code FREE Unlimited Setup<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=raEyZPg5xE0">
+        <img src="https://img.youtube.com/vi/raEyZPg5xE0/maxresdefault.jpg" alt="9Router Setup Tutorial" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>9Router + Claude Code FREE Setup<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+    
+  </tr>
+  <tr>
+  <td align="center" width="320">
+      <a href="https://youtu.be/3dF5GIYMrcQ?si=bAyfyiHbARJQAHj_">
+        <img src="https://img.youtube.com/vi/3dF5GIYMrcQ/hqdefault.jpg" alt="9Router Setup Tutorial" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>9Router + Claude Code FREE Setup<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=o3qYCyjrFYg">
+        <img src="https://img.youtube.com/vi/o3qYCyjrFYg/maxresdefault.jpg" alt="Claude Code FREE Forever" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>Claude Code FREE Forever — Unlimited Models<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=Ttpc26m39Dw">
+        <img src="https://img.youtube.com/vi/Ttpc26m39Dw/maxresdefault.jpg" alt="Claude CLI Free Setup" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>Claude CLI Free Setup with 9Router 🚀<br/>by <a href="https://www.youtube.com/@CodeVerseSoban">CodeVerse Soban</a></sub>
+    </td>
+    
+  </tr>
+  <tr>
+  <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=G-5A_D5Pm6Y">
+        <img src="https://img.youtube.com/vi/G-5A_D5Pm6Y/maxresdefault.jpg" alt="Cài đặt OpenClaw Free A-Z" width="300"/>
+      </a><br/>
+      <b>🇻🇳 Tiếng Việt</b><br/>
+      <sub>Cài Đặt OpenClaw Free Từ A-Z + 9Router<br/>by <a href="https://www.youtube.com/@maigia">Mai Gia</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=JXmg8_gccgE">
+        <img src="https://img.youtube.com/vi/JXmg8_gccgE/maxresdefault.jpg" alt="FREE OpenClaw with Claude Opus" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>FREE OpenClaw + Claude Opus 4.6<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=CkVZZUSTXAI">
+        <img src="https://img.youtube.com/vi/CkVZZUSTXAI/mqdefault.jpg" alt="Claude CLI Free Setup" width="300"/>
+      </a><br/>
+      <b>🇮🇩 Indonesia</b><br/>
+      <sub>Koding 24 Jam Anti Rate Limit! Hemat Token AI 65% | Tutorial Quick Setup 9Router 🚀<br/>by <a href="https://www.youtube.com/@krisswuh">Krisswuh</a></sub>
+    </td>
+    
+  </tr>
+  
+  <tr>
+  <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=TXGv4eofe1I">
+        <img src="https://img.youtube.com/vi/TXGv4eofe1I/mqdefault.jpg" alt="Cara Deploy 9Router di Hugging Face GRATIS Non-Stop! | Alternatif VPS RAM 16GB" width="300"/>
+      </a><br/>
+      <b>🇮🇩 Indonesia</b><br/>
+      <sub>Cara Deploy 9Router di Hugging Face GRATIS Non-Stop! | Alternatif VPS RAM 16GB<br/>by <a href="https://www.youtube.com/@krisswuh">Krisswuh</a></sub>
+    </td>
+  </tr>
+
+</table>
+
+</div>
+
+> 🎬 **Made a video about 9Router?** Submit a [Pull Request](https://github.com/decolua/9router/pulls) adding your video to this section — we'll merge it!
+
+---
+
+## 🛠️ Supported CLI Tools
+
+9Router works seamlessly with all major AI coding tools:
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="./public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/openclaw.png" width="60" alt="OpenClaw"/><br/>
+        <b>OpenClaw</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/opencode.png" width="60" alt="OpenCode"/><br/>
+        <b>OpenCode</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="120">
+        <img src="./public/providers/cline.png" width="60" alt="Cline"/><br/>
+        <b>Cline</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/continue.png" width="60" alt="Continue"/><br/>
+        <b>Continue</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/droid.png" width="60" alt="Droid"/><br/>
+        <b>Droid</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/roo.png" width="60" alt="Roo"/><br/>
+        <b>Roo</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/copilot.png" width="60" alt="Copilot"/><br/>
+        <b>Copilot</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/kilocode.png" width="60" alt="Kilo Code"/><br/>
+        <b>Kilo Code</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+---
+
+## 🌐 Supported Providers
+
+### 🔐 OAuth Providers
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="./public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/github.png" width="60" alt="GitHub"/><br/>
+        <b>GitHub</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/kimchi.png" width="60" alt="Kimchi"/><br/>
+        <b>Kimchi</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🆓 Free Providers
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="150">
+        <img src="./public/providers/kiro.png" width="70" alt="Kiro"/><br/>
+        <b>Kiro AI</b><br/>
+        <sub>Claude 4.5 + GLM-5 + MiniMax<br/>Unlimited FREE</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="./public/providers/opencode.png" width="70" alt="OpenCode Free"/><br/>
+        <b>OpenCode Free</b><br/>
+        <sub>No auth • Auto-fetch models<br/>Unlimited FREE</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="./public/providers/gemini.png" width="70" alt="Vertex AI"/><br/>
+        <b>Vertex AI</b><br/>
+        <sub>Gemini 3 Pro + GLM-5 + DeepSeek<br/>$300 credits free</sub>
+      </td>
+    </tr>
+  </table>
+</div>
+
+> **Note:** iFlow, Qwen and Gemini CLI free tiers were discontinued in 2026. Use Kiro / OpenCode Free / Vertex instead.
+
+### 🔑 API Key Providers (40+)
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="100">
+        <img src="./public/providers/openrouter.png" width="50" alt="OpenRouter"/><br/>
+        <sub>OpenRouter</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/glm.png" width="50" alt="GLM"/><br/>
+        <sub>GLM</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/kimi.png" width="50" alt="Kimi"/><br/>
+        <sub>Kimi</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/minimax.png" width="50" alt="MiniMax"/><br/>
+        <sub>MiniMax</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/openai.png" width="50" alt="OpenAI"/><br/>
+        <sub>OpenAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/anthropic.png" width="50" alt="Anthropic"/><br/>
+        <sub>Anthropic</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="./public/providers/gemini.png" width="50" alt="Gemini"/><br/>
+        <sub>Gemini</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/deepseek.png" width="50" alt="DeepSeek"/><br/>
+        <sub>DeepSeek</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/groq.png" width="50" alt="Groq"/><br/>
+        <sub>Groq</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/xai.png" width="50" alt="xAI"/><br/>
+        <sub>xAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/mistral.png" width="50" alt="Mistral"/><br/>
+        <sub>Mistral</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/perplexity.png" width="50" alt="Perplexity"/><br/>
+        <sub>Perplexity</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="./public/providers/together.png" width="50" alt="Together"/><br/>
+        <sub>Together AI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/fireworks.png" width="50" alt="Fireworks"/><br/>
+        <sub>Fireworks</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/cerebras.png" width="50" alt="Cerebras"/><br/>
+        <sub>Cerebras</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/cohere.png" width="50" alt="Cohere"/><br/>
+        <sub>Cohere</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/nvidia.png" width="50" alt="NVIDIA"/><br/>
+        <sub>NVIDIA</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/siliconflow.png" width="50" alt="SiliconFlow"/><br/>
+        <sub>SiliconFlow</sub>
+      </td>
+    </tr>
+  </table>
+  <p><i>...and 20+ more providers including Nebius, Chutes, Hyperbolic, and custom OpenAI/Anthropic compatible endpoints</i></p>
+</div>
+
+---
+
+## 💡 Key Features
+
+| Feature                                                                           | What It Does                                                                             | Why It Matters                                    |
+| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| 🚀 **RTK Token Saver** ([RTK](https://github.com/rtk-ai/rtk) ⭐40K)               | Compress tool outputs (`git diff`, `grep`, `ls`, `tree`...) before sending to LLM        | Save **20-40% input tokens** per request          |
+| 🧠 **Headroom Token Saver** ([Headroom](https://github.com/chopratejas/headroom)) | Optional external `/v1/compress` proxy before provider routing                           | Save more context tokens without changing clients |
+| 🪨 **Caveman Mode** ([Caveman](https://github.com/JuliusBrussee/caveman) ⭐52K)   | Inject caveman-speak prompt → LLM replies terse, technical substance preserved           | Save **up to 65% output tokens**                  |
+| 🐴 **Ponytail** ([Ponytail](https://github.com/DietrichGebert/ponytail))          | Inject "lazy senior dev" prompt → LLM writes minimal, YAGNI-first code (Lite/Full/Ultra) | **Fewer output tokens, less refactoring**         |
+| 🎯 **Smart 3-Tier Fallback**                                                      | Auto-route: Subscription → Cheap → Free                                                  | Never stop coding, zero downtime                  |
+| 📊 **Real-Time Quota Tracking**                                                   | Live token count + reset countdown                                                       | Maximize subscription value                       |
+| 🔄 **Format Translation**                                                         | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex                                        | Works with any CLI tool                           |
+| 👥 **Multi-Account Support**                                                      | Multiple accounts per provider                                                           | Load balancing + redundancy                       |
+| 🔄 **Auto Token Refresh**                                                         | OAuth tokens refresh automatically                                                       | No manual re-login needed                         |
+| 🎨 **Custom Combos**                                                              | Create unlimited model combinations                                                      | Tailor fallback to your needs                     |
+| 📝 **Request Logging**                                                            | Debug mode with full request/response logs                                               | Troubleshoot issues easily                        |
+| 💾 **Cloud Sync**                                                                 | Sync config across devices                                                               | Same setup everywhere                             |
+| 📊 **Usage Analytics**                                                            | Track tokens, cost, trends over time                                                     | Optimize spending                                 |
+| 🌐 **Deploy Anywhere**                                                            | Localhost, VPS, Docker, Cloudflare Workers                                               | Flexible deployment options                       |
+
+<details>
+<summary><b>📖 Feature Details</b></summary>
+
+### 🚀 RTK Token Saver
+
+Tool outputs (`git diff`, `grep`, `find`, `ls`, `tree`, log dumps...) often eat 30-50% of your prompt budget. RTK detects them and applies smart, lossless compression **before** the request hits the LLM:
+
+- **Filters:** `git-diff`, `git-status`, `grep`, `find`, `ls`, `tree`, `dedup-log`, `smart-truncate`, `read-numbered`, `search-list`
+- **Auto-detect:** No config needed — RTK peeks the first 1KB of each `tool_result` and picks the right filter.
+- **Safe by design:** If a filter fails, throws, or makes output bigger, RTK silently keeps the original text. Errors never break your request.
+- **Universal:** Works across all formats (OpenAI, Claude, Gemini, Cursor, Kiro, OpenAI Responses) because it runs **before** any format translation.
+- **Default ON:** Toggle anytime in Dashboard → Endpoint settings.
+
+```
+Without RTK: 47K tokens sent to LLM
+With RTK:    28K tokens sent to LLM   (40% saved · same context · same answer)
+```
+
+### 🧠 Headroom Token Saver
+
+Headroom is optional and runs separately. 9Router calls Headroom's local `/v1/compress` endpoint, then keeps normal routing, fallback, auth, and usage tracking:
+
+```
+Client → 9Router → Headroom /v1/compress → 9Router → provider
+```
+
+Local setup:
+
+```bash
+pip install "headroom-ai[proxy]"
+headroom proxy --port 8787
+```
+
+Enable in Dashboard → Endpoint → Token Saver → Headroom. Default URL: `http://localhost:8787`.
+
+Docker examples:
+
+```bash
+# Headroom service in same Docker network
+http://headroom:8787
+
+# Headroom running on host machine
+http://host.docker.internal:8787
+```
+
+If Headroom is down or returns an error, 9Router fails open and sends the original request.
+
+### 🐴 Ponytail (Lazy Senior Dev)
+
+Ponytail injects a _"lazy senior dev"_ system prompt into every request, biasing the LLM toward minimal, YAGNI-first code — deletion over addition, stdlib over new deps, one-liners over abstractions. Adapted from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail).
+
+- **Lite** — Build what's asked, name the lazier alternative.
+- **Full** — YAGNI ladder enforced: stdlib → native → existing deps → one-liner → minimal code.
+- **Ultra** — YAGNI extremist: deletion first, ship the one-liner, challenge the rest of the requirement in the same response.
+
+```
+Without Ponytail: verbose code, extra abstractions, "just in case" scaffolding
+With Ponytail:    shortest working diff, no unrequested abstractions, fewer tokens
+```
+
+Never trades away: input validation, error handling that prevents data loss, security, accessibility, or anything explicitly requested. Enable in Dashboard → Endpoint → Ponytail. Stacks with Caveman (output terseness) and RTK (input compression).
+
+### 🎯 Smart 3-Tier Fallback
+
+Create combos with automatic fallback:
+
+```
+Combo: "my-coding-stack"
+  1. cc/claude-opus-4-6        (your subscription)
+  2. glm/glm-4.7               (cheap backup, $0.6/1M)
+  3. if/kimi-k2-thinking       (free fallback)
+
+→ Auto switches when quota runs out or errors occur
+```
+
+### 📊 Real-Time Quota Tracking
+
+- Token consumption per provider
+- Reset countdown (5-hour, daily, weekly)
+- Cost estimation for paid tiers
+- Monthly spending reports
+
+### 🔄 Format Translation
+
+Seamless translation between formats:
+
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **Cursor** ↔ **Kiro** ↔ **Vertex** ↔ **Antigravity** ↔ **Ollama** ↔ **OpenAI Responses**
+- Your CLI tool sends OpenAI format → 9Router translates → Provider receives native format
+- Works with any tool that supports custom OpenAI endpoints
+
+### 👥 Multi-Account Support
+
+- Add multiple accounts per provider
+- Auto round-robin or priority-based routing
+- Fallback to next account when one hits quota
+
+### 🔄 Auto Token Refresh
+
+- OAuth tokens automatically refresh before expiration
+- No manual re-authentication needed
+- Seamless experience across all providers
+
+### 🎨 Custom Combos
+
+- Create unlimited model combinations
+- Mix subscription, cheap, and free tiers
+- Name your combos for easy access
+- Share combos across devices with Cloud Sync
+
+### 📝 Request Logging
+
+- Enable debug mode for full request/response logs
+- Track API calls, headers, and payloads
+- Troubleshoot integration issues
+- Export logs for analysis
+
+### 💾 Cloud Sync
+
+- Sync providers, combos, and settings across devices
+- Automatic background sync
+- Secure encrypted storage
+- Access your setup from anywhere
+
+#### Cloud Runtime Notes
+
+- Prefer server-side cloud variables in production:
+  - `BASE_URL` (internal callback URL used by sync scheduler)
+  - `CLOUD_URL` (cloud sync endpoint base)
+- `NEXT_PUBLIC_BASE_URL` and `NEXT_PUBLIC_CLOUD_URL` are still supported for compatibility/UI, but server runtime now prioritizes `BASE_URL`/`CLOUD_URL`.
+- Cloud sync requests now use timeout + fail-fast behavior to avoid UI hanging when cloud DNS/network is unavailable.
+
+### 📊 Usage Analytics
+
+- Track token usage per provider and model
+- Cost estimation and spending trends
+- Monthly reports and insights
+- Optimize your AI spending
+
+> **💡 IMPORTANT - Understanding Dashboard Costs:**
+>
+> The "cost" displayed in Usage Analytics is **for tracking and comparison purposes only**.
+> 9Router itself **never charges** you anything. You only pay providers directly (if using paid services).
+>
+> **Example:** If your dashboard shows "$290 total cost" while using iFlow models, this represents
+> what you would have paid using paid APIs directly. Your actual cost = **$0** (iFlow is free unlimited).
+>
+> Think of it as a "savings tracker" showing how much you're saving by using free models or
+> routing through 9Router!
+
+### 🌐 Deploy Anywhere
+
+- 💻 **Localhost** - Default, works offline
+- ☁️ **VPS/Cloud** - Share across devices
+- 🐳 **Docker** - One-command deployment
+- 🚀 **Cloudflare Workers** - Global edge network
+
+</details>
+
+---
+
+## 💰 Pricing at a Glance
+
+| Tier                | Provider              | Cost         | Quota Reset      | Best For                                |
+| ------------------- | --------------------- | ------------ | ---------------- | --------------------------------------- |
+| **🚀 TOKEN SAVER**  | **RTK (built-in)**    | **FREE**     | Always on        | **Save 20-40% tokens on EVERY request** |
+| **💳 SUBSCRIPTION** | Claude Code (Pro/Max) | $20-200/mo   | 5h + weekly      | Already subscribed                      |
+|                     | Codex (Plus/Pro)      | $20-200/mo   | 5h + weekly      | OpenAI users                            |
+|                     | GitHub Copilot        | $10-19/mo    | Monthly          | GitHub users                            |
+|                     | Cursor IDE            | $20/mo       | Monthly          | Cursor users                            |
+| **💰 CHEAP**        | GLM-5.1 / GLM-4.7     | $0.6/1M      | Daily 10AM       | Budget backup                           |
+|                     | MiniMax M2.7          | $0.2/1M      | 5-hour rolling   | Cheapest option                         |
+|                     | Kimi K2.5             | $9/mo flat   | 10M tokens/mo    | Predictable cost                        |
+| **🆓 FREE**         | Kiro AI               | $0           | Unlimited        | Claude 4.5 + GLM-5 + MiniMax free       |
+|                     | OpenCode Free         | $0           | Unlimited        | No auth, auto-fetch models              |
+|                     | Vertex AI             | $300 credits | New GCP accounts | Gemini 3 Pro + DeepSeek + GLM-5         |
+
+**💡 Pro Tip:** RTK + Kiro AI + OpenCode Free combo = **$0 cost + 20-40% token savings**!
+
+---
+
+### 📊 Understanding 9Router Costs & Billing
+
+**9Router Billing Reality:**
+
+✅ **9Router software = FREE forever** (open source, never charges)  
+✅ **Dashboard "costs" = Display/tracking only** (not actual bills)  
+✅ **You pay providers directly** (subscriptions or API fees)  
+✅ **FREE providers stay FREE** (iFlow, Kiro, Qwen = $0 unlimited)  
+❌ **9Router never sends invoices** or charges your card
+
+**How Cost Display Works:**
+
+The dashboard shows **estimated costs** as if you were using paid APIs directly. This is **not billing** - it's a comparison tool to show your savings.
+
+**Example Scenario:**
+
+```
+Dashboard Display:
+• Total Requests: 1,662
+• Total Tokens: 47M
+• Display Cost: $290
+
+Reality Check:
+• Provider: iFlow (FREE unlimited)
+• Actual Payment: $0.00
+• What $290 Means: Amount you SAVED by using free models!
+```
+
+**Payment Rules:**
+
+- **Subscription providers** (Claude Code, Codex): Pay them directly via their websites
+- **Cheap providers** (GLM, MiniMax): Pay them directly, 9Router just routes
+- **FREE providers** (iFlow, Kiro, Qwen): Genuinely free forever, no hidden charges
+- **9Router**: Never charges anything, ever
+
+---
+
+## 🎯 Use Cases
+
+### Case 1: "I have Claude Pro subscription"
+
+**Problem:** Quota expires unused, rate limits during heavy coding
+
+**Solution:**
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-7        (use subscription fully)
+  2. glm/glm-5.1               (cheap backup when quota out)
+  3. kr/claude-sonnet-4.5      (free emergency fallback)
+
+Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
+vs. $20 + hitting limits = frustration
+```
+
+### Case 2: "I want zero cost"
+
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+**Solution:**
+
+```
+Combo: "free-forever"
+  1. kr/claude-sonnet-4.5      (Claude 4.5 free unlimited)
+  2. kr/glm-5                  (GLM-5 free via Kiro)
+  3. oc/<auto>                 (OpenCode Free, no auth)
+
+Monthly cost: $0
+Quality: Production-ready models + RTK saves 20-40% tokens
+```
+
+### Case 3: "I need 24/7 coding, no interruptions"
+
+**Problem:** Deadlines, can't afford downtime
+
+**Solution:**
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-7        (best quality)
+  2. cx/gpt-5.5                (second subscription)
+  3. glm/glm-5.1               (cheap, resets daily)
+  4. minimax/MiniMax-M2.7      (cheapest, 5h reset)
+  5. kr/claude-sonnet-4.5      (free unlimited)
+
+Result: 5 layers of fallback = zero downtime
+Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
+```
+
+### Case 4: "I want FREE AI in OpenClaw"
+
+**Problem:** Need AI assistant in messaging apps (WhatsApp, Telegram, Slack...), completely free
+
+**Solution:**
+
+```
+Combo: "openclaw-free"
+  1. kr/claude-sonnet-4.5      (Claude 4.5 free)
+  2. kr/glm-5                  (GLM-5 free)
+  3. kr/MiniMax-M2.5           (MiniMax free)
+
+Monthly cost: $0
+Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## ❓ Frequently Asked Questions
+
+<details>
+<summary><b>📊 Why does my dashboard show high costs?</b></summary>
+
+The dashboard tracks your token usage and displays **estimated costs** as if you were using paid APIs directly. This is **not actual billing** - it's a reference to show how much you're saving by using free models or existing subscriptions through 9Router.
+
+**Example:**
+
+- **Dashboard shows:** "$290 total cost"
+- **Reality:** You're using iFlow (FREE unlimited)
+- **Your actual cost:** **$0.00**
+- **What $290 means:** Amount you **saved** by using free models instead of paid APIs!
+
+The cost display is a "savings tracker" to help you understand your usage patterns and optimization opportunities.
+
+</details>
+
+<details>
+<summary><b>💳 Will I be charged by 9Router?</b></summary>
+
+**No.** 9Router is free, open-source software that runs on your own computer. It never charges you anything.
+
+**You only pay:**
+
+- ✅ **Subscription providers** (Claude Code $20/mo, Codex $20-200/mo) → Pay them directly on their websites
+- ✅ **Cheap providers** (GLM, MiniMax) → Pay them directly, 9Router just routes your requests
+- ❌ **9Router itself** → **Never charges anything, ever**
+
+9Router is a local proxy/router. It doesn't have your credit card, can't send invoices, and has no billing system. It's completely free software.
+
+</details>
+
+<details>
+<summary><b>🆓 Are FREE providers really unlimited?</b></summary>
+
+**Yes!** The current FREE providers (Kiro, OpenCode Free, Vertex) are genuinely free with **no hidden charges**.
+
+These are free services offered by those respective companies:
+
+- **Kiro AI**: Free unlimited Claude 4.5 + GLM-5 + MiniMax via AWS Builder ID / Google / GitHub OAuth
+- **OpenCode Free**: No-auth passthrough proxy, models auto-fetched from `opencode.ai/zen/v1/models`
+- **Vertex AI**: $300 free credits for new Google Cloud accounts (90 days)
+
+9Router just routes your requests to them - there's no "catch" or future billing. They're truly free services, and 9Router makes them easy to use with fallback support.
+
+**Discontinued free tiers (no longer recommended):**
+
+- ❌ **iFlow**: Was free unlimited, now changed to paid (2026)
+- ❌ **Qwen Code**: Free OAuth tier discontinued by Alibaba on 2026-04-15
+- ❌ **Gemini CLI**: Still works, but using it with non-CLI tools (Claude, Codex, Cursor...) may result in account bans — only use if you stick to Gemini CLI itself
+
+</details>
+
+<details>
+<summary><b>💰 How do I minimize my actual AI costs?</b></summary>
+
+**Free-First Strategy:**
+
+1. **Start with 100% free combo:**
+
+   ```
+   1. gc/gemini-3-flash (180K/month free from Google)
+   2. if/kimi-k2-thinking (unlimited free from iFlow)
+   3. qw/qwen3-coder-plus (unlimited free from Qwen)
+   ```
+
+   **Cost: $0/month**
+
+2. **Add cheap backup** only if you need it:
+
+   ```
+   4. glm/glm-4.7 ($0.6/1M tokens)
+   ```
+
+   **Additional cost: Only pay for what you actually use**
+
+3. **Use subscription providers last:**
+   - Only if you already have them
+   - 9Router helps maximize their value through quota tracking
+
+**Result:** Most users can operate at $0/month using only free tiers!
+
+</details>
+
+<details>
+<summary><b>📈 What if my usage suddenly spikes?</b></summary>
+
+9Router's smart fallback prevents surprise charges:
+
+**Scenario:** You're on a coding sprint and blow through your quotas
+
+**Without 9Router:**
+
+- ❌ Hit rate limit → Work stops → Frustration
+- ❌ Or: Accidentally rack up huge API bills
+
+**With 9Router:**
+
+- ✅ Subscription hits limit → Auto-fallback to cheap tier
+- ✅ Cheap tier gets expensive → Auto-fallback to free tier
+- ✅ Never stop coding → Predictable costs
+
+**You're in control:** Set spending limits per provider in dashboard, and 9Router respects them.
+
+</details>
+
+---
+
+## 📖 Setup Guide
+
+<details>
+<summary><b>🔐 Subscription Providers (Maximize Value)</b></summary>
+
+### Claude Code (Pro/Max)
+
+```bash
+Dashboard → Providers → Connect Claude Code
+→ OAuth login → Auto token refresh
+→ 5-hour + weekly quota tracking
+
+Models:
+  cc/claude-opus-4-7
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-6
+  cc/claude-haiku-4-5-20251001
+```
+
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. 9Router tracks quota per model!
+
+### OpenAI Codex (Plus/Pro)
+
+```bash
+Dashboard → Providers → Connect Codex
+→ OAuth login (port 1455)
+→ 5-hour + weekly reset
+
+Models:
+  cx/gpt-5.5
+  cx/gpt-5.4
+  cx/gpt-5.3-codex
+  cx/gpt-5.2-codex
+```
+
+### GitHub Copilot
+
+```bash
+Dashboard → Providers → Connect GitHub
+→ OAuth via GitHub
+→ Monthly reset (1st of month)
+
+Models:
+  gh/gpt-5.4
+  gh/claude-opus-4.7
+  gh/claude-sonnet-4.6
+  gh/gemini-3.1-pro-preview
+  gh/grok-code-fast-1
+```
+
+### Cursor IDE
+
+```bash
+Dashboard → Providers → Connect Cursor
+→ OAuth login
+→ Monthly subscription
+
+Models:
+  cu/claude-4.6-opus-max
+  cu/claude-4.5-sonnet-thinking
+  cu/gpt-5.3-codex
+```
+
+</details>
+
+<details>
+<summary><b>💰 Cheap Providers (Backup)</b></summary>
+
+### GLM-5.1 / GLM-4.7 (Daily reset, $0.6/1M)
+
+1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)
+2. Get API key from Coding Plan
+3. Dashboard → Add API Key:
+   - Provider: `glm`
+   - API Key: `your-key`
+
+**Use:** `glm/glm-5.1`, `glm/glm-5`, `glm/glm-4.7`
+
+**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
+
+### MiniMax M2.7 (5h reset, $0.20/1M)
+
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key
+3. Dashboard → Add API Key
+
+**Use:** `minimax/MiniMax-M2.7`, `minimax/MiniMax-M2.5`
+
+**Pro Tip:** Cheapest option for long context (1M tokens)!
+
+### Kimi K2.5 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key
+3. Dashboard → Add API Key
+
+**Use:** `kimi/kimi-k2.5`, `kimi/kimi-k2.5-thinking`
+
+**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+</details>
+
+<details>
+<summary><b>🆓 FREE Providers (Recommended)</b></summary>
+
+### Kiro AI (Claude 4.5 + GLM-5 + MiniMax FREE)
+
+```bash
+Dashboard → Connect Kiro
+→ AWS Builder ID, AWS IAM Identity Center, Google, or GitHub
+→ Unlimited usage
+
+Models:
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+  kr/glm-5
+  kr/MiniMax-M2.5
+  kr/qwen3-coder-next
+  kr/deepseek-3.2
+```
+
+**Pro Tip:** Best free option for Claude. No API key, no payment, fully unlimited.
+
+### OpenCode Free (No auth, auto-fetch models)
+
+```bash
+Dashboard → Connect OpenCode Free
+→ No login required (passthrough proxy)
+→ Models auto-fetched from opencode.ai/zen/v1/models
+```
+
+**Pro Tip:** Fastest setup. Just connect and start coding.
+
+### Vertex AI ($300 free credits for new GCP accounts)
+
+```bash
+Dashboard → Connect Vertex AI
+→ Upload Google Cloud Service Account JSON
+→ Enable Vertex AI API in your GCP project
+
+Models:
+  vertex/gemini-3.1-pro-preview
+  vertex/gemini-3-flash-preview
+  vertex/gemini-2.5-flash
+
+Vertex Partner (Anthropic / DeepSeek / GLM / Qwen via Vertex):
+  vertex-partner/glm-5-maas
+  vertex-partner/deepseek-v3.2-maas
+  vertex-partner/qwen3-next-80b-a3b-thinking-maas
+```
+
+**Pro Tip:** New Google Cloud accounts get $300 credits free for 90 days. Plenty for daily coding.
+
+</details>
+
+<details>
+<summary><b>🎨 Create Combos</b></summary>
+
+### Example 1: Maximize Subscription → Cheap Backup
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-7 (Subscription primary)
+  2. glm/glm-5.1 (Cheap backup, $0.6/1M)
+  3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.20/1M)
+
+Use in CLI: premium-coding
+
+Monthly cost example (100M tokens):
+  80M via Claude (subscription): $0 extra
+  15M via GLM: $9
+  5M via MiniMax: $1
+  Total: $10 + your subscription
+```
+
+### Example 2: Free-Only (Zero Cost)
+
+```
+Name: free-combo
+Models:
+  1. kr/claude-sonnet-4.5 (Claude 4.5 free unlimited)
+  2. kr/glm-5 (GLM-5 free via Kiro)
+  3. vertex/gemini-3.1-pro-preview ($300 free credits)
+
+Cost: $0 forever (+ 20-40% token savings via RTK)!
+```
+
+</details>
+
+<details>
+<summary><b>🔧 CLI Integration</b></summary>
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: cc/claude-opus-4-7
+```
+
+Or use combo: `premium-coding`
+
+### Claude Code
+
+Edit `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+### OpenClaw
+
+**Option 1 — Dashboard (recommended):**
+
+```
+Dashboard → CLI Tools → OpenClaw → Select Model → Apply
+```
+
+**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "9router/kr/claude-sonnet-4.5"
+      }
+    }
+  },
+  "models": {
+    "providers": {
+      "9router": {
+        "baseUrl": "http://127.0.0.1:20128/v1",
+        "apiKey": "sk_9router",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "kr/claude-sonnet-4.5",
+            "name": "Claude Sonnet 4.5 (Kiro Free)"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+> **Note:** OpenClaw only works with local 9Router. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-7
+```
+
+</details>
+
+<details>
+<summary><b>🚀 Deployment</b></summary>
+
+### VPS Deployment
+
+```bash
+# Clone and install
+git clone https://github.com/decolua/9router.git
+cd 9router
+npm install
+npm run build
+
+# Configure
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/9router"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export NEXT_PUBLIC_CLOUD_URL="https://9router.com"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+export MACHINE_ID_SALT="endpoint-proxy-salt"
+
+# Start
+npm run start
+
+# Or use PM2
+npm install -g pm2
+pm2 start npm --name 9router -- start
+pm2 save
+pm2 startup
+```
+
+### Docker
+
+Published images (multi-platform `linux/amd64` + `linux/arm64`):
+
+- Docker Hub: [`decolua/9router`](https://hub.docker.com/r/decolua/9router)
+- GHCR: [`ghcr.io/decolua/9router`](https://github.com/decolua/9router/pkgs/container/9router)
+
+**Quick start (use published image):**
+
+```bash
+docker run -d \
+  --name 9router \
+  -p 20128:20128 \
+  -v "$HOME/.9router:/app/data" \
+  -e DATA_DIR=/app/data \
+  decolua/9router:latest
+```
+
+→ Open http://localhost:20128
+
+**Build from source (dev):**
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+docker build -t 9router .
+docker run -d --name 9router -p 20128:20128 \
+  -v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data 9router
+```
+
+**Container defaults:**
+
+- `PORT=20128`
+- `HOSTNAME=0.0.0.0`
+
+**Useful commands:**
+
+```bash
+docker logs -f 9router
+docker restart 9router
+docker stop 9router && docker rm 9router
+docker pull decolua/9router:latest   # update to latest
+```
+
+**Data persistence:** `$HOME/.9router/db/data.sqlite` on host ↔ `/app/data/db/data.sqlite` in container.
+
+### Environment Variables
+
+| Variable                                             | Default                                  | Description                                                                         |
+| ---------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------- |
+| `JWT_SECRET`                                         | Auto-generated (`~/.9router/jwt-secret`) | JWT signing secret for dashboard auth cookie (override to share across instances)   |
+| `INITIAL_PASSWORD`                                   | `123456`                                 | First login password when no saved hash exists                                      |
+| `DATA_DIR`                                           | `~/.9router`                             | Main app data location (SQLite at `$DATA_DIR/db/data.sqlite`)                       |
+| `PORT`                                               | framework default                        | Service port (`20128` in examples)                                                  |
+| `HOSTNAME`                                           | framework default                        | Bind host (Docker defaults to `0.0.0.0`)                                            |
+| `NODE_ENV`                                           | runtime default                          | Set `production` for deploy                                                         |
+| `BASE_URL`                                           | `http://localhost:20128`                 | Server-side internal base URL used by cloud sync jobs                               |
+| `CLOUD_URL`                                          | `https://9router.com`                    | Server-side cloud sync endpoint base URL                                            |
+| `NEXT_PUBLIC_BASE_URL`                               | `http://localhost:3000`                  | Backward-compatible/public base URL (prefer `BASE_URL` for server runtime)          |
+| `NEXT_PUBLIC_CLOUD_URL`                              | `https://9router.com`                    | Backward-compatible/public cloud URL (prefer `CLOUD_URL` for server runtime)        |
+| `API_KEY_SECRET`                                     | `endpoint-proxy-api-key-secret`          | HMAC secret for generated API keys                                                  |
+| `MACHINE_ID_SALT`                                    | `endpoint-proxy-salt`                    | Salt for stable machine ID hashing                                                  |
+| `ENABLE_REQUEST_LOGS`                                | `false`                                  | Enables request/response logs under `logs/`                                         |
+| `AUTH_COOKIE_SECURE`                                 | `false`                                  | Force `Secure` auth cookie (set `true` behind HTTPS reverse proxy)                  |
+| `REQUIRE_API_KEY`                                    | `false`                                  | Enforce Bearer API key on `/v1/*` routes (recommended for internet-exposed deploys) |
+| `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` | empty                                    | Optional outbound proxy for upstream provider calls                                 |
+| `SEARXNG_URL`                                        | `http://localhost:8888/search`           | Endpoint for the built-in unauthenticated SearXNG web-search provider               |
+
+Notes:
+
+- Lowercase proxy variables are also supported: `http_proxy`, `https_proxy`, `all_proxy`, `no_proxy`.
+- `.env` is not baked into Docker image (`.dockerignore`); inject runtime config with `--env-file` or `-e`.
+- On Windows, `APPDATA` can be used for local storage path resolution.
+- `INSTANCE_NAME` appears in older docs/env templates, but is currently not used at runtime.
+
+### Runtime Files and Storage
+
+- Main app state: `${DATA_DIR}/db/data.sqlite` (SQLite — providers, combos, aliases, keys, settings, usage history)
+- Auto backups: `${DATA_DIR}/db/backups/`
+- Optional request/translator logs: `<repo>/logs/...` when `ENABLE_REQUEST_LOGS=true`
+- Both `${DATA_DIR}` and `~/.9router` resolve to the same location in a Docker container — the symlink `/root/.9router -> /app/data` is created at build time.
+
+</details>
+
+---
+
+## 📊 Available Models
+
+<details>
+<summary><b>View all available models</b></summary>
+
+**Claude Code (`cc/`)** - Pro/Max:
+
+- `cc/claude-opus-4-7`
+- `cc/claude-opus-4-6`
+- `cc/claude-sonnet-4-6`
+- `cc/claude-sonnet-4-5-20250929`
+- `cc/claude-haiku-4-5-20251001`
+
+**Codex (`cx/`)** - Plus/Pro:
+
+- `cx/gpt-5.5`
+- `cx/gpt-5.4`
+- `cx/gpt-5.3-codex`
+- `cx/gpt-5.2-codex`
+- `cx/gpt-5.1-codex-max`
+
+**GitHub Copilot (`gh/`)**:
+
+- `gh/gpt-5.4`
+- `gh/claude-opus-4.7`
+- `gh/claude-sonnet-4.6`
+- `gh/gemini-3.1-pro-preview`
+- `gh/grok-code-fast-1`
+
+**Cursor (`cu/`)** - Subscription:
+
+- `cu/claude-4.6-opus-max`
+- `cu/claude-4.5-sonnet-thinking`
+- `cu/gpt-5.3-codex`
+- `cu/kimi-k2.5`
+
+**GLM (`glm/`)** - $0.6/1M:
+
+- `glm/glm-5.1`
+- `glm/glm-5`
+- `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** - $0.2/1M:
+
+- `minimax/MiniMax-M2.7`
+- `minimax/MiniMax-M2.5`
+
+**Kimi (`kimi/`)** - $9/mo flat:
+
+- `kimi/kimi-k2.5`
+- `kimi/kimi-k2.5-thinking`
+
+**Kiro (`kr/`)** - FREE unlimited:
+
+- `kr/claude-sonnet-4.5`
+- `kr/claude-haiku-4.5`
+- `kr/glm-5`
+- `kr/MiniMax-M2.5`
+- `kr/qwen3-coder-next`
+- `kr/deepseek-3.2`
+
+**OpenCode Free (`oc/`)** - FREE no-auth:
+
+- Auto-fetched from `opencode.ai/zen/v1/models`
+
+**Vertex AI (`vertex/`)** - $300 free credits:
+
+- `vertex/gemini-3.1-pro-preview`
+- `vertex/gemini-3-flash-preview`
+- `vertex/gemini-2.5-flash`
+- `vertex-partner/glm-5-maas`
+- `vertex-partner/deepseek-v3.2-maas`
+
+</details>
+
+---
+
+## 🐛 Troubleshooting
+
+**"Language model did not provide messages"**
+
+- Provider quota exhausted → Check dashboard quota tracker
+- Solution: Use combo fallback or switch to cheaper tier
+
+**Rate limiting**
+
+- Subscription quota out → Fallback to GLM/MiniMax
+- Add combo: `cc/claude-opus-4-7 → glm/glm-5.1 → kr/claude-sonnet-4.5`
+
+**OAuth token expired**
+
+- Auto-refreshed by 9Router
+- If issues persist: Dashboard → Provider → Reconnect
+
+**High costs**
+
+- Enable RTK in Dashboard → Endpoint settings (default ON, saves 20-40% tokens)
+- Check usage stats in Dashboard
+- Switch primary model to GLM/MiniMax
+- Use free tier (Kiro, OpenCode Free, Vertex) for non-critical tasks
+
+**Dashboard opens on wrong port**
+
+- Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+
+**First login not working**
+
+- Check `INITIAL_PASSWORD` in `.env`
+- If unset, fallback password is `123456`
+
+**No request logs under `logs/`**
+
+- Set `ENABLE_REQUEST_LOGS=true`
+
+---
+
+## 🛠️ Tech Stack
+
+- **Runtime**: Node.js 20+
+- **Framework**: Next.js 16
+- **UI**: React 19 + Tailwind CSS 4
+- **Database**: SQLite (better-sqlite3 / node:sqlite / sql.js fallback)
+- **Streaming**: Server-Sent Events (SSE)
+- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
+
+---
+
+## 📝 API Reference
+
+### Chat Completions
+
+```bash
+POST http://localhost:20128/v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### List Models
+
+```bash
+GET http://localhost:20128/v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all models + combos in OpenAI format
+```
+
+## 📧 Support
+
+- **Website**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+
+---
+
+## 👥 Contributors
+
+Thanks to all contributors who helped make 9Router better!
+
+[![Contributors](https://contrib.rocks/image?repo=decolua/9router&max=150&columns=15&anon=1&v=20260309)](https://github.com/decolua/9router/graphs/contributors)
+
+---
+
+## 📊 Star Chart
+
+[![Star Chart](https://starchart.cc/decolua/9router.svg?variant=adaptive)](https://starchart.cc/decolua/9router)
+
+## 🔀 Forks
+
+**[OmniRoute](https://github.com/diegosouzapw/OmniRoute)** — A full-featured TypeScript fork of 9Router. Adds 36+ providers, 4-tier auto-fallback, multi-modal APIs (images, embeddings, audio, TTS), circuit breaker, semantic cache, LLM evaluations, and a polished dashboard. 368+ unit tests. Available via npm and Docker.
+
+---
+
+## 🙏 Acknowledgments
+
+Built on the shoulders of giants:
+
+- **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — original Go implementation that inspired this JavaScript port.
+- **[RTK](https://github.com/rtk-ai/rtk)** ![Stars](https://img.shields.io/github/stars/rtk-ai/rtk?style=flat&color=yellow) — Rust token-saver. 9Router ports its compression pipeline to JS → **−20-40% input tokens** on every request.
+- **[Caveman](https://github.com/JuliusBrussee/caveman)** ![Stars](https://img.shields.io/github/stars/JuliusBrussee/caveman?style=flat&color=yellow) by **[@JuliusBrussee](https://github.com/JuliusBrussee)** — viral _"why use many token when few token do trick"_. 9Router adapts its prompt → **−65% output tokens**.
+- **[Ponytail](https://github.com/DietrichGebert/ponytail)** ![Stars](https://img.shields.io/github/stars/DietrichGebert/ponytail?style=flat&color=yellow) by **[@DietrichGebert](https://github.com/DietrichGebert)** — _"lazy senior dev"_ skill. 9Router injects its YAGNI-first ladder → **fewer tokens, less code, shorter diffs**.
+
+Huge thanks to these authors — without their work, 9Router's token-saving features wouldn't exist. ⭐ them on GitHub!
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ for developers who code 24/7</sub>
+</div>
diff --git a/README.wehub.md b/README.wehub.md
new file mode 100644
index 0000000..0241f22
--- /dev/null
+++ b/README.wehub.md
@@ -0,0 +1,7 @@
+# WeHub 来源说明
+
+- 原始项目：`decolua/9router`
+- 原始仓库：https://github.com/decolua/9router
+- 导入方式：上游默认分支的最新快照
+- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
+- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..8ba77ff
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,1311 @@
+
+<div align="center">
+  <img src="./images/9router.png?1" alt="9Router Dashboard" width="800"/>
+  
+  # 9Router - 免费 AI 路由器与 Token 节省器
+  
+  **编程永不停歇。使用 RTK + 自动切换到免费/低价 AI 模型，节省 20-40% 的 tokens。**
+  
+  **将所有 AI 编程工具（Claude Code、Cursor、Antigravity、Copilot、Codex、Gemini、OpenCode、Cline、OpenClaw...）连接到 40+ AI 提供商和 100+ 模型。**
+  
+  [![npm](https://img.shields.io/npm/v/9router.svg)](https://www.npmjs.com/package/9router)
+  [![Downloads](https://img.shields.io/npm/dm/9router.svg)](https://www.npmjs.com/package/9router)
+  [![License](https://img.shields.io/npm/l/9router.svg)](https://github.com/decolua/9router/blob/main/LICENSE)
+
+  <a href="https://trendshift.io/repositories/22628" target="_blank"><img src="https://trendshift.io/api/badge/repositories/22628" alt="decolua%2F9router | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+  
+  [🚀 快速开始](#-快速开始) • [💡 功能特点](#-主要功能) • [📖 设置指南](#-设置指南) • [🌐 网站](https://9router.com)
+
+  [🇻🇳 Tiếng Việt](./i18n/README.vi.md) • [🇨🇳 中文](./i18n/README.zh-CN.md) • [🇯🇵 日本語](./i18n/README.ja-JP.md)
+</div>
+
+---
+
+## 🤔 为什么选择 9Router？
+
+**告别浪费金钱、tokens 和触碰限制的困扰：**
+
+- ❌ 订阅配额每月到期却未使用
+- ❌ 速率限制在编程中途打断你
+- ❌ 工具输出（git diff、grep、ls...）快速消耗 tokens
+- ❌ 昂贵的 API（每个提供商 $20-50/月）
+- ❌ 需要手动在提供商之间切换
+
+**9Router 解决这一切：**
+
+- ✅ **RTK Token 节省器** - 自动压缩 tool_result 内容，每次请求节省 20-40% tokens
+- ✅ **充分利用订阅** - 追踪配额，在重置前用尽每一分额度
+- ✅ **自动切换** - 订阅 → 低价 → 免费，零停机时间
+- ✅ **多账户支持** - 按提供商在账户之间轮询
+- ✅ **通用兼容** - 支持 Claude Code、Codex、Cursor、Cline 以及任何 CLI 工具
+
+---
+
+## 🔄 工作原理
+
+```
+┌─────────────┐
+│  你的 CLI   │  (Claude Code、Codex、OpenClaw、Cursor、Cline...)
+│   工具      │
+└──────┬──────┘
+       │ http://localhost:20128/v1
+       ↓
+┌─────────────────────────────────────────────┐
+│           9Router（智能路由器）              │
+│  • RTK Token 节省器（减少 tool_result tokens）│
+│  • 格式转换（OpenAI ↔ Claude）              │
+│  • 配额追踪                                  │
+│  • 自动刷新 token                           │
+└──────┬──────────────────────────────────────┘
+       │
+       ├─→ [第一层：订阅] Claude Code、Codex、GitHub Copilot
+       │   ↓ 配额耗尽
+       ├─→ [第二层：低价] GLM ($0.6/1M)、MiniMax ($0.2/1M)
+       │   ↓ 预算超限
+       └─→ [第三层：免费] Kiro、OpenCode Free、Vertex ($300 额度)
+
+结果：编程永不停歇，最小成本 + 通过 RTK 节省 20-40% tokens
+```
+
+---
+
+## ⚡ 快速开始
+
+**1. 全局安装：**
+
+```bash
+npm install -g 9router
+9router
+```
+
+🎉 控制面板在 `http://localhost:20128` 打开
+
+**2. 连接免费提供商（无需注册）：**
+
+控制面板 → 提供商 → 连接 **Kiro AI**（免费 Claude 无限量）或 **OpenCode Free**（无需认证）→ 完成！
+
+**3. 在 CLI 工具中使用：**
+
+```
+Claude Code/Codex/OpenClaw/Cursor/Cline 设置：
+  Endpoint: http://localhost:20128/v1
+  API Key: [从控制面板复制]
+  Model: kr/claude-sonnet-4.5
+```
+
+**就这么简单！** 开始使用免费 AI 模型编程。
+
+**替代方案：从源码运行（本仓库）：**
+
+本仓库的包是私有的（`9router-app`），所以源码/Docker 执行是预期的本地开发方式。
+
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+生产模式：
+
+```bash
+npm run build
+PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start
+```
+
+默认 URL：
+- 控制面板：`http://localhost:20128/dashboard`
+- OpenAI 兼容 API：`http://localhost:20128/v1`
+
+---
+
+## 视频教程
+
+<div align="center">
+
+<table>
+  <tr>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=raEyZPg5xE0">
+        <img src="https://img.youtube.com/vi/raEyZPg5xE0/maxresdefault.jpg" alt="9Router Setup Tutorial" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>9Router + Claude Code 免费设置<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=X69n5Lm06Yw">
+        <img src="https://img.youtube.com/vi/X69n5Lm06Yw/maxresdefault.jpg" alt="Tiết kiệm chi phí LLM với 9Router" width="300"/>
+      </a><br/>
+      <b>🇻🇳 Tiếng Việt</b><br/>
+      <sub>使用 9Router 节省 OpenClaw 的 LLM 成本<br/>by <a href="https://www.youtube.com/c/M%C3%ACAIblog">Mì AI</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=o3qYCyjrFYg">
+        <img src="https://img.youtube.com/vi/o3qYCyjrFYg/maxresdefault.jpg" alt="Claude Code FREE Forever" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>Claude Code 免费永久使用 — 无限模型<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=Ttpc26m39Dw">
+        <img src="https://img.youtube.com/vi/Ttpc26m39Dw/maxresdefault.jpg" alt="Claude CLI Free Setup" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>使用 9Router 免费设置 Claude CLI 🚀<br/>by <a href="https://www.youtube.com/@CodeVerseSoban">CodeVerse Soban</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=G-5A_D5Pm6Y">
+        <img src="https://img.youtube.com/vi/G-5A_D5Pm6Y/maxresdefault.jpg" alt="Cài đặt OpenClaw Free A-Z" width="300"/>
+      </a><br/>
+      <b>🇻🇳 Tiếng Việt</b><br/>
+      <sub>从零开始安装 OpenClaw 免费版 + 9Router<br/>by <a href="https://www.youtube.com/@maigia">Mai Gia</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=JXmg8_gccgE">
+        <img src="https://img.youtube.com/vi/JXmg8_gccgE/maxresdefault.jpg" alt="FREE OpenClaw with Claude Opus" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>免费 OpenClaw + Claude Opus 4.6<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+  </tr>
+</table>
+
+</div>
+
+> 🎬 **制作了关于 9Router 的视频？** 提交 [Pull Request](https://github.com/decolua/9router/pulls)，将你的视频添加到此部分 — 我们会合并它！
+
+---
+
+## 🛠️ 支持的 CLI 工具
+
+9Router 与所有主流 AI 编程工具无缝协作：
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="./public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/openclaw.png" width="60" alt="OpenClaw"/><br/>
+        <b>OpenClaw</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/opencode.png" width="60" alt="OpenCode"/><br/>
+        <b>OpenCode</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="120">
+        <img src="./public/providers/cline.png" width="60" alt="Cline"/><br/>
+        <b>Cline</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/continue.png" width="60" alt="Continue"/><br/>
+        <b>Continue</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/droid.png" width="60" alt="Droid"/><br/>
+        <b>Droid</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/roo.png" width="60" alt="Roo"/><br/>
+        <b>Roo</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/copilot.png" width="60" alt="Copilot"/><br/>
+        <b>Copilot</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/kilocode.png" width="60" alt="Kilo Code"/><br/>
+        <b>Kilo Code</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+---
+
+## 🌐 支持的提供商
+
+### 🔐 OAuth 提供商
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="./public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/github.png" width="60" alt="GitHub"/><br/>
+        <b>GitHub</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🆓 免费提供商
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="150">
+        <img src="./public/providers/kiro.png" width="70" alt="Kiro"/><br/>
+        <b>Kiro AI</b><br/>
+        <sub>Claude 4.5 + GLM-5 + MiniMax<br/>无限免费</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="./public/providers/opencode.png" width="70" alt="OpenCode Free"/><br/>
+        <b>OpenCode Free</b><br/>
+        <sub>无需认证 • 自动获取模型<br/>无限免费</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="./public/providers/gemini.png" width="70" alt="Vertex AI"/><br/>
+        <b>Vertex AI</b><br/>
+        <sub>Gemini 3 Pro + GLM-5 + DeepSeek<br/>$300 免费额度</sub>
+      </td>
+    </tr>
+  </table>
+</div>
+
+> **注意：** iFlow、Qwen 和 Gemini CLI 的免费等级已于 2026 年停止。请改用 Kiro / OpenCode Free / Vertex。
+
+### 🔑 API Key 提供商（40+）
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="100">
+        <img src="./public/providers/openrouter.png" width="50" alt="OpenRouter"/><br/>
+        <sub>OpenRouter</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/glm.png" width="50" alt="GLM"/><br/>
+        <sub>GLM</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/kimi.png" width="50" alt="Kimi"/><br/>
+        <sub>Kimi</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/minimax.png" width="50" alt="MiniMax"/><br/>
+        <sub>MiniMax</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/openai.png" width="50" alt="OpenAI"/><br/>
+        <sub>OpenAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/anthropic.png" width="50" alt="Anthropic"/><br/>
+        <sub>Anthropic</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="./public/providers/gemini.png" width="50" alt="Gemini"/><br/>
+        <sub>Gemini</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/deepseek.png" width="50" alt="DeepSeek"/><br/>
+        <sub>DeepSeek</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/groq.png" width="50" alt="Groq"/><br/>
+        <sub>Groq</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/xai.png" width="50" alt="xAI"/><br/>
+        <sub>xAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/mistral.png" width="50" alt="Mistral"/><br/>
+        <sub>Mistral</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/perplexity.png" width="50" alt="Perplexity"/><br/>
+        <sub>Perplexity</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="./public/providers/together.png" width="50" alt="Together"/><br/>
+        <sub>Together AI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/fireworks.png" width="50" alt="Fireworks"/><br/>
+        <sub>Fireworks</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/cerebras.png" width="50" alt="Cerebras"/><br/>
+        <sub>Cerebras</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/cohere.png" width="50" alt="Cohere"/><br/>
+        <sub>Cohere</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/nvidia.png" width="50" alt="NVIDIA"/><br/>
+        <sub>NVIDIA</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/siliconflow.png" width="50" alt="SiliconFlow"/><br/>
+        <sub>SiliconFlow</sub>
+      </td>
+    </tr>
+  </table>
+  <p><i>...以及 20+ 更多提供商，包括 Nebius、Chutes、Hyperbolic 和自定义 OpenAI/Anthropic 兼容端点</i></p>
+</div>
+
+---
+
+## 💡 主要功能
+
+| 功能 | 作用 | 为什么重要 |
+|---------|--------------|----------------|
+| 🚀 **RTK Token 节省器**（[RTK](https://github.com/rtk-ai/rtk) ⭐40K） | 压缩工具输出（`git diff`、`grep`、`ls`、`tree`...）后再发送给 LLM | 每次请求节省 **20-40% 输入 tokens** |
+| 🪨 **Caveman 模式**（[Caveman](https://github.com/JuliusBrussee/caveman) ⭐52K） | 注入 caveman 风格提示词 → LLM 回复简洁，保留技术实质 | 节省 **高达 65% 输出 tokens** |
+| 🎯 **智能三层切换** | 自动路由：订阅 → 低价 → 免费 | 编程永不停歇，零停机时间 |
+| 📊 **实时配额追踪** | 实时 token 计数 + 重置倒计时 | 充分利用订阅价值 |
+| 🔄 **格式转换** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex | 兼容任何 CLI 工具 |
+| 👥 **多账户支持** | 每个提供商支持多个账户 | 负载均衡 + 冗余备份 |
+| 🔄 **自动 Token 刷新** | OAuth token 自动刷新 | 无需手动重新登录 |
+| 🎨 **自定义组合** | 创建无限模型组合 | 自定义适合你的切换策略 |
+| 📝 **请求日志** | 调试模式下的完整请求/响应日志 | 轻松排查问题 |
+| 💾 **云同步** | 跨设备同步配置 | 处处相同设置 |
+| 📊 **使用分析** | 追踪 tokens、成本、趋势 | 优化开支 |
+| 🌐 **任意部署** | 本地、VPS、Docker、Cloudflare Workers | 灵活部署选项 |
+
+<details>
+<summary><b>📖 功能详情</b></summary>
+
+### 🚀 RTK Token 节省器
+
+工具输出（`git diff`、`grep`、`find`、`ls`、`tree`、日志转储...）通常占用 30-50% 的提示词预算。RTK 在请求到达 LLM 之前检测并应用智能、无损压缩：
+
+- **过滤器：** `git-diff`、`git-status`、`grep`、`find`、`ls`、`tree`、`dedup-log`、`smart-truncate`、`read-numbered`、`search-list`
+- **自动检测：** 无需配置 — RTK 检查每个 `tool_result` 的前 1KB，选择合适的过滤器。
+- **安全设计：** 如果过滤器失败、抛出异常或使输出变大，RTK 会静默保留原始文本。错误永远不会中断你的请求。
+- **通用兼容：** 适用于所有格式（OpenAI、Claude、Gemini、Cursor、Kiro、OpenAI Responses），因为它在任何格式转换**之前**运行。
+- **默认开启：** 可随时在控制面板 → 端点设置中切换。
+
+```
+不使用 RTK：47K tokens 发送给 LLM
+使用 RTK：    28K tokens 发送给 LLM   (节省 40% · 相同上下文 · 相同答案)
+```
+
+### 🎯 智能三层切换
+
+创建具有自动切换功能的组合：
+
+```
+组合："my-coding-stack"
+  1. cc/claude-opus-4-6        （你的订阅）
+  2. glm/glm-4.7               （低价备份，$0.6/1M）
+  3. if/kimi-k2-thinking       （免费备选）
+
+→ 配额用完或出错时自动切换
+```
+
+### 📊 实时配额追踪
+
+- 每个提供商的 token 消耗
+- 重置倒计时（5小时、每日、每周）
+- 付费等级的成本估算
+- 月度支出报告
+
+### 🔄 格式转换
+
+格式间无缝转换：
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **Cursor** ↔ **Kiro** ↔ **Vertex** ↔ **Antigravity** ↔ **Ollama** ↔ **OpenAI Responses**
+- 你的 CLI 工具发送 OpenAI 格式 → 9Router 转换 → 提供商接收原生格式
+- 适用于任何支持自定义 OpenAI 端点的工具
+
+### 👥 多账户支持
+
+- 每个提供商添加多个账户
+- 自动轮询或基于优先级的路由
+- 当一个账户达到配额时切换到下一个
+
+### 🔄 自动 Token 刷新
+
+- OAuth token 在过期前自动刷新
+- 无需手动重新认证
+- 所有提供商的无缝体验
+
+### 🎨 自定义组合
+
+- 创建无限模型组合
+- 混合订阅、低价和免费等级
+- 为组合命名以便访问
+- 使用云同步跨设备共享组合
+
+### 📝 请求日志
+
+- 启用调试模式获取完整请求/响应日志
+- 追踪 API 调用、请求头和载荷
+- 排查集成问题
+- 导出日志进行分析
+
+### 💾 云同步
+
+- 跨设备同步提供商、组合和设置
+- 自动后台同步
+- 安全加密存储
+- 从任何地方访问你的设置
+
+#### 云运行时说明
+
+- 生产环境中优先使用服务端云变量：
+  - `BASE_URL`（云同步调度程序使用的内部回调 URL）
+  - `CLOUD_URL`（云同步端点基础 URL）
+- `NEXT_PUBLIC_BASE_URL` 和 `NEXT_PUBLIC_CLOUD_URL` 仍用于兼容性/UI，但服务端运行时现在优先使用 `BASE_URL`/`CLOUD_URL`。
+- 云同步请求现在使用超时 + 快速失败行为，以避免云 DNS/网络不可用时 UI 挂起。
+
+### 📊 使用分析
+
+- 追踪每个提供商和模型的 token 使用量
+- 成本估算和支出趋势
+- 月度报告和洞察
+- 优化你的 AI 支出
+
+> **💡 重要 - 了解控制面板成本：**
+> 
+> 使用分析中显示的"成本"**仅用于追踪和比较目的**。
+> 9Router 本身**永远不会向你收费**。你只直接向提供商付款（如果使用付费服务）。
+> 
+> **示例：** 如果你的控制面板显示使用 iFlow 模型时"总成本 $290"，这代表你如果直接使用付费 API 需要支付的金额。你的实际成本 = **$0**（iFlow 免费无限量）。
+> 
+> 把它想象成一个"节省追踪器"，展示你通过使用免费模型或通过 9Router 路由节省了多少钱！
+
+### 🌐 任意部署
+
+- 💻 **本地** - 默认，离线可用
+- ☁️ **VPS/云** - 跨设备共享
+- 🐳 **Docker** - 一键部署
+- 🚀 **Cloudflare Workers** - 全球边缘网络
+
+</details>
+
+---
+
+## 💰 价格一览
+
+| 等级 | 提供商 | 成本 | 配额重置 | 适用场景 |
+|------|----------|------|-------------|----------|
+| **🚀 TOKEN 节省器** | **RTK（内置）** | **免费** | 始终开启 | **每次请求节省 20-40% tokens** |
+| **💳 订阅** | Claude Code (Pro/Max) | $20-200/月 | 5小时 + 每周 | 已有订阅的用户 |
+| | Codex (Plus/Pro) | $20-200/月 | 5小时 + 每周 | OpenAI 用户 |
+| | GitHub Copilot | $10-19/月 | 每月 | GitHub 用户 |
+| | Cursor IDE | $20/月 | 每月 | Cursor 用户 |
+| **💰 低价** | GLM-5.1 / GLM-4.7 | $0.6/1M | 每日 10AM | 预算备份 |
+| | MiniMax M2.7 | $0.2/1M | 5小时滚动 | 最便宜选项 |
+| | Kimi K2.5 | $9/月固定 | 10M tokens/月 | 可预测成本 |
+| **🆓 免费** | Kiro AI | $0 | 无限量 | Claude 4.5 + GLM-5 + MiniMax 免费 |
+| | OpenCode Free | $0 | 无限量 | 无需认证，自动获取模型 |
+| | Vertex AI | $300 额度 | 新 GCP 账户 | Gemini 3 Pro + DeepSeek + GLM-5 |
+
+**💡 专业提示：** RTK + Kiro AI + OpenCode Free 组合 = **$0 成本 + 节省 20-40% tokens**！
+
+---
+
+### 📊 理解 9Router 成本与计费
+
+**9Router 计费真相：**
+
+✅ **9Router 软件 = 永久免费**（开源，绝不收费）  
+✅ **控制面板"成本" = 仅用于显示/追踪**（不是实际账单）  
+✅ **你直接向提供商付款**（订阅或 API 费用）  
+✅ **免费提供商保持免费**（iFlow、Kiro、Qwen = $0 无限量）  
+❌ **9Router 永不发送发票** 或扣款
+
+**成本显示如何工作：**
+
+控制面板显示**估算成本**，如同你直接使用付费 API。这**不是计费** — 它是一个比较工具，展示你的节省。
+
+**示例场景：**
+```
+控制面板显示：
+• 总请求数：1,662
+• 总 Tokens：47M
+• 显示成本：$290
+
+实际检查：
+• 提供商：iFlow（免费无限量）
+• 实际支付：$0.00
+• $290 意味着什么：通过使用免费模型节省的金额！
+```
+
+**付款规则：**
+- **订阅提供商**（Claude Code、Codex）：通过他们的网站直接付款
+- **低价提供商**（GLM、MiniMax）：直接付款，9Router 只做路由
+- **免费提供商**（iFlow、Kiro、Qwen）：真正的永久免费，无隐藏费用
+- **9Router**：从不收取任何费用，永远不会
+
+---
+
+## 🎯 使用场景
+
+### 场景 1："我有 Claude Pro 订阅"
+
+**问题：** 配额到期未用完，繁忙编码时遇到速率限制
+
+**解决方案：**
+```
+组合："maximize-claude"
+  1. cc/claude-opus-4-7        （充分利用订阅）
+  2. glm/glm-5.1               （配额用完时的低价备份）
+  3. kr/claude-sonnet-4.5      （免费紧急备选）
+
+月成本：$20（订阅）+ ~$5（备份）= $25 总计
+对比：$20 + 遇到限制 = 沮丧
+```
+
+### 场景 2："我想零成本"
+
+**问题：** 负担不起订阅，需要可靠的 AI 编码
+
+**解决方案：**
+```
+组合："free-forever"
+  1. kr/claude-sonnet-4.5      （Claude 4.5 免费无限量）
+  2. kr/glm-5                  （通过 Kiro 免费使用 GLM-5）
+  3. oc/<auto>                 （OpenCode Free，无需认证）
+
+月成本：$0
+质量：生产级模型 + RTK 节省 20-40% tokens
+```
+
+### 场景 3："我需要 24/7 编码，不中断"
+
+**问题：** 截止日期紧迫，不能承受停机
+
+**解决方案：**
+```
+组合："always-on"
+  1. cc/claude-opus-4-7        （最佳质量）
+  2. cx/gpt-5.5                （第二个订阅）
+  3. glm/glm-5.1               （低价，每日重置）
+  4. minimax/MiniMax-M2.7      （最便宜，5小时重置）
+  5. kr/claude-sonnet-4.5      （免费无限量）
+
+结果：5 层切换 = 零停机时间
+月成本：$20-200（订阅）+ $10-20（备份）
+```
+
+### 场景 4："我想在 OpenClaw 中使用免费 AI"
+
+**问题：** 需要在消息应用（WhatsApp、Telegram、Slack...）中使用 AI 助手，完全免费
+
+**解决方案：**
+```
+组合："openclaw-free"
+  1. kr/claude-sonnet-4.5      （Claude 4.5 免费）
+  2. kr/glm-5                  （GLM-5 免费）
+  3. kr/MiniMax-M2.5           （MiniMax 免费）
+
+月成本：$0
+访问方式：WhatsApp、Telegram、Slack、Discord、iMessage、Signal...
+```
+
+---
+
+## ❓ 常见问题
+
+<details>
+<summary><b>📊 为什么我的控制面板显示高成本？</b></summary>
+
+控制面板追踪你的 token 使用情况，并显示**估算成本**，如同你直接使用付费 API。这**不是实际计费** — 它是一个参考，展示你通过使用免费模型或通过 9Router 路由现有订阅节省了多少钱。
+
+**示例：**
+- **控制面板显示：** "$290 总成本"
+- **实际情况：** 你在使用 iFlow（免费无限量）
+- **你的实际成本：** **$0.00**
+- **$290 的含义：** 你通过使用免费模型而不是付费 API **节省**的金额！
+
+成本显示是一个"节省追踪器"，帮助你了解使用模式和优化机会。
+
+</details>
+
+<details>
+<summary><b>💳 9Router 会扣我的钱吗？</b></summary>
+
+**不会。** 9Router 是在你自己的电脑上运行的开源软件。它永远不会向你收取任何费用。
+
+**你只需支付：**
+- ✅ **订阅提供商**（Claude Code $20/月、Codex $20-200/月）→ 在他们的网站上直接付款
+- ✅ **低价提供商**（GLM、MiniMax）→ 直接付款，9Router 只是路由你的请求
+- ❌ **9Router 本身** → **永不收费，永远不会**
+
+9Router 是一个本地代理/路由器。它没有你的信用卡，不能发送发票，也没有计费系统。它是完全免费的软件。
+
+</details>
+
+<details>
+<summary><b>🆓 免费提供商真的是无限量的吗？</b></summary>
+
+**是的！** 当前的免费提供商（Kiro、OpenCode Free、Vertex）是真正的免费，**无隐藏费用**。
+
+这些是各公司提供的免费服务：
+- **Kiro AI**：通过 AWS Builder ID / Google / GitHub OAuth 免费无限量使用 Claude 4.5 + GLM-5 + MiniMax
+- **OpenCode Free**：无认证直连代理，模型从 `opencode.ai/zen/v1/models` 自动获取
+- **Vertex AI**：新 Google Cloud 账户可获得 $300 免费额度（90 天）
+
+9Router 只是路由你的请求到它们 — 没有"陷阱"或未来的计费。它们是真正的免费服务，9Router 让它们易于使用并支持切换。
+
+**已停止的免费等级（不再推荐）：**
+- ❌ **iFlow**：曾是免费无限量，现在改为付费（2026）
+- ❌ **Qwen Code**：阿里巴巴于 2026-04-15 停止免费 OAuth 等级
+- ❌ **Gemini CLI**：仍可用，但与非 CLI 工具（Claude、Codex、Cursor...）一起使用可能会导致账户被封 — 仅在你坚持使用 Gemini CLI 本身时才使用
+
+</details>
+
+<details>
+<summary><b>💰 如何最小化我的实际 AI 成本？</b></summary>
+
+**免费优先策略：**
+
+1. **从 100% 免费组合开始：**
+   ```
+   1. gc/gemini-3-flash (Google 每月 180K 免费)
+   2. if/kimi-k2-thinking (iFlow 无限量免费)
+   3. qw/qwen3-coder-plus (Qwen 无限量免费)
+   ```
+   **成本：$0/月**
+
+2. **仅在需要时添加低价备份：**
+   ```
+   4. glm/glm-4.7 ($0.6/1M tokens)
+   ```
+   **额外成本：只为实际使用的部分付费**
+
+3. **最后使用订阅提供商：**
+   - 仅当你已有订阅时
+   - 9Router 通过配额追踪帮助最大化其价值
+
+**结果：** 大多数用户可以仅使用免费等级以 $0/月运行！
+
+</details>
+
+<details>
+<summary><b>📈 如果我的使用量突然激增怎么办？</b></summary>
+
+9Router 的智能切换可以防止意外费用：
+
+**场景：** 你正在进行编码冲刺，用尽了配额
+
+**没有 9Router：**
+- ❌ 达到速率限制 → 工作停止 → 沮丧
+- ❌ 或者：不慎累积大量 API 账单
+
+**有 9Router：**
+- ✅ 订阅达到限制 → 自动切换到低价等级
+- ✅ 低价等级变得昂贵 → 自动切换到免费等级
+- ✅ 编程永不停歇 → 可预测的成本
+
+**你掌控一切：** 在控制面板中设置每个提供商的支出限制，9Router 会遵守它们。
+
+</details>
+
+---
+
+## 📖 设置指南
+
+<details>
+<summary><b>🔐 订阅提供商（充分利用价值）</b></summary>
+
+### Claude Code (Pro/Max)
+
+```bash
+控制面板 → 提供商 → 连接 Claude Code
+→ OAuth 登录 → 自动 token 刷新
+→ 5小时 + 每周配额追踪
+
+模型：
+  cc/claude-opus-4-7
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-6
+  cc/claude-haiku-4-5-20251001
+```
+
+**专业提示：** 复杂任务使用 Opus，追求速度使用 Sonnet。9Router 按模型追踪配额！
+
+### OpenAI Codex (Plus/Pro)
+
+```bash
+控制面板 → 提供商 → 连接 Codex
+→ OAuth 登录（端口 1455）
+→ 5小时 + 每周重置
+
+模型：
+  cx/gpt-5.5
+  cx/gpt-5.4
+  cx/gpt-5.3-codex
+  cx/gpt-5.2-codex
+```
+
+### GitHub Copilot
+
+```bash
+控制面板 → 提供商 → 连接 GitHub
+→ 通过 GitHub 进行 OAuth
+→ 每月重置（每月 1 日）
+
+模型：
+  gh/gpt-5.4
+  gh/claude-opus-4.7
+  gh/claude-sonnet-4.6
+  gh/gemini-3.1-pro-preview
+  gh/grok-code-fast-1
+```
+
+### Cursor IDE
+
+```bash
+控制面板 → 提供商 → 连接 Cursor
+→ OAuth 登录
+→ 每月订阅
+
+模型：
+  cu/claude-4.6-opus-max
+  cu/claude-4.5-sonnet-thinking
+  cu/gpt-5.3-codex
+```
+
+</details>
+
+<details>
+<summary><b>💰 低价提供商（备份）</b></summary>
+
+### GLM-5.1 / GLM-4.7（每日重置，$0.6/1M）
+
+1. 注册：[Zhipu AI](https://open.bigmodel.cn/)
+2. 从编程计划获取 API key
+3. 控制面板 → 添加 API Key：
+   - 提供商：`glm`
+   - API Key：`your-key`
+
+**使用：** `glm/glm-5.1`、`glm/glm-5`、`glm/glm-4.7`
+
+**专业提示：** 编程计划提供 3 倍配额，成本仅为 1/7！每日 10:00 AM 重置。
+
+### MiniMax M2.7（5小时重置，$0.20/1M）
+
+1. 注册：[MiniMax](https://www.minimax.io/)
+2. 获取 API key
+3. 控制面板 → 添加 API Key
+
+**使用：** `minimax/MiniMax-M2.7`、`minimax/MiniMax-M2.5`
+
+**专业提示：** 长上下文（1M tokens）的最便宜选项！
+
+### Kimi K2.5（$9/月固定）
+
+1. 订阅：[Moonshot AI](https://platform.moonshot.ai/)
+2. 获取 API key
+3. 控制面板 → 添加 API Key
+
+**使用：** `kimi/kimi-k2.5`、`kimi/kimi-k2.5-thinking`
+
+**专业提示：** 每月 $9 固定费用获得 10M tokens = 实际成本 $0.90/1M！
+
+</details>
+
+<details>
+<summary><b>🆓 免费提供商（推荐）</b></summary>
+
+### Kiro AI（Claude 4.5 + GLM-5 + MiniMax 免费）
+
+```bash
+控制面板 → 连接 Kiro
+→ AWS Builder ID、AWS IAM Identity Center、Google 或 GitHub
+→ 无限量使用
+
+模型：
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+  kr/glm-5
+  kr/MiniMax-M2.5
+  kr/qwen3-coder-next
+  kr/deepseek-3.2
+```
+
+**专业提示：** Claude 最佳免费选项。无需 API key，无需付款，完全无限量。
+
+### OpenCode Free（无需认证，自动获取模型）
+
+```bash
+控制面板 → 连接 OpenCode Free
+→ 无需登录（直连代理）
+→ 模型从 opencode.ai/zen/v1/models 自动获取
+```
+
+**专业提示：** 最快的设置。连接后即可开始编码。
+
+### Vertex AI（新 GCP 账户 $300 免费额度）
+
+```bash
+控制面板 → 连接 Vertex AI
+→ 上传 Google Cloud 服务账户 JSON
+→ 在你的 GCP 项目中启用 Vertex AI API
+
+模型：
+  vertex/gemini-3.1-pro-preview
+  vertex/gemini-3-flash-preview
+  vertex/gemini-2.5-flash
+
+Vertex 合作伙伴（通过 Vertex 提供 Anthropic / DeepSeek / GLM / Qwen）：
+  vertex-partner/glm-5-maas
+  vertex-partner/deepseek-v3.2-maas
+  vertex-partner/qwen3-next-80b-a3b-thinking-maas
+```
+
+**专业提示：** 新 Google Cloud 账户可获得 90 天内 $300 免费额度。足够日常编码使用。
+
+</details>
+
+<details>
+<summary><b>🎨 创建组合</b></summary>
+
+### 示例 1：充分利用订阅 → 低价备份
+
+```
+控制面板 → 组合 → 创建新组合
+
+名称：premium-coding
+模型：
+  1. cc/claude-opus-4-7 (订阅主用)
+  2. glm/glm-5.1 (低价备份，$0.6/1M)
+  3. minimax/MiniMax-M2.7 (最便宜的备选，$0.20/1M)
+
+在 CLI 中使用：premium-coding
+
+月度成本示例（100M tokens）：
+  80M 通过 Claude（订阅）：$0 额外费用
+  15M 通过 GLM：$9
+  5M 通过 MiniMax：$1
+  总计：$10 + 你的订阅费用
+```
+
+### 示例 2：仅免费（零成本）
+
+```
+名称：free-combo
+模型：
+  1. kr/claude-sonnet-4.5 (Claude 4.5 免费无限量)
+  2. kr/glm-5 (通过 Kiro 免费使用 GLM-5)
+  3. vertex/gemini-3.1-pro-preview ($300 免费额度)
+
+成本：通过 RTK 永久 $0（+ 节省 20-40% tokens）！
+```
+
+</details>
+
+<details>
+<summary><b>🔧 CLI 集成</b></summary>
+
+### Cursor IDE
+
+```
+设置 → 模型 → 高级：
+  OpenAI API Base URL：http://localhost:20128/v1
+  OpenAI API Key：[来自 9router 控制面板]
+  Model：cc/claude-opus-4-7
+```
+
+或使用组合：`premium-coding`
+
+### Claude Code
+
+编辑 `~/.claude/config.json`：
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+### OpenClaw
+
+**选项 1 — 控制面板（推荐）：**
+
+```
+控制面板 → CLI 工具 → OpenClaw → 选择模型 → 应用
+```
+
+**选项 2 — 手动：** 编辑 `~/.openclaw/openclaw.json`：
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "9router/kr/claude-sonnet-4.5"
+      }
+    }
+  },
+  "models": {
+    "providers": {
+      "9router": {
+        "baseUrl": "http://127.0.0.1:20128/v1",
+        "apiKey": "sk_9router",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "kr/claude-sonnet-4.5",
+            "name": "Claude Sonnet 4.5 (Kiro Free)"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+> **注意：** OpenClaw 仅适用于本地 9Router。使用 `127.0.0.1` 而不是 `localhost` 以避免 IPv6 解析问题。
+
+### Cline / Continue / RooCode
+
+```
+Provider：OpenAI 兼容
+Base URL：http://localhost:20128/v1
+API Key：[来自控制面板]
+Model：cc/claude-opus-4-7
+```
+
+</details>
+
+<details>
+<summary><b>🚀 部署</b></summary>
+
+### VPS 部署
+
+```bash
+# 克隆并安装
+git clone https://github.com/decolua/9router.git
+cd 9router
+npm install
+npm run build
+
+# 配置
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/9router"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export NEXT_PUBLIC_CLOUD_URL="https://9router.com"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+export MACHINE_ID_SALT="endpoint-proxy-salt"
+
+# 启动
+npm run start
+
+# 或使用 PM2
+npm install -g pm2
+pm2 start npm --name 9router -- start
+pm2 save
+pm2 startup
+```
+
+### Docker
+
+```bash
+# 构建镜像（从仓库根目录）
+docker build -t 9router .
+
+# 运行容器（当前设置使用的命令）
+docker run -d \
+  --name 9router \
+  -p 20128:20128 \
+  --env-file /root/dev/9router/.env \
+  -v 9router-data:/app/data \
+  -v 9router-usage:/root/.9router \
+  9router
+```
+
+便携命令（如果你已经在仓库根目录）：
+
+```bash
+docker run -d \
+  --name 9router \
+  -p 20128:20128 \
+  --env-file ./.env \
+  -v 9router-data:/app/data \
+  -v 9router-usage:/root/.9router \
+  9router
+```
+
+容器默认值：
+- `PORT=20128`
+- `HOSTNAME=0.0.0.0`
+
+常用命令：
+
+```bash
+docker logs -f 9router
+docker restart 9router
+docker stop 9router && docker rm 9router
+```
+
+### 环境变量
+
+| 变量 | 默认值 | 描述 |
+|----------|---------|-------------|
+| `JWT_SECRET` | 自动生成（`~/.9router/jwt-secret`） | 用于控制面板 auth cookie 的 JWT 签名密钥（设置可在多实例间共享） |
+| `INITIAL_PASSWORD` | `123456` | 当没有保存的哈希时首次登录的密码 |
+| `DATA_DIR` | `~/.9router` | 主应用数据库位置（`db.json`） |
+| `PORT` | 框架默认值 | 服务端口（示例中为 `20128`） |
+| `HOSTNAME` | 框架默认值 | 绑定主机（Docker 默认为 `0.0.0.0`） |
+| `NODE_ENV` | 运行时默认值 | 设置 `production` 用于部署 |
+| `BASE_URL` | `http://localhost:20128` | 云同步任务使用的服务端内部基础 URL |
+| `CLOUD_URL` | `https://9router.com` | 服务端云同步端点基础 URL |
+| `NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | 向后兼容/公开基础 URL（服务端运行时优先使用 `BASE_URL`） |
+| `NEXT_PUBLIC_CLOUD_URL` | `https://9router.com` | 向后兼容/公开云 URL（服务端运行时优先使用 `CLOUD_URL`） |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | 生成 API key 的 HMAC 密钥 |
+| `MACHINE_ID_SALT` | `endpoint-proxy-salt` | 稳定机器 ID 哈希的盐值 |
+| `ENABLE_REQUEST_LOGS` | `false` | 在 `logs/` 下启用请求/响应日志 |
+| `AUTH_COOKIE_SECURE` | `false` | 强制 `Secure` auth cookie（在 HTTPS 反向代理后面设置为 `true`） |
+| `REQUIRE_API_KEY` | `false` | 在 `/v1/*` 路由上强制使用 Bearer API key（面向互联网部署时推荐） |
+| `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY` | 空 | 用于上游提供商调用的可选出站代理 |
+
+注意：
+- 也支持小写代理变量：`http_proxy`、`https_proxy`、`all_proxy`、`no_proxy`。
+- `.env` 不会打包到 Docker 镜像中（`.dockerignore`）；使用 `--env-file` 或 `-e` 注入运行时配置。
+- 在 Windows 上，`APPDATA` 可用于本地存储路径解析。
+- `INSTANCE_NAME` 出现在较旧的文档/环境变量模板中，但当前运行时未使用。
+
+### 运行时文件和存储
+
+- 主应用状态：`${DATA_DIR}/db.json`（提供商、组合、别名、密钥、设置），由 `src/lib/localDb.js` 管理。
+- 使用历史和日志：`${DATA_DIR}/usage.json` 和 `${DATA_DIR}/log.txt`，由 `src/lib/usageDb.js` 管理。
+- 可选的请求/翻译器日志：`ENABLE_REQUEST_LOGS=true` 时位于 `<repo>/logs/...`。
+- `${DATA_DIR}` 和 `~/.9router` 在 Docker 容器中解析到同一位置 — 符号链接 `/root/.9router -> /app/data` 在构建时创建。
+
+</details>
+
+---
+
+## 📊 可用模型
+
+<details>
+<summary><b>查看所有可用模型</b></summary>
+
+**Claude Code（`cc/`）** - Pro/Max：
+- `cc/claude-opus-4-7`
+- `cc/claude-opus-4-6`
+- `cc/claude-sonnet-4-6`
+- `cc/claude-sonnet-4-5-20250929`
+- `cc/claude-haiku-4-5-20251001`
+
+**Codex（`cx/`）** - Plus/Pro：
+- `cx/gpt-5.5`
+- `cx/gpt-5.4`
+- `cx/gpt-5.3-codex`
+- `cx/gpt-5.2-codex`
+- `cx/gpt-5.1-codex-max`
+
+**GitHub Copilot（`gh/`）**：
+- `gh/gpt-5.4`
+- `gh/claude-opus-4.7`
+- `gh/claude-sonnet-4.6`
+- `gh/gemini-3.1-pro-preview`
+- `gh/grok-code-fast-1`
+
+**Cursor（`cu/`）** - 订阅：
+- `cu/claude-4.6-opus-max`
+- `cu/claude-4.5-sonnet-thinking`
+- `cu/gpt-5.3-codex`
+- `cu/kimi-k2.5`
+
+**GLM（`glm/`）** - $0.6/1M：
+- `glm/glm-5.1`
+- `glm/glm-5`
+- `glm/glm-4.7`
+
+**MiniMax（`minimax/`）** - $0.2/1M：
+- `minimax/MiniMax-M2.7`
+- `minimax/MiniMax-M2.5`
+
+**Kimi（`kimi/`）** - $9/月固定：
+- `kimi/kimi-k2.5`
+- `kimi/kimi-k2.5-thinking`
+
+**Kiro（`kr/`）** - 免费无限量：
+- `kr/claude-sonnet-4.5`
+- `kr/claude-haiku-4.5`
+- `kr/glm-5`
+- `kr/MiniMax-M2.5`
+- `kr/qwen3-coder-next`
+- `kr/deepseek-3.2`
+
+**OpenCode Free（`oc/`）** - 免费无需认证：
+- 从 `opencode.ai/zen/v1/models` 自动获取
+
+**Vertex AI（`vertex/`）** - $300 免费额度：
+- `vertex/gemini-3.1-pro-preview`
+- `vertex/gemini-3-flash-preview`
+- `vertex/gemini-2.5-flash`
+- `vertex-partner/glm-5-maas`
+- `vertex-partner/deepseek-v3.2-maas`
+
+</details>
+
+---
+
+## 🐛 故障排除
+
+**"语言模型未提供消息"**
+- 提供商配额耗尽 → 检查控制面板配额追踪器
+- 解决方案：使用组合切换或切换到更便宜的等级
+
+**速率限制**
+- 订阅配额用完 → 切换到 GLM/MiniMax
+- 添加组合：`cc/claude-opus-4-7 → glm/glm-5.1 → kr/claude-sonnet-4.5`
+
+**OAuth token 已过期**
+- 9Router 自动刷新
+- 如果问题持续：控制面板 → 提供商 → 重新连接
+
+**高成本**
+- 在控制面板 → 端点设置中启用 RTK（默认开启，节省 20-40% tokens）
+- 在控制面板中检查使用统计
+- 将主模型切换到 GLM/MiniMax
+- 对于非关键任务使用免费等级（Kiro、OpenCode Free、Vertex）
+
+**控制面板在错误端口打开**
+- 设置 `PORT=20128` 和 `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+
+**首次登录不工作**
+- 检查 `.env` 中的 `INITIAL_PASSWORD`
+- 如果未设置，回退密码是 `123456`
+
+**`logs/` 下没有请求日志**
+- 设置 `ENABLE_REQUEST_LOGS=true`
+
+---
+
+## 🛠️ 技术栈
+
+- **运行时**：Node.js 20+
+- **框架**：Next.js 16
+- **UI**：React 19 + Tailwind CSS 4
+- **数据库**：LowDB（基于 JSON 文件）
+- **流式传输**：Server-Sent Events (SSE)
+- **认证**：OAuth 2.0 (PKCE) + JWT + API Keys
+
+---
+
+## 📝 API 参考
+
+### 聊天补全
+
+```bash
+POST http://localhost:20128/v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### 列出模型
+
+```bash
+GET http://localhost:20128/v1/models
+Authorization: Bearer your-api-key
+
+→ 以 OpenAI 格式返回所有模型和组合
+```
+
+## 📧 支持
+
+- **网站**：[9router.com](https://9router.com)
+- **GitHub**：[github.com/decolua/9router](https://github.com/decolua/9router)
+- **问题**：[github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+
+---
+
+## 👥 贡献者
+
+感谢所有帮助改进 9Router 的贡献者！
+
+[![Contributors](https://contrib.rocks/image?repo=decolua/9router&max=150&columns=15&anon=1&v=20260309)](https://github.com/decolua/9router/graphs/contributors)
+
+---
+
+## 📊 Star 图表
+
+[![Star Chart](https://starchart.cc/decolua/9router.svg?variant=adaptive)](https://starchart.cc/decolua/9router)
+
+
+
+## 🔀 分支
+
+**[OmniRoute](https://github.com/diegosouzapw/OmniRoute)** — 9Router 的全功能 TypeScript 分支。增加了 36+ 提供商、4 层自动切换、多模态 API（图像、嵌入、音频、TTS）、断路器、语义缓存、LLM 评估和精美的控制面板。368+ 单元测试。可通过 npm 和 Docker 使用。
+
+---
+
+## 🙏 致谢
+
+站在巨人的肩膀上构建：
+
+- **CLIProxyAPI** — 启发了这个 JavaScript 移植的原始 Go 实现。
+- **[RTK](https://github.com/rtk-ai/rtk)** ![Stars](https://img.shields.io/github/stars/rtk-ai/rtk?style=flat&color=yellow) — Rust token 节省器。9Router 将其压缩管道移植到 JS → 每次请求 **减少 20-40% 输入 tokens**。
+- **[Caveman](https://github.com/JuliusBrussee/caveman)** ![Stars](https://img.shields.io/github/stars/JuliusBrussee/caveman?style=flat&color=yellow) by **[@JuliusBrussee](https://github.com/JuliusBrussee)** — 病毒式传播的 *"为什么用很多 token 当少的 token 就能搞定"*。9Router 适配其提示词 → **减少 65% 输出 tokens**。
+
+非常感谢这些作者 — 没有他们的工作，9Router 的 token 节省功能就不会存在。在 GitHub 上给他们加星！
+
+---
+
+## 📄 许可证
+
+MIT 许可证 — 详见 [LICENSE](LICENSE)。
+
+---
+
+<div align="center">
+  <sub>用 ❤️ 为 24/7 编程的开发者构建</sub>
+</div>
\ No newline at end of file
diff --git a/captain-definition b/captain-definition
new file mode 100644
index 0000000..0e14f82
--- /dev/null
+++ b/captain-definition
@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 2,
+  "dockerfilePath": "./Dockerfile"
+}
diff --git a/cli/.gitignore b/cli/.gitignore
new file mode 100644
index 0000000..55fd8c4
--- /dev/null
+++ b/cli/.gitignore
@@ -0,0 +1,2 @@
+app/*
+node_modules/*
diff --git a/cli/.npmignore b/cli/.npmignore
new file mode 100644
index 0000000..231c936
--- /dev/null
+++ b/cli/.npmignore
@@ -0,0 +1,9 @@
+# Ignore everything except what's in package.json "files"
+*
+!cli.js
+!hooks/
+!app/
+!package.json
+!README.md
+!LICENSE
+
diff --git a/cli/LICENSE b/cli/LICENSE
new file mode 100644
index 0000000..ddd5dd4
--- /dev/null
+++ b/cli/LICENSE
@@ -0,0 +1,42 @@
+MIT License
+
+Copyright (c) 2026 9Router Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/cli/README.md b/cli/README.md
new file mode 100644
index 0000000..050d996
--- /dev/null
+++ b/cli/README.md
@@ -0,0 +1,125 @@
+# 9Router - FREE AI Router & Token Saver
+
+**Never stop coding. Save 20-40% tokens with RTK + auto-fallback to FREE & cheap AI models.**
+
+**Connect All AI Code Tools (Claude Code, Cursor, Antigravity, Copilot, Codex, Gemini, OpenCode, Cline, OpenClaw...) to 40+ AI Providers & 100+ Models.**
+
+[![npm](https://img.shields.io/npm/v/9router.svg)](https://www.npmjs.com/package/9router)
+[![Downloads](https://img.shields.io/npm/dm/9router.svg)](https://www.npmjs.com/package/9router)
+[![Docker Pulls](https://img.shields.io/docker/pulls/decolua/9router.svg?logo=docker&label=Docker%20pulls)](https://hub.docker.com/r/decolua/9router)
+[![GHCR](https://img.shields.io/badge/GHCR-decolua%2F9router-blue?logo=github)](https://github.com/decolua/9router/pkgs/container/9router)
+[![License](https://img.shields.io/npm/l/9router.svg)](https://github.com/decolua/9router/blob/main/LICENSE)
+
+<a href="https://trendshift.io/repositories/22628" target="_blank"><img src="https://trendshift.io/api/badge/repositories/22628" alt="decolua%2F9router | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+
+[🌐 Website](https://9router.com) • [📖 Full Docs](https://github.com/decolua/9router)
+
+---
+
+## 🤔 Why 9Router?
+
+**Stop wasting money, tokens and hitting limits:**
+
+- ❌ Subscription quota expires unused every month
+- ❌ Rate limits stop you mid-coding
+- ❌ Tool outputs (git diff, grep, ls...) burn tokens fast
+- ❌ Expensive APIs ($20-50/month per provider)
+
+**9Router solves this:**
+
+- ✅ **RTK Token Saver** - Auto-compress tool_result, save 20-40% tokens
+- ✅ **Maximize subscriptions** - Track quota, use every bit before reset
+- ✅ **Auto fallback** - Subscription → Cheap → Free, zero downtime
+- ✅ **Multi-account** - Round-robin between accounts per provider
+- ✅ **Universal** - Works with any OpenAI/Claude-compatible CLI
+
+---
+
+## ⚡ Quick Start
+
+**Option 1 — npm (recommended for desktop):**
+
+```bash
+npm install -g 9router
+9router
+
+# Or run directly with npx
+npx 9router
+```
+
+**Option 2 — Docker (server/VPS):**
+
+```bash
+docker run -d --name 9router -p 20128:20128 \
+  -v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data \
+  decolua/9router:latest
+```
+
+Published images: [Docker Hub](https://hub.docker.com/r/decolua/9router) • [GHCR](https://github.com/decolua/9router/pkgs/container/9router) (multi-platform amd64/arm64).
+
+🎉 Dashboard opens at `http://localhost:20128`
+
+**2. Connect a FREE provider (no signup needed):**
+
+Dashboard → Providers → Connect **Kiro AI** (free Claude unlimited) or **OpenCode Free** (no auth) → Done!
+
+**3. Use in your CLI tool:**
+
+```
+Claude Code/Codex/OpenClaw/Cursor/Cline Settings:
+  Endpoint: http://localhost:20128/v1
+  API Key:  [copy from dashboard]
+  Model:    kr/claude-sonnet-4.5
+```
+
+That's it! Start coding with FREE AI models.
+
+---
+
+## 🚀 CLI Options
+
+```bash
+9router                    # Start with default settings
+9router --port 8080        # Custom port
+9router --no-browser       # Don't open browser
+9router --skip-update      # Skip auto-update check
+9router --help             # Show all options
+```
+
+**Dashboard**: `http://localhost:20128/dashboard`
+
+---
+
+## 🛠️ Supported CLI Tools
+
+Claude-Code • OpenClaw • Codex • OpenCode • Cursor • Antigravity • Cline • Continue • Droid • Roo • Copilot • Kilo Code • Gemini CLI • Qwen Code • iFlow • Crush • Crusher • Aider
+
+Any tool supporting OpenAI/Claude-compatible API works.
+
+---
+
+## 💾 Data Location
+
+- **macOS/Linux**: `~/.9router/db/data.sqlite`
+- **Windows**: `%APPDATA%/9router/db/data.sqlite`
+- **Docker**: `/app/data/db/data.sqlite` (mount `$HOME/.9router` to persist)
+
+---
+
+## 📚 Documentation
+
+Full docs, advanced setup, video tutorials & development guide:
+
+- **GitHub**: https://github.com/decolua/9router
+- **Full README**: https://github.com/decolua/9router/blob/main/app/README.md
+- **Website**: https://9router.com
+
+---
+
+## 🙏 Acknowledgments
+
+- **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** - Original Go implementation
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
diff --git a/cli/cli.js b/cli/cli.js
new file mode 100755
index 0000000..6a0fc06
--- /dev/null
+++ b/cli/cli.js
@@ -0,0 +1,852 @@
+#!/usr/bin/env node
+
+const { spawn, exec, execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const https = require("https");
+const net = require("net");
+const os = require("os");
+
+// Poll until the server accepts TCP connections on port, or timeout — avoids blind fixed waits.
+function waitServerReady(port, { timeoutMs = 15000, intervalMs = 150 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve) => {
+    const tryConnect = () => {
+      const socket = net.connect({ host: "127.0.0.1", port }, () => {
+        socket.destroy();
+        resolve(true);
+      });
+      socket.on("error", () => {
+        socket.destroy();
+        if (Date.now() >= deadline) return resolve(false);
+        setTimeout(tryConnect, intervalMs);
+      });
+    };
+    tryConnect();
+  });
+}
+
+// Native spinner - no external dependency
+function createSpinner(text) {
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let i = 0;
+  let interval = null;
+  let currentText = text;
+  return {
+    start() {
+      if (process.stdout.isTTY) {
+        process.stdout.write(`\r${frames[0]} ${currentText}`);
+        interval = setInterval(() => {
+          process.stdout.write(`\r${frames[i++ % frames.length]} ${currentText}`);
+        }, 80);
+      }
+      return this;
+    },
+    stop() {
+      if (interval) {
+        clearInterval(interval);
+        interval = null;
+      }
+      if (process.stdout.isTTY) {
+        process.stdout.write("\r\x1b[K");
+      }
+    },
+    succeed(msg) {
+      this.stop();
+      console.log(`✅ ${msg}`);
+    },
+    fail(msg) {
+      this.stop();
+      console.log(`❌ ${msg}`);
+    }
+  };
+}
+
+const pkg = require("./package.json");
+const { ensureSqliteRuntime, buildEnvWithRuntime } = require("./hooks/sqliteRuntime");
+const { ensureTrayRuntime } = require("./hooks/trayRuntime");
+const args = process.argv.slice(2);
+
+// Self-heal SQLite runtime deps (sql.js + better-sqlite3) into ~/.9router/runtime
+// so the server can resolve them via NODE_PATH. Best-effort — sql.js is required,
+// better-sqlite3 is optional. Logs to stderr only on failure.
+try { ensureSqliteRuntime({ silent: true }); } catch {}
+
+// Self-heal tray runtime (systray for macOS/Linux only). Windows skipped.
+try { ensureTrayRuntime({ silent: true }); } catch {}
+
+// Configuration constants
+const APP_NAME = pkg.name; // Use from package.json
+const INSTALL_CMD_LATEST = `npm i -g ${APP_NAME}@latest --prefer-online`;
+
+const DEFAULT_PORT = 20128;
+const DEFAULT_HOST = "0.0.0.0";
+
+// First non-internal IPv4 — the address remote peers actually reach when bound to 0.0.0.0.
+function getLanIp() {
+  for (const ifaces of Object.values(os.networkInterfaces())) {
+    for (const i of ifaces || []) {
+      if (i.family === "IPv4" && !i.internal) return i.address;
+    }
+  }
+  return null;
+}
+
+// Local URL stays "localhost"; warn separately when bound to all interfaces (network-exposed).
+function getDisplayHost() {
+  return host === DEFAULT_HOST ? "localhost" : host;
+}
+const MAX_PORT_ATTEMPTS = 10;
+// Identifiers for killAllAppProcesses - only kill 9router specifically
+const PROCESS_IDENTIFIERS = [
+  '9router'  // Only package name - avoid killing other apps
+];
+
+// Parse arguments
+let port = DEFAULT_PORT;
+let host = DEFAULT_HOST;
+let noBrowser = false;
+let skipUpdate = false;
+let showLog = false;
+let trayMode = false;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--port" || args[i] === "-p") {
+    port = parseInt(args[i + 1], 10) || DEFAULT_PORT;
+    i++;
+  } else if (args[i] === "--host" || args[i] === "-H") {
+    host = args[i + 1] || DEFAULT_HOST;
+    i++;
+  } else if (args[i] === "--no-browser" || args[i] === "-n") {
+    noBrowser = true;
+  } else if (args[i] === "--log" || args[i] === "-l") {
+    showLog = true;
+  } else if (args[i] === "--skip-update") {
+    skipUpdate = true;
+  } else if (args[i] === "--tray" || args[i] === "-t") {
+    trayMode = true;
+    process.env.TRAY_MODE = "1";
+  } else if (args[i] === "--help" || args[i] === "-h") {
+    console.log(`
+Usage: ${APP_NAME} [options]
+
+Options:
+  -p, --port <port>   Port to run the server (default: ${DEFAULT_PORT})
+  -H, --host <host>   Host to bind (default: ${DEFAULT_HOST})
+  -n, --no-browser    Don't open browser automatically
+  -l, --log           Show server logs (default: hidden)
+  -t, --tray          Run in system tray mode (background)
+  --skip-update       Skip auto-update check
+  -h, --help          Show this help message
+  -v, --version       Show version
+`);
+    process.exit(0);
+  } else if (args[i] === "--version" || args[i] === "-v") {
+    console.log(pkg.version);
+    process.exit(0);
+  }
+}
+
+// Auto-relaunch after update: detached process has no TTY → fallback to tray
+if (skipUpdate && !trayMode && !process.stdin.isTTY) {
+  trayMode = true;
+  process.env.TRAY_MODE = "1";
+}
+
+// Always use Node.js runtime with absolute path
+const RUNTIME = process.execPath;
+
+// Compare semver versions: returns 1 if a > b, -1 if a < b, 0 if equal
+function compareVersions(a, b) {
+  const partsA = a.split(".").map(Number);
+  const partsB = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (partsA[i] > partsB[i]) return 1;
+    if (partsA[i] < partsB[i]) return -1;
+  }
+  return 0;
+}
+
+// Get app data dir (matches app/src/lib/dataDir.js convention)
+function getAppDataDir() {
+  return process.platform === "win32"
+    ? path.join(process.env.APPDATA || "", "9router")
+    : path.join(os.homedir(), ".9router");
+}
+
+// Kill PID from file (best-effort, removes file after)
+function killByPidFile(pidFile) {
+  try {
+    if (!fs.existsSync(pidFile)) return;
+    const pid = parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+    if (!pid) return;
+    try {
+      if (process.platform === "win32") {
+        execSync(`taskkill /F /T /PID ${pid}`, { stdio: "ignore", windowsHide: true, timeout: 3000 });
+      } else {
+        process.kill(pid, "SIGKILL");
+      }
+    } catch { }
+    try { fs.unlinkSync(pidFile); } catch { }
+  } catch { }
+}
+
+// Kill tunnel processes (cloudflared/tailscale) by their PID files
+function killTunnelByPidFile() {
+  const tunnelDir = path.join(getAppDataDir(), "tunnel");
+  killByPidFile(path.join(tunnelDir, "cloudflared.pid"));
+  killByPidFile(path.join(tunnelDir, "tailscale.pid"));
+}
+
+// Kill cloudflared whose --url targets this app's port (covers stale PID file case)
+function killCloudflaredByAppPort(appPort) {
+  if (!appPort) return [];
+  const portMatchers = [`localhost:${appPort}`, `127.0.0.1:${appPort}`];
+  const pids = [];
+  try {
+    if (process.platform === "win32") {
+      const psCmd = `powershell -NonInteractive -WindowStyle Hidden -Command "Get-WmiObject Win32_Process -Filter 'Name=\\"cloudflared.exe\\"' | Select-Object ProcessId,CommandLine | ConvertTo-Csv -NoTypeInformation"`;
+      const output = execSync(psCmd, { encoding: "utf8", windowsHide: true, timeout: 5000 });
+      const lines = output.split("\n").slice(1).filter(l => l.trim());
+      lines.forEach(line => {
+        if (portMatchers.some(m => line.includes(m))) {
+          const match = line.match(/^"(\d+)"/);
+          if (match && match[1]) pids.push(match[1]);
+        }
+      });
+    } else {
+      const output = execSync("ps -eo pid,command 2>/dev/null", { encoding: "utf8", timeout: 5000 });
+      output.split("\n").forEach(line => {
+        if (line.includes("cloudflared") && portMatchers.some(m => line.includes(m))) {
+          const parts = line.trim().split(/\s+/);
+          const pid = parts[0];
+          if (pid && !isNaN(pid)) pids.push(pid);
+        }
+      });
+    }
+  } catch { }
+  return pids;
+}
+
+// Kill all 9router processes
+function killAllAppProcesses(appPort) {
+  return new Promise((resolve) => {
+    try {
+      // Background: MITM + tunnel/cloudflared run on separate ports/processes —
+      // killing them doesn't free the app port, so don't block the critical path.
+      // Server-side MITM manager has stale-lock recovery and starts deferred (~3s).
+      setImmediate(() => {
+        try { killProxyByPidFile(); } catch {}
+        try { killTunnelByPidFile(); } catch {}
+        try { killCloudflaredByAppPort(appPort); } catch {}
+      });
+
+      const platform = process.platform;
+      let pids = [];
+
+      if (platform === "win32") {
+        // Windows: use WMI to get full CommandLine (tasklist /V doesn't include it)
+        try {
+          const psCmd = `powershell -NonInteractive -WindowStyle Hidden -Command "Get-WmiObject Win32_Process -Filter 'Name=\\"node.exe\\"' | Select-Object ProcessId,CommandLine | ConvertTo-Csv -NoTypeInformation"`;
+          const output = execSync(psCmd, {
+            encoding: "utf8",
+            windowsHide: true,
+            timeout: 5000
+          });
+          const lines = output.split("\n").slice(1).filter(l => l.trim());
+          lines.forEach(line => {
+            // Whitelist: real node process running 9router/cli.js, or next-server.
+            // Avoids killing editors/grep/strace/cursor that just have "9router" in cmdline.
+            const cmd = line.toLowerCase();
+            const isAppProcess =
+              (cmd.includes("node") && cmd.includes("9router") && (cmd.includes("cli.js") || cmd.includes("\\9router") || cmd.includes("/9router")))
+              || cmd.includes("next-server");
+            if (isAppProcess) {
+              const match = line.match(/^"(\d+)"/);
+              if (match && match[1] && match[1] !== process.pid.toString()) {
+                pids.push(match[1]);
+              }
+            }
+          });
+        } catch (e) {
+          // No processes found or error - continue
+        }
+      } else {
+        // macOS/Linux: use ps to find all matching processes
+        try {
+          const output = execSync('ps aux 2>/dev/null', {
+            encoding: 'utf8',
+            timeout: 5000
+          });
+          const lines = output.split('\n');
+
+          lines.forEach(line => {
+            // Whitelist: real node process running 9router/cli.js, or next-server.
+            // Avoids killing grep/strace/editors/cursor that incidentally match "9router".
+            const cmd = line.toLowerCase();
+            const isAppProcess =
+              (cmd.includes("node") && cmd.includes("9router") && (cmd.includes("cli.js") || cmd.includes("/9router")))
+              || cmd.includes("next-server");
+            if (isAppProcess) {
+              const parts = line.trim().split(/\s+/);
+              const pid = parts[1];
+              if (pid && !isNaN(pid) && pid !== process.pid.toString()) {
+                pids.push(pid);
+              }
+            }
+          });
+        } catch (e) {
+          // No processes found or error - continue
+        }
+      }
+
+      // Kill all found processes
+      if (pids.length > 0) {
+        pids.forEach(pid => {
+          try {
+            if (platform === "win32") {
+              execSync(`taskkill /F /PID ${pid} 2>nul`, { stdio: 'ignore', shell: true, windowsHide: true, timeout: 3000 });
+            } else {
+              execSync(`kill -9 ${pid} 2>/dev/null`, { stdio: 'ignore', timeout: 3000 });
+            }
+          } catch (err) {
+            // Process already dead or can't kill - continue
+          }
+        });
+
+        // Wait for processes to fully terminate
+        setTimeout(() => resolve(), 1000);
+      } else {
+        resolve();
+      }
+    } catch (err) {
+      // Silent fail - continue anyway
+      resolve();
+    }
+  });
+}
+
+// Sleep helper using SharedArrayBuffer wait (sync, no busy-loop)
+function sleepSync(ms) {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* ignore */ }
+}
+
+// Wait until process dies or timeout reached
+function waitForExit(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try { process.kill(pid, 0); } catch { return true; }
+    sleepSync(100);
+  }
+  return false;
+}
+
+// Kill MIT server by PID file (runs privileged, needs special handling)
+// Sends SIGTERM first so MIT can clean up host entries before dying.
+function killProxyByPidFile() {
+  try {
+    const pidFile = path.join(getAppDataDir(), "mitm", ".mitm.pid");
+    if (!fs.existsSync(pidFile)) return;
+    const pid = parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+    if (!pid) return;
+
+    if (process.platform === "win32") {
+      // Graceful first (lets server cleanup hosts), then force
+      try { execSync(`taskkill /T /PID ${pid}`, { stdio: "ignore", windowsHide: true, timeout: 2000 }); } catch { }
+      if (!waitForExit(pid, 1500)) {
+        try { execSync(`taskkill /F /T /PID ${pid}`, { stdio: "ignore", windowsHide: true, timeout: 3000 }); } catch { }
+      }
+      // Last-resort: PowerShell Stop-Process (sometimes succeeds where taskkill fails on admin processes)
+      if (!waitForExit(pid, 500)) {
+        try { execSync(`powershell -NonInteractive -WindowStyle Hidden -Command "Stop-Process -Id ${pid} -Force"`, { stdio: "ignore", windowsHide: true, timeout: 3000 }); } catch { }
+      }
+    } else {
+      // SIGTERM via cached sudo token first
+      try { execSync(`sudo -n kill -TERM ${pid} 2>/dev/null`, { stdio: "ignore", timeout: 2000 }); }
+      catch { try { process.kill(pid, "SIGTERM"); } catch { } }
+      if (!waitForExit(pid, 1500)) {
+        try { execSync(`sudo -n kill -9 ${pid} 2>/dev/null`, { stdio: "ignore", timeout: 2000 }); }
+        catch { try { process.kill(pid, "SIGKILL"); } catch { } }
+      }
+    }
+    try { fs.unlinkSync(pidFile); } catch { }
+  } catch { }
+}
+
+// Kill any process on specific port
+function killProcessOnPort(port) {
+  return new Promise((resolve) => {
+    try {
+      const platform = process.platform;
+      let pid;
+
+      if (platform === "win32") {
+        try {
+          const output = execSync(`netstat -ano | findstr :${port}`, {
+            encoding: 'utf8',
+            shell: true,
+            windowsHide: true,
+            timeout: 5000
+          }).trim();
+          const lines = output.split('\n').filter(l => l.includes('LISTENING'));
+          if (lines.length > 0) {
+            pid = lines[0].trim().split(/\s+/).pop();
+            execSync(`taskkill /F /PID ${pid} 2>nul`, { stdio: 'ignore', shell: true, windowsHide: true, timeout: 3000 });
+          }
+        } catch (e) {
+          // Port is free or error
+        }
+      } else {
+        // macOS/Linux
+        try {
+          const pidOutput = execSync(`lsof -ti:${port}`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore']
+          }).trim();
+          if (pidOutput) {
+            pid = pidOutput.split('\n')[0];
+            execSync(`kill -9 ${pid} 2>/dev/null`, { stdio: 'ignore', timeout: 3000 });
+          }
+        } catch (e) {
+          // Port is free or error
+        }
+      }
+
+      // Wait for port to be released
+      setTimeout(() => resolve(), 500);
+    } catch (err) {
+      // Silent fail - continue anyway
+      resolve();
+    }
+  });
+}
+
+
+// Detect if running in restricted environment (Codespaces, Docker)
+function isRestrictedEnvironment() {
+  // Check for Codespaces
+  if (process.env.CODESPACES === "true" || process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN) {
+    return "GitHub Codespaces";
+  }
+
+  // Check for Docker
+  if (fs.existsSync("/.dockerenv") || (fs.existsSync("/proc/1/cgroup") && fs.readFileSync("/proc/1/cgroup", "utf8").includes("docker"))) {
+    return "Docker";
+  }
+
+  return null;
+}
+
+// Check if new version available, return latest version or null
+function checkForUpdate() {
+  return new Promise((resolve) => {
+    if (skipUpdate) {
+      resolve(null);
+      return;
+    }
+
+    const spinner = createSpinner("Checking for updates...").start();
+    let resolved = false;
+
+    const safetyTimeout = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        spinner.stop();
+        resolve(null);
+      }
+    }, 8000);
+
+    const done = (version) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(safetyTimeout);
+      spinner.stop();
+      resolve(version);
+    };
+
+    const req = https.get(`https://registry.npmjs.org/${pkg.name}/latest`, { timeout: 3000 }, (res) => {
+      let data = "";
+      res.on("data", chunk => data += chunk);
+      res.on("end", () => {
+        try {
+          const latest = JSON.parse(data);
+          if (latest.version && compareVersions(latest.version, pkg.version) > 0) {
+            done(latest.version);
+          } else {
+            done(null);
+          }
+        } catch (e) {
+          done(null);
+        }
+      });
+    });
+
+    req.on("error", () => done(null));
+    req.on("timeout", () => { req.destroy(); done(null); });
+  });
+}
+
+// Open browser
+function openBrowser(url) {
+  const platform = process.platform;
+  let cmd;
+
+  if (platform === "darwin") {
+    cmd = `open "${url}"`;
+  } else if (platform === "win32") {
+    cmd = `start "" "${url}"`;
+  } else {
+    cmd = `xdg-open "${url}"`;
+  }
+
+  exec(cmd, { windowsHide: true }, (err) => {
+    if (err) {
+      console.log(`Open browser manually: ${url}`);
+    }
+  });
+}
+
+// Find standalone server (bundled in bin/app for published package).
+// Prefer custom-server.js (injects real socket IP) when present.
+const standaloneDir = path.join(__dirname, "app");
+const customServerPath = path.join(standaloneDir, "custom-server.js");
+const serverPath = fs.existsSync(customServerPath)
+  ? customServerPath
+  : path.join(standaloneDir, "server.js");
+
+if (!fs.existsSync(serverPath)) {
+  console.error("Error: Standalone build not found.");
+  console.error("Please run 'npm run build:cli' first.");
+  process.exit(1);
+}
+
+// Start server immediately; run update check in parallel (not on the critical path).
+const updatePromise = checkForUpdate();
+killAllAppProcesses(port)
+  .then(() => killProcessOnPort(port))
+  .then(() => startServer(updatePromise));
+
+// Show interface selection menu
+async function showInterfaceMenu(latestVersion) {
+  const { selectMenu } = require("./src/cli/utils/input");
+  const { clearScreen } = require("./src/cli/utils/display");
+  const { getEndpoint } = require("./src/cli/utils/endpoint");
+
+  clearScreen();
+
+  const displayHost = getDisplayHost();
+
+  // Detect tunnel/local mode for server URL display
+  let serverUrl;
+  try {
+    const { endpoint, tunnelEnabled } = await getEndpoint(port);
+    serverUrl = tunnelEnabled ? endpoint.replace(/\/v1$/, "") : `http://${displayHost}:${port}`;
+  } catch (e) {
+    serverUrl = `http://${displayHost}:${port}`;
+  }
+
+  const subtitle = `🚀 Server: \x1b[32m${serverUrl}\x1b[0m`;
+
+  const menuItems = [];
+
+  if (latestVersion) {
+    menuItems.push({ label: `Update to v${latestVersion} (current: v${pkg.version})`, icon: "⬆" });
+  }
+
+  menuItems.push(
+    { label: "Web UI (Open in Browser)", icon: "🌐" },
+    { label: "Terminal UI (Interactive CLI)", icon: "💻" },
+    { label: "Hide to Tray (Background)", icon: "🔔" },
+    { label: "Exit", icon: "🚪" }
+  );
+
+  const selected = await selectMenu(`Choose Interface (v${pkg.version})`, menuItems, 0, subtitle);
+
+  const offset = latestVersion ? 1 : 0;
+
+  if (latestVersion && selected === 0) return "update";
+  if (selected === offset) return "web";
+  if (selected === offset + 1) return "terminal";
+  if (selected === offset + 2) return "hide";
+  return "exit";
+}
+
+const MAX_RESTARTS = 2;
+const RESTART_RESET_MS = 30000; // Reset counter if alive > 30s
+
+function startServer(updatePromise) {
+  // Accept either a Promise (parallel update check) or a resolved value.
+  const latestVersionPromise = Promise.resolve(updatePromise);
+  const displayHost = getDisplayHost();
+  const url = `http://${displayHost}:${port}/dashboard`;
+  // Surface real network exposure when bound to all interfaces (default 0.0.0.0).
+  if (host === DEFAULT_HOST) {
+    const lanIp = getLanIp();
+    if (lanIp) console.log(`\x1b[33m⚠ Network-exposed: reachable at http://${lanIp}:${port} (bound 0.0.0.0). Use --host 127.0.0.1 for local-only.\x1b[0m`);
+  }
+
+  let restartCount = 0;
+  let serverStartTime = Date.now();
+
+  const CRASH_LOG_LINES = 50;
+  let crashLog = [];
+
+  function spawnServer() {
+    serverStartTime = Date.now();
+    crashLog = [];
+    const child = spawn(RUNTIME, ["--max-old-space-size=6144", serverPath], {
+      cwd: standaloneDir,
+      stdio: showLog ? "inherit" : ["ignore", "ignore", "pipe"],
+      detached: true,
+      windowsHide: true,
+      env: {
+        ...buildEnvWithRuntime(process.env),
+        PORT: port.toString(),
+        HOSTNAME: host
+      }
+    });
+    if (!showLog && child.stderr) {
+      child.stderr.on("data", (data) => {
+        const lines = data.toString().split("\n").filter(Boolean);
+        crashLog.push(...lines);
+        if (crashLog.length > CRASH_LOG_LINES) crashLog = crashLog.slice(-CRASH_LOG_LINES);
+      });
+    }
+    return child;
+  }
+
+  let server = spawnServer();
+
+  // Cleanup function - force kill server process
+  let isCleaningUp = false;
+  function cleanup() {
+    if (isCleaningUp) return;
+    isCleaningUp = true;
+    try {
+      // Kill tray if running
+      try {
+        const { killTray } = require("./src/cli/tray/tray");
+        killTray();
+      } catch (e) { }
+      // Kill MIT server (privileged process) via PID file
+      killProxyByPidFile();
+      // Kill cloudflared/tailscale via PID file (only this app's tunnel)
+      killTunnelByPidFile();
+      // Kill server process directly
+      if (server.pid) {
+        process.kill(server.pid, "SIGKILL");
+      }
+      // Also try to kill process group
+      process.kill(-server.pid, "SIGKILL");
+    } catch (e) { }
+  }
+
+  // Suppress all errors during shutdown (systray lib throws JSON parse errors)
+  let isShuttingDown = false;
+  process.on("uncaughtException", (err) => {
+    if (isShuttingDown) return;
+    console.error("Error:", err.message);
+  });
+
+  // Handle all exit scenarios
+  process.on("SIGINT", () => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+    console.log("\nExiting...");
+    cleanup();
+    setTimeout(() => process.exit(0), 100);
+  });
+  process.on("SIGTERM", () => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+    cleanup();
+    setTimeout(() => process.exit(0), 100);
+  });
+  process.on("SIGHUP", () => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+    cleanup();
+    setTimeout(() => process.exit(0), 100);
+  });
+
+  // Initialize tray icon (runs alongside TUI)
+  const initTrayIcon = () => {
+    try {
+      const { initTray } = require("./src/cli/tray/tray");
+      initTray({
+        port,
+        onQuit: () => {
+          isShuttingDown = true;
+          console.log("\n👋 Shutting down from tray...");
+          cleanup();
+          setTimeout(() => process.exit(0), 100);
+        },
+        onOpenDashboard: () => openBrowser(url)
+      });
+    } catch (err) {
+      // Tray not available - continue without it
+    }
+  };
+
+  // Tray-only mode: no TUI, just tray icon
+  if (trayMode) {
+    // Ignore SIGHUP so macOS terminal close doesn't kill the background tray process
+    process.removeAllListeners("SIGHUP");
+    process.on("SIGHUP", () => {});
+
+    console.log(`\n🚀 ${pkg.name} v${pkg.version}`);
+    console.log(`Server: http://${displayHost}:${port}`);
+
+    waitServerReady(port).then(() => {
+      initTrayIcon();
+      console.log("\n💡 Router is now running in system tray. Close this terminal if you want.");
+      console.log("   Right-click tray icon to open dashboard or quit.\n");
+    });
+
+    return;
+  }
+
+  // Wait for server to be ready, then show interface menu loop + tray
+  waitServerReady(port).then(async () => {
+    // Resolve parallel update check (already running); don't block server start on it.
+    const latestVersion = await latestVersionPromise;
+    // Start tray icon alongside TUI
+    initTrayIcon();
+
+    try {
+      while (true) {
+        const choice = await showInterfaceMenu(latestVersion);
+
+        if (choice === "update") {
+          isShuttingDown = true;
+          const { clearScreen } = require("./src/cli/utils/display");
+          clearScreen();
+          console.log(`\n⬆  Update v${pkg.version} → v${latestVersion}\n`);
+          console.log(`Run this after exit:\n`);
+          console.log(`   \x1b[33m${INSTALL_CMD_LATEST}\x1b[0m\n`);
+          cleanup();
+          await killAllAppProcesses(port);
+          await killProcessOnPort(port);
+          setTimeout(() => process.exit(0), 200);
+          return;
+        } else if (choice === "web") {
+          openBrowser(url);
+          // Wait for user to come back
+          const { pause } = require("./src/cli/utils/input");
+          await pause("\nPress Enter to go back to menu...");
+        } else if (choice === "terminal") {
+          // Start Terminal UI - it will return when user selects Back
+          const { startTerminalUI } = require("./src/cli/terminalUI");
+          await startTerminalUI(port);
+          // Loop continues, show menu again
+        } else if (choice === "hide") {
+          const { clearScreen } = require("./src/cli/utils/display");
+          clearScreen();
+
+          // Enable auto startup on OS boot
+          try {
+            const { enableAutoStart } = require("./src/cli/tray/autostart");
+            enableAutoStart(__filename);
+          } catch (e) { }
+
+          if (process.platform === "darwin") {
+            // macOS: keep current process alive — spawning a detached child puts
+            // it outside the login session so NSStatusItem silently fails.
+            process.removeAllListeners("SIGHUP");
+            process.on("SIGHUP", () => {});
+
+            console.log(`\n⏳ Switching to tray mode... (icon already visible in menu bar)`);
+            console.log(`🔔 9Router is running in tray (PID: ${process.pid})`);
+            console.log(`   Server: http://${displayHost}:${port}`);
+            console.log(`\n💡 You can close this terminal. Right-click tray icon to quit.\n`);
+
+            // Tray already init'd at startup — just keep event loop alive.
+            return;
+          }
+
+          // Windows/Linux: spawn detached bgProcess (systray works fine in child)
+          console.log(`\n⏳ Starting background process... (tray icon will appear in ~3s)`);
+
+          const bgProcess = spawn(process.execPath, [__filename, "--tray", "--skip-update", "-p", port.toString()], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+            env: { ...process.env }
+          });
+          bgProcess.unref();
+
+          console.log(`🔔 9Router is now running in background (PID: ${bgProcess.pid})`);
+          console.log(`   Server: http://${displayHost}:${port}`);
+          console.log(`\n💡 You can close this terminal. Right-click tray icon to quit.\n`);
+
+          // cleanup() kills server so bgProcess can claim the port fresh
+          cleanup();
+          process.exit(0);
+        } else if (choice === "exit") {
+          isShuttingDown = true;
+          console.log("\nExiting...");
+          cleanup();
+          setTimeout(() => process.exit(0), 100);
+        }
+      }
+    } catch (err) {
+      console.error("Error:", err.message);
+      cleanup();
+      process.exit(1);
+    }
+  });
+
+  function attachServerEvents() {
+    server.on("error", (err) => {
+      console.error("Failed to start server:", err.message);
+      if (!isShuttingDown) tryRestart();
+      else { cleanup(); process.exit(1); }
+    });
+
+    server.on("close", (code) => {
+      if (isShuttingDown || code === 0) {
+        process.exit(code || 0);
+        return;
+      }
+      tryRestart(code);
+    });
+  }
+
+  function tryRestart(code) {
+    const aliveMs = Date.now() - serverStartTime;
+    // Reset counter if last run was stable
+    if (aliveMs >= RESTART_RESET_MS) restartCount = 0;
+
+    if (restartCount >= MAX_RESTARTS) {
+      console.error(`\n⚠️  Server crashed ${MAX_RESTARTS} times. Disabling MIT and restarting...`);
+      try {
+        const dbPath = path.join(os.homedir(), process.platform === "win32" ? path.join("AppData", "Roaming", "9router", "db.json") : path.join(".9router", "db.json"));
+        if (fs.existsSync(dbPath)) {
+          const db = JSON.parse(fs.readFileSync(dbPath, "utf-8"));
+          if (db.settings) db.settings.mitmEnabled = false;
+          fs.writeFileSync(dbPath, JSON.stringify(db, null, 2));
+        }
+      } catch { /* best effort */ }
+      restartCount = 0;
+      server = spawnServer();
+      attachServerEvents();
+      return;
+    }
+
+    restartCount++;
+    const delay = Math.min(1000 * restartCount, 10000);
+    console.error(`\n⚠️  Server exited (code=${code ?? "unknown"}). Restarting in ${delay / 1000}s... (${restartCount}/${MAX_RESTARTS})`);
+    if (crashLog.length) {
+      console.error("\n--- Server crash log ---");
+      crashLog.forEach(l => console.error(l));
+      console.error("--- End crash log ---\n");
+    }
+
+    setTimeout(() => {
+      server = spawnServer();
+      attachServerEvents();
+    }, delay);
+  }
+
+  attachServerEvents();
+}
diff --git a/cli/hooks/postinstall.js b/cli/hooks/postinstall.js
new file mode 100644
index 0000000..3a59332
--- /dev/null
+++ b/cli/hooks/postinstall.js
@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+// Postinstall: warm-up SQLite deps into ~/.9router/runtime so the first
+// `9router` start doesn't need network. Failure here is non-fatal —
+// cli.js will retry at runtime if anything is missing.
+const { ensureSqliteRuntime } = require("./sqliteRuntime");
+const { ensureTrayRuntime } = require("./trayRuntime");
+
+try {
+  ensureSqliteRuntime({ silent: false });
+  console.log("[9router] runtime SQLite deps ready");
+} catch (e) {
+  console.warn(`[9router] runtime warm-up skipped: ${e.message}`);
+}
+
+try {
+  ensureTrayRuntime({ silent: false });
+} catch (e) {
+  console.warn(`[9router] tray runtime skipped: ${e.message}`);
+}
+
+process.exit(0);
diff --git a/cli/hooks/sqliteRuntime.js b/cli/hooks/sqliteRuntime.js
new file mode 100644
index 0000000..feca2f5
--- /dev/null
+++ b/cli/hooks/sqliteRuntime.js
@@ -0,0 +1,156 @@
+// Ensure better-sqlite3 is installed in USER_DATA_DIR/runtime/node_modules
+// (user-writable, avoids Windows EBUSY locks during npm i -g updates).
+// sql.js is bundled in bin/app already; node:sqlite / bun:sqlite are built-in.
+const { execSync, spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const BETTER_SQLITE3_VERSION = "12.6.2";
+const SQL_JS_VERSION = "1.14.1";
+
+function getDataDir() {
+  if (process.env.DATA_DIR) return process.env.DATA_DIR;
+  return process.platform === "win32"
+    ? path.join(process.env.APPDATA || os.homedir(), "9router")
+    : path.join(os.homedir(), ".9router");
+}
+
+function getRuntimeDir() {
+  return path.join(getDataDir(), "runtime");
+}
+
+function getRuntimeNodeModules() {
+  return path.join(getRuntimeDir(), "node_modules");
+}
+
+function ensureRuntimeDir() {
+  const dir = getRuntimeDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  // Minimal package.json so npm treats it as a project root
+  const pkgPath = path.join(dir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    fs.writeFileSync(pkgPath, JSON.stringify({
+      name: "9router-runtime",
+      version: "1.0.0",
+      private: true,
+      description: "User-writable runtime deps for 9router (better-sqlite3 native binary)",
+    }, null, 2));
+  }
+  return dir;
+}
+
+function hasModule(name) {
+  return fs.existsSync(path.join(getRuntimeNodeModules(), name, "package.json"));
+}
+
+function isBetterSqliteBinaryValid() {
+  const binary = path.join(getRuntimeNodeModules(), "better-sqlite3", "build", "Release", "better_sqlite3.node");
+  if (!fs.existsSync(binary)) return false;
+  try {
+    const fd = fs.openSync(binary, "r");
+    const buf = Buffer.alloc(4);
+    fs.readSync(fd, buf, 0, 4, 0);
+    fs.closeSync(fd);
+    const magic = buf.toString("hex");
+    if (process.platform === "linux") return magic.startsWith("7f454c46");
+    if (process.platform === "darwin") return magic.startsWith("cffaedfe") || magic.startsWith("cefaedfe");
+    if (process.platform === "win32") return magic.startsWith("4d5a");
+    return true;
+  } catch { return false; }
+}
+
+// Extract a short, user-friendly reason from npm stderr.
+function summarizeNpmError(stderr = "") {
+  const text = String(stderr);
+  if (/ENOTFOUND|ETIMEDOUT|EAI_AGAIN|network|getaddrinfo/i.test(text)) return "No internet connection or registry unreachable";
+  if (/EACCES|EPERM|permission denied/i.test(text)) return "Permission denied (check folder permissions)";
+  if (/ENOSPC|no space/i.test(text)) return "Not enough disk space";
+  if (/node-gyp|gyp ERR|python|MSBuild|Visual Studio|Xcode/i.test(text)) return "Missing build tools (Xcode CLT / Python / VS Build Tools)";
+  if (/ETARGET|version.*not found/i.test(text)) return "Package version not found on registry";
+  const m = text.match(/npm ERR! (.+)/);
+  if (m) return m[1].slice(0, 200);
+  const lastLine = text.trim().split(/\r?\n/).filter(Boolean).pop();
+  return lastLine ? lastLine.slice(0, 200) : "Unknown error";
+}
+
+function runNpmInstall({ cwd, pkgs, extraArgs = [], timeout = 180000 }) {
+  const args = ["install", ...pkgs, "--no-audit", "--no-fund", "--prefer-online", ...extraArgs];
+  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+  const res = spawnSync(npmCmd, args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout,
+    shell: process.platform === "win32",
+    encoding: "utf8",
+  });
+  return { ok: res.status === 0, code: res.status, stderr: res.stderr || "", stdout: res.stdout || "" };
+}
+
+function npmInstall(pkgs, opts = {}) {
+  const cwd = ensureRuntimeDir();
+  const extra = opts.optional ? ["--no-save"] : [];
+  if (!opts.silent) console.log("⏳ Installing SQLite engine (first run)...");
+  const res = runNpmInstall({ cwd, pkgs, extraArgs: extra, timeout: opts.timeout || 180000 });
+  if (!res.ok && !opts.silent) {
+    const reason = summarizeNpmError(res.stderr);
+    console.warn("⚠️  SQLite engine install failed — using fallback");
+    console.warn(`   Reason: ${reason}`);
+    console.warn(`   Retry:  cd "${cwd}" && npm install ${pkgs.join(" ")}`);
+  }
+  return res.ok;
+}
+
+// Public: ensure better-sqlite3 native module is installed in user-writable
+// runtime dir. sql.js may be bundled in bin/app, but npm publish strips .wasm
+// from nested node_modules — verify and reinstall if missing. node:sqlite is
+// built-in. This is purely a *speed optimization* — app works without
+// better-sqlite3 via fallbacks.
+function isSqlJsWasmValid() {
+  const bundledWasm = path.join(__dirname, "..", "app", "node_modules", "sql.js", "dist", "sql-wasm.wasm");
+  if (fs.existsSync(bundledWasm)) return true;
+  const runtimeWasm = path.join(getRuntimeNodeModules(), "sql.js", "dist", "sql-wasm.wasm");
+  return fs.existsSync(runtimeWasm);
+}
+
+function ensureSqliteRuntime({ silent = false } = {}) {
+  ensureRuntimeDir();
+
+  let sqlJsOk = isSqlJsWasmValid();
+  if (!sqlJsOk) {
+    sqlJsOk = npmInstall([`sql.js@${SQL_JS_VERSION}`], { silent });
+    if (sqlJsOk) sqlJsOk = isSqlJsWasmValid();
+  }
+
+  const needBetterSqlite = !hasModule("better-sqlite3") || !isBetterSqliteBinaryValid();
+  if (!needBetterSqlite) {
+    if (!silent) console.log("✅ SQLite engine ready");
+    return { betterSqlite: true, sqlJs: sqlJsOk };
+  }
+
+  const ok = npmInstall([`better-sqlite3@${BETTER_SQLITE3_VERSION}`], { optional: true, silent });
+  return {
+    betterSqlite: ok && hasModule("better-sqlite3") && isBetterSqliteBinaryValid(),
+    sqlJs: sqlJsOk,
+  };
+}
+
+// Inject runtime + bundled node_modules into NODE_PATH so child Node processes
+// resolve sql.js (bundled in bin/app/node_modules) and better-sqlite3 (runtime).
+function buildEnvWithRuntime(baseEnv = process.env) {
+  const runtimeNm = getRuntimeNodeModules();
+  const bundledNm = path.join(__dirname, "..", "app", "node_modules");
+  const existing = baseEnv.NODE_PATH || "";
+  const NODE_PATH = [runtimeNm, bundledNm, existing].filter(Boolean).join(path.delimiter);
+  return { ...baseEnv, NODE_PATH };
+}
+
+module.exports = {
+  ensureSqliteRuntime,
+  buildEnvWithRuntime,
+  getRuntimeDir,
+  getRuntimeNodeModules,
+  runNpmInstall,
+  summarizeNpmError,
+};
diff --git a/cli/hooks/trayRuntime.js b/cli/hooks/trayRuntime.js
new file mode 100644
index 0000000..dafb215
--- /dev/null
+++ b/cli/hooks/trayRuntime.js
@@ -0,0 +1,107 @@
+// Lazy install systray2 for macOS/Linux into USER_DATA_DIR/runtime/node_modules.
+// Windows uses PowerShell NotifyIcon (no binary) → no systray needed.
+// This keeps the published npm tarball free of unsigned Go binaries that
+// trigger antivirus false positives (e.g. Kaspersky flagging tray_windows.exe).
+//
+// We use the maintained `systray2` fork. The original `systray@1.0.5` package
+// bundles a 2017 x86_64 Go binary whose Mach-O headers are rejected by modern
+// dyld (macOS 14+), so the tray silently fails to register on Apple Silicon.
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const { getRuntimeDir, getRuntimeNodeModules, runNpmInstall, summarizeNpmError } = require("./sqliteRuntime");
+
+const SYSTRAY_PKG = "systray2";
+const SYSTRAY_VERSION = "2.1.4";
+const LEGACY_SYSTRAY_PKG = "systray";
+
+function hasSystray() {
+  return fs.existsSync(path.join(getRuntimeNodeModules(), SYSTRAY_PKG, "package.json"));
+}
+
+// Remove the legacy `systray` package from all known locations.
+// On Windows it was an AV false-positive risk; on macOS/Linux its bundled
+// binary is broken on modern OS versions.
+function cleanupLegacySystray({ silent = false } = {}) {
+  // 1) Runtime dir: ~/.9router/runtime/node_modules/systray (or %APPDATA% on Win)
+  // 2) npm global nested: <npm_prefix>/node_modules/9router/node_modules/systray
+  //    __dirname here = <pkg root>/hooks → up 1 = pkg root
+  const targets = [
+    path.join(getRuntimeNodeModules(), LEGACY_SYSTRAY_PKG),
+    path.join(__dirname, "..", "node_modules", LEGACY_SYSTRAY_PKG)
+  ];
+  for (const dir of targets) {
+    if (fs.existsSync(dir)) {
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+        if (!silent) console.log(`[9router][runtime] removed legacy systray: ${dir}`);
+      } catch (e) {
+        if (!silent) console.warn(`[9router][runtime] failed to remove ${dir}: ${e.message}`);
+      }
+    }
+  }
+}
+
+// systray2's npm tarball sometimes ships the bundled Go binary without the
+// executable bit set on macOS, causing spawn() to fail with EACCES. Set +x
+// best-effort so the tray actually starts.
+function chmodSystrayBin({ silent = false } = {}) {
+  if (process.platform === "win32") return;
+  const binName = process.platform === "darwin" ? "tray_darwin_release" : "tray_linux_release";
+  const binPath = path.join(getRuntimeNodeModules(), SYSTRAY_PKG, "traybin", binName);
+  if (!fs.existsSync(binPath)) return;
+  try {
+    fs.chmodSync(binPath, 0o755);
+  } catch (e) {
+    if (!silent) console.warn(`[9router][runtime] chmod tray bin failed: ${e.message}`);
+  }
+}
+
+function ensureRuntimeDir() {
+  const dir = getRuntimeDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const pkgPath = path.join(dir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    fs.writeFileSync(pkgPath, JSON.stringify({
+      name: "9router-runtime",
+      version: "1.0.0",
+      private: true
+    }, null, 2));
+  }
+  return dir;
+}
+
+function npmInstall(pkgs, { silent = false } = {}) {
+  const cwd = ensureRuntimeDir();
+  if (!silent) console.log("⏳ Installing system tray (first run)...");
+  const res = runNpmInstall({ cwd, pkgs, extraArgs: ["--no-save"], timeout: 120000 });
+  if (!res.ok && !silent) {
+    const reason = summarizeNpmError(res.stderr);
+    console.warn("⚠️  System tray install failed — tray disabled");
+    console.warn(`   Reason: ${reason}`);
+    console.warn(`   Retry:  cd "${cwd}" && npm install ${pkgs.join(" ")}`);
+  }
+  return res.ok;
+}
+
+// Public: ensure systray2 is installed on macOS/Linux only.
+// Windows skips entirely (uses PowerShell tray).
+function ensureTrayRuntime({ silent = false } = {}) {
+  // Always evict the legacy `systray` package — its binary is broken on
+  // modern macOS and an AV false-positive on Windows.
+  cleanupLegacySystray({ silent });
+
+  if (process.platform === "win32") {
+    return { systray: false, skipped: true };
+  }
+  if (hasSystray()) {
+    chmodSystrayBin({ silent });
+    if (!silent) console.log("✅ System tray ready");
+    return { systray: true };
+  }
+  const ok = npmInstall([`${SYSTRAY_PKG}@${SYSTRAY_VERSION}`], { silent });
+  if (ok) chmodSystrayBin({ silent });
+  return { systray: ok && hasSystray() };
+}
+
+module.exports = { ensureTrayRuntime };
diff --git a/cli/package.json b/cli/package.json
new file mode 100644
index 0000000..e72fd18
--- /dev/null
+++ b/cli/package.json
@@ -0,0 +1,48 @@
+{
+  "name": "9router",
+  "version": "0.5.30",
+  "description": "9Router CLI - Start and manage 9Router server",
+  "bin": {
+    "9router": "./cli.js"
+  },
+  "files": [
+    "cli.js",
+    "src",
+    "hooks",
+    "app",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "nodemon -I --watch cli.js --watch src --watch hooks --ext js,json cli.js",
+    "build": "node scripts/build-cli.js",
+    "pack:cli": "npm run build && npm pack --pack-destination ../..",
+    "publish:cli": "npm run build && npm publish",
+    "postinstall": "node hooks/postinstall.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "enquirer": "^2.4.1",
+    "node-forge": "^1.3.3",
+    "node-machine-id": "^1.1.12",
+    "react": "19.2.1",
+    "react-dom": "19.2.1"
+  },
+  "comment_sqlite": "sql.js + better-sqlite3 are NOT bundled here. They are installed into ~/.9router/runtime/node_modules by hooks/postinstall.js (and re-checked at runtime by cli.js). This avoids Windows EBUSY errors when updating the global CLI, since native .node files no longer live under the locked install dir.",
+  "comment_systray": "systray2 is NOT bundled here. It is lazy-installed into ~/.9router/runtime/node_modules by hooks/postinstall.js on macOS/Linux only. Windows uses PowerShell NotifyIcon (zero binary). This avoids shipping unsigned Go binaries that trigger antivirus false positives (Kaspersky). We use the systray2 fork because the legacy systray@1.0.5 ships a 2017 x86_64 binary that fails on modern macOS dyld.",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "9router",
+    "cli",
+    "proxy",
+    "ai",
+    "api"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "esbuild": "^0.25.12",
+    "nodemon": "^3.1.14"
+  }
+}
diff --git a/cli/scripts/build-cli.js b/cli/scripts/build-cli.js
new file mode 100644
index 0000000..a1b28c5
--- /dev/null
+++ b/cli/scripts/build-cli.js
@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const cliDir = path.resolve(__dirname, "..");
+const appDir = path.resolve(cliDir, "..");
+const rootDir = path.resolve(appDir, "..");
+const cliAppDir = process.env.NINEROUTER_CLI_APP_DIR || path.join(cliDir, "app");
+const buildHomeDir = path.join(cliDir, ".build-home");
+const buildDistDirName = ".next-cli-build";
+const buildDistDir = path.join(appDir, buildDistDirName);
+
+// Exclude patterns for files/folders we don't want to copy
+const EXCLUDE_PATTERNS = [
+  "@img",           // Sharp image processing (not needed with unoptimized images)
+  "sharp",          // Sharp core lib (not needed with unoptimized images)
+  "detect-libc",    // Sharp dependency
+  ".env",           // Environment files
+  ".env.local",
+  ".env.*.local",
+  "*.log",          // Log files
+  "tmp",            // Temp files
+  ".DS_Store",      // macOS files
+];
+
+function shouldExclude(name) {
+  return EXCLUDE_PATTERNS.some(pattern => {
+    if (pattern.includes("*")) {
+      const regex = new RegExp("^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$");
+      return regex.test(name);
+    }
+    return name === pattern;
+  });
+}
+
+function copyRecursive(src, dest) {
+  if (!fs.existsSync(src)) {
+    console.warn(`Warning: Source ${src} does not exist`);
+    return;
+  }
+  
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (shouldExclude(entry.name)) {
+      continue;
+    }
+
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    // Skip broken symlinks (common in workspace setups)
+    try {
+      fs.accessSync(srcPath);
+    } catch {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      copyRecursive(srcPath, destPath);
+    } else if (entry.isSymbolicLink()) {
+      // Resolve and copy target (avoid linking outside bundle)
+      try {
+        const real = fs.realpathSync(srcPath);
+        if (fs.statSync(real).isDirectory()) {
+          copyRecursive(real, destPath);
+        } else {
+          fs.copyFileSync(real, destPath);
+        }
+      } catch {}
+    } else {
+      try {
+        fs.copyFileSync(srcPath, destPath);
+      } catch {}
+    }
+  }
+}
+
+console.log("📦 Building 9Router CLI package with Next.js...\n");
+
+fs.mkdirSync(buildHomeDir, { recursive: true });
+fs.mkdirSync(path.join(buildHomeDir, "AppData", "Roaming"), { recursive: true });
+fs.mkdirSync(path.join(buildHomeDir, "AppData", "Local"), { recursive: true });
+
+// Step 0: Sync version from app/cli/package.json to app/package.json
+console.log("0️⃣  Syncing version to app/package.json...");
+const cliPkg = JSON.parse(fs.readFileSync(path.join(cliDir, "package.json"), "utf8"));
+const appPkgPath = path.join(appDir, "package.json");
+const appPkg = JSON.parse(fs.readFileSync(appPkgPath, "utf8"));
+if (appPkg.version !== cliPkg.version) {
+  appPkg.version = cliPkg.version;
+  fs.writeFileSync(appPkgPath, JSON.stringify(appPkg, null, 2) + "\n");
+  console.log(`✅ Version synced: ${cliPkg.version}\n`);
+} else {
+  console.log(`✅ Version already synced: ${cliPkg.version}\n`);
+}
+
+// Step 1: Build app with Next.js (workspace tracing root → traced node_modules in standalone).
+console.log("1️⃣  Building Next.js app...");
+try {
+  execSync("npm run build", {
+    stdio: "inherit",
+    cwd: appDir,
+    env: {
+      ...process.env,
+      HOME: buildHomeDir,
+      USERPROFILE: buildHomeDir,
+      APPDATA: path.join(buildHomeDir, "AppData", "Roaming"),
+      LOCALAPPDATA: path.join(buildHomeDir, "AppData", "Local"),
+      NEXT_DIST_DIR: buildDistDirName,
+      NEXT_TRACING_ROOT_MODE: "workspace",
+    }
+  });
+  console.log("✅ Next.js build completed\n");
+} catch (error) {
+  console.error("❌ Next.js build failed");
+  process.exit(1);
+}
+
+// Step 2: Clean old app/cli/app if exists
+console.log("2️⃣  Cleaning old app/cli/app...");
+if (fs.existsSync(cliAppDir)) {
+  fs.rmSync(cliAppDir, { recursive: true, force: true });
+}
+console.log("✅ Cleaned\n");
+
+// Step 3: Copy Next.js standalone build to app/cli/app.
+// Newer Next.js standalone output writes server.js/package.json plus .next/, src/, and
+// node_modules/ directly under .next/standalone. Older builds may still use a nested app/.
+console.log("3️⃣  Copying Next.js standalone build to app/cli/app...");
+const standaloneRoot = path.join(appDir, ".next", "standalone");
+const standaloneRootResolved = path.join(buildDistDir, "standalone");
+let standaloneRootToUse = fs.existsSync(standaloneRootResolved) ? standaloneRootResolved : standaloneRoot;
+// Next.js 16 nests standalone output under the project name when NEXT_TRACING_ROOT_MODE=workspace
+// e.g. .next-cli-build/standalone/9router/server.js
+const pkgName = path.basename(appDir);
+const nestedRoot = path.join(standaloneRootToUse, pkgName);
+if (fs.existsSync(path.join(nestedRoot, "server.js")) && !fs.existsSync(path.join(standaloneRootToUse, "server.js"))) {
+  console.log(`ℹ️  Detected nested standalone output: ${pkgName}/`);
+  standaloneRootToUse = nestedRoot;
+}
+const standaloneApp = fs.existsSync(path.join(standaloneRootToUse, "server.js"))
+  ? standaloneRootToUse
+  : path.join(standaloneRootToUse, "app");
+if (!fs.existsSync(standaloneApp)) {
+  console.error("❌ Next.js standalone build not found under .next/standalone");
+  console.error("Expected either .next/standalone/server.js or .next/standalone/app/");
+  process.exit(1);
+}
+copyRecursive(standaloneApp, cliAppDir);
+
+// Older nested-app layout stores traced node_modules at standalone root.
+const standaloneNodeModules = path.join(standaloneRootToUse, "node_modules");
+if (standaloneApp !== standaloneRootToUse && fs.existsSync(standaloneNodeModules)) {
+  copyRecursive(standaloneNodeModules, path.join(cliAppDir, "node_modules"));
+}
+console.log("✅ Copied standalone build\n");
+
+// Step 3a: Copy custom server (injects real socket IP, strips spoofable XFF).
+const customServerSrc = path.join(appDir, "custom-server.js");
+if (fs.existsSync(customServerSrc)) {
+  fs.copyFileSync(customServerSrc, path.join(cliAppDir, "custom-server.js"));
+  console.log("✅ Copied custom-server.js\n");
+} else {
+  console.warn("⚠️  custom-server.js not found — server will run without real-IP injection\n");
+}
+
+// Step 3b: Ensure sql.js (pure JS fallback) bundled in app/cli/app/node_modules.
+// Strip better-sqlite3 (native) — it lives in ~/.9router/runtime to avoid
+// Windows EBUSY during global CLI updates. node:sqlite (Node ≥22.5) is also
+// available as a no-install middle tier.
+console.log("3️⃣ b Configuring SQLite drivers...");
+function ensureModuleInBundle(pkg) {
+  const dest = path.join(cliAppDir, "node_modules", pkg);
+  if (fs.existsSync(dest)) {
+    console.log(`✅ ${pkg} already bundled`);
+    return;
+  }
+  const candidates = [
+    path.join(appDir, "node_modules", pkg),
+    path.join(rootDir, "node_modules", pkg),
+  ];
+  const src = candidates.find((p) => fs.existsSync(p));
+  if (!src) {
+    console.warn(`⚠️  ${pkg} not found locally — bundle will rely on node:sqlite or runtime install`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  copyRecursive(src, dest);
+  console.log(`✅ Bundled ${pkg}`);
+}
+ensureModuleInBundle("sql.js");
+const betterDir = path.join(cliAppDir, "node_modules", "better-sqlite3");
+if (fs.existsSync(betterDir)) {
+  fs.rmSync(betterDir, { recursive: true, force: true });
+  console.log("✅ Stripped better-sqlite3 (lives in ~/.9router/runtime)");
+}
+console.log("");
+
+// Step 4: Copy static files
+console.log("4️⃣  Copying static files...");
+const staticSrc = path.join(appDir, ".next", "static");
+const staticSrcResolved = path.join(buildDistDir, "static");
+const staticDest = path.join(cliAppDir, buildDistDirName, "static");
+if (fs.existsSync(staticSrcResolved) || fs.existsSync(staticSrc)) {
+  copyRecursive(fs.existsSync(staticSrcResolved) ? staticSrcResolved : staticSrc, staticDest);
+  console.log("✅ Copied static files\n");
+} else {
+  console.log("⏭️  No static files found\n");
+}
+
+// Step 5: Copy public folder if exists
+console.log("5️⃣  Copying public folder...");
+const publicSrc = path.join(appDir, "public");
+const publicDest = path.join(cliAppDir, "public");
+if (fs.existsSync(publicSrc)) {
+  copyRecursive(publicSrc, publicDest);
+  console.log("✅ Copied public folder\n");
+} else {
+  console.log("⏭️  No public folder found\n");
+}
+
+// Step 6: Copy vendor-chunks (required for production)
+console.log("6️⃣  Copying vendor-chunks...");
+const vendorChunksSrc = path.join(appDir, ".next", "server", "vendor-chunks");
+const vendorChunksSrcResolved = path.join(buildDistDir, "server", "vendor-chunks");
+const vendorChunksDest = path.join(cliAppDir, buildDistDirName, "server", "vendor-chunks");
+if (fs.existsSync(vendorChunksSrcResolved) || fs.existsSync(vendorChunksSrc)) {
+  copyRecursive(fs.existsSync(vendorChunksSrcResolved) ? vendorChunksSrcResolved : vendorChunksSrc, vendorChunksDest);
+  console.log("✅ Copied vendor-chunks\n");
+} else {
+  console.log("⏭️  No vendor-chunks found\n");
+}
+
+// Step 7: Copy MITM server files (not bundled by Next.js standalone)
+console.log("7️⃣  Copying MITM server files...");
+const mitmSrc = path.join(appDir, "src", "mitm");
+const mitmDest = path.join(cliAppDir, "src", "mitm");
+if (fs.existsSync(mitmSrc)) {
+  copyRecursive(mitmSrc, mitmDest);
+  console.log("✅ Copied MITM files\n");
+} else {
+  console.log("⏭️  No MITM files found\n");
+}
+
+// Step 7b: Copy standalone updater (headless Node process for install progress)
+console.log("7️⃣ b Copying updater files...");
+const updaterSrc = path.join(appDir, "src", "lib", "updater");
+const updaterDest = path.join(cliAppDir, "src", "lib", "updater");
+if (fs.existsSync(updaterSrc)) {
+  copyRecursive(updaterSrc, updaterDest);
+  console.log("✅ Copied updater files\n");
+} else {
+  console.log("⏭️  No updater files found\n");
+}
+
+// Step 8: Build MITM server (config driven - see app/cli/scripts/buildMitm.js)
+console.log("8️⃣  Building MITM server...");
+try {
+  execSync("node scripts/buildMitm.js", { stdio: "inherit", cwd: cliDir });
+  console.log("✅ MITM server build completed\n");
+} catch (error) {
+  console.error("❌ MITM build failed");
+  process.exit(1);
+}
+
+console.log("✨ CLI package build completed!");
+console.log(`📁 Output: ${cliAppDir}`);
+
+try {
+  const { execSync: exec } = require("child_process");
+  const size = exec(`du -sh "${cliAppDir}"`, { encoding: "utf8" }).trim();
+  console.log(`📊 Package size: ${size.split("\t")[0]}`);
+} catch (e) {
+  // Silent fail on size check
+}
diff --git a/cli/scripts/buildMitm.js b/cli/scripts/buildMitm.js
new file mode 100644
index 0000000..e47f593
--- /dev/null
+++ b/cli/scripts/buildMitm.js
@@ -0,0 +1,71 @@
+const esbuild = require("esbuild");
+const fs = require("fs");
+const path = require("path");
+
+// ── Build config ─────────────────────────────────────────
+const BUILD_CONFIG = {
+  bundle: true,
+  minify: true,
+  cleanPlainFiles: true,
+};
+// ─────────────────────────────────────────────────────────
+
+const cliDir = path.resolve(__dirname, "..");
+const appDir = path.resolve(cliDir, "..");
+const cliAppDir = process.env.NINEROUTER_CLI_APP_DIR || path.join(cliDir, "app");
+const cliMitmDir = path.join(cliAppDir, "src", "mitm");
+// Bundle everything — no externals. This keeps MITM runtime self-contained so
+// it can be copied to DATA_DIR/runtime/ and spawned from there (escapes
+// node_modules file locks that block `npm i -g 9router@latest` on Windows).
+const EXTERNALS = [];
+const ENTRIES = ["server.js"];
+
+async function buildEntry(entry) {
+  const mitmSrc = path.join(appDir, "src", "mitm");
+  const output = path.join(cliMitmDir, entry);
+
+  const buildPlugin = {
+    name: "build-plugin",
+    setup(build) {
+      // Stub .git file scanned by esbuild
+      build.onResolve({ filter: /\.git/ }, args => ({ path: args.path, namespace: "git-stub" }));
+      build.onLoad({ filter: /.*/, namespace: "git-stub" }, () => ({ contents: "module.exports={}", loader: "js" }));
+    },
+  };
+
+  const steps = [];
+
+  if (BUILD_CONFIG.bundle) {
+    await esbuild.build({
+      entryPoints: [path.join(mitmSrc, entry)],
+      bundle: true,
+      minify: BUILD_CONFIG.minify,
+      platform: "node",
+      target: "node18",
+      external: EXTERNALS,
+      plugins: [buildPlugin],
+      outfile: output,
+    });
+    steps.push("bundled");
+    if (BUILD_CONFIG.minify) steps.push("minified");
+  }
+
+  console.log(`✅ ${steps.join(" + ")} → ${output}`);
+}
+
+async function run() {
+  const flags = Object.entries(BUILD_CONFIG).filter(([, v]) => v).map(([k]) => k).join(", ");
+  console.log(`⚙️  Config: ${flags}`);
+
+  for (const entry of ENTRIES) await buildEntry(entry);
+
+  if (BUILD_CONFIG.cleanPlainFiles) {
+    const keep = new Set(ENTRIES);
+    for (const name of fs.readdirSync(cliMitmDir)) {
+      if (!keep.has(name)) fs.rmSync(path.join(cliMitmDir, name), { recursive: true, force: true });
+    }
+    console.log("✅ Removed plain MITM files from CLI bundle");
+  }
+}
+
+run().catch((e) => { console.error(e); process.exit(1); });
diff --git a/cli/src/cli/api/client.js b/cli/src/cli/api/client.js
new file mode 100644
index 0000000..257fcd2
--- /dev/null
+++ b/cli/src/cli/api/client.js
@@ -0,0 +1,556 @@
+const http = require("http");
+const https = require("https");
+const crypto = require("crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const { machineIdSync } = require("node-machine-id");
+
+// Default configuration
+const DEFAULT_CONFIG = {
+  host: "localhost",
+  port: 20128,
+  protocol: "http:",
+};
+
+const CLI_TOKEN_HEADER = "x-9r-cli-token";
+const CLI_TOKEN_SALT = "9r-cli-auth";
+const APP_NAME = "9router";
+
+function getDataDir() {
+  if (process.env.DATA_DIR) return process.env.DATA_DIR;
+  if (process.platform === "win32") {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), APP_NAME);
+  }
+  return path.join(os.homedir(), `.${APP_NAME}`);
+}
+
+const MACHINE_ID_FILE = path.join(getDataDir(), "machine-id");
+const AUTH_DIR = path.join(getDataDir(), "auth");
+const CLI_SECRET_FILE = path.join(AUTH_DIR, "cli-secret");
+
+let config = { ...DEFAULT_CONFIG };
+let cachedCliToken = null;
+let cachedCliSecret = null;
+
+// Read raw machineId from shared file (written by server) → guarantees token match
+function loadRawMachineId() {
+  try {
+    const raw = fs.readFileSync(MACHINE_ID_FILE, "utf8").trim();
+    if (raw) return raw;
+  } catch {}
+  try { return machineIdSync(); } catch { return ""; }
+}
+
+// Random secret shared with server via file → token unpredictable from machineId alone.
+function loadCliSecret() {
+  if (cachedCliSecret) return cachedCliSecret;
+  try {
+    cachedCliSecret = fs.readFileSync(CLI_SECRET_FILE, "utf8").trim();
+    if (cachedCliSecret) return cachedCliSecret;
+  } catch {}
+  cachedCliSecret = crypto.randomBytes(32).toString("hex");
+  try {
+    fs.mkdirSync(AUTH_DIR, { recursive: true });
+    fs.writeFileSync(CLI_SECRET_FILE, cachedCliSecret, { mode: 0o600 });
+  } catch {}
+  return cachedCliSecret;
+}
+
+function getCliToken() {
+  if (cachedCliToken !== null) return cachedCliToken;
+  const raw = loadRawMachineId();
+  const secret = loadCliSecret();
+  cachedCliToken = raw ? crypto.createHash("sha256").update(raw + CLI_TOKEN_SALT + secret).digest("hex").substring(0, 16) : "";
+  return cachedCliToken;
+}
+
+/**
+ * Configure API client
+ * @param {Object} options - Configuration options
+ * @param {string} options.host - API host
+ * @param {number} options.port - API port
+ * @param {string} options.protocol - Protocol (http: or https:)
+ */
+function configure(options = {}) {
+  config = { ...config, ...options };
+}
+
+/**
+ * Make HTTP request to API
+ * @param {string} method - HTTP method
+ * @param {string} path - API path
+ * @param {Object} body - Request body (optional)
+ * @returns {Promise<Object>} Response with { success, data/error }
+ */
+function makeRequest(method, path, body = null) {
+  return new Promise((resolve) => {
+    const httpModule = config.protocol === "https:" ? https : http;
+    
+    const options = {
+      hostname: config.host,
+      port: config.port,
+      path: path,
+      method: method,
+      headers: {
+        "Content-Type": "application/json",
+        [CLI_TOKEN_HEADER]: getCliToken(),
+      },
+    };
+
+    // Add Content-Length for POST/PUT requests
+    if (body && (method === "POST" || method === "PUT" || method === "PATCH")) {
+      const bodyString = JSON.stringify(body);
+      options.headers["Content-Length"] = Buffer.byteLength(bodyString);
+    }
+
+    const req = httpModule.request(options, (res) => {
+      let data = "";
+
+      res.on("data", (chunk) => {
+        data += chunk;
+      });
+
+      res.on("end", () => {
+        try {
+          const parsed = data ? JSON.parse(data) : {};
+          
+          // Check if response indicates error
+          if (res.statusCode >= 400 || parsed.error) {
+            resolve({
+              success: false,
+              error: parsed.error || `HTTP ${res.statusCode}`,
+              statusCode: res.statusCode,
+            });
+          } else {
+            resolve({
+              success: true,
+              data: parsed,
+              statusCode: res.statusCode,
+            });
+          }
+        } catch (err) {
+          resolve({
+            success: false,
+            error: `Failed to parse response: ${err.message}`,
+          });
+        }
+      });
+    });
+
+    req.on("error", (err) => {
+      resolve({
+        success: false,
+        error: `Network error: ${err.message}`,
+      });
+    });
+
+    req.on("timeout", () => {
+      req.destroy();
+      resolve({
+        success: false,
+        error: "Request timeout",
+      });
+    });
+
+    // Set timeout (30 seconds)
+    req.setTimeout(30000);
+
+    // Write body if present
+    if (body && (method === "POST" || method === "PUT" || method === "PATCH")) {
+      req.write(JSON.stringify(body));
+    }
+
+    req.end();
+  });
+}
+
+// ============================================================================
+// PROVIDERS API
+// ============================================================================
+
+/**
+ * Get all providers
+ * @returns {Promise<Object>} { success, data: { connections } }
+ */
+async function getProviders() {
+  return makeRequest("GET", "/api/providers");
+}
+
+/**
+ * Get provider by ID
+ * @param {string} id - Provider ID
+ * @returns {Promise<Object>} { success, data: { connection } }
+ */
+async function getProviderById(id) {
+  return makeRequest("GET", `/api/providers/${id}`);
+}
+
+/**
+ * Test provider connection
+ * @param {string} id - Provider ID
+ * @returns {Promise<Object>} { success, data: { valid, error } }
+ */
+async function testProvider(id) {
+  return makeRequest("POST", `/api/providers/${id}/test`);
+}
+
+/**
+ * Delete provider
+ * @param {string} id - Provider ID
+ * @returns {Promise<Object>} { success, data: { message } }
+ */
+async function deleteProvider(id) {
+  return makeRequest("DELETE", `/api/providers/${id}`);
+}
+
+/**
+ * Get provider models
+ * @param {string} id - Provider ID
+ * @returns {Promise<Object>} { success, data: { provider, connectionId, models } }
+ */
+async function getProviderModels(id) {
+  return makeRequest("GET", `/api/providers/${id}/models`);
+}
+
+// ============================================================================
+// OAUTH API
+// ============================================================================
+
+/**
+ * Get OAuth authorization URL
+ * @param {string} provider - Provider ID
+ * @returns {Promise<Object>} { success, data: { authUrl, codeVerifier, state, redirectUri } }
+ */
+async function getOAuthAuthUrl(provider) {
+  // Codex requires fixed port 1455 and path /auth/callback
+  const redirectUri = provider === "codex" 
+    ? "http://localhost:1455/auth/callback"
+    : "http://localhost:20128/callback";
+  return makeRequest("GET", `/api/oauth/${provider}/authorize?redirect_uri=${encodeURIComponent(redirectUri)}`);
+}
+
+/**
+ * Exchange OAuth authorization code for token
+ * @param {string} provider - Provider ID
+ * @param {Object} data - { code, redirectUri, codeVerifier, state }
+ * @returns {Promise<Object>} { success, data }
+ */
+async function exchangeOAuthCode(provider, data) {
+  return makeRequest("POST", `/api/oauth/${provider}/exchange`, data);
+}
+
+/**
+ * Get OAuth device code
+ * @param {string} provider - Provider ID
+ * @returns {Promise<Object>} { success, data: { device_code, user_code, verification_uri, verification_uri_complete, codeVerifier, extraData } }
+ */
+async function getOAuthDeviceCode(provider) {
+  return makeRequest("GET", `/api/oauth/${provider}/device-code`);
+}
+
+/**
+ * Poll OAuth token using device code
+ * @param {string} provider - Provider ID
+ * @param {Object} data - { deviceCode, codeVerifier, extraData }
+ * @returns {Promise<Object>} { success, data: { pending } }
+ */
+async function pollOAuthToken(provider, data) {
+  return makeRequest("POST", `/api/oauth/${provider}/poll`, data);
+}
+
+/**
+ * Create API key provider connection
+ * @param {Object} data - { provider, name, apiKey }
+ * @returns {Promise<Object>} { success, data }
+ */
+async function createApiKeyProvider(data) {
+  return makeRequest("POST", "/api/providers", data);
+}
+
+/**
+ * Update provider connection
+ * @param {string} id - Connection ID
+ * @param {Object} data - { name, priority, defaultModel, isActive }
+ * @returns {Promise<Object>} { success, data: { connection } }
+ */
+async function updateConnection(id, data) {
+  return makeRequest("PUT", `/api/providers/${id}`, data);
+}
+
+// ============================================================================
+// API KEYS API
+// ============================================================================
+
+/**
+ * Get all API keys
+ * @returns {Promise<Object>} { success, data: { keys } }
+ */
+async function getApiKeys() {
+  return makeRequest("GET", "/api/keys");
+}
+
+/**
+ * Create new API key
+ * @param {string} name - Key name
+ * @returns {Promise<Object>} { success, data: { key, name, id, machineId } }
+ */
+async function createApiKey(name) {
+  return makeRequest("POST", "/api/keys", { name });
+}
+
+/**
+ * Delete API key
+ * @param {string} id - Key ID
+ * @returns {Promise<Object>} { success, data: { success } }
+ */
+async function deleteApiKey(id) {
+  return makeRequest("DELETE", `/api/keys/${id}`);
+}
+
+// ============================================================================
+// COMBOS API
+// ============================================================================
+
+/**
+ * Get all combos
+ * @returns {Promise<Object>} { success, data: { combos } }
+ */
+async function getCombos() {
+  return makeRequest("GET", "/api/combos");
+}
+
+/**
+ * Get combo by ID
+ * @param {string} id - Combo ID
+ * @returns {Promise<Object>} { success, data: combo }
+ */
+async function getComboById(id) {
+  return makeRequest("GET", `/api/combos/${id}`);
+}
+
+/**
+ * Create new combo
+ * @param {Object} data - Combo data { name, models }
+ * @returns {Promise<Object>} { success, data: combo }
+ */
+async function createCombo(data) {
+  return makeRequest("POST", "/api/combos", data);
+}
+
+/**
+ * Update combo
+ * @param {string} id - Combo ID
+ * @param {Object} data - Update data { name?, models? }
+ * @returns {Promise<Object>} { success, data: combo }
+ */
+async function updateCombo(id, data) {
+  return makeRequest("PUT", `/api/combos/${id}`, data);
+}
+
+/**
+ * Delete combo
+ * @param {string} id - Combo ID
+ * @returns {Promise<Object>} { success, data: { success } }
+ */
+async function deleteCombo(id) {
+  return makeRequest("DELETE", `/api/combos/${id}`);
+}
+
+// ============================================================================
+// CLI TOOLS API
+// ============================================================================
+
+/**
+ * Get CLI tool settings
+ * @param {string} tool - Tool name: claude | codex | droid | openclaw
+ * @returns {Promise<Object>} { success, data: { installed, has9Router, ... } }
+ */
+async function getCliToolSettings(tool) {
+  return makeRequest("GET", `/api/cli-tools/${tool}-settings`);
+}
+
+/**
+ * Apply CLI tool settings (POST)
+ * @param {string} tool - Tool name: claude | codex | droid | openclaw
+ * @param {Object} body - Payload depends on tool
+ * @returns {Promise<Object>} { success, data }
+ */
+async function applyCliToolSettings(tool, body) {
+  return makeRequest("POST", `/api/cli-tools/${tool}-settings`, body);
+}
+
+/**
+ * Reset CLI tool settings (DELETE)
+ * @param {string} tool - Tool name: claude | codex | droid | openclaw
+ * @returns {Promise<Object>} { success, data }
+ */
+async function resetCliToolSettings(tool) {
+  return makeRequest("DELETE", `/api/cli-tools/${tool}-settings`);
+}
+
+// ============================================================================
+// SETTINGS API
+// ============================================================================
+
+/**
+ * Get settings
+ * @returns {Promise<Object>} { success, data: settings }
+ */
+async function getSettings() {
+  return makeRequest("GET", "/api/settings");
+}
+
+/**
+ * Update settings
+ * @param {Object} data - Settings data
+ * @returns {Promise<Object>} { success, data: settings }
+ */
+async function updateSettings(data) {
+  return makeRequest("PATCH", "/api/settings", data);
+}
+
+/**
+ * Reset dashboard password to default (clears stored hash server-side)
+ * @returns {Promise<Object>} { success }
+ */
+async function resetPassword() {
+  return makeRequest("POST", "/api/auth/reset-password");
+}
+
+// ============================================================================
+// MODELS API
+// ============================================================================
+
+/**
+ * Get all models (internal API)
+ * @returns {Promise<Object>} { success, data: { models } }
+ */
+async function getModels() {
+  return makeRequest("GET", "/api/models");
+}
+
+/**
+ * Get available models from active providers + combos (OpenAI compatible)
+ * @returns {Promise<Object>} { success, data: { object, data: [...models] } }
+ */
+async function getAvailableModels() {
+  return makeRequest("GET", "/v1/models");
+}
+
+// ============================================================================
+// PROVIDER NODES API (custom providers)
+// ============================================================================
+
+async function getProviderNodes() {
+  return makeRequest("GET", "/api/provider-nodes");
+}
+
+async function createProviderNode(data) {
+  return makeRequest("POST", "/api/provider-nodes", data);
+}
+
+async function updateProviderNode(id, data) {
+  return makeRequest("PUT", `/api/provider-nodes/${id}`, data);
+}
+
+async function deleteProviderNode(id) {
+  return makeRequest("DELETE", `/api/provider-nodes/${id}`);
+}
+
+async function validateProviderNode(data) {
+  return makeRequest("POST", "/api/provider-nodes/validate", data);
+}
+
+// ============================================================================
+// TUNNEL API
+// ============================================================================
+
+/**
+ * Get tunnel status
+ * @returns {Promise<Object>} { success, data: { enabled, tunnelUrl, shortId, running } }
+ */
+async function getTunnelStatus() {
+  return makeRequest("GET", "/api/tunnel/status");
+}
+
+/**
+ * Enable tunnel
+ * @returns {Promise<Object>} { success, data: { tunnelUrl, shortId } }
+ */
+async function enableTunnel() {
+  return makeRequest("POST", "/api/tunnel/enable");
+}
+
+/**
+ * Disable tunnel
+ * @returns {Promise<Object>} { success, data: { success } }
+ */
+async function disableTunnel() {
+  return makeRequest("POST", "/api/tunnel/disable");
+}
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+module.exports = {
+  configure,
+  
+  // Providers
+  getProviders,
+  getProviderById,
+  testProvider,
+  deleteProvider,
+  getProviderModels,
+  
+  // Connection aliases
+  testConnection: testProvider,
+  deleteConnection: deleteProvider,
+  updateConnection,
+  
+  // OAuth
+  getOAuthAuthUrl,
+  exchangeOAuthCode,
+  getOAuthDeviceCode,
+  pollOAuthToken,
+  createApiKeyProvider,
+  
+  // API Keys
+  getApiKeys,
+  createApiKey,
+  deleteApiKey,
+  
+  // Combos
+  getCombos,
+  getComboById,
+  createCombo,
+  updateCombo,
+  deleteCombo,
+  
+  // CLI Tools
+  getCliToolSettings,
+  applyCliToolSettings,
+  resetCliToolSettings,
+
+  // Settings
+  getSettings,
+  updateSettings,
+  resetPassword,
+  
+  // Tunnel
+  getTunnelStatus,
+  enableTunnel,
+  disableTunnel,
+  
+  // Models
+  getModels,
+  getAvailableModels,
+
+  // Provider Nodes (custom providers)
+  getProviderNodes,
+  createProviderNode,
+  updateProviderNode,
+  deleteProviderNode,
+  validateProviderNode,
+};
diff --git a/cli/src/cli/menus/apiKeys.js b/cli/src/cli/menus/apiKeys.js
new file mode 100644
index 0000000..ecd4e68
--- /dev/null
+++ b/cli/src/cli/menus/apiKeys.js
@@ -0,0 +1,233 @@
+const api = require("../api/client");
+const { prompt, confirm, pause } = require("../utils/input");
+const { clearScreen, showStatus, showHeader } = require("../utils/display");
+const { maskKey, formatDate, getRelativeTime } = require("../utils/format");
+const { showMenuWithBack } = require("../utils/menuHelper");
+const { copyToClipboard } = require("../utils/clipboard");
+const { getEndpoint } = require("../utils/endpoint");
+
+/**
+ * Display API keys list with formatted output
+ * @param {Array} keys - Array of API key objects
+ * @param {number} port - Server port
+ */
+function displayApiKeys(keys, port) {
+  console.log("┌─────────────────────────────────────────────────────────┐");
+  console.log("│  🔑 API Keys Management                                 │");
+  console.log("├─────────────────────────────────────────────────────────┤");
+  // Note: This function is legacy, endpoint shown in menu header instead
+  console.log("│                                                          │");
+  
+  if (keys.length === 0) {
+    console.log("│  No API keys found.                                     │");
+  } else {
+    console.log(`│  Your API Keys (${keys.length}):${" ".repeat(42 - String(keys.length).length)}│`);
+    
+    keys.forEach((key, index) => {
+      console.log("│                                                          │");
+      console.log(`│  ${index + 1}. ${key.name}${" ".repeat(52 - String(index + 1).length - key.name.length)}│`);
+      
+      const maskedKey = maskKey(key.key);
+      console.log(`│     Key: ${maskedKey}${" ".repeat(47 - maskedKey.length)}│`);
+      
+      const created = formatDate(key.createdAt);
+      console.log(`│     Created: ${created}${" ".repeat(43 - created.length)}│`);
+      
+      if (key.lastUsedAt) {
+        const lastUsed = getRelativeTime(key.lastUsedAt);
+        console.log(`│     Last used: ${lastUsed}${" ".repeat(41 - lastUsed.length)}│`);
+      } else {
+        console.log("│     Last used: Never                                    │");
+      }
+    });
+  }
+  
+  console.log("│                                                          │");
+  console.log("│  Actions:                                               │");
+  console.log("│  1. Create New API Key                                  │");
+  console.log("│  2. View Full Key (by number)                           │");
+  console.log("│  3. Copy Key to Clipboard (by number)                   │");
+  console.log("│  4. Delete Key (by number)                              │");
+  console.log("│  0. ← Back to Main Menu                                 │");
+  console.log("└─────────────────────────────────────────────────────────┘");
+}
+
+/**
+ * Handle creating new API key
+ * @returns {Promise<boolean>} Success status
+ */
+async function handleCreateKey() {
+  console.log("\n📝 Create New API Key");
+  console.log("─".repeat(30));
+  
+  const name = await prompt("Enter key name: ");
+  
+  if (!name) {
+    showStatus("Key name cannot be empty", "error");
+    await pause();
+    return false;
+  }
+  
+  const result = await api.createApiKey(name);
+  
+  if (!result.success) {
+    showStatus(`Failed to create key: ${result.error}`, "error");
+    await pause();
+    return false;
+  }
+  
+  console.log("\n✅ API Key created successfully!");
+  console.log("\n⚠️  IMPORTANT: Save this key now. You won't be able to see it again!");
+  console.log(`\nKey: ${result.data.key}`);
+  console.log(`Name: ${result.data.name}`);
+  console.log(`ID: ${result.data.id}`);
+  
+  const shouldCopy = await confirm("\nCopy key to clipboard?");
+  if (shouldCopy) {
+    if (copyToClipboard(result.data.key)) {
+      showStatus("Key copied to clipboard!", "success");
+    } else {
+      showStatus("Failed to copy to clipboard", "error");
+    }
+  }
+  
+  await pause();
+  return true;
+}
+
+/**
+ * Handle viewing full API key
+ * @param {Object} key - API key object
+ */
+async function handleViewFullKey(key) {
+  console.log("\n🔍 Full API Key");
+  console.log("─".repeat(30));
+  console.log(`Name: ${key.name}`);
+  console.log(`Key: ${key.key}`);
+  console.log(`ID: ${key.id}`);
+  console.log(`Created: ${formatDate(key.createdAt)}`);
+  
+  if (key.lastUsedAt) {
+    console.log(`Last used: ${getRelativeTime(key.lastUsedAt)}`);
+  } else {
+    console.log("Last used: Never");
+  }
+  
+  await pause();
+}
+
+/**
+ * Handle copying API key to clipboard
+ * @param {Object} key - API key object
+ */
+async function handleCopyKey(key) {
+  if (copyToClipboard(key.key)) {
+    showStatus(`Key "${key.name}" copied to clipboard!`, "success");
+  } else {
+    showStatus("Failed to copy to clipboard", "error");
+  }
+  await pause();
+}
+
+/**
+ * Handle deleting API key
+ * @param {Object} key - API key object
+ * @returns {Promise<boolean>} Success status
+ */
+async function handleDeleteKey(key) {
+  console.log(`\n⚠️  Delete API Key: ${key.name}`);
+  console.log("─".repeat(30));
+  console.log(`Key: ${maskKey(key.key)}`);
+  console.log(`Created: ${formatDate(key.createdAt)}`);
+  
+  const confirmed = await confirm("\nAre you sure you want to delete this key?");
+  
+  if (!confirmed) {
+    showStatus("Deletion cancelled", "info");
+    await pause();
+    return false;
+  }
+  
+  const result = await api.deleteApiKey(key.id);
+  
+  if (!result.success) {
+    showStatus(`Failed to delete key: ${result.error}`, "error");
+    await pause();
+    return false;
+  }
+  
+  showStatus("API key deleted successfully", "success");
+  await pause();
+  return true;
+}
+
+/**
+ * Show actions for a specific key
+ * @param {Object} key - API key object
+ * @param {number} port - Server port
+ * @param {Array<string>} breadcrumb - Breadcrumb path
+ */
+async function showKeyActions(key, port, breadcrumb = []) {
+  const { endpoint } = await getEndpoint(port);
+  await showMenuWithBack({
+    title: `🔑 ${key.name}`,
+    breadcrumb: [...breadcrumb, key.name],
+    headerContent: `Name: ${key.name}\nKey: ${key.key}\nEndpoint: ${endpoint}`,
+    items: [
+      {
+        label: "Copy to Clipboard",
+        action: async () => {
+          await handleCopyKey(key);
+          return true;
+        }
+      },
+      {
+        label: "Delete Key",
+        action: async () => {
+          await handleDeleteKey(key);
+          return false; // Exit after delete
+        }
+      }
+    ]
+  });
+}
+
+/**
+ * Main API Keys menu
+ * @param {number} port - Server port number
+ * @param {Array<string>} breadcrumb - Breadcrumb path
+ */
+async function showApiKeysMenu(port, breadcrumb = []) {
+  const { showListMenu } = require("../utils/menuHelper");
+  
+  const { endpoint } = await getEndpoint(port);
+  await showListMenu({
+    title: "🔑 API Keys Management",
+    breadcrumb,
+    headerContent: `Endpoint: ${endpoint}`,
+    fetchItems: async () => {
+      const result = await api.getApiKeys();
+      if (!result.success) {
+        clearScreen();
+        showStatus(`Failed to fetch API keys: ${result.error}`, "error");
+        await pause();
+        return null;
+      }
+      return { items: result.data.keys || [] };
+    },
+    formatItem: (key) => `${key.name} (${maskKey(key.key)})`,
+    onSelect: async (key) => {
+      await showKeyActions(key, port, breadcrumb);
+    },
+    createAction: {
+      label: "Create New API Key",
+      action: async () => {
+        await handleCreateKey();
+      }
+    }
+  });
+}
+
+module.exports = {
+  showApiKeysMenu
+};
diff --git a/cli/src/cli/menus/cliTools.js b/cli/src/cli/menus/cliTools.js
new file mode 100644
index 0000000..3a84a07
--- /dev/null
+++ b/cli/src/cli/menus/cliTools.js
@@ -0,0 +1,618 @@
+const api = require("../api/client");
+const { pause, confirm } = require("../utils/input");
+const { showStatus } = require("../utils/display");
+const { selectModelFromList } = require("../utils/modelSelector");
+const { showMenuWithBack } = require("../utils/menuHelper");
+const { getEndpoint } = require("../utils/endpoint");
+
+const COLORS = {
+  reset: "\x1b[0m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m"
+};
+
+// Claude model types with defaults (matching Web UI)
+const CLAUDE_MODEL_TYPES = [
+  { id: "sonnet", name: "Sonnet", envKey: "ANTHROPIC_DEFAULT_SONNET_MODEL", defaultValue: "cc/claude-sonnet-4-5-20250929" },
+  { id: "opus",   name: "Opus",   envKey: "ANTHROPIC_DEFAULT_OPUS_MODEL",   defaultValue: "cc/claude-opus-4-5-20251101" },
+  { id: "haiku",  name: "Haiku",  envKey: "ANTHROPIC_DEFAULT_HAIKU_MODEL",  defaultValue: "cc/claude-haiku-4-5-20251001" },
+];
+
+// ─── Shared helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Get first available API key from server
+ * @returns {Promise<string|null>}
+ */
+async function getFirstApiKey() {
+  const result = await api.getApiKeys();
+  const keys = result.success ? (result.data.keys || []) : [];
+  return keys.length > 0 ? keys[0].key : null;
+}
+
+// ─── Claude Code ──────────────────────────────────────────────────────────────
+
+/**
+ * Build header showing current Claude config status
+ * @returns {Promise<string>}
+ */
+async function buildClaudeHeader() {
+  const result = await api.getCliToolSettings("claude");
+  if (!result.success) return `  ${COLORS.red}Failed to load settings${COLORS.reset}`;
+
+  const settings = result.data.settings;
+  const currentUrl = settings?.env?.ANTHROPIC_BASE_URL;
+  const currentKey = settings?.env?.ANTHROPIC_AUTH_TOKEN;
+  const lines = [];
+
+  if (currentUrl) {
+    lines.push(`Status:   ${COLORS.green}✓ Configured${COLORS.reset}`);
+    lines.push(`Endpoint: ${COLORS.cyan}${currentUrl}${COLORS.reset}`);
+    if (currentKey) {
+      lines.push(`API Key:  ${COLORS.dim}${currentKey.substring(0, 10)}...${COLORS.reset}`);
+    }
+  } else {
+    lines.push(`Status:   ${COLORS.red}✗ Not configured${COLORS.reset}`);
+    lines.push(`${COLORS.dim}Run "Quick Setup" to configure${COLORS.reset}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Get current Claude model from settings
+ * @param {string} envKey
+ * @returns {Promise<string>}
+ */
+async function getClaudeModel(envKey) {
+  const result = await api.getCliToolSettings("claude");
+  return result.success ? (result.data.settings?.env?.[envKey] || "Not set") : "Not set";
+}
+
+/**
+ * Quick setup for Claude Code — sets endpoint, key, and all default models
+ * @param {number} port
+ */
+async function claudeQuickSetup(port) {
+  const { endpoint } = await getEndpoint(port);
+  const apiKey = await getFirstApiKey();
+
+  if (!apiKey) {
+    showStatus("No API keys found. Create one in API Keys menu first.", "error");
+    await pause();
+    return;
+  }
+
+  const env = { ANTHROPIC_BASE_URL: endpoint, ANTHROPIC_AUTH_TOKEN: apiKey, API_TIMEOUT_MS: "600000" };
+  CLAUDE_MODEL_TYPES.forEach(t => { env[t.envKey] = t.defaultValue; });
+
+  const result = await api.applyCliToolSettings("claude", { env });
+  showStatus(result.success ? "Quick Setup completed!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Select and save a specific Claude model type
+ * @param {Object} modelType
+ * @param {number} port
+ */
+async function claudeSelectModel(modelType, port) {
+  const current = await getClaudeModel(modelType.envKey);
+  const selected = await selectModelFromList(`Select ${modelType.name} Model`, current, { excludeCombos: true });
+  if (!selected) return;
+
+  const env = { [modelType.envKey]: selected };
+
+  // Also set base URL if not configured yet
+  const settingsResult = await api.getCliToolSettings("claude");
+  if (!settingsResult.data?.settings?.env?.ANTHROPIC_BASE_URL) {
+    const { endpoint } = await getEndpoint(port);
+    const apiKey = await getFirstApiKey();
+    env.ANTHROPIC_BASE_URL = endpoint;
+    env.API_TIMEOUT_MS = "600000";
+    if (apiKey) env.ANTHROPIC_AUTH_TOKEN = apiKey;
+  }
+
+  const result = await api.applyCliToolSettings("claude", { env });
+  showStatus(result.success ? `${modelType.name} → ${selected} saved!` : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Reset Claude Code settings
+ */
+async function claudeReset() {
+  const result = await api.resetCliToolSettings("claude");
+  showStatus(result.success ? "Settings reset successfully!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Claude Code submenu
+ * @param {number} port
+ * @param {Array<string>} breadcrumb
+ */
+async function showClaudeCodeMenu(port, breadcrumb = []) {
+  await showMenuWithBack({
+    title: "🔧 Claude Code Settings",
+    breadcrumb,
+    headerContent: buildClaudeHeader,
+    refresh: async () => ({
+      sonnet: await getClaudeModel("ANTHROPIC_DEFAULT_SONNET_MODEL"),
+      opus:   await getClaudeModel("ANTHROPIC_DEFAULT_OPUS_MODEL"),
+      haiku:  await getClaudeModel("ANTHROPIC_DEFAULT_HAIKU_MODEL"),
+    }),
+    items: [
+      {
+        label: "⚡ Quick Setup (recommended)",
+        action: async () => { await claudeQuickSetup(port); return true; }
+      },
+      {
+        label: (d) => `Sonnet → ${d.sonnet}`,
+        action: async () => { await claudeSelectModel(CLAUDE_MODEL_TYPES[0], port); return true; }
+      },
+      {
+        label: (d) => `Opus → ${d.opus}`,
+        action: async () => { await claudeSelectModel(CLAUDE_MODEL_TYPES[1], port); return true; }
+      },
+      {
+        label: (d) => `Haiku → ${d.haiku}`,
+        action: async () => { await claudeSelectModel(CLAUDE_MODEL_TYPES[2], port); return true; }
+      },
+      {
+        label: "Reset to Default",
+        action: async () => { await claudeReset(); return true; }
+      }
+    ]
+  });
+}
+
+// ─── Codex CLI ────────────────────────────────────────────────────────────────
+
+/**
+ * Build header showing current Codex config status
+ * @returns {Promise<string>}
+ */
+async function buildCodexHeader() {
+  const result = await api.getCliToolSettings("codex");
+  if (!result.success) return `  ${COLORS.red}Failed to load settings${COLORS.reset}`;
+
+  const { installed, has9Router, config } = result.data;
+  if (!installed) return `Status:   ${COLORS.red}✗ Codex CLI not installed${COLORS.reset}`;
+
+  if (!has9Router) {
+    return [
+      `Status:   ${COLORS.red}✗ Not configured${COLORS.reset}`,
+      `${COLORS.dim}Run "Quick Setup" to configure${COLORS.reset}`
+    ].join("\n");
+  }
+
+  // Parse base_url and model from raw TOML string
+  const baseUrlMatch = config && config.match(/base_url\s*=\s*"([^"]+)"/);
+  const modelMatch = config && config.match(/^model\s*=\s*"([^"]+)"/m);
+  const baseUrl = baseUrlMatch ? baseUrlMatch[1] : "";
+  const model = modelMatch ? modelMatch[1] : "";
+
+  const lines = [`Status:   ${COLORS.green}✓ Configured${COLORS.reset}`];
+  if (baseUrl) lines.push(`Endpoint: ${COLORS.cyan}${baseUrl}${COLORS.reset}`);
+  if (model)   lines.push(`Model:    ${COLORS.dim}${model}${COLORS.reset}`);
+  return lines.join("\n");
+}
+
+/**
+ * Quick setup for Codex CLI
+ * @param {number} port
+ */
+async function codexQuickSetup(port) {
+  const { endpoint } = await getEndpoint(port);
+  const apiKey = await getFirstApiKey();
+
+  if (!apiKey) {
+    showStatus("No API keys found. Create one in API Keys menu first.", "error");
+    await pause();
+    return;
+  }
+
+  // Get model selection
+  const model = await selectModelFromList("Select Codex Model", "cx/claude-sonnet-4-5-20250929", { excludeCombos: true });
+  if (!model) return;
+
+  const result = await api.applyCliToolSettings("codex", { baseUrl: endpoint, apiKey, model });
+  showStatus(result.success ? "Codex setup completed!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Reset Codex CLI settings
+ */
+async function codexReset() {
+  const result = await api.resetCliToolSettings("codex");
+  showStatus(result.success ? "Codex settings reset!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Codex CLI submenu
+ * @param {number} port
+ * @param {Array<string>} breadcrumb
+ */
+async function showCodexMenu(port, breadcrumb = []) {
+  await showMenuWithBack({
+    title: "🤖 Codex CLI Settings",
+    breadcrumb,
+    headerContent: buildCodexHeader,
+    refresh: async () => ({}),
+    items: [
+      {
+        label: "⚡ Quick Setup",
+        action: async () => { await codexQuickSetup(port); return true; }
+      },
+      {
+        label: "Reset to Default",
+        action: async () => { await codexReset(); return true; }
+      }
+    ]
+  });
+}
+
+// ─── Factory Droid ────────────────────────────────────────────────────────────
+
+/**
+ * Build header showing current Droid config status
+ * @returns {Promise<string>}
+ */
+async function buildDroidHeader() {
+  const result = await api.getCliToolSettings("droid");
+  if (!result.success) return `  ${COLORS.red}Failed to load settings${COLORS.reset}`;
+
+  const { installed, has9Router, settings } = result.data;
+  if (!installed) return `Status:   ${COLORS.red}✗ Factory Droid not installed${COLORS.reset}`;
+
+  if (!has9Router) {
+    return [
+      `Status:   ${COLORS.red}✗ Not configured${COLORS.reset}`,
+      `${COLORS.dim}Run "Quick Setup" to configure${COLORS.reset}`
+    ].join("\n");
+  }
+
+  // Extract 9Router custom model config
+  const custom = settings?.customModels?.find(m => m.id === "custom:9Router-0");
+  const lines = [`Status:   ${COLORS.green}✓ Configured${COLORS.reset}`];
+  if (custom?.baseUrl) lines.push(`Endpoint: ${COLORS.cyan}${custom.baseUrl}${COLORS.reset}`);
+  if (custom?.model)   lines.push(`Model:    ${COLORS.dim}${custom.model}${COLORS.reset}`);
+  return lines.join("\n");
+}
+
+/**
+ * Quick setup for Factory Droid
+ * @param {number} port
+ */
+async function droidQuickSetup(port) {
+  const { endpoint } = await getEndpoint(port);
+  const apiKey = await getFirstApiKey();
+
+  if (!apiKey) {
+    showStatus("No API keys found. Create one in API Keys menu first.", "error");
+    await pause();
+    return;
+  }
+
+  const model = await selectModelFromList("Select Droid Model", "cc/claude-sonnet-4-5-20250929", { excludeCombos: true });
+  if (!model) return;
+
+  const result = await api.applyCliToolSettings("droid", { baseUrl: endpoint, apiKey, model });
+  showStatus(result.success ? "Factory Droid setup completed!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Reset Factory Droid settings
+ */
+async function droidReset() {
+  const result = await api.resetCliToolSettings("droid");
+  showStatus(result.success ? "Factory Droid settings reset!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Factory Droid submenu
+ * @param {number} port
+ * @param {Array<string>} breadcrumb
+ */
+async function showDroidMenu(port, breadcrumb = []) {
+  await showMenuWithBack({
+    title: "🤖 Factory Droid Settings",
+    breadcrumb,
+    headerContent: buildDroidHeader,
+    refresh: async () => ({}),
+    items: [
+      {
+        label: "⚡ Quick Setup",
+        action: async () => { await droidQuickSetup(port); return true; }
+      },
+      {
+        label: "Reset to Default",
+        action: async () => { await droidReset(); return true; }
+      }
+    ]
+  });
+}
+
+// ─── Open Claw ────────────────────────────────────────────────────────────────
+
+/**
+ * Build header showing current OpenClaw config status
+ * @returns {Promise<string>}
+ */
+async function buildOpenClawHeader() {
+  const result = await api.getCliToolSettings("openclaw");
+  if (!result.success) return `  ${COLORS.red}Failed to load settings${COLORS.reset}`;
+
+  const { installed, has9Router, settings } = result.data;
+  if (!installed) return `Status:   ${COLORS.red}✗ Open Claw not installed${COLORS.reset}`;
+
+  if (!has9Router) {
+    return [
+      `Status:   ${COLORS.red}✗ Not configured${COLORS.reset}`,
+      `${COLORS.dim}Run "Quick Setup" to configure${COLORS.reset}`
+    ].join("\n");
+  }
+
+  // Extract 9Router provider config
+  const provider = settings?.models?.providers?.["9router"];
+  const primary = settings?.agents?.defaults?.model?.primary || "";
+  const model = primary.startsWith("9router/") ? primary.replace("9router/", "") : (provider?.models?.[0]?.id || "");
+  const lines = [`Status:   ${COLORS.green}✓ Configured${COLORS.reset}`];
+  if (provider?.baseUrl) lines.push(`Endpoint: ${COLORS.cyan}${provider.baseUrl}${COLORS.reset}`);
+  if (model)             lines.push(`Model:    ${COLORS.dim}${model}${COLORS.reset}`);
+  return lines.join("\n");
+}
+
+/**
+ * Quick setup for Open Claw
+ * @param {number} port
+ */
+async function openClawQuickSetup(port) {
+  const { endpoint } = await getEndpoint(port);
+  const apiKey = await getFirstApiKey();
+
+  if (!apiKey) {
+    showStatus("No API keys found. Create one in API Keys menu first.", "error");
+    await pause();
+    return;
+  }
+
+  const model = await selectModelFromList("Select OpenClaw Model", "cc/claude-sonnet-4-5-20250929", { excludeCombos: true });
+  if (!model) return;
+
+  const result = await api.applyCliToolSettings("openclaw", { baseUrl: endpoint, apiKey, model });
+  showStatus(result.success ? "Open Claw setup completed!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Reset Open Claw settings
+ */
+async function openClawReset() {
+  const result = await api.resetCliToolSettings("openclaw");
+  showStatus(result.success ? "Open Claw settings reset!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Open Claw submenu
+ * @param {number} port
+ * @param {Array<string>} breadcrumb
+ */
+async function showOpenClawMenu(port, breadcrumb = []) {
+  await showMenuWithBack({
+    title: "🦞 Open Claw Settings",
+    breadcrumb,
+    headerContent: buildOpenClawHeader,
+    refresh: async () => ({}),
+    items: [
+      {
+        label: "⚡ Quick Setup",
+        action: async () => { await openClawQuickSetup(port); return true; }
+      },
+      {
+        label: "Reset to Default",
+        action: async () => { await openClawReset(); return true; }
+      }
+    ]
+  });
+}
+
+// ─── OpenCode CLI ─────────────────────────────────────────────────────────────
+
+async function buildOpenCodeHeader() {
+  const result = await api.getCliToolSettings("opencode");
+  if (!result.success) return `  ${COLORS.red}Failed to load settings${COLORS.reset}`;
+
+  const { installed, has9Router, opencode } = result.data;
+  if (!installed) return `Status:   ${COLORS.red}✗ OpenCode CLI not installed${COLORS.reset}`;
+
+  if (!has9Router) {
+    return [
+      `Status:   ${COLORS.red}✗ Not configured${COLORS.reset}`,
+      `${COLORS.dim}Run "Quick Setup" to configure${COLORS.reset}`
+    ].join("\n");
+  }
+
+  const lines = [`Status:   ${COLORS.green}✓ Configured${COLORS.reset}`];
+  if (opencode?.baseURL) lines.push(`Endpoint: ${COLORS.cyan}${opencode.baseURL}${COLORS.reset}`);
+  if (opencode?.activeModel) lines.push(`Active:   ${COLORS.dim}${opencode.activeModel}${COLORS.reset}`);
+  if (Array.isArray(opencode?.models) && opencode.models.length > 0) {
+    lines.push(`Models:   ${COLORS.dim}${opencode.models.join(", ")}${COLORS.reset}`);
+  }
+  return lines.join("\n");
+}
+
+async function openCodeQuickSetup(port) {
+  const { endpoint } = await getEndpoint(port);
+  const apiKey = await getFirstApiKey();
+
+  if (!apiKey) {
+    showStatus("No API keys found. Create one in API Keys menu first.", "error");
+    await pause();
+    return;
+  }
+
+  // Pick first model (also becomes active model by default)
+  const firstModel = await selectModelFromList("Select Active Model (OpenCode)", "", { excludeCombos: true });
+  if (!firstModel) return;
+
+  const models = [firstModel];
+
+  // Optionally add more models
+  while (true) {
+    const more = await confirm(`Add another model? (current: ${models.length})`);
+    if (!more) break;
+    const next = await selectModelFromList(`Add Model #${models.length + 1}`, models.join(", "), { excludeCombos: true });
+    if (!next) break;
+    if (!models.includes(next)) models.push(next);
+  }
+
+  // Optional subagent model
+  let subagentModel = firstModel;
+  const wantSubagent = await confirm(`Set a different subagent model? (default: ${firstModel})`);
+  if (wantSubagent) {
+    const picked = await selectModelFromList("Select Subagent Model", firstModel, { excludeCombos: true });
+    if (picked) subagentModel = picked;
+  }
+
+  const result = await api.applyCliToolSettings("opencode", {
+    baseUrl: endpoint,
+    apiKey,
+    models,
+    activeModel: firstModel,
+    subagentModel,
+  });
+  showStatus(result.success ? "OpenCode setup completed!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+async function openCodeReset() {
+  const result = await api.resetCliToolSettings("opencode");
+  showStatus(result.success ? "OpenCode settings reset!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+async function showOpenCodeMenu(port, breadcrumb = []) {
+  await showMenuWithBack({
+    title: "💻 OpenCode CLI Settings",
+    breadcrumb,
+    headerContent: buildOpenCodeHeader,
+    refresh: async () => ({}),
+    items: [
+      { label: "⚡ Quick Setup", action: async () => { await openCodeQuickSetup(port); return true; } },
+      { label: "Reset to Default", action: async () => { await openCodeReset(); return true; } }
+    ]
+  });
+}
+
+// ─── Hermes Agent ─────────────────────────────────────────────────────────────
+
+async function buildHermesHeader() {
+  const result = await api.getCliToolSettings("hermes");
+  if (!result.success) return `  ${COLORS.red}Failed to load settings${COLORS.reset}`;
+
+  const { installed, has9Router, settings } = result.data;
+  if (!installed) return `Status:   ${COLORS.red}✗ Hermes Agent not installed${COLORS.reset}`;
+
+  if (!has9Router) {
+    return [
+      `Status:   ${COLORS.red}✗ Not configured${COLORS.reset}`,
+      `${COLORS.dim}Run "Quick Setup" to configure${COLORS.reset}`
+    ].join("\n");
+  }
+
+  const model = settings?.model || {};
+  const lines = [`Status:   ${COLORS.green}✓ Configured${COLORS.reset}`];
+  if (model.base_url) lines.push(`Endpoint: ${COLORS.cyan}${model.base_url}${COLORS.reset}`);
+  if (model.default)  lines.push(`Model:    ${COLORS.dim}${model.default}${COLORS.reset}`);
+  return lines.join("\n");
+}
+
+async function hermesQuickSetup(port) {
+  const { endpoint } = await getEndpoint(port);
+  const apiKey = await getFirstApiKey();
+
+  if (!apiKey) {
+    showStatus("No API keys found. Create one in API Keys menu first.", "error");
+    await pause();
+    return;
+  }
+
+  const model = await selectModelFromList("Select Hermes Model", "", { excludeCombos: true });
+  if (!model) return;
+
+  const result = await api.applyCliToolSettings("hermes", { baseUrl: endpoint, apiKey, model });
+  showStatus(result.success ? "Hermes setup completed!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+async function hermesReset() {
+  const result = await api.resetCliToolSettings("hermes");
+  showStatus(result.success ? "Hermes settings reset!" : `Failed: ${result.error}`, result.success ? "success" : "error");
+  await pause();
+}
+
+async function showHermesMenu(port, breadcrumb = []) {
+  await showMenuWithBack({
+    title: "⚡ Hermes Agent Settings",
+    breadcrumb,
+    headerContent: buildHermesHeader,
+    refresh: async () => ({}),
+    items: [
+      { label: "⚡ Quick Setup", action: async () => { await hermesQuickSetup(port); return true; } },
+      { label: "Reset to Default", action: async () => { await hermesReset(); return true; } }
+    ]
+  });
+}
+
+// ─── Main CLI Tools Menu ──────────────────────────────────────────────────────
+
+/**
+ * Main CLI Tools menu
+ * @param {number} port
+ * @param {Array<string>} breadcrumb
+ */
+async function showCliToolsMenu(port, breadcrumb = []) {
+  const { endpoint } = await getEndpoint(port);
+  await showMenuWithBack({
+    title: "🔧 CLI Tools",
+    breadcrumb,
+    headerContent: `Configure CLI tools to use 9Router\nEndpoint: ${endpoint}`,
+    items: [
+      {
+        label: "Claude Code",
+        action: async () => { await showClaudeCodeMenu(port, [...breadcrumb, "Claude Code"]); return true; }
+      },
+      {
+        label: "Codex CLI",
+        action: async () => { await showCodexMenu(port, [...breadcrumb, "Codex CLI"]); return true; }
+      },
+      {
+        label: "Factory Droid",
+        action: async () => { await showDroidMenu(port, [...breadcrumb, "Factory Droid"]); return true; }
+      },
+      {
+        label: "Open Claw",
+        action: async () => { await showOpenClawMenu(port, [...breadcrumb, "Open Claw"]); return true; }
+      },
+      {
+        label: "OpenCode",
+        action: async () => { await showOpenCodeMenu(port, [...breadcrumb, "OpenCode"]); return true; }
+      },
+      {
+        label: "Hermes",
+        action: async () => { await showHermesMenu(port, [...breadcrumb, "Hermes"]); return true; }
+      }
+    ]
+  });
+}
+
+module.exports = { showCliToolsMenu };
diff --git a/cli/src/cli/menus/combos.js b/cli/src/cli/menus/combos.js
new file mode 100644
index 0000000..5a8b202
--- /dev/null
+++ b/cli/src/cli/menus/combos.js
@@ -0,0 +1,477 @@
+const api = require("../api/client");
+const { prompt, confirm, pause } = require("../utils/input");
+const { clearScreen, showStatus, showHeader } = require("../utils/display");
+const { formatDate } = require("../utils/format");
+const { selectModelFromList } = require("../utils/modelSelector");
+const { showMenuWithBack } = require("../utils/menuHelper");
+
+/**
+ * Format model to string (handle both string and object)
+ */
+function formatModel(model) {
+  if (typeof model === "string") return model;
+  if (model && typeof model === "object") {
+    return model.id || model.name || `${model.provider}/${model.model}` || JSON.stringify(model);
+  }
+  return String(model);
+}
+
+/**
+ * Show actions for a specific combo
+ * @param {Object} combo - Combo object
+ * @param {Array<string>} breadcrumb - Breadcrumb path
+ */
+async function showComboActions(combo, breadcrumb = []) {
+  const modelsChain = Array.isArray(combo.models) 
+    ? combo.models.map(formatModel).join(" → ") 
+    : "";
+  
+  await showMenuWithBack({
+    title: `🔀 ${combo.name}`,
+    breadcrumb: [...breadcrumb, combo.name],
+    headerContent: `Name: ${combo.name}\nModels: ${modelsChain}`,
+    items: [
+      {
+        label: "Edit Combo",
+        action: async () => {
+          await handleEditSingleCombo(combo);
+          return true;
+        }
+      },
+      {
+        label: "Delete Combo",
+        action: async () => {
+          await handleDeleteSingleCombo(combo);
+          return false; // Exit after delete
+        }
+      }
+    ]
+  });
+}
+
+/**
+ * Handle editing a single combo
+ * @param {Object} combo - Combo to edit
+ */
+async function handleEditSingleCombo(combo) {
+  clearScreen();
+  console.log(`\n✏️  Edit Combo: ${combo.name}\n`);
+  
+  const newName = await prompt(`New name (Enter to keep "${combo.name}"): `);
+  const name = newName || combo.name;
+  
+  console.log("\nCurrent models: " + (Array.isArray(combo.models) ? combo.models.map(formatModel).join(" → ") : ""));
+  console.log("\nSelect models for this combo (add one by one):");
+  
+  const models = [];
+  let addMore = true;
+  
+  while (addMore) {
+    const currentChain = models.length > 0 ? models.join(" → ") : "None";
+    const model = await selectModelFromList(`Add Model #${models.length + 1}`, `Chain: ${currentChain}`);
+    
+    if (model) {
+      models.push(model);
+      console.log(`\n✓ Added: ${model}`);
+      console.log(`Current chain: ${models.join(" → ")}\n`);
+      
+      const continueAdding = await confirm("Add another model?");
+      addMore = continueAdding;
+    } else {
+      addMore = false;
+    }
+  }
+  
+  // Use new models if any were added, otherwise keep current
+  const finalModels = models.length > 0 ? models : combo.models;
+  
+  const result = await api.updateCombo(combo.id, { name, models: finalModels });
+  
+  if (result.success) {
+    showStatus("Combo updated!", "success");
+  } else {
+    showStatus(`Update failed: ${result.error}`, "error");
+  }
+  await pause();
+}
+
+/**
+ * Handle deleting a single combo
+ * @param {Object} combo - Combo to delete
+ */
+async function handleDeleteSingleCombo(combo) {
+  const confirmed = await confirm(`Delete combo "${combo.name}"?`);
+  if (confirmed) {
+    const result = await api.deleteCombo(combo.id);
+    if (result.success) {
+      showStatus("Combo deleted!", "success");
+    } else {
+      showStatus(`Delete failed: ${result.error}`, "error");
+    }
+    await pause();
+  }
+}
+
+/**
+ * Main combos menu - list all combos and actions
+ * @param {Array<string>} breadcrumb - Breadcrumb path
+ */
+async function showCombosMenu(breadcrumb = []) {
+  const { showListMenu } = require("../utils/menuHelper");
+  
+  await showListMenu({
+    title: "🔀 Combos Management",
+    breadcrumb,
+    fetchItems: async () => {
+      const result = await api.getCombos();
+      if (!result.success) {
+        clearScreen();
+        showStatus(`Failed to load combos: ${result.error}`, "error");
+        await pause();
+        return null;
+      }
+      return { items: result.data.combos || [] };
+    },
+    formatItem: (combo) => {
+      const modelsChain = Array.isArray(combo.models) ? combo.models.map(formatModel).join(" → ") : "";
+      const maxLen = 35;
+      const displayModels = modelsChain.length > maxLen 
+        ? modelsChain.substring(0, maxLen - 3) + "..." 
+        : modelsChain;
+      return `${combo.name}: ${displayModels}`;
+    },
+    onSelect: async (combo) => {
+      await showComboActions(combo, breadcrumb);
+    },
+    createAction: {
+      label: "Create New Combo",
+      action: async () => {
+        await handleCreateCombo();
+      }
+    }
+  });
+}
+
+/**
+ * Show combo detail with stats
+ */
+async function showComboDetail(comboId) {
+  clearScreen();
+  
+  const result = await api.getComboById(comboId);
+  
+  if (!result.success) {
+    showStatus(`Failed to load combo: ${result.error}`, "error");
+    await pause();
+    return;
+  }
+  
+  const combo = result.data;
+  
+  console.log("┌─────────────────────────────────────────────────────────┐");
+  console.log(`│  🔀 Combo: ${combo.name.padEnd(46)} │`);
+  console.log("├─────────────────────────────────────────────────────────┤");
+  console.log("│                                                          │");
+  console.log(`│  ID: ${combo.id.padEnd(51)} │`);
+  console.log(`│  Created: ${formatDate(combo.createdAt).padEnd(46)} │`);
+  console.log(`│  Updated: ${formatDate(combo.updatedAt).padEnd(46)} │`);
+  console.log("│                                                          │");
+  console.log("│  Model Chain:                                           │");
+  
+  // Models is array of strings like ["ag/claude-sonnet-4-5", "kr/claude-sonnet-4.5"]
+  const models = Array.isArray(combo.models) ? combo.models : [];
+  models.forEach((modelStr, index) => {
+    const arrow = index < models.length - 1 ? " →" : "  ";
+    const displayText = `${index + 1}. ${modelStr}${arrow}`;
+    const padding = Math.max(0, 54 - displayText.length);
+    console.log(`│    ${displayText}${" ".repeat(padding)} │`);
+  });
+  
+  console.log("│                                                          │");
+  console.log("└─────────────────────────────────────────────────────────┘");
+  
+  await pause();
+}
+
+/**
+ * Format combo for menu display
+ */
+function formatComboLabel(combo) {
+  const modelsChain = Array.isArray(combo.models) ? combo.models.map(formatModel).join(" → ") : "";
+  const maxLen = 40;
+  const displayModels = modelsChain.length > maxLen 
+    ? modelsChain.substring(0, maxLen - 3) + "..." 
+    : modelsChain;
+  return `${combo.name}: ${displayModels}`;
+}
+
+/**
+ * Create new combo
+ */
+async function handleCreateCombo() {
+  clearScreen();
+  
+  showStatus("Create New Combo", "info");
+  console.log();
+  
+  // Get combo name
+  const name = await prompt("Combo name: ");
+  if (!name) {
+    showStatus("Combo name is required", "error");
+    await pause();
+    return;
+  }
+  
+  // Fetch available models
+  showStatus("Loading available models...", "info");
+  const modelsResult = await api.getModels();
+  
+  if (!modelsResult.success) {
+    showStatus(`Failed to load models: ${modelsResult.error}`, "error");
+    await pause();
+    return;
+  }
+  
+  const availableModels = modelsResult.data.models || [];
+  
+  if (availableModels.length === 0) {
+    showStatus("No models available. Please add providers first.", "warning");
+    await pause();
+    return;
+  }
+  
+  // Select models for chain
+  const selectedModels = [];
+  
+  console.log();
+  showStatus("Select models for the chain (minimum 2)", "info");
+  
+  while (true) {
+    clearScreen();
+    console.log(`Creating combo: ${name}`);
+    console.log(`Selected models (${selectedModels.length}):`);
+    
+    if (selectedModels.length > 0) {
+      selectedModels.forEach((m, i) => {
+        console.log(`  ${i + 1}. ${m.provider}/${m.model}`);
+      });
+    } else {
+      console.log("  (none)");
+    }
+    
+    console.log();
+    console.log("Available models:");
+    availableModels.forEach((m, i) => {
+      console.log(`  ${i + 1}. ${m.provider}/${m.model}`);
+    });
+    
+    console.log();
+    console.log("Actions:");
+    console.log("  - Enter number to add model");
+    console.log("  - Type 'done' to finish (min 2 models)");
+    console.log("  - Type 'cancel' to abort");
+    
+    const input = await prompt("\nAction: ");
+    
+    if (input.toLowerCase() === "cancel") {
+      showStatus("Cancelled", "warning");
+      await pause();
+      return;
+    }
+    
+    if (input.toLowerCase() === "done") {
+      if (selectedModels.length < 2) {
+        showStatus("Please select at least 2 models", "error");
+        await pause();
+        continue;
+      }
+      break;
+    }
+    
+    const num = parseInt(input, 10);
+    if (isNaN(num) || num < 1 || num > availableModels.length) {
+      showStatus("Invalid model number", "error");
+      await pause();
+      continue;
+    }
+    
+    selectedModels.push(availableModels[num - 1]);
+  }
+  
+  // Create combo
+  showStatus("Creating combo...", "info");
+  
+  const createResult = await api.createCombo({
+    name,
+    models: selectedModels
+  });
+  
+  if (!createResult.success) {
+    showStatus(`Failed to create combo: ${createResult.error}`, "error");
+    await pause();
+    return;
+  }
+  
+  showStatus(`Combo "${name}" created successfully!`, "success");
+  await pause();
+}
+
+/**
+ * Edit combo - select which combo to edit
+ */
+async function handleEditCombo(combos) {
+  if (combos.length === 0) {
+    showStatus("No combos available", "warning");
+    await pause();
+    return;
+  }
+  
+  let selectedCombo = null;
+  
+  await showMenuWithBack({
+    title: "✏️  Select Combo to Edit",
+    items: combos.map(combo => ({
+      label: formatComboLabel(combo),
+      action: async () => {
+        selectedCombo = combo;
+        return false;
+      }
+    }))
+  });
+  
+  if (!selectedCombo) return;
+  await editSingleCombo(selectedCombo);
+}
+
+/**
+ * Edit a single combo
+ */
+async function editSingleCombo(combo) {
+  clearScreen();
+  showStatus(`Editing combo: ${combo.name}`, "info");
+  console.log();
+  
+  const newName = await prompt(`New name (current: ${combo.name}, press Enter to keep): `);
+  const editModels = await confirm("Edit model chain?");
+  
+  let newModels = combo.models;
+  
+  if (editModels) {
+    newModels = [];
+    
+    while (true) {
+      clearScreen();
+      console.log(`Editing combo: ${combo.name}`);
+      console.log(`Selected models (${newModels.length}):`);
+      
+      if (newModels.length > 0) {
+        newModels.forEach((m, i) => console.log(`  ${i + 1}. ${m}`));
+      } else {
+        console.log("  (none)");
+      }
+      
+      console.log("\nType 'done' to finish (min 2 models) or 'cancel' to abort\n");
+      
+      const model = await selectModelFromList("Add Model", "");
+      
+      if (model === null) {
+        showStatus("Cancelled", "warning");
+        await pause();
+        return;
+      }
+      
+      if (model === "done") {
+        if (newModels.length < 2) {
+          showStatus("Please select at least 2 models", "error");
+          await pause();
+          continue;
+        }
+        break;
+      }
+      
+      newModels.push(model);
+      showStatus(`Added: ${model}`, "success");
+      await pause();
+    }
+  }
+  
+  const updateData = {};
+  if (newName) updateData.name = newName;
+  if (editModels) updateData.models = newModels;
+  
+  if (Object.keys(updateData).length === 0) {
+    showStatus("No changes made", "warning");
+    await pause();
+    return;
+  }
+  
+  showStatus("Updating combo...", "info");
+  
+  const updateResult = await api.updateCombo(combo.id, updateData);
+  
+  if (!updateResult.success) {
+    showStatus(`Failed to update combo: ${updateResult.error}`, "error");
+    await pause();
+    return;
+  }
+  
+  showStatus("Combo updated successfully!", "success");
+  await pause();
+}
+
+/**
+ * Delete combo - select which combo to delete
+ */
+async function handleDeleteCombo(combos) {
+  if (combos.length === 0) {
+    showStatus("No combos available", "warning");
+    await pause();
+    return;
+  }
+  
+  let selectedCombo = null;
+  
+  await showMenuWithBack({
+    title: "🗑️  Select Combo to Delete",
+    items: combos.map(combo => ({
+      label: formatComboLabel(combo),
+      action: async () => {
+        selectedCombo = combo;
+        return false;
+      }
+    }))
+  });
+  
+  if (!selectedCombo) return;
+  
+  clearScreen();
+  showStatus(`Combo: ${selectedCombo.name}`, "warning");
+  const modelsDisplay = Array.isArray(selectedCombo.models) 
+    ? selectedCombo.models.map(formatModel).join(" → ") 
+    : "";
+  console.log(`Models: ${modelsDisplay}`);
+  console.log();
+  
+  const confirmed = await confirm("Are you sure you want to delete this combo?");
+  
+  if (!confirmed) {
+    showStatus("Cancelled", "info");
+    await pause();
+    return;
+  }
+  
+  showStatus("Deleting combo...", "info");
+  
+  const deleteResult = await api.deleteCombo(selectedCombo.id);
+  
+  if (!deleteResult.success) {
+    showStatus(`Failed to delete combo: ${deleteResult.error}`, "error");
+    await pause();
+    return;
+  }
+  
+  showStatus("Combo deleted successfully!", "success");
+  await pause();
+}
+
+module.exports = { showCombosMenu };
diff --git a/cli/src/cli/menus/providers.js b/cli/src/cli/menus/providers.js
new file mode 100644
index 0000000..5701346
--- /dev/null
+++ b/cli/src/cli/menus/providers.js
@@ -0,0 +1,847 @@
+const api = require("../api/client");
+const { prompt, confirm, pause } = require("../utils/input");
+const { clearScreen, showStatus, showHeader } = require("../utils/display");
+const { formatDate, getRelativeTime } = require("../utils/format");
+const { showMenuWithBack } = require("../utils/menuHelper");
+const { copyToClipboard } = require("../utils/clipboard");
+
+// ANSI colors for styling
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m"
+};
+
+// Provider models - static config (synced from open-sse/config/providerModels.js)
+const PROVIDER_MODELS = {
+  cc: [
+    { id: "claude-opus-4-5-20251101" },
+    { id: "claude-sonnet-4-5-20250929" },
+    { id: "claude-haiku-4-5-20251001" },
+  ],
+  cx: [
+    { id: "gpt-5.2-codex" },
+    { id: "gpt-5.2" },
+    { id: "gpt-5.1-codex-max" },
+    { id: "gpt-5.1-codex" },
+    { id: "gpt-5.1-codex-mini" },
+    { id: "gpt-5.1" },
+    { id: "gpt-5-codex" },
+    { id: "gpt-5-codex-mini" },
+  ],
+  gc: [
+    { id: "gemini-3-flash-preview" },
+    { id: "gemini-3-pro-preview" },
+    { id: "gemini-2.5-pro" },
+    { id: "gemini-2.5-flash" },
+    { id: "gemini-2.5-flash-lite" },
+  ],
+  qw: [
+    { id: "qwen3-coder-plus" },
+    { id: "qwen3-coder-flash" },
+    { id: "vision-model" },
+  ],
+  if: [
+    { id: "qwen3-coder-plus" },
+    { id: "kimi-k2" },
+    { id: "kimi-k2-thinking" },
+    { id: "deepseek-r1" },
+    { id: "deepseek-v3.2-chat" },
+    { id: "deepseek-v3.2-reasoner" },
+    { id: "minimax-m2" },
+    { id: "glm-4.7" },
+  ],
+  ag: [
+    { id: "gemini-3-flash-agent" },
+    { id: "gemini-3.5-flash-low" },
+    { id: "gemini-3.5-flash-extra-low" },
+    { id: "gemini-pro-agent" },
+    { id: "gemini-3.1-pro-low" },
+    { id: "claude-sonnet-4-6" },
+    { id: "claude-opus-4-6-thinking" },
+    { id: "gpt-oss-120b-medium" },
+    { id: "gemini-3-flash" },
+  ],
+  gh: [
+    { id: "gpt-5" },
+    { id: "gpt-5-mini" },
+    { id: "gpt-5.1-codex" },
+    { id: "gpt-5.1-codex-max" },
+    { id: "gpt-4.1" },
+    { id: "claude-4.5-sonnet" },
+    { id: "claude-4.5-opus" },
+    { id: "claude-4.5-haiku" },
+    { id: "gemini-3-pro" },
+    { id: "gemini-3-flash" },
+    { id: "gemini-2.5-pro" },
+    { id: "grok-code-fast-1" },
+  ],
+  kr: [
+    { id: "claude-sonnet-5" },
+    { id: "claude-sonnet-4.5" },
+    { id: "claude-haiku-4.5" },
+  ],
+  openai: [
+    { id: "gpt-4o" },
+    { id: "gpt-4o-mini" },
+    { id: "gpt-4-turbo" },
+    { id: "o1" },
+    { id: "o1-mini" },
+  ],
+  anthropic: [
+    { id: "claude-sonnet-4-20250514" },
+    { id: "claude-opus-4-20250514" },
+    { id: "claude-3-5-sonnet-20241022" },
+  ],
+  gemini: [
+    { id: "gemini-3-pro-preview" },
+    { id: "gemini-2.5-pro" },
+    { id: "gemini-2.5-flash" },
+    { id: "gemini-2.5-flash-lite" },
+  ],
+  openrouter: [
+    { id: "auto" },
+  ],
+  glm: [
+    { id: "glm-4.7" },
+    { id: "glm-4.6v" },
+  ],
+  kimi: [
+    { id: "kimi-latest" },
+  ],
+  minimax: [
+    { id: "MiniMax-M2.1" },
+  ],
+};
+
+// Provider definitions
+const OAUTH_PROVIDERS = {
+  claude: { id: "claude", alias: "cc", name: "Claude Code" },
+  codex: { id: "codex", alias: "cx", name: "OpenAI Codex" },
+  "gemini-cli": { id: "gemini-cli", alias: "gc", name: "Gemini CLI" },
+  github: { id: "github", alias: "gh", name: "GitHub Copilot" },
+  antigravity: { id: "antigravity", alias: "ag", name: "Antigravity" },
+  iflow: { id: "iflow", alias: "if", name: "iFlow AI" },
+  qwen: { id: "qwen", alias: "qw", name: "Qwen Code" },
+  kiro: { id: "kiro", alias: "kr", name: "Kiro AI" },
+};
+
+const APIKEY_PROVIDERS = {
+  openrouter: { id: "openrouter", name: "OpenRouter" },
+  glm: { id: "glm", name: "GLM Coding" },
+  minimax: { id: "minimax", name: "Minimax Coding" },
+  kimi: { id: "kimi", name: "Kimi Coding" },
+  openai: { id: "openai", name: "OpenAI" },
+  anthropic: { id: "anthropic", name: "Anthropic" },
+  gemini: { id: "gemini", name: "Gemini" },
+};
+
+const ALL_PROVIDERS = { ...OAUTH_PROVIDERS, ...APIKEY_PROVIDERS };
+
+/**
+ * Get auth type for provider
+ * @param {string} providerId - Provider ID
+ * @returns {string} "oauth" or "apikey"
+ */
+function getAuthType(providerId) {
+  return OAUTH_PROVIDERS[providerId] ? "oauth" : "apikey";
+}
+
+/**
+ * Count connections by provider
+ * @param {Array} connections - Array of connection objects
+ * @returns {Object} Map of providerId -> count
+ */
+function countConnectionsByProvider(connections) {
+  const counts = {};
+  connections.forEach(conn => {
+    const providerId = conn.provider || conn.providerId;
+    counts[providerId] = (counts[providerId] || 0) + 1;
+  });
+  return counts;
+}
+
+/**
+ * Show main providers menu
+ * @param {Array<string>} breadcrumb - Breadcrumb path
+ */
+async function showProvidersMenu(breadcrumb = []) {
+  // Build provider items list
+  const providerItems = [];
+  
+  Object.values(OAUTH_PROVIDERS).forEach(provider => {
+    providerItems.push({
+      provider,
+      authType: "oauth",
+      label: (data) => {
+        const count = data.counts[provider.id] || 0;
+        return `${provider.name} (OAuth) - ${count} Connected`;
+      },
+      action: async (data) => {
+        await showProviderDetail(provider.id, "oauth", data.connections, [...breadcrumb, provider.name]);
+        return true;
+      }
+    });
+  });
+  
+  Object.values(APIKEY_PROVIDERS).forEach(provider => {
+    providerItems.push({
+      provider,
+      authType: "apikey",
+      label: (data) => {
+        const count = data.counts[provider.id] || 0;
+        return `${provider.name} (API) - ${count} Connected`;
+      },
+      action: async (data) => {
+        await showProviderDetail(provider.id, "apikey", data.connections, [...breadcrumb, provider.name]);
+        return true;
+      }
+    });
+  });
+
+  // Custom provider nodes section
+  providerItems.push({
+    label: () => `${COLORS.dim}── Custom Providers ──${COLORS.reset}`,
+    action: async () => true, // separator, no-op
+    isSeparator: true,
+  });
+  providerItems.push({
+    label: (data) => {
+      const count = data.nodeCount || 0;
+      return `Custom Providers - ${count} Configured`;
+    },
+    action: async () => {
+      await showCustomProvidersMenu([...breadcrumb, "Custom Providers"]);
+      return true;
+    }
+  });
+
+  await showMenuWithBack({
+    title: "🔌 Providers Management",
+    breadcrumb,
+    refresh: async () => {
+      const [provRes, nodeRes] = await Promise.all([api.getProviders(), api.getProviderNodes()]);
+      if (!provRes.success) {
+        showStatus(`Failed to fetch providers: ${provRes.error}`, "error");
+        await pause();
+        return null;
+      }
+      const connections = provRes.data.connections || [];
+      const nodes = nodeRes.success ? (nodeRes.data.nodes || nodeRes.data || []) : [];
+      return {
+        connections,
+        counts: countConnectionsByProvider(connections),
+        nodeCount: nodes.length,
+      };
+    },
+    items: providerItems
+  });
+}
+
+/**
+ * Build provider header with alias and models
+ * @param {string} providerId - Provider ID
+ * @returns {string}
+ */
+function buildProviderHeader(providerId) {
+  const provider = ALL_PROVIDERS[providerId];
+  const alias = provider.alias || providerId;
+  
+  const lines = [];
+  lines.push(`Alias: ${COLORS.cyan}${alias}${COLORS.reset}`);
+  
+  // Get models from static config
+  const models = PROVIDER_MODELS[alias] || [];
+  if (models.length > 0) {
+    const modelList = models
+      .slice(0, 5)
+      .map(m => `${alias}/${m.id}`)
+      .join(", ");
+    const more = models.length > 5 ? ` (+${models.length - 5} more)` : "";
+    lines.push(`Models: ${COLORS.dim}${modelList}${more}${COLORS.reset}`);
+  } else {
+    lines.push(`Models: ${COLORS.dim}No models configured${COLORS.reset}`);
+  }
+  
+  return lines.join("\n");
+}
+
+/**
+ * Show provider detail with connections and actions
+ * @param {string} providerId - Provider ID
+ * @param {string} authType - "oauth" or "apikey"
+ * @param {Array} allConnections - All connections
+ * @param {Array<string>} breadcrumb - Breadcrumb path
+ */
+async function showProviderDetail(providerId, authType, allConnections, breadcrumb = []) {
+  const provider = ALL_PROVIDERS[providerId];
+  const { showListMenu } = require("../utils/menuHelper");
+  
+  await showListMenu({
+    title: `🔌 ${provider.name} (${authType.toUpperCase()})`,
+    breadcrumb,
+    backLabel: "← Back to Providers",
+    headerContent: buildProviderHeader(providerId),
+    fetchItems: async () => {
+      const response = await api.getProviders();
+      if (response.success) {
+        allConnections.length = 0;
+        allConnections.push(...(response.data.connections || []));
+      }
+      const providerConns = allConnections.filter(conn => 
+        (conn.provider || conn.providerId) === providerId
+      );
+      return { items: providerConns };
+    },
+    formatItem: (conn) => {
+      const status = conn.testStatus === "active" ? "✓" : conn.testStatus === "error" ? "✗" : "?";
+      const name = conn.name || conn.email || conn.displayName || "Unnamed";
+      return `${name} (${status})`;
+    },
+    onSelect: async (conn) => {
+      await showConnectionActions(conn, providerId, breadcrumb);
+    },
+    createAction: {
+      label: "Add New Connection",
+      action: async () => {
+        await handleAddConnection(providerId, authType);
+      }
+    }
+  });
+}
+
+/**
+ * Show actions for a specific connection
+ * @param {Object} connection - Connection object
+ * @param {string} providerId - Provider ID
+ * @param {Array<string>} breadcrumb - Breadcrumb path
+ */
+async function showConnectionActions(connection, providerId, breadcrumb = []) {
+  const name = connection.name || connection.email || connection.displayName || "Unnamed";
+  const status = connection.testStatus === "active" ? "✓ Active" : 
+                 connection.testStatus === "error" ? "✗ Error" : "? Unknown";
+  
+  await showMenuWithBack({
+    title: `🔌 ${name}`,
+    breadcrumb: [...breadcrumb, name],
+    headerContent: `Connection: ${name}\nStatus: ${status}`,
+    items: [
+      {
+        label: "Rename Connection",
+        action: async () => {
+          const newName = await prompt(`New name (current: ${name}): `);
+          if (newName && newName.trim()) {
+            showStatus("Renaming connection...", "info");
+            const result = await api.updateConnection(connection.id, { name: newName.trim() });
+            if (result.success) {
+              showStatus("Connection renamed!", "success");
+              connection.name = newName.trim();
+            } else {
+              showStatus(`Rename failed: ${result.error}`, "error");
+            }
+            await pause();
+          }
+          return true;
+        }
+      },
+      {
+        label: "Test Connection",
+        action: async () => {
+          showStatus("Testing connection...", "info");
+          const result = await api.testConnection(connection.id);
+          if (result.success) {
+            showStatus("Connection is working!", "success");
+          } else {
+            showStatus(`Test failed: ${result.error}`, "error");
+          }
+          await pause();
+          return true;
+        }
+      },
+      {
+        label: "Delete Connection",
+        action: async () => {
+          const confirmed = await confirm(`Delete connection "${name}"?`);
+          if (confirmed) {
+            const result = await api.deleteConnection(connection.id);
+            if (result.success) {
+              showStatus("Connection deleted!", "success");
+            } else {
+              showStatus(`Delete failed: ${result.error}`, "error");
+            }
+            await pause();
+            return false; // Exit menu after delete
+          }
+          return true;
+        }
+      }
+    ]
+  });
+}
+
+/**
+ * Handle adding new connection
+ * @param {string} providerId - Provider ID
+ * @param {string} authType - "oauth" or "apikey"
+ */
+// Providers that use Device Code Flow (terminal-based polling)
+const DEVICE_CODE_PROVIDERS = ["github", "qwen", "kiro"];
+
+/**
+ * Handle adding new connection - auto-detect flow type
+ * @param {string} providerId - Provider ID
+ * @param {string} authType - "oauth" or "apikey"
+ */
+async function handleAddConnection(providerId, authType) {
+  if (authType === "apikey") {
+    await handleAddApiKeyConnection(providerId);
+  } else {
+    // OAuth: auto-detect flow type based on provider
+    if (DEVICE_CODE_PROVIDERS.includes(providerId)) {
+      // Device Code Flow for GitHub, Qwen, Kiro
+      await handleAddDeviceCodeConnection(providerId);
+    } else {
+      // Authorization Code Flow for Claude, Codex, Gemini, etc.
+      await handleAddOAuthConnection(providerId);
+    }
+  }
+}
+
+/**
+ * Handle adding API Key connection
+ * @param {string} providerId - Provider ID
+ */
+async function handleAddApiKeyConnection(providerId) {
+  clearScreen();
+  const provider = ALL_PROVIDERS[providerId];
+  console.log(`\n➕ Add ${provider.name} API Key Connection\n`);
+  
+  const name = await prompt("Connection Name: ");
+  if (!name) {
+    showStatus("Cancelled", "warning");
+    await pause();
+    return;
+  }
+  
+  const apiKey = await prompt("API Key: ");
+  if (!apiKey) {
+    showStatus("Cancelled", "warning");
+    await pause();
+    return;
+  }
+  
+  showStatus("Creating connection...", "info");
+  
+  const result = await api.createApiKeyProvider({
+    provider: providerId,
+    name,
+    apiKey
+  });
+  
+  if (result.success) {
+    showStatus("✓ Connection created successfully!", "success");
+  } else {
+    showStatus(`✗ Failed: ${result.error}`, "error");
+  }
+  
+  await pause();
+}
+
+/**
+ * Handle adding OAuth Authorization Code connection
+ * User opens URL manually and pastes callback URL
+ * @param {string} providerId - Provider ID
+ */
+async function handleAddOAuthConnection(providerId) {
+  clearScreen();
+  const provider = ALL_PROVIDERS[providerId];
+  
+  // Step 1: Get auth URL
+  showStatus("Requesting authorization URL...", "info");
+  const authResult = await api.getOAuthAuthUrl(providerId);
+  
+  if (!authResult.success) {
+    showStatus(`Failed: ${authResult.error}`, "error");
+    await pause();
+    return;
+  }
+  
+  const authData = authResult.data || authResult;
+  const authUrl = authData.authUrl;
+  const codeVerifier = authData.codeVerifier;
+  const state = authData.state;
+  const redirectUri = authData.redirectUri;
+  
+  if (!authUrl) {
+    showStatus("Failed: No auth URL received", "error");
+    await pause();
+    return;
+  }
+  
+  // Step 2: Show URL and instructions
+  clearScreen();
+  showHeader("🔐 OAuth Login", `Providers > ${provider.name} > Add Connection`);
+  
+  console.log(`  ${COLORS.bold}${COLORS.cyan}1.${COLORS.reset} Open this URL in your browser:`);
+  console.log(`     ${COLORS.dim}${authUrl}${COLORS.reset}`);
+  if (copyToClipboard(authUrl)) {
+    console.log(`     \x1b[32m✓ Link copied to clipboard!\x1b[0m`);
+  }
+  console.log();
+  console.log(`  ${COLORS.bold}${COLORS.cyan}2.${COLORS.reset} Complete authorization in browser`);
+  console.log();
+  console.log(`  ${COLORS.bold}${COLORS.cyan}3.${COLORS.reset} Copy the callback URL from address bar`);
+  console.log(`     ${COLORS.dim}(looks like: http://localhost:20128/callback?code=...)${COLORS.reset}`);
+  console.log();
+  
+  const callbackUrl = await prompt("  Paste callback URL: ");
+  if (!callbackUrl) {
+    showStatus("Cancelled", "warning");
+    await pause();
+    return;
+  }
+  
+  // Step 3: Parse callback URL and extract code
+  let code, urlState, error;
+  try {
+    const url = new URL(callbackUrl.trim());
+    code = url.searchParams.get("code");
+    urlState = url.searchParams.get("state");
+    error = url.searchParams.get("error");
+    
+    if (error) {
+      const errorDesc = url.searchParams.get("error_description") || error;
+      showStatus(`Authorization failed: ${errorDesc}`, "error");
+      await pause();
+      return;
+    }
+    
+    if (!code) {
+      showStatus("No authorization code found in URL", "error");
+      await pause();
+      return;
+    }
+  } catch (err) {
+    showStatus("Invalid URL format", "error");
+    await pause();
+    return;
+  }
+  
+  // Step 4: Exchange code for tokens
+  console.log();
+  showStatus("Exchanging code for tokens...", "info");
+  const exchangeResult = await api.exchangeOAuthCode(providerId, {
+    code,
+    redirectUri,
+    codeVerifier,
+    state: urlState || state
+  });
+  
+  if (exchangeResult.success) {
+    showStatus("Connection created successfully!", "success");
+  } else {
+    showStatus(`Failed: ${exchangeResult.error}`, "error");
+  }
+  
+  await pause();
+}
+
+/**
+ * Handle adding OAuth Device Code connection
+ * @param {string} providerId - Provider ID
+ */
+async function handleAddDeviceCodeConnection(providerId) {
+  clearScreen();
+  const provider = ALL_PROVIDERS[providerId];
+  
+  // Step 1: Request device code
+  showStatus("Requesting device code...", "info");
+  const deviceResult = await api.getOAuthDeviceCode(providerId);
+  
+  if (!deviceResult.success) {
+    showStatus(`Failed: ${deviceResult.error}`, "error");
+    await pause();
+    return;
+  }
+  
+  const deviceData = deviceResult.data || deviceResult;
+  const device_code = deviceData.device_code;
+  const user_code = deviceData.user_code;
+  const verification_uri = deviceData.verification_uri;
+  const verification_uri_complete = deviceData.verification_uri_complete;
+  const codeVerifier = deviceData.codeVerifier;
+  const extraData = deviceData.extraData || deviceData;
+  
+  if (!device_code) {
+    showStatus("Failed: No device code received", "error");
+    await pause();
+    return;
+  }
+  
+  // Step 2: Show instructions
+  clearScreen();
+  const deviceUrl = verification_uri_complete || verification_uri;
+  showHeader("📱 Device Login", `Providers > ${provider.name} > Add Connection`);
+  
+  console.log(`  ${COLORS.bold}${COLORS.cyan}1.${COLORS.reset} Open: ${COLORS.dim}${deviceUrl}${COLORS.reset}`);
+  if (copyToClipboard(deviceUrl)) {
+    console.log(`     \x1b[32m✓ Link copied to clipboard!\x1b[0m`);
+  }
+  console.log();
+  if (!verification_uri_complete && user_code) {
+    console.log(`  ${COLORS.bold}${COLORS.cyan}2.${COLORS.reset} Enter code: ${COLORS.bold}${user_code}${COLORS.reset}`);
+    console.log();
+  }
+  console.log(`  ${COLORS.dim}Waiting for authorization...${COLORS.reset}`);
+  console.log();
+  
+  // Step 3: Poll for token
+  const maxAttempts = 60; // 5 minutes (5s interval)
+  for (let i = 0; i < maxAttempts; i++) {
+    await new Promise(resolve => setTimeout(resolve, 5000));
+    
+    const pollResult = await api.pollOAuthToken(providerId, {
+      deviceCode: device_code,
+      codeVerifier,
+      extraData
+    });
+    
+    if (pollResult.success) {
+      showStatus("\nConnection created successfully!", "success");
+      await pause();
+      return;
+    }
+    
+    // Check if still pending (pending flag is at root level, not in data)
+    const isPending = pollResult.pending || pollResult.error === "authorization_pending" || pollResult.error === "slow_down";
+    if (!isPending) {
+      showStatus(`\nFailed: ${pollResult.error || "Unknown error"}`, "error");
+      await pause();
+      return;
+    }
+    
+    process.stdout.write(".");
+  }
+  
+  showStatus("\nTimeout waiting for authorization", "error");
+  await pause();
+}
+
+// ============================================================================
+// CUSTOM PROVIDERS (provider nodes)
+// ============================================================================
+
+const CUSTOM_NODE_TYPES = ["openai-compatible", "anthropic-compatible"];
+const OPENAI_API_TYPES = ["chat", "responses"];
+
+/**
+ * Show custom providers section in main providers menu
+ * @param {Array} nodes - List of provider nodes
+ * @param {Array} connections - All connections
+ * @param {Array<string>} breadcrumb
+ */
+async function showCustomProvidersMenu(breadcrumb = []) {
+  const { showListMenu } = require("../utils/menuHelper");
+
+  await showListMenu({
+    title: "🔧 Custom Providers",
+    breadcrumb,
+    backLabel: "← Back to Providers",
+    fetchItems: async () => {
+      const res = await api.getProviderNodes();
+      if (!res.success) return { items: [] };
+      return { items: res.data.nodes || res.data || [] };
+    },
+    formatItem: (node) => `[${node.prefix}] ${node.name} (${node.type})`,
+    onSelect: async (node) => {
+      await showCustomNodeDetail(node, [...breadcrumb, node.name]);
+    },
+    createAction: {
+      label: "➕ Add Custom Provider",
+      action: async () => {
+        await handleAddCustomNode();
+      }
+    }
+  });
+}
+
+/**
+ * Show detail menu for a custom provider node
+ */
+async function showCustomNodeDetail(node, breadcrumb = []) {
+  await showMenuWithBack({
+    title: `🔧 ${node.name}`,
+    breadcrumb,
+    headerContent: [
+      `Type: ${node.type}`,
+      `Prefix: ${COLORS.cyan}${node.prefix}${COLORS.reset}`,
+      `Base URL: ${COLORS.dim}${node.baseUrl}${COLORS.reset}`,
+    ].join("\n"),
+    items: [
+      {
+        label: "Connections",
+        action: async () => {
+          await showCustomNodeConnections(node, breadcrumb);
+          return true;
+        }
+      },
+      {
+        label: "Edit Node",
+        action: async () => {
+          await handleEditCustomNode(node);
+          return true;
+        }
+      },
+      {
+        label: "Delete Node",
+        action: async () => {
+          const confirmed = await confirm(`Delete "${node.name}" and all its connections?`);
+          if (confirmed) {
+            const res = await api.deleteProviderNode(node.id);
+            if (res.success) {
+              showStatus("Node deleted!", "success");
+            } else {
+              showStatus(`Delete failed: ${res.error}`, "error");
+            }
+            await pause();
+            return false;
+          }
+          return true;
+        }
+      }
+    ]
+  });
+}
+
+/**
+ * Show connections for a custom provider node
+ */
+async function showCustomNodeConnections(node, breadcrumb = []) {
+  const { showListMenu } = require("../utils/menuHelper");
+
+  await showListMenu({
+    title: `🔌 ${node.name} – Connections`,
+    breadcrumb,
+    backLabel: "← Back",
+    fetchItems: async () => {
+      const res = await api.getProviders();
+      if (!res.success) return { items: [] };
+      const all = res.data.connections || [];
+      const items = all.filter(c => c.provider === node.id);
+      return { items };
+    },
+    formatItem: (conn) => {
+      const status = conn.testStatus === "active" ? "✓" : conn.testStatus === "error" ? "✗" : "?";
+      return `${conn.name || "Unnamed"} (${status})`;
+    },
+    onSelect: async (conn) => {
+      await showConnectionActions(conn, node.id, breadcrumb);
+    },
+    createAction: {
+      label: "Add API Key Connection",
+      action: async () => {
+        await handleAddCustomNodeConnection(node);
+      }
+    }
+  });
+}
+
+/**
+ * Add API key connection to a custom provider node
+ */
+async function handleAddCustomNodeConnection(node) {
+  clearScreen();
+  console.log(`\n➕ Add Connection to ${node.name}\n`);
+
+  const name = await prompt("Connection Name: ");
+  if (!name) { showStatus("Cancelled", "warning"); await pause(); return; }
+
+  const apiKey = await prompt("API Key: ");
+  if (!apiKey) { showStatus("Cancelled", "warning"); await pause(); return; }
+
+  showStatus("Creating connection...", "info");
+  const res = await api.createApiKeyProvider({ provider: node.id, name, apiKey });
+
+  showStatus(res.success ? "✓ Connection created!" : `✗ Failed: ${res.error}`, res.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Handle adding a new custom provider node
+ */
+async function handleAddCustomNode() {
+  clearScreen();
+  console.log("\n➕ Add Custom Provider\n");
+
+  // Step 1: Select type
+  const typeChoices = CUSTOM_NODE_TYPES.map((t, i) => `  ${i + 1}. ${t}`).join("\n");
+  console.log(`Select type:\n${typeChoices}\n`);
+  const typeInput = await prompt("Type (1/2): ");
+  const typeIdx = parseInt(typeInput) - 1;
+  if (isNaN(typeIdx) || !CUSTOM_NODE_TYPES[typeIdx]) {
+    showStatus("Cancelled", "warning"); await pause(); return;
+  }
+  const type = CUSTOM_NODE_TYPES[typeIdx];
+
+  // Step 2: Inputs
+  const name = await prompt("Name: ");
+  if (!name) { showStatus("Cancelled", "warning"); await pause(); return; }
+
+  const prefix = await prompt("Prefix (used in model IDs, e.g. myapi): ");
+  if (!prefix) { showStatus("Cancelled", "warning"); await pause(); return; }
+
+  const baseUrl = await prompt("Base URL (e.g. https://api.example.com/v1): ");
+  if (!baseUrl) { showStatus("Cancelled", "warning"); await pause(); return; }
+
+  // Step 3: API type (OpenAI only)
+  let apiType;
+  if (type === "openai-compatible") {
+    const apiTypeChoices = OPENAI_API_TYPES.map((t, i) => `  ${i + 1}. ${t}`).join("\n");
+    console.log(`\nAPI Type:\n${apiTypeChoices}\n`);
+    const apiTypeInput = await prompt("API Type (1/2, default 1): ");
+    const apiTypeIdx = parseInt(apiTypeInput) - 1;
+    apiType = OPENAI_API_TYPES[apiTypeIdx] || "chat";
+  }
+
+  showStatus("Creating provider node...", "info");
+  const body = { name, prefix, baseUrl, type, ...(apiType && { apiType }) };
+  const res = await api.createProviderNode(body);
+
+  showStatus(res.success ? "✓ Provider created!" : `✗ Failed: ${res.error}`, res.success ? "success" : "error");
+  await pause();
+}
+
+/**
+ * Handle editing a custom provider node
+ */
+async function handleEditCustomNode(node) {
+  clearScreen();
+  console.log(`\n✏️  Edit ${node.name}\n`);
+  console.log(`${COLORS.dim}Leave blank to keep current value${COLORS.reset}\n`);
+
+  const name = await prompt(`Name (${node.name}): `);
+  const baseUrl = await prompt(`Base URL (${node.baseUrl}): `);
+  const prefix = await prompt(`Prefix (${node.prefix}): `);
+
+  const updates = {};
+  if (name && name.trim()) updates.name = name.trim();
+  if (baseUrl && baseUrl.trim()) updates.baseUrl = baseUrl.trim();
+  if (prefix && prefix.trim()) updates.prefix = prefix.trim();
+
+  if (!Object.keys(updates).length) {
+    showStatus("No changes", "warning"); await pause(); return;
+  }
+
+  showStatus("Updating...", "info");
+  const res = await api.updateProviderNode(node.id, updates);
+  if (res.success) {
+    Object.assign(node, updates);
+    showStatus("✓ Updated!", "success");
+  } else {
+    showStatus(`✗ Failed: ${res.error}`, "error");
+  }
+  await pause();
+}
+
+module.exports = { showProvidersMenu };
diff --git a/cli/src/cli/menus/settings.js b/cli/src/cli/menus/settings.js
new file mode 100644
index 0000000..ce77933
--- /dev/null
+++ b/cli/src/cli/menus/settings.js
@@ -0,0 +1,204 @@
+const api = require("../api/client");
+const { confirm, pause } = require("../utils/input");
+const { showStatus } = require("../utils/display");
+const { showMenuWithBack } = require("../utils/menuHelper");
+
+// ANSI colors
+const COLORS = {
+  reset: "\x1b[0m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m"
+};
+
+const DEFAULT_PASSWORD = "123456";
+
+/**
+ * Show settings menu (tunnel + RTK + reset password)
+ * @param {Array<string>} breadcrumb - Breadcrumb path
+ */
+async function showSettingsMenu(breadcrumb = []) {
+  await showMenuWithBack({
+    title: "⚙️  Settings",
+    breadcrumb,
+    headerContent: async (data) => {
+      const lines = [];
+
+      // Tunnel section
+      const tunnel = data?.tunnel || {};
+      if (tunnel.enabled && tunnel.publicUrl) {
+        lines.push(`  Endpoint: ${COLORS.green}${tunnel.publicUrl}/v1${COLORS.reset}`);
+        lines.push(`  Tunnel:   ${COLORS.green}ON${COLORS.reset} ${COLORS.dim}(${tunnel.shortId})${COLORS.reset}`);
+      } else {
+        lines.push(`  Endpoint: http://localhost:20128/v1`);
+        lines.push(`  Tunnel:   ${COLORS.red}OFF${COLORS.reset} ${COLORS.dim}(local only)${COLORS.reset}`);
+      }
+
+      // RTK section
+      const rtkOn = data?.settings?.rtkEnabled !== false;
+      lines.push(`  RTK:      ${rtkOn ? `${COLORS.green}ON${COLORS.reset}` : `${COLORS.red}OFF${COLORS.reset}`} ${COLORS.dim}(Token Saver)${COLORS.reset}`);
+      const headroomOn = data?.settings?.headroomEnabled === true;
+      lines.push(`  Headroom: ${headroomOn ? `${COLORS.green}ON${COLORS.reset}` : `${COLORS.red}OFF${COLORS.reset}`} ${COLORS.dim}(${data?.settings?.headroomUrl || "http://localhost:8787"})${COLORS.reset}`);
+
+      // Auth mode section
+      const authMode = data?.settings?.authMode || "password";
+      const authColor = authMode === "password" ? COLORS.green : COLORS.yellow;
+      lines.push(`  Auth:     ${authColor}${authMode.toUpperCase()}${COLORS.reset} ${COLORS.dim}(login mode)${COLORS.reset}`);
+
+      return lines.join("\n");
+    },
+    refresh: async () => {
+      const [tunnelRes, settingsRes] = await Promise.all([
+        api.getTunnelStatus(),
+        api.getSettings()
+      ]);
+      return {
+        tunnel: tunnelRes.success ? (tunnelRes.data || {}) : {},
+        settings: settingsRes.success ? (settingsRes.data || {}) : {}
+      };
+    },
+    items: [
+      {
+        label: "Tunnel ON",
+        action: async () => { await enableTunnel(); return true; }
+      },
+      {
+        label: "Tunnel OFF",
+        action: async () => { await disableTunnel(); return true; }
+      },
+      {
+        label: (d) => {
+          const on = d?.settings?.rtkEnabled !== false;
+          return `Token Saver (RTK): ${on ? "ON" : "OFF"} → toggle`;
+        },
+        action: async (d) => { await toggleRtk(d?.settings?.rtkEnabled !== false); return true; }
+      },
+      {
+        label: (d) => {
+          const on = d?.settings?.headroomEnabled === true;
+          return `Token Saver (Headroom): ${on ? "ON" : "OFF"} → toggle`;
+        },
+        action: async (d) => { await toggleHeadroom(d?.settings?.headroomEnabled === true); return true; }
+      },
+      {
+        label: "🔑 Reset Password to Default",
+        action: async () => { await resetPassword(); return true; }
+      },
+      {
+        label: (d) => {
+          const mode = d?.settings?.authMode || "password";
+          return mode === "password" ? "🔓 Reset Auth Mode (already password)" : `🔓 Reset Auth Mode to Password (current: ${mode})`;
+        },
+        action: async () => { await resetAuthMode(); return true; }
+      }
+    ]
+  });
+}
+
+/**
+ * Reset authMode to "password" via API. Used when OIDC is misconfigured
+ * and user is locked out of dashboard. CLI bypasses auth via x-9r-cli-token.
+ */
+async function resetAuthMode() {
+  const ok = await confirm("Reset auth mode to PASSWORD (disable OIDC)?");
+  if (!ok) {
+    showStatus("Cancelled", "info");
+    await pause();
+    return;
+  }
+
+  const result = await api.updateSettings({ authMode: "password" });
+  if (result.success) {
+    showStatus("Auth mode reset to password. OIDC disabled.", "success");
+  } else {
+    showStatus(`Failed: ${result.error}`, "error");
+  }
+  await pause();
+}
+
+/**
+ * Enable tunnel via API
+ */
+async function enableTunnel() {
+  showStatus("Creating tunnel...", "info");
+  const result = await api.enableTunnel();
+
+  if (result.success) {
+    const { publicUrl, shortId, alreadyRunning } = result.data || {};
+    if (alreadyRunning) {
+      showStatus(`Tunnel already running: ${publicUrl}`, "success");
+    } else {
+      showStatus(`Tunnel enabled: ${publicUrl} (${shortId})`, "success");
+    }
+  } else {
+    showStatus(`Failed: ${result.error}`, "error");
+  }
+
+  await pause();
+}
+
+/**
+ * Disable tunnel via API
+ */
+async function disableTunnel() {
+  const result = await api.disableTunnel();
+
+  if (result.success) {
+    showStatus("Tunnel disabled", "success");
+  } else {
+    showStatus(`Failed: ${result.error}`, "error");
+  }
+
+  await pause();
+}
+
+/**
+ * Toggle RTK (Token Saver) via API
+ * @param {boolean} currentlyOn
+ */
+async function toggleRtk(currentlyOn) {
+  const next = !currentlyOn;
+  const result = await api.updateSettings({ rtkEnabled: next });
+  if (result.success) {
+    showStatus(`Token Saver ${next ? "enabled" : "disabled"}`, "success");
+  } else {
+    showStatus(`Failed: ${result.error}`, "error");
+  }
+  await pause();
+}
+
+async function toggleHeadroom(currentlyOn) {
+  const next = !currentlyOn;
+  const result = await api.updateSettings({ headroomEnabled: next });
+  if (result.success) {
+    showStatus(`Headroom ${next ? "enabled" : "disabled"}`, "success");
+  } else {
+    showStatus(`Failed: ${result.error}`, "error");
+  }
+  await pause();
+}
+
+/**
+ * Reset dashboard password to default via server API (writes the live SQLite DB).
+ * After reset, user can log in with the default password "123456".
+ */
+async function resetPassword() {
+  const ok = await confirm(`Reset dashboard password to default "${DEFAULT_PASSWORD}"?`);
+  if (!ok) {
+    showStatus("Cancelled", "info");
+    await pause();
+    return;
+  }
+
+  const result = await api.resetPassword();
+  if (result.success) {
+    showStatus(`Password reset. Default: ${DEFAULT_PASSWORD}`, "success");
+  } else {
+    showStatus(`Failed to reset password: ${result.error}`, "error");
+  }
+  await pause();
+}
+
+module.exports = { showSettingsMenu };
diff --git a/cli/src/cli/terminalUI.js b/cli/src/cli/terminalUI.js
new file mode 100644
index 0000000..fb28330
--- /dev/null
+++ b/cli/src/cli/terminalUI.js
@@ -0,0 +1,121 @@
+const api = require("./api/client");
+const { showMenuWithBack } = require("./utils/menuHelper");
+const { showProvidersMenu } = require("./menus/providers");
+const { showApiKeysMenu } = require("./menus/apiKeys");
+const { showCombosMenu } = require("./menus/combos");
+const { showSettingsMenu } = require("./menus/settings");
+const { showCliToolsMenu } = require("./menus/cliTools");
+
+const COLORS = {
+  reset: "\x1b[0m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m"
+};
+
+// Cached header (SWR): show last value instantly, refresh in background.
+let cachedHeader = "";
+let fetchingHeader = false;
+
+function renderHeader(port, keys, tunnel) {
+  const tunnelEnabled = tunnel && tunnel.enabled === true;
+  const lines = [];
+  if (tunnelEnabled && tunnel.publicUrl) {
+    lines.push(`Endpoint: ${COLORS.green}${tunnel.publicUrl}/v1${COLORS.reset}`);
+    lines.push(`Tunnel:   ${COLORS.green}ON${COLORS.reset} ${COLORS.dim}(${tunnel.shortId})${COLORS.reset}`);
+  } else {
+    lines.push(`Endpoint: http://localhost:${port}/v1`);
+    lines.push(`Tunnel:   ${COLORS.red}OFF${COLORS.reset} ${COLORS.dim}(local only)${COLORS.reset}`);
+  }
+  if (!keys || keys.length === 0) {
+    lines.push(`Key:      ${COLORS.dim}No API keys yet${COLORS.reset}`);
+  } else {
+    lines.push(`Key:      ${COLORS.cyan}${keys[0].key}${COLORS.reset}`);
+    keys.slice(1).forEach(k => lines.push(`          ${COLORS.cyan}${k.key}${COLORS.reset}`));
+  }
+  return lines.join("\n");
+}
+
+async function refreshHeaderBg(port) {
+  if (fetchingHeader) return;
+  fetchingHeader = true;
+  try {
+    const [keysResult, tunnelResult] = await Promise.all([
+      api.getApiKeys(),
+      api.getTunnelStatus()
+    ]);
+    const keys = keysResult.success ? (keysResult.data.keys || []) : [];
+    const tunnel = tunnelResult.success ? (tunnelResult.data || {}) : {};
+    cachedHeader = renderHeader(port, keys, tunnel);
+  } finally {
+    fetchingHeader = false;
+  }
+}
+
+function getHeader(port) {
+  // Kick off background refresh; return cache (or placeholder on first call).
+  refreshHeaderBg(port);
+  return cachedHeader || `Endpoint: http://localhost:${port}/v1\nTunnel:   ${COLORS.dim}...${COLORS.reset}\nKey:      ${COLORS.dim}...${COLORS.reset}`;
+}
+
+/**
+ * Start Terminal UI
+ * @param {number} port - Server port number
+ */
+async function startTerminalUI(port) {
+  // Configure API client
+  api.configure({ port });
+
+  const basePath = ["9Router"];
+
+  // Prime header cache before first render
+  await refreshHeaderBg(port);
+
+  // Main menu
+  await showMenuWithBack({
+    title: "📡 9Router Terminal UI",
+    breadcrumb: basePath,
+    headerContent: () => getHeader(port),
+    items: [
+      {
+        label: "Providers",
+        action: async () => {
+          await showProvidersMenu([...basePath, "Providers"]);
+          return true; // Continue
+        }
+      },
+      {
+        label: "API Keys",
+        action: async () => {
+          await showApiKeysMenu(port, [...basePath, "API Keys"]);
+          return true;
+        }
+      },
+      {
+        label: "Combos",
+        action: async () => {
+          await showCombosMenu([...basePath, "Combos"]);
+          return true;
+        }
+      },
+      {
+        label: "CLI Tools",
+        action: async () => {
+          await showCliToolsMenu(port, [...basePath, "CLI Tools"]);
+          return true;
+        }
+      },
+      {
+        label: "Settings",
+        action: async () => {
+          await showSettingsMenu([...basePath, "Settings"]);
+          return true;
+        }
+      }
+    ],
+    backLabel: "← Back to Interface Menu"
+  });
+}
+
+module.exports = { startTerminalUI };
diff --git a/cli/src/cli/tray/autostart.js b/cli/src/cli/tray/autostart.js
new file mode 100644
index 0000000..4ab93cf
--- /dev/null
+++ b/cli/src/cli/tray/autostart.js
@@ -0,0 +1,306 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync } = require("child_process");
+
+const APP_NAME = "9router";
+const APP_LABEL = "com.9router.autostart";
+
+/**
+ * Resolve the absolute path to this package's cli.js.
+ *
+ * Order of preference:
+ *   1. Explicit `cliPath` argument — cleanest, used when called from running
+ *      cli.js with `__filename`.
+ *   2. `process.argv[1]` if it's our cli.js — true when 9router is currently
+ *      running and the tray menu fires this code path.
+ *   3. Compute relative to this file's own location. autostart.js lives at
+ *      `<pkg>/src/cli/tray/autostart.js`, so cli.js is three levels up.
+ *      This works for any global install layout (nvm, Volta, asdf, Homebrew,
+ *      /usr/local, etc.) without depending on `npm bin -g` (removed in npm 9)
+ *      or a hardcoded `/usr/local/...` path.
+ *
+ * Returns null if no candidate exists — callers should not write an autostart
+ * entry pointing at a non-existent script.
+ */
+function getCliJsPath(cliPath) {
+  if (cliPath) {
+    const resolved = path.resolve(cliPath);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+  if (process.argv[1]) {
+    const resolved = path.resolve(process.argv[1]);
+    if (path.basename(resolved) === "cli.js" && fs.existsSync(resolved)) {
+      return resolved;
+    }
+  }
+  const computed = path.resolve(__dirname, "..", "..", "..", "cli.js");
+  if (fs.existsSync(computed)) return computed;
+  return null;
+}
+
+/**
+ * Enable auto startup on OS boot
+ * @param {string} cliPath - Optional path to cli.js (defaults to auto-detect)
+ * @returns {boolean} success
+ */
+function enableAutoStart(cliPath) {
+  const platform = process.platform;
+
+  if (!["darwin", "win32", "linux"].includes(platform)) return false;
+  if (platform === "linux" && !process.env.DISPLAY) return false;
+
+  try {
+    if (platform === "darwin") return enableMacOS(cliPath);
+    if (platform === "win32") return enableWindows(cliPath);
+    if (platform === "linux") return enableLinux(cliPath);
+  } catch (err) {
+    // Silent fail — autostart is optional
+  }
+  return false;
+}
+
+/**
+ * Disable auto startup
+ * @returns {boolean} success
+ */
+function disableAutoStart() {
+  const platform = process.platform;
+  try {
+    if (platform === "darwin") return disableMacOS();
+    if (platform === "win32") return disableWindows();
+    if (platform === "linux") return disableLinux();
+  } catch (err) {}
+  return false;
+}
+
+/**
+ * Check if autostart is enabled.
+ *
+ * On macOS, both the plist file and the launchd registration must be present —
+ * otherwise the tray menu would lie about the state (showing "✓ Enabled" even
+ * when launchd has the agent in a failed state or hasn't loaded it).
+ */
+function isAutoStartEnabled() {
+  const platform = process.platform;
+
+  try {
+    if (platform === "darwin") {
+      const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", `${APP_LABEL}.plist`);
+      if (!fs.existsSync(plistPath)) return false;
+      try {
+        execSync(`launchctl list ${APP_LABEL}`, {
+          stdio: ["ignore", "ignore", "ignore"],
+          timeout: 3000
+        });
+        return true;
+      } catch (e) {
+        return false;
+      }
+    } else if (platform === "win32") {
+      const startupPath = path.join(process.env.APPDATA || "", "Microsoft", "Windows", "Start Menu", "Programs", "Startup", `${APP_NAME}.vbs`);
+      return fs.existsSync(startupPath);
+    } else if (platform === "linux") {
+      const desktopPath = path.join(os.homedir(), ".config", "autostart", `${APP_NAME}.desktop`);
+      return fs.existsSync(desktopPath);
+    }
+  } catch (e) {}
+  return false;
+}
+
+// ============ macOS ============
+
+/**
+ * Returns true when the current Node process IS the running instance that
+ * launchd is managing under our agent label.
+ *
+ * `launchctl unload <plist>` (and `load`) for an Aqua user-domain agent sends
+ * SIGTERM to the running process. When the running 9router cli.js was itself
+ * spawned by the autostart launchd agent (i.e. user enabled autostart at
+ * some point, then rebooted, then clicked the tray icon's "Disable
+ * Auto-start" menu item), an unload would kill the very process executing
+ * the click handler — and the tray icon would disappear instead of the menu
+ * label flipping back to "Enable Auto-start". This helper lets the enable
+ * and disable paths sidestep that by skipping launchctl when we'd otherwise
+ * be killing ourselves.
+ */
+function isAgentSelfMacOS() {
+  try {
+    const output = execSync(`launchctl list ${APP_LABEL}`, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000
+    });
+    const match = output.match(/"PID"\s*=\s*(\d+)/);
+    return !!(match && parseInt(match[1], 10) === process.pid);
+  } catch (e) {
+    return false;
+  }
+}
+
+function enableMacOS(cliPath) {
+  const launchAgentsDir = path.join(os.homedir(), "Library", "LaunchAgents");
+  const plistPath = path.join(launchAgentsDir, `${APP_LABEL}.plist`);
+
+  if (!fs.existsSync(launchAgentsDir)) {
+    fs.mkdirSync(launchAgentsDir, { recursive: true });
+  }
+
+  const nodePath = process.execPath;
+  const routerScript = getCliJsPath(cliPath);
+  // Don't write a broken plist that references a non-existent script.
+  if (!routerScript) return false;
+
+  // Invoke node + cli.js directly with absolute paths — no shell wrapper.
+  // The previous design ran `zsh -l -c "..."` so a login shell would source
+  // nvm/.zshrc and set PATH; that's fragile (nvm.sh sourcing varies by user,
+  // some setups don't put node on PATH from a non-interactive login shell).
+  // EnvironmentVariables.PATH explicitly includes node's bin dir so child
+  // processes spawned by cli.js (npm install at runtime, etc.) resolve.
+  const launchPath = `${path.dirname(nodePath)}:/usr/local/bin:/usr/bin:/bin`;
+
+  const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${APP_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${nodePath}</string>
+        <string>${routerScript}</string>
+        <string>--tray</string>
+        <string>--skip-update</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>${launchPath}</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <false/>
+    <key>StandardOutPath</key>
+    <string>/tmp/9router.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/9router.error.log</string>
+</dict>
+</plist>`;
+
+  fs.writeFileSync(plistPath, plistContent);
+
+  // If we're the running agent already, launchctl unload/load would send
+  // ourselves SIGTERM. Skip it — the plist file is updated on disk and
+  // launchd will pick it up at next login. isAutoStartEnabled() will still
+  // return true because launchctl already has the agent loaded.
+  if (isAgentSelfMacOS()) {
+    return true;
+  }
+
+  // Register with launchd in the current session. Without this, the agent
+  // only takes effect on the next user login and the user has no signal that
+  // anything actually happened. `unload` first defends against re-enable
+  // replacing an existing plist.
+  try {
+    execSync(`launchctl unload "${plistPath}"`, { stdio: "ignore" });
+  } catch (e) {}
+  try {
+    execSync(`launchctl load -w "${plistPath}"`, { stdio: "ignore" });
+  } catch (e) {
+    // Even if load fails, the plist is on disk and will be picked up at next
+    // login; report success based on the file write.
+  }
+  return true;
+}
+
+function disableMacOS() {
+  const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", `${APP_LABEL}.plist`);
+
+  // Don't kill ourselves: when the current process is the running agent,
+  // `launchctl unload` would send SIGTERM and the user clicking
+  // "Disable Auto-start" from the tray menu would lose their tray icon
+  // instead of just flipping the menu label. Skip the unload — removing the
+  // plist file is enough to prevent the agent from starting on next login.
+  if (!isAgentSelfMacOS()) {
+    try {
+      execSync(`launchctl unload "${plistPath}"`, { stdio: "ignore" });
+    } catch (e) {}
+  }
+
+  if (fs.existsSync(plistPath)) {
+    fs.unlinkSync(plistPath);
+  }
+  return true;
+}
+
+// ============ Windows ============
+
+function enableWindows(cliPath) {
+  const startupDir = path.join(process.env.APPDATA || "", "Microsoft", "Windows", "Start Menu", "Programs", "Startup");
+  const vbsPath = path.join(startupDir, `${APP_NAME}.vbs`);
+
+  if (!fs.existsSync(startupDir)) return false;
+
+  const nodePath = process.execPath;
+  const routerScript = getCliJsPath(cliPath);
+  if (!routerScript) return false;
+
+  // Run node + cli.js directly, hidden window. Avoids the fragile
+  // `9router.cmd` lookup that depended on the npm prefix path.
+  const vbsContent = `Set WshShell = CreateObject("WScript.Shell")
+WshShell.Run """${nodePath}"" ""${routerScript}"" --tray --skip-update", 0, False
+`;
+  fs.writeFileSync(vbsPath, vbsContent);
+  return true;
+}
+
+function disableWindows() {
+  const vbsPath = path.join(process.env.APPDATA || "", "Microsoft", "Windows", "Start Menu", "Programs", "Startup", `${APP_NAME}.vbs`);
+  if (fs.existsSync(vbsPath)) {
+    fs.unlinkSync(vbsPath);
+  }
+  return true;
+}
+
+// ============ Linux ============
+
+function enableLinux(cliPath) {
+  const autostartDir = path.join(os.homedir(), ".config", "autostart");
+  const desktopPath = path.join(autostartDir, `${APP_NAME}.desktop`);
+
+  if (!fs.existsSync(autostartDir)) {
+    try { fs.mkdirSync(autostartDir, { recursive: true }); }
+    catch (e) { return false; }
+  }
+
+  const nodePath = process.execPath;
+  const routerScript = getCliJsPath(cliPath);
+  if (!routerScript) return false;
+
+  const desktopContent = `[Desktop Entry]
+Type=Application
+Name=9Router
+Comment=9Router API Proxy
+Exec=${nodePath} ${routerScript} --tray --skip-update
+Hidden=false
+NoDisplay=false
+X-GNOME-Autostart-enabled=true
+`;
+  fs.writeFileSync(desktopPath, desktopContent);
+  return true;
+}
+
+function disableLinux() {
+  const desktopPath = path.join(os.homedir(), ".config", "autostart", `${APP_NAME}.desktop`);
+  if (fs.existsSync(desktopPath)) {
+    fs.unlinkSync(desktopPath);
+  }
+  return true;
+}
+
+module.exports = {
+  enableAutoStart,
+  disableAutoStart,
+  isAutoStartEnabled
+};
diff --git a/cli/src/cli/tray/icon.ico b/cli/src/cli/tray/icon.ico
new file mode 100644
index 0000000..9cf0e3d
Binary files /dev/null and b/cli/src/cli/tray/icon.ico differ
diff --git a/cli/src/cli/tray/icon.png b/cli/src/cli/tray/icon.png
new file mode 100644
index 0000000..55bf515
Binary files /dev/null and b/cli/src/cli/tray/icon.png differ
diff --git a/cli/src/cli/tray/tray.js b/cli/src/cli/tray/tray.js
new file mode 100644
index 0000000..6658e94
--- /dev/null
+++ b/cli/src/cli/tray/tray.js
@@ -0,0 +1,322 @@
+const { exec } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+let trayInstance = null;
+let isWinTray = false;
+
+/**
+ * Get icon base64 from file — used for systray (mac/linux)
+ */
+function getIconBase64() {
+  const isWin = process.platform === "win32";
+  const iconFile = isWin ? "icon.ico" : "icon.png";
+  try {
+    const iconPath = path.join(__dirname, iconFile);
+    if (fs.existsSync(iconPath)) {
+      return fs.readFileSync(iconPath).toString("base64");
+    }
+  } catch (e) {}
+  // Fallback: minimal green dot icon (PNG)
+  return "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABGdBTUEAALGPC/xhBQAAAAlwSFlzAAALEwAACxMBAJqcGAAAAHpJREFUOE9jYBgFgwEwMjIy/Gdg+P8fyP4PxP8ZGBgEcBnGyMjIsICBgSEAhyH/gfgBUNN8XJoZsdkCVL8Ah+b/QPwbqvkBMvk/AwMDAzYX/GdgYAhAN+A/SICRWAMYGfFEJSMjzriEiwDR/xmIa2RkZCSqnZERb3QCAAo3KxzxbKe1AAAAAElFTkSuQmCC";
+}
+
+/**
+ * Check if system tray is supported on current OS
+ * Supported: macOS, Windows, Linux (with GUI)
+ */
+function isTraySupported() {
+  const platform = process.platform;
+  if (!["darwin", "win32", "linux"].includes(platform)) {
+    return false;
+  }
+  if (platform === "linux" && !process.env.DISPLAY) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Initialize system tray with menu
+ * @param {Object} options - { port, onQuit, onOpenDashboard }
+ * @returns {Object|null} tray instance or null if not supported/failed
+ */
+function initTray(options) {
+  if (!isTraySupported()) {
+    return null;
+  }
+
+  // Windows uses PowerShell NotifyIcon (AV-safe), others use systray
+  if (process.platform === "win32") {
+    return initWindowsTray(options);
+  }
+  return initUnixTray(options);
+}
+
+/**
+ * Build menu items array shared between platforms
+ */
+function buildMenuItems(port, autostartEnabled) {
+  return [
+    { title: `9Router (Port ${port})`, tooltip: "Server is running", enabled: false },
+    { title: "Open Dashboard", tooltip: "Open in browser", enabled: true },
+    {
+      title: autostartEnabled ? "✓ Auto-start Enabled" : "Enable Auto-start",
+      tooltip: "Run on OS startup",
+      enabled: true
+    },
+    { title: "Quit", tooltip: "Stop server and exit", enabled: true }
+  ];
+}
+
+// Menu item indexes
+const MENU_INDEX = { STATUS: 0, DASHBOARD: 1, AUTOSTART: 2, QUIT: 3 };
+
+/**
+ * Get current autostart state
+ */
+function getAutostartEnabled() {
+  try {
+    const { isAutoStartEnabled } = require("./autostart");
+    return isAutoStartEnabled();
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Handle menu item click (shared logic)
+ */
+function handleClick(index, options, onAutostartToggle) {
+  const { onQuit, onOpenDashboard, port } = options;
+  if (index === MENU_INDEX.DASHBOARD) {
+    if (onOpenDashboard) onOpenDashboard();
+    else openBrowser(`http://localhost:${port}/dashboard`);
+  } else if (index === MENU_INDEX.AUTOSTART) {
+    const enabled = getAutostartEnabled();
+    try {
+      const { enableAutoStart, disableAutoStart } = require("./autostart");
+      if (enabled) disableAutoStart();
+      else enableAutoStart();
+      onAutostartToggle(!enabled);
+    } catch (e) {}
+  } else if (index === MENU_INDEX.QUIT) {
+    console.log("\n👋 Shutting down...");
+    if (onQuit) onQuit();
+    killTray();
+    setTimeout(() => process.exit(0), 500);
+  }
+}
+
+/**
+ * Windows tray via PowerShell NotifyIcon
+ */
+function initWindowsTray(options) {
+  const { port } = options;
+  try {
+    const { initWinTray } = require("./trayWin");
+    const iconPath = path.join(__dirname, "icon.ico");
+    const autostartEnabled = getAutostartEnabled();
+    const items = buildMenuItems(port, autostartEnabled);
+
+    trayInstance = initWinTray({
+      iconPath,
+      tooltip: `9Router - Port ${port}`,
+      items,
+      onClick: (index) => {
+        handleClick(index, options, (newEnabled) => {
+          const newTitle = newEnabled ? "✓ Auto-start Enabled" : "Enable Auto-start";
+          trayInstance.updateItem(MENU_INDEX.AUTOSTART, newTitle, true);
+        });
+      }
+    });
+
+    isWinTray = true;
+    return trayInstance;
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * macOS/Linux tray via systray binary
+ *
+ * Prefers `systray2` (active fork of `systray`, ships newer
+ * getlantern/systray-portable binaries that work on macOS 14+ and Apple
+ * Silicon under Rosetta). Falls back to legacy `systray@1.0.5` if systray2
+ * is not available, though that binary's Mach-O headers are rejected by
+ * modern dyld and the icon will not appear.
+ */
+function resolveSystray() {
+  let runtimeDir = null;
+  try {
+    const { getRuntimeNodeModules } = require("../../../hooks/sqliteRuntime");
+    runtimeDir = getRuntimeNodeModules();
+  } catch (e) {}
+
+  // 1) systray2 in runtime dir (where ensureTrayRuntime installs it)
+  if (runtimeDir) {
+    try { return { mod: require(path.join(runtimeDir, "systray2")).default, isV2: true }; } catch (e) {}
+  }
+  // 2) systray2 resolvable from the package's own node_modules / NODE_PATH
+  try { return { mod: require("systray2").default, isV2: true }; } catch (e) {}
+  // 3) Legacy systray fallback (unlikely to render on modern macOS)
+  try { return { mod: require("systray").default, isV2: false }; } catch (e) {}
+  if (runtimeDir) {
+    try { return { mod: require(path.join(runtimeDir, "systray")).default, isV2: false }; } catch (e) {}
+  }
+  return null;
+}
+
+function chmodTrayBin(pkgName) {
+  // systray2's npm tarball occasionally lands without +x on the bundled Go
+  // binary (observed on macOS). spawn() then fails with EACCES. Best-effort
+  // chmod on every init avoids a hard-to-diagnose silent tray failure.
+  try {
+    const { getRuntimeNodeModules } = require("../../../hooks/sqliteRuntime");
+    const binName = process.platform === "darwin" ? "tray_darwin_release" : "tray_linux_release";
+    const candidates = [
+      path.join(getRuntimeNodeModules(), pkgName, "traybin", binName),
+      path.join(__dirname, "..", "..", "..", "node_modules", pkgName, "traybin", binName)
+    ];
+    for (const p of candidates) {
+      if (fs.existsSync(p)) fs.chmodSync(p, 0o755);
+    }
+  } catch (e) {}
+}
+
+function initUnixTray(options) {
+  const { port } = options;
+  try {
+    const resolved = resolveSystray();
+    if (!resolved) return null;
+    const { mod: SysTray, isV2 } = resolved;
+
+    chmodTrayBin(isV2 ? "systray2" : "systray");
+
+    const autostartEnabled = getAutostartEnabled();
+    const items = buildMenuItems(port, autostartEnabled);
+
+    const menu = {
+      icon: getIconBase64(),
+      // The bundled icon.png is a full-color RGBA logo. Don't mark it as a
+      // template icon: macOS would then render it as a solid white square
+      // because template mode only uses the alpha channel.
+      isTemplateIcon: false,
+      title: "",
+      tooltip: `9Router - Port ${port}`,
+      items
+    };
+
+    trayInstance = new SysTray({ menu, debug: false, copyDir: true });
+    isWinTray = false;
+
+    trayInstance.onClick((action) => {
+      handleClick(action.seq_id, options, (newEnabled) => {
+        trayInstance.sendAction({
+          type: "update-item",
+          item: {
+            title: newEnabled ? "✓ Auto-start Enabled" : "Enable Auto-start",
+            tooltip: "Run on OS startup",
+            enabled: true
+          },
+          seq_id: MENU_INDEX.AUTOSTART
+        });
+      });
+    });
+
+    if (isV2) {
+      // systray2 exposes a ready() promise instead of onReady/onError. Surface
+      // failures (binary crash, EACCES, etc.) so users can see why the icon
+      // didn't appear instead of getting a misleading "running in tray" log.
+      trayInstance.ready().catch((err) => {
+        process.stderr.write(`[9router] tray failed to start: ${err && err.message ? err.message : err}\n`);
+      });
+    } else {
+      trayInstance.onReady(() => {});
+      trayInstance.onError(() => {});
+    }
+
+    return trayInstance;
+  } catch (err) {
+    process.stderr.write(`[9router] tray init error: ${err.message}\n`);
+    return null;
+  }
+}
+
+/**
+ * Kill tray, wait Go binary fully exit (returns Promise).
+ * Critical for hide-to-tray: macOS must release NSStatusItem before bgProcess
+ * spawns a new tray, otherwise the new icon silently fails to register.
+ */
+function killTray() {
+  const instance = trayInstance;
+  const wasWin = isWinTray;
+  trayInstance = null;
+  if (!instance) return Promise.resolve();
+
+  if (wasWin) {
+    try { instance.kill(); } catch (e) {}
+    return Promise.resolve();
+  }
+
+  // Unix: get the Go tray child process handle.
+  let proc = null;
+  try {
+    proc = instance._process || (typeof instance.process === "function" ? instance.process() : null);
+  } catch (e) {}
+
+  // Graceful shutdown: send {type:"exit"} via IPC so the Go binary can call
+  // systray.Quit() and release NSStatusItem. SIGKILL leaves a ghost icon on
+  // the macOS menubar until logout, causing duplicate icons after re-spawn.
+  const gracefulQuit = () => { try { instance.kill(true); } catch (e) {} };
+  const closeIpc = () => { try { instance.kill(false); } catch (e) {} };
+
+  if (!proc || !proc.pid) {
+    gracefulQuit();
+    closeIpc();
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = () => { if (done) return; done = true; closeIpc(); resolve(); };
+
+    proc.once("exit", finish);
+    gracefulQuit();
+
+    // Escalate: SIGTERM after 800ms, SIGKILL after 1600ms if still alive.
+    setTimeout(() => { try { process.kill(proc.pid, 0); proc.kill("SIGTERM"); } catch (e) {} }, 800);
+    setTimeout(() => { try { process.kill(proc.pid, 0); proc.kill("SIGKILL"); } catch (e) {} }, 1600);
+
+    // Fallback poll in case "exit" never fires (detached child, pipe closed)
+    const deadline = Date.now() + 3000;
+    const poll = setInterval(() => {
+      try { process.kill(proc.pid, 0); } catch { clearInterval(poll); finish(); return; }
+      if (Date.now() > deadline) { clearInterval(poll); finish(); }
+    }, 50);
+  });
+}
+
+/**
+ * Open browser
+ */
+function openBrowser(url) {
+  const platform = process.platform;
+  let cmd;
+
+  if (platform === "darwin") {
+    cmd = `open "${url}"`;
+  } else if (platform === "win32") {
+    cmd = `start "" "${url}"`;
+  } else {
+    cmd = `xdg-open "${url}"`;
+  }
+
+  exec(cmd);
+}
+
+module.exports = {
+  initTray,
+  killTray
+};
diff --git a/cli/src/cli/tray/tray.ps1 b/cli/src/cli/tray/tray.ps1
new file mode 100644
index 0000000..bc55f39
--- /dev/null
+++ b/cli/src/cli/tray/tray.ps1
@@ -0,0 +1,130 @@
+# 9Router tray icon for Windows using NotifyIcon
+# IPC: stdin JSON commands, stdout JSON events
+param([string]$IconPath, [string]$Tooltip)
+
+$ErrorActionPreference = "Stop"
+
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+
+public static class WinDpiAwareness {
+  public static IntPtr PerMonitorAwareV2 { get { return new IntPtr(-4); } }
+  public static IntPtr PerMonitorAware { get { return new IntPtr(-3); } }
+
+  [DllImport("user32.dll")]
+  public static extern bool SetProcessDpiAwarenessContext(IntPtr value);
+
+  [DllImport("user32.dll")]
+  public static extern IntPtr SetThreadDpiAwarenessContext(IntPtr value);
+
+  [DllImport("shcore.dll")]
+  public static extern int SetProcessDpiAwareness(int value);
+
+  [DllImport("user32.dll")]
+  public static extern bool SetProcessDPIAware();
+}
+"@
+
+function Enable-HighDpiAwareness {
+  $contexts = @(
+    [WinDpiAwareness]::PerMonitorAwareV2,
+    [WinDpiAwareness]::PerMonitorAware
+  )
+
+  foreach ($context in $contexts) {
+    try {
+      if ([WinDpiAwareness]::SetProcessDpiAwarenessContext($context)) { break }
+    } catch {}
+  }
+
+  try { [WinDpiAwareness]::SetProcessDpiAwareness(2) | Out-Null } catch {}
+  try { [WinDpiAwareness]::SetProcessDPIAware() | Out-Null } catch {}
+
+  foreach ($context in $contexts) {
+    try {
+      $previous = [WinDpiAwareness]::SetThreadDpiAwarenessContext($context)
+      if ($previous -ne [IntPtr]::Zero) { break }
+    } catch {}
+  }
+}
+
+Enable-HighDpiAwareness
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+[Console]::InputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+
+[System.Windows.Forms.Application]::EnableVisualStyles()
+[System.Windows.Forms.Application]::SetCompatibleTextRenderingDefault($false)
+
+$script:notifyIcon = New-Object System.Windows.Forms.NotifyIcon
+$script:notifyIcon.Icon = New-Object System.Drawing.Icon($IconPath)
+$script:notifyIcon.Text = $Tooltip
+$script:notifyIcon.Visible = $true
+
+$script:menu = New-Object System.Windows.Forms.ContextMenuStrip
+$script:notifyIcon.ContextMenuStrip = $script:menu
+$script:items = @()
+
+function Write-Event($obj) {
+  $json = $obj | ConvertTo-Json -Compress
+  [Console]::Out.WriteLine($json)
+  [Console]::Out.Flush()
+}
+
+function Add-MenuItem($index, $title, $enabled) {
+  $item = New-Object System.Windows.Forms.ToolStripMenuItem
+  $item.Text = $title
+  $item.Enabled = $enabled
+  $idx = $index
+  $item.Add_Click({ Write-Event @{ type = "click"; index = $idx } }.GetNewClosure())
+  $script:menu.Items.Add($item) | Out-Null
+  $script:items += $item
+}
+
+function Update-MenuItem($index, $title, $enabled) {
+  if ($index -lt $script:items.Count) {
+    $script:items[$index].Text = $title
+    $script:items[$index].Enabled = $enabled
+  }
+}
+
+function Set-Tooltip($text) {
+  # NotifyIcon.Text max 63 chars
+  if ($text.Length -gt 63) { $text = $text.Substring(0, 63) }
+  $script:notifyIcon.Text = $text
+}
+
+# Background reader thread polls stdin via timer on UI thread
+$script:timer = New-Object System.Windows.Forms.Timer
+$script:timer.Interval = 100
+$script:timer.Add_Tick({
+  try {
+    while ([Console]::In.Peek() -ne -1) {
+      $line = [Console]::In.ReadLine()
+      if ([string]::IsNullOrWhiteSpace($line)) { continue }
+      $cmd = $line | ConvertFrom-Json
+      switch ($cmd.action) {
+        "add-item"    { Add-MenuItem $cmd.index $cmd.title $cmd.enabled }
+        "update-item" { Update-MenuItem $cmd.index $cmd.title $cmd.enabled }
+        "set-tooltip" { Set-Tooltip $cmd.text }
+        "ready"       { Write-Event @{ type = "ready" } }
+        "kill"        {
+          $script:notifyIcon.Visible = $false
+          $script:notifyIcon.Dispose()
+          [System.Windows.Forms.Application]::Exit()
+        }
+      }
+    }
+  } catch {
+    Write-Event @{ type = "error"; message = $_.Exception.Message }
+  }
+})
+$script:timer.Start()
+
+Write-Event @{ type = "started" }
+[System.Windows.Forms.Application]::Run()
diff --git a/cli/src/cli/tray/trayWin.js b/cli/src/cli/tray/trayWin.js
new file mode 100644
index 0000000..8c11280
--- /dev/null
+++ b/cli/src/cli/tray/trayWin.js
@@ -0,0 +1,89 @@
+const { spawn } = require("child_process");
+const path = require("path");
+const readline = require("readline");
+
+// PowerShell-based tray for Windows (AV-safe, zero binary deps)
+
+let psProcess = null;
+let clickHandler = null;
+
+/**
+ * Send JSON command to PowerShell tray process via stdin
+ */
+function sendCommand(cmd) {
+  if (psProcess && psProcess.stdin.writable) {
+    psProcess.stdin.write(`${JSON.stringify(cmd)}\n`, "utf8");
+  }
+}
+
+/**
+ * Initialize Windows tray using PowerShell NotifyIcon
+ * @param {Object} options - { iconPath, tooltip, items, onClick }
+ *   items: [{ title, enabled }]
+ * @returns {Object|null} controller with sendAction/kill
+ */
+function initWinTray(options) {
+  const { iconPath, tooltip, items, onClick } = options;
+  clickHandler = onClick;
+
+  const scriptPath = path.join(__dirname, "tray.ps1");
+
+  try {
+    psProcess = spawn(
+      "powershell.exe",
+      [
+        "-NoProfile",
+        "-ExecutionPolicy", "Bypass",
+        "-WindowStyle", "Hidden",
+        "-InputFormat", "Text",
+        "-OutputFormat", "Text",
+        "-File", scriptPath,
+        "-IconPath", iconPath,
+        "-Tooltip", tooltip
+      ],
+      { windowsHide: true, stdio: ["pipe", "pipe", "pipe"] }
+    );
+  } catch (err) {
+    return null;
+  }
+
+  const rl = readline.createInterface({ input: psProcess.stdout });
+  rl.on("line", (line) => {
+    try {
+      const evt = JSON.parse(line);
+      if (evt.type === "click" && clickHandler) {
+        clickHandler(evt.index);
+      }
+    } catch (e) {}
+  });
+
+  psProcess.on("error", () => {});
+  psProcess.stderr.on("data", () => {});
+
+  // Send initial menu items
+  items.forEach((item, index) => {
+    sendCommand({ action: "add-item", index, title: item.title, enabled: item.enabled });
+  });
+
+  return {
+    updateItem(index, title, enabled) {
+      sendCommand({ action: "update-item", index, title, enabled });
+    },
+    setTooltip(text) {
+      sendCommand({ action: "set-tooltip", text });
+    },
+    kill() {
+      try {
+        sendCommand({ action: "kill" });
+      } catch (e) {}
+      setTimeout(() => {
+        if (psProcess && !psProcess.killed) {
+          try { psProcess.kill(); } catch (e) {}
+        }
+        psProcess = null;
+      }, 300);
+    }
+  };
+}
+
+module.exports = { initWinTray };
diff --git a/cli/src/cli/utils/clipboard.js b/cli/src/cli/utils/clipboard.js
new file mode 100644
index 0000000..c9cc5b5
--- /dev/null
+++ b/cli/src/cli/utils/clipboard.js
@@ -0,0 +1,30 @@
+const { execSync } = require("child_process");
+
+/**
+ * Copy text to clipboard based on OS
+ * @param {string} text - Text to copy
+ * @returns {boolean} Success status
+ */
+function copyToClipboard(text) {
+  try {
+    const platform = process.platform;
+    
+    if (platform === "darwin") {
+      execSync("pbcopy", { input: text });
+    } else if (platform === "win32") {
+      execSync("clip", { input: text });
+    } else {
+      // Linux - try xclip first, then xsel
+      try {
+        execSync("xclip -selection clipboard", { input: text });
+      } catch {
+        execSync("xsel --clipboard --input", { input: text });
+      }
+    }
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+module.exports = { copyToClipboard };
diff --git a/cli/src/cli/utils/display.js b/cli/src/cli/utils/display.js
new file mode 100644
index 0000000..a68d830
--- /dev/null
+++ b/cli/src/cli/utils/display.js
@@ -0,0 +1,156 @@
+const { formatNumber } = require("./format");
+
+// ANSI color codes
+const COLORS = {
+  reset: "\x1b[0m",
+  success: "\x1b[32m",
+  error: "\x1b[31m",
+  warning: "\x1b[33m",
+  info: "\x1b[36m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  bright: "\x1b[1m",
+  cyan: "\x1b[36m"
+};
+
+// Box drawing characters
+const BOX_CHARS = {
+  topLeft: "┌",
+  topRight: "┐",
+  bottomLeft: "└",
+  bottomRight: "┘",
+  horizontal: "─",
+  vertical: "│"
+};
+
+/**
+ * Draw a box with border around content
+ * @param {string} title - Box title
+ * @param {string} content - Content to display inside box
+ * @param {number} [width=60] - Box width
+ */
+function showBox(title, content, width = 60) {
+  const innerWidth = width - 4;
+  const lines = content.split("\n");
+
+  // Top border with title
+  const topBorder = BOX_CHARS.topLeft + BOX_CHARS.horizontal.repeat(2) + 
+    ` ${title} ` + 
+    BOX_CHARS.horizontal.repeat(Math.max(0, innerWidth - title.length - 3)) + 
+    BOX_CHARS.topRight;
+
+  console.log(topBorder);
+
+  // Content lines
+  lines.forEach(line => {
+    const paddedLine = line.padEnd(innerWidth);
+    console.log(`${BOX_CHARS.vertical} ${paddedLine} ${BOX_CHARS.vertical}`);
+  });
+
+  // Bottom border
+  const bottomBorder = BOX_CHARS.bottomLeft + 
+    BOX_CHARS.horizontal.repeat(innerWidth + 2) + 
+    BOX_CHARS.bottomRight;
+
+  console.log(bottomBorder);
+}
+
+/**
+ * Display a menu with numbered items
+ * @param {string} title - Menu title
+ * @param {string[]} items - Array of menu items
+ * @param {string} [footer] - Optional footer text
+ */
+function showMenu(title, items, footer) {
+  console.log(`\n${COLORS.bold}${title}${COLORS.reset}`);
+  console.log(COLORS.dim + "─".repeat(title.length) + COLORS.reset);
+
+  items.forEach((item, index) => {
+    console.log(`  ${COLORS.info}${index + 1}.${COLORS.reset} ${item}`);
+  });
+
+  if (footer) {
+    console.log(`\n${COLORS.dim}${footer}${COLORS.reset}`);
+  }
+  console.log();
+}
+
+/**
+ * Display data in table format
+ * @param {string[]} headers - Array of column headers
+ * @param {Array<Array<string|number>>} rows - Array of row data
+ */
+function showTable(headers, rows) {
+  if (!headers.length || !rows.length) {
+    return;
+  }
+
+  // Calculate column widths
+  const colWidths = headers.map((header, i) => {
+    const maxDataWidth = Math.max(...rows.map(row => String(row[i] || "").length));
+    return Math.max(header.length, maxDataWidth);
+  });
+
+  // Print header
+  const headerRow = headers.map((h, i) => h.padEnd(colWidths[i])).join(" │ ");
+  console.log(COLORS.bold + headerRow + COLORS.reset);
+
+  // Print separator
+  const separator = colWidths.map(w => "─".repeat(w)).join("─┼─");
+  console.log(COLORS.dim + separator + COLORS.reset);
+
+  // Print rows
+  rows.forEach(row => {
+    const rowStr = row.map((cell, i) => String(cell || "").padEnd(colWidths[i])).join(" │ ");
+    console.log(rowStr);
+  });
+}
+
+/**
+ * Show colored status message
+ * @param {string} message - Message to display
+ * @param {string} [type="info"] - Status type: success, error, warning, info
+ */
+function showStatus(message, type = "info") {
+  const symbols = {
+    success: "✓",
+    error: "✗",
+    warning: "⚠",
+    info: "ℹ"
+  };
+
+  const color = COLORS[type] || COLORS.info;
+  const symbol = symbols[type] || symbols.info;
+
+  console.log(`${color}${symbol} ${message}${COLORS.reset}`);
+}
+
+/**
+ * Clear the terminal screen
+ */
+function clearScreen() {
+  console.clear();
+}
+
+/**
+ * Show menu header with title and subtitle
+ * @param {string} title - Main title
+ * @param {string} subtitle - Optional subtitle
+ */
+function showHeader(title, subtitle) {
+  console.log(`\n${"=".repeat(60)}`);
+  console.log(`  ${COLORS.bright}${COLORS.cyan}${title}${COLORS.reset}`);
+  if (subtitle) {
+    console.log(`  ${COLORS.dim}${subtitle}${COLORS.reset}`);
+  }
+  console.log(`${"=".repeat(60)}\n`);
+}
+
+module.exports = {
+  showBox,
+  showMenu,
+  showTable,
+  showStatus,
+  clearScreen,
+  showHeader
+};
diff --git a/cli/src/cli/utils/endpoint.js b/cli/src/cli/utils/endpoint.js
new file mode 100644
index 0000000..20226e6
--- /dev/null
+++ b/cli/src/cli/utils/endpoint.js
@@ -0,0 +1,32 @@
+const api = require("../api/client");
+
+const COLORS = {
+  reset: "\x1b[0m",
+  green: "\x1b[32m"
+};
+
+/**
+ * Get endpoint URL based on tunnel status
+ * @param {number} port - Local server port
+ * @returns {Promise<{endpoint: string, tunnelEnabled: boolean}>}
+ */
+async function getEndpoint(port) {
+  const result = await api.getTunnelStatus();
+  const tunnelEnabled = result.success && result.data?.enabled === true;
+  const publicUrl = result.success ? result.data?.publicUrl : "";
+  
+  const endpoint = tunnelEnabled && publicUrl ? `${publicUrl}/v1` : `http://localhost:${port}/v1`;
+  return { endpoint, tunnelEnabled };
+}
+
+/**
+ * Get endpoint with color formatting
+ * @param {number} port - Local server port
+ * @returns {Promise<string>} Colored endpoint string
+ */
+async function getEndpointColored(port) {
+  const { endpoint, tunnelEnabled } = await getEndpoint(port);
+  return tunnelEnabled ? `${COLORS.green}${endpoint}${COLORS.reset}` : endpoint;
+}
+
+module.exports = { getEndpoint, getEndpointColored };
diff --git a/cli/src/cli/utils/format.js b/cli/src/cli/utils/format.js
new file mode 100644
index 0000000..5bf2ea4
--- /dev/null
+++ b/cli/src/cli/utils/format.js
@@ -0,0 +1,125 @@
+/**
+ * Truncate text with ellipsis
+ * @param {string} text - Text to truncate
+ * @param {number} maxLength - Maximum length
+ * @returns {string} Truncated text
+ */
+function truncate(text, maxLength) {
+  if (!text || text.length <= maxLength) {
+    return text;
+  }
+  return text.substring(0, maxLength - 3) + "...";
+}
+
+/**
+ * Mask API key showing only first and last characters
+ * @param {string} key - API key to mask
+ * @returns {string} Masked key
+ */
+function maskKey(key) {
+  if (!key || key.length < 8) {
+    return "***";
+  }
+  const firstChars = key.substring(0, 4);
+  const lastChars = key.substring(key.length - 4);
+  return `${firstChars}${"*".repeat(key.length - 8)}${lastChars}`;
+}
+
+/**
+ * Format date to readable string
+ * @param {Date|string|number} date - Date to format
+ * @returns {string} Formatted date string
+ */
+function formatDate(date) {
+  const d = new Date(date);
+  if (isNaN(d.getTime())) {
+    return "Invalid Date";
+  }
+
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const hours = String(d.getHours()).padStart(2, "0");
+  const minutes = String(d.getMinutes()).padStart(2, "0");
+  const seconds = String(d.getSeconds()).padStart(2, "0");
+
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
+/**
+ * Format number with commas
+ * @param {number} num - Number to format
+ * @returns {string} Formatted number
+ */
+function formatNumber(num) {
+  if (typeof num !== "number" || isNaN(num)) {
+    return "0";
+  }
+  return num.toLocaleString("en-US");
+}
+
+/**
+ * Format bytes to human readable size
+ * @param {number} bytes - Bytes to format
+ * @returns {string} Formatted size string
+ */
+function formatBytes(bytes) {
+  if (typeof bytes !== "number" || isNaN(bytes) || bytes < 0) {
+    return "0 B";
+  }
+
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let size = bytes;
+  let unitIndex = 0;
+
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex++;
+  }
+
+  return `${size.toFixed(2)} ${units[unitIndex]}`;
+}
+
+/**
+ * Get relative time string
+ * @param {Date|string|number} date - Date to compare
+ * @returns {string} Relative time string
+ */
+function getRelativeTime(date) {
+  const d = new Date(date);
+  if (isNaN(d.getTime())) {
+    return "Invalid Date";
+  }
+
+  const now = new Date();
+  const diffMs = now - d;
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHour = Math.floor(diffMin / 60);
+  const diffDay = Math.floor(diffHour / 24);
+  const diffMonth = Math.floor(diffDay / 30);
+  const diffYear = Math.floor(diffDay / 365);
+
+  if (diffSec < 60) {
+    return "just now";
+  } else if (diffMin < 60) {
+    return `${diffMin} minute${diffMin > 1 ? "s" : ""} ago`;
+  } else if (diffHour < 24) {
+    return `${diffHour} hour${diffHour > 1 ? "s" : ""} ago`;
+  } else if (diffDay < 30) {
+    return `${diffDay} day${diffDay > 1 ? "s" : ""} ago`;
+  } else if (diffMonth < 12) {
+    return `${diffMonth} month${diffMonth > 1 ? "s" : ""} ago`;
+  } else {
+    return `${diffYear} year${diffYear > 1 ? "s" : ""} ago`;
+  }
+}
+
+module.exports = {
+  truncate,
+  maskKey,
+  formatDate,
+  formatNumber,
+  formatBytes,
+  getRelativeTime
+};
diff --git a/cli/src/cli/utils/input.js b/cli/src/cli/utils/input.js
new file mode 100644
index 0000000..5761a2b
--- /dev/null
+++ b/cli/src/cli/utils/input.js
@@ -0,0 +1,156 @@
+const readline = require("readline");
+
+const COLORS = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  dim: "\x1b[2m",
+  underline: "\x1b[4m",
+  reverse: "\x1b[7m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  white: "\x1b[37m",
+  bgGreen: "\x1b[42m",
+  bgBlue: "\x1b[44m",
+  black: "\x1b[30m",
+  terracotta: "\x1b[38;2;217;119;87m",
+  bgTerracotta: "\x1b[48;2;217;119;87m"
+};
+
+// Prime stdin once globally. Toggling raw mode between menus adds latency on
+// macOS, so we keep raw mode on for the whole TUI session.
+let rawPrimed = false;
+function primeRawOnce() {
+  if (rawPrimed || !process.stdin.isTTY) return;
+  try {
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.setEncoding("utf8");
+    process.stdin.resume();
+    rawPrimed = true;
+  } catch {}
+}
+
+function suspendRawFor(fn) {
+  // Temporarily drop raw mode so readline.question can buffer line input.
+  const wasPrimed = rawPrimed;
+  if (wasPrimed && process.stdin.isTTY) {
+    try { process.stdin.setRawMode(false); } catch {}
+  }
+  return fn().finally(() => {
+    if (wasPrimed && process.stdin.isTTY) {
+      try { process.stdin.setRawMode(true); } catch {}
+      process.stdin.resume();
+    }
+  });
+}
+
+async function prompt(question) {
+  return suspendRawFor(() => new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve((answer || "").trim());
+    });
+  }));
+}
+
+async function select(question, options) {
+  console.log(question);
+  options.forEach((opt, i) => console.log(`  ${i + 1}. ${opt}`));
+  while (true) {
+    const answer = await prompt("\nSelect option (number): ");
+    const num = parseInt(answer, 10);
+    if (!isNaN(num) && num >= 1 && num <= options.length) return num - 1;
+    console.log(`Invalid selection. Please enter a number between 1 and ${options.length}`);
+  }
+}
+
+async function confirm(question) {
+  while (true) {
+    const answer = await prompt(`${question} (y/n): `);
+    const lower = answer.toLowerCase();
+    if (lower === "y" || lower === "yes") return true;
+    if (lower === "n" || lower === "no") return false;
+    console.log("Please answer 'y' or 'n'");
+  }
+}
+
+async function pause(message = "Press Enter to continue...") {
+  return suspendRawFor(() => new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(message, () => { rl.close(); resolve(); });
+  }));
+}
+
+/**
+ * Interactive arrow-key menu. Renders ★/☆ icons; selected line uses reverse+bright
+ * (no underline). Uses readline keypress + raw 'data' fallback to prevent
+ * arrow-key escape sequence leaks on macOS.
+ */
+async function selectMenu(title, items, defaultIndex = 0, subtitle = "", headerContent = "", breadcrumb = []) {
+  return new Promise((resolve) => {
+    let selectedIndex = defaultIndex;
+    let isActive = true;
+
+    primeRawOnce();
+    if (!process.stdin.isTTY) { resolve(-1); return; }
+
+    const renderMenu = () => {
+      if (!isActive) return;
+      process.stdout.write("\x1b[2J\x1b[H");
+      const width = Math.min(process.stdout.columns || 40, 40);
+      console.log(`\n${COLORS.terracotta}${"=".repeat(width)}${COLORS.reset}`);
+      console.log(`  ${COLORS.bright}${COLORS.terracotta}${title}${COLORS.reset}`);
+      if (subtitle) console.log(`  ${COLORS.dim}${subtitle}${COLORS.reset}`);
+      console.log(`${COLORS.terracotta}${"=".repeat(width)}${COLORS.reset}`);
+      if (breadcrumb.length > 0) console.log(`  ${COLORS.dim}${breadcrumb.join(" > ")}${COLORS.reset}`);
+      console.log();
+      if (headerContent) { console.log(headerContent); console.log(); }
+
+      const isWin = process.platform === "win32";
+      items.forEach((item, index) => {
+        const isSelected = index === selectedIndex;
+        const icon = isSelected ? (isWin ? ">" : "★") : (isWin ? " " : "☆");
+        if (isSelected) {
+          console.log(` ${COLORS.reverse}${COLORS.bright}${icon} ${item.label}${COLORS.reset}`);
+        } else {
+          console.log(`  ${icon} ${item.label}`);
+        }
+      });
+    };
+
+    const cleanup = () => {
+      if (!isActive) return;
+      isActive = false;
+      process.stdin.removeListener("keypress", onKeypress);
+    };
+
+    const move = (delta) => {
+      selectedIndex = (selectedIndex + delta + items.length) % items.length;
+      renderMenu();
+    };
+
+    const onKeypress = (_str, key) => {
+      if (!isActive || !key) return;
+      if (key.name === "up") return move(-1);
+      if (key.name === "down") return move(1);
+      if (key.name === "return") { cleanup(); resolve(selectedIndex); return; }
+      if (key.name === "escape") { cleanup(); resolve(-1); return; }
+      if (key.ctrl && key.name === "c") { cleanup(); process.exit(0); }
+    };
+
+    process.stdin.on("keypress", onKeypress);
+    renderMenu();
+  });
+}
+
+module.exports = {
+  prompt,
+  select,
+  confirm,
+  pause,
+  selectMenu,
+  COLORS
+};
diff --git a/cli/src/cli/utils/menuHelper.js b/cli/src/cli/utils/menuHelper.js
new file mode 100644
index 0000000..41d2906
--- /dev/null
+++ b/cli/src/cli/utils/menuHelper.js
@@ -0,0 +1,156 @@
+const { selectMenu } = require("./input");
+
+/**
+ * Show a menu with back button at top and handle selection
+ * @param {Object} config - Menu configuration
+ * @param {string} config.title - Menu title
+ * @param {string} config.headerContent - Optional header content
+ * @param {Array<{label: string, action: Function}>} config.items - Menu items with actions
+ * @param {string} config.backLabel - Back button label (default: "← Back")
+ * @param {number} config.defaultIndex - Default selected index (default: 0)
+ * @param {Function} config.refresh - Optional refresh function to call after each action
+ * @param {Array<string>} config.breadcrumb - Optional breadcrumb path
+ * @returns {Promise<void>}
+ */
+async function showMenuWithBack(config) {
+  const {
+    title,
+    headerContent = "",
+    items,
+    backLabel = "← Back",
+    defaultIndex = 0,
+    refresh = null,
+    breadcrumb = []
+  } = config;
+
+  while (true) {
+    // Call refresh if provided
+    let refreshedData = null;
+    if (refresh) {
+      refreshedData = await refresh();
+      if (refreshedData === null) {
+        // Refresh failed, exit menu
+        return;
+      }
+    }
+
+    // Build menu items with back at top
+    const menuItems = [
+      { label: backLabel, icon: "☆" },
+      ...items.map(item => ({
+        label: typeof item.label === "function" ? item.label(refreshedData) : item.label,
+        icon: "☆"
+      }))
+    ];
+
+    // Resolve headerContent if it's a function
+    const resolvedHeader = typeof headerContent === "function" 
+      ? await headerContent(refreshedData) 
+      : headerContent;
+
+    const selected = await selectMenu(
+      title,
+      menuItems,
+      defaultIndex,
+      "",
+      resolvedHeader,
+      breadcrumb
+    );
+
+    // Back or ESC
+    if (selected === -1 || selected === 0) {
+      return;
+    }
+
+    // Execute action for selected item
+    const actionIndex = selected - 1;
+    const item = items[actionIndex];
+    
+    if (item && item.action) {
+      const shouldContinue = await item.action(refreshedData);
+      // If action returns false, exit menu
+      if (shouldContinue === false) {
+        return;
+      }
+    }
+  }
+}
+
+/**
+ * Show a list menu where items are fetched dynamically
+ * @param {Object} config - Menu configuration
+ * @param {string} config.title - Menu title
+ * @param {string} config.headerContent - Optional header content
+ * @param {Function} config.fetchItems - Async function to fetch items array
+ * @param {Function} config.formatItem - Function to format each item to {label, data}
+ * @param {Function} config.onSelect - Action when item is selected
+ * @param {Object} config.createAction - Optional create action {label, action}
+ * @param {string} config.backLabel - Back button label
+ * @param {Array<string>} config.breadcrumb - Optional breadcrumb path
+ * @returns {Promise<void>}
+ */
+async function showListMenu(config) {
+  const {
+    title,
+    headerContent = "",
+    fetchItems,
+    formatItem,
+    onSelect,
+    createAction = null,
+    backLabel = "← Back",
+    breadcrumb = []
+  } = config;
+
+  while (true) {
+    // Fetch items
+    const result = await fetchItems();
+    if (!result) {
+      return;
+    }
+
+    const items = result.items || [];
+    const metadata = result.metadata || {};
+
+    // Build menu items
+    const menuItems = [{ label: backLabel, icon: "☆" }];
+    
+    if (createAction) {
+      menuItems.push({ label: createAction.label, icon: "☆" });
+    }
+
+    items.forEach(item => {
+      const formatted = formatItem(item);
+      menuItems.push({ label: formatted, icon: "☆" });
+    });
+
+    const header = typeof headerContent === "function" 
+      ? await headerContent(metadata) 
+      : headerContent;
+
+    const selected = await selectMenu(title, menuItems, 0, "", header, breadcrumb);
+
+    // Back or ESC
+    if (selected === -1 || selected === 0) {
+      return;
+    }
+
+    // Create action
+    if (createAction && selected === 1) {
+      await createAction.action();
+      continue;
+    }
+
+    // Select item
+    const offset = createAction ? 2 : 1;
+    const itemIndex = selected - offset;
+    
+    if (itemIndex >= 0 && itemIndex < items.length) {
+      await onSelect(items[itemIndex]);
+    }
+  }
+}
+
+module.exports = {
+  showMenuWithBack,
+  showListMenu
+};
diff --git a/cli/src/cli/utils/modelSelector.js b/cli/src/cli/utils/modelSelector.js
new file mode 100644
index 0000000..438220d
--- /dev/null
+++ b/cli/src/cli/utils/modelSelector.js
@@ -0,0 +1,136 @@
+const api = require("../api/client");
+const { prompt } = require("./input");
+const { clearScreen } = require("./display");
+
+// Provider alias order: OAuth first, then API Key (matches ModelSelectModal)
+const PROVIDER_ALIAS_ORDER = [
+  "cc", "ag", "cx", "if", "qw", "gc", "gh", "kr",
+  "openrouter", "glm", "kimi", "minimax", "openai", "anthropic", "gemini"
+];
+
+// Alias to display name mapping
+const PROVIDER_ALIAS_NAMES = {
+  cc: "Claude Code",
+  ag: "Antigravity", 
+  cx: "OpenAI Codex",
+  if: "iFlow AI",
+  qw: "Qwen Code",
+  gc: "Gemini CLI",
+  gh: "GitHub Copilot",
+  kr: "Kiro AI",
+  openrouter: "OpenRouter",
+  glm: "GLM Coding",
+  kimi: "Kimi Coding",
+  minimax: "Minimax Coding",
+  openai: "OpenAI",
+  anthropic: "Anthropic",
+  gemini: "Gemini"
+};
+
+/**
+ * Get all available models grouped by provider + combos
+ * @returns {Promise<{combos: Array, groups: Object}>}
+ */
+async function getAvailableModelsGrouped() {
+  const result = await api.getAvailableModels();
+  if (!result.success) return { combos: [], groups: {} };
+  
+  const models = result.data?.data || [];
+  const combos = [];
+  const groups = {};
+  
+  models.forEach(m => {
+    if (m.owned_by === "combo") {
+      combos.push(m.id);
+    } else {
+      const provider = m.owned_by;
+      if (!groups[provider]) {
+        groups[provider] = [];
+      }
+      groups[provider].push(m.id);
+    }
+  });
+  
+  return { combos, groups };
+}
+
+/**
+ * Display model list and prompt for selection
+ * @param {string} title - Title to display
+ * @param {string} currentValue - Current selected value (optional)
+ * @param {Object} options - { excludeCombos?: boolean }
+ * @returns {Promise<string|null>} Selected model ID or null if cancelled
+ */
+async function selectModelFromList(title, currentValue = "", options = {}) {
+  const { excludeCombos = false } = options;
+  const { combos: rawCombos, groups } = await getAvailableModelsGrouped();
+  const combos = excludeCombos ? [] : rawCombos;
+
+  const totalModels = combos.length + Object.values(groups).flat().length;
+  if (totalModels === 0) {
+    return null;
+  }
+  
+  // Build flat list for selection
+  const allModels = [];
+  
+  // Display
+  clearScreen();
+  console.log(`\n🎯 ${title}`);
+  console.log("=".repeat(50));
+  if (currentValue) {
+    console.log(`Current: ${currentValue}\n`);
+  } else {
+    console.log();
+  }
+  
+  let idx = 1;
+  
+  // Combos first (skipped when excludeCombos is true)
+  if (combos.length > 0) {
+    console.log("[Combos]");
+    combos.forEach(combo => {
+      console.log(`  ${idx}. ${combo}`);
+      allModels.push(combo);
+      idx++;
+    });
+    console.log();
+  }
+  
+  // Provider groups in order (by alias)
+  const sortedProviders = Object.keys(groups).sort((a, b) => {
+    const idxA = PROVIDER_ALIAS_ORDER.indexOf(a);
+    const idxB = PROVIDER_ALIAS_ORDER.indexOf(b);
+    return (idxA === -1 ? 999 : idxA) - (idxB === -1 ? 999 : idxB);
+  });
+  
+  sortedProviders.forEach(provider => {
+    const providerName = PROVIDER_ALIAS_NAMES[provider] || provider;
+    console.log(`[${providerName}]`);
+    groups[provider].forEach(model => {
+      console.log(`  ${idx}. ${model}`);
+      allModels.push(model);
+      idx++;
+    });
+    console.log();
+  });
+  
+  console.log("  0. Cancel\n");
+  
+  // Prompt for number input
+  const input = await prompt("Enter number: ");
+  const num = parseInt(input, 10);
+  
+  if (isNaN(num) || num === 0 || num < 0 || num > allModels.length) {
+    return null;
+  }
+  
+  return allModels[num - 1];
+}
+
+module.exports = {
+  selectModelFromList,
+  getAvailableModelsGrouped,
+  PROVIDER_ALIAS_ORDER,
+  PROVIDER_ALIAS_NAMES
+};
diff --git a/custom-server.js b/custom-server.js
new file mode 100644
index 0000000..6e39683
--- /dev/null
+++ b/custom-server.js
@@ -0,0 +1,32 @@
+const http = require("http");
+
+const origCreate = http.createServer.bind(http);
+
+// Wrap Next standalone HTTP server: derive client IP from the TCP socket
+// (unspoofable) and strip client-supplied forwarding headers so downstream
+// rate-limiting keys on the real peer address instead of attacker-controlled XFF.
+http.createServer = (...args) => {
+  const handler = args.find((a) => typeof a === "function");
+  const rest = args.filter((a) => typeof a !== "function");
+  if (!handler) return origCreate(...args);
+  const wrapped = (req, res) => {
+    const socketIp = req.socket && req.socket.remoteAddress ? req.socket.remoteAddress : "";
+    const xff = req.headers["x-forwarded-for"];
+    const xRealIp = req.headers["x-real-ip"];
+    const viaProxy = !!(xff || xRealIp);
+    const isLoopbackProxy = socketIp === "127.0.0.1" || socketIp === "::1" || socketIp === "::ffff:127.0.0.1";
+    // Trust forwarding headers only when the TCP peer is a local reverse proxy.
+    // Direct/public sockets remain keyed by the unspoofable peer address.
+    const proxyIp = xRealIp || (xff ? String(xff).split(",")[0].trim() : "");
+    const ip = isLoopbackProxy && proxyIp ? proxyIp : socketIp;
+    delete req.headers["x-9r-real-ip"];
+    delete req.headers["x-forwarded-for"];
+    delete req.headers["x-9r-via-proxy"];
+    req.headers["x-9r-real-ip"] = ip;
+    if (viaProxy) req.headers["x-9r-via-proxy"] = "1";
+    return handler(req, res);
+  };
+  return origCreate(...rest, wrapped);
+};
+
+require("./server.js");
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..8331b26
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,30 @@
+services:
+  9router:
+    image: decolua/9router:latest
+    container_name: 9router
+    restart: always
+    ports:
+      - "20128:20128"
+    volumes:
+      - 9router-data:/app/data
+    env_file:
+      - .env
+    environment:
+      DATA_DIR: /app/data
+      PORT: "20128"
+      HOSTNAME: "0.0.0.0"
+      NODE_ENV: production
+      HEADROOM_URL: http://headroom:8787
+    depends_on:
+      - headroom
+
+  headroom:
+    image: ghcr.io/chopratejas/headroom:latest
+    container_name: headroom
+    restart: always
+    ports:
+      - "8787:8787"
+
+volumes:
+  9router-data:
+    name: 9router-data
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..548c319
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,557 @@
+# 9Router Architecture
+
+_Last updated: 2026-02-06_
+
+## Executive Summary
+
+9Router is a local AI routing gateway and dashboard built on Next.js.
+It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
+
+Core capabilities:
+
+- OpenAI-compatible API surface for CLI/tools
+- Request/response translation across provider formats
+- Model combo fallback (multi-model sequence)
+- Account-level fallback (multi-account per provider)
+- OAuth + API-key provider connection management
+- Local persistence for providers, keys, aliases, combos, settings, pricing
+- Usage/cost tracking and request logging
+- Optional cloud sync for multi-device/state sync
+
+Primary runtime model:
+
+- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
+- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
+
+## Scope and Boundaries
+
+### In Scope
+
+- Local gateway runtime
+- Dashboard management APIs
+- Provider authentication and token refresh
+- Request translation and SSE streaming
+- Local state + usage persistence
+- Optional cloud sync orchestration
+
+### Out of Scope
+
+- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
+- Provider SLA/control plane outside local process
+- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
+
+## High-Level System Context
+
+```mermaid
+flowchart LR
+    subgraph Clients[Developer Clients]
+        C1[Claude Code]
+        C2[Codex CLI]
+        C3[OpenClaw / Droid / Cline / Continue / Roo]
+        C4[Custom OpenAI-compatible clients]
+        BROWSER[Browser Dashboard]
+    end
+
+    subgraph Router[9Router Local Process]
+        API[V1 Compatibility API\n/v1/*]
+        DASH[Dashboard + Management API\n/api/*]
+        CORE[SSE + Translation Core\nopen-sse + src/sse]
+        DB[(db.json)]
+        UDB[(usage.json + log.txt)]
+    end
+
+    subgraph Upstreams[Upstream Providers]
+        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
+        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax]
+        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
+    end
+
+    subgraph Cloud[Optional Cloud Sync]
+        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
+    end
+
+    C1 --> API
+    C2 --> API
+    C3 --> API
+    C4 --> API
+    BROWSER --> DASH
+
+    API --> CORE
+    DASH --> DB
+    CORE --> DB
+    CORE --> UDB
+
+    CORE --> P1
+    CORE --> P2
+    CORE --> P3
+
+    DASH --> CLOUD
+```
+
+## Core Runtime Components
+
+## 1) API and Routing Layer (Next.js App Routes)
+
+Main directories:
+
+- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
+- `src/app/api/*` for management/configuration APIs
+- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
+
+Important compatibility routes:
+
+- `src/app/api/v1/chat/completions/route.js`
+- `src/app/api/v1/messages/route.js`
+- `src/app/api/v1/responses/route.js`
+- `src/app/api/v1/models/route.js`
+- `src/app/api/v1/messages/count_tokens/route.js`
+- `src/app/api/v1beta/models/route.js`
+- `src/app/api/v1beta/models/[...path]/route.js`
+
+Management domains:
+
+- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
+- Providers/connections: `src/app/api/providers*`
+- Provider nodes: `src/app/api/provider-nodes*`
+- OAuth: `src/app/api/oauth/*`
+- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
+- Usage: `src/app/api/usage/*`
+- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
+- CLI tooling helpers: `src/app/api/cli-tools/*`
+
+## 2) SSE + Translation Core
+
+Main flow modules:
+
+- Entry: `src/sse/handlers/chat.js`
+- Core orchestration: `open-sse/handlers/chatCore.js`
+- Provider execution adapters: `open-sse/executors/*`
+- Format detection/provider config: `open-sse/services/provider.js`
+- Model parse/resolve: `src/sse/services/model.js`, `open-sse/services/model.js`
+- Account fallback logic: `open-sse/services/accountFallback.js`
+- Translation registry: `open-sse/translator/index.js`
+- Stream transformations: `open-sse/utils/stream.js`, `open-sse/utils/streamHandler.js`
+- Usage extraction/normalization: `open-sse/utils/usageTracking.js`
+
+## 3) Persistence Layer
+
+Primary state DB:
+
+- `src/lib/localDb.js`
+- file: `${DATA_DIR}/db.json` (or `~/.9router/db.json` when `DATA_DIR` is unset)
+- entities: providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing
+
+Usage DB:
+
+- `src/lib/usageDb.js`
+- files: `~/.9router/usage.json`, `~/.9router/log.txt`
+- note: currently independent from `DATA_DIR`
+
+## 4) Auth + Security Surfaces
+
+- Dashboard cookie auth: `src/proxy.js`, `src/app/api/auth/login/route.js`
+- API key generation/verification: `src/shared/utils/apiKey.js`
+- Provider secrets persisted in `providerConnections` entries
+- Optional proxy support for upstream calls via env proxy variables (`open-sse/utils/proxyFetch.js`)
+
+## 5) Cloud Sync
+
+- Scheduler init: `src/lib/initCloudSync.js`, `src/shared/services/initializeCloudSync.js`
+- Periodic task: `src/shared/services/cloudSyncScheduler.js`
+- Control route: `src/app/api/sync/cloud/route.js`
+
+## Request Lifecycle (`/v1/chat/completions`)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as CLI/SDK Client
+    participant Route as /api/v1/chat/completions
+    participant Chat as src/sse/handlers/chat
+    participant Core as open-sse/handlers/chatCore
+    participant Model as Model Resolver
+    participant Auth as Credential Selector
+    participant Exec as Provider Executor
+    participant Prov as Upstream Provider
+    participant Stream as Stream Translator
+    participant Usage as usageDb
+
+    Client->>Route: POST /v1/chat/completions
+    Route->>Chat: handleChat(request)
+    Chat->>Model: parse/resolve model or combo
+
+    alt Combo model
+        Chat->>Chat: iterate combo models (handleComboChat)
+    end
+
+    Chat->>Auth: getProviderCredentials(provider)
+    Auth-->>Chat: active account + tokens/api key
+
+    Chat->>Core: handleChatCore(body, modelInfo, credentials)
+    Core->>Core: detect source format
+    Core->>Core: translate request to target format
+    Core->>Exec: execute(provider, transformedBody)
+    Exec->>Prov: upstream API call
+    Prov-->>Exec: SSE/JSON response
+    Exec-->>Core: response + metadata
+
+    alt 401/403
+        Core->>Exec: refreshCredentials()
+        Exec-->>Core: updated tokens
+        Core->>Exec: retry request
+    end
+
+    Core->>Stream: translate/normalize stream to client format
+    Stream-->>Client: SSE chunks / JSON response
+
+    Stream->>Usage: extract usage + persist history/log
+```
+
+## Combo + Account Fallback Flow
+
+```mermaid
+flowchart TD
+    A[Incoming model string] --> B{Is combo name?}
+    B -- Yes --> C[Load combo models sequence]
+    B -- No --> D[Single model path]
+
+    C --> E[Try model N]
+    E --> F[Resolve provider/model]
+    D --> F
+
+    F --> G[Select account credentials]
+    G --> H{Credentials available?}
+    H -- No --> I[Return provider unavailable]
+    H -- Yes --> J[Execute request]
+
+    J --> K{Success?}
+    K -- Yes --> L[Return response]
+    K -- No --> M{Fallback-eligible error?}
+
+    M -- No --> N[Return error]
+    M -- Yes --> O[Mark account unavailable cooldown]
+    O --> P{Another account for provider?}
+    P -- Yes --> G
+    P -- No --> Q{In combo with next model?}
+    Q -- Yes --> E
+    Q -- No --> R[Return all unavailable]
+```
+
+Fallback decisions are driven by `open-sse/services/accountFallback.js` using status codes and error-message heuristics.
+
+## OAuth Onboarding and Token Refresh Lifecycle
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Dashboard UI
+    participant OAuth as /api/oauth/[provider]/[action]
+    participant ProvAuth as Provider Auth Server
+    participant DB as localDb
+    participant Test as /api/providers/[id]/test
+    participant Exec as Provider Executor
+
+    UI->>OAuth: GET authorize or device-code
+    OAuth->>ProvAuth: create auth/device flow
+    ProvAuth-->>OAuth: auth URL or device code payload
+    OAuth-->>UI: flow data
+
+    UI->>OAuth: POST exchange or poll
+    OAuth->>ProvAuth: token exchange/poll
+    ProvAuth-->>OAuth: access/refresh tokens
+    OAuth->>DB: createProviderConnection(oauth data)
+    OAuth-->>UI: success + connection id
+
+    UI->>Test: POST /api/providers/[id]/test
+    Test->>Exec: validate credentials / optional refresh
+    Exec-->>Test: valid or refreshed token info
+    Test->>DB: update status/tokens/errors
+    Test-->>UI: validation result
+```
+
+Refresh during live traffic is executed inside `open-sse/handlers/chatCore.js` via executor `refreshCredentials()`.
+
+## Cloud Sync Lifecycle (Enable / Sync / Disable)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Endpoint Page UI
+    participant Sync as /api/sync/cloud
+    participant DB as localDb
+    participant Cloud as External Cloud Sync
+    participant Claude as ~/.claude/settings.json
+
+    UI->>Sync: POST action=enable
+    Sync->>DB: set cloudEnabled=true
+    Sync->>DB: ensure API key exists
+    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
+    Cloud-->>Sync: sync result
+    Sync->>Cloud: GET /{machineId}/v1/verify
+    Sync-->>UI: enabled + verification status
+
+    UI->>Sync: POST action=sync
+    Sync->>Cloud: POST /sync/{machineId}
+    Cloud-->>Sync: remote data
+    Sync->>DB: update newer local tokens/status
+    Sync-->>UI: synced
+
+    UI->>Sync: POST action=disable
+    Sync->>DB: set cloudEnabled=false
+    Sync->>Cloud: DELETE /sync/{machineId}
+    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
+    Sync-->>UI: disabled
+```
+
+Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
+
+## Data Model and Storage Map
+
+```mermaid
+erDiagram
+    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
+    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
+    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
+
+    SETTINGS {
+      boolean cloudEnabled
+      number stickyRoundRobinLimit
+      boolean requireLogin
+      string password_hash
+    }
+
+    PROVIDER_CONNECTION {
+      string id
+      string provider
+      string authType
+      string name
+      number priority
+      boolean isActive
+      string apiKey
+      string accessToken
+      string refreshToken
+      string expiresAt
+      string testStatus
+      string lastError
+      string rateLimitedUntil
+      json providerSpecificData
+    }
+
+    PROVIDER_NODE {
+      string id
+      string type
+      string name
+      string prefix
+      string apiType
+      string baseUrl
+    }
+
+    MODEL_ALIAS {
+      string alias
+      string targetModel
+    }
+
+    COMBO {
+      string id
+      string name
+      string[] models
+    }
+
+    API_KEY {
+      string id
+      string name
+      string key
+      string machineId
+      boolean isActive
+    }
+
+    USAGE_ENTRY {
+      string provider
+      string model
+      number prompt_tokens
+      number completion_tokens
+      string connectionId
+      string timestamp
+    }
+```
+
+Physical storage files:
+
+- main state: `${DATA_DIR}/db.json` (or `~/.9router/db.json`)
+- usage stats: `~/.9router/usage.json`
+- request log lines: `~/.9router/log.txt`
+- optional translator/request debug sessions: `<repo>/logs/...`
+
+## Deployment Topology
+
+```mermaid
+flowchart LR
+    subgraph LocalHost[Developer Host]
+        CLI[CLI Tools]
+        Browser[Dashboard Browser]
+    end
+
+    subgraph ContainerOrProcess[9Router Runtime]
+        Next[Next.js Server\nPORT=20128]
+        Core[SSE Core + Executors]
+        MainDB[(db.json)]
+        UsageDB[(usage.json/log.txt)]
+    end
+
+    subgraph External[External Services]
+        Providers[AI Providers]
+        SyncCloud[Cloud Sync Service]
+    end
+
+    CLI --> Next
+    Browser --> Next
+    Next --> Core
+    Next --> MainDB
+    Core --> MainDB
+    Core --> UsageDB
+    Core --> Providers
+    Next --> SyncCloud
+```
+
+## Module Mapping (Decision-Critical)
+
+### Route and API Modules
+
+- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
+- `src/app/api/providers*`: provider CRUD, validation, testing
+- `src/app/api/provider-nodes*`: custom compatible node management
+- `src/app/api/oauth/*`: OAuth/device-code flows
+- `src/app/api/keys*`: local API key lifecycle
+- `src/app/api/models/alias`: alias management
+- `src/app/api/combos*`: fallback combo management
+- `src/app/api/pricing`: pricing overrides for cost calculation
+- `src/app/api/usage/*`: usage and logs APIs
+- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
+- `src/app/api/cli-tools/*`: local CLI config writers/checkers
+
+### Routing and Execution Core
+
+- `src/sse/handlers/chat.js`: request parse, combo handling, account selection loop
+- `open-sse/handlers/chatCore.js`: translation, executor dispatch, retry/refresh handling, stream setup
+- `open-sse/executors/*`: provider-specific network and format behavior
+
+### Translation Registry and Format Converters
+
+- `open-sse/translator/index.js`: translator registry and orchestration
+- Request translators: `open-sse/translator/request/*`
+- Response translators: `open-sse/translator/response/*`
+- Format constants: `open-sse/translator/formats.js`
+
+### Persistence
+
+- `src/lib/localDb.js`: persistent config/state
+- `src/lib/usageDb.js`: usage history and rolling request logs
+
+## Provider Executor Coverage
+
+Specialized executors:
+
+- `antigravity`
+- `gemini-cli`
+- `github`
+- `kiro`
+- `codex`
+- `cursor`
+
+Default executor path:
+
+- all other providers (including compatible node providers) use `open-sse/executors/default.js`
+
+## Format Translation Coverage
+
+Detected source formats include:
+
+- `openai`
+- `openai-responses`
+- `claude`
+- `gemini`
+
+Target formats include:
+
+- OpenAI chat/Responses
+- Claude
+- Gemini/Gemini-CLI/Antigravity envelope
+- Kiro
+- Cursor
+
+Translations are selected dynamically based on source payload shape and provider target format.
+
+## Failure Modes and Resilience
+
+## 1) Account/Provider Availability
+
+- provider account cooldown on transient/rate/auth errors
+- account fallback before failing request
+- combo model fallback when current model/provider path is exhausted
+
+## 2) Token Expiry
+
+- pre-check and refresh with retry for refreshable providers
+- 401/403 retry after refresh attempt in core path
+
+## 3) Stream Safety
+
+- disconnect-aware stream controller
+- translation stream with end-of-stream flush and `[DONE]` handling
+- usage estimation fallback when provider usage metadata is missing
+
+## 4) Cloud Sync Degradation
+
+- sync errors are surfaced but local runtime continues
+- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
+
+## 5) Data Integrity
+
+- DB shape migration/repair for missing keys
+- corrupt JSON reset safeguards for localDb and usageDb
+
+## Observability and Operational Signals
+
+Runtime visibility sources:
+
+- console logs from `src/sse/utils/logger.js`
+- per-request usage aggregates in `usage.json`
+- textual request status log in `log.txt`
+- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true`
+- dashboard usage endpoints (`/api/usage/*`) for UI consumption
+
+## Security-Sensitive Boundaries
+
+- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
+- Initial password fallback (`INITIAL_PASSWORD`, default `123456`) must be overridden in real deployments
+- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
+- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
+- Cloud sync endpoints rely on API key auth + machine id semantics
+
+## Environment and Runtime Matrix
+
+Environment variables actively used by code:
+
+- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
+- Storage: `DATA_DIR`
+- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
+- Logging: `ENABLE_REQUEST_LOGS`
+- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
+- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants
+- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
+
+## Known Architectural Notes
+
+1. `usageDb` currently stores under `~/.9router` and does not follow `DATA_DIR`.
+2. `/api/v1/route.js` returns a static model list and is not the main models source used by `/v1/models`.
+3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
+4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
+
+## Operational Verification Checklist
+
+- Build from source: `cd /root/dev/9router && npm run build`
+- Build Docker image: `cd /root/dev/9router && docker build -t 9router .`
+- Start service and verify:
+- `GET /api/settings`
+- `GET /api/v1/models`
+- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`
diff --git a/eslint.config.mjs b/eslint.config.mjs
new file mode 100644
index 0000000..f443835
--- /dev/null
+++ b/eslint.config.mjs
@@ -0,0 +1,16 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;
diff --git a/gitbook/.gitignore b/gitbook/.gitignore
new file mode 100644
index 0000000..d972524
--- /dev/null
+++ b/gitbook/.gitignore
@@ -0,0 +1,44 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Testing
+coverage/
+
+# Next.js
+.next/
+out/
+build/
+dist/
+
+# Production
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Misc
+*.tsbuildinfo
+
+# Wrangler
+.wrangler/
+.dev.vars
diff --git a/gitbook/app/[lang]/[...slug]/page.js b/gitbook/app/[lang]/[...slug]/page.js
new file mode 100644
index 0000000..792856d
--- /dev/null
+++ b/gitbook/app/[lang]/[...slug]/page.js
@@ -0,0 +1,36 @@
+import DocsLayout from "@/components/DocsLayout";
+import DocsContent from "@/components/DocsContent";
+import { extractHeadings } from "@/utils/markdown";
+import { loadContent, getAllSlugs } from "@/lib/content";
+import { LANG_CODES, isValidLang, DEFAULT_LANG } from "@/constants/languages";
+import { notFound } from "next/navigation";
+
+export const dynamicParams = false;
+
+export async function generateStaticParams() {
+  // Build params for every (lang × slug) combination based on default language slugs.
+  const slugs = getAllSlugs(DEFAULT_LANG);
+  const params = [];
+  for (const lang of LANG_CODES) {
+    for (const slug of slugs) {
+      params.push({ lang, slug });
+    }
+  }
+  return params;
+}
+
+export default async function DocPage({ params }) {
+  const { lang, slug } = await params;
+  if (!isValidLang(lang)) notFound();
+
+  const content = loadContent(lang, slug);
+  if (!content) notFound();
+
+  const headings = extractHeadings(content);
+
+  return (
+    <DocsLayout headings={headings} lang={lang}>
+      <DocsContent content={content} />
+    </DocsLayout>
+  );
+}
diff --git a/gitbook/app/[lang]/page.js b/gitbook/app/[lang]/page.js
new file mode 100644
index 0000000..4da007c
--- /dev/null
+++ b/gitbook/app/[lang]/page.js
@@ -0,0 +1,26 @@
+import DocsLayout from "@/components/DocsLayout";
+import DocsContent from "@/components/DocsContent";
+import { extractHeadings } from "@/utils/markdown";
+import { loadContent } from "@/lib/content";
+import { LANG_CODES, isValidLang } from "@/constants/languages";
+import { notFound } from "next/navigation";
+
+export const dynamicParams = false;
+
+export async function generateStaticParams() {
+  return LANG_CODES.map(lang => ({ lang }));
+}
+
+export default async function LangHomePage({ params }) {
+  const { lang } = await params;
+  if (!isValidLang(lang)) notFound();
+
+  const content = loadContent(lang, "index") || "# 9Router Documentation\n\nContent coming soon...";
+  const headings = extractHeadings(content);
+
+  return (
+    <DocsLayout headings={headings} lang={lang}>
+      <DocsContent content={content} />
+    </DocsLayout>
+  );
+}
diff --git a/gitbook/app/globals.css b/gitbook/app/globals.css
new file mode 100644
index 0000000..8ac76c1
--- /dev/null
+++ b/gitbook/app/globals.css
@@ -0,0 +1,190 @@
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800;900&display=swap');
+@import "tailwindcss";
+
+/* Base styles */
+* {
+  box-sizing: border-box;
+}
+
+body {
+  font-family: 'Inter', system-ui, -apple-system, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  margin: 0;
+  padding: 0;
+}
+
+/* Scrollbar */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #CBD5E1;
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #E68A6E;
+}
+
+/* Code highlighting */
+pre {
+  background: #F1F5F9 !important;
+  border-radius: 8px;
+  padding: 1rem;
+  overflow-x: auto;
+}
+
+code {
+  font-family: 'Monaco', 'Menlo', 'Courier New', monospace;
+  font-size: 0.875rem;
+  line-height: 1.5;
+}
+
+/* Inline code */
+:not(pre) > code {
+  background: #F1F5F9;
+  color: #E68A6E;
+  padding: 0.125rem 0.375rem;
+  border-radius: 4px;
+  font-size: 0.875em;
+}
+
+/* Markdown content styles */
+.markdown-content h1 {
+  font-size: 2.5rem;
+  font-weight: 800;
+  color: #E68A6E;
+  /* margin-top: 2rem; */
+  margin-bottom: 1rem;
+  line-height: 1.2;
+  display: flex;
+  align-items: center;
+}
+
+.markdown-content h1 svg {
+  width: 2.5rem;
+  height: 2.5rem;
+  flex-shrink: 0;
+}
+
+.markdown-content h2 {
+  font-size: 2rem;
+  font-weight: 700;
+  color: #000000;
+  margin-top: 2rem;
+  margin-bottom: 1rem;
+  line-height: 1.3;
+  border-bottom: 1px solid #E5E7EB;
+  padding-bottom: 0.5rem;
+}
+
+.markdown-content h3 {
+  font-size: 1.5rem;
+  font-weight: 600;
+  color: #000000;
+  margin-top: 1.5rem;
+  margin-bottom: 0.75rem;
+  line-height: 1.4;
+}
+
+.markdown-content p {
+  font-size: 1.125rem;
+  line-height: 1.75;
+  margin-bottom: 1rem;
+  color: #6B7280;
+}
+
+.markdown-content ul,
+.markdown-content ol {
+  margin-left: 1.5rem;
+  margin-bottom: 1rem;
+}
+
+.markdown-content li {
+  font-size: 1.125rem;
+  line-height: 1.75;
+  margin-bottom: 0.5rem;
+  color: #6B7280;
+}
+
+.markdown-content a {
+  color: #E68A6E;
+  text-decoration: underline;
+  transition: opacity 0.2s;
+}
+
+.markdown-content a:hover {
+  opacity: 0.8;
+}
+
+.markdown-content blockquote {
+  border-left: 4px solid #E68A6E;
+  padding-left: 1rem;
+  margin: 1rem 0;
+  font-style: italic;
+  color: #6B7280;
+}
+
+.markdown-content strong {
+  font-weight: 600;
+  color: #000000;
+}
+
+/* Smooth scroll */
+html {
+  scroll-behavior: smooth;
+  scroll-padding-top: 5rem; /* Offset for sticky header (64px + padding) */
+}
+
+/* Heading anchor offset for sticky header */
+.markdown-content h1,
+.markdown-content h2,
+.markdown-content h3 {
+  scroll-margin-top: 5rem;
+}
+
+/* Mobile menu overlay */
+.mobile-menu-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.5);
+  z-index: 40;
+  animation: fadeIn 0.2s ease-out;
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+.mobile-menu-drawer {
+  position: fixed;
+  top: 0;
+  left: 0;
+  bottom: 0;
+  width: 280px;
+  background: white;
+  z-index: 50;
+  animation: slideInLeft 0.3s ease-out;
+  overflow-y: auto;
+}
+
+@keyframes slideInLeft {
+  from {
+    transform: translateX(-100%);
+  }
+  to {
+    transform: translateX(0);
+  }
+}
diff --git a/gitbook/app/layout.js b/gitbook/app/layout.js
new file mode 100644
index 0000000..aa49925
--- /dev/null
+++ b/gitbook/app/layout.js
@@ -0,0 +1,21 @@
+import { DOCS_CONFIG } from "@/constants/docsConfig";
+import "./globals.css";
+
+export const metadata = {
+  title: DOCS_CONFIG.title,
+  description: DOCS_CONFIG.description,
+};
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <head>
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+      </head>
+      <body className="bg-[#FCFBF9] text-[#6B7280]">
+        {children}
+      </body>
+    </html>
+  );
+}
diff --git a/gitbook/app/page.js b/gitbook/app/page.js
new file mode 100644
index 0000000..71df826
--- /dev/null
+++ b/gitbook/app/page.js
@@ -0,0 +1,26 @@
+import { DEFAULT_LANG } from "@/constants/languages";
+
+// Static-friendly redirect to default language (meta refresh + client script)
+export const metadata = {
+  title: "Redirecting...",
+  other: {
+    "http-equiv:refresh": `0; url=/${DEFAULT_LANG}/`
+  }
+};
+
+export default function HomePage() {
+  const target = `/${DEFAULT_LANG}/`;
+  return (
+    <>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `window.location.replace("${target}");`
+        }}
+      />
+      <meta httpEquiv="refresh" content={`0; url=${target}`} />
+      <p style={{ padding: "2rem", textAlign: "center" }}>
+        Redirecting to <a href={target}>{target}</a>...
+      </p>
+    </>
+  );
+}
diff --git a/gitbook/components/DocsContent.js b/gitbook/components/DocsContent.js
new file mode 100644
index 0000000..1924593
--- /dev/null
+++ b/gitbook/components/DocsContent.js
@@ -0,0 +1,13 @@
+"use client";
+
+import { MarkdownRenderer } from "@/utils/markdown";
+
+export default function DocsContent({ content }) {
+  return (
+    <main className="flex-1 min-w-0 overflow-x-hidden overflow-y-auto">
+      <article className="max-w-4xl mx-auto px-4 sm:px-6 py-8">
+        <MarkdownRenderer content={content} />
+      </article>
+    </main>
+  );
+}
diff --git a/gitbook/components/DocsHeader.js b/gitbook/components/DocsHeader.js
new file mode 100644
index 0000000..2f069c5
--- /dev/null
+++ b/gitbook/components/DocsHeader.js
@@ -0,0 +1,78 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { DOCS_CONFIG, t } from "@/constants/docsConfig";
+import { DEFAULT_LANG } from "@/constants/languages";
+import { ExternalLink, Menu, X } from "lucide-react";
+import DocsSidebar from "./DocsSidebar";
+import LanguageSwitcher from "./LanguageSwitcher";
+
+export default function DocsHeader({ lang = DEFAULT_LANG }) {
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+
+  return (
+    <>
+      <header className="sticky top-0 z-50 w-full border-b bg-white/80 backdrop-blur-sm border-gray-200">
+        <div className=" mx-auto px-4 h-16 flex items-center justify-between">
+          {/* Mobile menu button */}
+          <button
+            onClick={() => setMobileMenuOpen(true)}
+            className="lg:hidden p-2 rounded-lg hover:bg-gray-100 transition-colors"
+            aria-label="Open menu"
+          >
+            <Menu className="w-6 h-6 text-gray-600" />
+          </button>
+
+          {/* Logo */}
+          <Link href={`/${lang}`} className="flex items-center gap-2 font-bold text-2xl text-black hover:opacity-80 transition-opacity">
+            <span>9</span>
+            <span className="text-[#E68A6E]">{DOCS_CONFIG.logo} Docs</span>
+          </Link>
+
+          {/* Right side */}
+          <div className="flex items-center gap-2 sm:gap-3">
+            <LanguageSwitcher currentLang={lang} />
+
+            {/* Go to App */}
+            <Link
+              href={DOCS_CONFIG.appUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="flex items-center gap-2 px-3 sm:px-4 py-2 bg-[#E68A6E] text-white rounded-lg font-medium hover:bg-[#d67a5e] transition-colors text-sm"
+            >
+              <span className="hidden sm:inline">{t(lang, "goToApp")}</span>
+              <ExternalLink className="w-4 h-4" />
+            </Link>
+          </div>
+        </div>
+      </header>
+
+      {/* Mobile menu */}
+      {mobileMenuOpen && (
+        <>
+          <div
+            className="mobile-menu-overlay lg:hidden"
+            onClick={() => setMobileMenuOpen(false)}
+          />
+          
+          <div className="mobile-menu-drawer lg:hidden">
+            <div className="flex items-center justify-between p-4 border-b border-gray-200">
+              <span className="font-bold text-lg text-black">
+                <span className="text-[#E68A6E]">9</span>{DOCS_CONFIG.logo} Docs
+              </span>
+              <button
+                onClick={() => setMobileMenuOpen(false)}
+                className="p-2 rounded-lg hover:bg-gray-100 transition-colors"
+                aria-label="Close menu"
+              >
+                <X className="w-5 h-5 text-gray-600" />
+              </button>
+            </div>
+            <DocsSidebar isMobile onClose={() => setMobileMenuOpen(false)} lang={lang} />
+          </div>
+        </>
+      )}
+    </>
+  );
+}
diff --git a/gitbook/components/DocsLayout.js b/gitbook/components/DocsLayout.js
new file mode 100644
index 0000000..0cf74b4
--- /dev/null
+++ b/gitbook/components/DocsLayout.js
@@ -0,0 +1,25 @@
+"use client";
+
+import DocsHeader from "./DocsHeader";
+import DocsSidebar from "./DocsSidebar";
+import DocsToc from "./DocsToc";
+import { DEFAULT_LANG } from "@/constants/languages";
+
+export default function DocsLayout({ children, headings = [], lang = DEFAULT_LANG }) {
+  return (
+    <div className="min-h-screen flex flex-col bg-[#FCFBF9]">
+      <DocsHeader lang={lang} />
+      <div className="flex-1 flex">
+        <div className="hidden lg:block">
+          <DocsSidebar lang={lang} />
+        </div>
+        <div className="flex-1 flex min-w-0">
+          {children}
+          <div className="hidden lg:block">
+            <DocsToc headings={headings} lang={lang} />
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/gitbook/components/DocsSidebar.js b/gitbook/components/DocsSidebar.js
new file mode 100644
index 0000000..7700439
--- /dev/null
+++ b/gitbook/components/DocsSidebar.js
@@ -0,0 +1,125 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { getNavigation } from "@/constants/docsConfig";
+import { DEFAULT_LANG } from "@/constants/languages";
+import { ChevronDown, ChevronRight, BookOpen, Rocket, Terminal, Monitor, HelpCircle, MessageCircle, Layers, Plug, Cloud, Zap, Wallet, Gift, GitBranch, BarChart3, Code2, Sparkles, Server } from "lucide-react";
+
+// Icons keyed by structural key (language-independent)
+const SECTION_ICONS = {
+  gettingStarted: Rocket,
+  providers: Layers,
+  features: Zap,
+  integration: Plug,
+  deployment: Cloud,
+  help: HelpCircle
+};
+
+const ITEM_ICONS = {
+  introduction: BookOpen,
+  quickStart: Rocket,
+  installation: Terminal,
+  subscription: Sparkles,
+  cheap: Wallet,
+  free: Gift,
+  smartRouting: GitBranch,
+  combos: Layers,
+  quotaTracking: BarChart3,
+  claudeCode: Code2,
+  codex: Code2,
+  cursor: Code2,
+  cline: Code2,
+  roo: Code2,
+  continue: Code2,
+  otherTools: Plug,
+  localhost: Monitor,
+  cloud: Server,
+  troubleshooting: HelpCircle,
+  faq: MessageCircle
+};
+
+export default function DocsSidebar({ isMobile = false, onClose, lang = DEFAULT_LANG }) {
+  const pathname = usePathname();
+  const navigation = getNavigation(lang);
+  const [openSections, setOpenSections] = useState(() => {
+    if (typeof window === "undefined") return [];
+    try {
+      return JSON.parse(sessionStorage.getItem("sidebarOpen") || "[]");
+    } catch { return []; }
+  });
+
+  useEffect(() => {
+    sessionStorage.setItem("sidebarOpen", JSON.stringify(openSections));
+  }, [openSections]);
+
+  const toggleSection = (index) => {
+    setOpenSections(prev =>
+      prev.includes(index)
+        ? prev.filter(i => i !== index)
+        : [...prev, index]
+    );
+  };
+
+  const buildHref = (slug) => (slug ? `/${lang}/${slug}` : `/${lang}`);
+  const isActive = (slug) => pathname === buildHref(slug);
+
+  const handleLinkClick = () => {
+    if (isMobile && onClose) onClose();
+  };
+
+  return (
+    <aside className={`${isMobile ? 'w-full' : 'w-64'} border-r bg-white border-gray-200 ${isMobile ? 'h-full' : 'h-[calc(100vh-4rem)] sticky top-16'} overflow-y-auto`}>
+      <nav className="p-4 space-y-6">
+        {navigation.map((section, sectionIndex) => {
+          const SectionIcon = SECTION_ICONS[section.key] || BookOpen;
+
+          return (
+            <div key={section.key}>
+              <button
+                onClick={() => toggleSection(sectionIndex)}
+                className="flex items-center justify-between w-full text-sm font-semibold text-gray-900 mb-2 hover:text-[#E68A6E] transition-colors"
+              >
+                <span className="flex items-center gap-2">
+                  <SectionIcon className="w-4 h-4" />
+                  {section.title}
+                </span>
+                {openSections.includes(sectionIndex) ? (
+                  <ChevronDown className="w-4 h-4" />
+                ) : (
+                  <ChevronRight className="w-4 h-4" />
+                )}
+              </button>
+
+              {openSections.includes(sectionIndex) && (
+                <ul className="space-y-1">
+                  {section.items.map((item) => {
+                    const ItemIcon = ITEM_ICONS[item.key] || BookOpen;
+
+                    return (
+                      <li key={item.key}>
+                        <Link
+                          href={buildHref(item.slug)}
+                          onClick={handleLinkClick}
+                          className={`flex items-center gap-2 px-3 py-2 text-sm rounded-lg transition-colors ${
+                            isActive(item.slug)
+                              ? "bg-[#E68A6E]/10 text-[#E68A6E] font-medium"
+                              : "text-gray-600 hover:bg-gray-100 hover:text-gray-900"
+                          }`}
+                        >
+                          <ItemIcon className="w-4 h-4" />
+                          {item.title}
+                        </Link>
+                      </li>
+                    );
+                  })}
+                </ul>
+              )}
+            </div>
+          );
+        })}
+      </nav>
+    </aside>
+  );
+}
diff --git a/gitbook/components/DocsToc.js b/gitbook/components/DocsToc.js
new file mode 100644
index 0000000..c652c28
--- /dev/null
+++ b/gitbook/components/DocsToc.js
@@ -0,0 +1,61 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { List } from "lucide-react";
+import { t } from "@/constants/docsConfig";
+import { DEFAULT_LANG } from "@/constants/languages";
+
+export default function DocsToc({ headings, lang = DEFAULT_LANG }) {
+  const [activeId, setActiveId] = useState("");
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id);
+          }
+        });
+      },
+      { rootMargin: "-80px 0px -80% 0px" }
+    );
+
+    headings.forEach(({ id }) => {
+      const element = document.getElementById(id);
+      if (element) observer.observe(element);
+    });
+
+    return () => observer.disconnect();
+  }, [headings]);
+
+  if (!headings || headings.length === 0) return null;
+
+  return (
+    <aside className="hidden xl:block w-64 border-l bg-white border-gray-200 h-[calc(100vh-4rem)] sticky top-16 overflow-y-auto">
+      <nav className="p-4">
+        <h3 className="flex items-center gap-2 text-sm font-semibold text-gray-900 mb-3">
+          <List className="w-4 h-4" />
+          {t(lang, "onThisPage")}
+        </h3>
+        <ul className="space-y-2">
+          {headings.map((heading, idx) => (
+            <li key={`${heading.id}-${idx}`}>
+              <a
+                href={`#${heading.id}`}
+                className={`block text-sm transition-colors ${
+                  heading.level === 3 ? "pl-4" : ""
+                } ${
+                  activeId === heading.id
+                    ? "text-[#E68A6E] font-medium"
+                    : "text-gray-600 hover:text-gray-900"
+                }`}
+              >
+                {heading.text}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </aside>
+  );
+}
diff --git a/gitbook/components/LanguageSwitcher.js b/gitbook/components/LanguageSwitcher.js
new file mode 100644
index 0000000..9dea279
--- /dev/null
+++ b/gitbook/components/LanguageSwitcher.js
@@ -0,0 +1,96 @@
+"use client";
+
+import { useState, useLayoutEffect } from "react";
+import { createPortal } from "react-dom";
+import { useRouter, usePathname } from "next/navigation";
+import { Globe, X } from "lucide-react";
+import { LANGUAGES, getLanguage, DEFAULT_LANG } from "@/constants/languages";
+import { t } from "@/constants/docsConfig";
+
+function extractLangFromPath(pathname) {
+  const match = pathname.match(/^\/([^/]+)(?:\/(.*))?$/);
+  if (!match) return { lang: DEFAULT_LANG, rest: "" };
+  return { lang: match[1], rest: match[2] || "" };
+}
+
+export default function LanguageSwitcher({ currentLang }) {
+  const [open, setOpen] = useState(false);
+  const router = useRouter();
+  const pathname = usePathname();
+  const current = getLanguage(currentLang);
+
+  useLayoutEffect(() => {
+    setMounted(true);
+  }, []);
+
+  // Lock body scroll when modal is open
+  useEffect(() => {
+    if (open) {
+      document.body.style.overflow = "hidden";
+      return () => { document.body.style.overflow = ""; };
+    }
+  }, [open]);
+
+  const switchTo = (code) => {
+    const { rest } = extractLangFromPath(pathname);
+    const target = rest ? `/${code}/${rest}` : `/${code}`;
+    setOpen(false);
+    router.push(target);
+  };
+
+  const modal = open && (
+    <div className="fixed inset-0 z-[9999] flex items-center justify-center bg-black/50 p-4" onClick={() => setOpen(false)}>
+      <div
+        className="bg-white rounded-xl shadow-2xl max-w-md w-full max-h-[80vh] overflow-hidden"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center justify-between p-4 border-b border-gray-200">
+          <h2 className="font-bold text-lg text-gray-900">{t(currentLang, "selectLanguage")}</h2>
+          <button
+            onClick={() => setOpen(false)}
+            className="p-1.5 rounded-lg hover:bg-gray-100 transition-colors"
+            aria-label="Close"
+          >
+            <X className="w-5 h-5 text-gray-600" />
+          </button>
+        </div>
+        <div className="p-2 overflow-y-auto max-h-[60vh]">
+          {LANGUAGES.map((lang) => (
+            <button
+              key={lang.code}
+              onClick={() => switchTo(lang.code)}
+              className={`w-full flex items-center gap-3 px-3 py-2.5 rounded-lg text-left transition-colors ${
+                lang.code === currentLang
+                  ? "bg-[#E68A6E]/10 text-[#E68A6E] font-medium"
+                  : "text-gray-700 hover:bg-gray-100"
+              }`}
+            >
+              <span className="text-2xl">{lang.flag}</span>
+              <div className="flex-1">
+                <div className="font-medium">{lang.native}</div>
+                <div className="text-xs text-gray-500">{lang.name}</div>
+              </div>
+              {lang.code === currentLang && <span className="text-xs">✓</span>}
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+
+  return (
+    <>
+      <button
+        onClick={() => setOpen(true)}
+        className="flex items-center gap-1.5 px-2.5 py-1.5 text-sm text-gray-700 bg-gray-100 rounded-lg hover:bg-gray-200 transition-colors"
+        aria-label="Switch language"
+      >
+        <Globe className="w-4 h-4" />
+        <span className="hidden sm:inline">{current.flag} {current.native}</span>
+        <span className="sm:hidden">{current.flag}</span>
+      </button>
+
+      {open && createPortal(modal, document.body)}
+    </>
+  );
+}
diff --git a/gitbook/constants/docsConfig.js b/gitbook/constants/docsConfig.js
new file mode 100644
index 0000000..3cee1bf
--- /dev/null
+++ b/gitbook/constants/docsConfig.js
@@ -0,0 +1,242 @@
+import { DEFAULT_LANG } from "./languages";
+
+// Navigation structure (slugs are shared). Labels are per-language.
+const NAV_STRUCTURE = [
+  {
+    key: "gettingStarted",
+    items: [
+      { key: "introduction", slug: "" },
+      { key: "quickStart", slug: "getting-started/quick-start" },
+      { key: "installation", slug: "getting-started/installation" }
+    ]
+  },
+  {
+    key: "providers",
+    items: [
+      { key: "subscription", slug: "providers/subscription" },
+      { key: "cheap", slug: "providers/cheap" },
+      { key: "free", slug: "providers/free" }
+    ]
+  },
+  {
+    key: "features",
+    items: [
+      { key: "smartRouting", slug: "features/smart-routing" },
+      { key: "combos", slug: "features/combos" },
+      { key: "quotaTracking", slug: "features/quota-tracking" }
+    ]
+  },
+  {
+    key: "integration",
+    items: [
+      { key: "claudeCode", slug: "integration/claude-code" },
+      { key: "codex", slug: "integration/codex" },
+      { key: "cursor", slug: "integration/cursor" },
+      { key: "cline", slug: "integration/cline" },
+      { key: "roo", slug: "integration/roo" },
+      { key: "continue", slug: "integration/continue" },
+      { key: "otherTools", slug: "integration/other-tools" }
+    ]
+  },
+  {
+    key: "deployment",
+    items: [
+      { key: "localhost", slug: "deployment/localhost" },
+      { key: "cloud", slug: "deployment/cloud" }
+    ]
+  },
+  {
+    key: "help",
+    items: [
+      { key: "troubleshooting", slug: "troubleshooting" },
+      { key: "faq", slug: "faq" }
+    ]
+  }
+];
+
+// Translations for section/item titles (5 langs).
+const TRANSLATIONS = {
+  en: {
+    gettingStarted: "Getting Started",
+    introduction: "Introduction",
+    quickStart: "Quick Start",
+    installation: "Installation",
+    providers: "Providers",
+    subscription: "Subscription (Maximize)",
+    cheap: "Cheap (Backup)",
+    free: "Free (Fallback)",
+    features: "Features",
+    smartRouting: "Smart Routing",
+    combos: "Combos & Fallback",
+    quotaTracking: "Quota Tracking",
+    integration: "Integration",
+    claudeCode: "Claude Code",
+    codex: "OpenAI Codex",
+    cursor: "Cursor",
+    cline: "Cline",
+    roo: "Roo",
+    continue: "Continue",
+    otherTools: "Other Tools",
+    deployment: "Deployment",
+    localhost: "Localhost",
+    cloud: "Cloud (VPS/Docker)",
+    help: "Help",
+    troubleshooting: "Troubleshooting",
+    faq: "FAQ",
+    goToApp: "Go to App",
+    selectLanguage: "Select Language",
+    onThisPage: "On this page"
+  },
+  vi: {
+    gettingStarted: "Bắt đầu",
+    introduction: "Giới thiệu",
+    quickStart: "Bắt đầu nhanh",
+    installation: "Cài đặt",
+    providers: "Nhà cung cấp",
+    subscription: "Subscription (Tối đa hóa)",
+    cheap: "Giá rẻ (Dự phòng)",
+    free: "Miễn phí (Phương án cuối)",
+    features: "Tính năng",
+    smartRouting: "Định tuyến thông minh",
+    combos: "Combo & Fallback",
+    quotaTracking: "Theo dõi Quota",
+    integration: "Tích hợp",
+    claudeCode: "Claude Code",
+    codex: "OpenAI Codex",
+    cursor: "Cursor",
+    cline: "Cline",
+    roo: "Roo",
+    continue: "Continue",
+    otherTools: "Công cụ khác",
+    deployment: "Triển khai",
+    localhost: "Localhost",
+    cloud: "Cloud (VPS/Docker)",
+    help: "Trợ giúp",
+    troubleshooting: "Khắc phục sự cố",
+    faq: "Câu hỏi thường gặp",
+    goToApp: "Vào ứng dụng",
+    selectLanguage: "Chọn ngôn ngữ",
+    onThisPage: "Trên trang này"
+  },
+  "zh-CN": {
+    gettingStarted: "开始使用",
+    introduction: "简介",
+    quickStart: "快速开始",
+    installation: "安装",
+    providers: "提供商",
+    subscription: "订阅 (最大化)",
+    cheap: "低价 (备用)",
+    free: "免费 (兜底)",
+    features: "功能",
+    smartRouting: "智能路由",
+    combos: "组合与回退",
+    quotaTracking: "配额跟踪",
+    integration: "集成",
+    claudeCode: "Claude Code",
+    codex: "OpenAI Codex",
+    cursor: "Cursor",
+    cline: "Cline",
+    roo: "Roo",
+    continue: "Continue",
+    otherTools: "其他工具",
+    deployment: "部署",
+    localhost: "本地",
+    cloud: "云端 (VPS/Docker)",
+    help: "帮助",
+    troubleshooting: "故障排查",
+    faq: "常见问题",
+    goToApp: "前往应用",
+    selectLanguage: "选择语言",
+    onThisPage: "本页内容"
+  },
+  es: {
+    gettingStarted: "Comenzar",
+    introduction: "Introducción",
+    quickStart: "Inicio rápido",
+    installation: "Instalación",
+    providers: "Proveedores",
+    subscription: "Suscripción (Maximizar)",
+    cheap: "Económico (Respaldo)",
+    free: "Gratis (Alternativa)",
+    features: "Funciones",
+    smartRouting: "Enrutamiento inteligente",
+    combos: "Combos y Fallback",
+    quotaTracking: "Seguimiento de cuota",
+    integration: "Integración",
+    claudeCode: "Claude Code",
+    codex: "OpenAI Codex",
+    cursor: "Cursor",
+    cline: "Cline",
+    roo: "Roo",
+    continue: "Continue",
+    otherTools: "Otras herramientas",
+    deployment: "Despliegue",
+    localhost: "Localhost",
+    cloud: "Nube (VPS/Docker)",
+    help: "Ayuda",
+    troubleshooting: "Solución de problemas",
+    faq: "Preguntas frecuentes",
+    goToApp: "Ir a la app",
+    selectLanguage: "Seleccionar idioma",
+    onThisPage: "En esta página"
+  },
+  ja: {
+    gettingStarted: "はじめに",
+    introduction: "概要",
+    quickStart: "クイックスタート",
+    installation: "インストール",
+    providers: "プロバイダー",
+    subscription: "サブスクリプション (最大化)",
+    cheap: "格安 (バックアップ)",
+    free: "無料 (フォールバック)",
+    features: "機能",
+    smartRouting: "スマートルーティング",
+    combos: "コンボとフォールバック",
+    quotaTracking: "クォータ追跡",
+    integration: "連携",
+    claudeCode: "Claude Code",
+    codex: "OpenAI Codex",
+    cursor: "Cursor",
+    cline: "Cline",
+    roo: "Roo",
+    continue: "Continue",
+    otherTools: "その他のツール",
+    deployment: "デプロイ",
+    localhost: "ローカル",
+    cloud: "クラウド (VPS/Docker)",
+    help: "ヘルプ",
+    troubleshooting: "トラブルシューティング",
+    faq: "よくある質問",
+    goToApp: "アプリへ",
+    selectLanguage: "言語を選択",
+    onThisPage: "このページ"
+  }
+};
+
+// Translate one key for given language with fallback to default.
+export function t(lang, key) {
+  return TRANSLATIONS[lang]?.[key] || TRANSLATIONS[DEFAULT_LANG][key] || key;
+}
+
+// Build localized navigation for sidebar.
+export function getNavigation(lang) {
+  return NAV_STRUCTURE.map(section => ({
+    key: section.key,
+    title: t(lang, section.key),
+    items: section.items.map(item => ({
+      key: item.key,
+      slug: item.slug,
+      title: t(lang, item.key)
+    }))
+  }));
+}
+
+// Static config (logo, urls, default English nav for backward compatibility).
+export const DOCS_CONFIG = {
+  title: "9Router Documentation",
+  description: "Smart AI model router - Maximize subscriptions, minimize costs",
+  logo: "9Router",
+  appUrl: "https://9router.com",
+  githubUrl: "https://github.com/decolua/9router",
+  navigation: getNavigation(DEFAULT_LANG)
+};
diff --git a/gitbook/constants/languages.js b/gitbook/constants/languages.js
new file mode 100644
index 0000000..9f64174
--- /dev/null
+++ b/gitbook/constants/languages.js
@@ -0,0 +1,19 @@
+export const DEFAULT_LANG = "en";
+
+export const LANGUAGES = [
+  { code: "en", name: "English", native: "English", flag: "🇺🇸" },
+  { code: "vi", name: "Vietnamese", native: "Tiếng Việt", flag: "🇻🇳" },
+  { code: "zh-CN", name: "Chinese (Simplified)", native: "简体中文", flag: "🇨🇳" },
+  { code: "es", name: "Spanish", native: "Español", flag: "🇪🇸" },
+  { code: "ja", name: "Japanese", native: "日本語", flag: "🇯🇵" }
+];
+
+export const LANG_CODES = LANGUAGES.map(l => l.code);
+
+export function isValidLang(code) {
+  return LANG_CODES.includes(code);
+}
+
+export function getLanguage(code) {
+  return LANGUAGES.find(l => l.code === code) || LANGUAGES[0];
+}
diff --git a/gitbook/content/en/deployment/cloud.md b/gitbook/content/en/deployment/cloud.md
new file mode 100644
index 0000000..80e4b28
--- /dev/null
+++ b/gitbook/content/en/deployment/cloud.md
@@ -0,0 +1,473 @@
+# ☁️ Cloud Deployment
+
+Deploy 9Router on VPS or Docker for remote access and production use.
+
+---
+
+## 🖥️ VPS Deployment
+
+### Prerequisites
+
+- Ubuntu 20.04+ or similar Linux distribution
+- Node.js 20+
+- Git
+- Root or sudo access
+
+### Step 1: Clone Repository
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+```
+
+### Step 2: Install Dependencies
+
+```bash
+npm install
+```
+
+### Step 3: Build Application
+
+```bash
+npm run build
+```
+
+### Step 4: Configure Environment Variables
+
+Create a `.env` file or export variables:
+
+```bash
+export JWT_SECRET="your-secure-secret-change-this-to-random-string"
+export INITIAL_PASSWORD="your-secure-password"
+export DATA_DIR="/var/lib/9router"
+export NODE_ENV="production"
+```
+
+**Environment Variables:**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JWT_SECRET` | Auto-generated | **MUST change in production!** Used for JWT token signing |
+| `INITIAL_PASSWORD` | `123456` | Dashboard login password |
+| `DATA_DIR` | `~/.9router` | Database and data storage path |
+| `NODE_ENV` | `development` | Set to `production` for deployment |
+| `ENABLE_REQUEST_LOGS` | `false` | Enable debug request/response logs |
+
+### Step 5: Create Data Directory
+
+```bash
+sudo mkdir -p /var/lib/9router
+sudo chown $USER:$USER /var/lib/9router
+```
+
+### Step 6: Start Application
+
+```bash
+npm run start
+```
+
+### Step 7: Setup PM2 for Production
+
+PM2 keeps your application running and restarts it on crashes:
+
+```bash
+# Install PM2 globally
+npm install -g pm2
+
+# Start 9Router with PM2
+pm2 start npm --name 9router -- start
+
+# Save PM2 configuration
+pm2 save
+
+# Setup PM2 to start on system boot
+pm2 startup
+# Follow the instructions printed by the command above
+```
+
+**PM2 Management Commands:**
+
+```bash
+# View logs
+pm2 logs 9router
+
+# Restart application
+pm2 restart 9router
+
+# Stop application
+pm2 stop 9router
+
+# View status
+pm2 status
+
+# Monitor resources
+pm2 monit
+```
+
+---
+
+## 🐳 Docker Deployment
+
+### Option 1: Using Dockerfile
+
+Create a `Dockerfile` in the `app` directory:
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy application files
+COPY . .
+
+# Build application
+RUN npm run build
+
+# Expose ports
+EXPOSE 3000 20128
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV DATA_DIR=/app/data
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Start application
+CMD ["npm", "run", "start"]
+```
+
+**Build and Run:**
+
+```bash
+# Build image
+docker build -t 9router .
+
+# Run container
+docker run -d \
+  --name 9router \
+  -p 3000:3000 \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret-change-this" \
+  -e INITIAL_PASSWORD="your-secure-password" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Option 2: Docker Compose
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  9router:
+    build: .
+    container_name: 9router
+    ports:
+      - "3000:3000"
+      - "20128:20128"
+    environment:
+      - NODE_ENV=production
+      - JWT_SECRET=your-secure-secret-change-this
+      - INITIAL_PASSWORD=your-secure-password
+      - DATA_DIR=/app/data
+    volumes:
+      - 9router-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  9router-data:
+```
+
+**Run with Docker Compose:**
+
+```bash
+# Start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+
+# Rebuild and restart
+docker-compose up -d --build
+```
+
+---
+
+## 🌐 Reverse Proxy with Nginx
+
+### Why Use Nginx?
+
+- SSL/TLS termination
+- Domain name mapping
+- Load balancing
+- Better security
+
+### Step 1: Install Nginx
+
+```bash
+sudo apt update
+sudo apt install nginx
+```
+
+### Step 2: Configure Nginx
+
+Create `/etc/nginx/sites-available/9router`:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    # SSL certificates (use certbot to generate)
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    # SSL configuration
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # Proxy to 9Router
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+
+    # API endpoint
+    location /v1 {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+### Step 3: Enable Site
+
+```bash
+# Create symbolic link
+sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/
+
+# Test configuration
+sudo nginx -t
+
+# Reload Nginx
+sudo systemctl reload nginx
+```
+
+### Step 4: Setup SSL with Let's Encrypt
+
+```bash
+# Install certbot
+sudo apt install certbot python3-certbot-nginx
+
+# Obtain SSL certificate
+sudo certbot --nginx -d your-domain.com
+
+# Auto-renewal is configured automatically
+# Test renewal
+sudo certbot renew --dry-run
+```
+
+---
+
+## 🔒 Security Considerations
+
+### 1. Change Default Credentials
+
+**CRITICAL:** Change `JWT_SECRET` and `INITIAL_PASSWORD` before deployment:
+
+```bash
+# Generate secure JWT secret
+openssl rand -base64 32
+
+# Use this value for JWT_SECRET
+export JWT_SECRET="generated-secret-here"
+```
+
+### 2. Firewall Configuration
+
+```bash
+# Allow SSH
+sudo ufw allow 22/tcp
+
+# Allow HTTP/HTTPS (if using Nginx)
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+
+# If NOT using reverse proxy, allow 9Router ports
+sudo ufw allow 3000/tcp
+sudo ufw allow 20128/tcp
+
+# Enable firewall
+sudo ufw enable
+```
+
+### 3. Restrict Dashboard Access
+
+If you only need API access, restrict dashboard port:
+
+```bash
+# Only allow localhost access to dashboard
+sudo ufw deny 3000/tcp
+```
+
+Access dashboard via SSH tunnel:
+
+```bash
+ssh -L 3000:localhost:3000 user@your-server.com
+# Then open http://localhost:3000 in your browser
+```
+
+### 4. Regular Updates
+
+```bash
+# Update system packages
+sudo apt update && sudo apt upgrade -y
+
+# Update 9Router
+cd /path/to/9router/app
+git pull
+npm install
+npm run build
+pm2 restart 9router
+```
+
+### 5. Backup Strategy
+
+```bash
+# Backup data directory
+tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router
+
+# Automated daily backup (add to crontab)
+0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router
+```
+
+---
+
+## 📊 Monitoring
+
+### Check Application Status
+
+```bash
+# PM2 status
+pm2 status
+
+# View logs
+pm2 logs 9router --lines 100
+
+# Monitor resources
+pm2 monit
+```
+
+### Nginx Logs
+
+```bash
+# Access logs
+sudo tail -f /var/log/nginx/access.log
+
+# Error logs
+sudo tail -f /var/log/nginx/error.log
+```
+
+### System Resources
+
+```bash
+# CPU and memory usage
+htop
+
+# Disk usage
+df -h
+
+# Network connections
+netstat -tulpn | grep -E '3000|20128'
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### Application Won't Start
+
+```bash
+# Check logs
+pm2 logs 9router
+
+# Check if ports are in use
+sudo lsof -i :3000
+sudo lsof -i :20128
+
+# Check environment variables
+pm2 env 9router
+```
+
+### Nginx 502 Bad Gateway
+
+```bash
+# Check if 9Router is running
+pm2 status
+
+# Check Nginx error logs
+sudo tail -f /var/log/nginx/error.log
+
+# Test Nginx configuration
+sudo nginx -t
+```
+
+### SSE Streaming Not Working
+
+Ensure `proxy_buffering off` is set in Nginx configuration for SSE support.
+
+### Permission Denied Errors
+
+```bash
+# Fix data directory permissions
+sudo chown -R $USER:$USER /var/lib/9router
+chmod 755 /var/lib/9router
+```
+
+---
+
+## 🔗 Next Steps
+
+- [Connect Providers](/providers/subscription.md)
+- [Setup Combos](/features/combos.md)
+- [Integrate with Tools](/integration/cursor.md)
diff --git a/gitbook/content/en/deployment/localhost.md b/gitbook/content/en/deployment/localhost.md
new file mode 100644
index 0000000..cf2db78
--- /dev/null
+++ b/gitbook/content/en/deployment/localhost.md
@@ -0,0 +1,164 @@
+# 🏠 Localhost Deployment
+
+Run 9Router on your local machine for development and personal use.
+
+---
+
+## 📦 Installation
+
+Install 9Router globally via npm:
+
+```bash
+npm install -g 9router
+```
+
+**Requirements:**
+- Node.js 20 or higher
+- npm 9 or higher
+
+---
+
+## 🚀 Starting the Server
+
+Start 9Router with a single command:
+
+```bash
+9router
+```
+
+The dashboard will automatically open in your browser at `http://localhost:3000`
+
+**Default Configuration:**
+- **Dashboard**: `http://localhost:3000`
+- **API Endpoint**: `http://localhost:20128/v1`
+- **Data Directory**: `~/.9router`
+
+---
+
+## 🔧 Configuration
+
+### Custom Data Directory
+
+Set a custom data directory using environment variable:
+
+```bash
+DATA_DIR=/path/to/data 9router
+```
+
+### Custom Port
+
+The API port (20128) and dashboard port (3000) are configured in the application. To change them, you'll need to modify the source code or use environment variables if supported.
+
+---
+
+## 🛑 Stopping the Server
+
+Press `Ctrl+C` in the terminal where 9Router is running.
+
+```bash
+# In the terminal running 9router
+^C  # Press Ctrl+C
+```
+
+The server will gracefully shut down and save all data.
+
+---
+
+## 🔄 Restarting the Server
+
+Simply run the start command again:
+
+```bash
+9router
+```
+
+All your configurations, API keys, and combos are preserved in the data directory.
+
+---
+
+## 📊 Updating 9Router
+
+Update to the latest version:
+
+```bash
+npm update -g 9router
+```
+
+Check your current version:
+
+```bash
+npm list -g 9router
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### Port Already in Use
+
+If port 20128 or 3000 is already in use:
+
+```bash
+# Find process using the port (macOS/Linux)
+lsof -i :20128
+lsof -i :3000
+
+# Kill the process
+kill -9 <PID>
+```
+
+### Permission Errors
+
+If you encounter permission errors during installation:
+
+```bash
+# Use sudo (not recommended)
+sudo npm install -g 9router
+
+# Or fix npm permissions (recommended)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Data Directory Issues
+
+If the data directory is not accessible:
+
+```bash
+# Check permissions
+ls -la ~/.9router
+
+# Fix permissions
+chmod 755 ~/.9router
+```
+
+---
+
+## 📁 Data Directory Structure
+
+```
+~/.9router/
+├── db.json           # Main database (providers, combos, settings)
+├── logs/             # Application logs
+└── cache/            # Temporary cache files
+```
+
+**Backup Your Data:**
+
+```bash
+# Backup
+cp -r ~/.9router ~/.9router.backup
+
+# Restore
+cp -r ~/.9router.backup ~/.9router
+```
+
+---
+
+## 🔗 Next Steps
+
+- [Connect Providers](/providers/subscription.md)
+- [Create Combos](/features/combos.md)
+- [Integrate with CLI Tools](/integration/cursor.md)
diff --git a/gitbook/content/en/faq.md b/gitbook/content/en/faq.md
new file mode 100644
index 0000000..cc8f5a1
--- /dev/null
+++ b/gitbook/content/en/faq.md
@@ -0,0 +1,387 @@
+# Frequently Asked Questions
+
+Common questions about 9Router.
+
+---
+
+## What is 9Router?
+
+**9Router is an AI model router that maximizes your subscription value and minimizes costs.**
+
+It intelligently routes requests across multiple AI providers using a 3-tier fallback system:
+1. **Subscription tier** - Maximize Claude Code, Codex, Gemini quotas you already pay for
+2. **Cheap tier** - Ultra-cheap alternatives ($0.20-$0.60 per 1M tokens)
+3. **Free tier** - Emergency backup with unlimited free models
+
+**Key benefits:**
+- Never waste subscription quota
+- Automatic fallback when quota exhausted
+- Real-time quota tracking
+- 90% cost savings vs direct API usage
+
+---
+
+## How does pricing work?
+
+**9Router uses a 3-tier pricing strategy:**
+
+### Tier 1: Subscription (Maximize First)
+- **Claude Code** (Pro/Max): $20-100/month - 5-hour + weekly quota
+- **OpenAI Codex** (Plus/Pro): $20-200/month - 5-hour + weekly quota
+- **Gemini CLI**: FREE - 180K completions/month + 1K/day
+- **GitHub Copilot**: $10-19/month - Monthly reset
+- **Antigravity**: FREE - Similar to Gemini
+
+**Goal:** Use every bit of quota before it resets!
+
+### Tier 2: Cheap (Backup)
+- **GLM-4.7**: $0.60/$2.20 per 1M tokens - Daily reset 10AM
+- **MiniMax M2.1**: $0.20/$1.00 per 1M tokens - 5-hour rolling
+- **Kimi K2**: $9/month flat (10M tokens)
+
+**Goal:** 90% cheaper than ChatGPT API ($20/1M)!
+
+### Tier 3: Free (Emergency)
+- **iFlow**: 8 models FREE (Kimi K2, Qwen3, GLM, MiniMax...)
+- **Qwen**: 3 models FREE (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro**: 2 models FREE (Claude Sonnet 4.5, Haiku 4.5)
+
+**Goal:** Zero cost fallback when everything else is quota-limited!
+
+---
+
+## Is 9Router free?
+
+**Yes, 9Router itself is 100% free and open source.**
+
+**Free tier providers available:**
+- **Gemini CLI** - 180K completions/month (FREE Google account)
+- **iFlow** - 8 models unlimited (FREE OAuth)
+- **Qwen** - 3 models unlimited (FREE OAuth)
+- **Kiro** - Claude Sonnet/Haiku (FREE AWS Builder ID)
+
+**You can code for FREE forever using only free tier providers!**
+
+**Optional paid providers:**
+- Subscription services you may already have (Claude Code, Codex, Copilot)
+- Ultra-cheap alternatives ($0.20-$0.60 per 1M tokens)
+
+---
+
+## Which providers are supported?
+
+### Subscription Providers
+- **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
+- **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
+- **Gemini CLI** (FREE) - Gemini 3 Flash/Pro, 2.5 Pro/Flash
+- **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
+- **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
+
+### Cheap Providers
+- **GLM** (Zhipu AI) - GLM 4.7, GLM 4.6V Vision
+- **MiniMax** - MiniMax M2.1
+- **Kimi** (Moonshot AI) - Kimi Latest
+- **OpenRouter** - Passthrough to any OpenRouter model
+
+### Free Providers
+- **iFlow** - 8 models (Kimi K2, Qwen3, GLM, MiniMax, DeepSeek...)
+- **Qwen** - 3 models (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro** - 2 models (Claude Sonnet 4.5, Haiku 4.5)
+
+**Total: 15+ providers, 50+ models**
+
+See [providers documentation](providers/subscription.md) for details.
+
+---
+
+## Can I use multiple providers?
+
+**Yes! This is 9Router's core feature.**
+
+**Combos allow you to chain multiple providers with automatic fallback:**
+
+```
+Example combo: "premium-coding"
+1. cc/claude-opus-4-5 (Subscription primary)
+2. glm/glm-4.7 (Cheap backup)
+3. if/kimi-k2 (Free emergency)
+
+→ Auto-switches when quota exhausted
+→ Never stops coding
+→ Minimal extra cost
+```
+
+**How to create combos:**
+```
+Dashboard → Combos → Create New
+→ Add models in priority order
+→ Use combo name in CLI: "premium-coding"
+```
+
+**Benefits:**
+- Zero downtime when quota runs out
+- Automatic cost optimization
+- Single model name for all tools
+
+See [combos documentation](features/combos.md) for examples.
+
+---
+
+## How does quota tracking work?
+
+**9Router tracks quota in real-time for all providers:**
+
+**Features:**
+- **Token consumption** - Input/output tokens per request
+- **Reset countdown** - Time until quota refreshes
+- **Usage stats** - Daily/weekly/monthly reports
+- **Cost estimation** - Projected spending (paid tiers)
+- **Quota alerts** - Notifications when quota low
+
+**Quota types:**
+- **5-hour rolling** - Claude Code, Codex, MiniMax
+- **Daily reset** - Gemini CLI (1K/day), GLM (10AM)
+- **Weekly reset** - Claude Code, Codex (additional quota)
+- **Monthly reset** - Gemini CLI (180K), GitHub Copilot (1st)
+
+**View quota:**
+```
+Dashboard → Providers → Quota Tracking
+→ Real-time usage + reset countdown
+```
+
+See [quota tracking documentation](features/quota-tracking.md) for details.
+
+---
+
+## Does 9Router work with Cursor?
+
+**Yes, but Cursor requires a cloud endpoint.**
+
+**Problem:** Cursor IDE doesn't support localhost endpoints.
+
+**Solution:** Use 9Router cloud deployment:
+
+```
+Cursor Settings → Models → Advanced:
+  OpenAI API Base URL: https://9router.com/v1
+  OpenAI API Key: [from dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+**Alternative:** Self-host on VPS with public domain:
+```bash
+# Deploy to VPS
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+npm start
+
+# Configure Nginx reverse proxy
+# Point Cursor to: https://your-domain.com/v1
+```
+
+**Other CLI tools work with localhost:**
+- Cline ✅
+- Claude Desktop ✅
+- Codex CLI ✅
+- Continue ✅
+- RooCode ✅
+
+See [Cursor integration guide](integration/cursor.md) for details.
+
+---
+
+## Can I self-host 9Router?
+
+**Yes! 9Router supports multiple deployment options:**
+
+### Localhost (Default)
+```bash
+npm install -g 9router
+9router
+→ Dashboard: http://localhost:3000
+→ API: http://localhost:20128/v1
+```
+
+### VPS/Cloud
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+npm start
+```
+
+### Docker
+```bash
+docker build -t 9router .
+docker run -d \
+  -p 3000:3000 \
+  -e JWT_SECRET="your-secret" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Cloudflare Workers
+```bash
+cd 9router/app
+npm run deploy:cloudflare
+```
+
+**Environment variables:**
+- `JWT_SECRET` - **MUST change in production!**
+- `DATA_DIR` - Database storage path (default: `~/.9router`)
+- `INITIAL_PASSWORD` - Dashboard login (default: `123456`)
+- `NODE_ENV` - Set to `production` for deploy
+
+See [deployment guide](getting-started/installation.md#deployment) for details.
+
+---
+
+## Is my data secure?
+
+**Yes, 9Router prioritizes security and privacy:**
+
+**Local storage:**
+- All data stored locally in `~/.9router` (or custom `DATA_DIR`)
+- No data sent to 9Router servers
+- OAuth tokens encrypted with JWT
+
+**No telemetry:**
+- No usage tracking
+- No analytics
+- No phone-home
+
+**Open source:**
+- Full source code available on GitHub
+- Audit security yourself
+- Community-reviewed
+
+**Best practices:**
+- Change `JWT_SECRET` in production
+- Use strong `INITIAL_PASSWORD`
+- Enable HTTPS for cloud deployments
+- Rotate API keys regularly
+
+**What 9Router stores:**
+- Provider OAuth tokens (encrypted)
+- API keys (encrypted)
+- Usage statistics (local only)
+- Combo configurations
+
+**What 9Router does NOT store:**
+- Your prompts or responses
+- Code you generate
+- Personal information
+
+---
+
+## How do I update 9Router?
+
+**Update methods depend on installation type:**
+
+### Global NPM Install
+```bash
+npm update -g 9router
+```
+
+### Local Install
+```bash
+cd 9router/app
+git pull origin main
+npm install
+npm run build
+npm start
+```
+
+### Docker
+```bash
+docker pull 9router:latest
+docker stop 9router
+docker rm 9router
+docker run -d \
+  -p 3000:3000 \
+  -v 9router-data:/app/data \
+  9router:latest
+```
+
+**Check version:**
+```bash
+9router --version
+```
+
+**Breaking changes:**
+- Check [CHANGELOG.md](https://github.com/decolua/9router/blob/main/CHANGELOG.md)
+- Backup `~/.9router` before major updates
+- Review migration guides for major versions
+
+---
+
+## How can I contribute?
+
+**We welcome contributions!**
+
+### Ways to contribute:
+
+1. **Report bugs:**
+   - [GitHub Issues](https://github.com/decolua/9router/issues)
+   - Include error logs, steps to reproduce
+
+2. **Request features:**
+   - [GitHub Discussions](https://github.com/decolua/9router/discussions)
+   - Describe use case and benefits
+
+3. **Submit code:**
+   ```bash
+   # Fork repo
+   git clone https://github.com/YOUR_USERNAME/9router.git
+   cd 9router
+   
+   # Create branch
+   git checkout -b feature/your-feature
+   
+   # Make changes
+   npm install
+   npm run dev
+   
+   # Test
+   npm test
+   
+   # Commit and push
+   git add .
+   git commit -m "Add your feature"
+   git push origin feature/your-feature
+   
+   # Create Pull Request on GitHub
+   ```
+
+4. **Improve docs:**
+   - Fix typos, add examples
+   - Translate to other languages
+   - Write tutorials
+
+5. **Add providers:**
+   - Implement new provider adapters
+   - See `app/lib/providers/` for examples
+
+**Contribution guidelines:**
+- Follow existing code style
+- Add tests for new features
+- Update documentation
+- Keep commits atomic and descriptive
+
+See [CONTRIBUTING.md](https://github.com/decolua/9router/blob/main/CONTRIBUTING.md) for details.
+
+---
+
+## Need More Help?
+
+- **Documentation:** [9router.com/docs](https://9router.com/docs)
+- **GitHub:** [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **Troubleshooting:** [troubleshooting.md](troubleshooting.md)
diff --git a/gitbook/content/en/features/combos.md b/gitbook/content/en/features/combos.md
new file mode 100644
index 0000000..2b94eff
--- /dev/null
+++ b/gitbook/content/en/features/combos.md
@@ -0,0 +1,537 @@
+# Combos - Custom Fallback Chains
+
+Create custom model combinations with automatic fallback. Combos let you define your own routing strategy based on cost, quality, and availability.
+
+---
+
+## What Are Combos?
+
+Combos are **custom fallback chains** that you create in the dashboard. Instead of using a single model, you define a sequence of models that 9Router tries in order.
+
+**Example:**
+```
+Combo name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101 (try first)
+  2. glm/glm-4.7 (if #1 quota exhausted)
+  3. minimax/MiniMax-M2.1 (if #2 quota exhausted)
+```
+
+**Usage in CLI:**
+```
+Model: premium-coding
+```
+
+9Router automatically tries each model in sequence until one succeeds.
+
+---
+
+## Why Use Combos?
+
+### 1. Maximize Subscription Value
+```
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ Use subscription first, cheap backup, free emergency
+→ Get full value from subscriptions you already pay for
+```
+
+### 2. Minimize Costs
+```
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+
+→ Start with cheapest paid option ($0.60/1M)
+→ Fallback to even cheaper ($0.20/1M)
+→ Emergency free tier
+→ Total cost: ~$5-10/month vs $2000 on ChatGPT API
+```
+
+### 3. Ensure 24/7 Availability
+```
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ Always include free tier at the end
+→ Never run out of quota
+→ Code anytime, anywhere
+```
+
+### 4. Optimize for Quality
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → gc/gemini-3-pro
+
+→ Best models first
+→ Fallback to other premium models
+→ Maintain high quality across fallback chain
+```
+
+---
+
+## How to Create Combos
+
+### Step 1: Open Dashboard
+
+```
+http://localhost:20128
+→ Login with your password
+```
+
+### Step 2: Navigate to Combos
+
+```
+Dashboard → Combos → Create New Combo
+```
+
+### Step 3: Configure Combo
+
+**Combo Name:**
+```
+premium-coding
+```
+
+**Description (optional):**
+```
+Subscription first, cheap backup, free emergency
+```
+
+**Select Models:**
+```
+1. cc/claude-opus-4-5-20251101
+2. glm/glm-4.7
+3. minimax/MiniMax-M2.1
+```
+
+**Drag to reorder** - Priority from top to bottom.
+
+### Step 4: Save
+
+```
+Click "Save Combo"
+→ Combo appears in model list
+```
+
+### Step 5: Use in CLI
+
+```
+Cursor/Cline/Any tool:
+  Model: premium-coding
+```
+
+---
+
+## Example Combos
+
+### Example 1: Premium Coding (Subscription → Cheap → Free)
+
+**Goal**: Maximize subscription value, minimize extra costs.
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101
+  2. glm/glm-4.7
+  3. minimax/MiniMax-M2.1
+```
+
+**Usage:**
+```
+Cursor IDE:
+  Model: premium-coding
+```
+
+**Behavior:**
+```
+Morning (fresh quota):
+  Request → cc/claude-opus-4-5 ✅
+
+Afternoon (Claude quota out):
+  Request → glm/glm-4.7 ✅ (auto switched)
+
+Evening (GLM quota out):
+  Request → minimax/MiniMax-M2.1 ✅ (auto switched)
+```
+
+**Monthly cost (100M tokens):**
+```
+80M via Claude Code: $0 (subscription)
+15M via GLM: $9
+5M via MiniMax: $1
+Total: $10 + your subscription
+```
+
+**Savings**: ~99% vs ChatGPT API ($2000).
+
+---
+
+### Example 2: Budget Combo (Cheap → Free)
+
+**Goal**: Minimize costs, use free tier as backup.
+
+```
+Dashboard → Combos → Create New
+
+Name: budget-combo
+Models:
+  1. glm/glm-4.7
+  2. minimax/MiniMax-M2.1
+  3. if/kimi-k2-thinking
+```
+
+**Usage:**
+```
+Cline:
+  Provider: OpenAI Compatible
+  Base URL: http://localhost:20128/v1
+  Model: budget-combo
+```
+
+**Behavior:**
+```
+Request → glm/glm-4.7
+  ✅ Daily quota available → Use GLM ($0.60/1M)
+  ❌ Quota exhausted → Try MiniMax ($0.20/1M)
+  ❌ MiniMax quota out → Use iFlow (FREE)
+```
+
+**Monthly cost (100M tokens):**
+```
+70M via GLM: $42
+20M via MiniMax: $4
+10M via iFlow: $0
+Total: $46 vs $2000 on ChatGPT API
+```
+
+**Savings**: 97%.
+
+---
+
+### Example 3: Free Combo (Zero Cost)
+
+**Goal**: 100% free, no costs ever.
+
+```
+Dashboard → Combos → Create New
+
+Name: free-combo
+Models:
+  1. if/kimi-k2-thinking
+  2. qw/qwen3-coder-plus
+  3. kr/claude-sonnet-4.5
+```
+
+**Usage:**
+```
+Claude Desktop:
+  Model: free-combo
+```
+
+**Behavior:**
+```
+Request → if/kimi-k2-thinking
+  ✅ Available → Use iFlow
+  ❌ Error → Try Qwen
+  ❌ Error → Try Kiro
+```
+
+**Monthly cost:**
+```
+100M tokens via free providers: $0
+Total: $0 forever
+```
+
+**Use case**: Personal projects, learning, experimentation.
+
+---
+
+### Example 4: Quality First (Premium Models Only)
+
+**Goal**: Best quality, no cheap fallback.
+
+```
+Dashboard → Combos → Create New
+
+Name: quality-first
+Models:
+  1. cc/claude-opus-4-5-20251101
+  2. cx/gpt-5.2-codex
+  3. gc/gemini-3-pro-preview
+```
+
+**Usage:**
+```
+Codex CLI:
+  export OPENAI_BASE_URL="http://localhost:20128"
+  Model: quality-first
+```
+
+**Behavior:**
+```
+Request → cc/claude-opus-4-5
+  ❌ Quota out → cx/gpt-5.2-codex
+  ❌ Quota out → gc/gemini-3-pro-preview
+  ❌ All out → Return error (no cheap fallback)
+```
+
+**Use case**: Critical production code, complex refactoring.
+
+---
+
+### Example 5: Multi-Subscription (Maximize All)
+
+**Goal**: Use all subscriptions before paying extra.
+
+```
+Dashboard → Combos → Create New
+
+Name: multi-sub
+Models:
+  1. gc/gemini-3-flash-preview (FREE 180K/month)
+  2. cc/claude-opus-4-5-20251101 (Pro subscription)
+  3. cx/gpt-5.2-codex (Plus subscription)
+  4. gh/gpt-5 (Copilot subscription)
+  5. glm/glm-4.7 (Cheap backup)
+  6. if/kimi-k2-thinking (Free emergency)
+```
+
+**Monthly cost (200M tokens):**
+```
+50M via Gemini CLI: $0 (free tier)
+80M via Claude Code: $0 (subscription)
+40M via Codex: $0 (subscription)
+20M via Copilot: $0 (subscription)
+8M via GLM: $4.80
+2M via iFlow: $0
+Total: $4.80 + existing subscriptions
+```
+
+**Result**: Use 190M tokens from subscriptions, only $4.80 extra.
+
+---
+
+### Example 6: Quota Reset Optimization
+
+**Goal**: Distribute usage based on reset times.
+
+```
+Dashboard → Combos → Create New
+
+Name: reset-optimized
+Models:
+  1. cc/claude-opus-4-5 (5h reset, use morning)
+  2. gc/gemini-3-flash (1K/day, use afternoon)
+  3. glm/glm-4.7 (daily 10AM reset, use evening)
+  4. minimax/MiniMax-M2.1 (5h rolling, use night)
+  5. if/kimi-k2-thinking (unlimited, emergency)
+```
+
+**Daily routine:**
+```
+08:00 - 13:00: Claude Code (fresh 5h quota)
+13:00 - 18:00: Gemini CLI (1K/day quota)
+18:00 - 22:00: GLM (resets 10AM next day)
+22:00 - 08:00: MiniMax (5h rolling) or iFlow
+```
+
+**Result**: Code 24/7 with minimal costs.
+
+---
+
+## Use Combos in CLI Tools
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from dashboard]
+  Model: premium-coding
+```
+
+### Claude Desktop
+
+Edit `~/.claude/config.json`:
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key",
+  "model": "budget-combo"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex --model quality-first "your prompt"
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: free-combo
+```
+
+### API Request
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "premium-coding",
+    "messages": [
+      {"role": "user", "content": "Write a function to..."}
+    ],
+    "stream": true
+  }'
+```
+
+---
+
+## Best Practices
+
+### 1. Always Include Free Tier
+
+```
+✅ Good:
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+❌ Bad:
+cc/claude-opus → glm/glm-4.7
+(no free fallback, can run out of quota)
+```
+
+**Why**: Ensures 24/7 availability, never blocked by quota.
+
+### 2. Order by Cost (Cheap to Expensive)
+
+```
+✅ Good:
+glm/glm-4.7 → minimax/MiniMax-M2.1 → cc/claude-opus
+
+❌ Bad:
+cc/claude-opus → glm/glm-4.7
+(wastes subscription quota on simple tasks)
+```
+
+**Exception**: If you want to maximize subscription value, put subscription first.
+
+### 3. Match Quality Requirements
+
+```
+For production code:
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7
+
+For quick tasks:
+glm/glm-4.7 → if/kimi-k2-thinking
+
+For experimentation:
+if/kimi-k2-thinking → qw/qwen3-coder-plus
+```
+
+### 4. Consider Quota Reset Times
+
+```
+Morning combo (fresh quotas):
+cc/claude-opus → cx/gpt-5.2-codex
+
+Evening combo (quotas likely exhausted):
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+### 5. Create Multiple Combos for Different Use Cases
+
+```
+premium-coding: For complex tasks
+budget-combo: For simple tasks
+free-combo: For experimentation
+quality-first: For production code
+```
+
+**Switch between combos** based on task requirements.
+
+### 6. Monitor Combo Performance
+
+```
+Dashboard → Analytics → Combo Usage:
+  premium-coding:
+    80% via cc/claude-opus (good, using subscription)
+    15% via glm/glm-4.7 (acceptable backup)
+    5% via minimax (rare fallback)
+```
+
+**Optimize**: If too much fallback usage, increase primary quota or reorder models.
+
+---
+
+## Advanced Configuration
+
+### Set Budget Limits per Combo
+
+```
+Dashboard → Combos → Edit → Budget:
+  Daily limit: $5
+  Monthly limit: $50
+```
+
+When limit reached, 9Router skips paid models and uses free tier only.
+
+### Enable/Disable Models in Combo
+
+```
+Dashboard → Combos → Edit → Models:
+  ✅ cc/claude-opus-4-5 (enabled)
+  ❌ glm/glm-4.7 (temporarily disabled)
+  ✅ if/kimi-k2-thinking (enabled)
+```
+
+**Use case**: Temporarily disable expensive models without deleting combo.
+
+### Clone Existing Combo
+
+```
+Dashboard → Combos → Clone "premium-coding"
+→ Creates copy with "-copy" suffix
+→ Modify and save as new combo
+```
+
+**Use case**: Create variations for different scenarios.
+
+---
+
+## Troubleshooting
+
+**Issue: Combo not appearing in model list**
+
+**Solution:**
+1. Refresh dashboard
+2. Check combo is saved (green checkmark)
+3. Restart CLI tool to refresh model list
+
+**Issue: Combo always uses last model (free tier)**
+
+**Solution:**
+1. Check quota for primary models (Dashboard → Quota)
+2. Verify API keys are valid (Dashboard → Providers)
+3. Check budget limits not exceeded
+
+**Issue: Combo costs more than expected**
+
+**Solution:**
+1. Dashboard → Analytics → Review combo usage
+2. Check if primary models are quota-exhausted
+3. Reorder models (put cheaper first)
+4. Set budget limits
+
+---
+
+## Related
+
+- [Smart Routing](./smart-routing.md) - How auto fallback works
+- [Quota Tracking](./quota-tracking.md) - Monitor usage and costs
diff --git a/gitbook/content/en/features/quota-tracking.md b/gitbook/content/en/features/quota-tracking.md
new file mode 100644
index 0000000..9246807
--- /dev/null
+++ b/gitbook/content/en/features/quota-tracking.md
@@ -0,0 +1,687 @@
+# Quota Tracking & Usage Monitoring
+
+Track real-time token consumption, monitor quota limits, estimate costs, and get alerts before running out. Never waste subscription quota or exceed budget limits.
+
+---
+
+## Overview
+
+9Router provides comprehensive quota tracking for all providers:
+
+- **Real-time token consumption** - See tokens used per request
+- **Quota limits & remaining** - Track usage vs limits
+- **Reset countdown** - Know when quota refreshes
+- **Cost estimation** - Calculate spending for paid tiers
+- **Monthly reports** - Analyze usage patterns
+- **Alerts & notifications** - Get warned before limits
+
+---
+
+## Dashboard Overview
+
+### Quota Summary
+
+```
+Dashboard → Home → Quota Overview
+
+┌─────────────────────────────────────────────┐
+│ Claude Code (cc/)                           │
+│ ████████████░░░░░░░░ 2.5h / 5h (50%)       │
+│ Resets in: 2h 30m                           │
+│ Cost: $0 (subscription)                     │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ Gemini CLI (gc/)                            │
+│ ████████░░░░░░░░░░░░ 450 / 1000 (45%)      │
+│ Daily reset in: 18h 30m                     │
+│ Monthly: 45K / 180K (25%)                   │
+│ Cost: $0 (free tier)                        │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ GLM-4.7 (glm/)                              │
+│ ██████████████░░░░░░ 7M / 10M tokens (70%)  │
+│ Resets: Daily 10:00 AM (in 5h 35m)         │
+│ Cost today: $4.20                           │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ MiniMax M2.1 (minimax/)                     │
+│ ████████████████░░░░ 4M / 5M tokens (80%)   │
+│ Rolling 5h window                           │
+│ Cost (5h): $0.80                            │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ iFlow (if/)                                 │
+│ ████████████████████ Unlimited              │
+│ Cost: $0 (free forever)                     │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Real-Time Token Consumption
+
+### Per-Request Tracking
+
+Every request shows detailed token usage:
+
+```
+Dashboard → Activity → Recent Requests
+
+Request #1234
+Model: cc/claude-opus-4-5-20251101
+Timestamp: 2026-02-04 04:15:32
+
+Tokens:
+  Input: 1,250 tokens
+  Output: 850 tokens
+  Total: 2,100 tokens
+
+Cost: $0 (subscription quota)
+Duration: 3.2s
+Status: ✅ Success
+```
+
+### Live Usage Monitor
+
+```
+Dashboard → Live Monitor
+
+Current request:
+  Model: glm/glm-4.7
+  Tokens streamed: 450 / ~800 estimated
+  Cost so far: $0.0009
+  Duration: 1.8s
+```
+
+### Token Breakdown by Model
+
+```
+Dashboard → Analytics → Token Usage
+
+Today (Feb 4, 2026):
+  cc/claude-opus-4-5: 15M tokens ($0, subscription)
+  glm/glm-4.7: 8M tokens ($4.80)
+  if/kimi-k2-thinking: 3M tokens ($0, free)
+  
+Total: 26M tokens
+Cost: $4.80
+```
+
+---
+
+## Quota Limits & Reset Times
+
+### Subscription Providers
+
+**Claude Code (Pro/Max)**
+```
+Quota type: Time-based (5-hour rolling)
+Limit: 5 hours of usage
+Reset: Rolling 5-hour window + Weekly refresh
+Tracking: Usage time per model
+
+Dashboard shows:
+  Opus: 2.5h / 5h used
+  Sonnet: 1.2h / 5h used
+  Haiku: 0.8h / 5h used
+  
+Weekly reset: Every Monday 00:00 UTC
+```
+
+**OpenAI Codex (Plus/Pro)**
+```
+Quota type: Time-based (5-hour rolling)
+Limit: 5 hours (Plus) / 10 hours (Pro)
+Reset: Rolling 5-hour window + Weekly refresh
+
+Dashboard shows:
+  GPT-5.2 Codex: 3.5h / 5h used
+  Resets in: 1h 30m
+```
+
+**Gemini CLI (FREE)**
+```
+Quota type: Request count + Monthly tokens
+Daily limit: 1,000 requests
+Monthly limit: 180,000 completions
+Reset: Daily 00:00 UTC + Monthly 1st
+
+Dashboard shows:
+  Today: 450 / 1,000 requests (45%)
+  This month: 45K / 180K completions (25%)
+  Daily reset in: 18h 30m
+  Monthly reset in: 26 days
+```
+
+**GitHub Copilot**
+```
+Quota type: Monthly usage
+Limit: Varies by plan
+Reset: 1st of each month
+
+Dashboard shows:
+  Usage: 60% of monthly quota
+  Resets: March 1, 2026 (in 25 days)
+```
+
+### Cheap Providers
+
+**GLM-4.7**
+```
+Quota type: Daily token limit
+Limit: 10M tokens/day (Coding Plan)
+Reset: Daily 10:00 AM Beijing Time (UTC+8)
+
+Dashboard shows:
+  Used: 7M / 10M tokens (70%)
+  Remaining: 3M tokens
+  Resets in: 5h 35m
+  Cost today: $4.20
+```
+
+**MiniMax M2.1**
+```
+Quota type: Rolling 5-hour window
+Limit: 5M tokens per 5 hours
+Reset: Continuous rolling window
+
+Dashboard shows:
+  Used (5h): 4M / 5M tokens (80%)
+  Oldest usage expires in: 45m
+  Cost (5h): $0.80
+```
+
+**Kimi K2**
+```
+Quota type: Monthly subscription
+Limit: 10M tokens/month ($9 flat)
+Reset: Monthly on subscription date
+
+Dashboard shows:
+  Used: 6M / 10M tokens (60%)
+  Resets: Feb 15, 2026 (in 11 days)
+  Cost: $9/month (prepaid)
+```
+
+### Free Providers
+
+**iFlow / Qwen / Kiro**
+```
+Quota type: Unlimited (rate-limited)
+Limit: No hard limit
+Reset: N/A
+
+Dashboard shows:
+  Used today: 5M tokens
+  Cost: $0 (free forever)
+  Status: ✅ Available
+```
+
+---
+
+## Cost Estimation
+
+### Real-Time Cost Tracking
+
+```
+Dashboard → Costs → Today
+
+Subscription providers: $0
+  Claude Code: 15M tokens ($0, included)
+  Gemini CLI: 3M tokens ($0, free tier)
+
+Paid providers: $4.80
+  GLM-4.7: 8M tokens ($4.80)
+    Input: 6M × $0.60/1M = $3.60
+    Output: 2M × $2.20/1M = $4.40
+    Total: $4.80
+
+Free providers: $0
+  iFlow: 3M tokens ($0)
+
+Total today: $4.80
+```
+
+### Monthly Spending Report
+
+```
+Dashboard → Costs → This Month (February 2026)
+
+Week 1 (Feb 1-7):
+  Subscription: $0 (80M tokens)
+  Paid: $15.20 (25M tokens)
+  Free: $0 (10M tokens)
+  Total: $15.20
+
+Week 2 (Feb 8-14):
+  Subscription: $0 (75M tokens)
+  Paid: $12.80 (20M tokens)
+  Free: $0 (8M tokens)
+  Total: $12.80
+
+Month to date: $28.00
+Projected (30 days): ~$120
+
+Breakdown by provider:
+  GLM-4.7: $22.00 (78%)
+  MiniMax M2.1: $6.00 (22%)
+  
+Average cost per 1M tokens: $0.62
+Savings vs ChatGPT API: 97% ($4,000 → $120)
+```
+
+### Cost Projection
+
+```
+Dashboard → Costs → Projections
+
+Based on last 7 days usage:
+  Daily average: 50M tokens
+  Daily cost: $4.50
+
+Monthly projection:
+  Tokens: 1,500M (1.5B)
+  Cost: $135
+  
+Breakdown:
+  Subscription: 900M tokens ($0)
+  GLM-4.7: 450M tokens ($90)
+  MiniMax: 120M tokens ($24)
+  Free: 30M tokens ($0)
+
+Budget status:
+  Daily limit: $5 → 90% used today
+  Monthly limit: $150 → 90% projected
+  ⚠️ Warning: May exceed monthly budget
+```
+
+---
+
+## Usage Dashboard
+
+### Overview Stats
+
+```
+Dashboard → Analytics → Overview
+
+Today (Feb 4, 2026):
+  Requests: 1,234
+  Tokens: 26M
+  Cost: $4.80
+  Avg response time: 2.1s
+
+This week:
+  Requests: 8,456
+  Tokens: 180M
+  Cost: $28.00
+  Success rate: 99.2%
+
+This month:
+  Requests: 15,234
+  Tokens: 320M
+  Cost: $52.00
+  Top model: cc/claude-opus-4-5 (45%)
+```
+
+### Usage by Model
+
+```
+Dashboard → Analytics → Models
+
+Top models (this month):
+1. cc/claude-opus-4-5: 145M tokens (45%)
+2. glm/glm-4.7: 95M tokens (30%)
+3. if/kimi-k2-thinking: 50M tokens (16%)
+4. minimax/MiniMax-M2.1: 20M tokens (6%)
+5. gc/gemini-3-flash: 10M tokens (3%)
+
+Cost breakdown:
+  cc/claude-opus: $0 (subscription)
+  glm/glm-4.7: $45.00
+  if/kimi-k2-thinking: $0 (free)
+  minimax/MiniMax-M2.1: $7.00
+  gc/gemini-3-flash: $0 (free)
+```
+
+### Usage by Time
+
+```
+Dashboard → Analytics → Timeline
+
+Hourly usage (today):
+00:00 - 01:00: 0.5M tokens
+01:00 - 02:00: 0.2M tokens
+...
+08:00 - 09:00: 3.2M tokens (peak)
+09:00 - 10:00: 2.8M tokens
+...
+23:00 - 00:00: 0.8M tokens
+
+Peak hours: 08:00 - 12:00 (morning coding)
+Low hours: 00:00 - 06:00 (night)
+```
+
+### Usage by Combo
+
+```
+Dashboard → Analytics → Combos
+
+premium-coding:
+  Requests: 456
+  Tokens: 12M
+  Cost: $2.40
+  
+  Breakdown:
+    cc/claude-opus: 8M tokens (67%, $0)
+    glm/glm-4.7: 3M tokens (25%, $1.80)
+    minimax/MiniMax-M2.1: 1M tokens (8%, $0.20)
+
+budget-combo:
+  Requests: 234
+  Tokens: 6M
+  Cost: $1.20
+  
+  Breakdown:
+    glm/glm-4.7: 4M tokens (67%, $2.40)
+    if/kimi-k2-thinking: 2M tokens (33%, $0)
+```
+
+---
+
+## Alerts & Notifications
+
+### Quota Alerts
+
+```
+Dashboard → Settings → Alerts
+
+Quota warnings:
+  ✅ Alert at 80% quota used
+  ✅ Alert at 90% quota used
+  ✅ Alert when quota exhausted
+  ✅ Notify when quota resets
+
+Delivery:
+  ✅ Dashboard notification
+  ✅ Email (optional)
+  ✅ Webhook (optional)
+```
+
+**Example notifications:**
+```
+⚠️ Claude Code quota 80% used
+   2.5h remaining (resets in 1h 30m)
+   
+⚠️ GLM-4.7 quota 90% used
+   1M tokens remaining (resets in 5h)
+   
+✅ Gemini CLI quota reset
+   1,000 requests available (daily limit)
+```
+
+### Budget Alerts
+
+```
+Dashboard → Settings → Budget Alerts
+
+Daily budget: $5
+  ✅ Alert at 80% ($4)
+  ✅ Alert at 100% ($5)
+  ✅ Auto-switch to free tier when exceeded
+
+Monthly budget: $150
+  ✅ Alert at 50% ($75)
+  ✅ Alert at 80% ($120)
+  ✅ Alert at 100% ($150)
+```
+
+**Example notifications:**
+```
+⚠️ Daily budget 80% used
+   $4.00 / $5.00 spent today
+   
+⚠️ Monthly budget 50% reached
+   $75 / $150 spent this month
+   Projected: $135 (within budget)
+   
+🚨 Daily budget exceeded
+   $5.20 / $5.00 spent today
+   Auto-switched to free tier
+```
+
+### Cost Anomaly Detection
+
+```
+Dashboard → Settings → Anomaly Detection
+
+✅ Detect unusual spending patterns
+✅ Alert on cost spikes (>2× daily average)
+✅ Warn on quota exhaustion patterns
+
+Example alert:
+⚠️ Cost spike detected
+   Today: $12.50 (2.5× daily average)
+   Reason: High GLM-4.7 usage (20M tokens)
+   Suggestion: Check if primary models quota-exhausted
+```
+
+---
+
+## Best Practices
+
+### 1. Monitor Quota Daily
+
+```
+Daily routine:
+1. Check dashboard quota overview (30 seconds)
+2. Review reset times
+3. Plan usage around quota availability
+```
+
+**Example:**
+```
+Morning check:
+  ✅ Claude Code: 5h available (fresh reset)
+  ✅ Gemini CLI: 1K requests available
+  ⚠️ GLM-4.7: 2M tokens left (resets 10AM)
+  
+Action: Use Claude Code for morning work
+```
+
+### 2. Set Budget Limits
+
+```
+Dashboard → Settings → Budget:
+  Daily: $5 (prevents overspending)
+  Monthly: $150 (aligns with budget)
+```
+
+**Result**: Auto-switch to free tier when limit reached.
+
+### 3. Optimize Combo Usage
+
+```
+Dashboard → Analytics → Combos:
+  Review which models are used most
+  Adjust combo order to minimize costs
+```
+
+**Example:**
+```
+Current: cc/claude-opus → glm/glm-4.7
+  80% via Claude (good)
+  20% via GLM ($12/month)
+
+Optimized: gc/gemini-3-flash → cc/claude-opus → glm/glm-4.7
+  50% via Gemini (free)
+  40% via Claude (subscription)
+  10% via GLM ($6/month)
+  
+Savings: $6/month
+```
+
+### 4. Track Reset Times
+
+```
+Dashboard → Quota → Reset Schedule:
+  Claude Code: 5h rolling + Weekly Monday
+  Gemini CLI: Daily 00:00 UTC + Monthly 1st
+  GLM-4.7: Daily 10:00 AM Beijing Time
+  MiniMax: Rolling 5h window
+```
+
+**Strategy**: Use providers when quota is fresh.
+
+### 5. Review Monthly Reports
+
+```
+Dashboard → Analytics → Monthly Report:
+  Total tokens: 1.5B
+  Total cost: $120
+  Savings: 97% vs ChatGPT API
+  
+Insights:
+  - 60% usage via subscriptions ($0)
+  - 30% via GLM ($90)
+  - 10% via free tier ($0)
+  
+Optimization:
+  - Increase Gemini CLI usage (free)
+  - Reduce GLM usage (expensive)
+```
+
+---
+
+## API Access
+
+### Get Quota Status
+
+```bash
+GET http://localhost:20128/api/quota
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "providers": [
+    {
+      "id": "cc",
+      "name": "Claude Code",
+      "quota": {
+        "used": 2.5,
+        "limit": 5,
+        "unit": "hours",
+        "percentage": 50
+      },
+      "reset": {
+        "type": "rolling",
+        "window": "5h",
+        "nextReset": "2026-02-04T06:45:00Z"
+      },
+      "cost": {
+        "today": 0,
+        "month": 0,
+        "currency": "USD"
+      }
+    },
+    {
+      "id": "glm",
+      "name": "GLM-4.7",
+      "quota": {
+        "used": 7000000,
+        "limit": 10000000,
+        "unit": "tokens",
+        "percentage": 70
+      },
+      "reset": {
+        "type": "daily",
+        "time": "10:00 AM UTC+8",
+        "nextReset": "2026-02-04T10:00:00+08:00"
+      },
+      "cost": {
+        "today": 4.20,
+        "month": 52.00,
+        "currency": "USD"
+      }
+    }
+  ]
+}
+```
+
+### Get Usage Stats
+
+```bash
+GET http://localhost:20128/api/usage?period=today
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "period": "today",
+  "date": "2026-02-04",
+  "summary": {
+    "requests": 1234,
+    "tokens": 26000000,
+    "cost": 4.80
+  },
+  "byModel": [
+    {
+      "model": "cc/claude-opus-4-5",
+      "requests": 456,
+      "tokens": 15000000,
+      "cost": 0
+    },
+    {
+      "model": "glm/glm-4.7",
+      "requests": 234,
+      "tokens": 8000000,
+      "cost": 4.80
+    }
+  ]
+}
+```
+
+---
+
+## Troubleshooting
+
+**Issue: Quota shows 0% but requests failing**
+
+**Solution:**
+1. Check provider connection (Dashboard → Providers)
+2. Verify API keys are valid
+3. Check if provider is down (status page)
+4. Try reconnecting OAuth providers
+
+**Issue: Cost estimation incorrect**
+
+**Solution:**
+1. Dashboard → Settings → Pricing
+2. Verify pricing per provider matches current rates
+3. Update pricing if provider changed rates
+4. Contact support if discrepancy persists
+
+**Issue: Reset time not updating**
+
+**Solution:**
+1. Refresh dashboard (F5)
+2. Check system time is correct
+3. Verify timezone settings
+4. Restart 9Router if issue persists
+
+**Issue: Alerts not received**
+
+**Solution:**
+1. Dashboard → Settings → Alerts
+2. Verify email address is correct
+3. Check spam folder
+4. Test notification (Send Test button)
+
+---
+
+## Related
+
+- [Smart Routing](./smart-routing.md) - Auto fallback based on quota
+- [Combos](./combos.md) - Create custom fallback chains
diff --git a/gitbook/content/en/features/smart-routing.md b/gitbook/content/en/features/smart-routing.md
new file mode 100644
index 0000000..a6aa0c5
--- /dev/null
+++ b/gitbook/content/en/features/smart-routing.md
@@ -0,0 +1,407 @@
+# Smart Routing & Auto Fallback
+
+9Router automatically routes your requests through the best available provider using a 3-tier fallback system. Never stop coding due to quota limits or rate limiting.
+
+---
+
+## How It Works
+
+9Router uses intelligent routing to maximize your existing subscriptions, minimize costs, and ensure 24/7 availability:
+
+```
+Request → 9Router → Check Tier 1 (Subscription)
+                     ↓ quota exhausted
+                     Check Tier 2 (Cheap)
+                     ↓ budget limit
+                     Check Tier 3 (Free)
+                     ↓
+                     Response
+```
+
+### 3-Tier Fallback System
+
+**Tier 1: SUBSCRIPTION (Primary)**
+- Claude Code (Pro/Max)
+- OpenAI Codex (Plus/Pro)
+- Gemini CLI (FREE 180K/month)
+- GitHub Copilot
+- Antigravity (Google)
+
+**Goal**: Maximize value from subscriptions you already pay for.
+
+**Tier 2: CHEAP (Backup)**
+- GLM-4.7 ($0.60/1M input)
+- MiniMax M2.1 ($0.20/1M input)
+- Kimi K2 ($9/month flat)
+
+**Goal**: Ultra-cheap backup when subscription quota runs out (~90% cheaper than ChatGPT API).
+
+**Tier 3: FREE (Emergency)**
+- iFlow (8 models)
+- Qwen (3 models)
+- Kiro (Claude FREE)
+
+**Goal**: Zero-cost fallback for unlimited coding.
+
+---
+
+## Automatic Switching
+
+9Router monitors quota in real-time and switches providers automatically:
+
+### Scenario 1: Subscription Quota Exhausted
+
+```
+User request → cc/claude-opus-4-5
+               ↓ quota exhausted (5-hour limit reached)
+               Auto switch → glm/glm-4.7
+               ↓ daily quota exhausted
+               Auto switch → minimax/MiniMax-M2.1
+               ↓ 5-hour quota exhausted
+               Auto switch → if/kimi-k2-thinking (FREE)
+               ↓
+               Response delivered ✅
+```
+
+**Result**: Zero downtime, seamless experience.
+
+### Scenario 2: Rate Limiting
+
+```
+User request → cx/gpt-5.2-codex
+               ↓ rate limited (too many requests)
+               Auto switch → glm/glm-4.7
+               ↓
+               Response delivered ✅
+```
+
+### Scenario 3: Provider Unavailable
+
+```
+User request → cc/claude-opus-4-5
+               ↓ provider error (503)
+               Auto switch → next available model
+               ↓
+               Response delivered ✅
+```
+
+---
+
+## Model Selection Logic
+
+9Router selects the best model based on:
+
+1. **Quota availability** - Check if provider has remaining quota
+2. **Cost tier** - Prefer subscription → cheap → free
+3. **Reset timing** - Consider when quota resets
+4. **Provider health** - Skip providers with errors
+
+### Priority Order Example
+
+For a request to `cc/claude-opus-4-5`:
+
+```
+1. Check Claude Code quota
+   ✅ Available → Use cc/claude-opus-4-5
+   ❌ Exhausted → Continue to step 2
+
+2. Check fallback tier (if configured)
+   ✅ GLM quota available → Use glm/glm-4.7
+   ❌ Exhausted → Continue to step 3
+
+3. Check free tier
+   ✅ iFlow available → Use if/kimi-k2-thinking
+   ❌ All exhausted → Return quota error
+```
+
+---
+
+## Configuration Options
+
+### Dashboard Settings
+
+**1. Enable/Disable Auto Fallback**
+
+```
+Dashboard → Settings → Smart Routing
+→ Toggle "Auto Fallback" ON/OFF
+```
+
+- **ON** (default): Automatic tier switching
+- **OFF**: Strict mode, return error if primary model unavailable
+
+**2. Set Budget Limits**
+
+```
+Dashboard → Settings → Budget Control
+→ Daily limit: $5
+→ Monthly limit: $50
+```
+
+When budget reached, 9Router automatically switches to free tier.
+
+**3. Configure Fallback Order**
+
+```
+Dashboard → Settings → Fallback Priority
+→ Drag to reorder providers within each tier
+```
+
+Example custom order:
+```
+Tier 1: Gemini CLI → Claude Code → Codex
+Tier 2: MiniMax → GLM → Kimi
+Tier 3: iFlow → Kiro → Qwen
+```
+
+**4. Quota Reset Notifications**
+
+```
+Dashboard → Settings → Notifications
+→ Email when quota resets
+→ Alert when 80% quota used
+```
+
+---
+
+## Examples
+
+### Example 1: Basic Auto Fallback
+
+**Setup:**
+```
+Model: cc/claude-opus-4-5-20251101
+Fallback: Auto (default 3-tier)
+```
+
+**Behavior:**
+```
+Morning (fresh quota):
+  Request → cc/claude-opus-4-5 ✅
+
+Afternoon (quota exhausted):
+  Request → glm/glm-4.7 ✅ (auto switched)
+
+Evening (GLM quota out):
+  Request → minimax/MiniMax-M2.1 ✅ (auto switched)
+
+Late night (all paid quota out):
+  Request → if/kimi-k2-thinking ✅ (free tier)
+```
+
+**Cost**: ~$5-10/month extra (mostly covered by subscription).
+
+### Example 2: Budget-Conscious Routing
+
+**Setup:**
+```
+Dashboard → Settings:
+  Daily budget: $2
+  Monthly budget: $20
+  Fallback: Enabled
+```
+
+**Behavior:**
+```
+Day 1-15 (within budget):
+  Requests → glm/glm-4.7 (cheap tier)
+  Cost: $1.50/day
+
+Day 16 (budget reached):
+  Requests → if/kimi-k2-thinking (free tier)
+  Cost: $0
+
+Next month (budget resets):
+  Requests → glm/glm-4.7 again
+```
+
+**Result**: Never exceed $20/month, always available.
+
+### Example 3: Subscription-Only Mode
+
+**Setup:**
+```
+Dashboard → Settings:
+  Auto Fallback: OFF
+  Strict mode: ON
+```
+
+**Behavior:**
+```
+Request → cc/claude-opus-4-5
+  ✅ Quota available → Success
+  ❌ Quota exhausted → Return error (no fallback)
+```
+
+**Use case**: When you only want to use paid subscriptions, no extra costs.
+
+### Example 4: Free-Only Mode
+
+**Setup:**
+```
+Model: if/kimi-k2-thinking
+Fallback: qw/qwen3-coder-plus → kr/claude-sonnet-4.5
+```
+
+**Behavior:**
+```
+All requests → Free tier only
+Cost: $0 forever
+```
+
+**Use case**: Personal projects, learning, experimentation.
+
+---
+
+## Best Practices
+
+### 1. Maximize Subscription Value
+
+```
+Strategy:
+- Set subscription models as Tier 1
+- Monitor quota usage in dashboard
+- Use cheap tier only when subscription exhausted
+```
+
+**Example combo:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 2. Optimize for Cost
+
+```
+Strategy:
+- Use Gemini CLI free tier first (180K/month)
+- Fallback to GLM/MiniMax (ultra-cheap)
+- Emergency: iFlow (free)
+```
+
+**Example combo:**
+```
+gc/gemini-3-flash-preview → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 3. Optimize for Quality
+
+```
+Strategy:
+- Use best models (Claude Opus, GPT-5.2)
+- Fallback to good cheap models (GLM-4.7)
+- Last resort: Free tier
+```
+
+**Example combo:**
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → glm/glm-4.7
+```
+
+### 4. 24/7 Availability
+
+```
+Strategy:
+- Always include free tier in fallback
+- Monitor quota reset times
+- Distribute usage across providers
+```
+
+**Example combo:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+**Result**: Never run out of quota, code anytime.
+
+---
+
+## Quota Reset Strategy
+
+Plan your usage around quota reset times:
+
+| Provider | Quota Reset | Strategy |
+|----------|-------------|----------|
+| **Claude Code** | 5-hour + weekly | Use in morning, fresh quota |
+| **Codex** | 5-hour + weekly | Use after Claude quota out |
+| **Gemini CLI** | Daily (1K) + Monthly (180K) | Use throughout day |
+| **GLM-4.7** | Daily 10:00 AM | Use evening, resets next morning |
+| **MiniMax M2.1** | 5-hour rolling | Use anytime, tracks rolling window |
+| **iFlow/Qwen/Kiro** | No limit | Emergency backup |
+
+**Daily routine example:**
+```
+08:00 - 13:00: Claude Code (fresh 5h quota)
+13:00 - 18:00: Gemini CLI (1K/day quota)
+18:00 - 22:00: GLM-4.7 (cheap, resets 10AM)
+22:00 - 08:00: MiniMax or iFlow (5h rolling or free)
+```
+
+---
+
+## Monitoring & Alerts
+
+### Dashboard Quota Tracker
+
+```
+Dashboard → Quota Overview:
+  Claude Code: 2.5h / 5h remaining (50%)
+  Gemini CLI: 450 / 1000 requests today
+  GLM-4.7: 5M / 10M tokens (resets in 8h)
+  MiniMax: 3M / 5M tokens (rolling 5h)
+```
+
+### Real-Time Notifications
+
+```
+Dashboard → Notifications:
+  ⚠️ Claude Code quota 80% used (1h remaining)
+  ✅ GLM-4.7 quota reset (10M tokens available)
+  💰 Daily budget 50% used ($2.50 / $5)
+```
+
+### Usage Analytics
+
+```
+Dashboard → Analytics:
+  Today: 50M tokens
+    - 30M via Claude Code (subscription)
+    - 15M via GLM-4.7 ($9)
+    - 5M via iFlow (free)
+  
+  Cost: $9 (vs $1000 on ChatGPT API)
+  Savings: 99%
+```
+
+---
+
+## Troubleshooting
+
+**Issue: "All providers quota exhausted"**
+
+**Solution:**
+1. Check dashboard quota tracker
+2. Wait for quota reset (see countdown)
+3. Add free tier to fallback chain
+4. Or increase budget limit
+
+**Issue: "Too many fallback switches"**
+
+**Solution:**
+1. Check if primary provider is down
+2. Increase quota limits (upgrade subscription)
+3. Use cheaper primary model (GLM instead of Claude)
+
+**Issue: "Unexpected costs"**
+
+**Solution:**
+1. Dashboard → Analytics → Review usage
+2. Set daily/monthly budget limits
+3. Switch to free tier for non-critical tasks
+4. Use combos with free fallback
+
+---
+
+## Related
+
+- [Combos](./combos.md) - Create custom fallback chains
+- [Quota Tracking](./quota-tracking.md) - Monitor usage and costs
diff --git a/gitbook/content/en/getting-started/installation.md b/gitbook/content/en/getting-started/installation.md
new file mode 100644
index 0000000..7e7393f
--- /dev/null
+++ b/gitbook/content/en/getting-started/installation.md
@@ -0,0 +1,478 @@
+# Installation
+
+Detailed installation guide for 9Router with troubleshooting tips.
+
+---
+
+## Requirements
+
+### System Requirements
+
+- **Node.js**: Version 20.0.0 or higher
+- **npm**: Version 10.0.0 or higher (comes with Node.js)
+- **OS**: macOS, Linux, Windows (WSL recommended)
+- **Disk Space**: ~200MB for installation
+
+### Check Your Version
+
+```bash
+node --version
+# Should show v20.x.x or higher
+
+npm --version
+# Should show 10.x.x or higher
+```
+
+**Don't have Node.js?** Install from [nodejs.org](https://nodejs.org/)
+
+---
+
+## Installation Methods
+
+### Method 1: Global Installation (Recommended)
+
+Install 9Router globally to use from anywhere:
+
+```bash
+npm install -g 9router
+```
+
+**Start 9Router:**
+
+```bash
+9router
+```
+
+**Benefits:**
+- ✅ Run from any directory
+- ✅ Simple command: `9router`
+- ✅ Auto-updates with `npm update -g 9router`
+
+### Method 2: Local Installation
+
+Install in a specific project:
+
+```bash
+mkdir my-9router
+cd my-9router
+npm install 9router
+```
+
+**Start 9Router:**
+
+```bash
+npx 9router
+```
+
+**Benefits:**
+- ✅ Isolated per project
+- ✅ Version control per project
+- ✅ No global namespace pollution
+
+### Method 3: From Source (Development)
+
+Clone and build from GitHub:
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install
+npm run build
+npm start
+```
+
+**Benefits:**
+- ✅ Latest development features
+- ✅ Contribute to development
+- ✅ Custom modifications
+
+---
+
+## First Run
+
+### Start the Server
+
+```bash
+9router
+```
+
+**What happens:**
+1. Server starts on `http://localhost:20128`
+2. Dashboard opens automatically in browser
+3. Data directory created at `~/.9router`
+4. API key generated automatically
+
+### Dashboard Login
+
+**Default credentials:**
+- Password: `123456`
+
+**⚠️ Change password immediately:**
+1. Login to dashboard
+2. Settings → Change Password
+3. Use strong password
+
+### Get Your API Key
+
+```
+Dashboard → Settings → API Keys
+→ Copy your API key
+→ Use in CLI tools
+```
+
+**Example API key format:**
+```
+9r_1234567890abcdef1234567890abcdef
+```
+
+---
+
+## Verify Installation
+
+### Check Server Status
+
+```bash
+curl http://localhost:20128/health
+```
+
+**Expected response:**
+```json
+{
+  "status": "ok",
+  "version": "1.0.0"
+}
+```
+
+### List Available Models
+
+```bash
+curl http://localhost:20128/v1/models \
+  -H "Authorization: Bearer your-api-key"
+```
+
+**Expected response:**
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "cc/claude-opus-4-5-20251101",
+      "object": "model",
+      "created": 1234567890,
+      "owned_by": "claude-code"
+    }
+  ]
+}
+```
+
+### Test Chat Completion
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "cc/claude-opus-4-5-20251101",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+Create `.env` file or set environment variables:
+
+```bash
+# Security (REQUIRED in production)
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+
+# Storage
+export DATA_DIR="~/.9router"
+
+# Server
+export PORT="20128"
+export NODE_ENV="production"
+
+# Logging
+export ENABLE_REQUEST_LOGS="false"
+```
+
+### Data Directory
+
+**Default location:** `~/.9router`
+
+**Contents:**
+```
+~/.9router/
+  ├── db.json           # Database (providers, combos, usage)
+  ├── api-keys.json     # API keys
+  └── logs/             # Request logs (if enabled)
+```
+
+**Change location:**
+
+```bash
+export DATA_DIR="/custom/path"
+9router
+```
+
+### Port Configuration
+
+**Default port:** `20128`
+
+**Change port:**
+
+```bash
+export PORT="3000"
+9router
+```
+
+**Or use command line:**
+
+```bash
+9router --port 3000
+```
+
+---
+
+## Troubleshooting
+
+### Port Already in Use
+
+**Error:**
+```
+Error: listen EADDRINUSE: address already in use :::20128
+```
+
+**Solution 1: Kill existing process**
+
+```bash
+# Find process using port 20128
+lsof -i :20128
+
+# Kill process
+kill -9 <PID>
+```
+
+**Solution 2: Use different port**
+
+```bash
+9router --port 3000
+```
+
+### Permission Denied
+
+**Error:**
+```
+Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
+```
+
+**Solution: Use sudo (not recommended) or fix npm permissions**
+
+```bash
+# Fix npm permissions (recommended)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# Then install again
+npm install -g 9router
+```
+
+### Node.js Version Too Old
+
+**Error:**
+```
+Error: The engine "node" is incompatible with this module
+```
+
+**Solution: Update Node.js**
+
+```bash
+# Using nvm (recommended)
+nvm install 20
+nvm use 20
+
+# Or download from nodejs.org
+```
+
+### Dashboard Not Opening
+
+**Issue:** Dashboard doesn't open automatically
+
+**Solution 1: Open manually**
+
+```
+http://localhost:20128
+```
+
+**Solution 2: Check firewall**
+
+```bash
+# macOS: Allow Node.js in System Preferences → Security
+# Linux: Check iptables
+# Windows: Check Windows Firewall
+```
+
+### Cannot Connect to Providers
+
+**Issue:** OAuth login fails or API key invalid
+
+**Solution 1: Check internet connection**
+
+```bash
+ping google.com
+```
+
+**Solution 2: Check provider status**
+
+- Claude Code: [status.anthropic.com](https://status.anthropic.com)
+- OpenAI: [status.openai.com](https://status.openai.com)
+- Gemini: [status.cloud.google.com](https://status.cloud.google.com)
+
+**Solution 3: Regenerate API key**
+
+```
+Dashboard → Provider → Disconnect → Reconnect
+```
+
+### High Memory Usage
+
+**Issue:** 9Router using too much RAM
+
+**Solution: Restart server**
+
+```bash
+# Stop
+pkill -f 9router
+
+# Start
+9router
+```
+
+**Or use PM2 for auto-restart:**
+
+```bash
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+```
+
+---
+
+## Deployment Options
+
+### Local Development
+
+```bash
+npm install -g 9router
+9router
+```
+
+**Use case:** Personal coding, testing
+
+### VPS/Cloud Server
+
+```bash
+# Install
+npm install -g 9router
+
+# Configure
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+# Start with PM2
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+pm2 startup
+```
+
+**Use case:** Team access, remote coding
+
+### Docker
+
+```bash
+docker pull 9router/9router:latest
+
+docker run -d \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret" \
+  -e INITIAL_PASSWORD="your-password" \
+  -v 9router-data:/root/.9router \
+  --name 9router \
+  9router/9router:latest
+```
+
+**Use case:** Containerized deployment, Kubernetes
+
+### Reverse Proxy (Nginx)
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        
+        # SSE support for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+**Use case:** HTTPS, custom domain, load balancing
+
+---
+
+## Uninstallation
+
+### Remove Global Installation
+
+```bash
+npm uninstall -g 9router
+```
+
+### Remove Data Directory
+
+```bash
+rm -rf ~/.9router
+```
+
+### Remove Configuration
+
+```bash
+# Remove environment variables from shell config
+nano ~/.bashrc  # or ~/.zshrc
+# Delete 9router-related exports
+```
+
+---
+
+## Next Steps
+
+- [Getting Started Guide](../getting-started.md) - Connect providers and start coding
+- [Features](../features/) - Explore quota tracking, combos, deployment
+- [Troubleshooting](../troubleshooting.md) - Fix common issues
+
+---
+
+## Need Help?
+
+- **Website**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
diff --git a/gitbook/content/en/getting-started/quick-start.md b/gitbook/content/en/getting-started/quick-start.md
new file mode 100644
index 0000000..b62c65d
--- /dev/null
+++ b/gitbook/content/en/getting-started/quick-start.md
@@ -0,0 +1,247 @@
+# Getting Started
+
+Get 9Router running in 5 minutes and start routing AI requests intelligently.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g 9router
+```
+
+**Requirements:** Node.js 20+ ([Installation details](getting-started/installation.md))
+
+### 2. Start
+
+```bash
+9router
+```
+
+🎉 **Dashboard opens automatically** at `http://localhost:20128`
+
+- Default password: `123456` (change in dashboard)
+- API key generated automatically
+- Ready to connect providers
+
+### 3. Connect Providers
+
+You have 3 ways to connect providers:
+
+#### Option A: OAuth (Subscription Providers)
+
+**Best for:** Claude Code, Codex, Gemini CLI, GitHub Copilot
+
+```
+Dashboard → Providers → Connect [Provider]
+→ OAuth login → Auto token refresh
+→ Quota tracking enabled
+```
+
+**Example: Claude Code**
+1. Click "Connect Claude Code"
+2. Login with your Claude account
+3. Authorize 9Router
+4. ✅ Done! Use model: `cc/claude-opus-4-5-20251101`
+
+#### Option B: API Key (Cheap Providers)
+
+**Best for:** GLM, MiniMax, Kimi, OpenRouter
+
+```
+Dashboard → Providers → Add API Key
+→ Select provider
+→ Paste API key
+→ Save
+```
+
+**Example: GLM-4.7**
+1. Sign up at [Zhipu AI](https://open.bigmodel.cn/)
+2. Get API key from Coding Plan
+3. Dashboard → Add API Key → Provider: `glm` → Paste key
+4. ✅ Done! Use model: `glm/glm-4.7`
+
+#### Option C: Free Providers (No Cost)
+
+**Best for:** iFlow, Qwen, Kiro
+
+```
+Dashboard → Providers → Connect [Free Provider]
+→ Device code or OAuth
+→ Unlimited usage
+```
+
+**Example: iFlow**
+1. Click "Connect iFlow"
+2. Login with iFlow account
+3. Authorize
+4. ✅ Done! Use 8 models: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, etc.
+
+---
+
+## 4. Use in CLI Tools
+
+Point your coding tool to 9Router:
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Claude Desktop
+
+Edit `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-5-20251101
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+---
+
+## 5. Create Smart Combos (Optional)
+
+Combos enable automatic fallback between models:
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. if/kimi-k2-thinking (Free fallback)
+
+Use in CLI: premium-coding
+```
+
+**How it works:**
+1. Tries Claude Opus first (your subscription)
+2. If quota exhausted → GLM-4.7 (ultra-cheap)
+3. If budget limit → iFlow (free)
+4. Zero downtime, automatic switching!
+
+---
+
+## Available Models
+
+### Subscription Models (Maximize First)
+
+**Claude Code (`cc/`)** - Pro/Max subscription:
+- `cc/claude-opus-4-5-20251101` - Claude 4.5 Opus
+- `cc/claude-sonnet-4-5-20250929` - Claude 4.5 Sonnet
+- `cc/claude-haiku-4-5-20251001` - Claude 4.5 Haiku
+
+**Codex (`cx/`)** - Plus/Pro subscription:
+- `cx/gpt-5.2-codex` - GPT 5.2 Codex
+- `cx/gpt-5.1-codex-max` - GPT 5.1 Codex Max
+
+**Gemini CLI (`gc/`)** - FREE 180K/month:
+- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
+- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
+
+**GitHub Copilot (`gh/`)** - Subscription:
+- `gh/gpt-5` - GPT-5
+- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
+
+### Cheap Models (Backup)
+
+**GLM (`glm/`)** - $0.6/$2.2 per 1M:
+- `glm/glm-4.7` - GLM 4.7 (daily reset 10AM)
+
+**MiniMax (`minimax/`)** - $0.20/$1.00 per 1M:
+- `minimax/MiniMax-M2.1` - MiniMax M2.1 (5h reset)
+
+**Kimi (`kimi/`)** - $9/month (10M tokens):
+- `kimi/kimi-latest` - Kimi Latest
+
+### FREE Models (Emergency)
+
+**iFlow (`if/`)** - 8 models FREE:
+- `if/kimi-k2-thinking` - Kimi K2 Thinking
+- `if/qwen3-coder-plus` - Qwen3 Coder Plus
+- `if/glm-4.7` - GLM 4.7
+- `if/deepseek-r1` - DeepSeek R1
+
+**Qwen (`qw/`)** - 3 models FREE:
+- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
+- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
+
+**Kiro (`kr/`)** - 2 models FREE:
+- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
+- `kr/claude-haiku-4.5` - Claude Haiku 4.5
+
+---
+
+## Cost Optimization Strategy
+
+### Monthly Budget: $10-20/month
+
+```
+1. Use Gemini CLI free tier (180K/month) for quick tasks
+2. Use Claude Code subscription quota fully (you already pay)
+3. Fallback to GLM ($0.6/1M) when quota out
+4. Emergency: MiniMax M2.1 ($0.20/1M) or iFlow (free)
+
+Real example (100M tokens/month):
+  60M via Gemini CLI: $0 (free tier)
+  30M via Claude Code: $0 (subscription you already have)
+  8M via GLM: $4.80
+  2M via MiniMax: $0.40
+  Total: $5.20/month + existing subscriptions
+```
+
+### Quota Reset Strategy
+
+```
+Daily routine:
+1. Morning: Fresh Claude Code quota (5h reset)
+2. Afternoon: Switch to Gemini CLI (1K/day)
+3. Evening: GLM daily quota (reset 10AM next day)
+4. Late night: MiniMax (5h rolling) or iFlow (free)
+
+→ Code 24/7 with minimal extra cost!
+```
+
+---
+
+## Next Steps
+
+- [Installation Details](getting-started/installation.md) - Requirements, troubleshooting
+- [Features](features/) - Explore quota tracking, combos, deployment
+- [FAQ](faq.md) - Common questions and answers
+- [Troubleshooting](troubleshooting.md) - Fix common issues
+
+---
+
+## Need Help?
+
+- **Website**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
diff --git a/gitbook/content/en/index.md b/gitbook/content/en/index.md
new file mode 100644
index 0000000..2c25f24
--- /dev/null
+++ b/gitbook/content/en/index.md
@@ -0,0 +1,164 @@
+# Welcome to 9Router
+
+**Use Claude, Codex, Gemini for FREE • Ultra-cheap alternatives from $0.20/1M tokens**
+
+9Router is an AI model router that maximizes your subscription value and minimizes costs through intelligent routing and automatic fallback.
+
+---
+
+## What is 9Router?
+
+9Router is a smart proxy that sits between your coding tools (Cursor, Cline, Claude Desktop) and AI providers. It automatically routes requests to the best available model based on quota, cost, and availability.
+
+**Stop wasting money:**
+- ❌ Subscription quota expires unused every month
+- ❌ Rate limits stop you mid-coding
+- ❌ Expensive APIs ($20-50/month per provider)
+- ❌ Manual switching between providers
+
+**Start maximizing value:**
+- ✅ **Maximize Subscriptions** - Track and use every bit of Claude Code, Codex, Gemini quota
+- ✅ **FREE Available** - Access iFlow, Qwen, Kiro models via CLI
+- ✅ **Ultra-Cheap Backup** - GLM ($0.6/1M), MiniMax M2.1 ($0.20/1M)
+- ✅ **Smart Fallback** - Subscription → Cheap → Free, automatic switching
+
+---
+
+## Key Features
+
+### 🔄 Smart 3-Tier Fallback
+
+```
+Setup once, never stop coding:
+
+Tier 1 (SUBSCRIPTION): Claude Code → Codex → Gemini
+  ↓ quota exhausted
+Tier 2 (CHEAP): GLM-4.7 → MiniMax M2.1 → Kimi
+  ↓ budget limit
+Tier 3 (FREE): iFlow → Qwen → Kiro
+
+→ Automatic switching, zero downtime!
+```
+
+### 📊 Quota Tracking
+
+- Real-time token consumption per provider
+- Reset countdown (5-hour, daily, weekly, monthly)
+- Cost estimation for paid tiers
+- Monthly spending reports
+
+### 🎯 Universal CLI Support
+
+Works with any tool that supports custom OpenAI endpoints:
+
+✅ **Cursor** • **Cline** • **Claude Desktop** • **Codex** • **RooCode** • **Continue** • **Any OpenAI-compatible tool**
+
+### 💰 Cost Optimization
+
+**Real example (100M tokens/month):**
+```
+60M via Gemini CLI: $0 (free tier)
+30M via Claude Code: $0 (subscription you already have)
+8M via GLM: $4.80
+2M via MiniMax: $0.40
+Total: $5.20/month vs $2000 on ChatGPT API!
+```
+
+---
+
+## Why Choose 9Router?
+
+### Maximize Subscriptions
+
+Already paying for Claude Code ($20-100/month) or Codex ($20-200/month)? Get full value:
+
+- Track quota usage in real-time
+- Auto-switch when quota resets (5-hour, weekly)
+- Use every token before it expires
+- Gemini CLI: 180K completions/month **FREE**
+
+### Ultra-Cheap Backup
+
+When subscription quota runs out, pay pennies:
+
+| Provider | Cost per 1M tokens | Reset |
+|----------|-------------------|-------|
+| **GLM-4.7** | $0.60 input / $2.20 output | Daily 10:00 AM |
+| **MiniMax M2.1** | $0.20 input / $1.00 output | 5-hour rolling |
+| **Kimi K2** | $9/month (10M tokens) | Monthly |
+
+**~90% cheaper than ChatGPT API ($20/1M)!**
+
+### Free Forever Fallback
+
+Emergency backup when everything else is quota-limited:
+
+- **iFlow**: 8 models (Kimi K2, Qwen3 Coder Plus, GLM 4.7, MiniMax M2)
+- **Qwen**: 3 models (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro**: Claude Sonnet 4.5, Haiku 4.5 (AWS Builder ID)
+
+---
+
+## Quick Start
+
+Get started in 2 minutes:
+
+```bash
+# Install globally
+npm install -g 9router
+
+# Start (dashboard opens automatically)
+9router
+```
+
+🎉 **Dashboard opens** → Connect providers → Start coding!
+
+**Use in your CLI tool:**
+
+```
+Endpoint: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-5-20251101
+```
+
+[→ Full Getting Started Guide](getting-started.md)
+
+---
+
+## Use Cases
+
+### For Individual Developers
+
+- Maximize your Claude Code/Codex subscription
+- Use Gemini CLI free tier (180K/month)
+- Fallback to ultra-cheap models ($0.20/1M)
+- Code 24/7 without rate limits
+
+### For Teams
+
+- Deploy on VPS/Cloud for shared access
+- Track team spending in real-time
+- Set budget limits per tier
+- Centralized provider management
+
+### For Mobile/Remote Coding
+
+- Use cloud deployment (https://9router.com)
+- Access from iPad, phone, anywhere
+- No localhost limitations
+- Cloudflare edge network (300+ locations)
+
+---
+
+## What's Next?
+
+- [Getting Started](getting-started.md) - Install and configure in 5 minutes
+- [Installation Guide](getting-started/installation.md) - Detailed setup instructions
+- [Features](features/) - Explore all capabilities
+- [FAQ](faq.md) - Common questions
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ for developers maximizing AI value</sub>
+</div>
diff --git a/gitbook/content/en/integration/claude-code.md b/gitbook/content/en/integration/claude-code.md
new file mode 100644
index 0000000..acf5770
--- /dev/null
+++ b/gitbook/content/en/integration/claude-code.md
@@ -0,0 +1,109 @@
+# Claude Code Integration
+
+Integrate 9Router with Claude Code CLI to route your Anthropic API requests through 9Router's intelligent routing system.
+
+## Prerequisites
+
+- Claude Code CLI installed
+- 9Router running locally or cloud endpoint configured
+- API key from 9Router dashboard
+
+## Setup
+
+### 1. Configure Environment Variables
+
+Set the following environment variables in your shell configuration file (`~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`):
+
+```bash
+# Base URL for 9Router
+export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
+
+# Optional: Set default models for aliases
+export ANTHROPIC_DEFAULT_OPUS_MODEL="cc/claude-opus-4-5-20251101"
+export ANTHROPIC_DEFAULT_SONNET_MODEL="cc/claude-sonnet-4-5-20250929"
+export ANTHROPIC_DEFAULT_HAIKU_MODEL="cc/claude-haiku-4-5-20251001"
+```
+
+### 2. Reload Shell Configuration
+
+```bash
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### 3. Verify Configuration
+
+Check that the environment variables are set correctly:
+
+```bash
+echo $ANTHROPIC_BASE_URL
+```
+
+## Model Aliases
+
+Claude Code supports the following model aliases that map to 9Router models:
+
+| Alias | Model | Environment Variable |
+|-------|-------|---------------------|
+| `opus` | Claude Opus 4.5 | `ANTHROPIC_DEFAULT_OPUS_MODEL` |
+| `sonnet` | Claude Sonnet 4.5 | `ANTHROPIC_DEFAULT_SONNET_MODEL` |
+| `haiku` | Claude Haiku 4.5 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` |
+
+## Usage Examples
+
+### Using Model Aliases
+
+```bash
+# Use Opus model
+claude --model opus "Explain quantum computing"
+
+# Use Sonnet model
+claude --model sonnet "Write a Python function"
+
+# Use Haiku model
+claude --model haiku "Quick code review"
+```
+
+### Using Full Model Names
+
+```bash
+claude --model cc/claude-opus-4-5-20251101 "Your prompt here"
+```
+
+## Settings File
+
+Claude Code stores its configuration in `~/.claude/settings.json`. You can manually edit this file if needed:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "defaultModel": "sonnet"
+}
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+If you encounter connection errors:
+
+1. Verify 9Router is running: `curl http://localhost:20128/health`
+2. Check environment variables are set correctly
+3. Ensure no firewall is blocking port 20128
+
+### Model Not Found
+
+If you get "model not found" errors:
+
+1. Verify the model name matches your 9Router configuration
+2. Check that the provider connection is active in 9Router dashboard
+3. Ensure the model is available in your connected providers
+
+## Cloud Endpoint
+
+To use 9Router cloud endpoint instead of localhost:
+
+```bash
+export ANTHROPIC_BASE_URL="https://9router.com"
+```
+
+Make sure you have configured your API key in the 9Router cloud dashboard.
diff --git a/gitbook/content/en/integration/cline.md b/gitbook/content/en/integration/cline.md
new file mode 100644
index 0000000..3fa60e7
--- /dev/null
+++ b/gitbook/content/en/integration/cline.md
@@ -0,0 +1,201 @@
+# Cline Integration
+
+Integrate 9Router with Cline VSCode extension to route your AI requests through 9Router's intelligent routing system.
+
+## Prerequisites
+
+- Visual Studio Code installed
+- Cline extension installed from VSCode marketplace
+- 9Router running locally or cloud endpoint configured
+- API key from 9Router dashboard
+
+## Setup
+
+### 1. Open Cline Settings
+
+1. Open Visual Studio Code
+2. Open the Cline extension panel (click the Cline icon in the sidebar)
+3. Click the **Settings** icon (gear icon) in the Cline panel
+
+### 2. Select API Provider
+
+1. In the Cline settings, find **API Provider** dropdown
+2. Select **Ollama** from the list
+   - Note: We use Ollama provider type because it's compatible with OpenAI-style APIs
+
+### 3. Configure Base URL
+
+Set the base URL to your 9Router endpoint:
+
+**For Local 9Router:**
+```
+http://localhost:20128/v1
+```
+
+**For Cloud 9Router:**
+```
+https://9router.com
+```
+
+**Steps:**
+1. In the **Base URL** field, enter your 9Router endpoint
+2. Make sure to include `/v1` at the end
+
+### 4. Add API Key
+
+1. In the **API Key** field, enter your 9Router API key
+2. You can find your API key in the 9Router dashboard under **Settings → API Keys**
+3. The key should start with `sk-9router-`
+
+### 5. Select Model
+
+1. In the **Model** dropdown, you can either:
+   - Select from available models (if Cline auto-detects them)
+   - Manually enter the model name from your 9Router configuration
+
+2. Common model names:
+   - `gpt-4`
+   - `gpt-4o`
+   - `claude-opus-4-5`
+   - `claude-sonnet-4-5`
+   - `gemini-2.0-flash`
+
+### 6. Save Configuration
+
+Click **Save** or close the settings panel. Cline will automatically save your configuration.
+
+## Configuration Example
+
+Your Cline settings should look like this:
+
+```
+API Provider: Ollama
+Base URL: http://localhost:20128/v1
+API Key: sk-9router-xxxxxxxxxxxxx
+Model: gpt-4
+```
+
+## Available Models
+
+You can use any model configured in your 9Router dashboard. Common examples:
+
+| Model Name | Provider | Description |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## Usage
+
+### Chat with AI
+
+1. Open the Cline panel in VSCode
+2. Type your message in the chat input
+3. Press Enter to send
+4. Cline will use 9Router to process your request
+
+### Code Generation
+
+1. Ask Cline to generate code: "Create a React component for a login form"
+2. Cline will generate code using 9Router
+3. Review and accept the generated code
+
+### Code Explanation
+
+1. Select code in your editor
+2. Ask Cline: "Explain this code"
+3. Get AI-powered explanations through 9Router
+
+### File Operations
+
+1. Ask Cline to create, modify, or delete files
+2. Cline will use 9Router to understand context and make changes
+3. Review changes before accepting
+
+## Troubleshooting
+
+### "Connection Failed" Error
+
+1. Verify 9Router is running: `curl http://localhost:20128/health`
+2. Check that the base URL is correct and includes `/v1`
+3. Ensure no firewall is blocking port 20128
+4. Try restarting VSCode
+
+### "Invalid API Key" Error
+
+1. Verify your API key in 9Router dashboard
+2. Make sure you copied the entire key including the `sk-9router-` prefix
+3. Check that the API key has not expired
+4. Try regenerating a new API key
+
+### "Model Not Found" Error
+
+1. Verify the model name matches exactly with your 9Router configuration
+2. Check that the provider connection is active in 9Router dashboard
+3. Ensure the model is available in your connected providers
+4. Try using the full model name (e.g., `openai/gpt-4` instead of `gpt-4`)
+
+### Cline Not Responding
+
+1. Check the Cline output panel for error messages
+2. Verify your 9Router instance is running and healthy
+3. Try reloading VSCode window (Cmd/Ctrl + Shift + P → "Reload Window")
+4. Check 9Router logs for any errors
+
+## Advanced Configuration
+
+### Using Cloud Endpoint
+
+To use 9Router cloud endpoint instead of localhost:
+
+1. In Cline settings, set Base URL to: `https://9router.com`
+2. Make sure you have configured your API key in the 9Router cloud dashboard
+3. Ensure your cloud endpoint is active and accessible
+
+### Multiple Models
+
+You can quickly switch between models:
+
+1. Open Cline settings
+2. Change the **Model** field to a different model
+3. Save and continue chatting with the new model
+
+### Custom Timeout
+
+If you experience timeout issues with large requests:
+
+1. Open VSCode settings (Cmd/Ctrl + ,)
+2. Search for "Cline timeout"
+3. Increase the timeout value (default is usually 30 seconds)
+
+## Best Practices
+
+1. **Use Appropriate Models**: Choose faster models (like Haiku or Flash) for simple tasks, and more powerful models (like Opus or GPT-4) for complex tasks
+2. **Monitor Usage**: Check 9Router dashboard for usage statistics and costs
+3. **Context Management**: Keep your conversations focused to reduce token usage
+4. **Model Switching**: Switch models based on task complexity to optimize cost and performance
+5. **API Key Security**: Never commit your API key to version control
+
+## Integration with 9Router Features
+
+### Model Routing
+
+9Router automatically routes your requests to the best available provider based on:
+- Model availability
+- Provider health status
+- Cost optimization
+- Load balancing
+
+### Fallback Support
+
+If a provider fails, 9Router automatically falls back to alternative providers configured in your dashboard.
+
+### Usage Tracking
+
+Monitor your Cline usage through 9Router dashboard:
+- Total requests
+- Token usage
+- Cost per model
+- Provider distribution
diff --git a/gitbook/content/en/integration/codex.md b/gitbook/content/en/integration/codex.md
new file mode 100644
index 0000000..06a7073
--- /dev/null
+++ b/gitbook/content/en/integration/codex.md
@@ -0,0 +1,136 @@
+# OpenAI Codex CLI Integration
+
+Integrate 9Router with OpenAI Codex CLI to route your OpenAI API requests through 9Router's intelligent routing system.
+
+## Prerequisites
+
+- OpenAI Codex CLI installed
+- 9Router running locally or cloud endpoint configured
+- API key from 9Router dashboard
+
+## Setup
+
+### 1. Configure Environment Variables
+
+Set the following environment variables in your shell configuration file (`~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`):
+
+```bash
+# Base URL for 9Router
+export OPENAI_BASE_URL="http://localhost:20128/v1"
+
+# API Key from 9Router dashboard
+export OPENAI_API_KEY="your-9router-api-key"
+```
+
+### 2. Reload Shell Configuration
+
+```bash
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### 3. Verify Configuration
+
+Check that the environment variables are set correctly:
+
+```bash
+echo $OPENAI_BASE_URL
+echo $OPENAI_API_KEY
+```
+
+## Available Models
+
+9Router provides the following Codex models:
+
+| Model ID | Description |
+|----------|-------------|
+| `cx/gpt-5.2-codex` | GPT-5.2 Codex - Latest version |
+| `cx/gpt-5.1-codex-max` | GPT-5.1 Codex Max - Extended context |
+
+## Usage Examples
+
+### Basic Usage
+
+```bash
+# Use GPT-5.2 Codex
+codex --model cx/gpt-5.2-codex "Write a function to sort an array"
+
+# Use GPT-5.1 Codex Max
+codex --model cx/gpt-5.1-codex-max "Explain this complex algorithm"
+```
+
+### Code Generation
+
+```bash
+codex --model cx/gpt-5.2-codex "Create a REST API endpoint for user authentication"
+```
+
+### Code Explanation
+
+```bash
+codex --model cx/gpt-5.1-codex-max "Explain what this code does: $(cat myfile.js)"
+```
+
+## Configuration File
+
+You can also configure Codex CLI using a configuration file. Create or edit `~/.codex/config.json`:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "apiKey": "your-9router-api-key",
+  "defaultModel": "cx/gpt-5.2-codex"
+}
+```
+
+## Troubleshooting
+
+### Authentication Errors
+
+If you encounter authentication errors:
+
+1. Verify your API key is correct in 9Router dashboard
+2. Check that `OPENAI_API_KEY` environment variable is set
+3. Ensure the API key has not expired
+
+### Connection Issues
+
+If you encounter connection errors:
+
+1. Verify 9Router is running: `curl http://localhost:20128/health`
+2. Check environment variables are set correctly
+3. Ensure no firewall is blocking port 20128
+
+### Model Not Available
+
+If you get "model not available" errors:
+
+1. Verify the model name matches your 9Router configuration
+2. Check that the OpenAI provider connection is active in 9Router dashboard
+3. Ensure the model is available in your connected providers
+
+## Cloud Endpoint
+
+To use 9Router cloud endpoint instead of localhost:
+
+```bash
+export OPENAI_BASE_URL="https://9router.com"
+```
+
+Make sure you have configured your API key in the 9Router cloud dashboard.
+
+## Advanced Configuration
+
+### Custom Timeout
+
+```bash
+export OPENAI_TIMEOUT=60  # seconds
+```
+
+### Debug Mode
+
+Enable debug mode to see detailed request/response logs:
+
+```bash
+export CODEX_DEBUG=true
+codex --model cx/gpt-5.2-codex "Your prompt"
+```
diff --git a/gitbook/content/en/integration/continue.md b/gitbook/content/en/integration/continue.md
new file mode 100644
index 0000000..3cd8435
--- /dev/null
+++ b/gitbook/content/en/integration/continue.md
@@ -0,0 +1,249 @@
+# Continue VSCode Extension Integration
+
+Integrate 9Router with Continue extension to bring AI assistance directly into Visual Studio Code.
+
+## Prerequisites
+
+- Visual Studio Code installed
+- Continue extension installed from VSCode marketplace
+- 9Router API key from [dashboard](https://9router.com/dashboard)
+- 9Router running (local or cloud)
+
+## Configuration Steps
+
+### 1. Open Continue Configuration
+
+1. Open VSCode
+2. Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
+3. Type "Continue: Open Config" and select it
+4. This opens `~/.continue/config.json`
+
+### 2. Add 9Router Model Configuration
+
+Add the following configuration to your `config.json`:
+
+**Single Model Setup:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**Multiple Models Setup:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus (Best)",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Sonnet (Balanced)",
+      "provider": "openai",
+      "model": "cc/claude-sonnet-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - DeepSeek Chat (Code)",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Haiku (Fast)",
+      "provider": "openai",
+      "model": "cc/claude-haiku-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**For Cloud 9Router:**
+Replace `apiBase` with:
+```json
+"apiBase": "https://9router.com/v1"
+```
+
+### 3. Save and Reload
+
+1. Save the configuration file
+2. Reload VSCode window: `Cmd+Shift+P` → "Developer: Reload Window"
+3. Continue extension will load the new configuration
+
+### 4. Select Model
+
+1. Open Continue sidebar (click Continue icon in left panel)
+2. Click model selector dropdown at the top
+3. Choose your preferred 9Router model
+
+## Available Models
+
+### Claude Models (Anthropic)
+- `cc/claude-opus-4-5-20251101` - Most capable, best for complex tasks
+- `cc/claude-sonnet-4-20250514` - Balanced performance and speed
+- `cc/claude-haiku-4-20250514` - Fastest, good for simple tasks
+
+### DeepSeek Models
+- `cx/deepseek-chat` - Excellent for code generation
+- `cx/deepseek-reasoner` - Best for complex problem solving
+
+### GLM Models (Zhipu AI)
+- `glm/glm-4-plus` - Advanced Chinese and English
+- `glm/glm-4-flash` - Fast responses
+
+## Usage Examples
+
+### Code Explanation
+1. Select code in editor
+2. Open Continue sidebar
+3. Type: "Explain this code"
+4. Model: `cc/claude-sonnet-4-20250514`
+
+### Code Generation
+1. Open Continue sidebar
+2. Type: "Create a React component for user profile card"
+3. Model: `cx/deepseek-chat`
+
+### Refactoring
+1. Select code to refactor
+2. Type: "Refactor this to use async/await"
+3. Model: `cc/claude-sonnet-4-20250514`
+
+### Bug Fixing
+1. Select problematic code
+2. Type: "Find and fix the bug in this code"
+3. Model: `cx/deepseek-reasoner`
+
+## Advanced Configuration
+
+### Custom System Prompts
+
+Add custom system prompts for specific behaviors:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Code Expert",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "systemMessage": "You are an expert programmer. Always provide clean, well-documented code with best practices."
+    }
+  ]
+}
+```
+
+### Temperature and Parameters
+
+Adjust model behavior with parameters:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Creative Writer",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "temperature": 0.9,
+      "topP": 0.95
+    }
+  ]
+}
+```
+
+### Context Providers
+
+Configure what context Continue sends to the model:
+
+```json
+{
+  "contextProviders": [
+    {
+      "name": "code",
+      "params": {
+        "maxLines": 100
+      }
+    },
+    {
+      "name": "diff",
+      "params": {}
+    },
+    {
+      "name": "terminal",
+      "params": {}
+    }
+  ]
+}
+```
+
+## Keyboard Shortcuts
+
+- `Cmd+L` (Mac) / `Ctrl+L` (Windows/Linux) - Open Continue chat
+- `Cmd+I` (Mac) / `Ctrl+I` (Windows/Linux) - Inline edit
+- `Cmd+Shift+R` (Mac) / `Ctrl+Shift+R` (Windows/Linux) - Regenerate response
+
+## Troubleshooting
+
+### Model Not Responding
+- Check 9Router is running: `curl http://localhost:20128/health`
+- Verify API key in config.json
+- Check VSCode Developer Console for errors: `Help` → `Toggle Developer Tools`
+
+### Wrong Model Selected
+- Click model dropdown in Continue sidebar
+- Select correct 9Router model
+- Model name must match exactly (case-sensitive)
+
+### Configuration Not Loading
+- Verify JSON syntax is valid (use JSON validator)
+- Check file location: `~/.continue/config.json`
+- Reload VSCode window after changes
+
+### Slow Performance
+- Switch to faster models (haiku, flash)
+- Reduce context size in contextProviders
+- Check network latency to 9Router
+
+## Best Practices
+
+### Model Selection Strategy
+- **Quick edits**: Use `cc/claude-haiku-4-20250514`
+- **Code generation**: Use `cx/deepseek-chat`
+- **Complex refactoring**: Use `cc/claude-opus-4-5-20251101`
+- **Problem solving**: Use `cx/deepseek-reasoner`
+
+### Context Management
+- Select only relevant code before asking
+- Use specific, clear prompts
+- Break complex tasks into smaller steps
+
+### Cost Optimization
+- Use faster/cheaper models for simple tasks
+- Limit context size when possible
+- Cache frequently used responses
+
+## Next Steps
+
+- [Configure Cursor](cursor.md) for enhanced IDE integration
+- [Set up Roo](roo.md) for AI assistant
+- [Explore CLI usage](../cli/basic-usage.md)
+- [Learn about model selection](../models/overview.md)
diff --git a/gitbook/content/en/integration/cursor.md b/gitbook/content/en/integration/cursor.md
new file mode 100644
index 0000000..146fcfa
--- /dev/null
+++ b/gitbook/content/en/integration/cursor.md
@@ -0,0 +1,149 @@
+# Cursor Integration
+
+Integrate 9Router with Cursor IDE to route your AI requests through 9Router's intelligent routing system.
+
+## Prerequisites
+
+- Cursor IDE installed
+- Cursor Pro account (required for custom API endpoints)
+- 9Router cloud endpoint configured
+- API key from 9Router dashboard
+
+## ⚠️ Important Notes
+
+> **Cloud Endpoint Required**: Cursor routes requests through its own server and does not support localhost endpoints. You must use the 9Router cloud endpoint: `https://9router.com`
+
+> **Cursor Pro Required**: This feature requires a Cursor Pro account to use custom API endpoints.
+
+## Setup
+
+### 1. Open Cursor Settings
+
+1. Open Cursor IDE
+2. Go to **Settings** (Cmd/Ctrl + ,)
+3. Navigate to **Models** section
+
+### 2. Enable OpenAI API
+
+1. Find the **OpenAI API key** option
+2. Enable the toggle to activate custom API configuration
+
+### 3. Configure Base URL
+
+Set the base URL to 9Router cloud endpoint:
+
+```
+https://9router.com
+```
+
+**Steps:**
+1. In the Models settings, locate the **Base URL** field
+2. Enter: `https://9router.com`
+3. Click **Save**
+
+### 4. Add API Key
+
+1. In the **API Key** field, enter your 9Router API key
+2. You can find your API key in the 9Router dashboard under **Settings → API Keys**
+3. Click **Save**
+
+### 5. Add Custom Model
+
+1. Click **View All Models** button
+2. Click **Add Custom Model**
+3. Enter the model name from your 9Router configuration (e.g., `gpt-4`, `claude-opus-4-5`, etc.)
+4. Click **Add**
+
+### 6. Select Model
+
+1. In the Cursor chat interface, click the model selector dropdown
+2. Choose your custom model from the list
+3. Start using 9Router with Cursor!
+
+## Configuration Example
+
+Your Cursor settings should look like this:
+
+```
+OpenAI API: ✓ Enabled
+Base URL: https://9router.com
+API Key: sk-9router-xxxxxxxxxxxxx
+Custom Models: gpt-4, claude-opus-4-5, gemini-2.0-flash
+```
+
+## Available Models
+
+You can use any model configured in your 9Router dashboard. Common examples:
+
+| Model Name | Provider | Description |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## Usage
+
+### Chat Interface
+
+1. Open Cursor chat (Cmd/Ctrl + L)
+2. Select your model from the dropdown
+3. Start chatting with AI through 9Router
+
+### Inline Code Generation
+
+1. Select code in your editor
+2. Press Cmd/Ctrl + K
+3. Enter your prompt
+4. Cursor will use 9Router to generate code
+
+### Code Explanation
+
+1. Select code in your editor
+2. Press Cmd/Ctrl + L
+3. Ask "Explain this code"
+4. Get AI-powered explanations through 9Router
+
+## Troubleshooting
+
+### "Invalid API Key" Error
+
+1. Verify your API key in 9Router dashboard
+2. Make sure you copied the entire key including the `sk-9router-` prefix
+3. Check that the API key has not expired
+4. Try regenerating a new API key
+
+### "Model Not Found" Error
+
+1. Verify the model name matches exactly with your 9Router configuration
+2. Check that the provider connection is active in 9Router dashboard
+3. Ensure the model is available in your connected providers
+4. Try using the full model name (e.g., `openai/gpt-4` instead of `gpt-4`)
+
+### Connection Issues
+
+1. Verify you are using the cloud endpoint: `https://9router.com`
+2. Check your internet connection
+3. Ensure 9Router cloud service is operational
+4. Try disabling VPN or proxy if enabled
+
+### Localhost Not Working
+
+> **Remember**: Cursor does not support localhost endpoints. You must use the cloud endpoint `https://9router.com`. If you need to use a local 9Router instance, consider using a tunneling service like ngrok to expose your local endpoint.
+
+## Cloud Endpoint Setup
+
+If you're running 9Router locally and want to use it with Cursor:
+
+1. Enable cloud endpoint in 9Router settings
+2. Configure your cloud endpoint URL in 9Router dashboard
+3. Use the cloud URL in Cursor settings
+4. Ensure your local 9Router instance is accessible from the internet
+
+## Best Practices
+
+1. **Use Model Aliases**: Create short aliases for frequently used models in 9Router
+2. **Monitor Usage**: Check 9Router dashboard for usage statistics and costs
+3. **Rotate API Keys**: Regularly rotate your API keys for security
+4. **Test Models**: Try different models to find the best one for your use case
diff --git a/gitbook/content/en/integration/other-tools.md b/gitbook/content/en/integration/other-tools.md
new file mode 100644
index 0000000..c08837d
--- /dev/null
+++ b/gitbook/content/en/integration/other-tools.md
@@ -0,0 +1,416 @@
+# Other Tools Integration
+
+9Router is compatible with any tool that supports the OpenAI API format. This guide covers generic integration patterns for various tools and custom applications.
+
+## Overview
+
+9Router provides an OpenAI-compatible API endpoint that works with:
+- Custom scripts and applications
+- API clients and testing tools
+- CLI tools and utilities
+- Third-party integrations
+- Development frameworks
+
+## Generic Setup Pattern
+
+Any OpenAI-compatible tool can connect to 9Router using these settings:
+
+**Local 9Router:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+Model: any 9Router model (cc/*, cx/*, glm/*, etc.)
+```
+
+**Cloud 9Router:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+Model: any 9Router model (cc/*, cx/*, glm/*, etc.)
+```
+
+## Available Models
+
+### Claude Models (Anthropic)
+- `cc/claude-opus-4-5-20251101`
+- `cc/claude-sonnet-4-20250514`
+- `cc/claude-haiku-4-20250514`
+
+### DeepSeek Models
+- `cx/deepseek-chat`
+- `cx/deepseek-reasoner`
+
+### GLM Models (Zhipu AI)
+- `glm/glm-4-plus`
+- `glm/glm-4-flash`
+
+## Integration Examples
+
+### Python with OpenAI SDK
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+response = client.chat.completions.create(
+    model="cc/claude-sonnet-4-20250514",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ]
+)
+
+print(response.choices[0].message.content)
+```
+
+### Node.js with OpenAI SDK
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+const response = await client.chat.completions.create({
+  model: "cc/claude-sonnet-4-20250514",
+  messages: [
+    { role: "user", content: "Hello, how are you?" }
+  ]
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### cURL Command
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-api-key-from-dashboard" \
+  -d '{
+    "model": "cc/claude-sonnet-4-20250514",
+    "messages": [
+      {"role": "user", "content": "Hello, how are you?"}
+    ]
+  }'
+```
+
+### HTTP Client (Postman, Insomnia)
+
+**Request:**
+```
+POST http://localhost:20128/v1/chat/completions
+```
+
+**Headers:**
+```
+Content-Type: application/json
+Authorization: Bearer your-api-key-from-dashboard
+```
+
+**Body:**
+```json
+{
+  "model": "cc/claude-sonnet-4-20250514",
+  "messages": [
+    {"role": "user", "content": "Hello, how are you?"}
+  ],
+  "temperature": 0.7,
+  "max_tokens": 1000
+}
+```
+
+### LangChain Integration
+
+```python
+from langchain.chat_models import ChatOpenAI
+from langchain.schema import HumanMessage
+
+llm = ChatOpenAI(
+    model_name="cc/claude-sonnet-4-20250514",
+    openai_api_key="your-api-key-from-dashboard",
+    openai_api_base="http://localhost:20128/v1",
+    temperature=0.7
+)
+
+messages = [HumanMessage(content="Explain quantum computing")]
+response = llm(messages)
+print(response.content)
+```
+
+### LlamaIndex Integration
+
+```python
+from llama_index.llms import OpenAI
+
+llm = OpenAI(
+    model="cc/claude-sonnet-4-20250514",
+    api_key="your-api-key-from-dashboard",
+    api_base="http://localhost:20128/v1"
+)
+
+response = llm.complete("What is machine learning?")
+print(response.text)
+```
+
+## Custom Script Examples
+
+### Batch Processing Script
+
+```python
+import openai
+import json
+
+openai.api_key = "your-api-key-from-dashboard"
+openai.api_base = "http://localhost:20128/v1"
+
+def process_batch(prompts, model="cx/deepseek-chat"):
+    results = []
+    for prompt in prompts:
+        response = openai.ChatCompletion.create(
+            model=model,
+            messages=[{"role": "user", "content": prompt}]
+        )
+        results.append({
+            "prompt": prompt,
+            "response": response.choices[0].message.content
+        })
+    return results
+
+prompts = [
+    "Explain AI in one sentence",
+    "What is machine learning?",
+    "Define neural networks"
+]
+
+results = process_batch(prompts)
+print(json.dumps(results, indent=2))
+```
+
+### Streaming Response Handler
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+async function streamResponse(prompt) {
+  const stream = await client.chat.completions.create({
+    model: "cc/claude-sonnet-4-20250514",
+    messages: [{ role: "user", content: prompt }],
+    stream: true
+  });
+
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content || "";
+    process.stdout.write(content);
+  }
+}
+
+streamResponse("Write a short story about AI");
+```
+
+### Multi-Model Comparison
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+models = [
+    "cc/claude-sonnet-4-20250514",
+    "cx/deepseek-chat",
+    "glm/glm-4-plus"
+]
+
+prompt = "Explain quantum computing in simple terms"
+
+for model in models:
+    response = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "user", "content": prompt}]
+    )
+    print(f"\n=== {model} ===")
+    print(response.choices[0].message.content)
+```
+
+## Common Integration Patterns
+
+### Environment Variables
+
+Store credentials securely:
+
+```bash
+# .env file
+ROUTER_API_KEY=your-api-key-from-dashboard
+ROUTER_BASE_URL=http://localhost:20128/v1
+ROUTER_MODEL=cc/claude-sonnet-4-20250514
+```
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.getenv("ROUTER_API_KEY"),
+    base_url=os.getenv("ROUTER_BASE_URL")
+)
+```
+
+### Error Handling
+
+```python
+from openai import OpenAI, OpenAIError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+try:
+    response = client.chat.completions.create(
+        model="cc/claude-sonnet-4-20250514",
+        messages=[{"role": "user", "content": "Hello"}]
+    )
+    print(response.choices[0].message.content)
+except OpenAIError as e:
+    print(f"Error: {e}")
+```
+
+### Retry Logic
+
+```python
+import time
+from openai import OpenAI, RateLimitError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+def chat_with_retry(prompt, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            response = client.chat.completions.create(
+                model="cc/claude-sonnet-4-20250514",
+                messages=[{"role": "user", "content": prompt}]
+            )
+            return response.choices[0].message.content
+        except RateLimitError:
+            if attempt < max_retries - 1:
+                time.sleep(2 ** attempt)  # Exponential backoff
+            else:
+                raise
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+**Problem:** Cannot connect to 9Router
+```bash
+# Check if 9Router is running
+curl http://localhost:20128/health
+
+# Expected response:
+{"status": "ok"}
+```
+
+**Solution:**
+- Verify 9Router is running
+- Check port 20128 is not blocked
+- Ensure correct base URL (include `/v1`)
+
+### Authentication Errors
+
+**Problem:** 401 Unauthorized
+```
+Error: Invalid API key
+```
+
+**Solution:**
+- Verify API key from dashboard
+- Check Authorization header format: `Bearer your-api-key`
+- Ensure no extra spaces or newlines in API key
+
+### Model Not Found
+
+**Problem:** 404 Model not found
+```
+Error: Model 'cc/claude-opus' not found
+```
+
+**Solution:**
+- Use exact model name (case-sensitive)
+- Check available models: `curl http://localhost:20128/v1/models`
+- Verify model is enabled in your plan
+
+### Timeout Issues
+
+**Problem:** Request timeout
+```
+Error: Request timed out after 30s
+```
+
+**Solution:**
+- Increase timeout in client configuration
+- Use faster models for time-sensitive tasks
+- Check network connection to 9Router
+
+### Rate Limiting
+
+**Problem:** 429 Too Many Requests
+```
+Error: Rate limit exceeded
+```
+
+**Solution:**
+- Implement exponential backoff
+- Reduce request frequency
+- Check rate limits in dashboard
+- Consider upgrading plan
+
+## Best Practices
+
+### Security
+- Store API keys in environment variables
+- Never commit API keys to version control
+- Use HTTPS for cloud deployments
+- Rotate API keys regularly
+
+### Performance
+- Use appropriate models for task complexity
+- Implement caching for repeated queries
+- Use streaming for long responses
+- Batch requests when possible
+
+### Error Handling
+- Always implement try-catch blocks
+- Add retry logic with exponential backoff
+- Log errors for debugging
+- Provide fallback mechanisms
+
+### Cost Optimization
+- Choose cost-effective models for simple tasks
+- Cache responses when appropriate
+- Monitor usage in dashboard
+- Set request limits in code
+
+## Next Steps
+
+- [Configure Cursor](cursor.md) for IDE integration
+- [Set up Continue](continue.md) for VSCode
+- [Explore CLI usage](../cli/basic-usage.md)
+- [Learn about model selection](../models/overview.md)
+- [API Reference](../api/reference.md)
diff --git a/gitbook/content/en/integration/roo.md b/gitbook/content/en/integration/roo.md
new file mode 100644
index 0000000..4ad7141
--- /dev/null
+++ b/gitbook/content/en/integration/roo.md
@@ -0,0 +1,127 @@
+# Roo AI Assistant Integration
+
+Integrate 9Router with Roo AI Assistant to access multiple AI models through a unified interface.
+
+## Prerequisites
+
+- Roo AI Assistant installed
+- 9Router API key from [dashboard](https://9router.com/dashboard)
+- 9Router running (local or cloud)
+
+## Configuration Steps
+
+### 1. Open Roo Settings
+
+Launch Roo AI Assistant and open the settings panel.
+
+### 2. Configure API Provider
+
+1. Navigate to **API Provider** settings
+2. Select **Ollama** as the provider type
+3. Configure the following settings:
+
+**For Local 9Router:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+```
+
+**For Cloud 9Router:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+```
+
+### 3. Select Model
+
+Choose from available 9Router models:
+
+**Claude Models:**
+- `cc/claude-opus-4-5-20251101` - Most capable
+- `cc/claude-sonnet-4-20250514` - Balanced
+- `cc/claude-haiku-4-20250514` - Fast
+
+**DeepSeek Models:**
+- `cx/deepseek-chat` - General purpose
+- `cx/deepseek-reasoner` - Complex reasoning
+
+**GLM Models:**
+- `glm/glm-4-plus` - Advanced
+- `glm/glm-4-flash` - Fast responses
+
+### 4. Test Connection
+
+Send a test message to verify the integration:
+
+```
+Hello! Can you confirm you're connected through 9Router?
+```
+
+## Usage Examples
+
+### Basic Chat
+```
+Ask Roo: "Explain quantum computing in simple terms"
+Model: cc/claude-sonnet-4-20250514
+```
+
+### Code Generation
+```
+Ask Roo: "Write a Python function to calculate Fibonacci numbers"
+Model: cx/deepseek-chat
+```
+
+### Complex Reasoning
+```
+Ask Roo: "Analyze the trade-offs between microservices and monolithic architecture"
+Model: cx/deepseek-reasoner
+```
+
+## Model Selection Tips
+
+- **Quick tasks**: Use `cc/claude-haiku-4-20250514` or `glm/glm-4-flash`
+- **Balanced performance**: Use `cc/claude-sonnet-4-20250514` or `cx/deepseek-chat`
+- **Complex reasoning**: Use `cc/claude-opus-4-5-20251101` or `cx/deepseek-reasoner`
+- **Cost optimization**: Use DeepSeek or GLM models
+
+## Troubleshooting
+
+### Connection Failed
+- Verify 9Router is running: `curl http://localhost:20128/health`
+- Check API key is correct
+- Ensure Base URL includes `/v1` suffix
+
+### Model Not Available
+- Check model name matches exactly (case-sensitive)
+- Verify model is enabled in your 9Router plan
+- Try a different model from the list
+
+### Slow Responses
+- Switch to faster models (haiku, flash)
+- Check network connection
+- Monitor 9Router logs for issues
+
+## Advanced Configuration
+
+### Custom Model Aliases
+
+You can create shortcuts for frequently used models in Roo settings:
+
+```
+Alias: "fast" → cc/claude-haiku-4-20250514
+Alias: "smart" → cc/claude-opus-4-5-20251101
+Alias: "code" → cx/deepseek-chat
+```
+
+### Multiple Profiles
+
+Set up different profiles for different use cases:
+- **Development**: DeepSeek models for code
+- **Writing**: Claude models for content
+- **Research**: Reasoner models for analysis
+
+## Next Steps
+
+- [Configure Cursor](cursor.md) for IDE integration
+- [Set up Continue](continue.md) for VSCode
+- [Explore CLI usage](../cli/basic-usage.md)
diff --git a/gitbook/content/en/providers/cheap.md b/gitbook/content/en/providers/cheap.md
new file mode 100644
index 0000000..1e97f2f
--- /dev/null
+++ b/gitbook/content/en/providers/cheap.md
@@ -0,0 +1,462 @@
+# Cheap Providers - Ultra-Cheap Backup
+
+When subscription quota runs out, pay pennies instead of dollars. ~90% cheaper than ChatGPT API!
+
+---
+
+## Overview
+
+Cheap tier providers are your **backup** when subscription quota exhausted:
+
+- 💰 **GLM-4.7** - $0.6/$2.2 per 1M tokens (daily reset)
+- 💰 **MiniMax M2.1** - $0.2/$1.0 per 1M tokens (5h reset)
+- 💰 **Kimi K2** - $9/month flat (10M tokens)
+
+**Strategy:** Use after subscription quota out, before free tier. Massive cost savings vs ChatGPT API ($20/1M).
+
+---
+
+## GLM-4.7 (Daily Reset)
+
+### Pricing
+
+| Tier | Input | Output | Reset |
+|------|-------|--------|-------|
+| Standard | $0.60/1M | $2.20/1M | Daily 10:00 AM |
+| Coding Plan | $0.60/1M | $2.20/1M | Daily 10:00 AM (3× quota) |
+
+**Cost Example (10M tokens):**
+- Input: 10M × $0.60 = $6
+- Output: 10M × $2.20 = $22
+- **Total: $6-22** vs $200 on ChatGPT API!
+
+### Setup
+
+**Step 1: Sign Up**
+
+1. Visit [Zhipu AI](https://open.bigmodel.cn/)
+2. Create account (phone verification)
+3. Choose **Coding Plan** for 3× quota at same price
+
+**Step 2: Get API Key**
+
+```bash
+Dashboard → API Keys → Create New
+→ Copy API key (starts with "zhipu-")
+```
+
+**Step 3: Add to 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: glm
+API Key: zhipu-your-api-key-here
+```
+
+**Step 4: Use in CLI**
+
+```
+Model: glm/glm-4.7
+       glm/glm-4.6v (vision)
+```
+
+### Available Models
+
+| Model ID | Description | Context | Best For |
+|----------|-------------|---------|----------|
+| `glm/glm-4.7` | GLM 4.7 | 128K | Coding, general tasks |
+| `glm/glm-4.6v` | GLM 4.6V Vision | 128K | Image analysis |
+
+### Pro Tips
+
+- **Coding Plan** - 3× quota at same price ($0.6/$2.2)
+- **Daily reset** - Fresh quota at 10:00 AM Beijing time
+- **Best for coding** - Optimized for code generation
+- **128K context** - Handle large files
+
+### Quota Reset
+
+```
+Daily reset: 10:00 AM Beijing Time (UTC+8)
+→ 2:00 AM UTC
+→ 6:00 PM PST (previous day)
+→ 9:00 PM EST (previous day)
+
+Plan your heavy tasks around reset time!
+```
+
+---
+
+## MiniMax M2.1 (5-Hour Reset)
+
+### Pricing
+
+| Tier | Input | Output | Reset |
+|------|-------|--------|-------|
+| Standard | $0.20/1M | $1.00/1M | 5-hour rolling |
+
+**Cost Example (10M tokens):**
+- Input: 10M × $0.20 = $2
+- Output: 10M × $1.00 = $10
+- **Total: $2-10** - Cheapest option!
+
+### Setup
+
+**Step 1: Sign Up**
+
+1. Visit [MiniMax](https://www.minimax.io/)
+2. Create account
+3. Verify email/phone
+
+**Step 2: Get API Key**
+
+```bash
+Dashboard → API Management → Create Key
+→ Copy API key
+```
+
+**Step 3: Add to 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: minimax
+API Key: your-minimax-api-key
+```
+
+**Step 4: Use in CLI**
+
+```
+Model: minimax/MiniMax-M2.1
+```
+
+### Available Models
+
+| Model ID | Description | Context | Best For |
+|----------|-------------|---------|----------|
+| `minimax/MiniMax-M2.1` | MiniMax M2.1 | 1M tokens | Long context, coding |
+
+### Pro Tips
+
+- **Cheapest option** - $0.20/1M input (90% cheaper than ChatGPT)
+- **5-hour rolling** - Quota resets every 5 hours
+- **1M context** - Massive context window
+- **Best for long files** - Handle entire codebases
+
+### Quota Reset
+
+```
+5-hour rolling window:
+→ Use quota → Wait 5 hours → Fresh quota
+
+Example:
+10:00 AM - Use 5M tokens
+3:00 PM - Fresh quota available
+8:00 PM - Fresh quota available
+
+Code 24/7 with minimal cost!
+```
+
+---
+
+## Kimi K2 (Flat $9/month)
+
+### Pricing
+
+| Plan | Monthly Cost | Included Tokens | Effective Cost |
+|------|--------------|-----------------|----------------|
+| Subscription | $9 | 10M tokens | $0.90/1M |
+
+**Cost Example:**
+- $9/month flat
+- 10M tokens included
+- **Effective: $0.90/1M** - Best value for consistent usage!
+
+### Setup
+
+**Step 1: Subscribe**
+
+1. Visit [Moonshot AI](https://platform.moonshot.ai/)
+2. Create account
+3. Subscribe to $9/month plan
+
+**Step 2: Get API Key**
+
+```bash
+Dashboard → API Keys → Create New
+→ Copy API key
+```
+
+**Step 3: Add to 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: kimi
+API Key: your-kimi-api-key
+```
+
+**Step 4: Use in CLI**
+
+```
+Model: kimi/kimi-latest
+```
+
+### Available Models
+
+| Model ID | Description | Context | Best For |
+|----------|-------------|---------|----------|
+| `kimi/kimi-latest` | Kimi Latest | 200K | General coding |
+
+### Pro Tips
+
+- **Fixed cost** - $9/month regardless of usage (up to 10M)
+- **Best for consistent usage** - If you use 10M/month, only $0.90/1M
+- **Monthly reset** - 10M tokens reset monthly
+- **Predictable billing** - No surprise costs
+
+### Quota Reset
+
+```
+Monthly reset: 1st of each month
+→ 10M tokens refresh
+
+Example monthly usage:
+Week 1: 3M tokens
+Week 2: 2M tokens
+Week 3: 3M tokens
+Week 4: 2M tokens
+Total: 10M tokens = $9 flat
+```
+
+---
+
+## Pricing Comparison
+
+| Provider | Input/1M | Output/1M | Reset | 10M Cost | Best For |
+|----------|----------|-----------|-------|----------|----------|
+| **GLM-4.7** | $0.60 | $2.20 | Daily 10AM | $6-22 | Daily quota users |
+| **MiniMax M2.1** | $0.20 | $1.00 | 5-hour | $2-10 | **Cheapest!** |
+| **Kimi K2** | $0.90 | $0.90 | Monthly | **$9 flat** | Consistent usage |
+| ChatGPT API | $20.00 | $20.00 | None | $200 | ❌ Expensive |
+
+**Savings:** 90-95% cheaper than ChatGPT API!
+
+---
+
+## Usage Example
+
+### Cursor IDE Setup
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: glm/glm-4.7
+```
+
+### Create Combo (Recommended)
+
+```
+Dashboard → Combos → Create New
+
+Name: cheap-backup
+Models:
+  1. cc/claude-opus-4-5 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, daily reset)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback)
+  4. if/kimi-k2-thinking (FREE emergency)
+
+Use in CLI: cheap-backup
+```
+
+**Result:** Subscription → Cheap → Cheapest → Free
+
+---
+
+## Cost Optimization
+
+### Strategy 1: Daily Reset Routine
+
+```
+Morning (10AM): Fresh GLM quota
+→ Use GLM for heavy tasks
+→ Save subscription quota
+
+Afternoon: Subscription quota
+→ Use Claude/Codex for complex tasks
+
+Evening: MiniMax (5h reset)
+→ Cheap fallback for late work
+
+Night: Free tier (iFlow)
+→ Zero cost emergency backup
+```
+
+### Strategy 2: Budget-First
+
+```
+Set monthly budget: $20
+
+Allocation:
+- $9 Kimi K2 (10M tokens flat)
+- $6 GLM daily quota (10M tokens)
+- $5 MiniMax overflow (25M tokens)
+
+Total: 45M tokens for $20
+vs 1M tokens for $20 on ChatGPT API!
+```
+
+### Strategy 3: Maximize Subscriptions First
+
+```
+Priority:
+1. Gemini CLI (180K/month FREE)
+2. Claude Code (subscription you already pay)
+3. GLM-4.7 (cheap backup, $0.6/1M)
+4. MiniMax M2.1 (cheapest, $0.2/1M)
+5. iFlow (FREE emergency)
+
+Monthly cost example (100M tokens):
+- 60M via Gemini CLI: $0 (free)
+- 30M via Claude Code: $0 (subscription)
+- 8M via GLM: $4.80
+- 2M via MiniMax: $0.40
+Total: $5.20/month!
+```
+
+---
+
+## Real-World Examples
+
+### Example 1: Heavy Coding Month (100M tokens)
+
+```
+Breakdown:
+- 60M via subscription (Claude/Codex): $0 extra
+- 30M via GLM-4.7: $18
+- 10M via MiniMax M2.1: $2
+
+Total: $20/month
+vs $2000 on ChatGPT API!
+
+Savings: 99% cheaper!
+```
+
+### Example 2: Budget Coder ($10/month)
+
+```
+Strategy:
+- $9 Kimi K2 (10M tokens)
+- $1 MiniMax overflow (5M tokens)
+
+Total: 15M tokens for $10
+vs 0.5M tokens for $10 on ChatGPT API!
+
+30× more tokens!
+```
+
+### Example 3: Freelancer (Variable Usage)
+
+```
+Light month (20M tokens):
+- 15M via subscription: $0
+- 5M via GLM: $3
+Total: $3
+
+Heavy month (150M tokens):
+- 60M via subscription: $0
+- 60M via GLM: $36
+- 30M via MiniMax: $6
+Total: $42
+
+Average: $22.50/month
+vs $3400 on ChatGPT API!
+```
+
+---
+
+## Best Practices
+
+### 1. Track Daily Quota
+
+```
+Dashboard shows:
+- GLM quota: 75% used (reset in 6h)
+- MiniMax quota: 50% used (reset in 2h)
+- Kimi quota: 8M/10M used (reset in 15 days)
+
+Plan heavy tasks around reset times!
+```
+
+### 2. Use Coding Plan (GLM)
+
+```
+Standard: 1× quota
+Coding Plan: 3× quota (same price!)
+
+→ Always choose Coding Plan
+```
+
+### 3. Combine with Free Tier
+
+```
+Combo:
+1. gc/gemini-3-flash (FREE primary)
+2. glm/glm-4.7 (cheap backup)
+3. minimax/MiniMax-M2.1 (cheapest)
+4. if/kimi-k2-thinking (FREE emergency)
+
+Result: Minimize costs, maximize uptime
+```
+
+### 4. Set Budget Alerts
+
+```
+Dashboard → Settings → Budget Alerts
+
+Daily: $2 limit
+Weekly: $10 limit
+Monthly: $30 limit
+
+→ Auto switch to free tier when limit reached
+```
+
+---
+
+## Troubleshooting
+
+### "Quota exhausted"
+
+**Solution:**
+- GLM: Wait until 10:00 AM Beijing time
+- MiniMax: Wait 5 hours from first use
+- Kimi: Wait until 1st of next month
+- Use combo fallback to free tier
+
+### "API key invalid"
+
+**Solution:**
+- Check API key copied correctly
+- Verify account has credits
+- Regenerate API key if needed
+
+### "High costs"
+
+**Solution:**
+- Check usage stats in Dashboard
+- Set budget alerts
+- Switch to MiniMax ($0.2/1M cheapest)
+- Use free tier for non-critical tasks
+
+---
+
+## Next Steps
+
+- **Add free fallback:** [Free Providers](./free.md)
+- **Setup subscriptions:** [Subscription Providers](./subscription.md)
+- **Create combos:** Dashboard → Combos → Create New
diff --git a/gitbook/content/en/providers/free.md b/gitbook/content/en/providers/free.md
new file mode 100644
index 0000000..c80a3e1
--- /dev/null
+++ b/gitbook/content/en/providers/free.md
@@ -0,0 +1,442 @@
+# Free Providers - Zero Cost Fallback
+
+Emergency backup when everything else is quota-limited. Code 24/7 with zero cost!
+
+---
+
+## Overview
+
+Free tier providers are your **fallback** when subscription and cheap quota exhausted:
+
+- 🆓 **iFlow** - 8 models FREE (Kimi K2, Qwen3, GLM 4.7, MiniMax M2...)
+- 🆓 **Qwen** - 3 models FREE (Qwen3 Coder Plus/Flash, Vision)
+- 🆓 **Kiro** - 2 models FREE (Claude Sonnet 4.5, Haiku 4.5)
+
+**Strategy:** Use as emergency backup. Unlimited usage, zero cost forever!
+
+---
+
+## iFlow (8 FREE Models)
+
+### Pricing
+
+| Plan | Monthly Cost | Models | Quota |
+|------|--------------|--------|-------|
+| FREE | $0 | 8 models | Unlimited |
+
+**Best Value:** Most models in free tier! Kimi K2, Qwen3, GLM, MiniMax, DeepSeek.
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect iFlow
+```
+
+**Step 2: iFlow OAuth Login**
+
+- Click "Connect iFlow"
+- Browser opens → iFlow login page
+- Create account or login
+- Grant permissions
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: if/kimi-k2-thinking
+       if/kimi-k2
+       if/qwen3-coder-plus
+       if/glm-4.7
+       if/minimax-m2
+       if/deepseek-r1
+       if/deepseek-v3.2-chat
+       if/deepseek-v3.2-reasoner
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `if/kimi-k2-thinking` | Kimi K2 Thinking | Complex reasoning |
+| `if/kimi-k2` | Kimi K2 | General coding |
+| `if/qwen3-coder-plus` | Qwen3 Coder Plus | Code generation |
+| `if/glm-4.7` | GLM 4.7 | Chinese + English |
+| `if/minimax-m2` | MiniMax M2 | Long context |
+| `if/deepseek-r1` | DeepSeek R1 | Reasoning tasks |
+| `if/deepseek-v3.2-chat` | DeepSeek V3.2 Chat | Conversational |
+| `if/deepseek-v3.2-reasoner` | DeepSeek V3.2 Reasoner | Complex logic |
+
+### Pro Tips
+
+- **8 models FREE** - Most variety in free tier
+- **Unlimited usage** - No quota limits
+- **Kimi K2 Thinking** - Best for complex reasoning
+- **DeepSeek R1** - Strong reasoning capabilities
+
+---
+
+## Qwen (3 FREE Models)
+
+### Pricing
+
+| Plan | Monthly Cost | Models | Quota |
+|------|--------------|--------|-------|
+| FREE | $0 | 3 models | Unlimited |
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Qwen
+```
+
+**Step 2: Device Code Authorization**
+
+- Click "Connect Qwen"
+- Dashboard shows device code
+- Visit authorization URL
+- Enter device code
+- Login to Qwen account
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: qw/qwen3-coder-plus
+       qw/qwen3-coder-flash
+       qw/vision-model
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `qw/qwen3-coder-plus` | Qwen3 Coder Plus | Advanced coding |
+| `qw/qwen3-coder-flash` | Qwen3 Coder Flash | Fast responses |
+| `qw/vision-model` | Qwen3 Vision | Image analysis |
+
+### Pro Tips
+
+- **Qwen3 Coder Plus** - Strong coding capabilities
+- **Qwen3 Coder Flash** - Fast for quick tasks
+- **Vision model** - FREE image analysis
+- **Unlimited usage** - No quota limits
+
+---
+
+## Kiro (Claude FREE)
+
+### Pricing
+
+| Plan | Monthly Cost | Models | Quota |
+|------|--------------|--------|-------|
+| FREE | $0 | Claude Sonnet 4.5, Haiku 4.5 | Unlimited |
+
+**Best Value:** FREE Claude! Same quality as paid Claude Code.
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Kiro
+```
+
+**Step 2: AWS Builder ID or OAuth**
+
+- Click "Connect Kiro"
+- Choose login method:
+  - AWS Builder ID (recommended)
+  - Google account
+  - GitHub account
+- Grant permissions
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: kr/claude-sonnet-4.5
+       kr/claude-haiku-4.5
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `kr/claude-sonnet-4.5` | Claude Sonnet 4.5 | Balanced quality/speed |
+| `kr/claude-haiku-4.5` | Claude Haiku 4.5 | Fast responses |
+
+### Pro Tips
+
+- **FREE Claude** - Same quality as paid tier
+- **AWS Builder ID** - Easy setup with AWS account
+- **Unlimited usage** - No quota limits
+- **Best quality** - Claude 4.5 for free!
+
+---
+
+## Feature Comparison
+
+| Provider | Models | Best Model | Setup | Quota |
+|----------|--------|------------|-------|-------|
+| **iFlow** | 8 | Kimi K2 Thinking | OAuth | Unlimited |
+| **Qwen** | 3 | Qwen3 Coder Plus | Device Code | Unlimited |
+| **Kiro** | 2 | Claude Sonnet 4.5 | AWS Builder ID | Unlimited |
+
+**Winner:** iFlow for variety, Kiro for quality!
+
+---
+
+## Usage Example
+
+### Cursor IDE Setup
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: if/kimi-k2-thinking
+```
+
+### Create Combo (Recommended)
+
+```
+Dashboard → Combos → Create New
+
+Name: free-combo
+Models:
+  1. if/kimi-k2-thinking (iFlow primary)
+  2. qw/qwen3-coder-plus (Qwen backup)
+  3. kr/claude-sonnet-4.5 (Kiro quality)
+
+Use in CLI: free-combo
+```
+
+**Result:** Zero cost, maximum uptime!
+
+---
+
+## Full Fallback Strategy
+
+### Complete 3-Tier Combo
+
+```
+Dashboard → Combos → Create New
+
+Name: complete-fallback
+Models:
+  1. gc/gemini-3-flash-preview (FREE subscription)
+  2. cc/claude-opus-4-5 (Paid subscription)
+  3. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  4. minimax/MiniMax-M2.1 (Cheapest, $0.2/1M)
+  5. if/kimi-k2-thinking (FREE fallback)
+  6. kr/claude-sonnet-4.5 (FREE quality)
+
+Use in CLI: complete-fallback
+```
+
+**Result:**
+- Tier 1: FREE subscription (Gemini CLI)
+- Tier 2: Paid subscription (Claude Code)
+- Tier 3: Cheap backup (GLM, MiniMax)
+- Tier 4: FREE fallback (iFlow, Kiro)
+
+**Never stop coding!**
+
+---
+
+## Best Practices
+
+### 1. Use as Emergency Backup
+
+```
+Priority:
+1. Subscription tier (maximize paid quota)
+2. Cheap tier (pennies per 1M tokens)
+3. FREE tier (unlimited, zero cost)
+
+Only use free tier when:
+- Subscription quota exhausted
+- Budget limit reached
+- Testing/non-critical tasks
+```
+
+### 2. Choose Right Model
+
+```
+Complex reasoning: if/kimi-k2-thinking
+Fast coding: qw/qwen3-coder-flash
+Best quality: kr/claude-sonnet-4.5
+Long context: if/minimax-m2
+Vision tasks: qw/vision-model
+```
+
+### 3. Create Free-Only Combo
+
+```
+For zero-cost coding:
+
+Name: zero-cost
+Models:
+  1. kr/claude-sonnet-4.5 (Best quality)
+  2. if/kimi-k2-thinking (Complex tasks)
+  3. qw/qwen3-coder-plus (Fast coding)
+
+Cost: $0 forever!
+```
+
+### 4. Test Before Production
+
+```
+Use free tier to:
+- Test prompts
+- Prototype features
+- Learn new frameworks
+- Non-critical tasks
+
+Save paid quota for:
+- Production code
+- Complex refactoring
+- Critical features
+```
+
+---
+
+## Real-World Examples
+
+### Example 1: Student/Learner (Zero Budget)
+
+```
+Setup:
+1. kr/claude-sonnet-4.5 (Best quality)
+2. if/kimi-k2-thinking (Complex reasoning)
+3. qw/qwen3-coder-plus (Fast coding)
+
+Monthly cost: $0
+Usage: Unlimited
+
+Perfect for:
+- Learning to code
+- Personal projects
+- Homework/assignments
+```
+
+### Example 2: Freelancer (Budget-Conscious)
+
+```
+Setup:
+1. gc/gemini-3-flash-preview (FREE 180K/month)
+2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+3. if/kimi-k2-thinking (FREE fallback)
+
+Monthly cost: $5-10
+Usage: 100M+ tokens
+
+Perfect for:
+- Client projects (paid tier)
+- Testing (free tier)
+- Emergency backup
+```
+
+### Example 3: Heavy User (Maximize Everything)
+
+```
+Setup:
+1. gc/gemini-3-flash-preview (FREE 180K/month)
+2. cc/claude-opus-4-5 (Subscription $20-100)
+3. cx/gpt-5.2-codex (Subscription $20-200)
+4. glm/glm-4.7 (Cheap $0.6/1M)
+5. minimax/MiniMax-M2.1 (Cheapest $0.2/1M)
+6. if/kimi-k2-thinking (FREE unlimited)
+7. kr/claude-sonnet-4.5 (FREE quality)
+
+Monthly cost: $40-320 (subscriptions) + $10-20 (cheap tier)
+Usage: 500M+ tokens
+
+Perfect for:
+- Professional development
+- Team projects
+- 24/7 coding
+```
+
+---
+
+## Cost Comparison
+
+### Scenario: 100M tokens/month
+
+**Option 1: ChatGPT API Only**
+```
+100M × $20/1M = $2,000/month
+```
+
+**Option 2: 9Router Free Tier Only**
+```
+100M via free tier = $0/month
+Savings: $2,000/month (100%)
+```
+
+**Option 3: 9Router Complete Strategy**
+```
+60M via Gemini CLI (FREE): $0
+30M via Claude Code (subscription): $0 extra
+8M via GLM (cheap): $4.80
+2M via iFlow (FREE): $0
+Total: $4.80/month + subscriptions you already have
+Savings: $1,995/month (99.76%)
+```
+
+---
+
+## Troubleshooting
+
+### "OAuth failed"
+
+**Solution:**
+- Check internet connection
+- Try different browser
+- Clear browser cache
+- Reconnect in dashboard
+
+### "Model not available"
+
+**Solution:**
+- Check provider connected in dashboard
+- Verify OAuth token valid
+- Reconnect provider if needed
+
+### "Slow responses"
+
+**Solution:**
+- Free tier may have lower priority
+- Use during off-peak hours
+- Switch to different free provider
+- Upgrade to cheap tier for speed
+
+---
+
+## Limitations
+
+### Free Tier Considerations
+
+- **Speed** - May be slower than paid tiers
+- **Priority** - Lower priority during peak hours
+- **Rate limits** - Possible rate limiting (but unlimited quota)
+- **Availability** - May have occasional downtime
+
+**Solution:** Use 3-tier fallback strategy for reliability!
+
+---
+
+## Next Steps
+
+- **Setup subscriptions:** [Subscription Providers](./subscription.md)
+- **Add cheap backup:** [Cheap Providers](./cheap.md)
+- **Create combos:** Dashboard → Combos → Create New
+- **Start coding:** Use `complete-fallback` combo for maximum reliability
diff --git a/gitbook/content/en/providers/subscription.md b/gitbook/content/en/providers/subscription.md
new file mode 100644
index 0000000..830f429
--- /dev/null
+++ b/gitbook/content/en/providers/subscription.md
@@ -0,0 +1,404 @@
+# Subscription Providers - Maximize Your Value
+
+Maximize your existing AI subscriptions with smart quota tracking and automatic fallback. Use every bit of your subscription before it resets!
+
+---
+
+## Overview
+
+Subscription tier providers are your **primary** choice - you're already paying for them, so get full value:
+
+- ✅ **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
+- ✅ **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
+- ✅ **Gemini CLI** (FREE tier!) - 180K completions/month
+- ✅ **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
+- ✅ **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
+
+**Strategy:** Use these first, track quota in real-time, fallback to cheap/free when exhausted.
+
+---
+
+## Claude Code (Pro/Max)
+
+### Pricing
+
+| Plan | Monthly Cost | Quota Reset | Models |
+|------|--------------|-------------|--------|
+| Pro | $20 | 5-hour + Weekly | Opus, Sonnet, Haiku |
+| Max | $100 | 5-hour + Weekly | Opus, Sonnet, Haiku |
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard opens → Providers → Connect Claude Code
+```
+
+**Step 2: OAuth Login**
+
+- Click "Connect Claude Code"
+- Browser opens → Login to Claude.ai
+- Auto token refresh enabled
+- Quota tracking starts
+
+**Step 3: Use in CLI**
+
+```
+Model: cc/claude-opus-4-5-20251101
+       cc/claude-sonnet-4-5-20250929
+       cc/claude-haiku-4-5-20251001
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `cc/claude-opus-4-5-20251101` | Claude 4.5 Opus | Complex tasks, architecture |
+| `cc/claude-sonnet-4-5-20250929` | Claude 4.5 Sonnet | Balanced speed/quality |
+| `cc/claude-haiku-4-5-20251001` | Claude 4.5 Haiku | Fast responses |
+
+### Pro Tips
+
+- **Use Opus for complex tasks** - Architecture decisions, refactoring
+- **Use Sonnet for speed** - Quick edits, code generation
+- **Track quota per model** - Dashboard shows usage per model
+- **5-hour reset** - Fresh quota every 5 hours + weekly reset
+
+---
+
+## OpenAI Codex (Plus/Pro)
+
+### Pricing
+
+| Plan | Monthly Cost | Quota Reset | Models |
+|------|--------------|-------------|--------|
+| Plus | $20 | 5-hour + Weekly | GPT 5.2, GPT 5.1 |
+| Pro | $200 | 5-hour + Weekly | GPT 5.2 Codex, GPT 5.1 Max |
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Codex
+```
+
+**Step 2: OAuth Login**
+
+- Click "Connect Codex"
+- Browser opens to `http://localhost:1455`
+- Login to OpenAI account
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: cx/gpt-5.2-codex
+       cx/gpt-5.1-codex-max
+       cx/gpt-5.2
+       cx/gpt-5.1-codex
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `cx/gpt-5.2-codex` | GPT 5.2 Codex | Latest coding model |
+| `cx/gpt-5.1-codex-max` | GPT 5.1 Codex Max | Maximum context |
+| `cx/gpt-5.2` | GPT 5.2 | General tasks |
+| `cx/gpt-5.1-codex` | GPT 5.1 Codex | Stable coding |
+
+### Pro Tips
+
+- **5-hour rolling quota** - Fresh quota every 5 hours
+- **Weekly reset** - Full quota reset weekly
+- **Pro tier** - 10× more quota than Plus
+
+---
+
+## Gemini CLI (FREE 180K/month!)
+
+### Pricing
+
+| Plan | Monthly Cost | Quota | Reset |
+|------|--------------|-------|-------|
+| FREE | $0 | 180K completions/month + 1K/day | Daily + Monthly |
+
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Gemini CLI
+```
+
+**Step 2: Google OAuth**
+
+- Click "Connect Gemini CLI"
+- Browser opens → Login to Google account
+- Grant permissions
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: gc/gemini-3-flash-preview
+       gc/gemini-3-pro-preview
+       gc/gemini-2.5-pro
+       gc/gemini-2.5-flash
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `gc/gemini-3-flash-preview` | Gemini 3 Flash Preview | Fast responses |
+| `gc/gemini-3-pro-preview` | Gemini 3 Pro Preview | Complex tasks |
+| `gc/gemini-2.5-pro` | Gemini 2.5 Pro | Stable production |
+| `gc/gemini-2.5-flash` | Gemini 2.5 Flash | Quick tasks |
+
+### Pro Tips
+
+- **180K completions/month** - Massive free tier
+- **1K/day limit** - Daily quota resets at midnight
+- **Use first** - Free tier, use before paid subscriptions
+- **No credit card** - Completely free with Google account
+
+---
+
+## GitHub Copilot
+
+### Pricing
+
+| Plan | Monthly Cost | Quota Reset | Models |
+|------|--------------|-------------|--------|
+| Individual | $10 | Monthly (1st) | GPT-5, Claude 4.5, Gemini 3 |
+| Business | $19 | Monthly (1st) | GPT-5, Claude 4.5, Gemini 3 |
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect GitHub
+```
+
+**Step 2: OAuth via GitHub**
+
+- Click "Connect GitHub"
+- Browser opens → Login to GitHub
+- Authorize GitHub Copilot
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: gh/gpt-5
+       gh/gpt-5.1-codex-max
+       gh/claude-4.5-sonnet
+       gh/gemini-3-pro
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `gh/gpt-5` | GPT-5 | Latest OpenAI model |
+| `gh/gpt-5.1-codex-max` | GPT-5.1 Codex Max | Maximum context |
+| `gh/claude-4.5-sonnet` | Claude 4.5 Sonnet | Anthropic quality |
+| `gh/gemini-3-pro` | Gemini 3 Pro | Google quality |
+
+### Pro Tips
+
+- **Monthly reset** - Full quota reset on 1st of month
+- **Multiple models** - Access GPT, Claude, Gemini in one subscription
+- **Business tier** - Higher quota for teams
+
+---
+
+## Antigravity (Google Account)
+
+### Pricing
+
+| Plan | Monthly Cost | Quota | Models |
+|------|--------------|-------|--------|
+| FREE | $0 | Similar to Gemini CLI | Gemini 3 Pro, Claude Sonnet 4.5 |
+
+### Setup
+
+**Step 1: Connect via Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Antigravity
+```
+
+**Step 2: Google OAuth**
+
+- Click "Connect Antigravity"
+- Browser opens → Login to Google account
+- Grant permissions
+- Auto token refresh enabled
+
+**Step 3: Use in CLI**
+
+```
+Model: ag/gemini-3-pro-high
+       ag/claude-sonnet-4-5
+       ag/claude-opus-4-5-thinking
+```
+
+### Available Models
+
+| Model ID | Description | Best For |
+|----------|-------------|----------|
+| `ag/gemini-3-pro-high` | Gemini 3 Pro High | High-quality responses |
+| `ag/claude-sonnet-4-5` | Claude Sonnet 4.5 | Anthropic quality |
+| `ag/claude-opus-4-5-thinking` | Claude Opus 4.5 Thinking | Complex reasoning |
+
+### Pro Tips
+
+- **Free tier** - No cost with Google account
+- **Claude access** - Free Claude Sonnet/Opus
+- **Quota similar to Gemini CLI** - Daily/monthly limits
+
+---
+
+## Pricing Comparison
+
+| Provider | Monthly Cost | Quota Reset | Value |
+|----------|--------------|-------------|-------|
+| **Claude Code Pro** | $20 | 5-hour + Weekly | ⭐⭐⭐⭐⭐ Best quality |
+| **Claude Code Max** | $100 | 5-hour + Weekly | ⭐⭐⭐⭐⭐ Highest quota |
+| **Codex Plus** | $20 | 5-hour + Weekly | ⭐⭐⭐⭐ Good value |
+| **Codex Pro** | $200 | 5-hour + Weekly | ⭐⭐⭐⭐⭐ 10× quota |
+| **Gemini CLI** | **$0** | Daily + Monthly | ⭐⭐⭐⭐⭐ FREE 180K/month! |
+| **GitHub Copilot** | $10-19 | Monthly (1st) | ⭐⭐⭐⭐ Multi-model |
+| **Antigravity** | **$0** | Daily + Monthly | ⭐⭐⭐⭐ FREE Claude! |
+
+---
+
+## Usage Example
+
+### Cursor IDE Setup
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Create Combo (Recommended)
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. gc/gemini-3-flash-preview (FREE, use first)
+  2. cc/claude-opus-4-5-20251101 (Subscription)
+  3. cx/gpt-5.2-codex (Subscription backup)
+
+Use in CLI: premium-coding
+```
+
+**Result:** Maximize free tier → Use subscription → Auto fallback
+
+---
+
+## Quota Tracking
+
+9Router tracks quota in real-time:
+
+- **Token consumption** - Input/output tokens per request
+- **Reset countdown** - Time until next quota reset
+- **Usage percentage** - How much quota used
+- **Auto fallback** - Switch to next tier when exhausted
+
+**Dashboard view:**
+
+```
+Claude Code Pro
+├─ Quota: 75% used
+├─ Reset: 2h 15m (5-hour)
+├─ Weekly reset: 3 days
+└─ Fallback: glm/glm-4.7 (cheap tier)
+```
+
+---
+
+## Best Practices
+
+### 1. Use Free Tier First
+
+```
+Priority:
+1. Gemini CLI (180K/month FREE)
+2. Antigravity (FREE Claude)
+3. Claude Code/Codex (paid subscriptions)
+```
+
+### 2. Track Quota Daily
+
+- Check dashboard every morning
+- Plan heavy tasks around quota resets
+- Use cheap/free tier for non-critical tasks
+
+### 3. Create Smart Combos
+
+```
+Example combo:
+1. gc/gemini-3-flash-preview (FREE primary)
+2. cc/claude-opus-4-5 (Complex tasks)
+3. glm/glm-4.7 (Cheap backup)
+4. if/kimi-k2-thinking (FREE fallback)
+```
+
+### 4. Optimize by Time
+
+```
+Morning: Fresh 5-hour quota (Claude/Codex)
+Afternoon: Gemini CLI (1K/day)
+Evening: Subscription quota
+Night: Cheap/free tier
+```
+
+---
+
+## Troubleshooting
+
+### "Quota exhausted"
+
+**Solution:**
+- Check dashboard quota tracker
+- Wait for reset (5-hour or daily)
+- Use combo fallback to cheap/free tier
+
+### "OAuth token expired"
+
+**Solution:**
+- Auto-refreshed by 9Router
+- If issues: Dashboard → Provider → Reconnect
+
+### "Rate limiting"
+
+**Solution:**
+- Subscription quota out
+- Add fallback: `cc/claude-opus → glm/glm-4.7`
+- Use free tier: `if/kimi-k2-thinking`
+
+---
+
+## Next Steps
+
+- **Setup cheap backup:** [Cheap Providers](./cheap.md)
+- **Add free fallback:** [Free Providers](./free.md)
+- **Create combos:** Dashboard → Combos → Create New
diff --git a/gitbook/content/en/troubleshooting.md b/gitbook/content/en/troubleshooting.md
new file mode 100644
index 0000000..5b38fa4
--- /dev/null
+++ b/gitbook/content/en/troubleshooting.md
@@ -0,0 +1,351 @@
+# Troubleshooting
+
+Common issues and solutions when using 9Router.
+
+---
+
+## "Language model did not provide messages"
+
+**Problem:** Request fails with empty response or error message.
+
+**Causes:**
+- Provider quota exhausted
+- API key invalid or expired
+- Model not available
+
+**Solutions:**
+
+1. **Check quota status:**
+   ```
+   Dashboard → Providers → View quota tracker
+   ```
+   If quota is exhausted, wait for reset or switch provider.
+
+2. **Use combo fallback:**
+   ```
+   Dashboard → Combos → Create fallback chain
+   Example: cc/claude-opus → glm/glm-4.7 → if/kimi-k2
+   ```
+
+3. **Verify provider connection:**
+   ```
+   Dashboard → Providers → Reconnect if needed
+   ```
+
+---
+
+## Rate Limiting
+
+**Problem:** "Rate limit exceeded" or "Too many requests" errors.
+
+**Causes:**
+- Subscription quota depleted (5-hour/daily/weekly limits)
+- API rate limits hit
+- Too many concurrent requests
+
+**Solutions:**
+
+1. **Check reset time:**
+   ```
+   Dashboard → Quota Tracking → View reset countdown
+   ```
+
+2. **Switch to cheap tier:**
+   ```
+   Use: glm/glm-4.7 ($0.6/1M tokens)
+        minimax/MiniMax-M2.1 ($0.20/1M tokens)
+   ```
+
+3. **Add fallback combo:**
+   ```
+   Dashboard → Combos → Add backup models
+   Primary: cc/claude-opus (subscription)
+   Backup: glm/glm-4.7 (cheap)
+   Emergency: if/kimi-k2 (free)
+   ```
+
+---
+
+## OAuth Token Expired
+
+**Problem:** "Unauthorized" or "Token expired" errors.
+
+**Causes:**
+- OAuth token expired (auto-refresh failed)
+- Provider session invalidated
+- Network issues during refresh
+
+**Solutions:**
+
+1. **Auto-refresh (default):**
+   9Router automatically refreshes tokens. Wait 30 seconds and retry.
+
+2. **Manual reconnect:**
+   ```
+   Dashboard → Providers → [Provider Name] → Reconnect
+   → Complete OAuth flow again
+   ```
+
+3. **Check provider status:**
+   Verify provider service is online (Claude Code, Codex, etc.)
+
+---
+
+## High Costs
+
+**Problem:** Unexpected high usage or costs.
+
+**Causes:**
+- Using expensive models unnecessarily
+- No fallback to cheaper tiers
+- Large context windows
+
+**Solutions:**
+
+1. **Check usage stats:**
+   ```
+   Dashboard → Usage Stats → View token consumption
+   → Identify high-cost models
+   ```
+
+2. **Switch to cheaper models:**
+   ```
+   Replace: cc/claude-opus ($20-100/month subscription)
+   With: glm/glm-4.7 ($0.6/1M tokens)
+         minimax/MiniMax-M2.1 ($0.20/1M tokens)
+   ```
+
+3. **Use free tier:**
+   ```
+   if/kimi-k2-thinking (FREE)
+   qw/qwen3-coder-plus (FREE)
+   kr/claude-sonnet-4.5 (FREE)
+   gc/gemini-3-flash-preview (FREE 180K/month)
+   ```
+
+4. **Optimize prompts:**
+   - Reduce context size
+   - Use streaming for long responses
+   - Cache common prompts
+
+---
+
+## Connection Refused
+
+**Problem:** "ECONNREFUSED" or "Cannot connect to localhost:20128".
+
+**Causes:**
+- 9Router not running
+- Port 20128 blocked
+- Firewall blocking connection
+
+**Solutions:**
+
+1. **Start 9Router:**
+   ```bash
+   9router
+   ```
+   Dashboard should open at http://localhost:3000
+
+2. **Verify port 20128:**
+   ```bash
+   # Check if port is listening
+   lsof -i :20128
+   
+   # Or on Windows
+   netstat -ano | findstr :20128
+   ```
+
+3. **Check firewall:**
+   - macOS: System Settings → Network → Firewall
+   - Windows: Windows Defender Firewall → Allow app
+   - Linux: `sudo ufw allow 20128`
+
+4. **Use cloud endpoint:**
+   If localhost doesn't work (e.g., Cursor IDE):
+   ```
+   Endpoint: https://9router.com/v1
+   ```
+
+---
+
+## Dashboard Not Opening
+
+**Problem:** Dashboard doesn't load at http://localhost:3000.
+
+**Causes:**
+- Port 3000 already in use
+- 9Router crashed
+- Browser cache issues
+
+**Solutions:**
+
+1. **Check if 9Router is running:**
+   ```bash
+   # Check process
+   ps aux | grep 9router
+   
+   # Check port 3000
+   lsof -i :3000
+   ```
+
+2. **Kill conflicting process:**
+   ```bash
+   # macOS/Linux
+   lsof -ti:3000 | xargs kill -9
+   
+   # Windows
+   netstat -ano | findstr :3000
+   taskkill /PID <PID> /F
+   ```
+
+3. **Restart 9Router:**
+   ```bash
+   # Stop
+   pkill -f 9router
+   
+   # Start
+   9router
+   ```
+
+4. **Clear browser cache:**
+   - Chrome: Ctrl+Shift+Delete → Clear cache
+   - Try incognito mode
+
+5. **Check firewall settings:**
+   Ensure port 3000 is not blocked.
+
+---
+
+## Model Not Found
+
+**Problem:** "Model not found" or "Invalid model" errors.
+
+**Causes:**
+- Provider not connected
+- Model ID typo
+- Provider inactive
+
+**Solutions:**
+
+1. **Verify provider connection:**
+   ```
+   Dashboard → Providers → Check status (green = active)
+   ```
+
+2. **Check model ID format:**
+   ```
+   Correct: cc/claude-opus-4-5-20251101
+   Wrong: claude-opus-4-5-20251101
+   
+   Format: [provider-prefix]/[model-name]
+   ```
+
+3. **List available models:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer your-api-key"
+   ```
+
+4. **Reconnect provider:**
+   ```
+   Dashboard → Providers → [Provider] → Reconnect
+   ```
+
+---
+
+## Slow Response
+
+**Problem:** Requests take too long or timeout.
+
+**Causes:**
+- Provider latency
+- Network issues
+- Large context/response
+- Provider rate limiting
+
+**Solutions:**
+
+1. **Check provider status:**
+   ```
+   Dashboard → Providers → View latency stats
+   ```
+
+2. **Switch to faster model:**
+   ```
+   Fast: cc/claude-haiku-4-5 (Haiku is faster than Opus)
+         gc/gemini-3-flash-preview
+         qw/qwen3-coder-flash
+   ```
+
+3. **Use streaming:**
+   ```json
+   {
+     "model": "cc/claude-opus-4-5",
+     "messages": [...],
+     "stream": true
+   }
+   ```
+
+4. **Check network:**
+   ```bash
+   # Test latency
+   ping api.anthropic.com
+   ping api.openai.com
+   ```
+
+5. **Reduce context size:**
+   - Trim message history
+   - Use smaller prompts
+   - Enable context pruning in CLI tool
+
+---
+
+## API Key Invalid
+
+**Problem:** "Invalid API key" or "Authentication failed" errors.
+
+**Causes:**
+- Wrong API key copied
+- API key expired
+- API key not generated
+
+**Solutions:**
+
+1. **Regenerate API key:**
+   ```
+   Dashboard → Settings → API Keys → Generate New Key
+   → Copy and use new key
+   ```
+
+2. **Verify key format:**
+   ```
+   Correct: 9r_xxxxxxxxxxxxxxxxxxxxxxxx
+   Wrong: Missing 9r_ prefix
+   ```
+
+3. **Check key in CLI config:**
+   ```bash
+   # Cursor
+   Settings → Models → OpenAI API Key
+   
+   # Cline
+   Settings → API Key
+   
+   # Environment variable
+   export OPENAI_API_KEY="9r_your_key"
+   ```
+
+4. **Test API key:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer 9r_your_key"
+   ```
+
+---
+
+## Need More Help?
+
+- **GitHub Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **Documentation:** [9router.com/docs](https://9router.com/docs)
+- **FAQ:** [faq.md](faq.md)
diff --git a/gitbook/content/es/deployment/cloud.md b/gitbook/content/es/deployment/cloud.md
new file mode 100644
index 0000000..560ed9f
--- /dev/null
+++ b/gitbook/content/es/deployment/cloud.md
@@ -0,0 +1,473 @@
+# ☁️ Despliegue en la nube
+
+Despliega 9Router en VPS o Docker para acceso remoto y uso en producción.
+
+---
+
+## 🖥️ Despliegue en VPS
+
+### Requisitos previos
+
+- Ubuntu 20.04+ o distribución Linux similar
+- Node.js 20+
+- Git
+- Acceso root o sudo
+
+### Paso 1: Clonar el repositorio
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+```
+
+### Paso 2: Instalar dependencias
+
+```bash
+npm install
+```
+
+### Paso 3: Compilar la aplicación
+
+```bash
+npm run build
+```
+
+### Paso 4: Configurar variables de entorno
+
+Crea un archivo `.env` o exporta variables:
+
+```bash
+export JWT_SECRET="your-secure-secret-change-this-to-random-string"
+export INITIAL_PASSWORD="your-secure-password"
+export DATA_DIR="/var/lib/9router"
+export NODE_ENV="production"
+```
+
+**Variables de entorno:**
+
+| Variable | Por defecto | Descripción |
+|----------|---------|-------------|
+| `JWT_SECRET` | Auto-generado | **¡DEBE cambiarse en producción!** Usado para firmar tokens JWT |
+| `INITIAL_PASSWORD` | `123456` | Contraseña de login del dashboard |
+| `DATA_DIR` | `~/.9router` | Ruta de almacenamiento de la base de datos |
+| `NODE_ENV` | `development` | Establece a `production` para despliegue |
+| `ENABLE_REQUEST_LOGS` | `false` | Habilita logs de debug de request/response |
+
+### Paso 5: Crear el directorio de datos
+
+```bash
+sudo mkdir -p /var/lib/9router
+sudo chown $USER:$USER /var/lib/9router
+```
+
+### Paso 6: Iniciar la aplicación
+
+```bash
+npm run start
+```
+
+### Paso 7: Configurar PM2 para producción
+
+PM2 mantiene tu aplicación corriendo y la reinicia en caso de crash:
+
+```bash
+# Instalar PM2 globalmente
+npm install -g pm2
+
+# Iniciar 9Router con PM2
+pm2 start npm --name 9router -- start
+
+# Guardar la configuración de PM2
+pm2 save
+
+# Configurar PM2 para iniciar al arrancar el sistema
+pm2 startup
+# Sigue las instrucciones impresas por el comando anterior
+```
+
+**Comandos de gestión de PM2:**
+
+```bash
+# Ver logs
+pm2 logs 9router
+
+# Reiniciar aplicación
+pm2 restart 9router
+
+# Detener aplicación
+pm2 stop 9router
+
+# Ver estado
+pm2 status
+
+# Monitorear recursos
+pm2 monit
+```
+
+---
+
+## 🐳 Despliegue con Docker
+
+### Opción 1: Usando Dockerfile
+
+Crea un `Dockerfile` en el directorio `app`:
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy application files
+COPY . .
+
+# Build application
+RUN npm run build
+
+# Expose ports
+EXPOSE 3000 20128
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV DATA_DIR=/app/data
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Start application
+CMD ["npm", "run", "start"]
+```
+
+**Build y Run:**
+
+```bash
+# Construir imagen
+docker build -t 9router .
+
+# Ejecutar contenedor
+docker run -d \
+  --name 9router \
+  -p 3000:3000 \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret-change-this" \
+  -e INITIAL_PASSWORD="your-secure-password" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Opción 2: Docker Compose
+
+Crea `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  9router:
+    build: .
+    container_name: 9router
+    ports:
+      - "3000:3000"
+      - "20128:20128"
+    environment:
+      - NODE_ENV=production
+      - JWT_SECRET=your-secure-secret-change-this
+      - INITIAL_PASSWORD=your-secure-password
+      - DATA_DIR=/app/data
+    volumes:
+      - 9router-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  9router-data:
+```
+
+**Ejecutar con Docker Compose:**
+
+```bash
+# Iniciar servicios
+docker-compose up -d
+
+# Ver logs
+docker-compose logs -f
+
+# Detener servicios
+docker-compose down
+
+# Reconstruir y reiniciar
+docker-compose up -d --build
+```
+
+---
+
+## 🌐 Proxy reverso con Nginx
+
+### ¿Por qué usar Nginx?
+
+- Terminación SSL/TLS
+- Mapeo de nombre de dominio
+- Balanceo de carga
+- Mejor seguridad
+
+### Paso 1: Instalar Nginx
+
+```bash
+sudo apt update
+sudo apt install nginx
+```
+
+### Paso 2: Configurar Nginx
+
+Crea `/etc/nginx/sites-available/9router`:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    # SSL certificates (use certbot to generate)
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    # SSL configuration
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # Proxy to 9Router
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+
+    # API endpoint
+    location /v1 {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+### Paso 3: Habilitar el sitio
+
+```bash
+# Crear enlace simbólico
+sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/
+
+# Probar configuración
+sudo nginx -t
+
+# Recargar Nginx
+sudo systemctl reload nginx
+```
+
+### Paso 4: Configurar SSL con Let's Encrypt
+
+```bash
+# Instalar certbot
+sudo apt install certbot python3-certbot-nginx
+
+# Obtener certificado SSL
+sudo certbot --nginx -d your-domain.com
+
+# La auto-renovación se configura automáticamente
+# Probar renovación
+sudo certbot renew --dry-run
+```
+
+---
+
+## 🔒 Consideraciones de seguridad
+
+### 1. Cambiar credenciales por defecto
+
+**CRÍTICO:** Cambia `JWT_SECRET` y `INITIAL_PASSWORD` antes del despliegue:
+
+```bash
+# Generar JWT secret seguro
+openssl rand -base64 32
+
+# Usa este valor para JWT_SECRET
+export JWT_SECRET="generated-secret-here"
+```
+
+### 2. Configuración del firewall
+
+```bash
+# Permitir SSH
+sudo ufw allow 22/tcp
+
+# Permitir HTTP/HTTPS (si usas Nginx)
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+
+# Si NO usas proxy reverso, permite los puertos de 9Router
+sudo ufw allow 3000/tcp
+sudo ufw allow 20128/tcp
+
+# Habilitar firewall
+sudo ufw enable
+```
+
+### 3. Restringir el acceso al dashboard
+
+Si solo necesitas acceso por API, restringe el puerto del dashboard:
+
+```bash
+# Solo permitir acceso localhost al dashboard
+sudo ufw deny 3000/tcp
+```
+
+Accede al dashboard vía túnel SSH:
+
+```bash
+ssh -L 3000:localhost:3000 user@your-server.com
+# Luego abre http://localhost:3000 en tu navegador
+```
+
+### 4. Actualizaciones regulares
+
+```bash
+# Actualizar paquetes del sistema
+sudo apt update && sudo apt upgrade -y
+
+# Actualizar 9Router
+cd /path/to/9router/app
+git pull
+npm install
+npm run build
+pm2 restart 9router
+```
+
+### 5. Estrategia de respaldo
+
+```bash
+# Respaldar el directorio de datos
+tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router
+
+# Respaldo automatizado diario (agregar a crontab)
+0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router
+```
+
+---
+
+## 📊 Monitoreo
+
+### Verificar el estado de la aplicación
+
+```bash
+# Estado PM2
+pm2 status
+
+# Ver logs
+pm2 logs 9router --lines 100
+
+# Monitorear recursos
+pm2 monit
+```
+
+### Logs de Nginx
+
+```bash
+# Logs de acceso
+sudo tail -f /var/log/nginx/access.log
+
+# Logs de error
+sudo tail -f /var/log/nginx/error.log
+```
+
+### Recursos del sistema
+
+```bash
+# Uso de CPU y memoria
+htop
+
+# Uso de disco
+df -h
+
+# Conexiones de red
+netstat -tulpn | grep -E '3000|20128'
+```
+
+---
+
+## 🚨 Solución de problemas
+
+### La aplicación no inicia
+
+```bash
+# Verificar logs
+pm2 logs 9router
+
+# Verificar si los puertos están en uso
+sudo lsof -i :3000
+sudo lsof -i :20128
+
+# Verificar variables de entorno
+pm2 env 9router
+```
+
+### Nginx 502 Bad Gateway
+
+```bash
+# Verificar si 9Router está corriendo
+pm2 status
+
+# Verificar logs de error de Nginx
+sudo tail -f /var/log/nginx/error.log
+
+# Probar configuración de Nginx
+sudo nginx -t
+```
+
+### El streaming SSE no funciona
+
+Asegúrate de que `proxy_buffering off` esté configurado en Nginx para soporte SSE.
+
+### Errores de permiso denegado
+
+```bash
+# Corregir permisos del directorio de datos
+sudo chown -R $USER:$USER /var/lib/9router
+chmod 755 /var/lib/9router
+```
+
+---
+
+## 🔗 Próximos pasos
+
+- [Conectar proveedores](/providers/subscription.md)
+- [Configurar combos](/features/combos.md)
+- [Integrar con herramientas](/integration/cursor.md)
diff --git a/gitbook/content/es/deployment/localhost.md b/gitbook/content/es/deployment/localhost.md
new file mode 100644
index 0000000..a082fcc
--- /dev/null
+++ b/gitbook/content/es/deployment/localhost.md
@@ -0,0 +1,164 @@
+# 🏠 Despliegue en localhost
+
+Ejecuta 9Router en tu máquina local para desarrollo y uso personal.
+
+---
+
+## 📦 Instalación
+
+Instala 9Router globalmente vía npm:
+
+```bash
+npm install -g 9router
+```
+
+**Requisitos:**
+- Node.js 20 o superior
+- npm 9 o superior
+
+---
+
+## 🚀 Iniciar el servidor
+
+Inicia 9Router con un solo comando:
+
+```bash
+9router
+```
+
+El dashboard se abrirá automáticamente en tu navegador en `http://localhost:3000`
+
+**Configuración por defecto:**
+- **Dashboard**: `http://localhost:3000`
+- **API Endpoint**: `http://localhost:20128/v1`
+- **Directorio de datos**: `~/.9router`
+
+---
+
+## 🔧 Configuración
+
+### Directorio de datos personalizado
+
+Establece un directorio de datos personalizado usando una variable de entorno:
+
+```bash
+DATA_DIR=/path/to/data 9router
+```
+
+### Puerto personalizado
+
+El puerto de API (20128) y el puerto del dashboard (3000) están configurados en la aplicación. Para cambiarlos, necesitarás modificar el código fuente o usar variables de entorno si se soportan.
+
+---
+
+## 🛑 Detener el servidor
+
+Presiona `Ctrl+C` en la terminal donde 9Router se está ejecutando.
+
+```bash
+# En la terminal ejecutando 9router
+^C  # Presiona Ctrl+C
+```
+
+El servidor se apagará correctamente y guardará todos los datos.
+
+---
+
+## 🔄 Reiniciar el servidor
+
+Simplemente ejecuta el comando de inicio nuevamente:
+
+```bash
+9router
+```
+
+Todas tus configuraciones, API keys y combos se preservan en el directorio de datos.
+
+---
+
+## 📊 Actualizar 9Router
+
+Actualiza a la última versión:
+
+```bash
+npm update -g 9router
+```
+
+Verifica tu versión actual:
+
+```bash
+npm list -g 9router
+```
+
+---
+
+## 🔍 Solución de problemas
+
+### Puerto ya en uso
+
+Si el puerto 20128 o 3000 ya está en uso:
+
+```bash
+# Encontrar proceso usando el puerto (macOS/Linux)
+lsof -i :20128
+lsof -i :3000
+
+# Matar el proceso
+kill -9 <PID>
+```
+
+### Errores de permisos
+
+Si encuentras errores de permisos durante la instalación:
+
+```bash
+# Usar sudo (no recomendado)
+sudo npm install -g 9router
+
+# O corregir los permisos de npm (recomendado)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Problemas con el directorio de datos
+
+Si el directorio de datos no es accesible:
+
+```bash
+# Verificar permisos
+ls -la ~/.9router
+
+# Corregir permisos
+chmod 755 ~/.9router
+```
+
+---
+
+## 📁 Estructura del directorio de datos
+
+```
+~/.9router/
+├── db.json           # Main database (providers, combos, settings)
+├── logs/             # Application logs
+└── cache/            # Temporary cache files
+```
+
+**Respaldar tus datos:**
+
+```bash
+# Respaldo
+cp -r ~/.9router ~/.9router.backup
+
+# Restaurar
+cp -r ~/.9router.backup ~/.9router
+```
+
+---
+
+## 🔗 Próximos pasos
+
+- [Conectar proveedores](/providers/subscription.md)
+- [Crear combos](/features/combos.md)
+- [Integrar con herramientas CLI](/integration/cursor.md)
diff --git a/gitbook/content/es/faq.md b/gitbook/content/es/faq.md
new file mode 100644
index 0000000..0d1f128
--- /dev/null
+++ b/gitbook/content/es/faq.md
@@ -0,0 +1,387 @@
+# Preguntas frecuentes
+
+Preguntas comunes sobre 9Router.
+
+---
+
+## ¿Qué es 9Router?
+
+**9Router es un router de modelos de IA que maximiza el valor de tu suscripción y minimiza los costos.**
+
+Enruta inteligentemente las solicitudes a través de múltiples proveedores de IA usando un sistema de fallback de 3 niveles:
+1. **Nivel de suscripción** - Maximiza las cuotas de Claude Code, Codex, Gemini que ya pagas
+2. **Nivel barato** - Alternativas ultra-baratas ($0.20-$0.60 por 1M tokens)
+3. **Nivel gratis** - Respaldo de emergencia con modelos gratis ilimitados
+
+**Beneficios clave:**
+- Nunca desperdicies la cuota de suscripción
+- Fallback automático cuando se agota la cuota
+- Seguimiento de cuota en tiempo real
+- 90% de ahorro en costos vs uso directo de API
+
+---
+
+## ¿Cómo funciona el precio?
+
+**9Router usa una estrategia de precios de 3 niveles:**
+
+### Nivel 1: Suscripción (Maximiza primero)
+- **Claude Code** (Pro/Max): $20-100/mes - Cuota de 5 horas + semanal
+- **OpenAI Codex** (Plus/Pro): $20-200/mes - Cuota de 5 horas + semanal
+- **Gemini CLI**: GRATIS - 180K completados/mes + 1K/día
+- **GitHub Copilot**: $10-19/mes - Reinicio mensual
+- **Antigravity**: GRATIS - Similar a Gemini
+
+**Objetivo:** ¡Usa cada bit de cuota antes de que se reinicie!
+
+### Nivel 2: Barato (Respaldo)
+- **GLM-4.7**: $0.60/$2.20 por 1M tokens - Reinicio diario 10AM
+- **MiniMax M2.1**: $0.20/$1.00 por 1M tokens - 5 horas rolling
+- **Kimi K2**: $9/mes plano (10M tokens)
+
+**Objetivo:** ¡90% más barato que ChatGPT API ($20/1M)!
+
+### Nivel 3: Gratis (Emergencia)
+- **iFlow**: 8 modelos GRATIS (Kimi K2, Qwen3, GLM, MiniMax...)
+- **Qwen**: 3 modelos GRATIS (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro**: 2 modelos GRATIS (Claude Sonnet 4.5, Haiku 4.5)
+
+**Objetivo:** ¡Fallback de cero costo cuando todo lo demás está limitado por cuota!
+
+---
+
+## ¿9Router es gratis?
+
+**Sí, 9Router en sí es 100% gratis y open source.**
+
+**Proveedores de nivel gratis disponibles:**
+- **Gemini CLI** - 180K completados/mes (cuenta Google GRATIS)
+- **iFlow** - 8 modelos ilimitados (OAuth GRATIS)
+- **Qwen** - 3 modelos ilimitados (OAuth GRATIS)
+- **Kiro** - Claude Sonnet/Haiku (AWS Builder ID GRATIS)
+
+**¡Puedes codificar GRATIS para siempre usando solo proveedores de nivel gratis!**
+
+**Proveedores de pago opcionales:**
+- Servicios de suscripción que ya puedes tener (Claude Code, Codex, Copilot)
+- Alternativas ultra-baratas ($0.20-$0.60 por 1M tokens)
+
+---
+
+## ¿Qué proveedores son compatibles?
+
+### Proveedores de suscripción
+- **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
+- **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
+- **Gemini CLI** (GRATIS) - Gemini 3 Flash/Pro, 2.5 Pro/Flash
+- **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
+- **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
+
+### Proveedores baratos
+- **GLM** (Zhipu AI) - GLM 4.7, GLM 4.6V Vision
+- **MiniMax** - MiniMax M2.1
+- **Kimi** (Moonshot AI) - Kimi Latest
+- **OpenRouter** - Passthrough a cualquier modelo de OpenRouter
+
+### Proveedores gratis
+- **iFlow** - 8 modelos (Kimi K2, Qwen3, GLM, MiniMax, DeepSeek...)
+- **Qwen** - 3 modelos (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro** - 2 modelos (Claude Sonnet 4.5, Haiku 4.5)
+
+**Total: 15+ proveedores, 50+ modelos**
+
+Consulta la [documentación de proveedores](providers/subscription.md) para más detalles.
+
+---
+
+## ¿Puedo usar múltiples proveedores?
+
+**¡Sí! Esta es la característica principal de 9Router.**
+
+**Los combos te permiten encadenar múltiples proveedores con fallback automático:**
+
+```
+Ejemplo de combo: "premium-coding"
+1. cc/claude-opus-4-5 (Suscripción principal)
+2. glm/glm-4.7 (Respaldo barato)
+3. if/kimi-k2 (Emergencia gratis)
+
+→ Cambio automático cuando se agota la cuota
+→ Nunca para de codificar
+→ Costo extra mínimo
+```
+
+**Cómo crear combos:**
+```
+Dashboard → Combos → Create New
+→ Agrega modelos en orden de prioridad
+→ Usa el nombre del combo en CLI: "premium-coding"
+```
+
+**Beneficios:**
+- Cero tiempo de inactividad cuando se agota la cuota
+- Optimización automática de costos
+- Un solo nombre de modelo para todas las herramientas
+
+Consulta la [documentación de combos](features/combos.md) para ejemplos.
+
+---
+
+## ¿Cómo funciona el seguimiento de cuota?
+
+**9Router rastrea la cuota en tiempo real para todos los proveedores:**
+
+**Características:**
+- **Consumo de tokens** - Tokens de entrada/salida por solicitud
+- **Cuenta regresiva de reinicio** - Tiempo hasta que se refresca la cuota
+- **Estadísticas de uso** - Reportes diarios/semanales/mensuales
+- **Estimación de costos** - Gasto proyectado (niveles de pago)
+- **Alertas de cuota** - Notificaciones cuando la cuota es baja
+
+**Tipos de cuota:**
+- **5 horas rolling** - Claude Code, Codex, MiniMax
+- **Reinicio diario** - Gemini CLI (1K/día), GLM (10AM)
+- **Reinicio semanal** - Claude Code, Codex (cuota adicional)
+- **Reinicio mensual** - Gemini CLI (180K), GitHub Copilot (día 1)
+
+**Ver cuota:**
+```
+Dashboard → Providers → Quota Tracking
+→ Uso en tiempo real + cuenta regresiva de reinicio
+```
+
+Consulta la [documentación de seguimiento de cuota](features/quota-tracking.md) para detalles.
+
+---
+
+## ¿9Router funciona con Cursor?
+
+**Sí, pero Cursor requiere un endpoint en la nube.**
+
+**Problema:** Cursor IDE no soporta endpoints en localhost.
+
+**Solución:** Usa el despliegue en la nube de 9Router:
+
+```
+Cursor Settings → Models → Advanced:
+  OpenAI API Base URL: https://9router.com/v1
+  OpenAI API Key: [desde el dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+**Alternativa:** Auto-hospéda en VPS con dominio público:
+```bash
+# Despliega en VPS
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+npm start
+
+# Configura proxy reverso Nginx
+# Apunta Cursor a: https://your-domain.com/v1
+```
+
+**Otras herramientas CLI funcionan con localhost:**
+- Cline ✅
+- Claude Desktop ✅
+- Codex CLI ✅
+- Continue ✅
+- RooCode ✅
+
+Consulta la [guía de integración de Cursor](integration/cursor.md) para detalles.
+
+---
+
+## ¿Puedo auto-hospedar 9Router?
+
+**¡Sí! 9Router soporta múltiples opciones de despliegue:**
+
+### Localhost (Por defecto)
+```bash
+npm install -g 9router
+9router
+→ Dashboard: http://localhost:3000
+→ API: http://localhost:20128/v1
+```
+
+### VPS/Cloud
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+npm start
+```
+
+### Docker
+```bash
+docker build -t 9router .
+docker run -d \
+  -p 3000:3000 \
+  -e JWT_SECRET="your-secret" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Cloudflare Workers
+```bash
+cd 9router/app
+npm run deploy:cloudflare
+```
+
+**Variables de entorno:**
+- `JWT_SECRET` - **¡DEBE cambiarse en producción!**
+- `DATA_DIR` - Ruta de almacenamiento de la base de datos (por defecto: `~/.9router`)
+- `INITIAL_PASSWORD` - Login del dashboard (por defecto: `123456`)
+- `NODE_ENV` - Establece en `production` para desplegar
+
+Consulta la [guía de despliegue](getting-started/installation.md#deployment) para detalles.
+
+---
+
+## ¿Mis datos están seguros?
+
+**Sí, 9Router prioriza la seguridad y privacidad:**
+
+**Almacenamiento local:**
+- Todos los datos se almacenan localmente en `~/.9router` (o `DATA_DIR` personalizado)
+- No se envían datos a los servidores de 9Router
+- Tokens OAuth cifrados con JWT
+
+**Sin telemetría:**
+- Sin seguimiento de uso
+- Sin analítica
+- Sin phone-home
+
+**Open source:**
+- Código fuente completo disponible en GitHub
+- Audita la seguridad tú mismo
+- Revisado por la comunidad
+
+**Mejores prácticas:**
+- Cambia `JWT_SECRET` en producción
+- Usa un `INITIAL_PASSWORD` fuerte
+- Habilita HTTPS para despliegues en la nube
+- Rota las API keys regularmente
+
+**Lo que 9Router almacena:**
+- Tokens OAuth de proveedores (cifrados)
+- API keys (cifradas)
+- Estadísticas de uso (solo locales)
+- Configuraciones de combos
+
+**Lo que 9Router NO almacena:**
+- Tus prompts o respuestas
+- El código que generas
+- Información personal
+
+---
+
+## ¿Cómo actualizo 9Router?
+
+**Los métodos de actualización dependen del tipo de instalación:**
+
+### Instalación global NPM
+```bash
+npm update -g 9router
+```
+
+### Instalación local
+```bash
+cd 9router/app
+git pull origin main
+npm install
+npm run build
+npm start
+```
+
+### Docker
+```bash
+docker pull 9router:latest
+docker stop 9router
+docker rm 9router
+docker run -d \
+  -p 3000:3000 \
+  -v 9router-data:/app/data \
+  9router:latest
+```
+
+**Verificar versión:**
+```bash
+9router --version
+```
+
+**Cambios disruptivos:**
+- Revisa [CHANGELOG.md](https://github.com/decolua/9router/blob/main/CHANGELOG.md)
+- Respalda `~/.9router` antes de actualizaciones mayores
+- Revisa las guías de migración para versiones mayores
+
+---
+
+## ¿Cómo puedo contribuir?
+
+**¡Damos la bienvenida a las contribuciones!**
+
+### Formas de contribuir:
+
+1. **Reportar bugs:**
+   - [GitHub Issues](https://github.com/decolua/9router/issues)
+   - Incluye logs de error, pasos para reproducir
+
+2. **Solicitar características:**
+   - [GitHub Discussions](https://github.com/decolua/9router/discussions)
+   - Describe el caso de uso y los beneficios
+
+3. **Enviar código:**
+   ```bash
+   # Fork del repo
+   git clone https://github.com/YOUR_USERNAME/9router.git
+   cd 9router
+   
+   # Crea una rama
+   git checkout -b feature/your-feature
+   
+   # Haz cambios
+   npm install
+   npm run dev
+   
+   # Prueba
+   npm test
+   
+   # Commit y push
+   git add .
+   git commit -m "Add your feature"
+   git push origin feature/your-feature
+   
+   # Crea un Pull Request en GitHub
+   ```
+
+4. **Mejorar docs:**
+   - Corrige errores tipográficos, agrega ejemplos
+   - Traduce a otros idiomas
+   - Escribe tutoriales
+
+5. **Agregar proveedores:**
+   - Implementa nuevos adaptadores de proveedores
+   - Consulta `app/lib/providers/` para ejemplos
+
+**Directrices de contribución:**
+- Sigue el estilo de código existente
+- Agrega tests para nuevas características
+- Actualiza la documentación
+- Mantén los commits atómicos y descriptivos
+
+Consulta [CONTRIBUTING.md](https://github.com/decolua/9router/blob/main/CONTRIBUTING.md) para detalles.
+
+---
+
+## ¿Necesitas más ayuda?
+
+- **Documentación:** [9router.com/docs](https://9router.com/docs)
+- **GitHub:** [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **Troubleshooting:** [troubleshooting.md](troubleshooting.md)
diff --git a/gitbook/content/es/features/combos.md b/gitbook/content/es/features/combos.md
new file mode 100644
index 0000000..aadfe19
--- /dev/null
+++ b/gitbook/content/es/features/combos.md
@@ -0,0 +1,537 @@
+# Combos - Cadenas de fallback personalizadas
+
+Crea combinaciones de modelos personalizadas con fallback automático. Los combos te permiten definir tu propia estrategia de enrutamiento basada en costo, calidad y disponibilidad.
+
+---
+
+## ¿Qué son los combos?
+
+Los combos son **cadenas de fallback personalizadas** que creas en el dashboard. En lugar de usar un solo modelo, defines una secuencia de modelos que 9Router intenta en orden.
+
+**Ejemplo:**
+```
+Nombre del combo: premium-coding
+Modelos:
+  1. cc/claude-opus-4-5-20251101 (intentar primero)
+  2. glm/glm-4.7 (si #1 tiene cuota agotada)
+  3. minimax/MiniMax-M2.1 (si #2 tiene cuota agotada)
+```
+
+**Uso en CLI:**
+```
+Model: premium-coding
+```
+
+9Router intenta automáticamente cada modelo en secuencia hasta que uno tenga éxito.
+
+---
+
+## ¿Por qué usar combos?
+
+### 1. Maximiza el valor de la suscripción
+```
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ Usa la suscripción primero, respaldo barato, emergencia gratis
+→ Obtén el valor completo de las suscripciones que ya pagas
+```
+
+### 2. Minimiza costos
+```
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+
+→ Comienza con la opción de pago más barata ($0.60/1M)
+→ Fallback a una aún más barata ($0.20/1M)
+→ Nivel de emergencia gratis
+→ Costo total: ~$5-10/mes vs $2000 en ChatGPT API
+```
+
+### 3. Garantiza disponibilidad 24/7
+```
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ Siempre incluye el nivel gratis al final
+→ Nunca te quedes sin cuota
+→ Codifica en cualquier momento, en cualquier lugar
+```
+
+### 4. Optimiza por calidad
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → gc/gemini-3-pro
+
+→ Mejores modelos primero
+→ Fallback a otros modelos premium
+→ Mantén alta calidad en toda la cadena de fallback
+```
+
+---
+
+## Cómo crear combos
+
+### Paso 1: Abrir el dashboard
+
+```
+http://localhost:20128
+→ Inicia sesión con tu contraseña
+```
+
+### Paso 2: Navegar a Combos
+
+```
+Dashboard → Combos → Create New Combo
+```
+
+### Paso 3: Configurar el combo
+
+**Nombre del combo:**
+```
+premium-coding
+```
+
+**Descripción (opcional):**
+```
+Suscripción primero, respaldo barato, emergencia gratis
+```
+
+**Seleccionar modelos:**
+```
+1. cc/claude-opus-4-5-20251101
+2. glm/glm-4.7
+3. minimax/MiniMax-M2.1
+```
+
+**Arrastra para reordenar** - Prioridad de arriba a abajo.
+
+### Paso 4: Guardar
+
+```
+Clic en "Save Combo"
+→ El combo aparece en la lista de modelos
+```
+
+### Paso 5: Usar en CLI
+
+```
+Cursor/Cline/Cualquier herramienta:
+  Model: premium-coding
+```
+
+---
+
+## Combos de ejemplo
+
+### Ejemplo 1: Premium Coding (Suscripción → Barato → Gratis)
+
+**Objetivo**: Maximizar el valor de la suscripción, minimizar costos extras.
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101
+  2. glm/glm-4.7
+  3. minimax/MiniMax-M2.1
+```
+
+**Uso:**
+```
+Cursor IDE:
+  Model: premium-coding
+```
+
+**Comportamiento:**
+```
+Mañana (cuota fresca):
+  Solicitud → cc/claude-opus-4-5 ✅
+
+Tarde (cuota de Claude agotada):
+  Solicitud → glm/glm-4.7 ✅ (cambio automático)
+
+Noche (cuota de GLM agotada):
+  Solicitud → minimax/MiniMax-M2.1 ✅ (cambio automático)
+```
+
+**Costo mensual (100M tokens):**
+```
+80M vía Claude Code: $0 (suscripción)
+15M vía GLM: $9
+5M vía MiniMax: $1
+Total: $10 + tu suscripción
+```
+
+**Ahorros**: ~99% vs ChatGPT API ($2000).
+
+---
+
+### Ejemplo 2: Combo de presupuesto (Barato → Gratis)
+
+**Objetivo**: Minimizar costos, usar el nivel gratis como respaldo.
+
+```
+Dashboard → Combos → Create New
+
+Name: budget-combo
+Models:
+  1. glm/glm-4.7
+  2. minimax/MiniMax-M2.1
+  3. if/kimi-k2-thinking
+```
+
+**Uso:**
+```
+Cline:
+  Provider: OpenAI Compatible
+  Base URL: http://localhost:20128/v1
+  Model: budget-combo
+```
+
+**Comportamiento:**
+```
+Solicitud → glm/glm-4.7
+  ✅ Cuota diaria disponible → Usa GLM ($0.60/1M)
+  ❌ Cuota agotada → Intenta MiniMax ($0.20/1M)
+  ❌ Cuota de MiniMax agotada → Usa iFlow (GRATIS)
+```
+
+**Costo mensual (100M tokens):**
+```
+70M vía GLM: $42
+20M vía MiniMax: $4
+10M vía iFlow: $0
+Total: $46 vs $2000 en ChatGPT API
+```
+
+**Ahorros**: 97%.
+
+---
+
+### Ejemplo 3: Combo gratis (Cero costo)
+
+**Objetivo**: 100% gratis, sin costos nunca.
+
+```
+Dashboard → Combos → Create New
+
+Name: free-combo
+Models:
+  1. if/kimi-k2-thinking
+  2. qw/qwen3-coder-plus
+  3. kr/claude-sonnet-4.5
+```
+
+**Uso:**
+```
+Claude Desktop:
+  Model: free-combo
+```
+
+**Comportamiento:**
+```
+Solicitud → if/kimi-k2-thinking
+  ✅ Disponible → Usa iFlow
+  ❌ Error → Intenta Qwen
+  ❌ Error → Intenta Kiro
+```
+
+**Costo mensual:**
+```
+100M tokens vía proveedores gratis: $0
+Total: $0 para siempre
+```
+
+**Caso de uso**: Proyectos personales, aprendizaje, experimentación.
+
+---
+
+### Ejemplo 4: Calidad primero (Solo modelos premium)
+
+**Objetivo**: Mejor calidad, sin fallback barato.
+
+```
+Dashboard → Combos → Create New
+
+Name: quality-first
+Models:
+  1. cc/claude-opus-4-5-20251101
+  2. cx/gpt-5.2-codex
+  3. gc/gemini-3-pro-preview
+```
+
+**Uso:**
+```
+Codex CLI:
+  export OPENAI_BASE_URL="http://localhost:20128"
+  Model: quality-first
+```
+
+**Comportamiento:**
+```
+Solicitud → cc/claude-opus-4-5
+  ❌ Cuota agotada → cx/gpt-5.2-codex
+  ❌ Cuota agotada → gc/gemini-3-pro-preview
+  ❌ Todo agotado → Devuelve error (sin fallback barato)
+```
+
+**Caso de uso**: Código crítico de producción, refactoring complejo.
+
+---
+
+### Ejemplo 5: Multi-suscripción (Maximiza todo)
+
+**Objetivo**: Usa todas las suscripciones antes de pagar extra.
+
+```
+Dashboard → Combos → Create New
+
+Name: multi-sub
+Models:
+  1. gc/gemini-3-flash-preview (GRATIS 180K/mes)
+  2. cc/claude-opus-4-5-20251101 (suscripción Pro)
+  3. cx/gpt-5.2-codex (suscripción Plus)
+  4. gh/gpt-5 (suscripción Copilot)
+  5. glm/glm-4.7 (respaldo barato)
+  6. if/kimi-k2-thinking (emergencia gratis)
+```
+
+**Costo mensual (200M tokens):**
+```
+50M vía Gemini CLI: $0 (nivel gratis)
+80M vía Claude Code: $0 (suscripción)
+40M vía Codex: $0 (suscripción)
+20M vía Copilot: $0 (suscripción)
+8M vía GLM: $4.80
+2M vía iFlow: $0
+Total: $4.80 + suscripciones existentes
+```
+
+**Resultado**: Usa 190M tokens de suscripciones, solo $4.80 extra.
+
+---
+
+### Ejemplo 6: Optimización de reinicio de cuota
+
+**Objetivo**: Distribuir el uso según los tiempos de reinicio.
+
+```
+Dashboard → Combos → Create New
+
+Name: reset-optimized
+Models:
+  1. cc/claude-opus-4-5 (reinicio 5h, usar mañana)
+  2. gc/gemini-3-flash (1K/día, usar tarde)
+  3. glm/glm-4.7 (reinicio diario 10AM, usar noche)
+  4. minimax/MiniMax-M2.1 (rolling 5h, usar madrugada)
+  5. if/kimi-k2-thinking (ilimitado, emergencia)
+```
+
+**Rutina diaria:**
+```
+08:00 - 13:00: Claude Code (cuota fresca de 5h)
+13:00 - 18:00: Gemini CLI (cuota 1K/día)
+18:00 - 22:00: GLM (se reinicia 10AM del día siguiente)
+22:00 - 08:00: MiniMax (rolling 5h) o iFlow
+```
+
+**Resultado**: Codifica 24/7 con costos mínimos.
+
+---
+
+## Usar combos en herramientas CLI
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [desde el dashboard]
+  Model: premium-coding
+```
+
+### Claude Desktop
+
+Edita `~/.claude/config.json`:
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key",
+  "model": "budget-combo"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex --model quality-first "your prompt"
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [desde el dashboard]
+Model: free-combo
+```
+
+### Solicitud por API
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "premium-coding",
+    "messages": [
+      {"role": "user", "content": "Write a function to..."}
+    ],
+    "stream": true
+  }'
+```
+
+---
+
+## Mejores prácticas
+
+### 1. Siempre incluye el nivel gratis
+
+```
+✅ Bueno:
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+❌ Malo:
+cc/claude-opus → glm/glm-4.7
+(sin fallback gratis, puede quedarse sin cuota)
+```
+
+**Por qué**: Garantiza disponibilidad 24/7, nunca bloqueado por cuota.
+
+### 2. Ordena por costo (Barato a costoso)
+
+```
+✅ Bueno:
+glm/glm-4.7 → minimax/MiniMax-M2.1 → cc/claude-opus
+
+❌ Malo:
+cc/claude-opus → glm/glm-4.7
+(desperdicia cuota de suscripción en tareas simples)
+```
+
+**Excepción**: Si quieres maximizar el valor de la suscripción, pon la suscripción primero.
+
+### 3. Coincide con los requisitos de calidad
+
+```
+Para código de producción:
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7
+
+Para tareas rápidas:
+glm/glm-4.7 → if/kimi-k2-thinking
+
+Para experimentación:
+if/kimi-k2-thinking → qw/qwen3-coder-plus
+```
+
+### 4. Considera los tiempos de reinicio de cuota
+
+```
+Combo matutino (cuotas frescas):
+cc/claude-opus → cx/gpt-5.2-codex
+
+Combo nocturno (cuotas probablemente agotadas):
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+### 5. Crea múltiples combos para diferentes casos de uso
+
+```
+premium-coding: Para tareas complejas
+budget-combo: Para tareas simples
+free-combo: Para experimentación
+quality-first: Para código de producción
+```
+
+**Cambia entre combos** según los requisitos de la tarea.
+
+### 6. Monitorea el desempeño del combo
+
+```
+Dashboard → Analytics → Combo Usage:
+  premium-coding:
+    80% vía cc/claude-opus (bueno, usando suscripción)
+    15% vía glm/glm-4.7 (respaldo aceptable)
+    5% vía minimax (fallback raro)
+```
+
+**Optimiza**: Si hay demasiado uso de fallback, aumenta la cuota principal o reordena modelos.
+
+---
+
+## Configuración avanzada
+
+### Establecer límites de presupuesto por combo
+
+```
+Dashboard → Combos → Edit → Budget:
+  Daily limit: $5
+  Monthly limit: $50
+```
+
+Cuando se alcanza el límite, 9Router omite los modelos de pago y usa solo el nivel gratis.
+
+### Habilitar/Deshabilitar modelos en un combo
+
+```
+Dashboard → Combos → Edit → Models:
+  ✅ cc/claude-opus-4-5 (habilitado)
+  ❌ glm/glm-4.7 (deshabilitado temporalmente)
+  ✅ if/kimi-k2-thinking (habilitado)
+```
+
+**Caso de uso**: Deshabilitar temporalmente modelos costosos sin eliminar el combo.
+
+### Clonar un combo existente
+
+```
+Dashboard → Combos → Clone "premium-coding"
+→ Crea una copia con sufijo "-copy"
+→ Modifica y guarda como nuevo combo
+```
+
+**Caso de uso**: Crear variaciones para diferentes escenarios.
+
+---
+
+## Solución de problemas
+
+**Problema: El combo no aparece en la lista de modelos**
+
+**Solución:**
+1. Refresca el dashboard
+2. Verifica que el combo esté guardado (marca verde)
+3. Reinicia la herramienta CLI para refrescar la lista de modelos
+
+**Problema: El combo siempre usa el último modelo (nivel gratis)**
+
+**Solución:**
+1. Verifica la cuota de los modelos principales (Dashboard → Quota)
+2. Verifica que las API keys sean válidas (Dashboard → Providers)
+3. Verifica que no se hayan excedido los límites de presupuesto
+
+**Problema: El combo cuesta más de lo esperado**
+
+**Solución:**
+1. Dashboard → Analytics → Revisa el uso del combo
+2. Verifica si los modelos principales tienen cuota agotada
+3. Reordena los modelos (pon los más baratos primero)
+4. Establece límites de presupuesto
+
+---
+
+## Relacionado
+
+- [Enrutamiento inteligente](./smart-routing.md) - Cómo funciona el fallback automático
+- [Seguimiento de cuota](./quota-tracking.md) - Monitorea uso y costos
diff --git a/gitbook/content/es/features/quota-tracking.md b/gitbook/content/es/features/quota-tracking.md
new file mode 100644
index 0000000..437b769
--- /dev/null
+++ b/gitbook/content/es/features/quota-tracking.md
@@ -0,0 +1,687 @@
+# Seguimiento de cuota y monitoreo de uso
+
+Rastrea el consumo de tokens en tiempo real, monitorea los límites de cuota, estima costos y recibe alertas antes de quedarte sin recursos. Nunca desperdicies cuota de suscripción ni excedas los límites de presupuesto.
+
+---
+
+## Resumen
+
+9Router proporciona un seguimiento de cuota integral para todos los proveedores:
+
+- **Consumo de tokens en tiempo real** - Mira los tokens usados por solicitud
+- **Límites de cuota y restantes** - Rastrea el uso vs límites
+- **Cuenta regresiva de reinicio** - Sabe cuándo se refresca la cuota
+- **Estimación de costos** - Calcula el gasto para niveles de pago
+- **Reportes mensuales** - Analiza patrones de uso
+- **Alertas y notificaciones** - Recibe advertencias antes de los límites
+
+---
+
+## Resumen del dashboard
+
+### Resumen de cuota
+
+```
+Dashboard → Home → Quota Overview
+
+┌─────────────────────────────────────────────┐
+│ Claude Code (cc/)                           │
+│ ████████████░░░░░░░░ 2.5h / 5h (50%)       │
+│ Se reinicia en: 2h 30m                      │
+│ Costo: $0 (suscripción)                     │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ Gemini CLI (gc/)                            │
+│ ████████░░░░░░░░░░░░ 450 / 1000 (45%)      │
+│ Reinicio diario en: 18h 30m                 │
+│ Mensual: 45K / 180K (25%)                   │
+│ Costo: $0 (nivel gratis)                    │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ GLM-4.7 (glm/)                              │
+│ ██████████████░░░░░░ 7M / 10M tokens (70%)  │
+│ Se reinicia: Diario 10:00 AM (en 5h 35m)   │
+│ Costo hoy: $4.20                            │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ MiniMax M2.1 (minimax/)                     │
+│ ████████████████░░░░ 4M / 5M tokens (80%)   │
+│ Ventana rolling 5h                          │
+│ Costo (5h): $0.80                           │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ iFlow (if/)                                 │
+│ ████████████████████ Ilimitado              │
+│ Costo: $0 (gratis para siempre)             │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Consumo de tokens en tiempo real
+
+### Seguimiento por solicitud
+
+Cada solicitud muestra el uso detallado de tokens:
+
+```
+Dashboard → Activity → Recent Requests
+
+Request #1234
+Model: cc/claude-opus-4-5-20251101
+Timestamp: 2026-02-04 04:15:32
+
+Tokens:
+  Input: 1,250 tokens
+  Output: 850 tokens
+  Total: 2,100 tokens
+
+Cost: $0 (cuota de suscripción)
+Duration: 3.2s
+Status: ✅ Success
+```
+
+### Monitor de uso en vivo
+
+```
+Dashboard → Live Monitor
+
+Solicitud actual:
+  Model: glm/glm-4.7
+  Tokens transmitidos: 450 / ~800 estimados
+  Costo hasta ahora: $0.0009
+  Duración: 1.8s
+```
+
+### Desglose de tokens por modelo
+
+```
+Dashboard → Analytics → Token Usage
+
+Hoy (4 feb 2026):
+  cc/claude-opus-4-5: 15M tokens ($0, suscripción)
+  glm/glm-4.7: 8M tokens ($4.80)
+  if/kimi-k2-thinking: 3M tokens ($0, gratis)
+  
+Total: 26M tokens
+Costo: $4.80
+```
+
+---
+
+## Límites de cuota y tiempos de reinicio
+
+### Proveedores de suscripción
+
+**Claude Code (Pro/Max)**
+```
+Tipo de cuota: Basado en tiempo (rolling 5 horas)
+Límite: 5 horas de uso
+Reinicio: Ventana rolling 5 horas + refresh semanal
+Seguimiento: Tiempo de uso por modelo
+
+El dashboard muestra:
+  Opus: 2.5h / 5h usados
+  Sonnet: 1.2h / 5h usados
+  Haiku: 0.8h / 5h usados
+  
+Reinicio semanal: Todos los lunes 00:00 UTC
+```
+
+**OpenAI Codex (Plus/Pro)**
+```
+Tipo de cuota: Basado en tiempo (rolling 5 horas)
+Límite: 5 horas (Plus) / 10 horas (Pro)
+Reinicio: Ventana rolling 5 horas + refresh semanal
+
+El dashboard muestra:
+  GPT-5.2 Codex: 3.5h / 5h usados
+  Se reinicia en: 1h 30m
+```
+
+**Gemini CLI (GRATIS)**
+```
+Tipo de cuota: Conteo de solicitudes + tokens mensuales
+Límite diario: 1,000 solicitudes
+Límite mensual: 180,000 completados
+Reinicio: Diario 00:00 UTC + Mensual día 1
+
+El dashboard muestra:
+  Hoy: 450 / 1,000 solicitudes (45%)
+  Este mes: 45K / 180K completados (25%)
+  Reinicio diario en: 18h 30m
+  Reinicio mensual en: 26 días
+```
+
+**GitHub Copilot**
+```
+Tipo de cuota: Uso mensual
+Límite: Varía según el plan
+Reinicio: 1ro de cada mes
+
+El dashboard muestra:
+  Uso: 60% de la cuota mensual
+  Se reinicia: 1 mar 2026 (en 25 días)
+```
+
+### Proveedores baratos
+
+**GLM-4.7**
+```
+Tipo de cuota: Límite diario de tokens
+Límite: 10M tokens/día (Coding Plan)
+Reinicio: Diario 10:00 AM hora de Beijing (UTC+8)
+
+El dashboard muestra:
+  Usados: 7M / 10M tokens (70%)
+  Restantes: 3M tokens
+  Se reinicia en: 5h 35m
+  Costo hoy: $4.20
+```
+
+**MiniMax M2.1**
+```
+Tipo de cuota: Ventana rolling 5 horas
+Límite: 5M tokens por 5 horas
+Reinicio: Ventana rolling continua
+
+El dashboard muestra:
+  Usados (5h): 4M / 5M tokens (80%)
+  El uso más antiguo expira en: 45m
+  Costo (5h): $0.80
+```
+
+**Kimi K2**
+```
+Tipo de cuota: Suscripción mensual
+Límite: 10M tokens/mes ($9 plano)
+Reinicio: Mensual en la fecha de suscripción
+
+El dashboard muestra:
+  Usados: 6M / 10M tokens (60%)
+  Se reinicia: 15 feb 2026 (en 11 días)
+  Costo: $9/mes (pagado por adelantado)
+```
+
+### Proveedores gratis
+
+**iFlow / Qwen / Kiro**
+```
+Tipo de cuota: Ilimitado (con rate-limit)
+Límite: Sin límite duro
+Reinicio: N/A
+
+El dashboard muestra:
+  Usados hoy: 5M tokens
+  Costo: $0 (gratis para siempre)
+  Estado: ✅ Disponible
+```
+
+---
+
+## Estimación de costos
+
+### Seguimiento de costos en tiempo real
+
+```
+Dashboard → Costs → Today
+
+Proveedores de suscripción: $0
+  Claude Code: 15M tokens ($0, incluido)
+  Gemini CLI: 3M tokens ($0, nivel gratis)
+
+Proveedores de pago: $4.80
+  GLM-4.7: 8M tokens ($4.80)
+    Input: 6M × $0.60/1M = $3.60
+    Output: 2M × $2.20/1M = $4.40
+    Total: $4.80
+
+Proveedores gratis: $0
+  iFlow: 3M tokens ($0)
+
+Total hoy: $4.80
+```
+
+### Reporte de gasto mensual
+
+```
+Dashboard → Costs → This Month (Febrero 2026)
+
+Semana 1 (1-7 feb):
+  Suscripción: $0 (80M tokens)
+  Pago: $15.20 (25M tokens)
+  Gratis: $0 (10M tokens)
+  Total: $15.20
+
+Semana 2 (8-14 feb):
+  Suscripción: $0 (75M tokens)
+  Pago: $12.80 (20M tokens)
+  Gratis: $0 (8M tokens)
+  Total: $12.80
+
+Mes hasta la fecha: $28.00
+Proyectado (30 días): ~$120
+
+Desglose por proveedor:
+  GLM-4.7: $22.00 (78%)
+  MiniMax M2.1: $6.00 (22%)
+  
+Costo promedio por 1M tokens: $0.62
+Ahorros vs ChatGPT API: 97% ($4,000 → $120)
+```
+
+### Proyección de costos
+
+```
+Dashboard → Costs → Projections
+
+Basado en uso de los últimos 7 días:
+  Promedio diario: 50M tokens
+  Costo diario: $4.50
+
+Proyección mensual:
+  Tokens: 1,500M (1.5B)
+  Costo: $135
+  
+Desglose:
+  Suscripción: 900M tokens ($0)
+  GLM-4.7: 450M tokens ($90)
+  MiniMax: 120M tokens ($24)
+  Gratis: 30M tokens ($0)
+
+Estado del presupuesto:
+  Límite diario: $5 → 90% usado hoy
+  Límite mensual: $150 → 90% proyectado
+  ⚠️ Advertencia: Puede exceder el presupuesto mensual
+```
+
+---
+
+## Dashboard de uso
+
+### Estadísticas generales
+
+```
+Dashboard → Analytics → Overview
+
+Hoy (4 feb 2026):
+  Solicitudes: 1,234
+  Tokens: 26M
+  Costo: $4.80
+  Tiempo promedio de respuesta: 2.1s
+
+Esta semana:
+  Solicitudes: 8,456
+  Tokens: 180M
+  Costo: $28.00
+  Tasa de éxito: 99.2%
+
+Este mes:
+  Solicitudes: 15,234
+  Tokens: 320M
+  Costo: $52.00
+  Modelo principal: cc/claude-opus-4-5 (45%)
+```
+
+### Uso por modelo
+
+```
+Dashboard → Analytics → Models
+
+Modelos principales (este mes):
+1. cc/claude-opus-4-5: 145M tokens (45%)
+2. glm/glm-4.7: 95M tokens (30%)
+3. if/kimi-k2-thinking: 50M tokens (16%)
+4. minimax/MiniMax-M2.1: 20M tokens (6%)
+5. gc/gemini-3-flash: 10M tokens (3%)
+
+Desglose de costos:
+  cc/claude-opus: $0 (suscripción)
+  glm/glm-4.7: $45.00
+  if/kimi-k2-thinking: $0 (gratis)
+  minimax/MiniMax-M2.1: $7.00
+  gc/gemini-3-flash: $0 (gratis)
+```
+
+### Uso por tiempo
+
+```
+Dashboard → Analytics → Timeline
+
+Uso por hora (hoy):
+00:00 - 01:00: 0.5M tokens
+01:00 - 02:00: 0.2M tokens
+...
+08:00 - 09:00: 3.2M tokens (pico)
+09:00 - 10:00: 2.8M tokens
+...
+23:00 - 00:00: 0.8M tokens
+
+Horas pico: 08:00 - 12:00 (codificación matutina)
+Horas bajas: 00:00 - 06:00 (noche)
+```
+
+### Uso por combo
+
+```
+Dashboard → Analytics → Combos
+
+premium-coding:
+  Solicitudes: 456
+  Tokens: 12M
+  Costo: $2.40
+  
+  Desglose:
+    cc/claude-opus: 8M tokens (67%, $0)
+    glm/glm-4.7: 3M tokens (25%, $1.80)
+    minimax/MiniMax-M2.1: 1M tokens (8%, $0.20)
+
+budget-combo:
+  Solicitudes: 234
+  Tokens: 6M
+  Costo: $1.20
+  
+  Desglose:
+    glm/glm-4.7: 4M tokens (67%, $2.40)
+    if/kimi-k2-thinking: 2M tokens (33%, $0)
+```
+
+---
+
+## Alertas y notificaciones
+
+### Alertas de cuota
+
+```
+Dashboard → Settings → Alerts
+
+Advertencias de cuota:
+  ✅ Alerta al 80% de cuota usada
+  ✅ Alerta al 90% de cuota usada
+  ✅ Alerta cuando la cuota se agota
+  ✅ Notificar cuando la cuota se reinicia
+
+Entrega:
+  ✅ Notificación del dashboard
+  ✅ Email (opcional)
+  ✅ Webhook (opcional)
+```
+
+**Ejemplo de notificaciones:**
+```
+⚠️ Cuota de Claude Code 80% usada
+   2.5h restantes (se reinicia en 1h 30m)
+   
+⚠️ Cuota de GLM-4.7 90% usada
+   1M tokens restantes (se reinicia en 5h)
+   
+✅ Cuota de Gemini CLI reiniciada
+   1,000 solicitudes disponibles (límite diario)
+```
+
+### Alertas de presupuesto
+
+```
+Dashboard → Settings → Budget Alerts
+
+Presupuesto diario: $5
+  ✅ Alerta al 80% ($4)
+  ✅ Alerta al 100% ($5)
+  ✅ Cambio automático al nivel gratis cuando se excede
+
+Presupuesto mensual: $150
+  ✅ Alerta al 50% ($75)
+  ✅ Alerta al 80% ($120)
+  ✅ Alerta al 100% ($150)
+```
+
+**Ejemplo de notificaciones:**
+```
+⚠️ Presupuesto diario 80% usado
+   $4.00 / $5.00 gastados hoy
+   
+⚠️ Presupuesto mensual 50% alcanzado
+   $75 / $150 gastados este mes
+   Proyectado: $135 (dentro del presupuesto)
+   
+🚨 Presupuesto diario excedido
+   $5.20 / $5.00 gastados hoy
+   Cambio automático al nivel gratis
+```
+
+### Detección de anomalías de costo
+
+```
+Dashboard → Settings → Anomaly Detection
+
+✅ Detectar patrones de gasto inusuales
+✅ Alerta en picos de costo (>2× promedio diario)
+✅ Advertencia en patrones de agotamiento de cuota
+
+Ejemplo de alerta:
+⚠️ Pico de costo detectado
+   Hoy: $12.50 (2.5× promedio diario)
+   Razón: Alto uso de GLM-4.7 (20M tokens)
+   Sugerencia: Verifica si los modelos principales tienen cuota agotada
+```
+
+---
+
+## Mejores prácticas
+
+### 1. Monitorea la cuota diariamente
+
+```
+Rutina diaria:
+1. Revisa el resumen de cuota del dashboard (30 segundos)
+2. Revisa los tiempos de reinicio
+3. Planifica el uso según la disponibilidad de cuota
+```
+
+**Ejemplo:**
+```
+Revisión matutina:
+  ✅ Claude Code: 5h disponibles (reinicio fresco)
+  ✅ Gemini CLI: 1K solicitudes disponibles
+  ⚠️ GLM-4.7: 2M tokens restantes (se reinicia 10AM)
+  
+Acción: Usar Claude Code para el trabajo matutino
+```
+
+### 2. Establece límites de presupuesto
+
+```
+Dashboard → Settings → Budget:
+  Diario: $5 (previene gastos excesivos)
+  Mensual: $150 (alinea con el presupuesto)
+```
+
+**Resultado**: Cambio automático al nivel gratis cuando se alcanza el límite.
+
+### 3. Optimiza el uso de combos
+
+```
+Dashboard → Analytics → Combos:
+  Revisa qué modelos se usan más
+  Ajusta el orden del combo para minimizar costos
+```
+
+**Ejemplo:**
+```
+Actual: cc/claude-opus → glm/glm-4.7
+  80% vía Claude (bueno)
+  20% vía GLM ($12/mes)
+
+Optimizado: gc/gemini-3-flash → cc/claude-opus → glm/glm-4.7
+  50% vía Gemini (gratis)
+  40% vía Claude (suscripción)
+  10% vía GLM ($6/mes)
+  
+Ahorros: $6/mes
+```
+
+### 4. Rastrea los tiempos de reinicio
+
+```
+Dashboard → Quota → Reset Schedule:
+  Claude Code: 5h rolling + Semanal lunes
+  Gemini CLI: Diario 00:00 UTC + Mensual día 1
+  GLM-4.7: Diario 10:00 AM hora Beijing
+  MiniMax: Ventana rolling 5h
+```
+
+**Estrategia**: Usa proveedores cuando la cuota esté fresca.
+
+### 5. Revisa los reportes mensuales
+
+```
+Dashboard → Analytics → Monthly Report:
+  Total de tokens: 1.5B
+  Costo total: $120
+  Ahorros: 97% vs ChatGPT API
+  
+Insights:
+  - 60% de uso vía suscripciones ($0)
+  - 30% vía GLM ($90)
+  - 10% vía nivel gratis ($0)
+  
+Optimización:
+  - Aumentar el uso de Gemini CLI (gratis)
+  - Reducir el uso de GLM (costoso)
+```
+
+---
+
+## Acceso por API
+
+### Obtener estado de cuota
+
+```bash
+GET http://localhost:20128/api/quota
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "providers": [
+    {
+      "id": "cc",
+      "name": "Claude Code",
+      "quota": {
+        "used": 2.5,
+        "limit": 5,
+        "unit": "hours",
+        "percentage": 50
+      },
+      "reset": {
+        "type": "rolling",
+        "window": "5h",
+        "nextReset": "2026-02-04T06:45:00Z"
+      },
+      "cost": {
+        "today": 0,
+        "month": 0,
+        "currency": "USD"
+      }
+    },
+    {
+      "id": "glm",
+      "name": "GLM-4.7",
+      "quota": {
+        "used": 7000000,
+        "limit": 10000000,
+        "unit": "tokens",
+        "percentage": 70
+      },
+      "reset": {
+        "type": "daily",
+        "time": "10:00 AM UTC+8",
+        "nextReset": "2026-02-04T10:00:00+08:00"
+      },
+      "cost": {
+        "today": 4.20,
+        "month": 52.00,
+        "currency": "USD"
+      }
+    }
+  ]
+}
+```
+
+### Obtener estadísticas de uso
+
+```bash
+GET http://localhost:20128/api/usage?period=today
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "period": "today",
+  "date": "2026-02-04",
+  "summary": {
+    "requests": 1234,
+    "tokens": 26000000,
+    "cost": 4.80
+  },
+  "byModel": [
+    {
+      "model": "cc/claude-opus-4-5",
+      "requests": 456,
+      "tokens": 15000000,
+      "cost": 0
+    },
+    {
+      "model": "glm/glm-4.7",
+      "requests": 234,
+      "tokens": 8000000,
+      "cost": 4.80
+    }
+  ]
+}
+```
+
+---
+
+## Solución de problemas
+
+**Problema: La cuota muestra 0% pero las solicitudes fallan**
+
+**Solución:**
+1. Verifica la conexión del proveedor (Dashboard → Providers)
+2. Verifica que las API keys sean válidas
+3. Verifica si el proveedor está caído (página de estado)
+4. Intenta reconectar los proveedores OAuth
+
+**Problema: Estimación de costos incorrecta**
+
+**Solución:**
+1. Dashboard → Settings → Pricing
+2. Verifica que el precio por proveedor coincida con las tarifas actuales
+3. Actualiza el precio si el proveedor cambió las tarifas
+4. Contacta a soporte si la discrepancia persiste
+
+**Problema: El tiempo de reinicio no se actualiza**
+
+**Solución:**
+1. Refresca el dashboard (F5)
+2. Verifica que la hora del sistema sea correcta
+3. Verifica la configuración de zona horaria
+4. Reinicia 9Router si el problema persiste
+
+**Problema: No se reciben alertas**
+
+**Solución:**
+1. Dashboard → Settings → Alerts
+2. Verifica que la dirección de email sea correcta
+3. Revisa la carpeta de spam
+4. Prueba la notificación (botón Send Test)
+
+---
+
+## Relacionado
+
+- [Enrutamiento inteligente](./smart-routing.md) - Fallback automático según cuota
+- [Combos](./combos.md) - Crea cadenas de fallback personalizadas
diff --git a/gitbook/content/es/features/smart-routing.md b/gitbook/content/es/features/smart-routing.md
new file mode 100644
index 0000000..407d5fe
--- /dev/null
+++ b/gitbook/content/es/features/smart-routing.md
@@ -0,0 +1,407 @@
+# Enrutamiento inteligente y fallback automático
+
+9Router enruta automáticamente tus solicitudes a través del mejor proveedor disponible usando un sistema de fallback de 3 niveles. Nunca dejes de codificar debido a límites de cuota o rate-limiting.
+
+---
+
+## Cómo funciona
+
+9Router usa enrutamiento inteligente para maximizar tus suscripciones existentes, minimizar costos y garantizar disponibilidad 24/7:
+
+```
+Solicitud → 9Router → Verificar Nivel 1 (Suscripción)
+                       ↓ cuota agotada
+                       Verificar Nivel 2 (Barato)
+                       ↓ límite de presupuesto
+                       Verificar Nivel 3 (Gratis)
+                       ↓
+                       Respuesta
+```
+
+### Sistema de fallback de 3 niveles
+
+**Nivel 1: SUSCRIPCIÓN (Primario)**
+- Claude Code (Pro/Max)
+- OpenAI Codex (Plus/Pro)
+- Gemini CLI (GRATIS 180K/mes)
+- GitHub Copilot
+- Antigravity (Google)
+
+**Objetivo**: Maximizar el valor de las suscripciones que ya pagas.
+
+**Nivel 2: BARATO (Respaldo)**
+- GLM-4.7 ($0.60/1M entrada)
+- MiniMax M2.1 ($0.20/1M entrada)
+- Kimi K2 ($9/mes plano)
+
+**Objetivo**: Respaldo ultra-barato cuando se agota la cuota de suscripción (~90% más barato que ChatGPT API).
+
+**Nivel 3: GRATIS (Emergencia)**
+- iFlow (8 modelos)
+- Qwen (3 modelos)
+- Kiro (Claude GRATIS)
+
+**Objetivo**: Fallback de cero costo para codificación ilimitada.
+
+---
+
+## Cambio automático
+
+9Router monitorea la cuota en tiempo real y cambia de proveedor automáticamente:
+
+### Escenario 1: Cuota de suscripción agotada
+
+```
+Solicitud del usuario → cc/claude-opus-4-5
+                       ↓ cuota agotada (límite de 5 horas alcanzado)
+                       Cambio automático → glm/glm-4.7
+                       ↓ cuota diaria agotada
+                       Cambio automático → minimax/MiniMax-M2.1
+                       ↓ cuota de 5 horas agotada
+                       Cambio automático → if/kimi-k2-thinking (GRATIS)
+                       ↓
+                       Respuesta entregada ✅
+```
+
+**Resultado**: Cero tiempo de inactividad, experiencia sin interrupciones.
+
+### Escenario 2: Rate limiting
+
+```
+Solicitud del usuario → cx/gpt-5.2-codex
+                       ↓ rate limited (demasiadas solicitudes)
+                       Cambio automático → glm/glm-4.7
+                       ↓
+                       Respuesta entregada ✅
+```
+
+### Escenario 3: Proveedor no disponible
+
+```
+Solicitud del usuario → cc/claude-opus-4-5
+                       ↓ error del proveedor (503)
+                       Cambio automático → siguiente modelo disponible
+                       ↓
+                       Respuesta entregada ✅
+```
+
+---
+
+## Lógica de selección de modelo
+
+9Router selecciona el mejor modelo según:
+
+1. **Disponibilidad de cuota** - Verifica si el proveedor tiene cuota restante
+2. **Nivel de costo** - Prefiere suscripción → barato → gratis
+3. **Tiempo de reinicio** - Considera cuándo se reinicia la cuota
+4. **Salud del proveedor** - Omite proveedores con errores
+
+### Ejemplo de orden de prioridad
+
+Para una solicitud a `cc/claude-opus-4-5`:
+
+```
+1. Verificar cuota de Claude Code
+   ✅ Disponible → Usa cc/claude-opus-4-5
+   ❌ Agotada → Continúa al paso 2
+
+2. Verificar nivel de fallback (si está configurado)
+   ✅ Cuota de GLM disponible → Usa glm/glm-4.7
+   ❌ Agotada → Continúa al paso 3
+
+3. Verificar nivel gratis
+   ✅ iFlow disponible → Usa if/kimi-k2-thinking
+   ❌ Todo agotado → Devuelve error de cuota
+```
+
+---
+
+## Opciones de configuración
+
+### Configuración del dashboard
+
+**1. Habilitar/Deshabilitar fallback automático**
+
+```
+Dashboard → Settings → Smart Routing
+→ Toggle "Auto Fallback" ON/OFF
+```
+
+- **ON** (por defecto): Cambio automático de nivel
+- **OFF**: Modo estricto, devuelve error si el modelo principal no está disponible
+
+**2. Establecer límites de presupuesto**
+
+```
+Dashboard → Settings → Budget Control
+→ Límite diario: $5
+→ Límite mensual: $50
+```
+
+Cuando se alcanza el presupuesto, 9Router cambia automáticamente al nivel gratis.
+
+**3. Configurar el orden de fallback**
+
+```
+Dashboard → Settings → Fallback Priority
+→ Arrastra para reordenar proveedores dentro de cada nivel
+```
+
+Ejemplo de orden personalizado:
+```
+Nivel 1: Gemini CLI → Claude Code → Codex
+Nivel 2: MiniMax → GLM → Kimi
+Nivel 3: iFlow → Kiro → Qwen
+```
+
+**4. Notificaciones de reinicio de cuota**
+
+```
+Dashboard → Settings → Notifications
+→ Email cuando se reinicia la cuota
+→ Alerta cuando se usa 80% de cuota
+```
+
+---
+
+## Ejemplos
+
+### Ejemplo 1: Fallback automático básico
+
+**Configuración:**
+```
+Model: cc/claude-opus-4-5-20251101
+Fallback: Auto (3 niveles por defecto)
+```
+
+**Comportamiento:**
+```
+Mañana (cuota fresca):
+  Solicitud → cc/claude-opus-4-5 ✅
+
+Tarde (cuota agotada):
+  Solicitud → glm/glm-4.7 ✅ (cambio automático)
+
+Noche (cuota de GLM agotada):
+  Solicitud → minimax/MiniMax-M2.1 ✅ (cambio automático)
+
+Madrugada (toda la cuota de pago agotada):
+  Solicitud → if/kimi-k2-thinking ✅ (nivel gratis)
+```
+
+**Costo**: ~$5-10/mes extra (en su mayoría cubierto por la suscripción).
+
+### Ejemplo 2: Enrutamiento consciente del presupuesto
+
+**Configuración:**
+```
+Dashboard → Settings:
+  Presupuesto diario: $2
+  Presupuesto mensual: $20
+  Fallback: Habilitado
+```
+
+**Comportamiento:**
+```
+Día 1-15 (dentro del presupuesto):
+  Solicitudes → glm/glm-4.7 (nivel barato)
+  Costo: $1.50/día
+
+Día 16 (presupuesto alcanzado):
+  Solicitudes → if/kimi-k2-thinking (nivel gratis)
+  Costo: $0
+
+Mes siguiente (presupuesto se reinicia):
+  Solicitudes → glm/glm-4.7 nuevamente
+```
+
+**Resultado**: Nunca excede $20/mes, siempre disponible.
+
+### Ejemplo 3: Modo solo suscripción
+
+**Configuración:**
+```
+Dashboard → Settings:
+  Fallback automático: OFF
+  Modo estricto: ON
+```
+
+**Comportamiento:**
+```
+Solicitud → cc/claude-opus-4-5
+  ✅ Cuota disponible → Éxito
+  ❌ Cuota agotada → Devuelve error (sin fallback)
+```
+
+**Caso de uso**: Cuando solo quieres usar suscripciones de pago, sin costos extras.
+
+### Ejemplo 4: Modo solo gratis
+
+**Configuración:**
+```
+Model: if/kimi-k2-thinking
+Fallback: qw/qwen3-coder-plus → kr/claude-sonnet-4.5
+```
+
+**Comportamiento:**
+```
+Todas las solicitudes → Solo nivel gratis
+Costo: $0 para siempre
+```
+
+**Caso de uso**: Proyectos personales, aprendizaje, experimentación.
+
+---
+
+## Mejores prácticas
+
+### 1. Maximiza el valor de la suscripción
+
+```
+Estrategia:
+- Establece modelos de suscripción como Nivel 1
+- Monitorea el uso de cuota en el dashboard
+- Usa el nivel barato solo cuando la suscripción se agote
+```
+
+**Ejemplo de combo:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 2. Optimiza por costo
+
+```
+Estrategia:
+- Usa el nivel gratis de Gemini CLI primero (180K/mes)
+- Fallback a GLM/MiniMax (ultra-baratos)
+- Emergencia: iFlow (gratis)
+```
+
+**Ejemplo de combo:**
+```
+gc/gemini-3-flash-preview → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 3. Optimiza por calidad
+
+```
+Estrategia:
+- Usa los mejores modelos (Claude Opus, GPT-5.2)
+- Fallback a modelos baratos buenos (GLM-4.7)
+- Último recurso: Nivel gratis
+```
+
+**Ejemplo de combo:**
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → glm/glm-4.7
+```
+
+### 4. Disponibilidad 24/7
+
+```
+Estrategia:
+- Siempre incluye el nivel gratis en el fallback
+- Monitorea los tiempos de reinicio de cuota
+- Distribuye el uso entre proveedores
+```
+
+**Ejemplo de combo:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+**Resultado**: Nunca te quedas sin cuota, codifica en cualquier momento.
+
+---
+
+## Estrategia de reinicio de cuota
+
+Planifica tu uso según los tiempos de reinicio de cuota:
+
+| Proveedor | Reinicio de cuota | Estrategia |
+|----------|-------------|----------|
+| **Claude Code** | 5 horas + semanal | Usar en la mañana, cuota fresca |
+| **Codex** | 5 horas + semanal | Usar después de cuota de Claude |
+| **Gemini CLI** | Diario (1K) + Mensual (180K) | Usar durante el día |
+| **GLM-4.7** | Diario 10:00 AM | Usar en la noche, se reinicia al día siguiente |
+| **MiniMax M2.1** | Rolling 5 horas | Usar cuando sea, rastrea ventana rolling |
+| **iFlow/Qwen/Kiro** | Sin límite | Respaldo de emergencia |
+
+**Ejemplo de rutina diaria:**
+```
+08:00 - 13:00: Claude Code (cuota fresca 5h)
+13:00 - 18:00: Gemini CLI (cuota 1K/día)
+18:00 - 22:00: GLM-4.7 (barato, se reinicia 10AM)
+22:00 - 08:00: MiniMax o iFlow (rolling 5h o gratis)
+```
+
+---
+
+## Monitoreo y alertas
+
+### Rastreador de cuota del dashboard
+
+```
+Dashboard → Quota Overview:
+  Claude Code: 2.5h / 5h restantes (50%)
+  Gemini CLI: 450 / 1000 solicitudes hoy
+  GLM-4.7: 5M / 10M tokens (se reinicia en 8h)
+  MiniMax: 3M / 5M tokens (rolling 5h)
+```
+
+### Notificaciones en tiempo real
+
+```
+Dashboard → Notifications:
+  ⚠️ Cuota de Claude Code 80% usada (1h restante)
+  ✅ Cuota de GLM-4.7 reiniciada (10M tokens disponibles)
+  💰 Presupuesto diario 50% usado ($2.50 / $5)
+```
+
+### Analítica de uso
+
+```
+Dashboard → Analytics:
+  Hoy: 50M tokens
+    - 30M vía Claude Code (suscripción)
+    - 15M vía GLM-4.7 ($9)
+    - 5M vía iFlow (gratis)
+  
+  Costo: $9 (vs $1000 en ChatGPT API)
+  Ahorros: 99%
+```
+
+---
+
+## Solución de problemas
+
+**Problema: "All providers quota exhausted"**
+
+**Solución:**
+1. Verifica el rastreador de cuota del dashboard
+2. Espera el reinicio de cuota (mira la cuenta regresiva)
+3. Agrega el nivel gratis a la cadena de fallback
+4. O aumenta el límite de presupuesto
+
+**Problema: "Demasiados cambios de fallback"**
+
+**Solución:**
+1. Verifica si el proveedor principal está caído
+2. Aumenta los límites de cuota (mejora la suscripción)
+3. Usa un modelo principal más barato (GLM en lugar de Claude)
+
+**Problema: "Costos inesperados"**
+
+**Solución:**
+1. Dashboard → Analytics → Revisa el uso
+2. Establece límites de presupuesto diarios/mensuales
+3. Cambia al nivel gratis para tareas no críticas
+4. Usa combos con fallback gratis
+
+---
+
+## Relacionado
+
+- [Combos](./combos.md) - Crea cadenas de fallback personalizadas
+- [Seguimiento de cuota](./quota-tracking.md) - Monitorea uso y costos
diff --git a/gitbook/content/es/getting-started/installation.md b/gitbook/content/es/getting-started/installation.md
new file mode 100644
index 0000000..8b2b8bd
--- /dev/null
+++ b/gitbook/content/es/getting-started/installation.md
@@ -0,0 +1,478 @@
+# Instalación
+
+Guía detallada de instalación de 9Router con consejos de solución de problemas.
+
+---
+
+## Requisitos
+
+### Requisitos del sistema
+
+- **Node.js**: Versión 20.0.0 o superior
+- **npm**: Versión 10.0.0 o superior (viene con Node.js)
+- **OS**: macOS, Linux, Windows (WSL recomendado)
+- **Espacio en disco**: ~200MB para la instalación
+
+### Verifica tu versión
+
+```bash
+node --version
+# Debería mostrar v20.x.x o superior
+
+npm --version
+# Debería mostrar 10.x.x o superior
+```
+
+**¿No tienes Node.js?** Instálalo desde [nodejs.org](https://nodejs.org/)
+
+---
+
+## Métodos de instalación
+
+### Método 1: Instalación global (Recomendado)
+
+Instala 9Router globalmente para usar desde cualquier lugar:
+
+```bash
+npm install -g 9router
+```
+
+**Iniciar 9Router:**
+
+```bash
+9router
+```
+
+**Beneficios:**
+- ✅ Ejecuta desde cualquier directorio
+- ✅ Comando simple: `9router`
+- ✅ Auto-actualizaciones con `npm update -g 9router`
+
+### Método 2: Instalación local
+
+Instala en un proyecto específico:
+
+```bash
+mkdir my-9router
+cd my-9router
+npm install 9router
+```
+
+**Iniciar 9Router:**
+
+```bash
+npx 9router
+```
+
+**Beneficios:**
+- ✅ Aislado por proyecto
+- ✅ Control de versiones por proyecto
+- ✅ Sin contaminación del namespace global
+
+### Método 3: Desde el código fuente (Desarrollo)
+
+Clona y compila desde GitHub:
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install
+npm run build
+npm start
+```
+
+**Beneficios:**
+- ✅ Últimas características de desarrollo
+- ✅ Contribuir al desarrollo
+- ✅ Modificaciones personalizadas
+
+---
+
+## Primera ejecución
+
+### Iniciar el servidor
+
+```bash
+9router
+```
+
+**Qué sucede:**
+1. El servidor inicia en `http://localhost:20128`
+2. El dashboard se abre automáticamente en el navegador
+3. Se crea el directorio de datos en `~/.9router`
+4. API key generada automáticamente
+
+### Login del dashboard
+
+**Credenciales por defecto:**
+- Contraseña: `123456`
+
+**⚠️ Cambia la contraseña inmediatamente:**
+1. Inicia sesión en el dashboard
+2. Settings → Change Password
+3. Usa una contraseña fuerte
+
+### Obtén tu API key
+
+```
+Dashboard → Settings → API Keys
+→ Copia tu API key
+→ Úsala en herramientas CLI
+```
+
+**Ejemplo de formato de API key:**
+```
+9r_1234567890abcdef1234567890abcdef
+```
+
+---
+
+## Verificar la instalación
+
+### Verifica el estado del servidor
+
+```bash
+curl http://localhost:20128/health
+```
+
+**Respuesta esperada:**
+```json
+{
+  "status": "ok",
+  "version": "1.0.0"
+}
+```
+
+### Lista los modelos disponibles
+
+```bash
+curl http://localhost:20128/v1/models \
+  -H "Authorization: Bearer your-api-key"
+```
+
+**Respuesta esperada:**
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "cc/claude-opus-4-5-20251101",
+      "object": "model",
+      "created": 1234567890,
+      "owned_by": "claude-code"
+    }
+  ]
+}
+```
+
+### Prueba el chat completion
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "cc/claude-opus-4-5-20251101",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+---
+
+## Configuración
+
+### Variables de entorno
+
+Crea un archivo `.env` o establece variables de entorno:
+
+```bash
+# Security (REQUIRED in production)
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+
+# Storage
+export DATA_DIR="~/.9router"
+
+# Server
+export PORT="20128"
+export NODE_ENV="production"
+
+# Logging
+export ENABLE_REQUEST_LOGS="false"
+```
+
+### Directorio de datos
+
+**Ubicación por defecto:** `~/.9router`
+
+**Contenido:**
+```
+~/.9router/
+  ├── db.json           # Database (providers, combos, usage)
+  ├── api-keys.json     # API keys
+  └── logs/             # Request logs (if enabled)
+```
+
+**Cambiar ubicación:**
+
+```bash
+export DATA_DIR="/custom/path"
+9router
+```
+
+### Configuración de puerto
+
+**Puerto por defecto:** `20128`
+
+**Cambiar puerto:**
+
+```bash
+export PORT="3000"
+9router
+```
+
+**O usa la línea de comandos:**
+
+```bash
+9router --port 3000
+```
+
+---
+
+## Solución de problemas
+
+### Puerto ya en uso
+
+**Error:**
+```
+Error: listen EADDRINUSE: address already in use :::20128
+```
+
+**Solución 1: Mata el proceso existente**
+
+```bash
+# Encuentra proceso usando el puerto 20128
+lsof -i :20128
+
+# Mata el proceso
+kill -9 <PID>
+```
+
+**Solución 2: Usa otro puerto**
+
+```bash
+9router --port 3000
+```
+
+### Permiso denegado
+
+**Error:**
+```
+Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
+```
+
+**Solución: Usa sudo (no recomendado) o corrige los permisos de npm**
+
+```bash
+# Corregir permisos de npm (recomendado)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# Luego instalar nuevamente
+npm install -g 9router
+```
+
+### Versión de Node.js muy antigua
+
+**Error:**
+```
+Error: The engine "node" is incompatible with this module
+```
+
+**Solución: Actualizar Node.js**
+
+```bash
+# Usando nvm (recomendado)
+nvm install 20
+nvm use 20
+
+# O descargar desde nodejs.org
+```
+
+### El dashboard no se abre
+
+**Problema:** El dashboard no se abre automáticamente
+
+**Solución 1: Abrir manualmente**
+
+```
+http://localhost:20128
+```
+
+**Solución 2: Verifica el firewall**
+
+```bash
+# macOS: Permitir Node.js en System Preferences → Security
+# Linux: Verificar iptables
+# Windows: Verificar Windows Firewall
+```
+
+### No se puede conectar a proveedores
+
+**Problema:** El login OAuth falla o la API key es inválida
+
+**Solución 1: Verifica la conexión a internet**
+
+```bash
+ping google.com
+```
+
+**Solución 2: Verifica el estado del proveedor**
+
+- Claude Code: [status.anthropic.com](https://status.anthropic.com)
+- OpenAI: [status.openai.com](https://status.openai.com)
+- Gemini: [status.cloud.google.com](https://status.cloud.google.com)
+
+**Solución 3: Regenera la API key**
+
+```
+Dashboard → Provider → Disconnect → Reconnect
+```
+
+### Uso alto de memoria
+
+**Problema:** 9Router usa demasiada RAM
+
+**Solución: Reinicia el servidor**
+
+```bash
+# Detener
+pkill -f 9router
+
+# Iniciar
+9router
+```
+
+**O usa PM2 para auto-reinicio:**
+
+```bash
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+```
+
+---
+
+## Opciones de despliegue
+
+### Desarrollo local
+
+```bash
+npm install -g 9router
+9router
+```
+
+**Caso de uso:** Codificación personal, pruebas
+
+### Servidor VPS/Cloud
+
+```bash
+# Instalar
+npm install -g 9router
+
+# Configurar
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+# Iniciar con PM2
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+pm2 startup
+```
+
+**Caso de uso:** Acceso de equipo, codificación remota
+
+### Docker
+
+```bash
+docker pull 9router/9router:latest
+
+docker run -d \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret" \
+  -e INITIAL_PASSWORD="your-password" \
+  -v 9router-data:/root/.9router \
+  --name 9router \
+  9router/9router:latest
+```
+
+**Caso de uso:** Despliegue containerizado, Kubernetes
+
+### Proxy reverso (Nginx)
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        
+        # SSE support for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+**Caso de uso:** HTTPS, dominio personalizado, balanceo de carga
+
+---
+
+## Desinstalación
+
+### Eliminar instalación global
+
+```bash
+npm uninstall -g 9router
+```
+
+### Eliminar el directorio de datos
+
+```bash
+rm -rf ~/.9router
+```
+
+### Eliminar la configuración
+
+```bash
+# Eliminar variables de entorno del archivo de configuración del shell
+nano ~/.bashrc  # o ~/.zshrc
+# Eliminar exports relacionados con 9router
+```
+
+---
+
+## Próximos pasos
+
+- [Guía para empezar](../getting-started.md) - Conecta proveedores y comienza a codificar
+- [Características](../features/) - Explora seguimiento de cuota, combos, despliegue
+- [Solución de problemas](../troubleshooting.md) - Resuelve problemas comunes
+
+---
+
+## ¿Necesitas ayuda?
+
+- **Sitio web**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
diff --git a/gitbook/content/es/getting-started/quick-start.md b/gitbook/content/es/getting-started/quick-start.md
new file mode 100644
index 0000000..23d55f0
--- /dev/null
+++ b/gitbook/content/es/getting-started/quick-start.md
@@ -0,0 +1,247 @@
+# Empezar
+
+Pon en marcha 9Router en 5 minutos y comienza a enrutar solicitudes de IA de forma inteligente.
+
+---
+
+## Inicio rápido
+
+### 1. Instalar
+
+```bash
+npm install -g 9router
+```
+
+**Requisitos:** Node.js 20+ ([Detalles de instalación](getting-started/installation.md))
+
+### 2. Iniciar
+
+```bash
+9router
+```
+
+🎉 **El dashboard se abre automáticamente** en `http://localhost:20128`
+
+- Contraseña por defecto: `123456` (cámbiala en el dashboard)
+- API key generada automáticamente
+- Listo para conectar proveedores
+
+### 3. Conectar proveedores
+
+Tienes 3 formas de conectar proveedores:
+
+#### Opción A: OAuth (Proveedores de suscripción)
+
+**Ideal para:** Claude Code, Codex, Gemini CLI, GitHub Copilot
+
+```
+Dashboard → Providers → Connect [Provider]
+→ Login OAuth → Refresh automático de token
+→ Seguimiento de cuota habilitado
+```
+
+**Ejemplo: Claude Code**
+1. Clic en "Connect Claude Code"
+2. Inicia sesión con tu cuenta de Claude
+3. Autoriza 9Router
+4. ✅ ¡Listo! Usa el modelo: `cc/claude-opus-4-5-20251101`
+
+#### Opción B: API Key (Proveedores baratos)
+
+**Ideal para:** GLM, MiniMax, Kimi, OpenRouter
+
+```
+Dashboard → Providers → Add API Key
+→ Selecciona proveedor
+→ Pega API key
+→ Guardar
+```
+
+**Ejemplo: GLM-4.7**
+1. Regístrate en [Zhipu AI](https://open.bigmodel.cn/)
+2. Obtén la API key del Coding Plan
+3. Dashboard → Add API Key → Provider: `glm` → Pega la key
+4. ✅ ¡Listo! Usa el modelo: `glm/glm-4.7`
+
+#### Opción C: Proveedores gratis (Sin costo)
+
+**Ideal para:** iFlow, Qwen, Kiro
+
+```
+Dashboard → Providers → Connect [Free Provider]
+→ Device code u OAuth
+→ Uso ilimitado
+```
+
+**Ejemplo: iFlow**
+1. Clic en "Connect iFlow"
+2. Inicia sesión con tu cuenta de iFlow
+3. Autoriza
+4. ✅ ¡Listo! Usa 8 modelos: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, etc.
+
+---
+
+## 4. Usar en herramientas CLI
+
+Apunta tu herramienta de codificación a 9Router:
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [desde el dashboard de 9router]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Claude Desktop
+
+Edita `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [desde el dashboard]
+Model: cc/claude-opus-4-5-20251101
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+---
+
+## 5. Crear combos inteligentes (Opcional)
+
+Los combos habilitan el fallback automático entre modelos:
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101 (Suscripción principal)
+  2. glm/glm-4.7 (Respaldo barato, $0.6/1M)
+  3. if/kimi-k2-thinking (Fallback gratis)
+
+Usar en CLI: premium-coding
+```
+
+**Cómo funciona:**
+1. Intenta primero Claude Opus (tu suscripción)
+2. Si la cuota se agota → GLM-4.7 (ultra-barato)
+3. Si llega al límite de presupuesto → iFlow (gratis)
+4. ¡Cero tiempo de inactividad, cambio automático!
+
+---
+
+## Modelos disponibles
+
+### Modelos de suscripción (Maximiza primero)
+
+**Claude Code (`cc/`)** - Suscripción Pro/Max:
+- `cc/claude-opus-4-5-20251101` - Claude 4.5 Opus
+- `cc/claude-sonnet-4-5-20250929` - Claude 4.5 Sonnet
+- `cc/claude-haiku-4-5-20251001` - Claude 4.5 Haiku
+
+**Codex (`cx/`)** - Suscripción Plus/Pro:
+- `cx/gpt-5.2-codex` - GPT 5.2 Codex
+- `cx/gpt-5.1-codex-max` - GPT 5.1 Codex Max
+
+**Gemini CLI (`gc/`)** - GRATIS 180K/mes:
+- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
+- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
+
+**GitHub Copilot (`gh/`)** - Suscripción:
+- `gh/gpt-5` - GPT-5
+- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
+
+### Modelos baratos (Respaldo)
+
+**GLM (`glm/`)** - $0.6/$2.2 por 1M:
+- `glm/glm-4.7` - GLM 4.7 (reinicio diario 10AM)
+
+**MiniMax (`minimax/`)** - $0.20/$1.00 por 1M:
+- `minimax/MiniMax-M2.1` - MiniMax M2.1 (reinicio 5h)
+
+**Kimi (`kimi/`)** - $9/mes (10M tokens):
+- `kimi/kimi-latest` - Kimi Latest
+
+### Modelos GRATIS (Emergencia)
+
+**iFlow (`if/`)** - 8 modelos GRATIS:
+- `if/kimi-k2-thinking` - Kimi K2 Thinking
+- `if/qwen3-coder-plus` - Qwen3 Coder Plus
+- `if/glm-4.7` - GLM 4.7
+- `if/deepseek-r1` - DeepSeek R1
+
+**Qwen (`qw/`)** - 3 modelos GRATIS:
+- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
+- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
+
+**Kiro (`kr/`)** - 2 modelos GRATIS:
+- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
+- `kr/claude-haiku-4.5` - Claude Haiku 4.5
+
+---
+
+## Estrategia de optimización de costos
+
+### Presupuesto mensual: $10-20/mes
+
+```
+1. Usa el nivel gratis de Gemini CLI (180K/mes) para tareas rápidas
+2. Usa la cuota de suscripción de Claude Code al máximo (ya pagas)
+3. Fallback a GLM ($0.6/1M) cuando se agote la cuota
+4. Emergencia: MiniMax M2.1 ($0.20/1M) o iFlow (gratis)
+
+Ejemplo real (100M tokens/mes):
+  60M vía Gemini CLI: $0 (nivel gratis)
+  30M vía Claude Code: $0 (suscripción que ya tienes)
+  8M vía GLM: $4.80
+  2M vía MiniMax: $0.40
+  Total: $5.20/mes + suscripciones existentes
+```
+
+### Estrategia de reinicio de cuota
+
+```
+Rutina diaria:
+1. Mañana: Cuota fresca de Claude Code (reinicio 5h)
+2. Tarde: Cambia a Gemini CLI (1K/día)
+3. Noche: Cuota diaria de GLM (reinicio 10AM del día siguiente)
+4. Madrugada: MiniMax (rolling 5h) o iFlow (gratis)
+
+→ ¡Codifica 24/7 con costo extra mínimo!
+```
+
+---
+
+## Próximos pasos
+
+- [Detalles de instalación](getting-started/installation.md) - Requisitos, troubleshooting
+- [Características](features/) - Explora seguimiento de cuota, combos, despliegue
+- [FAQ](faq.md) - Preguntas y respuestas comunes
+- [Troubleshooting](troubleshooting.md) - Soluciona problemas comunes
+
+---
+
+## ¿Necesitas ayuda?
+
+- **Sitio web**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
diff --git a/gitbook/content/es/index.md b/gitbook/content/es/index.md
new file mode 100644
index 0000000..9e7c053
--- /dev/null
+++ b/gitbook/content/es/index.md
@@ -0,0 +1,164 @@
+# Bienvenido a 9Router
+
+**Usa Claude, Codex, Gemini GRATIS • Alternativas ultra-baratas desde $0.20/1M tokens**
+
+9Router es un router de modelos de IA que maximiza el valor de tus suscripciones y minimiza los costos mediante enrutamiento inteligente y fallback automático.
+
+---
+
+## ¿Qué es 9Router?
+
+9Router es un proxy inteligente que se sitúa entre tus herramientas de codificación (Cursor, Cline, Claude Desktop) y los proveedores de IA. Enruta automáticamente las solicitudes al mejor modelo disponible según la cuota, el costo y la disponibilidad.
+
+**Deja de desperdiciar dinero:**
+- ❌ La cuota de suscripción expira sin usar cada mes
+- ❌ Los límites de tasa te detienen a mitad de la codificación
+- ❌ APIs costosas ($20-50/mes por proveedor)
+- ❌ Cambio manual entre proveedores
+
+**Empieza a maximizar el valor:**
+- ✅ **Maximiza tus suscripciones** - Rastrea y usa cada bit de cuota de Claude Code, Codex, Gemini
+- ✅ **GRATIS disponible** - Accede a modelos iFlow, Qwen, Kiro vía CLI
+- ✅ **Respaldo ultra-barato** - GLM ($0.6/1M), MiniMax M2.1 ($0.20/1M)
+- ✅ **Fallback inteligente** - Suscripción → Barato → Gratis, cambio automático
+
+---
+
+## Características clave
+
+### 🔄 Fallback inteligente de 3 niveles
+
+```
+Configura una vez, nunca dejes de codificar:
+
+Nivel 1 (SUSCRIPCIÓN): Claude Code → Codex → Gemini
+  ↓ cuota agotada
+Nivel 2 (BARATO): GLM-4.7 → MiniMax M2.1 → Kimi
+  ↓ límite de presupuesto
+Nivel 3 (GRATIS): iFlow → Qwen → Kiro
+
+→ Cambio automático, sin tiempo de inactividad!
+```
+
+### 📊 Seguimiento de cuota
+
+- Consumo de tokens en tiempo real por proveedor
+- Cuenta regresiva de reinicio (5 horas, diario, semanal, mensual)
+- Estimación de costos para niveles de pago
+- Reportes de gasto mensual
+
+### 🎯 Soporte universal de CLI
+
+Funciona con cualquier herramienta que soporte endpoints personalizados de OpenAI:
+
+✅ **Cursor** • **Cline** • **Claude Desktop** • **Codex** • **RooCode** • **Continue** • **Cualquier herramienta compatible con OpenAI**
+
+### 💰 Optimización de costos
+
+**Ejemplo real (100M tokens/mes):**
+```
+60M vía Gemini CLI: $0 (nivel gratis)
+30M vía Claude Code: $0 (suscripción que ya tienes)
+8M vía GLM: $4.80
+2M vía MiniMax: $0.40
+Total: $5.20/mes vs $2000 en ChatGPT API!
+```
+
+---
+
+## ¿Por qué elegir 9Router?
+
+### Maximiza tus suscripciones
+
+¿Ya pagas Claude Code ($20-100/mes) o Codex ($20-200/mes)? Obtén el valor completo:
+
+- Rastrea el uso de cuota en tiempo real
+- Cambio automático cuando se reinicia la cuota (5 horas, semanal)
+- Usa cada token antes de que expire
+- Gemini CLI: 180K completados/mes **GRATIS**
+
+### Respaldo ultra-barato
+
+Cuando se agota la cuota de suscripción, paga centavos:
+
+| Proveedor | Costo por 1M tokens | Reinicio |
+|----------|-------------------|-------|
+| **GLM-4.7** | $0.60 entrada / $2.20 salida | Diario 10:00 AM |
+| **MiniMax M2.1** | $0.20 entrada / $1.00 salida | 5 horas rolling |
+| **Kimi K2** | $9/mes (10M tokens) | Mensual |
+
+**~90% más barato que ChatGPT API ($20/1M)!**
+
+### Fallback gratis para siempre
+
+Respaldo de emergencia cuando todo lo demás está limitado por cuota:
+
+- **iFlow**: 8 modelos (Kimi K2, Qwen3 Coder Plus, GLM 4.7, MiniMax M2)
+- **Qwen**: 3 modelos (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro**: Claude Sonnet 4.5, Haiku 4.5 (AWS Builder ID)
+
+---
+
+## Inicio rápido
+
+Comienza en 2 minutos:
+
+```bash
+# Instala globalmente
+npm install -g 9router
+
+# Inicia (el dashboard se abre automáticamente)
+9router
+```
+
+🎉 **Se abre el dashboard** → Conecta proveedores → ¡Empieza a codificar!
+
+**Úsalo en tu herramienta CLI:**
+
+```
+Endpoint: http://localhost:20128/v1
+API Key: [desde el dashboard]
+Model: cc/claude-opus-4-5-20251101
+```
+
+[→ Guía completa para empezar](getting-started.md)
+
+---
+
+## Casos de uso
+
+### Para desarrolladores individuales
+
+- Maximiza tu suscripción de Claude Code/Codex
+- Usa el nivel gratis de Gemini CLI (180K/mes)
+- Fallback a modelos ultra-baratos ($0.20/1M)
+- Codifica 24/7 sin límites de tasa
+
+### Para equipos
+
+- Despliega en VPS/Cloud para acceso compartido
+- Rastrea el gasto del equipo en tiempo real
+- Establece límites de presupuesto por nivel
+- Gestión centralizada de proveedores
+
+### Para codificación móvil/remota
+
+- Usa el despliegue en la nube (https://9router.com)
+- Accede desde iPad, teléfono, donde sea
+- Sin limitaciones de localhost
+- Red edge de Cloudflare (300+ ubicaciones)
+
+---
+
+## ¿Qué sigue?
+
+- [Empezar](getting-started.md) - Instala y configura en 5 minutos
+- [Guía de instalación](getting-started/installation.md) - Instrucciones detalladas
+- [Características](features/) - Explora todas las capacidades
+- [FAQ](faq.md) - Preguntas comunes
+
+---
+
+<div align="center">
+  <sub>Construido con ❤️ para desarrolladores que maximizan el valor de la IA</sub>
+</div>
diff --git a/gitbook/content/es/integration/claude-code.md b/gitbook/content/es/integration/claude-code.md
new file mode 100644
index 0000000..61b3c1f
--- /dev/null
+++ b/gitbook/content/es/integration/claude-code.md
@@ -0,0 +1,109 @@
+# Integración con Claude Code
+
+Integra 9Router con Claude Code CLI para enrutar tus solicitudes de la API de Anthropic a través del sistema de enrutamiento inteligente de 9Router.
+
+## Requisitos previos
+
+- Claude Code CLI instalado
+- 9Router ejecutándose localmente o endpoint en la nube configurado
+- API key del dashboard de 9Router
+
+## Configuración
+
+### 1. Configurar variables de entorno
+
+Establece las siguientes variables de entorno en tu archivo de configuración del shell (`~/.bashrc`, `~/.zshrc`, o `~/.bash_profile`):
+
+```bash
+# Base URL for 9Router
+export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
+
+# Optional: Set default models for aliases
+export ANTHROPIC_DEFAULT_OPUS_MODEL="cc/claude-opus-4-5-20251101"
+export ANTHROPIC_DEFAULT_SONNET_MODEL="cc/claude-sonnet-4-5-20250929"
+export ANTHROPIC_DEFAULT_HAIKU_MODEL="cc/claude-haiku-4-5-20251001"
+```
+
+### 2. Recargar la configuración del shell
+
+```bash
+source ~/.zshrc  # o ~/.bashrc
+```
+
+### 3. Verificar la configuración
+
+Verifica que las variables de entorno estén configuradas correctamente:
+
+```bash
+echo $ANTHROPIC_BASE_URL
+```
+
+## Aliases de modelos
+
+Claude Code soporta los siguientes aliases de modelos que mapean a modelos de 9Router:
+
+| Alias | Modelo | Variable de entorno |
+|-------|-------|---------------------|
+| `opus` | Claude Opus 4.5 | `ANTHROPIC_DEFAULT_OPUS_MODEL` |
+| `sonnet` | Claude Sonnet 4.5 | `ANTHROPIC_DEFAULT_SONNET_MODEL` |
+| `haiku` | Claude Haiku 4.5 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` |
+
+## Ejemplos de uso
+
+### Usando aliases de modelos
+
+```bash
+# Usar modelo Opus
+claude --model opus "Explain quantum computing"
+
+# Usar modelo Sonnet
+claude --model sonnet "Write a Python function"
+
+# Usar modelo Haiku
+claude --model haiku "Quick code review"
+```
+
+### Usando nombres completos de modelos
+
+```bash
+claude --model cc/claude-opus-4-5-20251101 "Your prompt here"
+```
+
+## Archivo de configuración
+
+Claude Code almacena su configuración en `~/.claude/settings.json`. Puedes editar este archivo manualmente si es necesario:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "defaultModel": "sonnet"
+}
+```
+
+## Solución de problemas
+
+### Problemas de conexión
+
+Si encuentras errores de conexión:
+
+1. Verifica que 9Router esté corriendo: `curl http://localhost:20128/health`
+2. Verifica que las variables de entorno estén configuradas correctamente
+3. Asegúrate de que ningún firewall esté bloqueando el puerto 20128
+
+### Modelo no encontrado
+
+Si obtienes errores de "modelo no encontrado":
+
+1. Verifica que el nombre del modelo coincida con tu configuración de 9Router
+2. Verifica que la conexión del proveedor esté activa en el dashboard de 9Router
+3. Asegúrate de que el modelo esté disponible en tus proveedores conectados
+
+## Endpoint en la nube
+
+Para usar el endpoint en la nube de 9Router en lugar de localhost:
+
+```bash
+export ANTHROPIC_BASE_URL="https://9router.com"
+```
+
+Asegúrate de haber configurado tu API key en el dashboard en la nube de 9Router.
diff --git a/gitbook/content/es/integration/cline.md b/gitbook/content/es/integration/cline.md
new file mode 100644
index 0000000..07fe447
--- /dev/null
+++ b/gitbook/content/es/integration/cline.md
@@ -0,0 +1,201 @@
+# Integración con Cline
+
+Integra 9Router con la extensión Cline de VSCode para enrutar tus solicitudes de IA a través del sistema de enrutamiento inteligente de 9Router.
+
+## Requisitos previos
+
+- Visual Studio Code instalado
+- Extensión Cline instalada desde el marketplace de VSCode
+- 9Router ejecutándose localmente o endpoint en la nube configurado
+- API key del dashboard de 9Router
+
+## Configuración
+
+### 1. Abrir la configuración de Cline
+
+1. Abre Visual Studio Code
+2. Abre el panel de la extensión Cline (clic en el ícono de Cline en la barra lateral)
+3. Clic en el ícono de **Settings** (engranaje) en el panel de Cline
+
+### 2. Seleccionar el proveedor de API
+
+1. En la configuración de Cline, encuentra el dropdown **API Provider**
+2. Selecciona **Ollama** de la lista
+   - Nota: Usamos el tipo de proveedor Ollama porque es compatible con APIs estilo OpenAI
+
+### 3. Configurar Base URL
+
+Establece la URL base a tu endpoint de 9Router:
+
+**Para 9Router local:**
+```
+http://localhost:20128/v1
+```
+
+**Para 9Router en la nube:**
+```
+https://9router.com
+```
+
+**Pasos:**
+1. En el campo **Base URL**, ingresa tu endpoint de 9Router
+2. Asegúrate de incluir `/v1` al final
+
+### 4. Agregar API Key
+
+1. En el campo **API Key**, ingresa tu API key de 9Router
+2. Puedes encontrar tu API key en el dashboard de 9Router en **Settings → API Keys**
+3. La key debe comenzar con `sk-9router-`
+
+### 5. Seleccionar modelo
+
+1. En el dropdown **Model**, puedes:
+   - Seleccionar de los modelos disponibles (si Cline los auto-detecta)
+   - Ingresar manualmente el nombre del modelo desde tu configuración de 9Router
+
+2. Nombres comunes de modelos:
+   - `gpt-4`
+   - `gpt-4o`
+   - `claude-opus-4-5`
+   - `claude-sonnet-4-5`
+   - `gemini-2.0-flash`
+
+### 6. Guardar la configuración
+
+Clic en **Save** o cierra el panel de configuración. Cline guardará automáticamente tu configuración.
+
+## Ejemplo de configuración
+
+Tu configuración de Cline debería verse así:
+
+```
+API Provider: Ollama
+Base URL: http://localhost:20128/v1
+API Key: sk-9router-xxxxxxxxxxxxx
+Model: gpt-4
+```
+
+## Modelos disponibles
+
+Puedes usar cualquier modelo configurado en tu dashboard de 9Router. Ejemplos comunes:
+
+| Nombre del modelo | Proveedor | Descripción |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## Uso
+
+### Chat con IA
+
+1. Abre el panel de Cline en VSCode
+2. Escribe tu mensaje en el input del chat
+3. Presiona Enter para enviar
+4. Cline usará 9Router para procesar tu solicitud
+
+### Generación de código
+
+1. Pide a Cline que genere código: "Create a React component for a login form"
+2. Cline generará código usando 9Router
+3. Revisa y acepta el código generado
+
+### Explicación de código
+
+1. Selecciona código en tu editor
+2. Pregunta a Cline: "Explain this code"
+3. Obtén explicaciones potenciadas por IA a través de 9Router
+
+### Operaciones con archivos
+
+1. Pide a Cline que cree, modifique o elimine archivos
+2. Cline usará 9Router para entender el contexto y hacer cambios
+3. Revisa los cambios antes de aceptar
+
+## Solución de problemas
+
+### Error "Connection Failed"
+
+1. Verifica que 9Router esté corriendo: `curl http://localhost:20128/health`
+2. Verifica que la URL base sea correcta e incluya `/v1`
+3. Asegúrate de que ningún firewall esté bloqueando el puerto 20128
+4. Intenta reiniciar VSCode
+
+### Error "Invalid API Key"
+
+1. Verifica tu API key en el dashboard de 9Router
+2. Asegúrate de haber copiado la key completa incluyendo el prefijo `sk-9router-`
+3. Verifica que la API key no haya expirado
+4. Intenta regenerar una nueva API key
+
+### Error "Model Not Found"
+
+1. Verifica que el nombre del modelo coincida exactamente con tu configuración de 9Router
+2. Verifica que la conexión del proveedor esté activa en el dashboard de 9Router
+3. Asegúrate de que el modelo esté disponible en tus proveedores conectados
+4. Intenta usar el nombre completo del modelo (ej. `openai/gpt-4` en lugar de `gpt-4`)
+
+### Cline no responde
+
+1. Revisa el panel de output de Cline para mensajes de error
+2. Verifica que tu instancia de 9Router esté ejecutándose y saludable
+3. Intenta recargar la ventana de VSCode (Cmd/Ctrl + Shift + P → "Reload Window")
+4. Revisa los logs de 9Router para cualquier error
+
+## Configuración avanzada
+
+### Usar endpoint en la nube
+
+Para usar el endpoint en la nube de 9Router en lugar de localhost:
+
+1. En la configuración de Cline, establece Base URL a: `https://9router.com`
+2. Asegúrate de haber configurado tu API key en el dashboard en la nube de 9Router
+3. Asegúrate de que tu endpoint en la nube esté activo y accesible
+
+### Múltiples modelos
+
+Puedes cambiar rápidamente entre modelos:
+
+1. Abre la configuración de Cline
+2. Cambia el campo **Model** a otro modelo
+3. Guarda y continúa chateando con el nuevo modelo
+
+### Timeout personalizado
+
+Si experimentas problemas de timeout con solicitudes grandes:
+
+1. Abre la configuración de VSCode (Cmd/Ctrl + ,)
+2. Busca "Cline timeout"
+3. Aumenta el valor de timeout (por defecto suele ser 30 segundos)
+
+## Mejores prácticas
+
+1. **Usa modelos apropiados**: Elige modelos rápidos (como Haiku o Flash) para tareas simples, y modelos más potentes (como Opus o GPT-4) para tareas complejas
+2. **Monitorea el uso**: Revisa el dashboard de 9Router para estadísticas de uso y costos
+3. **Gestión de contexto**: Mantén tus conversaciones enfocadas para reducir el uso de tokens
+4. **Cambio de modelo**: Cambia modelos según la complejidad de la tarea para optimizar costo y rendimiento
+5. **Seguridad de API Key**: Nunca subas tu API key al control de versiones
+
+## Integración con características de 9Router
+
+### Enrutamiento de modelos
+
+9Router enruta automáticamente tus solicitudes al mejor proveedor disponible según:
+- Disponibilidad del modelo
+- Estado de salud del proveedor
+- Optimización de costos
+- Balanceo de carga
+
+### Soporte de fallback
+
+Si un proveedor falla, 9Router automáticamente cambia a proveedores alternativos configurados en tu dashboard.
+
+### Seguimiento de uso
+
+Monitorea tu uso de Cline a través del dashboard de 9Router:
+- Total de solicitudes
+- Uso de tokens
+- Costo por modelo
+- Distribución por proveedor
diff --git a/gitbook/content/es/integration/codex.md b/gitbook/content/es/integration/codex.md
new file mode 100644
index 0000000..db030e8
--- /dev/null
+++ b/gitbook/content/es/integration/codex.md
@@ -0,0 +1,136 @@
+# Integración con OpenAI Codex CLI
+
+Integra 9Router con OpenAI Codex CLI para enrutar tus solicitudes de la API de OpenAI a través del sistema de enrutamiento inteligente de 9Router.
+
+## Requisitos previos
+
+- OpenAI Codex CLI instalado
+- 9Router ejecutándose localmente o endpoint en la nube configurado
+- API key del dashboard de 9Router
+
+## Configuración
+
+### 1. Configurar variables de entorno
+
+Establece las siguientes variables de entorno en tu archivo de configuración del shell (`~/.bashrc`, `~/.zshrc`, o `~/.bash_profile`):
+
+```bash
+# Base URL for 9Router
+export OPENAI_BASE_URL="http://localhost:20128/v1"
+
+# API Key from 9Router dashboard
+export OPENAI_API_KEY="your-9router-api-key"
+```
+
+### 2. Recargar la configuración del shell
+
+```bash
+source ~/.zshrc  # o ~/.bashrc
+```
+
+### 3. Verificar la configuración
+
+Verifica que las variables de entorno estén configuradas correctamente:
+
+```bash
+echo $OPENAI_BASE_URL
+echo $OPENAI_API_KEY
+```
+
+## Modelos disponibles
+
+9Router proporciona los siguientes modelos de Codex:
+
+| ID del modelo | Descripción |
+|----------|-------------|
+| `cx/gpt-5.2-codex` | GPT-5.2 Codex - Última versión |
+| `cx/gpt-5.1-codex-max` | GPT-5.1 Codex Max - Contexto extendido |
+
+## Ejemplos de uso
+
+### Uso básico
+
+```bash
+# Usar GPT-5.2 Codex
+codex --model cx/gpt-5.2-codex "Write a function to sort an array"
+
+# Usar GPT-5.1 Codex Max
+codex --model cx/gpt-5.1-codex-max "Explain this complex algorithm"
+```
+
+### Generación de código
+
+```bash
+codex --model cx/gpt-5.2-codex "Create a REST API endpoint for user authentication"
+```
+
+### Explicación de código
+
+```bash
+codex --model cx/gpt-5.1-codex-max "Explain what this code does: $(cat myfile.js)"
+```
+
+## Archivo de configuración
+
+También puedes configurar Codex CLI usando un archivo de configuración. Crea o edita `~/.codex/config.json`:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "apiKey": "your-9router-api-key",
+  "defaultModel": "cx/gpt-5.2-codex"
+}
+```
+
+## Solución de problemas
+
+### Errores de autenticación
+
+Si encuentras errores de autenticación:
+
+1. Verifica que tu API key sea correcta en el dashboard de 9Router
+2. Verifica que la variable de entorno `OPENAI_API_KEY` esté configurada
+3. Asegúrate de que la API key no haya expirado
+
+### Problemas de conexión
+
+Si encuentras errores de conexión:
+
+1. Verifica que 9Router esté corriendo: `curl http://localhost:20128/health`
+2. Verifica que las variables de entorno estén configuradas correctamente
+3. Asegúrate de que ningún firewall esté bloqueando el puerto 20128
+
+### Modelo no disponible
+
+Si obtienes errores de "modelo no disponible":
+
+1. Verifica que el nombre del modelo coincida con tu configuración de 9Router
+2. Verifica que la conexión del proveedor de OpenAI esté activa en el dashboard de 9Router
+3. Asegúrate de que el modelo esté disponible en tus proveedores conectados
+
+## Endpoint en la nube
+
+Para usar el endpoint en la nube de 9Router en lugar de localhost:
+
+```bash
+export OPENAI_BASE_URL="https://9router.com"
+```
+
+Asegúrate de haber configurado tu API key en el dashboard en la nube de 9Router.
+
+## Configuración avanzada
+
+### Timeout personalizado
+
+```bash
+export OPENAI_TIMEOUT=60  # segundos
+```
+
+### Modo debug
+
+Habilita el modo debug para ver logs detallados de request/response:
+
+```bash
+export CODEX_DEBUG=true
+codex --model cx/gpt-5.2-codex "Your prompt"
+```
diff --git a/gitbook/content/es/integration/continue.md b/gitbook/content/es/integration/continue.md
new file mode 100644
index 0000000..9fbecdd
--- /dev/null
+++ b/gitbook/content/es/integration/continue.md
@@ -0,0 +1,249 @@
+# Integración con la extensión Continue de VSCode
+
+Integra 9Router con la extensión Continue para llevar la asistencia de IA directamente a Visual Studio Code.
+
+## Requisitos previos
+
+- Visual Studio Code instalado
+- Extensión Continue instalada desde el marketplace de VSCode
+- API key de 9Router desde el [dashboard](https://9router.com/dashboard)
+- 9Router ejecutándose (local o en la nube)
+
+## Pasos de configuración
+
+### 1. Abrir la configuración de Continue
+
+1. Abre VSCode
+2. Presiona `Cmd+Shift+P` (Mac) o `Ctrl+Shift+P` (Windows/Linux)
+3. Escribe "Continue: Open Config" y selecciónalo
+4. Esto abre `~/.continue/config.json`
+
+### 2. Agregar configuración de modelo de 9Router
+
+Agrega la siguiente configuración a tu `config.json`:
+
+**Configuración de un solo modelo:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**Configuración de múltiples modelos:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus (Best)",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Sonnet (Balanced)",
+      "provider": "openai",
+      "model": "cc/claude-sonnet-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - DeepSeek Chat (Code)",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Haiku (Fast)",
+      "provider": "openai",
+      "model": "cc/claude-haiku-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**Para 9Router en la nube:**
+Reemplaza `apiBase` con:
+```json
+"apiBase": "https://9router.com/v1"
+```
+
+### 3. Guardar y recargar
+
+1. Guarda el archivo de configuración
+2. Recarga la ventana de VSCode: `Cmd+Shift+P` → "Developer: Reload Window"
+3. La extensión Continue cargará la nueva configuración
+
+### 4. Seleccionar modelo
+
+1. Abre la barra lateral de Continue (clic en el ícono de Continue en el panel izquierdo)
+2. Clic en el dropdown selector de modelo en la parte superior
+3. Elige tu modelo preferido de 9Router
+
+## Modelos disponibles
+
+### Modelos Claude (Anthropic)
+- `cc/claude-opus-4-5-20251101` - El más capaz, ideal para tareas complejas
+- `cc/claude-sonnet-4-20250514` - Rendimiento y velocidad equilibrados
+- `cc/claude-haiku-4-20250514` - El más rápido, bueno para tareas simples
+
+### Modelos DeepSeek
+- `cx/deepseek-chat` - Excelente para generación de código
+- `cx/deepseek-reasoner` - Mejor para resolución de problemas complejos
+
+### Modelos GLM (Zhipu AI)
+- `glm/glm-4-plus` - Chino e inglés avanzado
+- `glm/glm-4-flash` - Respuestas rápidas
+
+## Ejemplos de uso
+
+### Explicación de código
+1. Selecciona código en el editor
+2. Abre la barra lateral de Continue
+3. Escribe: "Explain this code"
+4. Modelo: `cc/claude-sonnet-4-20250514`
+
+### Generación de código
+1. Abre la barra lateral de Continue
+2. Escribe: "Create a React component for user profile card"
+3. Modelo: `cx/deepseek-chat`
+
+### Refactorización
+1. Selecciona código para refactorizar
+2. Escribe: "Refactor this to use async/await"
+3. Modelo: `cc/claude-sonnet-4-20250514`
+
+### Corrección de bugs
+1. Selecciona código problemático
+2. Escribe: "Find and fix the bug in this code"
+3. Modelo: `cx/deepseek-reasoner`
+
+## Configuración avanzada
+
+### Prompts de sistema personalizados
+
+Agrega prompts de sistema personalizados para comportamientos específicos:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Code Expert",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "systemMessage": "You are an expert programmer. Always provide clean, well-documented code with best practices."
+    }
+  ]
+}
+```
+
+### Temperatura y parámetros
+
+Ajusta el comportamiento del modelo con parámetros:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Creative Writer",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "temperature": 0.9,
+      "topP": 0.95
+    }
+  ]
+}
+```
+
+### Proveedores de contexto
+
+Configura qué contexto envía Continue al modelo:
+
+```json
+{
+  "contextProviders": [
+    {
+      "name": "code",
+      "params": {
+        "maxLines": 100
+      }
+    },
+    {
+      "name": "diff",
+      "params": {}
+    },
+    {
+      "name": "terminal",
+      "params": {}
+    }
+  ]
+}
+```
+
+## Atajos de teclado
+
+- `Cmd+L` (Mac) / `Ctrl+L` (Windows/Linux) - Abrir chat de Continue
+- `Cmd+I` (Mac) / `Ctrl+I` (Windows/Linux) - Edición inline
+- `Cmd+Shift+R` (Mac) / `Ctrl+Shift+R` (Windows/Linux) - Regenerar respuesta
+
+## Solución de problemas
+
+### El modelo no responde
+- Verifica que 9Router esté corriendo: `curl http://localhost:20128/health`
+- Verifica la API key en config.json
+- Revisa la consola de desarrollador de VSCode por errores: `Help` → `Toggle Developer Tools`
+
+### Modelo incorrecto seleccionado
+- Clic en el dropdown de modelo en la barra lateral de Continue
+- Selecciona el modelo correcto de 9Router
+- El nombre del modelo debe coincidir exactamente (sensible a mayúsculas)
+
+### La configuración no se carga
+- Verifica que la sintaxis JSON sea válida (usa un validador de JSON)
+- Verifica la ubicación del archivo: `~/.continue/config.json`
+- Recarga la ventana de VSCode después de cambios
+
+### Rendimiento lento
+- Cambia a modelos más rápidos (haiku, flash)
+- Reduce el tamaño del contexto en contextProviders
+- Verifica la latencia de red hacia 9Router
+
+## Mejores prácticas
+
+### Estrategia de selección de modelo
+- **Ediciones rápidas**: Usa `cc/claude-haiku-4-20250514`
+- **Generación de código**: Usa `cx/deepseek-chat`
+- **Refactoring complejo**: Usa `cc/claude-opus-4-5-20251101`
+- **Resolución de problemas**: Usa `cx/deepseek-reasoner`
+
+### Gestión de contexto
+- Selecciona solo el código relevante antes de preguntar
+- Usa prompts específicos y claros
+- Divide tareas complejas en pasos más pequeños
+
+### Optimización de costos
+- Usa modelos más rápidos/baratos para tareas simples
+- Limita el tamaño del contexto cuando sea posible
+- Cachea respuestas usadas con frecuencia
+
+## Próximos pasos
+
+- [Configurar Cursor](cursor.md) para integración mejorada con IDE
+- [Configurar Roo](roo.md) para asistente de IA
+- [Explorar uso de CLI](../cli/basic-usage.md)
+- [Aprende sobre la selección de modelos](../models/overview.md)
diff --git a/gitbook/content/es/integration/cursor.md b/gitbook/content/es/integration/cursor.md
new file mode 100644
index 0000000..6fa60f3
--- /dev/null
+++ b/gitbook/content/es/integration/cursor.md
@@ -0,0 +1,149 @@
+# Integración con Cursor
+
+Integra 9Router con Cursor IDE para enrutar tus solicitudes de IA a través del sistema de enrutamiento inteligente de 9Router.
+
+## Requisitos previos
+
+- Cursor IDE instalado
+- Cuenta Cursor Pro (requerida para endpoints de API personalizados)
+- Endpoint en la nube de 9Router configurado
+- API key del dashboard de 9Router
+
+## ⚠️ Notas importantes
+
+> **Endpoint en la nube requerido**: Cursor enruta solicitudes a través de su propio servidor y no soporta endpoints localhost. Debes usar el endpoint en la nube de 9Router: `https://9router.com`
+
+> **Cursor Pro requerido**: Esta característica requiere una cuenta Cursor Pro para usar endpoints de API personalizados.
+
+## Configuración
+
+### 1. Abrir la configuración de Cursor
+
+1. Abre Cursor IDE
+2. Ve a **Settings** (Cmd/Ctrl + ,)
+3. Navega a la sección **Models**
+
+### 2. Habilitar OpenAI API
+
+1. Encuentra la opción **OpenAI API key**
+2. Activa el toggle para habilitar la configuración de API personalizada
+
+### 3. Configurar Base URL
+
+Establece la URL base al endpoint en la nube de 9Router:
+
+```
+https://9router.com
+```
+
+**Pasos:**
+1. En la configuración de Models, localiza el campo **Base URL**
+2. Ingresa: `https://9router.com`
+3. Clic en **Save**
+
+### 4. Agregar API Key
+
+1. En el campo **API Key**, ingresa tu API key de 9Router
+2. Puedes encontrar tu API key en el dashboard de 9Router en **Settings → API Keys**
+3. Clic en **Save**
+
+### 5. Agregar modelo personalizado
+
+1. Clic en el botón **View All Models**
+2. Clic en **Add Custom Model**
+3. Ingresa el nombre del modelo desde tu configuración de 9Router (ej. `gpt-4`, `claude-opus-4-5`, etc.)
+4. Clic en **Add**
+
+### 6. Seleccionar modelo
+
+1. En la interfaz de chat de Cursor, clic en el dropdown selector de modelo
+2. Elige tu modelo personalizado de la lista
+3. ¡Empieza a usar 9Router con Cursor!
+
+## Ejemplo de configuración
+
+Tu configuración de Cursor debería verse así:
+
+```
+OpenAI API: ✓ Enabled
+Base URL: https://9router.com
+API Key: sk-9router-xxxxxxxxxxxxx
+Custom Models: gpt-4, claude-opus-4-5, gemini-2.0-flash
+```
+
+## Modelos disponibles
+
+Puedes usar cualquier modelo configurado en tu dashboard de 9Router. Ejemplos comunes:
+
+| Nombre del modelo | Proveedor | Descripción |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## Uso
+
+### Interfaz de chat
+
+1. Abre el chat de Cursor (Cmd/Ctrl + L)
+2. Selecciona tu modelo del dropdown
+3. Comienza a chatear con IA a través de 9Router
+
+### Generación de código inline
+
+1. Selecciona código en tu editor
+2. Presiona Cmd/Ctrl + K
+3. Ingresa tu prompt
+4. Cursor usará 9Router para generar código
+
+### Explicación de código
+
+1. Selecciona código en tu editor
+2. Presiona Cmd/Ctrl + L
+3. Pregunta "Explain this code"
+4. Obtén explicaciones potenciadas por IA a través de 9Router
+
+## Solución de problemas
+
+### Error "Invalid API Key"
+
+1. Verifica tu API key en el dashboard de 9Router
+2. Asegúrate de haber copiado la key completa incluyendo el prefijo `sk-9router-`
+3. Verifica que la API key no haya expirado
+4. Intenta regenerar una nueva API key
+
+### Error "Model Not Found"
+
+1. Verifica que el nombre del modelo coincida exactamente con tu configuración de 9Router
+2. Verifica que la conexión del proveedor esté activa en el dashboard de 9Router
+3. Asegúrate de que el modelo esté disponible en tus proveedores conectados
+4. Intenta usar el nombre completo del modelo (ej. `openai/gpt-4` en lugar de `gpt-4`)
+
+### Problemas de conexión
+
+1. Verifica que estés usando el endpoint en la nube: `https://9router.com`
+2. Verifica tu conexión a internet
+3. Asegúrate de que el servicio en la nube de 9Router esté operativo
+4. Intenta deshabilitar VPN o proxy si está habilitado
+
+### Localhost no funciona
+
+> **Recuerda**: Cursor no soporta endpoints localhost. Debes usar el endpoint en la nube `https://9router.com`. Si necesitas usar una instancia local de 9Router, considera usar un servicio de tunneling como ngrok para exponer tu endpoint local.
+
+## Configuración del endpoint en la nube
+
+Si estás ejecutando 9Router localmente y quieres usarlo con Cursor:
+
+1. Habilita el endpoint en la nube en la configuración de 9Router
+2. Configura tu URL del endpoint en la nube en el dashboard de 9Router
+3. Usa la URL en la nube en la configuración de Cursor
+4. Asegúrate de que tu instancia local de 9Router sea accesible desde internet
+
+## Mejores prácticas
+
+1. **Usa aliases de modelos**: Crea aliases cortos para modelos usados con frecuencia en 9Router
+2. **Monitorea el uso**: Revisa el dashboard de 9Router para estadísticas de uso y costos
+3. **Rota las API Keys**: Rota tus API keys regularmente por seguridad
+4. **Prueba modelos**: Prueba diferentes modelos para encontrar el mejor para tu caso de uso
diff --git a/gitbook/content/es/integration/other-tools.md b/gitbook/content/es/integration/other-tools.md
new file mode 100644
index 0000000..62816f8
--- /dev/null
+++ b/gitbook/content/es/integration/other-tools.md
@@ -0,0 +1,416 @@
+# Integración con otras herramientas
+
+9Router es compatible con cualquier herramienta que soporte el formato de API de OpenAI. Esta guía cubre patrones de integración genéricos para varias herramientas y aplicaciones personalizadas.
+
+## Resumen
+
+9Router proporciona un endpoint de API compatible con OpenAI que funciona con:
+- Scripts y aplicaciones personalizadas
+- Clientes de API y herramientas de testing
+- Herramientas CLI y utilidades
+- Integraciones de terceros
+- Frameworks de desarrollo
+
+## Patrón de configuración genérico
+
+Cualquier herramienta compatible con OpenAI puede conectarse a 9Router usando estas configuraciones:
+
+**9Router local:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+Model: cualquier modelo de 9Router (cc/*, cx/*, glm/*, etc.)
+```
+
+**9Router en la nube:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+Model: cualquier modelo de 9Router (cc/*, cx/*, glm/*, etc.)
+```
+
+## Modelos disponibles
+
+### Modelos Claude (Anthropic)
+- `cc/claude-opus-4-5-20251101`
+- `cc/claude-sonnet-4-20250514`
+- `cc/claude-haiku-4-20250514`
+
+### Modelos DeepSeek
+- `cx/deepseek-chat`
+- `cx/deepseek-reasoner`
+
+### Modelos GLM (Zhipu AI)
+- `glm/glm-4-plus`
+- `glm/glm-4-flash`
+
+## Ejemplos de integración
+
+### Python con OpenAI SDK
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+response = client.chat.completions.create(
+    model="cc/claude-sonnet-4-20250514",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ]
+)
+
+print(response.choices[0].message.content)
+```
+
+### Node.js con OpenAI SDK
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+const response = await client.chat.completions.create({
+  model: "cc/claude-sonnet-4-20250514",
+  messages: [
+    { role: "user", content: "Hello, how are you?" }
+  ]
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### Comando cURL
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-api-key-from-dashboard" \
+  -d '{
+    "model": "cc/claude-sonnet-4-20250514",
+    "messages": [
+      {"role": "user", "content": "Hello, how are you?"}
+    ]
+  }'
+```
+
+### Cliente HTTP (Postman, Insomnia)
+
+**Solicitud:**
+```
+POST http://localhost:20128/v1/chat/completions
+```
+
+**Headers:**
+```
+Content-Type: application/json
+Authorization: Bearer your-api-key-from-dashboard
+```
+
+**Body:**
+```json
+{
+  "model": "cc/claude-sonnet-4-20250514",
+  "messages": [
+    {"role": "user", "content": "Hello, how are you?"}
+  ],
+  "temperature": 0.7,
+  "max_tokens": 1000
+}
+```
+
+### Integración con LangChain
+
+```python
+from langchain.chat_models import ChatOpenAI
+from langchain.schema import HumanMessage
+
+llm = ChatOpenAI(
+    model_name="cc/claude-sonnet-4-20250514",
+    openai_api_key="your-api-key-from-dashboard",
+    openai_api_base="http://localhost:20128/v1",
+    temperature=0.7
+)
+
+messages = [HumanMessage(content="Explain quantum computing")]
+response = llm(messages)
+print(response.content)
+```
+
+### Integración con LlamaIndex
+
+```python
+from llama_index.llms import OpenAI
+
+llm = OpenAI(
+    model="cc/claude-sonnet-4-20250514",
+    api_key="your-api-key-from-dashboard",
+    api_base="http://localhost:20128/v1"
+)
+
+response = llm.complete("What is machine learning?")
+print(response.text)
+```
+
+## Ejemplos de scripts personalizados
+
+### Script de procesamiento por lotes
+
+```python
+import openai
+import json
+
+openai.api_key = "your-api-key-from-dashboard"
+openai.api_base = "http://localhost:20128/v1"
+
+def process_batch(prompts, model="cx/deepseek-chat"):
+    results = []
+    for prompt in prompts:
+        response = openai.ChatCompletion.create(
+            model=model,
+            messages=[{"role": "user", "content": prompt}]
+        )
+        results.append({
+            "prompt": prompt,
+            "response": response.choices[0].message.content
+        })
+    return results
+
+prompts = [
+    "Explain AI in one sentence",
+    "What is machine learning?",
+    "Define neural networks"
+]
+
+results = process_batch(prompts)
+print(json.dumps(results, indent=2))
+```
+
+### Manejador de respuestas streaming
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+async function streamResponse(prompt) {
+  const stream = await client.chat.completions.create({
+    model: "cc/claude-sonnet-4-20250514",
+    messages: [{ role: "user", content: prompt }],
+    stream: true
+  });
+
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content || "";
+    process.stdout.write(content);
+  }
+}
+
+streamResponse("Write a short story about AI");
+```
+
+### Comparación multi-modelo
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+models = [
+    "cc/claude-sonnet-4-20250514",
+    "cx/deepseek-chat",
+    "glm/glm-4-plus"
+]
+
+prompt = "Explain quantum computing in simple terms"
+
+for model in models:
+    response = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "user", "content": prompt}]
+    )
+    print(f"\n=== {model} ===")
+    print(response.choices[0].message.content)
+```
+
+## Patrones comunes de integración
+
+### Variables de entorno
+
+Almacena credenciales de forma segura:
+
+```bash
+# .env file
+ROUTER_API_KEY=your-api-key-from-dashboard
+ROUTER_BASE_URL=http://localhost:20128/v1
+ROUTER_MODEL=cc/claude-sonnet-4-20250514
+```
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.getenv("ROUTER_API_KEY"),
+    base_url=os.getenv("ROUTER_BASE_URL")
+)
+```
+
+### Manejo de errores
+
+```python
+from openai import OpenAI, OpenAIError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+try:
+    response = client.chat.completions.create(
+        model="cc/claude-sonnet-4-20250514",
+        messages=[{"role": "user", "content": "Hello"}]
+    )
+    print(response.choices[0].message.content)
+except OpenAIError as e:
+    print(f"Error: {e}")
+```
+
+### Lógica de reintentos
+
+```python
+import time
+from openai import OpenAI, RateLimitError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+def chat_with_retry(prompt, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            response = client.chat.completions.create(
+                model="cc/claude-sonnet-4-20250514",
+                messages=[{"role": "user", "content": prompt}]
+            )
+            return response.choices[0].message.content
+        except RateLimitError:
+            if attempt < max_retries - 1:
+                time.sleep(2 ** attempt)  # Exponential backoff
+            else:
+                raise
+```
+
+## Solución de problemas
+
+### Problemas de conexión
+
+**Problema:** No se puede conectar a 9Router
+```bash
+# Verifica si 9Router está corriendo
+curl http://localhost:20128/health
+
+# Respuesta esperada:
+{"status": "ok"}
+```
+
+**Solución:**
+- Verifica que 9Router esté corriendo
+- Verifica que el puerto 20128 no esté bloqueado
+- Asegúrate de tener la URL base correcta (incluir `/v1`)
+
+### Errores de autenticación
+
+**Problema:** 401 Unauthorized
+```
+Error: Invalid API key
+```
+
+**Solución:**
+- Verifica la API key desde el dashboard
+- Verifica el formato del header de Authorization: `Bearer your-api-key`
+- Asegúrate de no tener espacios extras o saltos de línea en la API key
+
+### Modelo no encontrado
+
+**Problema:** 404 Model not found
+```
+Error: Model 'cc/claude-opus' not found
+```
+
+**Solución:**
+- Usa el nombre exacto del modelo (sensible a mayúsculas)
+- Verifica los modelos disponibles: `curl http://localhost:20128/v1/models`
+- Verifica que el modelo esté habilitado en tu plan
+
+### Problemas de timeout
+
+**Problema:** Request timeout
+```
+Error: Request timed out after 30s
+```
+
+**Solución:**
+- Aumenta el timeout en la configuración del cliente
+- Usa modelos más rápidos para tareas sensibles al tiempo
+- Verifica la conexión de red a 9Router
+
+### Rate limiting
+
+**Problema:** 429 Too Many Requests
+```
+Error: Rate limit exceeded
+```
+
+**Solución:**
+- Implementa exponential backoff
+- Reduce la frecuencia de solicitudes
+- Verifica los límites de tasa en el dashboard
+- Considera actualizar tu plan
+
+## Mejores prácticas
+
+### Seguridad
+- Almacena las API keys en variables de entorno
+- Nunca subas las API keys al control de versiones
+- Usa HTTPS para despliegues en la nube
+- Rota las API keys regularmente
+
+### Rendimiento
+- Usa modelos apropiados para la complejidad de la tarea
+- Implementa caché para consultas repetidas
+- Usa streaming para respuestas largas
+- Agrupa solicitudes cuando sea posible
+
+### Manejo de errores
+- Siempre implementa bloques try-catch
+- Agrega lógica de reintento con exponential backoff
+- Registra errores para debugging
+- Proporciona mecanismos de fallback
+
+### Optimización de costos
+- Elige modelos costo-efectivos para tareas simples
+- Cachea respuestas cuando sea apropiado
+- Monitorea el uso en el dashboard
+- Establece límites de solicitudes en el código
+
+## Próximos pasos
+
+- [Configurar Cursor](cursor.md) para integración con IDE
+- [Configurar Continue](continue.md) para VSCode
+- [Explorar uso de CLI](../cli/basic-usage.md)
+- [Aprende sobre la selección de modelos](../models/overview.md)
+- [Referencia de API](../api/reference.md)
diff --git a/gitbook/content/es/integration/roo.md b/gitbook/content/es/integration/roo.md
new file mode 100644
index 0000000..b4f4c67
--- /dev/null
+++ b/gitbook/content/es/integration/roo.md
@@ -0,0 +1,127 @@
+# Integración con Roo AI Assistant
+
+Integra 9Router con Roo AI Assistant para acceder a múltiples modelos de IA a través de una interfaz unificada.
+
+## Requisitos previos
+
+- Roo AI Assistant instalado
+- API key de 9Router desde el [dashboard](https://9router.com/dashboard)
+- 9Router ejecutándose (local o en la nube)
+
+## Pasos de configuración
+
+### 1. Abrir la configuración de Roo
+
+Inicia Roo AI Assistant y abre el panel de configuración.
+
+### 2. Configurar el proveedor de API
+
+1. Navega a la configuración de **API Provider**
+2. Selecciona **Ollama** como tipo de proveedor
+3. Configura los siguientes ajustes:
+
+**Para 9Router local:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+```
+
+**Para 9Router en la nube:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+```
+
+### 3. Seleccionar modelo
+
+Elige entre los modelos disponibles de 9Router:
+
+**Modelos Claude:**
+- `cc/claude-opus-4-5-20251101` - El más capaz
+- `cc/claude-sonnet-4-20250514` - Equilibrado
+- `cc/claude-haiku-4-20250514` - Rápido
+
+**Modelos DeepSeek:**
+- `cx/deepseek-chat` - Propósito general
+- `cx/deepseek-reasoner` - Razonamiento complejo
+
+**Modelos GLM:**
+- `glm/glm-4-plus` - Avanzado
+- `glm/glm-4-flash` - Respuestas rápidas
+
+### 4. Probar la conexión
+
+Envía un mensaje de prueba para verificar la integración:
+
+```
+Hello! Can you confirm you're connected through 9Router?
+```
+
+## Ejemplos de uso
+
+### Chat básico
+```
+Pregunta a Roo: "Explain quantum computing in simple terms"
+Modelo: cc/claude-sonnet-4-20250514
+```
+
+### Generación de código
+```
+Pregunta a Roo: "Write a Python function to calculate Fibonacci numbers"
+Modelo: cx/deepseek-chat
+```
+
+### Razonamiento complejo
+```
+Pregunta a Roo: "Analyze the trade-offs between microservices and monolithic architecture"
+Modelo: cx/deepseek-reasoner
+```
+
+## Consejos de selección de modelo
+
+- **Tareas rápidas**: Usa `cc/claude-haiku-4-20250514` o `glm/glm-4-flash`
+- **Rendimiento equilibrado**: Usa `cc/claude-sonnet-4-20250514` o `cx/deepseek-chat`
+- **Razonamiento complejo**: Usa `cc/claude-opus-4-5-20251101` o `cx/deepseek-reasoner`
+- **Optimización de costos**: Usa modelos DeepSeek o GLM
+
+## Solución de problemas
+
+### Connection Failed
+- Verifica que 9Router esté corriendo: `curl http://localhost:20128/health`
+- Verifica que la API key sea correcta
+- Asegúrate de que la Base URL incluya el sufijo `/v1`
+
+### Modelo no disponible
+- Verifica que el nombre del modelo coincida exactamente (sensible a mayúsculas)
+- Verifica que el modelo esté habilitado en tu plan de 9Router
+- Intenta otro modelo de la lista
+
+### Respuestas lentas
+- Cambia a modelos más rápidos (haiku, flash)
+- Verifica la conexión de red
+- Monitorea los logs de 9Router por problemas
+
+## Configuración avanzada
+
+### Aliases personalizados de modelos
+
+Puedes crear atajos para modelos usados con frecuencia en la configuración de Roo:
+
+```
+Alias: "fast" → cc/claude-haiku-4-20250514
+Alias: "smart" → cc/claude-opus-4-5-20251101
+Alias: "code" → cx/deepseek-chat
+```
+
+### Múltiples perfiles
+
+Configura diferentes perfiles para distintos casos de uso:
+- **Desarrollo**: Modelos DeepSeek para código
+- **Escritura**: Modelos Claude para contenido
+- **Investigación**: Modelos reasoner para análisis
+
+## Próximos pasos
+
+- [Configurar Cursor](cursor.md) para integración con IDE
+- [Configurar Continue](continue.md) para VSCode
+- [Explorar uso de CLI](../cli/basic-usage.md)
diff --git a/gitbook/content/es/providers/cheap.md b/gitbook/content/es/providers/cheap.md
new file mode 100644
index 0000000..757199a
--- /dev/null
+++ b/gitbook/content/es/providers/cheap.md
@@ -0,0 +1,462 @@
+# Proveedores baratos - Respaldo ultra-barato
+
+Cuando se agota la cuota de suscripción, paga centavos en lugar de dólares. ¡~90% más barato que ChatGPT API!
+
+---
+
+## Resumen
+
+Los proveedores del nivel barato son tu **respaldo** cuando se agota la cuota de suscripción:
+
+- 💰 **GLM-4.7** - $0.6/$2.2 por 1M tokens (reinicio diario)
+- 💰 **MiniMax M2.1** - $0.2/$1.0 por 1M tokens (reinicio 5h)
+- 💰 **Kimi K2** - $9/mes plano (10M tokens)
+
+**Estrategia:** Úsalos después de agotar la cuota de suscripción, antes del nivel gratis. Ahorros masivos vs ChatGPT API ($20/1M).
+
+---
+
+## GLM-4.7 (Reinicio diario)
+
+### Precios
+
+| Nivel | Entrada | Salida | Reinicio |
+|------|-------|--------|-------|
+| Standard | $0.60/1M | $2.20/1M | Diario 10:00 AM |
+| Coding Plan | $0.60/1M | $2.20/1M | Diario 10:00 AM (3× cuota) |
+
+**Ejemplo de costo (10M tokens):**
+- Entrada: 10M × $0.60 = $6
+- Salida: 10M × $2.20 = $22
+- **Total: $6-22** ¡vs $200 en ChatGPT API!
+
+### Configuración
+
+**Paso 1: Registrarse**
+
+1. Visita [Zhipu AI](https://open.bigmodel.cn/)
+2. Crea cuenta (verificación por teléfono)
+3. Elige **Coding Plan** para 3× cuota al mismo precio
+
+**Paso 2: Obtener API Key**
+
+```bash
+Dashboard → API Keys → Create New
+→ Copia la API key (comienza con "zhipu-")
+```
+
+**Paso 3: Agregar a 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: glm
+API Key: zhipu-your-api-key-here
+```
+
+**Paso 4: Usar en CLI**
+
+```
+Model: glm/glm-4.7
+       glm/glm-4.6v (vision)
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Contexto | Ideal para |
+|----------|-------------|---------|----------|
+| `glm/glm-4.7` | GLM 4.7 | 128K | Codificación, tareas generales |
+| `glm/glm-4.6v` | GLM 4.6V Vision | 128K | Análisis de imágenes |
+
+### Pro Tips
+
+- **Coding Plan** - 3× cuota al mismo precio ($0.6/$2.2)
+- **Reinicio diario** - Cuota fresca a las 10:00 AM hora de Beijing
+- **Ideal para codificación** - Optimizado para generación de código
+- **128K de contexto** - Maneja archivos grandes
+
+### Reinicio de cuota
+
+```
+Reinicio diario: 10:00 AM hora Beijing (UTC+8)
+→ 2:00 AM UTC
+→ 6:00 PM PST (día anterior)
+→ 9:00 PM EST (día anterior)
+
+¡Planifica tus tareas pesadas según el tiempo de reinicio!
+```
+
+---
+
+## MiniMax M2.1 (Reinicio 5 horas)
+
+### Precios
+
+| Nivel | Entrada | Salida | Reinicio |
+|------|-------|--------|-------|
+| Standard | $0.20/1M | $1.00/1M | Rolling 5 horas |
+
+**Ejemplo de costo (10M tokens):**
+- Entrada: 10M × $0.20 = $2
+- Salida: 10M × $1.00 = $10
+- **Total: $2-10** - ¡La opción más barata!
+
+### Configuración
+
+**Paso 1: Registrarse**
+
+1. Visita [MiniMax](https://www.minimax.io/)
+2. Crea cuenta
+3. Verifica email/teléfono
+
+**Paso 2: Obtener API Key**
+
+```bash
+Dashboard → API Management → Create Key
+→ Copia la API key
+```
+
+**Paso 3: Agregar a 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: minimax
+API Key: your-minimax-api-key
+```
+
+**Paso 4: Usar en CLI**
+
+```
+Model: minimax/MiniMax-M2.1
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Contexto | Ideal para |
+|----------|-------------|---------|----------|
+| `minimax/MiniMax-M2.1` | MiniMax M2.1 | 1M tokens | Contexto largo, codificación |
+
+### Pro Tips
+
+- **La opción más barata** - $0.20/1M entrada (90% más barato que ChatGPT)
+- **Rolling 5 horas** - La cuota se reinicia cada 5 horas
+- **Contexto de 1M** - Ventana de contexto masiva
+- **Ideal para archivos largos** - Maneja codebases enteras
+
+### Reinicio de cuota
+
+```
+Ventana rolling de 5 horas:
+→ Usar cuota → Esperar 5 horas → Cuota fresca
+
+Ejemplo:
+10:00 AM - Usar 5M tokens
+3:00 PM - Cuota fresca disponible
+8:00 PM - Cuota fresca disponible
+
+¡Codifica 24/7 con costo mínimo!
+```
+
+---
+
+## Kimi K2 ($9/mes plano)
+
+### Precios
+
+| Plan | Costo mensual | Tokens incluidos | Costo efectivo |
+|------|--------------|-----------------|----------------|
+| Subscription | $9 | 10M tokens | $0.90/1M |
+
+**Ejemplo de costo:**
+- $9/mes plano
+- 10M tokens incluidos
+- **Efectivo: $0.90/1M** - ¡Mejor valor para uso constante!
+
+### Configuración
+
+**Paso 1: Suscribirse**
+
+1. Visita [Moonshot AI](https://platform.moonshot.ai/)
+2. Crea cuenta
+3. Suscríbete al plan $9/mes
+
+**Paso 2: Obtener API Key**
+
+```bash
+Dashboard → API Keys → Create New
+→ Copia la API key
+```
+
+**Paso 3: Agregar a 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: kimi
+API Key: your-kimi-api-key
+```
+
+**Paso 4: Usar en CLI**
+
+```
+Model: kimi/kimi-latest
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Contexto | Ideal para |
+|----------|-------------|---------|----------|
+| `kimi/kimi-latest` | Kimi Latest | 200K | Codificación general |
+
+### Pro Tips
+
+- **Costo fijo** - $9/mes sin importar el uso (hasta 10M)
+- **Ideal para uso constante** - Si usas 10M/mes, solo $0.90/1M
+- **Reinicio mensual** - 10M tokens se reinician mensualmente
+- **Facturación predecible** - Sin costos sorpresa
+
+### Reinicio de cuota
+
+```
+Reinicio mensual: 1ro de cada mes
+→ 10M tokens se refrescan
+
+Ejemplo de uso mensual:
+Semana 1: 3M tokens
+Semana 2: 2M tokens
+Semana 3: 3M tokens
+Semana 4: 2M tokens
+Total: 10M tokens = $9 plano
+```
+
+---
+
+## Comparación de precios
+
+| Proveedor | Entrada/1M | Salida/1M | Reinicio | Costo 10M | Ideal para |
+|----------|----------|-----------|-------|----------|----------|
+| **GLM-4.7** | $0.60 | $2.20 | Diario 10AM | $6-22 | Usuarios con cuota diaria |
+| **MiniMax M2.1** | $0.20 | $1.00 | 5 horas | $2-10 | **¡La más barata!** |
+| **Kimi K2** | $0.90 | $0.90 | Mensual | **$9 plano** | Uso constante |
+| ChatGPT API | $20.00 | $20.00 | Ninguno | $200 | ❌ Costoso |
+
+**Ahorros:** ¡90-95% más barato que ChatGPT API!
+
+---
+
+## Ejemplo de uso
+
+### Configuración en Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [desde el dashboard de 9router]
+  Model: glm/glm-4.7
+```
+
+### Crear combo (Recomendado)
+
+```
+Dashboard → Combos → Create New
+
+Name: cheap-backup
+Models:
+  1. cc/claude-opus-4-5 (Suscripción principal)
+  2. glm/glm-4.7 (Respaldo barato, reinicio diario)
+  3. minimax/MiniMax-M2.1 (Fallback más barato)
+  4. if/kimi-k2-thinking (Emergencia GRATIS)
+
+Usar en CLI: cheap-backup
+```
+
+**Resultado:** Suscripción → Barato → Más barato → Gratis
+
+---
+
+## Optimización de costos
+
+### Estrategia 1: Rutina de reinicio diario
+
+```
+Mañana (10AM): Cuota fresca de GLM
+→ Usa GLM para tareas pesadas
+→ Ahorra cuota de suscripción
+
+Tarde: Cuota de suscripción
+→ Usa Claude/Codex para tareas complejas
+
+Noche: MiniMax (reinicio 5h)
+→ Respaldo barato para trabajo nocturno
+
+Madrugada: Nivel gratis (iFlow)
+→ Respaldo de emergencia cero costo
+```
+
+### Estrategia 2: Presupuesto primero
+
+```
+Establece presupuesto mensual: $20
+
+Asignación:
+- $9 Kimi K2 (10M tokens plano)
+- $6 cuota diaria de GLM (10M tokens)
+- $5 overflow de MiniMax (25M tokens)
+
+Total: 45M tokens por $20
+¡vs 1M tokens por $20 en ChatGPT API!
+```
+
+### Estrategia 3: Maximiza suscripciones primero
+
+```
+Prioridad:
+1. Gemini CLI (180K/mes GRATIS)
+2. Claude Code (suscripción que ya pagas)
+3. GLM-4.7 (respaldo barato, $0.6/1M)
+4. MiniMax M2.1 (más barato, $0.2/1M)
+5. iFlow (emergencia GRATIS)
+
+Ejemplo de costo mensual (100M tokens):
+- 60M vía Gemini CLI: $0 (gratis)
+- 30M vía Claude Code: $0 (suscripción)
+- 8M vía GLM: $4.80
+- 2M vía MiniMax: $0.40
+¡Total: $5.20/mes!
+```
+
+---
+
+## Ejemplos reales
+
+### Ejemplo 1: Mes de codificación intensa (100M tokens)
+
+```
+Desglose:
+- 60M vía suscripción (Claude/Codex): $0 extra
+- 30M vía GLM-4.7: $18
+- 10M vía MiniMax M2.1: $2
+
+Total: $20/mes
+¡vs $2000 en ChatGPT API!
+
+Ahorros: ¡99% más barato!
+```
+
+### Ejemplo 2: Codificador con presupuesto ($10/mes)
+
+```
+Estrategia:
+- $9 Kimi K2 (10M tokens)
+- $1 overflow de MiniMax (5M tokens)
+
+Total: 15M tokens por $10
+¡vs 0.5M tokens por $10 en ChatGPT API!
+
+¡30× más tokens!
+```
+
+### Ejemplo 3: Freelancer (Uso variable)
+
+```
+Mes ligero (20M tokens):
+- 15M vía suscripción: $0
+- 5M vía GLM: $3
+Total: $3
+
+Mes intenso (150M tokens):
+- 60M vía suscripción: $0
+- 60M vía GLM: $36
+- 30M vía MiniMax: $6
+Total: $42
+
+Promedio: $22.50/mes
+¡vs $3400 en ChatGPT API!
+```
+
+---
+
+## Mejores prácticas
+
+### 1. Rastrea la cuota diaria
+
+```
+El dashboard muestra:
+- Cuota GLM: 75% usado (reinicio en 6h)
+- Cuota MiniMax: 50% usado (reinicio en 2h)
+- Cuota Kimi: 8M/10M usado (reinicio en 15 días)
+
+¡Planifica tareas pesadas según los tiempos de reinicio!
+```
+
+### 2. Usa el Coding Plan (GLM)
+
+```
+Standard: 1× cuota
+Coding Plan: 3× cuota (¡mismo precio!)
+
+→ Siempre elige Coding Plan
+```
+
+### 3. Combina con el nivel gratis
+
+```
+Combo:
+1. gc/gemini-3-flash (GRATIS principal)
+2. glm/glm-4.7 (respaldo barato)
+3. minimax/MiniMax-M2.1 (más barato)
+4. if/kimi-k2-thinking (emergencia GRATIS)
+
+Resultado: Minimiza costos, maximiza uptime
+```
+
+### 4. Establece alertas de presupuesto
+
+```
+Dashboard → Settings → Budget Alerts
+
+Diario: $2 límite
+Semanal: $10 límite
+Mensual: $30 límite
+
+→ Cambio automático al nivel gratis cuando se alcanza el límite
+```
+
+---
+
+## Solución de problemas
+
+### "Cuota agotada"
+
+**Solución:**
+- GLM: Espera hasta las 10:00 AM hora Beijing
+- MiniMax: Espera 5 horas desde el primer uso
+- Kimi: Espera hasta el 1ro del próximo mes
+- Usa fallback de combo al nivel gratis
+
+### "API key inválida"
+
+**Solución:**
+- Verifica que la API key esté copiada correctamente
+- Verifica que la cuenta tenga créditos
+- Regenera la API key si es necesario
+
+### "Costos altos"
+
+**Solución:**
+- Revisa las estadísticas de uso en el dashboard
+- Establece alertas de presupuesto
+- Cambia a MiniMax ($0.2/1M, la más barata)
+- Usa el nivel gratis para tareas no críticas
+
+---
+
+## Próximos pasos
+
+- **Agregar fallback gratis:** [Proveedores gratis](./free.md)
+- **Configurar suscripciones:** [Proveedores de suscripción](./subscription.md)
+- **Crear combos:** Dashboard → Combos → Create New
diff --git a/gitbook/content/es/providers/free.md b/gitbook/content/es/providers/free.md
new file mode 100644
index 0000000..937f8a2
--- /dev/null
+++ b/gitbook/content/es/providers/free.md
@@ -0,0 +1,442 @@
+# Proveedores gratis - Fallback de cero costo
+
+Respaldo de emergencia cuando todo lo demás está limitado por cuota. ¡Codifica 24/7 con cero costo!
+
+---
+
+## Resumen
+
+Los proveedores del nivel gratis son tu **fallback** cuando se agota la cuota de suscripción y la del nivel barato:
+
+- 🆓 **iFlow** - 8 modelos GRATIS (Kimi K2, Qwen3, GLM 4.7, MiniMax M2...)
+- 🆓 **Qwen** - 3 modelos GRATIS (Qwen3 Coder Plus/Flash, Vision)
+- 🆓 **Kiro** - 2 modelos GRATIS (Claude Sonnet 4.5, Haiku 4.5)
+
+**Estrategia:** Úsalos como respaldo de emergencia. ¡Uso ilimitado, cero costo para siempre!
+
+---
+
+## iFlow (8 modelos GRATIS)
+
+### Precios
+
+| Plan | Costo mensual | Modelos | Cuota |
+|------|--------------|--------|-------|
+| FREE | $0 | 8 modelos | Ilimitado |
+
+**Mejor valor:** ¡La mayoría de modelos en el nivel gratis! Kimi K2, Qwen3, GLM, MiniMax, DeepSeek.
+
+### Configuración
+
+**Paso 1: Conectar vía Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect iFlow
+```
+
+**Paso 2: Login OAuth de iFlow**
+
+- Clic en "Connect iFlow"
+- El navegador abre → página de login de iFlow
+- Crea cuenta o inicia sesión
+- Otorga permisos
+- Auto-refresh de token habilitado
+
+**Paso 3: Usar en CLI**
+
+```
+Model: if/kimi-k2-thinking
+       if/kimi-k2
+       if/qwen3-coder-plus
+       if/glm-4.7
+       if/minimax-m2
+       if/deepseek-r1
+       if/deepseek-v3.2-chat
+       if/deepseek-v3.2-reasoner
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Ideal para |
+|----------|-------------|----------|
+| `if/kimi-k2-thinking` | Kimi K2 Thinking | Razonamiento complejo |
+| `if/kimi-k2` | Kimi K2 | Codificación general |
+| `if/qwen3-coder-plus` | Qwen3 Coder Plus | Generación de código |
+| `if/glm-4.7` | GLM 4.7 | Chino + inglés |
+| `if/minimax-m2` | MiniMax M2 | Contexto largo |
+| `if/deepseek-r1` | DeepSeek R1 | Tareas de razonamiento |
+| `if/deepseek-v3.2-chat` | DeepSeek V3.2 Chat | Conversacional |
+| `if/deepseek-v3.2-reasoner` | DeepSeek V3.2 Reasoner | Lógica compleja |
+
+### Pro Tips
+
+- **8 modelos GRATIS** - La mayor variedad en el nivel gratis
+- **Uso ilimitado** - Sin límites de cuota
+- **Kimi K2 Thinking** - Ideal para razonamiento complejo
+- **DeepSeek R1** - Fuertes capacidades de razonamiento
+
+---
+
+## Qwen (3 modelos GRATIS)
+
+### Precios
+
+| Plan | Costo mensual | Modelos | Cuota |
+|------|--------------|--------|-------|
+| FREE | $0 | 3 modelos | Ilimitado |
+
+### Configuración
+
+**Paso 1: Conectar vía Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Qwen
+```
+
+**Paso 2: Autorización por código de dispositivo**
+
+- Clic en "Connect Qwen"
+- El dashboard muestra el código de dispositivo
+- Visita la URL de autorización
+- Ingresa el código de dispositivo
+- Inicia sesión en la cuenta de Qwen
+- Auto-refresh de token habilitado
+
+**Paso 3: Usar en CLI**
+
+```
+Model: qw/qwen3-coder-plus
+       qw/qwen3-coder-flash
+       qw/vision-model
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Ideal para |
+|----------|-------------|----------|
+| `qw/qwen3-coder-plus` | Qwen3 Coder Plus | Codificación avanzada |
+| `qw/qwen3-coder-flash` | Qwen3 Coder Flash | Respuestas rápidas |
+| `qw/vision-model` | Qwen3 Vision | Análisis de imágenes |
+
+### Pro Tips
+
+- **Qwen3 Coder Plus** - Fuertes capacidades de codificación
+- **Qwen3 Coder Flash** - Rápido para tareas rápidas
+- **Modelo de visión** - Análisis de imágenes GRATIS
+- **Uso ilimitado** - Sin límites de cuota
+
+---
+
+## Kiro (Claude GRATIS)
+
+### Precios
+
+| Plan | Costo mensual | Modelos | Cuota |
+|------|--------------|--------|-------|
+| FREE | $0 | Claude Sonnet 4.5, Haiku 4.5 | Ilimitado |
+
+**Mejor valor:** ¡Claude GRATIS! Misma calidad que Claude Code de pago.
+
+### Configuración
+
+**Paso 1: Conectar vía Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Kiro
+```
+
+**Paso 2: AWS Builder ID u OAuth**
+
+- Clic en "Connect Kiro"
+- Elige método de login:
+  - AWS Builder ID (recomendado)
+  - Cuenta Google
+  - Cuenta GitHub
+- Otorga permisos
+- Auto-refresh de token habilitado
+
+**Paso 3: Usar en CLI**
+
+```
+Model: kr/claude-sonnet-4.5
+       kr/claude-haiku-4.5
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Ideal para |
+|----------|-------------|----------|
+| `kr/claude-sonnet-4.5` | Claude Sonnet 4.5 | Calidad/velocidad equilibrada |
+| `kr/claude-haiku-4.5` | Claude Haiku 4.5 | Respuestas rápidas |
+
+### Pro Tips
+
+- **Claude GRATIS** - Misma calidad que el nivel de pago
+- **AWS Builder ID** - Configuración fácil con cuenta AWS
+- **Uso ilimitado** - Sin límites de cuota
+- **Mejor calidad** - ¡Claude 4.5 gratis!
+
+---
+
+## Comparación de características
+
+| Proveedor | Modelos | Mejor modelo | Configuración | Cuota |
+|----------|--------|------------|-------|-------|
+| **iFlow** | 8 | Kimi K2 Thinking | OAuth | Ilimitado |
+| **Qwen** | 3 | Qwen3 Coder Plus | Device Code | Ilimitado |
+| **Kiro** | 2 | Claude Sonnet 4.5 | AWS Builder ID | Ilimitado |
+
+**Ganador:** ¡iFlow por variedad, Kiro por calidad!
+
+---
+
+## Ejemplo de uso
+
+### Configuración en Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [desde el dashboard de 9router]
+  Model: if/kimi-k2-thinking
+```
+
+### Crear combo (Recomendado)
+
+```
+Dashboard → Combos → Create New
+
+Name: free-combo
+Models:
+  1. if/kimi-k2-thinking (iFlow principal)
+  2. qw/qwen3-coder-plus (Qwen respaldo)
+  3. kr/claude-sonnet-4.5 (Kiro calidad)
+
+Usar en CLI: free-combo
+```
+
+**Resultado:** ¡Cero costo, máximo uptime!
+
+---
+
+## Estrategia de fallback completa
+
+### Combo completo de 3 niveles
+
+```
+Dashboard → Combos → Create New
+
+Name: complete-fallback
+Models:
+  1. gc/gemini-3-flash-preview (Suscripción GRATIS)
+  2. cc/claude-opus-4-5 (Suscripción de pago)
+  3. glm/glm-4.7 (Respaldo barato, $0.6/1M)
+  4. minimax/MiniMax-M2.1 (Más barato, $0.2/1M)
+  5. if/kimi-k2-thinking (Fallback GRATIS)
+  6. kr/claude-sonnet-4.5 (Calidad GRATIS)
+
+Usar en CLI: complete-fallback
+```
+
+**Resultado:**
+- Nivel 1: Suscripción GRATIS (Gemini CLI)
+- Nivel 2: Suscripción de pago (Claude Code)
+- Nivel 3: Respaldo barato (GLM, MiniMax)
+- Nivel 4: Fallback GRATIS (iFlow, Kiro)
+
+**¡Nunca dejes de codificar!**
+
+---
+
+## Mejores prácticas
+
+### 1. Úsalos como respaldo de emergencia
+
+```
+Prioridad:
+1. Nivel de suscripción (maximiza cuota de pago)
+2. Nivel barato (centavos por 1M tokens)
+3. Nivel GRATIS (ilimitado, cero costo)
+
+Usa el nivel gratis solo cuando:
+- Cuota de suscripción agotada
+- Límite de presupuesto alcanzado
+- Pruebas/tareas no críticas
+```
+
+### 2. Elige el modelo correcto
+
+```
+Razonamiento complejo: if/kimi-k2-thinking
+Codificación rápida: qw/qwen3-coder-flash
+Mejor calidad: kr/claude-sonnet-4.5
+Contexto largo: if/minimax-m2
+Tareas de visión: qw/vision-model
+```
+
+### 3. Crea un combo solo-gratis
+
+```
+Para codificación de cero costo:
+
+Name: zero-cost
+Models:
+  1. kr/claude-sonnet-4.5 (Mejor calidad)
+  2. if/kimi-k2-thinking (Tareas complejas)
+  3. qw/qwen3-coder-plus (Codificación rápida)
+
+¡Costo: $0 para siempre!
+```
+
+### 4. Prueba antes de producción
+
+```
+Usa el nivel gratis para:
+- Probar prompts
+- Prototipar características
+- Aprender nuevos frameworks
+- Tareas no críticas
+
+Guarda la cuota de pago para:
+- Código de producción
+- Refactoring complejo
+- Características críticas
+```
+
+---
+
+## Ejemplos reales
+
+### Ejemplo 1: Estudiante/Aprendiz (Cero presupuesto)
+
+```
+Configuración:
+1. kr/claude-sonnet-4.5 (Mejor calidad)
+2. if/kimi-k2-thinking (Razonamiento complejo)
+3. qw/qwen3-coder-plus (Codificación rápida)
+
+Costo mensual: $0
+Uso: Ilimitado
+
+Perfecto para:
+- Aprender a programar
+- Proyectos personales
+- Tareas/asignaciones
+```
+
+### Ejemplo 2: Freelancer (Consciente del presupuesto)
+
+```
+Configuración:
+1. gc/gemini-3-flash-preview (GRATIS 180K/mes)
+2. glm/glm-4.7 (Respaldo barato, $0.6/1M)
+3. if/kimi-k2-thinking (Fallback GRATIS)
+
+Costo mensual: $5-10
+Uso: 100M+ tokens
+
+Perfecto para:
+- Proyectos de cliente (nivel de pago)
+- Pruebas (nivel gratis)
+- Respaldo de emergencia
+```
+
+### Ejemplo 3: Usuario intensivo (Maximiza todo)
+
+```
+Configuración:
+1. gc/gemini-3-flash-preview (GRATIS 180K/mes)
+2. cc/claude-opus-4-5 (Suscripción $20-100)
+3. cx/gpt-5.2-codex (Suscripción $20-200)
+4. glm/glm-4.7 (Barato $0.6/1M)
+5. minimax/MiniMax-M2.1 (Más barato $0.2/1M)
+6. if/kimi-k2-thinking (GRATIS ilimitado)
+7. kr/claude-sonnet-4.5 (Calidad GRATIS)
+
+Costo mensual: $40-320 (suscripciones) + $10-20 (nivel barato)
+Uso: 500M+ tokens
+
+Perfecto para:
+- Desarrollo profesional
+- Proyectos de equipo
+- Codificación 24/7
+```
+
+---
+
+## Comparación de costos
+
+### Escenario: 100M tokens/mes
+
+**Opción 1: Solo ChatGPT API**
+```
+100M × $20/1M = $2,000/mes
+```
+
+**Opción 2: Solo nivel gratis de 9Router**
+```
+100M vía nivel gratis = $0/mes
+Ahorros: $2,000/mes (100%)
+```
+
+**Opción 3: Estrategia completa de 9Router**
+```
+60M vía Gemini CLI (GRATIS): $0
+30M vía Claude Code (suscripción): $0 extra
+8M vía GLM (barato): $4.80
+2M vía iFlow (GRATIS): $0
+Total: $4.80/mes + suscripciones que ya tienes
+Ahorros: $1,995/mes (99.76%)
+```
+
+---
+
+## Solución de problemas
+
+### "OAuth failed"
+
+**Solución:**
+- Verifica la conexión a internet
+- Prueba otro navegador
+- Limpia la caché del navegador
+- Reconecta en el dashboard
+
+### "Modelo no disponible"
+
+**Solución:**
+- Verifica que el proveedor esté conectado en el dashboard
+- Verifica que el token OAuth sea válido
+- Reconecta el proveedor si es necesario
+
+### "Respuestas lentas"
+
+**Solución:**
+- El nivel gratis puede tener menor prioridad
+- Úsalo durante horas off-peak
+- Cambia a otro proveedor gratis
+- Mejora al nivel barato para velocidad
+
+---
+
+## Limitaciones
+
+### Consideraciones del nivel gratis
+
+- **Velocidad** - Puede ser más lento que los niveles de pago
+- **Prioridad** - Menor prioridad en horas pico
+- **Rate limits** - Posible rate-limiting (pero cuota ilimitada)
+- **Disponibilidad** - Puede tener tiempo de inactividad ocasional
+
+**Solución:** ¡Usa la estrategia de fallback de 3 niveles para confiabilidad!
+
+---
+
+## Próximos pasos
+
+- **Configurar suscripciones:** [Proveedores de suscripción](./subscription.md)
+- **Agregar respaldo barato:** [Proveedores baratos](./cheap.md)
+- **Crear combos:** Dashboard → Combos → Create New
+- **Empezar a codificar:** Usa el combo `complete-fallback` para máxima confiabilidad
diff --git a/gitbook/content/es/providers/subscription.md b/gitbook/content/es/providers/subscription.md
new file mode 100644
index 0000000..9e83a25
--- /dev/null
+++ b/gitbook/content/es/providers/subscription.md
@@ -0,0 +1,404 @@
+# Proveedores de suscripción - Maximiza tu valor
+
+Maximiza tus suscripciones de IA existentes con seguimiento inteligente de cuota y fallback automático. ¡Usa cada bit de tu suscripción antes de que se reinicie!
+
+---
+
+## Resumen
+
+Los proveedores del nivel de suscripción son tu opción **principal** - ya estás pagando por ellos, así que obtén el valor completo:
+
+- ✅ **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
+- ✅ **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
+- ✅ **Gemini CLI** (¡Nivel GRATIS!) - 180K completados/mes
+- ✅ **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
+- ✅ **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
+
+**Estrategia:** Úsalos primero, rastrea la cuota en tiempo real, fallback al barato/gratis cuando se agote.
+
+---
+
+## Claude Code (Pro/Max)
+
+### Precios
+
+| Plan | Costo mensual | Reinicio de cuota | Modelos |
+|------|--------------|-------------|--------|
+| Pro | $20 | 5 horas + semanal | Opus, Sonnet, Haiku |
+| Max | $100 | 5 horas + semanal | Opus, Sonnet, Haiku |
+
+### Configuración
+
+**Paso 1: Conectar vía Dashboard**
+
+```bash
+9router
+# Se abre el dashboard → Providers → Connect Claude Code
+```
+
+**Paso 2: Login OAuth**
+
+- Clic en "Connect Claude Code"
+- El navegador abre → Inicia sesión en Claude.ai
+- Auto-refresh de token habilitado
+- Comienza el seguimiento de cuota
+
+**Paso 3: Usar en CLI**
+
+```
+Model: cc/claude-opus-4-5-20251101
+       cc/claude-sonnet-4-5-20250929
+       cc/claude-haiku-4-5-20251001
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Ideal para |
+|----------|-------------|----------|
+| `cc/claude-opus-4-5-20251101` | Claude 4.5 Opus | Tareas complejas, arquitectura |
+| `cc/claude-sonnet-4-5-20250929` | Claude 4.5 Sonnet | Velocidad/calidad equilibrada |
+| `cc/claude-haiku-4-5-20251001` | Claude 4.5 Haiku | Respuestas rápidas |
+
+### Pro Tips
+
+- **Usa Opus para tareas complejas** - Decisiones de arquitectura, refactoring
+- **Usa Sonnet por velocidad** - Ediciones rápidas, generación de código
+- **Rastrea cuota por modelo** - El dashboard muestra uso por modelo
+- **Reinicio de 5 horas** - Cuota fresca cada 5 horas + reinicio semanal
+
+---
+
+## OpenAI Codex (Plus/Pro)
+
+### Precios
+
+| Plan | Costo mensual | Reinicio de cuota | Modelos |
+|------|--------------|-------------|--------|
+| Plus | $20 | 5 horas + semanal | GPT 5.2, GPT 5.1 |
+| Pro | $200 | 5 horas + semanal | GPT 5.2 Codex, GPT 5.1 Max |
+
+### Configuración
+
+**Paso 1: Conectar vía Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Codex
+```
+
+**Paso 2: Login OAuth**
+
+- Clic en "Connect Codex"
+- El navegador abre `http://localhost:1455`
+- Inicia sesión en la cuenta de OpenAI
+- Auto-refresh de token habilitado
+
+**Paso 3: Usar en CLI**
+
+```
+Model: cx/gpt-5.2-codex
+       cx/gpt-5.1-codex-max
+       cx/gpt-5.2
+       cx/gpt-5.1-codex
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Ideal para |
+|----------|-------------|----------|
+| `cx/gpt-5.2-codex` | GPT 5.2 Codex | Último modelo de codificación |
+| `cx/gpt-5.1-codex-max` | GPT 5.1 Codex Max | Contexto máximo |
+| `cx/gpt-5.2` | GPT 5.2 | Tareas generales |
+| `cx/gpt-5.1-codex` | GPT 5.1 Codex | Codificación estable |
+
+### Pro Tips
+
+- **Cuota rolling de 5 horas** - Cuota fresca cada 5 horas
+- **Reinicio semanal** - Reinicio completo de cuota cada semana
+- **Nivel Pro** - 10× más cuota que Plus
+
+---
+
+## Gemini CLI (¡GRATIS 180K/mes!)
+
+### Precios
+
+| Plan | Costo mensual | Cuota | Reinicio |
+|------|--------------|-------|-------|
+| FREE | $0 | 180K completados/mes + 1K/día | Diario + Mensual |
+
+**Mejor valor:** ¡Nivel gratis enorme! Úsalo antes de los niveles de pago.
+
+### Configuración
+
+**Paso 1: Conectar vía Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Gemini CLI
+```
+
+**Paso 2: OAuth de Google**
+
+- Clic en "Connect Gemini CLI"
+- El navegador abre → Inicia sesión en cuenta Google
+- Otorga permisos
+- Auto-refresh de token habilitado
+
+**Paso 3: Usar en CLI**
+
+```
+Model: gc/gemini-3-flash-preview
+       gc/gemini-3-pro-preview
+       gc/gemini-2.5-pro
+       gc/gemini-2.5-flash
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Ideal para |
+|----------|-------------|----------|
+| `gc/gemini-3-flash-preview` | Gemini 3 Flash Preview | Respuestas rápidas |
+| `gc/gemini-3-pro-preview` | Gemini 3 Pro Preview | Tareas complejas |
+| `gc/gemini-2.5-pro` | Gemini 2.5 Pro | Producción estable |
+| `gc/gemini-2.5-flash` | Gemini 2.5 Flash | Tareas rápidas |
+
+### Pro Tips
+
+- **180K completados/mes** - Nivel gratis masivo
+- **Límite de 1K/día** - La cuota diaria se reinicia a medianoche
+- **Úsalo primero** - Nivel gratis, úsalo antes de las suscripciones de pago
+- **Sin tarjeta de crédito** - Completamente gratis con cuenta Google
+
+---
+
+## GitHub Copilot
+
+### Precios
+
+| Plan | Costo mensual | Reinicio de cuota | Modelos |
+|------|--------------|-------------|--------|
+| Individual | $10 | Mensual (día 1) | GPT-5, Claude 4.5, Gemini 3 |
+| Business | $19 | Mensual (día 1) | GPT-5, Claude 4.5, Gemini 3 |
+
+### Configuración
+
+**Paso 1: Conectar vía Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect GitHub
+```
+
+**Paso 2: OAuth vía GitHub**
+
+- Clic en "Connect GitHub"
+- El navegador abre → Inicia sesión en GitHub
+- Autoriza GitHub Copilot
+- Auto-refresh de token habilitado
+
+**Paso 3: Usar en CLI**
+
+```
+Model: gh/gpt-5
+       gh/gpt-5.1-codex-max
+       gh/claude-4.5-sonnet
+       gh/gemini-3-pro
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Ideal para |
+|----------|-------------|----------|
+| `gh/gpt-5` | GPT-5 | Último modelo de OpenAI |
+| `gh/gpt-5.1-codex-max` | GPT-5.1 Codex Max | Contexto máximo |
+| `gh/claude-4.5-sonnet` | Claude 4.5 Sonnet | Calidad de Anthropic |
+| `gh/gemini-3-pro` | Gemini 3 Pro | Calidad de Google |
+
+### Pro Tips
+
+- **Reinicio mensual** - Reinicio completo de cuota el 1ro del mes
+- **Múltiples modelos** - Accede a GPT, Claude, Gemini en una suscripción
+- **Nivel Business** - Mayor cuota para equipos
+
+---
+
+## Antigravity (Cuenta Google)
+
+### Precios
+
+| Plan | Costo mensual | Cuota | Modelos |
+|------|--------------|-------|--------|
+| FREE | $0 | Similar a Gemini CLI | Gemini 3 Pro, Claude Sonnet 4.5 |
+
+### Configuración
+
+**Paso 1: Conectar vía Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Antigravity
+```
+
+**Paso 2: OAuth de Google**
+
+- Clic en "Connect Antigravity"
+- El navegador abre → Inicia sesión en cuenta Google
+- Otorga permisos
+- Auto-refresh de token habilitado
+
+**Paso 3: Usar en CLI**
+
+```
+Model: ag/gemini-3-pro-high
+       ag/claude-sonnet-4-5
+       ag/claude-opus-4-5-thinking
+```
+
+### Modelos disponibles
+
+| ID del modelo | Descripción | Ideal para |
+|----------|-------------|----------|
+| `ag/gemini-3-pro-high` | Gemini 3 Pro High | Respuestas de alta calidad |
+| `ag/claude-sonnet-4-5` | Claude Sonnet 4.5 | Calidad de Anthropic |
+| `ag/claude-opus-4-5-thinking` | Claude Opus 4.5 Thinking | Razonamiento complejo |
+
+### Pro Tips
+
+- **Nivel gratis** - Sin costo con cuenta Google
+- **Acceso a Claude** - Claude Sonnet/Opus gratis
+- **Cuota similar a Gemini CLI** - Límites diarios/mensuales
+
+---
+
+## Comparación de precios
+
+| Proveedor | Costo mensual | Reinicio de cuota | Valor |
+|----------|--------------|-------------|-------|
+| **Claude Code Pro** | $20 | 5 horas + semanal | ⭐⭐⭐⭐⭐ Mejor calidad |
+| **Claude Code Max** | $100 | 5 horas + semanal | ⭐⭐⭐⭐⭐ Mayor cuota |
+| **Codex Plus** | $20 | 5 horas + semanal | ⭐⭐⭐⭐ Buen valor |
+| **Codex Pro** | $200 | 5 horas + semanal | ⭐⭐⭐⭐⭐ 10× cuota |
+| **Gemini CLI** | **$0** | Diario + Mensual | ⭐⭐⭐⭐⭐ ¡GRATIS 180K/mes! |
+| **GitHub Copilot** | $10-19 | Mensual (día 1) | ⭐⭐⭐⭐ Multi-modelo |
+| **Antigravity** | **$0** | Diario + Mensual | ⭐⭐⭐⭐ ¡Claude GRATIS! |
+
+---
+
+## Ejemplo de uso
+
+### Configuración en Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [desde el dashboard de 9router]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Crear combo (Recomendado)
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. gc/gemini-3-flash-preview (GRATIS, usar primero)
+  2. cc/claude-opus-4-5-20251101 (Suscripción)
+  3. cx/gpt-5.2-codex (Respaldo de suscripción)
+
+Usar en CLI: premium-coding
+```
+
+**Resultado:** Maximiza el nivel gratis → Usa suscripción → Fallback automático
+
+---
+
+## Seguimiento de cuota
+
+9Router rastrea la cuota en tiempo real:
+
+- **Consumo de tokens** - Tokens de entrada/salida por solicitud
+- **Cuenta regresiva de reinicio** - Tiempo hasta el próximo reinicio de cuota
+- **Porcentaje de uso** - Cuánta cuota se ha usado
+- **Fallback automático** - Cambia al siguiente nivel cuando se agota
+
+**Vista del dashboard:**
+
+```
+Claude Code Pro
+├─ Cuota: 75% usada
+├─ Reinicio: 2h 15m (5 horas)
+├─ Reinicio semanal: 3 días
+└─ Fallback: glm/glm-4.7 (nivel barato)
+```
+
+---
+
+## Mejores prácticas
+
+### 1. Usa el nivel gratis primero
+
+```
+Prioridad:
+1. Gemini CLI (180K/mes GRATIS)
+2. Antigravity (Claude GRATIS)
+3. Claude Code/Codex (suscripciones de pago)
+```
+
+### 2. Rastrea la cuota diariamente
+
+- Revisa el dashboard cada mañana
+- Planifica tareas pesadas según reinicios de cuota
+- Usa el nivel barato/gratis para tareas no críticas
+
+### 3. Crea combos inteligentes
+
+```
+Ejemplo de combo:
+1. gc/gemini-3-flash-preview (GRATIS principal)
+2. cc/claude-opus-4-5 (Tareas complejas)
+3. glm/glm-4.7 (Respaldo barato)
+4. if/kimi-k2-thinking (Fallback GRATIS)
+```
+
+### 4. Optimiza por tiempo
+
+```
+Mañana: Cuota fresca de 5 horas (Claude/Codex)
+Tarde: Gemini CLI (1K/día)
+Noche: Cuota de suscripción
+Madrugada: Nivel barato/gratis
+```
+
+---
+
+## Solución de problemas
+
+### "Cuota agotada"
+
+**Solución:**
+- Verifica el rastreador de cuota del dashboard
+- Espera el reinicio (5 horas o diario)
+- Usa fallback de combo al nivel barato/gratis
+
+### "Token OAuth expirado"
+
+**Solución:**
+- Auto-refresh por 9Router
+- Si hay problemas: Dashboard → Provider → Reconnect
+
+### "Rate limiting"
+
+**Solución:**
+- Cuota de suscripción agotada
+- Agrega fallback: `cc/claude-opus → glm/glm-4.7`
+- Usa el nivel gratis: `if/kimi-k2-thinking`
+
+---
+
+## Próximos pasos
+
+- **Configurar respaldo barato:** [Proveedores baratos](./cheap.md)
+- **Agregar fallback gratis:** [Proveedores gratis](./free.md)
+- **Crear combos:** Dashboard → Combos → Create New
diff --git a/gitbook/content/es/troubleshooting.md b/gitbook/content/es/troubleshooting.md
new file mode 100644
index 0000000..77d0359
--- /dev/null
+++ b/gitbook/content/es/troubleshooting.md
@@ -0,0 +1,351 @@
+# Solución de problemas
+
+Problemas comunes y soluciones al usar 9Router.
+
+---
+
+## "Language model did not provide messages"
+
+**Problema:** La solicitud falla con una respuesta vacía o un mensaje de error.
+
+**Causas:**
+- Cuota del proveedor agotada
+- API key inválida o expirada
+- Modelo no disponible
+
+**Soluciones:**
+
+1. **Verifica el estado de la cuota:**
+   ```
+   Dashboard → Providers → Ver el rastreador de cuota
+   ```
+   Si la cuota está agotada, espera el reinicio o cambia de proveedor.
+
+2. **Usa el fallback con combo:**
+   ```
+   Dashboard → Combos → Crea cadena de fallback
+   Ejemplo: cc/claude-opus → glm/glm-4.7 → if/kimi-k2
+   ```
+
+3. **Verifica la conexión del proveedor:**
+   ```
+   Dashboard → Providers → Reconecta si es necesario
+   ```
+
+---
+
+## Rate Limiting
+
+**Problema:** Errores "Rate limit exceeded" o "Too many requests".
+
+**Causas:**
+- Cuota de suscripción agotada (límites de 5 horas/diario/semanal)
+- Límites de tasa de API alcanzados
+- Demasiadas solicitudes concurrentes
+
+**Soluciones:**
+
+1. **Verifica el tiempo de reinicio:**
+   ```
+   Dashboard → Quota Tracking → Ver cuenta regresiva
+   ```
+
+2. **Cambia al nivel barato:**
+   ```
+   Usa: glm/glm-4.7 ($0.6/1M tokens)
+        minimax/MiniMax-M2.1 ($0.20/1M tokens)
+   ```
+
+3. **Agrega un combo de fallback:**
+   ```
+   Dashboard → Combos → Agrega modelos de respaldo
+   Principal: cc/claude-opus (suscripción)
+   Respaldo: glm/glm-4.7 (barato)
+   Emergencia: if/kimi-k2 (gratis)
+   ```
+
+---
+
+## Token OAuth expirado
+
+**Problema:** Errores "Unauthorized" o "Token expired".
+
+**Causas:**
+- Token OAuth expirado (refresh automático falló)
+- Sesión del proveedor invalidada
+- Problemas de red durante el refresh
+
+**Soluciones:**
+
+1. **Refresh automático (por defecto):**
+   9Router refresca automáticamente los tokens. Espera 30 segundos y reintenta.
+
+2. **Reconexión manual:**
+   ```
+   Dashboard → Providers → [Nombre del proveedor] → Reconnect
+   → Completa el flujo OAuth de nuevo
+   ```
+
+3. **Verifica el estado del proveedor:**
+   Verifica que el servicio del proveedor esté en línea (Claude Code, Codex, etc.)
+
+---
+
+## Costos altos
+
+**Problema:** Uso o costos altos inesperados.
+
+**Causas:**
+- Uso de modelos costosos innecesariamente
+- Sin fallback a niveles más baratos
+- Ventanas de contexto grandes
+
+**Soluciones:**
+
+1. **Verifica las estadísticas de uso:**
+   ```
+   Dashboard → Usage Stats → Ver consumo de tokens
+   → Identifica modelos de alto costo
+   ```
+
+2. **Cambia a modelos más baratos:**
+   ```
+   Reemplaza: cc/claude-opus (suscripción $20-100/mes)
+   Con: glm/glm-4.7 ($0.6/1M tokens)
+        minimax/MiniMax-M2.1 ($0.20/1M tokens)
+   ```
+
+3. **Usa el nivel gratis:**
+   ```
+   if/kimi-k2-thinking (GRATIS)
+   qw/qwen3-coder-plus (GRATIS)
+   kr/claude-sonnet-4.5 (GRATIS)
+   gc/gemini-3-flash-preview (GRATIS 180K/mes)
+   ```
+
+4. **Optimiza los prompts:**
+   - Reduce el tamaño del contexto
+   - Usa streaming para respuestas largas
+   - Cachea prompts comunes
+
+---
+
+## Connection Refused
+
+**Problema:** "ECONNREFUSED" o "Cannot connect to localhost:20128".
+
+**Causas:**
+- 9Router no está ejecutándose
+- Puerto 20128 bloqueado
+- Firewall bloqueando la conexión
+
+**Soluciones:**
+
+1. **Inicia 9Router:**
+   ```bash
+   9router
+   ```
+   El dashboard debe abrir en http://localhost:3000
+
+2. **Verifica el puerto 20128:**
+   ```bash
+   # Verifica si el puerto está escuchando
+   lsof -i :20128
+   
+   # O en Windows
+   netstat -ano | findstr :20128
+   ```
+
+3. **Revisa el firewall:**
+   - macOS: System Settings → Network → Firewall
+   - Windows: Windows Defender Firewall → Allow app
+   - Linux: `sudo ufw allow 20128`
+
+4. **Usa el endpoint en la nube:**
+   Si localhost no funciona (ej. Cursor IDE):
+   ```
+   Endpoint: https://9router.com/v1
+   ```
+
+---
+
+## El dashboard no abre
+
+**Problema:** El dashboard no carga en http://localhost:3000.
+
+**Causas:**
+- Puerto 3000 ya en uso
+- 9Router crasheó
+- Problemas de caché del navegador
+
+**Soluciones:**
+
+1. **Verifica si 9Router está ejecutándose:**
+   ```bash
+   # Verifica el proceso
+   ps aux | grep 9router
+   
+   # Verifica el puerto 3000
+   lsof -i :3000
+   ```
+
+2. **Mata el proceso en conflicto:**
+   ```bash
+   # macOS/Linux
+   lsof -ti:3000 | xargs kill -9
+   
+   # Windows
+   netstat -ano | findstr :3000
+   taskkill /PID <PID> /F
+   ```
+
+3. **Reinicia 9Router:**
+   ```bash
+   # Detener
+   pkill -f 9router
+   
+   # Iniciar
+   9router
+   ```
+
+4. **Limpia la caché del navegador:**
+   - Chrome: Ctrl+Shift+Delete → Limpiar caché
+   - Prueba en modo incógnito
+
+5. **Verifica la configuración del firewall:**
+   Asegúrate de que el puerto 3000 no esté bloqueado.
+
+---
+
+## Modelo no encontrado
+
+**Problema:** Errores "Model not found" o "Invalid model".
+
+**Causas:**
+- Proveedor no conectado
+- Error tipográfico en el ID del modelo
+- Proveedor inactivo
+
+**Soluciones:**
+
+1. **Verifica la conexión del proveedor:**
+   ```
+   Dashboard → Providers → Verifica estado (verde = activo)
+   ```
+
+2. **Revisa el formato del ID del modelo:**
+   ```
+   Correcto: cc/claude-opus-4-5-20251101
+   Incorrecto: claude-opus-4-5-20251101
+   
+   Formato: [prefijo-proveedor]/[nombre-modelo]
+   ```
+
+3. **Lista los modelos disponibles:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer your-api-key"
+   ```
+
+4. **Reconecta el proveedor:**
+   ```
+   Dashboard → Providers → [Proveedor] → Reconnect
+   ```
+
+---
+
+## Respuesta lenta
+
+**Problema:** Las solicitudes tardan demasiado o hacen timeout.
+
+**Causas:**
+- Latencia del proveedor
+- Problemas de red
+- Contexto/respuesta grande
+- Rate limiting del proveedor
+
+**Soluciones:**
+
+1. **Verifica el estado del proveedor:**
+   ```
+   Dashboard → Providers → Ver estadísticas de latencia
+   ```
+
+2. **Cambia a un modelo más rápido:**
+   ```
+   Rápidos: cc/claude-haiku-4-5 (Haiku es más rápido que Opus)
+         gc/gemini-3-flash-preview
+         qw/qwen3-coder-flash
+   ```
+
+3. **Usa streaming:**
+   ```json
+   {
+     "model": "cc/claude-opus-4-5",
+     "messages": [...],
+     "stream": true
+   }
+   ```
+
+4. **Verifica la red:**
+   ```bash
+   # Prueba la latencia
+   ping api.anthropic.com
+   ping api.openai.com
+   ```
+
+5. **Reduce el tamaño del contexto:**
+   - Recorta el historial de mensajes
+   - Usa prompts más pequeños
+   - Habilita el pruning de contexto en la herramienta CLI
+
+---
+
+## API Key inválida
+
+**Problema:** Errores "Invalid API key" o "Authentication failed".
+
+**Causas:**
+- API key incorrecta copiada
+- API key expirada
+- API key no generada
+
+**Soluciones:**
+
+1. **Regenera la API key:**
+   ```
+   Dashboard → Settings → API Keys → Generate New Key
+   → Copia y usa la nueva key
+   ```
+
+2. **Verifica el formato de la key:**
+   ```
+   Correcto: 9r_xxxxxxxxxxxxxxxxxxxxxxxx
+   Incorrecto: Falta el prefijo 9r_
+   ```
+
+3. **Verifica la key en la configuración del CLI:**
+   ```bash
+   # Cursor
+   Settings → Models → OpenAI API Key
+   
+   # Cline
+   Settings → API Key
+   
+   # Variable de entorno
+   export OPENAI_API_KEY="9r_your_key"
+   ```
+
+4. **Prueba la API key:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer 9r_your_key"
+   ```
+
+---
+
+## ¿Necesitas más ayuda?
+
+- **GitHub Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **Documentación:** [9router.com/docs](https://9router.com/docs)
+- **FAQ:** [faq.md](faq.md)
diff --git a/gitbook/content/ja/deployment/cloud.md b/gitbook/content/ja/deployment/cloud.md
new file mode 100644
index 0000000..e15a293
--- /dev/null
+++ b/gitbook/content/ja/deployment/cloud.md
@@ -0,0 +1,473 @@
+# ☁️ クラウドデプロイメント
+
+リモートアクセスと本番利用のため、VPSまたはDockerに9Routerをデプロイ。
+
+---
+
+## 🖥️ VPSデプロイメント
+
+### 前提条件
+
+- Ubuntu 20.04+ または同様のLinuxディストリビューション
+- Node.js 20以上
+- Git
+- rootまたはsudoアクセス
+
+### ステップ1: リポジトリをクローン
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+```
+
+### ステップ2: 依存関係をインストール
+
+```bash
+npm install
+```
+
+### ステップ3: アプリケーションをビルド
+
+```bash
+npm run build
+```
+
+### ステップ4: 環境変数を設定
+
+`.env` ファイルを作成するか、変数をエクスポート:
+
+```bash
+export JWT_SECRET="your-secure-secret-change-this-to-random-string"
+export INITIAL_PASSWORD="your-secure-password"
+export DATA_DIR="/var/lib/9router"
+export NODE_ENV="production"
+```
+
+**環境変数:**
+
+| 変数 | デフォルト | 説明 |
+|----------|---------|-------------|
+| `JWT_SECRET` | 自動生成 | **本番環境では必ず変更!** JWTトークンの署名に使用 |
+| `INITIAL_PASSWORD` | `123456` | ダッシュボードログインパスワード |
+| `DATA_DIR` | `~/.9router` | データベースとデータの保存パス |
+| `NODE_ENV` | `development` | デプロイ時は `production` に設定 |
+| `ENABLE_REQUEST_LOGS` | `false` | デバッグリクエスト/レスポンスログを有効化 |
+
+### ステップ5: データディレクトリを作成
+
+```bash
+sudo mkdir -p /var/lib/9router
+sudo chown $USER:$USER /var/lib/9router
+```
+
+### ステップ6: アプリケーションを起動
+
+```bash
+npm run start
+```
+
+### ステップ7: 本番環境用にPM2をセットアップ
+
+PM2はアプリケーションを稼働させ続け、クラッシュ時に再起動します:
+
+```bash
+# PM2をグローバルにインストール
+npm install -g pm2
+
+# PM2で9Routerを起動
+pm2 start npm --name 9router -- start
+
+# PM2設定を保存
+pm2 save
+
+# システム起動時にPM2を開始するようセットアップ
+pm2 startup
+# 上記コマンドが出力する指示に従ってください
+```
+
+**PM2管理コマンド:**
+
+```bash
+# ログを表示
+pm2 logs 9router
+
+# アプリケーションを再起動
+pm2 restart 9router
+
+# アプリケーションを停止
+pm2 stop 9router
+
+# ステータスを表示
+pm2 status
+
+# リソースをモニタリング
+pm2 monit
+```
+
+---
+
+## 🐳 Dockerデプロイメント
+
+### オプション1: Dockerfileを使用
+
+`app` ディレクトリに `Dockerfile` を作成:
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy application files
+COPY . .
+
+# Build application
+RUN npm run build
+
+# Expose ports
+EXPOSE 3000 20128
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV DATA_DIR=/app/data
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Start application
+CMD ["npm", "run", "start"]
+```
+
+**ビルドと実行:**
+
+```bash
+# イメージをビルド
+docker build -t 9router .
+
+# コンテナを実行
+docker run -d \
+  --name 9router \
+  -p 3000:3000 \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret-change-this" \
+  -e INITIAL_PASSWORD="your-secure-password" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### オプション2: Docker Compose
+
+`docker-compose.yml` を作成:
+
+```yaml
+version: '3.8'
+
+services:
+  9router:
+    build: .
+    container_name: 9router
+    ports:
+      - "3000:3000"
+      - "20128:20128"
+    environment:
+      - NODE_ENV=production
+      - JWT_SECRET=your-secure-secret-change-this
+      - INITIAL_PASSWORD=your-secure-password
+      - DATA_DIR=/app/data
+    volumes:
+      - 9router-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  9router-data:
+```
+
+**Docker Composeで実行:**
+
+```bash
+# サービスを起動
+docker-compose up -d
+
+# ログを表示
+docker-compose logs -f
+
+# サービスを停止
+docker-compose down
+
+# 再ビルドして再起動
+docker-compose up -d --build
+```
+
+---
+
+## 🌐 Nginxリバースプロキシ
+
+### Nginxを使う理由
+
+- SSL/TLS終端
+- ドメイン名マッピング
+- ロードバランシング
+- セキュリティ強化
+
+### ステップ1: Nginxをインストール
+
+```bash
+sudo apt update
+sudo apt install nginx
+```
+
+### ステップ2: Nginxを設定
+
+`/etc/nginx/sites-available/9router` を作成:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    # SSL certificates (use certbot to generate)
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    # SSL configuration
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # Proxy to 9Router
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+
+    # API endpoint
+    location /v1 {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+### ステップ3: サイトを有効化
+
+```bash
+# シンボリックリンクを作成
+sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/
+
+# 設定をテスト
+sudo nginx -t
+
+# Nginxをリロード
+sudo systemctl reload nginx
+```
+
+### ステップ4: Let's EncryptでSSLをセットアップ
+
+```bash
+# certbotをインストール
+sudo apt install certbot python3-certbot-nginx
+
+# SSL証明書を取得
+sudo certbot --nginx -d your-domain.com
+
+# 自動更新は自動的に設定されます
+# 更新をテスト
+sudo certbot renew --dry-run
+```
+
+---
+
+## 🔒 セキュリティ考慮事項
+
+### 1. デフォルト認証情報を変更
+
+**重要:** デプロイ前に `JWT_SECRET` と `INITIAL_PASSWORD` を変更:
+
+```bash
+# 安全なJWTシークレットを生成
+openssl rand -base64 32
+
+# この値をJWT_SECRETに使用
+export JWT_SECRET="generated-secret-here"
+```
+
+### 2. ファイアウォール設定
+
+```bash
+# SSHを許可
+sudo ufw allow 22/tcp
+
+# HTTP/HTTPSを許可 (Nginx使用時)
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+
+# リバースプロキシを使用しない場合、9Routerポートを許可
+sudo ufw allow 3000/tcp
+sudo ufw allow 20128/tcp
+
+# ファイアウォールを有効化
+sudo ufw enable
+```
+
+### 3. ダッシュボードアクセスを制限
+
+APIアクセスのみ必要な場合、ダッシュボードポートを制限:
+
+```bash
+# ダッシュボードへのlocalhostアクセスのみ許可
+sudo ufw deny 3000/tcp
+```
+
+SSHトンネル経由でダッシュボードにアクセス:
+
+```bash
+ssh -L 3000:localhost:3000 user@your-server.com
+# ブラウザで http://localhost:3000 を開く
+```
+
+### 4. 定期的な更新
+
+```bash
+# システムパッケージを更新
+sudo apt update && sudo apt upgrade -y
+
+# 9Routerを更新
+cd /path/to/9router/app
+git pull
+npm install
+npm run build
+pm2 restart 9router
+```
+
+### 5. バックアップ戦略
+
+```bash
+# データディレクトリをバックアップ
+tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router
+
+# 自動毎日バックアップ (crontabに追加)
+0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router
+```
+
+---
+
+## 📊 モニタリング
+
+### アプリケーションステータスを確認
+
+```bash
+# PM2ステータス
+pm2 status
+
+# ログを表示
+pm2 logs 9router --lines 100
+
+# リソースをモニタリング
+pm2 monit
+```
+
+### Nginxログ
+
+```bash
+# アクセスログ
+sudo tail -f /var/log/nginx/access.log
+
+# エラーログ
+sudo tail -f /var/log/nginx/error.log
+```
+
+### システムリソース
+
+```bash
+# CPUとメモリ使用量
+htop
+
+# ディスク使用量
+df -h
+
+# ネットワーク接続
+netstat -tulpn | grep -E '3000|20128'
+```
+
+---
+
+## 🚨 トラブルシューティング
+
+### アプリケーションが起動しない
+
+```bash
+# ログを確認
+pm2 logs 9router
+
+# ポートが使用中か確認
+sudo lsof -i :3000
+sudo lsof -i :20128
+
+# 環境変数を確認
+pm2 env 9router
+```
+
+### Nginx 502 Bad Gateway
+
+```bash
+# 9Routerが実行中か確認
+pm2 status
+
+# Nginxエラーログを確認
+sudo tail -f /var/log/nginx/error.log
+
+# Nginx設定をテスト
+sudo nginx -t
+```
+
+### SSEストリーミングが動作しない
+
+SSEサポート用にNginx設定で `proxy_buffering off` が設定されていることを確認。
+
+### Permission Deniedエラー
+
+```bash
+# データディレクトリ権限を修正
+sudo chown -R $USER:$USER /var/lib/9router
+chmod 755 /var/lib/9router
+```
+
+---
+
+## 🔗 次のステップ
+
+- [プロバイダーを接続](/providers/subscription.md)
+- [コンボをセットアップ](/features/combos.md)
+- [ツールと統合](/integration/cursor.md)
diff --git a/gitbook/content/ja/deployment/localhost.md b/gitbook/content/ja/deployment/localhost.md
new file mode 100644
index 0000000..c7f1bb2
--- /dev/null
+++ b/gitbook/content/ja/deployment/localhost.md
@@ -0,0 +1,164 @@
+# 🏠 ローカルホストデプロイメント
+
+開発と個人利用のため、ローカルマシンで9Routerを実行。
+
+---
+
+## 📦 インストール
+
+npm経由で9Routerをグローバルインストール:
+
+```bash
+npm install -g 9router
+```
+
+**要件:**
+- Node.js 20以上
+- npm 9以上
+
+---
+
+## 🚀 サーバーの起動
+
+一つのコマンドで9Routerを起動:
+
+```bash
+9router
+```
+
+ダッシュボードが自動的にブラウザで `http://localhost:3000` に開きます。
+
+**デフォルト設定:**
+- **ダッシュボード**: `http://localhost:3000`
+- **APIエンドポイント**: `http://localhost:20128/v1`
+- **データディレクトリ**: `~/.9router`
+
+---
+
+## 🔧 設定
+
+### カスタムデータディレクトリ
+
+環境変数を使ってカスタムデータディレクトリを設定:
+
+```bash
+DATA_DIR=/path/to/data 9router
+```
+
+### カスタムポート
+
+APIポート(20128)とダッシュボードポート(3000)はアプリケーションで設定されています。変更するにはソースコードを修正するか、サポートされている場合は環境変数を使用してください。
+
+---
+
+## 🛑 サーバーの停止
+
+9Routerが実行されているターミナルで `Ctrl+C` を押します。
+
+```bash
+# 9routerを実行しているターミナル
+^C  # Ctrl+Cを押す
+```
+
+サーバーはグレースフルにシャットダウンし、すべてのデータを保存します。
+
+---
+
+## 🔄 サーバーの再起動
+
+起動コマンドを再度実行するだけです:
+
+```bash
+9router
+```
+
+すべての設定、APIキー、コンボはデータディレクトリに保持されます。
+
+---
+
+## 📊 9Routerの更新
+
+最新バージョンに更新:
+
+```bash
+npm update -g 9router
+```
+
+現在のバージョンを確認:
+
+```bash
+npm list -g 9router
+```
+
+---
+
+## 🔍 トラブルシューティング
+
+### ポートがすでに使用されている
+
+ポート20128または3000がすでに使用されている場合:
+
+```bash
+# ポートを使用しているプロセスを検索 (macOS/Linux)
+lsof -i :20128
+lsof -i :3000
+
+# プロセスを終了
+kill -9 <PID>
+```
+
+### 権限エラー
+
+インストール中に権限エラーが発生した場合:
+
+```bash
+# sudoを使用 (非推奨)
+sudo npm install -g 9router
+
+# またはnpm権限を修正 (推奨)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### データディレクトリの問題
+
+データディレクトリにアクセスできない場合:
+
+```bash
+# 権限を確認
+ls -la ~/.9router
+
+# 権限を修正
+chmod 755 ~/.9router
+```
+
+---
+
+## 📁 データディレクトリ構造
+
+```
+~/.9router/
+├── db.json           # メインデータベース (プロバイダー、コンボ、設定)
+├── logs/             # アプリケーションログ
+└── cache/            # 一時キャッシュファイル
+```
+
+**データのバックアップ:**
+
+```bash
+# バックアップ
+cp -r ~/.9router ~/.9router.backup
+
+# 復元
+cp -r ~/.9router.backup ~/.9router
+```
+
+---
+
+## 🔗 次のステップ
+
+- [プロバイダーを接続](/providers/subscription.md)
+- [コンボを作成](/features/combos.md)
+- [CLIツールとの統合](/integration/cursor.md)
diff --git a/gitbook/content/ja/faq.md b/gitbook/content/ja/faq.md
new file mode 100644
index 0000000..3eee083
--- /dev/null
+++ b/gitbook/content/ja/faq.md
@@ -0,0 +1,387 @@
+# よくある質問
+
+9Routerに関する一般的な質問。
+
+---
+
+## 9Routerとは?
+
+**9Routerは、サブスクリプションの価値を最大化し、コストを最小限に抑えるAIモデルルーターです。**
+
+3階層フォールバックシステムを使用して、複数のAIプロバイダー間でリクエストをインテリジェントにルーティングします:
+1. **サブスクリプション階層** - すでに支払っているClaude Code、Codex、Geminiのクォータを最大化
+2. **低価格階層** - 超低価格な代替手段(100万トークンあたり$0.20〜$0.60)
+3. **無料階層** - 無制限の無料モデルによる緊急バックアップ
+
+**主な利点:**
+- サブスクリプションのクォータを無駄にしない
+- クォータ消費時の自動フォールバック
+- リアルタイムクォータトラッキング
+- 直接API利用に対して90%のコスト削減
+
+---
+
+## 料金体系はどうなっていますか?
+
+**9Routerは3階層の料金戦略を使用します:**
+
+### Tier 1: サブスクリプション(最初に最大化)
+- **Claude Code** (Pro/Max): 月$20〜100 - 5時間 + 週次クォータ
+- **OpenAI Codex** (Plus/Pro): 月$20〜200 - 5時間 + 週次クォータ
+- **Gemini CLI**: 無料 - 月18万コンプリーション + 1K/日
+- **GitHub Copilot**: 月$10〜19 - 月次リセット
+- **Antigravity**: 無料 - Geminiと同様
+
+**目標:** リセット前にクォータを余すことなく使用!
+
+### Tier 2: 低価格(バックアップ)
+- **GLM-4.7**: 100万トークンあたり$0.60/$2.20 - 毎日午前10時リセット
+- **MiniMax M2.1**: 100万トークンあたり$0.20/$1.00 - 5時間ローリング
+- **Kimi K2**: 月$9固定(1000万トークン)
+
+**目標:** ChatGPT API(100万あたり$20)より90%安い!
+
+### Tier 3: 無料(緊急時)
+- **iFlow**: 8モデル無料(Kimi K2、Qwen3、GLM、MiniMax...)
+- **Qwen**: 3モデル無料(Qwen3 Coder Plus/Flash、Vision)
+- **Kiro**: 2モデル無料(Claude Sonnet 4.5、Haiku 4.5)
+
+**目標:** 他のすべてがクォータ制限に達した時のゼロコストフォールバック!
+
+---
+
+## 9Routerは無料ですか?
+
+**はい、9Router自体は100%無料でオープンソースです。**
+
+**利用可能な無料階層プロバイダー:**
+- **Gemini CLI** - 月18万コンプリーション(無料Googleアカウント)
+- **iFlow** - 8モデル無制限(無料OAuth)
+- **Qwen** - 3モデル無制限(無料OAuth)
+- **Kiro** - Claude Sonnet/Haiku(無料AWS Builder ID)
+
+**無料階層プロバイダーのみを使用して永久に無料でコーディングできます!**
+
+**オプションの有料プロバイダー:**
+- すでに持っている可能性のあるサブスクリプションサービス(Claude Code、Codex、Copilot)
+- 超低価格な代替手段(100万トークンあたり$0.20〜$0.60)
+
+---
+
+## どのプロバイダーがサポートされていますか?
+
+### サブスクリプションプロバイダー
+- **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
+- **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex、GPT 5.1 Codex Max
+- **Gemini CLI** (無料) - Gemini 3 Flash/Pro、2.5 Pro/Flash
+- **GitHub Copilot** - GPT-5、Claude 4.5、Gemini 3
+- **Antigravity** (Google) - Gemini 3 Pro、Claude Sonnet 4.5
+
+### 低価格プロバイダー
+- **GLM** (Zhipu AI) - GLM 4.7、GLM 4.6V Vision
+- **MiniMax** - MiniMax M2.1
+- **Kimi** (Moonshot AI) - Kimi Latest
+- **OpenRouter** - 任意のOpenRouterモデルへのパススルー
+
+### 無料プロバイダー
+- **iFlow** - 8モデル(Kimi K2、Qwen3、GLM、MiniMax、DeepSeek...)
+- **Qwen** - 3モデル(Qwen3 Coder Plus/Flash、Vision)
+- **Kiro** - 2モデル(Claude Sonnet 4.5、Haiku 4.5)
+
+**合計: 15以上のプロバイダー、50以上のモデル**
+
+詳細は[プロバイダードキュメント](providers/subscription.md)を参照。
+
+---
+
+## 複数のプロバイダーを使用できますか?
+
+**はい! これは9Routerのコア機能です。**
+
+**コンボにより、複数のプロバイダーを自動フォールバック付きで連鎖させることができます:**
+
+```
+コンボ例: "premium-coding"
+1. cc/claude-opus-4-5 (サブスクリプション優先)
+2. glm/glm-4.7 (低価格バックアップ)
+3. if/kimi-k2 (無料緊急時)
+
+→ クォータ消費時に自動切替
+→ コーディングが止まらない
+→ 最小の追加コスト
+```
+
+**コンボの作成方法:**
+```
+Dashboard → Combos → Create New
+→ 優先順位順にモデルを追加
+→ CLIでコンボ名を使用: "premium-coding"
+```
+
+**利点:**
+- クォータ切れ時のダウンタイムゼロ
+- 自動コスト最適化
+- すべてのツール用の単一モデル名
+
+例については[コンボドキュメント](features/combos.md)を参照。
+
+---
+
+## クォータトラッキングはどのように機能しますか?
+
+**9Routerはすべてのプロバイダーのクォータをリアルタイムで追跡します:**
+
+**機能:**
+- **トークン消費** - リクエストごとの入出力トークン
+- **リセットカウントダウン** - クォータが更新されるまでの時間
+- **使用統計** - 日次/週次/月次レポート
+- **コスト見積もり** - 予測支出(有料階層)
+- **クォータアラート** - クォータが少ない時の通知
+
+**クォータタイプ:**
+- **5時間ローリング** - Claude Code、Codex、MiniMax
+- **日次リセット** - Gemini CLI(1K/日)、GLM(午前10時)
+- **週次リセット** - Claude Code、Codex(追加クォータ)
+- **月次リセット** - Gemini CLI(18万)、GitHub Copilot(1日)
+
+**クォータを表示:**
+```
+Dashboard → Providers → Quota Tracking
+→ リアルタイム使用量 + リセットカウントダウン
+```
+
+詳細は[クォータトラッキングドキュメント](features/quota-tracking.md)を参照。
+
+---
+
+## 9RouterはCursorで動作しますか?
+
+**はい、ただしCursorはクラウドエンドポイントが必要です。**
+
+**問題:** Cursor IDEはlocalhostエンドポイントをサポートしていません。
+
+**解決策:** 9Routerクラウドデプロイメントを使用:
+
+```
+Cursor Settings → Models → Advanced:
+  OpenAI API Base URL: https://9router.com/v1
+  OpenAI API Key: [ダッシュボードから取得]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+**代替案:** パブリックドメインでVPSにセルフホスト:
+```bash
+# VPSへデプロイ
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+npm start
+
+# Nginxリバースプロキシを設定
+# Cursorを向ける: https://your-domain.com/v1
+```
+
+**他のCLIツールはlocalhostで動作:**
+- Cline ✅
+- Claude Desktop ✅
+- Codex CLI ✅
+- Continue ✅
+- RooCode ✅
+
+詳細は[Cursor統合ガイド](integration/cursor.md)を参照。
+
+---
+
+## 9Routerをセルフホストできますか?
+
+**はい! 9Routerは複数のデプロイメントオプションをサポートします:**
+
+### Localhost(デフォルト)
+```bash
+npm install -g 9router
+9router
+→ Dashboard: http://localhost:3000
+→ API: http://localhost:20128/v1
+```
+
+### VPS/クラウド
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+npm start
+```
+
+### Docker
+```bash
+docker build -t 9router .
+docker run -d \
+  -p 3000:3000 \
+  -e JWT_SECRET="your-secret" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Cloudflare Workers
+```bash
+cd 9router/app
+npm run deploy:cloudflare
+```
+
+**環境変数:**
+- `JWT_SECRET` - **本番環境で必ず変更!**
+- `DATA_DIR` - データベース保存パス(デフォルト: `~/.9router`)
+- `INITIAL_PASSWORD` - ダッシュボードログイン(デフォルト: `123456`)
+- `NODE_ENV` - デプロイ時は`production`に設定
+
+詳細は[デプロイメントガイド](getting-started/installation.md#deployment)を参照。
+
+---
+
+## データは安全ですか?
+
+**はい、9Routerはセキュリティとプライバシーを優先します:**
+
+**ローカルストレージ:**
+- すべてのデータは`~/.9router`(またはカスタム`DATA_DIR`)にローカル保存
+- 9Routerサーバーへのデータ送信なし
+- OAuthトークンはJWTで暗号化
+
+**テレメトリなし:**
+- 使用状況追跡なし
+- アナリティクスなし
+- フォンホームなし
+
+**オープンソース:**
+- 完全なソースコードがGitHubで利用可能
+- 自分でセキュリティを監査可能
+- コミュニティレビュー済み
+
+**ベストプラクティス:**
+- 本番環境で`JWT_SECRET`を変更
+- 強力な`INITIAL_PASSWORD`を使用
+- クラウドデプロイでHTTPSを有効化
+- APIキーを定期的にローテーション
+
+**9Routerが保存するもの:**
+- プロバイダーOAuthトークン(暗号化)
+- APIキー(暗号化)
+- 使用統計(ローカルのみ)
+- コンボ設定
+
+**9Routerが保存しないもの:**
+- プロンプトやレスポンス
+- 生成したコード
+- 個人情報
+
+---
+
+## 9Routerを更新するには?
+
+**更新方法はインストールタイプによって異なります:**
+
+### グローバルNPMインストール
+```bash
+npm update -g 9router
+```
+
+### ローカルインストール
+```bash
+cd 9router/app
+git pull origin main
+npm install
+npm run build
+npm start
+```
+
+### Docker
+```bash
+docker pull 9router:latest
+docker stop 9router
+docker rm 9router
+docker run -d \
+  -p 3000:3000 \
+  -v 9router-data:/app/data \
+  9router:latest
+```
+
+**バージョンを確認:**
+```bash
+9router --version
+```
+
+**破壊的変更:**
+- [CHANGELOG.md](https://github.com/decolua/9router/blob/main/CHANGELOG.md)を確認
+- メジャー更新前に`~/.9router`をバックアップ
+- メジャーバージョンの移行ガイドを確認
+
+---
+
+## どのように貢献できますか?
+
+**貢献を歓迎します!**
+
+### 貢献方法:
+
+1. **バグを報告:**
+   - [GitHub Issues](https://github.com/decolua/9router/issues)
+   - エラーログ、再現手順を含める
+
+2. **機能をリクエスト:**
+   - [GitHub Discussions](https://github.com/decolua/9router/discussions)
+   - ユースケースと利点を説明
+
+3. **コードを提出:**
+   ```bash
+   # リポジトリをフォーク
+   git clone https://github.com/YOUR_USERNAME/9router.git
+   cd 9router
+   
+   # ブランチを作成
+   git checkout -b feature/your-feature
+   
+   # 変更を加える
+   npm install
+   npm run dev
+   
+   # テスト
+   npm test
+   
+   # コミットしてプッシュ
+   git add .
+   git commit -m "Add your feature"
+   git push origin feature/your-feature
+   
+   # GitHubでPull Requestを作成
+   ```
+
+4. **ドキュメントを改善:**
+   - 誤字の修正、例の追加
+   - 他言語への翻訳
+   - チュートリアルの執筆
+
+5. **プロバイダーを追加:**
+   - 新しいプロバイダーアダプターを実装
+   - 例については`app/lib/providers/`を参照
+
+**貢献ガイドライン:**
+- 既存のコードスタイルに従う
+- 新機能にはテストを追加
+- ドキュメントを更新
+- コミットは小さく、わかりやすく
+
+詳細は[CONTRIBUTING.md](https://github.com/decolua/9router/blob/main/CONTRIBUTING.md)を参照。
+
+---
+
+## さらにヘルプが必要?
+
+- **ドキュメント:** [9router.com/docs](https://9router.com/docs)
+- **GitHub:** [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **トラブルシューティング:** [troubleshooting.md](troubleshooting.md)
diff --git a/gitbook/content/ja/features/combos.md b/gitbook/content/ja/features/combos.md
new file mode 100644
index 0000000..e331a10
--- /dev/null
+++ b/gitbook/content/ja/features/combos.md
@@ -0,0 +1,537 @@
+# コンボ - カスタムフォールバックチェーン
+
+自動フォールバック付きのカスタムモデル組み合わせを作成。コンボを使って、コスト、品質、可用性に基づく独自のルーティング戦略を定義できます。
+
+---
+
+## コンボとは?
+
+コンボはダッシュボードで作成する**カスタムフォールバックチェーン**です。単一モデルを使う代わりに、9Routerが順番に試すモデルのシーケンスを定義します。
+
+**例:**
+```
+コンボ名: premium-coding
+モデル:
+  1. cc/claude-opus-4-5-20251101 (最初に試行)
+  2. glm/glm-4.7 (#1のクォータ消費時)
+  3. minimax/MiniMax-M2.1 (#2のクォータ消費時)
+```
+
+**CLIでの使用:**
+```
+Model: premium-coding
+```
+
+9Routerは成功するまで各モデルを順番に自動的に試します。
+
+---
+
+## なぜコンボを使うのか?
+
+### 1. サブスクリプション価値を最大化
+```
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ サブスクリプション優先、低価格バックアップ、無料緊急時
+→ すでに支払っているサブスクリプションから完全な価値を得る
+```
+
+### 2. コストを最小化
+```
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+
+→ 最安の有料オプションから開始 (100万あたり$0.60)
+→ さらに安いものへフォールバック (100万あたり$0.20)
+→ 緊急時の無料階層
+→ 総コスト: 月$5〜10 vs ChatGPT APIの$2000
+```
+
+### 3. 24時間可用性を確保
+```
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ 最後に常に無料階層を含める
+→ クォータ切れにならない
+→ いつでもどこでもコーディング
+```
+
+### 4. 品質に最適化
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → gc/gemini-3-pro
+
+→ 最高のモデルが最初
+→ 他のプレミアムモデルへフォールバック
+→ フォールバックチェーン全体で高品質を維持
+```
+
+---
+
+## コンボの作成方法
+
+### ステップ1: ダッシュボードを開く
+
+```
+http://localhost:20128
+→ パスワードでログイン
+```
+
+### ステップ2: コンボへ移動
+
+```
+Dashboard → Combos → Create New Combo
+```
+
+### ステップ3: コンボを設定
+
+**コンボ名:**
+```
+premium-coding
+```
+
+**説明(任意):**
+```
+サブスクリプション優先、低価格バックアップ、無料緊急時
+```
+
+**モデルを選択:**
+```
+1. cc/claude-opus-4-5-20251101
+2. glm/glm-4.7
+3. minimax/MiniMax-M2.1
+```
+
+**ドラッグで並べ替え** - 上から下へ優先順位。
+
+### ステップ4: 保存
+
+```
+「Save Combo」をクリック
+→ コンボがモデルリストに表示
+```
+
+### ステップ5: CLIで使用
+
+```
+Cursor/Cline/任意のツール:
+  Model: premium-coding
+```
+
+---
+
+## コンボの例
+
+### 例1: プレミアムコーディング (サブスク → 低価格 → 無料)
+
+**目標**: サブスクリプション価値を最大化、追加コストを最小化。
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101
+  2. glm/glm-4.7
+  3. minimax/MiniMax-M2.1
+```
+
+**使用法:**
+```
+Cursor IDE:
+  Model: premium-coding
+```
+
+**動作:**
+```
+朝 (新鮮なクォータ):
+  Request → cc/claude-opus-4-5 ✅
+
+午後 (Claudeクォータ切れ):
+  Request → glm/glm-4.7 ✅ (自動切替)
+
+夕方 (GLMクォータ切れ):
+  Request → minimax/MiniMax-M2.1 ✅ (自動切替)
+```
+
+**月コスト (1億トークン):**
+```
+Claude Code経由で8000万: $0 (サブスクリプション)
+GLM経由で1500万: $9
+MiniMax経由で500万: $1
+合計: $10 + サブスクリプション
+```
+
+**節約**: ChatGPT API ($2000) に対して約99%。
+
+---
+
+### 例2: バジェットコンボ (低価格 → 無料)
+
+**目標**: コストを最小化、バックアップに無料階層を使用。
+
+```
+Dashboard → Combos → Create New
+
+Name: budget-combo
+Models:
+  1. glm/glm-4.7
+  2. minimax/MiniMax-M2.1
+  3. if/kimi-k2-thinking
+```
+
+**使用法:**
+```
+Cline:
+  Provider: OpenAI Compatible
+  Base URL: http://localhost:20128/v1
+  Model: budget-combo
+```
+
+**動作:**
+```
+Request → glm/glm-4.7
+  ✅ 日次クォータ利用可 → GLMを使用 (100万あたり$0.60)
+  ❌ クォータ消費 → MiniMaxを試行 (100万あたり$0.20)
+  ❌ MiniMaxクォータ切れ → iFlowを使用 (無料)
+```
+
+**月コスト (1億トークン):**
+```
+GLM経由で7000万: $42
+MiniMax経由で2000万: $4
+iFlow経由で1000万: $0
+合計: $46 vs ChatGPT APIの$2000
+```
+
+**節約**: 97%。
+
+---
+
+### 例3: フリーコンボ (ゼロコスト)
+
+**目標**: 100%無料、コストはゼロ。
+
+```
+Dashboard → Combos → Create New
+
+Name: free-combo
+Models:
+  1. if/kimi-k2-thinking
+  2. qw/qwen3-coder-plus
+  3. kr/claude-sonnet-4.5
+```
+
+**使用法:**
+```
+Claude Desktop:
+  Model: free-combo
+```
+
+**動作:**
+```
+Request → if/kimi-k2-thinking
+  ✅ 利用可 → iFlowを使用
+  ❌ エラー → Qwenを試行
+  ❌ エラー → Kiroを試行
+```
+
+**月コスト:**
+```
+無料プロバイダー経由で1億トークン: $0
+合計: 永久に$0
+```
+
+**ユースケース**: 個人プロジェクト、学習、実験。
+
+---
+
+### 例4: 品質優先 (プレミアムモデルのみ)
+
+**目標**: 最高の品質、低価格フォールバックなし。
+
+```
+Dashboard → Combos → Create New
+
+Name: quality-first
+Models:
+  1. cc/claude-opus-4-5-20251101
+  2. cx/gpt-5.2-codex
+  3. gc/gemini-3-pro-preview
+```
+
+**使用法:**
+```
+Codex CLI:
+  export OPENAI_BASE_URL="http://localhost:20128"
+  Model: quality-first
+```
+
+**動作:**
+```
+Request → cc/claude-opus-4-5
+  ❌ クォータ切れ → cx/gpt-5.2-codex
+  ❌ クォータ切れ → gc/gemini-3-pro-preview
+  ❌ すべて切れ → エラーを返す (低価格フォールバックなし)
+```
+
+**ユースケース**: クリティカルな本番コード、複雑なリファクタリング。
+
+---
+
+### 例5: マルチサブスクリプション (すべてを最大化)
+
+**目標**: 追加料金前にすべてのサブスクリプションを利用。
+
+```
+Dashboard → Combos → Create New
+
+Name: multi-sub
+Models:
+  1. gc/gemini-3-flash-preview (月18万無料)
+  2. cc/claude-opus-4-5-20251101 (Proサブスクリプション)
+  3. cx/gpt-5.2-codex (Plusサブスクリプション)
+  4. gh/gpt-5 (Copilotサブスクリプション)
+  5. glm/glm-4.7 (低価格バックアップ)
+  6. if/kimi-k2-thinking (無料緊急時)
+```
+
+**月コスト (2億トークン):**
+```
+Gemini CLI経由で5000万: $0 (無料プラン)
+Claude Code経由で8000万: $0 (サブスクリプション)
+Codex経由で4000万: $0 (サブスクリプション)
+Copilot経由で2000万: $0 (サブスクリプション)
+GLM経由で800万: $4.80
+iFlow経由で200万: $0
+合計: $4.80 + 既存サブスクリプション
+```
+
+**結果**: サブスクリプションから1.9億トークン使用、わずか$4.80の追加料金。
+
+---
+
+### 例6: クォータリセット最適化
+
+**目標**: リセット時間に基づいて使用量を分散。
+
+```
+Dashboard → Combos → Create New
+
+Name: reset-optimized
+Models:
+  1. cc/claude-opus-4-5 (5時間リセット、朝に使用)
+  2. gc/gemini-3-flash (1K/日、午後に使用)
+  3. glm/glm-4.7 (毎日午前10時リセット、夕方に使用)
+  4. minimax/MiniMax-M2.1 (5時間ローリング、夜に使用)
+  5. if/kimi-k2-thinking (無制限、緊急時)
+```
+
+**日課:**
+```
+08:00 - 13:00: Claude Code (新鮮な5時間クォータ)
+13:00 - 18:00: Gemini CLI (1K/日クォータ)
+18:00 - 22:00: GLM (翌朝10時リセット)
+22:00 - 08:00: MiniMax (5時間ローリング) または iFlow
+```
+
+**結果**: 最小コストで24時間コーディング。
+
+---
+
+## CLIツールでコンボを使用
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [ダッシュボードから取得]
+  Model: premium-coding
+```
+
+### Claude Desktop
+
+`~/.claude/config.json`を編集:
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key",
+  "model": "budget-combo"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex --model quality-first "your prompt"
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [ダッシュボードから取得]
+Model: free-combo
+```
+
+### APIリクエスト
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "premium-coding",
+    "messages": [
+      {"role": "user", "content": "Write a function to..."}
+    ],
+    "stream": true
+  }'
+```
+
+---
+
+## ベストプラクティス
+
+### 1. 常に無料階層を含める
+
+```
+✅ 良い:
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+❌ 悪い:
+cc/claude-opus → glm/glm-4.7
+(無料フォールバックなし、クォータ切れの可能性)
+```
+
+**理由**: 24時間可用性を確保、クォータでブロックされない。
+
+### 2. コスト順に並べる (安価→高価)
+
+```
+✅ 良い:
+glm/glm-4.7 → minimax/MiniMax-M2.1 → cc/claude-opus
+
+❌ 悪い:
+cc/claude-opus → glm/glm-4.7
+(シンプルなタスクにサブスクリプションクォータを浪費)
+```
+
+**例外**: サブスクリプション価値を最大化したい場合は、サブスクリプションを最初に。
+
+### 3. 品質要件に合わせる
+
+```
+本番コードの場合:
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7
+
+クイックタスクの場合:
+glm/glm-4.7 → if/kimi-k2-thinking
+
+実験用:
+if/kimi-k2-thinking → qw/qwen3-coder-plus
+```
+
+### 4. クォータリセット時間を考慮
+
+```
+朝のコンボ (新鮮なクォータ):
+cc/claude-opus → cx/gpt-5.2-codex
+
+夕方のコンボ (クォータが消費されている可能性):
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+### 5. 異なるユースケース用に複数のコンボを作成
+
+```
+premium-coding: 複雑なタスク用
+budget-combo: シンプルなタスク用
+free-combo: 実験用
+quality-first: 本番コード用
+```
+
+**タスク要件に基づいてコンボを切り替え**ます。
+
+### 6. コンボパフォーマンスをモニター
+
+```
+Dashboard → Analytics → Combo Usage:
+  premium-coding:
+    80% cc/claude-opus経由 (良好、サブスクリプション使用)
+    15% glm/glm-4.7経由 (許容バックアップ)
+    5% minimax経由 (まれなフォールバック)
+```
+
+**最適化**: フォールバック使用が多すぎる場合、プライマリクォータを増やすかモデルを並べ替え。
+
+---
+
+## 高度な設定
+
+### コンボごとに予算上限を設定
+
+```
+Dashboard → Combos → Edit → Budget:
+  Daily limit: $5
+  Monthly limit: $50
+```
+
+上限に達すると、9Routerは有料モデルをスキップして無料階層のみを使用。
+
+### コンボ内のモデルを有効/無効
+
+```
+Dashboard → Combos → Edit → Models:
+  ✅ cc/claude-opus-4-5 (有効)
+  ❌ glm/glm-4.7 (一時的に無効)
+  ✅ if/kimi-k2-thinking (有効)
+```
+
+**ユースケース**: コンボを削除せずに高価なモデルを一時的に無効化。
+
+### 既存のコンボを複製
+
+```
+Dashboard → Combos → Clone "premium-coding"
+→ "-copy" サフィックス付きのコピーを作成
+→ 変更して新しいコンボとして保存
+```
+
+**ユースケース**: 異なるシナリオ用のバリエーションを作成。
+
+---
+
+## トラブルシューティング
+
+**問題: コンボがモデルリストに表示されない**
+
+**解決策:**
+1. ダッシュボードを更新
+2. コンボが保存されていることを確認 (緑のチェック)
+3. CLIツールを再起動してモデルリストを更新
+
+**問題: コンボが常に最後のモデル (無料階層) を使用**
+
+**解決策:**
+1. プライマリモデルのクォータを確認 (Dashboard → Quota)
+2. APIキーが有効か確認 (Dashboard → Providers)
+3. 予算上限を超えていないか確認
+
+**問題: コンボのコストが予想より高い**
+
+**解決策:**
+1. Dashboard → Analytics → コンボ使用量を確認
+2. プライマリモデルがクォータ切れか確認
+3. モデルを並べ替え (安価を先に)
+4. 予算上限を設定
+
+---
+
+## 関連
+
+- [スマートルーティング](./smart-routing.md) - 自動フォールバックの仕組み
+- [クォータトラッキング](./quota-tracking.md) - 使用量とコストを監視
diff --git a/gitbook/content/ja/features/quota-tracking.md b/gitbook/content/ja/features/quota-tracking.md
new file mode 100644
index 0000000..719da66
--- /dev/null
+++ b/gitbook/content/ja/features/quota-tracking.md
@@ -0,0 +1,687 @@
+# クォータトラッキングと使用量モニタリング
+
+リアルタイムのトークン消費を追跡し、クォータ制限を監視し、コストを見積もり、不足前にアラートを取得。サブスクリプションクォータを無駄にしたり、予算上限を超えたりすることはありません。
+
+---
+
+## 概要
+
+9Routerはすべてのプロバイダーに対して包括的なクォータトラッキングを提供:
+
+- **リアルタイムトークン消費** - リクエストごとの使用トークンを表示
+- **クォータ上限と残量** - 使用量 vs 上限を追跡
+- **リセットカウントダウン** - クォータが更新されるタイミング
+- **コスト見積もり** - 有料階層の支出を計算
+- **月次レポート** - 使用パターンを分析
+- **アラートと通知** - 上限前に警告を取得
+
+---
+
+## ダッシュボード概要
+
+### クォータサマリー
+
+```
+Dashboard → Home → Quota Overview
+
+┌─────────────────────────────────────────────┐
+│ Claude Code (cc/)                           │
+│ ████████████░░░░░░░░ 2.5h / 5h (50%)       │
+│ Resets in: 2h 30m                           │
+│ Cost: $0 (subscription)                     │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ Gemini CLI (gc/)                            │
+│ ████████░░░░░░░░░░░░ 450 / 1000 (45%)      │
+│ Daily reset in: 18h 30m                     │
+│ Monthly: 45K / 180K (25%)                   │
+│ Cost: $0 (free tier)                        │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ GLM-4.7 (glm/)                              │
+│ ██████████████░░░░░░ 7M / 10M tokens (70%)  │
+│ Resets: Daily 10:00 AM (in 5h 35m)         │
+│ Cost today: $4.20                           │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ MiniMax M2.1 (minimax/)                     │
+│ ████████████████░░░░ 4M / 5M tokens (80%)   │
+│ Rolling 5h window                           │
+│ Cost (5h): $0.80                            │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ iFlow (if/)                                 │
+│ ████████████████████ Unlimited              │
+│ Cost: $0 (free forever)                     │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## リアルタイムトークン消費
+
+### リクエストごとのトラッキング
+
+各リクエストに詳細なトークン使用量が表示されます:
+
+```
+Dashboard → Activity → Recent Requests
+
+Request #1234
+Model: cc/claude-opus-4-5-20251101
+Timestamp: 2026-02-04 04:15:32
+
+Tokens:
+  Input: 1,250 tokens
+  Output: 850 tokens
+  Total: 2,100 tokens
+
+Cost: $0 (subscription quota)
+Duration: 3.2s
+Status: ✅ Success
+```
+
+### ライブ使用量モニター
+
+```
+Dashboard → Live Monitor
+
+Current request:
+  Model: glm/glm-4.7
+  Tokens streamed: 450 / ~800 estimated
+  Cost so far: $0.0009
+  Duration: 1.8s
+```
+
+### モデル別のトークン内訳
+
+```
+Dashboard → Analytics → Token Usage
+
+Today (Feb 4, 2026):
+  cc/claude-opus-4-5: 15M tokens ($0, subscription)
+  glm/glm-4.7: 8M tokens ($4.80)
+  if/kimi-k2-thinking: 3M tokens ($0, free)
+  
+Total: 26M tokens
+Cost: $4.80
+```
+
+---
+
+## クォータ上限とリセット時間
+
+### サブスクリプションプロバイダー
+
+**Claude Code (Pro/Max)**
+```
+クォータタイプ: 時間ベース (5時間ローリング)
+上限: 5時間の使用
+リセット: 5時間ローリングウィンドウ + 週次更新
+追跡: モデルごとの使用時間
+
+ダッシュボード表示:
+  Opus: 2.5h / 5h 使用
+  Sonnet: 1.2h / 5h 使用
+  Haiku: 0.8h / 5h 使用
+  
+週次リセット: 毎週月曜00:00 UTC
+```
+
+**OpenAI Codex (Plus/Pro)**
+```
+クォータタイプ: 時間ベース (5時間ローリング)
+上限: 5時間 (Plus) / 10時間 (Pro)
+リセット: 5時間ローリングウィンドウ + 週次更新
+
+ダッシュボード表示:
+  GPT-5.2 Codex: 3.5h / 5h 使用
+  Resets in: 1h 30m
+```
+
+**Gemini CLI (無料)**
+```
+クォータタイプ: リクエスト数 + 月次トークン
+日次上限: 1,000 リクエスト
+月次上限: 180,000 コンプリーション
+リセット: 日次 00:00 UTC + 月次 1日
+
+ダッシュボード表示:
+  Today: 450 / 1,000 requests (45%)
+  This month: 45K / 180K completions (25%)
+  Daily reset in: 18h 30m
+  Monthly reset in: 26 days
+```
+
+**GitHub Copilot**
+```
+クォータタイプ: 月次使用量
+上限: プランによる
+リセット: 各月1日
+
+ダッシュボード表示:
+  Usage: 60% of monthly quota
+  Resets: March 1, 2026 (in 25 days)
+```
+
+### 低価格プロバイダー
+
+**GLM-4.7**
+```
+クォータタイプ: 日次トークン上限
+上限: 10Mトークン/日 (Coding Plan)
+リセット: 毎日午前10時 北京時間 (UTC+8)
+
+ダッシュボード表示:
+  Used: 7M / 10M tokens (70%)
+  Remaining: 3M tokens
+  Resets in: 5h 35m
+  Cost today: $4.20
+```
+
+**MiniMax M2.1**
+```
+クォータタイプ: 5時間ローリングウィンドウ
+上限: 5時間あたり5Mトークン
+リセット: 連続ローリングウィンドウ
+
+ダッシュボード表示:
+  Used (5h): 4M / 5M tokens (80%)
+  Oldest usage expires in: 45m
+  Cost (5h): $0.80
+```
+
+**Kimi K2**
+```
+クォータタイプ: 月次サブスクリプション
+上限: 10Mトークン/月 ($9固定)
+リセット: サブスクリプション日に月次
+
+ダッシュボード表示:
+  Used: 6M / 10M tokens (60%)
+  Resets: Feb 15, 2026 (in 11 days)
+  Cost: $9/month (prepaid)
+```
+
+### 無料プロバイダー
+
+**iFlow / Qwen / Kiro**
+```
+クォータタイプ: 無制限 (レート制限)
+上限: ハード制限なし
+リセット: なし
+
+ダッシュボード表示:
+  Used today: 5M tokens
+  Cost: $0 (free forever)
+  Status: ✅ Available
+```
+
+---
+
+## コスト見積もり
+
+### リアルタイムコストトラッキング
+
+```
+Dashboard → Costs → Today
+
+Subscription providers: $0
+  Claude Code: 15M tokens ($0, included)
+  Gemini CLI: 3M tokens ($0, free tier)
+
+Paid providers: $4.80
+  GLM-4.7: 8M tokens ($4.80)
+    Input: 6M × $0.60/1M = $3.60
+    Output: 2M × $2.20/1M = $4.40
+    Total: $4.80
+
+Free providers: $0
+  iFlow: 3M tokens ($0)
+
+Total today: $4.80
+```
+
+### 月次支出レポート
+
+```
+Dashboard → Costs → This Month (February 2026)
+
+Week 1 (Feb 1-7):
+  Subscription: $0 (80M tokens)
+  Paid: $15.20 (25M tokens)
+  Free: $0 (10M tokens)
+  Total: $15.20
+
+Week 2 (Feb 8-14):
+  Subscription: $0 (75M tokens)
+  Paid: $12.80 (20M tokens)
+  Free: $0 (8M tokens)
+  Total: $12.80
+
+Month to date: $28.00
+Projected (30 days): ~$120
+
+Breakdown by provider:
+  GLM-4.7: $22.00 (78%)
+  MiniMax M2.1: $6.00 (22%)
+  
+Average cost per 1M tokens: $0.62
+Savings vs ChatGPT API: 97% ($4,000 → $120)
+```
+
+### コスト予測
+
+```
+Dashboard → Costs → Projections
+
+Based on last 7 days usage:
+  Daily average: 50M tokens
+  Daily cost: $4.50
+
+Monthly projection:
+  Tokens: 1,500M (1.5B)
+  Cost: $135
+  
+Breakdown:
+  Subscription: 900M tokens ($0)
+  GLM-4.7: 450M tokens ($90)
+  MiniMax: 120M tokens ($24)
+  Free: 30M tokens ($0)
+
+Budget status:
+  Daily limit: $5 → 90% used today
+  Monthly limit: $150 → 90% projected
+  ⚠️ Warning: May exceed monthly budget
+```
+
+---
+
+## 使用量ダッシュボード
+
+### 概要統計
+
+```
+Dashboard → Analytics → Overview
+
+Today (Feb 4, 2026):
+  Requests: 1,234
+  Tokens: 26M
+  Cost: $4.80
+  Avg response time: 2.1s
+
+This week:
+  Requests: 8,456
+  Tokens: 180M
+  Cost: $28.00
+  Success rate: 99.2%
+
+This month:
+  Requests: 15,234
+  Tokens: 320M
+  Cost: $52.00
+  Top model: cc/claude-opus-4-5 (45%)
+```
+
+### モデル別使用量
+
+```
+Dashboard → Analytics → Models
+
+Top models (this month):
+1. cc/claude-opus-4-5: 145M tokens (45%)
+2. glm/glm-4.7: 95M tokens (30%)
+3. if/kimi-k2-thinking: 50M tokens (16%)
+4. minimax/MiniMax-M2.1: 20M tokens (6%)
+5. gc/gemini-3-flash: 10M tokens (3%)
+
+Cost breakdown:
+  cc/claude-opus: $0 (subscription)
+  glm/glm-4.7: $45.00
+  if/kimi-k2-thinking: $0 (free)
+  minimax/MiniMax-M2.1: $7.00
+  gc/gemini-3-flash: $0 (free)
+```
+
+### 時間別使用量
+
+```
+Dashboard → Analytics → Timeline
+
+Hourly usage (today):
+00:00 - 01:00: 0.5M tokens
+01:00 - 02:00: 0.2M tokens
+...
+08:00 - 09:00: 3.2M tokens (peak)
+09:00 - 10:00: 2.8M tokens
+...
+23:00 - 00:00: 0.8M tokens
+
+Peak hours: 08:00 - 12:00 (morning coding)
+Low hours: 00:00 - 06:00 (night)
+```
+
+### コンボ別使用量
+
+```
+Dashboard → Analytics → Combos
+
+premium-coding:
+  Requests: 456
+  Tokens: 12M
+  Cost: $2.40
+  
+  Breakdown:
+    cc/claude-opus: 8M tokens (67%, $0)
+    glm/glm-4.7: 3M tokens (25%, $1.80)
+    minimax/MiniMax-M2.1: 1M tokens (8%, $0.20)
+
+budget-combo:
+  Requests: 234
+  Tokens: 6M
+  Cost: $1.20
+  
+  Breakdown:
+    glm/glm-4.7: 4M tokens (67%, $2.40)
+    if/kimi-k2-thinking: 2M tokens (33%, $0)
+```
+
+---
+
+## アラートと通知
+
+### クォータアラート
+
+```
+Dashboard → Settings → Alerts
+
+Quota warnings:
+  ✅ Alert at 80% quota used
+  ✅ Alert at 90% quota used
+  ✅ Alert when quota exhausted
+  ✅ Notify when quota resets
+
+Delivery:
+  ✅ Dashboard notification
+  ✅ Email (optional)
+  ✅ Webhook (optional)
+```
+
+**通知例:**
+```
+⚠️ Claude Code quota 80% used
+   2.5h remaining (resets in 1h 30m)
+   
+⚠️ GLM-4.7 quota 90% used
+   1M tokens remaining (resets in 5h)
+   
+✅ Gemini CLI quota reset
+   1,000 requests available (daily limit)
+```
+
+### 予算アラート
+
+```
+Dashboard → Settings → Budget Alerts
+
+Daily budget: $5
+  ✅ Alert at 80% ($4)
+  ✅ Alert at 100% ($5)
+  ✅ Auto-switch to free tier when exceeded
+
+Monthly budget: $150
+  ✅ Alert at 50% ($75)
+  ✅ Alert at 80% ($120)
+  ✅ Alert at 100% ($150)
+```
+
+**通知例:**
+```
+⚠️ Daily budget 80% used
+   $4.00 / $5.00 spent today
+   
+⚠️ Monthly budget 50% reached
+   $75 / $150 spent this month
+   Projected: $135 (within budget)
+   
+🚨 Daily budget exceeded
+   $5.20 / $5.00 spent today
+   Auto-switched to free tier
+```
+
+### コスト異常検知
+
+```
+Dashboard → Settings → Anomaly Detection
+
+✅ Detect unusual spending patterns
+✅ Alert on cost spikes (>2× daily average)
+✅ Warn on quota exhaustion patterns
+
+Example alert:
+⚠️ Cost spike detected
+   Today: $12.50 (2.5× daily average)
+   Reason: High GLM-4.7 usage (20M tokens)
+   Suggestion: Check if primary models quota-exhausted
+```
+
+---
+
+## ベストプラクティス
+
+### 1. クォータを毎日モニター
+
+```
+日課:
+1. ダッシュボードクォータ概要を確認 (30秒)
+2. リセット時間を確認
+3. クォータ可用性に合わせて使用量を計画
+```
+
+**例:**
+```
+朝の確認:
+  ✅ Claude Code: 5時間利用可 (新鮮なリセット)
+  ✅ Gemini CLI: 1Kリクエスト利用可
+  ⚠️ GLM-4.7: 2Mトークン残 (午前10時リセット)
+  
+アクション: 朝の作業にClaude Codeを使用
+```
+
+### 2. 予算上限を設定
+
+```
+Dashboard → Settings → Budget:
+  Daily: $5 (使いすぎ防止)
+  Monthly: $150 (予算に整合)
+```
+
+**結果**: 上限到達時に自動的に無料階層へ切替。
+
+### 3. コンボ使用を最適化
+
+```
+Dashboard → Analytics → Combos:
+  どのモデルが最もよく使われているか確認
+  コストを最小化するためにコンボ順序を調整
+```
+
+**例:**
+```
+現在: cc/claude-opus → glm/glm-4.7
+  80% Claude経由 (良好)
+  20% GLM経由 ($12/月)
+
+最適化後: gc/gemini-3-flash → cc/claude-opus → glm/glm-4.7
+  50% Gemini経由 (無料)
+  40% Claude経由 (サブスクリプション)
+  10% GLM経由 ($6/月)
+  
+節約: $6/月
+```
+
+### 4. リセット時間を追跡
+
+```
+Dashboard → Quota → Reset Schedule:
+  Claude Code: 5時間ローリング + 週次月曜
+  Gemini CLI: 日次 00:00 UTC + 月次 1日
+  GLM-4.7: 毎日午前10時 北京時間
+  MiniMax: 5時間ローリングウィンドウ
+```
+
+**戦略**: クォータが新鮮な時にプロバイダーを使用。
+
+### 5. 月次レポートを確認
+
+```
+Dashboard → Analytics → Monthly Report:
+  Total tokens: 1.5B
+  Total cost: $120
+  Savings: 97% vs ChatGPT API
+  
+インサイト:
+  - 60% サブスクリプション経由の使用 ($0)
+  - 30% GLM経由 ($90)
+  - 10% 無料階層経由 ($0)
+  
+最適化:
+  - Gemini CLI使用を増やす (無料)
+  - GLM使用を減らす (高価)
+```
+
+---
+
+## APIアクセス
+
+### クォータステータスを取得
+
+```bash
+GET http://localhost:20128/api/quota
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "providers": [
+    {
+      "id": "cc",
+      "name": "Claude Code",
+      "quota": {
+        "used": 2.5,
+        "limit": 5,
+        "unit": "hours",
+        "percentage": 50
+      },
+      "reset": {
+        "type": "rolling",
+        "window": "5h",
+        "nextReset": "2026-02-04T06:45:00Z"
+      },
+      "cost": {
+        "today": 0,
+        "month": 0,
+        "currency": "USD"
+      }
+    },
+    {
+      "id": "glm",
+      "name": "GLM-4.7",
+      "quota": {
+        "used": 7000000,
+        "limit": 10000000,
+        "unit": "tokens",
+        "percentage": 70
+      },
+      "reset": {
+        "type": "daily",
+        "time": "10:00 AM UTC+8",
+        "nextReset": "2026-02-04T10:00:00+08:00"
+      },
+      "cost": {
+        "today": 4.20,
+        "month": 52.00,
+        "currency": "USD"
+      }
+    }
+  ]
+}
+```
+
+### 使用統計を取得
+
+```bash
+GET http://localhost:20128/api/usage?period=today
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "period": "today",
+  "date": "2026-02-04",
+  "summary": {
+    "requests": 1234,
+    "tokens": 26000000,
+    "cost": 4.80
+  },
+  "byModel": [
+    {
+      "model": "cc/claude-opus-4-5",
+      "requests": 456,
+      "tokens": 15000000,
+      "cost": 0
+    },
+    {
+      "model": "glm/glm-4.7",
+      "requests": 234,
+      "tokens": 8000000,
+      "cost": 4.80
+    }
+  ]
+}
+```
+
+---
+
+## トラブルシューティング
+
+**問題: クォータが0%を表示するがリクエストが失敗**
+
+**解決策:**
+1. プロバイダー接続を確認 (Dashboard → Providers)
+2. APIキーが有効か確認
+3. プロバイダーがダウンしているか確認 (ステータスページ)
+4. OAuthプロバイダーを再接続してみる
+
+**問題: コスト見積もりが正しくない**
+
+**解決策:**
+1. Dashboard → Settings → Pricing
+2. プロバイダーごとの料金が現在のレートと一致するか確認
+3. プロバイダーがレートを変更した場合は料金を更新
+4. 不一致が続く場合はサポートに連絡
+
+**問題: リセット時間が更新されない**
+
+**解決策:**
+1. ダッシュボードを更新 (F5)
+2. システム時刻が正しいか確認
+3. タイムゾーン設定を確認
+4. 問題が続く場合は9Routerを再起動
+
+**問題: アラートが受信されない**
+
+**解決策:**
+1. Dashboard → Settings → Alerts
+2. メールアドレスが正しいか確認
+3. スパムフォルダを確認
+4. 通知をテスト (Send Testボタン)
+
+---
+
+## 関連
+
+- [スマートルーティング](./smart-routing.md) - クォータに基づく自動フォールバック
+- [コンボ](./combos.md) - カスタムフォールバックチェーンを作成
diff --git a/gitbook/content/ja/features/smart-routing.md b/gitbook/content/ja/features/smart-routing.md
new file mode 100644
index 0000000..d7a3444
--- /dev/null
+++ b/gitbook/content/ja/features/smart-routing.md
@@ -0,0 +1,407 @@
+# スマートルーティングと自動フォールバック
+
+9Routerは3階層フォールバックシステムを使用して、最適な利用可能なプロバイダーへリクエストを自動的にルーティングします。クォータ制限やレート制限でコーディングが止まることはありません。
+
+---
+
+## 動作の仕組み
+
+9Routerは、既存のサブスクリプションを最大化し、コストを最小化し、24時間可用性を確保するため、インテリジェントなルーティングを使用します:
+
+```
+Request → 9Router → Tier 1を確認 (サブスクリプション)
+                     ↓ クォータ消費
+                     Tier 2を確認 (低価格)
+                     ↓ 予算上限
+                     Tier 3を確認 (無料)
+                     ↓
+                     Response
+```
+
+### 3階層フォールバックシステム
+
+**Tier 1: サブスクリプション (プライマリ)**
+- Claude Code (Pro/Max)
+- OpenAI Codex (Plus/Pro)
+- Gemini CLI (月18万無料)
+- GitHub Copilot
+- Antigravity (Google)
+
+**目標**: すでに支払っているサブスクリプションから価値を最大化。
+
+**Tier 2: 低価格 (バックアップ)**
+- GLM-4.7 (入力100万あたり$0.60)
+- MiniMax M2.1 (入力100万あたり$0.20)
+- Kimi K2 (月$9固定)
+
+**目標**: サブスクリプションクォータ切れ時の超低価格バックアップ (ChatGPT APIより約90%安い)。
+
+**Tier 3: 無料 (緊急時)**
+- iFlow (8モデル)
+- Qwen (3モデル)
+- Kiro (Claude無料)
+
+**目標**: 無制限コーディング用のゼロコストフォールバック。
+
+---
+
+## 自動切替
+
+9Routerはクォータをリアルタイムでモニターし、プロバイダーを自動的に切り替えます:
+
+### シナリオ1: サブスクリプションクォータ消費
+
+```
+ユーザーリクエスト → cc/claude-opus-4-5
+               ↓ クォータ消費 (5時間制限到達)
+               自動切替 → glm/glm-4.7
+               ↓ 日次クォータ消費
+               自動切替 → minimax/MiniMax-M2.1
+               ↓ 5時間クォータ消費
+               自動切替 → if/kimi-k2-thinking (無料)
+               ↓
+               レスポンス配信 ✅
+```
+
+**結果**: ダウンタイムゼロ、シームレスな体験。
+
+### シナリオ2: レート制限
+
+```
+ユーザーリクエスト → cx/gpt-5.2-codex
+               ↓ レート制限 (リクエストが多すぎ)
+               自動切替 → glm/glm-4.7
+               ↓
+               レスポンス配信 ✅
+```
+
+### シナリオ3: プロバイダー利用不可
+
+```
+ユーザーリクエスト → cc/claude-opus-4-5
+               ↓ プロバイダーエラー (503)
+               自動切替 → 次の利用可能なモデル
+               ↓
+               レスポンス配信 ✅
+```
+
+---
+
+## モデル選択ロジック
+
+9Routerは以下に基づいて最適なモデルを選択します:
+
+1. **クォータ可用性** - プロバイダーに残量があるか確認
+2. **コスト階層** - サブスクリプション → 低価格 → 無料を優先
+3. **リセットタイミング** - クォータリセット時を考慮
+4. **プロバイダー健全性** - エラーのあるプロバイダーをスキップ
+
+### 優先順位の例
+
+`cc/claude-opus-4-5` へのリクエストの場合:
+
+```
+1. Claude Codeクォータを確認
+   ✅ 利用可 → cc/claude-opus-4-5を使用
+   ❌ 消費 → ステップ2へ
+
+2. フォールバック階層を確認 (設定されている場合)
+   ✅ GLMクォータ利用可 → glm/glm-4.7を使用
+   ❌ 消費 → ステップ3へ
+
+3. 無料階層を確認
+   ✅ iFlow利用可 → if/kimi-k2-thinkingを使用
+   ❌ すべて消費 → クォータエラーを返す
+```
+
+---
+
+## 設定オプション
+
+### ダッシュボード設定
+
+**1. 自動フォールバックを有効/無効化**
+
+```
+Dashboard → Settings → Smart Routing
+→ 「Auto Fallback」をオン/オフに切替
+```
+
+- **オン** (デフォルト): 自動階層切替
+- **オフ**: 厳格モード、プライマリモデル利用不可時にエラーを返す
+
+**2. 予算上限を設定**
+
+```
+Dashboard → Settings → Budget Control
+→ 日次上限: $5
+→ 月次上限: $50
+```
+
+予算到達時、9Routerは自動的に無料階層へ切替。
+
+**3. フォールバック順序を設定**
+
+```
+Dashboard → Settings → Fallback Priority
+→ 各階層内でプロバイダーをドラッグして並べ替え
+```
+
+カスタム順序の例:
+```
+Tier 1: Gemini CLI → Claude Code → Codex
+Tier 2: MiniMax → GLM → Kimi
+Tier 3: iFlow → Kiro → Qwen
+```
+
+**4. クォータリセット通知**
+
+```
+Dashboard → Settings → Notifications
+→ クォータリセット時にメール
+→ 80%クォータ使用時にアラート
+```
+
+---
+
+## 例
+
+### 例1: 基本的な自動フォールバック
+
+**セットアップ:**
+```
+Model: cc/claude-opus-4-5-20251101
+Fallback: 自動 (デフォルト3階層)
+```
+
+**動作:**
+```
+朝 (新鮮なクォータ):
+  Request → cc/claude-opus-4-5 ✅
+
+午後 (クォータ消費):
+  Request → glm/glm-4.7 ✅ (自動切替)
+
+夕方 (GLMクォータ切れ):
+  Request → minimax/MiniMax-M2.1 ✅ (自動切替)
+
+深夜 (すべての有料クォータ切れ):
+  Request → if/kimi-k2-thinking ✅ (無料階層)
+```
+
+**コスト**: 月$5〜10の追加料金 (主にサブスクリプションでカバー)。
+
+### 例2: 予算意識のルーティング
+
+**セットアップ:**
+```
+Dashboard → Settings:
+  Daily budget: $2
+  Monthly budget: $20
+  Fallback: 有効
+```
+
+**動作:**
+```
+1〜15日 (予算内):
+  Requests → glm/glm-4.7 (低価格階層)
+  コスト: $1.50/日
+
+16日 (予算到達):
+  Requests → if/kimi-k2-thinking (無料階層)
+  コスト: $0
+
+翌月 (予算リセット):
+  Requests → 再びglm/glm-4.7
+```
+
+**結果**: 月$20を超えない、常に利用可能。
+
+### 例3: サブスクリプションのみモード
+
+**セットアップ:**
+```
+Dashboard → Settings:
+  Auto Fallback: オフ
+  Strict mode: オン
+```
+
+**動作:**
+```
+Request → cc/claude-opus-4-5
+  ✅ クォータ利用可 → 成功
+  ❌ クォータ消費 → エラーを返す (フォールバックなし)
+```
+
+**ユースケース**: 有料サブスクリプションのみを使用したい場合、追加コストなし。
+
+### 例4: 無料のみモード
+
+**セットアップ:**
+```
+Model: if/kimi-k2-thinking
+Fallback: qw/qwen3-coder-plus → kr/claude-sonnet-4.5
+```
+
+**動作:**
+```
+すべてのリクエスト → 無料階層のみ
+コスト: 永久に$0
+```
+
+**ユースケース**: 個人プロジェクト、学習、実験。
+
+---
+
+## ベストプラクティス
+
+### 1. サブスクリプション価値を最大化
+
+```
+戦略:
+- サブスクリプションモデルをTier 1に設定
+- ダッシュボードでクォータ使用量をモニター
+- サブスクリプション消費時のみ低価格階層を使用
+```
+
+**コンボ例:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 2. コストに最適化
+
+```
+戦略:
+- Gemini CLI無料階層を最初に使用 (月18万)
+- GLM/MiniMaxへフォールバック (超低価格)
+- 緊急時: iFlow (無料)
+```
+
+**コンボ例:**
+```
+gc/gemini-3-flash-preview → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 3. 品質に最適化
+
+```
+戦略:
+- 最高のモデルを使用 (Claude Opus、GPT-5.2)
+- 良質な低価格モデルへフォールバック (GLM-4.7)
+- 最後の手段: 無料階層
+```
+
+**コンボ例:**
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → glm/glm-4.7
+```
+
+### 4. 24時間可用性
+
+```
+戦略:
+- フォールバックに常に無料階層を含める
+- クォータリセット時間をモニター
+- プロバイダー間で使用量を分散
+```
+
+**コンボ例:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+**結果**: クォータ切れにならない、いつでもコーディング。
+
+---
+
+## クォータリセット戦略
+
+クォータリセット時間に合わせて使用量を計画:
+
+| プロバイダー | クォータリセット | 戦略 |
+|----------|-------------|----------|
+| **Claude Code** | 5時間 + 週次 | 朝、新鮮なクォータを使用 |
+| **Codex** | 5時間 + 週次 | Claudeクォータ切れ後に使用 |
+| **Gemini CLI** | 日次 (1K) + 月次 (18万) | 一日中使用 |
+| **GLM-4.7** | 毎日午前10時 | 夕方使用、翌朝リセット |
+| **MiniMax M2.1** | 5時間ローリング | いつでも使用、ローリングウィンドウを追跡 |
+| **iFlow/Qwen/Kiro** | 制限なし | 緊急時バックアップ |
+
+**日課の例:**
+```
+08:00 - 13:00: Claude Code (新鮮な5時間クォータ)
+13:00 - 18:00: Gemini CLI (1K/日クォータ)
+18:00 - 22:00: GLM-4.7 (低価格、午前10時リセット)
+22:00 - 08:00: MiniMaxまたはiFlow (5時間ローリングまたは無料)
+```
+
+---
+
+## モニタリングとアラート
+
+### ダッシュボードクォータトラッカー
+
+```
+Dashboard → Quota Overview:
+  Claude Code: 2.5h / 5h 残 (50%)
+  Gemini CLI: 今日 450 / 1000 リクエスト
+  GLM-4.7: 5M / 10M トークン (8時間後リセット)
+  MiniMax: 3M / 5M トークン (5時間ローリング)
+```
+
+### リアルタイム通知
+
+```
+Dashboard → Notifications:
+  ⚠️ Claude Codeクォータ80%使用 (1時間残)
+  ✅ GLM-4.7クォータリセット (10Mトークン利用可)
+  💰 日次予算50%使用 ($2.50 / $5)
+```
+
+### 使用統計
+
+```
+Dashboard → Analytics:
+  今日: 5000万トークン
+    - 3000万 Claude Code経由 (サブスクリプション)
+    - 1500万 GLM-4.7経由 ($9)
+    - 500万 iFlow経由 (無料)
+  
+  コスト: $9 (vs ChatGPT APIの$1000)
+  節約: 99%
+```
+
+---
+
+## トラブルシューティング
+
+**問題: "All providers quota exhausted"**
+
+**解決策:**
+1. ダッシュボードクォータトラッカーを確認
+2. クォータリセットを待つ (カウントダウン参照)
+3. フォールバックチェーンに無料階層を追加
+4. または予算上限を増やす
+
+**問題: "Too many fallback switches"**
+
+**解決策:**
+1. プライマリプロバイダーがダウンしているか確認
+2. クォータ上限を増やす (サブスクリプションをアップグレード)
+3. より安いプライマリモデルを使用 (Claudeの代わりにGLM)
+
+**問題: "Unexpected costs"**
+
+**解決策:**
+1. Dashboard → Analytics → 使用量を確認
+2. 日次/月次予算上限を設定
+3. クリティカルでないタスクは無料階層へ切替
+4. 無料フォールバック付きのコンボを使用
+
+---
+
+## 関連
+
+- [コンボ](./combos.md) - カスタムフォールバックチェーンを作成
+- [クォータトラッキング](./quota-tracking.md) - 使用量とコストをモニター
diff --git a/gitbook/content/ja/getting-started/installation.md b/gitbook/content/ja/getting-started/installation.md
new file mode 100644
index 0000000..9da1d96
--- /dev/null
+++ b/gitbook/content/ja/getting-started/installation.md
@@ -0,0 +1,478 @@
+# インストール
+
+トラブルシューティングのヒント付きの9Router詳細インストールガイド。
+
+---
+
+## 要件
+
+### システム要件
+
+- **Node.js**: バージョン 20.0.0以上
+- **npm**: バージョン 10.0.0以上 (Node.jsに付属)
+- **OS**: macOS、Linux、Windows (WSL推奨)
+- **ディスク容量**: インストールに約200MB
+
+### バージョンを確認
+
+```bash
+node --version
+# v20.x.x以上が表示されるはず
+
+npm --version
+# 10.x.x以上が表示されるはず
+```
+
+**Node.jsがない場合?** [nodejs.org](https://nodejs.org/)からインストール
+
+---
+
+## インストール方法
+
+### 方法1: グローバルインストール (推奨)
+
+どこからでも使用できるように9Routerをグローバルインストール:
+
+```bash
+npm install -g 9router
+```
+
+**9Routerを起動:**
+
+```bash
+9router
+```
+
+**利点:**
+- ✅ どのディレクトリからでも実行
+- ✅ シンプルなコマンド: `9router`
+- ✅ `npm update -g 9router` で自動更新
+
+### 方法2: ローカルインストール
+
+特定のプロジェクトにインストール:
+
+```bash
+mkdir my-9router
+cd my-9router
+npm install 9router
+```
+
+**9Routerを起動:**
+
+```bash
+npx 9router
+```
+
+**利点:**
+- ✅ プロジェクトごとに分離
+- ✅ プロジェクトごとのバージョン管理
+- ✅ グローバル名前空間の汚染なし
+
+### 方法3: ソースから (開発)
+
+GitHubからクローンしてビルド:
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install
+npm run build
+npm start
+```
+
+**利点:**
+- ✅ 最新の開発機能
+- ✅ 開発に貢献可能
+- ✅ カスタム変更
+
+---
+
+## 初回実行
+
+### サーバーを起動
+
+```bash
+9router
+```
+
+**何が起こるか:**
+1. サーバーが `http://localhost:20128` で起動
+2. ダッシュボードが自動的にブラウザで開く
+3. `~/.9router` にデータディレクトリが作成される
+4. APIキーが自動生成される
+
+### ダッシュボードログイン
+
+**デフォルト認証情報:**
+- パスワード: `123456`
+
+**⚠️ パスワードをすぐに変更:**
+1. ダッシュボードにログイン
+2. Settings → Change Password
+3. 強力なパスワードを使用
+
+### APIキーを取得
+
+```
+Dashboard → Settings → API Keys
+→ APIキーをコピー
+→ CLIツールで使用
+```
+
+**APIキー形式の例:**
+```
+9r_1234567890abcdef1234567890abcdef
+```
+
+---
+
+## インストールを確認
+
+### サーバーステータスを確認
+
+```bash
+curl http://localhost:20128/health
+```
+
+**期待されるレスポンス:**
+```json
+{
+  "status": "ok",
+  "version": "1.0.0"
+}
+```
+
+### 利用可能なモデルを一覧表示
+
+```bash
+curl http://localhost:20128/v1/models \
+  -H "Authorization: Bearer your-api-key"
+```
+
+**期待されるレスポンス:**
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "cc/claude-opus-4-5-20251101",
+      "object": "model",
+      "created": 1234567890,
+      "owned_by": "claude-code"
+    }
+  ]
+}
+```
+
+### チャットコンプリーションをテスト
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "cc/claude-opus-4-5-20251101",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+---
+
+## 設定
+
+### 環境変数
+
+`.env` ファイルを作成するか、環境変数を設定:
+
+```bash
+# セキュリティ (本番環境では必須)
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+
+# ストレージ
+export DATA_DIR="~/.9router"
+
+# サーバー
+export PORT="20128"
+export NODE_ENV="production"
+
+# ロギング
+export ENABLE_REQUEST_LOGS="false"
+```
+
+### データディレクトリ
+
+**デフォルトの場所:** `~/.9router`
+
+**内容:**
+```
+~/.9router/
+  ├── db.json           # データベース (プロバイダー、コンボ、使用量)
+  ├── api-keys.json     # APIキー
+  └── logs/             # リクエストログ (有効化されている場合)
+```
+
+**場所を変更:**
+
+```bash
+export DATA_DIR="/custom/path"
+9router
+```
+
+### ポート設定
+
+**デフォルトポート:** `20128`
+
+**ポートを変更:**
+
+```bash
+export PORT="3000"
+9router
+```
+
+**またはコマンドラインで:**
+
+```bash
+9router --port 3000
+```
+
+---
+
+## トラブルシューティング
+
+### ポートがすでに使用されている
+
+**エラー:**
+```
+Error: listen EADDRINUSE: address already in use :::20128
+```
+
+**解決策1: 既存のプロセスを終了**
+
+```bash
+# ポート20128を使用しているプロセスを検索
+lsof -i :20128
+
+# プロセスを終了
+kill -9 <PID>
+```
+
+**解決策2: 別のポートを使用**
+
+```bash
+9router --port 3000
+```
+
+### Permission Denied
+
+**エラー:**
+```
+Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
+```
+
+**解決策: sudoを使用 (非推奨) またはnpm権限を修正**
+
+```bash
+# npm権限を修正 (推奨)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# 再度インストール
+npm install -g 9router
+```
+
+### Node.jsバージョンが古すぎる
+
+**エラー:**
+```
+Error: The engine "node" is incompatible with this module
+```
+
+**解決策: Node.jsを更新**
+
+```bash
+# nvmを使用 (推奨)
+nvm install 20
+nvm use 20
+
+# またはnodejs.orgからダウンロード
+```
+
+### ダッシュボードが開かない
+
+**問題:** ダッシュボードが自動的に開かない
+
+**解決策1: 手動で開く**
+
+```
+http://localhost:20128
+```
+
+**解決策2: ファイアウォールを確認**
+
+```bash
+# macOS: システム環境設定 → セキュリティでNode.jsを許可
+# Linux: iptablesを確認
+# Windows: Windowsファイアウォールを確認
+```
+
+### プロバイダーに接続できない
+
+**問題:** OAuthログインが失敗、またはAPIキーが無効
+
+**解決策1: インターネット接続を確認**
+
+```bash
+ping google.com
+```
+
+**解決策2: プロバイダーのステータスを確認**
+
+- Claude Code: [status.anthropic.com](https://status.anthropic.com)
+- OpenAI: [status.openai.com](https://status.openai.com)
+- Gemini: [status.cloud.google.com](https://status.cloud.google.com)
+
+**解決策3: APIキーを再生成**
+
+```
+Dashboard → Provider → Disconnect → Reconnect
+```
+
+### 高メモリ使用量
+
+**問題:** 9RouterがRAMを使いすぎている
+
+**解決策: サーバーを再起動**
+
+```bash
+# 停止
+pkill -f 9router
+
+# 起動
+9router
+```
+
+**または自動再起動にPM2を使用:**
+
+```bash
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+```
+
+---
+
+## デプロイメントオプション
+
+### ローカル開発
+
+```bash
+npm install -g 9router
+9router
+```
+
+**ユースケース:** 個人コーディング、テスト
+
+### VPS/クラウドサーバー
+
+```bash
+# インストール
+npm install -g 9router
+
+# 設定
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+# PM2で起動
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+pm2 startup
+```
+
+**ユースケース:** チームアクセス、リモートコーディング
+
+### Docker
+
+```bash
+docker pull 9router/9router:latest
+
+docker run -d \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret" \
+  -e INITIAL_PASSWORD="your-password" \
+  -v 9router-data:/root/.9router \
+  --name 9router \
+  9router/9router:latest
+```
+
+**ユースケース:** コンテナデプロイ、Kubernetes
+
+### リバースプロキシ (Nginx)
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        
+        # SSE support for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+**ユースケース:** HTTPS、カスタムドメイン、ロードバランシング
+
+---
+
+## アンインストール
+
+### グローバルインストールを削除
+
+```bash
+npm uninstall -g 9router
+```
+
+### データディレクトリを削除
+
+```bash
+rm -rf ~/.9router
+```
+
+### 設定を削除
+
+```bash
+# シェル設定から環境変数を削除
+nano ~/.bashrc  # または ~/.zshrc
+# 9router関連のエクスポートを削除
+```
+
+---
+
+## 次のステップ
+
+- [スタートガイド](../getting-started.md) - プロバイダーを接続してコーディング開始
+- [機能](../features/) - クォータトラッキング、コンボ、デプロイを確認
+- [トラブルシューティング](../troubleshooting.md) - 一般的な問題の修正
+
+---
+
+## ヘルプが必要?
+
+- **ウェブサイト**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
diff --git a/gitbook/content/ja/getting-started/quick-start.md b/gitbook/content/ja/getting-started/quick-start.md
new file mode 100644
index 0000000..cea02bf
--- /dev/null
+++ b/gitbook/content/ja/getting-started/quick-start.md
@@ -0,0 +1,247 @@
+# はじめに
+
+9Routerを5分で起動し、AIリクエストをインテリジェントにルーティングし始めましょう。
+
+---
+
+## クイックスタート
+
+### 1. インストール
+
+```bash
+npm install -g 9router
+```
+
+**要件:** Node.js 20+ ([インストール詳細](getting-started/installation.md))
+
+### 2. 起動
+
+```bash
+9router
+```
+
+🎉 **ダッシュボードが自動的に開きます** (`http://localhost:20128`)
+
+- デフォルトパスワード: `123456` (ダッシュボードで変更)
+- APIキーは自動生成
+- プロバイダー接続の準備完了
+
+### 3. プロバイダーを接続
+
+プロバイダーを接続する方法は3つあります:
+
+#### オプションA: OAuth(サブスクリプションプロバイダー)
+
+**最適:** Claude Code、Codex、Gemini CLI、GitHub Copilot
+
+```
+Dashboard → Providers → Connect [Provider]
+→ OAuthログイン → トークン自動更新
+→ クォータトラッキング有効化
+```
+
+**例: Claude Code**
+1. 「Connect Claude Code」をクリック
+2. Claudeアカウントでログイン
+3. 9Routerを認可
+4. ✅ 完了! モデルを使用: `cc/claude-opus-4-5-20251101`
+
+#### オプションB: APIキー(低価格プロバイダー)
+
+**最適:** GLM、MiniMax、Kimi、OpenRouter
+
+```
+Dashboard → Providers → Add API Key
+→ プロバイダーを選択
+→ APIキーを貼り付け
+→ 保存
+```
+
+**例: GLM-4.7**
+1. [Zhipu AI](https://open.bigmodel.cn/)でサインアップ
+2. Coding PlanからAPIキーを取得
+3. Dashboard → Add API Key → Provider: `glm` → キーを貼り付け
+4. ✅ 完了! モデルを使用: `glm/glm-4.7`
+
+#### オプションC: 無料プロバイダー(コストなし)
+
+**最適:** iFlow、Qwen、Kiro
+
+```
+Dashboard → Providers → Connect [Free Provider]
+→ デバイスコードまたはOAuth
+→ 無制限利用
+```
+
+**例: iFlow**
+1. 「Connect iFlow」をクリック
+2. iFlowアカウントでログイン
+3. 認可
+4. ✅ 完了! 8モデルを使用: `if/kimi-k2-thinking`、`if/qwen3-coder-plus`など
+
+---
+
+## 4. CLIツールで使用
+
+コーディングツールを9Routerに向けます:
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [9routerダッシュボードから取得]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Claude Desktop
+
+`~/.claude/config.json`を編集:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [ダッシュボードから取得]
+Model: cc/claude-opus-4-5-20251101
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+---
+
+## 5. スマートコンボを作成(オプション)
+
+コンボはモデル間の自動フォールバックを可能にします:
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101 (サブスクリプション優先)
+  2. glm/glm-4.7 (低価格バックアップ、100万あたり$0.6)
+  3. if/kimi-k2-thinking (無料フォールバック)
+
+CLIで使用: premium-coding
+```
+
+**動作:**
+1. 最初にClaude Opusを試行(サブスクリプション)
+2. クォータ消費時 → GLM-4.7(超低価格)
+3. 予算上限時 → iFlow(無料)
+4. ダウンタイムゼロ、自動切替!
+
+---
+
+## 利用可能なモデル
+
+### サブスクリプションモデル(最初に最大化)
+
+**Claude Code (`cc/`)** - Pro/Maxサブスクリプション:
+- `cc/claude-opus-4-5-20251101` - Claude 4.5 Opus
+- `cc/claude-sonnet-4-5-20250929` - Claude 4.5 Sonnet
+- `cc/claude-haiku-4-5-20251001` - Claude 4.5 Haiku
+
+**Codex (`cx/`)** - Plus/Proサブスクリプション:
+- `cx/gpt-5.2-codex` - GPT 5.2 Codex
+- `cx/gpt-5.1-codex-max` - GPT 5.1 Codex Max
+
+**Gemini CLI (`gc/`)** - 月18万無料:
+- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
+- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
+
+**GitHub Copilot (`gh/`)** - サブスクリプション:
+- `gh/gpt-5` - GPT-5
+- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
+
+### 低価格モデル(バックアップ)
+
+**GLM (`glm/`)** - 100万あたり$0.6/$2.2:
+- `glm/glm-4.7` - GLM 4.7(毎日午前10時リセット)
+
+**MiniMax (`minimax/`)** - 100万あたり$0.20/$1.00:
+- `minimax/MiniMax-M2.1` - MiniMax M2.1(5時間リセット)
+
+**Kimi (`kimi/`)** - 月$9(1000万トークン):
+- `kimi/kimi-latest` - Kimi Latest
+
+### 無料モデル(緊急時)
+
+**iFlow (`if/`)** - 8モデル無料:
+- `if/kimi-k2-thinking` - Kimi K2 Thinking
+- `if/qwen3-coder-plus` - Qwen3 Coder Plus
+- `if/glm-4.7` - GLM 4.7
+- `if/deepseek-r1` - DeepSeek R1
+
+**Qwen (`qw/`)** - 3モデル無料:
+- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
+- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
+
+**Kiro (`kr/`)** - 2モデル無料:
+- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
+- `kr/claude-haiku-4.5` - Claude Haiku 4.5
+
+---
+
+## コスト最適化戦略
+
+### 月予算: $10〜20/月
+
+```
+1. クイックタスクにGemini CLI無料プラン(月18万)を使用
+2. Claude Codeサブスクリプションのクォータを完全利用(すでに支払い済み)
+3. クォータ切れ時はGLM(100万あたり$0.6)へフォールバック
+4. 緊急時: MiniMax M2.1(100万あたり$0.20)またはiFlow(無料)
+
+実例(月1億トークン):
+  Gemini CLI経由で6000万: $0(無料プラン)
+  Claude Code経由で3000万: $0(既存サブスクリプション)
+  GLM経由で800万: $4.80
+  MiniMax経由で200万: $0.40
+  合計: 月$5.20 + 既存サブスクリプション
+```
+
+### クォータリセット戦略
+
+```
+日課:
+1. 朝: Claude Codeの新しいクォータ(5時間リセット)
+2. 午後: Gemini CLIへ切替(1K/日)
+3. 夕方: GLM日次クォータ(翌朝10時リセット)
+4. 深夜: MiniMax(5時間ローリング)またはiFlow(無料)
+
+→ 最小の追加コストで24時間コーディング!
+```
+
+---
+
+## 次のステップ
+
+- [インストール詳細](getting-started/installation.md) - 要件、トラブルシューティング
+- [機能](features/) - クォータトラッキング、コンボ、デプロイを確認
+- [FAQ](faq.md) - よくある質問と回答
+- [トラブルシューティング](troubleshooting.md) - 一般的な問題の修正
+
+---
+
+## ヘルプが必要?
+
+- **ウェブサイト**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
diff --git a/gitbook/content/ja/index.md b/gitbook/content/ja/index.md
new file mode 100644
index 0000000..d3cbdcf
--- /dev/null
+++ b/gitbook/content/ja/index.md
@@ -0,0 +1,164 @@
+# 9Routerへようこそ
+
+**Claude、Codex、Geminiを無料で利用 • 100万トークンあたり$0.20からの超低価格な代替手段**
+
+9Routerは、インテリジェントなルーティングと自動フォールバックを通じて、サブスクリプションの価値を最大化し、コストを最小限に抑えるAIモデルルーターです。
+
+---
+
+## 9Routerとは?
+
+9Routerは、コーディングツール(Cursor、Cline、Claude Desktop)とAIプロバイダーの間に位置するスマートプロキシです。クォータ、コスト、可用性に基づいて、リクエストを最適なモデルへ自動的にルーティングします。
+
+**お金を無駄にしないために:**
+- ❌ サブスクリプションのクォータが毎月未使用のまま失効
+- ❌ レート制限でコーディングが中断
+- ❌ 高額なAPI(プロバイダーあたり月$20〜50)
+- ❌ プロバイダー間の手動切り替え
+
+**価値を最大化するために:**
+- ✅ **サブスクリプションを最大限活用** - Claude Code、Codex、Geminiのクォータを余すことなく追跡・利用
+- ✅ **無料で利用可能** - CLI経由でiFlow、Qwen、Kiroモデルにアクセス
+- ✅ **超低価格バックアップ** - GLM(100万あたり$0.6)、MiniMax M2.1(100万あたり$0.20)
+- ✅ **スマートフォールバック** - サブスクリプション → 低価格 → 無料へ自動切替
+
+---
+
+## 主な機能
+
+### 🔄 スマート3階層フォールバック
+
+```
+一度セットアップすれば、コーディングが止まらない:
+
+Tier 1 (サブスクリプション): Claude Code → Codex → Gemini
+  ↓ クォータ消費
+Tier 2 (低価格): GLM-4.7 → MiniMax M2.1 → Kimi
+  ↓ 予算上限
+Tier 3 (無料): iFlow → Qwen → Kiro
+
+→ 自動切替、ダウンタイムゼロ!
+```
+
+### 📊 クォータトラッキング
+
+- プロバイダーごとのリアルタイムトークン消費
+- リセットカウントダウン(5時間、毎日、毎週、毎月)
+- 有料プランのコスト見積もり
+- 月次支出レポート
+
+### 🎯 ユニバーサルCLIサポート
+
+カスタムOpenAIエンドポイントをサポートするあらゆるツールで動作:
+
+✅ **Cursor** • **Cline** • **Claude Desktop** • **Codex** • **RooCode** • **Continue** • **OpenAI互換ツール全般**
+
+### 💰 コスト最適化
+
+**実例(月1億トークン):**
+```
+Gemini CLI経由で6000万: $0(無料プラン)
+Claude Code経由で3000万: $0(既存サブスクリプション)
+GLM経由で800万: $4.80
+MiniMax経由で200万: $0.40
+合計: 月$5.20 vs ChatGPT APIの$2000!
+```
+
+---
+
+## なぜ9Routerを選ぶのか?
+
+### サブスクリプションを最大化
+
+すでにClaude Code(月$20〜100)やCodex(月$20〜200)に支払っていますか? 完全な価値を引き出しましょう:
+
+- クォータ使用量をリアルタイムで追跡
+- クォータリセット(5時間、週次)時に自動切替
+- 失効前にすべてのトークンを使い切る
+- Gemini CLI: 月18万コンプリーション**無料**
+
+### 超低価格バックアップ
+
+サブスクリプションのクォータが切れたら、わずかな金額で:
+
+| プロバイダー | 100万トークンあたりのコスト | リセット |
+|----------|-------------------|-------|
+| **GLM-4.7** | 入力$0.60 / 出力$2.20 | 毎日午前10時 |
+| **MiniMax M2.1** | 入力$0.20 / 出力$1.00 | 5時間ローリング |
+| **Kimi K2** | 月$9(1000万トークン) | 月次 |
+
+**ChatGPT API(100万あたり$20)より約90%安い!**
+
+### 永久無料フォールバック
+
+他がすべてクォータ制限に達した時の緊急バックアップ:
+
+- **iFlow**: 8モデル(Kimi K2、Qwen3 Coder Plus、GLM 4.7、MiniMax M2)
+- **Qwen**: 3モデル(Qwen3 Coder Plus/Flash、Vision)
+- **Kiro**: Claude Sonnet 4.5、Haiku 4.5(AWS Builder ID)
+
+---
+
+## クイックスタート
+
+2分で始められます:
+
+```bash
+# グローバルインストール
+npm install -g 9router
+
+# 起動(ダッシュボードが自動で開きます)
+9router
+```
+
+🎉 **ダッシュボードが開く** → プロバイダーを接続 → コーディング開始!
+
+**CLIツールで使う:**
+
+```
+Endpoint: http://localhost:20128/v1
+API Key: [ダッシュボードから取得]
+Model: cc/claude-opus-4-5-20251101
+```
+
+[→ 完全なスタートガイド](getting-started.md)
+
+---
+
+## ユースケース
+
+### 個人開発者向け
+
+- Claude Code/Codexサブスクリプションを最大限活用
+- Gemini CLI無料プラン(月18万)を活用
+- 超低価格モデル(100万あたり$0.20)へフォールバック
+- レート制限なしで24時間コーディング
+
+### チーム向け
+
+- VPS/クラウドにデプロイして共有アクセス
+- チームの支出をリアルタイムで追跡
+- 階層ごとに予算上限を設定
+- 集中型のプロバイダー管理
+
+### モバイル/リモートコーディング向け
+
+- クラウドデプロイ(https://9router.com)を使用
+- iPad、スマホ、どこからでもアクセス
+- localhost制限なし
+- Cloudflareエッジネットワーク(300以上のロケーション)
+
+---
+
+## 次は?
+
+- [スタートガイド](getting-started.md) - 5分でインストールと設定
+- [インストールガイド](getting-started/installation.md) - 詳細なセットアップ手順
+- [機能](features/) - すべての機能を確認
+- [FAQ](faq.md) - よくある質問
+
+---
+
+<div align="center">
+  <sub>AIの価値を最大化する開発者のために ❤️ で構築</sub>
+</div>
diff --git a/gitbook/content/ja/integration/claude-code.md b/gitbook/content/ja/integration/claude-code.md
new file mode 100644
index 0000000..7c3e814
--- /dev/null
+++ b/gitbook/content/ja/integration/claude-code.md
@@ -0,0 +1,109 @@
+# Claude Code統合
+
+9RouterをClaude Code CLIと統合し、AnthropicのAPIリクエストを9Routerのインテリジェントルーティングシステム経由でルーティングします。
+
+## 前提条件
+
+- Claude Code CLIがインストール済み
+- 9Routerがローカルで動作中、またはクラウドエンドポイントが設定済み
+- 9RouterダッシュボードからのAPIキー
+
+## セットアップ
+
+### 1. 環境変数を設定
+
+シェル設定ファイル (`~/.bashrc`、`~/.zshrc`、または `~/.bash_profile`) で以下の環境変数を設定:
+
+```bash
+# 9Router用Base URL
+export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
+
+# オプション: エイリアス用のデフォルトモデルを設定
+export ANTHROPIC_DEFAULT_OPUS_MODEL="cc/claude-opus-4-5-20251101"
+export ANTHROPIC_DEFAULT_SONNET_MODEL="cc/claude-sonnet-4-5-20250929"
+export ANTHROPIC_DEFAULT_HAIKU_MODEL="cc/claude-haiku-4-5-20251001"
+```
+
+### 2. シェル設定をリロード
+
+```bash
+source ~/.zshrc  # または ~/.bashrc
+```
+
+### 3. 設定を確認
+
+環境変数が正しく設定されているか確認:
+
+```bash
+echo $ANTHROPIC_BASE_URL
+```
+
+## モデルエイリアス
+
+Claude Codeは9Routerモデルにマッピングされる以下のモデルエイリアスをサポート:
+
+| エイリアス | モデル | 環境変数 |
+|-------|-------|---------------------|
+| `opus` | Claude Opus 4.5 | `ANTHROPIC_DEFAULT_OPUS_MODEL` |
+| `sonnet` | Claude Sonnet 4.5 | `ANTHROPIC_DEFAULT_SONNET_MODEL` |
+| `haiku` | Claude Haiku 4.5 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` |
+
+## 使用例
+
+### モデルエイリアスを使用
+
+```bash
+# Opusモデルを使用
+claude --model opus "Explain quantum computing"
+
+# Sonnetモデルを使用
+claude --model sonnet "Write a Python function"
+
+# Haikuモデルを使用
+claude --model haiku "Quick code review"
+```
+
+### フルモデル名を使用
+
+```bash
+claude --model cc/claude-opus-4-5-20251101 "Your prompt here"
+```
+
+## 設定ファイル
+
+Claude Codeは設定を `~/.claude/settings.json` に保存します。必要に応じてこのファイルを手動で編集できます:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "defaultModel": "sonnet"
+}
+```
+
+## トラブルシューティング
+
+### 接続の問題
+
+接続エラーが発生した場合:
+
+1. 9Routerが動作中か確認: `curl http://localhost:20128/health`
+2. 環境変数が正しく設定されているか確認
+3. ファイアウォールがポート20128をブロックしていないか確認
+
+### モデルが見つからない
+
+「model not found」エラーが発生した場合:
+
+1. モデル名が9Routerの設定と一致しているか確認
+2. 9Routerダッシュボードでプロバイダー接続がアクティブか確認
+3. 接続されたプロバイダーでモデルが利用可能か確認
+
+## クラウドエンドポイント
+
+localhostの代わりに9Routerクラウドエンドポイントを使用するには:
+
+```bash
+export ANTHROPIC_BASE_URL="https://9router.com"
+```
+
+9RouterクラウドダッシュボードでAPIキーが設定されていることを確認してください。
diff --git a/gitbook/content/ja/integration/cline.md b/gitbook/content/ja/integration/cline.md
new file mode 100644
index 0000000..3ef951d
--- /dev/null
+++ b/gitbook/content/ja/integration/cline.md
@@ -0,0 +1,201 @@
+# Cline統合
+
+9RouterをCline VSCode拡張機能と統合し、AIリクエストを9Routerのインテリジェントルーティングシステム経由でルーティングします。
+
+## 前提条件
+
+- Visual Studio Codeがインストール済み
+- VSCodeマーケットプレイスからCline拡張機能がインストール済み
+- 9Routerがローカルで動作中、またはクラウドエンドポイントが設定済み
+- 9RouterダッシュボードからのAPIキー
+
+## セットアップ
+
+### 1. Cline設定を開く
+
+1. Visual Studio Codeを開く
+2. Cline拡張機能パネルを開く (サイドバーのClineアイコンをクリック)
+3. Clineパネルの **Settings** アイコン (歯車アイコン) をクリック
+
+### 2. APIプロバイダーを選択
+
+1. Cline設定で **API Provider** ドロップダウンを見つける
+2. リストから **Ollama** を選択
+   - 注: OpenAIスタイルAPIと互換性があるためOllamaプロバイダータイプを使用します
+
+### 3. Base URLを設定
+
+Base URLを9Routerエンドポイントに設定:
+
+**ローカル9Router用:**
+```
+http://localhost:20128/v1
+```
+
+**クラウド9Router用:**
+```
+https://9router.com
+```
+
+**手順:**
+1. **Base URL** フィールドに9Routerエンドポイントを入力
+2. 末尾に `/v1` を必ず含める
+
+### 4. APIキーを追加
+
+1. **API Key** フィールドに9Router APIキーを入力
+2. APIキーは9Routerダッシュボードの **Settings → API Keys** で確認できます
+3. キーは `sk-9router-` で始まります
+
+### 5. モデルを選択
+
+1. **Model** ドロップダウンで、次のいずれかを実行:
+   - 利用可能なモデルから選択 (Clineが自動検出した場合)
+   - 9Router設定からモデル名を手動で入力
+
+2. 一般的なモデル名:
+   - `gpt-4`
+   - `gpt-4o`
+   - `claude-opus-4-5`
+   - `claude-sonnet-4-5`
+   - `gemini-2.0-flash`
+
+### 6. 設定を保存
+
+**Save** をクリックするか、設定パネルを閉じます。Clineは設定を自動的に保存します。
+
+## 設定例
+
+Cline設定は次のようになります:
+
+```
+API Provider: Ollama
+Base URL: http://localhost:20128/v1
+API Key: sk-9router-xxxxxxxxxxxxx
+Model: gpt-4
+```
+
+## 利用可能なモデル
+
+9Routerダッシュボードで設定されたモデルを使用できます。一般的な例:
+
+| モデル名 | プロバイダー | 説明 |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## 使用法
+
+### AIとチャット
+
+1. VSCodeでClineパネルを開く
+2. チャット入力にメッセージを入力
+3. Enterを押して送信
+4. Clineは9Routerを使用してリクエストを処理
+
+### コード生成
+
+1. Clineにコード生成を依頼: 「Create a React component for a login form」
+2. Clineは9Routerを使用してコードを生成
+3. 生成されたコードを確認して受け入れる
+
+### コード説明
+
+1. エディタでコードを選択
+2. Clineに質問: 「Explain this code」
+3. 9Router経由でAIによる説明を取得
+
+### ファイル操作
+
+1. Clineにファイルの作成、変更、削除を依頼
+2. Clineは9Routerを使用してコンテキストを理解し変更を加える
+3. 受け入れる前に変更を確認
+
+## トラブルシューティング
+
+### 「Connection Failed」エラー
+
+1. 9Routerが動作中か確認: `curl http://localhost:20128/health`
+2. Base URLが正しく、`/v1` を含むことを確認
+3. ファイアウォールがポート20128をブロックしていないか確認
+4. VSCodeを再起動してみる
+
+### 「Invalid API Key」エラー
+
+1. 9RouterダッシュボードでAPIキーを確認
+2. `sk-9router-` プレフィックスを含むキー全体をコピーしたか確認
+3. APIキーが期限切れでないか確認
+4. 新しいAPIキーを再生成してみる
+
+### 「Model Not Found」エラー
+
+1. モデル名が9Router設定と正確に一致するか確認
+2. 9Routerダッシュボードでプロバイダー接続がアクティブか確認
+3. 接続されたプロバイダーでモデルが利用可能か確認
+4. フルモデル名を使用してみる (例: `gpt-4` の代わりに `openai/gpt-4`)
+
+### Clineが応答しない
+
+1. エラーメッセージについてCline出力パネルを確認
+2. 9Routerインスタンスが動作中で正常か確認
+3. VSCodeウィンドウをリロードしてみる (Cmd/Ctrl + Shift + P → 「Reload Window」)
+4. エラーについて9Routerログを確認
+
+## 高度な設定
+
+### クラウドエンドポイントを使用
+
+localhostの代わりに9Routerクラウドエンドポイントを使用:
+
+1. Cline設定で、Base URLを設定: `https://9router.com`
+2. 9RouterクラウドダッシュボードでAPIキーが設定されていることを確認
+3. クラウドエンドポイントがアクティブでアクセス可能か確認
+
+### 複数のモデル
+
+モデルをすばやく切り替えることができます:
+
+1. Cline設定を開く
+2. **Model** フィールドを別のモデルに変更
+3. 保存して新しいモデルでチャットを続行
+
+### カスタムタイムアウト
+
+大きなリクエストでタイムアウトの問題が発生した場合:
+
+1. VSCode設定を開く (Cmd/Ctrl + ,)
+2. 「Cline timeout」を検索
+3. タイムアウト値を増やす (デフォルトは通常30秒)
+
+## ベストプラクティス
+
+1. **適切なモデルを使用**: シンプルなタスクには高速モデル (HaikuやFlash) を、複雑なタスクには強力なモデル (OpusやGPT-4) を選択
+2. **使用量をモニター**: 9Routerダッシュボードで使用統計とコストを確認
+3. **コンテキスト管理**: トークン使用量を減らすため、会話を焦点を絞ったものに保つ
+4. **モデル切替**: タスクの複雑さに基づいてモデルを切り替え、コストとパフォーマンスを最適化
+5. **APIキーセキュリティ**: APIキーをバージョン管理にコミットしない
+
+## 9Router機能との統合
+
+### モデルルーティング
+
+9Routerは以下に基づいて最適な利用可能なプロバイダーにリクエストを自動的にルーティング:
+- モデル可用性
+- プロバイダーヘルスステータス
+- コスト最適化
+- ロードバランシング
+
+### フォールバックサポート
+
+プロバイダーが失敗した場合、9Routerは自動的にダッシュボードで設定された代替プロバイダーにフォールバックします。
+
+### 使用量トラッキング
+
+9Routerダッシュボード経由でCline使用量をモニター:
+- 総リクエスト数
+- トークン使用量
+- モデルごとのコスト
+- プロバイダー分布
diff --git a/gitbook/content/ja/integration/codex.md b/gitbook/content/ja/integration/codex.md
new file mode 100644
index 0000000..61c9d66
--- /dev/null
+++ b/gitbook/content/ja/integration/codex.md
@@ -0,0 +1,136 @@
+# OpenAI Codex CLI統合
+
+9RouterをOpenAI Codex CLIと統合し、OpenAI APIリクエストを9Routerのインテリジェントルーティングシステム経由でルーティングします。
+
+## 前提条件
+
+- OpenAI Codex CLIがインストール済み
+- 9Routerがローカルで動作中、またはクラウドエンドポイントが設定済み
+- 9RouterダッシュボードからのAPIキー
+
+## セットアップ
+
+### 1. 環境変数を設定
+
+シェル設定ファイル (`~/.bashrc`、`~/.zshrc`、または `~/.bash_profile`) で以下の環境変数を設定:
+
+```bash
+# 9Router用Base URL
+export OPENAI_BASE_URL="http://localhost:20128/v1"
+
+# 9RouterダッシュボードからのAPIキー
+export OPENAI_API_KEY="your-9router-api-key"
+```
+
+### 2. シェル設定をリロード
+
+```bash
+source ~/.zshrc  # または ~/.bashrc
+```
+
+### 3. 設定を確認
+
+環境変数が正しく設定されているか確認:
+
+```bash
+echo $OPENAI_BASE_URL
+echo $OPENAI_API_KEY
+```
+
+## 利用可能なモデル
+
+9Routerは以下のCodexモデルを提供します:
+
+| モデルID | 説明 |
+|----------|-------------|
+| `cx/gpt-5.2-codex` | GPT-5.2 Codex - 最新バージョン |
+| `cx/gpt-5.1-codex-max` | GPT-5.1 Codex Max - 拡張コンテキスト |
+
+## 使用例
+
+### 基本的な使用法
+
+```bash
+# GPT-5.2 Codexを使用
+codex --model cx/gpt-5.2-codex "Write a function to sort an array"
+
+# GPT-5.1 Codex Maxを使用
+codex --model cx/gpt-5.1-codex-max "Explain this complex algorithm"
+```
+
+### コード生成
+
+```bash
+codex --model cx/gpt-5.2-codex "Create a REST API endpoint for user authentication"
+```
+
+### コード説明
+
+```bash
+codex --model cx/gpt-5.1-codex-max "Explain what this code does: $(cat myfile.js)"
+```
+
+## 設定ファイル
+
+設定ファイルを使ってCodex CLIを設定することもできます。`~/.codex/config.json` を作成または編集:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "apiKey": "your-9router-api-key",
+  "defaultModel": "cx/gpt-5.2-codex"
+}
+```
+
+## トラブルシューティング
+
+### 認証エラー
+
+認証エラーが発生した場合:
+
+1. 9RouterダッシュボードでAPIキーが正しいか確認
+2. `OPENAI_API_KEY` 環境変数が設定されているか確認
+3. APIキーが期限切れでないか確認
+
+### 接続の問題
+
+接続エラーが発生した場合:
+
+1. 9Routerが動作中か確認: `curl http://localhost:20128/health`
+2. 環境変数が正しく設定されているか確認
+3. ファイアウォールがポート20128をブロックしていないか確認
+
+### モデルが利用不可
+
+「model not available」エラーが発生した場合:
+
+1. モデル名が9Router設定と一致するか確認
+2. 9RouterダッシュボードでOpenAIプロバイダー接続がアクティブか確認
+3. 接続されたプロバイダーでモデルが利用可能か確認
+
+## クラウドエンドポイント
+
+localhostの代わりに9Routerクラウドエンドポイントを使用するには:
+
+```bash
+export OPENAI_BASE_URL="https://9router.com"
+```
+
+9RouterクラウドダッシュボードでAPIキーが設定されていることを確認してください。
+
+## 高度な設定
+
+### カスタムタイムアウト
+
+```bash
+export OPENAI_TIMEOUT=60  # 秒
+```
+
+### デバッグモード
+
+詳細なリクエスト/レスポンスログを表示するため、デバッグモードを有効化:
+
+```bash
+export CODEX_DEBUG=true
+codex --model cx/gpt-5.2-codex "Your prompt"
+```
diff --git a/gitbook/content/ja/integration/continue.md b/gitbook/content/ja/integration/continue.md
new file mode 100644
index 0000000..0b37d59
--- /dev/null
+++ b/gitbook/content/ja/integration/continue.md
@@ -0,0 +1,249 @@
+# Continue VSCode拡張機能統合
+
+9RouterをContinue拡張機能と統合し、Visual Studio Codeに直接AIアシスタンスを導入します。
+
+## 前提条件
+
+- Visual Studio Codeがインストール済み
+- VSCodeマーケットプレイスからContinue拡張機能がインストール済み
+- [ダッシュボード](https://9router.com/dashboard)からの9Router APIキー
+- 9Routerが動作中 (ローカルまたはクラウド)
+
+## 設定手順
+
+### 1. Continue設定を開く
+
+1. VSCodeを開く
+2. `Cmd+Shift+P` (Mac) または `Ctrl+Shift+P` (Windows/Linux) を押す
+3. 「Continue: Open Config」と入力して選択
+4. `~/.continue/config.json` が開きます
+
+### 2. 9Routerモデル設定を追加
+
+以下の設定を `config.json` に追加:
+
+**単一モデルセットアップ:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**複数モデルセットアップ:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus (Best)",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Sonnet (Balanced)",
+      "provider": "openai",
+      "model": "cc/claude-sonnet-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - DeepSeek Chat (Code)",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Haiku (Fast)",
+      "provider": "openai",
+      "model": "cc/claude-haiku-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**クラウド9Router用:**
+`apiBase` を以下に置き換え:
+```json
+"apiBase": "https://9router.com/v1"
+```
+
+### 3. 保存してリロード
+
+1. 設定ファイルを保存
+2. VSCodeウィンドウをリロード: `Cmd+Shift+P` → 「Developer: Reload Window」
+3. Continue拡張機能が新しい設定を読み込みます
+
+### 4. モデルを選択
+
+1. Continueサイドバーを開く (左パネルのContinueアイコンをクリック)
+2. 上部のモデルセレクタードロップダウンをクリック
+3. お好みの9Routerモデルを選択
+
+## 利用可能なモデル
+
+### Claudeモデル (Anthropic)
+- `cc/claude-opus-4-5-20251101` - 最も高性能、複雑なタスクに最適
+- `cc/claude-sonnet-4-20250514` - パフォーマンスと速度のバランス
+- `cc/claude-haiku-4-20250514` - 最速、シンプルなタスクに適している
+
+### DeepSeekモデル
+- `cx/deepseek-chat` - コード生成に優れている
+- `cx/deepseek-reasoner` - 複雑な問題解決に最適
+
+### GLMモデル (Zhipu AI)
+- `glm/glm-4-plus` - 高度な中国語と英語
+- `glm/glm-4-flash` - 高速応答
+
+## 使用例
+
+### コード説明
+1. エディタでコードを選択
+2. Continueサイドバーを開く
+3. 入力: 「Explain this code」
+4. Model: `cc/claude-sonnet-4-20250514`
+
+### コード生成
+1. Continueサイドバーを開く
+2. 入力: 「Create a React component for user profile card」
+3. Model: `cx/deepseek-chat`
+
+### リファクタリング
+1. リファクタリングするコードを選択
+2. 入力: 「Refactor this to use async/await」
+3. Model: `cc/claude-sonnet-4-20250514`
+
+### バグ修正
+1. 問題のあるコードを選択
+2. 入力: 「Find and fix the bug in this code」
+3. Model: `cx/deepseek-reasoner`
+
+## 高度な設定
+
+### カスタムシステムプロンプト
+
+特定の動作のためのカスタムシステムプロンプトを追加:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Code Expert",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "systemMessage": "You are an expert programmer. Always provide clean, well-documented code with best practices."
+    }
+  ]
+}
+```
+
+### Temperatureとパラメータ
+
+パラメータでモデルの動作を調整:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Creative Writer",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "temperature": 0.9,
+      "topP": 0.95
+    }
+  ]
+}
+```
+
+### コンテキストプロバイダー
+
+Continueがモデルに送信するコンテキストを設定:
+
+```json
+{
+  "contextProviders": [
+    {
+      "name": "code",
+      "params": {
+        "maxLines": 100
+      }
+    },
+    {
+      "name": "diff",
+      "params": {}
+    },
+    {
+      "name": "terminal",
+      "params": {}
+    }
+  ]
+}
+```
+
+## キーボードショートカット
+
+- `Cmd+L` (Mac) / `Ctrl+L` (Windows/Linux) - Continueチャットを開く
+- `Cmd+I` (Mac) / `Ctrl+I` (Windows/Linux) - インライン編集
+- `Cmd+Shift+R` (Mac) / `Ctrl+Shift+R` (Windows/Linux) - 応答を再生成
+
+## トラブルシューティング
+
+### モデルが応答しない
+- 9Routerが動作中か確認: `curl http://localhost:20128/health`
+- config.jsonのAPIキーを確認
+- エラーについてVSCode開発者コンソールを確認: `Help` → `Toggle Developer Tools`
+
+### 間違ったモデルが選択されている
+- Continueサイドバーのモデルドロップダウンをクリック
+- 正しい9Routerモデルを選択
+- モデル名は正確に一致する必要があります (大文字小文字を区別)
+
+### 設定が読み込まれない
+- JSON構文が有効であることを確認 (JSONバリデータを使用)
+- ファイルの場所を確認: `~/.continue/config.json`
+- 変更後にVSCodeウィンドウをリロード
+
+### パフォーマンスが遅い
+- より高速なモデルへ切替 (haiku、flash)
+- contextProvidersでコンテキストサイズを削減
+- 9Routerへのネットワークレイテンシを確認
+
+## ベストプラクティス
+
+### モデル選択戦略
+- **クイック編集**: `cc/claude-haiku-4-20250514` を使用
+- **コード生成**: `cx/deepseek-chat` を使用
+- **複雑なリファクタリング**: `cc/claude-opus-4-5-20251101` を使用
+- **問題解決**: `cx/deepseek-reasoner` を使用
+
+### コンテキスト管理
+- 質問する前に関連コードのみを選択
+- 具体的で明確なプロンプトを使用
+- 複雑なタスクを小さなステップに分解
+
+### コスト最適化
+- シンプルなタスクには高速/安価なモデルを使用
+- 可能な場合はコンテキストサイズを制限
+- 頻繁に使用される応答をキャッシュ
+
+## 次のステップ
+
+- [Cursorを設定](cursor.md) IDE統合を強化
+- [Rooをセットアップ](roo.md) AIアシスタント用
+- [CLI使用法を確認](../cli/basic-usage.md)
+- [モデル選択について学ぶ](../models/overview.md)
diff --git a/gitbook/content/ja/integration/cursor.md b/gitbook/content/ja/integration/cursor.md
new file mode 100644
index 0000000..e30ebd5
--- /dev/null
+++ b/gitbook/content/ja/integration/cursor.md
@@ -0,0 +1,149 @@
+# Cursor統合
+
+9RouterをCursor IDEと統合し、AIリクエストを9Routerのインテリジェントルーティングシステム経由でルーティングします。
+
+## 前提条件
+
+- Cursor IDEがインストール済み
+- Cursor Proアカウント (カスタムAPIエンドポイントに必要)
+- 9Routerクラウドエンドポイントが設定済み
+- 9RouterダッシュボードからのAPIキー
+
+## ⚠️ 重要な注意点
+
+> **クラウドエンドポイントが必要**: Cursorは独自のサーバー経由でリクエストをルーティングし、localhostエンドポイントをサポートしません。9Routerクラウドエンドポイント `https://9router.com` を使用する必要があります。
+
+> **Cursor Proが必要**: この機能はカスタムAPIエンドポイントを使用するためにCursor Proアカウントが必要です。
+
+## セットアップ
+
+### 1. Cursor設定を開く
+
+1. Cursor IDEを開く
+2. **Settings** へ移動 (Cmd/Ctrl + ,)
+3. **Models** セクションへ移動
+
+### 2. OpenAI APIを有効化
+
+1. **OpenAI API key** オプションを見つける
+2. トグルを有効にしてカスタムAPI設定を有効化
+
+### 3. Base URLを設定
+
+Base URLを9Routerクラウドエンドポイントに設定:
+
+```
+https://9router.com
+```
+
+**手順:**
+1. Models設定で **Base URL** フィールドを見つける
+2. 入力: `https://9router.com`
+3. **Save** をクリック
+
+### 4. APIキーを追加
+
+1. **API Key** フィールドに9Router APIキーを入力
+2. APIキーは9Routerダッシュボードの **Settings → API Keys** で確認できます
+3. **Save** をクリック
+
+### 5. カスタムモデルを追加
+
+1. **View All Models** ボタンをクリック
+2. **Add Custom Model** をクリック
+3. 9Router設定からモデル名を入力 (例: `gpt-4`、`claude-opus-4-5` など)
+4. **Add** をクリック
+
+### 6. モデルを選択
+
+1. Cursorチャットインターフェイスでモデルセレクタードロップダウンをクリック
+2. リストからカスタムモデルを選択
+3. Cursorで9Routerを使い始める!
+
+## 設定例
+
+Cursor設定は次のようになります:
+
+```
+OpenAI API: ✓ Enabled
+Base URL: https://9router.com
+API Key: sk-9router-xxxxxxxxxxxxx
+Custom Models: gpt-4, claude-opus-4-5, gemini-2.0-flash
+```
+
+## 利用可能なモデル
+
+9Routerダッシュボードで設定されたモデルを使用できます。一般的な例:
+
+| モデル名 | プロバイダー | 説明 |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## 使用法
+
+### チャットインターフェイス
+
+1. Cursorチャットを開く (Cmd/Ctrl + L)
+2. ドロップダウンからモデルを選択
+3. 9Router経由でAIとチャット開始
+
+### インラインコード生成
+
+1. エディタでコードを選択
+2. Cmd/Ctrl + Kを押す
+3. プロンプトを入力
+4. Cursorは9Routerを使用してコードを生成
+
+### コード説明
+
+1. エディタでコードを選択
+2. Cmd/Ctrl + Lを押す
+3. 「Explain this code」と質問
+4. 9Router経由でAIによる説明を取得
+
+## トラブルシューティング
+
+### 「Invalid API Key」エラー
+
+1. 9RouterダッシュボードでAPIキーを確認
+2. `sk-9router-` プレフィックスを含むキー全体をコピーしたか確認
+3. APIキーが期限切れでないか確認
+4. 新しいAPIキーを再生成してみる
+
+### 「Model Not Found」エラー
+
+1. モデル名が9Router設定と正確に一致するか確認
+2. 9Routerダッシュボードでプロバイダー接続がアクティブか確認
+3. 接続されたプロバイダーでモデルが利用可能か確認
+4. フルモデル名を使用してみる (例: `gpt-4` の代わりに `openai/gpt-4`)
+
+### 接続の問題
+
+1. クラウドエンドポイントを使用しているか確認: `https://9router.com`
+2. インターネット接続を確認
+3. 9Routerクラウドサービスが運用中か確認
+4. VPNまたはプロキシが有効な場合は無効化してみる
+
+### Localhostが動作しない
+
+> **覚えておいてください**: Cursorはlocalhostエンドポイントをサポートしません。クラウドエンドポイント `https://9router.com` を使用する必要があります。ローカル9Routerインスタンスを使用したい場合は、ngrokなどのトンネリングサービスを検討してローカルエンドポイントを公開してください。
+
+## クラウドエンドポイントのセットアップ
+
+ローカルで9Routerを実行し、Cursorで使用したい場合:
+
+1. 9Router設定でクラウドエンドポイントを有効化
+2. 9RouterダッシュボードでクラウドエンドポイントURLを設定
+3. Cursor設定でクラウドURLを使用
+4. ローカル9Routerインスタンスがインターネットからアクセス可能か確認
+
+## ベストプラクティス
+
+1. **モデルエイリアスを使用**: 9Routerで頻繁に使うモデル用のショートエイリアスを作成
+2. **使用量をモニター**: 9Routerダッシュボードで使用統計とコストを確認
+3. **APIキーをローテーション**: セキュリティのためAPIキーを定期的にローテーション
+4. **モデルをテスト**: ユースケースに最適なモデルを見つけるため、異なるモデルを試す
diff --git a/gitbook/content/ja/integration/other-tools.md b/gitbook/content/ja/integration/other-tools.md
new file mode 100644
index 0000000..654cfdb
--- /dev/null
+++ b/gitbook/content/ja/integration/other-tools.md
@@ -0,0 +1,416 @@
+# その他ツール統合
+
+9RouterはOpenAI API形式をサポートする任意のツールと互換性があります。このガイドでは、様々なツールやカスタムアプリケーション向けの汎用統合パターンを説明します。
+
+## 概要
+
+9RouterはOpenAI互換APIエンドポイントを提供し、以下と動作します:
+- カスタムスクリプトとアプリケーション
+- APIクライアントとテストツール
+- CLIツールとユーティリティ
+- サードパーティ統合
+- 開発フレームワーク
+
+## 汎用セットアップパターン
+
+任意のOpenAI互換ツールは以下の設定で9Routerに接続できます:
+
+**ローカル9Router:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+Model: 任意の9Routerモデル (cc/*, cx/*, glm/*など)
+```
+
+**クラウド9Router:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+Model: 任意の9Routerモデル (cc/*, cx/*, glm/*など)
+```
+
+## 利用可能なモデル
+
+### Claudeモデル (Anthropic)
+- `cc/claude-opus-4-5-20251101`
+- `cc/claude-sonnet-4-20250514`
+- `cc/claude-haiku-4-20250514`
+
+### DeepSeekモデル
+- `cx/deepseek-chat`
+- `cx/deepseek-reasoner`
+
+### GLMモデル (Zhipu AI)
+- `glm/glm-4-plus`
+- `glm/glm-4-flash`
+
+## 統合例
+
+### PythonとOpenAI SDK
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+response = client.chat.completions.create(
+    model="cc/claude-sonnet-4-20250514",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ]
+)
+
+print(response.choices[0].message.content)
+```
+
+### Node.jsとOpenAI SDK
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+const response = await client.chat.completions.create({
+  model: "cc/claude-sonnet-4-20250514",
+  messages: [
+    { role: "user", content: "Hello, how are you?" }
+  ]
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### cURLコマンド
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-api-key-from-dashboard" \
+  -d '{
+    "model": "cc/claude-sonnet-4-20250514",
+    "messages": [
+      {"role": "user", "content": "Hello, how are you?"}
+    ]
+  }'
+```
+
+### HTTPクライアント (Postman、Insomnia)
+
+**Request:**
+```
+POST http://localhost:20128/v1/chat/completions
+```
+
+**Headers:**
+```
+Content-Type: application/json
+Authorization: Bearer your-api-key-from-dashboard
+```
+
+**Body:**
+```json
+{
+  "model": "cc/claude-sonnet-4-20250514",
+  "messages": [
+    {"role": "user", "content": "Hello, how are you?"}
+  ],
+  "temperature": 0.7,
+  "max_tokens": 1000
+}
+```
+
+### LangChain統合
+
+```python
+from langchain.chat_models import ChatOpenAI
+from langchain.schema import HumanMessage
+
+llm = ChatOpenAI(
+    model_name="cc/claude-sonnet-4-20250514",
+    openai_api_key="your-api-key-from-dashboard",
+    openai_api_base="http://localhost:20128/v1",
+    temperature=0.7
+)
+
+messages = [HumanMessage(content="Explain quantum computing")]
+response = llm(messages)
+print(response.content)
+```
+
+### LlamaIndex統合
+
+```python
+from llama_index.llms import OpenAI
+
+llm = OpenAI(
+    model="cc/claude-sonnet-4-20250514",
+    api_key="your-api-key-from-dashboard",
+    api_base="http://localhost:20128/v1"
+)
+
+response = llm.complete("What is machine learning?")
+print(response.text)
+```
+
+## カスタムスクリプトの例
+
+### バッチ処理スクリプト
+
+```python
+import openai
+import json
+
+openai.api_key = "your-api-key-from-dashboard"
+openai.api_base = "http://localhost:20128/v1"
+
+def process_batch(prompts, model="cx/deepseek-chat"):
+    results = []
+    for prompt in prompts:
+        response = openai.ChatCompletion.create(
+            model=model,
+            messages=[{"role": "user", "content": prompt}]
+        )
+        results.append({
+            "prompt": prompt,
+            "response": response.choices[0].message.content
+        })
+    return results
+
+prompts = [
+    "Explain AI in one sentence",
+    "What is machine learning?",
+    "Define neural networks"
+]
+
+results = process_batch(prompts)
+print(json.dumps(results, indent=2))
+```
+
+### ストリーミングレスポンスハンドラ
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+async function streamResponse(prompt) {
+  const stream = await client.chat.completions.create({
+    model: "cc/claude-sonnet-4-20250514",
+    messages: [{ role: "user", content: prompt }],
+    stream: true
+  });
+
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content || "";
+    process.stdout.write(content);
+  }
+}
+
+streamResponse("Write a short story about AI");
+```
+
+### マルチモデル比較
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+models = [
+    "cc/claude-sonnet-4-20250514",
+    "cx/deepseek-chat",
+    "glm/glm-4-plus"
+]
+
+prompt = "Explain quantum computing in simple terms"
+
+for model in models:
+    response = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "user", "content": prompt}]
+    )
+    print(f"\n=== {model} ===")
+    print(response.choices[0].message.content)
+```
+
+## 一般的な統合パターン
+
+### 環境変数
+
+認証情報を安全に保存:
+
+```bash
+# .envファイル
+ROUTER_API_KEY=your-api-key-from-dashboard
+ROUTER_BASE_URL=http://localhost:20128/v1
+ROUTER_MODEL=cc/claude-sonnet-4-20250514
+```
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.getenv("ROUTER_API_KEY"),
+    base_url=os.getenv("ROUTER_BASE_URL")
+)
+```
+
+### エラーハンドリング
+
+```python
+from openai import OpenAI, OpenAIError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+try:
+    response = client.chat.completions.create(
+        model="cc/claude-sonnet-4-20250514",
+        messages=[{"role": "user", "content": "Hello"}]
+    )
+    print(response.choices[0].message.content)
+except OpenAIError as e:
+    print(f"Error: {e}")
+```
+
+### リトライロジック
+
+```python
+import time
+from openai import OpenAI, RateLimitError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+def chat_with_retry(prompt, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            response = client.chat.completions.create(
+                model="cc/claude-sonnet-4-20250514",
+                messages=[{"role": "user", "content": prompt}]
+            )
+            return response.choices[0].message.content
+        except RateLimitError:
+            if attempt < max_retries - 1:
+                time.sleep(2 ** attempt)  # Exponential backoff
+            else:
+                raise
+```
+
+## トラブルシューティング
+
+### 接続の問題
+
+**問題:** 9Routerに接続できない
+```bash
+# 9Routerが動作中か確認
+curl http://localhost:20128/health
+
+# 期待されるレスポンス:
+{"status": "ok"}
+```
+
+**解決策:**
+- 9Routerが動作中か確認
+- ポート20128がブロックされていないか確認
+- 正しいbase URLを確認 (`/v1`を含む)
+
+### 認証エラー
+
+**問題:** 401 Unauthorized
+```
+Error: Invalid API key
+```
+
+**解決策:**
+- ダッシュボードからのAPIキーを確認
+- AuthorizationヘッダーフォーマットがBearer your-api-keyであることを確認
+- APIキーに余分なスペースや改行がないことを確認
+
+### モデルが見つからない
+
+**問題:** 404 Model not found
+```
+Error: Model 'cc/claude-opus' not found
+```
+
+**解決策:**
+- 正確なモデル名を使用 (大文字小文字を区別)
+- 利用可能なモデルを確認: `curl http://localhost:20128/v1/models`
+- プランでモデルが有効になっていることを確認
+
+### タイムアウトの問題
+
+**問題:** リクエストタイムアウト
+```
+Error: Request timed out after 30s
+```
+
+**解決策:**
+- クライアント設定でタイムアウトを増やす
+- 時間制約のあるタスクには高速モデルを使用
+- 9Routerへのネットワーク接続を確認
+
+### レート制限
+
+**問題:** 429 Too Many Requests
+```
+Error: Rate limit exceeded
+```
+
+**解決策:**
+- 指数バックオフを実装
+- リクエスト頻度を減らす
+- ダッシュボードでレート制限を確認
+- プランのアップグレードを検討
+
+## ベストプラクティス
+
+### セキュリティ
+- APIキーを環境変数に保存
+- APIキーをバージョン管理にコミットしない
+- クラウドデプロイにはHTTPSを使用
+- APIキーを定期的にローテーション
+
+### パフォーマンス
+- タスクの複雑さに応じて適切なモデルを使用
+- 繰り返しクエリにキャッシュを実装
+- 長い応答にはストリーミングを使用
+- 可能な場合はリクエストをバッチ処理
+
+### エラーハンドリング
+- 常にtry-catchブロックを実装
+- 指数バックオフでリトライロジックを追加
+- デバッグのためエラーをログ
+- フォールバックメカニズムを提供
+
+### コスト最適化
+- シンプルなタスクには費用対効果の高いモデルを選択
+- 適切な場合は応答をキャッシュ
+- ダッシュボードで使用量をモニター
+- コードでリクエスト制限を設定
+
+## 次のステップ
+
+- [Cursorを設定](cursor.md) IDE統合用
+- [Continueをセットアップ](continue.md) VSCode用
+- [CLI使用法を確認](../cli/basic-usage.md)
+- [モデル選択について学ぶ](../models/overview.md)
+- [APIリファレンス](../api/reference.md)
diff --git a/gitbook/content/ja/integration/roo.md b/gitbook/content/ja/integration/roo.md
new file mode 100644
index 0000000..0d5ca6e
--- /dev/null
+++ b/gitbook/content/ja/integration/roo.md
@@ -0,0 +1,127 @@
+# Roo AIアシスタント統合
+
+9RouterをRoo AIアシスタントと統合し、統一インターフェイスから複数のAIモデルにアクセスします。
+
+## 前提条件
+
+- Roo AIアシスタントがインストール済み
+- [ダッシュボード](https://9router.com/dashboard)からの9Router APIキー
+- 9Routerが動作中 (ローカルまたはクラウド)
+
+## 設定手順
+
+### 1. Roo設定を開く
+
+Roo AIアシスタントを起動し、設定パネルを開きます。
+
+### 2. APIプロバイダーを設定
+
+1. **API Provider** 設定へ移動
+2. プロバイダータイプとして **Ollama** を選択
+3. 以下の設定を行う:
+
+**ローカル9Router用:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+```
+
+**クラウド9Router用:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+```
+
+### 3. モデルを選択
+
+利用可能な9Routerモデルから選択:
+
+**Claudeモデル:**
+- `cc/claude-opus-4-5-20251101` - 最も高性能
+- `cc/claude-sonnet-4-20250514` - バランス
+- `cc/claude-haiku-4-20250514` - 高速
+
+**DeepSeekモデル:**
+- `cx/deepseek-chat` - 汎用
+- `cx/deepseek-reasoner` - 複雑な推論
+
+**GLMモデル:**
+- `glm/glm-4-plus` - 高度
+- `glm/glm-4-flash` - 高速応答
+
+### 4. 接続をテスト
+
+統合を確認するためにテストメッセージを送信:
+
+```
+Hello! Can you confirm you're connected through 9Router?
+```
+
+## 使用例
+
+### 基本チャット
+```
+Rooに質問: "Explain quantum computing in simple terms"
+Model: cc/claude-sonnet-4-20250514
+```
+
+### コード生成
+```
+Rooに質問: "Write a Python function to calculate Fibonacci numbers"
+Model: cx/deepseek-chat
+```
+
+### 複雑な推論
+```
+Rooに質問: "Analyze the trade-offs between microservices and monolithic architecture"
+Model: cx/deepseek-reasoner
+```
+
+## モデル選択のヒント
+
+- **クイックタスク**: `cc/claude-haiku-4-20250514` または `glm/glm-4-flash` を使用
+- **バランスのとれたパフォーマンス**: `cc/claude-sonnet-4-20250514` または `cx/deepseek-chat` を使用
+- **複雑な推論**: `cc/claude-opus-4-5-20251101` または `cx/deepseek-reasoner` を使用
+- **コスト最適化**: DeepSeekまたはGLMモデルを使用
+
+## トラブルシューティング
+
+### 接続失敗
+- 9Routerが動作中か確認: `curl http://localhost:20128/health`
+- APIキーが正しいか確認
+- Base URLに `/v1` サフィックスが含まれていることを確認
+
+### モデルが利用不可
+- モデル名が正確に一致するか確認 (大文字小文字を区別)
+- 9Routerプランでモデルが有効か確認
+- リストから別のモデルを試す
+
+### 応答が遅い
+- より高速なモデルへ切替 (haiku、flash)
+- ネットワーク接続を確認
+- 問題について9Routerログをモニター
+
+## 高度な設定
+
+### カスタムモデルエイリアス
+
+Roo設定で頻繁に使うモデルのショートカットを作成:
+
+```
+エイリアス: "fast" → cc/claude-haiku-4-20250514
+エイリアス: "smart" → cc/claude-opus-4-5-20251101
+エイリアス: "code" → cx/deepseek-chat
+```
+
+### 複数のプロファイル
+
+異なるユースケース用の異なるプロファイルをセットアップ:
+- **開発**: コード用のDeepSeekモデル
+- **執筆**: コンテンツ用のClaudeモデル
+- **リサーチ**: 分析用のReasonerモデル
+
+## 次のステップ
+
+- [Cursorを設定](cursor.md) IDE統合用
+- [Continueをセットアップ](continue.md) VSCode用
+- [CLI使用法を確認](../cli/basic-usage.md)
diff --git a/gitbook/content/ja/providers/cheap.md b/gitbook/content/ja/providers/cheap.md
new file mode 100644
index 0000000..27c92de
--- /dev/null
+++ b/gitbook/content/ja/providers/cheap.md
@@ -0,0 +1,462 @@
+# 低価格プロバイダー - 超低価格バックアップ
+
+サブスクリプションクォータが切れたら、ドルではなくセント単位で支払い。ChatGPT APIより約90%安い!
+
+---
+
+## 概要
+
+低価格階層プロバイダーは、サブスクリプションクォータが消費された時の**バックアップ**:
+
+- 💰 **GLM-4.7** - 100万トークンあたり$0.6/$2.2 (日次リセット)
+- 💰 **MiniMax M2.1** - 100万トークンあたり$0.2/$1.0 (5時間リセット)
+- 💰 **Kimi K2** - 月$9固定 (1000万トークン)
+
+**戦略:** サブスクリプションクォータ切れ後、無料階層前に使用。ChatGPT API (100万あたり$20) に対して大幅なコスト削減。
+
+---
+
+## GLM-4.7 (日次リセット)
+
+### 料金
+
+| 階層 | 入力 | 出力 | リセット |
+|------|-------|--------|-------|
+| Standard | $0.60/1M | $2.20/1M | 毎日午前10時 |
+| Coding Plan | $0.60/1M | $2.20/1M | 毎日午前10時 (3×クォータ) |
+
+**コスト例 (1000万トークン):**
+- 入力: 1000万 × $0.60 = $6
+- 出力: 1000万 × $2.20 = $22
+- **合計: $6〜22** vs ChatGPT APIの$200!
+
+### セットアップ
+
+**ステップ1: サインアップ**
+
+1. [Zhipu AI](https://open.bigmodel.cn/) を訪問
+2. アカウント作成 (電話認証)
+3. 同じ価格で3×クォータの **Coding Plan** を選択
+
+**ステップ2: APIキーを取得**
+
+```bash
+Dashboard → API Keys → Create New
+→ APIキーをコピー ("zhipu-"で始まる)
+```
+
+**ステップ3: 9Routerに追加**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: glm
+API Key: zhipu-your-api-key-here
+```
+
+**ステップ4: CLIで使用**
+
+```
+Model: glm/glm-4.7
+       glm/glm-4.6v (vision)
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | コンテキスト | 最適用途 |
+|----------|-------------|---------|----------|
+| `glm/glm-4.7` | GLM 4.7 | 128K | コーディング、汎用タスク |
+| `glm/glm-4.6v` | GLM 4.6V Vision | 128K | 画像分析 |
+
+### プロのヒント
+
+- **Coding Plan** - 同じ価格で3×クォータ ($0.6/$2.2)
+- **日次リセット** - 北京時間午前10時に新鮮なクォータ
+- **コーディングに最適** - コード生成用に最適化
+- **128Kコンテキスト** - 大きなファイルを処理
+
+### クォータリセット
+
+```
+日次リセット: 北京時間午前10時 (UTC+8)
+→ UTC午前2時
+→ PST午後6時 (前日)
+→ EST午後9時 (前日)
+
+リセット時間に合わせて重いタスクを計画!
+```
+
+---
+
+## MiniMax M2.1 (5時間リセット)
+
+### 料金
+
+| 階層 | 入力 | 出力 | リセット |
+|------|-------|--------|-------|
+| Standard | $0.20/1M | $1.00/1M | 5時間ローリング |
+
+**コスト例 (1000万トークン):**
+- 入力: 1000万 × $0.20 = $2
+- 出力: 1000万 × $1.00 = $10
+- **合計: $2〜10** - 最安オプション!
+
+### セットアップ
+
+**ステップ1: サインアップ**
+
+1. [MiniMax](https://www.minimax.io/) を訪問
+2. アカウント作成
+3. メール/電話を認証
+
+**ステップ2: APIキーを取得**
+
+```bash
+Dashboard → API Management → Create Key
+→ APIキーをコピー
+```
+
+**ステップ3: 9Routerに追加**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: minimax
+API Key: your-minimax-api-key
+```
+
+**ステップ4: CLIで使用**
+
+```
+Model: minimax/MiniMax-M2.1
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | コンテキスト | 最適用途 |
+|----------|-------------|---------|----------|
+| `minimax/MiniMax-M2.1` | MiniMax M2.1 | 1Mトークン | 長いコンテキスト、コーディング |
+
+### プロのヒント
+
+- **最安オプション** - 入力100万あたり$0.20 (ChatGPTより90%安い)
+- **5時間ローリング** - 5時間ごとにクォータリセット
+- **1Mコンテキスト** - 巨大なコンテキストウィンドウ
+- **長いファイルに最適** - コードベース全体を処理
+
+### クォータリセット
+
+```
+5時間ローリングウィンドウ:
+→ クォータ使用 → 5時間待つ → 新鮮なクォータ
+
+例:
+午前10時 - 500万トークン使用
+午後3時 - 新鮮なクォータ利用可
+午後8時 - 新鮮なクォータ利用可
+
+最小コストで24時間コーディング!
+```
+
+---
+
+## Kimi K2 (月$9固定)
+
+### 料金
+
+| プラン | 月額コスト | 含まれるトークン | 実効コスト |
+|------|--------------|-----------------|----------------|
+| Subscription | $9 | 1000万トークン | 100万あたり$0.90 |
+
+**コスト例:**
+- 月$9固定
+- 1000万トークン含む
+- **実効: 100万あたり$0.90** - 一貫した使用に最適の価値!
+
+### セットアップ
+
+**ステップ1: 購読**
+
+1. [Moonshot AI](https://platform.moonshot.ai/) を訪問
+2. アカウント作成
+3. 月$9プランに購読
+
+**ステップ2: APIキーを取得**
+
+```bash
+Dashboard → API Keys → Create New
+→ APIキーをコピー
+```
+
+**ステップ3: 9Routerに追加**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: kimi
+API Key: your-kimi-api-key
+```
+
+**ステップ4: CLIで使用**
+
+```
+Model: kimi/kimi-latest
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | コンテキスト | 最適用途 |
+|----------|-------------|---------|----------|
+| `kimi/kimi-latest` | Kimi Latest | 200K | 汎用コーディング |
+
+### プロのヒント
+
+- **固定コスト** - 使用量に関わらず月$9 (1000万まで)
+- **一貫した使用に最適** - 月1000万使用なら100万あたりわずか$0.90
+- **月次リセット** - 1000万トークンが月次リセット
+- **予測可能な請求** - 予期しないコストなし
+
+### クォータリセット
+
+```
+月次リセット: 各月1日
+→ 1000万トークンが更新
+
+月次使用例:
+週1: 300万トークン
+週2: 200万トークン
+週3: 300万トークン
+週4: 200万トークン
+合計: 1000万トークン = $9固定
+```
+
+---
+
+## 料金比較
+
+| プロバイダー | 入力/1M | 出力/1M | リセット | 1000万コスト | 最適用途 |
+|----------|----------|-----------|-------|----------|----------|
+| **GLM-4.7** | $0.60 | $2.20 | 毎日午前10時 | $6〜22 | 日次クォータユーザー |
+| **MiniMax M2.1** | $0.20 | $1.00 | 5時間 | $2〜10 | **最安!** |
+| **Kimi K2** | $0.90 | $0.90 | 月次 | **$9固定** | 一貫した使用 |
+| ChatGPT API | $20.00 | $20.00 | なし | $200 | ❌ 高価 |
+
+**節約:** ChatGPT APIより90〜95%安い!
+
+---
+
+## 使用例
+
+### Cursor IDEセットアップ
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [9routerダッシュボードから取得]
+  Model: glm/glm-4.7
+```
+
+### コンボを作成 (推奨)
+
+```
+Dashboard → Combos → Create New
+
+Name: cheap-backup
+Models:
+  1. cc/claude-opus-4-5 (サブスクリプション優先)
+  2. glm/glm-4.7 (低価格バックアップ、日次リセット)
+  3. minimax/MiniMax-M2.1 (最安フォールバック)
+  4. if/kimi-k2-thinking (無料緊急時)
+
+CLIで使用: cheap-backup
+```
+
+**結果:** サブスクリプション → 低価格 → 最安 → 無料
+
+---
+
+## コスト最適化
+
+### 戦略1: 日次リセットルーチン
+
+```
+朝 (午前10時): 新鮮なGLMクォータ
+→ 重いタスクにGLMを使用
+→ サブスクリプションクォータを節約
+
+午後: サブスクリプションクォータ
+→ 複雑なタスクにClaude/Codexを使用
+
+夕方: MiniMax (5時間リセット)
+→ 遅い作業の低価格フォールバック
+
+夜: 無料階層 (iFlow)
+→ ゼロコスト緊急バックアップ
+```
+
+### 戦略2: 予算優先
+
+```
+月次予算設定: $20
+
+割り当て:
+- $9 Kimi K2 (1000万トークン固定)
+- $6 GLM日次クォータ (1000万トークン)
+- $5 MiniMaxオーバーフロー (2500万トークン)
+
+合計: $20で4500万トークン
+vs ChatGPT APIでは$20で100万トークン!
+```
+
+### 戦略3: サブスクリプションを最初に最大化
+
+```
+優先順位:
+1. Gemini CLI (月18万無料)
+2. Claude Code (すでに支払っているサブスクリプション)
+3. GLM-4.7 (低価格バックアップ、100万あたり$0.6)
+4. MiniMax M2.1 (最安、100万あたり$0.2)
+5. iFlow (無料緊急時)
+
+月次コスト例 (1億トークン):
+- Gemini CLI経由で6000万: $0 (無料)
+- Claude Code経由で3000万: $0 (サブスクリプション)
+- GLM経由で800万: $4.80
+- MiniMax経由で200万: $0.40
+合計: 月$5.20!
+```
+
+---
+
+## 実例
+
+### 例1: 重いコーディング月 (1億トークン)
+
+```
+内訳:
+- サブスクリプション (Claude/Codex) 経由で6000万: $0追加
+- GLM-4.7経由で3000万: $18
+- MiniMax M2.1経由で1000万: $2
+
+合計: 月$20
+vs ChatGPT APIの$2000!
+
+節約: 99%安い!
+```
+
+### 例2: バジェットコーダー ($10/月)
+
+```
+戦略:
+- $9 Kimi K2 (1000万トークン)
+- $1 MiniMaxオーバーフロー (500万トークン)
+
+合計: $10で1500万トークン
+vs ChatGPT APIでは$10で50万トークン!
+
+30倍多くのトークン!
+```
+
+### 例3: フリーランサー (変動使用量)
+
+```
+軽い月 (2000万トークン):
+- サブスクリプション経由で1500万: $0
+- GLM経由で500万: $3
+合計: $3
+
+重い月 (1.5億トークン):
+- サブスクリプション経由で6000万: $0
+- GLM経由で6000万: $36
+- MiniMax経由で3000万: $6
+合計: $42
+
+平均: 月$22.50
+vs ChatGPT APIの$3400!
+```
+
+---
+
+## ベストプラクティス
+
+### 1. 日次クォータを追跡
+
+```
+ダッシュボード表示:
+- GLMクォータ: 75%使用 (6時間後リセット)
+- MiniMaxクォータ: 50%使用 (2時間後リセット)
+- Kimiクォータ: 800万/1000万使用 (15日後リセット)
+
+リセット時間に合わせて重いタスクを計画!
+```
+
+### 2. Coding Planを使用 (GLM)
+
+```
+Standard: 1×クォータ
+Coding Plan: 3×クォータ (同じ価格!)
+
+→ 常にCoding Planを選択
+```
+
+### 3. 無料階層と組み合わせる
+
+```
+コンボ:
+1. gc/gemini-3-flash (無料プライマリ)
+2. glm/glm-4.7 (低価格バックアップ)
+3. minimax/MiniMax-M2.1 (最安)
+4. if/kimi-k2-thinking (無料緊急時)
+
+結果: コストを最小化、アップタイムを最大化
+```
+
+### 4. 予算アラートを設定
+
+```
+Dashboard → Settings → Budget Alerts
+
+日次: $2上限
+週次: $10上限
+月次: $30上限
+
+→ 上限到達時に自動的に無料階層へ切替
+```
+
+---
+
+## トラブルシューティング
+
+### 「クォータ消費」
+
+**解決策:**
+- GLM: 北京時間午前10時まで待つ
+- MiniMax: 最初の使用から5時間待つ
+- Kimi: 翌月1日まで待つ
+- 無料階層へのコンボフォールバックを使用
+
+### 「APIキー無効」
+
+**解決策:**
+- APIキーが正しくコピーされたか確認
+- アカウントにクレジットがあるか確認
+- 必要に応じてAPIキーを再生成
+
+### 「高コスト」
+
+**解決策:**
+- ダッシュボードで使用統計を確認
+- 予算アラートを設定
+- MiniMax (100万あたり$0.2最安) へ切替
+- クリティカルでないタスクに無料階層を使用
+
+---
+
+## 次のステップ
+
+- **無料フォールバックを追加:** [無料プロバイダー](./free.md)
+- **サブスクリプションをセットアップ:** [サブスクリプションプロバイダー](./subscription.md)
+- **コンボを作成:** Dashboard → Combos → Create New
diff --git a/gitbook/content/ja/providers/free.md b/gitbook/content/ja/providers/free.md
new file mode 100644
index 0000000..807858b
--- /dev/null
+++ b/gitbook/content/ja/providers/free.md
@@ -0,0 +1,442 @@
+# 無料プロバイダー - ゼロコストフォールバック
+
+他のすべてがクォータ制限に達した時の緊急バックアップ。ゼロコストで24時間コーディング!
+
+---
+
+## 概要
+
+無料階層プロバイダーは、サブスクリプションと低価格クォータが消費された時の**フォールバック**:
+
+- 🆓 **iFlow** - 8モデル無料 (Kimi K2、Qwen3、GLM 4.7、MiniMax M2...)
+- 🆓 **Qwen** - 3モデル無料 (Qwen3 Coder Plus/Flash、Vision)
+- 🆓 **Kiro** - 2モデル無料 (Claude Sonnet 4.5、Haiku 4.5)
+
+**戦略:** 緊急バックアップとして使用。無制限利用、永久ゼロコスト!
+
+---
+
+## iFlow (8つの無料モデル)
+
+### 料金
+
+| プラン | 月額コスト | モデル | クォータ |
+|------|--------------|--------|-------|
+| FREE | $0 | 8モデル | 無制限 |
+
+**最高の価値:** 無料階層で最も多くのモデル! Kimi K2、Qwen3、GLM、MiniMax、DeepSeek。
+
+### セットアップ
+
+**ステップ1: ダッシュボード経由で接続**
+
+```bash
+9router
+# Dashboard → Providers → Connect iFlow
+```
+
+**ステップ2: iFlow OAuthログイン**
+
+- 「Connect iFlow」をクリック
+- ブラウザが開く → iFlowログインページ
+- アカウント作成またはログイン
+- 権限を付与
+- 自動トークン更新有効化
+
+**ステップ3: CLIで使用**
+
+```
+Model: if/kimi-k2-thinking
+       if/kimi-k2
+       if/qwen3-coder-plus
+       if/glm-4.7
+       if/minimax-m2
+       if/deepseek-r1
+       if/deepseek-v3.2-chat
+       if/deepseek-v3.2-reasoner
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | 最適用途 |
+|----------|-------------|----------|
+| `if/kimi-k2-thinking` | Kimi K2 Thinking | 複雑な推論 |
+| `if/kimi-k2` | Kimi K2 | 汎用コーディング |
+| `if/qwen3-coder-plus` | Qwen3 Coder Plus | コード生成 |
+| `if/glm-4.7` | GLM 4.7 | 中国語 + 英語 |
+| `if/minimax-m2` | MiniMax M2 | 長いコンテキスト |
+| `if/deepseek-r1` | DeepSeek R1 | 推論タスク |
+| `if/deepseek-v3.2-chat` | DeepSeek V3.2 Chat | 会話 |
+| `if/deepseek-v3.2-reasoner` | DeepSeek V3.2 Reasoner | 複雑なロジック |
+
+### プロのヒント
+
+- **8モデル無料** - 無料階層で最多種類
+- **無制限利用** - クォータ制限なし
+- **Kimi K2 Thinking** - 複雑な推論に最適
+- **DeepSeek R1** - 強力な推論能力
+
+---
+
+## Qwen (3つの無料モデル)
+
+### 料金
+
+| プラン | 月額コスト | モデル | クォータ |
+|------|--------------|--------|-------|
+| FREE | $0 | 3モデル | 無制限 |
+
+### セットアップ
+
+**ステップ1: ダッシュボード経由で接続**
+
+```bash
+9router
+# Dashboard → Providers → Connect Qwen
+```
+
+**ステップ2: デバイスコード認可**
+
+- 「Connect Qwen」をクリック
+- ダッシュボードがデバイスコードを表示
+- 認可URLを訪問
+- デバイスコードを入力
+- Qwenアカウントにログイン
+- 自動トークン更新有効化
+
+**ステップ3: CLIで使用**
+
+```
+Model: qw/qwen3-coder-plus
+       qw/qwen3-coder-flash
+       qw/vision-model
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | 最適用途 |
+|----------|-------------|----------|
+| `qw/qwen3-coder-plus` | Qwen3 Coder Plus | 高度なコーディング |
+| `qw/qwen3-coder-flash` | Qwen3 Coder Flash | 高速応答 |
+| `qw/vision-model` | Qwen3 Vision | 画像分析 |
+
+### プロのヒント
+
+- **Qwen3 Coder Plus** - 強力なコーディング能力
+- **Qwen3 Coder Flash** - クイックタスク用に高速
+- **Visionモデル** - 無料画像分析
+- **無制限利用** - クォータ制限なし
+
+---
+
+## Kiro (Claude無料)
+
+### 料金
+
+| プラン | 月額コスト | モデル | クォータ |
+|------|--------------|--------|-------|
+| FREE | $0 | Claude Sonnet 4.5、Haiku 4.5 | 無制限 |
+
+**最高の価値:** 無料Claude! 有料Claude Codeと同じ品質。
+
+### セットアップ
+
+**ステップ1: ダッシュボード経由で接続**
+
+```bash
+9router
+# Dashboard → Providers → Connect Kiro
+```
+
+**ステップ2: AWS Builder IDまたはOAuth**
+
+- 「Connect Kiro」をクリック
+- ログイン方法を選択:
+  - AWS Builder ID (推奨)
+  - Googleアカウント
+  - GitHubアカウント
+- 権限を付与
+- 自動トークン更新有効化
+
+**ステップ3: CLIで使用**
+
+```
+Model: kr/claude-sonnet-4.5
+       kr/claude-haiku-4.5
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | 最適用途 |
+|----------|-------------|----------|
+| `kr/claude-sonnet-4.5` | Claude Sonnet 4.5 | バランスのとれた品質/速度 |
+| `kr/claude-haiku-4.5` | Claude Haiku 4.5 | 高速応答 |
+
+### プロのヒント
+
+- **無料Claude** - 有料階層と同じ品質
+- **AWS Builder ID** - AWSアカウントで簡単セットアップ
+- **無制限利用** - クォータ制限なし
+- **最高品質** - Claude 4.5を無料で!
+
+---
+
+## 機能比較
+
+| プロバイダー | モデル | 最高のモデル | セットアップ | クォータ |
+|----------|--------|------------|-------|-------|
+| **iFlow** | 8 | Kimi K2 Thinking | OAuth | 無制限 |
+| **Qwen** | 3 | Qwen3 Coder Plus | デバイスコード | 無制限 |
+| **Kiro** | 2 | Claude Sonnet 4.5 | AWS Builder ID | 無制限 |
+
+**勝者:** 種類はiFlow、品質はKiro!
+
+---
+
+## 使用例
+
+### Cursor IDEセットアップ
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [9routerダッシュボードから取得]
+  Model: if/kimi-k2-thinking
+```
+
+### コンボを作成 (推奨)
+
+```
+Dashboard → Combos → Create New
+
+Name: free-combo
+Models:
+  1. if/kimi-k2-thinking (iFlowプライマリ)
+  2. qw/qwen3-coder-plus (Qwenバックアップ)
+  3. kr/claude-sonnet-4.5 (Kiro品質)
+
+CLIで使用: free-combo
+```
+
+**結果:** ゼロコスト、最大アップタイム!
+
+---
+
+## 完全なフォールバック戦略
+
+### 完全な3階層コンボ
+
+```
+Dashboard → Combos → Create New
+
+Name: complete-fallback
+Models:
+  1. gc/gemini-3-flash-preview (無料サブスクリプション)
+  2. cc/claude-opus-4-5 (有料サブスクリプション)
+  3. glm/glm-4.7 (低価格バックアップ、100万あたり$0.6)
+  4. minimax/MiniMax-M2.1 (最安、100万あたり$0.2)
+  5. if/kimi-k2-thinking (無料フォールバック)
+  6. kr/claude-sonnet-4.5 (無料品質)
+
+CLIで使用: complete-fallback
+```
+
+**結果:**
+- Tier 1: 無料サブスクリプション (Gemini CLI)
+- Tier 2: 有料サブスクリプション (Claude Code)
+- Tier 3: 低価格バックアップ (GLM、MiniMax)
+- Tier 4: 無料フォールバック (iFlow、Kiro)
+
+**コーディングが止まらない!**
+
+---
+
+## ベストプラクティス
+
+### 1. 緊急バックアップとして使用
+
+```
+優先順位:
+1. サブスクリプション階層 (有料クォータを最大化)
+2. 低価格階層 (100万トークンあたりセント)
+3. 無料階層 (無制限、ゼロコスト)
+
+以下の時のみ無料階層を使用:
+- サブスクリプションクォータ消費
+- 予算上限到達
+- テスト/クリティカルでないタスク
+```
+
+### 2. 適切なモデルを選択
+
+```
+複雑な推論: if/kimi-k2-thinking
+高速コーディング: qw/qwen3-coder-flash
+最高品質: kr/claude-sonnet-4.5
+長いコンテキスト: if/minimax-m2
+Visionタスク: qw/vision-model
+```
+
+### 3. 無料のみのコンボを作成
+
+```
+ゼロコストコーディング用:
+
+Name: zero-cost
+Models:
+  1. kr/claude-sonnet-4.5 (最高品質)
+  2. if/kimi-k2-thinking (複雑なタスク)
+  3. qw/qwen3-coder-plus (高速コーディング)
+
+コスト: 永久に$0!
+```
+
+### 4. 本番前にテスト
+
+```
+無料階層を使用して:
+- プロンプトをテスト
+- 機能のプロトタイプを作成
+- 新しいフレームワークを学ぶ
+- クリティカルでないタスク
+
+有料クォータを以下に節約:
+- 本番コード
+- 複雑なリファクタリング
+- クリティカルな機能
+```
+
+---
+
+## 実例
+
+### 例1: 学生/学習者 (ゼロ予算)
+
+```
+セットアップ:
+1. kr/claude-sonnet-4.5 (最高品質)
+2. if/kimi-k2-thinking (複雑な推論)
+3. qw/qwen3-coder-plus (高速コーディング)
+
+月次コスト: $0
+利用: 無制限
+
+最適:
+- コーディング学習
+- 個人プロジェクト
+- 宿題/課題
+```
+
+### 例2: フリーランサー (予算意識)
+
+```
+セットアップ:
+1. gc/gemini-3-flash-preview (月18万無料)
+2. glm/glm-4.7 (低価格バックアップ、100万あたり$0.6)
+3. if/kimi-k2-thinking (無料フォールバック)
+
+月次コスト: $5〜10
+利用: 1億以上のトークン
+
+最適:
+- クライアントプロジェクト (有料階層)
+- テスト (無料階層)
+- 緊急バックアップ
+```
+
+### 例3: ヘビーユーザー (すべてを最大化)
+
+```
+セットアップ:
+1. gc/gemini-3-flash-preview (月18万無料)
+2. cc/claude-opus-4-5 (サブスクリプション$20〜100)
+3. cx/gpt-5.2-codex (サブスクリプション$20〜200)
+4. glm/glm-4.7 (低価格 100万あたり$0.6)
+5. minimax/MiniMax-M2.1 (最安 100万あたり$0.2)
+6. if/kimi-k2-thinking (無料無制限)
+7. kr/claude-sonnet-4.5 (無料品質)
+
+月次コスト: $40〜320 (サブスクリプション) + $10〜20 (低価格階層)
+利用: 5億以上のトークン
+
+最適:
+- プロフェッショナル開発
+- チームプロジェクト
+- 24時間コーディング
+```
+
+---
+
+## コスト比較
+
+### シナリオ: 月1億トークン
+
+**オプション1: ChatGPT APIのみ**
+```
+1億 × $20/1M = 月$2,000
+```
+
+**オプション2: 9Router無料階層のみ**
+```
+無料階層経由で1億 = 月$0
+節約: 月$2,000 (100%)
+```
+
+**オプション3: 9Router完全戦略**
+```
+Gemini CLI経由で6000万 (無料): $0
+Claude Code経由で3000万 (サブスクリプション): $0追加
+GLM経由で800万 (低価格): $4.80
+iFlow経由で200万 (無料): $0
+合計: 月$4.80 + すでに持っているサブスクリプション
+節約: 月$1,995 (99.76%)
+```
+
+---
+
+## トラブルシューティング
+
+### "OAuth failed"
+
+**解決策:**
+- インターネット接続を確認
+- 別のブラウザを試す
+- ブラウザキャッシュをクリア
+- ダッシュボードで再接続
+
+### "モデルが利用不可"
+
+**解決策:**
+- ダッシュボードでプロバイダーが接続されているか確認
+- OAuthトークンが有効か確認
+- 必要に応じてプロバイダーを再接続
+
+### "応答が遅い"
+
+**解決策:**
+- 無料階層は優先度が低い可能性
+- ピーク外時間に使用
+- 別の無料プロバイダーへ切替
+- 速度のため低価格階層へアップグレード
+
+---
+
+## 制限事項
+
+### 無料階層の考慮事項
+
+- **速度** - 有料階層より遅い可能性
+- **優先度** - ピーク時間中は優先度が低い
+- **レート制限** - レート制限の可能性 (ただしクォータは無制限)
+- **可用性** - 時折ダウンタイムがある可能性
+
+**解決策:** 信頼性のため3階層フォールバック戦略を使用!
+
+---
+
+## 次のステップ
+
+- **サブスクリプションをセットアップ:** [サブスクリプションプロバイダー](./subscription.md)
+- **低価格バックアップを追加:** [低価格プロバイダー](./cheap.md)
+- **コンボを作成:** Dashboard → Combos → Create New
+- **コーディング開始:** 最大の信頼性のため `complete-fallback` コンボを使用
diff --git a/gitbook/content/ja/providers/subscription.md b/gitbook/content/ja/providers/subscription.md
new file mode 100644
index 0000000..49ecf36
--- /dev/null
+++ b/gitbook/content/ja/providers/subscription.md
@@ -0,0 +1,404 @@
+# サブスクリプションプロバイダー - 価値を最大化
+
+スマートクォータトラッキングと自動フォールバックで既存のAIサブスクリプションを最大化。リセット前にサブスクリプションを余すことなく使用しましょう!
+
+---
+
+## 概要
+
+サブスクリプション階層プロバイダーは**プライマリ**選択です - すでに支払っているので、完全な価値を引き出しましょう:
+
+- ✅ **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
+- ✅ **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex、GPT 5.1 Codex Max
+- ✅ **Gemini CLI** (無料階層!) - 月18万コンプリーション
+- ✅ **GitHub Copilot** - GPT-5、Claude 4.5、Gemini 3
+- ✅ **Antigravity** (Google) - Gemini 3 Pro、Claude Sonnet 4.5
+
+**戦略:** これらを最初に使用、クォータをリアルタイムで追跡、消費時に低価格/無料へフォールバック。
+
+---
+
+## Claude Code (Pro/Max)
+
+### 料金
+
+| プラン | 月額コスト | クォータリセット | モデル |
+|------|--------------|-------------|--------|
+| Pro | $20 | 5時間 + 週次 | Opus、Sonnet、Haiku |
+| Max | $100 | 5時間 + 週次 | Opus、Sonnet、Haiku |
+
+### セットアップ
+
+**ステップ1: ダッシュボード経由で接続**
+
+```bash
+9router
+# Dashboard開く → Providers → Connect Claude Code
+```
+
+**ステップ2: OAuthログイン**
+
+- 「Connect Claude Code」をクリック
+- ブラウザが開く → Claude.aiにログイン
+- 自動トークン更新有効化
+- クォータトラッキング開始
+
+**ステップ3: CLIで使用**
+
+```
+Model: cc/claude-opus-4-5-20251101
+       cc/claude-sonnet-4-5-20250929
+       cc/claude-haiku-4-5-20251001
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | 最適用途 |
+|----------|-------------|----------|
+| `cc/claude-opus-4-5-20251101` | Claude 4.5 Opus | 複雑なタスク、アーキテクチャ |
+| `cc/claude-sonnet-4-5-20250929` | Claude 4.5 Sonnet | バランスのとれた速度/品質 |
+| `cc/claude-haiku-4-5-20251001` | Claude 4.5 Haiku | 高速応答 |
+
+### プロのヒント
+
+- **複雑なタスクにOpusを使用** - アーキテクチャ決定、リファクタリング
+- **速度にSonnetを使用** - クイック編集、コード生成
+- **モデルごとのクォータを追跡** - ダッシュボードがモデルごとの使用量を表示
+- **5時間リセット** - 5時間ごとの新鮮なクォータ + 週次リセット
+
+---
+
+## OpenAI Codex (Plus/Pro)
+
+### 料金
+
+| プラン | 月額コスト | クォータリセット | モデル |
+|------|--------------|-------------|--------|
+| Plus | $20 | 5時間 + 週次 | GPT 5.2、GPT 5.1 |
+| Pro | $200 | 5時間 + 週次 | GPT 5.2 Codex、GPT 5.1 Max |
+
+### セットアップ
+
+**ステップ1: ダッシュボード経由で接続**
+
+```bash
+9router
+# Dashboard → Providers → Connect Codex
+```
+
+**ステップ2: OAuthログイン**
+
+- 「Connect Codex」をクリック
+- ブラウザが `http://localhost:1455` を開く
+- OpenAIアカウントにログイン
+- 自動トークン更新有効化
+
+**ステップ3: CLIで使用**
+
+```
+Model: cx/gpt-5.2-codex
+       cx/gpt-5.1-codex-max
+       cx/gpt-5.2
+       cx/gpt-5.1-codex
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | 最適用途 |
+|----------|-------------|----------|
+| `cx/gpt-5.2-codex` | GPT 5.2 Codex | 最新コーディングモデル |
+| `cx/gpt-5.1-codex-max` | GPT 5.1 Codex Max | 最大コンテキスト |
+| `cx/gpt-5.2` | GPT 5.2 | 汎用タスク |
+| `cx/gpt-5.1-codex` | GPT 5.1 Codex | 安定したコーディング |
+
+### プロのヒント
+
+- **5時間ローリングクォータ** - 5時間ごとに新鮮なクォータ
+- **週次リセット** - 週次フルクォータリセット
+- **Pro階層** - Plusの10倍のクォータ
+
+---
+
+## Gemini CLI (月18万無料!)
+
+### 料金
+
+| プラン | 月額コスト | クォータ | リセット |
+|------|--------------|-------|-------|
+| FREE | $0 | 月18万コンプリーション + 1K/日 | 日次 + 月次 |
+
+**最高の価値:** 巨大な無料階層! 有料階層の前にこれを使用。
+
+### セットアップ
+
+**ステップ1: ダッシュボード経由で接続**
+
+```bash
+9router
+# Dashboard → Providers → Connect Gemini CLI
+```
+
+**ステップ2: Google OAuth**
+
+- 「Connect Gemini CLI」をクリック
+- ブラウザが開く → Googleアカウントにログイン
+- 権限を付与
+- 自動トークン更新有効化
+
+**ステップ3: CLIで使用**
+
+```
+Model: gc/gemini-3-flash-preview
+       gc/gemini-3-pro-preview
+       gc/gemini-2.5-pro
+       gc/gemini-2.5-flash
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | 最適用途 |
+|----------|-------------|----------|
+| `gc/gemini-3-flash-preview` | Gemini 3 Flash Preview | 高速応答 |
+| `gc/gemini-3-pro-preview` | Gemini 3 Pro Preview | 複雑なタスク |
+| `gc/gemini-2.5-pro` | Gemini 2.5 Pro | 安定した本番 |
+| `gc/gemini-2.5-flash` | Gemini 2.5 Flash | クイックタスク |
+
+### プロのヒント
+
+- **月18万コンプリーション** - 巨大な無料階層
+- **1K/日制限** - 日次クォータは深夜にリセット
+- **最初に使用** - 無料階層、有料サブスクリプションの前に使用
+- **クレジットカード不要** - Googleアカウントで完全無料
+
+---
+
+## GitHub Copilot
+
+### 料金
+
+| プラン | 月額コスト | クォータリセット | モデル |
+|------|--------------|-------------|--------|
+| Individual | $10 | 月次 (1日) | GPT-5、Claude 4.5、Gemini 3 |
+| Business | $19 | 月次 (1日) | GPT-5、Claude 4.5、Gemini 3 |
+
+### セットアップ
+
+**ステップ1: ダッシュボード経由で接続**
+
+```bash
+9router
+# Dashboard → Providers → Connect GitHub
+```
+
+**ステップ2: GitHub経由のOAuth**
+
+- 「Connect GitHub」をクリック
+- ブラウザが開く → GitHubにログイン
+- GitHub Copilotを認可
+- 自動トークン更新有効化
+
+**ステップ3: CLIで使用**
+
+```
+Model: gh/gpt-5
+       gh/gpt-5.1-codex-max
+       gh/claude-4.5-sonnet
+       gh/gemini-3-pro
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | 最適用途 |
+|----------|-------------|----------|
+| `gh/gpt-5` | GPT-5 | 最新OpenAIモデル |
+| `gh/gpt-5.1-codex-max` | GPT-5.1 Codex Max | 最大コンテキスト |
+| `gh/claude-4.5-sonnet` | Claude 4.5 Sonnet | Anthropic品質 |
+| `gh/gemini-3-pro` | Gemini 3 Pro | Google品質 |
+
+### プロのヒント
+
+- **月次リセット** - 月1日にフルクォータリセット
+- **複数モデル** - 一つのサブスクリプションでGPT、Claude、Geminiにアクセス
+- **Business階層** - チーム用の高クォータ
+
+---
+
+## Antigravity (Googleアカウント)
+
+### 料金
+
+| プラン | 月額コスト | クォータ | モデル |
+|------|--------------|-------|--------|
+| FREE | $0 | Gemini CLIと同様 | Gemini 3 Pro、Claude Sonnet 4.5 |
+
+### セットアップ
+
+**ステップ1: ダッシュボード経由で接続**
+
+```bash
+9router
+# Dashboard → Providers → Connect Antigravity
+```
+
+**ステップ2: Google OAuth**
+
+- 「Connect Antigravity」をクリック
+- ブラウザが開く → Googleアカウントにログイン
+- 権限を付与
+- 自動トークン更新有効化
+
+**ステップ3: CLIで使用**
+
+```
+Model: ag/gemini-3-pro-high
+       ag/claude-sonnet-4-5
+       ag/claude-opus-4-5-thinking
+```
+
+### 利用可能なモデル
+
+| モデルID | 説明 | 最適用途 |
+|----------|-------------|----------|
+| `ag/gemini-3-pro-high` | Gemini 3 Pro High | 高品質応答 |
+| `ag/claude-sonnet-4-5` | Claude Sonnet 4.5 | Anthropic品質 |
+| `ag/claude-opus-4-5-thinking` | Claude Opus 4.5 Thinking | 複雑な推論 |
+
+### プロのヒント
+
+- **無料階層** - Googleアカウントでコストなし
+- **Claudeアクセス** - 無料Claude Sonnet/Opus
+- **Gemini CLIと同様のクォータ** - 日次/月次制限
+
+---
+
+## 料金比較
+
+| プロバイダー | 月額コスト | クォータリセット | 価値 |
+|----------|--------------|-------------|-------|
+| **Claude Code Pro** | $20 | 5時間 + 週次 | ⭐⭐⭐⭐⭐ 最高品質 |
+| **Claude Code Max** | $100 | 5時間 + 週次 | ⭐⭐⭐⭐⭐ 最高クォータ |
+| **Codex Plus** | $20 | 5時間 + 週次 | ⭐⭐⭐⭐ 良い価値 |
+| **Codex Pro** | $200 | 5時間 + 週次 | ⭐⭐⭐⭐⭐ 10×クォータ |
+| **Gemini CLI** | **$0** | 日次 + 月次 | ⭐⭐⭐⭐⭐ 月18万無料! |
+| **GitHub Copilot** | $10〜19 | 月次 (1日) | ⭐⭐⭐⭐ マルチモデル |
+| **Antigravity** | **$0** | 日次 + 月次 | ⭐⭐⭐⭐ 無料Claude! |
+
+---
+
+## 使用例
+
+### Cursor IDEセットアップ
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [9routerダッシュボードから取得]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### コンボを作成 (推奨)
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. gc/gemini-3-flash-preview (無料、最初に使用)
+  2. cc/claude-opus-4-5-20251101 (サブスクリプション)
+  3. cx/gpt-5.2-codex (サブスクリプションバックアップ)
+
+CLIで使用: premium-coding
+```
+
+**結果:** 無料階層を最大化 → サブスクリプションを使用 → 自動フォールバック
+
+---
+
+## クォータトラッキング
+
+9Routerはクォータをリアルタイムで追跡:
+
+- **トークン消費** - リクエストごとの入出力トークン
+- **リセットカウントダウン** - 次のクォータリセットまでの時間
+- **使用量パーセンテージ** - クォータの使用量
+- **自動フォールバック** - 消費時に次の階層へ切替
+
+**ダッシュボード表示:**
+
+```
+Claude Code Pro
+├─ Quota: 75% used
+├─ Reset: 2h 15m (5-hour)
+├─ Weekly reset: 3 days
+└─ Fallback: glm/glm-4.7 (cheap tier)
+```
+
+---
+
+## ベストプラクティス
+
+### 1. 無料階層を最初に使用
+
+```
+優先順位:
+1. Gemini CLI (月18万無料)
+2. Antigravity (無料Claude)
+3. Claude Code/Codex (有料サブスクリプション)
+```
+
+### 2. クォータを毎日追跡
+
+- 毎朝ダッシュボードを確認
+- クォータリセットに合わせて重いタスクを計画
+- クリティカルでないタスクには低価格/無料階層を使用
+
+### 3. スマートコンボを作成
+
+```
+コンボ例:
+1. gc/gemini-3-flash-preview (無料プライマリ)
+2. cc/claude-opus-4-5 (複雑なタスク)
+3. glm/glm-4.7 (低価格バックアップ)
+4. if/kimi-k2-thinking (無料フォールバック)
+```
+
+### 4. 時間別に最適化
+
+```
+朝: 新鮮な5時間クォータ (Claude/Codex)
+午後: Gemini CLI (1K/日)
+夕方: サブスクリプションクォータ
+夜: 低価格/無料階層
+```
+
+---
+
+## トラブルシューティング
+
+### 「クォータ消費」
+
+**解決策:**
+- ダッシュボードクォータトラッカーを確認
+- リセットを待つ (5時間または日次)
+- 低価格/無料階層へのコンボフォールバックを使用
+
+### 「OAuthトークン期限切れ」
+
+**解決策:**
+- 9Routerにより自動更新
+- 問題がある場合: Dashboard → Provider → Reconnect
+
+### 「レート制限」
+
+**解決策:**
+- サブスクリプションクォータ切れ
+- フォールバックを追加: `cc/claude-opus → glm/glm-4.7`
+- 無料階層を使用: `if/kimi-k2-thinking`
+
+---
+
+## 次のステップ
+
+- **低価格バックアップをセットアップ:** [低価格プロバイダー](./cheap.md)
+- **無料フォールバックを追加:** [無料プロバイダー](./free.md)
+- **コンボを作成:** Dashboard → Combos → Create New
diff --git a/gitbook/content/ja/troubleshooting.md b/gitbook/content/ja/troubleshooting.md
new file mode 100644
index 0000000..201fac2
--- /dev/null
+++ b/gitbook/content/ja/troubleshooting.md
@@ -0,0 +1,351 @@
+# トラブルシューティング
+
+9Router利用時の一般的な問題と解決策。
+
+---
+
+## "Language model did not provide messages"
+
+**問題:** リクエストが空のレスポンスまたはエラーメッセージで失敗。
+
+**原因:**
+- プロバイダーのクォータが消費された
+- APIキーが無効または期限切れ
+- モデルが利用不可
+
+**解決策:**
+
+1. **クォータ状況を確認:**
+   ```
+   Dashboard → Providers → クォータトラッカーを表示
+   ```
+   クォータが消費されている場合、リセットを待つかプロバイダーを切替。
+
+2. **コンボフォールバックを使用:**
+   ```
+   Dashboard → Combos → フォールバックチェーンを作成
+   例: cc/claude-opus → glm/glm-4.7 → if/kimi-k2
+   ```
+
+3. **プロバイダー接続を確認:**
+   ```
+   Dashboard → Providers → 必要に応じて再接続
+   ```
+
+---
+
+## レート制限
+
+**問題:** 「Rate limit exceeded」または「Too many requests」エラー。
+
+**原因:**
+- サブスクリプションのクォータが枯渇(5時間/日次/週次の制限)
+- APIレート制限に達した
+- 同時リクエストが多すぎる
+
+**解決策:**
+
+1. **リセット時間を確認:**
+   ```
+   Dashboard → Quota Tracking → リセットカウントダウンを表示
+   ```
+
+2. **低価格階層へ切替:**
+   ```
+   使用: glm/glm-4.7 (100万トークンあたり$0.6)
+        minimax/MiniMax-M2.1 (100万トークンあたり$0.20)
+   ```
+
+3. **フォールバックコンボを追加:**
+   ```
+   Dashboard → Combos → バックアップモデルを追加
+   優先: cc/claude-opus (サブスクリプション)
+   バックアップ: glm/glm-4.7 (低価格)
+   緊急時: if/kimi-k2 (無料)
+   ```
+
+---
+
+## OAuthトークン期限切れ
+
+**問題:** 「Unauthorized」または「Token expired」エラー。
+
+**原因:**
+- OAuthトークンが期限切れ(自動更新失敗)
+- プロバイダーセッションが無効化された
+- 更新中のネットワーク問題
+
+**解決策:**
+
+1. **自動更新(デフォルト):**
+   9Routerは自動的にトークンを更新します。30秒待ってから再試行。
+
+2. **手動で再接続:**
+   ```
+   Dashboard → Providers → [プロバイダー名] → Reconnect
+   → OAuthフローを再度完了
+   ```
+
+3. **プロバイダーステータスを確認:**
+   プロバイダーサービスがオンラインであることを確認(Claude Code、Codexなど)
+
+---
+
+## 高コスト
+
+**問題:** 予期しない高使用量またはコスト。
+
+**原因:**
+- 不必要に高価なモデルを使用
+- 低価格階層へのフォールバックがない
+- 大きなコンテキストウィンドウ
+
+**解決策:**
+
+1. **使用統計を確認:**
+   ```
+   Dashboard → Usage Stats → トークン消費量を表示
+   → 高コストモデルを特定
+   ```
+
+2. **より安いモデルへ切替:**
+   ```
+   置換: cc/claude-opus (月$20〜100サブスクリプション)
+   へ: glm/glm-4.7 (100万トークンあたり$0.6)
+       minimax/MiniMax-M2.1 (100万トークンあたり$0.20)
+   ```
+
+3. **無料階層を使用:**
+   ```
+   if/kimi-k2-thinking (無料)
+   qw/qwen3-coder-plus (無料)
+   kr/claude-sonnet-4.5 (無料)
+   gc/gemini-3-flash-preview (月18万無料)
+   ```
+
+4. **プロンプトを最適化:**
+   - コンテキストサイズを削減
+   - 長い応答にストリーミングを使用
+   - 一般的なプロンプトをキャッシュ
+
+---
+
+## Connection Refused
+
+**問題:** 「ECONNREFUSED」または「Cannot connect to localhost:20128」。
+
+**原因:**
+- 9Routerが起動していない
+- ポート20128がブロックされている
+- ファイアウォールが接続をブロック
+
+**解決策:**
+
+1. **9Routerを起動:**
+   ```bash
+   9router
+   ```
+   ダッシュボードがhttp://localhost:3000で開くはず
+
+2. **ポート20128を確認:**
+   ```bash
+   # ポートがリッスンしているか確認
+   lsof -i :20128
+   
+   # またはWindowsで
+   netstat -ano | findstr :20128
+   ```
+
+3. **ファイアウォールを確認:**
+   - macOS: システム設定 → ネットワーク → ファイアウォール
+   - Windows: Windows Defenderファイアウォール → アプリを許可
+   - Linux: `sudo ufw allow 20128`
+
+4. **クラウドエンドポイントを使用:**
+   localhostが動作しない場合(例: Cursor IDE):
+   ```
+   Endpoint: https://9router.com/v1
+   ```
+
+---
+
+## ダッシュボードが開かない
+
+**問題:** ダッシュボードがhttp://localhost:3000で読み込まれない。
+
+**原因:**
+- ポート3000がすでに使用中
+- 9Routerがクラッシュした
+- ブラウザキャッシュの問題
+
+**解決策:**
+
+1. **9Routerが実行中か確認:**
+   ```bash
+   # プロセスを確認
+   ps aux | grep 9router
+   
+   # ポート3000を確認
+   lsof -i :3000
+   ```
+
+2. **競合するプロセスを終了:**
+   ```bash
+   # macOS/Linux
+   lsof -ti:3000 | xargs kill -9
+   
+   # Windows
+   netstat -ano | findstr :3000
+   taskkill /PID <PID> /F
+   ```
+
+3. **9Routerを再起動:**
+   ```bash
+   # 停止
+   pkill -f 9router
+   
+   # 起動
+   9router
+   ```
+
+4. **ブラウザキャッシュをクリア:**
+   - Chrome: Ctrl+Shift+Delete → キャッシュをクリア
+   - シークレットモードを試す
+
+5. **ファイアウォール設定を確認:**
+   ポート3000がブロックされていないことを確認。
+
+---
+
+## モデルが見つからない
+
+**問題:** 「Model not found」または「Invalid model」エラー。
+
+**原因:**
+- プロバイダーが接続されていない
+- モデルIDのタイポ
+- プロバイダーが非アクティブ
+
+**解決策:**
+
+1. **プロバイダー接続を確認:**
+   ```
+   Dashboard → Providers → ステータスを確認(緑 = アクティブ)
+   ```
+
+2. **モデルID形式を確認:**
+   ```
+   正しい: cc/claude-opus-4-5-20251101
+   誤り: claude-opus-4-5-20251101
+   
+   形式: [provider-prefix]/[model-name]
+   ```
+
+3. **利用可能なモデルを一覧表示:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer your-api-key"
+   ```
+
+4. **プロバイダーを再接続:**
+   ```
+   Dashboard → Providers → [Provider] → Reconnect
+   ```
+
+---
+
+## 応答が遅い
+
+**問題:** リクエストに時間がかかりすぎる、またはタイムアウト。
+
+**原因:**
+- プロバイダーのレイテンシ
+- ネットワーク問題
+- 大きなコンテキスト/応答
+- プロバイダーのレート制限
+
+**解決策:**
+
+1. **プロバイダーステータスを確認:**
+   ```
+   Dashboard → Providers → レイテンシ統計を表示
+   ```
+
+2. **高速モデルへ切替:**
+   ```
+   高速: cc/claude-haiku-4-5 (HaikuはOpusより高速)
+         gc/gemini-3-flash-preview
+         qw/qwen3-coder-flash
+   ```
+
+3. **ストリーミングを使用:**
+   ```json
+   {
+     "model": "cc/claude-opus-4-5",
+     "messages": [...],
+     "stream": true
+   }
+   ```
+
+4. **ネットワークを確認:**
+   ```bash
+   # レイテンシをテスト
+   ping api.anthropic.com
+   ping api.openai.com
+   ```
+
+5. **コンテキストサイズを削減:**
+   - メッセージ履歴をトリミング
+   - 短いプロンプトを使用
+   - CLIツールでコンテキストの剪定を有効化
+
+---
+
+## APIキー無効
+
+**問題:** 「Invalid API key」または「Authentication failed」エラー。
+
+**原因:**
+- 間違ったAPIキーをコピー
+- APIキーが期限切れ
+- APIキーが生成されていない
+
+**解決策:**
+
+1. **APIキーを再生成:**
+   ```
+   Dashboard → Settings → API Keys → Generate New Key
+   → 新しいキーをコピーして使用
+   ```
+
+2. **キー形式を確認:**
+   ```
+   正しい: 9r_xxxxxxxxxxxxxxxxxxxxxxxx
+   誤り: 9r_プレフィックスがない
+   ```
+
+3. **CLI設定でキーを確認:**
+   ```bash
+   # Cursor
+   Settings → Models → OpenAI API Key
+   
+   # Cline
+   Settings → API Key
+   
+   # 環境変数
+   export OPENAI_API_KEY="9r_your_key"
+   ```
+
+4. **APIキーをテスト:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer 9r_your_key"
+   ```
+
+---
+
+## さらにヘルプが必要?
+
+- **GitHub Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **ドキュメント:** [9router.com/docs](https://9router.com/docs)
+- **FAQ:** [faq.md](faq.md)
diff --git a/gitbook/content/vi/deployment/cloud.md b/gitbook/content/vi/deployment/cloud.md
new file mode 100644
index 0000000..06ba271
--- /dev/null
+++ b/gitbook/content/vi/deployment/cloud.md
@@ -0,0 +1,473 @@
+# ☁️ Triển khai Cloud
+
+Triển khai 9Router trên VPS hoặc Docker để truy cập từ xa và dùng trong production.
+
+---
+
+## 🖥️ Triển khai VPS
+
+### Yêu cầu
+
+- Ubuntu 20.04+ hoặc distro Linux tương tự
+- Node.js 20+
+- Git
+- Quyền root hoặc sudo
+
+### Bước 1: Clone Repository
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+```
+
+### Bước 2: Cài đặt Dependencies
+
+```bash
+npm install
+```
+
+### Bước 3: Build Application
+
+```bash
+npm run build
+```
+
+### Bước 4: Cấu hình biến môi trường
+
+Tạo file `.env` hoặc export biến:
+
+```bash
+export JWT_SECRET="your-secure-secret-change-this-to-random-string"
+export INITIAL_PASSWORD="your-secure-password"
+export DATA_DIR="/var/lib/9router"
+export NODE_ENV="production"
+```
+
+**Biến môi trường:**
+
+| Biến | Mặc định | Mô tả |
+|----------|---------|-------------|
+| `JWT_SECRET` | Auto-generated | **PHẢI đổi trong production!** Dùng để ký JWT token |
+| `INITIAL_PASSWORD` | `123456` | Mật khẩu đăng nhập Dashboard |
+| `DATA_DIR` | `~/.9router` | Đường dẫn lưu database và data |
+| `NODE_ENV` | `development` | Đặt `production` cho deployment |
+| `ENABLE_REQUEST_LOGS` | `false` | Bật debug request/response logs |
+
+### Bước 5: Tạo Data Directory
+
+```bash
+sudo mkdir -p /var/lib/9router
+sudo chown $USER:$USER /var/lib/9router
+```
+
+### Bước 6: Khởi động Application
+
+```bash
+npm run start
+```
+
+### Bước 7: Setup PM2 cho Production
+
+PM2 giữ application chạy và tự khởi động lại khi crash:
+
+```bash
+# Install PM2 globally
+npm install -g pm2
+
+# Start 9Router with PM2
+pm2 start npm --name 9router -- start
+
+# Save PM2 configuration
+pm2 save
+
+# Setup PM2 to start on system boot
+pm2 startup
+# Follow the instructions printed by the command above
+```
+
+**Lệnh quản lý PM2:**
+
+```bash
+# View logs
+pm2 logs 9router
+
+# Restart application
+pm2 restart 9router
+
+# Stop application
+pm2 stop 9router
+
+# View status
+pm2 status
+
+# Monitor resources
+pm2 monit
+```
+
+---
+
+## 🐳 Triển khai Docker
+
+### Cách 1: Dùng Dockerfile
+
+Tạo `Dockerfile` trong thư mục `app`:
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy application files
+COPY . .
+
+# Build application
+RUN npm run build
+
+# Expose ports
+EXPOSE 3000 20128
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV DATA_DIR=/app/data
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Start application
+CMD ["npm", "run", "start"]
+```
+
+**Build và Run:**
+
+```bash
+# Build image
+docker build -t 9router .
+
+# Run container
+docker run -d \
+  --name 9router \
+  -p 3000:3000 \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret-change-this" \
+  -e INITIAL_PASSWORD="your-secure-password" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Cách 2: Docker Compose
+
+Tạo `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  9router:
+    build: .
+    container_name: 9router
+    ports:
+      - "3000:3000"
+      - "20128:20128"
+    environment:
+      - NODE_ENV=production
+      - JWT_SECRET=your-secure-secret-change-this
+      - INITIAL_PASSWORD=your-secure-password
+      - DATA_DIR=/app/data
+    volumes:
+      - 9router-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  9router-data:
+```
+
+**Chạy với Docker Compose:**
+
+```bash
+# Start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+
+# Rebuild and restart
+docker-compose up -d --build
+```
+
+---
+
+## 🌐 Reverse Proxy với Nginx
+
+### Tại sao dùng Nginx?
+
+- Terminate SSL/TLS
+- Map domain
+- Load balancing
+- Bảo mật tốt hơn
+
+### Bước 1: Cài đặt Nginx
+
+```bash
+sudo apt update
+sudo apt install nginx
+```
+
+### Bước 2: Cấu hình Nginx
+
+Tạo `/etc/nginx/sites-available/9router`:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    # SSL certificates (use certbot to generate)
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    # SSL configuration
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # Proxy to 9Router
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+
+    # API endpoint
+    location /v1 {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+### Bước 3: Enable Site
+
+```bash
+# Create symbolic link
+sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/
+
+# Test configuration
+sudo nginx -t
+
+# Reload Nginx
+sudo systemctl reload nginx
+```
+
+### Bước 4: Setup SSL với Let's Encrypt
+
+```bash
+# Install certbot
+sudo apt install certbot python3-certbot-nginx
+
+# Obtain SSL certificate
+sudo certbot --nginx -d your-domain.com
+
+# Auto-renewal is configured automatically
+# Test renewal
+sudo certbot renew --dry-run
+```
+
+---
+
+## 🔒 Cân nhắc về Bảo mật
+
+### 1. Đổi credentials mặc định
+
+**QUAN TRỌNG:** Đổi `JWT_SECRET` và `INITIAL_PASSWORD` trước khi deploy:
+
+```bash
+# Generate secure JWT secret
+openssl rand -base64 32
+
+# Use this value for JWT_SECRET
+export JWT_SECRET="generated-secret-here"
+```
+
+### 2. Cấu hình Firewall
+
+```bash
+# Allow SSH
+sudo ufw allow 22/tcp
+
+# Allow HTTP/HTTPS (if using Nginx)
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+
+# If NOT using reverse proxy, allow 9Router ports
+sudo ufw allow 3000/tcp
+sudo ufw allow 20128/tcp
+
+# Enable firewall
+sudo ufw enable
+```
+
+### 3. Giới hạn truy cập Dashboard
+
+Nếu chỉ cần truy cập API, giới hạn port dashboard:
+
+```bash
+# Only allow localhost access to dashboard
+sudo ufw deny 3000/tcp
+```
+
+Truy cập dashboard qua SSH tunnel:
+
+```bash
+ssh -L 3000:localhost:3000 user@your-server.com
+# Then open http://localhost:3000 in your browser
+```
+
+### 4. Cập nhật định kỳ
+
+```bash
+# Update system packages
+sudo apt update && sudo apt upgrade -y
+
+# Update 9Router
+cd /path/to/9router/app
+git pull
+npm install
+npm run build
+pm2 restart 9router
+```
+
+### 5. Chiến lược Backup
+
+```bash
+# Backup data directory
+tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router
+
+# Automated daily backup (add to crontab)
+0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router
+```
+
+---
+
+## 📊 Giám sát
+
+### Kiểm tra trạng thái Application
+
+```bash
+# PM2 status
+pm2 status
+
+# View logs
+pm2 logs 9router --lines 100
+
+# Monitor resources
+pm2 monit
+```
+
+### Nginx Logs
+
+```bash
+# Access logs
+sudo tail -f /var/log/nginx/access.log
+
+# Error logs
+sudo tail -f /var/log/nginx/error.log
+```
+
+### Tài nguyên hệ thống
+
+```bash
+# CPU and memory usage
+htop
+
+# Disk usage
+df -h
+
+# Network connections
+netstat -tulpn | grep -E '3000|20128'
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### Application không khởi động
+
+```bash
+# Check logs
+pm2 logs 9router
+
+# Check if ports are in use
+sudo lsof -i :3000
+sudo lsof -i :20128
+
+# Check environment variables
+pm2 env 9router
+```
+
+### Nginx 502 Bad Gateway
+
+```bash
+# Check if 9Router is running
+pm2 status
+
+# Check Nginx error logs
+sudo tail -f /var/log/nginx/error.log
+
+# Test Nginx configuration
+sudo nginx -t
+```
+
+### SSE Streaming không hoạt động
+
+Đảm bảo `proxy_buffering off` được set trong cấu hình Nginx để hỗ trợ SSE.
+
+### Lỗi Permission Denied
+
+```bash
+# Fix data directory permissions
+sudo chown -R $USER:$USER /var/lib/9router
+chmod 755 /var/lib/9router
+```
+
+---
+
+## 🔗 Bước tiếp theo
+
+- [Kết nối Providers](/providers/subscription.md)
+- [Setup Combos](/features/combos.md)
+- [Tích hợp với Tools](/integration/cursor.md)
diff --git a/gitbook/content/vi/deployment/localhost.md b/gitbook/content/vi/deployment/localhost.md
new file mode 100644
index 0000000..b6fc38c
--- /dev/null
+++ b/gitbook/content/vi/deployment/localhost.md
@@ -0,0 +1,164 @@
+# 🏠 Triển khai Localhost
+
+Chạy 9Router trên máy cá nhân để phát triển và dùng cá nhân.
+
+---
+
+## 📦 Cài đặt
+
+Cài đặt 9Router toàn cục qua npm:
+
+```bash
+npm install -g 9router
+```
+
+**Yêu cầu:**
+- Node.js 20 trở lên
+- npm 9 trở lên
+
+---
+
+## 🚀 Khởi động Server
+
+Khởi động 9Router với một lệnh duy nhất:
+
+```bash
+9router
+```
+
+Dashboard sẽ tự động mở trong trình duyệt tại `http://localhost:3000`
+
+**Cấu hình mặc định:**
+- **Dashboard**: `http://localhost:3000`
+- **API Endpoint**: `http://localhost:20128/v1`
+- **Data Directory**: `~/.9router`
+
+---
+
+## 🔧 Cấu hình
+
+### Custom Data Directory
+
+Đặt thư mục data tùy chỉnh qua biến môi trường:
+
+```bash
+DATA_DIR=/path/to/data 9router
+```
+
+### Custom Port
+
+Port API (20128) và port dashboard (3000) được cấu hình trong application. Để đổi, bạn cần sửa source code hoặc dùng biến môi trường nếu được hỗ trợ.
+
+---
+
+## 🛑 Dừng Server
+
+Nhấn `Ctrl+C` trong terminal đang chạy 9Router.
+
+```bash
+# In the terminal running 9router
+^C  # Press Ctrl+C
+```
+
+Server sẽ shutdown an toàn và lưu mọi dữ liệu.
+
+---
+
+## 🔄 Khởi động lại Server
+
+Chỉ cần chạy lệnh start lại:
+
+```bash
+9router
+```
+
+Mọi cấu hình, API keys và combos được giữ lại trong thư mục data.
+
+---
+
+## 📊 Cập nhật 9Router
+
+Cập nhật phiên bản mới nhất:
+
+```bash
+npm update -g 9router
+```
+
+Kiểm tra version hiện tại:
+
+```bash
+npm list -g 9router
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### Port đã được dùng
+
+Nếu port 20128 hoặc 3000 đã được dùng:
+
+```bash
+# Find process using the port (macOS/Linux)
+lsof -i :20128
+lsof -i :3000
+
+# Kill the process
+kill -9 <PID>
+```
+
+### Lỗi Permission
+
+Nếu gặp lỗi permission khi cài đặt:
+
+```bash
+# Use sudo (not recommended)
+sudo npm install -g 9router
+
+# Or fix npm permissions (recommended)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Vấn đề Data Directory
+
+Nếu thư mục data không truy cập được:
+
+```bash
+# Check permissions
+ls -la ~/.9router
+
+# Fix permissions
+chmod 755 ~/.9router
+```
+
+---
+
+## 📁 Cấu trúc Data Directory
+
+```
+~/.9router/
+├── db.json           # Main database (providers, combos, settings)
+├── logs/             # Application logs
+└── cache/            # Temporary cache files
+```
+
+**Backup Data:**
+
+```bash
+# Backup
+cp -r ~/.9router ~/.9router.backup
+
+# Restore
+cp -r ~/.9router.backup ~/.9router
+```
+
+---
+
+## 🔗 Bước tiếp theo
+
+- [Kết nối Providers](/providers/subscription.md)
+- [Tạo Combos](/features/combos.md)
+- [Tích hợp với CLI Tools](/integration/cursor.md)
diff --git a/gitbook/content/vi/faq.md b/gitbook/content/vi/faq.md
new file mode 100644
index 0000000..d1c5280
--- /dev/null
+++ b/gitbook/content/vi/faq.md
@@ -0,0 +1,387 @@
+# Câu hỏi thường gặp
+
+Những câu hỏi phổ biến về 9Router.
+
+---
+
+## 9Router là gì?
+
+**9Router là bộ định tuyến mô hình AI giúp tối đa hóa giá trị subscription và giảm chi phí.**
+
+Nó định tuyến request thông minh qua nhiều provider AI bằng hệ thống fallback 3 tầng:
+1. **Tầng Subscription** - Tối đa quota Claude Code, Codex, Gemini bạn đang trả tiền
+2. **Tầng Cheap** - Lựa chọn siêu rẻ ($0.20-$0.60 per 1M tokens)
+3. **Tầng Free** - Backup khẩn cấp với model miễn phí không giới hạn
+
+**Lợi ích chính:**
+- Không bao giờ lãng phí quota subscription
+- Fallback tự động khi hết quota
+- Theo dõi quota thời gian thực
+- Tiết kiệm 90% chi phí so với dùng API trực tiếp
+
+---
+
+## Pricing hoạt động thế nào?
+
+**9Router dùng chiến lược pricing 3 tầng:**
+
+### Tier 1: Subscription (Dùng đầu tiên)
+- **Claude Code** (Pro/Max): $20-100/tháng - Quota 5 giờ + hàng tuần
+- **OpenAI Codex** (Plus/Pro): $20-200/tháng - Quota 5 giờ + hàng tuần
+- **Gemini CLI**: MIỄN PHÍ - 180K completions/tháng + 1K/ngày
+- **GitHub Copilot**: $10-19/tháng - Reset hàng tháng
+- **Antigravity**: MIỄN PHÍ - Tương tự Gemini
+
+**Mục tiêu:** Dùng hết mọi quota trước khi reset!
+
+### Tier 2: Cheap (Backup)
+- **GLM-4.7**: $0.60/$2.20 per 1M tokens - Reset 10AM hàng ngày
+- **MiniMax M2.1**: $0.20/$1.00 per 1M tokens - 5 giờ rolling
+- **Kimi K2**: $9/tháng cố định (10M tokens)
+
+**Mục tiêu:** Rẻ hơn 90% so với ChatGPT API ($20/1M)!
+
+### Tier 3: Free (Khẩn cấp)
+- **iFlow**: 8 model MIỄN PHÍ (Kimi K2, Qwen3, GLM, MiniMax...)
+- **Qwen**: 3 model MIỄN PHÍ (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro**: 2 model MIỄN PHÍ (Claude Sonnet 4.5, Haiku 4.5)
+
+**Mục tiêu:** Fallback chi phí 0 khi mọi thứ khác bị giới hạn quota!
+
+---
+
+## 9Router có miễn phí không?
+
+**Có, 9Router hoàn toàn miễn phí và mã nguồn mở 100%.**
+
+**Provider free tier có sẵn:**
+- **Gemini CLI** - 180K completions/tháng (MIỄN PHÍ tài khoản Google)
+- **iFlow** - 8 model không giới hạn (MIỄN PHÍ OAuth)
+- **Qwen** - 3 model không giới hạn (MIỄN PHÍ OAuth)
+- **Kiro** - Claude Sonnet/Haiku (MIỄN PHÍ AWS Builder ID)
+
+**Bạn có thể code MIỄN PHÍ mãi mãi chỉ dùng provider free tier!**
+
+**Provider trả phí tùy chọn:**
+- Dịch vụ subscription bạn có thể đã có (Claude Code, Codex, Copilot)
+- Lựa chọn siêu rẻ ($0.20-$0.60 per 1M tokens)
+
+---
+
+## Provider nào được hỗ trợ?
+
+### Subscription Providers
+- **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
+- **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
+- **Gemini CLI** (MIỄN PHÍ) - Gemini 3 Flash/Pro, 2.5 Pro/Flash
+- **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
+- **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
+
+### Cheap Providers
+- **GLM** (Zhipu AI) - GLM 4.7, GLM 4.6V Vision
+- **MiniMax** - MiniMax M2.1
+- **Kimi** (Moonshot AI) - Kimi Latest
+- **OpenRouter** - Passthrough đến mọi model OpenRouter
+
+### Free Providers
+- **iFlow** - 8 models (Kimi K2, Qwen3, GLM, MiniMax, DeepSeek...)
+- **Qwen** - 3 models (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro** - 2 models (Claude Sonnet 4.5, Haiku 4.5)
+
+**Tổng: 15+ providers, 50+ models**
+
+Xem [tài liệu providers](providers/subscription.md) để biết chi tiết.
+
+---
+
+## Tôi có thể dùng nhiều provider không?
+
+**Có! Đây là tính năng cốt lõi của 9Router.**
+
+**Combo cho phép bạn nối nhiều provider với fallback tự động:**
+
+```
+Example combo: "premium-coding"
+1. cc/claude-opus-4-5 (Subscription primary)
+2. glm/glm-4.7 (Cheap backup)
+3. if/kimi-k2 (Free emergency)
+
+→ Auto-switches when quota exhausted
+→ Never stops coding
+→ Minimal extra cost
+```
+
+**Cách tạo combo:**
+```
+Dashboard → Combos → Create New
+→ Add models in priority order
+→ Use combo name in CLI: "premium-coding"
+```
+
+**Lợi ích:**
+- Zero downtime khi hết quota
+- Tối ưu chi phí tự động
+- Một tên model cho mọi công cụ
+
+Xem [tài liệu combos](features/combos.md) để biết ví dụ.
+
+---
+
+## Quota tracking hoạt động thế nào?
+
+**9Router theo dõi quota thời gian thực cho tất cả provider:**
+
+**Tính năng:**
+- **Token consumption** - Tokens input/output mỗi request
+- **Reset countdown** - Thời gian đến khi quota refresh
+- **Usage stats** - Báo cáo hàng ngày/tuần/tháng
+- **Cost estimation** - Dự kiến chi tiêu (tier trả phí)
+- **Quota alerts** - Thông báo khi quota thấp
+
+**Loại quota:**
+- **5 giờ rolling** - Claude Code, Codex, MiniMax
+- **Reset hàng ngày** - Gemini CLI (1K/ngày), GLM (10AM)
+- **Reset hàng tuần** - Claude Code, Codex (quota thêm)
+- **Reset hàng tháng** - Gemini CLI (180K), GitHub Copilot (ngày 1)
+
+**Xem quota:**
+```
+Dashboard → Providers → Quota Tracking
+→ Real-time usage + reset countdown
+```
+
+Xem [tài liệu quota tracking](features/quota-tracking.md) để biết chi tiết.
+
+---
+
+## 9Router có hoạt động với Cursor không?
+
+**Có, nhưng Cursor yêu cầu endpoint cloud.**
+
+**Vấn đề:** Cursor IDE không hỗ trợ endpoint localhost.
+
+**Giải pháp:** Dùng 9Router cloud deployment:
+
+```
+Cursor Settings → Models → Advanced:
+  OpenAI API Base URL: https://9router.com/v1
+  OpenAI API Key: [from dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+**Thay thế:** Self-host trên VPS với domain công khai:
+```bash
+# Deploy to VPS
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+npm start
+
+# Configure Nginx reverse proxy
+# Point Cursor to: https://your-domain.com/v1
+```
+
+**Công cụ CLI khác hoạt động với localhost:**
+- Cline ✅
+- Claude Desktop ✅
+- Codex CLI ✅
+- Continue ✅
+- RooCode ✅
+
+Xem [hướng dẫn tích hợp Cursor](integration/cursor.md) để biết chi tiết.
+
+---
+
+## Tôi có thể self-host 9Router không?
+
+**Có! 9Router hỗ trợ nhiều tùy chọn deployment:**
+
+### Localhost (Mặc định)
+```bash
+npm install -g 9router
+9router
+→ Dashboard: http://localhost:3000
+→ API: http://localhost:20128/v1
+```
+
+### VPS/Cloud
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+npm start
+```
+
+### Docker
+```bash
+docker build -t 9router .
+docker run -d \
+  -p 3000:3000 \
+  -e JWT_SECRET="your-secret" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Cloudflare Workers
+```bash
+cd 9router/app
+npm run deploy:cloudflare
+```
+
+**Biến môi trường:**
+- `JWT_SECRET` - **PHẢI đổi trong production!**
+- `DATA_DIR` - Đường dẫn lưu database (mặc định: `~/.9router`)
+- `INITIAL_PASSWORD` - Đăng nhập Dashboard (mặc định: `123456`)
+- `NODE_ENV` - Đặt `production` để deploy
+
+Xem [hướng dẫn deployment](getting-started/installation.md#deployment) để biết chi tiết.
+
+---
+
+## Dữ liệu của tôi có an toàn không?
+
+**Có, 9Router ưu tiên bảo mật và quyền riêng tư:**
+
+**Local storage:**
+- Mọi dữ liệu lưu cục bộ tại `~/.9router` (hoặc `DATA_DIR` tùy chỉnh)
+- Không gửi data đến server 9Router
+- OAuth tokens mã hóa bằng JWT
+
+**Không telemetry:**
+- Không tracking sử dụng
+- Không analytics
+- Không phone-home
+
+**Mã nguồn mở:**
+- Toàn bộ source code có trên GitHub
+- Tự audit bảo mật
+- Community review
+
+**Best practice:**
+- Đổi `JWT_SECRET` trong production
+- Dùng `INITIAL_PASSWORD` mạnh
+- Bật HTTPS cho cloud deployment
+- Xoay API key định kỳ
+
+**9Router lưu gì:**
+- Tokens OAuth của provider (mã hóa)
+- API keys (mã hóa)
+- Thống kê sử dụng (chỉ cục bộ)
+- Cấu hình combo
+
+**9Router KHÔNG lưu:**
+- Prompts hoặc responses của bạn
+- Code bạn tạo
+- Thông tin cá nhân
+
+---
+
+## Làm thế nào để cập nhật 9Router?
+
+**Phương thức cập nhật phụ thuộc loại cài đặt:**
+
+### Global NPM Install
+```bash
+npm update -g 9router
+```
+
+### Local Install
+```bash
+cd 9router/app
+git pull origin main
+npm install
+npm run build
+npm start
+```
+
+### Docker
+```bash
+docker pull 9router:latest
+docker stop 9router
+docker rm 9router
+docker run -d \
+  -p 3000:3000 \
+  -v 9router-data:/app/data \
+  9router:latest
+```
+
+**Kiểm tra version:**
+```bash
+9router --version
+```
+
+**Breaking changes:**
+- Xem [CHANGELOG.md](https://github.com/decolua/9router/blob/main/CHANGELOG.md)
+- Backup `~/.9router` trước khi update lớn
+- Xem hướng dẫn migration cho major version
+
+---
+
+## Tôi có thể đóng góp như thế nào?
+
+**Chúng tôi hoan nghênh đóng góp!**
+
+### Các cách đóng góp:
+
+1. **Report bugs:**
+   - [GitHub Issues](https://github.com/decolua/9router/issues)
+   - Bao gồm error logs, các bước reproduce
+
+2. **Request features:**
+   - [GitHub Discussions](https://github.com/decolua/9router/discussions)
+   - Mô tả use case và lợi ích
+
+3. **Submit code:**
+   ```bash
+   # Fork repo
+   git clone https://github.com/YOUR_USERNAME/9router.git
+   cd 9router
+   
+   # Create branch
+   git checkout -b feature/your-feature
+   
+   # Make changes
+   npm install
+   npm run dev
+   
+   # Test
+   npm test
+   
+   # Commit and push
+   git add .
+   git commit -m "Add your feature"
+   git push origin feature/your-feature
+   
+   # Create Pull Request on GitHub
+   ```
+
+4. **Cải thiện docs:**
+   - Sửa lỗi chính tả, thêm ví dụ
+   - Dịch sang ngôn ngữ khác
+   - Viết tutorial
+
+5. **Thêm provider:**
+   - Triển khai adapter provider mới
+   - Xem `app/lib/providers/` để có ví dụ
+
+**Hướng dẫn đóng góp:**
+- Tuân theo code style hiện có
+- Thêm test cho tính năng mới
+- Cập nhật tài liệu
+- Giữ commit nhỏ gọn và mô tả rõ ràng
+
+Xem [CONTRIBUTING.md](https://github.com/decolua/9router/blob/main/CONTRIBUTING.md) để biết chi tiết.
+
+---
+
+## Cần trợ giúp thêm?
+
+- **Documentation:** [9router.com/docs](https://9router.com/docs)
+- **GitHub:** [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **Troubleshooting:** [troubleshooting.md](troubleshooting.md)
diff --git a/gitbook/content/vi/features/combos.md b/gitbook/content/vi/features/combos.md
new file mode 100644
index 0000000..b583df6
--- /dev/null
+++ b/gitbook/content/vi/features/combos.md
@@ -0,0 +1,537 @@
+# Combos - Chuỗi Fallback Tùy chỉnh
+
+Tạo các tổ hợp model tùy chỉnh với fallback tự động. Combo cho phép bạn định nghĩa chiến lược routing dựa trên chi phí, chất lượng và tính khả dụng.
+
+---
+
+## Combos là gì?
+
+Combos là **chuỗi fallback tùy chỉnh** bạn tạo trong dashboard. Thay vì dùng một model duy nhất, bạn định nghĩa một chuỗi các model mà 9Router sẽ thử theo thứ tự.
+
+**Ví dụ:**
+```
+Combo name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101 (try first)
+  2. glm/glm-4.7 (if #1 quota exhausted)
+  3. minimax/MiniMax-M2.1 (if #2 quota exhausted)
+```
+
+**Dùng trong CLI:**
+```
+Model: premium-coding
+```
+
+9Router tự động thử từng model theo thứ tự cho đến khi thành công.
+
+---
+
+## Tại sao dùng Combos?
+
+### 1. Tối đa hóa Giá trị Subscription
+```
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ Use subscription first, cheap backup, free emergency
+→ Get full value from subscriptions you already pay for
+```
+
+### 2. Giảm Chi phí
+```
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+
+→ Start with cheapest paid option ($0.60/1M)
+→ Fallback to even cheaper ($0.20/1M)
+→ Emergency free tier
+→ Total cost: ~$5-10/month vs $2000 on ChatGPT API
+```
+
+### 3. Đảm bảo Khả dụng 24/7
+```
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ Always include free tier at the end
+→ Never run out of quota
+→ Code anytime, anywhere
+```
+
+### 4. Tối ưu Chất lượng
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → gc/gemini-3-pro
+
+→ Best models first
+→ Fallback to other premium models
+→ Maintain high quality across fallback chain
+```
+
+---
+
+## Cách tạo Combos
+
+### Bước 1: Mở Dashboard
+
+```
+http://localhost:20128
+→ Login with your password
+```
+
+### Bước 2: Đi đến Combos
+
+```
+Dashboard → Combos → Create New Combo
+```
+
+### Bước 3: Cấu hình Combo
+
+**Tên Combo:**
+```
+premium-coding
+```
+
+**Mô tả (tùy chọn):**
+```
+Subscription first, cheap backup, free emergency
+```
+
+**Chọn Models:**
+```
+1. cc/claude-opus-4-5-20251101
+2. glm/glm-4.7
+3. minimax/MiniMax-M2.1
+```
+
+**Kéo để sắp xếp lại** - Ưu tiên từ trên xuống dưới.
+
+### Bước 4: Lưu
+
+```
+Click "Save Combo"
+→ Combo appears in model list
+```
+
+### Bước 5: Dùng trong CLI
+
+```
+Cursor/Cline/Any tool:
+  Model: premium-coding
+```
+
+---
+
+## Ví dụ Combos
+
+### Ví dụ 1: Premium Coding (Subscription → Cheap → Free)
+
+**Mục tiêu**: Tối đa giá trị subscription, giảm chi phí thêm.
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101
+  2. glm/glm-4.7
+  3. minimax/MiniMax-M2.1
+```
+
+**Sử dụng:**
+```
+Cursor IDE:
+  Model: premium-coding
+```
+
+**Hoạt động:**
+```
+Morning (fresh quota):
+  Request → cc/claude-opus-4-5 ✅
+
+Afternoon (Claude quota out):
+  Request → glm/glm-4.7 ✅ (auto switched)
+
+Evening (GLM quota out):
+  Request → minimax/MiniMax-M2.1 ✅ (auto switched)
+```
+
+**Chi phí hàng tháng (100M tokens):**
+```
+80M via Claude Code: $0 (subscription)
+15M via GLM: $9
+5M via MiniMax: $1
+Total: $10 + your subscription
+```
+
+**Tiết kiệm**: ~99% so với ChatGPT API ($2000).
+
+---
+
+### Ví dụ 2: Budget Combo (Cheap → Free)
+
+**Mục tiêu**: Giảm chi phí, dùng free tier làm backup.
+
+```
+Dashboard → Combos → Create New
+
+Name: budget-combo
+Models:
+  1. glm/glm-4.7
+  2. minimax/MiniMax-M2.1
+  3. if/kimi-k2-thinking
+```
+
+**Sử dụng:**
+```
+Cline:
+  Provider: OpenAI Compatible
+  Base URL: http://localhost:20128/v1
+  Model: budget-combo
+```
+
+**Hoạt động:**
+```
+Request → glm/glm-4.7
+  ✅ Daily quota available → Use GLM ($0.60/1M)
+  ❌ Quota exhausted → Try MiniMax ($0.20/1M)
+  ❌ MiniMax quota out → Use iFlow (FREE)
+```
+
+**Chi phí hàng tháng (100M tokens):**
+```
+70M via GLM: $42
+20M via MiniMax: $4
+10M via iFlow: $0
+Total: $46 vs $2000 on ChatGPT API
+```
+
+**Tiết kiệm**: 97%.
+
+---
+
+### Ví dụ 3: Free Combo (Chi phí 0)
+
+**Mục tiêu**: 100% miễn phí, không bao giờ tốn tiền.
+
+```
+Dashboard → Combos → Create New
+
+Name: free-combo
+Models:
+  1. if/kimi-k2-thinking
+  2. qw/qwen3-coder-plus
+  3. kr/claude-sonnet-4.5
+```
+
+**Sử dụng:**
+```
+Claude Desktop:
+  Model: free-combo
+```
+
+**Hoạt động:**
+```
+Request → if/kimi-k2-thinking
+  ✅ Available → Use iFlow
+  ❌ Error → Try Qwen
+  ❌ Error → Try Kiro
+```
+
+**Chi phí hàng tháng:**
+```
+100M tokens via free providers: $0
+Total: $0 forever
+```
+
+**Use case**: Dự án cá nhân, học tập, thử nghiệm.
+
+---
+
+### Ví dụ 4: Quality First (Chỉ Premium Models)
+
+**Mục tiêu**: Chất lượng tốt nhất, không fallback rẻ.
+
+```
+Dashboard → Combos → Create New
+
+Name: quality-first
+Models:
+  1. cc/claude-opus-4-5-20251101
+  2. cx/gpt-5.2-codex
+  3. gc/gemini-3-pro-preview
+```
+
+**Sử dụng:**
+```
+Codex CLI:
+  export OPENAI_BASE_URL="http://localhost:20128"
+  Model: quality-first
+```
+
+**Hoạt động:**
+```
+Request → cc/claude-opus-4-5
+  ❌ Quota out → cx/gpt-5.2-codex
+  ❌ Quota out → gc/gemini-3-pro-preview
+  ❌ All out → Return error (no cheap fallback)
+```
+
+**Use case**: Code production quan trọng, refactoring phức tạp.
+
+---
+
+### Ví dụ 5: Multi-Subscription (Tối đa hết tất cả)
+
+**Mục tiêu**: Dùng hết subscription trước khi trả thêm tiền.
+
+```
+Dashboard → Combos → Create New
+
+Name: multi-sub
+Models:
+  1. gc/gemini-3-flash-preview (FREE 180K/month)
+  2. cc/claude-opus-4-5-20251101 (Pro subscription)
+  3. cx/gpt-5.2-codex (Plus subscription)
+  4. gh/gpt-5 (Copilot subscription)
+  5. glm/glm-4.7 (Cheap backup)
+  6. if/kimi-k2-thinking (Free emergency)
+```
+
+**Chi phí hàng tháng (200M tokens):**
+```
+50M via Gemini CLI: $0 (free tier)
+80M via Claude Code: $0 (subscription)
+40M via Codex: $0 (subscription)
+20M via Copilot: $0 (subscription)
+8M via GLM: $4.80
+2M via iFlow: $0
+Total: $4.80 + existing subscriptions
+```
+
+**Kết quả**: Dùng 190M tokens từ subscription, chỉ $4.80 phụ.
+
+---
+
+### Ví dụ 6: Tối ưu Reset Quota
+
+**Mục tiêu**: Phân bổ sử dụng dựa trên thời gian reset.
+
+```
+Dashboard → Combos → Create New
+
+Name: reset-optimized
+Models:
+  1. cc/claude-opus-4-5 (5h reset, use morning)
+  2. gc/gemini-3-flash (1K/day, use afternoon)
+  3. glm/glm-4.7 (daily 10AM reset, use evening)
+  4. minimax/MiniMax-M2.1 (5h rolling, use night)
+  5. if/kimi-k2-thinking (unlimited, emergency)
+```
+
+**Lịch trình hàng ngày:**
+```
+08:00 - 13:00: Claude Code (fresh 5h quota)
+13:00 - 18:00: Gemini CLI (1K/day quota)
+18:00 - 22:00: GLM (resets 10AM next day)
+22:00 - 08:00: MiniMax (5h rolling) or iFlow
+```
+
+**Kết quả**: Code 24/7 với chi phí tối thiểu.
+
+---
+
+## Dùng Combos trong CLI Tools
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from dashboard]
+  Model: premium-coding
+```
+
+### Claude Desktop
+
+Sửa `~/.claude/config.json`:
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key",
+  "model": "budget-combo"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex --model quality-first "your prompt"
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: free-combo
+```
+
+### API Request
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "premium-coding",
+    "messages": [
+      {"role": "user", "content": "Write a function to..."}
+    ],
+    "stream": true
+  }'
+```
+
+---
+
+## Best Practices
+
+### 1. Luôn bao gồm Free Tier
+
+```
+✅ Good:
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+❌ Bad:
+cc/claude-opus → glm/glm-4.7
+(no free fallback, can run out of quota)
+```
+
+**Lý do**: Đảm bảo khả dụng 24/7, không bao giờ bị chặn bởi quota.
+
+### 2. Sắp xếp theo Chi phí (Rẻ đến Đắt)
+
+```
+✅ Good:
+glm/glm-4.7 → minimax/MiniMax-M2.1 → cc/claude-opus
+
+❌ Bad:
+cc/claude-opus → glm/glm-4.7
+(wastes subscription quota on simple tasks)
+```
+
+**Ngoại lệ**: Nếu muốn tối đa giá trị subscription, đặt subscription đầu tiên.
+
+### 3. Phù hợp với Yêu cầu Chất lượng
+
+```
+For production code:
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7
+
+For quick tasks:
+glm/glm-4.7 → if/kimi-k2-thinking
+
+For experimentation:
+if/kimi-k2-thinking → qw/qwen3-coder-plus
+```
+
+### 4. Cân nhắc Thời gian Reset Quota
+
+```
+Morning combo (fresh quotas):
+cc/claude-opus → cx/gpt-5.2-codex
+
+Evening combo (quotas likely exhausted):
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+### 5. Tạo nhiều Combo cho các Use Case khác nhau
+
+```
+premium-coding: For complex tasks
+budget-combo: For simple tasks
+free-combo: For experimentation
+quality-first: For production code
+```
+
+**Chuyển đổi combo** dựa trên yêu cầu task.
+
+### 6. Theo dõi hiệu năng Combo
+
+```
+Dashboard → Analytics → Combo Usage:
+  premium-coding:
+    80% via cc/claude-opus (good, using subscription)
+    15% via glm/glm-4.7 (acceptable backup)
+    5% via minimax (rare fallback)
+```
+
+**Tối ưu**: Nếu fallback quá nhiều, tăng quota chính hoặc sắp xếp lại model.
+
+---
+
+## Cấu hình Nâng cao
+
+### Đặt Giới hạn Ngân sách cho mỗi Combo
+
+```
+Dashboard → Combos → Edit → Budget:
+  Daily limit: $5
+  Monthly limit: $50
+```
+
+Khi đạt giới hạn, 9Router bỏ qua model trả phí và chỉ dùng free tier.
+
+### Bật/Tắt Model trong Combo
+
+```
+Dashboard → Combos → Edit → Models:
+  ✅ cc/claude-opus-4-5 (enabled)
+  ❌ glm/glm-4.7 (temporarily disabled)
+  ✅ if/kimi-k2-thinking (enabled)
+```
+
+**Use case**: Tạm tắt model đắt mà không cần xóa combo.
+
+### Clone Combo có sẵn
+
+```
+Dashboard → Combos → Clone "premium-coding"
+→ Creates copy with "-copy" suffix
+→ Modify and save as new combo
+```
+
+**Use case**: Tạo biến thể cho các kịch bản khác nhau.
+
+---
+
+## Troubleshooting
+
+**Issue: Combo không xuất hiện trong danh sách model**
+
+**Giải pháp:**
+1. Refresh dashboard
+2. Kiểm tra combo đã được lưu (dấu tick xanh)
+3. Khởi động lại CLI tool để refresh danh sách model
+
+**Issue: Combo luôn dùng model cuối cùng (free tier)**
+
+**Giải pháp:**
+1. Kiểm tra quota cho các model chính (Dashboard → Quota)
+2. Xác minh API keys hợp lệ (Dashboard → Providers)
+3. Kiểm tra giới hạn ngân sách không vượt quá
+
+**Issue: Combo tốn hơn dự kiến**
+
+**Giải pháp:**
+1. Dashboard → Analytics → Xem usage combo
+2. Kiểm tra model chính có bị hết quota không
+3. Sắp xếp lại model (đặt rẻ hơn lên trước)
+4. Đặt giới hạn ngân sách
+
+---
+
+## Liên quan
+
+- [Smart Routing](./smart-routing.md) - Cách auto fallback hoạt động
+- [Quota Tracking](./quota-tracking.md) - Theo dõi sử dụng và chi phí
diff --git a/gitbook/content/vi/features/quota-tracking.md b/gitbook/content/vi/features/quota-tracking.md
new file mode 100644
index 0000000..7e728d4
--- /dev/null
+++ b/gitbook/content/vi/features/quota-tracking.md
@@ -0,0 +1,687 @@
+# Quota Tracking & Giám sát Usage
+
+Theo dõi tiêu thụ token thời gian thực, giám sát giới hạn quota, ước tính chi phí và nhận cảnh báo trước khi hết. Không bao giờ lãng phí quota subscription hoặc vượt giới hạn ngân sách.
+
+---
+
+## Tổng quan
+
+9Router cung cấp quota tracking toàn diện cho mọi provider:
+
+- **Tiêu thụ token thời gian thực** - Xem tokens dùng mỗi request
+- **Giới hạn quota & còn lại** - Theo dõi usage so với giới hạn
+- **Đếm ngược Reset** - Biết khi nào quota refresh
+- **Ước tính chi phí** - Tính chi tiêu cho tier trả phí
+- **Báo cáo hàng tháng** - Phân tích pattern sử dụng
+- **Cảnh báo & thông báo** - Nhận cảnh báo trước giới hạn
+
+---
+
+## Tổng quan Dashboard
+
+### Tóm tắt Quota
+
+```
+Dashboard → Home → Quota Overview
+
+┌─────────────────────────────────────────────┐
+│ Claude Code (cc/)                           │
+│ ████████████░░░░░░░░ 2.5h / 5h (50%)       │
+│ Resets in: 2h 30m                           │
+│ Cost: $0 (subscription)                     │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ Gemini CLI (gc/)                            │
+│ ████████░░░░░░░░░░░░ 450 / 1000 (45%)      │
+│ Daily reset in: 18h 30m                     │
+│ Monthly: 45K / 180K (25%)                   │
+│ Cost: $0 (free tier)                        │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ GLM-4.7 (glm/)                              │
+│ ██████████████░░░░░░ 7M / 10M tokens (70%)  │
+│ Resets: Daily 10:00 AM (in 5h 35m)         │
+│ Cost today: $4.20                           │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ MiniMax M2.1 (minimax/)                     │
+│ ████████████████░░░░ 4M / 5M tokens (80%)   │
+│ Rolling 5h window                           │
+│ Cost (5h): $0.80                            │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ iFlow (if/)                                 │
+│ ████████████████████ Unlimited              │
+│ Cost: $0 (free forever)                     │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Tiêu thụ Token Thời gian thực
+
+### Theo dõi từng Request
+
+Mỗi request hiển thị usage token chi tiết:
+
+```
+Dashboard → Activity → Recent Requests
+
+Request #1234
+Model: cc/claude-opus-4-5-20251101
+Timestamp: 2026-02-04 04:15:32
+
+Tokens:
+  Input: 1,250 tokens
+  Output: 850 tokens
+  Total: 2,100 tokens
+
+Cost: $0 (subscription quota)
+Duration: 3.2s
+Status: ✅ Success
+```
+
+### Live Usage Monitor
+
+```
+Dashboard → Live Monitor
+
+Current request:
+  Model: glm/glm-4.7
+  Tokens streamed: 450 / ~800 estimated
+  Cost so far: $0.0009
+  Duration: 1.8s
+```
+
+### Phân tích Token theo Model
+
+```
+Dashboard → Analytics → Token Usage
+
+Today (Feb 4, 2026):
+  cc/claude-opus-4-5: 15M tokens ($0, subscription)
+  glm/glm-4.7: 8M tokens ($4.80)
+  if/kimi-k2-thinking: 3M tokens ($0, free)
+  
+Total: 26M tokens
+Cost: $4.80
+```
+
+---
+
+## Giới hạn Quota & Thời gian Reset
+
+### Subscription Providers
+
+**Claude Code (Pro/Max)**
+```
+Quota type: Time-based (5-hour rolling)
+Limit: 5 hours of usage
+Reset: Rolling 5-hour window + Weekly refresh
+Tracking: Usage time per model
+
+Dashboard shows:
+  Opus: 2.5h / 5h used
+  Sonnet: 1.2h / 5h used
+  Haiku: 0.8h / 5h used
+  
+Weekly reset: Every Monday 00:00 UTC
+```
+
+**OpenAI Codex (Plus/Pro)**
+```
+Quota type: Time-based (5-hour rolling)
+Limit: 5 hours (Plus) / 10 hours (Pro)
+Reset: Rolling 5-hour window + Weekly refresh
+
+Dashboard shows:
+  GPT-5.2 Codex: 3.5h / 5h used
+  Resets in: 1h 30m
+```
+
+**Gemini CLI (MIỄN PHÍ)**
+```
+Quota type: Request count + Monthly tokens
+Daily limit: 1,000 requests
+Monthly limit: 180,000 completions
+Reset: Daily 00:00 UTC + Monthly 1st
+
+Dashboard shows:
+  Today: 450 / 1,000 requests (45%)
+  This month: 45K / 180K completions (25%)
+  Daily reset in: 18h 30m
+  Monthly reset in: 26 days
+```
+
+**GitHub Copilot**
+```
+Quota type: Monthly usage
+Limit: Varies by plan
+Reset: 1st of each month
+
+Dashboard shows:
+  Usage: 60% of monthly quota
+  Resets: March 1, 2026 (in 25 days)
+```
+
+### Cheap Providers
+
+**GLM-4.7**
+```
+Quota type: Daily token limit
+Limit: 10M tokens/day (Coding Plan)
+Reset: Daily 10:00 AM Beijing Time (UTC+8)
+
+Dashboard shows:
+  Used: 7M / 10M tokens (70%)
+  Remaining: 3M tokens
+  Resets in: 5h 35m
+  Cost today: $4.20
+```
+
+**MiniMax M2.1**
+```
+Quota type: Rolling 5-hour window
+Limit: 5M tokens per 5 hours
+Reset: Continuous rolling window
+
+Dashboard shows:
+  Used (5h): 4M / 5M tokens (80%)
+  Oldest usage expires in: 45m
+  Cost (5h): $0.80
+```
+
+**Kimi K2**
+```
+Quota type: Monthly subscription
+Limit: 10M tokens/month ($9 flat)
+Reset: Monthly on subscription date
+
+Dashboard shows:
+  Used: 6M / 10M tokens (60%)
+  Resets: Feb 15, 2026 (in 11 days)
+  Cost: $9/month (prepaid)
+```
+
+### Free Providers
+
+**iFlow / Qwen / Kiro**
+```
+Quota type: Unlimited (rate-limited)
+Limit: No hard limit
+Reset: N/A
+
+Dashboard shows:
+  Used today: 5M tokens
+  Cost: $0 (free forever)
+  Status: ✅ Available
+```
+
+---
+
+## Ước tính Chi phí
+
+### Theo dõi Chi phí Thời gian thực
+
+```
+Dashboard → Costs → Today
+
+Subscription providers: $0
+  Claude Code: 15M tokens ($0, included)
+  Gemini CLI: 3M tokens ($0, free tier)
+
+Paid providers: $4.80
+  GLM-4.7: 8M tokens ($4.80)
+    Input: 6M × $0.60/1M = $3.60
+    Output: 2M × $2.20/1M = $4.40
+    Total: $4.80
+
+Free providers: $0
+  iFlow: 3M tokens ($0)
+
+Total today: $4.80
+```
+
+### Báo cáo Chi tiêu Hàng tháng
+
+```
+Dashboard → Costs → This Month (February 2026)
+
+Week 1 (Feb 1-7):
+  Subscription: $0 (80M tokens)
+  Paid: $15.20 (25M tokens)
+  Free: $0 (10M tokens)
+  Total: $15.20
+
+Week 2 (Feb 8-14):
+  Subscription: $0 (75M tokens)
+  Paid: $12.80 (20M tokens)
+  Free: $0 (8M tokens)
+  Total: $12.80
+
+Month to date: $28.00
+Projected (30 days): ~$120
+
+Breakdown by provider:
+  GLM-4.7: $22.00 (78%)
+  MiniMax M2.1: $6.00 (22%)
+  
+Average cost per 1M tokens: $0.62
+Savings vs ChatGPT API: 97% ($4,000 → $120)
+```
+
+### Dự kiến Chi phí
+
+```
+Dashboard → Costs → Projections
+
+Based on last 7 days usage:
+  Daily average: 50M tokens
+  Daily cost: $4.50
+
+Monthly projection:
+  Tokens: 1,500M (1.5B)
+  Cost: $135
+  
+Breakdown:
+  Subscription: 900M tokens ($0)
+  GLM-4.7: 450M tokens ($90)
+  MiniMax: 120M tokens ($24)
+  Free: 30M tokens ($0)
+
+Budget status:
+  Daily limit: $5 → 90% used today
+  Monthly limit: $150 → 90% projected
+  ⚠️ Warning: May exceed monthly budget
+```
+
+---
+
+## Dashboard Usage
+
+### Thống kê Tổng quan
+
+```
+Dashboard → Analytics → Overview
+
+Today (Feb 4, 2026):
+  Requests: 1,234
+  Tokens: 26M
+  Cost: $4.80
+  Avg response time: 2.1s
+
+This week:
+  Requests: 8,456
+  Tokens: 180M
+  Cost: $28.00
+  Success rate: 99.2%
+
+This month:
+  Requests: 15,234
+  Tokens: 320M
+  Cost: $52.00
+  Top model: cc/claude-opus-4-5 (45%)
+```
+
+### Usage theo Model
+
+```
+Dashboard → Analytics → Models
+
+Top models (this month):
+1. cc/claude-opus-4-5: 145M tokens (45%)
+2. glm/glm-4.7: 95M tokens (30%)
+3. if/kimi-k2-thinking: 50M tokens (16%)
+4. minimax/MiniMax-M2.1: 20M tokens (6%)
+5. gc/gemini-3-flash: 10M tokens (3%)
+
+Cost breakdown:
+  cc/claude-opus: $0 (subscription)
+  glm/glm-4.7: $45.00
+  if/kimi-k2-thinking: $0 (free)
+  minimax/MiniMax-M2.1: $7.00
+  gc/gemini-3-flash: $0 (free)
+```
+
+### Usage theo Thời gian
+
+```
+Dashboard → Analytics → Timeline
+
+Hourly usage (today):
+00:00 - 01:00: 0.5M tokens
+01:00 - 02:00: 0.2M tokens
+...
+08:00 - 09:00: 3.2M tokens (peak)
+09:00 - 10:00: 2.8M tokens
+...
+23:00 - 00:00: 0.8M tokens
+
+Peak hours: 08:00 - 12:00 (morning coding)
+Low hours: 00:00 - 06:00 (night)
+```
+
+### Usage theo Combo
+
+```
+Dashboard → Analytics → Combos
+
+premium-coding:
+  Requests: 456
+  Tokens: 12M
+  Cost: $2.40
+  
+  Breakdown:
+    cc/claude-opus: 8M tokens (67%, $0)
+    glm/glm-4.7: 3M tokens (25%, $1.80)
+    minimax/MiniMax-M2.1: 1M tokens (8%, $0.20)
+
+budget-combo:
+  Requests: 234
+  Tokens: 6M
+  Cost: $1.20
+  
+  Breakdown:
+    glm/glm-4.7: 4M tokens (67%, $2.40)
+    if/kimi-k2-thinking: 2M tokens (33%, $0)
+```
+
+---
+
+## Cảnh báo & Thông báo
+
+### Cảnh báo Quota
+
+```
+Dashboard → Settings → Alerts
+
+Quota warnings:
+  ✅ Alert at 80% quota used
+  ✅ Alert at 90% quota used
+  ✅ Alert when quota exhausted
+  ✅ Notify when quota resets
+
+Delivery:
+  ✅ Dashboard notification
+  ✅ Email (optional)
+  ✅ Webhook (optional)
+```
+
+**Ví dụ thông báo:**
+```
+⚠️ Claude Code quota 80% used
+   2.5h remaining (resets in 1h 30m)
+   
+⚠️ GLM-4.7 quota 90% used
+   1M tokens remaining (resets in 5h)
+   
+✅ Gemini CLI quota reset
+   1,000 requests available (daily limit)
+```
+
+### Cảnh báo Ngân sách
+
+```
+Dashboard → Settings → Budget Alerts
+
+Daily budget: $5
+  ✅ Alert at 80% ($4)
+  ✅ Alert at 100% ($5)
+  ✅ Auto-switch to free tier when exceeded
+
+Monthly budget: $150
+  ✅ Alert at 50% ($75)
+  ✅ Alert at 80% ($120)
+  ✅ Alert at 100% ($150)
+```
+
+**Ví dụ thông báo:**
+```
+⚠️ Daily budget 80% used
+   $4.00 / $5.00 spent today
+   
+⚠️ Monthly budget 50% reached
+   $75 / $150 spent this month
+   Projected: $135 (within budget)
+   
+🚨 Daily budget exceeded
+   $5.20 / $5.00 spent today
+   Auto-switched to free tier
+```
+
+### Phát hiện Bất thường Chi phí
+
+```
+Dashboard → Settings → Anomaly Detection
+
+✅ Detect unusual spending patterns
+✅ Alert on cost spikes (>2× daily average)
+✅ Warn on quota exhaustion patterns
+
+Example alert:
+⚠️ Cost spike detected
+   Today: $12.50 (2.5× daily average)
+   Reason: High GLM-4.7 usage (20M tokens)
+   Suggestion: Check if primary models quota-exhausted
+```
+
+---
+
+## Best Practices
+
+### 1. Theo dõi Quota Hàng ngày
+
+```
+Daily routine:
+1. Check dashboard quota overview (30 seconds)
+2. Review reset times
+3. Plan usage around quota availability
+```
+
+**Ví dụ:**
+```
+Morning check:
+  ✅ Claude Code: 5h available (fresh reset)
+  ✅ Gemini CLI: 1K requests available
+  ⚠️ GLM-4.7: 2M tokens left (resets 10AM)
+  
+Action: Use Claude Code for morning work
+```
+
+### 2. Đặt Giới hạn Ngân sách
+
+```
+Dashboard → Settings → Budget:
+  Daily: $5 (prevents overspending)
+  Monthly: $150 (aligns with budget)
+```
+
+**Kết quả**: Auto-switch sang free tier khi đạt giới hạn.
+
+### 3. Tối ưu Combo Usage
+
+```
+Dashboard → Analytics → Combos:
+  Review which models are used most
+  Adjust combo order to minimize costs
+```
+
+**Ví dụ:**
+```
+Current: cc/claude-opus → glm/glm-4.7
+  80% via Claude (good)
+  20% via GLM ($12/month)
+
+Optimized: gc/gemini-3-flash → cc/claude-opus → glm/glm-4.7
+  50% via Gemini (free)
+  40% via Claude (subscription)
+  10% via GLM ($6/month)
+  
+Savings: $6/month
+```
+
+### 4. Theo dõi Thời gian Reset
+
+```
+Dashboard → Quota → Reset Schedule:
+  Claude Code: 5h rolling + Weekly Monday
+  Gemini CLI: Daily 00:00 UTC + Monthly 1st
+  GLM-4.7: Daily 10:00 AM Beijing Time
+  MiniMax: Rolling 5h window
+```
+
+**Chiến lược**: Dùng provider khi quota mới reset.
+
+### 5. Xem Báo cáo Hàng tháng
+
+```
+Dashboard → Analytics → Monthly Report:
+  Total tokens: 1.5B
+  Total cost: $120
+  Savings: 97% vs ChatGPT API
+  
+Insights:
+  - 60% usage via subscriptions ($0)
+  - 30% via GLM ($90)
+  - 10% via free tier ($0)
+  
+Optimization:
+  - Increase Gemini CLI usage (free)
+  - Reduce GLM usage (expensive)
+```
+
+---
+
+## Truy cập API
+
+### Lấy trạng thái Quota
+
+```bash
+GET http://localhost:20128/api/quota
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "providers": [
+    {
+      "id": "cc",
+      "name": "Claude Code",
+      "quota": {
+        "used": 2.5,
+        "limit": 5,
+        "unit": "hours",
+        "percentage": 50
+      },
+      "reset": {
+        "type": "rolling",
+        "window": "5h",
+        "nextReset": "2026-02-04T06:45:00Z"
+      },
+      "cost": {
+        "today": 0,
+        "month": 0,
+        "currency": "USD"
+      }
+    },
+    {
+      "id": "glm",
+      "name": "GLM-4.7",
+      "quota": {
+        "used": 7000000,
+        "limit": 10000000,
+        "unit": "tokens",
+        "percentage": 70
+      },
+      "reset": {
+        "type": "daily",
+        "time": "10:00 AM UTC+8",
+        "nextReset": "2026-02-04T10:00:00+08:00"
+      },
+      "cost": {
+        "today": 4.20,
+        "month": 52.00,
+        "currency": "USD"
+      }
+    }
+  ]
+}
+```
+
+### Lấy Usage Stats
+
+```bash
+GET http://localhost:20128/api/usage?period=today
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "period": "today",
+  "date": "2026-02-04",
+  "summary": {
+    "requests": 1234,
+    "tokens": 26000000,
+    "cost": 4.80
+  },
+  "byModel": [
+    {
+      "model": "cc/claude-opus-4-5",
+      "requests": 456,
+      "tokens": 15000000,
+      "cost": 0
+    },
+    {
+      "model": "glm/glm-4.7",
+      "requests": 234,
+      "tokens": 8000000,
+      "cost": 4.80
+    }
+  ]
+}
+```
+
+---
+
+## Troubleshooting
+
+**Issue: Quota hiển thị 0% nhưng request thất bại**
+
+**Giải pháp:**
+1. Kiểm tra kết nối provider (Dashboard → Providers)
+2. Xác minh API keys hợp lệ
+3. Kiểm tra provider có down không (trang status)
+4. Thử kết nối lại OAuth providers
+
+**Issue: Ước tính chi phí sai**
+
+**Giải pháp:**
+1. Dashboard → Settings → Pricing
+2. Xác minh giá mỗi provider khớp với mức hiện tại
+3. Cập nhật giá nếu provider thay đổi
+4. Liên hệ support nếu vẫn lệch
+
+**Issue: Thời gian reset không cập nhật**
+
+**Giải pháp:**
+1. Refresh dashboard (F5)
+2. Kiểm tra thời gian hệ thống đúng
+3. Xác minh cài đặt timezone
+4. Khởi động lại 9Router nếu vẫn lỗi
+
+**Issue: Không nhận được cảnh báo**
+
+**Giải pháp:**
+1. Dashboard → Settings → Alerts
+2. Xác minh địa chỉ email đúng
+3. Kiểm tra folder spam
+4. Test notification (nút Send Test)
+
+---
+
+## Liên quan
+
+- [Smart Routing](./smart-routing.md) - Auto fallback dựa trên quota
+- [Combos](./combos.md) - Tạo chuỗi fallback tùy chỉnh
diff --git a/gitbook/content/vi/features/smart-routing.md b/gitbook/content/vi/features/smart-routing.md
new file mode 100644
index 0000000..277a74d
--- /dev/null
+++ b/gitbook/content/vi/features/smart-routing.md
@@ -0,0 +1,407 @@
+# Smart Routing & Auto Fallback
+
+9Router tự động định tuyến request qua provider tốt nhất hiện có bằng hệ thống fallback 3 tầng. Không bao giờ ngừng code vì giới hạn quota hay rate limiting.
+
+---
+
+## Cách hoạt động
+
+9Router dùng định tuyến thông minh để tối đa hóa subscription hiện có, giảm chi phí và đảm bảo khả dụng 24/7:
+
+```
+Request → 9Router → Check Tier 1 (Subscription)
+                     ↓ quota exhausted
+                     Check Tier 2 (Cheap)
+                     ↓ budget limit
+                     Check Tier 3 (Free)
+                     ↓
+                     Response
+```
+
+### Hệ thống Fallback 3 tầng
+
+**Tier 1: SUBSCRIPTION (Chính)**
+- Claude Code (Pro/Max)
+- OpenAI Codex (Plus/Pro)
+- Gemini CLI (MIỄN PHÍ 180K/tháng)
+- GitHub Copilot
+- Antigravity (Google)
+
+**Mục tiêu**: Tối đa giá trị từ subscription đã trả tiền.
+
+**Tier 2: CHEAP (Backup)**
+- GLM-4.7 ($0.60/1M input)
+- MiniMax M2.1 ($0.20/1M input)
+- Kimi K2 ($9/tháng cố định)
+
+**Mục tiêu**: Backup siêu rẻ khi hết quota subscription (~90% rẻ hơn ChatGPT API).
+
+**Tier 3: FREE (Khẩn cấp)**
+- iFlow (8 models)
+- Qwen (3 models)
+- Kiro (Claude MIỄN PHÍ)
+
+**Mục tiêu**: Fallback chi phí 0 để code không giới hạn.
+
+---
+
+## Chuyển đổi Tự động
+
+9Router giám sát quota thời gian thực và chuyển provider tự động:
+
+### Kịch bản 1: Hết Quota Subscription
+
+```
+User request → cc/claude-opus-4-5
+               ↓ quota exhausted (5-hour limit reached)
+               Auto switch → glm/glm-4.7
+               ↓ daily quota exhausted
+               Auto switch → minimax/MiniMax-M2.1
+               ↓ 5-hour quota exhausted
+               Auto switch → if/kimi-k2-thinking (FREE)
+               ↓
+               Response delivered ✅
+```
+
+**Kết quả**: Zero downtime, trải nghiệm liền mạch.
+
+### Kịch bản 2: Rate Limiting
+
+```
+User request → cx/gpt-5.2-codex
+               ↓ rate limited (too many requests)
+               Auto switch → glm/glm-4.7
+               ↓
+               Response delivered ✅
+```
+
+### Kịch bản 3: Provider không khả dụng
+
+```
+User request → cc/claude-opus-4-5
+               ↓ provider error (503)
+               Auto switch → next available model
+               ↓
+               Response delivered ✅
+```
+
+---
+
+## Logic chọn Model
+
+9Router chọn model tốt nhất dựa trên:
+
+1. **Khả dụng quota** - Kiểm tra provider còn quota không
+2. **Tier chi phí** - Ưu tiên subscription → cheap → free
+3. **Thời gian reset** - Cân nhắc khi quota reset
+4. **Sức khỏe provider** - Bỏ qua provider có lỗi
+
+### Ví dụ Thứ tự Ưu tiên
+
+Cho request đến `cc/claude-opus-4-5`:
+
+```
+1. Check Claude Code quota
+   ✅ Available → Use cc/claude-opus-4-5
+   ❌ Exhausted → Continue to step 2
+
+2. Check fallback tier (if configured)
+   ✅ GLM quota available → Use glm/glm-4.7
+   ❌ Exhausted → Continue to step 3
+
+3. Check free tier
+   ✅ iFlow available → Use if/kimi-k2-thinking
+   ❌ All exhausted → Return quota error
+```
+
+---
+
+## Tùy chọn Cấu hình
+
+### Cài đặt Dashboard
+
+**1. Bật/Tắt Auto Fallback**
+
+```
+Dashboard → Settings → Smart Routing
+→ Toggle "Auto Fallback" ON/OFF
+```
+
+- **ON** (mặc định): Chuyển tier tự động
+- **OFF**: Strict mode, trả lỗi nếu model chính không khả dụng
+
+**2. Đặt Giới hạn Ngân sách**
+
+```
+Dashboard → Settings → Budget Control
+→ Daily limit: $5
+→ Monthly limit: $50
+```
+
+Khi đạt ngân sách, 9Router tự động chuyển sang free tier.
+
+**3. Cấu hình Thứ tự Fallback**
+
+```
+Dashboard → Settings → Fallback Priority
+→ Drag to reorder providers within each tier
+```
+
+Ví dụ thứ tự tùy chỉnh:
+```
+Tier 1: Gemini CLI → Claude Code → Codex
+Tier 2: MiniMax → GLM → Kimi
+Tier 3: iFlow → Kiro → Qwen
+```
+
+**4. Thông báo Reset Quota**
+
+```
+Dashboard → Settings → Notifications
+→ Email when quota resets
+→ Alert when 80% quota used
+```
+
+---
+
+## Ví dụ
+
+### Ví dụ 1: Auto Fallback Cơ bản
+
+**Setup:**
+```
+Model: cc/claude-opus-4-5-20251101
+Fallback: Auto (default 3-tier)
+```
+
+**Hoạt động:**
+```
+Morning (fresh quota):
+  Request → cc/claude-opus-4-5 ✅
+
+Afternoon (quota exhausted):
+  Request → glm/glm-4.7 ✅ (auto switched)
+
+Evening (GLM quota out):
+  Request → minimax/MiniMax-M2.1 ✅ (auto switched)
+
+Late night (all paid quota out):
+  Request → if/kimi-k2-thinking ✅ (free tier)
+```
+
+**Chi phí**: ~$5-10/tháng extra (chủ yếu được bao bởi subscription).
+
+### Ví dụ 2: Định tuyến theo Ngân sách
+
+**Setup:**
+```
+Dashboard → Settings:
+  Daily budget: $2
+  Monthly budget: $20
+  Fallback: Enabled
+```
+
+**Hoạt động:**
+```
+Day 1-15 (within budget):
+  Requests → glm/glm-4.7 (cheap tier)
+  Cost: $1.50/day
+
+Day 16 (budget reached):
+  Requests → if/kimi-k2-thinking (free tier)
+  Cost: $0
+
+Next month (budget resets):
+  Requests → glm/glm-4.7 again
+```
+
+**Kết quả**: Không bao giờ vượt $20/tháng, luôn khả dụng.
+
+### Ví dụ 3: Chế độ Chỉ Subscription
+
+**Setup:**
+```
+Dashboard → Settings:
+  Auto Fallback: OFF
+  Strict mode: ON
+```
+
+**Hoạt động:**
+```
+Request → cc/claude-opus-4-5
+  ✅ Quota available → Success
+  ❌ Quota exhausted → Return error (no fallback)
+```
+
+**Use case**: Khi chỉ muốn dùng subscription trả phí, không phí thêm.
+
+### Ví dụ 4: Chế độ Chỉ Free
+
+**Setup:**
+```
+Model: if/kimi-k2-thinking
+Fallback: qw/qwen3-coder-plus → kr/claude-sonnet-4.5
+```
+
+**Hoạt động:**
+```
+All requests → Free tier only
+Cost: $0 forever
+```
+
+**Use case**: Dự án cá nhân, học tập, thử nghiệm.
+
+---
+
+## Best Practices
+
+### 1. Tối đa Giá trị Subscription
+
+```
+Strategy:
+- Set subscription models as Tier 1
+- Monitor quota usage in dashboard
+- Use cheap tier only when subscription exhausted
+```
+
+**Ví dụ combo:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 2. Tối ưu Chi phí
+
+```
+Strategy:
+- Use Gemini CLI free tier first (180K/month)
+- Fallback to GLM/MiniMax (ultra-cheap)
+- Emergency: iFlow (free)
+```
+
+**Ví dụ combo:**
+```
+gc/gemini-3-flash-preview → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 3. Tối ưu Chất lượng
+
+```
+Strategy:
+- Use best models (Claude Opus, GPT-5.2)
+- Fallback to good cheap models (GLM-4.7)
+- Last resort: Free tier
+```
+
+**Ví dụ combo:**
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → glm/glm-4.7
+```
+
+### 4. Khả dụng 24/7
+
+```
+Strategy:
+- Always include free tier in fallback
+- Monitor quota reset times
+- Distribute usage across providers
+```
+
+**Ví dụ combo:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+**Kết quả**: Không bao giờ hết quota, code mọi lúc.
+
+---
+
+## Chiến lược Reset Quota
+
+Lên kế hoạch usage quanh thời gian reset quota:
+
+| Provider | Quota Reset | Chiến lược |
+|----------|-------------|----------|
+| **Claude Code** | 5 giờ + hàng tuần | Dùng buổi sáng, quota mới |
+| **Codex** | 5 giờ + hàng tuần | Dùng sau khi hết quota Claude |
+| **Gemini CLI** | Hàng ngày (1K) + Hàng tháng (180K) | Dùng cả ngày |
+| **GLM-4.7** | Hàng ngày 10:00 AM | Dùng buổi tối, reset sáng hôm sau |
+| **MiniMax M2.1** | 5 giờ rolling | Dùng mọi lúc, theo rolling window |
+| **iFlow/Qwen/Kiro** | Không giới hạn | Backup khẩn cấp |
+
+**Ví dụ lịch hàng ngày:**
+```
+08:00 - 13:00: Claude Code (fresh 5h quota)
+13:00 - 18:00: Gemini CLI (1K/day quota)
+18:00 - 22:00: GLM-4.7 (cheap, resets 10AM)
+22:00 - 08:00: MiniMax or iFlow (5h rolling or free)
+```
+
+---
+
+## Giám sát & Cảnh báo
+
+### Dashboard Quota Tracker
+
+```
+Dashboard → Quota Overview:
+  Claude Code: 2.5h / 5h remaining (50%)
+  Gemini CLI: 450 / 1000 requests today
+  GLM-4.7: 5M / 10M tokens (resets in 8h)
+  MiniMax: 3M / 5M tokens (rolling 5h)
+```
+
+### Thông báo Thời gian thực
+
+```
+Dashboard → Notifications:
+  ⚠️ Claude Code quota 80% used (1h remaining)
+  ✅ GLM-4.7 quota reset (10M tokens available)
+  💰 Daily budget 50% used ($2.50 / $5)
+```
+
+### Usage Analytics
+
+```
+Dashboard → Analytics:
+  Today: 50M tokens
+    - 30M via Claude Code (subscription)
+    - 15M via GLM-4.7 ($9)
+    - 5M via iFlow (free)
+  
+  Cost: $9 (vs $1000 on ChatGPT API)
+  Savings: 99%
+```
+
+---
+
+## Troubleshooting
+
+**Issue: "All providers quota exhausted"**
+
+**Giải pháp:**
+1. Kiểm tra quota tracker trong dashboard
+2. Đợi quota reset (xem countdown)
+3. Thêm free tier vào fallback chain
+4. Hoặc tăng giới hạn ngân sách
+
+**Issue: "Too many fallback switches"**
+
+**Giải pháp:**
+1. Kiểm tra provider chính có down không
+2. Tăng giới hạn quota (upgrade subscription)
+3. Dùng model chính rẻ hơn (GLM thay vì Claude)
+
+**Issue: "Unexpected costs"**
+
+**Giải pháp:**
+1. Dashboard → Analytics → Xem usage
+2. Đặt giới hạn ngân sách hàng ngày/tháng
+3. Chuyển sang free tier cho task không quan trọng
+4. Dùng combo với free fallback
+
+---
+
+## Liên quan
+
+- [Combos](./combos.md) - Tạo chuỗi fallback tùy chỉnh
+- [Quota Tracking](./quota-tracking.md) - Theo dõi usage và chi phí
diff --git a/gitbook/content/vi/getting-started/installation.md b/gitbook/content/vi/getting-started/installation.md
new file mode 100644
index 0000000..8e38773
--- /dev/null
+++ b/gitbook/content/vi/getting-started/installation.md
@@ -0,0 +1,478 @@
+# Cài đặt
+
+Hướng dẫn cài đặt chi tiết cho 9Router với mẹo troubleshooting.
+
+---
+
+## Yêu cầu
+
+### Yêu cầu hệ thống
+
+- **Node.js**: Phiên bản 20.0.0 trở lên
+- **npm**: Phiên bản 10.0.0 trở lên (đi kèm Node.js)
+- **OS**: macOS, Linux, Windows (khuyên dùng WSL)
+- **Dung lượng**: ~200MB để cài đặt
+
+### Kiểm tra Phiên bản
+
+```bash
+node --version
+# Should show v20.x.x or higher
+
+npm --version
+# Should show 10.x.x or higher
+```
+
+**Chưa có Node.js?** Cài đặt từ [nodejs.org](https://nodejs.org/)
+
+---
+
+## Phương thức Cài đặt
+
+### Cách 1: Cài Global (Khuyên dùng)
+
+Cài 9Router toàn cục để dùng ở bất kỳ đâu:
+
+```bash
+npm install -g 9router
+```
+
+**Khởi động 9Router:**
+
+```bash
+9router
+```
+
+**Lợi ích:**
+- ✅ Chạy từ mọi thư mục
+- ✅ Lệnh đơn giản: `9router`
+- ✅ Auto-update với `npm update -g 9router`
+
+### Cách 2: Cài Local
+
+Cài trong project cụ thể:
+
+```bash
+mkdir my-9router
+cd my-9router
+npm install 9router
+```
+
+**Khởi động 9Router:**
+
+```bash
+npx 9router
+```
+
+**Lợi ích:**
+- ✅ Cô lập mỗi project
+- ✅ Version control mỗi project
+- ✅ Không làm bẩn global namespace
+
+### Cách 3: Từ Source (Development)
+
+Clone và build từ GitHub:
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install
+npm run build
+npm start
+```
+
+**Lợi ích:**
+- ✅ Tính năng phát triển mới nhất
+- ✅ Đóng góp cho dự án
+- ✅ Tùy chỉnh
+
+---
+
+## Lần chạy Đầu tiên
+
+### Khởi động Server
+
+```bash
+9router
+```
+
+**Điều gì xảy ra:**
+1. Server khởi động tại `http://localhost:20128`
+2. Dashboard tự động mở trong browser
+3. Data directory được tạo tại `~/.9router`
+4. API key được tạo tự động
+
+### Đăng nhập Dashboard
+
+**Credentials mặc định:**
+- Mật khẩu: `123456`
+
+**⚠️ Đổi mật khẩu ngay:**
+1. Đăng nhập dashboard
+2. Settings → Change Password
+3. Dùng mật khẩu mạnh
+
+### Lấy API Key
+
+```
+Dashboard → Settings → API Keys
+→ Copy your API key
+→ Use in CLI tools
+```
+
+**Ví dụ format API key:**
+```
+9r_1234567890abcdef1234567890abcdef
+```
+
+---
+
+## Xác minh Cài đặt
+
+### Kiểm tra trạng thái Server
+
+```bash
+curl http://localhost:20128/health
+```
+
+**Phản hồi dự kiến:**
+```json
+{
+  "status": "ok",
+  "version": "1.0.0"
+}
+```
+
+### Liệt kê Model khả dụng
+
+```bash
+curl http://localhost:20128/v1/models \
+  -H "Authorization: Bearer your-api-key"
+```
+
+**Phản hồi dự kiến:**
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "cc/claude-opus-4-5-20251101",
+      "object": "model",
+      "created": 1234567890,
+      "owned_by": "claude-code"
+    }
+  ]
+}
+```
+
+### Test Chat Completion
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "cc/claude-opus-4-5-20251101",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+---
+
+## Cấu hình
+
+### Biến môi trường
+
+Tạo file `.env` hoặc set biến môi trường:
+
+```bash
+# Security (REQUIRED in production)
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+
+# Storage
+export DATA_DIR="~/.9router"
+
+# Server
+export PORT="20128"
+export NODE_ENV="production"
+
+# Logging
+export ENABLE_REQUEST_LOGS="false"
+```
+
+### Data Directory
+
+**Vị trí mặc định:** `~/.9router`
+
+**Nội dung:**
+```
+~/.9router/
+  ├── db.json           # Database (providers, combos, usage)
+  ├── api-keys.json     # API keys
+  └── logs/             # Request logs (if enabled)
+```
+
+**Đổi vị trí:**
+
+```bash
+export DATA_DIR="/custom/path"
+9router
+```
+
+### Cấu hình Port
+
+**Port mặc định:** `20128`
+
+**Đổi port:**
+
+```bash
+export PORT="3000"
+9router
+```
+
+**Hoặc dùng command line:**
+
+```bash
+9router --port 3000
+```
+
+---
+
+## Troubleshooting
+
+### Port đã được dùng
+
+**Lỗi:**
+```
+Error: listen EADDRINUSE: address already in use :::20128
+```
+
+**Giải pháp 1: Kill process hiện có**
+
+```bash
+# Find process using port 20128
+lsof -i :20128
+
+# Kill process
+kill -9 <PID>
+```
+
+**Giải pháp 2: Dùng port khác**
+
+```bash
+9router --port 3000
+```
+
+### Permission Denied
+
+**Lỗi:**
+```
+Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
+```
+
+**Giải pháp: Dùng sudo (không khuyến nghị) hoặc fix npm permissions**
+
+```bash
+# Fix npm permissions (recommended)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# Then install again
+npm install -g 9router
+```
+
+### Node.js Phiên bản quá cũ
+
+**Lỗi:**
+```
+Error: The engine "node" is incompatible with this module
+```
+
+**Giải pháp: Cập nhật Node.js**
+
+```bash
+# Using nvm (recommended)
+nvm install 20
+nvm use 20
+
+# Or download from nodejs.org
+```
+
+### Dashboard không mở
+
+**Vấn đề:** Dashboard không tự mở
+
+**Giải pháp 1: Mở thủ công**
+
+```
+http://localhost:20128
+```
+
+**Giải pháp 2: Kiểm tra firewall**
+
+```bash
+# macOS: Allow Node.js in System Preferences → Security
+# Linux: Check iptables
+# Windows: Check Windows Firewall
+```
+
+### Không kết nối được Provider
+
+**Vấn đề:** OAuth login thất bại hoặc API key không hợp lệ
+
+**Giải pháp 1: Kiểm tra kết nối internet**
+
+```bash
+ping google.com
+```
+
+**Giải pháp 2: Kiểm tra trạng thái provider**
+
+- Claude Code: [status.anthropic.com](https://status.anthropic.com)
+- OpenAI: [status.openai.com](https://status.openai.com)
+- Gemini: [status.cloud.google.com](https://status.cloud.google.com)
+
+**Giải pháp 3: Tạo lại API key**
+
+```
+Dashboard → Provider → Disconnect → Reconnect
+```
+
+### Sử dụng RAM cao
+
+**Vấn đề:** 9Router dùng quá nhiều RAM
+
+**Giải pháp: Khởi động lại server**
+
+```bash
+# Stop
+pkill -f 9router
+
+# Start
+9router
+```
+
+**Hoặc dùng PM2 để auto-restart:**
+
+```bash
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+```
+
+---
+
+## Tùy chọn Deployment
+
+### Phát triển cục bộ
+
+```bash
+npm install -g 9router
+9router
+```
+
+**Use case:** Code cá nhân, testing
+
+### VPS/Cloud Server
+
+```bash
+# Install
+npm install -g 9router
+
+# Configure
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+# Start with PM2
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+pm2 startup
+```
+
+**Use case:** Team access, remote coding
+
+### Docker
+
+```bash
+docker pull 9router/9router:latest
+
+docker run -d \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret" \
+  -e INITIAL_PASSWORD="your-password" \
+  -v 9router-data:/root/.9router \
+  --name 9router \
+  9router/9router:latest
+```
+
+**Use case:** Containerized deployment, Kubernetes
+
+### Reverse Proxy (Nginx)
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        
+        # SSE support for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+**Use case:** HTTPS, custom domain, load balancing
+
+---
+
+## Gỡ cài đặt
+
+### Gỡ Global Installation
+
+```bash
+npm uninstall -g 9router
+```
+
+### Xóa Data Directory
+
+```bash
+rm -rf ~/.9router
+```
+
+### Xóa Cấu hình
+
+```bash
+# Remove environment variables from shell config
+nano ~/.bashrc  # or ~/.zshrc
+# Delete 9router-related exports
+```
+
+---
+
+## Bước tiếp theo
+
+- [Hướng dẫn Bắt đầu](../getting-started.md) - Kết nối provider và bắt đầu code
+- [Tính năng](../features/) - Khám phá quota tracking, combos, deployment
+- [Troubleshooting](../troubleshooting.md) - Sửa các vấn đề thường gặp
+
+---
+
+## Cần trợ giúp?
+
+- **Website**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
diff --git a/gitbook/content/vi/getting-started/quick-start.md b/gitbook/content/vi/getting-started/quick-start.md
new file mode 100644
index 0000000..ab16ff8
--- /dev/null
+++ b/gitbook/content/vi/getting-started/quick-start.md
@@ -0,0 +1,247 @@
+# Bắt đầu
+
+Khởi chạy 9Router trong 5 phút và bắt đầu định tuyến các request AI một cách thông minh.
+
+---
+
+## Bắt đầu nhanh
+
+### 1. Cài đặt
+
+```bash
+npm install -g 9router
+```
+
+**Yêu cầu:** Node.js 20+ ([Chi tiết cài đặt](getting-started/installation.md))
+
+### 2. Khởi chạy
+
+```bash
+9router
+```
+
+🎉 **Dashboard tự động mở** tại `http://localhost:20128`
+
+- Mật khẩu mặc định: `123456` (đổi trong dashboard)
+- API key được tạo tự động
+- Sẵn sàng kết nối provider
+
+### 3. Kết nối Provider
+
+Bạn có 3 cách để kết nối provider:
+
+#### Cách A: OAuth (Subscription Provider)
+
+**Tốt nhất cho:** Claude Code, Codex, Gemini CLI, GitHub Copilot
+
+```
+Dashboard → Providers → Connect [Provider]
+→ OAuth login → Auto token refresh
+→ Quota tracking enabled
+```
+
+**Ví dụ: Claude Code**
+1. Click "Connect Claude Code"
+2. Đăng nhập tài khoản Claude
+3. Cho phép 9Router
+4. ✅ Xong! Dùng model: `cc/claude-opus-4-5-20251101`
+
+#### Cách B: API Key (Cheap Provider)
+
+**Tốt nhất cho:** GLM, MiniMax, Kimi, OpenRouter
+
+```
+Dashboard → Providers → Add API Key
+→ Select provider
+→ Paste API key
+→ Save
+```
+
+**Ví dụ: GLM-4.7**
+1. Đăng ký tại [Zhipu AI](https://open.bigmodel.cn/)
+2. Lấy API key từ Coding Plan
+3. Dashboard → Add API Key → Provider: `glm` → Paste key
+4. ✅ Xong! Dùng model: `glm/glm-4.7`
+
+#### Cách C: Free Provider (Miễn phí)
+
+**Tốt nhất cho:** iFlow, Qwen, Kiro
+
+```
+Dashboard → Providers → Connect [Free Provider]
+→ Device code or OAuth
+→ Unlimited usage
+```
+
+**Ví dụ: iFlow**
+1. Click "Connect iFlow"
+2. Đăng nhập tài khoản iFlow
+3. Cho phép
+4. ✅ Xong! Dùng 8 model: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, v.v.
+
+---
+
+## 4. Dùng trong CLI Tools
+
+Trỏ công cụ code của bạn tới 9Router:
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Claude Desktop
+
+Sửa `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-5-20251101
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+---
+
+## 5. Tạo Smart Combos (Tùy chọn)
+
+Combo cho phép fallback tự động giữa các model:
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. if/kimi-k2-thinking (Free fallback)
+
+Use in CLI: premium-coding
+```
+
+**Cách hoạt động:**
+1. Thử Claude Opus trước (subscription của bạn)
+2. Nếu hết quota → GLM-4.7 (siêu rẻ)
+3. Nếu hết budget → iFlow (miễn phí)
+4. Zero downtime, chuyển đổi tự động!
+
+---
+
+## Model có sẵn
+
+### Subscription Models (Dùng đầu tiên)
+
+**Claude Code (`cc/`)** - Subscription Pro/Max:
+- `cc/claude-opus-4-5-20251101` - Claude 4.5 Opus
+- `cc/claude-sonnet-4-5-20250929` - Claude 4.5 Sonnet
+- `cc/claude-haiku-4-5-20251001` - Claude 4.5 Haiku
+
+**Codex (`cx/`)** - Subscription Plus/Pro:
+- `cx/gpt-5.2-codex` - GPT 5.2 Codex
+- `cx/gpt-5.1-codex-max` - GPT 5.1 Codex Max
+
+**Gemini CLI (`gc/`)** - MIỄN PHÍ 180K/tháng:
+- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
+- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
+
+**GitHub Copilot (`gh/`)** - Subscription:
+- `gh/gpt-5` - GPT-5
+- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
+
+### Cheap Models (Backup)
+
+**GLM (`glm/`)** - $0.6/$2.2 per 1M:
+- `glm/glm-4.7` - GLM 4.7 (reset 10AM hàng ngày)
+
+**MiniMax (`minimax/`)** - $0.20/$1.00 per 1M:
+- `minimax/MiniMax-M2.1` - MiniMax M2.1 (reset 5h)
+
+**Kimi (`kimi/`)** - $9/tháng (10M tokens):
+- `kimi/kimi-latest` - Kimi Latest
+
+### Model MIỄN PHÍ (Khẩn cấp)
+
+**iFlow (`if/`)** - 8 models MIỄN PHÍ:
+- `if/kimi-k2-thinking` - Kimi K2 Thinking
+- `if/qwen3-coder-plus` - Qwen3 Coder Plus
+- `if/glm-4.7` - GLM 4.7
+- `if/deepseek-r1` - DeepSeek R1
+
+**Qwen (`qw/`)** - 3 models MIỄN PHÍ:
+- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
+- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
+
+**Kiro (`kr/`)** - 2 models MIỄN PHÍ:
+- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
+- `kr/claude-haiku-4.5` - Claude Haiku 4.5
+
+---
+
+## Chiến lược Tối ưu Chi phí
+
+### Ngân sách hàng tháng: $10-20/tháng
+
+```
+1. Use Gemini CLI free tier (180K/month) for quick tasks
+2. Use Claude Code subscription quota fully (you already pay)
+3. Fallback to GLM ($0.6/1M) when quota out
+4. Emergency: MiniMax M2.1 ($0.20/1M) or iFlow (free)
+
+Real example (100M tokens/month):
+  60M via Gemini CLI: $0 (free tier)
+  30M via Claude Code: $0 (subscription you already have)
+  8M via GLM: $4.80
+  2M via MiniMax: $0.40
+  Total: $5.20/month + existing subscriptions
+```
+
+### Chiến lược Reset Quota
+
+```
+Daily routine:
+1. Morning: Fresh Claude Code quota (5h reset)
+2. Afternoon: Switch to Gemini CLI (1K/day)
+3. Evening: GLM daily quota (reset 10AM next day)
+4. Late night: MiniMax (5h rolling) or iFlow (free)
+
+→ Code 24/7 with minimal extra cost!
+```
+
+---
+
+## Bước tiếp theo
+
+- [Chi tiết cài đặt](getting-started/installation.md) - Yêu cầu, troubleshooting
+- [Tính năng](features/) - Khám phá quota tracking, combos, deployment
+- [FAQ](faq.md) - Câu hỏi thường gặp
+- [Troubleshooting](troubleshooting.md) - Sửa các vấn đề phổ biến
+
+---
+
+## Cần trợ giúp?
+
+- **Website**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
diff --git a/gitbook/content/vi/index.md b/gitbook/content/vi/index.md
new file mode 100644
index 0000000..7ef5f66
--- /dev/null
+++ b/gitbook/content/vi/index.md
@@ -0,0 +1,164 @@
+# Chào mừng đến với 9Router
+
+**Dùng Claude, Codex, Gemini MIỄN PHÍ • Lựa chọn siêu rẻ từ $0.20/1M tokens**
+
+9Router là bộ định tuyến mô hình AI giúp tối đa hóa giá trị subscription và giảm chi phí thông qua định tuyến thông minh và fallback tự động.
+
+---
+
+## 9Router là gì?
+
+9Router là một proxy thông minh nằm giữa các công cụ lập trình của bạn (Cursor, Cline, Claude Desktop) và các nhà cung cấp AI. Nó tự động định tuyến request đến model tốt nhất hiện có dựa trên quota, chi phí và tính khả dụng.
+
+**Đừng lãng phí tiền:**
+- ❌ Quota subscription hết hạn mỗi tháng mà không dùng đến
+- ❌ Rate limit chặn bạn đang lập trình
+- ❌ API đắt đỏ ($20-50/tháng cho mỗi provider)
+- ❌ Chuyển đổi provider thủ công
+
+**Bắt đầu tối đa hóa giá trị:**
+- ✅ **Tối đa Subscription** - Theo dõi và dùng từng chút quota của Claude Code, Codex, Gemini
+- ✅ **MIỄN PHÍ** - Truy cập model iFlow, Qwen, Kiro qua CLI
+- ✅ **Backup siêu rẻ** - GLM ($0.6/1M), MiniMax M2.1 ($0.20/1M)
+- ✅ **Smart Fallback** - Subscription → Cheap → Free, chuyển đổi tự động
+
+---
+
+## Tính năng chính
+
+### 🔄 Smart 3-Tier Fallback
+
+```
+Setup once, never stop coding:
+
+Tier 1 (SUBSCRIPTION): Claude Code → Codex → Gemini
+  ↓ quota exhausted
+Tier 2 (CHEAP): GLM-4.7 → MiniMax M2.1 → Kimi
+  ↓ budget limit
+Tier 3 (FREE): iFlow → Qwen → Kiro
+
+→ Automatic switching, zero downtime!
+```
+
+### 📊 Theo dõi Quota
+
+- Tiêu thụ token thời gian thực cho mỗi provider
+- Đếm ngược reset (5 giờ, hàng ngày, hàng tuần, hàng tháng)
+- Ước tính chi phí cho tier trả phí
+- Báo cáo chi tiêu hàng tháng
+
+### 🎯 Hỗ trợ CLI Toàn diện
+
+Hoạt động với mọi công cụ hỗ trợ custom OpenAI endpoint:
+
+✅ **Cursor** • **Cline** • **Claude Desktop** • **Codex** • **RooCode** • **Continue** • **Bất kỳ tool nào tương thích OpenAI**
+
+### 💰 Tối ưu Chi phí
+
+**Ví dụ thực tế (100M tokens/tháng):**
+```
+60M qua Gemini CLI: $0 (free tier)
+30M qua Claude Code: $0 (subscription đã có)
+8M qua GLM: $4.80
+2M qua MiniMax: $0.40
+Tổng: $5.20/tháng so với $2000 trên ChatGPT API!
+```
+
+---
+
+## Tại sao chọn 9Router?
+
+### Tối đa hóa Subscription
+
+Đã trả tiền cho Claude Code ($20-100/tháng) hoặc Codex ($20-200/tháng)? Nhận giá trị đầy đủ:
+
+- Theo dõi sử dụng quota thời gian thực
+- Tự động chuyển khi quota reset (5 giờ, hàng tuần)
+- Dùng hết mọi token trước khi hết hạn
+- Gemini CLI: 180K completions/tháng **MIỄN PHÍ**
+
+### Backup Siêu Rẻ
+
+Khi quota subscription hết, trả vài xu:
+
+| Provider | Giá per 1M tokens | Reset |
+|----------|-------------------|-------|
+| **GLM-4.7** | $0.60 input / $2.20 output | Hàng ngày 10:00 AM |
+| **MiniMax M2.1** | $0.20 input / $1.00 output | 5 giờ rolling |
+| **Kimi K2** | $9/tháng (10M tokens) | Hàng tháng |
+
+**~90% rẻ hơn ChatGPT API ($20/1M)!**
+
+### Fallback Miễn phí Mãi mãi
+
+Backup khẩn cấp khi mọi thứ khác đều bị giới hạn quota:
+
+- **iFlow**: 8 models (Kimi K2, Qwen3 Coder Plus, GLM 4.7, MiniMax M2)
+- **Qwen**: 3 models (Qwen3 Coder Plus/Flash, Vision)
+- **Kiro**: Claude Sonnet 4.5, Haiku 4.5 (AWS Builder ID)
+
+---
+
+## Bắt đầu nhanh
+
+Bắt đầu trong 2 phút:
+
+```bash
+# Install globally
+npm install -g 9router
+
+# Start (dashboard opens automatically)
+9router
+```
+
+🎉 **Dashboard mở** → Kết nối provider → Bắt đầu code!
+
+**Dùng trong CLI tool:**
+
+```
+Endpoint: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-5-20251101
+```
+
+[→ Hướng dẫn Bắt đầu đầy đủ](getting-started.md)
+
+---
+
+## Trường hợp sử dụng
+
+### Cho Developer cá nhân
+
+- Tối đa hóa subscription Claude Code/Codex
+- Dùng Gemini CLI free tier (180K/tháng)
+- Fallback sang model siêu rẻ ($0.20/1M)
+- Code 24/7 không bị rate limit
+
+### Cho Team
+
+- Triển khai trên VPS/Cloud để chia sẻ truy cập
+- Theo dõi chi tiêu team thời gian thực
+- Đặt giới hạn ngân sách cho mỗi tier
+- Quản lý provider tập trung
+
+### Cho Mobile/Remote Coding
+
+- Dùng cloud deployment (https://9router.com)
+- Truy cập từ iPad, điện thoại, mọi nơi
+- Không bị giới hạn localhost
+- Mạng Cloudflare edge (300+ vị trí)
+
+---
+
+## Tiếp theo là gì?
+
+- [Bắt đầu](getting-started.md) - Cài đặt và cấu hình trong 5 phút
+- [Hướng dẫn cài đặt](getting-started/installation.md) - Hướng dẫn setup chi tiết
+- [Tính năng](features/) - Khám phá mọi khả năng
+- [FAQ](faq.md) - Các câu hỏi thường gặp
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ for developers maximizing AI value</sub>
+</div>
diff --git a/gitbook/content/vi/integration/claude-code.md b/gitbook/content/vi/integration/claude-code.md
new file mode 100644
index 0000000..e4f9a08
--- /dev/null
+++ b/gitbook/content/vi/integration/claude-code.md
@@ -0,0 +1,109 @@
+# Tích hợp Claude Code
+
+Tích hợp 9Router với Claude Code CLI để định tuyến request API Anthropic qua hệ thống routing thông minh của 9Router.
+
+## Yêu cầu
+
+- Claude Code CLI đã cài đặt
+- 9Router đang chạy cục bộ hoặc cloud endpoint đã cấu hình
+- API key từ 9Router dashboard
+
+## Setup
+
+### 1. Cấu hình biến môi trường
+
+Đặt các biến môi trường sau trong file cấu hình shell (`~/.bashrc`, `~/.zshrc`, hoặc `~/.bash_profile`):
+
+```bash
+# Base URL for 9Router
+export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
+
+# Optional: Set default models for aliases
+export ANTHROPIC_DEFAULT_OPUS_MODEL="cc/claude-opus-4-5-20251101"
+export ANTHROPIC_DEFAULT_SONNET_MODEL="cc/claude-sonnet-4-5-20250929"
+export ANTHROPIC_DEFAULT_HAIKU_MODEL="cc/claude-haiku-4-5-20251001"
+```
+
+### 2. Reload Shell Configuration
+
+```bash
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### 3. Xác minh Cấu hình
+
+Kiểm tra các biến môi trường đã set đúng:
+
+```bash
+echo $ANTHROPIC_BASE_URL
+```
+
+## Model Aliases
+
+Claude Code hỗ trợ các alias model sau ánh xạ sang model 9Router:
+
+| Alias | Model | Biến môi trường |
+|-------|-------|---------------------|
+| `opus` | Claude Opus 4.5 | `ANTHROPIC_DEFAULT_OPUS_MODEL` |
+| `sonnet` | Claude Sonnet 4.5 | `ANTHROPIC_DEFAULT_SONNET_MODEL` |
+| `haiku` | Claude Haiku 4.5 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` |
+
+## Ví dụ Sử dụng
+
+### Dùng Model Aliases
+
+```bash
+# Use Opus model
+claude --model opus "Explain quantum computing"
+
+# Use Sonnet model
+claude --model sonnet "Write a Python function"
+
+# Use Haiku model
+claude --model haiku "Quick code review"
+```
+
+### Dùng Full Model Names
+
+```bash
+claude --model cc/claude-opus-4-5-20251101 "Your prompt here"
+```
+
+## File Settings
+
+Claude Code lưu cấu hình trong `~/.claude/settings.json`. Bạn có thể sửa file này thủ công nếu cần:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "defaultModel": "sonnet"
+}
+```
+
+## Troubleshooting
+
+### Lỗi Connection
+
+Nếu gặp lỗi kết nối:
+
+1. Xác minh 9Router đang chạy: `curl http://localhost:20128/health`
+2. Kiểm tra biến môi trường đã set đúng
+3. Đảm bảo không firewall nào chặn port 20128
+
+### Model Not Found
+
+Nếu gặp lỗi "model not found":
+
+1. Xác minh tên model khớp với cấu hình 9Router
+2. Kiểm tra kết nối provider đang hoạt động trong 9Router dashboard
+3. Đảm bảo model có sẵn trong các provider đã kết nối
+
+## Cloud Endpoint
+
+Để dùng 9Router cloud endpoint thay vì localhost:
+
+```bash
+export ANTHROPIC_BASE_URL="https://9router.com"
+```
+
+Đảm bảo bạn đã cấu hình API key trong 9Router cloud dashboard.
diff --git a/gitbook/content/vi/integration/cline.md b/gitbook/content/vi/integration/cline.md
new file mode 100644
index 0000000..9917265
--- /dev/null
+++ b/gitbook/content/vi/integration/cline.md
@@ -0,0 +1,201 @@
+# Tích hợp Cline
+
+Tích hợp 9Router với extension Cline VSCode để định tuyến request AI qua hệ thống routing thông minh của 9Router.
+
+## Yêu cầu
+
+- Visual Studio Code đã cài đặt
+- Extension Cline đã cài đặt từ VSCode marketplace
+- 9Router đang chạy cục bộ hoặc cloud endpoint đã cấu hình
+- API key từ 9Router dashboard
+
+## Setup
+
+### 1. Mở Cline Settings
+
+1. Mở Visual Studio Code
+2. Mở panel extension Cline (click icon Cline trong sidebar)
+3. Click icon **Settings** (icon bánh răng) trong panel Cline
+
+### 2. Chọn API Provider
+
+1. Trong Cline settings, tìm dropdown **API Provider**
+2. Chọn **Ollama** từ danh sách
+   - Lưu ý: Chúng ta dùng provider type Ollama vì nó tương thích với API kiểu OpenAI
+
+### 3. Cấu hình Base URL
+
+Đặt base URL tới endpoint 9Router:
+
+**Cho 9Router cục bộ:**
+```
+http://localhost:20128/v1
+```
+
+**Cho 9Router cloud:**
+```
+https://9router.com
+```
+
+**Các bước:**
+1. Trong field **Base URL**, nhập endpoint 9Router
+2. Đảm bảo bao gồm `/v1` ở cuối
+
+### 4. Thêm API Key
+
+1. Trong field **API Key**, nhập API key 9Router của bạn
+2. Bạn có thể tìm API key trong 9Router dashboard tại **Settings → API Keys**
+3. Key bắt đầu bằng `sk-9router-`
+
+### 5. Chọn Model
+
+1. Trong dropdown **Model**, bạn có thể:
+   - Chọn từ model có sẵn (nếu Cline auto-detect)
+   - Nhập tên model thủ công từ cấu hình 9Router
+
+2. Tên model phổ biến:
+   - `gpt-4`
+   - `gpt-4o`
+   - `claude-opus-4-5`
+   - `claude-sonnet-4-5`
+   - `gemini-2.0-flash`
+
+### 6. Lưu Cấu hình
+
+Click **Save** hoặc đóng panel settings. Cline sẽ tự lưu cấu hình.
+
+## Ví dụ Cấu hình
+
+Cline settings của bạn nên trông như sau:
+
+```
+API Provider: Ollama
+Base URL: http://localhost:20128/v1
+API Key: sk-9router-xxxxxxxxxxxxx
+Model: gpt-4
+```
+
+## Model có sẵn
+
+Bạn có thể dùng bất kỳ model nào đã cấu hình trong 9Router dashboard. Ví dụ phổ biến:
+
+| Tên Model | Provider | Mô tả |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## Sử dụng
+
+### Chat với AI
+
+1. Mở panel Cline trong VSCode
+2. Gõ tin nhắn vào input chat
+3. Nhấn Enter để gửi
+4. Cline sẽ dùng 9Router để xử lý request
+
+### Tạo Code
+
+1. Yêu cầu Cline tạo code: "Create a React component for a login form"
+2. Cline sẽ tạo code qua 9Router
+3. Xem và chấp nhận code được tạo
+
+### Giải thích Code
+
+1. Chọn code trong editor
+2. Hỏi Cline: "Explain this code"
+3. Nhận giải thích AI qua 9Router
+
+### Thao tác File
+
+1. Yêu cầu Cline tạo, sửa hoặc xóa files
+2. Cline sẽ dùng 9Router để hiểu context và thực hiện thay đổi
+3. Xem thay đổi trước khi chấp nhận
+
+## Troubleshooting
+
+### Lỗi "Connection Failed"
+
+1. Xác minh 9Router đang chạy: `curl http://localhost:20128/health`
+2. Kiểm tra base URL đúng và bao gồm `/v1`
+3. Đảm bảo không firewall nào chặn port 20128
+4. Thử khởi động lại VSCode
+
+### Lỗi "Invalid API Key"
+
+1. Xác minh API key trong 9Router dashboard
+2. Đảm bảo bạn sao chép đầy đủ key bao gồm prefix `sk-9router-`
+3. Kiểm tra API key chưa hết hạn
+4. Thử tạo API key mới
+
+### Lỗi "Model Not Found"
+
+1. Xác minh tên model khớp chính xác với cấu hình 9Router
+2. Kiểm tra kết nối provider đang hoạt động trong 9Router dashboard
+3. Đảm bảo model có sẵn trong các provider đã kết nối
+4. Thử dùng tên model đầy đủ (ví dụ: `openai/gpt-4` thay vì `gpt-4`)
+
+### Cline không phản hồi
+
+1. Kiểm tra panel output Cline để xem thông báo lỗi
+2. Xác minh 9Router instance đang chạy và healthy
+3. Thử reload cửa sổ VSCode (Cmd/Ctrl + Shift + P → "Reload Window")
+4. Kiểm tra logs 9Router để xem lỗi
+
+## Cấu hình Nâng cao
+
+### Dùng Cloud Endpoint
+
+Để dùng 9Router cloud endpoint thay vì localhost:
+
+1. Trong Cline settings, đặt Base URL: `https://9router.com`
+2. Đảm bảo bạn đã cấu hình API key trong 9Router cloud dashboard
+3. Đảm bảo cloud endpoint đang hoạt động và truy cập được
+
+### Nhiều Model
+
+Bạn có thể chuyển nhanh giữa các model:
+
+1. Mở Cline settings
+2. Đổi field **Model** sang model khác
+3. Lưu và tiếp tục chat với model mới
+
+### Custom Timeout
+
+Nếu gặp vấn đề timeout với request lớn:
+
+1. Mở VSCode settings (Cmd/Ctrl + ,)
+2. Tìm "Cline timeout"
+3. Tăng giá trị timeout (mặc định thường là 30 giây)
+
+## Best Practices
+
+1. **Dùng Model phù hợp**: Chọn model nhanh (như Haiku hoặc Flash) cho task đơn giản, model mạnh hơn (như Opus hoặc GPT-4) cho task phức tạp
+2. **Theo dõi Usage**: Kiểm tra 9Router dashboard để xem thống kê và chi phí
+3. **Quản lý Context**: Giữ cuộc trò chuyện tập trung để giảm token usage
+4. **Chuyển Model**: Chuyển model dựa trên độ phức tạp task để tối ưu chi phí và hiệu năng
+5. **Bảo mật API Key**: Không bao giờ commit API key vào version control
+
+## Tích hợp với Tính năng 9Router
+
+### Định tuyến Model
+
+9Router tự động định tuyến request đến provider tốt nhất hiện có dựa trên:
+- Tính khả dụng của model
+- Trạng thái sức khỏe provider
+- Tối ưu chi phí
+- Load balancing
+
+### Hỗ trợ Fallback
+
+Nếu một provider thất bại, 9Router tự động fallback sang provider khác đã cấu hình trong dashboard.
+
+### Theo dõi Usage
+
+Giám sát usage Cline qua 9Router dashboard:
+- Tổng request
+- Token usage
+- Chi phí mỗi model
+- Phân bổ provider
diff --git a/gitbook/content/vi/integration/codex.md b/gitbook/content/vi/integration/codex.md
new file mode 100644
index 0000000..1d2a76e
--- /dev/null
+++ b/gitbook/content/vi/integration/codex.md
@@ -0,0 +1,136 @@
+# Tích hợp OpenAI Codex CLI
+
+Tích hợp 9Router với OpenAI Codex CLI để định tuyến request API OpenAI qua hệ thống routing thông minh của 9Router.
+
+## Yêu cầu
+
+- OpenAI Codex CLI đã cài đặt
+- 9Router đang chạy cục bộ hoặc cloud endpoint đã cấu hình
+- API key từ 9Router dashboard
+
+## Setup
+
+### 1. Cấu hình biến môi trường
+
+Đặt các biến môi trường sau trong file cấu hình shell (`~/.bashrc`, `~/.zshrc`, hoặc `~/.bash_profile`):
+
+```bash
+# Base URL for 9Router
+export OPENAI_BASE_URL="http://localhost:20128/v1"
+
+# API Key from 9Router dashboard
+export OPENAI_API_KEY="your-9router-api-key"
+```
+
+### 2. Reload Shell Configuration
+
+```bash
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### 3. Xác minh Cấu hình
+
+Kiểm tra các biến môi trường đã set đúng:
+
+```bash
+echo $OPENAI_BASE_URL
+echo $OPENAI_API_KEY
+```
+
+## Model có sẵn
+
+9Router cung cấp các model Codex sau:
+
+| Model ID | Mô tả |
+|----------|-------------|
+| `cx/gpt-5.2-codex` | GPT-5.2 Codex - Phiên bản mới nhất |
+| `cx/gpt-5.1-codex-max` | GPT-5.1 Codex Max - Extended context |
+
+## Ví dụ Sử dụng
+
+### Sử dụng Cơ bản
+
+```bash
+# Use GPT-5.2 Codex
+codex --model cx/gpt-5.2-codex "Write a function to sort an array"
+
+# Use GPT-5.1 Codex Max
+codex --model cx/gpt-5.1-codex-max "Explain this complex algorithm"
+```
+
+### Tạo Code
+
+```bash
+codex --model cx/gpt-5.2-codex "Create a REST API endpoint for user authentication"
+```
+
+### Giải thích Code
+
+```bash
+codex --model cx/gpt-5.1-codex-max "Explain what this code does: $(cat myfile.js)"
+```
+
+## File Cấu hình
+
+Bạn cũng có thể cấu hình Codex CLI qua file cấu hình. Tạo hoặc sửa `~/.codex/config.json`:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "apiKey": "your-9router-api-key",
+  "defaultModel": "cx/gpt-5.2-codex"
+}
+```
+
+## Troubleshooting
+
+### Lỗi Xác thực
+
+Nếu gặp lỗi xác thực:
+
+1. Xác minh API key đúng trong 9Router dashboard
+2. Kiểm tra biến môi trường `OPENAI_API_KEY` đã set
+3. Đảm bảo API key chưa hết hạn
+
+### Lỗi Connection
+
+Nếu gặp lỗi kết nối:
+
+1. Xác minh 9Router đang chạy: `curl http://localhost:20128/health`
+2. Kiểm tra biến môi trường đã set đúng
+3. Đảm bảo không firewall nào chặn port 20128
+
+### Model không khả dụng
+
+Nếu gặp lỗi "model not available":
+
+1. Xác minh tên model khớp với cấu hình 9Router
+2. Kiểm tra kết nối provider OpenAI đang hoạt động trong 9Router dashboard
+3. Đảm bảo model có sẵn trong các provider đã kết nối
+
+## Cloud Endpoint
+
+Để dùng 9Router cloud endpoint thay vì localhost:
+
+```bash
+export OPENAI_BASE_URL="https://9router.com"
+```
+
+Đảm bảo bạn đã cấu hình API key trong 9Router cloud dashboard.
+
+## Cấu hình Nâng cao
+
+### Custom Timeout
+
+```bash
+export OPENAI_TIMEOUT=60  # seconds
+```
+
+### Debug Mode
+
+Bật debug mode để xem logs request/response chi tiết:
+
+```bash
+export CODEX_DEBUG=true
+codex --model cx/gpt-5.2-codex "Your prompt"
+```
diff --git a/gitbook/content/vi/integration/continue.md b/gitbook/content/vi/integration/continue.md
new file mode 100644
index 0000000..0aabef2
--- /dev/null
+++ b/gitbook/content/vi/integration/continue.md
@@ -0,0 +1,249 @@
+# Tích hợp Continue VSCode Extension
+
+Tích hợp 9Router với extension Continue để mang trợ lý AI trực tiếp vào Visual Studio Code.
+
+## Yêu cầu
+
+- Visual Studio Code đã cài đặt
+- Extension Continue đã cài đặt từ VSCode marketplace
+- 9Router API key từ [dashboard](https://9router.com/dashboard)
+- 9Router đang chạy (cục bộ hoặc cloud)
+
+## Các bước Cấu hình
+
+### 1. Mở Continue Configuration
+
+1. Mở VSCode
+2. Nhấn `Cmd+Shift+P` (Mac) hoặc `Ctrl+Shift+P` (Windows/Linux)
+3. Gõ "Continue: Open Config" và chọn
+4. Mở `~/.continue/config.json`
+
+### 2. Thêm Cấu hình Model 9Router
+
+Thêm cấu hình sau vào `config.json`:
+
+**Setup Một Model:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**Setup Nhiều Model:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus (Best)",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Sonnet (Balanced)",
+      "provider": "openai",
+      "model": "cc/claude-sonnet-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - DeepSeek Chat (Code)",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Haiku (Fast)",
+      "provider": "openai",
+      "model": "cc/claude-haiku-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**Cho Cloud 9Router:**
+Thay `apiBase` bằng:
+```json
+"apiBase": "https://9router.com/v1"
+```
+
+### 3. Lưu và Reload
+
+1. Lưu file cấu hình
+2. Reload cửa sổ VSCode: `Cmd+Shift+P` → "Developer: Reload Window"
+3. Extension Continue sẽ load cấu hình mới
+
+### 4. Chọn Model
+
+1. Mở sidebar Continue (click icon Continue trong panel trái)
+2. Click dropdown chọn model ở trên cùng
+3. Chọn model 9Router ưa thích
+
+## Model có sẵn
+
+### Claude Models (Anthropic)
+- `cc/claude-opus-4-5-20251101` - Mạnh nhất, tốt nhất cho task phức tạp
+- `cc/claude-sonnet-4-20250514` - Cân bằng hiệu năng và tốc độ
+- `cc/claude-haiku-4-20250514` - Nhanh nhất, phù hợp task đơn giản
+
+### DeepSeek Models
+- `cx/deepseek-chat` - Xuất sắc cho tạo code
+- `cx/deepseek-reasoner` - Tốt nhất cho giải quyết vấn đề phức tạp
+
+### GLM Models (Zhipu AI)
+- `glm/glm-4-plus` - Tiếng Trung và tiếng Anh nâng cao
+- `glm/glm-4-flash` - Phản hồi nhanh
+
+## Ví dụ Sử dụng
+
+### Giải thích Code
+1. Chọn code trong editor
+2. Mở sidebar Continue
+3. Gõ: "Explain this code"
+4. Model: `cc/claude-sonnet-4-20250514`
+
+### Tạo Code
+1. Mở sidebar Continue
+2. Gõ: "Create a React component for user profile card"
+3. Model: `cx/deepseek-chat`
+
+### Refactoring
+1. Chọn code để refactor
+2. Gõ: "Refactor this to use async/await"
+3. Model: `cc/claude-sonnet-4-20250514`
+
+### Sửa Bug
+1. Chọn code có vấn đề
+2. Gõ: "Find and fix the bug in this code"
+3. Model: `cx/deepseek-reasoner`
+
+## Cấu hình Nâng cao
+
+### Custom System Prompts
+
+Thêm system prompt tùy chỉnh cho hành vi cụ thể:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Code Expert",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "systemMessage": "You are an expert programmer. Always provide clean, well-documented code with best practices."
+    }
+  ]
+}
+```
+
+### Temperature và Parameters
+
+Điều chỉnh hành vi model với parameters:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Creative Writer",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "temperature": 0.9,
+      "topP": 0.95
+    }
+  ]
+}
+```
+
+### Context Providers
+
+Cấu hình context Continue gửi đến model:
+
+```json
+{
+  "contextProviders": [
+    {
+      "name": "code",
+      "params": {
+        "maxLines": 100
+      }
+    },
+    {
+      "name": "diff",
+      "params": {}
+    },
+    {
+      "name": "terminal",
+      "params": {}
+    }
+  ]
+}
+```
+
+## Phím tắt
+
+- `Cmd+L` (Mac) / `Ctrl+L` (Windows/Linux) - Mở Continue chat
+- `Cmd+I` (Mac) / `Ctrl+I` (Windows/Linux) - Inline edit
+- `Cmd+Shift+R` (Mac) / `Ctrl+Shift+R` (Windows/Linux) - Tạo lại response
+
+## Troubleshooting
+
+### Model không phản hồi
+- Kiểm tra 9Router đang chạy: `curl http://localhost:20128/health`
+- Xác minh API key trong config.json
+- Kiểm tra VSCode Developer Console để xem lỗi: `Help` → `Toggle Developer Tools`
+
+### Chọn sai Model
+- Click dropdown model trong sidebar Continue
+- Chọn đúng model 9Router
+- Tên model phải khớp chính xác (case-sensitive)
+
+### Cấu hình không Load
+- Xác minh JSON syntax hợp lệ (dùng JSON validator)
+- Kiểm tra vị trí file: `~/.continue/config.json`
+- Reload cửa sổ VSCode sau khi thay đổi
+
+### Hiệu năng Chậm
+- Chuyển sang model nhanh hơn (haiku, flash)
+- Giảm context size trong contextProviders
+- Kiểm tra độ trễ network đến 9Router
+
+## Best Practices
+
+### Chiến lược Chọn Model
+- **Edit nhanh**: Dùng `cc/claude-haiku-4-20250514`
+- **Tạo code**: Dùng `cx/deepseek-chat`
+- **Refactoring phức tạp**: Dùng `cc/claude-opus-4-5-20251101`
+- **Giải quyết vấn đề**: Dùng `cx/deepseek-reasoner`
+
+### Quản lý Context
+- Chỉ chọn code liên quan trước khi hỏi
+- Dùng prompt cụ thể, rõ ràng
+- Chia task phức tạp thành các bước nhỏ
+
+### Tối ưu Chi phí
+- Dùng model nhanh hơn/rẻ hơn cho task đơn giản
+- Giới hạn context size khi có thể
+- Cache response thường dùng
+
+## Bước tiếp theo
+
+- [Cấu hình Cursor](cursor.md) cho tích hợp IDE nâng cao
+- [Setup Roo](roo.md) cho trợ lý AI
+- [Khám phá CLI usage](../cli/basic-usage.md)
+- [Tìm hiểu về chọn model](../models/overview.md)
diff --git a/gitbook/content/vi/integration/cursor.md b/gitbook/content/vi/integration/cursor.md
new file mode 100644
index 0000000..6e89d99
--- /dev/null
+++ b/gitbook/content/vi/integration/cursor.md
@@ -0,0 +1,149 @@
+# Tích hợp Cursor
+
+Tích hợp 9Router với Cursor IDE để định tuyến request AI qua hệ thống routing thông minh của 9Router.
+
+## Yêu cầu
+
+- Cursor IDE đã cài đặt
+- Tài khoản Cursor Pro (cần thiết cho custom API endpoint)
+- 9Router cloud endpoint đã cấu hình
+- API key từ 9Router dashboard
+
+## ⚠️ Lưu ý Quan trọng
+
+> **Yêu cầu Cloud Endpoint**: Cursor định tuyến request qua server của chính nó và không hỗ trợ endpoint localhost. Bạn phải dùng 9Router cloud endpoint: `https://9router.com`
+
+> **Yêu cầu Cursor Pro**: Tính năng này yêu cầu tài khoản Cursor Pro để dùng custom API endpoint.
+
+## Setup
+
+### 1. Mở Cursor Settings
+
+1. Mở Cursor IDE
+2. Đi đến **Settings** (Cmd/Ctrl + ,)
+3. Đi đến phần **Models**
+
+### 2. Bật OpenAI API
+
+1. Tìm option **OpenAI API key**
+2. Bật toggle để kích hoạt cấu hình custom API
+
+### 3. Cấu hình Base URL
+
+Đặt base URL tới 9Router cloud endpoint:
+
+```
+https://9router.com
+```
+
+**Các bước:**
+1. Trong cài đặt Models, tìm field **Base URL**
+2. Nhập: `https://9router.com`
+3. Click **Save**
+
+### 4. Thêm API Key
+
+1. Trong field **API Key**, nhập API key 9Router
+2. Bạn có thể tìm API key trong 9Router dashboard tại **Settings → API Keys**
+3. Click **Save**
+
+### 5. Thêm Custom Model
+
+1. Click nút **View All Models**
+2. Click **Add Custom Model**
+3. Nhập tên model từ cấu hình 9Router (ví dụ: `gpt-4`, `claude-opus-4-5`, v.v.)
+4. Click **Add**
+
+### 6. Chọn Model
+
+1. Trong giao diện chat Cursor, click dropdown chọn model
+2. Chọn custom model từ danh sách
+3. Bắt đầu dùng 9Router với Cursor!
+
+## Ví dụ Cấu hình
+
+Cursor settings của bạn nên trông như sau:
+
+```
+OpenAI API: ✓ Enabled
+Base URL: https://9router.com
+API Key: sk-9router-xxxxxxxxxxxxx
+Custom Models: gpt-4, claude-opus-4-5, gemini-2.0-flash
+```
+
+## Model có sẵn
+
+Bạn có thể dùng bất kỳ model nào đã cấu hình trong 9Router dashboard. Ví dụ phổ biến:
+
+| Tên Model | Provider | Mô tả |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## Sử dụng
+
+### Giao diện Chat
+
+1. Mở Cursor chat (Cmd/Ctrl + L)
+2. Chọn model từ dropdown
+3. Bắt đầu chat với AI qua 9Router
+
+### Tạo Code Inline
+
+1. Chọn code trong editor
+2. Nhấn Cmd/Ctrl + K
+3. Nhập prompt
+4. Cursor sẽ dùng 9Router để tạo code
+
+### Giải thích Code
+
+1. Chọn code trong editor
+2. Nhấn Cmd/Ctrl + L
+3. Hỏi "Explain this code"
+4. Nhận giải thích AI qua 9Router
+
+## Troubleshooting
+
+### Lỗi "Invalid API Key"
+
+1. Xác minh API key trong 9Router dashboard
+2. Đảm bảo bạn sao chép đầy đủ key bao gồm prefix `sk-9router-`
+3. Kiểm tra API key chưa hết hạn
+4. Thử tạo API key mới
+
+### Lỗi "Model Not Found"
+
+1. Xác minh tên model khớp chính xác với cấu hình 9Router
+2. Kiểm tra kết nối provider đang hoạt động trong 9Router dashboard
+3. Đảm bảo model có sẵn trong các provider đã kết nối
+4. Thử dùng tên model đầy đủ (ví dụ: `openai/gpt-4` thay vì `gpt-4`)
+
+### Lỗi Connection
+
+1. Xác minh bạn đang dùng cloud endpoint: `https://9router.com`
+2. Kiểm tra kết nối internet
+3. Đảm bảo dịch vụ 9Router cloud đang hoạt động
+4. Thử tắt VPN hoặc proxy nếu đang bật
+
+### Localhost không hoạt động
+
+> **Nhớ**: Cursor không hỗ trợ endpoint localhost. Bạn phải dùng cloud endpoint `https://9router.com`. Nếu cần dùng 9Router cục bộ, hãy cân nhắc dùng dịch vụ tunneling như ngrok để expose endpoint cục bộ.
+
+## Setup Cloud Endpoint
+
+Nếu bạn chạy 9Router cục bộ và muốn dùng với Cursor:
+
+1. Bật cloud endpoint trong 9Router settings
+2. Cấu hình URL cloud endpoint trong 9Router dashboard
+3. Dùng URL cloud trong Cursor settings
+4. Đảm bảo 9Router instance cục bộ có thể truy cập từ internet
+
+## Best Practices
+
+1. **Dùng Model Aliases**: Tạo alias ngắn cho model thường dùng trong 9Router
+2. **Theo dõi Usage**: Kiểm tra 9Router dashboard để xem thống kê và chi phí
+3. **Xoay API Key**: Định kỳ xoay API key để bảo mật
+4. **Test Model**: Thử các model khác nhau để tìm model tốt nhất cho use case
diff --git a/gitbook/content/vi/integration/other-tools.md b/gitbook/content/vi/integration/other-tools.md
new file mode 100644
index 0000000..4bfffa8
--- /dev/null
+++ b/gitbook/content/vi/integration/other-tools.md
@@ -0,0 +1,416 @@
+# Tích hợp các Công cụ khác
+
+9Router tương thích với mọi công cụ hỗ trợ format API OpenAI. Hướng dẫn này bao gồm pattern tích hợp tổng quát cho nhiều công cụ và ứng dụng tùy chỉnh.
+
+## Tổng quan
+
+9Router cung cấp API endpoint tương thích OpenAI hoạt động với:
+- Script và ứng dụng tùy chỉnh
+- API client và công cụ test
+- Công cụ CLI và utility
+- Tích hợp bên thứ ba
+- Framework phát triển
+
+## Pattern Setup Tổng quát
+
+Mọi công cụ tương thích OpenAI có thể kết nối đến 9Router bằng các cài đặt sau:
+
+**9Router cục bộ:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+Model: any 9Router model (cc/*, cx/*, glm/*, etc.)
+```
+
+**9Router cloud:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+Model: any 9Router model (cc/*, cx/*, glm/*, etc.)
+```
+
+## Model có sẵn
+
+### Claude Models (Anthropic)
+- `cc/claude-opus-4-5-20251101`
+- `cc/claude-sonnet-4-20250514`
+- `cc/claude-haiku-4-20250514`
+
+### DeepSeek Models
+- `cx/deepseek-chat`
+- `cx/deepseek-reasoner`
+
+### GLM Models (Zhipu AI)
+- `glm/glm-4-plus`
+- `glm/glm-4-flash`
+
+## Ví dụ Tích hợp
+
+### Python với OpenAI SDK
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+response = client.chat.completions.create(
+    model="cc/claude-sonnet-4-20250514",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ]
+)
+
+print(response.choices[0].message.content)
+```
+
+### Node.js với OpenAI SDK
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+const response = await client.chat.completions.create({
+  model: "cc/claude-sonnet-4-20250514",
+  messages: [
+    { role: "user", content: "Hello, how are you?" }
+  ]
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### Lệnh cURL
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-api-key-from-dashboard" \
+  -d '{
+    "model": "cc/claude-sonnet-4-20250514",
+    "messages": [
+      {"role": "user", "content": "Hello, how are you?"}
+    ]
+  }'
+```
+
+### HTTP Client (Postman, Insomnia)
+
+**Request:**
+```
+POST http://localhost:20128/v1/chat/completions
+```
+
+**Headers:**
+```
+Content-Type: application/json
+Authorization: Bearer your-api-key-from-dashboard
+```
+
+**Body:**
+```json
+{
+  "model": "cc/claude-sonnet-4-20250514",
+  "messages": [
+    {"role": "user", "content": "Hello, how are you?"}
+  ],
+  "temperature": 0.7,
+  "max_tokens": 1000
+}
+```
+
+### Tích hợp LangChain
+
+```python
+from langchain.chat_models import ChatOpenAI
+from langchain.schema import HumanMessage
+
+llm = ChatOpenAI(
+    model_name="cc/claude-sonnet-4-20250514",
+    openai_api_key="your-api-key-from-dashboard",
+    openai_api_base="http://localhost:20128/v1",
+    temperature=0.7
+)
+
+messages = [HumanMessage(content="Explain quantum computing")]
+response = llm(messages)
+print(response.content)
+```
+
+### Tích hợp LlamaIndex
+
+```python
+from llama_index.llms import OpenAI
+
+llm = OpenAI(
+    model="cc/claude-sonnet-4-20250514",
+    api_key="your-api-key-from-dashboard",
+    api_base="http://localhost:20128/v1"
+)
+
+response = llm.complete("What is machine learning?")
+print(response.text)
+```
+
+## Ví dụ Script Tùy chỉnh
+
+### Script Xử lý Batch
+
+```python
+import openai
+import json
+
+openai.api_key = "your-api-key-from-dashboard"
+openai.api_base = "http://localhost:20128/v1"
+
+def process_batch(prompts, model="cx/deepseek-chat"):
+    results = []
+    for prompt in prompts:
+        response = openai.ChatCompletion.create(
+            model=model,
+            messages=[{"role": "user", "content": prompt}]
+        )
+        results.append({
+            "prompt": prompt,
+            "response": response.choices[0].message.content
+        })
+    return results
+
+prompts = [
+    "Explain AI in one sentence",
+    "What is machine learning?",
+    "Define neural networks"
+]
+
+results = process_batch(prompts)
+print(json.dumps(results, indent=2))
+```
+
+### Xử lý Streaming Response
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+async function streamResponse(prompt) {
+  const stream = await client.chat.completions.create({
+    model: "cc/claude-sonnet-4-20250514",
+    messages: [{ role: "user", content: prompt }],
+    stream: true
+  });
+
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content || "";
+    process.stdout.write(content);
+  }
+}
+
+streamResponse("Write a short story about AI");
+```
+
+### So sánh Nhiều Model
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+models = [
+    "cc/claude-sonnet-4-20250514",
+    "cx/deepseek-chat",
+    "glm/glm-4-plus"
+]
+
+prompt = "Explain quantum computing in simple terms"
+
+for model in models:
+    response = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "user", "content": prompt}]
+    )
+    print(f"\n=== {model} ===")
+    print(response.choices[0].message.content)
+```
+
+## Pattern Tích hợp Phổ biến
+
+### Biến môi trường
+
+Lưu credentials an toàn:
+
+```bash
+# .env file
+ROUTER_API_KEY=your-api-key-from-dashboard
+ROUTER_BASE_URL=http://localhost:20128/v1
+ROUTER_MODEL=cc/claude-sonnet-4-20250514
+```
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.getenv("ROUTER_API_KEY"),
+    base_url=os.getenv("ROUTER_BASE_URL")
+)
+```
+
+### Xử lý Lỗi
+
+```python
+from openai import OpenAI, OpenAIError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+try:
+    response = client.chat.completions.create(
+        model="cc/claude-sonnet-4-20250514",
+        messages=[{"role": "user", "content": "Hello"}]
+    )
+    print(response.choices[0].message.content)
+except OpenAIError as e:
+    print(f"Error: {e}")
+```
+
+### Logic Retry
+
+```python
+import time
+from openai import OpenAI, RateLimitError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+def chat_with_retry(prompt, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            response = client.chat.completions.create(
+                model="cc/claude-sonnet-4-20250514",
+                messages=[{"role": "user", "content": prompt}]
+            )
+            return response.choices[0].message.content
+        except RateLimitError:
+            if attempt < max_retries - 1:
+                time.sleep(2 ** attempt)  # Exponential backoff
+            else:
+                raise
+```
+
+## Troubleshooting
+
+### Vấn đề Connection
+
+**Vấn đề:** Không kết nối được đến 9Router
+```bash
+# Check if 9Router is running
+curl http://localhost:20128/health
+
+# Expected response:
+{"status": "ok"}
+```
+
+**Giải pháp:**
+- Xác minh 9Router đang chạy
+- Kiểm tra port 20128 không bị chặn
+- Đảm bảo base URL đúng (bao gồm `/v1`)
+
+### Lỗi Xác thực
+
+**Vấn đề:** 401 Unauthorized
+```
+Error: Invalid API key
+```
+
+**Giải pháp:**
+- Xác minh API key từ dashboard
+- Kiểm tra format header Authorization: `Bearer your-api-key`
+- Đảm bảo không có khoảng trắng hoặc xuống dòng thừa trong API key
+
+### Model Not Found
+
+**Vấn đề:** 404 Model not found
+```
+Error: Model 'cc/claude-opus' not found
+```
+
+**Giải pháp:**
+- Dùng tên model chính xác (case-sensitive)
+- Kiểm tra model có sẵn: `curl http://localhost:20128/v1/models`
+- Xác minh model được bật trong plan của bạn
+
+### Vấn đề Timeout
+
+**Vấn đề:** Request timeout
+```
+Error: Request timed out after 30s
+```
+
+**Giải pháp:**
+- Tăng timeout trong cấu hình client
+- Dùng model nhanh hơn cho task nhạy cảm về thời gian
+- Kiểm tra kết nối network đến 9Router
+
+### Rate Limiting
+
+**Vấn đề:** 429 Too Many Requests
+```
+Error: Rate limit exceeded
+```
+
+**Giải pháp:**
+- Triển khai exponential backoff
+- Giảm tần suất request
+- Kiểm tra rate limit trong dashboard
+- Cân nhắc nâng cấp plan
+
+## Best Practices
+
+### Bảo mật
+- Lưu API key trong biến môi trường
+- Không bao giờ commit API key vào version control
+- Dùng HTTPS cho cloud deployment
+- Xoay API key định kỳ
+
+### Hiệu năng
+- Dùng model phù hợp với độ phức tạp task
+- Triển khai caching cho query lặp lại
+- Dùng streaming cho phản hồi dài
+- Batch request khi có thể
+
+### Xử lý Lỗi
+- Luôn triển khai try-catch block
+- Thêm logic retry với exponential backoff
+- Log lỗi để debug
+- Cung cấp cơ chế fallback
+
+### Tối ưu Chi phí
+- Chọn model tiết kiệm chi phí cho task đơn giản
+- Cache phản hồi khi phù hợp
+- Theo dõi usage trong dashboard
+- Đặt giới hạn request trong code
+
+## Bước tiếp theo
+
+- [Cấu hình Cursor](cursor.md) cho tích hợp IDE
+- [Setup Continue](continue.md) cho VSCode
+- [Khám phá CLI usage](../cli/basic-usage.md)
+- [Tìm hiểu về chọn model](../models/overview.md)
+- [API Reference](../api/reference.md)
diff --git a/gitbook/content/vi/integration/roo.md b/gitbook/content/vi/integration/roo.md
new file mode 100644
index 0000000..431e15d
--- /dev/null
+++ b/gitbook/content/vi/integration/roo.md
@@ -0,0 +1,127 @@
+# Tích hợp Roo AI Assistant
+
+Tích hợp 9Router với Roo AI Assistant để truy cập nhiều model AI qua một giao diện thống nhất.
+
+## Yêu cầu
+
+- Roo AI Assistant đã cài đặt
+- 9Router API key từ [dashboard](https://9router.com/dashboard)
+- 9Router đang chạy (cục bộ hoặc cloud)
+
+## Các bước Cấu hình
+
+### 1. Mở Roo Settings
+
+Khởi chạy Roo AI Assistant và mở panel settings.
+
+### 2. Cấu hình API Provider
+
+1. Đi đến cài đặt **API Provider**
+2. Chọn **Ollama** làm provider type
+3. Cấu hình các settings sau:
+
+**Cho 9Router cục bộ:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+```
+
+**Cho 9Router cloud:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+```
+
+### 3. Chọn Model
+
+Chọn từ các model 9Router có sẵn:
+
+**Claude Models:**
+- `cc/claude-opus-4-5-20251101` - Mạnh nhất
+- `cc/claude-sonnet-4-20250514` - Cân bằng
+- `cc/claude-haiku-4-20250514` - Nhanh
+
+**DeepSeek Models:**
+- `cx/deepseek-chat` - Đa năng
+- `cx/deepseek-reasoner` - Reasoning phức tạp
+
+**GLM Models:**
+- `glm/glm-4-plus` - Nâng cao
+- `glm/glm-4-flash` - Phản hồi nhanh
+
+### 4. Test Connection
+
+Gửi tin nhắn test để xác minh tích hợp:
+
+```
+Hello! Can you confirm you're connected through 9Router?
+```
+
+## Ví dụ Sử dụng
+
+### Chat Cơ bản
+```
+Ask Roo: "Explain quantum computing in simple terms"
+Model: cc/claude-sonnet-4-20250514
+```
+
+### Tạo Code
+```
+Ask Roo: "Write a Python function to calculate Fibonacci numbers"
+Model: cx/deepseek-chat
+```
+
+### Reasoning Phức tạp
+```
+Ask Roo: "Analyze the trade-offs between microservices and monolithic architecture"
+Model: cx/deepseek-reasoner
+```
+
+## Mẹo Chọn Model
+
+- **Task nhanh**: Dùng `cc/claude-haiku-4-20250514` hoặc `glm/glm-4-flash`
+- **Hiệu năng cân bằng**: Dùng `cc/claude-sonnet-4-20250514` hoặc `cx/deepseek-chat`
+- **Reasoning phức tạp**: Dùng `cc/claude-opus-4-5-20251101` hoặc `cx/deepseek-reasoner`
+- **Tối ưu chi phí**: Dùng model DeepSeek hoặc GLM
+
+## Troubleshooting
+
+### Connection Failed
+- Xác minh 9Router đang chạy: `curl http://localhost:20128/health`
+- Kiểm tra API key đúng
+- Đảm bảo Base URL bao gồm hậu tố `/v1`
+
+### Model không khả dụng
+- Kiểm tra tên model khớp chính xác (case-sensitive)
+- Xác minh model được bật trong 9Router plan
+- Thử model khác từ danh sách
+
+### Phản hồi Chậm
+- Chuyển sang model nhanh hơn (haiku, flash)
+- Kiểm tra kết nối network
+- Theo dõi logs 9Router để xem vấn đề
+
+## Cấu hình Nâng cao
+
+### Custom Model Aliases
+
+Bạn có thể tạo shortcut cho model thường dùng trong Roo settings:
+
+```
+Alias: "fast" → cc/claude-haiku-4-20250514
+Alias: "smart" → cc/claude-opus-4-5-20251101
+Alias: "code" → cx/deepseek-chat
+```
+
+### Nhiều Profile
+
+Setup profile khác nhau cho use case khác nhau:
+- **Development**: Model DeepSeek cho code
+- **Writing**: Model Claude cho nội dung
+- **Research**: Model Reasoner cho phân tích
+
+## Bước tiếp theo
+
+- [Cấu hình Cursor](cursor.md) cho tích hợp IDE
+- [Setup Continue](continue.md) cho VSCode
+- [Khám phá CLI usage](../cli/basic-usage.md)
diff --git a/gitbook/content/vi/providers/cheap.md b/gitbook/content/vi/providers/cheap.md
new file mode 100644
index 0000000..f7b825d
--- /dev/null
+++ b/gitbook/content/vi/providers/cheap.md
@@ -0,0 +1,462 @@
+# Cheap Providers - Backup Siêu Rẻ
+
+Khi hết quota subscription, trả vài xu thay vì vài đô. Rẻ hơn ChatGPT API ~90%!
+
+---
+
+## Tổng quan
+
+Provider tier rẻ là **backup** khi hết quota subscription:
+
+- 💰 **GLM-4.7** - $0.6/$2.2 per 1M tokens (reset hàng ngày)
+- 💰 **MiniMax M2.1** - $0.2/$1.0 per 1M tokens (reset 5h)
+- 💰 **Kimi K2** - $9/tháng cố định (10M tokens)
+
+**Chiến lược:** Dùng sau khi hết quota subscription, trước free tier. Tiết kiệm chi phí khổng lồ so với ChatGPT API ($20/1M).
+
+---
+
+## GLM-4.7 (Reset Hàng ngày)
+
+### Pricing
+
+| Tier | Input | Output | Reset |
+|------|-------|--------|-------|
+| Standard | $0.60/1M | $2.20/1M | Hàng ngày 10:00 AM |
+| Coding Plan | $0.60/1M | $2.20/1M | Hàng ngày 10:00 AM (3× quota) |
+
+**Ví dụ Chi phí (10M tokens):**
+- Input: 10M × $0.60 = $6
+- Output: 10M × $2.20 = $22
+- **Tổng: $6-22** so với $200 trên ChatGPT API!
+
+### Setup
+
+**Bước 1: Đăng ký**
+
+1. Vào [Zhipu AI](https://open.bigmodel.cn/)
+2. Tạo tài khoản (xác thực số điện thoại)
+3. Chọn **Coding Plan** để có quota 3× ở cùng giá
+
+**Bước 2: Lấy API Key**
+
+```bash
+Dashboard → API Keys → Create New
+→ Copy API key (starts with "zhipu-")
+```
+
+**Bước 3: Thêm vào 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: glm
+API Key: zhipu-your-api-key-here
+```
+
+**Bước 4: Dùng trong CLI**
+
+```
+Model: glm/glm-4.7
+       glm/glm-4.6v (vision)
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Context | Tốt nhất cho |
+|----------|-------------|---------|----------|
+| `glm/glm-4.7` | GLM 4.7 | 128K | Coding, task chung |
+| `glm/glm-4.6v` | GLM 4.6V Vision | 128K | Phân tích ảnh |
+
+### Mẹo Pro
+
+- **Coding Plan** - 3× quota cùng giá ($0.6/$2.2)
+- **Reset hàng ngày** - Quota mới lúc 10:00 AM giờ Bắc Kinh
+- **Tốt nhất cho coding** - Tối ưu cho code generation
+- **Context 128K** - Xử lý file lớn
+
+### Reset Quota
+
+```
+Daily reset: 10:00 AM Beijing Time (UTC+8)
+→ 2:00 AM UTC
+→ 6:00 PM PST (previous day)
+→ 9:00 PM EST (previous day)
+
+Plan your heavy tasks around reset time!
+```
+
+---
+
+## MiniMax M2.1 (Reset 5 Giờ)
+
+### Pricing
+
+| Tier | Input | Output | Reset |
+|------|-------|--------|-------|
+| Standard | $0.20/1M | $1.00/1M | 5 giờ rolling |
+
+**Ví dụ Chi phí (10M tokens):**
+- Input: 10M × $0.20 = $2
+- Output: 10M × $1.00 = $10
+- **Tổng: $2-10** - Lựa chọn rẻ nhất!
+
+### Setup
+
+**Bước 1: Đăng ký**
+
+1. Vào [MiniMax](https://www.minimax.io/)
+2. Tạo tài khoản
+3. Xác thực email/điện thoại
+
+**Bước 2: Lấy API Key**
+
+```bash
+Dashboard → API Management → Create Key
+→ Copy API key
+```
+
+**Bước 3: Thêm vào 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: minimax
+API Key: your-minimax-api-key
+```
+
+**Bước 4: Dùng trong CLI**
+
+```
+Model: minimax/MiniMax-M2.1
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Context | Tốt nhất cho |
+|----------|-------------|---------|----------|
+| `minimax/MiniMax-M2.1` | MiniMax M2.1 | 1M tokens | Context dài, coding |
+
+### Mẹo Pro
+
+- **Lựa chọn rẻ nhất** - $0.20/1M input (rẻ hơn ChatGPT 90%)
+- **5 giờ rolling** - Quota reset mỗi 5 giờ
+- **Context 1M** - Cửa sổ context khổng lồ
+- **Tốt nhất cho file dài** - Xử lý cả codebase
+
+### Reset Quota
+
+```
+5-hour rolling window:
+→ Use quota → Wait 5 hours → Fresh quota
+
+Example:
+10:00 AM - Use 5M tokens
+3:00 PM - Fresh quota available
+8:00 PM - Fresh quota available
+
+Code 24/7 with minimal cost!
+```
+
+---
+
+## Kimi K2 (Cố định $9/tháng)
+
+### Pricing
+
+| Plan | Chi phí Hàng tháng | Tokens bao gồm | Chi phí Hiệu quả |
+|------|--------------|-----------------|----------------|
+| Subscription | $9 | 10M tokens | $0.90/1M |
+
+**Ví dụ Chi phí:**
+- $9/tháng cố định
+- 10M tokens bao gồm
+- **Hiệu quả: $0.90/1M** - Giá trị tốt nhất cho sử dụng đều!
+
+### Setup
+
+**Bước 1: Đăng ký**
+
+1. Vào [Moonshot AI](https://platform.moonshot.ai/)
+2. Tạo tài khoản
+3. Đăng ký plan $9/tháng
+
+**Bước 2: Lấy API Key**
+
+```bash
+Dashboard → API Keys → Create New
+→ Copy API key
+```
+
+**Bước 3: Thêm vào 9Router**
+
+```bash
+9router
+# Dashboard → Providers → Add API Key
+
+Provider: kimi
+API Key: your-kimi-api-key
+```
+
+**Bước 4: Dùng trong CLI**
+
+```
+Model: kimi/kimi-latest
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Context | Tốt nhất cho |
+|----------|-------------|---------|----------|
+| `kimi/kimi-latest` | Kimi Latest | 200K | Coding chung |
+
+### Mẹo Pro
+
+- **Chi phí cố định** - $9/tháng bất kể usage (lên tới 10M)
+- **Tốt nhất cho sử dụng đều** - Nếu dùng 10M/tháng, chỉ $0.90/1M
+- **Reset hàng tháng** - 10M tokens reset hàng tháng
+- **Billing dự đoán được** - Không có chi phí bất ngờ
+
+### Reset Quota
+
+```
+Monthly reset: 1st of each month
+→ 10M tokens refresh
+
+Example monthly usage:
+Week 1: 3M tokens
+Week 2: 2M tokens
+Week 3: 3M tokens
+Week 4: 2M tokens
+Total: 10M tokens = $9 flat
+```
+
+---
+
+## So sánh Giá
+
+| Provider | Input/1M | Output/1M | Reset | Chi phí 10M | Tốt nhất cho |
+|----------|----------|-----------|-------|----------|----------|
+| **GLM-4.7** | $0.60 | $2.20 | Hàng ngày 10AM | $6-22 | Dùng quota hàng ngày |
+| **MiniMax M2.1** | $0.20 | $1.00 | 5 giờ | $2-10 | **Rẻ nhất!** |
+| **Kimi K2** | $0.90 | $0.90 | Hàng tháng | **$9 cố định** | Sử dụng đều |
+| ChatGPT API | $20.00 | $20.00 | Không | $200 | ❌ Đắt |
+
+**Tiết kiệm:** Rẻ hơn ChatGPT API 90-95%!
+
+---
+
+## Ví dụ Sử dụng
+
+### Setup Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: glm/glm-4.7
+```
+
+### Tạo Combo (Khuyên dùng)
+
+```
+Dashboard → Combos → Create New
+
+Name: cheap-backup
+Models:
+  1. cc/claude-opus-4-5 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, daily reset)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback)
+  4. if/kimi-k2-thinking (FREE emergency)
+
+Use in CLI: cheap-backup
+```
+
+**Kết quả:** Subscription → Cheap → Cheapest → Free
+
+---
+
+## Tối ưu Chi phí
+
+### Chiến lược 1: Lịch Reset Hàng ngày
+
+```
+Morning (10AM): Fresh GLM quota
+→ Use GLM for heavy tasks
+→ Save subscription quota
+
+Afternoon: Subscription quota
+→ Use Claude/Codex for complex tasks
+
+Evening: MiniMax (5h reset)
+→ Cheap fallback for late work
+
+Night: Free tier (iFlow)
+→ Zero cost emergency backup
+```
+
+### Chiến lược 2: Ưu tiên Ngân sách
+
+```
+Set monthly budget: $20
+
+Allocation:
+- $9 Kimi K2 (10M tokens flat)
+- $6 GLM daily quota (10M tokens)
+- $5 MiniMax overflow (25M tokens)
+
+Total: 45M tokens for $20
+vs 1M tokens for $20 on ChatGPT API!
+```
+
+### Chiến lược 3: Tối đa Subscription Trước
+
+```
+Priority:
+1. Gemini CLI (180K/month FREE)
+2. Claude Code (subscription you already pay)
+3. GLM-4.7 (cheap backup, $0.6/1M)
+4. MiniMax M2.1 (cheapest, $0.2/1M)
+5. iFlow (FREE emergency)
+
+Monthly cost example (100M tokens):
+- 60M via Gemini CLI: $0 (free)
+- 30M via Claude Code: $0 (subscription)
+- 8M via GLM: $4.80
+- 2M via MiniMax: $0.40
+Total: $5.20/month!
+```
+
+---
+
+## Ví dụ Thực tế
+
+### Ví dụ 1: Tháng Coding Nặng (100M tokens)
+
+```
+Breakdown:
+- 60M via subscription (Claude/Codex): $0 extra
+- 30M via GLM-4.7: $18
+- 10M via MiniMax M2.1: $2
+
+Total: $20/month
+vs $2000 on ChatGPT API!
+
+Savings: 99% cheaper!
+```
+
+### Ví dụ 2: Coder Ngân sách ($10/tháng)
+
+```
+Strategy:
+- $9 Kimi K2 (10M tokens)
+- $1 MiniMax overflow (5M tokens)
+
+Total: 15M tokens for $10
+vs 0.5M tokens for $10 on ChatGPT API!
+
+30× more tokens!
+```
+
+### Ví dụ 3: Freelancer (Usage Biến thiên)
+
+```
+Light month (20M tokens):
+- 15M via subscription: $0
+- 5M via GLM: $3
+Total: $3
+
+Heavy month (150M tokens):
+- 60M via subscription: $0
+- 60M via GLM: $36
+- 30M via MiniMax: $6
+Total: $42
+
+Average: $22.50/month
+vs $3400 on ChatGPT API!
+```
+
+---
+
+## Best Practices
+
+### 1. Theo dõi Quota Hàng ngày
+
+```
+Dashboard shows:
+- GLM quota: 75% used (reset in 6h)
+- MiniMax quota: 50% used (reset in 2h)
+- Kimi quota: 8M/10M used (reset in 15 days)
+
+Plan heavy tasks around reset times!
+```
+
+### 2. Dùng Coding Plan (GLM)
+
+```
+Standard: 1× quota
+Coding Plan: 3× quota (same price!)
+
+→ Always choose Coding Plan
+```
+
+### 3. Kết hợp với Free Tier
+
+```
+Combo:
+1. gc/gemini-3-flash (FREE primary)
+2. glm/glm-4.7 (cheap backup)
+3. minimax/MiniMax-M2.1 (cheapest)
+4. if/kimi-k2-thinking (FREE emergency)
+
+Result: Minimize costs, maximize uptime
+```
+
+### 4. Đặt Cảnh báo Ngân sách
+
+```
+Dashboard → Settings → Budget Alerts
+
+Daily: $2 limit
+Weekly: $10 limit
+Monthly: $30 limit
+
+→ Auto switch to free tier when limit reached
+```
+
+---
+
+## Troubleshooting
+
+### "Quota exhausted"
+
+**Giải pháp:**
+- GLM: Đợi đến 10:00 AM giờ Bắc Kinh
+- MiniMax: Đợi 5 giờ kể từ lần dùng đầu
+- Kimi: Đợi đến ngày 1 tháng sau
+- Dùng combo fallback sang free tier
+
+### "API key invalid"
+
+**Giải pháp:**
+- Kiểm tra API key sao chép đúng
+- Xác minh tài khoản có credits
+- Tạo lại API key nếu cần
+
+### "High costs"
+
+**Giải pháp:**
+- Kiểm tra usage stats trong Dashboard
+- Đặt cảnh báo ngân sách
+- Chuyển sang MiniMax ($0.2/1M rẻ nhất)
+- Dùng free tier cho task không quan trọng
+
+---
+
+## Bước tiếp theo
+
+- **Thêm free fallback:** [Free Providers](./free.md)
+- **Setup subscriptions:** [Subscription Providers](./subscription.md)
+- **Tạo combos:** Dashboard → Combos → Create New
diff --git a/gitbook/content/vi/providers/free.md b/gitbook/content/vi/providers/free.md
new file mode 100644
index 0000000..707ceae
--- /dev/null
+++ b/gitbook/content/vi/providers/free.md
@@ -0,0 +1,442 @@
+# Free Providers - Fallback Chi phí 0
+
+Backup khẩn cấp khi mọi thứ khác bị giới hạn quota. Code 24/7 với chi phí 0!
+
+---
+
+## Tổng quan
+
+Provider free tier là **fallback** khi hết quota subscription và cheap:
+
+- 🆓 **iFlow** - 8 model MIỄN PHÍ (Kimi K2, Qwen3, GLM 4.7, MiniMax M2...)
+- 🆓 **Qwen** - 3 model MIỄN PHÍ (Qwen3 Coder Plus/Flash, Vision)
+- 🆓 **Kiro** - 2 model MIỄN PHÍ (Claude Sonnet 4.5, Haiku 4.5)
+
+**Chiến lược:** Dùng làm backup khẩn cấp. Usage không giới hạn, miễn phí mãi mãi!
+
+---
+
+## iFlow (8 Model MIỄN PHÍ)
+
+### Pricing
+
+| Plan | Chi phí Hàng tháng | Models | Quota |
+|------|--------------|--------|-------|
+| FREE | $0 | 8 models | Không giới hạn |
+
+**Giá trị tốt nhất:** Nhiều model nhất trong free tier! Kimi K2, Qwen3, GLM, MiniMax, DeepSeek.
+
+### Setup
+
+**Bước 1: Kết nối qua Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect iFlow
+```
+
+**Bước 2: Đăng nhập OAuth iFlow**
+
+- Click "Connect iFlow"
+- Browser mở → trang đăng nhập iFlow
+- Tạo tài khoản hoặc đăng nhập
+- Cấp quyền
+- Auto token refresh được bật
+
+**Bước 3: Dùng trong CLI**
+
+```
+Model: if/kimi-k2-thinking
+       if/kimi-k2
+       if/qwen3-coder-plus
+       if/glm-4.7
+       if/minimax-m2
+       if/deepseek-r1
+       if/deepseek-v3.2-chat
+       if/deepseek-v3.2-reasoner
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Tốt nhất cho |
+|----------|-------------|----------|
+| `if/kimi-k2-thinking` | Kimi K2 Thinking | Reasoning phức tạp |
+| `if/kimi-k2` | Kimi K2 | Coding chung |
+| `if/qwen3-coder-plus` | Qwen3 Coder Plus | Tạo code |
+| `if/glm-4.7` | GLM 4.7 | Tiếng Trung + Anh |
+| `if/minimax-m2` | MiniMax M2 | Context dài |
+| `if/deepseek-r1` | DeepSeek R1 | Task reasoning |
+| `if/deepseek-v3.2-chat` | DeepSeek V3.2 Chat | Conversational |
+| `if/deepseek-v3.2-reasoner` | DeepSeek V3.2 Reasoner | Logic phức tạp |
+
+### Mẹo Pro
+
+- **8 model MIỄN PHÍ** - Đa dạng nhất trong free tier
+- **Usage không giới hạn** - Không giới hạn quota
+- **Kimi K2 Thinking** - Tốt nhất cho reasoning phức tạp
+- **DeepSeek R1** - Khả năng reasoning mạnh
+
+---
+
+## Qwen (3 Model MIỄN PHÍ)
+
+### Pricing
+
+| Plan | Chi phí Hàng tháng | Models | Quota |
+|------|--------------|--------|-------|
+| FREE | $0 | 3 models | Không giới hạn |
+
+### Setup
+
+**Bước 1: Kết nối qua Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Qwen
+```
+
+**Bước 2: Xác thực Device Code**
+
+- Click "Connect Qwen"
+- Dashboard hiển thị device code
+- Vào URL xác thực
+- Nhập device code
+- Đăng nhập tài khoản Qwen
+- Auto token refresh được bật
+
+**Bước 3: Dùng trong CLI**
+
+```
+Model: qw/qwen3-coder-plus
+       qw/qwen3-coder-flash
+       qw/vision-model
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Tốt nhất cho |
+|----------|-------------|----------|
+| `qw/qwen3-coder-plus` | Qwen3 Coder Plus | Coding nâng cao |
+| `qw/qwen3-coder-flash` | Qwen3 Coder Flash | Phản hồi nhanh |
+| `qw/vision-model` | Qwen3 Vision | Phân tích ảnh |
+
+### Mẹo Pro
+
+- **Qwen3 Coder Plus** - Khả năng coding mạnh
+- **Qwen3 Coder Flash** - Nhanh cho task nhanh
+- **Vision model** - Phân tích ảnh MIỄN PHÍ
+- **Usage không giới hạn** - Không giới hạn quota
+
+---
+
+## Kiro (Claude MIỄN PHÍ)
+
+### Pricing
+
+| Plan | Chi phí Hàng tháng | Models | Quota |
+|------|--------------|--------|-------|
+| FREE | $0 | Claude Sonnet 4.5, Haiku 4.5 | Không giới hạn |
+
+**Giá trị tốt nhất:** Claude MIỄN PHÍ! Cùng chất lượng với Claude Code trả phí.
+
+### Setup
+
+**Bước 1: Kết nối qua Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Kiro
+```
+
+**Bước 2: AWS Builder ID hoặc OAuth**
+
+- Click "Connect Kiro"
+- Chọn phương thức đăng nhập:
+  - AWS Builder ID (khuyên dùng)
+  - Tài khoản Google
+  - Tài khoản GitHub
+- Cấp quyền
+- Auto token refresh được bật
+
+**Bước 3: Dùng trong CLI**
+
+```
+Model: kr/claude-sonnet-4.5
+       kr/claude-haiku-4.5
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Tốt nhất cho |
+|----------|-------------|----------|
+| `kr/claude-sonnet-4.5` | Claude Sonnet 4.5 | Cân bằng chất lượng/tốc độ |
+| `kr/claude-haiku-4.5` | Claude Haiku 4.5 | Phản hồi nhanh |
+
+### Mẹo Pro
+
+- **Claude MIỄN PHÍ** - Cùng chất lượng tier trả phí
+- **AWS Builder ID** - Setup dễ với tài khoản AWS
+- **Usage không giới hạn** - Không giới hạn quota
+- **Chất lượng tốt nhất** - Claude 4.5 miễn phí!
+
+---
+
+## So sánh Tính năng
+
+| Provider | Models | Model tốt nhất | Setup | Quota |
+|----------|--------|------------|-------|-------|
+| **iFlow** | 8 | Kimi K2 Thinking | OAuth | Không giới hạn |
+| **Qwen** | 3 | Qwen3 Coder Plus | Device Code | Không giới hạn |
+| **Kiro** | 2 | Claude Sonnet 4.5 | AWS Builder ID | Không giới hạn |
+
+**Thắng cuộc:** iFlow vì đa dạng, Kiro vì chất lượng!
+
+---
+
+## Ví dụ Sử dụng
+
+### Setup Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: if/kimi-k2-thinking
+```
+
+### Tạo Combo (Khuyên dùng)
+
+```
+Dashboard → Combos → Create New
+
+Name: free-combo
+Models:
+  1. if/kimi-k2-thinking (iFlow primary)
+  2. qw/qwen3-coder-plus (Qwen backup)
+  3. kr/claude-sonnet-4.5 (Kiro quality)
+
+Use in CLI: free-combo
+```
+
+**Kết quả:** Chi phí 0, uptime tối đa!
+
+---
+
+## Chiến lược Fallback Đầy đủ
+
+### Combo 3 Tầng Hoàn chỉnh
+
+```
+Dashboard → Combos → Create New
+
+Name: complete-fallback
+Models:
+  1. gc/gemini-3-flash-preview (FREE subscription)
+  2. cc/claude-opus-4-5 (Paid subscription)
+  3. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  4. minimax/MiniMax-M2.1 (Cheapest, $0.2/1M)
+  5. if/kimi-k2-thinking (FREE fallback)
+  6. kr/claude-sonnet-4.5 (FREE quality)
+
+Use in CLI: complete-fallback
+```
+
+**Kết quả:**
+- Tier 1: Subscription MIỄN PHÍ (Gemini CLI)
+- Tier 2: Subscription trả phí (Claude Code)
+- Tier 3: Backup rẻ (GLM, MiniMax)
+- Tier 4: Fallback MIỄN PHÍ (iFlow, Kiro)
+
+**Không bao giờ ngừng code!**
+
+---
+
+## Best Practices
+
+### 1. Dùng làm Backup Khẩn cấp
+
+```
+Priority:
+1. Subscription tier (maximize paid quota)
+2. Cheap tier (pennies per 1M tokens)
+3. FREE tier (unlimited, zero cost)
+
+Only use free tier when:
+- Subscription quota exhausted
+- Budget limit reached
+- Testing/non-critical tasks
+```
+
+### 2. Chọn Model phù hợp
+
+```
+Complex reasoning: if/kimi-k2-thinking
+Fast coding: qw/qwen3-coder-flash
+Best quality: kr/claude-sonnet-4.5
+Long context: if/minimax-m2
+Vision tasks: qw/vision-model
+```
+
+### 3. Tạo Combo Chỉ Free
+
+```
+For zero-cost coding:
+
+Name: zero-cost
+Models:
+  1. kr/claude-sonnet-4.5 (Best quality)
+  2. if/kimi-k2-thinking (Complex tasks)
+  3. qw/qwen3-coder-plus (Fast coding)
+
+Cost: $0 forever!
+```
+
+### 4. Test Trước Production
+
+```
+Use free tier to:
+- Test prompts
+- Prototype features
+- Learn new frameworks
+- Non-critical tasks
+
+Save paid quota for:
+- Production code
+- Complex refactoring
+- Critical features
+```
+
+---
+
+## Ví dụ Thực tế
+
+### Ví dụ 1: Sinh viên/Người học (Ngân sách 0)
+
+```
+Setup:
+1. kr/claude-sonnet-4.5 (Best quality)
+2. if/kimi-k2-thinking (Complex reasoning)
+3. qw/qwen3-coder-plus (Fast coding)
+
+Monthly cost: $0
+Usage: Unlimited
+
+Perfect for:
+- Learning to code
+- Personal projects
+- Homework/assignments
+```
+
+### Ví dụ 2: Freelancer (Tiết kiệm Ngân sách)
+
+```
+Setup:
+1. gc/gemini-3-flash-preview (FREE 180K/month)
+2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+3. if/kimi-k2-thinking (FREE fallback)
+
+Monthly cost: $5-10
+Usage: 100M+ tokens
+
+Perfect for:
+- Client projects (paid tier)
+- Testing (free tier)
+- Emergency backup
+```
+
+### Ví dụ 3: Heavy User (Tối đa hết tất cả)
+
+```
+Setup:
+1. gc/gemini-3-flash-preview (FREE 180K/month)
+2. cc/claude-opus-4-5 (Subscription $20-100)
+3. cx/gpt-5.2-codex (Subscription $20-200)
+4. glm/glm-4.7 (Cheap $0.6/1M)
+5. minimax/MiniMax-M2.1 (Cheapest $0.2/1M)
+6. if/kimi-k2-thinking (FREE unlimited)
+7. kr/claude-sonnet-4.5 (FREE quality)
+
+Monthly cost: $40-320 (subscriptions) + $10-20 (cheap tier)
+Usage: 500M+ tokens
+
+Perfect for:
+- Professional development
+- Team projects
+- 24/7 coding
+```
+
+---
+
+## So sánh Chi phí
+
+### Kịch bản: 100M tokens/tháng
+
+**Phương án 1: Chỉ ChatGPT API**
+```
+100M × $20/1M = $2,000/month
+```
+
+**Phương án 2: Chỉ 9Router Free Tier**
+```
+100M via free tier = $0/month
+Savings: $2,000/month (100%)
+```
+
+**Phương án 3: Chiến lược Hoàn chỉnh 9Router**
+```
+60M via Gemini CLI (FREE): $0
+30M via Claude Code (subscription): $0 extra
+8M via GLM (cheap): $4.80
+2M via iFlow (FREE): $0
+Total: $4.80/month + subscriptions you already have
+Savings: $1,995/month (99.76%)
+```
+
+---
+
+## Troubleshooting
+
+### "OAuth failed"
+
+**Giải pháp:**
+- Kiểm tra kết nối internet
+- Thử browser khác
+- Xóa cache browser
+- Kết nối lại trong dashboard
+
+### "Model not available"
+
+**Giải pháp:**
+- Kiểm tra provider đã kết nối trong dashboard
+- Xác minh OAuth token hợp lệ
+- Kết nối lại provider nếu cần
+
+### "Slow responses"
+
+**Giải pháp:**
+- Free tier có thể có ưu tiên thấp hơn
+- Dùng trong giờ thấp điểm
+- Chuyển sang free provider khác
+- Nâng cấp lên cheap tier để tăng tốc
+
+---
+
+## Giới hạn
+
+### Cân nhắc Free Tier
+
+- **Tốc độ** - Có thể chậm hơn tier trả phí
+- **Ưu tiên** - Ưu tiên thấp hơn trong giờ cao điểm
+- **Rate limit** - Có thể bị rate limit (nhưng không giới hạn quota)
+- **Tính khả dụng** - Có thể có downtime thỉnh thoảng
+
+**Giải pháp:** Dùng chiến lược fallback 3 tầng để đáng tin cậy!
+
+---
+
+## Bước tiếp theo
+
+- **Setup subscriptions:** [Subscription Providers](./subscription.md)
+- **Thêm cheap backup:** [Cheap Providers](./cheap.md)
+- **Tạo combos:** Dashboard → Combos → Create New
+- **Bắt đầu code:** Dùng combo `complete-fallback` để có độ tin cậy tối đa
diff --git a/gitbook/content/vi/providers/subscription.md b/gitbook/content/vi/providers/subscription.md
new file mode 100644
index 0000000..4cdbdfd
--- /dev/null
+++ b/gitbook/content/vi/providers/subscription.md
@@ -0,0 +1,404 @@
+# Subscription Providers - Tối đa hóa Giá trị
+
+Tối đa hóa subscription AI hiện có với quota tracking thông minh và auto fallback. Dùng hết mọi quota subscription trước khi reset!
+
+---
+
+## Tổng quan
+
+Provider tier subscription là lựa chọn **chính** - bạn đã trả tiền cho chúng, hãy lấy đầy đủ giá trị:
+
+- ✅ **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
+- ✅ **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
+- ✅ **Gemini CLI** (Free tier!) - 180K completions/tháng
+- ✅ **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
+- ✅ **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
+
+**Chiến lược:** Dùng đầu tiên, theo dõi quota thời gian thực, fallback sang cheap/free khi hết.
+
+---
+
+## Claude Code (Pro/Max)
+
+### Pricing
+
+| Plan | Chi phí Hàng tháng | Quota Reset | Models |
+|------|--------------|-------------|--------|
+| Pro | $20 | 5 giờ + Hàng tuần | Opus, Sonnet, Haiku |
+| Max | $100 | 5 giờ + Hàng tuần | Opus, Sonnet, Haiku |
+
+### Setup
+
+**Bước 1: Kết nối qua Dashboard**
+
+```bash
+9router
+# Dashboard opens → Providers → Connect Claude Code
+```
+
+**Bước 2: Đăng nhập OAuth**
+
+- Click "Connect Claude Code"
+- Browser mở → Đăng nhập Claude.ai
+- Auto token refresh được bật
+- Quota tracking bắt đầu
+
+**Bước 3: Dùng trong CLI**
+
+```
+Model: cc/claude-opus-4-5-20251101
+       cc/claude-sonnet-4-5-20250929
+       cc/claude-haiku-4-5-20251001
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Tốt nhất cho |
+|----------|-------------|----------|
+| `cc/claude-opus-4-5-20251101` | Claude 4.5 Opus | Task phức tạp, kiến trúc |
+| `cc/claude-sonnet-4-5-20250929` | Claude 4.5 Sonnet | Cân bằng tốc độ/chất lượng |
+| `cc/claude-haiku-4-5-20251001` | Claude 4.5 Haiku | Phản hồi nhanh |
+
+### Mẹo Pro
+
+- **Dùng Opus cho task phức tạp** - Quyết định kiến trúc, refactoring
+- **Dùng Sonnet cho tốc độ** - Edit nhanh, tạo code
+- **Theo dõi quota mỗi model** - Dashboard hiển thị usage mỗi model
+- **Reset 5 giờ** - Quota mới mỗi 5 giờ + reset hàng tuần
+
+---
+
+## OpenAI Codex (Plus/Pro)
+
+### Pricing
+
+| Plan | Chi phí Hàng tháng | Quota Reset | Models |
+|------|--------------|-------------|--------|
+| Plus | $20 | 5 giờ + Hàng tuần | GPT 5.2, GPT 5.1 |
+| Pro | $200 | 5 giờ + Hàng tuần | GPT 5.2 Codex, GPT 5.1 Max |
+
+### Setup
+
+**Bước 1: Kết nối qua Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Codex
+```
+
+**Bước 2: Đăng nhập OAuth**
+
+- Click "Connect Codex"
+- Browser mở đến `http://localhost:1455`
+- Đăng nhập tài khoản OpenAI
+- Auto token refresh được bật
+
+**Bước 3: Dùng trong CLI**
+
+```
+Model: cx/gpt-5.2-codex
+       cx/gpt-5.1-codex-max
+       cx/gpt-5.2
+       cx/gpt-5.1-codex
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Tốt nhất cho |
+|----------|-------------|----------|
+| `cx/gpt-5.2-codex` | GPT 5.2 Codex | Model coding mới nhất |
+| `cx/gpt-5.1-codex-max` | GPT 5.1 Codex Max | Context tối đa |
+| `cx/gpt-5.2` | GPT 5.2 | Task chung |
+| `cx/gpt-5.1-codex` | GPT 5.1 Codex | Coding ổn định |
+
+### Mẹo Pro
+
+- **Quota rolling 5 giờ** - Quota mới mỗi 5 giờ
+- **Reset hàng tuần** - Reset quota đầy đủ hàng tuần
+- **Tier Pro** - Quota gấp 10× Plus
+
+---
+
+## Gemini CLI (MIỄN PHÍ 180K/tháng!)
+
+### Pricing
+
+| Plan | Chi phí Hàng tháng | Quota | Reset |
+|------|--------------|-------|-------|
+| FREE | $0 | 180K completions/tháng + 1K/ngày | Hàng ngày + Hàng tháng |
+
+**Giá trị tốt nhất:** Free tier khổng lồ! Dùng trước tier trả phí.
+
+### Setup
+
+**Bước 1: Kết nối qua Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Gemini CLI
+```
+
+**Bước 2: Google OAuth**
+
+- Click "Connect Gemini CLI"
+- Browser mở → Đăng nhập tài khoản Google
+- Cấp quyền
+- Auto token refresh được bật
+
+**Bước 3: Dùng trong CLI**
+
+```
+Model: gc/gemini-3-flash-preview
+       gc/gemini-3-pro-preview
+       gc/gemini-2.5-pro
+       gc/gemini-2.5-flash
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Tốt nhất cho |
+|----------|-------------|----------|
+| `gc/gemini-3-flash-preview` | Gemini 3 Flash Preview | Phản hồi nhanh |
+| `gc/gemini-3-pro-preview` | Gemini 3 Pro Preview | Task phức tạp |
+| `gc/gemini-2.5-pro` | Gemini 2.5 Pro | Production ổn định |
+| `gc/gemini-2.5-flash` | Gemini 2.5 Flash | Task nhanh |
+
+### Mẹo Pro
+
+- **180K completions/tháng** - Free tier khổng lồ
+- **Giới hạn 1K/ngày** - Quota hàng ngày reset lúc nửa đêm
+- **Dùng đầu tiên** - Free tier, dùng trước subscription trả phí
+- **Không cần thẻ tín dụng** - Hoàn toàn miễn phí với tài khoản Google
+
+---
+
+## GitHub Copilot
+
+### Pricing
+
+| Plan | Chi phí Hàng tháng | Quota Reset | Models |
+|------|--------------|-------------|--------|
+| Individual | $10 | Hàng tháng (ngày 1) | GPT-5, Claude 4.5, Gemini 3 |
+| Business | $19 | Hàng tháng (ngày 1) | GPT-5, Claude 4.5, Gemini 3 |
+
+### Setup
+
+**Bước 1: Kết nối qua Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect GitHub
+```
+
+**Bước 2: OAuth qua GitHub**
+
+- Click "Connect GitHub"
+- Browser mở → Đăng nhập GitHub
+- Authorize GitHub Copilot
+- Auto token refresh được bật
+
+**Bước 3: Dùng trong CLI**
+
+```
+Model: gh/gpt-5
+       gh/gpt-5.1-codex-max
+       gh/claude-4.5-sonnet
+       gh/gemini-3-pro
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Tốt nhất cho |
+|----------|-------------|----------|
+| `gh/gpt-5` | GPT-5 | Model OpenAI mới nhất |
+| `gh/gpt-5.1-codex-max` | GPT-5.1 Codex Max | Context tối đa |
+| `gh/claude-4.5-sonnet` | Claude 4.5 Sonnet | Chất lượng Anthropic |
+| `gh/gemini-3-pro` | Gemini 3 Pro | Chất lượng Google |
+
+### Mẹo Pro
+
+- **Reset hàng tháng** - Reset quota đầy đủ vào ngày 1 hàng tháng
+- **Nhiều model** - Truy cập GPT, Claude, Gemini trong một subscription
+- **Tier Business** - Quota cao hơn cho team
+
+---
+
+## Antigravity (Tài khoản Google)
+
+### Pricing
+
+| Plan | Chi phí Hàng tháng | Quota | Models |
+|------|--------------|-------|--------|
+| FREE | $0 | Tương tự Gemini CLI | Gemini 3 Pro, Claude Sonnet 4.5 |
+
+### Setup
+
+**Bước 1: Kết nối qua Dashboard**
+
+```bash
+9router
+# Dashboard → Providers → Connect Antigravity
+```
+
+**Bước 2: Google OAuth**
+
+- Click "Connect Antigravity"
+- Browser mở → Đăng nhập tài khoản Google
+- Cấp quyền
+- Auto token refresh được bật
+
+**Bước 3: Dùng trong CLI**
+
+```
+Model: ag/gemini-3-pro-high
+       ag/claude-sonnet-4-5
+       ag/claude-opus-4-5-thinking
+```
+
+### Model có sẵn
+
+| Model ID | Mô tả | Tốt nhất cho |
+|----------|-------------|----------|
+| `ag/gemini-3-pro-high` | Gemini 3 Pro High | Phản hồi chất lượng cao |
+| `ag/claude-sonnet-4-5` | Claude Sonnet 4.5 | Chất lượng Anthropic |
+| `ag/claude-opus-4-5-thinking` | Claude Opus 4.5 Thinking | Reasoning phức tạp |
+
+### Mẹo Pro
+
+- **Free tier** - Không phí với tài khoản Google
+- **Truy cập Claude** - Claude Sonnet/Opus miễn phí
+- **Quota tương tự Gemini CLI** - Giới hạn hàng ngày/tháng
+
+---
+
+## So sánh Giá
+
+| Provider | Chi phí Hàng tháng | Quota Reset | Giá trị |
+|----------|--------------|-------------|-------|
+| **Claude Code Pro** | $20 | 5 giờ + Hàng tuần | ⭐⭐⭐⭐⭐ Chất lượng tốt nhất |
+| **Claude Code Max** | $100 | 5 giờ + Hàng tuần | ⭐⭐⭐⭐⭐ Quota cao nhất |
+| **Codex Plus** | $20 | 5 giờ + Hàng tuần | ⭐⭐⭐⭐ Giá trị tốt |
+| **Codex Pro** | $200 | 5 giờ + Hàng tuần | ⭐⭐⭐⭐⭐ Quota 10× |
+| **Gemini CLI** | **$0** | Hàng ngày + Hàng tháng | ⭐⭐⭐⭐⭐ MIỄN PHÍ 180K/tháng! |
+| **GitHub Copilot** | $10-19 | Hàng tháng (ngày 1) | ⭐⭐⭐⭐ Đa model |
+| **Antigravity** | **$0** | Hàng ngày + Hàng tháng | ⭐⭐⭐⭐ Claude MIỄN PHÍ! |
+
+---
+
+## Ví dụ Sử dụng
+
+### Setup Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Tạo Combo (Khuyên dùng)
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. gc/gemini-3-flash-preview (FREE, use first)
+  2. cc/claude-opus-4-5-20251101 (Subscription)
+  3. cx/gpt-5.2-codex (Subscription backup)
+
+Use in CLI: premium-coding
+```
+
+**Kết quả:** Tối đa free tier → Dùng subscription → Auto fallback
+
+---
+
+## Quota Tracking
+
+9Router theo dõi quota thời gian thực:
+
+- **Tiêu thụ token** - Tokens input/output mỗi request
+- **Đếm ngược reset** - Thời gian đến lần reset tiếp theo
+- **Phần trăm usage** - Đã dùng bao nhiêu quota
+- **Auto fallback** - Chuyển sang tier sau khi hết
+
+**Dashboard view:**
+
+```
+Claude Code Pro
+├─ Quota: 75% used
+├─ Reset: 2h 15m (5-hour)
+├─ Weekly reset: 3 days
+└─ Fallback: glm/glm-4.7 (cheap tier)
+```
+
+---
+
+## Best Practices
+
+### 1. Dùng Free Tier Trước
+
+```
+Priority:
+1. Gemini CLI (180K/month FREE)
+2. Antigravity (FREE Claude)
+3. Claude Code/Codex (paid subscriptions)
+```
+
+### 2. Theo dõi Quota Hàng ngày
+
+- Kiểm tra dashboard mỗi sáng
+- Lên kế hoạch task nặng quanh thời gian reset quota
+- Dùng cheap/free tier cho task không quan trọng
+
+### 3. Tạo Smart Combos
+
+```
+Example combo:
+1. gc/gemini-3-flash-preview (FREE primary)
+2. cc/claude-opus-4-5 (Complex tasks)
+3. glm/glm-4.7 (Cheap backup)
+4. if/kimi-k2-thinking (FREE fallback)
+```
+
+### 4. Tối ưu theo Thời gian
+
+```
+Morning: Fresh 5-hour quota (Claude/Codex)
+Afternoon: Gemini CLI (1K/day)
+Evening: Subscription quota
+Night: Cheap/free tier
+```
+
+---
+
+## Troubleshooting
+
+### "Quota exhausted"
+
+**Giải pháp:**
+- Kiểm tra quota tracker trong dashboard
+- Đợi reset (5 giờ hoặc hàng ngày)
+- Dùng combo fallback sang cheap/free tier
+
+### "OAuth token expired"
+
+**Giải pháp:**
+- Auto-refresh bởi 9Router
+- Nếu vẫn lỗi: Dashboard → Provider → Reconnect
+
+### "Rate limiting"
+
+**Giải pháp:**
+- Hết quota subscription
+- Thêm fallback: `cc/claude-opus → glm/glm-4.7`
+- Dùng free tier: `if/kimi-k2-thinking`
+
+---
+
+## Bước tiếp theo
+
+- **Setup cheap backup:** [Cheap Providers](./cheap.md)
+- **Thêm free fallback:** [Free Providers](./free.md)
+- **Tạo combos:** Dashboard → Combos → Create New
diff --git a/gitbook/content/vi/troubleshooting.md b/gitbook/content/vi/troubleshooting.md
new file mode 100644
index 0000000..7ae6cf3
--- /dev/null
+++ b/gitbook/content/vi/troubleshooting.md
@@ -0,0 +1,351 @@
+# Troubleshooting
+
+Các vấn đề và giải pháp phổ biến khi dùng 9Router.
+
+---
+
+## "Language model did not provide messages"
+
+**Vấn đề:** Request thất bại với phản hồi rỗng hoặc thông báo lỗi.
+
+**Nguyên nhân:**
+- Hết quota provider
+- API key không hợp lệ hoặc hết hạn
+- Model không khả dụng
+
+**Giải pháp:**
+
+1. **Kiểm tra trạng thái quota:**
+   ```
+   Dashboard → Providers → View quota tracker
+   ```
+   Nếu hết quota, đợi reset hoặc đổi provider.
+
+2. **Dùng fallback combo:**
+   ```
+   Dashboard → Combos → Create fallback chain
+   Example: cc/claude-opus → glm/glm-4.7 → if/kimi-k2
+   ```
+
+3. **Xác minh kết nối provider:**
+   ```
+   Dashboard → Providers → Reconnect if needed
+   ```
+
+---
+
+## Rate Limiting
+
+**Vấn đề:** Lỗi "Rate limit exceeded" hoặc "Too many requests".
+
+**Nguyên nhân:**
+- Hết quota subscription (giới hạn 5h/ngày/tuần)
+- Đạt API rate limit
+- Quá nhiều request đồng thời
+
+**Giải pháp:**
+
+1. **Kiểm tra thời gian reset:**
+   ```
+   Dashboard → Quota Tracking → View reset countdown
+   ```
+
+2. **Chuyển sang tier rẻ:**
+   ```
+   Use: glm/glm-4.7 ($0.6/1M tokens)
+        minimax/MiniMax-M2.1 ($0.20/1M tokens)
+   ```
+
+3. **Thêm fallback combo:**
+   ```
+   Dashboard → Combos → Add backup models
+   Primary: cc/claude-opus (subscription)
+   Backup: glm/glm-4.7 (cheap)
+   Emergency: if/kimi-k2 (free)
+   ```
+
+---
+
+## OAuth Token hết hạn
+
+**Vấn đề:** Lỗi "Unauthorized" hoặc "Token expired".
+
+**Nguyên nhân:**
+- OAuth token hết hạn (auto-refresh thất bại)
+- Session provider không hợp lệ
+- Vấn đề network khi refresh
+
+**Giải pháp:**
+
+1. **Auto-refresh (mặc định):**
+   9Router tự refresh tokens. Đợi 30 giây rồi thử lại.
+
+2. **Kết nối lại thủ công:**
+   ```
+   Dashboard → Providers → [Provider Name] → Reconnect
+   → Complete OAuth flow again
+   ```
+
+3. **Kiểm tra trạng thái provider:**
+   Xác minh provider service đang online (Claude Code, Codex, v.v.)
+
+---
+
+## Chi phí cao
+
+**Vấn đề:** Sử dụng hoặc chi phí cao bất ngờ.
+
+**Nguyên nhân:**
+- Dùng model đắt không cần thiết
+- Không fallback sang tier rẻ hơn
+- Context window lớn
+
+**Giải pháp:**
+
+1. **Kiểm tra usage stats:**
+   ```
+   Dashboard → Usage Stats → View token consumption
+   → Identify high-cost models
+   ```
+
+2. **Chuyển sang model rẻ hơn:**
+   ```
+   Replace: cc/claude-opus ($20-100/month subscription)
+   With: glm/glm-4.7 ($0.6/1M tokens)
+         minimax/MiniMax-M2.1 ($0.20/1M tokens)
+   ```
+
+3. **Dùng free tier:**
+   ```
+   if/kimi-k2-thinking (FREE)
+   qw/qwen3-coder-plus (FREE)
+   kr/claude-sonnet-4.5 (FREE)
+   gc/gemini-3-flash-preview (FREE 180K/month)
+   ```
+
+4. **Tối ưu prompt:**
+   - Giảm context size
+   - Dùng streaming cho phản hồi dài
+   - Cache prompt thường dùng
+
+---
+
+## Connection Refused
+
+**Vấn đề:** Lỗi "ECONNREFUSED" hoặc "Cannot connect to localhost:20128".
+
+**Nguyên nhân:**
+- 9Router không chạy
+- Port 20128 bị chặn
+- Firewall chặn kết nối
+
+**Giải pháp:**
+
+1. **Khởi động 9Router:**
+   ```bash
+   9router
+   ```
+   Dashboard sẽ mở tại http://localhost:3000
+
+2. **Xác minh port 20128:**
+   ```bash
+   # Check if port is listening
+   lsof -i :20128
+   
+   # Or on Windows
+   netstat -ano | findstr :20128
+   ```
+
+3. **Kiểm tra firewall:**
+   - macOS: System Settings → Network → Firewall
+   - Windows: Windows Defender Firewall → Allow app
+   - Linux: `sudo ufw allow 20128`
+
+4. **Dùng cloud endpoint:**
+   Nếu localhost không hoạt động (ví dụ: Cursor IDE):
+   ```
+   Endpoint: https://9router.com/v1
+   ```
+
+---
+
+## Dashboard không mở
+
+**Vấn đề:** Dashboard không load tại http://localhost:3000.
+
+**Nguyên nhân:**
+- Port 3000 đã được dùng
+- 9Router bị crash
+- Vấn đề cache browser
+
+**Giải pháp:**
+
+1. **Kiểm tra 9Router có chạy không:**
+   ```bash
+   # Check process
+   ps aux | grep 9router
+   
+   # Check port 3000
+   lsof -i :3000
+   ```
+
+2. **Kill process xung đột:**
+   ```bash
+   # macOS/Linux
+   lsof -ti:3000 | xargs kill -9
+   
+   # Windows
+   netstat -ano | findstr :3000
+   taskkill /PID <PID> /F
+   ```
+
+3. **Khởi động lại 9Router:**
+   ```bash
+   # Stop
+   pkill -f 9router
+   
+   # Start
+   9router
+   ```
+
+4. **Xóa cache browser:**
+   - Chrome: Ctrl+Shift+Delete → Clear cache
+   - Thử chế độ ẩn danh
+
+5. **Kiểm tra cài đặt firewall:**
+   Đảm bảo port 3000 không bị chặn.
+
+---
+
+## Model Not Found
+
+**Vấn đề:** Lỗi "Model not found" hoặc "Invalid model".
+
+**Nguyên nhân:**
+- Provider chưa kết nối
+- Sai chính tả model ID
+- Provider không hoạt động
+
+**Giải pháp:**
+
+1. **Xác minh kết nối provider:**
+   ```
+   Dashboard → Providers → Check status (green = active)
+   ```
+
+2. **Kiểm tra format model ID:**
+   ```
+   Correct: cc/claude-opus-4-5-20251101
+   Wrong: claude-opus-4-5-20251101
+   
+   Format: [provider-prefix]/[model-name]
+   ```
+
+3. **Liệt kê model khả dụng:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer your-api-key"
+   ```
+
+4. **Kết nối lại provider:**
+   ```
+   Dashboard → Providers → [Provider] → Reconnect
+   ```
+
+---
+
+## Phản hồi chậm
+
+**Vấn đề:** Request mất quá lâu hoặc timeout.
+
+**Nguyên nhân:**
+- Độ trễ provider
+- Vấn đề network
+- Context/response lớn
+- Provider rate limiting
+
+**Giải pháp:**
+
+1. **Kiểm tra trạng thái provider:**
+   ```
+   Dashboard → Providers → View latency stats
+   ```
+
+2. **Chuyển sang model nhanh hơn:**
+   ```
+   Fast: cc/claude-haiku-4-5 (Haiku is faster than Opus)
+         gc/gemini-3-flash-preview
+         qw/qwen3-coder-flash
+   ```
+
+3. **Dùng streaming:**
+   ```json
+   {
+     "model": "cc/claude-opus-4-5",
+     "messages": [...],
+     "stream": true
+   }
+   ```
+
+4. **Kiểm tra network:**
+   ```bash
+   # Test latency
+   ping api.anthropic.com
+   ping api.openai.com
+   ```
+
+5. **Giảm context size:**
+   - Cắt bớt lịch sử tin nhắn
+   - Dùng prompt nhỏ hơn
+   - Bật context pruning trong CLI tool
+
+---
+
+## API Key không hợp lệ
+
+**Vấn đề:** Lỗi "Invalid API key" hoặc "Authentication failed".
+
+**Nguyên nhân:**
+- Sao chép sai API key
+- API key hết hạn
+- API key chưa được tạo
+
+**Giải pháp:**
+
+1. **Tạo lại API key:**
+   ```
+   Dashboard → Settings → API Keys → Generate New Key
+   → Copy and use new key
+   ```
+
+2. **Xác minh format key:**
+   ```
+   Correct: 9r_xxxxxxxxxxxxxxxxxxxxxxxx
+   Wrong: Missing 9r_ prefix
+   ```
+
+3. **Kiểm tra key trong CLI config:**
+   ```bash
+   # Cursor
+   Settings → Models → OpenAI API Key
+   
+   # Cline
+   Settings → API Key
+   
+   # Environment variable
+   export OPENAI_API_KEY="9r_your_key"
+   ```
+
+4. **Test API key:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer 9r_your_key"
+   ```
+
+---
+
+## Cần trợ giúp thêm?
+
+- **GitHub Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **Documentation:** [9router.com/docs](https://9router.com/docs)
+- **FAQ:** [faq.md](faq.md)
diff --git a/gitbook/content/zh-CN/deployment/cloud.md b/gitbook/content/zh-CN/deployment/cloud.md
new file mode 100644
index 0000000..6762f66
--- /dev/null
+++ b/gitbook/content/zh-CN/deployment/cloud.md
@@ -0,0 +1,473 @@
+# ☁️ 云端部署
+
+将 9Router 部署到 VPS 或 Docker,实现远程访问和生产使用。
+
+---
+
+## 🖥️ VPS 部署
+
+### 前置要求
+
+- Ubuntu 20.04+ 或类似 Linux 发行版
+- Node.js 20+
+- Git
+- root 或 sudo 权限
+
+### 步骤 1:克隆仓库
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+```
+
+### 步骤 2:安装依赖
+
+```bash
+npm install
+```
+
+### 步骤 3:构建应用
+
+```bash
+npm run build
+```
+
+### 步骤 4:配置环境变量
+
+创建 `.env` 文件或导出变量:
+
+```bash
+export JWT_SECRET="your-secure-secret-change-this-to-random-string"
+export INITIAL_PASSWORD="your-secure-password"
+export DATA_DIR="/var/lib/9router"
+export NODE_ENV="production"
+```
+
+**环境变量:**
+
+| 变量 | 默认值 | 说明 |
+|----------|---------|-------------|
+| `JWT_SECRET` | 自动生成 | **生产环境必须修改!** 用于 JWT token 签名 |
+| `INITIAL_PASSWORD` | `123456` | 仪表盘登录密码 |
+| `DATA_DIR` | `~/.9router` | 数据库与数据存储路径 |
+| `NODE_ENV` | `development` | 部署时设为 `production` |
+| `ENABLE_REQUEST_LOGS` | `false` | 启用 debug 请求/响应日志 |
+
+### 步骤 5:创建数据目录
+
+```bash
+sudo mkdir -p /var/lib/9router
+sudo chown $USER:$USER /var/lib/9router
+```
+
+### 步骤 6:启动应用
+
+```bash
+npm run start
+```
+
+### 步骤 7:用 PM2 部署到生产环境
+
+PM2 让应用持续运行,崩溃时自动重启:
+
+```bash
+# 全局安装 PM2
+npm install -g pm2
+
+# 用 PM2 启动 9Router
+pm2 start npm --name 9router -- start
+
+# 保存 PM2 配置
+pm2 save
+
+# 设置开机自启
+pm2 startup
+# 按上一条命令打印的提示执行
+```
+
+**PM2 管理命令:**
+
+```bash
+# 查看日志
+pm2 logs 9router
+
+# 重启应用
+pm2 restart 9router
+
+# 停止应用
+pm2 stop 9router
+
+# 查看状态
+pm2 status
+
+# 监控资源
+pm2 monit
+```
+
+---
+
+## 🐳 Docker 部署
+
+### 方式 1:使用 Dockerfile
+
+在 `app` 目录中创建 `Dockerfile`:
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy application files
+COPY . .
+
+# Build application
+RUN npm run build
+
+# Expose ports
+EXPOSE 3000 20128
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV DATA_DIR=/app/data
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Start application
+CMD ["npm", "run", "start"]
+```
+
+**构建并运行:**
+
+```bash
+# 构建镜像
+docker build -t 9router .
+
+# 运行容器
+docker run -d \
+  --name 9router \
+  -p 3000:3000 \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret-change-this" \
+  -e INITIAL_PASSWORD="your-secure-password" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### 方式 2:Docker Compose
+
+创建 `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  9router:
+    build: .
+    container_name: 9router
+    ports:
+      - "3000:3000"
+      - "20128:20128"
+    environment:
+      - NODE_ENV=production
+      - JWT_SECRET=your-secure-secret-change-this
+      - INITIAL_PASSWORD=your-secure-password
+      - DATA_DIR=/app/data
+    volumes:
+      - 9router-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  9router-data:
+```
+
+**使用 Docker Compose 运行:**
+
+```bash
+# 启动服务
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f
+
+# 停止服务
+docker-compose down
+
+# 重新构建并重启
+docker-compose up -d --build
+```
+
+---
+
+## 🌐 Nginx 反向代理
+
+### 为什么使用 Nginx?
+
+- SSL/TLS 终止
+- 域名映射
+- 负载均衡
+- 更好的安全性
+
+### 步骤 1:安装 Nginx
+
+```bash
+sudo apt update
+sudo apt install nginx
+```
+
+### 步骤 2:配置 Nginx
+
+创建 `/etc/nginx/sites-available/9router`:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    # SSL certificates (use certbot to generate)
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    # SSL configuration
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # Proxy to 9Router
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+
+    # API endpoint
+    location /v1 {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+### 步骤 3:启用站点
+
+```bash
+# 创建软链接
+sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/
+
+# 测试配置
+sudo nginx -t
+
+# 重新加载 Nginx
+sudo systemctl reload nginx
+```
+
+### 步骤 4:使用 Let's Encrypt 配置 SSL
+
+```bash
+# 安装 certbot
+sudo apt install certbot python3-certbot-nginx
+
+# 获取 SSL 证书
+sudo certbot --nginx -d your-domain.com
+
+# 自动续期已自动配置
+# 测试续期
+sudo certbot renew --dry-run
+```
+
+---
+
+## 🔒 安全注意事项
+
+### 1. 修改默认凭据
+
+**关键:** 部署前修改 `JWT_SECRET` 和 `INITIAL_PASSWORD`:
+
+```bash
+# 生成安全的 JWT secret
+openssl rand -base64 32
+
+# 将该值用于 JWT_SECRET
+export JWT_SECRET="generated-secret-here"
+```
+
+### 2. 防火墙配置
+
+```bash
+# 允许 SSH
+sudo ufw allow 22/tcp
+
+# 允许 HTTP/HTTPS(若使用 Nginx)
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+
+# 若不使用反向代理,放开 9Router 端口
+sudo ufw allow 3000/tcp
+sudo ufw allow 20128/tcp
+
+# 启用防火墙
+sudo ufw enable
+```
+
+### 3. 限制仪表盘访问
+
+如果只需要 API 访问,可限制仪表盘端口:
+
+```bash
+# 仅允许 localhost 访问仪表盘
+sudo ufw deny 3000/tcp
+```
+
+通过 SSH 隧道访问仪表盘:
+
+```bash
+ssh -L 3000:localhost:3000 user@your-server.com
+# 然后在浏览器打开 http://localhost:3000
+```
+
+### 4. 定期更新
+
+```bash
+# 更新系统包
+sudo apt update && sudo apt upgrade -y
+
+# 更新 9Router
+cd /path/to/9router/app
+git pull
+npm install
+npm run build
+pm2 restart 9router
+```
+
+### 5. 备份策略
+
+```bash
+# 备份数据目录
+tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router
+
+# 每日自动备份(加入 crontab)
+0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router
+```
+
+---
+
+## 📊 监控
+
+### 检查应用状态
+
+```bash
+# PM2 状态
+pm2 status
+
+# 查看日志
+pm2 logs 9router --lines 100
+
+# 监控资源
+pm2 monit
+```
+
+### Nginx 日志
+
+```bash
+# 访问日志
+sudo tail -f /var/log/nginx/access.log
+
+# 错误日志
+sudo tail -f /var/log/nginx/error.log
+```
+
+### 系统资源
+
+```bash
+# CPU 和内存使用
+htop
+
+# 磁盘使用
+df -h
+
+# 网络连接
+netstat -tulpn | grep -E '3000|20128'
+```
+
+---
+
+## 🚨 故障排除
+
+### 应用无法启动
+
+```bash
+# 查看日志
+pm2 logs 9router
+
+# 检查端口是否被占用
+sudo lsof -i :3000
+sudo lsof -i :20128
+
+# 检查环境变量
+pm2 env 9router
+```
+
+### Nginx 502 Bad Gateway
+
+```bash
+# 检查 9Router 是否运行
+pm2 status
+
+# 查看 Nginx 错误日志
+sudo tail -f /var/log/nginx/error.log
+
+# 测试 Nginx 配置
+sudo nginx -t
+```
+
+### SSE 流式输出无法工作
+
+确保 Nginx 配置中已设置 `proxy_buffering off` 以支持 SSE。
+
+### 权限被拒绝错误
+
+```bash
+# 修复数据目录权限
+sudo chown -R $USER:$USER /var/lib/9router
+chmod 755 /var/lib/9router
+```
+
+---
+
+## 🔗 下一步
+
+- [连接提供商](/providers/subscription.md)
+- [配置组合](/features/combos.md)
+- [集成工具](/integration/cursor.md)
diff --git a/gitbook/content/zh-CN/deployment/localhost.md b/gitbook/content/zh-CN/deployment/localhost.md
new file mode 100644
index 0000000..aed7d0c
--- /dev/null
+++ b/gitbook/content/zh-CN/deployment/localhost.md
@@ -0,0 +1,164 @@
+# 🏠 本地部署
+
+在本机运行 9Router,用于开发和个人使用。
+
+---
+
+## 📦 安装
+
+通过 npm 全局安装 9Router:
+
+```bash
+npm install -g 9router
+```
+
+**要求:**
+- Node.js 20 或更高
+- npm 9 或更高
+
+---
+
+## 🚀 启动服务器
+
+一条命令启动 9Router:
+
+```bash
+9router
+```
+
+仪表盘会自动在浏览器中打开,地址为 `http://localhost:3000`
+
+**默认配置:**
+- **仪表盘**: `http://localhost:3000`
+- **API Endpoint**: `http://localhost:20128/v1`
+- **数据目录**: `~/.9router`
+
+---
+
+## 🔧 配置
+
+### 自定义数据目录
+
+通过环境变量设置自定义数据目录:
+
+```bash
+DATA_DIR=/path/to/data 9router
+```
+
+### 自定义端口
+
+API 端口(20128)和仪表盘端口(3000)在应用中配置。如需修改,你需要改源码或使用支持的环境变量(如果有)。
+
+---
+
+## 🛑 停止服务器
+
+在运行 9Router 的终端中按 `Ctrl+C`。
+
+```bash
+# 在运行 9router 的终端中
+^C  # 按 Ctrl+C
+```
+
+服务器会优雅关闭并保存所有数据。
+
+---
+
+## 🔄 重启服务器
+
+再次运行启动命令即可:
+
+```bash
+9router
+```
+
+所有配置、API keys 和组合都保存在数据目录中。
+
+---
+
+## 📊 更新 9Router
+
+更新到最新版本:
+
+```bash
+npm update -g 9router
+```
+
+查看当前版本:
+
+```bash
+npm list -g 9router
+```
+
+---
+
+## 🔍 故障排除
+
+### 端口已被占用
+
+如果端口 20128 或 3000 已被占用:
+
+```bash
+# 找到使用该端口的进程(macOS/Linux)
+lsof -i :20128
+lsof -i :3000
+
+# 杀掉进程
+kill -9 <PID>
+```
+
+### 权限错误
+
+安装过程中遇到权限错误:
+
+```bash
+# 使用 sudo(不推荐)
+sudo npm install -g 9router
+
+# 或修复 npm 权限(推荐)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### 数据目录问题
+
+数据目录无法访问:
+
+```bash
+# 检查权限
+ls -la ~/.9router
+
+# 修复权限
+chmod 755 ~/.9router
+```
+
+---
+
+## 📁 数据目录结构
+
+```
+~/.9router/
+├── db.json           # 主数据库(提供商、组合、设置)
+├── logs/             # 应用日志
+└── cache/            # 临时缓存文件
+```
+
+**备份数据:**
+
+```bash
+# 备份
+cp -r ~/.9router ~/.9router.backup
+
+# 恢复
+cp -r ~/.9router.backup ~/.9router
+```
+
+---
+
+## 🔗 下一步
+
+- [连接提供商](/providers/subscription.md)
+- [创建组合](/features/combos.md)
+- [集成 CLI 工具](/integration/cursor.md)
diff --git a/gitbook/content/zh-CN/faq.md b/gitbook/content/zh-CN/faq.md
new file mode 100644
index 0000000..91dc816
--- /dev/null
+++ b/gitbook/content/zh-CN/faq.md
@@ -0,0 +1,387 @@
+# 常见问题
+
+关于 9Router 的常见问题。
+
+---
+
+## 什么是 9Router?
+
+**9Router 是一款 AI 模型路由工具,能够最大化你的订阅价值并最小化成本。**
+
+它使用 3 层回退系统在多个 AI 提供商之间智能路由请求:
+1. **订阅层** - 充分利用你已付费的 Claude Code、Codex、Gemini 配额
+2. **低价层** - 超低价替代方案(每 1M tokens $0.20-$0.60)
+3. **免费层** - 无限免费模型应急备用
+
+**核心优势:**
+- 不再浪费订阅配额
+- 配额耗尽时自动回退
+- 实时配额跟踪
+- 比直接使用 API 节省 90% 成本
+
+---
+
+## 价格是如何计算的?
+
+**9Router 采用三层定价策略:**
+
+### 第 1 层:订阅(优先使用)
+- **Claude Code**(Pro/Max):$20-100/月 - 5 小时 + 每周配额
+- **OpenAI Codex**(Plus/Pro):$20-200/月 - 5 小时 + 每周配额
+- **Gemini CLI**:免费 - 每月 180K 次补全 + 每天 1K
+- **GitHub Copilot**:$10-19/月 - 每月重置
+- **Antigravity**:免费 - 类似 Gemini
+
+**目标:** 在配额重置前用掉每一点!
+
+### 第 2 层:低价(备用)
+- **GLM-4.7**:每 1M tokens $0.60/$2.20 - 每日 10AM 重置
+- **MiniMax M2.1**:每 1M tokens $0.20/$1.00 - 5 小时滚动
+- **Kimi K2**:$9/月固定(10M tokens)
+
+**目标:** 比 ChatGPT API(每 1M $20)便宜 90%!
+
+### 第 3 层:免费(应急)
+- **iFlow**:8 个免费模型(Kimi K2、Qwen3、GLM、MiniMax...)
+- **Qwen**:3 个免费模型(Qwen3 Coder Plus/Flash、Vision)
+- **Kiro**:2 个免费模型(Claude Sonnet 4.5、Haiku 4.5)
+
+**目标:** 当其他配额都受限时零成本回退!
+
+---
+
+## 9Router 是免费的吗?
+
+**是的,9Router 本身 100% 免费且开源。**
+
+**可用的免费层提供商:**
+- **Gemini CLI** - 每月 180K 次补全(免费 Google 账户)
+- **iFlow** - 8 个无限模型(免费 OAuth)
+- **Qwen** - 3 个无限模型(免费 OAuth)
+- **Kiro** - Claude Sonnet/Haiku(免费 AWS Builder ID)
+
+**只用免费层提供商,就可以永久免费编码!**
+
+**可选的付费提供商:**
+- 你可能已有的订阅服务(Claude Code、Codex、Copilot)
+- 超低价替代方案(每 1M tokens $0.20-$0.60)
+
+---
+
+## 支持哪些提供商?
+
+### 订阅型提供商
+- **Claude Code**(Pro/Max)- Claude 4.5 Opus/Sonnet/Haiku
+- **OpenAI Codex**(Plus/Pro)- GPT 5.2 Codex、GPT 5.1 Codex Max
+- **Gemini CLI**(免费)- Gemini 3 Flash/Pro、2.5 Pro/Flash
+- **GitHub Copilot** - GPT-5、Claude 4.5、Gemini 3
+- **Antigravity**(Google)- Gemini 3 Pro、Claude Sonnet 4.5
+
+### 低价提供商
+- **GLM**(Zhipu AI)- GLM 4.7、GLM 4.6V Vision
+- **MiniMax** - MiniMax M2.1
+- **Kimi**(Moonshot AI)- Kimi Latest
+- **OpenRouter** - 透传到任意 OpenRouter 模型
+
+### 免费提供商
+- **iFlow** - 8 个模型(Kimi K2、Qwen3、GLM、MiniMax、DeepSeek...)
+- **Qwen** - 3 个模型(Qwen3 Coder Plus/Flash、Vision)
+- **Kiro** - 2 个模型(Claude Sonnet 4.5、Haiku 4.5)
+
+**合计:15+ 个提供商,50+ 个模型**
+
+详情请见 [提供商文档](providers/subscription.md)。
+
+---
+
+## 可以同时使用多个提供商吗?
+
+**可以!这正是 9Router 的核心功能。**
+
+**通过组合(Combos),你可以把多个提供商串联起来实现自动回退:**
+
+```
+示例组合: "premium-coding"
+1. cc/claude-opus-4-5(订阅主力)
+2. glm/glm-4.7(低价备用)
+3. if/kimi-k2(免费应急)
+
+→ 配额耗尽时自动切换
+→ 永不停止编码
+→ 几乎零额外成本
+```
+
+**创建组合的方法:**
+```
+仪表盘 → 组合 → 新建
+→ 按优先级添加模型
+→ CLI 中使用组合名: "premium-coding"
+```
+
+**优势:**
+- 配额耗尽时零停机
+- 自动成本优化
+- 所有工具使用同一个模型名
+
+详情见 [组合文档](features/combos.md)。
+
+---
+
+## 配额跟踪是如何工作的?
+
+**9Router 为所有提供商提供实时配额跟踪:**
+
+**功能:**
+- **Token 消耗** - 每次请求的输入/输出 tokens
+- **重置倒计时** - 配额刷新前剩余时间
+- **使用统计** - 每日/每周/每月报告
+- **成本估算** - 预计支出(付费层)
+- **配额告警** - 配额不足时通知
+
+**配额类型:**
+- **5 小时滚动** - Claude Code、Codex、MiniMax
+- **每日重置** - Gemini CLI(每日 1K)、GLM(10AM)
+- **每周重置** - Claude Code、Codex(额外配额)
+- **每月重置** - Gemini CLI(180K)、GitHub Copilot(1 日)
+
+**查看配额:**
+```
+仪表盘 → 提供商 → 配额跟踪
+→ 实时使用情况 + 重置倒计时
+```
+
+详情见 [配额跟踪文档](features/quota-tracking.md)。
+
+---
+
+## 9Router 能配合 Cursor 使用吗?
+
+**可以,但 Cursor 需要使用云端 endpoint。**
+
+**问题:** Cursor IDE 不支持 localhost endpoint。
+
+**解决方案:** 使用 9Router 云端部署:
+
+```
+Cursor Settings → Models → Advanced:
+  OpenAI API Base URL: https://9router.com/v1
+  OpenAI API Key: [从仪表盘获取]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+**替代方案:** 在 VPS 上自托管,使用公开域名:
+```bash
+# 部署到 VPS
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+npm start
+
+# 配置 Nginx 反向代理
+# 将 Cursor 指向: https://your-domain.com/v1
+```
+
+**其他 CLI 工具支持 localhost:**
+- Cline ✅
+- Claude Desktop ✅
+- Codex CLI ✅
+- Continue ✅
+- RooCode ✅
+
+详情见 [Cursor 集成指南](integration/cursor.md)。
+
+---
+
+## 可以自托管 9Router 吗?
+
+**可以!9Router 支持多种部署方式:**
+
+### Localhost(默认)
+```bash
+npm install -g 9router
+9router
+→ 仪表盘: http://localhost:3000
+→ API: http://localhost:20128/v1
+```
+
+### VPS/云
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install && npm run build
+
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+npm start
+```
+
+### Docker
+```bash
+docker build -t 9router .
+docker run -d \
+  -p 3000:3000 \
+  -e JWT_SECRET="your-secret" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Cloudflare Workers
+```bash
+cd 9router/app
+npm run deploy:cloudflare
+```
+
+**环境变量:**
+- `JWT_SECRET` - **生产环境必须修改!**
+- `DATA_DIR` - 数据库存储路径(默认:`~/.9router`)
+- `INITIAL_PASSWORD` - 仪表盘登录(默认:`123456`)
+- `NODE_ENV` - 部署时设为 `production`
+
+详情见 [部署指南](getting-started/installation.md#deployment)。
+
+---
+
+## 我的数据安全吗?
+
+**是的,9Router 优先考虑安全和隐私:**
+
+**本地存储:**
+- 所有数据存储在本地 `~/.9router`(或自定义 `DATA_DIR`)
+- 不会发送数据到 9Router 服务器
+- OAuth tokens 使用 JWT 加密
+
+**无遥测:**
+- 不跟踪使用情况
+- 不分析
+- 不向外回连
+
+**开源:**
+- GitHub 上提供完整源码
+- 可自行审计安全性
+- 社区评审
+
+**最佳实践:**
+- 生产环境修改 `JWT_SECRET`
+- 使用强 `INITIAL_PASSWORD`
+- 云端部署启用 HTTPS
+- 定期轮换 API keys
+
+**9Router 存储的内容:**
+- 提供商 OAuth tokens(加密)
+- API keys(加密)
+- 使用统计(仅本地)
+- 组合配置
+
+**9Router 不存储的内容:**
+- 你的 prompt 或响应
+- 你生成的代码
+- 个人信息
+
+---
+
+## 如何更新 9Router?
+
+**更新方式取决于安装类型:**
+
+### 全局 NPM 安装
+```bash
+npm update -g 9router
+```
+
+### 本地安装
+```bash
+cd 9router/app
+git pull origin main
+npm install
+npm run build
+npm start
+```
+
+### Docker
+```bash
+docker pull 9router:latest
+docker stop 9router
+docker rm 9router
+docker run -d \
+  -p 3000:3000 \
+  -v 9router-data:/app/data \
+  9router:latest
+```
+
+**查看版本:**
+```bash
+9router --version
+```
+
+**破坏性变更:**
+- 查看 [CHANGELOG.md](https://github.com/decolua/9router/blob/main/CHANGELOG.md)
+- 大版本更新前备份 `~/.9router`
+- 阅读大版本的迁移指南
+
+---
+
+## 如何贡献?
+
+**欢迎贡献!**
+
+### 贡献方式:
+
+1. **报告 bug:**
+   - [GitHub Issues](https://github.com/decolua/9router/issues)
+   - 附上错误日志、复现步骤
+
+2. **功能请求:**
+   - [GitHub Discussions](https://github.com/decolua/9router/discussions)
+   - 描述使用场景和价值
+
+3. **提交代码:**
+   ```bash
+   # Fork 仓库
+   git clone https://github.com/YOUR_USERNAME/9router.git
+   cd 9router
+   
+   # 创建分支
+   git checkout -b feature/your-feature
+   
+   # 修改代码
+   npm install
+   npm run dev
+   
+   # 测试
+   npm test
+   
+   # 提交并推送
+   git add .
+   git commit -m "Add your feature"
+   git push origin feature/your-feature
+   
+   # 在 GitHub 上创建 Pull Request
+   ```
+
+4. **改进文档:**
+   - 修正错别字、添加示例
+   - 翻译到其他语言
+   - 编写教程
+
+5. **添加提供商:**
+   - 实现新的 provider adapter
+   - 参考 `app/lib/providers/` 中的示例
+
+**贡献指南:**
+- 遵循现有代码风格
+- 为新功能添加测试
+- 更新文档
+- 提交保持原子化、描述清晰
+
+详情见 [CONTRIBUTING.md](https://github.com/decolua/9router/blob/main/CONTRIBUTING.md)。
+
+---
+
+## 需要更多帮助?
+
+- **文档:** [9router.com/docs](https://9router.com/docs)
+- **GitHub:** [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **故障排除:** [troubleshooting.md](troubleshooting.md)
diff --git a/gitbook/content/zh-CN/features/combos.md b/gitbook/content/zh-CN/features/combos.md
new file mode 100644
index 0000000..aa3456d
--- /dev/null
+++ b/gitbook/content/zh-CN/features/combos.md
@@ -0,0 +1,537 @@
+# 组合(Combos)- 自定义回退链
+
+创建自定义的模型组合并自动回退。组合让你根据成本、质量和可用性定义自己的路由策略。
+
+---
+
+## 什么是组合?
+
+组合是你在仪表盘中创建的 **自定义回退链**。它不是单一模型,而是定义一组顺序模型,由 9Router 依次尝试。
+
+**示例:**
+```
+组合名: premium-coding
+模型:
+  1. cc/claude-opus-4-5-20251101 (首选)
+  2. glm/glm-4.7 (#1 配额耗尽时)
+  3. minimax/MiniMax-M2.1 (#2 配额耗尽时)
+```
+
+**CLI 中使用:**
+```
+Model: premium-coding
+```
+
+9Router 会按顺序自动尝试每个模型,直到成功为止。
+
+---
+
+## 为什么使用组合?
+
+### 1. 最大化订阅价值
+```
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ 先用订阅,低价备用,免费应急
+→ 充分利用你已付费的订阅
+```
+
+### 2. 最小化成本
+```
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+
+→ 从最便宜的付费选项开始(每 1M $0.60)
+→ 回退到更便宜的(每 1M $0.20)
+→ 应急免费层
+→ 总成本: 约 $5-10/月,而 ChatGPT API 需要 $2000
+```
+
+### 3. 保障 24/7 可用
+```
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7 → if/kimi-k2-thinking
+
+→ 末尾总是放免费层
+→ 永不耗尽配额
+→ 随时随地编码
+```
+
+### 4. 质量优化
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → gc/gemini-3-pro
+
+→ 优先最好的模型
+→ 回退到其他高端模型
+→ 整个回退链保持高质量
+```
+
+---
+
+## 如何创建组合
+
+### 步骤 1:打开仪表盘
+
+```
+http://localhost:20128
+→ 用密码登录
+```
+
+### 步骤 2:进入组合页面
+
+```
+仪表盘 → 组合 → 新建组合
+```
+
+### 步骤 3:配置组合
+
+**组合名:**
+```
+premium-coding
+```
+
+**描述(可选):**
+```
+订阅优先,低价备用,免费应急
+```
+
+**选择模型:**
+```
+1. cc/claude-opus-4-5-20251101
+2. glm/glm-4.7
+3. minimax/MiniMax-M2.1
+```
+
+**拖动排序** - 自上而下表示优先级。
+
+### 步骤 4:保存
+
+```
+点击 "Save Combo"
+→ 组合出现在模型列表中
+```
+
+### 步骤 5:在 CLI 中使用
+
+```
+Cursor/Cline/任意工具:
+  Model: premium-coding
+```
+
+---
+
+## 示例组合
+
+### 示例 1:Premium Coding(订阅 → 低价 → 免费)
+
+**目标**:最大化订阅价值,最小化额外成本。
+
+```
+仪表盘 → 组合 → 新建
+
+名称: premium-coding
+模型:
+  1. cc/claude-opus-4-5-20251101
+  2. glm/glm-4.7
+  3. minimax/MiniMax-M2.1
+```
+
+**用法:**
+```
+Cursor IDE:
+  Model: premium-coding
+```
+
+**行为:**
+```
+早上(全新配额):
+  请求 → cc/claude-opus-4-5 ✅
+
+下午(Claude 配额用完):
+  请求 → glm/glm-4.7 ✅ (自动切换)
+
+晚上(GLM 配额用完):
+  请求 → minimax/MiniMax-M2.1 ✅ (自动切换)
+```
+
+**月成本(100M tokens):**
+```
+80M 通过 Claude Code: $0(订阅)
+15M 通过 GLM: $9
+5M 通过 MiniMax: $1
+合计: $10 + 你的订阅
+```
+
+**节省**:相比 ChatGPT API($2000)约 99%。
+
+---
+
+### 示例 2:Budget Combo(低价 → 免费)
+
+**目标**:最小化成本,免费层作为备用。
+
+```
+仪表盘 → 组合 → 新建
+
+名称: budget-combo
+模型:
+  1. glm/glm-4.7
+  2. minimax/MiniMax-M2.1
+  3. if/kimi-k2-thinking
+```
+
+**用法:**
+```
+Cline:
+  Provider: OpenAI Compatible
+  Base URL: http://localhost:20128/v1
+  Model: budget-combo
+```
+
+**行为:**
+```
+请求 → glm/glm-4.7
+  ✅ 每日配额可用 → 使用 GLM(每 1M $0.60)
+  ❌ 配额耗尽 → 尝试 MiniMax(每 1M $0.20)
+  ❌ MiniMax 配额用完 → 使用 iFlow(免费)
+```
+
+**月成本(100M tokens):**
+```
+70M 通过 GLM: $42
+20M 通过 MiniMax: $4
+10M 通过 iFlow: $0
+合计: $46,而 ChatGPT API 需 $2000
+```
+
+**节省**:97%。
+
+---
+
+### 示例 3:Free Combo(零成本)
+
+**目标**:100% 免费,永不付费。
+
+```
+仪表盘 → 组合 → 新建
+
+名称: free-combo
+模型:
+  1. if/kimi-k2-thinking
+  2. qw/qwen3-coder-plus
+  3. kr/claude-sonnet-4.5
+```
+
+**用法:**
+```
+Claude Desktop:
+  Model: free-combo
+```
+
+**行为:**
+```
+请求 → if/kimi-k2-thinking
+  ✅ 可用 → 使用 iFlow
+  ❌ 错误 → 尝试 Qwen
+  ❌ 错误 → 尝试 Kiro
+```
+
+**月成本:**
+```
+100M tokens 通过免费提供商: $0
+合计: 永远 $0
+```
+
+**适用场景**:个人项目、学习、试验。
+
+---
+
+### 示例 4:Quality First(仅高端模型)
+
+**目标**:最高质量,无低价回退。
+
+```
+仪表盘 → 组合 → 新建
+
+名称: quality-first
+模型:
+  1. cc/claude-opus-4-5-20251101
+  2. cx/gpt-5.2-codex
+  3. gc/gemini-3-pro-preview
+```
+
+**用法:**
+```
+Codex CLI:
+  export OPENAI_BASE_URL="http://localhost:20128"
+  Model: quality-first
+```
+
+**行为:**
+```
+请求 → cc/claude-opus-4-5
+  ❌ 配额用完 → cx/gpt-5.2-codex
+  ❌ 配额用完 → gc/gemini-3-pro-preview
+  ❌ 全部用完 → 返回错误(无低价回退)
+```
+
+**适用场景**:关键生产代码、复杂重构。
+
+---
+
+### 示例 5:Multi-Subscription(用足所有订阅)
+
+**目标**:在产生额外费用前用足所有订阅。
+
+```
+仪表盘 → 组合 → 新建
+
+名称: multi-sub
+模型:
+  1. gc/gemini-3-flash-preview (每月免费 180K)
+  2. cc/claude-opus-4-5-20251101 (Pro 订阅)
+  3. cx/gpt-5.2-codex (Plus 订阅)
+  4. gh/gpt-5 (Copilot 订阅)
+  5. glm/glm-4.7 (低价备用)
+  6. if/kimi-k2-thinking (免费应急)
+```
+
+**月成本(200M tokens):**
+```
+50M 通过 Gemini CLI: $0(免费层)
+80M 通过 Claude Code: $0(订阅)
+40M 通过 Codex: $0(订阅)
+20M 通过 Copilot: $0(订阅)
+8M 通过 GLM: $4.80
+2M 通过 iFlow: $0
+合计: $4.80 + 你已有的订阅
+```
+
+**结果**:190M tokens 来自订阅,只有 $4.80 额外费用。
+
+---
+
+### 示例 6:配额重置优化
+
+**目标**:根据重置时间分配使用。
+
+```
+仪表盘 → 组合 → 新建
+
+名称: reset-optimized
+模型:
+  1. cc/claude-opus-4-5 (5h 重置, 早上用)
+  2. gc/gemini-3-flash (每日 1K, 下午用)
+  3. glm/glm-4.7 (每日 10AM 重置, 晚上用)
+  4. minimax/MiniMax-M2.1 (5h 滚动, 夜里用)
+  5. if/kimi-k2-thinking (无限, 应急)
+```
+
+**日常安排:**
+```
+08:00 - 13:00: Claude Code(全新 5h 配额)
+13:00 - 18:00: Gemini CLI(每日 1K 配额)
+18:00 - 22:00: GLM(次日 10AM 重置)
+22:00 - 08:00: MiniMax(5h 滚动)或 iFlow
+```
+
+**结果**:24/7 编码,成本极低。
+
+---
+
+## 在 CLI 工具中使用组合
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [从仪表盘获取]
+  Model: premium-coding
+```
+
+### Claude Desktop
+
+编辑 `~/.claude/config.json`:
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key",
+  "model": "budget-combo"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex --model quality-first "your prompt"
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [从仪表盘获取]
+Model: free-combo
+```
+
+### API 请求
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "premium-coding",
+    "messages": [
+      {"role": "user", "content": "Write a function to..."}
+    ],
+    "stream": true
+  }'
+```
+
+---
+
+## 最佳实践
+
+### 1. 总是包含免费层
+
+```
+✅ 好:
+cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
+
+❌ 不好:
+cc/claude-opus → glm/glm-4.7
+(无免费回退,可能耗尽配额)
+```
+
+**原因**:确保 24/7 可用,绝不会被配额卡住。
+
+### 2. 按成本排序(便宜 → 贵)
+
+```
+✅ 好:
+glm/glm-4.7 → minimax/MiniMax-M2.1 → cc/claude-opus
+
+❌ 不好:
+cc/claude-opus → glm/glm-4.7
+(在简单任务上浪费订阅配额)
+```
+
+**例外**:如果想充分利用订阅价值,把订阅放在最前面。
+
+### 3. 匹配质量要求
+
+```
+生产代码:
+cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7
+
+简单任务:
+glm/glm-4.7 → if/kimi-k2-thinking
+
+试验:
+if/kimi-k2-thinking → qw/qwen3-coder-plus
+```
+
+### 4. 考虑配额重置时间
+
+```
+早上组合(配额刚刷新):
+cc/claude-opus → cx/gpt-5.2-codex
+
+晚上组合(配额大概率耗尽):
+glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+### 5. 为不同场景创建多个组合
+
+```
+premium-coding: 复杂任务
+budget-combo: 简单任务
+free-combo: 试验
+quality-first: 生产代码
+```
+
+**根据任务需求切换组合**。
+
+### 6. 监控组合性能
+
+```
+仪表盘 → 分析 → 组合使用:
+  premium-coding:
+    80% 通过 cc/claude-opus(良好,使用订阅)
+    15% 通过 glm/glm-4.7(可接受备用)
+    5% 通过 minimax(罕见回退)
+```
+
+**优化**:回退使用过多时,提高主配额或重新排序模型。
+
+---
+
+## 高级配置
+
+### 为组合设置预算上限
+
+```
+仪表盘 → 组合 → 编辑 → 预算:
+  每日上限: $5
+  每月上限: $50
+```
+
+达到上限时,9Router 跳过付费模型,仅使用免费层。
+
+### 启用/禁用组合中的模型
+
+```
+仪表盘 → 组合 → 编辑 → 模型:
+  ✅ cc/claude-opus-4-5(启用)
+  ❌ glm/glm-4.7(暂时禁用)
+  ✅ if/kimi-k2-thinking(启用)
+```
+
+**用途**:暂时禁用昂贵模型而不删除组合。
+
+### 克隆已有组合
+
+```
+仪表盘 → 组合 → 克隆 "premium-coding"
+→ 生成带 "-copy" 后缀的副本
+→ 修改后另存为新组合
+```
+
+**用途**:为不同场景创建变体。
+
+---
+
+## 故障排除
+
+**问题:组合未出现在模型列表中**
+
+**方案:**
+1. 刷新仪表盘
+2. 检查组合已保存(绿色对勾)
+3. 重启 CLI 工具以刷新模型列表
+
+**问题:组合总是用最后一个模型(免费层)**
+
+**方案:**
+1. 检查主模型的配额(仪表盘 → 配额)
+2. 确认 API keys 有效(仪表盘 → 提供商)
+3. 检查是否超出预算上限
+
+**问题:组合成本超出预期**
+
+**方案:**
+1. 仪表盘 → 分析 → 查看组合使用情况
+2. 检查主模型是否配额耗尽
+3. 重新排序模型(更便宜的放前面)
+4. 设置预算上限
+
+---
+
+## 相关
+
+- [智能路由](./smart-routing.md) - 自动回退如何工作
+- [配额跟踪](./quota-tracking.md) - 监控使用与成本
diff --git a/gitbook/content/zh-CN/features/quota-tracking.md b/gitbook/content/zh-CN/features/quota-tracking.md
new file mode 100644
index 0000000..8763cb4
--- /dev/null
+++ b/gitbook/content/zh-CN/features/quota-tracking.md
@@ -0,0 +1,687 @@
+# 配额跟踪 & 使用监控
+
+实时跟踪 token 消耗、监控配额上限、估算成本,并在配额用尽前获得提醒。绝不浪费订阅配额,也不超出预算上限。
+
+---
+
+## 概览
+
+9Router 为所有提供商提供完善的配额跟踪:
+
+- **实时 token 消耗** - 查看每次请求使用的 tokens
+- **配额上限与剩余** - 跟踪使用 vs 上限
+- **重置倒计时** - 了解配额何时刷新
+- **成本估算** - 计算付费层支出
+- **月度报告** - 分析使用模式
+- **告警与通知** - 接近上限时收到警告
+
+---
+
+## 仪表盘总览
+
+### 配额摘要
+
+```
+仪表盘 → 主页 → 配额概览
+
+┌─────────────────────────────────────────────┐
+│ Claude Code (cc/)                           │
+│ ████████████░░░░░░░░ 2.5h / 5h (50%)       │
+│ 重置剩余: 2h 30m                            │
+│ 成本: $0(订阅)                             │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ Gemini CLI (gc/)                            │
+│ ████████░░░░░░░░░░░░ 450 / 1000 (45%)      │
+│ 每日重置剩余: 18h 30m                       │
+│ 本月: 45K / 180K (25%)                      │
+│ 成本: $0(免费层)                           │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ GLM-4.7 (glm/)                              │
+│ ██████████████░░░░░░ 7M / 10M tokens (70%)  │
+│ 重置: 每日 10:00 AM(5h 35m 后)            │
+│ 今日成本: $4.20                             │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ MiniMax M2.1 (minimax/)                     │
+│ ████████████████░░░░ 4M / 5M tokens (80%)   │
+│ 5h 滚动窗口                                  │
+│ 成本(5h): $0.80                            │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│ iFlow (if/)                                 │
+│ ████████████████████ 无限                   │
+│ 成本: $0(永久免费)                        │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## 实时 Token 消耗
+
+### 按请求跟踪
+
+每次请求都会显示详细的 token 使用情况:
+
+```
+仪表盘 → 活动 → 最近请求
+
+请求 #1234
+模型: cc/claude-opus-4-5-20251101
+时间戳: 2026-02-04 04:15:32
+
+Tokens:
+  输入: 1,250 tokens
+  输出: 850 tokens
+  合计: 2,100 tokens
+
+成本: $0(订阅配额)
+耗时: 3.2s
+状态: ✅ 成功
+```
+
+### 实时使用监控
+
+```
+仪表盘 → 实时监控
+
+当前请求:
+  模型: glm/glm-4.7
+  已流式输出 tokens: 450 / 预计 ~800
+  当前成本: $0.0009
+  耗时: 1.8s
+```
+
+### 按模型分解 Token
+
+```
+仪表盘 → 分析 → Token 使用
+
+今日(2026-02-04):
+  cc/claude-opus-4-5: 15M tokens($0,订阅)
+  glm/glm-4.7: 8M tokens($4.80)
+  if/kimi-k2-thinking: 3M tokens($0,免费)
+  
+合计: 26M tokens
+成本: $4.80
+```
+
+---
+
+## 配额上限与重置时间
+
+### 订阅型提供商
+
+**Claude Code (Pro/Max)**
+```
+配额类型: 基于时间(5 小时滚动)
+上限: 5 小时使用时长
+重置: 5 小时滚动窗口 + 每周刷新
+跟踪: 每个模型的使用时间
+
+仪表盘显示:
+  Opus: 已用 2.5h / 5h
+  Sonnet: 已用 1.2h / 5h
+  Haiku: 已用 0.8h / 5h
+  
+每周重置: 每周一 00:00 UTC
+```
+
+**OpenAI Codex (Plus/Pro)**
+```
+配额类型: 基于时间(5 小时滚动)
+上限: 5 小时(Plus)/ 10 小时(Pro)
+重置: 5 小时滚动窗口 + 每周刷新
+
+仪表盘显示:
+  GPT-5.2 Codex: 已用 3.5h / 5h
+  重置剩余: 1h 30m
+```
+
+**Gemini CLI(免费)**
+```
+配额类型: 请求次数 + 月度 tokens
+每日上限: 1,000 次请求
+月度上限: 180,000 次补全
+重置: 每日 00:00 UTC + 每月 1 日
+
+仪表盘显示:
+  今日: 450 / 1,000 次请求 (45%)
+  本月: 45K / 180K 次补全 (25%)
+  每日重置剩余: 18h 30m
+  月度重置剩余: 26 天
+```
+
+**GitHub Copilot**
+```
+配额类型: 月度使用量
+上限: 因套餐而异
+重置: 每月 1 日
+
+仪表盘显示:
+  使用: 月度配额 60%
+  重置: 2026 年 3 月 1 日(25 天后)
+```
+
+### 低价提供商
+
+**GLM-4.7**
+```
+配额类型: 每日 token 上限
+上限: 10M tokens/天(Coding Plan)
+重置: 每日 10:00 AM 北京时间(UTC+8)
+
+仪表盘显示:
+  已用: 7M / 10M tokens (70%)
+  剩余: 3M tokens
+  重置剩余: 5h 35m
+  今日成本: $4.20
+```
+
+**MiniMax M2.1**
+```
+配额类型: 5 小时滚动窗口
+上限: 每 5 小时 5M tokens
+重置: 连续滚动窗口
+
+仪表盘显示:
+  已用(5h): 4M / 5M tokens (80%)
+  最早一次使用过期: 45m
+  成本(5h): $0.80
+```
+
+**Kimi K2**
+```
+配额类型: 月度订阅
+上限: 10M tokens/月($9 固定)
+重置: 订阅日每月一次
+
+仪表盘显示:
+  已用: 6M / 10M tokens (60%)
+  重置: 2026 年 2 月 15 日(11 天后)
+  成本: $9/月(预付)
+```
+
+### 免费提供商
+
+**iFlow / Qwen / Kiro**
+```
+配额类型: 无限(限速)
+上限: 无硬上限
+重置: 不适用
+
+仪表盘显示:
+  今日已用: 5M tokens
+  成本: $0(永久免费)
+  状态: ✅ 可用
+```
+
+---
+
+## 成本估算
+
+### 实时成本跟踪
+
+```
+仪表盘 → 成本 → 今日
+
+订阅型提供商: $0
+  Claude Code: 15M tokens($0,包含)
+  Gemini CLI: 3M tokens($0,免费层)
+
+付费提供商: $4.80
+  GLM-4.7: 8M tokens($4.80)
+    输入: 6M × $0.60/1M = $3.60
+    输出: 2M × $2.20/1M = $4.40
+    合计: $4.80
+
+免费提供商: $0
+  iFlow: 3M tokens($0)
+
+今日合计: $4.80
+```
+
+### 月度支出报告
+
+```
+仪表盘 → 成本 → 本月(2026 年 2 月)
+
+第 1 周(2 月 1-7 日):
+  订阅: $0(80M tokens)
+  付费: $15.20(25M tokens)
+  免费: $0(10M tokens)
+  合计: $15.20
+
+第 2 周(2 月 8-14 日):
+  订阅: $0(75M tokens)
+  付费: $12.80(20M tokens)
+  免费: $0(8M tokens)
+  合计: $12.80
+
+本月至今: $28.00
+预计(30 天): ~$120
+
+按提供商分解:
+  GLM-4.7: $22.00 (78%)
+  MiniMax M2.1: $6.00 (22%)
+  
+每 1M tokens 平均成本: $0.62
+相比 ChatGPT API 节省: 97%($4,000 → $120)
+```
+
+### 成本预测
+
+```
+仪表盘 → 成本 → 预测
+
+基于近 7 天使用:
+  日均: 50M tokens
+  日成本: $4.50
+
+月度预测:
+  Tokens: 1,500M (1.5B)
+  成本: $135
+  
+分解:
+  订阅: 900M tokens($0)
+  GLM-4.7: 450M tokens($90)
+  MiniMax: 120M tokens($24)
+  免费: 30M tokens($0)
+
+预算状态:
+  每日上限: $5 → 今日已用 90%
+  每月上限: $150 → 预计 90%
+  ⚠️ 警告: 可能超出每月预算
+```
+
+---
+
+## 使用仪表盘
+
+### 总览统计
+
+```
+仪表盘 → 分析 → 总览
+
+今日(2026-02-04):
+  请求: 1,234
+  Tokens: 26M
+  成本: $4.80
+  平均响应时间: 2.1s
+
+本周:
+  请求: 8,456
+  Tokens: 180M
+  成本: $28.00
+  成功率: 99.2%
+
+本月:
+  请求: 15,234
+  Tokens: 320M
+  成本: $52.00
+  Top 模型: cc/claude-opus-4-5 (45%)
+```
+
+### 按模型使用
+
+```
+仪表盘 → 分析 → 模型
+
+Top 模型(本月):
+1. cc/claude-opus-4-5: 145M tokens (45%)
+2. glm/glm-4.7: 95M tokens (30%)
+3. if/kimi-k2-thinking: 50M tokens (16%)
+4. minimax/MiniMax-M2.1: 20M tokens (6%)
+5. gc/gemini-3-flash: 10M tokens (3%)
+
+成本分解:
+  cc/claude-opus: $0(订阅)
+  glm/glm-4.7: $45.00
+  if/kimi-k2-thinking: $0(免费)
+  minimax/MiniMax-M2.1: $7.00
+  gc/gemini-3-flash: $0(免费)
+```
+
+### 按时间使用
+
+```
+仪表盘 → 分析 → 时间线
+
+按小时使用(今日):
+00:00 - 01:00: 0.5M tokens
+01:00 - 02:00: 0.2M tokens
+...
+08:00 - 09:00: 3.2M tokens(峰值)
+09:00 - 10:00: 2.8M tokens
+...
+23:00 - 00:00: 0.8M tokens
+
+峰值时段: 08:00 - 12:00(早上编码)
+低谷时段: 00:00 - 06:00(夜间)
+```
+
+### 按组合使用
+
+```
+仪表盘 → 分析 → 组合
+
+premium-coding:
+  请求: 456
+  Tokens: 12M
+  成本: $2.40
+  
+  分解:
+    cc/claude-opus: 8M tokens (67%, $0)
+    glm/glm-4.7: 3M tokens (25%, $1.80)
+    minimax/MiniMax-M2.1: 1M tokens (8%, $0.20)
+
+budget-combo:
+  请求: 234
+  Tokens: 6M
+  成本: $1.20
+  
+  分解:
+    glm/glm-4.7: 4M tokens (67%, $2.40)
+    if/kimi-k2-thinking: 2M tokens (33%, $0)
+```
+
+---
+
+## 告警与通知
+
+### 配额告警
+
+```
+仪表盘 → 设置 → 告警
+
+配额预警:
+  ✅ 配额使用 80% 时告警
+  ✅ 配额使用 90% 时告警
+  ✅ 配额耗尽时告警
+  ✅ 配额重置时通知
+
+发送方式:
+  ✅ 仪表盘通知
+  ✅ 邮件(可选)
+  ✅ Webhook(可选)
+```
+
+**通知示例:**
+```
+⚠️ Claude Code 配额已用 80%
+   剩余 2.5h(1h 30m 后重置)
+   
+⚠️ GLM-4.7 配额已用 90%
+   剩余 1M tokens(5h 后重置)
+   
+✅ Gemini CLI 配额已重置
+   1,000 次请求可用(每日上限)
+```
+
+### 预算告警
+
+```
+仪表盘 → 设置 → 预算告警
+
+每日预算: $5
+  ✅ 80%($4)告警
+  ✅ 100%($5)告警
+  ✅ 超额时自动切换到免费层
+
+每月预算: $150
+  ✅ 50%($75)告警
+  ✅ 80%($120)告警
+  ✅ 100%($150)告警
+```
+
+**通知示例:**
+```
+⚠️ 每日预算已用 80%
+   今日花费 $4.00 / $5.00
+   
+⚠️ 每月预算达到 50%
+   本月花费 $75 / $150
+   预计: $135(预算内)
+   
+🚨 每日预算超额
+   今日花费 $5.20 / $5.00
+   已自动切换到免费层
+```
+
+### 成本异常检测
+
+```
+仪表盘 → 设置 → 异常检测
+
+✅ 检测异常支出模式
+✅ 成本峰值告警(>2× 日均)
+✅ 配额耗尽模式警告
+
+告警示例:
+⚠️ 检测到成本峰值
+   今日: $12.50(2.5× 日均)
+   原因: GLM-4.7 高用量(20M tokens)
+   建议: 检查主模型是否配额耗尽
+```
+
+---
+
+## 最佳实践
+
+### 1. 每日监控配额
+
+```
+日常:
+1. 查看仪表盘配额概览(30 秒)
+2. 检查重置时间
+3. 根据配额可用性规划使用
+```
+
+**示例:**
+```
+早晨检查:
+  ✅ Claude Code: 5h 可用(刚重置)
+  ✅ Gemini CLI: 1K 请求可用
+  ⚠️ GLM-4.7: 剩 2M tokens(10AM 重置)
+  
+行动: 早上工作用 Claude Code
+```
+
+### 2. 设置预算上限
+
+```
+仪表盘 → 设置 → 预算:
+  每日: $5(防止超支)
+  每月: $150(与预算对齐)
+```
+
+**结果**:达到上限时自动切换到免费层。
+
+### 3. 优化组合使用
+
+```
+仪表盘 → 分析 → 组合:
+  查看哪些模型用得最多
+  调整组合顺序以最小化成本
+```
+
+**示例:**
+```
+当前: cc/claude-opus → glm/glm-4.7
+  80% 通过 Claude(好)
+  20% 通过 GLM($12/月)
+
+优化后: gc/gemini-3-flash → cc/claude-opus → glm/glm-4.7
+  50% 通过 Gemini(免费)
+  40% 通过 Claude(订阅)
+  10% 通过 GLM($6/月)
+  
+节省: $6/月
+```
+
+### 4. 跟踪重置时间
+
+```
+仪表盘 → 配额 → 重置日程:
+  Claude Code: 5h 滚动 + 每周一
+  Gemini CLI: 每日 00:00 UTC + 每月 1 日
+  GLM-4.7: 每日 10:00 AM 北京时间
+  MiniMax: 5h 滚动窗口
+```
+
+**策略**:配额刚刷新时使用对应提供商。
+
+### 5. 查看月度报告
+
+```
+仪表盘 → 分析 → 月度报告:
+  总 tokens: 1.5B
+  总成本: $120
+  节省: 相比 ChatGPT API 节省 97%
+  
+洞察:
+  - 60% 用量来自订阅($0)
+  - 30% 通过 GLM($90)
+  - 10% 通过免费层($0)
+  
+优化:
+  - 增加 Gemini CLI 用量(免费)
+  - 减少 GLM 用量(更贵)
+```
+
+---
+
+## API 访问
+
+### 获取配额状态
+
+```bash
+GET http://localhost:20128/api/quota
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "providers": [
+    {
+      "id": "cc",
+      "name": "Claude Code",
+      "quota": {
+        "used": 2.5,
+        "limit": 5,
+        "unit": "hours",
+        "percentage": 50
+      },
+      "reset": {
+        "type": "rolling",
+        "window": "5h",
+        "nextReset": "2026-02-04T06:45:00Z"
+      },
+      "cost": {
+        "today": 0,
+        "month": 0,
+        "currency": "USD"
+      }
+    },
+    {
+      "id": "glm",
+      "name": "GLM-4.7",
+      "quota": {
+        "used": 7000000,
+        "limit": 10000000,
+        "unit": "tokens",
+        "percentage": 70
+      },
+      "reset": {
+        "type": "daily",
+        "time": "10:00 AM UTC+8",
+        "nextReset": "2026-02-04T10:00:00+08:00"
+      },
+      "cost": {
+        "today": 4.20,
+        "month": 52.00,
+        "currency": "USD"
+      }
+    }
+  ]
+}
+```
+
+### 获取使用统计
+
+```bash
+GET http://localhost:20128/api/usage?period=today
+Authorization: Bearer your-api-key
+
+Response:
+{
+  "period": "today",
+  "date": "2026-02-04",
+  "summary": {
+    "requests": 1234,
+    "tokens": 26000000,
+    "cost": 4.80
+  },
+  "byModel": [
+    {
+      "model": "cc/claude-opus-4-5",
+      "requests": 456,
+      "tokens": 15000000,
+      "cost": 0
+    },
+    {
+      "model": "glm/glm-4.7",
+      "requests": 234,
+      "tokens": 8000000,
+      "cost": 4.80
+    }
+  ]
+}
+```
+
+---
+
+## 故障排除
+
+**问题:配额显示 0% 但请求失败**
+
+**方案:**
+1. 检查提供商连接(仪表盘 → 提供商)
+2. 确认 API keys 有效
+3. 检查提供商是否宕机(状态页)
+4. 尝试重新连接 OAuth 提供商
+
+**问题:成本估算不正确**
+
+**方案:**
+1. 仪表盘 → 设置 → 定价
+2. 确认每个提供商的定价与当前一致
+3. 若提供商调整费率,更新定价
+4. 若差异持续,联系支持
+
+**问题:重置时间没有更新**
+
+**方案:**
+1. 刷新仪表盘(F5)
+2. 检查系统时间是否正确
+3. 确认时区设置
+4. 若问题持续,重启 9Router
+
+**问题:未收到告警**
+
+**方案:**
+1. 仪表盘 → 设置 → 告警
+2. 确认邮箱地址正确
+3. 检查垃圾邮件夹
+4. 测试通知(Send Test 按钮)
+
+---
+
+## 相关
+
+- [智能路由](./smart-routing.md) - 基于配额自动回退
+- [组合](./combos.md) - 创建自定义回退链
diff --git a/gitbook/content/zh-CN/features/smart-routing.md b/gitbook/content/zh-CN/features/smart-routing.md
new file mode 100644
index 0000000..4a78ebe
--- /dev/null
+++ b/gitbook/content/zh-CN/features/smart-routing.md
@@ -0,0 +1,407 @@
+# 智能路由 & 自动回退
+
+9Router 通过 3 层回退系统,自动将你的请求路由到最佳可用提供商。绝不再因配额限制或速率限制而中断编码。
+
+---
+
+## 工作原理
+
+9Router 使用智能路由,最大化已有订阅价值、最小化成本,并保障 24/7 可用:
+
+```
+请求 → 9Router → 检查第 1 层 (订阅)
+                     ↓ 配额耗尽
+                     检查第 2 层 (低价)
+                     ↓ 预算上限
+                     检查第 3 层 (免费)
+                     ↓
+                     响应
+```
+
+### 3 层回退系统
+
+**第 1 层:订阅(主力)**
+- Claude Code(Pro/Max)
+- OpenAI Codex(Plus/Pro)
+- Gemini CLI(每月免费 180K)
+- GitHub Copilot
+- Antigravity(Google)
+
+**目标**:充分挖掘你已付费订阅的价值。
+
+**第 2 层:低价(备用)**
+- GLM-4.7(输入每 1M $0.60)
+- MiniMax M2.1(输入每 1M $0.20)
+- Kimi K2($9/月固定)
+
+**目标**:订阅配额用完后的超低价备用(比 ChatGPT API 便宜 ~90%)。
+
+**第 3 层:免费(应急)**
+- iFlow(8 个模型)
+- Qwen(3 个模型)
+- Kiro(Claude 免费)
+
+**目标**:零成本回退,实现无限编码。
+
+---
+
+## 自动切换
+
+9Router 实时监控配额,自动切换提供商:
+
+### 场景 1:订阅配额耗尽
+
+```
+用户请求 → cc/claude-opus-4-5
+           ↓ 配额耗尽(达到 5 小时限制)
+           自动切换 → glm/glm-4.7
+           ↓ 每日配额耗尽
+           自动切换 → minimax/MiniMax-M2.1
+           ↓ 5 小时配额耗尽
+           自动切换 → if/kimi-k2-thinking (免费)
+           ↓
+           响应已送达 ✅
+```
+
+**结果**:零停机,无缝体验。
+
+### 场景 2:速率限制
+
+```
+用户请求 → cx/gpt-5.2-codex
+           ↓ 速率受限(请求过多)
+           自动切换 → glm/glm-4.7
+           ↓
+           响应已送达 ✅
+```
+
+### 场景 3:提供商不可用
+
+```
+用户请求 → cc/claude-opus-4-5
+           ↓ 提供商错误(503)
+           自动切换 → 下一个可用模型
+           ↓
+           响应已送达 ✅
+```
+
+---
+
+## 模型选择逻辑
+
+9Router 基于以下因素选择最佳模型:
+
+1. **配额可用性** - 检查提供商是否仍有剩余配额
+2. **成本层级** - 优先订阅 → 低价 → 免费
+3. **重置时间** - 考虑配额何时重置
+4. **提供商健康度** - 跳过有错误的提供商
+
+### 优先级示例
+
+对 `cc/claude-opus-4-5` 的请求:
+
+```
+1. 检查 Claude Code 配额
+   ✅ 可用 → 使用 cc/claude-opus-4-5
+   ❌ 耗尽 → 继续步骤 2
+
+2. 检查回退层(若已配置)
+   ✅ GLM 配额可用 → 使用 glm/glm-4.7
+   ❌ 耗尽 → 继续步骤 3
+
+3. 检查免费层
+   ✅ iFlow 可用 → 使用 if/kimi-k2-thinking
+   ❌ 全部耗尽 → 返回配额错误
+```
+
+---
+
+## 配置选项
+
+### 仪表盘设置
+
+**1. 启用/禁用自动回退**
+
+```
+仪表盘 → 设置 → 智能路由
+→ 切换 "Auto Fallback" ON/OFF
+```
+
+- **ON**(默认):自动层级切换
+- **OFF**:严格模式,主模型不可用时返回错误
+
+**2. 设置预算上限**
+
+```
+仪表盘 → 设置 → 预算控制
+→ 每日上限: $5
+→ 每月上限: $50
+```
+
+预算耗尽时,9Router 自动切换到免费层。
+
+**3. 配置回退顺序**
+
+```
+仪表盘 → 设置 → 回退优先级
+→ 拖动以重新排序每层内的提供商
+```
+
+自定义顺序示例:
+```
+第 1 层: Gemini CLI → Claude Code → Codex
+第 2 层: MiniMax → GLM → Kimi
+第 3 层: iFlow → Kiro → Qwen
+```
+
+**4. 配额重置通知**
+
+```
+仪表盘 → 设置 → 通知
+→ 配额重置时邮件提醒
+→ 配额使用 80% 时告警
+```
+
+---
+
+## 示例
+
+### 示例 1:基础自动回退
+
+**设置:**
+```
+Model: cc/claude-opus-4-5-20251101
+Fallback: 自动(默认 3 层)
+```
+
+**行为:**
+```
+早上(全新配额):
+  请求 → cc/claude-opus-4-5 ✅
+
+下午(配额耗尽):
+  请求 → glm/glm-4.7 ✅ (自动切换)
+
+晚上(GLM 配额用完):
+  请求 → minimax/MiniMax-M2.1 ✅ (自动切换)
+
+深夜(付费配额全部耗尽):
+  请求 → if/kimi-k2-thinking ✅ (免费层)
+```
+
+**成本**:额外约 $5-10/月(大部分由订阅覆盖)。
+
+### 示例 2:预算优先路由
+
+**设置:**
+```
+仪表盘 → 设置:
+  每日预算: $2
+  每月预算: $20
+  Fallback: 启用
+```
+
+**行为:**
+```
+1-15 日(预算内):
+  请求 → glm/glm-4.7 (低价层)
+  成本: $1.50/天
+
+第 16 日(达到预算):
+  请求 → if/kimi-k2-thinking (免费层)
+  成本: $0
+
+下月(预算重置):
+  请求 → 重新使用 glm/glm-4.7
+```
+
+**结果**:绝不超过 $20/月,始终可用。
+
+### 示例 3:仅订阅模式
+
+**设置:**
+```
+仪表盘 → 设置:
+  Auto Fallback: OFF
+  Strict mode: ON
+```
+
+**行为:**
+```
+请求 → cc/claude-opus-4-5
+  ✅ 配额可用 → 成功
+  ❌ 配额耗尽 → 返回错误(无回退)
+```
+
+**适用场景**:只想用付费订阅,绝不产生额外成本。
+
+### 示例 4:仅免费模式
+
+**设置:**
+```
+Model: if/kimi-k2-thinking
+Fallback: qw/qwen3-coder-plus → kr/claude-sonnet-4.5
+```
+
+**行为:**
+```
+所有请求 → 仅免费层
+成本: 永远 $0
+```
+
+**适用场景**:个人项目、学习、试验。
+
+---
+
+## 最佳实践
+
+### 1. 最大化订阅价值
+
+```
+策略:
+- 将订阅模型设为第 1 层
+- 在仪表盘监控配额使用
+- 仅在订阅耗尽时使用低价层
+```
+
+**示例组合:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 2. 成本优化
+
+```
+策略:
+- 先用 Gemini CLI 免费层(每月 180K)
+- 回退到 GLM/MiniMax(超低价)
+- 应急: iFlow(免费)
+```
+
+**示例组合:**
+```
+gc/gemini-3-flash-preview → glm/glm-4.7 → if/kimi-k2-thinking
+```
+
+### 3. 质量优先
+
+```
+策略:
+- 使用最佳模型(Claude Opus、GPT-5.2)
+- 回退到优秀的低价模型(GLM-4.7)
+- 最后手段: 免费层
+```
+
+**示例组合:**
+```
+cc/claude-opus-4-5 → cx/gpt-5.2-codex → glm/glm-4.7
+```
+
+### 4. 24/7 可用性
+
+```
+策略:
+- 回退链中总是包含免费层
+- 监控配额重置时间
+- 在多个提供商间分散使用
+```
+
+**示例组合:**
+```
+cc/claude-opus-4-5 → glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
+```
+
+**结果**:永不耗尽配额,随时编码。
+
+---
+
+## 配额重置策略
+
+围绕配额重置时间规划使用:
+
+| 提供商 | 配额重置 | 策略 |
+|----------|-------------|----------|
+| **Claude Code** | 5 小时 + 每周 | 早上使用,配额最新鲜 |
+| **Codex** | 5 小时 + 每周 | Claude 配额用完后使用 |
+| **Gemini CLI** | 每日(1K)+ 每月(180K) | 全天均匀使用 |
+| **GLM-4.7** | 每日 10:00 AM | 晚上使用,次日上午重置 |
+| **MiniMax M2.1** | 5 小时滚动 | 任意时间用,跟踪滚动窗口 |
+| **iFlow/Qwen/Kiro** | 无限制 | 应急备用 |
+
+**日常安排示例:**
+```
+08:00 - 13:00: Claude Code(全新 5h 配额)
+13:00 - 18:00: Gemini CLI(每日 1K 配额)
+18:00 - 22:00: GLM-4.7(便宜,10AM 重置)
+22:00 - 08:00: MiniMax 或 iFlow(5h 滚动 或 免费)
+```
+
+---
+
+## 监控与告警
+
+### 仪表盘配额跟踪
+
+```
+仪表盘 → 配额概览:
+  Claude Code: 剩余 2.5h / 5h (50%)
+  Gemini CLI: 今日 450 / 1000 次请求
+  GLM-4.7: 5M / 10M tokens (8h 后重置)
+  MiniMax: 3M / 5M tokens (5h 滚动)
+```
+
+### 实时通知
+
+```
+仪表盘 → 通知:
+  ⚠️ Claude Code 配额使用 80%(剩 1h)
+  ✅ GLM-4.7 配额已重置(10M tokens 可用)
+  💰 每日预算使用 50%($2.50 / $5)
+```
+
+### 使用分析
+
+```
+仪表盘 → 分析:
+  今日: 50M tokens
+    - 30M 通过 Claude Code(订阅)
+    - 15M 通过 GLM-4.7($9)
+    - 5M 通过 iFlow(免费)
+  
+  成本: $9(对比 ChatGPT API $1000)
+  节省: 99%
+```
+
+---
+
+## 故障排除
+
+**问题:"All providers quota exhausted"**
+
+**方案:**
+1. 查看仪表盘配额跟踪
+2. 等待配额重置(查看倒计时)
+3. 在回退链中加入免费层
+4. 或提高预算上限
+
+**问题:"Too many fallback switches"**
+
+**方案:**
+1. 检查主提供商是否宕机
+2. 提高配额上限(升级订阅)
+3. 使用更便宜的主模型(用 GLM 代替 Claude)
+
+**问题:"Unexpected costs"**
+
+**方案:**
+1. 仪表盘 → 分析 → 查看使用情况
+2. 设置每日/每月预算上限
+3. 非关键任务切换到免费层
+4. 使用带免费回退的组合
+
+---
+
+## 相关
+
+- [组合](./combos.md) - 创建自定义回退链
+- [配额跟踪](./quota-tracking.md) - 监控使用与成本
diff --git a/gitbook/content/zh-CN/getting-started/installation.md b/gitbook/content/zh-CN/getting-started/installation.md
new file mode 100644
index 0000000..07160d9
--- /dev/null
+++ b/gitbook/content/zh-CN/getting-started/installation.md
@@ -0,0 +1,478 @@
+# 安装
+
+9Router 的详细安装指南,附故障排除技巧。
+
+---
+
+## 要求
+
+### 系统要求
+
+- **Node.js**:版本 20.0.0 或更高
+- **npm**:版本 10.0.0 或更高(随 Node.js 安装)
+- **OS**:macOS、Linux、Windows(推荐 WSL)
+- **磁盘空间**:安装约需 200MB
+
+### 查看版本
+
+```bash
+node --version
+# 应显示 v20.x.x 或更高
+
+npm --version
+# 应显示 10.x.x 或更高
+```
+
+**没有 Node.js?** 从 [nodejs.org](https://nodejs.org/) 安装
+
+---
+
+## 安装方式
+
+### 方式 1:全局安装(推荐)
+
+全局安装,任何位置都能使用:
+
+```bash
+npm install -g 9router
+```
+
+**启动 9Router:**
+
+```bash
+9router
+```
+
+**优势:**
+- ✅ 任意目录均可运行
+- ✅ 命令简单:`9router`
+- ✅ 通过 `npm update -g 9router` 自动更新
+
+### 方式 2:本地安装
+
+在特定项目中安装:
+
+```bash
+mkdir my-9router
+cd my-9router
+npm install 9router
+```
+
+**启动 9Router:**
+
+```bash
+npx 9router
+```
+
+**优势:**
+- ✅ 项目隔离
+- ✅ 项目级版本控制
+- ✅ 不污染全局命名空间
+
+### 方式 3:源码安装(开发用)
+
+从 GitHub 克隆并构建:
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install
+npm run build
+npm start
+```
+
+**优势:**
+- ✅ 最新开发特性
+- ✅ 可参与开发
+- ✅ 可自定义修改
+
+---
+
+## 首次运行
+
+### 启动服务器
+
+```bash
+9router
+```
+
+**发生了什么:**
+1. 服务器启动在 `http://localhost:20128`
+2. 仪表盘在浏览器中自动打开
+3. 数据目录创建在 `~/.9router`
+4. API key 自动生成
+
+### 仪表盘登录
+
+**默认凭据:**
+- 密码:`123456`
+
+**⚠️ 立即修改密码:**
+1. 登录仪表盘
+2. 设置 → 修改密码
+3. 使用强密码
+
+### 获取 API Key
+
+```
+仪表盘 → 设置 → API Keys
+→ 复制你的 API key
+→ 在 CLI 工具中使用
+```
+
+**API key 格式示例:**
+```
+9r_1234567890abcdef1234567890abcdef
+```
+
+---
+
+## 验证安装
+
+### 检查服务器状态
+
+```bash
+curl http://localhost:20128/health
+```
+
+**预期响应:**
+```json
+{
+  "status": "ok",
+  "version": "1.0.0"
+}
+```
+
+### 列出可用模型
+
+```bash
+curl http://localhost:20128/v1/models \
+  -H "Authorization: Bearer your-api-key"
+```
+
+**预期响应:**
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "cc/claude-opus-4-5-20251101",
+      "object": "model",
+      "created": 1234567890,
+      "owned_by": "claude-code"
+    }
+  ]
+}
+```
+
+### 测试 Chat Completion
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "cc/claude-opus-4-5-20251101",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+---
+
+## 配置
+
+### 环境变量
+
+创建 `.env` 文件或设置环境变量:
+
+```bash
+# Security (REQUIRED in production)
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+
+# Storage
+export DATA_DIR="~/.9router"
+
+# Server
+export PORT="20128"
+export NODE_ENV="production"
+
+# Logging
+export ENABLE_REQUEST_LOGS="false"
+```
+
+### 数据目录
+
+**默认位置:** `~/.9router`
+
+**内容:**
+```
+~/.9router/
+  ├── db.json           # 数据库(提供商、组合、使用)
+  ├── api-keys.json     # API keys
+  └── logs/             # 请求日志(若启用)
+```
+
+**修改位置:**
+
+```bash
+export DATA_DIR="/custom/path"
+9router
+```
+
+### 端口配置
+
+**默认端口:** `20128`
+
+**修改端口:**
+
+```bash
+export PORT="3000"
+9router
+```
+
+**或用命令行:**
+
+```bash
+9router --port 3000
+```
+
+---
+
+## 故障排除
+
+### 端口已被占用
+
+**错误:**
+```
+Error: listen EADDRINUSE: address already in use :::20128
+```
+
+**方案 1:杀掉占用进程**
+
+```bash
+# 找到使用 20128 端口的进程
+lsof -i :20128
+
+# 杀掉进程
+kill -9 <PID>
+```
+
+**方案 2:使用其他端口**
+
+```bash
+9router --port 3000
+```
+
+### 权限被拒绝
+
+**错误:**
+```
+Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
+```
+
+**方案:使用 sudo(不推荐)或修复 npm 权限**
+
+```bash
+# 修复 npm 权限(推荐)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# 然后重新安装
+npm install -g 9router
+```
+
+### Node.js 版本过低
+
+**错误:**
+```
+Error: The engine "node" is incompatible with this module
+```
+
+**方案:更新 Node.js**
+
+```bash
+# 使用 nvm(推荐)
+nvm install 20
+nvm use 20
+
+# 或从 nodejs.org 下载
+```
+
+### 仪表盘无法打开
+
+**问题:** 仪表盘没有自动打开
+
+**方案 1:手动打开**
+
+```
+http://localhost:20128
+```
+
+**方案 2:检查防火墙**
+
+```bash
+# macOS: 在 System Preferences → Security 中允许 Node.js
+# Linux: 检查 iptables
+# Windows: 检查 Windows Firewall
+```
+
+### 无法连接提供商
+
+**问题:** OAuth 登录失败或 API key 无效
+
+**方案 1:检查网络连接**
+
+```bash
+ping google.com
+```
+
+**方案 2:检查提供商状态**
+
+- Claude Code: [status.anthropic.com](https://status.anthropic.com)
+- OpenAI: [status.openai.com](https://status.openai.com)
+- Gemini: [status.cloud.google.com](https://status.cloud.google.com)
+
+**方案 3:重新生成 API key**
+
+```
+仪表盘 → 提供商 → 断开 → 重新连接
+```
+
+### 内存占用过高
+
+**问题:** 9Router 占用过多 RAM
+
+**方案:重启服务器**
+
+```bash
+# 停止
+pkill -f 9router
+
+# 启动
+9router
+```
+
+**或用 PM2 自动重启:**
+
+```bash
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+```
+
+---
+
+## 部署选项
+
+### 本地开发
+
+```bash
+npm install -g 9router
+9router
+```
+
+**适用场景:** 个人编码、测试
+
+### VPS/云服务器
+
+```bash
+# 安装
+npm install -g 9router
+
+# 配置
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+# 用 PM2 启动
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+pm2 startup
+```
+
+**适用场景:** 团队访问、远程编码
+
+### Docker
+
+```bash
+docker pull 9router/9router:latest
+
+docker run -d \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret" \
+  -e INITIAL_PASSWORD="your-password" \
+  -v 9router-data:/root/.9router \
+  --name 9router \
+  9router/9router:latest
+```
+
+**适用场景:** 容器化部署、Kubernetes
+
+### 反向代理(Nginx)
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        
+        # SSE support for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+**适用场景:** HTTPS、自定义域名、负载均衡
+
+---
+
+## 卸载
+
+### 移除全局安装
+
+```bash
+npm uninstall -g 9router
+```
+
+### 移除数据目录
+
+```bash
+rm -rf ~/.9router
+```
+
+### 移除配置
+
+```bash
+# 从 shell 配置中移除环境变量
+nano ~/.bashrc  # 或 ~/.zshrc
+# 删除 9router 相关的 export
+```
+
+---
+
+## 下一步
+
+- [入门指南](../getting-started.md) - 连接提供商并开始编码
+- [功能特性](../features/) - 探索配额跟踪、组合、部署
+- [故障排除](../troubleshooting.md) - 解决常见问题
+
+---
+
+## 需要帮助?
+
+- **网站**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
diff --git a/gitbook/content/zh-CN/getting-started/quick-start.md b/gitbook/content/zh-CN/getting-started/quick-start.md
new file mode 100644
index 0000000..42207ce
--- /dev/null
+++ b/gitbook/content/zh-CN/getting-started/quick-start.md
@@ -0,0 +1,247 @@
+# 入门指南
+
+5 分钟启动 9Router,开始智能路由 AI 请求。
+
+---
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+npm install -g 9router
+```
+
+**要求:** Node.js 20+([安装详情](getting-started/installation.md))
+
+### 2. 启动
+
+```bash
+9router
+```
+
+🎉 **仪表盘自动打开** 地址为 `http://localhost:20128`
+
+- 默认密码:`123456`(在仪表盘中修改)
+- API key 自动生成
+- 可立即连接提供商
+
+### 3. 连接提供商
+
+有 3 种方式连接提供商:
+
+#### 方式 A:OAuth(订阅型提供商)
+
+**适用于:** Claude Code、Codex、Gemini CLI、GitHub Copilot
+
+```
+仪表盘 → 提供商 → 连接 [提供商]
+→ OAuth 登录 → 自动刷新 token
+→ 启用配额跟踪
+```
+
+**示例:Claude Code**
+1. 点击 "Connect Claude Code"
+2. 用你的 Claude 账户登录
+3. 授权 9Router
+4. ✅ 完成!使用模型:`cc/claude-opus-4-5-20251101`
+
+#### 方式 B:API Key(低价提供商)
+
+**适用于:** GLM、MiniMax、Kimi、OpenRouter
+
+```
+仪表盘 → 提供商 → 添加 API Key
+→ 选择提供商
+→ 粘贴 API key
+→ 保存
+```
+
+**示例:GLM-4.7**
+1. 在 [Zhipu AI](https://open.bigmodel.cn/) 注册
+2. 从 Coding Plan 获取 API key
+3. 仪表盘 → 添加 API Key → 提供商:`glm` → 粘贴 key
+4. ✅ 完成!使用模型:`glm/glm-4.7`
+
+#### 方式 C:免费提供商(零成本)
+
+**适用于:** iFlow、Qwen、Kiro
+
+```
+仪表盘 → 提供商 → 连接 [免费提供商]
+→ 设备码或 OAuth
+→ 无限使用
+```
+
+**示例:iFlow**
+1. 点击 "Connect iFlow"
+2. 用 iFlow 账户登录
+3. 授权
+4. ✅ 完成!使用 8 个模型:`if/kimi-k2-thinking`、`if/qwen3-coder-plus` 等
+
+---
+
+## 4. 在 CLI 工具中使用
+
+将你的编码工具指向 9Router:
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [从 9router 仪表盘获取]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Claude Desktop
+
+编辑 `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [从仪表盘获取]
+Model: cc/claude-opus-4-5-20251101
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+---
+
+## 5. 创建智能组合(可选)
+
+组合(Combos)可在多个模型之间实现自动回退:
+
+```
+仪表盘 → 组合 → 新建
+
+名称: premium-coding
+模型:
+  1. cc/claude-opus-4-5-20251101 (订阅主力)
+  2. glm/glm-4.7 (低价备用, $0.6/1M)
+  3. if/kimi-k2-thinking (免费回退)
+
+CLI 中使用: premium-coding
+```
+
+**工作原理:**
+1. 先尝试 Claude Opus(你的订阅)
+2. 配额耗尽 → GLM-4.7(超低价)
+3. 预算上限 → iFlow(免费)
+4. 零停机,自动切换!
+
+---
+
+## 可用模型
+
+### 订阅型模型(优先使用)
+
+**Claude Code (`cc/`)** - Pro/Max 订阅:
+- `cc/claude-opus-4-5-20251101` - Claude 4.5 Opus
+- `cc/claude-sonnet-4-5-20250929` - Claude 4.5 Sonnet
+- `cc/claude-haiku-4-5-20251001` - Claude 4.5 Haiku
+
+**Codex (`cx/`)** - Plus/Pro 订阅:
+- `cx/gpt-5.2-codex` - GPT 5.2 Codex
+- `cx/gpt-5.1-codex-max` - GPT 5.1 Codex Max
+
+**Gemini CLI (`gc/`)** - 每月免费 180K:
+- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
+- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
+
+**GitHub Copilot (`gh/`)** - 订阅:
+- `gh/gpt-5` - GPT-5
+- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
+
+### 低价模型(备用)
+
+**GLM (`glm/`)** - 每 1M $0.6/$2.2:
+- `glm/glm-4.7` - GLM 4.7(每日 10AM 重置)
+
+**MiniMax (`minimax/`)** - 每 1M $0.20/$1.00:
+- `minimax/MiniMax-M2.1` - MiniMax M2.1(5h 重置)
+
+**Kimi (`kimi/`)** - $9/月(10M tokens):
+- `kimi/kimi-latest` - Kimi Latest
+
+### 免费模型(应急)
+
+**iFlow (`if/`)** - 8 个免费模型:
+- `if/kimi-k2-thinking` - Kimi K2 Thinking
+- `if/qwen3-coder-plus` - Qwen3 Coder Plus
+- `if/glm-4.7` - GLM 4.7
+- `if/deepseek-r1` - DeepSeek R1
+
+**Qwen (`qw/`)** - 3 个免费模型:
+- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
+- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
+
+**Kiro (`kr/`)** - 2 个免费模型:
+- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
+- `kr/claude-haiku-4.5` - Claude Haiku 4.5
+
+---
+
+## 成本优化策略
+
+### 月度预算:$10-20/月
+
+```
+1. 用 Gemini CLI 免费层(每月 180K)处理快速任务
+2. 用足 Claude Code 订阅配额(你已经付费了)
+3. 配额用完后回退到 GLM(每 1M $0.6)
+4. 应急: MiniMax M2.1(每 1M $0.20)或 iFlow(免费)
+
+真实案例(每月 100M tokens):
+  60M 通过 Gemini CLI: $0(免费层)
+  30M 通过 Claude Code: $0(你已有的订阅)
+  8M 通过 GLM: $4.80
+  2M 通过 MiniMax: $0.40
+  合计: $5.20/月 + 已有订阅
+```
+
+### 配额重置策略
+
+```
+日常安排:
+1. 早上: 全新的 Claude Code 配额(5h 重置)
+2. 下午: 切换到 Gemini CLI(每日 1K)
+3. 晚上: GLM 每日配额(次日 10AM 重置)
+4. 深夜: MiniMax(5h 滚动)或 iFlow(免费)
+
+→ 24/7 编码,几乎零额外成本!
+```
+
+---
+
+## 下一步
+
+- [安装详情](getting-started/installation.md) - 要求与故障排除
+- [功能特性](features/) - 探索配额跟踪、组合、部署
+- [常见问题](faq.md) - 常见问题与解答
+- [故障排除](troubleshooting.md) - 解决常见问题
+
+---
+
+## 需要帮助?
+
+- **网站**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
diff --git a/gitbook/content/zh-CN/index.md b/gitbook/content/zh-CN/index.md
new file mode 100644
index 0000000..8999837
--- /dev/null
+++ b/gitbook/content/zh-CN/index.md
@@ -0,0 +1,164 @@
+# 欢迎使用 9Router
+
+**免费使用 Claude、Codex、Gemini • 超低价替代方案,每 1M token 仅需 $0.20**
+
+9Router 是一款 AI 模型路由工具,通过智能路由和自动回退机制,最大化你的订阅价值并最小化成本。
+
+---
+
+## 什么是 9Router?
+
+9Router 是一款智能代理,位于你的编码工具(Cursor、Cline、Claude Desktop)与 AI 提供商之间。它会根据配额、成本和可用性,自动将请求路由到最合适的模型。
+
+**告别浪费:**
+- ❌ 订阅配额每月未用完就过期
+- ❌ 速率限制让你写代码写到一半被卡住
+- ❌ 昂贵的 API(每个提供商每月 $20-50)
+- ❌ 在不同提供商之间手动切换
+
+**开始最大化价值:**
+- ✅ **充分利用订阅** - 跟踪并用完 Claude Code、Codex、Gemini 的每一点配额
+- ✅ **免费可用** - 通过 CLI 访问 iFlow、Qwen、Kiro 模型
+- ✅ **超低价备用** - GLM(每 1M $0.6)、MiniMax M2.1(每 1M $0.20)
+- ✅ **智能回退** - 订阅 → 低价 → 免费,自动切换
+
+---
+
+## 核心特性
+
+### 🔄 智能三层回退
+
+```
+一次配置,永不停码:
+
+第 1 层(订阅): Claude Code → Codex → Gemini
+  ↓ 配额耗尽
+第 2 层(低价): GLM-4.7 → MiniMax M2.1 → Kimi
+  ↓ 预算上限
+第 3 层(免费): iFlow → Qwen → Kiro
+
+→ 自动切换,零停机!
+```
+
+### 📊 配额跟踪
+
+- 每个提供商的实时 token 消耗
+- 重置倒计时(5 小时、每日、每周、每月)
+- 付费层级的成本估算
+- 每月支出报告
+
+### 🎯 通用 CLI 支持
+
+适用于所有支持自定义 OpenAI endpoint 的工具:
+
+✅ **Cursor** • **Cline** • **Claude Desktop** • **Codex** • **RooCode** • **Continue** • **任何 OpenAI 兼容工具**
+
+### 💰 成本优化
+
+**真实案例(每月 100M tokens):**
+```
+60M 通过 Gemini CLI: $0(免费层)
+30M 通过 Claude Code: $0(你已有的订阅)
+8M 通过 GLM: $4.80
+2M 通过 MiniMax: $0.40
+合计: $5.20/月,而 ChatGPT API 需要 $2000!
+```
+
+---
+
+## 为什么选择 9Router?
+
+### 最大化订阅价值
+
+已经在为 Claude Code(每月 $20-100)或 Codex(每月 $20-200)付费?那就用足它:
+
+- 实时跟踪配额使用
+- 配额重置时(5 小时、每周)自动切换
+- 在过期前用掉每一个 token
+- Gemini CLI:每月 180K 次补全 **免费**
+
+### 超低价备用
+
+订阅配额用完时,只需花几分钱:
+
+| 提供商 | 每 1M tokens 成本 | 重置时间 |
+|----------|-------------------|-------|
+| **GLM-4.7** | 输入 $0.60 / 输出 $2.20 | 每日 10:00 AM |
+| **MiniMax M2.1** | 输入 $0.20 / 输出 $1.00 | 5 小时滚动 |
+| **Kimi K2** | $9/月(10M tokens) | 每月 |
+
+**比 ChatGPT API(每 1M $20)便宜约 90%!**
+
+### 永久免费回退
+
+当其他一切都受配额限制时的应急备用:
+
+- **iFlow**:8 个模型(Kimi K2、Qwen3 Coder Plus、GLM 4.7、MiniMax M2)
+- **Qwen**:3 个模型(Qwen3 Coder Plus/Flash、Vision)
+- **Kiro**:Claude Sonnet 4.5、Haiku 4.5(AWS Builder ID)
+
+---
+
+## 快速开始
+
+2 分钟即可上手:
+
+```bash
+# 全局安装
+npm install -g 9router
+
+# 启动(仪表盘自动打开)
+9router
+```
+
+🎉 **仪表盘自动打开** → 连接提供商 → 开始编码!
+
+**在你的 CLI 工具中使用:**
+
+```
+Endpoint: http://localhost:20128/v1
+API Key: [从仪表盘获取]
+Model: cc/claude-opus-4-5-20251101
+```
+
+[→ 完整入门指南](getting-started.md)
+
+---
+
+## 使用场景
+
+### 个人开发者
+
+- 最大化你的 Claude Code/Codex 订阅
+- 使用 Gemini CLI 免费层(每月 180K)
+- 回退到超低价模型(每 1M $0.20)
+- 24/7 编码不受速率限制
+
+### 团队
+
+- 部署在 VPS/云服务器上共享访问
+- 实时跟踪团队支出
+- 为每层设置预算上限
+- 集中管理提供商
+
+### 移动/远程编码
+
+- 使用云端部署(https://9router.com)
+- 从 iPad、手机、任何地方访问
+- 没有 localhost 限制
+- Cloudflare 边缘网络(300+ 节点)
+
+---
+
+## 接下来做什么?
+
+- [入门指南](getting-started.md) - 5 分钟内完成安装和配置
+- [安装指南](getting-started/installation.md) - 详细的设置说明
+- [功能特性](features/) - 探索所有能力
+- [常见问题](faq.md) - 常见问题解答
+
+---
+
+<div align="center">
+  <sub>用 ❤️ 为最大化 AI 价值的开发者打造</sub>
+</div>
diff --git a/gitbook/content/zh-CN/integration/claude-code.md b/gitbook/content/zh-CN/integration/claude-code.md
new file mode 100644
index 0000000..4c0dcd4
--- /dev/null
+++ b/gitbook/content/zh-CN/integration/claude-code.md
@@ -0,0 +1,109 @@
+# Claude Code 集成
+
+将 9Router 与 Claude Code CLI 集成,通过 9Router 的智能路由系统转发你的 Anthropic API 请求。
+
+## 前置要求
+
+- 已安装 Claude Code CLI
+- 9Router 本地运行或已配置云端 endpoint
+- 来自 9Router 仪表盘的 API key
+
+## 设置
+
+### 1. 配置环境变量
+
+在 shell 配置文件(`~/.bashrc`、`~/.zshrc` 或 `~/.bash_profile`)中设置以下环境变量:
+
+```bash
+# 9Router 的 Base URL
+export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
+
+# 可选: 为别名设置默认模型
+export ANTHROPIC_DEFAULT_OPUS_MODEL="cc/claude-opus-4-5-20251101"
+export ANTHROPIC_DEFAULT_SONNET_MODEL="cc/claude-sonnet-4-5-20250929"
+export ANTHROPIC_DEFAULT_HAIKU_MODEL="cc/claude-haiku-4-5-20251001"
+```
+
+### 2. 重新加载 Shell 配置
+
+```bash
+source ~/.zshrc  # 或 ~/.bashrc
+```
+
+### 3. 验证配置
+
+检查环境变量是否设置正确:
+
+```bash
+echo $ANTHROPIC_BASE_URL
+```
+
+## 模型别名
+
+Claude Code 支持以下模型别名,映射到 9Router 模型:
+
+| 别名 | 模型 | 环境变量 |
+|-------|-------|---------------------|
+| `opus` | Claude Opus 4.5 | `ANTHROPIC_DEFAULT_OPUS_MODEL` |
+| `sonnet` | Claude Sonnet 4.5 | `ANTHROPIC_DEFAULT_SONNET_MODEL` |
+| `haiku` | Claude Haiku 4.5 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` |
+
+## 使用示例
+
+### 使用模型别名
+
+```bash
+# 使用 Opus 模型
+claude --model opus "Explain quantum computing"
+
+# 使用 Sonnet 模型
+claude --model sonnet "Write a Python function"
+
+# 使用 Haiku 模型
+claude --model haiku "Quick code review"
+```
+
+### 使用完整模型名
+
+```bash
+claude --model cc/claude-opus-4-5-20251101 "Your prompt here"
+```
+
+## 配置文件
+
+Claude Code 将配置存储在 `~/.claude/settings.json`。如有需要可手动编辑:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "defaultModel": "sonnet"
+}
+```
+
+## 故障排除
+
+### 连接问题
+
+遇到连接错误时:
+
+1. 确认 9Router 正在运行:`curl http://localhost:20128/health`
+2. 检查环境变量设置是否正确
+3. 确保防火墙没有阻止 20128 端口
+
+### 模型未找到
+
+出现 "model not found" 错误时:
+
+1. 确认模型名与 9Router 配置一致
+2. 检查 9Router 仪表盘中提供商连接是否激活
+3. 确认所连接的提供商中包含该模型
+
+## 云端 Endpoint
+
+使用 9Router 云端 endpoint 而非 localhost:
+
+```bash
+export ANTHROPIC_BASE_URL="https://9router.com"
+```
+
+确保已在 9Router 云端仪表盘中配置 API key。
diff --git a/gitbook/content/zh-CN/integration/cline.md b/gitbook/content/zh-CN/integration/cline.md
new file mode 100644
index 0000000..1a023ba
--- /dev/null
+++ b/gitbook/content/zh-CN/integration/cline.md
@@ -0,0 +1,201 @@
+# Cline 集成
+
+将 9Router 与 Cline VSCode 扩展集成,通过 9Router 的智能路由系统转发你的 AI 请求。
+
+## 前置要求
+
+- 已安装 Visual Studio Code
+- 从 VSCode 市场安装了 Cline 扩展
+- 9Router 本地运行或已配置云端 endpoint
+- 来自 9Router 仪表盘的 API key
+
+## 设置
+
+### 1. 打开 Cline 设置
+
+1. 打开 Visual Studio Code
+2. 打开 Cline 扩展面板(点击侧边栏的 Cline 图标)
+3. 点击 Cline 面板中的 **Settings**(齿轮图标)
+
+### 2. 选择 API Provider
+
+1. 在 Cline 设置中找到 **API Provider** 下拉菜单
+2. 从列表中选择 **Ollama**
+   - 注意:我们使用 Ollama provider 类型,因为它与 OpenAI 风格 API 兼容
+
+### 3. 配置 Base URL
+
+将 base URL 设为你的 9Router endpoint:
+
+**本地 9Router:**
+```
+http://localhost:20128/v1
+```
+
+**云端 9Router:**
+```
+https://9router.com
+```
+
+**步骤:**
+1. 在 **Base URL** 字段中输入你的 9Router endpoint
+2. 末尾必须包含 `/v1`
+
+### 4. 添加 API Key
+
+1. 在 **API Key** 字段中输入你的 9Router API key
+2. 可在 9Router 仪表盘 **Settings → API Keys** 中找到 API key
+3. key 应以 `sk-9router-` 开头
+
+### 5. 选择模型
+
+1. 在 **Model** 下拉菜单中,可以:
+   - 从可用模型中选择(若 Cline 自动检测)
+   - 或手动输入 9Router 配置中的模型名
+
+2. 常见模型名:
+   - `gpt-4`
+   - `gpt-4o`
+   - `claude-opus-4-5`
+   - `claude-sonnet-4-5`
+   - `gemini-2.0-flash`
+
+### 6. 保存配置
+
+点击 **Save** 或关闭设置面板。Cline 会自动保存你的配置。
+
+## 配置示例
+
+你的 Cline 设置应如下所示:
+
+```
+API Provider: Ollama
+Base URL: http://localhost:20128/v1
+API Key: sk-9router-xxxxxxxxxxxxx
+Model: gpt-4
+```
+
+## 可用模型
+
+你可以使用 9Router 仪表盘中配置的任意模型。常见示例:
+
+| 模型名 | 提供商 | 描述 |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## 使用
+
+### 与 AI 对话
+
+1. 在 VSCode 中打开 Cline 面板
+2. 在聊天输入框中输入消息
+3. 按 Enter 发送
+4. Cline 会通过 9Router 处理你的请求
+
+### 生成代码
+
+1. 让 Cline 生成代码:"创建一个登录表单的 React 组件"
+2. Cline 会通过 9Router 生成代码
+3. 检查并接受生成的代码
+
+### 代码解释
+
+1. 在编辑器中选中代码
+2. 让 Cline:"解释这段代码"
+3. 通过 9Router 获得 AI 驱动的解释
+
+### 文件操作
+
+1. 让 Cline 创建、修改或删除文件
+2. Cline 会通过 9Router 理解上下文并进行修改
+3. 在接受前检查变更
+
+## 故障排除
+
+### "Connection Failed" 错误
+
+1. 确认 9Router 正在运行:`curl http://localhost:20128/health`
+2. 确认 base URL 正确且包含 `/v1`
+3. 确保防火墙没有阻止 20128 端口
+4. 尝试重启 VSCode
+
+### "Invalid API Key" 错误
+
+1. 在 9Router 仪表盘中确认 API key
+2. 确保复制了包含 `sk-9router-` 前缀在内的完整 key
+3. 检查 API key 是否过期
+4. 尝试重新生成 API key
+
+### "Model Not Found" 错误
+
+1. 确认模型名与 9Router 配置完全一致
+2. 检查 9Router 仪表盘中提供商连接是否激活
+3. 确认连接的提供商中包含该模型
+4. 尝试使用完整模型名(例如用 `openai/gpt-4` 代替 `gpt-4`)
+
+### Cline 无响应
+
+1. 查看 Cline 输出面板中的错误信息
+2. 确认 9Router 实例正在运行且健康
+3. 重新加载 VSCode 窗口(Cmd/Ctrl + Shift + P → "Reload Window")
+4. 检查 9Router 日志是否有错误
+
+## 高级配置
+
+### 使用云端 Endpoint
+
+使用 9Router 云端 endpoint 而非 localhost:
+
+1. 在 Cline 设置中将 Base URL 设为:`https://9router.com`
+2. 确保已在 9Router 云端仪表盘中配置 API key
+3. 确保云端 endpoint 已激活且可访问
+
+### 多个模型
+
+可以快速切换模型:
+
+1. 打开 Cline 设置
+2. 将 **Model** 字段改为另一个模型
+3. 保存并继续使用新模型对话
+
+### 自定义超时
+
+如果大请求出现超时:
+
+1. 打开 VSCode 设置(Cmd/Ctrl + ,)
+2. 搜索 "Cline timeout"
+3. 提高超时值(默认通常为 30 秒)
+
+## 最佳实践
+
+1. **使用合适的模型**:简单任务用更快的模型(如 Haiku 或 Flash),复杂任务用更强的模型(如 Opus 或 GPT-4)
+2. **监控使用**:在 9Router 仪表盘查看用量统计和成本
+3. **管理上下文**:保持对话聚焦以减少 token 用量
+4. **切换模型**:根据任务复杂度切换模型,优化成本和性能
+5. **API Key 安全**:绝不将 API key 提交到版本控制
+
+## 与 9Router 功能的集成
+
+### 模型路由
+
+9Router 会根据以下因素自动将请求路由到最佳提供商:
+- 模型可用性
+- 提供商健康状态
+- 成本优化
+- 负载均衡
+
+### 回退支持
+
+某个提供商失败时,9Router 会自动回退到仪表盘中配置的备用提供商。
+
+### 使用跟踪
+
+通过 9Router 仪表盘监控你的 Cline 使用:
+- 请求总数
+- Token 使用
+- 每个模型的成本
+- 提供商分布
diff --git a/gitbook/content/zh-CN/integration/codex.md b/gitbook/content/zh-CN/integration/codex.md
new file mode 100644
index 0000000..84e307d
--- /dev/null
+++ b/gitbook/content/zh-CN/integration/codex.md
@@ -0,0 +1,136 @@
+# OpenAI Codex CLI 集成
+
+将 9Router 与 OpenAI Codex CLI 集成,通过 9Router 的智能路由系统转发你的 OpenAI API 请求。
+
+## 前置要求
+
+- 已安装 OpenAI Codex CLI
+- 9Router 本地运行或已配置云端 endpoint
+- 来自 9Router 仪表盘的 API key
+
+## 设置
+
+### 1. 配置环境变量
+
+在 shell 配置文件(`~/.bashrc`、`~/.zshrc` 或 `~/.bash_profile`)中设置以下环境变量:
+
+```bash
+# 9Router 的 Base URL
+export OPENAI_BASE_URL="http://localhost:20128/v1"
+
+# 来自 9Router 仪表盘的 API Key
+export OPENAI_API_KEY="your-9router-api-key"
+```
+
+### 2. 重新加载 Shell 配置
+
+```bash
+source ~/.zshrc  # 或 ~/.bashrc
+```
+
+### 3. 验证配置
+
+检查环境变量是否设置正确:
+
+```bash
+echo $OPENAI_BASE_URL
+echo $OPENAI_API_KEY
+```
+
+## 可用模型
+
+9Router 提供以下 Codex 模型:
+
+| 模型 ID | 描述 |
+|----------|-------------|
+| `cx/gpt-5.2-codex` | GPT-5.2 Codex - 最新版本 |
+| `cx/gpt-5.1-codex-max` | GPT-5.1 Codex Max - 扩展上下文 |
+
+## 使用示例
+
+### 基础用法
+
+```bash
+# 使用 GPT-5.2 Codex
+codex --model cx/gpt-5.2-codex "Write a function to sort an array"
+
+# 使用 GPT-5.1 Codex Max
+codex --model cx/gpt-5.1-codex-max "Explain this complex algorithm"
+```
+
+### 代码生成
+
+```bash
+codex --model cx/gpt-5.2-codex "Create a REST API endpoint for user authentication"
+```
+
+### 代码解释
+
+```bash
+codex --model cx/gpt-5.1-codex-max "Explain what this code does: $(cat myfile.js)"
+```
+
+## 配置文件
+
+也可以通过配置文件配置 Codex CLI。创建或编辑 `~/.codex/config.json`:
+
+```json
+{
+  "baseUrl": "http://localhost:20128/v1",
+  "apiKey": "your-9router-api-key",
+  "defaultModel": "cx/gpt-5.2-codex"
+}
+```
+
+## 故障排除
+
+### 认证错误
+
+遇到认证错误时:
+
+1. 在 9Router 仪表盘中确认 API key 正确
+2. 检查 `OPENAI_API_KEY` 环境变量已设置
+3. 确认 API key 未过期
+
+### 连接问题
+
+遇到连接错误时:
+
+1. 确认 9Router 正在运行:`curl http://localhost:20128/health`
+2. 检查环境变量设置是否正确
+3. 确保防火墙没有阻止 20128 端口
+
+### 模型不可用
+
+出现 "model not available" 错误时:
+
+1. 确认模型名与 9Router 配置一致
+2. 检查 9Router 仪表盘中 OpenAI 提供商连接是否激活
+3. 确认连接的提供商中包含该模型
+
+## 云端 Endpoint
+
+使用 9Router 云端 endpoint 而非 localhost:
+
+```bash
+export OPENAI_BASE_URL="https://9router.com"
+```
+
+确保已在 9Router 云端仪表盘中配置 API key。
+
+## 高级配置
+
+### 自定义超时
+
+```bash
+export OPENAI_TIMEOUT=60  # 秒
+```
+
+### Debug 模式
+
+启用 debug 模式查看详细请求/响应日志:
+
+```bash
+export CODEX_DEBUG=true
+codex --model cx/gpt-5.2-codex "Your prompt"
+```
diff --git a/gitbook/content/zh-CN/integration/continue.md b/gitbook/content/zh-CN/integration/continue.md
new file mode 100644
index 0000000..fdc3ac3
--- /dev/null
+++ b/gitbook/content/zh-CN/integration/continue.md
@@ -0,0 +1,249 @@
+# Continue VSCode 扩展集成
+
+将 9Router 与 Continue 扩展集成,直接在 Visual Studio Code 中获得 AI 协助。
+
+## 前置要求
+
+- 已安装 Visual Studio Code
+- 从 VSCode 市场安装了 Continue 扩展
+- 来自 [仪表盘](https://9router.com/dashboard) 的 9Router API key
+- 9Router 正在运行(本地或云端)
+
+## 配置步骤
+
+### 1. 打开 Continue 配置
+
+1. 打开 VSCode
+2. 按 `Cmd+Shift+P` (Mac) 或 `Ctrl+Shift+P` (Windows/Linux)
+3. 输入 "Continue: Open Config" 并选择
+4. 这会打开 `~/.continue/config.json`
+
+### 2. 添加 9Router 模型配置
+
+将以下配置添加到 `config.json`:
+
+**单模型设置:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**多模型设置:**
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Claude Opus (Best)",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Sonnet (Balanced)",
+      "provider": "openai",
+      "model": "cc/claude-sonnet-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - DeepSeek Chat (Code)",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    },
+    {
+      "title": "9Router - Claude Haiku (Fast)",
+      "provider": "openai",
+      "model": "cc/claude-haiku-4-20250514",
+      "apiKey": "your-api-key-from-dashboard",
+      "apiBase": "http://localhost:20128/v1"
+    }
+  ]
+}
+```
+
+**云端 9Router:**
+将 `apiBase` 替换为:
+```json
+"apiBase": "https://9router.com/v1"
+```
+
+### 3. 保存并重新加载
+
+1. 保存配置文件
+2. 重新加载 VSCode 窗口:`Cmd+Shift+P` → "Developer: Reload Window"
+3. Continue 扩展会加载新配置
+
+### 4. 选择模型
+
+1. 打开 Continue 侧边栏(点击左侧 Continue 图标)
+2. 点击顶部模型选择下拉菜单
+3. 选择你偏好的 9Router 模型
+
+## 可用模型
+
+### Claude 模型(Anthropic)
+- `cc/claude-opus-4-5-20251101` - 最强,适合复杂任务
+- `cc/claude-sonnet-4-20250514` - 性能与速度平衡
+- `cc/claude-haiku-4-20250514` - 最快,适合简单任务
+
+### DeepSeek 模型
+- `cx/deepseek-chat` - 出色的代码生成
+- `cx/deepseek-reasoner` - 复杂问题求解
+
+### GLM 模型(Zhipu AI)
+- `glm/glm-4-plus` - 高级中文与英文
+- `glm/glm-4-flash` - 快速响应
+
+## 使用示例
+
+### 代码解释
+1. 在编辑器中选中代码
+2. 打开 Continue 侧边栏
+3. 输入:"Explain this code"
+4. 模型:`cc/claude-sonnet-4-20250514`
+
+### 代码生成
+1. 打开 Continue 侧边栏
+2. 输入:"Create a React component for user profile card"
+3. 模型:`cx/deepseek-chat`
+
+### 重构
+1. 选中要重构的代码
+2. 输入:"Refactor this to use async/await"
+3. 模型:`cc/claude-sonnet-4-20250514`
+
+### Bug 修复
+1. 选中有问题的代码
+2. 输入:"Find and fix the bug in this code"
+3. 模型:`cx/deepseek-reasoner`
+
+## 高级配置
+
+### 自定义系统 Prompt
+
+为特定行为添加自定义系统 prompt:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Code Expert",
+      "provider": "openai",
+      "model": "cx/deepseek-chat",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "systemMessage": "You are an expert programmer. Always provide clean, well-documented code with best practices."
+    }
+  ]
+}
+```
+
+### Temperature 与参数
+
+通过参数调整模型行为:
+
+```json
+{
+  "models": [
+    {
+      "title": "9Router - Creative Writer",
+      "provider": "openai",
+      "model": "cc/claude-opus-4-5-20251101",
+      "apiKey": "your-api-key",
+      "apiBase": "http://localhost:20128/v1",
+      "temperature": 0.9,
+      "topP": 0.95
+    }
+  ]
+}
+```
+
+### Context Provider
+
+配置 Continue 发送给模型的上下文:
+
+```json
+{
+  "contextProviders": [
+    {
+      "name": "code",
+      "params": {
+        "maxLines": 100
+      }
+    },
+    {
+      "name": "diff",
+      "params": {}
+    },
+    {
+      "name": "terminal",
+      "params": {}
+    }
+  ]
+}
+```
+
+## 键盘快捷键
+
+- `Cmd+L` (Mac) / `Ctrl+L` (Windows/Linux) - 打开 Continue 聊天
+- `Cmd+I` (Mac) / `Ctrl+I` (Windows/Linux) - 内联编辑
+- `Cmd+Shift+R` (Mac) / `Ctrl+Shift+R` (Windows/Linux) - 重新生成响应
+
+## 故障排除
+
+### 模型无响应
+- 确认 9Router 正在运行:`curl http://localhost:20128/health`
+- 检查 config.json 中的 API key
+- 查看 VSCode 开发者控制台错误:`Help` → `Toggle Developer Tools`
+
+### 选错模型
+- 点击 Continue 侧边栏的模型下拉菜单
+- 选择正确的 9Router 模型
+- 模型名必须完全匹配(大小写敏感)
+
+### 配置未加载
+- 确认 JSON 语法有效(使用 JSON 验证工具)
+- 检查文件位置:`~/.continue/config.json`
+- 修改后重新加载 VSCode 窗口
+
+### 性能缓慢
+- 切换到更快的模型(haiku、flash)
+- 在 contextProviders 中减少上下文大小
+- 检查到 9Router 的网络延迟
+
+## 最佳实践
+
+### 模型选择策略
+- **快速编辑**:使用 `cc/claude-haiku-4-20250514`
+- **代码生成**:使用 `cx/deepseek-chat`
+- **复杂重构**:使用 `cc/claude-opus-4-5-20251101`
+- **问题求解**:使用 `cx/deepseek-reasoner`
+
+### 上下文管理
+- 提问前只选中相关代码
+- 使用具体、清晰的 prompt
+- 将复杂任务拆分为小步骤
+
+### 成本优化
+- 简单任务使用更快/更便宜的模型
+- 尽可能限制上下文大小
+- 缓存常用响应
+
+## 下一步
+
+- [配置 Cursor](cursor.md) 以增强 IDE 集成
+- [设置 Roo](roo.md) AI 助手
+- [探索 CLI 用法](../cli/basic-usage.md)
+- [了解模型选择](../models/overview.md)
diff --git a/gitbook/content/zh-CN/integration/cursor.md b/gitbook/content/zh-CN/integration/cursor.md
new file mode 100644
index 0000000..2b2c48b
--- /dev/null
+++ b/gitbook/content/zh-CN/integration/cursor.md
@@ -0,0 +1,149 @@
+# Cursor 集成
+
+将 9Router 与 Cursor IDE 集成,通过 9Router 的智能路由系统转发你的 AI 请求。
+
+## 前置要求
+
+- 已安装 Cursor IDE
+- Cursor Pro 账户(使用自定义 API endpoint 必需)
+- 已配置 9Router 云端 endpoint
+- 来自 9Router 仪表盘的 API key
+
+## ⚠️ 重要说明
+
+> **必须使用云端 Endpoint**:Cursor 会通过自己的服务器转发请求,不支持 localhost endpoint。你必须使用 9Router 云端 endpoint:`https://9router.com`
+
+> **必须有 Cursor Pro**:此功能需要 Cursor Pro 账户才能使用自定义 API endpoint。
+
+## 设置
+
+### 1. 打开 Cursor 设置
+
+1. 打开 Cursor IDE
+2. 进入 **Settings**(Cmd/Ctrl + ,)
+3. 导航到 **Models** 部分
+
+### 2. 启用 OpenAI API
+
+1. 找到 **OpenAI API key** 选项
+2. 启用开关以激活自定义 API 配置
+
+### 3. 配置 Base URL
+
+将 base URL 设为 9Router 云端 endpoint:
+
+```
+https://9router.com
+```
+
+**步骤:**
+1. 在 Models 设置中找到 **Base URL** 字段
+2. 输入:`https://9router.com`
+3. 点击 **Save**
+
+### 4. 添加 API Key
+
+1. 在 **API Key** 字段中输入你的 9Router API key
+2. 可在 9Router 仪表盘 **Settings → API Keys** 中找到 API key
+3. 点击 **Save**
+
+### 5. 添加自定义模型
+
+1. 点击 **View All Models** 按钮
+2. 点击 **Add Custom Model**
+3. 输入 9Router 配置中的模型名(例如 `gpt-4`、`claude-opus-4-5` 等)
+4. 点击 **Add**
+
+### 6. 选择模型
+
+1. 在 Cursor 聊天界面,点击模型选择下拉菜单
+2. 从列表中选择你的自定义模型
+3. 开始在 Cursor 中使用 9Router!
+
+## 配置示例
+
+你的 Cursor 设置应如下所示:
+
+```
+OpenAI API: ✓ 已启用
+Base URL: https://9router.com
+API Key: sk-9router-xxxxxxxxxxxxx
+Custom Models: gpt-4, claude-opus-4-5, gemini-2.0-flash
+```
+
+## 可用模型
+
+你可以使用 9Router 仪表盘中配置的任意模型。常见示例:
+
+| 模型名 | 提供商 | 描述 |
+|------------|----------|-------------|
+| `gpt-4` | OpenAI | GPT-4 Turbo |
+| `gpt-4o` | OpenAI | GPT-4 Optimized |
+| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
+| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
+
+## 使用
+
+### 聊天界面
+
+1. 打开 Cursor 聊天(Cmd/Ctrl + L)
+2. 从下拉菜单中选择模型
+3. 通过 9Router 与 AI 对话
+
+### 内联代码生成
+
+1. 在编辑器中选中代码
+2. 按 Cmd/Ctrl + K
+3. 输入 prompt
+4. Cursor 会通过 9Router 生成代码
+
+### 代码解释
+
+1. 在编辑器中选中代码
+2. 按 Cmd/Ctrl + L
+3. 询问 "Explain this code"
+4. 通过 9Router 获得 AI 驱动的解释
+
+## 故障排除
+
+### "Invalid API Key" 错误
+
+1. 在 9Router 仪表盘中确认 API key
+2. 确保复制了包含 `sk-9router-` 前缀在内的完整 key
+3. 检查 API key 是否过期
+4. 尝试重新生成 API key
+
+### "Model Not Found" 错误
+
+1. 确认模型名与 9Router 配置完全一致
+2. 检查 9Router 仪表盘中提供商连接是否激活
+3. 确认连接的提供商中包含该模型
+4. 尝试使用完整模型名(例如用 `openai/gpt-4` 代替 `gpt-4`)
+
+### 连接问题
+
+1. 确认使用的是云端 endpoint:`https://9router.com`
+2. 检查网络连接
+3. 确认 9Router 云端服务运行正常
+4. 若启用了 VPN 或代理,尝试关闭
+
+### Localhost 无法使用
+
+> **请记住**:Cursor 不支持 localhost endpoint。你必须使用云端 endpoint `https://9router.com`。如果需要使用本地 9Router 实例,可以考虑使用 ngrok 之类的隧道服务把本地 endpoint 暴露到公网。
+
+## 云端 Endpoint 设置
+
+如果你在本地运行 9Router 并希望搭配 Cursor 使用:
+
+1. 在 9Router 设置中启用云端 endpoint
+2. 在 9Router 仪表盘中配置云端 endpoint URL
+3. 在 Cursor 设置中使用该云端 URL
+4. 确保本地 9Router 实例可从互联网访问
+
+## 最佳实践
+
+1. **使用模型别名**:为常用模型在 9Router 中创建简短别名
+2. **监控使用**:在 9Router 仪表盘查看用量统计和成本
+3. **轮换 API Keys**:为安全起见定期轮换 API key
+4. **测试模型**:尝试不同模型,找到最适合你场景的那个
diff --git a/gitbook/content/zh-CN/integration/other-tools.md b/gitbook/content/zh-CN/integration/other-tools.md
new file mode 100644
index 0000000..8469230
--- /dev/null
+++ b/gitbook/content/zh-CN/integration/other-tools.md
@@ -0,0 +1,416 @@
+# 其他工具集成
+
+9Router 兼容任何支持 OpenAI API 格式的工具。本指南介绍各种工具和自定义应用的通用集成模式。
+
+## 概览
+
+9Router 提供 OpenAI 兼容的 API endpoint,可与以下场景配合使用:
+- 自定义脚本与应用
+- API 客户端与测试工具
+- CLI 工具与实用程序
+- 第三方集成
+- 开发框架
+
+## 通用设置模式
+
+任何 OpenAI 兼容的工具都可以通过以下设置连接到 9Router:
+
+**本地 9Router:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+Model: 任意 9Router 模型(cc/*, cx/*, glm/*, 等)
+```
+
+**云端 9Router:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+Model: 任意 9Router 模型(cc/*, cx/*, glm/*, 等)
+```
+
+## 可用模型
+
+### Claude 模型(Anthropic)
+- `cc/claude-opus-4-5-20251101`
+- `cc/claude-sonnet-4-20250514`
+- `cc/claude-haiku-4-20250514`
+
+### DeepSeek 模型
+- `cx/deepseek-chat`
+- `cx/deepseek-reasoner`
+
+### GLM 模型(Zhipu AI)
+- `glm/glm-4-plus`
+- `glm/glm-4-flash`
+
+## 集成示例
+
+### Python 使用 OpenAI SDK
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+response = client.chat.completions.create(
+    model="cc/claude-sonnet-4-20250514",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ]
+)
+
+print(response.choices[0].message.content)
+```
+
+### Node.js 使用 OpenAI SDK
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+const response = await client.chat.completions.create({
+  model: "cc/claude-sonnet-4-20250514",
+  messages: [
+    { role: "user", content: "Hello, how are you?" }
+  ]
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### cURL 命令
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-api-key-from-dashboard" \
+  -d '{
+    "model": "cc/claude-sonnet-4-20250514",
+    "messages": [
+      {"role": "user", "content": "Hello, how are you?"}
+    ]
+  }'
+```
+
+### HTTP 客户端(Postman、Insomnia)
+
+**Request:**
+```
+POST http://localhost:20128/v1/chat/completions
+```
+
+**Headers:**
+```
+Content-Type: application/json
+Authorization: Bearer your-api-key-from-dashboard
+```
+
+**Body:**
+```json
+{
+  "model": "cc/claude-sonnet-4-20250514",
+  "messages": [
+    {"role": "user", "content": "Hello, how are you?"}
+  ],
+  "temperature": 0.7,
+  "max_tokens": 1000
+}
+```
+
+### LangChain 集成
+
+```python
+from langchain.chat_models import ChatOpenAI
+from langchain.schema import HumanMessage
+
+llm = ChatOpenAI(
+    model_name="cc/claude-sonnet-4-20250514",
+    openai_api_key="your-api-key-from-dashboard",
+    openai_api_base="http://localhost:20128/v1",
+    temperature=0.7
+)
+
+messages = [HumanMessage(content="Explain quantum computing")]
+response = llm(messages)
+print(response.content)
+```
+
+### LlamaIndex 集成
+
+```python
+from llama_index.llms import OpenAI
+
+llm = OpenAI(
+    model="cc/claude-sonnet-4-20250514",
+    api_key="your-api-key-from-dashboard",
+    api_base="http://localhost:20128/v1"
+)
+
+response = llm.complete("What is machine learning?")
+print(response.text)
+```
+
+## 自定义脚本示例
+
+### 批处理脚本
+
+```python
+import openai
+import json
+
+openai.api_key = "your-api-key-from-dashboard"
+openai.api_base = "http://localhost:20128/v1"
+
+def process_batch(prompts, model="cx/deepseek-chat"):
+    results = []
+    for prompt in prompts:
+        response = openai.ChatCompletion.create(
+            model=model,
+            messages=[{"role": "user", "content": prompt}]
+        )
+        results.append({
+            "prompt": prompt,
+            "response": response.choices[0].message.content
+        })
+    return results
+
+prompts = [
+    "Explain AI in one sentence",
+    "What is machine learning?",
+    "Define neural networks"
+]
+
+results = process_batch(prompts)
+print(json.dumps(results, indent=2))
+```
+
+### 流式响应处理
+
+```javascript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "your-api-key-from-dashboard",
+  baseURL: "http://localhost:20128/v1"
+});
+
+async function streamResponse(prompt) {
+  const stream = await client.chat.completions.create({
+    model: "cc/claude-sonnet-4-20250514",
+    messages: [{ role: "user", content: prompt }],
+    stream: true
+  });
+
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content || "";
+    process.stdout.write(content);
+  }
+}
+
+streamResponse("Write a short story about AI");
+```
+
+### 多模型对比
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-api-key-from-dashboard",
+    base_url="http://localhost:20128/v1"
+)
+
+models = [
+    "cc/claude-sonnet-4-20250514",
+    "cx/deepseek-chat",
+    "glm/glm-4-plus"
+]
+
+prompt = "Explain quantum computing in simple terms"
+
+for model in models:
+    response = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "user", "content": prompt}]
+    )
+    print(f"\n=== {model} ===")
+    print(response.choices[0].message.content)
+```
+
+## 常见集成模式
+
+### 环境变量
+
+安全地存储凭据:
+
+```bash
+# .env file
+ROUTER_API_KEY=your-api-key-from-dashboard
+ROUTER_BASE_URL=http://localhost:20128/v1
+ROUTER_MODEL=cc/claude-sonnet-4-20250514
+```
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.getenv("ROUTER_API_KEY"),
+    base_url=os.getenv("ROUTER_BASE_URL")
+)
+```
+
+### 错误处理
+
+```python
+from openai import OpenAI, OpenAIError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+try:
+    response = client.chat.completions.create(
+        model="cc/claude-sonnet-4-20250514",
+        messages=[{"role": "user", "content": "Hello"}]
+    )
+    print(response.choices[0].message.content)
+except OpenAIError as e:
+    print(f"Error: {e}")
+```
+
+### 重试逻辑
+
+```python
+import time
+from openai import OpenAI, RateLimitError
+
+client = OpenAI(
+    api_key="your-api-key",
+    base_url="http://localhost:20128/v1"
+)
+
+def chat_with_retry(prompt, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            response = client.chat.completions.create(
+                model="cc/claude-sonnet-4-20250514",
+                messages=[{"role": "user", "content": prompt}]
+            )
+            return response.choices[0].message.content
+        except RateLimitError:
+            if attempt < max_retries - 1:
+                time.sleep(2 ** attempt)  # Exponential backoff
+            else:
+                raise
+```
+
+## 故障排除
+
+### 连接问题
+
+**问题:** 无法连接到 9Router
+```bash
+# 检查 9Router 是否运行
+curl http://localhost:20128/health
+
+# 预期响应:
+{"status": "ok"}
+```
+
+**方案:**
+- 确认 9Router 正在运行
+- 检查 20128 端口未被阻止
+- 确保 base URL 正确(包含 `/v1`)
+
+### 认证错误
+
+**问题:** 401 Unauthorized
+```
+Error: Invalid API key
+```
+
+**方案:**
+- 在仪表盘中确认 API key
+- 检查 Authorization 头格式:`Bearer your-api-key`
+- 确保 API key 中没有多余的空格或换行
+
+### 模型未找到
+
+**问题:** 404 Model not found
+```
+Error: Model 'cc/claude-opus' not found
+```
+
+**方案:**
+- 使用精确的模型名(大小写敏感)
+- 查看可用模型:`curl http://localhost:20128/v1/models`
+- 确认套餐中已启用该模型
+
+### 超时问题
+
+**问题:** 请求超时
+```
+Error: Request timed out after 30s
+```
+
+**方案:**
+- 在客户端配置中增大超时
+- 时间敏感任务使用更快的模型
+- 检查到 9Router 的网络连接
+
+### 速率限制
+
+**问题:** 429 Too Many Requests
+```
+Error: Rate limit exceeded
+```
+
+**方案:**
+- 实现指数退避
+- 降低请求频率
+- 在仪表盘中查看速率限制
+- 考虑升级套餐
+
+## 最佳实践
+
+### 安全
+- 将 API key 存储在环境变量中
+- 绝不将 API key 提交到版本控制
+- 云端部署使用 HTTPS
+- 定期轮换 API keys
+
+### 性能
+- 根据任务复杂度选择合适的模型
+- 对重复查询实现缓存
+- 长响应使用流式输出
+- 尽可能批量请求
+
+### 错误处理
+- 始终用 try-catch 块包裹
+- 添加带指数退避的重试逻辑
+- 记录错误以便调试
+- 提供回退机制
+
+### 成本优化
+- 简单任务选择高性价比的模型
+- 适当时缓存响应
+- 在仪表盘监控使用
+- 在代码中设置请求上限
+
+## 下一步
+
+- [配置 Cursor](cursor.md) 进行 IDE 集成
+- [设置 Continue](continue.md) 用于 VSCode
+- [探索 CLI 用法](../cli/basic-usage.md)
+- [了解模型选择](../models/overview.md)
+- [API 参考](../api/reference.md)
diff --git a/gitbook/content/zh-CN/integration/roo.md b/gitbook/content/zh-CN/integration/roo.md
new file mode 100644
index 0000000..86112c5
--- /dev/null
+++ b/gitbook/content/zh-CN/integration/roo.md
@@ -0,0 +1,127 @@
+# Roo AI 助手集成
+
+将 9Router 与 Roo AI 助手集成,通过统一界面访问多个 AI 模型。
+
+## 前置要求
+
+- 已安装 Roo AI 助手
+- 来自 [仪表盘](https://9router.com/dashboard) 的 9Router API key
+- 9Router 正在运行(本地或云端)
+
+## 配置步骤
+
+### 1. 打开 Roo 设置
+
+启动 Roo AI 助手并打开设置面板。
+
+### 2. 配置 API Provider
+
+1. 进入 **API Provider** 设置
+2. 选择 **Ollama** 作为 provider 类型
+3. 配置以下设置:
+
+**本地 9Router:**
+```
+Base URL: http://localhost:20128/v1
+API Key: your-api-key-from-dashboard
+```
+
+**云端 9Router:**
+```
+Base URL: https://9router.com/v1
+API Key: your-api-key-from-dashboard
+```
+
+### 3. 选择模型
+
+从可用的 9Router 模型中选择:
+
+**Claude 模型:**
+- `cc/claude-opus-4-5-20251101` - 最强
+- `cc/claude-sonnet-4-20250514` - 平衡
+- `cc/claude-haiku-4-20250514` - 快速
+
+**DeepSeek 模型:**
+- `cx/deepseek-chat` - 通用
+- `cx/deepseek-reasoner` - 复杂推理
+
+**GLM 模型:**
+- `glm/glm-4-plus` - 高级
+- `glm/glm-4-flash` - 快速响应
+
+### 4. 测试连接
+
+发送测试消息验证集成:
+
+```
+Hello! Can you confirm you're connected through 9Router?
+```
+
+## 使用示例
+
+### 基础聊天
+```
+向 Roo 提问: "Explain quantum computing in simple terms"
+模型: cc/claude-sonnet-4-20250514
+```
+
+### 代码生成
+```
+向 Roo 提问: "Write a Python function to calculate Fibonacci numbers"
+模型: cx/deepseek-chat
+```
+
+### 复杂推理
+```
+向 Roo 提问: "Analyze the trade-offs between microservices and monolithic architecture"
+模型: cx/deepseek-reasoner
+```
+
+## 模型选择建议
+
+- **快速任务**:使用 `cc/claude-haiku-4-20250514` 或 `glm/glm-4-flash`
+- **均衡性能**:使用 `cc/claude-sonnet-4-20250514` 或 `cx/deepseek-chat`
+- **复杂推理**:使用 `cc/claude-opus-4-5-20251101` 或 `cx/deepseek-reasoner`
+- **成本优化**:使用 DeepSeek 或 GLM 模型
+
+## 故障排除
+
+### 连接失败
+- 确认 9Router 正在运行:`curl http://localhost:20128/health`
+- 检查 API key 是否正确
+- 确保 Base URL 末尾包含 `/v1`
+
+### 模型不可用
+- 检查模型名是否完全匹配(大小写敏感)
+- 确认 9Router 套餐中已启用该模型
+- 尝试列表中的其他模型
+
+### 响应缓慢
+- 切换到更快的模型(haiku、flash)
+- 检查网络连接
+- 查看 9Router 日志排查问题
+
+## 高级配置
+
+### 自定义模型别名
+
+可在 Roo 设置中为常用模型创建快捷别名:
+
+```
+别名: "fast" → cc/claude-haiku-4-20250514
+别名: "smart" → cc/claude-opus-4-5-20251101
+别名: "code" → cx/deepseek-chat
+```
+
+### 多个配置文件
+
+为不同场景设置不同配置:
+- **开发**:DeepSeek 模型用于编码
+- **写作**:Claude 模型用于内容创作
+- **研究**:Reasoner 模型用于分析
+
+## 下一步
+
+- [配置 Cursor](cursor.md) 进行 IDE 集成
+- [设置 Continue](continue.md) 用于 VSCode
+- [探索 CLI 用法](../cli/basic-usage.md)
diff --git a/gitbook/content/zh-CN/providers/cheap.md b/gitbook/content/zh-CN/providers/cheap.md
new file mode 100644
index 0000000..03533d7
--- /dev/null
+++ b/gitbook/content/zh-CN/providers/cheap.md
@@ -0,0 +1,462 @@
+# 低价提供商 - 超低价备用
+
+订阅配额耗尽时,只花几分钱而不是几美元。比 ChatGPT API 便宜 ~90%!
+
+---
+
+## 概览
+
+低价层提供商是订阅配额耗尽时的 **备用**:
+
+- 💰 **GLM-4.7** - 每 1M tokens $0.6/$2.2(每日重置)
+- 💰 **MiniMax M2.1** - 每 1M tokens $0.2/$1.0(5h 重置)
+- 💰 **Kimi K2** - $9/月固定(10M tokens)
+
+**策略:** 在订阅配额用完后、免费层之前使用。相比 ChatGPT API(每 1M $20),省钱巨大。
+
+---
+
+## GLM-4.7(每日重置)
+
+### 价格
+
+| 套餐 | 输入 | 输出 | 重置 |
+|------|-------|--------|-------|
+| 标准 | $0.60/1M | $2.20/1M | 每日 10:00 AM |
+| Coding Plan | $0.60/1M | $2.20/1M | 每日 10:00 AM(3× 配额) |
+
+**成本示例(10M tokens):**
+- 输入: 10M × $0.60 = $6
+- 输出: 10M × $2.20 = $22
+- **合计: $6-22**,而 ChatGPT API 需 $200!
+
+### 设置
+
+**步骤 1:注册**
+
+1. 访问 [Zhipu AI](https://open.bigmodel.cn/)
+2. 创建账户(手机验证)
+3. 选择 **Coding Plan**,相同价格下 3× 配额
+
+**步骤 2:获取 API Key**
+
+```bash
+仪表盘 → API Keys → 创建新 Key
+→ 复制 API key(以 "zhipu-" 开头)
+```
+
+**步骤 3:添加到 9Router**
+
+```bash
+9router
+# 仪表盘 → 提供商 → 添加 API Key
+
+Provider: glm
+API Key: zhipu-your-api-key-here
+```
+
+**步骤 4:在 CLI 中使用**
+
+```
+Model: glm/glm-4.7
+       glm/glm-4.6v (vision)
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 上下文 | 最佳场景 |
+|----------|-------------|---------|----------|
+| `glm/glm-4.7` | GLM 4.7 | 128K | 编码、通用任务 |
+| `glm/glm-4.6v` | GLM 4.6V Vision | 128K | 图像分析 |
+
+### 专业建议
+
+- **Coding Plan** - 相同价格下 3× 配额($0.6/$2.2)
+- **每日重置** - 每天北京时间 10:00 AM 重置
+- **编码首选** - 针对代码生成优化
+- **128K 上下文** - 可处理大文件
+
+### 配额重置
+
+```
+每日重置: 北京时间 10:00 AM(UTC+8)
+→ UTC 02:00
+→ PST 前一天 18:00
+→ EST 前一天 21:00
+
+围绕重置时间规划重任务!
+```
+
+---
+
+## MiniMax M2.1(5 小时重置)
+
+### 价格
+
+| 套餐 | 输入 | 输出 | 重置 |
+|------|-------|--------|-------|
+| 标准 | $0.20/1M | $1.00/1M | 5 小时滚动 |
+
+**成本示例(10M tokens):**
+- 输入: 10M × $0.20 = $2
+- 输出: 10M × $1.00 = $10
+- **合计: $2-10** - 最便宜的选择!
+
+### 设置
+
+**步骤 1:注册**
+
+1. 访问 [MiniMax](https://www.minimax.io/)
+2. 创建账户
+3. 验证邮箱/手机
+
+**步骤 2:获取 API Key**
+
+```bash
+仪表盘 → API Management → Create Key
+→ 复制 API key
+```
+
+**步骤 3:添加到 9Router**
+
+```bash
+9router
+# 仪表盘 → 提供商 → 添加 API Key
+
+Provider: minimax
+API Key: your-minimax-api-key
+```
+
+**步骤 4:在 CLI 中使用**
+
+```
+Model: minimax/MiniMax-M2.1
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 上下文 | 最佳场景 |
+|----------|-------------|---------|----------|
+| `minimax/MiniMax-M2.1` | MiniMax M2.1 | 1M tokens | 长上下文、编码 |
+
+### 专业建议
+
+- **最便宜的选择** - 输入每 1M $0.20(比 ChatGPT 便宜 90%)
+- **5 小时滚动** - 每 5 小时配额重置
+- **1M 上下文** - 超大上下文窗口
+- **处理整个代码库** - 适合大文件
+
+### 配额重置
+
+```
+5 小时滚动窗口:
+→ 使用配额 → 等待 5 小时 → 配额刷新
+
+示例:
+10:00 AM - 使用 5M tokens
+3:00 PM - 配额刷新
+8:00 PM - 配额刷新
+
+24/7 编码,成本极低!
+```
+
+---
+
+## Kimi K2(固定 $9/月)
+
+### 价格
+
+| 套餐 | 月费 | 包含 Tokens | 折合成本 |
+|------|--------------|-----------------|----------------|
+| 订阅 | $9 | 10M tokens | $0.90/1M |
+
+**成本示例:**
+- $9/月固定
+- 包含 10M tokens
+- **折合: $0.90/1M** - 持续使用的最佳性价比!
+
+### 设置
+
+**步骤 1:订阅**
+
+1. 访问 [Moonshot AI](https://platform.moonshot.ai/)
+2. 创建账户
+3. 订阅 $9/月套餐
+
+**步骤 2:获取 API Key**
+
+```bash
+仪表盘 → API Keys → 创建新 Key
+→ 复制 API key
+```
+
+**步骤 3:添加到 9Router**
+
+```bash
+9router
+# 仪表盘 → 提供商 → 添加 API Key
+
+Provider: kimi
+API Key: your-kimi-api-key
+```
+
+**步骤 4:在 CLI 中使用**
+
+```
+Model: kimi/kimi-latest
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 上下文 | 最佳场景 |
+|----------|-------------|---------|----------|
+| `kimi/kimi-latest` | Kimi Latest | 200K | 通用编码 |
+
+### 专业建议
+
+- **固定成本** - $9/月,不限用量(最多 10M)
+- **稳定使用最佳** - 若每月用 10M,折合 $0.90/1M
+- **每月重置** - 10M tokens 每月重置
+- **可预测账单** - 无意外费用
+
+### 配额重置
+
+```
+每月重置: 每月 1 日
+→ 10M tokens 刷新
+
+每月用量示例:
+第 1 周: 3M tokens
+第 2 周: 2M tokens
+第 3 周: 3M tokens
+第 4 周: 2M tokens
+合计: 10M tokens = $9 固定
+```
+
+---
+
+## 价格对比
+
+| 提供商 | 输入/1M | 输出/1M | 重置 | 10M 成本 | 最佳场景 |
+|----------|----------|-----------|-------|----------|----------|
+| **GLM-4.7** | $0.60 | $2.20 | 每日 10AM | $6-22 | 每日配额用户 |
+| **MiniMax M2.1** | $0.20 | $1.00 | 5 小时 | $2-10 | **最便宜!** |
+| **Kimi K2** | $0.90 | $0.90 | 每月 | **$9 固定** | 稳定使用 |
+| ChatGPT API | $20.00 | $20.00 | 无 | $200 | ❌ 昂贵 |
+
+**节省:** 比 ChatGPT API 便宜 90-95%!
+
+---
+
+## 使用示例
+
+### Cursor IDE 设置
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [从 9router 仪表盘获取]
+  Model: glm/glm-4.7
+```
+
+### 创建组合(推荐)
+
+```
+仪表盘 → 组合 → 新建
+
+名称: cheap-backup
+模型:
+  1. cc/claude-opus-4-5 (订阅主力)
+  2. glm/glm-4.7 (低价备用, 每日重置)
+  3. minimax/MiniMax-M2.1 (最便宜的回退)
+  4. if/kimi-k2-thinking (免费应急)
+
+CLI 中使用: cheap-backup
+```
+
+**结果:** 订阅 → 低价 → 最便宜 → 免费
+
+---
+
+## 成本优化
+
+### 策略 1:每日重置例程
+
+```
+早上(10AM): 全新 GLM 配额
+→ 用 GLM 处理重任务
+→ 节省订阅配额
+
+下午: 订阅配额
+→ 用 Claude/Codex 处理复杂任务
+
+晚上: MiniMax(5h 重置)
+→ 深夜的低价备用
+
+夜里: 免费层(iFlow)
+→ 零成本应急备用
+```
+
+### 策略 2:预算优先
+
+```
+设置月预算: $20
+
+分配:
+- $9 Kimi K2(10M tokens 固定)
+- $6 GLM 每日配额(10M tokens)
+- $5 MiniMax 溢出(25M tokens)
+
+合计: $20 拿到 45M tokens
+而 ChatGPT API 同样的钱只能拿 1M tokens!
+```
+
+### 策略 3:订阅优先最大化
+
+```
+优先级:
+1. Gemini CLI(每月免费 180K)
+2. Claude Code(已付费订阅)
+3. GLM-4.7(低价备用,每 1M $0.6)
+4. MiniMax M2.1(最便宜,每 1M $0.2)
+5. iFlow(免费应急)
+
+月成本示例(100M tokens):
+- 60M 通过 Gemini CLI: $0(免费)
+- 30M 通过 Claude Code: $0(订阅)
+- 8M 通过 GLM: $4.80
+- 2M 通过 MiniMax: $0.40
+合计: $5.20/月!
+```
+
+---
+
+## 真实案例
+
+### 案例 1:重度编码月(100M tokens)
+
+```
+分解:
+- 60M 通过订阅(Claude/Codex): 无额外费用
+- 30M 通过 GLM-4.7: $18
+- 10M 通过 MiniMax M2.1: $2
+
+合计: $20/月
+而 ChatGPT API 需 $2000!
+
+节省: 便宜 99%!
+```
+
+### 案例 2:预算编码者($10/月)
+
+```
+策略:
+- $9 Kimi K2(10M tokens)
+- $1 MiniMax 溢出(5M tokens)
+
+合计: $10 拿到 15M tokens
+而 ChatGPT API 同样的钱只能拿 0.5M tokens!
+
+多 30 倍 tokens!
+```
+
+### 案例 3:自由职业(用量浮动)
+
+```
+清淡月(20M tokens):
+- 15M 通过订阅: $0
+- 5M 通过 GLM: $3
+合计: $3
+
+繁忙月(150M tokens):
+- 60M 通过订阅: $0
+- 60M 通过 GLM: $36
+- 30M 通过 MiniMax: $6
+合计: $42
+
+平均: $22.50/月
+而 ChatGPT API 需 $3400!
+```
+
+---
+
+## 最佳实践
+
+### 1. 跟踪每日配额
+
+```
+仪表盘显示:
+- GLM 配额: 已用 75%(6h 后重置)
+- MiniMax 配额: 已用 50%(2h 后重置)
+- Kimi 配额: 已用 8M/10M(15 天后重置)
+
+围绕重置时间规划重任务!
+```
+
+### 2. 使用 Coding Plan(GLM)
+
+```
+标准: 1× 配额
+Coding Plan: 3× 配额(同价!)
+
+→ 永远选 Coding Plan
+```
+
+### 3. 结合免费层
+
+```
+组合:
+1. gc/gemini-3-flash(免费主力)
+2. glm/glm-4.7(低价备用)
+3. minimax/MiniMax-M2.1(最便宜)
+4. if/kimi-k2-thinking(免费应急)
+
+结果: 最小化成本,最大化在线
+```
+
+### 4. 设置预算告警
+
+```
+仪表盘 → 设置 → 预算告警
+
+每日: $2 上限
+每周: $10 上限
+每月: $30 上限
+
+→ 达到上限时自动切换到免费层
+```
+
+---
+
+## 故障排除
+
+### "Quota exhausted"
+
+**方案:**
+- GLM: 等到北京时间 10:00 AM
+- MiniMax: 从首次使用起等 5 小时
+- Kimi: 等到下月 1 日
+- 使用组合回退到免费层
+
+### "API key invalid"
+
+**方案:**
+- 检查 API key 是否复制正确
+- 确认账户有余额
+- 必要时重新生成 API key
+
+### "High costs"
+
+**方案:**
+- 在仪表盘查看使用统计
+- 设置预算告警
+- 切换到 MiniMax(每 1M $0.2 最便宜)
+- 非关键任务用免费层
+
+---
+
+## 下一步
+
+- **添加免费回退:** [免费提供商](./free.md)
+- **设置订阅:** [订阅型提供商](./subscription.md)
+- **创建组合:** 仪表盘 → 组合 → 新建
diff --git a/gitbook/content/zh-CN/providers/free.md b/gitbook/content/zh-CN/providers/free.md
new file mode 100644
index 0000000..e55fe42
--- /dev/null
+++ b/gitbook/content/zh-CN/providers/free.md
@@ -0,0 +1,442 @@
+# 免费提供商 - 零成本回退
+
+当其他一切都受配额限制时的应急备用。零成本 24/7 编码!
+
+---
+
+## 概览
+
+免费层提供商是订阅和低价配额都耗尽时的 **回退**:
+
+- 🆓 **iFlow** - 8 个免费模型(Kimi K2、Qwen3、GLM 4.7、MiniMax M2...)
+- 🆓 **Qwen** - 3 个免费模型(Qwen3 Coder Plus/Flash、Vision)
+- 🆓 **Kiro** - 2 个免费模型(Claude Sonnet 4.5、Haiku 4.5)
+
+**策略:** 作为应急备用使用。无限用量,永久零成本!
+
+---
+
+## iFlow(8 个免费模型)
+
+### 价格
+
+| 套餐 | 月费 | 模型 | 配额 |
+|------|--------------|--------|-------|
+| 免费 | $0 | 8 个模型 | 无限 |
+
+**最佳价值:** 免费层中模型最多!Kimi K2、Qwen3、GLM、MiniMax、DeepSeek。
+
+### 设置
+
+**步骤 1:通过仪表盘连接**
+
+```bash
+9router
+# 仪表盘 → 提供商 → 连接 iFlow
+```
+
+**步骤 2:iFlow OAuth 登录**
+
+- 点击 "Connect iFlow"
+- 浏览器打开 → iFlow 登录页
+- 创建账户或登录
+- 授予权限
+- 启用自动 token 刷新
+
+**步骤 3:在 CLI 中使用**
+
+```
+Model: if/kimi-k2-thinking
+       if/kimi-k2
+       if/qwen3-coder-plus
+       if/glm-4.7
+       if/minimax-m2
+       if/deepseek-r1
+       if/deepseek-v3.2-chat
+       if/deepseek-v3.2-reasoner
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 最佳场景 |
+|----------|-------------|----------|
+| `if/kimi-k2-thinking` | Kimi K2 Thinking | 复杂推理 |
+| `if/kimi-k2` | Kimi K2 | 通用编码 |
+| `if/qwen3-coder-plus` | Qwen3 Coder Plus | 代码生成 |
+| `if/glm-4.7` | GLM 4.7 | 中文 + 英文 |
+| `if/minimax-m2` | MiniMax M2 | 长上下文 |
+| `if/deepseek-r1` | DeepSeek R1 | 推理任务 |
+| `if/deepseek-v3.2-chat` | DeepSeek V3.2 Chat | 对话型 |
+| `if/deepseek-v3.2-reasoner` | DeepSeek V3.2 Reasoner | 复杂逻辑 |
+
+### 专业建议
+
+- **8 个免费模型** - 免费层中最丰富
+- **无限用量** - 无配额限制
+- **Kimi K2 Thinking** - 复杂推理最佳
+- **DeepSeek R1** - 强大的推理能力
+
+---
+
+## Qwen(3 个免费模型)
+
+### 价格
+
+| 套餐 | 月费 | 模型 | 配额 |
+|------|--------------|--------|-------|
+| 免费 | $0 | 3 个模型 | 无限 |
+
+### 设置
+
+**步骤 1:通过仪表盘连接**
+
+```bash
+9router
+# 仪表盘 → 提供商 → 连接 Qwen
+```
+
+**步骤 2:设备码授权**
+
+- 点击 "Connect Qwen"
+- 仪表盘显示设备码
+- 访问授权 URL
+- 输入设备码
+- 登录 Qwen 账户
+- 启用自动 token 刷新
+
+**步骤 3:在 CLI 中使用**
+
+```
+Model: qw/qwen3-coder-plus
+       qw/qwen3-coder-flash
+       qw/vision-model
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 最佳场景 |
+|----------|-------------|----------|
+| `qw/qwen3-coder-plus` | Qwen3 Coder Plus | 高级编码 |
+| `qw/qwen3-coder-flash` | Qwen3 Coder Flash | 快速响应 |
+| `qw/vision-model` | Qwen3 Vision | 图像分析 |
+
+### 专业建议
+
+- **Qwen3 Coder Plus** - 编码能力强
+- **Qwen3 Coder Flash** - 快速任务首选
+- **Vision 模型** - 免费图像分析
+- **无限用量** - 无配额限制
+
+---
+
+## Kiro(免费 Claude)
+
+### 价格
+
+| 套餐 | 月费 | 模型 | 配额 |
+|------|--------------|--------|-------|
+| 免费 | $0 | Claude Sonnet 4.5、Haiku 4.5 | 无限 |
+
+**最佳价值:** 免费 Claude!与付费 Claude Code 同质量。
+
+### 设置
+
+**步骤 1:通过仪表盘连接**
+
+```bash
+9router
+# 仪表盘 → 提供商 → 连接 Kiro
+```
+
+**步骤 2:AWS Builder ID 或 OAuth**
+
+- 点击 "Connect Kiro"
+- 选择登录方式:
+  - AWS Builder ID(推荐)
+  - Google 账户
+  - GitHub 账户
+- 授予权限
+- 启用自动 token 刷新
+
+**步骤 3:在 CLI 中使用**
+
+```
+Model: kr/claude-sonnet-4.5
+       kr/claude-haiku-4.5
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 最佳场景 |
+|----------|-------------|----------|
+| `kr/claude-sonnet-4.5` | Claude Sonnet 4.5 | 质量/速度平衡 |
+| `kr/claude-haiku-4.5` | Claude Haiku 4.5 | 快速响应 |
+
+### 专业建议
+
+- **免费 Claude** - 与付费层同质量
+- **AWS Builder ID** - 用 AWS 账户轻松设置
+- **无限用量** - 无配额限制
+- **顶级质量** - 免费的 Claude 4.5!
+
+---
+
+## 特性对比
+
+| 提供商 | 模型 | 最佳模型 | 设置方式 | 配额 |
+|----------|--------|------------|-------|-------|
+| **iFlow** | 8 | Kimi K2 Thinking | OAuth | 无限 |
+| **Qwen** | 3 | Qwen3 Coder Plus | 设备码 | 无限 |
+| **Kiro** | 2 | Claude Sonnet 4.5 | AWS Builder ID | 无限 |
+
+**赢家:** 多样性看 iFlow,质量看 Kiro!
+
+---
+
+## 使用示例
+
+### Cursor IDE 设置
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [从 9router 仪表盘获取]
+  Model: if/kimi-k2-thinking
+```
+
+### 创建组合(推荐)
+
+```
+仪表盘 → 组合 → 新建
+
+名称: free-combo
+模型:
+  1. if/kimi-k2-thinking (iFlow 主力)
+  2. qw/qwen3-coder-plus (Qwen 备用)
+  3. kr/claude-sonnet-4.5 (Kiro 质量)
+
+CLI 中使用: free-combo
+```
+
+**结果:** 零成本,最大在线!
+
+---
+
+## 完整回退策略
+
+### 完整 3 层组合
+
+```
+仪表盘 → 组合 → 新建
+
+名称: complete-fallback
+模型:
+  1. gc/gemini-3-flash-preview (免费订阅)
+  2. cc/claude-opus-4-5 (付费订阅)
+  3. glm/glm-4.7 (低价备用, 每 1M $0.6)
+  4. minimax/MiniMax-M2.1 (最便宜, 每 1M $0.2)
+  5. if/kimi-k2-thinking (免费回退)
+  6. kr/claude-sonnet-4.5 (免费质量)
+
+CLI 中使用: complete-fallback
+```
+
+**结果:**
+- 第 1 层: 免费订阅(Gemini CLI)
+- 第 2 层: 付费订阅(Claude Code)
+- 第 3 层: 低价备用(GLM、MiniMax)
+- 第 4 层: 免费回退(iFlow、Kiro)
+
+**永不停码!**
+
+---
+
+## 最佳实践
+
+### 1. 作为应急备用
+
+```
+优先级:
+1. 订阅层(最大化付费配额)
+2. 低价层(每 1M tokens 几分钱)
+3. 免费层(无限,零成本)
+
+仅在以下情况使用免费层:
+- 订阅配额耗尽
+- 预算上限达到
+- 测试/非关键任务
+```
+
+### 2. 选择合适的模型
+
+```
+复杂推理: if/kimi-k2-thinking
+快速编码: qw/qwen3-coder-flash
+最佳质量: kr/claude-sonnet-4.5
+长上下文: if/minimax-m2
+视觉任务: qw/vision-model
+```
+
+### 3. 创建仅免费组合
+
+```
+零成本编码:
+
+名称: zero-cost
+模型:
+  1. kr/claude-sonnet-4.5 (最佳质量)
+  2. if/kimi-k2-thinking (复杂任务)
+  3. qw/qwen3-coder-plus (快速编码)
+
+成本: 永远 $0!
+```
+
+### 4. 上生产前先测试
+
+```
+用免费层来:
+- 测试 prompt
+- 原型功能
+- 学习新框架
+- 非关键任务
+
+把付费配额留给:
+- 生产代码
+- 复杂重构
+- 关键功能
+```
+
+---
+
+## 真实案例
+
+### 案例 1:学生/学习者(零预算)
+
+```
+设置:
+1. kr/claude-sonnet-4.5 (最佳质量)
+2. if/kimi-k2-thinking (复杂推理)
+3. qw/qwen3-coder-plus (快速编码)
+
+月成本: $0
+用量: 无限
+
+适合:
+- 学习编程
+- 个人项目
+- 作业/任务
+```
+
+### 案例 2:自由职业(预算敏感)
+
+```
+设置:
+1. gc/gemini-3-flash-preview (每月免费 180K)
+2. glm/glm-4.7 (低价备用, 每 1M $0.6)
+3. if/kimi-k2-thinking (免费回退)
+
+月成本: $5-10
+用量: 100M+ tokens
+
+适合:
+- 客户项目(付费层)
+- 测试(免费层)
+- 应急备用
+```
+
+### 案例 3:重度用户(全部最大化)
+
+```
+设置:
+1. gc/gemini-3-flash-preview (每月免费 180K)
+2. cc/claude-opus-4-5 (订阅 $20-100)
+3. cx/gpt-5.2-codex (订阅 $20-200)
+4. glm/glm-4.7 (低价 每 1M $0.6)
+5. minimax/MiniMax-M2.1 (最便宜 每 1M $0.2)
+6. if/kimi-k2-thinking (免费无限)
+7. kr/claude-sonnet-4.5 (免费质量)
+
+月成本: $40-320(订阅)+ $10-20(低价层)
+用量: 500M+ tokens
+
+适合:
+- 专业开发
+- 团队项目
+- 24/7 编码
+```
+
+---
+
+## 成本对比
+
+### 场景:每月 100M tokens
+
+**方案 1:仅 ChatGPT API**
+```
+100M × $20/1M = $2,000/月
+```
+
+**方案 2:仅 9Router 免费层**
+```
+100M 通过免费层 = $0/月
+节省: $2,000/月 (100%)
+```
+
+**方案 3:9Router 完整策略**
+```
+60M 通过 Gemini CLI(免费): $0
+30M 通过 Claude Code(订阅): 无额外费用
+8M 通过 GLM(低价): $4.80
+2M 通过 iFlow(免费): $0
+合计: $4.80/月 + 你已有的订阅
+节省: $1,995/月 (99.76%)
+```
+
+---
+
+## 故障排除
+
+### "OAuth failed"
+
+**方案:**
+- 检查网络连接
+- 尝试其他浏览器
+- 清除浏览器缓存
+- 在仪表盘重新连接
+
+### "Model not available"
+
+**方案:**
+- 检查仪表盘中提供商已连接
+- 确认 OAuth token 有效
+- 必要时重新连接提供商
+
+### "Slow responses"
+
+**方案:**
+- 免费层优先级较低
+- 在非高峰时段使用
+- 切换到其他免费提供商
+- 升级到低价层以提速
+
+---
+
+## 限制
+
+### 免费层注意事项
+
+- **速度** - 可能慢于付费层
+- **优先级** - 高峰期优先级较低
+- **速率限制** - 可能限速(但配额无限)
+- **可用性** - 偶尔可能宕机
+
+**方案:** 使用 3 层回退策略保障可靠性!
+
+---
+
+## 下一步
+
+- **设置订阅:** [订阅型提供商](./subscription.md)
+- **添加低价备用:** [低价提供商](./cheap.md)
+- **创建组合:** 仪表盘 → 组合 → 新建
+- **开始编码:** 使用 `complete-fallback` 组合最大化可靠性
diff --git a/gitbook/content/zh-CN/providers/subscription.md b/gitbook/content/zh-CN/providers/subscription.md
new file mode 100644
index 0000000..51e7e49
--- /dev/null
+++ b/gitbook/content/zh-CN/providers/subscription.md
@@ -0,0 +1,404 @@
+# 订阅型提供商 - 最大化你的价值
+
+通过智能配额跟踪和自动回退,最大化你已有的 AI 订阅价值。在重置前用完每一点订阅配额!
+
+---
+
+## 概览
+
+订阅型提供商是你的 **首选** - 既然已经付费了,就要用足:
+
+- ✅ **Claude Code**(Pro/Max)- Claude 4.5 Opus/Sonnet/Haiku
+- ✅ **OpenAI Codex**(Plus/Pro)- GPT 5.2 Codex、GPT 5.1 Codex Max
+- ✅ **Gemini CLI**(免费层!)- 每月 180K 次补全
+- ✅ **GitHub Copilot** - GPT-5、Claude 4.5、Gemini 3
+- ✅ **Antigravity**(Google)- Gemini 3 Pro、Claude Sonnet 4.5
+
+**策略:** 优先使用这些,实时跟踪配额,耗尽时回退到低价/免费层。
+
+---
+
+## Claude Code(Pro/Max)
+
+### 价格
+
+| 套餐 | 月费 | 配额重置 | 模型 |
+|------|--------------|-------------|--------|
+| Pro | $20 | 5 小时 + 每周 | Opus、Sonnet、Haiku |
+| Max | $100 | 5 小时 + 每周 | Opus、Sonnet、Haiku |
+
+### 设置
+
+**步骤 1:通过仪表盘连接**
+
+```bash
+9router
+# 仪表盘打开 → 提供商 → 连接 Claude Code
+```
+
+**步骤 2:OAuth 登录**
+
+- 点击 "Connect Claude Code"
+- 浏览器打开 → 登录 Claude.ai
+- 启用自动 token 刷新
+- 开始配额跟踪
+
+**步骤 3:在 CLI 中使用**
+
+```
+Model: cc/claude-opus-4-5-20251101
+       cc/claude-sonnet-4-5-20250929
+       cc/claude-haiku-4-5-20251001
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 最佳场景 |
+|----------|-------------|----------|
+| `cc/claude-opus-4-5-20251101` | Claude 4.5 Opus | 复杂任务、架构 |
+| `cc/claude-sonnet-4-5-20250929` | Claude 4.5 Sonnet | 平衡速度/质量 |
+| `cc/claude-haiku-4-5-20251001` | Claude 4.5 Haiku | 快速响应 |
+
+### 专业建议
+
+- **Opus 用于复杂任务** - 架构决策、重构
+- **Sonnet 用于速度** - 快速编辑、代码生成
+- **按模型跟踪配额** - 仪表盘按模型显示使用情况
+- **5 小时重置** - 每 5 小时刷新配额,加每周重置
+
+---
+
+## OpenAI Codex(Plus/Pro)
+
+### 价格
+
+| 套餐 | 月费 | 配额重置 | 模型 |
+|------|--------------|-------------|--------|
+| Plus | $20 | 5 小时 + 每周 | GPT 5.2、GPT 5.1 |
+| Pro | $200 | 5 小时 + 每周 | GPT 5.2 Codex、GPT 5.1 Max |
+
+### 设置
+
+**步骤 1:通过仪表盘连接**
+
+```bash
+9router
+# 仪表盘 → 提供商 → 连接 Codex
+```
+
+**步骤 2:OAuth 登录**
+
+- 点击 "Connect Codex"
+- 浏览器打开 `http://localhost:1455`
+- 登录 OpenAI 账户
+- 启用自动 token 刷新
+
+**步骤 3:在 CLI 中使用**
+
+```
+Model: cx/gpt-5.2-codex
+       cx/gpt-5.1-codex-max
+       cx/gpt-5.2
+       cx/gpt-5.1-codex
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 最佳场景 |
+|----------|-------------|----------|
+| `cx/gpt-5.2-codex` | GPT 5.2 Codex | 最新编码模型 |
+| `cx/gpt-5.1-codex-max` | GPT 5.1 Codex Max | 最大上下文 |
+| `cx/gpt-5.2` | GPT 5.2 | 通用任务 |
+| `cx/gpt-5.1-codex` | GPT 5.1 Codex | 稳定编码 |
+
+### 专业建议
+
+- **5 小时滚动配额** - 每 5 小时刷新配额
+- **每周重置** - 每周配额完全重置
+- **Pro 层** - 配额是 Plus 的 10 倍
+
+---
+
+## Gemini CLI(每月免费 180K!)
+
+### 价格
+
+| 套餐 | 月费 | 配额 | 重置 |
+|------|--------------|-------|-------|
+| 免费 | $0 | 180K 次补全/月 + 每日 1K | 每日 + 每月 |
+
+**最佳性价比:** 巨大的免费层!请在付费层之前使用。
+
+### 设置
+
+**步骤 1:通过仪表盘连接**
+
+```bash
+9router
+# 仪表盘 → 提供商 → 连接 Gemini CLI
+```
+
+**步骤 2:Google OAuth**
+
+- 点击 "Connect Gemini CLI"
+- 浏览器打开 → 登录 Google 账户
+- 授予权限
+- 启用自动 token 刷新
+
+**步骤 3:在 CLI 中使用**
+
+```
+Model: gc/gemini-3-flash-preview
+       gc/gemini-3-pro-preview
+       gc/gemini-2.5-pro
+       gc/gemini-2.5-flash
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 最佳场景 |
+|----------|-------------|----------|
+| `gc/gemini-3-flash-preview` | Gemini 3 Flash Preview | 快速响应 |
+| `gc/gemini-3-pro-preview` | Gemini 3 Pro Preview | 复杂任务 |
+| `gc/gemini-2.5-pro` | Gemini 2.5 Pro | 稳定生产 |
+| `gc/gemini-2.5-flash` | Gemini 2.5 Flash | 快速任务 |
+
+### 专业建议
+
+- **每月 180K 次补全** - 大量免费层
+- **每日 1K 限制** - 每天午夜重置
+- **优先使用** - 免费层,先于付费订阅
+- **无需信用卡** - Google 账户完全免费
+
+---
+
+## GitHub Copilot
+
+### 价格
+
+| 套餐 | 月费 | 配额重置 | 模型 |
+|------|--------------|-------------|--------|
+| 个人 | $10 | 每月(1 日) | GPT-5、Claude 4.5、Gemini 3 |
+| 商业 | $19 | 每月(1 日) | GPT-5、Claude 4.5、Gemini 3 |
+
+### 设置
+
+**步骤 1:通过仪表盘连接**
+
+```bash
+9router
+# 仪表盘 → 提供商 → 连接 GitHub
+```
+
+**步骤 2:通过 GitHub 进行 OAuth**
+
+- 点击 "Connect GitHub"
+- 浏览器打开 → 登录 GitHub
+- 授权 GitHub Copilot
+- 启用自动 token 刷新
+
+**步骤 3:在 CLI 中使用**
+
+```
+Model: gh/gpt-5
+       gh/gpt-5.1-codex-max
+       gh/claude-4.5-sonnet
+       gh/gemini-3-pro
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 最佳场景 |
+|----------|-------------|----------|
+| `gh/gpt-5` | GPT-5 | 最新 OpenAI 模型 |
+| `gh/gpt-5.1-codex-max` | GPT-5.1 Codex Max | 最大上下文 |
+| `gh/claude-4.5-sonnet` | Claude 4.5 Sonnet | Anthropic 质量 |
+| `gh/gemini-3-pro` | Gemini 3 Pro | Google 质量 |
+
+### 专业建议
+
+- **每月重置** - 每月 1 日完全重置
+- **多模型** - 一个订阅访问 GPT、Claude、Gemini
+- **商业层** - 团队更高配额
+
+---
+
+## Antigravity(Google 账户)
+
+### 价格
+
+| 套餐 | 月费 | 配额 | 模型 |
+|------|--------------|-------|--------|
+| 免费 | $0 | 类似 Gemini CLI | Gemini 3 Pro、Claude Sonnet 4.5 |
+
+### 设置
+
+**步骤 1:通过仪表盘连接**
+
+```bash
+9router
+# 仪表盘 → 提供商 → 连接 Antigravity
+```
+
+**步骤 2:Google OAuth**
+
+- 点击 "Connect Antigravity"
+- 浏览器打开 → 登录 Google 账户
+- 授予权限
+- 启用自动 token 刷新
+
+**步骤 3:在 CLI 中使用**
+
+```
+Model: ag/gemini-3-pro-high
+       ag/claude-sonnet-4-5
+       ag/claude-opus-4-5-thinking
+```
+
+### 可用模型
+
+| 模型 ID | 描述 | 最佳场景 |
+|----------|-------------|----------|
+| `ag/gemini-3-pro-high` | Gemini 3 Pro High | 高质量响应 |
+| `ag/claude-sonnet-4-5` | Claude Sonnet 4.5 | Anthropic 质量 |
+| `ag/claude-opus-4-5-thinking` | Claude Opus 4.5 Thinking | 复杂推理 |
+
+### 专业建议
+
+- **免费层** - Google 账户零成本
+- **可访问 Claude** - 免费的 Claude Sonnet/Opus
+- **配额类似 Gemini CLI** - 每日/每月上限
+
+---
+
+## 价格对比
+
+| 提供商 | 月费 | 配额重置 | 价值 |
+|----------|--------------|-------------|-------|
+| **Claude Code Pro** | $20 | 5 小时 + 每周 | ⭐⭐⭐⭐⭐ 最佳质量 |
+| **Claude Code Max** | $100 | 5 小时 + 每周 | ⭐⭐⭐⭐⭐ 最高配额 |
+| **Codex Plus** | $20 | 5 小时 + 每周 | ⭐⭐⭐⭐ 良好性价比 |
+| **Codex Pro** | $200 | 5 小时 + 每周 | ⭐⭐⭐⭐⭐ 10× 配额 |
+| **Gemini CLI** | **$0** | 每日 + 每月 | ⭐⭐⭐⭐⭐ 免费 180K/月! |
+| **GitHub Copilot** | $10-19 | 每月(1 日) | ⭐⭐⭐⭐ 多模型 |
+| **Antigravity** | **$0** | 每日 + 每月 | ⭐⭐⭐⭐ 免费 Claude! |
+
+---
+
+## 使用示例
+
+### Cursor IDE 设置
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [从 9router 仪表盘获取]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### 创建组合(推荐)
+
+```
+仪表盘 → 组合 → 新建
+
+名称: premium-coding
+模型:
+  1. gc/gemini-3-flash-preview (免费, 优先使用)
+  2. cc/claude-opus-4-5-20251101 (订阅)
+  3. cx/gpt-5.2-codex (订阅备用)
+
+CLI 中使用: premium-coding
+```
+
+**结果:** 最大化免费层 → 使用订阅 → 自动回退
+
+---
+
+## 配额跟踪
+
+9Router 实时跟踪配额:
+
+- **Token 消耗** - 每次请求的输入/输出 tokens
+- **重置倒计时** - 下次配额重置剩余时间
+- **使用百分比** - 配额已用比例
+- **自动回退** - 耗尽时切换到下一层
+
+**仪表盘视图:**
+
+```
+Claude Code Pro
+├─ 配额: 已用 75%
+├─ 重置: 2h 15m(5 小时)
+├─ 每周重置: 3 天
+└─ 回退: glm/glm-4.7(低价层)
+```
+
+---
+
+## 最佳实践
+
+### 1. 优先使用免费层
+
+```
+优先级:
+1. Gemini CLI(每月免费 180K)
+2. Antigravity(免费 Claude)
+3. Claude Code/Codex(付费订阅)
+```
+
+### 2. 每日跟踪配额
+
+- 每天早上查看仪表盘
+- 围绕配额重置规划重任务
+- 非关键任务用低价/免费层
+
+### 3. 创建智能组合
+
+```
+示例组合:
+1. gc/gemini-3-flash-preview(免费主力)
+2. cc/claude-opus-4-5(复杂任务)
+3. glm/glm-4.7(低价备用)
+4. if/kimi-k2-thinking(免费回退)
+```
+
+### 4. 按时间优化
+
+```
+早上: 全新 5 小时配额(Claude/Codex)
+下午: Gemini CLI(每日 1K)
+晚上: 订阅配额
+深夜: 低价/免费层
+```
+
+---
+
+## 故障排除
+
+### "Quota exhausted"
+
+**方案:**
+- 查看仪表盘配额跟踪
+- 等待重置(5 小时或每日)
+- 使用组合回退到低价/免费层
+
+### "OAuth token expired"
+
+**方案:**
+- 9Router 会自动刷新
+- 若仍有问题: 仪表盘 → 提供商 → 重新连接
+
+### "Rate limiting"
+
+**方案:**
+- 订阅配额已用尽
+- 添加回退:`cc/claude-opus → glm/glm-4.7`
+- 使用免费层:`if/kimi-k2-thinking`
+
+---
+
+## 下一步
+
+- **设置低价备用:** [低价提供商](./cheap.md)
+- **添加免费回退:** [免费提供商](./free.md)
+- **创建组合:** 仪表盘 → 组合 → 新建
diff --git a/gitbook/content/zh-CN/troubleshooting.md b/gitbook/content/zh-CN/troubleshooting.md
new file mode 100644
index 0000000..a527dc4
--- /dev/null
+++ b/gitbook/content/zh-CN/troubleshooting.md
@@ -0,0 +1,351 @@
+# 故障排除
+
+使用 9Router 时常见的问题与解决方案。
+
+---
+
+## "Language model did not provide messages"
+
+**问题:** 请求失败,响应为空或返回错误。
+
+**原因:**
+- 提供商配额耗尽
+- API key 无效或过期
+- 模型不可用
+
+**解决方案:**
+
+1. **查看配额状态:**
+   ```
+   仪表盘 → 提供商 → 查看配额跟踪
+   ```
+   若配额耗尽,等待重置或切换提供商。
+
+2. **使用组合回退:**
+   ```
+   仪表盘 → 组合 → 创建回退链
+   示例: cc/claude-opus → glm/glm-4.7 → if/kimi-k2
+   ```
+
+3. **验证提供商连接:**
+   ```
+   仪表盘 → 提供商 → 必要时重新连接
+   ```
+
+---
+
+## 速率限制
+
+**问题:** 出现 "Rate limit exceeded" 或 "Too many requests" 错误。
+
+**原因:**
+- 订阅配额用完(5 小时/每日/每周限制)
+- 触发了 API 速率限制
+- 并发请求过多
+
+**解决方案:**
+
+1. **查看重置时间:**
+   ```
+   仪表盘 → 配额跟踪 → 查看重置倒计时
+   ```
+
+2. **切换到低价层:**
+   ```
+   使用: glm/glm-4.7 (每 1M tokens $0.6)
+        minimax/MiniMax-M2.1 (每 1M tokens $0.20)
+   ```
+
+3. **添加回退组合:**
+   ```
+   仪表盘 → 组合 → 添加备用模型
+   主力: cc/claude-opus (订阅)
+   备用: glm/glm-4.7 (低价)
+   应急: if/kimi-k2 (免费)
+   ```
+
+---
+
+## OAuth Token 过期
+
+**问题:** 出现 "Unauthorized" 或 "Token expired" 错误。
+
+**原因:**
+- OAuth token 过期(自动刷新失败)
+- 提供商会话失效
+- 刷新过程中出现网络问题
+
+**解决方案:**
+
+1. **自动刷新(默认):**
+   9Router 会自动刷新 token。等待 30 秒后重试。
+
+2. **手动重连:**
+   ```
+   仪表盘 → 提供商 → [提供商名称] → 重新连接
+   → 再次完成 OAuth 流程
+   ```
+
+3. **检查提供商状态:**
+   确认提供商服务在线(Claude Code、Codex 等)。
+
+---
+
+## 成本过高
+
+**问题:** 出现意外的高用量或高成本。
+
+**原因:**
+- 不必要地使用了昂贵模型
+- 没有回退到便宜层级
+- 上下文窗口过大
+
+**解决方案:**
+
+1. **查看使用统计:**
+   ```
+   仪表盘 → 使用统计 → 查看 token 消耗
+   → 找出高成本模型
+   ```
+
+2. **切换到更便宜的模型:**
+   ```
+   替换: cc/claude-opus ($20-100/月 订阅)
+   为: glm/glm-4.7 (每 1M tokens $0.6)
+       minimax/MiniMax-M2.1 (每 1M tokens $0.20)
+   ```
+
+3. **使用免费层:**
+   ```
+   if/kimi-k2-thinking (免费)
+   qw/qwen3-coder-plus (免费)
+   kr/claude-sonnet-4.5 (免费)
+   gc/gemini-3-flash-preview (每月免费 180K)
+   ```
+
+4. **优化 prompt:**
+   - 减少上下文大小
+   - 长响应使用流式输出
+   - 缓存常用 prompt
+
+---
+
+## 连接被拒绝
+
+**问题:** 出现 "ECONNREFUSED" 或 "Cannot connect to localhost:20128"。
+
+**原因:**
+- 9Router 未运行
+- 端口 20128 被阻止
+- 防火墙拦截连接
+
+**解决方案:**
+
+1. **启动 9Router:**
+   ```bash
+   9router
+   ```
+   仪表盘应该在 http://localhost:3000 打开。
+
+2. **检查端口 20128:**
+   ```bash
+   # 检查端口是否监听
+   lsof -i :20128
+   
+   # Windows
+   netstat -ano | findstr :20128
+   ```
+
+3. **检查防火墙:**
+   - macOS: 系统设置 → 网络 → 防火墙
+   - Windows: Windows Defender 防火墙 → 允许应用
+   - Linux: `sudo ufw allow 20128`
+
+4. **使用云端 endpoint:**
+   如果 localhost 不行(例如 Cursor IDE):
+   ```
+   Endpoint: https://9router.com/v1
+   ```
+
+---
+
+## 仪表盘无法打开
+
+**问题:** 仪表盘无法在 http://localhost:3000 加载。
+
+**原因:**
+- 端口 3000 被占用
+- 9Router 崩溃
+- 浏览器缓存问题
+
+**解决方案:**
+
+1. **确认 9Router 是否运行:**
+   ```bash
+   # 检查进程
+   ps aux | grep 9router
+   
+   # 检查端口 3000
+   lsof -i :3000
+   ```
+
+2. **杀掉冲突进程:**
+   ```bash
+   # macOS/Linux
+   lsof -ti:3000 | xargs kill -9
+   
+   # Windows
+   netstat -ano | findstr :3000
+   taskkill /PID <PID> /F
+   ```
+
+3. **重启 9Router:**
+   ```bash
+   # 停止
+   pkill -f 9router
+   
+   # 启动
+   9router
+   ```
+
+4. **清除浏览器缓存:**
+   - Chrome: Ctrl+Shift+Delete → 清除缓存
+   - 尝试无痕模式
+
+5. **检查防火墙设置:**
+   确认端口 3000 未被阻止。
+
+---
+
+## 模型未找到
+
+**问题:** 出现 "Model not found" 或 "Invalid model" 错误。
+
+**原因:**
+- 提供商未连接
+- 模型 ID 拼写错误
+- 提供商未激活
+
+**解决方案:**
+
+1. **验证提供商连接:**
+   ```
+   仪表盘 → 提供商 → 检查状态(绿色 = 已激活)
+   ```
+
+2. **检查模型 ID 格式:**
+   ```
+   正确: cc/claude-opus-4-5-20251101
+   错误: claude-opus-4-5-20251101
+   
+   格式: [provider-prefix]/[model-name]
+   ```
+
+3. **列出可用模型:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer your-api-key"
+   ```
+
+4. **重新连接提供商:**
+   ```
+   仪表盘 → 提供商 → [提供商] → 重新连接
+   ```
+
+---
+
+## 响应缓慢
+
+**问题:** 请求耗时过长或超时。
+
+**原因:**
+- 提供商延迟
+- 网络问题
+- 上下文/响应过大
+- 提供商速率限制
+
+**解决方案:**
+
+1. **查看提供商状态:**
+   ```
+   仪表盘 → 提供商 → 查看延迟统计
+   ```
+
+2. **切换到更快的模型:**
+   ```
+   快速: cc/claude-haiku-4-5 (Haiku 比 Opus 快)
+         gc/gemini-3-flash-preview
+         qw/qwen3-coder-flash
+   ```
+
+3. **使用流式响应:**
+   ```json
+   {
+     "model": "cc/claude-opus-4-5",
+     "messages": [...],
+     "stream": true
+   }
+   ```
+
+4. **检查网络:**
+   ```bash
+   # 测试延迟
+   ping api.anthropic.com
+   ping api.openai.com
+   ```
+
+5. **减小上下文:**
+   - 精简消息历史
+   - 使用更短的 prompt
+   - 在 CLI 工具中启用上下文裁剪
+
+---
+
+## API Key 无效
+
+**问题:** 出现 "Invalid API key" 或 "Authentication failed" 错误。
+
+**原因:**
+- 复制了错误的 API key
+- API key 已过期
+- 未生成 API key
+
+**解决方案:**
+
+1. **重新生成 API key:**
+   ```
+   仪表盘 → 设置 → API Keys → 生成新 Key
+   → 复制并使用新 key
+   ```
+
+2. **检查 key 格式:**
+   ```
+   正确: 9r_xxxxxxxxxxxxxxxxxxxxxxxx
+   错误: 缺少 9r_ 前缀
+   ```
+
+3. **检查 CLI 配置中的 key:**
+   ```bash
+   # Cursor
+   Settings → Models → OpenAI API Key
+   
+   # Cline
+   Settings → API Key
+   
+   # 环境变量
+   export OPENAI_API_KEY="9r_your_key"
+   ```
+
+4. **测试 API key:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer 9r_your_key"
+   ```
+
+---
+
+## 需要更多帮助?
+
+- **GitHub Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **文档:** [9router.com/docs](https://9router.com/docs)
+- **常见问题:** [faq.md](faq.md)
diff --git a/gitbook/jsconfig.json b/gitbook/jsconfig.json
new file mode 100644
index 0000000..9c33383
--- /dev/null
+++ b/gitbook/jsconfig.json
@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  }
+}
diff --git a/gitbook/lib/content.js b/gitbook/lib/content.js
new file mode 100644
index 0000000..e5198c0
--- /dev/null
+++ b/gitbook/lib/content.js
@@ -0,0 +1,42 @@
+import fs from "fs";
+import path from "path";
+import { DEFAULT_LANG, isValidLang } from "@/constants/languages";
+
+const CONTENT_ROOT = path.join(process.cwd(), "content");
+
+function readContentFile(lang, slugPath) {
+  const filePath = path.join(CONTENT_ROOT, lang, `${slugPath}.md`);
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, "utf-8");
+}
+
+// Load content with fallback to default language if missing
+export function loadContent(lang, slug = "index") {
+  const safeLang = isValidLang(lang) ? lang : DEFAULT_LANG;
+  const slugPath = Array.isArray(slug) ? slug.join("/") : slug;
+  return readContentFile(safeLang, slugPath) || readContentFile(DEFAULT_LANG, slugPath);
+}
+
+// Walk content/<lang>/ to collect all slugs (excluding index.md)
+export function getAllSlugs(lang = DEFAULT_LANG) {
+  const baseDir = path.join(CONTENT_ROOT, lang);
+  if (!fs.existsSync(baseDir)) return [];
+
+  const walk = (dir, basePath = "") => {
+    const files = fs.readdirSync(dir);
+    let results = [];
+    files.forEach(file => {
+      const full = path.join(dir, file);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) {
+        results = results.concat(walk(full, path.join(basePath, file)));
+      } else if (file.endsWith(".md") && file !== "index.md") {
+        const slug = path.join(basePath, file.replace(/\.md$/, ""));
+        results.push(slug.split(path.sep));
+      }
+    });
+    return results;
+  };
+
+  return walk(baseDir);
+}
diff --git a/gitbook/next.config.mjs b/gitbook/next.config.mjs
new file mode 100644
index 0000000..69608b6
--- /dev/null
+++ b/gitbook/next.config.mjs
@@ -0,0 +1,24 @@
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+/** @type {import('next').NextConfig} */
+const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? "";
+const projectRoot = dirname(fileURLToPath(import.meta.url));
+
+const nextConfig = {
+  output: "export",
+  basePath,
+  assetPrefix: basePath || undefined,
+  trailingSlash: true,
+  images: {
+    unoptimized: true
+  },
+  turbopack: {
+    root: projectRoot
+  },
+  env: {
+    NEXT_PUBLIC_BASE_PATH: basePath
+  }
+};
+
+export default nextConfig;
diff --git a/gitbook/package.json b/gitbook/package.json
new file mode 100644
index 0000000..12f2735
--- /dev/null
+++ b/gitbook/package.json
@@ -0,0 +1,25 @@
+{
+  "name": "9router-docs",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "next dev -p 3001",
+    "build": "next build",
+    "start": "next start -p 3001",
+    "deploy": "npm run build && npx wrangler pages deploy out --project-name=9router-docs --commit-dirty=true"
+  },
+  "dependencies": {
+    "lucide-react": "^0.563.0",
+    "next": "16.1.1",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-markdown": "^9.0.1",
+    "rehype-highlight": "^7.0.0",
+    "rehype-slug": "^6.0.0",
+    "remark-gfm": "^4.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.2.0",
+    "tailwindcss": "^4.2.0"
+  }
+}
diff --git a/gitbook/postcss.config.mjs b/gitbook/postcss.config.mjs
new file mode 100644
index 0000000..9b544e3
--- /dev/null
+++ b/gitbook/postcss.config.mjs
@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {}
+  }
+};
diff --git a/gitbook/utils/markdown.js b/gitbook/utils/markdown.js
new file mode 100644
index 0000000..4783a8a
--- /dev/null
+++ b/gitbook/utils/markdown.js
@@ -0,0 +1,218 @@
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import rehypeHighlight from "rehype-highlight";
+import rehypeSlug from "rehype-slug";
+import { BookOpen, Rocket, Terminal, Monitor, FolderOpen, HelpCircle, MessageCircle, Mouse, Folder, Lock, Zap, Smartphone, Lightbulb, AlertTriangle, CheckCircle, ArrowRight, Layers, Plug, Cloud, Wallet, Gift, GitBranch, BarChart3, Code2, Sparkles, Server, PartyPopper, Siren, Link2, Target, Heart, Check, Home, Package, Wrench, OctagonX, Search, Globe, Container } from "lucide-react";
+
+const PAGE_ICONS = {
+  "Welcome to 9Router": BookOpen,
+  "Introduction": BookOpen,
+  "Getting Started": Rocket,
+  "Quick Start": Rocket,
+  "Installation": Terminal,
+  "Providers": Layers,
+  "Subscription (Maximize)": Sparkles,
+  "Cheap (Backup)": Wallet,
+  "Free (Fallback)": Gift,
+  "Features": Zap,
+  "Smart Routing": GitBranch,
+  "Combos & Fallback": Layers,
+  "Quota Tracking": BarChart3,
+  "Integration": Plug,
+  "Claude Code": Code2,
+  "OpenAI Codex": Code2,
+  "Cursor": Code2,
+  "Cline": Code2,
+  "Roo": Code2,
+  "Continue": Code2,
+  "Other Tools": Plug,
+  "Deployment": Cloud,
+  "Localhost": Monitor,
+  "Cloud (VPS/Docker)": Server,
+  "Troubleshooting": HelpCircle,
+  "FAQ": MessageCircle,
+  "Frequently Asked Questions": MessageCircle
+};
+
+const ICON_MAP = {
+  "terminal": Terminal,
+  "monitor": Monitor,
+  "mouse": Mouse,
+  "folder": Folder,
+  "lock": Lock,
+  "zap": Zap,
+  "smartphone": Smartphone,
+  "lightbulb": Lightbulb,
+  "alert-triangle": AlertTriangle,
+  "check-circle": CheckCircle,
+  "arrow-right": ArrowRight,
+};
+
+// Emoji to lucide icon mapping (auto-converted in markdown)
+const EMOJI_ICON_MAP = {
+  "✅": { Icon: CheckCircle, color: "text-green-600" },
+  "✓": { Icon: Check, color: "text-green-600" },
+  "❌": { Icon: AlertTriangle, color: "text-red-500" },
+  "⚠️": { Icon: AlertTriangle, color: "text-yellow-600" },
+  "⚠": { Icon: AlertTriangle, color: "text-yellow-600" },
+  "🚨": { Icon: Siren, color: "text-red-500" },
+  "🛑": { Icon: OctagonX, color: "text-red-500" },
+  "💡": { Icon: Lightbulb, color: "text-yellow-500" },
+  "🔄": { Icon: GitBranch, color: "text-[#E68A6E]" },
+  "🚀": { Icon: Rocket, color: "text-[#E68A6E]" },
+  "⚡": { Icon: Zap, color: "text-yellow-500" },
+  "🔌": { Icon: Plug, color: "text-[#E68A6E]" },
+  "☁️": { Icon: Cloud, color: "text-blue-500" },
+  "☁": { Icon: Cloud, color: "text-blue-500" },
+  "📦": { Icon: Package, color: "text-[#E68A6E]" },
+  "💰": { Icon: Wallet, color: "text-green-600" },
+  "🎁": { Icon: Gift, color: "text-pink-500" },
+  "📊": { Icon: BarChart3, color: "text-[#E68A6E]" },
+  "💻": { Icon: Code2, color: "text-gray-700" },
+  "✨": { Icon: Sparkles, color: "text-[#E68A6E]" },
+  "🖥️": { Icon: Server, color: "text-gray-700" },
+  "🖥": { Icon: Server, color: "text-gray-700" },
+  "📖": { Icon: BookOpen, color: "text-[#E68A6E]" },
+  "🔒": { Icon: Lock, color: "text-gray-700" },
+  "➡️": { Icon: ArrowRight, color: "text-[#E68A6E]" },
+  "📱": { Icon: Smartphone, color: "text-[#E68A6E]" },
+  "📂": { Icon: Folder, color: "text-[#E68A6E]" },
+  "📁": { Icon: Folder, color: "text-[#E68A6E]" },
+  "🖱️": { Icon: Mouse, color: "text-[#E68A6E]" },
+  "🎉": { Icon: PartyPopper, color: "text-pink-500" },
+  "🔗": { Icon: Link2, color: "text-blue-500" },
+  "🎯": { Icon: Target, color: "text-red-500" },
+  "❤": { Icon: Heart, color: "text-red-500" },
+  "❤️": { Icon: Heart, color: "text-red-500" },
+  "🏠": { Icon: Home, color: "text-[#E68A6E]" },
+  "🔧": { Icon: Wrench, color: "text-gray-700" },
+  "🔍": { Icon: Search, color: "text-gray-700" },
+  "🌐": { Icon: Globe, color: "text-blue-500" },
+  "🐳": { Icon: Container, color: "text-blue-500" }
+};
+
+const EMOJI_REGEX = new RegExp(`^(${Object.keys(EMOJI_ICON_MAP).map(e => e.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\\\$&")).join("|")})\\s*`);
+
+export function parseMarkdown(content) {
+  return content;
+}
+
+// Unicode-aware slugify: keeps letters/numbers from any language (Vietnamese, Chinese, Japanese, etc.)
+export function slugify(text) {
+  return text
+    .toLowerCase()
+    .normalize("NFC")
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^\p{L}\p{N}-]+/gu, "")
+    .replace(/^-+|-+$/g, "");
+}
+
+// Extract leading emoji from heading children and replace with lucide icon
+function renderHeadingWithEmoji(tag, children, props) {
+  const Tag = tag;
+  const text = (Array.isArray(children) ? children : [children])
+    .map(c => (typeof c === "string" ? c : ""))
+    .join("");
+  const emojiMatch = text.match(EMOJI_REGEX);
+  const textForId = emojiMatch ? text.slice(emojiMatch[0].length).trim() : text;
+  const id = slugify(textForId);
+  if (emojiMatch) {
+    const { Icon, color } = EMOJI_ICON_MAP[emojiMatch[1]];
+    const rest = text.slice(emojiMatch[0].length);
+    return (
+      <Tag id={id} {...props}>
+        <Icon className={`inline-block mr-2 align-[-0.15em] w-[1em] h-[1em] ${color}`} />
+        {rest}
+      </Tag>
+    );
+  }
+  return <Tag id={id} {...props}>{children}</Tag>;
+}
+
+export function MarkdownRenderer({ content }) {
+  return (
+    <ReactMarkdown
+      remarkPlugins={[remarkGfm]}
+      rehypePlugins={[rehypeHighlight]}
+      className="markdown-content"
+      components={{
+        h1: ({ node, children, ...props }) => {
+          const text = children?.toString() || "";
+          const IconComponent = PAGE_ICONS[text];
+          const id = slugify(text);
+          
+          return (
+            <h1 id={id} {...props}>
+              {IconComponent && <IconComponent className="inline-block mr-3" />}
+              {children}
+            </h1>
+          );
+        },
+        h2: ({ node, children, ...props }) => renderHeadingWithEmoji("h2", children, props),
+        h3: ({ node, children, ...props }) => renderHeadingWithEmoji("h3", children, props),
+        li: ({ node, children, ...props }) => {
+          // Extract text from children (handle React elements)
+          const extractText = (child) => {
+            if (typeof child === 'string') return child;
+            if (Array.isArray(child)) return child.map(extractText).join('');
+            if (child?.props?.children) return extractText(child.props.children);
+            return '';
+          };
+          
+          const text = extractText(children);
+          const iconMatch = text.match(/^\[icon:([a-z-]+)\]\s*(.*)$/);
+          
+          if (iconMatch) {
+            const iconName = iconMatch[1];
+            const restText = iconMatch[2];
+            const IconComponent = ICON_MAP[iconName];
+            
+            return (
+              <li {...props}>
+                {IconComponent && <IconComponent className="inline-block mr-2 w-4 h-4 text-[#E68A6E]" />}
+                {restText}
+              </li>
+            );
+          }
+
+          // Auto-convert leading emoji to lucide icon
+          const emojiMatch = text.match(EMOJI_REGEX);
+          if (emojiMatch) {
+            const { Icon, color } = EMOJI_ICON_MAP[emojiMatch[1]];
+            const restText = text.slice(emojiMatch[0].length);
+            return (
+              <li {...props}>
+                <Icon className={`inline-block mr-2 w-4 h-4 ${color}`} />
+                {restText}
+              </li>
+            );
+          }
+          
+          return <li {...props}>{children}</li>;
+        },
+      }}
+    >
+      {content}
+    </ReactMarkdown>
+  );
+}
+
+export function extractHeadings(content) {
+  const headingRegex = /^(#{2,3})\s+(.+)$/gm;
+  const headings = [];
+  let match;
+
+  while ((match = headingRegex.exec(content)) !== null) {
+    const level = match[1].length;
+    const text = match[2].replace(EMOJI_REGEX, "").trim();
+    const id = slugify(text);
+    
+    headings.push({
+      level,
+      text,
+      id
+    });
+  }
+
+  return headings;
+}
diff --git a/i18n/README.ja-JP.md b/i18n/README.ja-JP.md
new file mode 100644
index 0000000..3ec1163
--- /dev/null
+++ b/i18n/README.ja-JP.md
@@ -0,0 +1,1209 @@
+<div align="center">
+  <img src="../images/9router.png?1" alt="9Router Dashboard" width="800"/>
+
+  # 9Router - 無料 AI ルーター
+
+  **コーディングを止めない。スマートフォールバックで無料＆格安AIモデルに自動ルーティング。**
+
+  **すべてのAIコーディングツール（Claude Code、Cursor、Antigravity、Copilot、Codex、Gemini、OpenCode、Cline、OpenClaw...）を40以上のAIプロバイダーと100以上のモデルに接続。**
+
+  [![npm](https://img.shields.io/npm/v/9router.svg)](https://www.npmjs.com/package/9router)
+  [![Downloads](https://img.shields.io/npm/dm/9router.svg)](https://www.npmjs.com/package/9router)
+  [![License](https://img.shields.io/npm/l/9router.svg)](https://github.com/decolua/9router/blob/main/LICENSE)
+
+  [🚀 クイックスタート](#-クイックスタート) • [💡 機能](#-主な機能) • [📖 セットアップ](#-セットアップガイド) • [🌐 ウェブサイト](https://9router.com)
+
+  [🇻🇳 Tiếng Việt](./README.vi.md) • [🇨🇳 中文](./README.zh-CN.md) • [🇯🇵 日本語](./README.ja-JP.md)
+</div>
+
+---
+
+## 🤔 なぜ9Router？
+
+**お金の無駄遣いと制限に悩まされるのはもう終わりです：**
+
+- ❌ サブスクリプションのクオータが毎月未使用のまま期限切れ
+- ❌ レート制限でコーディング中に停止
+- ❌ 高額なAPI（プロバイダーごとに月額$20〜50）
+- ❌ プロバイダー間の手動切り替え
+
+**9Routerが解決します：**
+
+- ✅ **サブスクリプションを最大化** - クオータを追跡し、リセット前にすべて使い切る
+- ✅ **自動フォールバック** - サブスクリプション → 格安 → 無料、ダウンタイムゼロ
+- ✅ **マルチアカウント** - プロバイダーごとにアカウント間でラウンドロビン
+- ✅ **ユニバーサル** - Claude Code、Codex、Gemini CLI、Cursor、Cline、あらゆるCLIツールに対応
+
+---
+
+## 🔄 仕組み
+
+```
+┌─────────────┐
+│  あなたの    │  （Claude Code、Codex、Gemini CLI、OpenClaw、Cursor、Cline...）
+│   CLIツール  │
+└──────┬──────┘
+       │ http://localhost:20128/v1
+       ↓
+┌─────────────────────────────────────────┐
+│        9Router（スマートルーター）        │
+│  • フォーマット変換（OpenAI ↔ Claude）   │
+│  • クオータ追跡                          │
+│  • 自動トークンリフレッシュ               │
+└──────┬──────────────────────────────────┘
+       │
+       ├─→ [Tier 1: サブスクリプション] Claude Code、Codex、Gemini CLI
+       │   ↓ クオータ消費済み
+       ├─→ [Tier 2: 格安] GLM ($0.6/1M)、MiniMax ($0.2/1M)
+       │   ↓ 予算上限
+       └─→ [Tier 3: 無料] iFlow、Qwen、Kiro（無制限）
+
+結果: コーディングが止まらない、最小コスト
+```
+
+---
+
+## ⚡ クイックスタート
+
+**1. グローバルインストール：**
+
+```bash
+npm install -g 9router
+9router
+```
+
+🎉 ダッシュボードが `http://localhost:20128` で開きます
+
+**2. 無料プロバイダーを接続（サインアップ不要）：**
+
+ダッシュボード → Providers → **Claude Code** または **Antigravity** を接続 → OAuthログイン → 完了！
+
+**3. CLIツールで使用：**
+
+```
+Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Clineの設定:
+  エンドポイント: http://localhost:20128/v1
+  APIキー: [ダッシュボードからコピー]
+  モデル: if/kimi-k2-thinking
+```
+
+**これだけです！** 無料AIモデルでコーディングを始めましょう。
+
+**代替方法: ソースから実行（このリポジトリ）：**
+
+このリポジトリパッケージはプライベート（`9router-app`）のため、ソース/Docker実行がローカル開発の想定パスです。
+
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+本番モード：
+
+```bash
+npm run build
+PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start
+```
+
+デフォルトURL：
+- ダッシュボード: `http://localhost:20128/dashboard`
+- OpenAI互換API: `http://localhost:20128/v1`
+
+---
+
+## 🎥 動画チュートリアル
+
+<div align="center">
+
+### 📺 完全セットアップガイド - 9Router + Claude Code 無料
+
+[![9Router + Claude Code Setup](https://img.youtube.com/vi/raEyZPg5xE0/maxresdefault.jpg)](https://www.youtube.com/watch?v=raEyZPg5xE0)
+
+**🎬 ステップバイステップのチュートリアルを視聴：**
+- ✅ 9Routerのインストールとセットアップ
+- ✅ 無料Claude Sonnet 4.5の設定
+- ✅ Claude Codeとの統合
+- ✅ ライブコーディングデモ
+
+**⏱️ 所要時間:** 20分 | **👥 作成:** Developer Community
+
+[▶️ YouTubeで視聴](https://www.youtube.com/watch?v=o3qYCyjrFYg)
+
+</div>
+
+---
+
+## 🛠️ 対応CLIツール
+
+9Routerはすべての主要AIコーディングツールとシームレスに連携します：
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/openclaw.png" width="60" alt="OpenClaw"/><br/>
+        <b>OpenClaw</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/opencode.png" width="60" alt="OpenCode"/><br/>
+        <b>OpenCode</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/cline.png" width="60" alt="Cline"/><br/>
+        <b>Cline</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/continue.png" width="60" alt="Continue"/><br/>
+        <b>Continue</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/droid.png" width="60" alt="Droid"/><br/>
+        <b>Droid</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/roo.png" width="60" alt="Roo"/><br/>
+        <b>Roo</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/copilot.png" width="60" alt="Copilot"/><br/>
+        <b>Copilot</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/kilocode.png" width="60" alt="Kilo Code"/><br/>
+        <b>Kilo Code</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+---
+
+## 🌐 対応プロバイダー
+
+### 🔐 OAuthプロバイダー
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/github.png" width="60" alt="GitHub"/><br/>
+        <b>GitHub</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🆓 無料プロバイダー
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="150">
+        <img src="../public/providers/iflow.png" width="70" alt="iFlow"/><br/>
+        <b>iFlow AI</b><br/>
+        <sub>8以上のモデル • 無制限</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/qwen.png" width="70" alt="Qwen"/><br/>
+        <b>Qwen Code</b><br/>
+        <sub>3以上のモデル • 無制限</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/gemini-cli.png" width="70" alt="Gemini CLI"/><br/>
+        <b>Gemini CLI</b><br/>
+        <sub>月18万回無料</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/kiro.png" width="70" alt="Kiro"/><br/>
+        <b>Kiro AI</b><br/>
+        <sub>Claude • 無制限</sub>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🔑 APIキープロバイダー（40以上）
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/openrouter.png" width="50" alt="OpenRouter"/><br/>
+        <sub>OpenRouter</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/glm.png" width="50" alt="GLM"/><br/>
+        <sub>GLM</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/kimi.png" width="50" alt="Kimi"/><br/>
+        <sub>Kimi</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/minimax.png" width="50" alt="MiniMax"/><br/>
+        <sub>MiniMax</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/openai.png" width="50" alt="OpenAI"/><br/>
+        <sub>OpenAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/anthropic.png" width="50" alt="Anthropic"/><br/>
+        <sub>Anthropic</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/gemini.png" width="50" alt="Gemini"/><br/>
+        <sub>Gemini</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/deepseek.png" width="50" alt="DeepSeek"/><br/>
+        <sub>DeepSeek</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/groq.png" width="50" alt="Groq"/><br/>
+        <sub>Groq</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/xai.png" width="50" alt="xAI"/><br/>
+        <sub>xAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/mistral.png" width="50" alt="Mistral"/><br/>
+        <sub>Mistral</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/perplexity.png" width="50" alt="Perplexity"/><br/>
+        <sub>Perplexity</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/together.png" width="50" alt="Together"/><br/>
+        <sub>Together AI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/fireworks.png" width="50" alt="Fireworks"/><br/>
+        <sub>Fireworks</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/cerebras.png" width="50" alt="Cerebras"/><br/>
+        <sub>Cerebras</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/cohere.png" width="50" alt="Cohere"/><br/>
+        <sub>Cohere</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/nvidia.png" width="50" alt="NVIDIA"/><br/>
+        <sub>NVIDIA</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/siliconflow.png" width="50" alt="SiliconFlow"/><br/>
+        <sub>SiliconFlow</sub>
+      </td>
+    </tr>
+  </table>
+  <p><i>...その他Nebius、Chutes、Hyperbolic、カスタムOpenAI/Anthropic互換エンドポイントなど20以上のプロバイダー</i></p>
+</div>
+
+---
+
+## 💡 主な機能
+
+| 機能 | 概要 | メリット |
+|------|------|----------|
+| 🎯 **スマート3段階フォールバック** | 自動ルーティング: サブスクリプション → 格安 → 無料 | コーディングが止まらない、ダウンタイムゼロ |
+| 📊 **リアルタイムクオータ追跡** | ライブトークン数 + リセットカウントダウン | サブスクリプション価値の最大化 |
+| 🔄 **フォーマット変換** | OpenAI ↔ Claude ↔ Gemini シームレス対応 | あらゆるCLIツールで動作 |
+| 👥 **マルチアカウント対応** | プロバイダーごとに複数アカウント | 負荷分散 + 冗長性 |
+| 🔄 **自動トークンリフレッシュ** | OAuthトークンの自動更新 | 手動再ログイン不要 |
+| 🎨 **カスタムコンボ** | 無制限のモデル組み合わせ作成 | ニーズに合わせたフォールバック |
+| 📝 **リクエストログ** | リクエスト/レスポンスの完全ログ | 問題の簡単なトラブルシューティング |
+| 💾 **クラウド同期** | デバイス間で設定を同期 | どこでも同じセットアップ |
+| 📊 **使用状況分析** | トークン、コスト、トレンドの追跡 | 支出の最適化 |
+| 🌐 **どこでもデプロイ** | Localhost、VPS、Docker、Cloudflare Workers | 柔軟なデプロイオプション |
+
+<details>
+<summary><b>📖 機能詳細</b></summary>
+
+### 🎯 スマート3段階フォールバック
+
+自動フォールバック付きコンボを作成：
+
+```
+コンボ: "my-coding-stack"
+  1. cc/claude-opus-4-6        (サブスクリプション)
+  2. glm/glm-4.7               (格安バックアップ、$0.6/1M)
+  3. if/kimi-k2-thinking       (無料フォールバック)
+
+→ クオータ切れやエラー発生時に自動切り替え
+```
+
+### 📊 リアルタイムクオータ追跡
+
+- プロバイダーごとのトークン消費量
+- リセットカウントダウン（5時間、日次、週次）
+- 有料ティアのコスト見積もり
+- 月間支出レポート
+
+### 🔄 フォーマット変換
+
+フォーマット間のシームレスな変換：
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
+- CLIツールがOpenAIフォーマットで送信 → 9Routerが変換 → プロバイダーがネイティブフォーマットで受信
+- カスタムOpenAIエンドポイントをサポートするすべてのツールで動作
+
+### 👥 マルチアカウント対応
+
+- プロバイダーごとに複数アカウント追加
+- 自動ラウンドロビンまたは優先度ベースのルーティング
+- 1つのアカウントがクオータに達したら次のアカウントにフォールバック
+
+### 🔄 自動トークンリフレッシュ
+
+- OAuthトークンが期限切れ前に自動リフレッシュ
+- 手動の再認証不要
+- すべてのプロバイダーでシームレスな体験
+
+### 🎨 カスタムコンボ
+
+- 無制限のモデル組み合わせ作成
+- サブスクリプション、格安、無料ティアを混合
+- コンボに名前を付けて簡単にアクセス
+- クラウド同期でデバイス間でコンボを共有
+
+### 📝 リクエストログ
+
+- デバッグモードでリクエスト/レスポンスの完全ログ
+- API呼び出し、ヘッダー、ペイロードの追跡
+- 統合の問題をトラブルシューティング
+- 分析用にログをエクスポート
+
+### 💾 クラウド同期
+
+- デバイス間でプロバイダー、コンボ、設定を同期
+- 自動バックグラウンド同期
+- 安全な暗号化ストレージ
+- どこからでもセットアップにアクセス
+
+#### クラウドランタイムに関する注意
+
+- 本番環境ではサーバーサイドのクラウド変数を推奨：
+  - `BASE_URL`（同期スケジューラで使用される内部コールバックURL）
+  - `CLOUD_URL`（クラウド同期エンドポイントのベースURL）
+- `NEXT_PUBLIC_BASE_URL` と `NEXT_PUBLIC_CLOUD_URL` は互換性/UI用にまだサポートされていますが、サーバーランタイムは `BASE_URL`/`CLOUD_URL` を優先します。
+- クラウド同期リクエストはタイムアウト + フェイルファスト動作を使用し、クラウドDNS/ネットワークが利用できない場合のUIハングを回避します。
+
+### 📊 使用状況分析
+
+- プロバイダーおよびモデルごとのトークン使用量追跡
+- コスト見積もりと支出トレンド
+- 月次レポートとインサイト
+- AI支出の最適化
+
+> **💡 重要 - ダッシュボードのコストについて：**
+>
+> 使用状況分析に表示される「コスト」は**追跡と比較目的のみ**です。
+> 9Router自体は**一切課金しません**。有料サービスを使用する場合のみ、プロバイダーに直接支払います。
+>
+> **例:** ダッシュボードにiFlowモデルの使用で「合計コスト$290」と表示されている場合、
+> これは有料APIを直接使用した場合に支払うであろう金額を表しています。実際のコスト = **$0**（iFlowは無料無制限）。
+>
+> これは無料モデルや9Router経由のルーティングでどれだけ節約しているかを示す「節約トラッカー」と考えてください！
+
+### 🌐 どこでもデプロイ
+
+- 💻 **ローカルホスト** - デフォルト、オフラインで動作
+- ☁️ **VPS/クラウド** - デバイス間で共有
+- 🐳 **Docker** - ワンコマンドデプロイ
+- 🚀 **Cloudflare Workers** - グローバルエッジネットワーク
+
+</details>
+
+---
+
+## 💰 料金の概要
+
+| ティア | プロバイダー | コスト | クオータリセット | 最適な用途 |
+|--------|-------------|--------|-----------------|------------|
+| **💳 サブスクリプション** | Claude Code (Pro) | $20/月 | 5時間 + 週次 | 既存のサブスク利用者 |
+| | Codex (Plus/Pro) | $20-200/月 | 5時間 + 週次 | OpenAIユーザー |
+| | Gemini CLI | **無料** | 月18万回 + 日1千回 | 全員！ |
+| | GitHub Copilot | $10-19/月 | 月次 | GitHubユーザー |
+| **💰 格安** | GLM-4.7 | $0.6/1M | 毎日午前10時 | 予算バックアップ |
+| | MiniMax M2.1 | $0.2/1M | 5時間ローリング | 最安オプション |
+| | Kimi K2 | $9/月固定 | 月1000万トークン | 予測可能なコスト |
+| **🆓 無料** | iFlow | $0 | 無制限 | 8モデル無料 |
+| | Qwen | $0 | 無制限 | 3モデル無料 |
+| | Kiro | $0 | 無制限 | Claude無料 |
+
+**💡 プロのヒント:** Gemini CLI（月18万回無料）+ iFlow（無制限無料）のコンボで $0 のコスト！
+
+---
+
+### 📊 9Routerのコストと課金について
+
+**9Routerの課金の実態：**
+
+✅ **9Routerソフトウェア = 永久無料**（オープンソース、課金なし）
+✅ **ダッシュボードの「コスト」= 表示/追跡のみ**（実際の請求ではない）
+✅ **プロバイダーに直接支払い**（サブスクリプションまたはAPI料金）
+✅ **無料プロバイダーは無料のまま**（iFlow、Kiro、Qwen = $0 無制限）
+❌ **9Routerは請求書を送ったり**カードに課金したりしません
+
+**コスト表示の仕組み：**
+
+ダッシュボードは有料APIを直接使用した場合の**推定コスト**を表示します。これは**課金ではなく**、節約額を示す比較ツールです。
+
+**シナリオ例：**
+```
+ダッシュボード表示:
+• 合計リクエスト: 1,662
+• 合計トークン: 4700万
+• 表示コスト: $290
+
+実際の確認:
+• プロバイダー: iFlow（無料無制限）
+• 実際の支払い: $0.00
+• $290の意味: 無料モデルの使用で節約した金額！
+```
+
+**支払いルール：**
+- **サブスクリプションプロバイダー**（Claude Code、Codex）：各ウェブサイトで直接支払い
+- **格安プロバイダー**（GLM、MiniMax）：直接支払い、9Routerはルーティングのみ
+- **無料プロバイダー**（iFlow、Kiro、Qwen）：本当に永久無料、隠れた料金なし
+- **9Router**：一切課金しない
+
+---
+
+## 🎯 ユースケース
+
+### ケース1: 「Claude Proサブスクリプションを持っている」
+
+**問題:** クオータが未使用のまま期限切れ、重いコーディング中にレート制限
+
+**解決策:**
+```
+コンボ: "maximize-claude"
+  1. cc/claude-opus-4-6        (サブスクリプションを最大限活用)
+  2. glm/glm-4.7               (クオータ切れ時の格安バックアップ)
+  3. if/kimi-k2-thinking       (無料の緊急フォールバック)
+
+月額コスト: $20 (サブスクリプション) + ~$5 (バックアップ) = 合計$25
+vs. $20 + 制限に引っかかる = フラストレーション
+```
+
+### ケース2: 「コストゼロにしたい」
+
+**問題:** サブスクリプションを払えない、信頼性のあるAIコーディングが必要
+
+**解決策:**
+```
+コンボ: "free-forever"
+  1. gc/gemini-3-flash         (月18万回無料)
+  2. if/kimi-k2-thinking       (無制限無料)
+  3. qw/qwen3-coder-plus       (無制限無料)
+
+月額コスト: $0
+品質: 本番対応モデル
+```
+
+### ケース3: 「24時間365日コーディング、中断なし」
+
+**問題:** 締め切り、ダウンタイムは許されない
+
+**解決策:**
+```
+コンボ: "always-on"
+  1. cc/claude-opus-4-6        (最高品質)
+  2. cx/gpt-5.2-codex          (セカンドサブスクリプション)
+  3. glm/glm-4.7               (格安、毎日リセット)
+  4. minimax/MiniMax-M2.1      (最安、5時間リセット)
+  5. if/kimi-k2-thinking       (無料無制限)
+
+結果: 5層のフォールバック = ダウンタイムゼロ
+月額コスト: $20-200 (サブスクリプション) + $10-20 (バックアップ)
+```
+
+### ケース4: 「OpenClawで無料AIを使いたい」
+
+**問題:** メッセージングアプリ（WhatsApp、Telegram、Slack...）でAIアシスタントが必要、完全無料で
+
+**解決策:**
+```
+コンボ: "openclaw-free"
+  1. if/glm-4.7                (無制限無料)
+  2. if/minimax-m2.1           (無制限無料)
+  3. if/kimi-k2-thinking       (無制限無料)
+
+月額コスト: $0
+アクセス方法: WhatsApp、Telegram、Slack、Discord、iMessage、Signal...
+```
+
+---
+
+## ❓ よくある質問
+
+<details>
+<summary><b>📊 ダッシュボードに高額なコストが表示されるのはなぜ？</b></summary>
+
+ダッシュボードはトークン使用量を追跡し、有料APIを直接使用した場合の**推定コスト**を表示します。これは**実際の課金ではなく**、9Routerを通じて無料モデルや既存のサブスクリプションを使用することでどれだけ節約しているかを示すための参考値です。
+
+**例：**
+- **ダッシュボード表示:** 「合計コスト$290」
+- **実際:** iFlow（無料無制限）を使用中
+- **実際のコスト:** **$0.00**
+- **$290の意味:** 有料APIの代わりに無料モデルを使用して**節約した**金額！
+
+コスト表示は使用パターンと最適化の機会を理解するための「節約トラッカー」です。
+
+</details>
+
+<details>
+<summary><b>💳 9Routerに課金されますか？</b></summary>
+
+**いいえ。** 9Routerはあなたのコンピューター上で動作する無料のオープンソースソフトウェアです。一切課金しません。
+
+**支払い先：**
+- ✅ **サブスクリプションプロバイダー**（Claude Code $20/月、Codex $20-200/月）→ 各ウェブサイトで直接支払い
+- ✅ **格安プロバイダー**（GLM、MiniMax）→ 直接支払い、9Routerはリクエストをルーティングするだけ
+- ❌ **9Router自体** → **一切課金しない**
+
+9Routerはローカルプロキシ/ルーターです。クレジットカード情報を持たず、請求書を送信できず、課金システムもありません。完全に無料のソフトウェアです。
+
+</details>
+
+<details>
+<summary><b>🆓 無料プロバイダーは本当に無制限ですか？</b></summary>
+
+**はい！** 無料と表示されているプロバイダー（iFlow、Kiro、Qwen）は本当に無制限で**隠れた料金はありません**。
+
+これらは各企業が提供する無料サービスです：
+- **iFlow**: OAuth経由で8以上のモデルに無料無制限アクセス
+- **Kiro**: AWS Builder ID経由で無料無制限Claudeモデル
+- **Qwen**: デバイス認証経由でQwenモデルに無料無制限アクセス
+
+9Routerはリクエストをルーティングするだけで、「罠」や将来の課金はありません。本当に無料のサービスであり、9Routerはフォールバックサポートでそれらを使いやすくしています。
+
+**注意:** 一部のサブスクリプションプロバイダー（Antigravity、GitHub Copilot）には無料プレビュー期間があり、後に有料になる可能性がありますが、それは9Routerではなく各プロバイダーから明確に告知されます。
+
+</details>
+
+<details>
+<summary><b>💰 実際のAIコストを最小化するには？</b></summary>
+
+**無料優先戦略：**
+
+1. **100%無料コンボから始める：**
+   ```
+   1. gc/gemini-3-flash (Googleから月18万回無料)
+   2. if/kimi-k2-thinking (iFlowから無制限無料)
+   3. qw/qwen3-coder-plus (Qwenから無制限無料)
+   ```
+   **コスト: $0/月**
+
+2. **必要な場合のみ格安バックアップを追加：**
+   ```
+   4. glm/glm-4.7 ($0.6/100万トークン)
+   ```
+   **追加コスト: 実際に使用した分だけ支払い**
+
+3. **サブスクリプションプロバイダーは最後に使用：**
+   - 既にお持ちの場合のみ
+   - 9Routerがクオータ追跡で価値を最大化
+
+**結果:** ほとんどのユーザーは無料ティアのみで月額$0で運用可能！
+
+</details>
+
+<details>
+<summary><b>📈 使用量が突然急増したら？</b></summary>
+
+9Routerのスマートフォールバックが予期しない課金を防止します：
+
+**シナリオ:** コーディングスプリント中にクオータを使い切った
+
+**9Routerなし：**
+- ❌ レート制限に到達 → 作業停止 → フラストレーション
+- ❌ または: 意図せず高額なAPI請求が発生
+
+**9Routerあり：**
+- ✅ サブスクリプションが上限に達する → 格安ティアに自動フォールバック
+- ✅ 格安ティアが高くなる → 無料ティアに自動フォールバック
+- ✅ コーディングが止まらない → 予測可能なコスト
+
+**あなたがコントロール:** ダッシュボードでプロバイダーごとの支出上限を設定し、9Routerはそれを遵守します。
+
+</details>
+
+---
+
+## 📖 セットアップガイド
+
+<details>
+<summary><b>🔐 サブスクリプションプロバイダー（価値の最大化）</b></summary>
+
+### Claude Code (Pro/Max)
+
+```bash
+ダッシュボード → Providers → Claude Codeを接続
+→ OAuthログイン → 自動トークンリフレッシュ
+→ 5時間 + 週次クオータ追跡
+
+モデル:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**プロのヒント:** 複雑なタスクにはOpus、スピード重視ならSonnet。9Routerはモデルごとにクオータを追跡します！
+
+### OpenAI Codex (Plus/Pro)
+
+```bash
+ダッシュボード → Providers → Codexを接続
+→ OAuthログイン（ポート1455）
+→ 5時間 + 週次リセット
+
+モデル:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+### Gemini CLI（月18万回無料！）
+
+```bash
+ダッシュボード → Providers → Gemini CLIを接続
+→ Google OAuth
+→ 月18万回 + 日1千回
+
+モデル:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**最高のコスパ:** 巨大な無料ティア！有料ティアの前にこちらを使用。
+
+### GitHub Copilot
+
+```bash
+ダッシュボード → Providers → GitHubを接続
+→ GitHub経由のOAuth
+→ 月次リセット（毎月1日）
+
+モデル:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+</details>
+
+<details>
+<summary><b>💰 格安プロバイダー（バックアップ）</b></summary>
+
+### GLM-4.7（日次リセット、$0.6/1M）
+
+1. サインアップ: [Zhipu AI](https://open.bigmodel.cn/)
+2. Coding PlanからAPIキーを取得
+3. ダッシュボード → APIキーを追加:
+   - プロバイダー: `glm`
+   - APIキー: `your-key`
+
+**使用:** `glm/glm-4.7`
+
+**プロのヒント:** Coding Planは1/7のコストで3倍のクオータを提供！毎日午前10:00にリセット。
+
+### MiniMax M2.1（5時間リセット、$0.20/1M）
+
+1. サインアップ: [MiniMax](https://www.minimax.io/)
+2. APIキーを取得
+3. ダッシュボード → APIキーを追加
+
+**使用:** `minimax/MiniMax-M2.1`
+
+**プロのヒント:** ロングコンテキスト（100万トークン）で最安オプション！
+
+### Kimi K2（月額$9固定）
+
+1. サブスクライブ: [Moonshot AI](https://platform.moonshot.ai/)
+2. APIキーを取得
+3. ダッシュボード → APIキーを追加
+
+**使用:** `kimi/kimi-latest`
+
+**プロのヒント:** 月額$9固定で1000万トークン = 実効コスト$0.90/1M！
+
+</details>
+
+<details>
+<summary><b>🆓 無料プロバイダー（緊急バックアップ）</b></summary>
+
+### iFlow（8つの無料モデル）
+
+```bash
+ダッシュボード → iFlowを接続
+→ iFlow OAuthログイン
+→ 無制限使用
+
+モデル:
+  if/kimi-k2-thinking
+  if/qwen3-coder-plus
+  if/glm-4.7
+  if/minimax-m2
+  if/deepseek-r1
+```
+
+### Qwen（3つの無料モデル）
+
+```bash
+ダッシュボード → Qwenを接続
+→ デバイスコード認証
+→ 無制限使用
+
+モデル:
+  qw/qwen3-coder-plus
+  qw/qwen3-coder-flash
+```
+
+### Kiro（Claude無料）
+
+```bash
+ダッシュボード → Kiroを接続
+→ AWS Builder IDまたはGoogle/GitHub
+→ 無制限使用
+
+モデル:
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+```
+
+</details>
+
+<details>
+<summary><b>🎨 コンボの作成</b></summary>
+
+### 例1: サブスクリプション最大化 → 格安バックアップ
+
+```
+ダッシュボード → Combos → 新規作成
+
+名前: premium-coding
+モデル:
+  1. cc/claude-opus-4-6 (サブスクリプション、プライマリ)
+  2. glm/glm-4.7 (格安バックアップ、$0.6/1M)
+  3. minimax/MiniMax-M2.1 (最安フォールバック、$0.20/1M)
+
+CLIでの使用: premium-coding
+
+月額コスト例（1億トークン）:
+  8000万 Claude経由（サブスクリプション）: 追加$0
+  1500万 GLM経由: $9
+  500万 MiniMax経由: $1
+  合計: $10 + サブスクリプション
+```
+
+### 例2: 無料のみ（コストゼロ）
+
+```
+名前: free-combo
+モデル:
+  1. gc/gemini-3-flash-preview (月18万回無料)
+  2. if/kimi-k2-thinking (無制限)
+  3. qw/qwen3-coder-plus (無制限)
+
+コスト: 永久$0！
+```
+
+</details>
+
+<details>
+<summary><b>🔧 CLI統合</b></summary>
+
+### Cursor IDE
+
+```
+設定 → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [9routerダッシュボードから]
+  Model: cc/claude-opus-4-6
+```
+
+またはコンボを使用: `premium-coding`
+
+### Claude Code
+
+`~/.claude/config.json` を編集:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+### OpenClaw
+
+**オプション1 — ダッシュボード（推奨）：**
+
+```
+ダッシュボード → CLI Tools → OpenClaw → モデルを選択 → 適用
+```
+
+**オプション2 — 手動:** `~/.openclaw/openclaw.json` を編集:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "9router/if/glm-4.7"
+      }
+    }
+  },
+  "models": {
+    "providers": {
+      "9router": {
+        "baseUrl": "http://127.0.0.1:20128/v1",
+        "apiKey": "sk_9router",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "if/glm-4.7",
+            "name": "glm-4.7"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+> **注意:** OpenClawはローカルの9Routerのみで動作します。IPv6解決の問題を避けるため、`localhost` ではなく `127.0.0.1` を使用してください。
+
+### Cline / Continue / RooCode
+
+```
+プロバイダー: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [ダッシュボードから]
+Model: cc/claude-opus-4-6
+```
+
+</details>
+
+<details>
+<summary><b>🚀 デプロイ</b></summary>
+
+### VPSデプロイ
+
+```bash
+# クローンとインストール
+git clone https://github.com/decolua/9router.git
+cd 9router
+npm install
+npm run build
+
+# 設定
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/9router"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export NEXT_PUBLIC_CLOUD_URL="https://9router.com"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+export MACHINE_ID_SALT="endpoint-proxy-salt"
+
+# 起動
+npm run start
+
+# またはPM2を使用
+npm install -g pm2
+pm2 start npm --name 9router -- start
+pm2 save
+pm2 startup
+```
+
+### Docker
+
+```bash
+# イメージをビルド（リポジトリルートから）
+docker build -t 9router .
+
+# コンテナを実行（現在のセットアップで使用しているコマンド）
+docker run -d \
+  --name 9router \
+  -p 20128:20128 \
+  --env-file /root/dev/9router/.env \
+  -v 9router-data:/app/data \
+  -v 9router-usage:/root/.9router \
+  9router
+```
+
+ポータブルコマンド（リポジトリルートにいる場合）：
+
+```bash
+docker run -d \
+  --name 9router \
+  -p 20128:20128 \
+  --env-file ./.env \
+  -v 9router-data:/app/data \
+  -v 9router-usage:/root/.9router \
+  9router
+```
+
+コンテナのデフォルト：
+- `PORT=20128`
+- `HOSTNAME=0.0.0.0`
+
+便利なコマンド：
+
+```bash
+docker logs -f 9router
+docker restart 9router
+docker stop 9router && docker rm 9router
+```
+
+### 環境変数
+
+| 変数 | デフォルト | 説明 |
+|------|-----------|------|
+| `JWT_SECRET` | 自動生成（`~/.9router/jwt-secret`） | ダッシュボード認証クッキーのJWT署名シークレット（複数インスタンス間で共有する場合に設定） |
+| `INITIAL_PASSWORD` | `123456` | 保存されたハッシュがない場合の初回ログインパスワード |
+| `DATA_DIR` | `~/.9router` | メインアプリのデータベース格納場所（`db.json`） |
+| `PORT` | フレームワークデフォルト | サービスポート（例では`20128`） |
+| `HOSTNAME` | フレームワークデフォルト | バインドホスト（Dockerデフォルトは`0.0.0.0`） |
+| `NODE_ENV` | ランタイムデフォルト | デプロイ時は`production`に設定 |
+| `BASE_URL` | `http://localhost:20128` | クラウド同期ジョブで使用されるサーバーサイド内部ベースURL |
+| `CLOUD_URL` | `https://9router.com` | サーバーサイドのクラウド同期エンドポイントベースURL |
+| `NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | 後方互換/公開ベースURL（サーバーランタイムには`BASE_URL`を推奨） |
+| `NEXT_PUBLIC_CLOUD_URL` | `https://9router.com` | 後方互換/公開クラウドURL（サーバーランタイムには`CLOUD_URL`を推奨） |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | 生成されたAPIキーのHMACシークレット |
+| `MACHINE_ID_SALT` | `endpoint-proxy-salt` | 安定したマシンIDハッシュのソルト |
+| `ENABLE_REQUEST_LOGS` | `false` | `logs/` 配下のリクエスト/レスポンスログを有効化 |
+| `AUTH_COOKIE_SECURE` | `false` | 認証クッキーに`Secure`を強制（HTTPSリバースプロキシの背後では`true`に設定） |
+| `REQUIRE_API_KEY` | `false` | `/v1/*` ルートでBearer APIキーを必須にする（インターネット公開デプロイで推奨） |
+| `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` | 空 | アップストリームプロバイダー呼び出し用のオプショナルアウトバウンドプロキシ |
+
+注意事項：
+- 小文字のプロキシ変数もサポート: `http_proxy`, `https_proxy`, `all_proxy`, `no_proxy`
+- `.env` はDockerイメージにベイクされません（`.dockerignore`）; `--env-file` または `-e` でランタイム設定を注入してください。
+- Windowsでは、`APPDATA` をローカルストレージパスの解決に使用できます。
+- `INSTANCE_NAME` は古いドキュメント/envテンプレートに記載がありますが、現在ランタイムでは使用されていません。
+
+### ランタイムファイルとストレージ
+
+- メインアプリ状態: `${DATA_DIR}/db.json`（プロバイダー、コンボ、エイリアス、キー、設定）、`src/lib/localDb.js` で管理。
+- 使用履歴とログ: `~/.9router/usage.json` と `~/.9router/log.txt`、`src/lib/usageDb.js` で管理。
+- オプションのリクエスト/トランスレーターログ: `ENABLE_REQUEST_LOGS=true` 時に `<repo>/logs/...`。
+- 使用状況ストレージは現在 `~/.9router` パスロジックに従い、`DATA_DIR` とは独立しています。
+
+</details>
+
+---
+
+## 📊 利用可能なモデル
+
+<details>
+<summary><b>すべての利用可能なモデルを表示</b></summary>
+
+**Claude Code (`cc/`)** - Pro/Max:
+- `cc/claude-opus-4-6`
+- `cc/claude-sonnet-4-5-20250929`
+- `cc/claude-haiku-4-5-20251001`
+
+**Codex (`cx/`)** - Plus/Pro:
+- `cx/gpt-5.2-codex`
+- `cx/gpt-5.1-codex-max`
+
+**Gemini CLI (`gc/`)** - 無料:
+- `gc/gemini-3-flash-preview`
+- `gc/gemini-2.5-pro`
+
+**GitHub Copilot (`gh/`)**:
+- `gh/gpt-5`
+- `gh/claude-4.5-sonnet`
+
+**GLM (`glm/`)** - $0.6/1M:
+- `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** - $0.2/1M:
+- `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** - 無料:
+- `if/kimi-k2-thinking`
+- `if/qwen3-coder-plus`
+- `if/deepseek-r1`
+
+**Qwen (`qw/`)** - 無料:
+- `qw/qwen3-coder-plus`
+- `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** - 無料:
+- `kr/claude-sonnet-4.5`
+- `kr/claude-haiku-4.5`
+
+</details>
+
+---
+
+## 🐛 トラブルシューティング
+
+**「Language model did not provide messages」**
+- プロバイダーのクオータが使い果たされた → ダッシュボードのクオータトラッカーを確認
+- 解決策: コンボフォールバックを使用するか、より安いティアに切り替え
+
+**レート制限**
+- サブスクリプションクオータ切れ → GLM/MiniMaxにフォールバック
+- コンボを追加: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+
+**OAuthトークンの期限切れ**
+- 9Routerが自動リフレッシュ
+- 問題が続く場合: ダッシュボード → Provider → 再接続
+
+**高コスト**
+- ダッシュボードで使用状況を確認
+- プライマリモデルをGLM/MiniMaxに切り替え
+- 重要でないタスクには無料ティア（Gemini CLI、iFlow）を使用
+
+**ダッシュボードが違うポートで開く**
+- `PORT=20128` と `NEXT_PUBLIC_BASE_URL=http://localhost:20128` を設定
+
+**初回ログインできない**
+- `.env` の `INITIAL_PASSWORD` を確認
+- 未設定の場合、デフォルトパスワードは `123456`
+
+**`logs/` にリクエストログがない**
+- `ENABLE_REQUEST_LOGS=true` に設定
+
+---
+
+## 🛠️ 技術スタック
+
+- **ランタイム**: Node.js 20+
+- **フレームワーク**: Next.js 16
+- **UI**: React 19 + Tailwind CSS 4
+- **データベース**: LowDB（JSONファイルベース）
+- **ストリーミング**: Server-Sent Events (SSE)
+- **認証**: OAuth 2.0 (PKCE) + JWT + APIキー
+
+---
+
+## 📝 APIリファレンス
+
+### チャット補完
+
+```bash
+POST http://localhost:20128/v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### モデル一覧
+
+```bash
+GET http://localhost:20128/v1/models
+Authorization: Bearer your-api-key
+
+→ すべてのモデル + コンボをOpenAI形式で返却
+```
+
+## 📧 サポート
+
+- **ウェブサイト**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+
+---
+
+## 👥 コントリビューター
+
+9Routerの改善に貢献してくださったすべてのコントリビューターに感謝します！
+
+[![Contributors](https://contrib.rocks/image?repo=decolua/9router&max=150&columns=15&anon=1&v=20260309)](https://github.com/decolua/9router/graphs/contributors)
+
+---
+
+## 📊 スターチャート
+
+[![Star Chart](https://starchart.cc/decolua/9router.svg?variant=adaptive)](https://starchart.cc/decolua/9router)
+
+
+
+## 🔀 フォーク
+
+**[OmniRoute](https://github.com/diegosouzapw/OmniRoute)** — 9RouterのフルフィーチャーTypeScriptフォーク。36以上のプロバイダー、4段階自動フォールバック、マルチモーダルAPI（画像、埋め込み、音声、TTS）、サーキットブレーカー、セマンティックキャッシュ、LLM評価、洗練されたダッシュボードを追加。368以上のユニットテスト。npmとDockerで利用可能。
+
+---
+
+## 🙏 謝辞
+
+**CLIProxyAPI** に特別な感謝を — このJavaScriptポートのインスピレーションとなったオリジナルのGo実装です。
+
+---
+
+## 📄 ライセンス
+
+MITライセンス - 詳細は [LICENSE](../LICENSE) を参照してください。
+
+---
+
+<div align="center">
+  <sub>24時間365日コーディングする開発者のために ❤️ で構築</sub>
+</div>
diff --git a/i18n/README.ru.md b/i18n/README.ru.md
new file mode 100644
index 0000000..01ed17b
--- /dev/null
+++ b/i18n/README.ru.md
@@ -0,0 +1,1311 @@
+<div align="center">
+  <img src="../images/9router.png?1" alt="Панель управления 9Router" width="800"/>
+  
+  # 9Router - Free AI Router
+  
+  **Никогда не прекращайте кодить. Автоматическая маршрутизация к БЕСПЛАТНЫМ и дешёвым AI-моделям с умным механизмом резервирования.**
+  
+  **Бесплатный AI-провайдер для OpenClaw.**
+  
+  <p align="center">
+    <img src="../public/providers/openclaw.png" alt="OpenClaw" width="80"/>
+  </p>
+  
+  [![npm](https://img.shields.io/npm/v/9router.svg)](https://www.npmjs.com/package/9router)
+  [![Downloads](https://img.shields.io/npm/dm/9router.svg)](https://www.npmjs.com/package/9router)
+  [![License](https://img.shields.io/npm/l/9router.svg)](https://github.com/decolua/9router/blob/main/LICENSE)
+  
+  [🚀 Быстрый старт](#-quick-start) • [💡 Возможности](#-key-features) • [📖 Установка](#-setup-guide) • [🌐 Сайт](https://9router.com)
+</div>
+
+---
+
+## 🤔 Почему 9Router?
+
+**Перестаньте тратить деньги и упираться в лимиты:**
+
+- ❌ Квота подписки сгорает каждый месяц, не будучи израсходованной
+- ❌ Ограничение скорости (rate limit) прерывает вас прямо во время работы
+- ❌ Дорогие API ($20-50/мес за каждого провайдера)
+- ❌ Приходится вручную переключаться между провайдерами
+
+**9Router решает это:**
+
+- ✅ **Максимум из подписки** — Отслеживает квоту, использует каждый бит до сброса
+- ✅ **Автоматическое резервирование** — Подписка → Дёшево → Бесплатно, нулевой простой
+- ✅ **Несколько аккаунтов** — Round-robin по аккаунтам каждого провайдера
+- ✅ **Универсальность** — Работает с Claude Code, Codex, Gemini CLI, Cursor, Cline, любым CLI-инструментом
+
+---
+
+## 🔄 Как это работает
+
+```
+┌─────────────┐
+│  Your CLI   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│   Tool      │
+└──────┬──────┘
+       │ http://localhost:20128/v1
+       ↓
+┌────────────────────────────────────────┐
+│           9Router (Smart Router)        │
+│  • Format translation (OpenAI ↔ Claude) │
+│  • Quota tracking                       │
+│  • Auto token refresh                   │
+└──────┬──────────────────────────────────┘
+       │
+       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+       │   ↓ quota exhausted
+       ├─→ [Tier 2: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
+       │   budget limit
+       └─→ [Tier 3: FREE] iFlow, Qwen, Kiro (unlimited)
+
+Result: Never stop coding, minimal cost
+```
+
+---
+
+## ⚡ Быстрый старт
+
+**1. Глобальная установка:**
+
+```bash
+npm install -g 9router
+9router
+```
+
+🎉 Панель управления откроется на `http://localhost:20128`
+
+**2. Подключите БЕСПЛАТНОГО провайдера (без подписки):**
+
+Панель управления → Providers → Подключить **Claude Code** или **Antigravity** → Вход через OAuth → Готово!
+
+**3. Используйте в вашем CLI-инструменте:**
+
+```
+Настройки Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline:
+  Endpoint: http://localhost:20128/v1
+  API Key: [скопируйте из панели управления]
+  Model: if/kimi-k2-thinking
+```
+
+**Готово!** Начинайте кодить с БЕСПЛАТНЫМИ AI-моделями.
+
+**Альтернатива: запуск из исходников (этот репозиторий):**
+
+Пакет этого репозитория приватный (`9router-app`), поэтому запуск из исходников/Docker — это ожидаемый путь локальной разработки.
+
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+Режим Production:
+
+```bash
+npm run build
+PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start
+```
+
+URL по умолчанию:
+- Панель управления: `http://localhost:20128/dashboard`
+- OpenAI-совместимый API: `http://localhost:20128/v1`
+
+---
+
+## 🎥 Видео-руководство
+
+<div align="center">
+  
+### 📺 Полное руководство по настройке - 9Router + Claude Code БЕСПЛАТНО
+  
+[![Настройка 9Router + Claude Code](https://img.youtube.com/vi/raEyZPg5xE0/maxresdefault.jpg)](https://www.youtube.com/watch?v=raEyZPg5xE0)
+
+**🎬 Полное пошаговое руководство:**
+- ✅ Установка и настройка 9Router
+- ✅ Настройка Claude Sonnet 4.5 БЕСПЛАТНО
+- ✅ Интеграция с Claude Code
+- ✅ Тестирование кода вживую
+
+**⏱️ Длительность:** 20 минут | **👥 Автор:** Сообщество разработчиков
+
+[▶️ Смотреть на YouTube](https://www.youtube.com/watch?v=o3qYCyjrFYg)
+
+</div>
+
+---
+
+## 🛠️ Поддерживаемые CLI-инструменты
+
+9Router бесшовно работает со всеми основными AI-инструментами для кодинга:
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/openclaw.png" width="60" alt="OpenClaw"/><br/>
+        <b>OpenClaw</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/opencode.png" width="60" alt="OpenCode"/><br/>
+        <b>OpenCode</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/cline.png" width="60" alt="Cline"/><br/>
+        <b>Cline</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/continue.png" width="60" alt="Continue"/><br/>
+        <b>Continue</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/droid.png" width="60" alt="Droid"/><br/>
+        <b>Droid</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/roo.png" width="60" alt="Roo"/><br/>
+        <b>Roo</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/copilot.png" width="60" alt="Copilot"/><br/>
+        <b>Copilot</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/kilocode.png" width="60" alt="Kilo Code"/><br/>
+        <b>Kilo Code</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+---
+
+## Поддерживаемые провайдеры
+
+### 🔐 OAuth-провайдеры
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/github.png" width="60" alt="GitHub"/><br/>
+        <b>GitHub</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🆓 Бесплатные провайдеры
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="150">
+        <img src="../public/providers/iflow.png" width="70" alt="iFlow"/><br/>
+        <b>iFlow AI</b><br/>
+        <sub>8+ моделей • Без ограничений</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/qwen.png" width="70" alt="Qwen"/><br/>
+        <b>Qwen Code</b><br/>
+        <sub>3+ моделей • Без ограничений</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/gemini-cli.png" width="70" alt="Gemini CLI"/><br/>
+        <b>Gemini CLI</b><br/>
+        <sub>180K/мес БЕСПЛАТНО</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/kiro.png" width="70" alt="Kiro"/><br/>
+        <b>Kiro AI</b><br/>
+        <sub>Claude • Без ограничений</sub>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🔑 Провайдеры с API Key (40+)
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/openrouter.png" width="50" alt="OpenRouter"/><br/>
+        <sub>OpenRouter</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/glm.png" width="50" alt="GLM"/><br/>
+        <sub>GLM</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/kimi.png" width="50" alt="Kimi"/><br/>
+        <sub>Kimi</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/minimax.png" width="50" alt="MiniMax"/><br/>
+        <sub>MiniMax</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/openai.png" width="50" alt="OpenAI"/><br/>
+        <sub>OpenAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/anthropic.png" width="50" alt="Anthropic"/><br/>
+        <sub>Anthropic</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/gemini.png" width="50" alt="Gemini"/><br/>
+        <sub>Gemini</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/deepseek.png" width="50" alt="DeepSeek"/><br/>
+        <sub>DeepSeek</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/groq.png" width="50" alt="Groq"/><br/>
+        <sub>Groq</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/xai.png" width="50" alt="xAI"/><br/>
+        <sub>xAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/mistral.png" width="50" alt="Mistral"/><br/>
+        <sub>Mistral</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/perplexity.png" width="50" alt="Perplexity"/><br/>
+        <sub>Perplexity</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/together.png" width="50" alt="Together"/><br/>
+        <sub>Together AI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/fireworks.png" width="50" alt="Fireworks"/><br/>
+        <sub>Fireworks</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/cerebras.png" width="50" alt="Cerebras"/><br/>
+        <sub>Cerebras</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/cohere.png" width="50" alt="Cohere"/><br/>
+        <sub>Cohere</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/nvidia.png" width="50" alt="NVIDIA"/><br/>
+        <sub>NVIDIA</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/siliconflow.png" width="50" alt="SiliconFlow"/><br/>
+        <sub>SiliconFlow</sub>
+      </td>
+    </tr>
+  </table>
+  <p><i>...и более 20 других провайдеров, включая Nebius, Chutes, Hyperbolic и пользовательские OpenAI/Anthropic-совместимые эндпоинты</i></p>
+</div>
+
+---
+
+## 💡 Ключевые возможности
+
+| Возможность | Что делает | Почему это важно |
+|---------|--------------|----------------|
+| 🎯 **Smart 3-Tier Fallback** | Авто-маршрутизация: Подписка → Дёшево → Бесплатно | Никогда не прекращайте кодить, нулевой простой |
+| 📊 **Отслеживание квоты в реальном времени** | Живой подсчёт токенов + обратный отсчёт до сброса | Максимум ценности из подписки |
+| 🔄 **Трансляция форматов** | OpenAI ↔ Claude ↔ Gemini бесшовно | Работает с любым CLI-инструментом |
+| 👥 **Поддержка нескольких аккаунтов** | Несколько аккаунтов на каждого провайдера | Балансировка нагрузки + резервирование |
+| 🔄 **Авто-обновление токена** | OAuth-токены обновляются автоматически | Не нужно входить вручную заново |
+| 🎨 **Пользовательские комбо** | Создавайте безграничные комбинации моделей | Настройте резервирование под себя |
+| 📝 **Логирование запросов** | Режим отладки с полным логом запросов/ответов | Лёгкая диагностика проблем |
+| 💾 **Облачная синхронизация** | Синхронизация конфигурации между устройствами | Одинаковые настройки везде |
+| 📊 **Аналитика использования** | Отслеживание токенов, затрат, трендов во времени | Оптимизация расходов |
+| 🌐 **Развёртывание где угодно** | Localhost, VPS, Docker, Cloudflare Workers | Гибкие варианты развёртывания |
+
+<details>
+<summary><b>📖 Подробности о возможностях</b></summary>
+
+### 🎯 Smart 3-Tier Fallback
+
+Создавайте комбо с автоматическим резервированием:
+
+```
+Combo: "my-coding-stack"
+  1. cc/claude-opus-4-6        (ваша подписка)
+  2. glm/glm-4.7               (дешёвый бэкап, $0.6/1M)
+  3. if/kimi-k2-thinking       (бесплатное резервирование)
+
+→ Автопереключение при исчерпании квоты или ошибке
+```
+
+### 📊 Отслеживание квоты в реальном времени
+
+- Потребление токенов по каждому провайдеру
+- Обратный отсчёт до сброса (5 часов, ежедневно, еженедельно)
+- Оценка затрат для платных уровней
+- Ежемесячный отчёт о расходах
+
+### 🔄 Трансляция форматов
+
+Бесшовная трансляция между форматами:
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
+- Ваш CLI-инструмент отправляет формат OpenAI → 9Router транслирует → Провайдер получает родной формат
+- Работает с любым инструментом, поддерживающим пользовательский эндпоинт OpenAI
+
+### 👥 Поддержка нескольких аккаунтов
+
+- Добавляйте несколько аккаунтов на каждого провайдера
+- Round-robin или маршрутизация по приоритету автоматически
+- Резервирование на следующий аккаунт при достижении квоты
+
+### 🔄 Авто-обновление токена
+
+- OAuth-токены автоматически обновляются до истечения срока
+- Не нужна повторная ручная аутентификация
+- Бесшовный опыт со всеми провайдерами
+
+### 🎨 Пользовательские комбо
+
+- Создавайте безграничные комбинации моделей
+- Сочетайте уровни подписки, дешёвые и бесплатные
+- Называйте комбо для удобного доступа
+- Делитесь комбо между устройствами через облачную синхронизацию
+
+### 📝 Логирование запросов
+
+- Включите режим отладки для просмотра полного лога запросов/ответов
+- Отслеживайте вызовы API, заголовки и payload
+- Диагностируйте проблемы интеграции
+- Экспортируйте логи для анализа
+
+### 💾 Облачная синхронизация
+
+- Синхронизация провайдеров, комбо и настроек между устройствами
+- Автоматическая фоновая синхронизация
+- Безопасное зашифрованное хранилище
+- Доступ к настройкам откуда угодно
+
+#### Заметки о облачном рантайме
+
+- Приоритет серверным облачным переменным в production-окружении:
+  - `BASE_URL` (внутренний callback URL, используемый планировщиком синхронизации)
+  - `CLOUD_URL` (база эндпоинта облачной синхронизации)
+- `NEXT_PUBLIC_BASE_URL` и `NEXT_PUBLIC_CLOUD_URL` по-прежнему поддерживаются для совместимости/UI, но серверный рантайм теперь приоритезирует `BASE_URL`/`CLOUD_URL`.
+- Запросы облачной синхронизации теперь используют тайм-аут + fail-fast поведение, чтобы избежать зависания UI при недоступности DNS/облачной сети.
+
+### 📊 Аналитика использования
+
+- Отслеживание использования токенов по провайдеру и модели
+- Оценка затрат и тренды расходов
+- Ежемесячные отчёты и инсайты
+- Оптимизация ваших AI-расходов
+
+> **💡 ВАЖНО - Понимание «Затрат» на панели управления:**
+> 
+> «Затраты», показанные в Аналитике использования, предназначены **только для отслеживания и сравнения**. 
+> Сам 9Router **никогда ничего не взимает** с вас. Вы платите напрямую провайдерам (если используете платные сервисы).
+> 
+> **Пример:** Если на панели показано «общие затраты $290» при использовании моделей iFlow, это представляет 
+> сумму, которую вы заплатили бы при прямом использовании платного API. Ваши фактические затраты = **$0** (iFlow бесплатен без ограничений).
+> 
+> Считайте это «трекером экономии», показывающим, сколько вы экономите, используя бесплатные модели или 
+> маршрутизацию через 9Router!
+
+### 🌐 Развёртывание где угодно
+
+- 💻 **Localhost** — По умолчанию, работает офлайн
+- ☁️ **VPS/Cloud** — Общий доступ между устройствами
+- 🐳 **Docker** — Развёртывание одной командой
+- 🚀 **Cloudflare Workers** — Глобальная edge-сеть
+
+</details>
+
+---
+
+## 💰 Обзор цен
+
+| Уровень | Провайдер | Стоимость | Сброс квоты | Лучше всего для |
+|------|----------|------|-------------|----------|
+| **💳 ПОДПИСКА** | Claude Code (Pro) | $20/мес | 5ч + еженедельно | Уже подписаны |
+| | Codex (Plus/Pro) | $20-200/мес | 5ч + еженедельно | Пользователи OpenAI |
+| | Gemini CLI | **БЕСПЛАТНО** | 180K/мес + 1K/день | Для всех! |
+| | GitHub Copilot | $10-19/мес | Ежемесячно | Пользователи GitHub |
+| **💰 ДЁШЕВО** | GLM-4.7 | $0.6/1M | 10:00 ежедневно | Бюджетный бэкап |
+| | MiniMax M2.1 | $0.2/1M | Скользящие 5 часов | Самый дешёвый вариант |
+| | Kimi K2 | $9/мес фикс. | 10M токенов/мес | Предсказуемая стоимость |
+| **🆓 БЕСПЛАТНО** | iFlow | $0 | Без ограничений | 8 бесплатных моделей |
+| | Qwen | $0 | Без ограничений | 3 бесплатные модели |
+| | Kiro | $0 | Без ограничений | Claude бесплатно |
+
+**💡 Профи-совет:** Начните с комбо Gemini CLI (180K бесплатно/мес) + iFlow (без ограничений бесплатно) = $0 затрат!
+
+---
+
+### 📊 Понимание затрат и оплаты в 9Router
+
+**Реальность оплаты 9Router:**
+
+✅ **Софт 9Router = БЕСПЛАТНО навсегда** (открытый код, никогда не взимает плату)  
+✅ **«Затраты» на панели = Только для отображения/отслеживания** (не реальный счёт)  
+✅ **Вы платите напрямую провайдерам** (подписка или плата за API)  
+✅ **БЕСПЛАТНЫЕ провайдеры остаются БЕСПЛАТНЫМИ** (iFlow, Kiro, Qwen = $0 без ограничений)  
+❌ **9Router никогда не выставляет счёт** и не списывает с вашей карты
+
+**Как работает отображение затрат:**
+
+Панель показывает **оценочные затраты**, как если бы вы напрямую использовали платный API. Это **не оплата** — это инструмент сравнения, показывающий вашу экономию.
+
+**Пример сценария:**
+```
+Показано на панели:
+• Всего запросов: 1,662
+• Всего токенов: 47M
+• Отображаемые затраты: $290
+
+Реальная проверка:
+• Провайдер: iFlow (БЕСПЛАТНО без ограничений)
+• Фактическая оплата: $0.00
+• Значение $290: Сумма, которую вы СЭКОНОМИЛИ, используя бесплатные модели!
+```
+
+**Правила оплаты:**
+- **Провайдеры подписки** (Claude Code, Codex): Платите им напрямую через их сайт
+- **Дешёвые провайдеры** (GLM, MiniMax): Платите им напрямую, 9Router только маршрутизирует
+- **БЕСПЛАТНЫЕ провайдеры** (iFlow, Kiro, Qwen): Действительно бесплатны навсегда, без скрытых платежей
+- **9Router**: Никогда ничего не взимает, никогда
+
+---
+
+## 🎯 Сценарии использования
+
+### Сценарий 1: «У меня подписка Claude Pro»
+
+**Проблема:** Квота сгорает неиспользованной, rate limit при интенсивной работе
+
+**Решение:**
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (полное использование подписки)
+  2. glm/glm-4.7               (дешёвый бэкап при исчерпании квоты)
+  3. if/kimi-k2-thinking       (бесплатное аварийное резервирование)
+
+Месячная стоимость: $20 (подписка) + ~$5 (бэкап) = $25 итого
+против $20 + упирание в лимит = разочарование
+```
+
+### Сценарий 2: «Хочу нулевые затраты»
+
+**Проблема:** Не могу позволить подписку, нужен надёжный AI-кодинг
+
+**Решение:**
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K бесплатно/мес)
+  2. if/kimi-k2-thinking       (без ограничений бесплатно)
+  3. qw/qwen3-coder-plus       (без ограничений бесплатно)
+
+Месячная стоимость: $0
+Качество: Production-ready модели
+```
+
+### Сценарий 3: «Нужно кодить 24/7, без перерывов»
+
+**Проблема:** Дедлайны, нельзя допустить простоя
+
+**Решение:**
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (лучшее качество)
+  2. cx/gpt-5.2-codex          (вторая подписка)
+  3. glm/glm-4.7               (дёшево, ежедневный сброс)
+  4. minimax/MiniMax-M2.1      (самый дешёвый, сброс 5ч)
+  5. if/kimi-k2-thinking       (бесплатно без ограничений)
+
+Результат: 5 слоёв резервирования = нулевой простой
+Месячная стоимость: $20-200 (подписки) + $10-20 (бэкап)
+```
+
+### Сценарий 4: «Хочу БЕСПЛАТНЫЙ AI в OpenClaw»
+
+**Проблема:** Нужен AI-ассистент в мессенджерах (WhatsApp, Telegram, Slack...), полностью бесплатно
+
+**Решение:**
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (без ограничений бесплатно)
+  2. if/minimax-m2.1           (без ограничений бесплатно)
+  3. if/kimi-k2-thinking       (без ограничений бесплатно)
+
+Месячная стоимость: $0
+Доступ через: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## ❓ Часто задаваемые вопросы
+
+<details>
+<summary><b>📊 Почему моя панель показывает высокие затраты?</b></summary>
+
+Панель отслеживает ваше использование токенов и показывает **оценочные затраты**, как если бы вы напрямую использовали платный API. Это **не реальная оплата** — это справка, показывающая, сколько вы экономите, используя бесплатные модели или существующие подписки через 9Router.
+
+**Пример:**
+- **Панель показывает:** «Общие затраты $290»
+- **Реальность:** Вы используете iFlow (БЕСПЛАТНО без ограничений)
+- **Ваши фактические затраты:** **$0.00**
+- **Значение $290:** Сумма, которую вы **экономите**, используя бесплатные модели вместо платного API!
+
+Отображение затрат — это «трекер экономии», помогающий понять паттерны использования и возможности оптимизации.
+
+</details>
+
+<details>
+<summary><b>💳 Взимает ли с меня плату 9Router?</b></summary>
+
+**Нет.** 9Router — это бесплатное ПО с открытым кодом, работающее на вашем собственном компьютере. Оно никогда ничего с вас не взимает.
+
+**Вы платите только:**
+- ✅ **Провайдерам подписки** (Claude Code $20/мес, Codex $20-200/мес) → Платите им напрямую на их сайте
+- ✅ **Дешёвым провайдерам** (GLM, MiniMax) → Платите им напрямую, 9Router только маршрутизирует ваши запросы
+- ❌ **Самому 9Router** → **Никогда ничего не взимает, никогда**
+
+9Router — это локальный прокси/роутер. У него нет вашей кредитной карты, он не может выставлять счета и не имеет платёжной системы. Это полностью бесплатное ПО.
+
+</details>
+
+<details>
+<summary><b>🆓 Действительно ли БЕСПЛАТНЫЕ провайдеры безлимитны?</b></summary>
+
+**Да!** Провайдеры, отмеченные как БЕСПЛАТНЫЕ (iFlow, Kiro, Qwen), действительно безлимитны и **без скрытых платежей**. 
+
+Это бесплатные сервисы, предоставляемые соответствующими компаниями:
+- **iFlow**: Бесплатный безлимитный доступ к 8+ моделям через OAuth
+- **Kiro**: Бесплатные безлимитные модели Claude через AWS Builder ID  
+- **Qwen**: Бесплатный безлимитный доступ к моделям Qwen через аутентификацию устройства
+
+9Router только маршрутизирует ваши запросы к ним — никаких «ловушек» или будущих платежей. Это действительно бесплатные сервисы, а 9Router облегчает их использование с поддержкой резервирования.
+
+**Примечание:** Некоторые провайдеры подписки (Antigravity, GitHub Copilot) могут иметь бесплатные пробные периоды, которые позже становятся платными, но об этом чётко уведомляют сами провайдеры, а не 9Router.
+
+</details>
+
+<details>
+<summary><b>💰 Как минимизировать мои реальные AI-затраты?</b></summary>
+
+**Стратегия «Бесплатное в приоритете»:**
+
+1. **Начните со 100% бесплатного комбо:**
+   ```
+   1. gc/gemini-3-flash (180K/мес бесплатно от Google)
+   2. if/kimi-k2-thinking (без ограничений бесплатно от iFlow)
+   3. qw/qwen3-coder-plus (без ограничений бесплатно от Qwen)
+   ```
+   **Стоимость: $0/мес**
+
+2. **Добавьте дешёвый бэкап** только при необходимости:
+   ```
+   4. glm/glm-4.7 ($0.6/1M токенов)
+   ```
+   **Доп. стоимость:** Платите только за то, что фактически используете
+
+3. **Используйте провайдеров подписки в последнюю очередь:**
+   - Только если они у вас уже есть
+   - 9Router помогает максимизировать их ценность через отслеживание квоты
+
+**Результат:** Большинство пользователей могут работать за $0/мес, используя только бесплатные уровни!
+
+</details>
+
+<details>
+<summary><b>📈 Что если моё использование внезапно вырастет?</b></summary>
+
+Умный механизм резервирования 9Router предотвращает неожиданные расходы:
+
+**Сценарий:** Вы в спринте кодинга и превышаете квоты
+
+**Без 9Router:**
+- ❌ Упёрлись в rate limit → Работа остановилась → Разочарование
+- ❌ Или: Случайно накопили огромный счёт за API
+
+**С 9Router:**
+- ✅ Подписка упёрлась в лимит → Авторезервирование на дешёвый уровень
+- ✅ Дешёвый уровень становится дорогим → Авторезервирование на бесплатный уровень
+- ✅ Никогда не прекращаете кодить → Предсказуемая стоимость
+
+**Вы контролируете:** Установите лимиты расходов на каждого провайдера в панели, и 9Router будет их соблюдать.
+
+</details>
+
+---
+
+## 📖 Руководство по настройке
+
+<details>
+<summary><b>🔐 Провайдеры подписки (Максимум ценности)</b></summary>
+
+### Claude Code (Pro/Max)
+
+```bash
+Панель управления → Providers → Подключить Claude Code
+→ Вход через OAuth → Авто-обновление токена
+→ Отслеживание квоты 5 часов + еженедельно
+
+Модели:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**Профи-совет:** Используйте Opus для сложных задач, Sonnet для скорости. 9Router отслеживает квоту для каждой модели!
+
+### OpenAI Codex (Plus/Pro)
+
+```bash
+Панель управления → Providers → Подключить Codex
+→ Вход через OAuth (порт 1455)
+→ Сброс 5 часов + еженедельно
+
+Модели:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+### Gemini CLI (БЕСПЛАТНО 180K/мес!)
+
+```bash
+Панель управления → Providers → Подключить Gemini CLI
+→ Google OAuth
+→ 180K запросов/мес + 1K/день
+
+Модели:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Лучшая ценность:** Огромный бесплатный уровень! Используйте его перед платными уровнями.
+
+### GitHub Copilot
+
+```bash
+Панель управления → Providers → Подключить GitHub
+→ OAuth через GitHub
+→ Ежемесячный сброс (1-го числа месяца)
+
+Модели:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+</details>
+
+<details>
+<summary><b>💰 Дешёвые провайдеры (Бэкап)</b></summary>
+
+### GLM-4.7 (Ежедневный сброс, $0.6/1M)
+
+1. Регистрация: [Zhipu AI](https://open.bigmodel.cn/)
+2. Получите API key из Coding Plan
+3. Панель управления → Добавить API Key:
+   - Провайдер: `glm`
+   - API Key: `your-key`
+
+**Использование:** `glm/glm-4.7`
+
+**Профи-совет:** Coding Plan даёт втрое больше квоты за 1/7 стоимости! Сброс ежедневно в 10:00.
+
+### MiniMax M2.1 (Сброс 5ч, $0.20/1M)
+
+1. Регистрация: [MiniMax](https://www.minimax.io/)
+2. Получите API key
+3. Панель управления → Добавить API Key
+
+**Использование:** `minimax/MiniMax-M2.1`
+
+**Профи-совет:** Самый дешёвый вариант для длинного контекста (1M)!
+
+### Kimi K2 ($9/мес фиксированно)
+
+1. Регистрация: [Moonshot AI](https://platform.moonshot.ai/)
+2. Получите API key
+3. Панель управления → Добавить API Key
+
+**Использование:** `kimi/kimi-latest`
+
+**Профи-совет:** Фиксированные $9/мес за 10M токенов = реальная стоимость $0.90/1M!
+
+</details>
+
+<details>
+<summary><b>🆓 БЕСПЛАТНЫЕ провайдеры (Аварийное резервирование)</b></summary>
+
+### iFlow (8 БЕСПЛАТНЫХ моделей)
+
+```bash
+Панель управления → Подключить iFlow
+→ Вход через OAuth iFlow
+→ Безлимитное использование
+
+Модели:
+  if/kimi-k2-thinking
+  if/qwen3-coder-plus
+  if/glm-4.7
+  if/minimax-m2
+  if/deepseek-r1
+```
+
+### Qwen (3 БЕСПЛАТНЫЕ модели)
+
+```bash
+Панель управления → Подключить Qwen
+→ Авторизация по коду устройства
+→ Безлимитное использование
+
+Модели:
+  qw/qwen3-coder-plus
+  qw/qwen3-coder-flash
+```
+
+### Kiro (БЕСПЛАТНЫЙ Claude)
+
+```bash
+Панель управления → Подключить Kiro
+→ AWS Builder ID или Google/GitHub
+→ Безлимитное использование
+
+Модели:
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+```
+
+</details>
+
+<details>
+<summary><b>🎨 Создание комбо</b></summary>
+
+### Пример 1: Максимум из подписки → Дешёвый бэкап
+
+```
+Панель управления → Combos → Создать новое
+
+Имя: premium-coding
+Модели:
+  1. cc/claude-opus-4-6 (Основная подписка)
+  2. glm/glm-4.7 (Дешёвый бэкап, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Самое дешёвое резервирование, $0.20/1M)
+
+Использование в CLI: premium-coding
+
+Пример месячной стоимости (100M токенов):
+  80M через Claude (подписка): $0 дополнительно
+  15M через GLM: $9
+  5M через MiniMax: $1
+  Итого: $10 + ваша подписка
+```
+
+### Пример 2: Только бесплатно (Нулевая стоимость)
+
+```
+Имя: free-combo
+Модели:
+  1. gc/gemini-3-flash-preview (180K бесплатно/мес)
+  2. if/kimi-k2-thinking (без ограничений)
+  3. qw/qwen3-coder-plus (без ограничений)
+
+Стоимость: $0 навсегда!
+```
+
+</details>
+
+<details>
+<summary><b>🔧 Интеграция CLI</b></summary>
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [из панели управления 9router]
+  Model: cc/claude-opus-4-6
+```
+
+Или используйте комбо: `premium-coding`
+
+### Claude Code
+
+Отредактируйте `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "ваш промпт"
+```
+
+### OpenClaw
+
+**Вариант 1 — Панель управления (рекомендуется):**
+
+```
+Панель управления → CLI Tools → OpenClaw → Выбрать модель → Применить
+```
+
+**Вариант 2 — Вручную:** Отредактируйте `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "9router/if/glm-4.7"
+      }
+    }
+  },
+  "models": {
+    "providers": {
+      "9router": {
+        "baseUrl": "http://127.0.0.1:20128/v1",
+        "apiKey": "sk_9router",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "if/glm-4.7",
+            "name": "glm-4.7"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+> **Примечание:** OpenClaw работает только с локальным 9Router. Используйте `127.0.0.1` вместо `localhost`, чтобы избежать проблем с разрешением имён.
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [из панели управления]
+Model: cc/claude-opus-4-6
+```
+
+</details>
+
+<details>
+<summary><b>🚀 Развёртывание</b></summary>
+
+### Развёртывание на VPS
+
+```bash
+# Clone and install
+git clone https://github.com/decolua/9router.git
+cd 9router
+npm install
+npm run build
+
+# Configure
+export JWT="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/9router"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export NEXT_PUBLIC_CLOUD_URL="https://9router.com"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+export MACHINE_ID_SALT="endpoint-proxy-salt"
+
+# Start
+npm run start
+
+# Or use PM2
+npm install -g pm2
+pm2 start --name 9router -- start
+pm2 save
+pm2 startup
+```
+
+### Docker
+
+```bash
+# Build image (from repository root)
+docker build -t 9router .
+
+# Run container (command used in current setup)
+docker run -d \
+  --name 9router \
+  -p 20128:20128 \
+  --env-file /root/dev/9router/.env \
+  -v 9router-data:/app/data \
+  -v 9router-usage:/root/.9router \
+  9router
+```
+
+Портативная команда (если вы уже в корне репозитория):
+
+```bash
+docker run -d \
+  --name 9router \
+  -p 20128:20128 \
+  --env-file ./.env \
+  -v 9router-data:/app/data \
+  -v 9router-usage:/root/.9router \
+  9router
+```
+
+Значения по умолчанию контейнера:
+- `PORT=20128`
+- `HOSTNAME=0.0.0.0`
+
+Полезные команды:
+
+```bash
+docker logs -f 9router
+docker restart 9router
+docker stop 9router && docker rm 9router
+```
+
+### Переменные окружения
+
+| Переменная | По умолчанию | Описание |
+|----------|---------|-------------|
+| `JWT_SECRET` | Автогенерация (`~/.9router/jwt-secret`) | Секрет подписи JWT для cookie аутентификации панели (задайте для общего доступа между инстансами) |
+| `INITIAL_PASSWORD` | `123456` | Пароль первого входа при отсутствии сохранённого хеша |
+| `DATA_DIR` | `~/.9router` | Расположение основной БД приложения (`db.json`) |
+| `PORT` | framework default | Порт сервиса (`20128` в примерах) |
+| `HOSTNAME` | framework default | Bind host (Docker по умолчанию `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Установите `production` для развёртывания |
+| `BASE_URL` | `http://localhost:20128` | Внутренний серверный базовый URL для задач облачной синхронизации |
+| `CLOUD_URL` | `https://9router.com` | Серверный базовый URL эндпоинта облачной синхронизации |
+| `NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | Обратно совместимый/публичный базовый URL (приоритет `BASE_URL` для серверного рантайма) |
+| `NEXT_PUBLIC_CLOUD_URL` | `https://9router.com` | Обратно совместимый/публичный облачный URL (приоритет `CLOUD_URL` для серверного рантайма) |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC-секрет для генерируемых API-ключей |
+| `MACHINE_ID_SALT` | `endpoint-proxy-salt` | Соль для стабильного хеширования ID машины |
+| `ENABLE_REQUEST_LOGS` | `false` | Включить лог запросов/ответов в `logs/` |
+| `AUTH_COOKIE_SECURE` | `false` | Принудительный `Secure` cookie аутентификации (задайте `true` за HTTPS reverse proxy) |
+| `REQUIRE_API_KEY` | `false` | Требовать Bearer API key на маршрутах `/v1/*` (рекомендуется для развёртываний с выходом в интернет) |
+| `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` | empty | Опциональный исходящий прокси для вызовов к провайдерам |
+
+Примечания:
+- Прокси-переменные в нижнем регистре также поддерживаются: `http_proxy`, `https_proxy`, `all_proxy`, `no_proxy`.
+- `.env` не запекается в Docker-образ (`.dockerignore`); подавайте runtime-конфигурацию через `--env-file` или `-e`.
+- В Windows для разрешения путей локального хранилища может использоваться `APPDATA`.
+- `INSTANCE_NAME` встречается в старых docs/env-шаблонах, но сейчас в рантайме не используется.
+
+### Runtime-файлы и хранилище
+
+- Основное состояние приложения: `${DATA_DIR}/db.json` (провайдеры, комбо, alias, ключи, настройки), управляется `src/lib/localDb.js`.
+- История использования и логи: `~/.9router/usage.json` и `~/.9router/log.txt`, управляется `src/lib/usageDb.js`.
+- Опциональные логи запросов/транслятора: `<repo>/logs/...` при `ENABLE_REQUEST_LOGS=true`.
+- Хранилище использования следует логике пути `~/.9router` и независимо от `DATA_DIR`.
+
+</details>
+
+---
+
+## 📊 Доступные модели
+
+<details>
+<summary><b>Показать все доступные модели</b></summary>
+
+**Claude Code (`cc/`)** - Pro/Max:
+- `cc/claude-opus-4-6`
+- `cc/claude-sonnet-4-5-20250929`
+- `cc/claude-haiku-4-5-20251001`
+
+**Codex (`cx/`)** - Plus/Pro:
+- `cx/gpt-5.2-codex`
+- `cx/gpt-5.1-codex-max`
+
+**Gemini CLI (`gc/`)** - БЕСПЛАТНО:
+- `gc/gemini-3-flash-preview`
+- `gc/gemini-2.5-pro`
+
+**GitHub Copilot (`gh/`)**:
+- `gh/gpt-5`
+- `gh/claude-4.5-sonnet`
+
+**GLM (`glm/`)** - $0.6/1M:
+- `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** - $0.2/1M:
+- `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** - БЕСПЛАТНО:
+- `if/kimi-k2-thinking`
+- `if/qwen3-coder-plus`
+- `if/deepseek-r1`
+
+**Qwen (`qw/`)** - БЕСПЛАТНО:
+- `qw/qwen3-coder-plus`
+- `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** - БЕСПЛАТНО:
+- `kr/claude-sonnet-4.5`
+- `kr/claude-haiku-4.5`
+
+</details>
+
+---
+
+## 🐛 Устранение неполадок
+
+**"Language model did not provide messages"**
+- Исчерпана квота провайдера → Проверьте трекер квоты на панели
+- Решение: Используйте резервирование комбо или переключитесь на более дешёвый уровень
+
+**Ограничение скорости (Rate limiting)**
+- Исчерпана квота подписки → Резервирование на GLM/MiniMax
+- Добавьте комбо: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+
+**OAuth-токен истёк**
+- Автообновление 9Router
+- Если проблема сохраняется: Панель управления → Провайдеры → Переподключить
+
+**Высокие затраты**
+- Проверьте статистику использования в панели
+- Переключите основную модель на GLM/MiniMax
+- Используйте бесплатные уровни (Gemini CLI, iFlow) для некритичных задач
+
+**Панель открывается на неверном порту**
+- Установите `PORT=20128` и `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+
+**Ошибки облачной синхронизации**
+- Убедитесь, что `BASE_URL` указывает на ваш работающий инстанс (например, `http://localhost:20128`)
+- Убедитесь, что `CLOUD_URL` указывает на ожидаемый облачный эндпоинт (например, `https://9router.com`)
+- По возможности держите значения `NEXT_PUBLIC_*` согласованными с серверными значениями.
+
+**Облачный эндпоинт `stream=false` возвращает 500 (`Unexpected token 'd'...`)**
+- Симптом обычно появляется на публичном облачном эндпоинте (`https://9router.com/v1`) для непотоковых (non-streaming) вызовов.
+- Корневая причина: upstream возвращает SSE-payload (`data: ...`), тогда как клиент ожидает JSON.
+- Обходное решение: используйте `stream=true` для прямых вызовов в облако.
+- Локальный рантайм 9Router включает резервирование SSE→JSON для непотоковых вызовов, когда upstream возвращает `text/event-stream`.
+
+**Облако сообщает о подключении, но запрос всё равно падает с `Invalid API key`**
+- Создайте новый ключ в локальной панели (`/api/keys`) и запустите облачную синхронизацию (`Enable Cloud`, затем `Sync Now`).
+- Старые/несинхронизированные ключи могут возвращать `401` в облаке, даже если локальный эндпоинт работает.
+
+**Первый вход не работает**
+- Проверьте `INITIAL_PASSWORD` в `.env`
+- Если не задан, резервный пароль — `123456`
+
+**Нет логов запросов в `logs/`**
+- Установите `ENABLE_REQUEST_LOGS=true`
+
+---
+
+## 🛠️ Tech Stack
+
+- **Runtime**: Node.js 20+
+- **Framework**: Next.js 16
+- **UI**: React 19 + Tailwind 4
+- **Database**: LowDB (на основе JSON-файлов)
+- **Streaming**: Server-Sent Events (SSE)
+- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
+
+---
+
+## 📝 Справочник по API
+
+### Chat Completions
+
+```bash
+POST http://localhost:20128/v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Напиши функцию для..."}
+  ],
+  "stream": true
+}
+```
+
+### Список моделей
+
+```bash
+GET http://localhost:20128/v1/models
+Authorization: Bearer your-api-key
+
+→ Возвращает все модели + комбо в формате OpenAI
+```
+
+### Совместимые эндпоинты
+
+- `POST /v1/chat/completions`
+- `POST /v1/messages`
+- `POST /v1/responses`
+- `GET /v1/models`
+- `POST /v1/messages/count_tokens`
+- `GET /v1beta/models`
+- `POST /v1beta/models/{...path}` (Gemini-style `generateContent`)
+- `POST /v1/api/chat` (путь конвертации в стиле Ollama)
+
+### Скрипты облачной аутентификации
+
+Добавлены тестовые скрипты в `tester/security/`:
+
+- `tester/security/test-docker-hardening.sh`
+  - Собирает Docker-образ и проверяет hardening-проверки (`/api/cloud/auth` auth guard, `REQUIRE_API_KEY`, безопасное поведение cookie аутентификации).
+- `tester/security/test-cloud-openai-compatible.sh`
+  - Отправляет OpenAI-совместимый запрос напрямую на облачный эндпоинт (`https://9router.com/v1/chat/completions`) с указанной моделью/ключом.
+- `tester/security/test-cloud-sync-and-call.sh`
+  - End-to-end процесс: создание локального ключа → включение/синхронизация облака → вызов облачного эндпоинта с повтором.
+  - Включает резервную проверку с `stream=true`, чтобы отличить ошибки аутентификации от проблем разбора потока.
+
+Заметки по безопасности для облачных тестовых скриптов:
+
+- Никогда не хардкодьте реальные API-ключи в скриптах/коммитах.
+- Передавайте ключи только через переменные окружения:
+  - `API_KEY`, `CLOUD_API_KEY` или `OPENAI_API_KEY` (поддерживается `test-cloud-openai-compatible.sh`)
+- Пример:
+
+```bash
+OPENAI_API_KEY="your-cloud-key" bash tester/security/test-cloud-openai-compatible.sh
+```
+
+Ожидаемое поведение по результатам недавней проверки:
+
+- Локально (`http://127.0.0.1:20128/v1/chat/completions`): работает с `stream=false` и `stream=true`.
+- Docker-рантайм (тот же API-путь, экспонируемый контейнером): hardening-проверки проходят, cloud auth guard работает, строгий режим API-ключа работает при включении.
+- Публичный облачный эндпоинт (`https://9router.com/v1/chat/completions`):
+  - `stream=true`: ожидается успех (возвращает SSE-чанки).
+  - `stream=false`: может падать с `500` + ошибкой разбора (`Unexpected token 'd'`), когда upstream возвращает SSE-контент для непотокового клиентского пути.
+
+### API управления и панели
+
+- Аутентификация/настройки: `/api/auth/login`, `/api/auth/logout`, `/api/settings`, `/api/settings/require-login`
+- Управление провайдерами: `/api/providers`, `/api/providers/[id]`, `/api/providers/[id]/test`, `/api/providers/[id]/models`, `/api/providers/validate`, `/api/provider-n*`
+- OAuth-потоки: `/api/oauth/[provider]/[action]` (+ специфичные для провайдеров импорты, такие как Cursor/Kiro)
+- Конфигурация маршрутизации: `/api/models/alias`, `/api/combos*`, `/api/keys*`, `/api/pricing`
+- Использование/логи: `/api/usage/history`, `/api/usage/logs`, `/api/usage/request-logs`, `/api/usage/[connectionId]`
+- Облачная синхронизация: `/api/sync/cloud`, `/api/sync/initialize`, `/api/cloud/*`
+- Помощники CLI: `/api/cli-tools/claude-settings`, `/api/cli-tools/codex-settings`, `/api/cli-tools/droid-settings`, `/api/cli-tools/openclaw-settings`
+
+### Поведение аутентификации
+
+- Маршруты панели (`/dashboard/*`) используют защиту cookie `auth_token`.
+- Вход использует сохранённый хеш пароля при наличии; иначе откатывается к `INITIAL_PASSWORD`.
+- `requireLogin` можно переключить через `/api/settings/require-login`.
+
+### Обработка запросов (высокоуровнево)
+
+1. Клиент отправляет запрос на `/v1/*`.
+2. Обработчик маршрута вызывает `handleChat` (`src/sse/handlers/chat.js`).
+3. Модель разрешается (прямой провайдер/модель или разрешение alias/combo).
+4. Учётные данные выбираются из локальной БД с фильтром доступности аккаунта.
+5. `handleChatCore` (`open-sse/handlers/chatCore.js`) определяет формат и транслирует запрос.
+6. Исполнитель провайдера отправляет upstream-запрос.
+7. Поток при необходимости транслируется обратно в клиентский формат.
+8. Использование/логи записываются (`src/lib/usageDb.js`).
+9. Резервирование применяется при ошибках провайдера/аккаунта/модели по правилам комбо.
+
+Полный справочник по архитектуре: [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md)
+
+---
+
+## 📧 Поддержка
+
+- **Сайт**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+
+---
+
+## 👥 Контрибьюторы
+
+Спасибо всем, кто помогает делать 9Router лучше!
+
+[![Contributors](https://contrib.rocks/image?repo=decolua/9router&max=100&columns=20&anon=1)](https://github.com/decolua/9router/graphs/contributors)
+
+---
+
+## 📊 Star Chart
+
+[![Star Chart](https://starchart.cc/decolua/9router.svg?variant=adaptive)](https://starchart.cc/decolua/9router)
+
+### Как внести вклад
+
+1. Сделайте форк репозитория
+2. Создайте свою feature-ветку (`git checkout -b feature/amazing-feature`)
+3. Закоммитьте изменения (`git commit -m 'Add amazing feature'`)
+4. Запушьте в ветку (`git push origin feature/amazing-feature`)
+5. Откройте Pull Request
+
+См. [Pull Requests](https://github.com/decolua/9router/pulls) для подробных инструкций.
+
+---
+
+## 🔀 Форки
+
+**[OmniRoute](https://github.com/diegosouzapw/OmniRoute)** — Полнофункциональный TypeScript-форк 9Router. Добавляет 36+ провайдеров, авторезервирование на 4 уровнях, мультимодальный API (изображения, embedding, аудио, TTS), circuit breaker, семантическое кеширование, оценку LLM и доработанную панель. 368+ юнит-тестов. Доступен через npm.
+
+---
+
+## 🙏 Благодарности
+
+Особая благодарность **CLIProxyAPI** — оригинальной Go-реализации, вдохновившей этот JavaScript-порт.
+
+---
+
+## 📄 Лицензия
+
+Лицензия MIT — см. [LICENSE](../LICENSE) для деталей.
+
+---
+
+<div align="center">
+  <sub>Создано с ❤️ для разработчиков, которые кодят 24/7</sub>
+</div>
diff --git a/i18n/README.vi.md b/i18n/README.vi.md
new file mode 100644
index 0000000..d0a51de
--- /dev/null
+++ b/i18n/README.vi.md
@@ -0,0 +1,1310 @@
+Dưới đây là bản dịch tiếng Việt của tài liệu Markdown, giữ nguyên toàn bộ cú pháp và cấu trúc kỹ thuật.
+
+<div align="center">
+  <img src="../images/9router.png?1" alt="Bảng điều khiển 9Router" width="800"/>
+  
+  # 9Router - Free AI Router
+  
+  **Không bao giờ ngừng code. Tự động định tuyến tới các mô hình AI MIỄN PHÍ & giá rẻ với cơ chế dự phòng thông minh.**
+  
+  **Nhà cung cấp AI Miễn cho OpenClaw.**
+  
+  <p align="center">
+    <img src="../public/providers/openclaw.png" alt="OpenClaw" width="80"/>
+  </p>
+  
+  [![npm](https://img.shields.io/npm/v/9router.svg)](https://www.npmjs.com/package/9router)
+  [![Downloads](https://img.shields.io/npm/dm/9router.svg)](https://www.npmjs.com/package/9router)
+  [![License](https://img.shields.io/npm/l/9router.svg)](https://github.com/decolua/9router/blob/main/LICENSE)
+  
+  [🚀 Bắt đầu nhanh](#-quick-start) • [💡 Tính năng](#-key-features) • [📖 Cài đặt](#-setup-guide) • [🌐 Website](https://9router.com)
+</div>
+
+---
+
+## 🤔 Tại sao chọn 9Router?
+
+**Ngừng lãng phí tiền bạc và gặp phải giới hạn:**
+
+- ❌ Hạn mức gói đăng ký hết hạn mỗi tháng mà không dùng hết
+- ❌ Giới hạn tốc độ (rate limit) ngăn bạn giữaừng khi code
+- ❌ Các API đắt đỏ ($20-50/tháng cho mỗi nhà cung cấp)
+- ❌ Phải chuyển đổi thủ công giữa các nhà cung cấp
+
+**9Router giải quyết vấn đề này:**
+
+- ✅ **Tối đa hóa gói đăng ký** - Theo dõi hạn mức, sử dụng từng bit trước khi reset
+- ✅ **Tự động dự phòng** - Gói đăng ký → Giá rẻ → Miễn phí, thời gian chết bằng không
+- ✅ **Đa tài khoản** - Vòng tròn (round-robin) các tài khoản của mỗi nhà cung cấp
+- ✅ **Phổ quát** - Hoạt động với Claude Code, Codex, Gemini CLI, Cursor, Cline, bất kỳ công cụ CLI nào
+
+---
+
+## 🔄 Cách thức hoạt động
+
+```
+┌─────────────┐
+│  Your CLI   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│   Tool      │
+└──────┬──────┘
+       │ http://localhost:20128/v1
+       ↓
+┌────────────────────────────────────────┐
+│           9Router (Smart Router)        │
+│  • Format translation (OpenAI ↔ Claude) │
+│  • Quota tracking                       │
+│  • Auto token refresh                   │
+└──────┬──────────────────────────────────┘
+       │
+       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+       │   ↓ quota exhausted
+       ├─→ [Tier 2: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
+       │   budget limit
+       └─→ [Tier 3: FREE] iFlow, Qwen, Kiro (unlimited)
+
+Result: Never stop coding, minimal cost
+```
+
+---
+
+## ⚡ Bắt đầu nhanh
+
+**1. Cài đặt toàn cục:**
+
+```bash
+npm install -g 9router
+9router
+```
+
+🎉 Bảng điều khiển mở tại `http://localhost:20128`
+
+**2. Kết nối nhà cung cấp MIỄN PHÍ (không cần đăng ký):**
+
+Bảng điều khiển → Providers -> Kết nối **ude Code** hoặc **Antigravity** -> Đăng nhập OAuth -> Xong!
+
+**3. Sử dụng trong công cụ CLI của bạn:**
+
+```
+Cài đặt Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline:
+  Endpoint: http://localhost:20128/v1
+  API Key: [sao chép từ bảng điều khiển]
+  Model: if/kimi-k2-thinking
+```
+
+**Xong rồi!** Bắt đầu code với các mô hình AI MIỄN PHÍ.
+
+**Phương án khác: chạy từ nguồn (k lưu trữ này):**
+
+Gói kho lưu trữ này là riêng tư (`9router-app`), vì vậy việc thực thi nguồn/Docker là đường dẫn phát triển cục bộ dự kiến.
+
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+Chế độ Production:
+
+```bash
+npm run build
+PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start
+```
+
+URL mặc định:
+- Bảng điều khiển: `http://localhost:20128/dashboard`
+- API tương thích OpenAI: `http://localhost:20128/v1`
+
+---
+
+## 🎥 Hướng dẫn Video
+
+<div align="center">
+  
+### 📺 Hướng dẫn thiết lập hoàn chỉnh - 9Router + Claude Code MIỄN PHÍ
+  
+[![Thiết lập 9Router + Claude Code](https://img.youtube.com/vi/raEyZPg5xE0/maxresdefault.jpg)](https://www.youtube.com/watch?v=raEyZPg5xE0)
+
+**🎬 Xem hướng dẫn từng đầy đủ:**
+- ✅ Cài đặt & thiết lập 9Router
+- ✅ Cấu hình Claude Sonnet 4.5 MIỄN PHÍ
+- ✅ Tích hợp Claude Code
+- ✅ Thử nghiệm code trực tiếp
+
+**⏱️ Thời lượng:** 20 phút | **👥 Bởi:** Cộng đồng Nhà phát triển
+
+[▶️ Xem trên YouTube](https://www.youtube.com/watch?v=o3qYCyjrFYg)
+
+</div>
+
+---
+
+## 🛠️ Các công cụ CLI được hỗ trợ
+
+9Router hoạt động liền mạch với tất cả các công cụ code AI chính:
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/openclaw.png" width="60" alt="OpenClaw"/><br/>
+        <b>OpenClaw</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/opencode.png" width="60" alt="OpenCode"/><br/>
+        <b>OpenCode</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/cline.png" width="60" alt="Cline"/><br/>
+        <b>Cline</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/continue.png" width="60" alt="Continue"/><br/>
+        <b>Continue</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/droid.png" width="60" alt="Droid"/><br/>
+        <b>Droid</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/roo.png" width="60" alt="Roo"/><br/>
+        <b>Roo</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/copilot.png" width="60" alt="Copilot"/><br/>
+        <b>Copilot</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/kilocode.png" width="60" alt="Kilo Code"/><br/>
+        <b>Kilo Code</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+---
+
+##  Các nhà cung cấp được hỗ trợ
+
+### 🔐 Các nhà cung cấp OAuth
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/github.png" width="60" alt="GitHub"/><br/>
+        <b>GitHub</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🆓 Các nhà cung cấp Miễn phí
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="150">
+        <img src="../public/providers/iflow.png" width="70" alt="iFlow"/><br/>
+        <b>iFlow AI</b><br/>
+        <sub>8+ mô hình • Không giới hạn</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/qwen.png" width="70" alt="Qwen"/><br/>
+        <b>Qwen Code</b><br/>
+        <sub>3+ mô hình • Không giới hạn</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/gemini-cli.png" width="70" alt="Gemini CLI"/><br/>
+        <b>Gemini CLI</b><br/>
+        <sub>180K/tháng MIỄN PHÍ</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/kiro.png" width="70" alt="Kiro"/><br/>
+        <b>Kiro AI</b><br/>
+        <sub>Claude • Không giới hạn</sub>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🔑 Các nhà cung cấp API Key (40+)
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/openrouter.png" width="50" alt="OpenRouter"/><br/>
+        <sub>OpenRouter</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/glm.png" width="50" alt="GLM"/><br/>
+        <sub>GLM</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/kimi.png" width="50" alt="Kimi"/><br/>
+        <sub>Kimi</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/minimax.png" width="50" alt="MiniMax"/><br/>
+        <sub>MiniMax</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/openai.png" width="50" alt="OpenAI"/><br/>
+        <sub>OpenAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/anthropic.png" width="50" alt="Anthropic"/><br/>
+        <sub>Anthropic</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/gemini.png" width="50" alt="Gemini"/><br/>
+        <sub>Gemini</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/deepseek.png" width="50" alt="DeepSeek"/><br/>
+        <sub>DeepSeek</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/groq.png" width="50" alt="Groq"/><br/>
+        <sub>Groq</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/xai.png" width="50" alt="xAI"/><br/>
+        <sub>xAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/mistral.png" width="50" alt="Mistral"/><br/>
+        <sub>Mistral</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/perplexity.png" width="50" alt="Perplexity"/><br/>
+        <sub>Perplexity</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/together.png" width="50" alt="Together"/><br/>
+        <sub>Together AI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/fireworks.png" width="50" alt="Fireworks"/><br/>
+        <sub>Fireworks</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/cerebras.png" width="50" alt="Cerebras"/><br/>
+        <sub>Cerebras</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/cohere.png" width="50" alt="Cohere"/><br/>
+        <sub>Cohere</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/nvidia.png" width="50" alt="NVIDIA"/><br/>
+        <sub>NVIDIA</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/siliconflow.png" width="50" alt="SiliconFlow"/><br/>
+        <sub>SiliconFlow</sub>
+      </td>
+    </tr>
+  </table>
+  <p><i>...và hơn 20 nhà cung cấp khác bao gồm Nebius, Chutes, Hyperbolic và các endpoint tương thích OpenAI/Anthropic tùy chỉnh</i></p>
+</div>
+
+---
+
+## 💡 Các tính năng chính
+
+| Tính năng | Công dụng | Tại sao nó trọng |
+|---------|--------------|----------------|
+| 🎯 **Smart 3-Tier Fallback** | Tự động định tuyến: Gói đăng ký → Giá rẻ → Miễn phí | Không bao giờ ngừng code, thời gian chết bằng không |
+| 📊 **Theo dõi hạn mức thời gian thực** | Đếm token trực tiếp + đếm ngược reset | Tối đa hóa giá trị gói đăng ký |
+| 🔄 **Dịch chuyển định dạng** | OpenAI ↔ Claude ↔ Gemini liền mạch | Hoạt động với mọi công cụ CLI |
+| 👥 **Hỗ trợ Đa tài khoản** | Nhiều tài khoản cho mỗi nhà cung cấp | Cân bằng tải + dự phòng |
+| 🔄 **Tự động làm mới Token** | Token OAuth tự động làm mới | Không cần đăng nhập lại thủ công |
+| 🎨 **Combo tùy chỉnh** | Tạo tổ hợp mô hình không giới hạn | Điều chỉnh dự phòng theo nhu cầu |
+| 📝 **Ghi log Request** | Chế độ gỡ lỗi với log request/response đầy đủ | Dễ dàng khắc phục sự cố |
+| 💾 **Đồng bộ đám mây** | Đồng bộ cấu hình giữa các thiết bị | Cài đặt giống nhau ở mọi nơi |
+| 📊 **Phân tích sử dụng** | Theo dõi token, chi phí, xu hướng theo thời gian | Tối ưu hóa chi tiêu |
+| 🌐 **Triển khai ở bất cứ đâu** | Localhost, VPS, Docker, Cloudflare Workers | Tùy chọn triển khai linh hoạt |
+
+<details>
+<summary><b>📖 Chi tiết tính năng</b></summary>
+
+### 🎯 Smart 3-Tier Fallback
+
+Tạo combo với tính năng phòng tự động:
+
+```
+Combo: "my-coding-stack"
+  1. cc/claude-opus-4-6        (gói đăng ký của bạn)
+  2. glm/glm-4.7               (backup giá rẻ, $0.6/1M)
+  3. if/kimi-k2-thinking       (dự phòng miễn phí)
+
+→ Tự động chuyển đổi khi hết hạn mức hoặc xảy ra lỗi
+```
+
+### 📊 Theo dõi hạn mức thời gian thực
+
+- Mức tiêu thụ token cho mỗi nhà cung cấp
+- Đếm ngược reset (5 giờ, hàng ngày, hàng tuần)
+- Ước tính chi phí cho các tầng trả phí
+- Báo cáo chi tiêu hàng tháng
+
+### 🔄 Dịch chuyển định dạng
+
+Dịch chuyển liền mạch giữa các định dạng:
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
+- Công cụ CLI của bạn gửi định dạng OpenAI → 9Router dịch chuyển → Nhà cung cấp nhận định dạng gốc
+- Hoạt động với mọi công cụ hỗ trợ endpoint OpenAI tùy chỉnh
+
+### 👥 Hỗ trợ Đa tài khoản
+
+- Thêm nhiều tài khoản cho mỗi nhà cung cấp
+- Định tuyến vòng tròn (round-robin) hoặc dựa trên ưu tiên tự động
+- Dự phòng sang tài khoản tiếp theo khi một tài khoản chạm hạn mức
+
+### 🔄 Tự động làm mới Token
+
+- Token OAuth tự động làm mới trước khi hết hạn
+- Không cần xác thực lại thủ công
+- Trải nghiệm liền mạch trên mọi nhà cung cấp
+
+### 🎨 Combo tùy chỉnh
+
+- Tạo tổ hợp mô hình không hạn
+- Kết hợp các tầng gói đăng ký, giá rẻ và miễn phí
+- Đặt tên combo để dễ truy cập
+- Chia sẻ combo giữa các thiết bị với Đồng bộ đám mây
+
+### 📝 Ghi log Request
+
+- Bật chế độ gỡ lỗi để xem log request/response đầy đủ
+- Theo dõi các lệnh gọi API, tiêu đề và payload
+- Khắc phục sự cố tích hợp
+- Xuất log để phân tích
+
+### 💾 Đồng bộ đám mây
+
+- Đồng bộ nhà cung cấp, combo và c đặt giữa các thiết bị
+- Tự động đồng bộ nền
+- Lưu trữ được mã hóa an toàn
+- Truy cập cài đặt của bạn từ bất cứ đâu
+
+#### Ghi chú Runtime Đám mây
+
+- Ưu tiên biến đám mây phía máy chủ trong môi trường production:
+  - `BASE_URL` (URL callback nội bộ được sử dụng bởi bộ lập lịch đồng bộ)
+  - `CLOUD_URL` (cơ sở endpoint đồng bộ đám mây)
+- `NEXT_PUBLIC_BASE_URL` và `NEXT_PUBLIC_CLOUD_URL` vẫn được hỗ trợ để thích/UI, nhưng runtime máy chủ hiện ưu tiên `BASE_URL`/`CLOUD_URL`.
+- Các yêu cầu đồng bộ đám mây hiện sử dụng thời gian chờ + hành vi fail-fast để tránh treo UI khi DNS/mạng đám mây không khả dụng.
+
+### 📊 Phân tích sử dụng
+
+- Theo dõi mức sử dụng token theo nhà cung cấp và mô hình
+- Ước tính chi phí và xu hướng chi tiêu
+- Báo cáo và thông tin chi tiết hàng tháng
+- Tối ưu hóa chi tiêu AI của bạn
+
+> **💡AN TRỌNG - Hiểu về Chi phí trên Bảng điều khiển:**
+> 
+> "Chi phí" hiển thị trong Phân tích sử dụng là **chỉ để theo dõi và so sánh**. 
+> Bản thân 9Router **không bao giờ thu phí** bạn bất cứ thứ gì. Bạn chỉ trả tiền trực tiếp cho các nhà cung cấp (nếu sử dụng dịch vụ trả phí).
+> 
+> **Ví dụ:** Nếu bảng điều khiển của bạn hiển thị "tổng chi phí $290" trong khi sử dụng các mô hìnhFlow, điều này đại diện cho 
+> số tiền bạn sẽ phải trả nếu sử dụng API trả phí trực tiếp. Chi phí thực tế của bạn = **$0** (iFlow miễn phí không giới hạn).
+> 
+> Hãy coi nó như một "trình theo dõi tiết kiệm" cho thấy bạn đang tiết kiệm được bao nhiêu bằng cách sử dụng các mô hình miễn phí hoặc 
+> định tuyến qua 9Router!
+
+### 🌐 Triển khai ở bất cứ đâu
+
+- 💻 **Localhost** - Mặc định, hoạt động ngoại tuyến
+ ☁️ **VPS/Cloud** - Chia sẻ giữa các thiết bị
+- 🐳 **Docker** - Triển khai bằng một lệnh
+- 🚀 **Cloudflare Workers** - Mạng edge toàn cầu
+
+</details>
+
+---
+
+## 💰 Tổng quan về giá
+
+| Hạng mục | Nhà cung cấp | Chi phí | Reset Hạn mức | Tốt nhất cho |
+|------|----------|------|-------------|----------|
+| **💳 GÓI ĐĂNG KÝ** | Claude Code (Pro) | $20/tháng | 5h + hàng tuần | Đã đăng ký rồi |
+| | Codex (Plus/Pro) | $20-200/tháng | 5h + hàng tuần | Người dùng OpenAI |
+| | Gemini CLI | **MIỄN PHÍ** | 180K/tháng + 1K/ngày | Tất cả mọi người! |
+| | GitHub Copilot | $10-19/tháng | Hàng tháng | Người dùng GitHub |
+| **💰 GIÁ RẺ** | GLM-4.7 | $0.6/1M | 10AM hàng ngày | Backup ngân sách |
+| | MiniMax M21 | $0.2/1M | 5 giờ luân phiên | Lựa chọn rẻ nhất |
+| | Kimi K2 | $9/tháng cố định | 10M token/tháng | Chi phí dự đoán được |
+| **🆓 MIỄN PHÍ** | iFlow | $0 | Không giới hạn | 8 mô hình miễn phí |
+| | Qwen | $0 | Không giới hạn | 3 mô hình miễn phí |
+| | Kiro | $0 | Không giới hạn | Claude miễn phí |
+
+**💡 Mẹo Chuyên nghiệp:** Bắt với combo Gemini CLI (180K miễn phí/tháng) + iFlow (không giới hạn miễn phí) = chi phí $0!
+
+---
+
+### 📊 Hiểu về Chi phí & Thanh toán của 9Router
+
+**Thực tế Thanh toán 9Router:**
+
+✅ **Phần mềm 9Router = MIỄN PHÍ mãi mãi** (mã nguồn mở, không bao giờ thu phí)  
+✅ **"Chi phí" trên bảng điều khiển = Chỉ để Hiển thị/Theo dõi** (không phải hóa đơn thực tế)  
+ **Bạn trả tiền trực tiếp cho nhà cung cấp** (gói đăng ký hoặc phí API)  
+✅ **Nhà cung cấp MIỄN PHÍ vẫn MIỄN PHÍ** (iFlow, Kiro, Qwen = $0 không giới hạn)  
+❌ **9Router không bao giờ gửi hóa đơn** hoặc tính phí thẻ của bạn
+
+**Cách Hoạt động của Hiển thị Chi phí:**
+
+Bảng điều khiển hiển thị **chi phí ước tính** như thể bạn đang sử dụng API trả phí trực tiếp. Đây **không phải là thanh toán** - đó là công cụ so sánh để cho thấy mức tiết kiệm của bạn.
+
+**Kịch bản Ví dụ:**
+```
+Hiển thị trên Bảng điều khiển:
+• Tổng số Request: 1,662
+• Tổng số Token: 47M
+• Chi phí Hiển thị: $290
+
+Kiểm tra Thực tế:
+• Nhà cung cấp: iFlow (MIỄN PHÍ không giới hạn)
+• Thanh toán Thực tế: $0.00
+• Ý nghĩa của $290: Số tiền bạn TIẾT KIỆM được bằng cách sử dụng mô hình miễn phí!
+```
+
+**Quy tắc Thanh toán:**
+- **Nhà cung cấp gói đăng ký** (Claude Code, Codex): Trả tiền trực tiếp cho họ qua website của họ
+- **Nhà cung cấp giá rẻ** (GLM, MiniMax): Trả tiền trực tiếp cho họ, 9Router chỉ định tuyến
+- **Nhà cung cấp MIỄN PHÍ** (iFlow, Kiro, Qwen): Thực sự miễn phí mãi mãi, không có phí ẩn
+- **9**: Không bao giờ thu phí bất cứ thứ gì, ever
+
+---
+
+## 🎯 Trường hợp sử dụng
+
+### Trường hợp 1: "Tôi có gói đăng ký Claude Pro"
+
+**Vấn đề:** Hạn mức hết hạn không dùng, giới hạn tốc độ khi code nặng
+
+**Giải pháp:**
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (sử dụng đầy đủ gói đăng ký)
+  2. glm/glm-4.7               (backup giá rẻ khi hết hạn mức  3. if/kimi-k2-thinking       (dự phòng khẩn cấp miễn phí)
+
+Chi phí hàng tháng: $20 (gói đăng ký) + ~$5 (backup) = $25 tổng cộng
+so với $20 + chạm giới hạn = sự thất vọng
+```
+
+### Trường hợp 2: "Tôi muốn chi phí bằng không"
+
+**Vấn đề:** Không đủ khả năng trả gói đăng ký, cần code AI đáng tin cậy
+
+**Giải pháp:**
+```
+Combo: "free-forever"
+  1. gc/gini-3-flash         (180K miễn phí/tháng)
+  2. if/kimi-k2-thinking       (không giới hạn miễn phí)
+  3. qw/qwen3-coder-plus       (không giới hạn miễn phí)
+
+Chi phí hàng tháng: $0
+Chất lượng: Các mô hình sẵn sàng cho production
+```
+
+### Trường hợp 3: "Tôi cần code 24/7, không gián đoạn"
+
+**Vấn đề:** Deadline, không thể để thời gian chết
+
+**Giải pháp:**
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (chất lượng tốt nhất)
+  2. cx/gpt-5.2-codex          (gói đăng ký thứ hai)
+  3. glm/glm-4.7               (giá rẻ, reset hàng ngày)
+  4. minimax/MiniMax-M2.1      (rẻ nhất, reset 5h)
+  5. if/kimi-k2-thinking       (miễn phí không giới hạn)
+
+Kết quả: 5 lớp dự phòng = thời gian chết bằng không
+Chi phí tháng: $20-200 (gói đăng ký) + $10-20 (backup)
+```
+
+### Trường hợp 4: "Tôi muốn AI MIỄN PHÍ trong OpenClaw"
+
+**Vấn đề:** Cần trợ lý AI trong các ứng dụng nhắn tin (WhatsApp, Telegram, Slack...), hoàn toàn miễn phí
+
+**Giải pháp:**
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (không giới hạn miễn phí)
+  2. if/minimax-m2.1           (không giới hạn phí)
+  3. if/kimi-k2-thinking       (không giới hạn miễn phí)
+
+Chi phí hàng tháng: $0
+Truy cập qua: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## ❓ Các câu hỏi thường gặp
+
+<details>
+<summary><b>📊 Tại sao bảng điều khiển của tôi hiển thị chi phí cao?</b></summary>
+
+Bảng điều khiển theo dõi mức sử dụng token của bạn và hiển thị **chi phí ước tính** như thể bạn đang sử dụng API trả phí trực tiếp. Đâykhông phải là thanh toán thực tế** - đó là tài liệu tham khảo để cho thấy bạn đang tiết kiệm được bao nhiêu bằng cách sử dụng các mô hình miễn phí hoặc gói đăng ký hiện có thông qua 9Router.
+
+**Ví dụ:**
+- **Bảng điều khiển hiển thị:** "Tổng chi phí $290"
+- **Thực tế:** Bạn đang sử dụng iFlow (MIỄN PHÍ không giới hạn)
+- **Chi phí thực tế của bạn:** **$0.00**
+- **Ý nghĩa của $290:** Số bạn **tiết kiệm** được bằng cách sử dụng các mô hình miễn phí thay vì API trả phí!
+
+Màn hình chi phí là một "trình theo dõi tiết kiệm" để giúp bạn hiểu các mẫu sử dụng và cơ hội tối ưu hóa.
+
+</details>
+
+<details>
+<summary><b>💳 Tôi có bị 9Router tính phí không?</b></summary>
+
+**Không.** 9Router là phần mềm miễn phí, mã nguồn mở chạy trên máy tính của chính bạn. Nó không bao giờ tính phí bạn bất cứ thứ gì.
+
+**Bạn chỉ trả tiền:**
+- ✅ **Nhà cung cấp gói đăng ký** (Claude Code $20/tháng, Codex $20-200/tháng) → Trả tiền trực tiếp cho họ trên website của họ
+- ✅ **Nhà cung cấp giá rẻ** (GLM, MiniMax) → Trả tiền trực tiếp cho họ, 9Router chỉ định tuyến yêu cầu của bạn
+- ❌ **Bản thân 9Router** → **Không bao giờ tính phí bất cứ thứ gì, ever**
+
+9Router là một proxy/router cục bộ. Nó không cóẻ tín dụng của bạn, không thể gửi hóa đơn và không có hệ thống thanh toán. Đó là phần mềm hoàn toàn miễn phí.
+
+</details>
+
+<details>
+<summary><b>🆓 Các nhà cung cấp MIỄN PHÍ có thực sự không giới hạn không?</b></summary>
+
+**Có!** Các nhà cung cấp được đánh dấu là MIỄN PHÍ (iFlow, Kiro, Qwen) thực sự không giới hạn với **không có phí ẩn**. 
+
+Đây là các dịch vụ miễn phí được cung cấp bởi các công ty tương ứng:
+- **iFlow**: Truy cập miễn phí không giới hạn vào hơn 8 mô hình qua OAuth
+- **Kiro**: Các mô hình Claude miễn phí không giới hạn qua AWS Builder ID  
+- **Qwen**: Truy cập miễn phí không giới hạn vào các mô hình Qwen qua xác thực thiết bị
+
+9Router chỉ định tuyến yêu cầu của bạn đến họ - không có "cạm bẫy" hay thanh toán trong tương lai. Đó là các dịch vụ thực sự miễn phí, và 9Router giúp chúng dễ sử dụng với hỗ trợ dự phòng.
+
+**Lưu ý:** số nhà cung cấp gói đăng ký (Antigravity, GitHub Copilot) có thể có các khoảng thời gian dùng thử miễn phí có thể trở thành trả phí sau này, nhưng điều này sẽ được các nhà cung cấp đó thông báo rõ ràng, không phải 9Router.
+
+</details>
+
+<details>
+<summary><b>💰 Làm thế nào để giảm thiểu chi phí AI thực tế của tôi?</b></summary>
+
+**Chiến lược Ưu tiên Miễn phí:**
+
+1. **Bắt đầu với combo 100% miễn phí:**
+   ```
+   1. gc/gemini-3-flash (180K/tháng miễn phí từ Google)
+   2. if/kimi-k2-thinking (không giới hạn miễn phí từ iFlow)
+   3. qw/qwen3-coder-plus (không giới hạn miễn phí từ Qwen)
+   ```
+   **Chi phí: $0/tháng**
+
+2. **Thêm backup giá rẻ** chỉ khi bạn cần:
+   ```
+   4. glm/glm-4.7 ($0.6/1M token)
+   ```
+   **Chi phí bổ sung:** Chỉ trả tiền cho những gì bạn sự sử dụng
+
+3. **Sử dụng nhà cung cấp gói đăng ký cuối cùng:**
+   - Chỉ khi bạn đã có chúng
+   - 9Router giúp tối đa hóa giá trị của chúng thông qua theo dõi hạn mức
+
+**Kết quả:** Hầu hết người dùng có thể hoạt động ở mức $0/tháng chỉ sử dụng các tầng miễn phí!
+
+</details>
+
+<details>
+<summary><b>📈 Điều gì xảy ra nếu mức sử dụng của tôi đột ngột tăng vọt?</b></summary>
+
+Cơ chế dự phòng thông minh của 9Router ngăn chặn các khoản phí bất ngờ:
+
+**Kịch bản:** Bạn đang trong giai đoạn code nước rút và vượt qua các hạn mức
+
+**Không có 9Router:**
+- ❌ Chạm giới hạn tốc độ → Công việc dừng lại → Thất vọng
+- ❌ Hoặc: Vô tình tích lũy hóa đơn API khổng lồ
+
+**Có 9Router:**
+- ✅ Gói đăng ký chạm giới hạn → Tự động dự phòng sang tầng giá rẻ
+- ✅ Tầng giá rẻ trở nên đắt đỏ → Tự động dự phòng sang tầng miễn phí
+- ✅ Không bao giờ ngừng code → Chi phí dự đoán được
+
+**Bạn nắm quyền kiểm soát:** Đặt giới hạn chi tiêu cho mỗi nhà cung cấp trong bảng điều khiển, và 9Router sẽ tuân thủ chúng.
+
+</details>
+
+---
+
+## 📖 Hướng dẫn thiết lập
+
+<details>
+<summary><b>🔐 Các nhà cung cấp Gói đăng ký (Tối đa hóa Giá trị)</b></summary>
+
+### Claude Code (Pro/Max)
+
+```bash
+Bảng điều khiển → Providers → Kết nối Claude Code
+→ Đăng nhập OAuth → Tự động làm mới token
+→ Theo dõi hạn mức 5 giờ + hàng tuần
+
+Các mô hình:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**Mẹo Chuyên nghiệp:** Sử dụng Opus cho các tác vụ phức tạp, Sonnet cho tốc độ. 9Router theo dõi hạn mức cho mỗi mô hình!
+
+### OpenAI Codex (Plus/Pro)
+
+```bash
+Bảng điều khiển → Providers → Kết nối Codex
+→ Đăng nhập OAuth (cổng 1455)
+→ Reset 5 giờ + hàng tuần
+
+Các mô hình:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+### Gemini CLI (MIỄN PHÍ 180K/tháng!)
+
+```bash
+Bảng điều khiển → Providers → Kết nối Gemini CLI
+→ Google OAuth
+→ 180K hoàn thành/tháng + 1K/ngày
+
+Các hình:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Giá trị tốt nhất:** Tầng miễn phí khổng lồ! Sử dụng cái này trước các tầng trả phí.
+
+### GitHub Copilot
+
+```bash
+Bảng điều khiển → Providers → Kết nối GitHub
+→ OAuth qua GitHub
+→ Reset hàng tháng (ngày 1 của tháng)
+
+Các mô hình:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+`
+
+</details>
+
+<details>
+<summary><b>💰 Các nhà cung cấp Giá rẻ (Backup)</b></summary>
+
+### GLM-4.7 (Reset hàng ngày, $0.6/1M)
+
+1. Đăng ký: [Zhipu AI](https://open.bigmodel.cn/)
+2. Lấy API key từ Coding Plan
+3. Bảng điều khiển → Thêm API Key:
+   - Nhà cung cấp: `glm`
+   - API Key: `your-key`
+
+**Sử dụng:** `glm/glm-4.7`
+
+**Mẹo Ch nghiệp:** Coding Plan cung cấp hạn mức gấp 3 lần với chi phí 1/7! Reset hàng ngày lúc 10:00 AM.
+
+### MiniMax M2.1 (Reset 5h, $0.20/1M)
+
+1. Đăng ký: [MiniMax](https://www.minimax.io/)
+2. Lấy API key
+3. Bảng điều khiển → Thêm API Key
+
+**Sử dụng:** `minimax/MiniMax-M2.1`
+
+**Mẹo Chuyên nghiệp:** Lựa chọn rẻ nhất cho ngữ cảnh dài (1M)!
+
+### Kimi K2 ($9/tháng cố định)
+
+1. Đăng ký: [Moonshot AI](https://platform.moonshot.ai/)
+2. Lấy API key
+3. Bảng điều khiển → Thêm API Key
+
+**Sử dụng:** `kimi/kimi-latest`
+
+**Mẹo Chuyên nghiệp:** Cố định $9/tháng cho 10M token = chi phí thực tế $0.90/1M!
+
+</details>
+
+<details>
+<summary><b>🆓 Các nhà cung cấp MIỄN PHÍ (Dự phòng Khẩn cấpb></summary>
+
+### iFlow (8 mô hình MIỄN PHÍ)
+
+```bash
+Bảng điều khiển → Kết nối iFlow
+→ Đăng nhập OAuth iFlow
+→ Sử dụng không giới hạn
+
+Các mô hình:
+  if/kimi-k2-thinking
+  if/qwen3-coder-plus
+  if/glm-4.7
+  if/minimax-m2
+  if/deepseek-r1
+```
+
+### Qwen (3 mô hình MIỄN PHÍ)
+
+```bash
+Bảng điều khiển → Kết nối Qwen
+ Ủy quyền mã thiết bị
+→ Sử dụng không giới hạn
+
+Các mô hình:
+  qw/qwen3-coder-plus
+  qw/qwen3-coder-flash
+```
+
+### Kiro (Claude MIỄN PHÍ)
+
+```bash
+Bảng điều khiển → Kết nối Kiro
+→ AWS Builder ID hoặc Google/GitHub
+→ Sử dụng không giới hạn
+
+Các mô hình:
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+```
+
+</details>
+
+<details>
+<summary><b>🎨 Tạo Combo</b></summary>
+
+### Ví dụ 1: Tối đa hóa Gói đăng ký → Backup Giá rẻ
+
+```
+Bảng điều khiển → Combos → Tạo Mới
+
+Tên: premium-coding
+Các mô hình:
+  1. cc/claude-opus-4-6 (Gói đăng ký chính)
+  2. glm/glm-4.7 (Backup giá rẻ, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Dự phòng rẻ nhất, $0.20/M)
+
+Sử dụng trong CLI: premium-coding
+
+Ví dụ chi phí hàng tháng (100M token):
+  80M qua Claude (gói đăng ký): $0 thêm
+  15M qua GLM: $9
+  5M qua MiniMax: $1
+  Tổng: $10 + gói đăng ký của bạn
+```
+
+### Ví dụ 2: Chỉ Miễn phí (Chi phí bằng không)
+
+```
+Tên: free-combo
+Các mô hình:
+  1. gc/gemini-3-flash-preview (180K miễn phíáng)
+  2. if/kimi-k2-thinking (không giới hạn)
+  3. qw/qwen3-coder-plus (không giới hạn)
+
+Chi phí: $0 mãi mãi!
+```
+
+</details>
+
+<details>
+<summary><b>🔧 Tích hợp CLI</b></summary>
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [từ bảng điều khiển 9router]
+  Model: cc/claude-opus-4-6
+``Hoặc sử dụng combo: `premium-coding`
+
+### Claude Code
+
+Chỉnh sửa `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "prompt của bạn"
+```
+
+### OpenClaw
+
+**Phương án 1 — B điều khiển (khuyên dùng):**
+
+```
+Bảng điều khiển → CLI Tools → OpenClaw → Chọn Mô hình → Áp dụng
+```
+
+**Phương án 2 — Thủ công:** Chỉnh sửa `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "9router/if/glm-4.7"
+      }
+    }
+  },
+  "models": {
+    "providers": {
+      "9router": {
+        "baseUrl": "://127.0.0.1:20128/v1",
+        "apiKey": "sk_9router",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "if/glm-4.7",
+            "name": "glm-4.7"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+> **Lưu ý:** OpenClaw chỉ hoạt động với 9Router cục bộ. Sử dụng `127.0.0.1` thay vì `localhost` để tránh các vấn đề phân giải6.
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [từ bảng điều khiển]
+Model: cc/claude-opus-4-6
+```
+
+</details>
+
+<details>
+<summary><b>🚀 Triển khai</b></summary>
+
+### Triển khai VPS
+
+```bash
+# Clone và cài đặt
+git clone https://github.com/decolua/9router.git
+cd 9router
+npm install
+npm run build
+
+# Cấu hình
+export JWT="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/9router"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export NEXT_PUBLIC_CLOUD_URL="https://9router.com"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+export MACHINE_ID_SALT="endpoint-proxy-salt"
+
+# Khởi động
+npm run start
+
+# Hoặc sử dụng PM2
+npm install -g pm2
+pm2 start --name 9router -- start
+pm2 save
+pm2 startup
+```
+
+### Docker
+
+```bash
+# Build image (từ gốc kho lưu trữ)
+docker build -t 9router .
+
+# Chạy container (lệnh được sử dụng trong thiết lập hiện tại)
+docker run -d \
+  --name 9router \
+  -p 20128:20128 \
+  --env-file /root/dev/9router/.env \
+  -v 9router-data:/app/data \
+  -v 9router-usage:/root/.9router \
+  9router
+```
+
+Lệnh di động (nếu bạn đã ở gốc kho lưu trữ):
+
+```bash
+docker run -d \
+  --name 9router \
+  -p 20128:20128 \
+  --env-file ./.env \
+  -v 9router-data:/app/data \
+  -v 9router-usage:/root/.9router \
+  9router
+```
+
+Mặc định container:
+- `PORT=20128`
+- `HOSTNAME=0.0.0.0`
+
+Các lệnh hữu ích:
+
+```bash
+docker logs -f 9router
+ restart 9router
+docker stop 9router && docker rm 9router
+```
+
+### Biến môi trường
+
+| Biến | Mặc định | Mô tả |
+|----------|---------|-------------|
+| `JWT_SECRET` | Tự động sinh (`~/.9router/jwt-secret`) | Bí mật ký JWT cho cookie xác thực bảng điều khiển (đặt để chia sẻ giữa nhiều instance) |
+| `INITIAL_PASSWORD` | `123456` | Mật khẩu đăng nhập đầu tiên khi không có hash đã lưu tồn tại |
+| `DATA_DIR` | `~/.9router` |ị trí cơ sở dữ liệu ứng dụng chính (`db.json`) |
+| `PORT` | framework default | Cổng dịch vụ (`20128` trong các ví dụ) |
+| `HOSTNAME` | framework default | Bind host (Docker mặc định là `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Đặt `production` để triển khai |
+| `BASE_URL` | `http://localhost:20128` | URL cơ sở nội bộ phía máy chủ được sử dụng bởi các tác vụ đồng bộ đám mây |
+| `CLOUD_URL` | `https://9router.com` | URL cơ sở endpoint đồng bộ đám mây phía máy chủ |
+| `NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | URL cơ sở tương thích ngược/công khai (ưu tiên `BASE_URL` cho runtime máy chủ) |
+| `NEXT_PUBLIC_CLOUD_URL` | `https://9router.com` | URL đám mây tương thích ngược/công khai (ưu tiên `CLOUD_URL` cho runtime máy chủ) |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | B mật HMAC cho các API key được tạo |
+| `MACHINE_ID_SALT` | `endpoint-proxy-salt` | Salt cho việc băm ID máy ổn định |
+| `ENABLE_REQUEST_LOGS` | `false` | Bật log request/response dưới `logs/` |
+| `AUTH_COOKIE_SECURE` | `false` | Buộc cookie xác thực `Secure` (đặt `true` phía reverse proxy HTTPS) |
+| `REQUIRE_API_KEY` | `false` | Thực thi Bearer API key trên các route `/v1/*` (khuyên dùng cho triển khai xúc internet) |
+| `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` | empty | Proxy gửi đi tùy chọn cho các lệnh gọi nhà cung cấp upstream |
+
+Ghi chú:
+- Các biến proxy chữ thường cũng được hỗ trợ: `http_proxy`, `https_proxy`, `all_proxy`, `no_proxy`.
+- `.env` không được nướng vào image Docker (`.dockerignore`); tiêm cấu hình runtime với `--env-file` hoặc `-e`.
+- Trên Windows, `APPDATA` có thể được sử dụng cho việc phân giải đường dẫn lưuữ cục bộ.
+- `INSTANCE_NAME` xuất hiện trong các tài liệu/mẫu env cũ hơn, nhưng hiện không được sử dụng trong runtime.
+
+### Tệp Runtime và Lưu trữ
+
+- Trạng thái ứng dụng chính: `${DATA_DIR}/db.json` (nhà cung cấp, combo, alias, key, cài đặt), được quản lý bởi `src/lib/localDb.js`.
+- Lịch sử sử dụng và log: `~/.9router/usage.json` và `~/.9router/log.txt`, được quản lý bởi `src/lib/usageDb.js`.
+- request/translator tùy chọn: `<repo>/logs/...` khi `ENABLE_REQUEST_LOGS=true`.
+- Lưu trữ sử dụng hiện tại tuân theo logic đường dẫn `~/.9router` và độc lập với `DATA_DIR`.
+
+</details>
+
+---
+
+## 📊 Các mô hình có sẵn
+
+<details>
+<summary><b>Xem tất cả các mô hình có sẵn</b></summary>
+
+**Claude Code (`cc/`)** - Pro/Max:
+- `cc/claude-opus-4-6`
+- `cc/claude-sonnet-4-5-2025029`
+- `cc/claude-haiku-4-5-20251001`
+
+**Codex (`cx/`)** - Plus/Pro:
+- `cx/gpt-5.2-codex`
+- `cx/gpt-5.1-codex-max`
+
+**Gemini CLI (`gc/`)** - MIỄN PHÍ:
+- `gc/gemini-3-flash-preview`
+- `gc/gemini-2.5-pro`
+
+**GitHub Copilot (`gh/`)**:
+- `gh/gpt-5`
+- `gh/claude-.5-sonnet`
+
+**GLM (`glm/`)** - $0.6/1M:
+- `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** - $0.2/1M:
+- `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** - MIỄN PHÍ:
+- `if/kimi-k2-thinking`
+- `if/qwen3-coder-plus`
+- `if/deepseek-r1`
+
+**Qwen (`qw/`)** - MIỄN PHÍ:
+- `qw/q3-coder-plus`
+- `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** - MIỄN PHÍ:
+- `kr/claude-sonnet-4.5`
+- `kr/claude-haiku-4.5`
+
+</details>
+
+---
+
+## 🐛 Khắc phục sự cố
+
+**"Language model did not provide messages"**
+- Hết hạn mức nhà cung cấp → Kiểm tra trình theo dõi hạn mức bảng điều khiển
+- Giải pháp: Sử dụng dự phòng combo hoặc chuyển sang tầng rẻ hơn
+
+**Gi hạn tốc độ (Rate limiting)**
+- Hết hạn mức gói đăng ký → Dự phòng sang GLM/MiniMax
+- Thêm combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+
+**Token OAuth hết hạn**
+- Tự động làm mới bởi 9Router
+- Nếu sự cố vẫn tiếp diễn: Bảng điều khiển → Nhà cung cấp → Kết nối lại
+
+**Chi phí cao**
+- Kiểm tra thống kê sử dụng trong Bảng điều khiển
+- Chuyển mô hình chính sang GLM/MiniMax
+- Sử dụng tầng miễn phí (Gemini CLI, iFlow) cho các tác vụ không quan trọng
+
+**Bảng điều khiển mở sai cổng**
+- Đặt `PORT=20128` và `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+
+**Lỗi đồng bộ đám mây**
+- Xác minh `BASE_URL` trỏ đến phiên bản đang chạy của bạn (ví dụ: `http://localhost:20128`)
+- Xác minh `CLOUD_URL` trỏ đến endpoint đám mây dự kiến của bạn (ví dụ: `https://9router.com`)
+- Giữ các giá trị `NEXT_PUBLIC_*` phù hợp với giá trị phía máy chủ khi có thể.
+
+**Endpoint đám mây `stream=false` trả về 500 (`Unexpected token 'd'...`)**
+- Triệu chứng thường xuất hiện trên endpoint đám mây công khai (`https://9router.com/v1`) cho các lệnh gọi không phát trực tiếp (non-streaming).
+- Nguyên nhân gốc rễ: upstream trả về payload SSE (`data: ...`) trong khi client mong đợi JSON.
+-ải pháp thay thế: sử dụng `stream=true` cho các lệnh gọi trực tiếp đến đám mây.
+- Runtime 9Router cục bộ bao gồm dự phòng SSE→JSON cho các lệnh gọi không phát trực tiếp khi upstream trả về `text/event-stream`.
+
+**Đám mây báo đã kết nối, nhưng yêu cầu vẫn thất bại với `Invalid API key`**
+- Tạo một key mới từ bảng điều khiển cục bộ (`/api/keys`) và chạy đồng bộ đám mây (`Enable Cloud` sau đó `Sync Now`).
+- Các key cũ/chưa đồng bộ vẫn có thể trả về `401` trên đám mây ngay cả khi endpoint cục bộ hoạt động.
+
+**Đăng nhập lần đầu không hoạt động**
+- Kiểm tra `INITIAL_PASSWORD` trong `.env`
+- Nếu chưa đặt, mật khẩu dự phòng là `123456`
+
+**Không có log request dưới `logs/`**
+- Đặt `ENABLE_REQUEST_LOGS=true`
+
+---
+
+## 🛠️ Tech Stack
+
+- **Runtime**: Node.js 20+
+- **Framework**: Next.js 16
+- **UI**: React 19 + Tailwind 4
+- **Database**: LowDB (dựa trên tệp JSON)
+- **Streaming**: Server-Sent Events (SSE)
+- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
+
+---
+
+## 📝 Tài liệu tham khảo API
+
+### Chat Completions
+
+```bash
+POST http://localhost:20128/v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role":user", "content": "Viết một hàm để..."}
+  ],
+  "stream": true
+}
+```
+
+### Liệt kê Mô hình
+
+```bash
+GET http://localhost:20128/v1/models
+Authorization: Bearer your-api-key
+
+→ Trả về tất cả các mô hình + combo ở định dạng OpenAI
+```
+
+### Các Endpoint Tương thích
+
+- `POST /v1/chat/completions`
+- `POST /v1/messages`
+- `POST /v1/responses`
+- `GET /v1/models`
+- `POST /v1/messages/count_tokens`
+- `GET /v1beta/models`
+- `POST /v1beta/models/{...path}` (Gemini-style `generateContent`)
+- `POST /v1/api/chat` (đường dẫn chuyển đổi kiểu Ollama)
+
+### Kịch bản Xác thực Đám mây
+
+Đã thêm các kịch bản kiểm tra dưới `tester/security/`:
+
+- `tester/security/test-docker-hardening.sh`
+  - Build image Docker và xác thực các kiểm tra hardening (`/api/cloud/auth` auth guard, `REQUIRE_API_KEY`, hành vi cookie xác thực bảo).
+- `tester/security/test-cloud-openai-compatible.sh`
+  - Gửi một yêu cầu tương thích OpenAI trực tiếp đến endpoint đám mây (`https://9router.com/v1/chat/completions`) với mô hình/key được cung cấp.
+- `tester/security/test-cloud-sync-and-call.sh`
+  - Quy trình end-to-end: tạo key cục bộ -> bật/đồng bộ đám mây -> gọi endpoint đám mây với thử lại.
+  - Bao gồm kiểm tra dự phòng với `stream=true` để phân biệt lỗi xác thực với các vấn đề phân tích phát trực tiếp.
+
+Ghi chú bảo mật cho các kịch bản kiểm tra đám mây:
+
+- Không bao giờ hardcode các API key thực trong kịch bản/commit.
+- Chỉ cung cấp key qua các biến môi trường:
+  - `API_KEY`, `CLOUD_API_KEY`, hoặc `OPENAI_API_KEY` (được hỗ trợ bởi `test-cloud-openai-compatible.sh`)
+- Ví dụ:
+
+```bash
+OPENAI_API_KEY="your-cloud-key" bash tester/security/test-cloud-openai-compatible.sh
+```
+
+Hành vi dự kiến từ việc xác thực gần đây:
+
+- cục bộ (`http://127.0.0.1:20128/v1/chat/completions`): hoạt động với `stream=false` và `stream=true`.
+- Runtime Docker (cùng đường dẫn API được expose bởi container): các kiểm tra hardening đạt, cloud auth guard hoạt động, chế độ API key nghiêm ngặt hoạt động khi được bật.
+- Endpoint đám mây công khai (`https://9router.com/v1/chat/completions`):
+  - `stream=true`: dự kiến thành công (trả về các khối SSE).
+  - `stream=false`: có thể thất bại với `500` + lỗi phân tích (`Unexpected token 'd'`) khi upstream trả về nội dung SSE cho đường dẫn client không phát trực tiếp.
+
+### API Quản lý và Bảng điều khiển
+
+- Xác thực/cài đặt: `/api/auth/login`, `/api/auth/logout`, `/api/settings`, `/api/settings/require-login`
+- Quản lý nhà cung cấp: `/api/providers`, `/api/providers/[id]`, `/api/providers/[id]/test`, `/api/providers/[id]/models`, `/api/providers/validate`, `/api/provider-n*`
+- Luồng OAuth: `/api/oauth/[provider]/[action]` (+ các import cụ thể theo nhà cung cấp như Cursor/Kiro)
+- Cấu hình định tuyến: `/api/models/alias`, `/api/combos*`, `/api/keys*`, `/api/pricing`
+- Sử dụng/log: `/api/usage/history`, `/api/usage/logs`, `/api/usage/request-logs`, `/api/usage/[connectionId]`
+- Đồng bộ đám mây: `/api/sync/cloud`, `/api/sync/initialize`, `/api/cloud/*`
+-ợ giúp CLI: `/api/cli-tools/claude-settings`, `/api/cli-tools/codex-settings`, `/api/cli-tools/droid-settings`, `/api/cli-tools/openclaw-settings`
+
+### Hành vi Xác thực
+
+- Các route Bảng điều khiển (`/dashboard/*`) sử dụng bảo vệ cookie `auth_token`.
+- Đăng nhập sử dụng hash mật khẩu đã lưu khi có mặt; nếu không, nó dự phòng vào `INITIAL_PASSWORD`.
+- `requireLogin` có thể được chuyển đổi qua `/api/settings/require-login`.
+
+### Xử lý Yêu cầu (C cao)
+
+1. Client gửi yêu cầu đến `/v1/*`.
+2. Trình xử lý route gọi `handleChat` (`src/sse/handlers/chat.js`).
+3. Mô hình được giải quyết (nhà cung cấp/mô hình trực tiếp hoặc giải quyết alias/combo).
+4. Thông tin xác thực được chọn từ DB cục bộ với bộ lọc khả dụng tài khoản.
+5. `handleChatCore` (`open-sse/handlers/chatCore.js`) phát hiện định dạng và dịch chuyển yêu cầu.
+6. Trình thực thi nhà cung cấp gửi cầu upstream.
+7. Luồng được dịch chuyển lại thành định dạng client khi cần.
+8. Sử dụng/log được ghi lại (`src/lib/usageDb.js`).
+9. Dự phòng áp dụng trên lỗi nhà cung cấp/tài khoản/mô hình theo quy tắc combo.
+
+Tài liệu tham khảo kiến trúc đầy đủ: [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md)
+
+---
+
+## 📧 Hỗ trợ
+
+- **Website**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+
+---
+
+## 👥 Người đóng góp
+
+Cảm ơn tất cả những người đã đóng góp giúp 9Router tốt hơn!
+
+[![Contributors](https://contrib.rocks/image?repo=decolua/9router&max=100&columns=20&anon=1)](https://github.com/decolua/9router/graphs/contributors)
+
+---
+
+## 📊 Star Chart
+
+[![ Chart](https://starchart.cc/decolua/9router.svg?variant=adaptive)](https://starchart.cc/decolua/9router)
+
+### Cách Đóng góp
+
+1. Fork kho lưu trữ
+2. Tạo nhánh tính năng của bạn (`git checkout -b feature/amazing-feature`)
+3. Commit các thay đổi của bạn (`git commit -m 'Add amazing feature'`)
+4. Push lên nhánh (`git push origin feature/amazing-feature`)
+5. Mở một Pull Request
+
+Xem [Pull Requests](https://github.com/decolua/9router/pulls) để biết hướng dẫn chi tiết.
+
+---
+
+## 🔀 Forks
+
+**[OmniRoute](https://github.com/diegosouzapw/OmniRoute)** — Một fork TypeScript đầy đủ tính năng của 9Router. Thêm 36+ nhà cung cấp, tự động dự phòng 4 tầng, API đa phương thức (hình ảnh, embedding, âm thanh, TTS), circuit breaker, bộ nhớ đệm ngữ nghĩa, đánh giá LLM và bảng điều khiển được tinh chỉnh. 368+ bài kiểm tra đơn vị. Có sẵn qua npm và.
+
+---
+
+## 🙏 Lời cảm ơn
+
+Cảm ơn đặc biệt đến **CLIProxyAPI** - bản triển khai Go gốc đã truyền cảm hứng cho bản chuyển đổi JavaScript này.
+
+---
+
+## 📄 Giấy phép
+
+Giấy phép MIT - xem [LICENSE](../LICENSE) để biết chi tiết.
+
+---
+
+<div align="center">
+  <sub>Được xây dựng với ❤️ cho các nhà phát triển code 24/7</sub>
+</div>
diff --git a/i18n/README.zh-CN.md b/i18n/README.zh-CN.md
new file mode 100644
index 0000000..92e0624
--- /dev/null
+++ b/i18n/README.zh-CN.md
@@ -0,0 +1,1306 @@
+<div align="center">
+  <img src="../images/9router.png?1" alt="9Router Dashboard" width="800"/>
+  
+  # 9Router - 免费 AI 路由器
+  
+  **永不停歇的编程体验。智能回退，自动路由到免费和廉价的 AI 模型。**
+  
+  **OpenClaw 的免费 AI 提供商。**
+  
+  <p align="center">
+    <img src="../public/providers/openclaw.png" alt="OpenClaw" width="80"/>
+  </p>
+  
+  [![npm](https://img.shields.io/npm/v/9router.svg)](https://www.npmjs.com/package/9router)
+  [![Downloads](https://img.shields.io/npm/dm/9router.svg)](https://www.npmjs.com/package/9router)
+  [![License](https://img.shields.io/npm/l/9router.svg)](https://github.com/decolua/9router/blob/main/LICENSE)
+  
+  [🚀 快速开始](#-quick-start) • [💡 特性](#-key-features) • [📖 设置](#-setup) • [🌐 网站](https://9router.com)
+</div>
+
+---
+
+## 🤔 为什么选择 9Router？
+
+**停止浪费金钱和触碰限制：**
+
+- ❌ 订阅配额每月未使用即过期
+- ❌ 编程中途遭遇速率限制
+- ❌ 昂贵的 API（每个提供商 $20-50/月）
+- ❌ 手动在提供商之间切换
+
+**9Router 解决方案：**
+
+- ✅ **最大化订阅价值** - 追踪配额，在重置前用尽每一分
+- ✅ **自动回退** - 订阅 廉价 → 免费，零停机时间
+- ✅ **多账户** - 每个提供商的账户间轮询
+- ✅ **通用性** - 适用于 Claude Code, Codex, Gemini CLI, Cursor, Cline, 任何 CLI 工具
+
+---
+
+## 🔄 工作原理
+
+```
+┌─────────────┐
+│  Your CLI   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│   Tool      │
+└──────┬──────┘
+       │ http://localhost:201281
+       ↓
+┌─────────────────────────────────────────┐
+│           9Router (Smart Router)        │
+│  • Format translation (OpenAI ↔ Claude) │
+│  • Quota tracking                       │
+│  • Auto token refresh                   │
+└──────┬──────────────────────────────────┘
+       │
+       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+       │   ↓ quota exhausted
+       ├─→ [Tier 2: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
+       │   ↓ budget limit
+       └─→ [Tier 3: FREE] iFlow, Qwen, Kiro (unlimited)
+
+Result: Never stop coding, minimal cost
+```
+
+---
+
+## ⚡ 快速开始
+
+**1. 全局安装：**
+
+```bash
+npm install -g 9router
+9router
+```
+
+🎉 仪表板将在 `http://localhost:20128` 打开
+
+**2. 连接免费提供商（无需注册）：**
+
+仪表板 → 提供商 → 连接 **Claude Code** 或 **Antigr** → OAuth 登录 → 完成！
+
+**3. 在您的 CLI 工具中使用：**
+
+```
+Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline 设置:
+  Endpoint: http://localhost:20128/v1
+  API Key: [从仪表板复制]
+  Model: if/kimi-k2-thinking
+```
+
+**就是这样！** 开始使用免费 AI 模型编程。
+
+**替代方案：从源码运行（此仓库）：**
+
+此仓库包是私有的（`9router-app`），因此源码/Docker 执行是预期的本地开发路径。
+
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+生产模式：
+
+```bash
+npm run build
+PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start
+```
+
+默认 URL：
+- 仪表板：`http://localhost:20128/dashboard`
+- OpenAI 兼容 API：`http://localhost:20128/v1`
+
+---
+
+## 🎥 视频教程
+
+<div align="center">
+  
+### 📺完整设置指南 - 9Router + Claude Code 免费
+  
+[![9Router + Claude Code Setup](https://img.youtube.com/vi/raEyZPg5xE0/maxresdefault.jpg)](https://www.youtube.com/watch?v=raEyZPg5xE0)
+
+**🎬 观看完整的分步教程：**
+- ✅ 9Router 安装与设置
+- ✅ 免费 Claude Sonnet 4.5 配置
+- ✅ Claude Code 集成
+- ✅ 实时编程演示
+
+**⏱️ 时长：** 20 分钟 | **👥 作者** 开发者社区
+
+[▶️ 在 YouTube 上观看](https://www.youtube.com/watch?v=o3qYCyjrFYg)
+
+</div>
+
+---
+
+## 🛠️ 支持的 CLI 工具
+
+9Router 与所有主流 AI 编程工具无缝协作：
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/openclaw.png" width="60" alt="OpenClaw"/><br/>
+        <b>OpenClaw</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/opencode.png" width="60" alt="OpenCode"/><br/>
+        <b>OpenCode</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/cline.png" width="60" alt="Cline"/><br/>
+        <b>Cline</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/continue.png" width="60" alt="Continue"/><br/>
+        <b>Continue</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/droid.png" width="60" alt="Droid"/><br/>
+        <b>Droid</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/roo.png" width="60" alt="Roo"/><br/>
+        <b>Roo</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/copilot.png" width="60" alt="Copilot"/><br/>
+        <b>Copilot</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/kilocode.png" width="60" alt="Kilo Code"/><br/>
+        <b>Kilo Code</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+---
+
+## 🌐 支持的提供商
+
+### 🔐 OAuth 提供商
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="../public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/github.png" width="60" alt="GitHub"/><br/>
+        <b>GitHub</b>
+      </td>
+      <td align="center" width="120">
+        <img src="../public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🆓 免费提供商
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="150">
+        <img src="../public/providers/iflow.png" width="70" alt="iFlow"/><br/>
+        <b>iFlow AI</b><br/>
+        <sub>8+ 模型 无限制</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/qwen.png" width="70" alt="Qwen"/><br/>
+        <b>Qwen Code</b><br/>
+        <sub>3+ 模型 • 无限制</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/gemini-cli.png" width="70" alt="Gemini CLI"/><br/>
+        <b>Gemini CLI</b><br/>
+        <sub>180K/月 免费</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="../public/providers/kiro.png" width="70" alt="Kiro"/><br/>
+        <b>Kiro AI</b><br/>
+        <sub>Claude • 无限制</sub>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🔑 API Key 提供商 (40+)
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/openrouter.png" width="50" alt="OpenRouter"/><br/>
+        <sub>OpenRouter</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/glm.png" width="50" alt="GLM"/><br/>
+        <sub>GLM</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/kimi.png" width="50" alt="Kimi"/><br/>
+        <sub>Kimi</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/minimax.png" width="50" alt="MiniMax"/><br/>
+        <sub>MiniMax</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/openai.png" width="50" alt="OpenAI"/><br/>
+        <sub>OpenAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/anthropic.png" width="50" alt="Anthropic"/><br/>
+        <sub>Anthropic</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/gemini.png" width="50" alt="Gemini"/><br/>
+        <sub>Gemini</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/deepseek.png" width="50" alt="DeepSeek"/><br/>
+        <sub>DeepSeek</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/groq.png" width="50" alt="Groq"/><br/>
+        <sub>Groq</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/xai.png" width="50" alt="xAI"/><br/>
+        <sub>xAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/mistral.png" width="50" alt="Mistral"/><br/>
+        <sub>Mistral</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/perplexity.png" width="50" alt="Perplexity"/><br/>
+        <sub>Perplexity</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="../public/providers/together.png" width="50" alt="Together"/><br/>
+        <sub>Together AI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/fireworks.png" width="50" alt="Fireworks"/><br/>
+        <sub>Fireworks</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/cerebras.png" width="50" alt="Cerebras"/><br/>
+        <sub>Cerebras</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/cohere.png" width="50" alt="Cohere"/><br/>
+        <sub>Cohere</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/nvidia.png" width="50" alt="NVIDIA"/><br/>
+        <sub>NVIDIA</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="../public/providers/siliconflow.png" width="50" alt="SiliconFlow"/><br/>
+        <sub>SiliconFlow</sub>
+      </td>
+    </tr>
+  </table>
+  <p><i>...以及 20+ 更多提供商，包括 Nebius, Chutes, Hyperbolic 和自定义 OpenAI/Anthropic 兼容端点</i></p>
+</div>
+
+---
+
+## 💡 核心特性
+
+| 特性 | 功能 | 重要性 |
+|---------|--------------|----------------|
+|  **智能 3 层回退** | 自动路由：订阅 → 廉价 → 免费 | 永不停止编程，零停机时间 |
+| 📊 **实时配额追踪** | 实时 Token 计数 + 重置倒计时 | 最大化订阅价值 |
+| 🔄 **格式转换** | OpenAI ↔ Claude ↔ Gemini 无缝转换 | 适用于任何 CLI 工具 |
+| 👥 **多账户支持** | 每个提供商多个账户 | 负载均衡 + 冗余 |
+| 🔄 **自动 Token 刷新** | OAuth token 自动刷新 |需手动重新登录 |
+| 🎨 **自定义组合** | 创建无限模型组合 | 根据需求定制回退策略 |
+| 📝 **请求日志** | 调试模式包含完整请求/响应日志 | 轻松排查问题 |
+| 💾 **云端同步** | 跨设备同步配置 | 到处都是相同的设置 |
+| 📊 **使用分析** | 追踪 Token、成本、趋势 | 优化支出 |
+| 🌐 **随处部署** | 本地主机、VPS、Docker、Cloudflare Workers | 灵活的部署选项 |
+
+<details>
+<summary><b>📖 特性详情</b></summary>
+
+### 🎯 智能 3 层回退
+
+创建具有自动回退功能的组合：
+
+```
+Combo: "my-coding-stack"
+  1. cc/claude-opus-4-6        (your subscription)
+  2. glm/glm-4.7               (cheap backup, $0.6/1M)
+  3. if/kimi-k2-thinking       (free fallback)
+
+→ Auto switches when quota runs out or errors occur
+```
+
+### 📊 实时配额追踪
+
+- 每个提供商的 Token 消
+- 重置倒计时（5 小时、每日、每周）
+- 付费层的成本估算
+- 月度支出报告
+
+### 🔄 格式转换
+
+格式间无缝转换：
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
+- 您的 CLI 工具发送 OpenAI 格式 → 9Router 转换 → 提供商接收原生格式
+- 适用于任何支持自定义 OpenAI 端点的工具
+
+### 👥 多账户支持
+
+- 每个提供商添加多个账户
+- 自动轮询或基于优先级的
+- 当一个账户达到配额时回退到下一个
+
+### 🔄 自动 Token 刷新
+
+- OAuth token 在过期前自动刷新
+- 无需手动重新认证
+- 所有提供商的无缝体验
+
+### 🎨 自定义组合
+
+- 创建无限模型组合
+- 混合订阅、廉价和免费层
+- 为您的组合命名以便访问
+- 通过云端同步跨设备共享组合
+
+### 📝 请求日志
+
+- 启用调试模式以获取完整请求/响应日志
+- 追踪 API 调用、标头和负载
+- 排查集成
+- 导出日志进行分析
+
+### 💾 云端同步
+
+- 跨设备同步提供商、组合和设置
+- 自动后台同步
+- 安全加密存储
+- 从任何地方访问您的设置
+
+#### 云端运行说明
+
+- 在生产环境中优先使用服务器端云变量：
+  - `BASE_URL`（同步调度器使用的内部回调 URL）
+  - `CLOUD_URL`（云端同步端点基础 URL）
+- `NEXT_PUBLIC_BASE_URL` 和 `NEXT_PUBLIC_CLOUD_URL` 仍支持兼容性/UI，但服务器运行时现在优先使用 `BASE_URL`/`C_URL`。
+- 云端同步请求现在使用超时 + 快速失败行为，以避免在云端 DNS/网络不可用时 UI 挂起。
+
+### 📊 使用分析
+
+- 追踪每个提供商和模型的 Token 使用情况
+- 成本估算和支出趋势
+- 月度报告和洞察
+- 优化您的 AI 支出
+
+> **💡 重要 - 理解仪表板成本：**
+> 
+> 使用分析中显示的“成本”**仅用于追踪和比较目的**。
+> 9Router 本身**从不向您收费**。您只需直接向提供商付款（如果使用付费服务）。
+> 
+> **示例：** 如果您的仪表板在使用 iFlow 模型时显示“$290 总成本”，这代表
+> 您直接使用付费 API 时需要支付的金额。您的实际成本 = **$0**（iFlow 是免费无限制的）。
+> 
+> 将其视为“节省追踪器”，显示您通过使用免费模型或
+> 通过 9Router 路由节省了多少！
+
+### 🌐 随处部署
+
+- 💻 **本地主机** - 默认，离线工作
+- ☁️ **VPS/云** 跨设备共享
+- 🐳 **Docker** - 一键部署
+- 🚀 **Cloudflare Workers** - 全球边缘网络
+
+</details>
+
+---
+
+## 💰 定价一览
+
+| 层级 | 提供商 | 成本 | 配额重置 | 最适合 |
+|------|----------|------|-------------|----------|
+| **💳 订阅** | Claude Code (Pro) | $20/月 | 5h + 每周 | 已订阅用户 |
+| | Codex (Plus/Pro) | $20-200/月 | 5h + 每周 OpenAI 用户 |
+| | Gemini CLI | **免费** | 180K/月 + 1K/天 | 所有人！ |
+| | GitHub Copilot | $10-19/月 | 每月 | GitHub 用户 |
+| **💰 廉价** | GLM-4.7 | $0.6/1M | 每日 10AM | 预算备份 |
+| | MiniMax M2.1 | $0.2/1M | 5 小时滚动 | 最便宜选项 |
+| | Kimi K2 | $9/月固定 | 10M tokens/月 | 可预测成本 |
+| **🆓 免费** | iFlow | $0 | 无限制 | 8 个模型免费 |
+| | Qwen | $0 | 无限制 | 3 个模型免费 |
+| | Kiro | $0 | 无限制 | Claude 免费 |
+
+**💡 专业提示：** 从 Gemini CLI（180K 免费/月）+ iFlow（无限制免费）组合开始 = $0 成本！
+
+---
+
+### 📊 理解 9Router 成本和计费
+
+**9Router 计费现实：**
+
+✅ **9Router 软件 = 永远免费**开源，从不收费）  
+✅ **仪表板“成本” = 仅显示/追踪**（非实际账单）  
+✅ **您直接向提供商付款**（订阅或 API 费用）  
+✅ **免费提供商保持免费**（iFlow, Kiro, Qwen = $0 无限制）  
+❌ **9Router 从不发送发票**或向您的卡收费
+
+**成本显示如何工作：**
+
+仪表板显示**估算成本**，就像您直接使用付费 API 一样。这**不是计费** - 它是一个比较工具，用于显示您的节省。
+
+**示例场景：```
+仪表板显示：
+• 总请求数：1,662
+• 总 Token 数：47M
+• 显示成本：$290
+
+现实检查：
+• 提供商：iFlow（免费无限制）
+• 实际付款：$0.00
+• $290 的含义：您通过使用免费模型节省的金额！
+```
+
+**付款规则：**
+- **订阅提供商**（Claude Code, Codex）：通过他们的网站直接向他们付款
+- **廉价提供商**（GLM, MiniMax）：直接向他们付款，9Router 只是路由
+- **免费**（iFlow, Kiro, Qwen）：真正永远免费，没有隐藏费用
+- **9Router**：从不收取任何费用，永远
+
+---
+
+## 🎯 使用案例
+
+### 案例 1：“我有 Claude Pro 订阅”
+
+**问题：** 配额未使用即过期，重度编程时遇到速率限制
+
+**解决方案：**
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (use subscription fully)
+  2. glm/glm-4.7               (cheap backup when quota out)
+  3 if/kimi-k2-thinking       (free emergency fallback)
+
+Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
+vs. $20 + hitting limits = frustration
+```
+
+### 案例 2：“我想要零成本”
+
+**问题：** 负担不起订阅，需要可靠的 AI 编程
+
+**解决方案：**
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K free/month)
+  2. if/kimi-k2-thinking       (unlimited free)
+  3. qw/qwen3-c-plus       (unlimited free)
+
+Monthly cost: $0
+Quality: Production-ready models
+```
+
+### 案例 3：“我需要 24/7 编程，无中断”
+
+**问题：** 截止日期，不能承受停机
+
+**解决方案：**
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (best quality)
+  2. cx/gpt-5.2-codex          (second subscription)
+  3. glm/glm-4.7               (cheap, resets daily)
+  4. minimaxMiniMax-M2.1      (cheapest, 5h reset)
+  5. if/kimi-k2-thinking       (free unlimited)
+
+Result: 5 layers of fallback = zero downtime
+Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
+```
+
+### 案例 4：“我想在 OpenClaw 中使用免费 AI”
+
+**问题：** 需要在消息应用（WhatsApp, Telegram, Slack...）中使用 AI 助手，完全免费
+
+**解决方案：**
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (unlimited free)
+  2. if/minimax-m2.1           (unlimited free)
+  3. if/kimi-k2-thinking       (unlimited free)
+
+Monthly cost: $0
+Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## ❓ 常见问题
+
+<details>
+<summary><b>📊 为什么我的仪表板显示高成本？</b></summary>
+
+仪表板追踪您的 Token 使用情况，并显示**估算成本**，就像您直接使用付费 API 一样。这**不是实际计费** - 它是一个参考，显示您通过 9Router 使用免费模型或现有订阅节省了多少。
+
+**示例：**
+- **仪表板显示：**“$290 总成本”
+- **现实：** 您正在使用 iFlow（免费无限制）
+- **您的实际成本：** **$0.00**
+- **$290 的含义：** 您通过使用免费模型而不是付费 API **节省**的金额！
+
+成本显示是一个“节省追踪器”，帮助您了解使用模式和优化机会。
+
+</details>
+
+<details>
+<summary><b>💳 9Router 会向我收费吗？</b></summary>
+
+**不会。** 9 是免费的开源软件，在您自己的计算机上运行。它从不向您收费。
+
+**您只需支付：**
+- ✅ **订阅提供商**（Claude Code $20/月, Codex $20-200/月）→ 在他们的网站上直接向他们付款
+- ✅ **廉价提供商**（GLM, MiniMax）→ 直接向他们付款，9Router 只是路由您的请求
+- ❌ **9Router 本身** → **从不收取任何费用，永远**
+
+9Router 是本地代理/路由器。它没有您的信用卡，不能发送发票，也没有计费系统。完全免费的软件。
+
+</details>
+
+<details>
+<summary><b>🆓 免费提供商真的无限制吗？</b></summary>
+
+**是的！** 标记为免费（iFlow, Kiro, Qwen）的提供商是真正无限制的，**没有隐藏费用**。
+
+这些是各自公司提供的免费服务：
+- **iFlow**：通过 OAuth 免费无限制访问 8+ 模型
+- **Kiro**：通过 AWS Builder ID 免费无限制 Claude 模型
+- **Qwen**：通过设备认证免费无限制访问 Qwen 模型
+
+Router 只是将您的请求路由到它们 - 没有“陷阱”或未来计费。它们是真正的免费服务，9Router 使它们易于使用并支持回退。
+
+**注意：** 一些订阅提供商（Antigravity, GitHub Copilot）可能有免费预览期，后来可能变成付费，但这会由这些提供商明确宣布，而不是 9Router。
+
+</details>
+
+<details>
+<summary><b>💰 如何最小化我的实际 AI 成本？</b></summary>
+
+**免费优先策略：**
+
+1. **从 100% 免费组合开始：**
+   ```
+   1. gc/gini-3-flash (180K/month free from Google)
+   2. if/kimi-k2-thinking (unlimited free from iFlow)
+   3. qw/qwen3-coder-plus (unlimited free from Qwen)
+   ```
+   **成本：$0/月**
+
+2. **仅在需要时添加廉价备份：**
+   ```
+   4. glm/glm-4.7 ($0.6/1M tokens)
+   ```
+   **额外成本：仅为您实际使用的付费**
+
+3. **最后使用订阅提供商：**
+   - 仅当您已经拥有它们时
+   - 9Router 通过配额追踪帮助最大化其价值
+
+**结果：** 大多数用户可以仅使用免费层以 $0/月运行！
+
+</details>
+
+<details>
+<summary><b>📈 如果我的使用量突然激增怎么办？</b></summary>
+
+9Router 的智能回退可防止意外费用：
+
+**场景：** 您正在进行编程冲刺并耗尽了配额
+
+**没有 9Router：**
+- ❌ 遇到速率限制 → 工作停止 → 沮丧
+- ❌ 或：意外累积巨额 API 账单
+
+**有 9Router：**
+- ✅订阅达到限制 → 自动回退到廉价层
+- ✅ 廉价层变得昂贵 → 自动回退到免费层
+- ✅ 永不停止编程 → 可预测的成本
+
+**您在控制中：** 在仪表板中设置每个提供商的支出限制，9Router 会遵守它们。
+
+</details>
+
+---
+
+## 📖 设置指南
+
+<details>
+<summary><b>🔐 订阅提供商（最大化价值）</b></summary>
+
+### Claude Code (Pro/Max)
+
+```bash
+Dashboard → Providers → Connect Claude Code
+→ OAuth login → Auto token refresh
+→ 5-hour + weekly quota tracking
+
+Models:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**专业提示：** 使用 Opus 处理复杂任务，Sonnet 追求速度。9Router 追踪每个模型的配额！
+
+### OpenAI Codex (Plus/Pro)
+
+```bash
+Dashboard → Providers → Connect Codex
+→ OAuth login (port 1455)
+→ 5-hour + weekly reset
+
+Models:
+ /gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+### Gemini CLI（免费 180K/月！）
+
+```bash
+Dashboard → Providers → Connect Gemini CLI
+→ Google OAuth
+→ 180K completions/month + 1K/day
+
+Models:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**最佳价值：** 巨大的免费层！在付费层之前使用这个。
+
+### GitHub Copilot
+
+```bash
+Dashboard → Providers → Connect GitHub
+→ OAuth via
+→ Monthly reset (1st of month)
+
+Models:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+</details>
+
+<details>
+<summary><b>💰 廉价提供商（备份）</b></summary>
+
+### GLM-4.7（每日重置，$0.6/1M）
+
+1. 注册：[Zhipu AI](https://open.bigmodel.cn/)
+2. 从 Coding Plan 获取 API key
+3. 仪表板 → 添加 API Key：
+   - Provider: `glm`
+   - API Key: `your-key`
+
+**使用：** `glm/glm-4.7`
+
+**专业提示：** Coding Plan 以 1/7 的成本提供 3× 配额！每日 10:00 AM 重置。
+
+### MiniMax M2.1（5h 重置，$0.20/1M）
+
+1. 注册：[MiniMax](https://www.minimax.io/)
+2. 获取 API key
+3. 仪表板 → 添加 API Key
+
+**使用：** `minimax/MiniMax-M2.1`
+
+**专业提示：** 长上下文（1M tokens）的最便宜选项！
+
+### Kimi K2（$9/月固定）
+
+1. 订阅：[Moonshot AI](https://platform.moonshot.ai/)
+2. 获取 API key
+3. 仪表板 → 添加 API Key
+
+**使用：** `kimi/kimi-latest`
+
+**专业提示：** 固定 $9/月可获得 10M tokens = $0.90/1M 实际成本！
+
+</details>
+
+<details>
+<summary><b>🆓 免费提供商（紧急备份）</b></summary>
+
+### i（8 个免费模型）
+
+```bash
+Dashboard → Connect iFlow
+→ iFlow OAuth login
+→ Unlimited usage
+
+Models:
+  if/kimi-k2-thinking
+  if/qwen3-coder-plus
+  if/glm-4.7
+  if/minimax-m2
+  if/deepseek-r1
+```
+
+### Qwen（3 个免费模型）
+
+```bash
+Dashboard → Connect Qwen
+→ Device code authorization
+→ Unlimited usage
+
+Models:
+  qw/qwen3-coder-plus
+  qw/qwen3-coder-flash
+```
+
+### Kiro（Claude 免费```bash
+Dashboard → Connect Kiro
+→ AWS Builder ID or Google/GitHub
+→ Unlimited usage
+
+Models:
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+```
+
+</details>
+
+<details>
+<summary><b>🎨 创建组合</b></summary>
+
+### 示例 1：最大化订阅 → 廉价备份
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-6 (Subscription primary)
+  2. glm/glm4.7 (Cheap backup, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
+
+Use in CLI: premium-coding
+
+Monthly cost example (100M tokens):
+  80M via Claude (subscription): $0 extra
+  15M via GLM: $9
+  5M via MiniMax: $1
+  Total: $10 + your subscription
+```
+
+### 示例 2：仅免费（零成本）
+
+```
+Name: free-combo
+Models:
+  1. gc/gemini-3-flash-preview (180K free/month)
+  2. if/kimi-k2-thinking (unlimited)
+  3. qw/qwen3-coder-plus (unlimited)
+
+Cost: $0 forever!
+```
+
+</details>
+
+<details>
+<summary><b>🔧 CLI 集成</b></summary>
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: cc/claude-opus-4-6
+```
+
+使用组合：`premium-coding`
+
+### Claude Code
+
+编辑 `~/.claude/config.json`：
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+### OpenClaw
+
+**选项 1 — 仪表板（推荐）：**
+
+```
+Dashboard → CLI Tools →Claw → Select Model → Apply
+```
+
+**选项 2 — 手动：** 编辑 `~/.openclaw/openclaw.json`：
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "9router/if/glm-4.7"
+      }
+    }
+  },
+  "models": {
+    "providers": {
+      "9router": {
+        "baseUrl": "http://127.0.0.1:20128/v1",
+        "apiKey": "sk_9router",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "if/glm-4.7",
+            "name": "glm-4.7"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+> **注意：** OpenClaw 仅适用于本地 9Router。使用 `127.0.0.1` 而不是 `localhost` 以避免 IPv6 解析问题。
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claudeus-4-6
+```
+
+</details>
+
+<details>
+<summary><b>🚀 部署</b></summary>
+
+### VPS 部署
+
+```bash
+# Clone and install
+git clone https://github.com/decolua/9router.git
+cd 9router
+npm install
+npm run build
+
+# Configure
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/9router"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URLhttp://localhost:20128"
+export NEXT_PUBLIC_CLOUD_URL="https://9router.com"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+export MACHINE_ID_SALT="endpoint-proxy-salt"
+
+# Start
+npm run start
+
+# Or use PM2
+npm install -g pm2
+pm2 start npm --name 9router -- start
+pm2 save
+pm2 startup
+```
+
+### Docker
+
+```bash
+# Build image (from repository root)
+docker build -t 9router .
+
+# Run container (command used in current setup)
+docker run -d \
+  --name 9router  -p 20128:20128 \
+  --env-file /root/dev/9router/.env \
+  -v 9router-data:/app/data \
+  -v 9router-usage:/root/.9router \
+  9router
+```
+
+便携式命令（如果您已在仓库根目录）：
+
+```bash
+docker run -d \
+  --name 9router \
+  -p 20128:20128 \
+  --env-file ./.env \
+  -v 9router-data:/app/data \
+  -v 9router-usage:/root/.9router \
+  9
+```
+
+容器默认值：
+- `PORT=20128`
+- `HOSTNAME=0.0.0.0`
+
+有用命令：
+
+```bash
+docker logs -f 9router
+docker restart 9router
+docker stop 9router && docker rm 9router
+```
+
+### 环境变量
+
+| 变量 | 默认值 | 描述 |
+|----------|---------|-------------|
+| `JWT_SECRET` | 自动生成（`~/.9router/jwt-secret`） | 仪表板认证 cookie 的 JWT 签名密钥（设置可在多实例间共享） |
+| `INITIAL_PASSWORD | `123456` | 当没有保存的哈希时的首次登录密码 |
+| `DATA_DIR` | `~/.9router` | 主应用数据库位置（`db.json`） |
+| `PORT` | 框架默认值 | 服务端口（示例中为 `20128`） |
+| `HOSTNAME` | 框架默认值 | 绑定主机（Docker 默认为 `0.0.0.0`） |
+| `NODE_ENV` | 运行时默认值 | 部署时设置 `production` |
+| `BASE_URL` |http://localhost:20128` | 云同步作业使用的服务器端内部基础 URL |
+| `CLOUD_URL` | `https://9router.com` | 服务器端云同步端点基础 URL |
+| `NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | 向后兼容/公共基础 URL（服务器运行时优先使用 `BASE_URL`） |
+| `NEXT_PUBLIC_CLOUD_URL` | `https://9router.com` | 向后兼容/公共云 URL（服务器运行时优先使用 `CLOUD_URL`） |
+| `API_KEY_SECRET` | `endpoint-proxy-api-secret` | 生成的 API Key 的 HMAC 密钥 |
+| `MACHINE_ID_SALT` | `endpoint-proxy-salt` | 稳定机器 ID 哈希的盐值 |
+| `ENABLE_REQUEST_LOGS` | `false` | 在 `logs/` 下启用请求/响应日志 |
+| `AUTH_COOKIE_SECURE` | `false` | 强制 `Secure` 认证 cookie（在 HTTPS 反向代理后设置 `true`） |
+| `REQUIRE_API_KEY` | `false` | 在 `/v1/*` 路由上强制执行 Bearer API key推荐用于暴露在互联网的部署） |
+| `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` | 空 | 上游提供商调用的可选出站代理 |
+
+注意：
+- 也支持小写代理变量：`http_proxy`, `https_proxy`, `all_proxy`, `no_proxy`。
+- `.env` 不会烘焙到 Docker 镜像中（`.dockerignore`）；使用 `--env-file` 或 `-e` 注入运行时配置。
+- 在 Windows 上，`APPDATA` 可用于本地存储路径解析。
+- `INSTANCE_NAME` 出现在旧/环境模板中，但目前运行时未使用。
+
+### 运行时文件和存储
+
+- 主应用状态：`${DATA_DIR}/db.json`（提供商、组合、别名、密钥、设置），由 `src/lib/localDb.js` 管理。
+- 使用历史和日志：`~/.9router/usage.json` 和 `~/.9router/log.txt`，由 `src/lib/usageDb.js` 管理。
+- 可选请求/转换器日志：当 `ENABLE_REQUEST_LOGS=true` 时为 `<repo>/logs/...`。
+- 使用存储当前遵循 `~/.9` 路径逻辑，独立于 `DATA_DIR`。
+
+</details>
+
+---
+
+## 📊 可用模型
+
+<details>
+<summary><b>查看所有可用模型</b></summary>
+
+**Claude Code (`cc/`)** - Pro/Max:
+- `cc/claude-opus-4-6`
+- `cc/claude-sonnet-4-5-20250929`
+- `cc/claude-haiku-4-5-20251001`
+
+**Codex (`cx/`)** - Plus/Pro:
+- `cx/gpt-5.2-codex- `cx/gpt-5.1-codex-max`
+
+**Gemini CLI (`gc/`)** - 免费:
+- `gc/gemini-3-flash-preview`
+- `gc/gemini-2.5-pro`
+
+**GitHub Copilot (`gh/`)**:
+- `gh/gpt-5`
+- `gh/claude-4.5-sonnet`
+
+**GLM (`glm/`)** - $0.6/1M:
+- `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** - $0.2/1M:
+- `imax/MiniMax-M2.1`
+
+**iFlow (`if/`)** - 免费:
+- `if/kimi-k2-thinking`
+- `if/qwen3-coder-plus`
+- `if/deepseek-r1`
+
+**Qwen (`qw/`)** - 免费:
+- `qw/qwen3-coder-plus`
+- `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** - 免费:
+- `kr/claude-sonnet-4.5`
+- `kr/claude-haiku-4.5`
+
+</details>
+
+---
+
+## 🐛 故障排除
+
+“Language model did not provide messages”**
+- 提供商配额耗尽 → 检查仪表板配额追踪器
+- 解决方案：使用组合回退或切换到更便宜的层
+
+**速率限制**
+- 订阅配额用完 → 回退到 GLM/MiniMax
+- 添加组合：`cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+
+**OAuth token 过期**
+- 由 9Router 自动刷新
+- 如果问题持续：仪表板 → 提供商 → 重新
+
+**高成本**
+- 在仪表板中检查使用统计
+- 将主要模型切换为 GLM/MiniMax
+- 对非关键任务使用免费层（Gemini CLI, iFlow）
+
+**仪表板在错误的端口打开**
+- 设置 `PORT=20128` 和 `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+
+**云端同步错误**
+- 验证 `BASE_URL` 指向您正在运行的实例（例如：`http://localhost:20128`）
+- 验证 `CLOUD_URL` 指向您预期的云端端点（例如：`https://9router.com`）
+- 尽可能保持 `NEXT_PUBLIC_*` 值与服务器端值一致。
+
+**云端端点 `stream=false` 返回 500（`Unexpected token 'd'...`）**
+- 症状通常出现在公共云端端点（`https://9router.com/v1`）的非流式调用上。
+- 根本原因：上游返回 SSE 负载（`data: ...`）而客户端期望 JSON。
+- 变通方法：对云端直接调用使用 `stream=true`。
+- 当上游返回 `text/event-stream` 时，本地 9Router 运行时包含 SSE→JSON 回退用于非流式调用。
+
+**云端显示已连接，但请求仍然失败并显示 `Invalid API key`**
+- 从本地仪表板（`/api/keys`）创建新密钥并运行云端同步（`Enable Cloud` 然后 `Sync Now`）。
+- 旧/未同步的密钥即使在本地端点工作的情况下，仍可能在云端返回 `401`。
+
+**首次登录不工作**
+- 检查 `.env` 中的 `INITIAL_PASSWORD`
+- 如果未设置，回退密码是 `123456`
+
+**`logs/` 下没有请求日志**
+- 设置 `ENABLE_REQUEST_LOGS=true`
+
+---
+
+## 🛠️ 技术栈
+
+- **运行时**：Node.js 20+
+- **框架**：Next.js 16
+- **UI**：React 19 + Tailwind CSS 4
+- **数据库**：LowDB（基于 JSON 文件）
+- **流式传输**：Server-Sent Events (SSE)
+- **认证**：OAuth 2.0 (PKCE) + JWT + API Keys
+
+---
+
+## 📝 API 参考
+
+### Chat Completions
+
+```bash
+POST httplocalhost:20128/v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
+```
+
+### 列出模型
+
+```bash
+GET http://localhost:20128/v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all models + combos in OpenAI format
+```
+
+### 兼容性端点
+
+- ` /v1/chat/completions`
+- `POST /v1/messages`
+- `POST /v1/responses`
+- `GET /v1/models`
+- `POST /v1/messages/count_tokens`
+- `GET /v1beta/models`
+- `POST /v1beta/models/{...path}`（Gemini 风格 `generateContent`）
+- `POST /v1/api/chat`（Ollama 风格转换路径）
+
+### 云端验证脚本
+
+在 `tester/security/` 下添加了测试脚本：
+
+- `tester/security/test-docker-hardening.sh`
+  - 构建 Docker 镜像并验证加固检查（`/api/cloud/auth` 认证保护、`REQUIRE_API_KEY`、安全认证 cookie 行为）。
+- `tester/security/test-cloud-openai-compatible.sh`
+  - 使用提供的模型/密钥向云端端点（`https://9router.com/v1/chat/completions`）发送直接的 OpenAI 兼容请求。
+- `tester/security/test-cloud-sync-and-call.sh`
+  - 端到端流程：创建本地密钥 -> 启用/同步云端 -> 带重试调用云端端点。
+  - 包含使用 `stream` 的回退检查，以区分认证错误和非流式解析问题。
+
+云端测试脚本的安全说明：
+
+- 永远不要在脚本/提交中硬编码真实的 API 密钥。
+- 仅通过环境变量提供密钥：
+  - `API_KEY`, `CLOUD_API_KEY`, 或 `OPENAI_API_KEY`（由 `test-cloud-openai-compatible.sh` 支持）
+- 示例：
+
+```bash
+OPENAI_API_KEY="your-cloud-key" bash tester/security/test-cloud-openai-compatible.sh
+```
+
+最近验证的预期行为：
+
+- 本地运行时（`http://127.0.0.1:20128/v1/chat/completions`）：使用 `stream=false` 和 `stream=true` 都可以工作。
+- Docker 运行时（容器暴露的相同 API 路径）：加固检查通过，云端认证保护工作，启用时严格 API 密钥模式工作。
+- 公共云端端点（`https://9router.com/v1/chat/completions`）：
+  - `stream=true`：预期成功（返回 SSE 块）。
+  - `stream=false`：当上游向非流式客户端路径返回 SSE 内容时，可能失败并显示 `500` + 解析错误（`Unexpected token 'd'`）。
+
+### 仪表板和管理 API
+
+- 认证/设置：`/api/auth/login`, `/api/auth/logout`, `/api/settings`, `/api/settings/require-login`
+- 提供商管理：`/api/providers`, `/api/providers/[id]`, `/api/providers/[id]/test`, `/api/providers/[id]/models`, `/api/providers/validate`, `/api/provider-nodes*`
+- OAuth 流程：`/api/oauth/[provider]/[action]`（+ 特定提供商导入如 Cursor/Kiro）
+ 路由配置：`/api/models/alias`, `/api/combos*`, `/api/keys*`, `/api/pricing`
+- 使用/日志：`/api/usage/history`, `/api/usage/logs`, `/api/usage/request-logs`, `/api/usage/[connectionId]`
+- 云端同步：`/api/sync/cloud`, `/api/sync/initialize`, `/api/cloud/*`
+- CLI 助手：`/api/cli-tools/claude-settings`, `/api/cli-tools/codex-settings`, `/api/cli-tools/droid-settings`, `/api/cli-tools/openaw-settings`
+
+### 认证行为
+
+- 仪表板路由（`/dashboard/*`）使用 `auth_token` cookie 保护。
+- 登录时如果存在保存的密码哈希则使用；否则回退到 `INITIAL_PASSWORD`。
+- `requireLogin` 可以通过 `/api/settings/require-login` 切换。
+
+### 请求处理（高级）
+
+1. 客户端向 `/v1/*` 发送请求。
+2. 路由处理器调用 `handleChat`（`src/sse/handlers/chat.js`）。
+3. 模型被解析直接提供商/模型或别名/组合解析）。
+4. 从本地数据库选择凭据，并进行账户可用性过滤。
+5. `handleChatCore`（`open-sse/handlers/chatCore.js`）检测格式并转换请求。
+6. 提供商执行器发送上游请求。
+7. 需要时将流转换回客户端格式。
+8. 记录使用/日志（`src/lib/usageDb.js`）。
+9. 根据组合规则在提供商/账户/模型错误时应用回退。
+
+完整架构参考：[`docs/ARCHITECTURE`](../docs/ARCHITECTURE.md)
+
+---
+
+## 📧 支持
+
+- **网站**：[9router.com](https://9router.com)
+- **GitHub**：[github.com/decolua/9router](https://github.com/decolua/9router)
+- **问题**：[github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+
+---
+
+## 👥 贡献者
+
+感谢所有帮助让 9Router 变得更好的贡献者！
+
+[![Contributors](https://contrib.rocks/image?repo=decolua/9router&max=100&columns=20&anon=1)](https://github.com/decolua/9router/graphs/contributors)
+
+---
+
+## 📊 Star 图表
+
+[![Star Chart](https://starchart.cc/decolua/9router.svg?variant=adaptive)](https://starchart.cc/decolua/9router)
+
+### 如何贡献
+
+1. Fork 仓库
+2. 创建您的功能分支（`git checkout -b feature/amazing-feature`）
+3. 提交您的更改（`git commit -m 'Add amazing feature'`）
+4 推送到分支（`git push origin feature/amazing-feature`）
+5. 打开 Pull Request
+
+详细指南请参阅 [Pull Requests](https://github.com/decolua/9router/pulls)。
+
+---
+
+## 🔀 分支
+
+**[OmniRoute](https://github.com/diegosouzapw/OmniRoute)** — 9Router 的全功能 TypeScript 分支。添加了 36+ 提供商、4 层自动回退、多模态 API（图像、嵌入、音频、TTS）、熔断器、语义缓存、LLM 评估和精美的仪表板。8+ 单元测试。通过 npm 和 Docker 可用。
+
+---
+
+## 🙏 致谢
+
+特别感谢 **CLIProxyAPI** - 启发这个 JavaScript 移植的原始 Go 实现。
+
+---
+
+## 📄 许可证
+
+MIT License - 详情请参阅 [LICENSE](../LICENSE)。
+
+---
+
+<div align="center">
+  <sub>用 ❤️ 为 24/7 编程的开发者构建</sub>
+</div>
diff --git a/images/9router.png b/images/9router.png
new file mode 100644
index 0000000..283210a
Binary files /dev/null and b/images/9router.png differ
diff --git a/images/fusion-combo-ui.png b/images/fusion-combo-ui.png
new file mode 100644
index 0000000..8799d72
Binary files /dev/null and b/images/fusion-combo-ui.png differ
diff --git a/jsconfig.json b/jsconfig.json
new file mode 100644
index 0000000..e8d4942
--- /dev/null
+++ b/jsconfig.json
@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "open-sse": ["./open-sse"],
+      "open-sse/*": ["./open-sse/*"]
+    },
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  }
+}
diff --git a/next.config.mjs b/next.config.mjs
new file mode 100644
index 0000000..d017c15
--- /dev/null
+++ b/next.config.mjs
@@ -0,0 +1,91 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const projectRoot = dirname(fileURLToPath(import.meta.url));
+// CLI bundling needs workspace root so tracing includes hoisted node_modules (slim ~50MB).
+// Docker / default uses projectRoot so server.js lands at /app/server.js (not nested).
+const tracingRoot = process.env.NEXT_TRACING_ROOT_MODE === "workspace"
+  ? join(projectRoot, "..")
+  : projectRoot;
+const proxyClientMaxBodySize = process.env.NINEROUTER_PROXY_CLIENT_MAX_BODY_SIZE || "128mb";
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  distDir: process.env.NEXT_DIST_DIR || ".next",
+  output: "standalone",
+  serverExternalPackages: ["better-sqlite3", "sql.js", "node:sqlite", "bun:sqlite"],
+  turbopack: {
+    root: tracingRoot
+  },
+  outputFileTracingRoot: tracingRoot,
+  outputFileTracingExcludes: {
+    "*": ["./gitbook/**/*"]
+  },
+  images: {
+    unoptimized: true
+  },
+  env: {},
+  experimental: {
+    // #1529/#1572: LLM clients can send long context or base64 image payloads through /v1 rewrites.
+    proxyClientMaxBodySize,
+    // Cache fetch responses across HMR refreshes for faster dev reloads.
+    serverComponentsHmrCache: true,
+    // Tree-shake heavy barrel imports to cut compile + bundle size
+    optimizePackageImports: ["@xyflow/react", "@dnd-kit/core", "@dnd-kit/sortable", "material-symbols", "marked"],
+  },
+  webpack: (config, { isServer }) => {
+    // Ignore fs/path modules in browser bundle
+    if (!isServer) {
+      config.resolve.fallback = {
+        ...config.resolve.fallback,
+        fs: false,
+        path: false,
+      };
+    }
+    // Exclude non-source dirs from watcher to reduce inotify load
+    config.watchOptions = {
+      ...config.watchOptions,
+      aggregateTimeout: 300,
+      ignored: /[\\/](node_modules|\.git|logs|\.next|\.next-cli-build|gitbook|cli|open-sse\.old|tests|docs)[\\/]/,
+    };
+    return config;
+  },
+  async rewrites() {
+    return [
+      {
+        source: "/v1/v1/:path*",
+        destination: "/api/v1/:path*"
+      },
+      {
+        source: "/v1/v1",
+        destination: "/api/v1"
+      },
+      {
+        source: "/codex/:path*",
+        destination: "/api/v1/responses"
+      },
+      {
+        source: "/responses",
+        destination: "/api/v1/responses"
+      },
+      {
+        source: "/v1beta/:path*",
+        destination: "/api/v1beta/:path*"
+      },
+      {
+        source: "/v1beta",
+        destination: "/api/v1beta"
+      },
+      {
+        source: "/v1/:path*",
+        destination: "/api/v1/:path*"
+      },
+      {
+        source: "/v1",
+        destination: "/api/v1"
+      }
+    ];
+  }
+};
+
+export default nextConfig;
diff --git a/open-sse/.npmignore b/open-sse/.npmignore
new file mode 100644
index 0000000..0b7b569
--- /dev/null
+++ b/open-sse/.npmignore
@@ -0,0 +1,8 @@
+node_modules/
+*.log
+.DS_Store
+test/
+*.test.js
+.env
+.env.*
+
diff --git a/open-sse/AGENTS.md b/open-sse/AGENTS.md
new file mode 100644
index 0000000..5ea0d97
--- /dev/null
+++ b/open-sse/AGENTS.md
@@ -0,0 +1,39 @@
+# open-sse
+
+Provider-agnostic SSE engine: one OpenAI-style request → any provider (LLM chat, image, embedding, tts, stt, search), streamed back in the client's format.
+
+## Request lifecycle (chat)
+
+`handlers/chatCore.js` → `services/model.js` `parseModel` (resolve `provider/model`) → **pre-translate hooks** (`rtk/` tool_result compress, `rtk/headroom.js` proxy compress, `rtk/caveman.js` system inject — all fail-open) → `executors/index.js` `getExecutor(provider)` → `translator/index.js` `translateRequest` (client format → provider format) → `executor.execute()` (streams upstream) → `translateResponse` (provider chunks → client format) → SSE out.
+
+## Directory map
+
+- `config/` — ALL constants/config (no hardcode elsewhere). `providers.js`/`registry/` (provider defs), `providerModels.js` (alias→models matrix), `runtimeConfig.js` (timeouts, token limits), `*Constants.js`.
+- `translator/` — format conversion. `request/<from>-to-<to>.js`, `response/<from>-to-<to>.js`, `schema/` (enums: ROLE, CLAUDE_BLOCK…), `concerns/` (shared logic), `formats.js`+`formats/` (per-format). `index.js` is the registry/entry.
+- `executors/` — per-provider upstream call. `base.js` (BaseExecutor), one file per special provider, `index.js` map.
+- `providers/` — registry build + `capabilities.js` + `pricing.js`. Entry: `index.js` (PROVIDERS).
+- `handlers/` — per-modality cores (chat/image/embedding/tts/stt/search) + sub-provider folders. `chatCore/` has the streaming/non-streaming/sse-to-json handlers.
+- `rtk/` — request token-killer. `index.js` compresses `tool_result` content in-place (OpenAI/Claude/Kiro shapes); `filters/` per-tool compressors + `autodetect.js`; `headroom.js` external compress proxy; `caveman.js` system-prompt injector.
+- `transformer/` — `responsesTransformer.js` (Chat Completions SSE → Codex Responses API SSE), `streamToJsonConverter.js`.
+- `shared/` — cross-provider auth/identity: `clineAuth.js`, `machineId.js`, `qoder/`.
+- `services/` — `model.js`, `provider.js`, `accountFallback.js`, `combo.js`, `compact.js`, `tokenRefresh/`+`tokenRefresh.js`, `oauthCredentialManager.js`, `usage/`, `projectId.js`, `kiroModels.js`/`qoderModels.js`.
+- `utils/` — streamHandler, stream, sse, error, sessionManager, claudeCloaking, clientDetector, proxyFetch (patches global fetch), cursorProtobuf/cursorChecksum, ollamaTransform.
+
+## Conventions
+
+- Config-driven, DRY, camelCase. NEVER hardcode values, models, or block/role strings — use `config/` + `schema/` constants.
+- Translator pipeline pivots through OpenAI as the intermediate format. A translator registered on the exact `source:target` pair (e.g. `claude:kiro`) runs as a **direct route**, skipping the lossy double-hop.
+- Translators self-register via `register(from, to, reqFn, resFn)` as an import side-effect — new files MUST be imported in `translator/index.js`.
+
+## How to add
+
+- **Provider**: copy `providers/REGISTRY_TEMPLATE.js` → `providers/registry/{id}.js`; add models to `config/providerModels.js`. Generic providers need no executor (DefaultExecutor handles OpenAI-compatible APIs).
+- **Executor** (only for non-standard upstream): subclass `BaseExecutor` (override `getBaseUrls`/`buildHeaders`/`buildUrl`/`execute`), register in `executors/index.js` map. `getExecutor` falls back to `DefaultExecutor` when absent.
+- **Translator**: add `request|response/<from>-to-<to>.js` calling `register(...)`, then import it in `translator/index.js`. Reuse `schema/` + `concerns/` — don't re-implement parsing.
+
+## Pitfalls
+
+- OpenAI bridge is lossy (thinking, non-base64 images, tool ids, is_error) — prefer a direct route for fragile pairs.
+- `registry/index.js` is an auto-generated static import list; regenerate it (don't hand-edit) after adding a `registry/{id}.js`. REGISTRY_TEMPLATE is excluded by design.
+- Special binary/protobuf formats (kiro EventStream, cursor protobuf, commandcode NDJSON) don't round-trip through OpenAI — handle in their executor.
+- `rtk/` + `headroom.js` mutate the request body in-place and are **fail-open**: any error returns null and leaves the body untouched — never throw out of them. RTK skips `is_error`/`status:"error"` tool results to preserve traces.
diff --git a/open-sse/config/appConstants.js b/open-sse/config/appConstants.js
new file mode 100644
index 0000000..cc46697
--- /dev/null
+++ b/open-sse/config/appConstants.js
@@ -0,0 +1,182 @@
+import { platform, arch } from "os";
+import { PROVIDERS, PROVIDER_OAUTH } from "./providers.js";
+import { ANTIGRAVITY_IDE_USER_AGENT } from "../providers/shared.js";
+
+// === Gemini CLI === derive từ registry gemini-cli.transport
+export const GEMINI_CLI_VERSION = PROVIDERS["gemini-cli"]?.cliVersion;
+export const GEMINI_CLI_API_CLIENT = PROVIDERS["gemini-cli"]?.apiClient;
+
+// Map Node arch to Gemini CLI arch string (x64/x86/arm64/...)
+function geminiCLIArch() {
+  const a = arch();
+  if (a === "ia32") return "x86";
+  return a;
+}
+
+export function geminiCLIUserAgent(model = "unknown") {
+  return `GeminiCLI/${GEMINI_CLI_VERSION}/${model || "unknown"} (${platform()}; ${geminiCLIArch()}; terminal)`;
+}
+
+// === GitHub Copilot ===
+// Derive từ registry github.transport.copilot
+const _ghCopilot = PROVIDERS.github?.copilot || {};
+export const GITHUB_COPILOT = {
+  VSCODE_VERSION: _ghCopilot.vscodeVersion,
+  COPILOT_CHAT_VERSION: _ghCopilot.chatVersion,
+  USER_AGENT: _ghCopilot.userAgent,
+  API_VERSION: _ghCopilot.apiVersion,
+};
+
+// === Antigravity enums ===
+export const IDE_TYPE = {
+  UNSPECIFIED: 0,
+  JETSKI: 10,
+  ANTIGRAVITY: 9,
+  PLUGINS: 7
+};
+
+export const PLATFORM = {
+  UNSPECIFIED: 0,
+  DARWIN_AMD64: 1,
+  DARWIN_ARM64: 2,
+  LINUX_AMD64: 3,
+  LINUX_ARM64: 4,
+  WINDOWS_AMD64: 5
+};
+
+export const PLUGIN_TYPE = {
+  UNSPECIFIED: 0,
+  CLOUD_CODE: 1,
+  GEMINI: 2
+};
+
+export function getPlatformEnum() {
+  const os = platform();
+  const architecture = arch();
+  if (os === "darwin") return architecture === "arm64" ? PLATFORM.DARWIN_ARM64 : PLATFORM.DARWIN_AMD64;
+  if (os === "linux") return architecture === "arm64" ? PLATFORM.LINUX_ARM64 : PLATFORM.LINUX_AMD64;
+  if (os === "win32") return PLATFORM.WINDOWS_AMD64;
+  return PLATFORM.UNSPECIFIED;
+}
+
+export function getPlatformUserAgent() {
+  return ANTIGRAVITY_IDE_USER_AGENT;
+}
+
+export const CLIENT_METADATA = {
+  ideType: IDE_TYPE.ANTIGRAVITY,
+  platform: getPlatformEnum(),
+  pluginType: PLUGIN_TYPE.GEMINI
+};
+
+// Internal anti-loop header
+export const INTERNAL_REQUEST_HEADER = { name: "x-request-source", value: "local" };
+
+// Suffix added to client tools when forwarding to Antigravity provider (anti-ban cloaking)
+export const AG_TOOL_SUFFIX = "_ide";
+
+// Suffix added to client tools when forwarding to Claude provider (anti-ban cloaking)
+export const CLAUDE_TOOL_SUFFIX = "_ide";
+
+// CC native default tools — these are Claude Code's own tools, kept as decoys
+// Client tools matching these names are skipped (not renamed), others get _cc suffix
+export const CC_DEFAULT_TOOLS = new Set([
+  "Task",
+  "TaskOutput",
+  "TaskStop",
+  "TaskCreate",
+  "TaskGet",
+  "TaskUpdate",
+  "TaskList",
+  "Bash",
+  "Glob",
+  "Grep",
+  "Read",
+  "Edit",
+  "Write",
+  "NotebookEdit",
+  "WebFetch",
+  "WebSearch",
+  "AskUserQuestion",
+  "Skill",
+  "EnterPlanMode",
+  "ExitPlanMode",
+]);
+
+// AG native default tools — kept as decoys with neutral description/properties
+// These names must match exactly what AG sends in the real request log
+export const AG_DEFAULT_TOOLS = new Set([
+  "browser_subagent",
+  "command_status",
+  "find_by_name",
+  "generate_image",
+  "grep_search",
+  "list_dir",
+  "list_resources",
+  "multi_replace_file_content",
+  "notify_user",
+  "read_resource",
+  "read_terminal",
+  "read_url_content",
+  "replace_file_content",
+  "run_command",
+  "search_web",
+  "send_command_input",
+  "task_boundary",
+  "view_content_chunk",
+  "view_file",
+  "write_to_file"
+]);
+
+// Antigravity chat/stream headers
+export const ANTIGRAVITY_HEADERS = {
+  "User-Agent": ANTIGRAVITY_IDE_USER_AGENT
+};
+
+// Cloud Code Assist API
+export const CLOUD_CODE_API = {
+  loadCodeAssist: "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+  onboardUser: "https://cloudcode-pa.googleapis.com/v1internal:onboardUser",
+};
+
+export const LOAD_CODE_ASSIST_HEADERS = {
+  "Content-Type": "application/json",
+  "User-Agent": "google-api-nodejs-client/9.15.1",
+  "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+  "Client-Metadata": JSON.stringify({ ideType: IDE_TYPE.ANTIGRAVITY, platform: getPlatformEnum(), pluginType: PLUGIN_TYPE.GEMINI }),
+};
+
+export const LOAD_CODE_ASSIST_METADATA = {
+  ideType: IDE_TYPE.ANTIGRAVITY,
+  platform: getPlatformEnum(),
+  pluginType: PLUGIN_TYPE.GEMINI,
+};
+
+// System prompts
+export const CLAUDE_SYSTEM_PROMPT = "You are Claude Code, Anthropic's official CLI for Claude.";
+export const ANTIGRAVITY_DEFAULT_SYSTEM = "You are Antigravity, a powerful agentic AI coding assistant designed by the Google Deepmind team working on Advanced Agentic Coding.You are pair programming with a USER to solve their coding task. The task may require creating a new codebase, modifying or debugging an existing codebase, or simply answering a question.**Absolute paths only****Proactiveness**";
+
+// Derive từ registry oauth.refreshLeadMs
+export const REFRESH_LEAD_MS = Object.fromEntries(
+  Object.entries(PROVIDER_OAUTH).filter(([, o]) => o.refreshLeadMs).map(([id, o]) => [id, o.refreshLeadMs])
+);
+
+// OAuth endpoints
+export const OAUTH_ENDPOINTS = {
+  google:    { token: "https://oauth2.googleapis.com/token", auth: "https://accounts.google.com/o/oauth2/auth" },
+  openai:    { token: PROVIDER_OAUTH["codex"]?.tokenUrl, auth: PROVIDER_OAUTH["codex"]?.authorizeUrl },
+  anthropic: { token: PROVIDER_OAUTH["claude"]?.tokenUrl, auth: "https://api.anthropic.com/v1/oauth/authorize" }, // ≠ claude.authorizeUrl (claude.ai login) — keep
+  qwen:      { token: PROVIDER_OAUTH["qwen"]?.tokenUrl, auth: PROVIDER_OAUTH["qwen"]?.deviceCodeUrl },
+  iflow:     { token: PROVIDER_OAUTH["iflow"]?.tokenUrl, auth: PROVIDER_OAUTH["iflow"]?.authorizeUrl },
+  github:    { token: PROVIDER_OAUTH["github"]?.tokenUrl, auth: PROVIDER_OAUTH["github"]?.authorizeUrl, deviceCode: PROVIDER_OAUTH["github"]?.deviceCodeUrl },
+};
+
+// Generate Kimi OAuth custom headers
+export function buildKimiHeaders() {
+  return {
+    "X-Msh-Platform": "9router",
+    "X-Msh-Version": "2.1.2",
+    "X-Msh-Device-Model": typeof process !== "undefined" ? `${process.platform} ${process.arch}` : "unknown",
+    "X-Msh-Device-Id": `kimi-${Date.now()}`
+  };
+}
diff --git a/open-sse/config/codexInstructions.js b/open-sse/config/codexInstructions.js
new file mode 100644
index 0000000..75b691d
--- /dev/null
+++ b/open-sse/config/codexInstructions.js
@@ -0,0 +1,119 @@
+// Default instructions for Codex models
+
+export const CODEX_DEFAULT_INSTRUCTIONS = `You are Codex, based on GPT-5. You are running as a coding agent in the Codex CLI on a user's computer.
+
+## General
+
+- When searching for text or files, prefer using \`rg\` or \`rg --files\` respectively because \`rg\` is much faster than alternatives like \`grep\`. (If the \`rg\` command is not found, then use alternatives.)
+
+## Editing constraints
+
+- Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
+- Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare.
+- Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase).
+- You may be in a dirty git worktree.
+    * NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
+    * If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
+    * If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them.
+    * If the changes are in unrelated files, just ignore them and don't revert them.
+- Do not amend a commit unless explicitly requested to do so.
+- While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed.
+- **NEVER** use destructive commands like \`git reset --hard\` or \`git checkout --\` unless specifically requested or approved by the user.
+
+## Plan tool
+
+When using the planning tool:
+- Skip using the planning tool for straightforward tasks (roughly the easiest 25%).
+- Do not make single-step plans.
+- When you made a plan, update it after having performed one of the sub-tasks that you shared on the plan.
+
+## Codex CLI harness, sandboxing, and approvals
+
+The Codex CLI harness supports several different configurations for sandboxing and escalation approvals that the user can choose from.
+
+Filesystem sandboxing defines which files can be read or written. The options for \`sandbox_mode\` are:
+- **read-only**: The sandbox only permits reading files.
+- **workspace-write**: The sandbox permits reading files, and editing files in \`cwd\` and \`writable_roots\`. Editing files in other directories requires approval.
+- **danger-full-access**: No filesystem sandboxing - all commands are permitted.
+
+Network sandboxing defines whether network can be accessed without approval. Options for \`network_access\` are:
+- **restricted**: Requires approval
+- **enabled**: No approval needed
+
+Approvals are your mechanism to get user consent to run shell commands without the sandbox. Possible configuration options for \`approval_policy\` are
+- **untrusted**: The harness will escalate most commands for user approval, apart from a limited allowlist of safe "read" commands.
+- **on-failure**: The harness will allow all commands to run in the sandbox (if enabled), and failures will be escalated to the user for approval to run again without the sandbox.
+- **on-request**: Commands will be run in the sandbox by default, and you can specify in your tool call if you want to escalate a command to run without sandboxing. (Note that this mode is not always available. If it is, you'll see parameters for it in the \`shell\` command description.)
+- **never**: This is a non-interactive mode where you may NEVER ask the user for approval to run commands. Instead, you must always persist and work around constraints to solve the task for the user. You MUST do your utmost best to finish the task and validate your work before yielding. If this mode is paired with \`danger-full-access\`, take advantage of it to deliver the best outcome for the user. Further, in this mode, your default testing philosophy is overridden: Even if you don't see local patterns for testing, you may add tests and scripts to validate your work. Just remove them before yielding.
+
+When you are running with \`approval_policy == on-request\`, and sandboxing enabled, here are scenarios where you'll need to request approval:
+- You need to run a command that writes to a directory that requires it (e.g. running tests that write to /var)
+- You need to run a GUI app (e.g., open/xdg-open/osascript) to open browsers or files.
+- You are running sandboxed and need to run a command that requires network access (e.g. installing packages)
+- If you run a command that is important to solving the user's query, but it fails because of sandboxing, rerun the command with approval. ALWAYS proceed to use the \`sandbox_permissions\` and \`justification\` parameters - do not message the user before requesting approval for the command.
+- You are about to take a potentially destructive action such as an \`rm\` or \`git reset\` that the user did not explicitly ask for
+- (for all of these, you should weigh alternative paths that do not require approval)
+
+When \`sandbox_mode\` is set to read-only, you'll need to request approval for any command that isn't a read.
+
+You will be told what filesystem sandboxing, network sandboxing, and approval mode are active in a developer or user message. If you are not told about this, assume that you are running with workspace-write, network sandboxing enabled, and approval on-failure.
+
+Although they introduce friction to the user because your work is paused until the user responds, you should leverage them when necessary to accomplish important work. If the completing the task requires escalated permissions, Do not let these settings or the sandbox deter you from attempting to accomplish the user's task unless it is set to "never", in which case never ask for approvals.
+
+When requesting approval to execute a command that will require escalated privileges:
+  - Provide the \`sandbox_permissions\` parameter with the value \`"require_escalated"\`
+  - Include a short, 1 sentence explanation for why you need escalated permissions in the justification parameter
+
+## Special user requests
+
+- If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as \`date\`), you should do so.
+- If the user asks for a "review", default to a code review mindset: prioritise identifying bugs, risks, behavioural regressions, and missing tests. Findings must be the primary focus of the response - keep summaries or overviews brief and only after enumerating the issues. Present findings first (ordered by severity with file/line references), follow with open questions or assumptions, and offer a change-summary only as a secondary detail. If no findings are discovered, state that explicitly and mention any residual risks or testing gaps.
+
+## Frontend tasks
+When doing frontend design tasks, avoid collapsing into "AI slop" or safe, average-looking layouts.
+Aim for interfaces that feel intentional, bold, and a bit surprising.
+- Typography: Use expressive, purposeful fonts and avoid default stacks (Inter, Roboto, Arial, system).
+- Color & Look: Choose a clear visual direction; define CSS variables; avoid purple-on-white defaults. No purple bias or dark mode bias.
+- Motion: Use a few meaningful animations (page-load, staggered reveals) instead of generic micro-motions.
+- Background: Don't rely on flat, single-color backgrounds; use gradients, shapes, or subtle patterns to build atmosphere.
+- Overall: Avoid boilerplate layouts and interchangeable UI patterns. Vary themes, type families, and visual languages across outputs.
+- Ensure the page loads properly on both desktop and mobile
+
+Exception: If working within an existing website or design system, preserve the established patterns, structure, and visual language.
+
+## Presenting your work and final message
+
+You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.
+
+- Default: be very concise; friendly coding teammate tone.
+- Ask only when needed; suggest ideas; mirror the user's style.
+- For substantial work, summarize clearly; follow final‑answer formatting.
+- Skip heavy formatting for simple confirmations.
+- Don't dump large files you've written; reference paths only.
+- No "save/copy this file" - User is on the same machine.
+- Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something.
+- For code changes:
+  * Lead with a quick explanation of the change, and then give more details on the context covering where and why a change was made. Do not start this explanation with "summary", just jump right in.
+  * If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps.
+  * When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number.
+- The user does not command execution outputs. When asked to show the output of a command (e.g. \`git show\`), relay the important details in your answer or summarize the key lines so the user understands the result.
+
+### Final answer structure and style guidelines
+
+- Plain text; CLI handles styling. Use structure only when it helps scanability.
+- Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blank line before the first bullet; add only if they truly help.
+- Bullets: use - ; merge related points; keep to one line when possible; 4–6 per list ordered by importance; keep phrasing consistent.
+- Monospace: backticks for commands/paths/env vars/code ids and inline examples; use for literal keyword bullets; never combine with **.
+- Code samples or multi-line snippets should be wrapped in fenced code blocks; include an info string as often as possible.
+- Structure: group related bullets; order sections general → specific → supporting; for subsections, start with a bolded keyword bullet, then items; match complexity to the task.
+- Tone: collaborative, concise, factual; present tense, active voice; self‑contained; no "above/below"; parallel wording.
+- Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelated keywords; keep keyword lists short—wrap/reformat if long; avoid naming formatting styles in answers.
+- Adaptation: code explanations → precise, structured with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences, no headers/bullets.
+- File References: When referencing files in your response follow the below rules:
+  * Use inline code to make file paths clickable.
+  * Each reference should have a stand alone path. Even if it's the same file.
+  * Accepted: absolute, workspace‑relative, a/ or b/ diff prefixes, or bare filename/suffix.
+  * Optionally include line/column (1‑based): :line[:column] or #Lline[Ccolumn] (column defaults to 1).
+  * Do not use URIs like file://, vscode://, or https://.
+  * Do not provide range of lines
+  * Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\\repo\\project\\main.rs:12:5`;
diff --git a/open-sse/config/constants.js b/open-sse/config/constants.js
new file mode 100644
index 0000000..7607376
--- /dev/null
+++ b/open-sse/config/constants.js
@@ -0,0 +1,4 @@
+// Barrel re-export — consumers can migrate to specific files over time
+export * from "./providers.js";
+export * from "./appConstants.js";
+export * from "./runtimeConfig.js";
diff --git a/open-sse/config/defaultThinkingSignature.js b/open-sse/config/defaultThinkingSignature.js
new file mode 100644
index 0000000..50975a4
--- /dev/null
+++ b/open-sse/config/defaultThinkingSignature.js
@@ -0,0 +1,12 @@
+// Default signature for thinking mode when no signature from thinkingStore
+export const DEFAULT_THINKING_CLAUDE_SIGNATURE = "EpwGCkYIChgCKkCzVUuRrg7CcglSUWEef4rH6o35g9UYS8ZPe0/VomQTBsFx6sttYNj5l8GqgW6ejuHyYqpFToxIbZl0bw17l5dJEgzCnqDO0Z8fRlMrNgsaDLS1cnCjC53KBqE0CCIwAADQdo1eO+7qPAmo8J4WR3JPmr92S97kmvr5K1iPMiOpkZNj8mEXW8uzBoOJs/9ZKoMFiqHJ3UObwaJDqFOW70E9oCwDoc6jesaWVAEdN5vWfKMpIkjFJjECdjIdkxyJNJ8Ib8yXVal3qwE7uThoPRqSZDdHB5mmwPEjWE/90cSYCbtX2YsJki1265CabBb8/QEkODXg4kgRrL+c8e8rRXz/dr1RswvaPuzEdGKHRNi9UooNUeOK4/ebx1KkP9YZttyohN9GWqlts36kOoW0Cfie/ABDgF9g534BPth/sstxDM6d79QlRmh6NxizyTF74DXJI34u0M4tTRchqE5pAq85SgdJaa+dix1yJPMji8m6nZkwJbscJb9rdc2MKyKWjz8QL2+rTSSuZ2F1k1qSsW0xNcI7qLcI12Vncfn/VqY6YOIZy/saZBR0ezXvN6g+UYbuIdyVg7AyIFZt3nbrO7/kmOEb2VKzygwklHGEIJHfFgMpH3JSrAzbZIowVHOF7VaJ+KXRFDCFin7hHTOiOsdg+1ij1mML9Z/x/9CP4b7OUcaQm1llDZPSHc6rZMNL3DdB+fW5YfmNgKU35S+7AMtA10nVILzDAk1UV4T2K9Do09JlI6rjOs9UuULlIN2Z0eE8YTlANR6uQcw7lMcdfqYE8tke4rDKc2dDiaS5vVe45VewICNpdXGN11yw8QqH7p27CR1HtN30e0tHXOR3bIwWk/Yb6O5fTaKG6Ri8e5ZCPvdD9HqepVi188nM0iTjJqL58F3ni04ECIhcbyaQWnuTes1Kw4CMwiZDLQkk8Hgz7HkUOf1btQTF/0nhD7ry0n0hAEg2PaDM3V6TjOjf4hEldRmeqERcQF1PfgKb6ZM12rlIIfUqKACczWJSzTV158+47HX36o0cgux6nFlv/DE+sEiRVxgB";
+
+export const DEFAULT_THINKING_AG_SIGNATURE = "EuwGCukGAXLI2nxwZIq54WWSoL/YN0P3TsDZ7zRnLi8g0S4aVr2HUGxvaHKySuY6HAVzcE0GPGjXrytLIldxthSvfxgUlJh6Qa9Z+Oj5QZBlYdg6HaJ6yuY5R7waE6rdwBsRf7Ft2j3DJ9rMi9qhWFqApewYtPhls3VHtuvND3l8Rm09+lbAXQs6KKWEWrxNLKTBkfpMgXhRERc/TQRMZu1twAablm6/Zk1tsYRvfWKLsNbeKF+CCojJdXJKvnR/8Ouuoa+Y2Ti20hcW7aZIIjZDFYPU//k6Ybmhg69J/imbFai2ckhfLaisqdDkdoIiBJScTOUvYqP6AE9d4MsydSC+UlhIMk4hoP76R8vUSCZRMkjOaDXstf/QoVZKbt94wyRZgAJ1G0BqI8L5ow86kLpA4wJEtxsRGymOE4bKUvApveBakYDNM9APkf+LbtbzWSseGjoZcSlycF9iN8Q2XNYKRrHbv3Lr5Y8JjdH/5y/6SHkNehTEZugaeGnSPSyCTWto1kQgHpxdWmhkLfJGNUGLmue7Mesj4TSms4J33mRpYVhNB/J333FCqIP0hr/E7BkkjEn7yZ4X7SQlh+xKPurapsnHRwiKmtsilmEFrnTE9iQr+pMr6M29qqFNv1tr5yumbaJw8JW9sB15tNsRv+dW6BjNanbsKz7HCgKUBc8tGy+7YuhXzAfViyRefcjK7eZW0Fbyt7AbybJTKz78W8NH7ye6LAwzOebXpeZ4D43fNIt8bKh26qgduSQv/7o+pAflkuqHZ99YWgHQ8h8OkZFi3eOiSYjsjhdZ/czWOdoPI/OnqIldzMPF5YlrKBLFX8VhRKVmqgsmWf5PHGulHhMkVlS+XG2UIseGy69ARa93D78Gsa+1n1kJr7EEB7Rh+27vUMxVYLdz1yMSvE5nalTAlg/ZeG8+XQ0cHuAI3KbQpHW2Q++RdXfm5JzD5WdJZUU+Zn8t8UUn85BH4RxZLeE0qJikgSsKoYVBc6YhiMjhPgkR95ReimY4Z0xCJdRo1gjexOFeODZMpQF6Yxnoic7IrdgsFA3iePTbFnPp3IAM1fAThWhXJUn3QInUOTd5o1qmTmn6REbL15g/JQNl+dqUoPkhleeb2V3kjqp1okmO3wMZbPknR3S1LZNmlS72/iBQUm+n2b/RCn4PjmM2";
+
+export const DEFAULT_THINKING_VERTEX_SIGNATURE = "CloBjz1rX5+yg1ILh/Ag+suum5k1f/9m/hI0XDQ33lsQIYnOHLn9KZwN0C7E4jgep5MzZvz5Se1Z1xxYrA1+Iz0Il4tabBhaDfMKNa5dGdEA3KnikfjfIpMlPaAKaQGPPWtf2hodPdBgguiZqDn+Qz2LwGEqHVJ16LVBUpeSx7UnYBLSwio8cyNy0jPijOh5QXKLTeHVdO2tKKcCCrtG2JCW3dOSrW2qA8eyAg40iQUnMNECjbcjkqB1+zrab7jX9ILwg7L9OgqYAQGPPWtfT4nzaPzSkXePAa920abYxPs3fg/RHDlg8PUVFLa+ko6qOjt7nXJTMxN0cpCwUCFX7eHHcMnA6vApyA/rXvJiAABkHZ3HilAktXRtxr/thHU0H8/4H5gT3kzoQcq9aMznrKomd3ct0mFi0ioSKnOEfoY1Mrfj00p/ZWm0tT7Wrjcm3BQXZ+T9Vrb94k+6CjtcEBrGCq8BAY89a1/vTMczqwB1NP3HCCuBdnds2vDXkj6XAYaXjsjmik8tGqwMKHz8R9RAWsx6SO6pkGEpXXpRzAaUx6c+aofsL/z1xOcN7ArCAa6uEeQKEgNngZuCP05p4+9P95epVmgOjFa4KfsPnyg+NKUkEFmpPSDrIRyMT+xERlclVcCI98/u7i8a9+vTbgzl8TRFYryClNH37K1ye5i6kqSGDUcMyiEasjke5BxbUh3i6wqMAgGPPWtfk+A+iY38QAldu117FEkTIkzbYOIt67lk9c6Ou3Y3Ct8TFHFw5QwGfSFc0YWjeTFHdm9UdV5jPK35p6VfhiRSva3w2+JLIHb4jvv5HutZPOJ3yQTt/+hUDj80oMNMbwnxNZvCEdzKS+D9vwmTACAm5H0ZetBSH2gPJXnhhuQo9AegS3wIWVR2a5k643Vx9r4u4pOvij4476lxKswIHvqsjL4jnTzRCvd44G6dn7vD0ENGb1K/i+dMRQMcOBaOxPN0ynk9bKxXWRDbZ+Rhakfr+y74z+6eYCdRPVqO9I7s+riilFuRIfaQ+U6/vuVKGIWEVKCfZZi0z6H5Xgz1xmse0u0AsittDlIKxwEBjz1rX783A0vehvUeabRia+/pX46IsN5efTAxFEBUeUce3jLuXIghkMV2b8KNhUs2G0aZldDDewRQbkluQabBMDT82N5I7reJP0VZgLIKccCL5DoGv1J7YWM2npLMIgZ6aP8aSlT3PFFJ0IXbUZUrzduczmIm6nzAJf9zxmq1aIFYw8YrgW8RjUdy0UvUmRoBEShSGUrvsyaRTl7J//KJW5utIPunFMu53GPWLidCFHzM1QA3Cj1+4zv5UXajP/V92RQayWbzCvYBAY89a1+yzoVSWukUGH7kX71Tg9dx7HA7OyKYwnYaqekG98zJfcUM/3KoiiiotW5t4xYu//ksEl36bSWvUHsRnxGByg+3WYdnZqKg0AtdRB/EXbI5PsjvS5ko96bkjSuFkY3TjHGwAM2B94K6/t6OTE/NBbxCsY9sT4d+1sbFv/iyfmfCnfvJaSzGmC9CDWKy4iqQ/vBNWps9j1JXk0p5uPAYC2BaMkxl5xoTVZqI3zAuRtQF5JLmPPy+PdqOgFxMKcLGNhwp7dbhIFLF68vCYQ9CL0NnK2d3CFk1UFVYxsi1TsolR1xahe/Rxt5HZDz/z65nevrQ";
+
+export const DEFAULT_THINKING_GEMINI_CLI_SIGNATURE = "CiQBjz1rX/AlslZWMe5RgBt4Tv9j4+YNZTTez+JH2/+5oAlICygKXgGPPWtf7/Sux9eLYap/bmYAdPqFThLXj+l7o0DLu/hdgU98MA9ZrlRDNHXx+T0tuY8AcnjPZbiDyOq2bE11Fjhsk6p5axqayaapC/Pt9GczcgIQf1z15WTxCeKWAPYKYQGPPWtfDYj0nlNFNoTlU39RC91Z16xFKJ2MLEmkm+NvimsoOJ6be3g2BssNPtJ/9BKDXRA5cVs17tBeeW72lH8TMB5999udtxHM2SiUsnWsrHlfVuGSCpNQQ+5REw8HNvEKkgEBjz1rXzBNWrqZGbjun55K+vgYPBhJO2qZ67uRWXUA5/qcU12U/mbi5XoA3swoxYE8LEXfZvFFC9WG/W28QNCA0Qd4Trk/WkWiAwZmB8a84Fs14rkv3wqyxwFavPkJorqurAfd2XzGiFy0sB0ITCOPYi1HzDGV5WfXk6b9k+jT66/RuzGa8EcSOWo/QtC3Bkhgowo4AY89a1/f/tw8A02zjIoK7JVDAbf8W4UfmbApJJhwXIiGtu1M0JItObx7g2reYqT+HHL2Q/R4VDc=";
+
+
+export const DEFAULT_THINKING_TEXT = "...";
+
diff --git a/open-sse/config/errorConfig.js b/open-sse/config/errorConfig.js
new file mode 100644
index 0000000..71491a4
--- /dev/null
+++ b/open-sse/config/errorConfig.js
@@ -0,0 +1,85 @@
+// OpenAI-compatible error types mapping (client-facing)
+export const ERROR_TYPES = {
+  400: { type: "invalid_request_error", code: "bad_request" },
+  401: { type: "authentication_error", code: "invalid_api_key" },
+  402: { type: "billing_error", code: "payment_required" },
+  403: { type: "permission_error", code: "insufficient_quota" },
+  404: { type: "invalid_request_error", code: "model_not_found" },
+  406: { type: "invalid_request_error", code: "model_not_supported" },
+  429: { type: "rate_limit_error", code: "rate_limit_exceeded" },
+  500: { type: "server_error", code: "internal_server_error" },
+  502: { type: "server_error", code: "bad_gateway" },
+  503: { type: "server_error", code: "service_unavailable" },
+  504: { type: "server_error", code: "gateway_timeout" }
+};
+
+// Default error messages per status code (client-facing)
+export const DEFAULT_ERROR_MESSAGES = {
+  400: "Bad request",
+  401: "Invalid API key provided",
+  402: "Payment required",
+  403: "You exceeded your current quota",
+  404: "Model not found",
+  406: "Model not supported",
+  429: "Rate limit exceeded",
+  500: "Internal server error",
+  502: "Bad gateway - upstream provider error",
+  503: "Service temporarily unavailable",
+  504: "Gateway timeout"
+};
+
+// Exponential backoff config for rate limits
+export const BACKOFF_CONFIG = {
+  base: 2000,
+  max: 5 * 60 * 1000,
+  maxLevel: 15
+};
+
+// Default cooldown for transient/unknown errors
+export const TRANSIENT_COOLDOWN_MS = 30 * 1000;
+
+// Hard cap for provider-reported rate limit cooldown (e.g. codex resets_at can be 5-6h)
+export const MAX_RATE_LIMIT_COOLDOWN_MS = 30 * 60 * 1000;
+
+// Cooldown durations (ms)
+const COOLDOWN = {
+  long: 2 * 60 * 1000,
+  short: 5 * 1000,
+};
+
+/**
+ * Unified error classification rules.
+ * Checked top-to-bottom: text rules first (by order), then status rules.
+ * Each rule: { text?, status?, cooldownMs?, backoff? }
+ *   - text: substring match (case-insensitive) on error message
+ *   - status: HTTP status code match
+ *   - cooldownMs: fixed cooldown duration
+ *   - backoff: true = use exponential backoff (rate limit)
+ */
+export const ERROR_RULES = [
+  // --- Text-based rules (checked first, order = priority) ---
+  { text: "no credentials",           cooldownMs: COOLDOWN.long },
+  { text: "request not allowed",      cooldownMs: COOLDOWN.short },
+  { text: "improperly formed request", cooldownMs: COOLDOWN.long },
+  { text: "rate limit",               backoff: true },
+  { text: "too many requests",        backoff: true },
+  { text: "quota exceeded",           backoff: true },
+  { text: "capacity",                 backoff: true },
+  { text: "overloaded",               backoff: true },
+
+  // --- Status-based rules (fallback when text doesn't match) ---
+  { status: 401, cooldownMs: COOLDOWN.long },
+  { status: 402, cooldownMs: COOLDOWN.long },
+  { status: 403, cooldownMs: COOLDOWN.long },
+  { status: 404, cooldownMs: COOLDOWN.long },
+  { status: 429, backoff: true },
+];
+
+// Backward compat: COOLDOWN_MS object (used by index.js re-export)
+export const COOLDOWN_MS = {
+  unauthorized: COOLDOWN.long,
+  paymentRequired: COOLDOWN.long,
+  notFound: COOLDOWN.long,
+  transient: TRANSIENT_COOLDOWN_MS,
+  requestNotAllowed: COOLDOWN.short,
+};
diff --git a/open-sse/config/googleTtsLanguages.js b/open-sse/config/googleTtsLanguages.js
new file mode 100644
index 0000000..e7d35c2
--- /dev/null
+++ b/open-sse/config/googleTtsLanguages.js
@@ -0,0 +1,62 @@
+export const GOOGLE_TTS_LANGUAGES = [
+  { id: "af",    name: "Afrikaans",             type: "tts" },
+  { id: "ar",    name: "Arabic",                type: "tts" },
+  { id: "bg",    name: "Bulgarian",             type: "tts" },
+  { id: "bn",    name: "Bengali",               type: "tts" },
+  { id: "bs",    name: "Bosnian",               type: "tts" },
+  { id: "ca",    name: "Catalan",               type: "tts" },
+  { id: "cs",    name: "Czech",                 type: "tts" },
+  { id: "cy",    name: "Welsh",                 type: "tts" },
+  { id: "da",    name: "Danish",                type: "tts" },
+  { id: "de",    name: "German",                type: "tts" },
+  { id: "el",    name: "Greek",                 type: "tts" },
+  { id: "en",    name: "English",               type: "tts" },
+  { id: "eo",    name: "Esperanto",             type: "tts" },
+  { id: "es",    name: "Spanish",               type: "tts" },
+  { id: "et",    name: "Estonian",              type: "tts" },
+  { id: "fi",    name: "Finnish",               type: "tts" },
+  { id: "fr",    name: "French",                type: "tts" },
+  { id: "gu",    name: "Gujarati",              type: "tts" },
+  { id: "hi",    name: "Hindi",                 type: "tts" },
+  { id: "hr",    name: "Croatian",              type: "tts" },
+  { id: "hu",    name: "Hungarian",             type: "tts" },
+  { id: "hy",    name: "Armenian",              type: "tts" },
+  { id: "id",    name: "Indonesian",            type: "tts" },
+  { id: "is",    name: "Icelandic",             type: "tts" },
+  { id: "it",    name: "Italian",               type: "tts" },
+  { id: "ja",    name: "Japanese",              type: "tts" },
+  { id: "jw",    name: "Javanese",              type: "tts" },
+  { id: "km",    name: "Khmer",                 type: "tts" },
+  { id: "kn",    name: "Kannada",               type: "tts" },
+  { id: "ko",    name: "Korean",                type: "tts" },
+  { id: "la",    name: "Latin",                 type: "tts" },
+  { id: "lv",    name: "Latvian",               type: "tts" },
+  { id: "mk",    name: "Macedonian",            type: "tts" },
+  { id: "ml",    name: "Malayalam",             type: "tts" },
+  { id: "mr",    name: "Marathi",               type: "tts" },
+  { id: "my",    name: "Myanmar (Burmese)",      type: "tts" },
+  { id: "ne",    name: "Nepali",                type: "tts" },
+  { id: "nl",    name: "Dutch",                 type: "tts" },
+  { id: "no",    name: "Norwegian",             type: "tts" },
+  { id: "pl",    name: "Polish",                type: "tts" },
+  { id: "pt",    name: "Portuguese",            type: "tts" },
+  { id: "ro",    name: "Romanian",              type: "tts" },
+  { id: "ru",    name: "Russian",               type: "tts" },
+  { id: "si",    name: "Sinhala",               type: "tts" },
+  { id: "sk",    name: "Slovak",                type: "tts" },
+  { id: "sq",    name: "Albanian",              type: "tts" },
+  { id: "sr",    name: "Serbian",               type: "tts" },
+  { id: "su",    name: "Sundanese",             type: "tts" },
+  { id: "sv",    name: "Swedish",               type: "tts" },
+  { id: "sw",    name: "Swahili",               type: "tts" },
+  { id: "ta",    name: "Tamil",                 type: "tts" },
+  { id: "te",    name: "Telugu",                type: "tts" },
+  { id: "th",    name: "Thai",                  type: "tts" },
+  { id: "tl",    name: "Filipino",              type: "tts" },
+  { id: "tr",    name: "Turkish",               type: "tts" },
+  { id: "uk",    name: "Ukrainian",             type: "tts" },
+  { id: "ur",    name: "Urdu",                  type: "tts" },
+  { id: "vi",    name: "Vietnamese",            type: "tts" },
+  { id: "zh-CN", name: "Chinese (Simplified)",  type: "tts" },
+  { id: "zh-TW", name: "Chinese (Traditional)", type: "tts" },
+];
diff --git a/open-sse/config/kiroConstants.js b/open-sse/config/kiroConstants.js
new file mode 100644
index 0000000..3ff6acb
--- /dev/null
+++ b/open-sse/config/kiroConstants.js
@@ -0,0 +1,277 @@
+/**
+ * Kiro-specific constants and helpers.
+ *
+ * Mirrors the behaviour of `internal/translator/kiro/common/constants.go` and
+ * `internal/translator/kiro/claude/kiro_claude_request.go` from the
+ * CLIProxyAPIPlus reference implementation, scoped down to what 9router needs:
+ *
+ *   - `-agentic` model suffix detection + chunked-write system prompt
+ *   - reasoning / thinking trigger detection (Anthropic-Beta header,
+ *     Claude `thinking`, OpenAI `reasoning_effort`, AMP/Cursor magic tag)
+ *   - the `<thinking_mode>enabled</thinking_mode>` system-prompt injection
+ *     that turns Kiro reasoning on
+ *
+ * Kiro upstream does not advertise `-agentic` model IDs; they are a 9router
+ * fiction. The suffix is stripped before the request leaves this process.
+ */
+
+import { extractThinking } from "../translator/concerns/thinkingUnified.js";
+import { effortToBudget } from "../translator/concerns/thinking.js";
+
+export const KIRO_AGENTIC_SUFFIX = "-agentic";
+export const KIRO_THINKING_SUFFIX = "-thinking";
+
+// Public default CodeWhisperer profile ARNs (us-east-1), keyed by auth method.
+// Used when an account cannot resolve its own profileArn. Builder ID and social
+// (Google/GitHub) sign-ins map to different shared profiles.
+export const KIRO_DEFAULT_PROFILE_ARNS = {
+  "builder-id": "arn:aws:codewhisperer:us-east-1:638616132270:profile/AAAACCCCXXXX",
+  social: "arn:aws:codewhisperer:us-east-1:699475941385:profile/EHGA3GRVQMUK",
+};
+
+// Back-compat single default (Builder ID).
+export const KIRO_DEFAULT_PROFILE_ARN = KIRO_DEFAULT_PROFILE_ARNS["builder-id"];
+
+/** Resolve the shared default profileArn for a given auth method. */
+export function resolveDefaultProfileArn(authMethod) {
+  const social = authMethod === "google" || authMethod === "github";
+  return social ? KIRO_DEFAULT_PROFILE_ARNS.social : KIRO_DEFAULT_PROFILE_ARNS["builder-id"];
+}
+
+export const KIRO_THINKING_BUDGET_DEFAULT = 16000;
+
+export const KIRO_AGENTIC_SYSTEM_PROMPT = `
+# CRITICAL: CHUNKED WRITE PROTOCOL (MANDATORY)
+
+You MUST follow these rules for ALL file operations. Violation causes server timeouts and task failure.
+
+## ABSOLUTE LIMITS
+- **MAXIMUM 350 LINES** per single write/edit operation - NO EXCEPTIONS
+- **RECOMMENDED 300 LINES** or less for optimal performance
+- **NEVER** write entire files in one operation if >300 lines
+
+## MANDATORY CHUNKED WRITE STRATEGY
+
+### For NEW FILES (>300 lines total):
+1. FIRST: Write initial chunk (first 250-300 lines) using write_to_file/fsWrite
+2. THEN: Append remaining content in 250-300 line chunks using file append operations
+3. REPEAT: Continue appending until complete
+
+### For EDITING EXISTING FILES:
+1. Use surgical edits (apply_diff/targeted edits) - change ONLY what's needed
+2. NEVER rewrite entire files - use incremental modifications
+3. Split large refactors into multiple small, focused edits
+
+### For LARGE CODE GENERATION:
+1. Generate in logical sections (imports, types, functions separately)
+2. Write each section as a separate operation
+3. Use append operations for subsequent sections
+
+## EXAMPLES OF CORRECT BEHAVIOR
+
+CORRECT: Writing a 600-line file
+- Operation 1: Write lines 1-300 (initial file creation)
+- Operation 2: Append lines 301-600
+
+CORRECT: Editing multiple functions
+- Operation 1: Edit function A
+- Operation 2: Edit function B
+- Operation 3: Edit function C
+
+WRONG: Writing 500 lines in single operation -> TIMEOUT
+WRONG: Rewriting entire file to change 5 lines -> TIMEOUT
+WRONG: Generating massive code blocks without chunking -> TIMEOUT
+
+## WHY THIS MATTERS
+- Server has 2-3 minute timeout for operations
+- Large writes exceed timeout and FAIL completely
+- Chunked writes are FASTER and more RELIABLE
+- Failed writes waste time and require retry
+
+REMEMBER: When in doubt, write LESS per operation. Multiple small operations > one large operation.
+`.trim();
+
+/**
+ * Resolve the Kiro thinking budget requested by a client.
+ *
+ * Reuses the shared thinkingUnified parser (extractThinking) so every client
+ * shape (Claude output_config.effort / thinking.budget_tokens, OpenAI
+ * reasoning_effort / reasoning.effort, Gemini, Qwen) maps consistently. Explicit
+ * `none`/`off`/disabled wins and returns null (no prefix injected).
+ * buildThinkingSystemPrefix performs Kiro's final 1..32000 clamp.
+ *
+ * @param {object} body OpenAI/Claude-shaped request body
+ * @param {object} [headers] Original inbound HTTP headers (case-insensitive)
+ * @param {string} [model] Model id the caller asked for
+ * @returns {number|null} budget to inject, or null when thinking is disabled
+ */
+export function resolveKiroThinkingBudget(body, headers, model) {
+  const cfg = extractThinking(body);
+  if (cfg) {
+    if (cfg.mode === "none") return null;
+    if (cfg.mode === "budget") return cfg.budget;
+    if (cfg.mode === "level") return effortToBudget(cfg.level) ?? KIRO_THINKING_BUDGET_DEFAULT;
+    return KIRO_THINKING_BUDGET_DEFAULT;
+  }
+
+  if (headers) {
+    const beta = pickHeader(headers, "anthropic-beta");
+    if (typeof beta === "string" && beta.toLowerCase().includes("interleaved-thinking")) {
+      return KIRO_THINKING_BUDGET_DEFAULT;
+    }
+  }
+
+  if (containsThinkingModeTag(body)) return KIRO_THINKING_BUDGET_DEFAULT;
+
+  if (typeof model === "string" && model) {
+    const m = model.toLowerCase();
+    if (m.includes("thinking") || m.includes("-reason")) return KIRO_THINKING_BUDGET_DEFAULT;
+  }
+
+  return null;
+}
+
+/**
+ * Detect whether an inbound request is asking for reasoning / thinking output.
+ * Thin wrapper over resolveKiroThinkingBudget (single source of truth).
+ *
+ * @param {object} body OpenAI-shaped request body (post-translation)
+ * @param {object} [headers] Original inbound HTTP headers (case-insensitive)
+ * @param {string} [model] Model id the caller asked for (post-strip ok)
+ * @returns {boolean}
+ */
+export function isThinkingEnabled(body, headers, model) {
+  return resolveKiroThinkingBudget(body, headers, model) !== null;
+}
+
+/**
+ * Detect whether a model id refers to a 9router synthetic agentic variant.
+ * Agentic variants share the same upstream model as the base; the only
+ * difference is the chunked-write system prompt this module injects.
+ *
+ * @param {string} model
+ * @returns {boolean}
+ */
+export function isAgenticModel(model) {
+  return typeof model === "string" && model.endsWith(KIRO_AGENTIC_SUFFIX);
+}
+
+/**
+ * Strip the `-agentic` suffix from a model id, leaving the upstream-real id.
+ *
+ * @param {string} model
+ * @returns {string}
+ */
+export function stripAgenticSuffix(model) {
+  if (!isAgenticModel(model)) return model;
+  return model.slice(0, -KIRO_AGENTIC_SUFFIX.length);
+}
+
+/**
+ * Detect whether a model id is a 9router synthetic thinking variant
+ * (e.g. `claude-sonnet-4.5-thinking`). Same upstream model as the base; the
+ * only difference is `<thinking_mode>enabled</thinking_mode>` injection.
+ *
+ * Note: real Kiro thinking-capable variants exist (e.g. `kimi-k2-thinking` in
+ * other providers), but for the `kr/` namespace there is no `-thinking`
+ * model on Kiro upstream. Treat the suffix as a synthetic alias.
+ *
+ * @param {string} model Model id with `-agentic` already stripped
+ * @returns {boolean}
+ */
+export function isThinkingModel(model) {
+  return typeof model === "string" && model.endsWith(KIRO_THINKING_SUFFIX);
+}
+
+/**
+ * Strip the `-thinking` suffix from a model id.
+ *
+ * @param {string} model
+ * @returns {string}
+ */
+export function stripThinkingSuffix(model) {
+  if (!isThinkingModel(model)) return model;
+  return model.slice(0, -KIRO_THINKING_SUFFIX.length);
+}
+
+/**
+ * Resolve a 9router model id to the real upstream Kiro model id, plus flags
+ * describing which behaviours the suffixes implied.
+ *
+ *   resolveKiroModel("claude-sonnet-4.5-thinking-agentic")
+ *     => { upstream: "claude-sonnet-4.5", agentic: true, thinking: true }
+ *   resolveKiroModel("claude-sonnet-4.5-thinking")
+ *     => { upstream: "claude-sonnet-4.5", agentic: false, thinking: true }
+ *   resolveKiroModel("claude-sonnet-4.5-agentic")
+ *     => { upstream: "claude-sonnet-4.5", agentic: true, thinking: false }
+ *   resolveKiroModel("claude-sonnet-4.5")
+ *     => { upstream: "claude-sonnet-4.5", agentic: false, thinking: false }
+ *
+ * @param {string} model
+ * @returns {{ upstream: string, agentic: boolean, thinking: boolean }}
+ */
+export function resolveKiroModel(model) {
+  let upstream = model;
+  let agentic = false;
+  let thinking = false;
+  if (isAgenticModel(upstream)) {
+    agentic = true;
+    upstream = stripAgenticSuffix(upstream);
+  }
+  if (isThinkingModel(upstream)) {
+    thinking = true;
+    upstream = stripThinkingSuffix(upstream);
+  }
+  return { upstream, agentic, thinking };
+}
+
+/**
+ * Build the magic system-prompt prefix that turns Kiro reasoning on.
+ * Same shape as CLIProxyAPIPlus.
+ *
+ * @param {number} [budget=KIRO_THINKING_BUDGET_DEFAULT]
+ */
+export function buildThinkingSystemPrefix(budget = KIRO_THINKING_BUDGET_DEFAULT) {
+  const safeBudget = Math.max(1, Math.min(32000, Number(budget) || KIRO_THINKING_BUDGET_DEFAULT));
+  return `<thinking_mode>enabled</thinking_mode>\n<max_thinking_length>${safeBudget}</max_thinking_length>`;
+}
+
+function pickHeader(headers, name) {
+  if (!headers) return undefined;
+  if (typeof headers.get === "function") {
+    return headers.get(name);
+  }
+  const lower = name.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === lower) {
+      return headers[key];
+    }
+  }
+  return undefined;
+}
+
+function containsThinkingModeTag(body) {
+  const messages = Array.isArray(body?.messages) ? body.messages : [];
+  for (const msg of messages) {
+    if (!msg) continue;
+    if (msg.role !== "system" && msg.role !== "user") continue;
+    const content = msg.content;
+    if (typeof content === "string") {
+      if (containsTagInText(content)) return true;
+    } else if (Array.isArray(content)) {
+      for (const part of content) {
+        const text = part?.text;
+        if (typeof text === "string" && containsTagInText(text)) return true;
+      }
+    }
+  }
+  if (typeof body?.system === "string" && containsTagInText(body.system)) return true;
+  return false;
+}
+
+function containsTagInText(text) {
+  if (!text) return false;
+  if (!text.includes("<thinking_mode>")) return false;
+  return text.includes("<thinking_mode>enabled</thinking_mode>")
+    || text.includes("<thinking_mode>interleaved</thinking_mode>");
+}
diff --git a/open-sse/config/mediaConfig.js b/open-sse/config/mediaConfig.js
new file mode 100644
index 0000000..5b8fbb2
--- /dev/null
+++ b/open-sse/config/mediaConfig.js
@@ -0,0 +1,27 @@
+// Central config for remote-media fetching security limits.
+
+// Max bytes accepted from a remote image fetch (reject larger to prevent memory DoS).
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024; // 10MB
+
+// Fetch timeout for remote media.
+export const FETCH_TIMEOUT_MS = 10000;
+
+// Magic-byte signatures -> mime. Each entry: { sig:[bytes], offset, mime }.
+// offset>0 for containers where the signature is not at byte 0 (e.g. webp).
+export const IMAGE_SIGNATURES = [
+  { sig: [0x89, 0x50, 0x4e, 0x47], offset: 0, mime: "image/png" },
+  { sig: [0xff, 0xd8, 0xff], offset: 0, mime: "image/jpeg" },
+  { sig: [0x47, 0x49, 0x46, 0x38], offset: 0, mime: "image/gif" },
+  { sig: [0x52, 0x49, 0x46, 0x46], offset: 0, mime: "image/webp", verifyWebp: true },
+  { sig: [0x42, 0x4d], offset: 0, mime: "image/bmp" },
+];
+
+// Hostnames/IPs that must never be fetched (SSRF guard for loopback + cloud metadata).
+export const BLOCKED_HOSTS = new Set([
+  "localhost",
+  "127.0.0.1",
+  "0.0.0.0",
+  "::1",
+  "169.254.169.254", // AWS/GCP/Azure IMDS
+  "metadata.google.internal",
+]);
diff --git a/open-sse/config/models.js b/open-sse/config/models.js
new file mode 100644
index 0000000..a1917cd
--- /dev/null
+++ b/open-sse/config/models.js
@@ -0,0 +1,13 @@
+// Model metadata registry
+// Only define models that differ from DEFAULT_MODEL_INFO
+// Custom entries are merged over default
+const DEFAULT_MODEL_INFO = {
+  type: ["chat"],
+  contextWindow: 200000,
+};
+
+export const MODEL_INFO = {};
+
+export function getModelInfo(modelId) {
+  return { ...DEFAULT_MODEL_INFO, ...MODEL_INFO[modelId] };
+}
diff --git a/open-sse/config/ollamaModels.js b/open-sse/config/ollamaModels.js
new file mode 100644
index 0000000..2c04b4f
--- /dev/null
+++ b/open-sse/config/ollamaModels.js
@@ -0,0 +1,19 @@
+export const ollamaModels = {
+  models: [
+    {
+      name: "llama3.2",
+      modified_at: "2025-12-26T00:00:00Z",
+      size: 2000000000,
+      digest: "abc123def456",
+      details: { format: "gguf", family: "llama", parameter_size: "3B", quantization_level: "Q4_K_M" }
+    },
+    {
+      name: "qwen2.5",
+      modified_at: "2025-12-26T00:00:00Z",
+      size: 4000000000,
+      digest: "def456abc123",
+      details: { format: "gguf", family: "qwen", parameter_size: "7B", quantization_level: "Q4_K_M" }
+    }
+  ]
+};
+
diff --git a/open-sse/config/providerModels.js b/open-sse/config/providerModels.js
new file mode 100644
index 0000000..108806e
--- /dev/null
+++ b/open-sse/config/providerModels.js
@@ -0,0 +1,106 @@
+import { PROVIDERS } from "./providers.js";
+import REGISTRY from "../providers/registry/index.js";
+// PROVIDER_MODELS now built from providers/registry (transport + models co-located)
+import { PROVIDER_MODELS } from "../providers/index.js";
+import { modelQuotaFamily, modelStrip, modelTargetFormat, normalizeModelId } from "../providers/models/schema.js";
+import { CODEX_REVIEW_SUFFIX } from "../providers/models/helpers.js";
+
+export { PROVIDER_MODELS };
+
+
+// Helper functions
+export function getProviderModels(aliasOrId) {
+  return PROVIDER_MODELS[aliasOrId] || [];
+}
+
+export function getDefaultModel(aliasOrId) {
+  const models = PROVIDER_MODELS[aliasOrId];
+  return models?.[0]?.id || null;
+}
+
+// Providers whose registry uses dots in version numbers (e.g. "claude-sonnet-4.5").
+// For these, we tolerate clients sending dashes ("claude-sonnet-4-5") by normalizing
+// digit-hyphen-digit to digit-dot-digit before lookup. Other providers are left untouched.
+const DOT_VERSION_PROVIDERS = new Set(["kr", "kiro"]);
+
+// Find a registry entry by id. For Kiro models, tolerates dash/dot version separators
+// ("claude-sonnet-4-5" ~= "claude-sonnet-4.5"). Other providers use exact match only.
+function findModel(models, modelId, aliasOrId) {
+  if (!models) return undefined;
+  const found = models.find(m => m.id === modelId);
+  if (found) return found;
+  if (!DOT_VERSION_PROVIDERS.has(aliasOrId)) return undefined;
+  const normalized = normalizeModelId(modelId);
+  if (normalized === modelId) return undefined;
+  return models.find(m => m.id === normalized);
+}
+
+export function isValidModel(aliasOrId, modelId, passthroughProviders = new Set()) {
+  if (passthroughProviders.has(aliasOrId)) return true;
+  const models = PROVIDER_MODELS[aliasOrId];
+  if (!models) return false;
+  return !!findModel(models, modelId, aliasOrId);
+}
+
+export function findModelName(aliasOrId, modelId) {
+  const models = PROVIDER_MODELS[aliasOrId];
+  if (!models) return modelId;
+  const found = findModel(models, modelId, aliasOrId);
+  return found?.name || modelId;
+}
+
+export function getModelTargetFormat(aliasOrId, modelId) {
+  const models = PROVIDER_MODELS[aliasOrId];
+  if (!models) return null;
+  return modelTargetFormat(findModel(models, modelId, aliasOrId));
+}
+
+export function getModelType(aliasOrId, modelId) {
+  const models = PROVIDER_MODELS[aliasOrId];
+  if (!models) return null;
+  const found = findModel(models, modelId, aliasOrId);
+  return found?.kind || found?.type || null;
+}
+
+export function getModelUpstreamId(aliasOrId, modelId) {
+  // Split off thinking suffix "(level)" so lookup hits the base id; re-append it to
+  // the result so downstream applyThinking still sees the suffix (body.model is stripped separately).
+  const sufMatch = typeof modelId === "string" ? modelId.match(/\([^()]+\)\s*$/) : null;
+  const suffix = sufMatch ? sufMatch[0] : "";
+  const baseId = suffix ? modelId.slice(0, sufMatch.index).trim() : modelId;
+  const models = PROVIDER_MODELS[aliasOrId];
+  const found = findModel(models, baseId, aliasOrId);
+  if (found?.upstreamModelId) return found.upstreamModelId + suffix;
+  if (found?.id) return found.id + suffix;
+  if (aliasOrId === "cx" && typeof baseId === "string" && baseId.endsWith(CODEX_REVIEW_SUFFIX)) {
+    return baseId.slice(0, -CODEX_REVIEW_SUFFIX.length) + suffix;
+  }
+  return baseId + suffix;
+}
+
+export function getModelQuotaFamily(aliasOrId, modelId) {
+  const models = PROVIDER_MODELS[aliasOrId];
+  return modelQuotaFamily(findModel(models, modelId, aliasOrId));
+}
+
+// OAuth short aliases — derived from registry `alias` (single source). everything else: alias = id.
+// vertex/vertex-partner keep alias=id (kept via the `|| id` fallback in consumers).
+export const OAUTH_ALIASES = Object.fromEntries(
+  REGISTRY.filter(r => r.alias && r.alias !== r.id).map(r => [r.id, r.alias])
+);
+
+// Derived from PROVIDERS — no need to maintain manually
+export const PROVIDER_ID_TO_ALIAS = Object.fromEntries(
+  Object.keys(PROVIDERS).map(id => [id, OAUTH_ALIASES[id] || id])
+);
+
+export function getModelsByProviderId(providerId) {
+  const alias = PROVIDER_ID_TO_ALIAS[providerId] || providerId;
+  return PROVIDER_MODELS[alias] || [];
+}
+
+// Get strip list for a model entry (explicit opt-in only)
+// Returns array of content types to strip, e.g. ["image", "audio"]
+export function getModelStrip(alias, modelId) {
+  return modelStrip(findModel(PROVIDER_MODELS[alias], modelId, alias));
+}
diff --git a/open-sse/config/providers.js b/open-sse/config/providers.js
new file mode 100644
index 0000000..f24ab96
--- /dev/null
+++ b/open-sse/config/providers.js
@@ -0,0 +1,19 @@
+// Barrel: PROVIDERS now built from providers/registry (transport co-located with models)
+import { PROVIDERS } from "../providers/index.js";
+export { PROVIDERS, PROVIDER_OAUTH } from "../providers/index.js";
+
+export const OLLAMA_LOCAL_DEFAULT_HOST = "http://localhost:11434";
+
+export function resolveOllamaLocalHost(credentials) {
+  const raw = credentials?.providerSpecificData?.baseUrl?.trim();
+  return (raw || OLLAMA_LOCAL_DEFAULT_HOST).replace(/\/$/, "");
+}
+
+// Region URLs single-source from registry xiaomi-tokenplan.transport
+export const XIAOMI_TOKENPLAN_REGIONS = PROVIDERS["xiaomi-tokenplan"]?.regions || {};
+export const XIAOMI_TOKENPLAN_DEFAULT_REGION = PROVIDERS["xiaomi-tokenplan"]?.defaultRegion;
+
+export function resolveXiaomiTokenplanBaseUrl(credentials) {
+  const region = credentials?.providerSpecificData?.region;
+  return XIAOMI_TOKENPLAN_REGIONS[region] || XIAOMI_TOKENPLAN_REGIONS[XIAOMI_TOKENPLAN_DEFAULT_REGION];
+}
diff --git a/open-sse/config/runtimeConfig.js b/open-sse/config/runtimeConfig.js
new file mode 100644
index 0000000..5cd5ba7
--- /dev/null
+++ b/open-sse/config/runtimeConfig.js
@@ -0,0 +1,96 @@
+// HTTP status codes
+export const HTTP_STATUS = {
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  PAYMENT_REQUIRED: 402,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  NOT_ACCEPTABLE: 406,
+  REQUEST_TIMEOUT: 408,
+  RATE_LIMITED: 429,
+  SERVER_ERROR: 500,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_TIMEOUT: 504
+};
+
+// Re-export error config (backward compat)
+export { ERROR_TYPES, DEFAULT_ERROR_MESSAGES, BACKOFF_CONFIG, COOLDOWN_MS } from "./errorConfig.js";
+
+// Cache TTLs (seconds)
+export const CACHE_TTL = {
+  userInfo: 300,    // 5 minutes
+  modelAlias: 3600  // 1 hour
+};
+
+// Memory management config
+export const MEMORY_CONFIG = {
+  sessionTtlMs: 2 * 60 * 60 * 1000,
+  sessionCleanupIntervalMs: 30 * 60 * 1000,
+  dnsCacheTtlMs: 5 * 60 * 1000,
+  proxyDispatchersMaxSize: 20,
+};
+
+// Parse a positive integer env override, falling back to a default.
+function envMs(name, def) {
+  const raw = process.env[name];
+  if (raw == null || raw === "") return def;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : def;
+}
+
+function envUrl(name, def) {
+  const raw = process.env[name]?.trim();
+  return raw || def;
+}
+
+// SearXNG endpoint used by the unauthenticated web-search provider.
+// Configure this for a separate Docker service or remote SearXNG instance.
+export const SEARXNG_URL = envUrl("SEARXNG_URL", "http://localhost:8888/search");
+
+// Inter-chunk stall timeout (once tokens are flowing). Generous headroom so
+// slow reasoning models aren't aborted mid-stream. Env: STREAM_STALL_TIMEOUT_MS.
+export const STREAM_STALL_TIMEOUT_MS = envMs("STREAM_STALL_TIMEOUT_MS", 360 * 1000);
+
+// Time-to-first-token timeout (prompt prefill). Env: STREAM_FIRST_CHUNK_TIMEOUT_MS.
+export const STREAM_FIRST_CHUNK_TIMEOUT_MS = envMs("STREAM_FIRST_CHUNK_TIMEOUT_MS", 200 * 1000);
+
+// Fetch connect timeout: abort if upstream doesn't return response headers within this duration
+export const FETCH_CONNECT_TIMEOUT_MS = envMs("FETCH_CONNECT_TIMEOUT_MS", 60 * 1000);
+
+// Gemini native TTS fetch timeout: abort if Google does not return response headers in time.
+export const GEMINI_NATIVE_TTS_FETCH_TIMEOUT_MS = envMs("GEMINI_NATIVE_TTS_FETCH_TIMEOUT_MS", 45 * 1000);
+
+// Default token limits
+export const DEFAULT_MAX_TOKENS = 64000;
+export const DEFAULT_MIN_TOKENS = 32000;
+
+// Retry config for 429 responses (legacy - kept for backward compatibility)
+export const RETRY_CONFIG = {
+  maxAttempts: 2,
+  delayMs: 2000
+};
+
+// Default retry config by status code: { attempts, delayMs }
+// Backward compat: if value is a number, treated as attempts with RETRY_CONFIG.delayMs
+export const DEFAULT_RETRY_CONFIG = {
+  429: { attempts: 0, delayMs: 0 },
+  502: { attempts: 3, delayMs: 3000 },
+  503: { attempts: 3, delayMs: 2000 },
+  504: { attempts: 2, delayMs: 3000 }
+};
+
+// Normalize a retry entry to { attempts, delayMs }
+export function resolveRetryEntry(entry) {
+  if (entry == null) return { attempts: 0, delayMs: RETRY_CONFIG.delayMs };
+  if (typeof entry === "number") return { attempts: entry, delayMs: RETRY_CONFIG.delayMs };
+  return {
+    attempts: entry.attempts || 0,
+    delayMs: entry.delayMs != null ? entry.delayMs : RETRY_CONFIG.delayMs
+  };
+}
+
+// Requests containing these texts will bypass provider
+export const SKIP_PATTERNS = [
+  "Please write a 5-10 word title for the following conversation:"
+];
diff --git a/open-sse/config/ttsModels.js b/open-sse/config/ttsModels.js
new file mode 100644
index 0000000..6925f5f
--- /dev/null
+++ b/open-sse/config/ttsModels.js
@@ -0,0 +1,131 @@
+import { GOOGLE_TTS_LANGUAGES } from "./googleTtsLanguages.js";
+
+// ── Voice definitions (DRY — reused across providers) ──────────────────────
+const VOICES = {
+  alloy:   { id: "alloy",   name: "Alloy" },
+  ash:     { id: "ash",     name: "Ash" },
+  ballad:  { id: "ballad",  name: "Ballad" },
+  cedar:   { id: "cedar",   name: "Cedar" },
+  coral:   { id: "coral",   name: "Coral" },
+  echo:    { id: "echo",    name: "Echo" },
+  fable:   { id: "fable",   name: "Fable" },
+  marin:   { id: "marin",   name: "Marin" },
+  nova:    { id: "nova",    name: "Nova" },
+  onyx:    { id: "onyx",    name: "Onyx" },
+  sage:    { id: "sage",    name: "Sage" },
+  shimmer: { id: "shimmer", name: "Shimmer" },
+  verse:   { id: "verse",   name: "Verse" },
+};
+
+const v = (...keys) => keys.map((k) => ({ ...VOICES[k], type: "tts" }));
+
+// 9 voices for tts-1 / tts-1-hd
+const VOICES_STANDARD = v("alloy", "ash", "coral", "echo", "fable", "nova", "onyx", "sage", "shimmer");
+// 13 voices for gpt-4o-mini-tts
+const VOICES_FULL = v("alloy", "ash", "ballad", "cedar", "coral", "echo", "fable", "marin", "nova", "onyx", "sage", "shimmer", "verse");
+
+// Gemini prebuilt voices (30 voices, multi-language auto-detect)
+const GEMINI_VOICES = [
+  "Zephyr", "Puck", "Charon", "Kore", "Fenrir", "Leda", "Orus", "Aoede",
+  "Callirrhoe", "Autonoe", "Enceladus", "Iapetus", "Umbriel", "Algieba",
+  "Despina", "Erinome", "Algenib", "Rasalgethi", "Laomedeia", "Achernar",
+  "Alnilam", "Schedar", "Gacrux", "Pulcherrima", "Achird", "Zubenelgenubi",
+  "Vindemiatrix", "Sadachbia", "Sadaltager", "Sulafat",
+].map((id) => ({ id, name: id, type: "tts" }));
+
+// ── TTS Config (config-driven, single source of truth) ─────────────────────
+export const TTS_MODELS_CONFIG = {
+  openai: {
+    models: [
+      { id: "gpt-4o-mini-tts", name: "GPT-4o Mini TTS", type: "tts" },
+      { id: "tts-1-hd",        name: "TTS-1 HD",        type: "tts" },
+      { id: "tts-1",           name: "TTS-1",           type: "tts" },
+    ],
+    voices: {
+      "gpt-4o-mini-tts": VOICES_FULL,
+      "tts-1":           VOICES_STANDARD,
+      "tts-1-hd":        VOICES_STANDARD,
+    },
+    // Flat voice list (all unique voices) for backward compat
+    allVoices: VOICES_FULL,
+  },
+  openrouter: {
+    models: [
+      { id: "openai/gpt-4o-mini-tts", name: "GPT-4o Mini TTS", type: "tts" },
+      { id: "openai/tts-1-hd",        name: "TTS-1 HD",        type: "tts" },
+      { id: "openai/tts-1",           name: "TTS-1",           type: "tts" },
+    ],
+    voices: {
+      "openai/gpt-4o-mini-tts": VOICES_FULL,
+      "openai/tts-1":           VOICES_STANDARD,
+      "openai/tts-1-hd":        VOICES_STANDARD,
+    },
+    allVoices: VOICES_FULL,
+  },
+  elevenlabs: {
+    models: [
+      { id: "eleven_flash_v2_5",      name: "Flash v2.5 (Fastest)",      type: "tts" },
+      { id: "eleven_turbo_v2_5",      name: "Turbo v2.5 (Fast)",         type: "tts" },
+      { id: "eleven_multilingual_v2", name: "Multilingual v2 (Quality)",  type: "tts" },
+      { id: "eleven_monolingual_v1",  name: "Monolingual v1 (English)",  type: "tts" },
+    ],
+    // voices come from API, not hardcoded
+  },
+  "edge-tts": {
+    defaults: [
+      { id: "en-US-AriaNeural",    name: "Aria (en-US)",    type: "tts" },
+      { id: "en-US-GuyNeural",     name: "Guy (en-US)",     type: "tts" },
+      { id: "en-GB-SoniaNeural",   name: "Sonia (en-GB)",   type: "tts" },
+      { id: "vi-VN-HoaiMyNeural",  name: "Hoai My (vi-VN)", type: "tts" },
+      { id: "vi-VN-NamMinhNeural", name: "Nam Minh (vi-VN)", type: "tts" },
+      { id: "zh-CN-XiaoxiaoNeural", name: "Xiaoxiao (zh-CN)", type: "tts" },
+      { id: "zh-CN-YunxiNeural",   name: "Yunxi (zh-CN)",   type: "tts" },
+      { id: "fr-FR-DeniseNeural",  name: "Denise (fr-FR)",  type: "tts" },
+      { id: "de-DE-KatjaNeural",   name: "Katja (de-DE)",   type: "tts" },
+      { id: "ja-JP-NanamiNeural",  name: "Nanami (ja-JP)",  type: "tts" },
+      { id: "ko-KR-SunHiNeural",   name: "SunHi (ko-KR)",   type: "tts" },
+    ],
+  },
+  "local-device": {
+    defaults: [
+      { id: "default", name: "System Default Voice", type: "tts" },
+    ],
+  },
+  "google-tts": {
+    defaults: GOOGLE_TTS_LANGUAGES,
+  },
+  gemini: {
+    models: [
+      { id: "gemini-3.1-flash-tts-preview", name: "Gemini 3.1 Flash TTS", type: "tts" },
+      { id: "gemini-2.5-flash-preview-tts", name: "Gemini 2.5 Flash TTS", type: "tts" },
+      { id: "gemini-2.5-pro-preview-tts",   name: "Gemini 2.5 Pro TTS",   type: "tts" },
+    ],
+    voices: {
+      "gemini-3.1-flash-tts-preview": GEMINI_VOICES,
+      "gemini-2.5-flash-preview-tts": GEMINI_VOICES,
+      "gemini-2.5-pro-preview-tts":   GEMINI_VOICES,
+    },
+    allVoices: GEMINI_VOICES,
+  },
+};
+
+// ── Helper: get voices for a specific model ────────────────────────────────
+export function getTtsVoicesForModel(provider, modelId) {
+  const cfg = TTS_MODELS_CONFIG[provider];
+  if (!cfg?.voices) return null;
+  return cfg.voices[modelId] || cfg.allVoices || null;
+}
+
+// ── Build flat entries for PROVIDER_MODELS backward compat ─────────────────
+export function buildTtsProviderModels() {
+  const entries = {};
+  for (const [provider, cfg] of Object.entries(TTS_MODELS_CONFIG)) {
+    if (cfg.models) entries[`${provider}-tts-models`] = cfg.models;
+    if (cfg.allVoices) entries[`${provider}-tts-voices`] = cfg.allVoices;
+    if (cfg.defaults) entries[provider] = cfg.defaults;
+  }
+  // Keep openai-tts-voices key pointing to full voice list for backward compat
+  entries["openai-tts-voices"] = TTS_MODELS_CONFIG.openai.allVoices;
+  entries["openrouter-tts-voices"] = TTS_MODELS_CONFIG.openrouter.allVoices;
+  return entries;
+}
diff --git a/open-sse/executors/antigravity.js b/open-sse/executors/antigravity.js
new file mode 100644
index 0000000..f669e3a
--- /dev/null
+++ b/open-sse/executors/antigravity.js
@@ -0,0 +1,620 @@
+import crypto from "crypto";
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { OAUTH_ENDPOINTS, ANTIGRAVITY_HEADERS, AG_DEFAULT_TOOLS, AG_TOOL_SUFFIX } from "../config/appConstants.js";
+import { HTTP_STATUS } from "../config/runtimeConfig.js";
+import { resolveSessionId } from "../utils/sessionManager.js";
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+import { cleanJSONSchemaForAntigravity } from "../translator/formats/gemini.js";
+import { DEFAULT_THINKING_AG_SIGNATURE } from "../config/defaultThinkingSignature.js";
+
+// Sanitize function name: Gemini requires [a-zA-Z_][a-zA-Z0-9_.:\-]{0,63}
+function sanitizeFunctionName(name) {
+  if (!name) return "_unknown";
+  let s = name.replace(/[^a-zA-Z0-9_.:\-]/g, "_");
+  if (!/^[a-zA-Z_]/.test(s)) s = "_" + s;
+  return s.substring(0, 64);
+}
+
+const MAX_RETRY_AFTER_MS = 10000;
+const ANTIGRAVITY_TRANSIENT_RETRY_MAX_MS = 15000;
+const MAX_ANTIGRAVITY_OUTPUT_TOKENS = 64000;
+const ANTIGRAVITY_IDE_REQUEST_ID_RE = /^agent\/[^/]+\/\d+\/[^/]+\/\d+$/;
+
+const ANTIGRAVITY_TRANSIENT_ERROR_PATTERNS = [
+  /high\s+traffic/i,
+  /agent\s+(execution\s+)?terminated\s+due\s+to\s+error/i,
+  /capacity/i,
+  /temporarily\s+unavailable/i,
+  /timeout/i,
+  /stream\s+(ended|closed|terminated|interrupted)/i,
+  /empty\s+response/i,
+];
+
+const ANTIGRAVITY_TRANSIENT_STATUSES = new Set([
+  HTTP_STATUS.SERVER_ERROR,
+  HTTP_STATUS.BAD_GATEWAY,
+  HTTP_STATUS.SERVICE_UNAVAILABLE,
+  HTTP_STATUS.GATEWAY_TIMEOUT,
+]);
+
+// Fields Google generateContent rejects (Claude/OpenAI/Qwen thinking fields set at body root by thinkingUnified.js)
+const ANTIGRAVITY_REQUEST_BLACKLIST = [
+  "output_config",
+  "thinking",
+  "reasoning_effort",
+  "reasoning",
+  "enable_thinking",
+  "thinking_budget",
+  "thinkingConfig",
+];
+
+// Strip blacklisted fields from an object (used for both body.request and top-level body)
+const stripBlacklisted = obj => {
+  for (const key of ANTIGRAVITY_REQUEST_BLACKLIST) delete obj[key];
+};
+
+// Image generation model name patterns
+const IMAGE_MODEL_PATTERNS = [
+  /image/i,
+  /imagen/i,
+  /image-generation/i,
+];
+
+// Detect if a model is an image generation model
+function isImageModel(model) {
+  if (!model) return false;
+  return IMAGE_MODEL_PATTERNS.some(p => p.test(model));
+}
+
+// Parse aspect ratio / resolution from model name suffixes
+// e.g. "gemini-3.1-flash-image-16x9" -> { aspectRatio: "16:9" }
+// e.g. "gemini-3.1-flash-image-1024x768" -> { aspectRatio: "4:3" }
+function parseImageConfig(model) {
+  const config = { aspectRatio: "1:1" };
+  const resMatch = model.match(/(\d+)x(\d+)$/);
+  if (resMatch) {
+    const w = parseInt(resMatch[1]);
+    const h = parseInt(resMatch[2]);
+    if (w <= 16 && h <= 16) {
+      config.aspectRatio = `${w}:${h}`;
+    } else {
+      // Resolution like 1024x768 — derive aspect ratio
+      const gcd = (a, b) => b ? gcd(b, a % b) : a;
+      const d = gcd(w, h);
+      config.aspectRatio = `${w/d}:${h/d}`;
+    }
+  }
+  return config;
+}
+
+function uuidFromSeed(seed) {
+  const bytes = crypto.createHash("sha256").update(String(seed || "antigravity")).digest().subarray(0, 16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x50;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function buildIdeRequestId({ body, request, credentials, model, requestType }) {
+  if (ANTIGRAVITY_IDE_REQUEST_ID_RE.test(body?.requestId || "")) {
+    return body.requestId;
+  }
+
+  const sessionId = request?.sessionId || body?.request?.sessionId || credentials?._clientSessionId || credentials?.connectionId || credentials?.email || "anonymous";
+  const conversationId = uuidFromSeed(`antigravity:conversation:${sessionId}`);
+  const trajectoryId = uuidFromSeed(`antigravity:trajectory:${sessionId}:${model}:${requestType}`);
+  const contentCount = Array.isArray(request?.contents) ? request.contents.length : 1;
+  const step = Math.max(1, contentCount * 2 - 1);
+  return `agent/${conversationId}/${Date.now()}/${trajectoryId}/${step}`;
+}
+
+export class AntigravityExecutor extends BaseExecutor {
+  constructor() {
+    super("antigravity", PROVIDERS.antigravity);
+  }
+
+  buildUrl(model, stream, urlIndex = 0) {
+    const baseUrls = this.getBaseUrls();
+    const baseUrl = baseUrls[urlIndex] || baseUrls[0];
+    // Image generation MUST use non-streaming generateContent
+    const forceNonStream = isImageModel(model);
+    const action = (stream && !forceNonStream) ? "streamGenerateContent?alt=sse" : "generateContent";
+    return `${baseUrl}/v1internal:${action}`;
+  }
+
+  // sessionId comes from transformRequest output; base.execute runs transformRequest before
+  // buildHeaders, so we read it from instance state cached there (fallback: explicit arg).
+  buildHeaders(credentials, stream = true, sessionId = null) {
+    return {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${credentials.accessToken}`,
+      "User-Agent": this.config.headers?.["User-Agent"] || ANTIGRAVITY_HEADERS["User-Agent"],
+    };
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    const projectId = credentials?.projectId || this.generateProjectId();
+
+    // ─── Image generation: completely different request structure ───
+    if (isImageModel(model)) {
+      const imageConfig = parseImageConfig(model);
+      // Strip model name suffixes for the actual API model name
+      const cleanModel = model.replace(/-(\d+)x(\d+)$/, "");
+
+      // Build simplified contents — text-only, merge all user messages
+      const contents = [];
+      const srcContents = body.request?.contents || body.contents || [];
+      for (const c of srcContents) {
+        const textParts = (c.parts || []).filter(p => p.text !== undefined).map(p => ({ text: p.text }));
+        if (textParts.length > 0) {
+          contents.push({ role: c.role || "user", parts: textParts });
+        }
+      }
+
+      const sessionId = resolveSessionId({
+        headers: credentials?.rawHeaders,
+        body,
+        connectionId: credentials?.email || credentials?.connectionId,
+        scope: "antigravity",
+      });
+
+      this._lastSessionId = sessionId;
+      const request = {
+        contents,
+        generationConfig: {
+          temperature: 1.0,
+          topP: 0.95,
+          topK: 40,
+          maxOutputTokens: 8192,
+          imageConfig,
+        },
+        sessionId,
+        // No tools, no systemInstruction, no safetySettings for image gen
+      };
+
+      return {
+        project: projectId,
+        model: cleanModel,
+        userAgent: "antigravity",
+        requestType: "image_gen",
+        requestId: buildIdeRequestId({ body, request, credentials, model: cleanModel, requestType: "image_gen" }),
+        request,
+      };
+    }
+
+    // ─── Standard (non-image) request ───
+    // Fix contents for Claude models via Antigravity
+    const contents = body.request?.contents?.map(c => {
+      let role = c.role;
+      // functionResponse must be role "user" for Claude models
+      if (c.parts?.some(p => p.functionResponse)) {
+        role = "user";
+      }
+      // Strip thought-only parts, keep thoughtSignature on functionCall parts (Gemini 3+ requires it)
+      const parts = c.parts?.filter(p => {
+        if (p.thought && !p.functionCall) return false;
+        if (p.thoughtSignature && !p.functionCall && !p.text) return false;
+        return true;
+      });
+      // Gemini 3+ rejects functionCall parts without thoughtSignature. Clients (Claude Code, IDE)
+      // don't persist thoughtSignature in their history, so backfill the default signature on any
+      // functionCall part that arrives without one.
+      const needsBackfill = parts?.some(p => p.functionCall && !p.thoughtSignature) ?? false;
+      if (role !== c.role || parts?.length !== c.parts?.length || needsBackfill) {
+        return {
+          ...c, role,
+          parts: needsBackfill
+            ? parts.map(p => (p.functionCall && !p.thoughtSignature)
+                ? { ...p, thoughtSignature: DEFAULT_THINKING_AG_SIGNATURE }
+                : p)
+            : parts,
+        };
+      }
+      return c;
+    });
+
+    // Sanitize tool schemas and function names before sending to Antigravity.
+    let tools = body.request?.tools;
+
+    if (tools && tools.length > 0) {
+      // Merge all groups into a single functionDeclarations group (Gemini expects 1 group)
+      const seenToolNames = new Set();
+      const allDeclarations = [];
+      for (const group of tools) {
+        for (const fn of group.functionDeclarations || []) {
+          const name = sanitizeFunctionName(fn.name);
+          if (seenToolNames.has(name)) continue;
+          seenToolNames.add(name);
+          allDeclarations.push({
+            ...fn,
+            name,
+            parameters: fn.parameters
+              ? cleanJSONSchemaForAntigravity(structuredClone(fn.parameters))
+              : { type: "object", properties: { reason: { type: "string", description: "Brief explanation" } }, required: ["reason"] }
+          });
+        }
+      }
+      tools = allDeclarations.length > 0 ? [{ functionDeclarations: allDeclarations }] : [];
+    }
+
+    // Strip tools/toolConfig (handled separately) and blacklisted fields that Google rejects
+    const { tools: _originalTools, toolConfig: _originalToolConfig, ...requestWithoutTools } = body.request || {};
+    stripBlacklisted(requestWithoutTools);
+    const generationConfig = { ...(requestWithoutTools.generationConfig || {}) };
+    if (generationConfig.maxOutputTokens > MAX_ANTIGRAVITY_OUTPUT_TOKENS) {
+      generationConfig.maxOutputTokens = MAX_ANTIGRAVITY_OUTPUT_TOKENS;
+    }
+
+    const transformedRequest = {
+      ...requestWithoutTools,
+      generationConfig,
+      ...(contents && { contents }),
+      ...(tools && { tools }),
+      sessionId: body.request?.sessionId || resolveSessionId({ headers: credentials?.rawHeaders, body, connectionId: credentials?.email || credentials?.connectionId, scope: "antigravity" }),
+      safetySettings: undefined,
+      ...(tools?.length > 0 && { toolConfig: { functionCallingConfig: { mode: "VALIDATED" } } })
+    };
+
+    // Strip blacklisted thinking fields from top-level body (set by thinkingUnified.js at root, not body.request)
+    stripBlacklisted(body);
+
+    this._lastSessionId = transformedRequest.sessionId; // cached for buildHeaders (base.execute order)
+
+    return {
+      ...body,
+      project: projectId,
+      model: model,
+      userAgent: "antigravity",
+      requestType: "agent",
+      requestId: buildIdeRequestId({ body, request: transformedRequest, credentials, model, requestType: "agent" }),
+      request: transformedRequest
+    };
+  }
+
+  async refreshCredentials(credentials, log, proxyOptions = null) {
+    if (!credentials.refreshToken) return null;
+
+    try {
+      const response = await proxyAwareFetch(OAUTH_ENDPOINTS.google.token, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json" },
+        body: new URLSearchParams({
+          grant_type: "refresh_token",
+          refresh_token: credentials.refreshToken,
+          client_id: this.config.clientId,
+          client_secret: this.config.clientSecret
+        })
+      }, proxyOptions);
+
+      if (!response.ok) return null;
+
+      const tokens = await response.json();
+      log?.info?.("TOKEN", "Antigravity refreshed");
+
+      return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token || credentials.refreshToken,
+        expiresIn: tokens.expires_in,
+        projectId: credentials.projectId
+      };
+    } catch (error) {
+      log?.error?.("TOKEN", `Antigravity refresh error: ${error.message}`);
+      return null;
+    }
+  }
+
+  generateProjectId() {
+    const adj = ["useful", "bright", "swift", "calm", "bold"][Math.floor(Math.random() * 5)];
+    const noun = ["fuze", "wave", "spark", "flow", "core"][Math.floor(Math.random() * 5)];
+    return `${adj}-${noun}-${crypto.randomUUID().slice(0, 5)}`;
+  }
+
+  generateSessionId() {
+    return crypto.randomUUID() + Date.now().toString();
+  }
+
+  parseRetryHeaders(headers) {
+    if (!headers?.get) return null;
+
+    const retryAfter = headers.get('retry-after');
+    if (retryAfter) {
+      const seconds = parseInt(retryAfter, 10);
+      if (!isNaN(seconds) && seconds > 0) return seconds * 1000;
+
+      const date = new Date(retryAfter);
+      if (!isNaN(date.getTime())) {
+        const diff = date.getTime() - Date.now();
+        return diff > 0 ? diff : null;
+      }
+    }
+
+    const resetAfter = headers.get('x-ratelimit-reset-after');
+    if (resetAfter) {
+      const seconds = parseInt(resetAfter, 10);
+      if (!isNaN(seconds) && seconds > 0) return seconds * 1000;
+    }
+
+    const resetTimestamp = headers.get('x-ratelimit-reset');
+    if (resetTimestamp) {
+      const ts = parseInt(resetTimestamp, 10) * 1000;
+      const diff = ts - Date.now();
+      return diff > 0 ? diff : null;
+    }
+
+    return null;
+  }
+
+  // Parse retry time from Antigravity error message body
+  // Format: "Your quota will reset after 2h7m23s" or "1h30m" or "45m" or "30s"
+  parseRetryFromErrorMessage(errorMessage) {
+    if (!errorMessage || typeof errorMessage !== "string") return null;
+
+    const match = errorMessage.match(/reset after (\d+h)?(\d+m)?(\d+s)?/i);
+    if (!match) return null;
+
+    let totalMs = 0;
+    if (match[1]) totalMs += parseInt(match[1]) * 3600 * 1000; // hours
+    if (match[2]) totalMs += parseInt(match[2]) * 60 * 1000; // minutes
+    if (match[3]) totalMs += parseInt(match[3]) * 1000; // seconds
+
+    return totalMs > 0 ? totalMs : null;
+  }
+
+  extractErrorMessage(errorJson, bodyText = "") {
+    return [
+      errorJson?.error?.message,
+      errorJson?.message,
+      errorJson?.error,
+      bodyText,
+    ].filter(Boolean).map(v => typeof v === "string" ? v : JSON.stringify(v)).join("\n");
+  }
+
+  isTransientAntigravityError(status, message) {
+    if (status === HTTP_STATUS.RATE_LIMITED) return true;
+    if (ANTIGRAVITY_TRANSIENT_STATUSES.has(status)) return true;
+    return ANTIGRAVITY_TRANSIENT_ERROR_PATTERNS.some(pattern => pattern.test(message || ""));
+  }
+
+  // Hook called by BaseExecutor.tryRetry: derive delay from Retry-After (header → body),
+  // cap at MAX_RETRY_AFTER_MS, else retry transient Antigravity failures with backoff.
+  // Return false to veto (fallback URL / final error).
+  async computeRetryDelay(response, attempt) {
+    let bodyText = "";
+    let errorJson = null;
+    let retryMs = this.parseRetryHeaders(response.headers);
+
+    try {
+      bodyText = await response.clone().text();
+      errorJson = bodyText ? JSON.parse(bodyText) : null;
+    } catch {
+      // ignore parse errors → fall through to status/message based retry
+    }
+
+    const errorMessage = this.extractErrorMessage(errorJson, bodyText);
+
+    if (!retryMs) {
+      retryMs = this.parseRetryFromErrorMessage(errorMessage);
+    }
+    if (retryMs) return retryMs <= MAX_RETRY_AFTER_MS ? retryMs : false;
+
+    if (!this.isTransientAntigravityError(response.status, errorMessage)) return false;
+
+    const cap = response.status === HTTP_STATUS.RATE_LIMITED
+      ? MAX_RETRY_AFTER_MS
+      : ANTIGRAVITY_TRANSIENT_RETRY_MAX_MS;
+    return Math.min(1000 * (2 ** attempt), cap); // exponential backoff
+  }
+
+  /**
+   * Cloak tools before sending to Antigravity provider (anti-ban):
+   * - Rename client tools with _ide suffix
+   * - Inject AG default decoy tools after client tools
+   * Returns { cloakedBody, toolNameMap } where toolNameMap maps suffixed → original
+   */
+  static cloakTools(body, clientTool = null) {
+    const tools = body.request?.tools;
+    if (!tools || tools.length === 0) {
+      return { cloakedBody: body, toolNameMap: null };
+    }
+
+    const isCopilot = clientTool === "github-copilot";
+    const toolNameMap = new Map();
+    const clientDeclarations = [];
+    const decoyNames = new Set(AG_DECOY_TOOLS.map(tool => tool.name));
+
+    // First: collect renamed client tools
+    for (const toolGroup of tools) {
+      if (!toolGroup.functionDeclarations) continue;
+
+      for (const func of toolGroup.functionDeclarations) {
+        // For GitHub Copilot, avoid emitting duplicate native Antigravity tool names.
+        // Keep the decoys only once in the final declaration list.
+        if (isCopilot && AG_DEFAULT_TOOLS.has(func.name)) {
+          continue;
+        }
+
+        // Skip if already covered by decoys for Copilot
+        if (isCopilot && decoyNames.has(func.name)) {
+          continue;
+        }
+
+        // Preserve native AG names for non-Copilot clients
+        if (AG_DEFAULT_TOOLS.has(func.name)) {
+          clientDeclarations.push(func);
+          continue;
+        }
+
+        const suffixed = `${func.name}${AG_TOOL_SUFFIX}`;
+        toolNameMap.set(suffixed, func.name);
+        clientDeclarations.push({ ...func, name: suffixed });
+      }
+    }
+
+    // Client tools first, then AG decoy tools
+    const allDeclarations = [];
+    const seenNames = new Set();
+    for (const decl of [...clientDeclarations, ...AG_DECOY_TOOLS]) {
+      if (!decl?.name || seenNames.has(decl.name)) continue;
+      seenNames.add(decl.name);
+      allDeclarations.push(decl);
+    }
+
+    // Rename tool names in conversation history (contents)
+    const cloakedContents = body.request?.contents?.map(msg => {
+      if (!msg.parts) return msg;
+      
+      const cloakedParts = msg.parts.map(part => {
+        // Rename functionCall.name
+        if (part.functionCall && !AG_DEFAULT_TOOLS.has(part.functionCall.name)) {
+          return {
+            ...part,
+            functionCall: {
+              ...part.functionCall,
+              name: `${part.functionCall.name}${AG_TOOL_SUFFIX}`
+            }
+          };
+        }
+        
+        // Rename functionResponse.name
+        if (part.functionResponse && !AG_DEFAULT_TOOLS.has(part.functionResponse.name)) {
+          return {
+            ...part,
+            functionResponse: {
+              ...part.functionResponse,
+              name: `${part.functionResponse.name}${AG_TOOL_SUFFIX}`
+            }
+          };
+        }
+        
+        return part;
+      });
+      
+      return { ...msg, parts: cloakedParts };
+    });
+
+    // Single functionDeclarations group: client tools first, then decoys
+    return {
+      cloakedBody: {
+        ...body,
+        request: {
+          ...body.request,
+          tools: [{ functionDeclarations: allDeclarations }],
+          contents: cloakedContents || body.request.contents
+        }
+      },
+      toolNameMap
+    };
+  }
+}
+
+// AG decoy tools — same names as AG native defaults, redirect to _ide suffixed tools
+const AG_DECOY_TOOLS = [
+  {
+    name: "browser_subagent",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "command_status",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "find_by_name",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "generate_image",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "grep_search",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "list_dir",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "list_resources",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "mcp_sequential-thinking_sequentialthinking",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "multi_replace_file_content",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "notify_user",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "read_resource",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "read_terminal",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "read_url_content",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "replace_file_content",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "run_command",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "search_web",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "send_command_input",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "task_boundary",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "view_content_chunk",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "view_file",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  },
+  {
+    name: "write_to_file",
+    description: "This tool is currently unavailable.",
+    parameters: { type: "OBJECT", properties: {}, required: [] }
+  }
+];
+
+export default AntigravityExecutor;
diff --git a/open-sse/executors/azure.js b/open-sse/executors/azure.js
new file mode 100644
index 0000000..574cda2
--- /dev/null
+++ b/open-sse/executors/azure.js
@@ -0,0 +1,57 @@
+import { DefaultExecutor } from "./default.js";
+
+export class AzureExecutor extends DefaultExecutor {
+  constructor() {
+    super("azure");
+  }
+
+  buildUrl(model, stream, urlIndex = 0, credentials = null) {
+    const azureEndpoint = credentials?.providerSpecificData?.azureEndpoint
+      || process.env.AZURE_ENDPOINT
+      || "https://api.openai.com";
+
+    const apiVersion = credentials?.providerSpecificData?.apiVersion
+      || process.env.AZURE_API_VERSION
+      || "2024-10-01-preview";
+
+    const deployment = credentials?.providerSpecificData?.deployment
+      || model
+      || process.env.AZURE_DEPLOYMENT
+      || "gpt-4";
+
+    const endpoint = azureEndpoint.replace(/\/$/, "");
+    return `${endpoint}/openai/deployments/${deployment}/chat/completions?api-version=${apiVersion}`;
+  }
+
+  buildHeaders(credentials, stream = true) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.config.headers
+    };
+
+    const apiKey = credentials?.apiKey
+      || credentials?.accessToken
+      || process.env.OPENAI_API_KEY;
+
+    if (apiKey) {
+      headers["api-key"] = apiKey;
+    }
+
+    const organization = credentials?.providerSpecificData?.organization
+      || process.env.AZURE_ORGANIZATION;
+
+    if (organization) {
+      headers["OpenAI-Organization"] = organization;
+    }
+
+    if (stream) {
+      headers["Accept"] = "text/event-stream";
+    }
+
+    return headers;
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    return body;
+  }
+}
diff --git a/open-sse/executors/base.js b/open-sse/executors/base.js
new file mode 100644
index 0000000..71418de
--- /dev/null
+++ b/open-sse/executors/base.js
@@ -0,0 +1,186 @@
+import { HTTP_STATUS, RETRY_CONFIG, DEFAULT_RETRY_CONFIG, resolveRetryEntry, FETCH_CONNECT_TIMEOUT_MS } from "../config/runtimeConfig.js";
+import { shouldRefreshCredentials } from "../services/oauthCredentialManager.js";
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+import { dbg } from "../utils/debugLog.js";
+import { ANTHROPIC_API_VERSION, OPENAI_COMPAT_BASE, ANTHROPIC_COMPAT_BASE } from "../providers/shared.js";
+
+/**
+ * BaseExecutor - Base class for provider executors
+ */
+export class BaseExecutor {
+  constructor(provider, config) {
+    this.provider = provider;
+    this.config = config;
+    this.noAuth = config?.noAuth || false;
+  }
+
+  getProvider() {
+    return this.provider;
+  }
+
+  getBaseUrls() {
+    return this.config.baseUrls || (this.config.baseUrl ? [this.config.baseUrl] : []);
+  }
+
+  getFallbackCount() {
+    return this.getBaseUrls().length || 1;
+  }
+
+  buildUrl(model, stream, urlIndex = 0, credentials = null) {
+    if (this.provider?.startsWith?.("openai-compatible-")) {
+      const baseUrl = credentials?.providerSpecificData?.baseUrl || OPENAI_COMPAT_BASE;
+      const normalized = baseUrl.replace(/\/$/, "");
+      const path = this.provider.includes("responses") ? "/responses" : "/chat/completions";
+      return `${normalized}${path}`;
+    }
+    if (this.provider?.startsWith?.("anthropic-compatible-")) {
+      const baseUrl = credentials?.providerSpecificData?.baseUrl || ANTHROPIC_COMPAT_BASE;
+      const normalized = baseUrl.replace(/\/$/, "");
+      return `${normalized}/messages`;
+    }
+    const baseUrls = this.getBaseUrls();
+    return baseUrls[urlIndex] || baseUrls[0] || this.config.baseUrl;
+  }
+
+  buildHeaders(credentials, stream = true) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.config.headers
+    };
+
+    if (this.provider?.startsWith?.("anthropic-compatible-")) {
+      // Anthropic-compatible providers use x-api-key header
+      if (credentials.apiKey) {
+        headers["x-api-key"] = credentials.apiKey;
+      } else if (credentials.accessToken) {
+        headers["Authorization"] = `Bearer ${credentials.accessToken}`;
+      }
+      if (!headers["anthropic-version"]) {
+        headers["anthropic-version"] = ANTHROPIC_API_VERSION;
+      }
+    } else {
+      // Standard Bearer token auth for other providers
+      if (credentials.accessToken) {
+        headers["Authorization"] = `Bearer ${credentials.accessToken}`;
+      } else if (credentials.apiKey) {
+        headers["Authorization"] = `Bearer ${credentials.apiKey}`;
+      }
+    }
+
+    if (stream) {
+      headers["Accept"] = "text/event-stream";
+    }
+
+    return headers;
+  }
+
+  // Override in subclass for provider-specific transformations
+  transformRequest(model, body, stream, credentials) {
+    return body;
+  }
+
+  shouldRetry(status, urlIndex) {
+    return status === HTTP_STATUS.RATE_LIMITED && urlIndex + 1 < this.getFallbackCount();
+  }
+
+  // Override in subclass for provider-specific refresh
+  async refreshCredentials(credentials, log, proxyOptions = null) {
+    return null;
+  }
+
+  needsRefresh(credentials) {
+    return shouldRefreshCredentials(this.provider, credentials);
+  }
+
+  parseError(response, bodyText) {
+    return { status: response.status, message: bodyText || `HTTP ${response.status}` };
+  }
+
+  async execute({ model, body, stream, credentials, signal, log, proxyOptions = null }) {
+    const fallbackCount = this.getFallbackCount();
+    let lastError = null;
+    let lastStatus = 0;
+    const retryAttemptsByUrl = {};
+
+    // Merge default retry config with provider-specific config
+    const retryConfig = { ...DEFAULT_RETRY_CONFIG, ...this.config.retry };
+
+    // Schedule retry via retryConfig[statusKey]. Returns true when caller should `urlIndex--; continue`
+    // response (optional) lets a subclass hook compute a dynamic delay (e.g. antigravity Retry-After).
+    const tryRetry = async (urlIndex, statusKey, reason, response = null) => {
+      const { attempts, delayMs } = resolveRetryEntry(retryConfig[statusKey]);
+      if (attempts <= 0 || retryAttemptsByUrl[urlIndex] >= attempts) return false;
+      // Hook: subclass may derive delay from the response (headers/body). null → skip retry, use fallback.
+      let waitMs = delayMs;
+      if (response && this.computeRetryDelay) {
+        const dynamic = await this.computeRetryDelay(response, retryAttemptsByUrl[urlIndex] + 1, delayMs);
+        if (dynamic === false) return false; // hook vetoes retry (e.g. Retry-After too long)
+        if (dynamic != null) waitMs = dynamic;
+      }
+      retryAttemptsByUrl[urlIndex]++;
+      log?.debug?.("RETRY", `${reason} retry ${retryAttemptsByUrl[urlIndex]}/${attempts} after ${waitMs / 1000}s`);
+      await new Promise(resolve => setTimeout(resolve, waitMs));
+      return true;
+    };
+
+    for (let urlIndex = 0; urlIndex < fallbackCount; urlIndex++) {
+      const url = this.buildUrl(model, stream, urlIndex, credentials);
+      const transformedBody = this.transformRequest(model, body, stream, credentials);
+      const headers = this.buildHeaders(credentials, stream);
+
+      if (!retryAttemptsByUrl[urlIndex]) retryAttemptsByUrl[urlIndex] = 0;
+
+      // Abort if upstream doesn't return response headers within connection timeout
+      const connectCtrl = new AbortController();
+      const timeoutMs = this.config?.timeoutMs || FETCH_CONNECT_TIMEOUT_MS;
+      const connectTimer = setTimeout(() => connectCtrl.abort(new Error("fetch connect timeout")), timeoutMs);
+      const mergedSignal = signal ? AbortSignal.any([signal, connectCtrl.signal]) : connectCtrl.signal;
+
+      try {
+        const bodyStr = JSON.stringify(transformedBody);
+        const fetchT0 = Date.now();
+        dbg("FETCH", `${this.provider.toUpperCase()} → ${url} | body=${bodyStr.length}B | connectTimeout=${timeoutMs}ms`);
+        const response = await proxyAwareFetch(url, {
+          method: "POST",
+          headers,
+          body: bodyStr,
+          signal: mergedSignal
+        }, proxyOptions);
+        clearTimeout(connectTimer);
+        const ct = response.headers?.get?.("content-type") || "";
+        const cl = response.headers?.get?.("content-length") || "?";
+        dbg("FETCH", `${this.provider.toUpperCase()} ← ${response.status} | ttft=${Date.now() - fetchT0}ms | ct=${ct} | cl=${cl}`);
+
+        if (await tryRetry(urlIndex, response.status, `status ${response.status}`, response)) { urlIndex--; continue; }
+
+        if (this.shouldRetry(response.status, urlIndex)) {
+          log?.debug?.("RETRY", `${response.status} on ${url}, trying fallback ${urlIndex + 1}`);
+          lastStatus = response.status;
+          continue;
+        }
+
+        return { response, url, headers, transformedBody };
+      } catch (error) {
+        clearTimeout(connectTimer);
+        lastError = error;
+        const isConnectTimeout = connectCtrl.signal.aborted && error.name === "AbortError";
+        dbg("FETCH", `${this.provider.toUpperCase()} ✖ ${error.name}: ${error.message}${isConnectTimeout ? " (connect timeout)" : ""}`);
+        // Connect timeout is internal — convert to retryable network error, don't propagate AbortError
+        if (error.name === "AbortError" && !isConnectTimeout) throw error;
+
+        // Map network/fetch exceptions to 502 retry config
+        if (await tryRetry(urlIndex, HTTP_STATUS.BAD_GATEWAY, `network "${error.message}"`)) { urlIndex--; continue; }
+
+        if (urlIndex + 1 < fallbackCount) {
+          log?.debug?.("RETRY", `Error on ${url}, trying fallback ${urlIndex + 1}`);
+          continue;
+        }
+        throw error;
+      }
+    }
+
+    throw lastError || new Error(`All ${fallbackCount} URLs failed with status ${lastStatus}`);
+  }
+}
+
+export default BaseExecutor;
diff --git a/open-sse/executors/codebuddy-cn.js b/open-sse/executors/codebuddy-cn.js
new file mode 100644
index 0000000..5f37d01
--- /dev/null
+++ b/open-sse/executors/codebuddy-cn.js
@@ -0,0 +1,40 @@
+import { DefaultExecutor } from "./default.js";
+
+/**
+ * CodeBuddyExecutor — talks to https://copilot.tencent.com/v2/chat/completions
+ *
+ * CodeBuddy is OpenAI-compatible but rejects non-stream chat requests
+ * (HTTP 400, code 11101 "Non-stream chat request is currently not supported").
+ * The same-format (openai→openai) translator path leaves body.stream as the
+ * client sent it, so we force it true here — 9router still re-aggregates the
+ * SSE into a JSON response for non-streaming clients.
+ */
+export class CodeBuddyExecutor extends DefaultExecutor {
+  constructor() {
+    super("codebuddy-cn");
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    const transformed = super.transformRequest(model, body, stream, credentials);
+    transformed.stream = true;
+
+    // CodeBuddy only surfaces model reasoning when the request carries the CLI's
+    // OpenAI-style params: reasoning_effort + reasoning_summary:"auto". 9router's
+    // thinking pipeline sets reasoning_effort only when the client asks, and never
+    // sets reasoning_summary — so reasoning never shows. Mirror the CLI here.
+    const eff = transformed.reasoning_effort;
+    if (eff === "none" || eff === "off") {
+      delete transformed.reasoning_effort; // gateway has no "none" — just omit
+    } else if (eff) {
+      // Client explicitly asked for reasoning — mirror the CLI's reasoning_summary
+      // so CodeBuddy surfaces the model's reasoning.
+      transformed.reasoning_summary = "auto";
+    }
+    // No reasoning requested: leave both unset. Forcing reasoning_effort:"medium"
+    // + reasoning_summary on plain requests makes CodeBuddy trip its content
+    // filter and return an error (#2071).
+    return transformed;
+  }
+}
+
+export default CodeBuddyExecutor;
diff --git a/open-sse/executors/codex.js b/open-sse/executors/codex.js
new file mode 100644
index 0000000..3b04445
--- /dev/null
+++ b/open-sse/executors/codex.js
@@ -0,0 +1,485 @@
+import { BaseExecutor } from "./base.js";
+import { CODEX_DEFAULT_INSTRUCTIONS } from "../config/codexInstructions.js";
+import { PROVIDERS } from "../config/providers.js";
+import {
+  refreshProviderCredentials,
+  shouldRefreshCredentials,
+} from "../services/oauthCredentialManager.js";
+import { normalizeResponsesInput } from "../translator/formats/responsesApi.js";
+import { fetchImageAsBase64 } from "../translator/concerns/image.js";
+import { getModelUpstreamId } from "../config/providerModels.js";
+import { DEFAULT_RETRY_CONFIG, HTTP_STATUS, resolveRetryEntry } from "../config/runtimeConfig.js";
+import { dbg } from "../utils/debugLog.js";
+import { resolveSessionId } from "../utils/sessionManager.js";
+
+// SSE error patterns inside 200-OK bodies. Some retry same account first; capacity rotates accounts.
+const CODEX_SSE_RETRY_PATTERNS = ["server_is_overloaded", "service_unavailable_error"];
+const CODEX_SSE_ACCOUNT_FALLBACK_PATTERNS = ["selected model is at capacity", "model_at_capacity"];
+const CODEX_SSE_USER_OUTPUT_PATTERNS = [
+  "event: response.output_text.delta",
+  "event: response.function_call_arguments.delta",
+  '"type":"response.output_text.delta"',
+  '"type":"response.function_call_arguments.delta"',
+];
+const CODEX_SSE_PEEK_BYTES = 256 * 1024;
+const CODEX_MODEL_CAPACITY_MESSAGE = "Selected model is at capacity. Please try a different model.";
+
+// Server-generated item id prefixes that Codex /responses cannot resolve when store=false
+const SERVER_ID_PATTERN = /^(rs|fc|resp|msg)_/;
+
+// Hosted tool types that Codex/OpenAI Responses executes server-side
+const CODEX_HOSTED_TOOL_TYPES = new Set([
+  "image_generation", "web_search", "web_search_preview", "file_search",
+  "computer", "computer_use_preview", "code_interpreter", "mcp", "local_shell",
+  "tool_search"
+]);
+
+// Responses-native freeform tools carry a name plus format payload and must pass through intact.
+const CODEX_PASSTHROUGH_TOOL_TYPES = new Set(["custom"]);
+
+// Allowlist of fields accepted by Codex Responses API — anything else is stripped
+const RESPONSES_API_ALLOWLIST = new Set([
+  "model", "input", "instructions", "tools", "tool_choice", "stream", "store",
+  "reasoning", "service_tier", "include", "prompt_cache_key", "client_metadata",
+  "text"
+]);
+
+// Convert role=system → role=developer in body.input (keeps content in cacheable prefix)
+function convertSystemToDeveloperRole(body) {
+  if (!Array.isArray(body.input)) return;
+  for (const item of body.input) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+    const isSystemMsg = item.role === "system" && (!item.type || item.type === "message");
+    if (isSystemMsg) item.role = "developer";
+  }
+}
+
+// Strip server-generated item IDs (rs_/fc_/resp_/msg_) from input — avoids 404 with store=false
+function stripStoredItemReferences(body) {
+  if (!Array.isArray(body.input)) return;
+  body.input = body.input.filter((item) => {
+    if (typeof item === "string" && SERVER_ID_PATTERN.test(item)) return false;
+    if (item && typeof item === "object" && !Array.isArray(item)) {
+      if (item.type === "item_reference") return false;
+      if (typeof item.id === "string" && SERVER_ID_PATTERN.test(item.id)) delete item.id;
+    }
+    return true;
+  });
+}
+
+// Flatten Chat-Completions tool shape into Responses flat format + filter unsupported tools
+function normalizeCodexTools(body) {
+  if (!Array.isArray(body.tools)) return;
+  const validNames = new Set();
+  body.tools = body.tools.filter((tool) => {
+    if (!tool || typeof tool !== "object" || Array.isArray(tool)) return false;
+    const type = typeof tool.type === "string" ? tool.type : "";
+    if (type === "namespace") {
+      if (Array.isArray(tool.tools)) {
+        for (const st of tool.tools) {
+          const n = typeof st?.name === "string" ? st.name.trim().slice(0, 128) : "";
+          if (n) validNames.add(n);
+        }
+      }
+      return true;
+    }
+    if (type !== "function") {
+      if (CODEX_PASSTHROUGH_TOOL_TYPES.has(type)) return true;
+      if (!type || tool.function || typeof tool.name === "string") return false;
+      return CODEX_HOSTED_TOOL_TYPES.has(type);
+    }
+    const fn = tool.function && typeof tool.function === "object" && !Array.isArray(tool.function) ? tool.function : null;
+    const rawName = typeof tool.name === "string" ? tool.name : (typeof fn?.name === "string" ? fn.name : "");
+    const name = rawName.trim();
+    if (!name) return false;
+    const description = typeof tool.description === "string" ? tool.description : (typeof fn?.description === "string" ? fn.description : "");
+    const parameters = (tool.parameters && typeof tool.parameters === "object" && !Array.isArray(tool.parameters))
+      ? tool.parameters
+      : (fn?.parameters && typeof fn.parameters === "object" && !Array.isArray(fn.parameters) ? fn.parameters : { type: "object", properties: {} });
+    for (const k of Object.keys(tool)) delete tool[k];
+    tool.type = "function";
+    tool.name = name.slice(0, 128);
+    if (description) tool.description = description;
+    tool.parameters = parameters;
+    validNames.add(name);
+    return true;
+  });
+  // Drop tool_choice if it references an unknown function name
+  if (body.tool_choice && typeof body.tool_choice === "object" && !Array.isArray(body.tool_choice)) {
+    if (body.tool_choice.type === "function") {
+      const n = typeof body.tool_choice.name === "string" ? body.tool_choice.name.trim() : "";
+      if (!n || !validNames.has(n)) delete body.tool_choice;
+    }
+  }
+}
+
+// Resolve prompt-cache session id: client session → assistant-text-hash → workspaceId → connection
+function resolveCacheSessionId(body, credentials) {
+  return resolveSessionId({
+    headers: credentials?.rawHeaders,
+    body,
+    connectionId: credentials?.connectionId,
+    workspaceId: credentials?.providerSpecificData?.workspaceId,
+    scope: "codex"
+  });
+}
+
+function normalizeReasoningEffort(value) {
+  return value === "max" ? "xhigh" : value;
+}
+
+function findNestedMessage(value, depth = 0) {
+  if (!value || depth > 6 || typeof value === "string") return null;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = findNestedMessage(item, depth + 1);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (typeof value !== "object") return null;
+  if (typeof value.message === "string" && value.message.trim()) return value.message;
+  if (typeof value.error?.message === "string" && value.error.message.trim()) return value.error.message;
+  if (typeof value.response?.error?.message === "string" && value.response.error.message.trim()) return value.response.error.message;
+  for (const child of Object.values(value)) {
+    const found = findNestedMessage(child, depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+
+function extractSseErrorMessage(text, fallback) {
+  const exact = text?.match(/Selected model is at capacity\. Please try a different model\./i)?.[0];
+  if (exact) return exact;
+
+  for (const line of String(text || "").split(/\r?\n/)) {
+    if (!line.startsWith("data:")) continue;
+    const data = line.slice(5).trim();
+    if (!data || data === "[DONE]") continue;
+    try {
+      const message = findNestedMessage(JSON.parse(data));
+      if (message) return message;
+    } catch {
+      // Ignore non-JSON SSE data lines.
+    }
+  }
+
+  return fallback || CODEX_MODEL_CAPACITY_MESSAGE;
+}
+
+function codexSseErrorResponse(status, message) {
+  return new Response(JSON.stringify({
+    error: {
+      message,
+      type: status >= 500 ? "server_error" : "invalid_request_error",
+      code: status === HTTP_STATUS.SERVICE_UNAVAILABLE ? "service_unavailable" : "upstream_error",
+    }
+  }), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+/**
+ * Codex Executor - handles OpenAI Codex API (Responses API format)
+ * Automatically injects default instructions if missing
+ */
+export class CodexExecutor extends BaseExecutor {
+  constructor() {
+    super("codex", PROVIDERS.codex);
+    this._currentSessionId = null;
+  }
+
+  /**
+   * Override headers to add codex-specific identity headers.
+   * transformRequest runs BEFORE buildHeaders, sets this._currentSessionId.
+   */
+  buildHeaders(credentials, stream = true) {
+    const headers = super.buildHeaders(credentials, stream);
+    headers["session_id"] = this._currentSessionId || credentials?.connectionId || "default";
+    // Identify client type to Codex backend (matches official codex CLI)
+    if (!headers["originator"]) headers["originator"] = "codex_cli_rs";
+    // Account/workspace binding header — required when multiple Codex accounts
+    // are configured. OAuth import stores ChatGPT account ID as chatgptAccountId;
+    // older/custom rows may use workspaceId/accountId. Prefer explicit workspaceId
+    // but fall back to chatgptAccountId so requests don't cross-bind to the wrong
+    // OpenAI account and surface as token_invalid after adding another account.
+    const accountId =
+      credentials?.providerSpecificData?.workspaceId ||
+      credentials?.providerSpecificData?.chatgptAccountId ||
+      credentials?.providerSpecificData?.accountId;
+    if (typeof accountId === "string" && accountId && !headers["ChatGPT-Account-ID"]) {
+      headers["ChatGPT-Account-ID"] = accountId;
+    }
+    return headers;
+  }
+
+  buildUrl(model, stream, urlIndex = 0, credentials = null) {
+    const base = super.buildUrl(model, stream, urlIndex, credentials);
+    return this._isCompact ? `${base}/compact` : base;
+  }
+
+  async refreshCredentials(credentials, log) {
+    if (!credentials?.refreshToken) return null;
+    return refreshProviderCredentials("codex", credentials, log);
+  }
+
+  needsRefresh(credentials) {
+    return shouldRefreshCredentials("codex", credentials);
+  }
+
+  /**
+   * Prefetch remote image URLs and inline them as base64 data URIs.
+   * Runs before execute() because Codex backend cannot fetch remote images.
+   * Mutates body.input in place.
+   */
+  async prefetchImages(body) {
+    if (!Array.isArray(body?.input)) return;
+    for (const item of body.input) {
+      if (!Array.isArray(item.content)) continue;
+      const pending = item.content.map(async (c) => {
+        if (c.type !== "image_url") return c;
+        const url = typeof c.image_url === "string" ? c.image_url : c.image_url?.url;
+        const detail = c.image_url?.detail || "auto";
+        if (!url) return c;
+        if (url.startsWith("data:")) return { type: "input_image", image_url: url, detail };
+        const fetched = await fetchImageAsBase64(url, { timeoutMs: 15000 });
+        return { type: "input_image", image_url: fetched?.url || url, detail };
+      });
+      item.content = await Promise.all(pending);
+    }
+  }
+
+  async execute(args) {
+    const imgCount = Array.isArray(args.body?.input) ? args.body.input.reduce((n, it) => n + (Array.isArray(it.content) ? it.content.filter(c => c.type === "image_url").length : 0), 0) : 0;
+    const inputLen = Array.isArray(args.body?.input) ? args.body.input.length : 0;
+    dbg("CODEX", `execute start | inputItems=${inputLen} | images=${imgCount} | sessionId=${this._currentSessionId || "pending"}`);
+    if (imgCount > 0) {
+      const t0 = Date.now();
+      await this.prefetchImages(args.body);
+      dbg("CODEX", `prefetchImages done | ${Date.now() - t0}ms`);
+    } else {
+      await this.prefetchImages(args.body);
+    }
+
+    // Retry loop for SSE-level overloaded errors (200 OK body contains event: error)
+    // Reuses 503 retry config — same semantic: upstream temporarily unavailable
+    const retryConfig = { ...DEFAULT_RETRY_CONFIG, ...this.config.retry };
+    const { attempts, delayMs } = resolveRetryEntry(retryConfig[503]);
+    let attempt = 0;
+    while (true) {
+      const result = await super.execute(args);
+      const peek = await this._peekSseTransientError(result.response);
+      if (!peek.matched) {
+        // Replace body with re-assembled stream (prefix bytes already read + rest)
+        if (peek.replacementBody) {
+          result.response = new Response(peek.replacementBody, {
+            status: result.response.status,
+            statusText: result.response.statusText,
+            headers: result.response.headers,
+          });
+        }
+        return result;
+      }
+      if (peek.accountFallback) {
+        args.log?.warn?.("RETRY", `CODEX | SSE account fallback "${peek.message}"`);
+        result.response = codexSseErrorResponse(HTTP_STATUS.SERVICE_UNAVAILABLE, peek.message || CODEX_MODEL_CAPACITY_MESSAGE);
+        return result;
+      }
+      if (attempt >= attempts) {
+        args.log?.warn?.("RETRY", `CODEX | SSE overloaded "${peek.matched}" — retries exhausted (${attempt}/${attempts})`);
+        result.response = codexSseErrorResponse(HTTP_STATUS.SERVICE_UNAVAILABLE, peek.message || peek.matched);
+        return result;
+      }
+      attempt++;
+      args.log?.debug?.("RETRY", `CODEX | SSE "${peek.matched}" retry ${attempt}/${attempts} after ${delayMs / 1000}s`);
+      dbg("CODEX", `SSE overloaded "${peek.matched}" → retry ${attempt}/${attempts} in ${delayMs}ms`);
+      await new Promise(r => setTimeout(r, delayMs));
+    }
+  }
+
+  // Peek first N bytes of SSE body to detect upstream transient errors.
+  // Returns { matched: string|null, message: string|null, accountFallback: boolean, replacementBody: ReadableStream|null }.
+  // Caller must use replacementBody when no error matched (original body has been read).
+  async _peekSseTransientError(response) {
+    if (!response || !response.ok || !response.body) return { matched: null, message: null, accountFallback: false, replacementBody: null };
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    const chunks = [];
+    let text = "";
+    let matched = null;
+    let accountFallback = false;
+    try {
+      while (text.length < CODEX_SSE_PEEK_BYTES) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+        text += decoder.decode(value, { stream: true });
+        const lowerText = text.toLowerCase();
+        const accountHit = CODEX_SSE_ACCOUNT_FALLBACK_PATTERNS.find(p => lowerText.includes(p));
+        if (accountHit) { matched = accountHit; accountFallback = true; break; }
+        const retryHit = CODEX_SSE_RETRY_PATTERNS.find(p => lowerText.includes(p));
+        if (retryHit) { matched = retryHit; break; }
+        if (CODEX_SSE_USER_OUTPUT_PATTERNS.some(p => lowerText.includes(p))) break;
+      }
+    } catch (e) {
+      dbg("CODEX", `peek read error: ${e.message}`);
+    }
+
+    if (matched) {
+      try { await reader.cancel(); } catch { /* noop */ }
+      try { reader.releaseLock(); } catch { /* noop */ }
+      return { matched, message: extractSseErrorMessage(text, matched), accountFallback, replacementBody: null };
+    }
+
+    reader.releaseLock();
+
+    // Re-assemble stream: prefix chunks + remaining upstream body
+    const upstream = response.body;
+    let upstreamReader = null;
+    const replacementBody = new ReadableStream({
+      start(controller) {
+        for (const c of chunks) controller.enqueue(c);
+        upstreamReader = upstream.getReader();
+      },
+      async pull(controller) {
+        try {
+          const { done, value } = await upstreamReader.read();
+          if (done) { controller.close(); return; }
+          controller.enqueue(value);
+        } catch (e) { controller.error(e); }
+      },
+      cancel(reason) {
+        try { upstreamReader?.cancel(reason); } catch { /* noop */ }
+      },
+    });
+    return { matched: null, message: null, accountFallback: false, replacementBody };
+  }
+
+  // Parse Codex usage_limit_reached to extract precise resetsAtMs; fallback to default otherwise
+  parseError(response, bodyText) {
+    if (response.status === 429 && bodyText) {
+      try {
+        const json = JSON.parse(bodyText);
+        const err = json?.error;
+        if (err?.type === "usage_limit_reached") {
+          const now = Date.now();
+          let resetsAtMs = null;
+          if (typeof err.resets_at === "number" && err.resets_at > 0) {
+            const ms = err.resets_at * 1000;
+            if (ms > now) resetsAtMs = ms;
+          }
+          if (!resetsAtMs && typeof err.resets_in_seconds === "number" && err.resets_in_seconds > 0) {
+            resetsAtMs = now + err.resets_in_seconds * 1000;
+          }
+          if (resetsAtMs) {
+            return { status: 429, message: err.message || bodyText, resetsAtMs };
+          }
+        }
+      } catch { /* fall through to default */ }
+    }
+    return super.parseError(response, bodyText);
+  }
+
+  /**
+   * Transform request before sending - inject default instructions if missing.
+   * Image fetching is handled separately in prefetchImages() so this stays sync.
+   */
+  transformRequest(model, body, stream, credentials) {
+    this._isCompact = !!body._compact;
+    delete body._compact;
+    // Resolve conversation-stable session_id (priority: body → assistant-text → workspace → machine)
+    this._currentSessionId = resolveCacheSessionId(body, credentials);
+    // Convert string input to array format (Codex API requires input as array)
+    const normalized = normalizeResponsesInput(body.input);
+    if (normalized) body.input = normalized;
+
+    // Ensure input is present and non-empty (Codex API rejects empty input)
+    if (!body.input || (Array.isArray(body.input) && body.input.length === 0)) {
+      body.input = [{ type: "message", role: "user", content: [{ type: "input_text", text: "..." }] }];
+    }
+
+    // Keep system prompts in body.input as role=developer so they stay in the cacheable prefix
+    convertSystemToDeveloperRole(body);
+    // Strip server-generated item IDs (rs_/fc_/resp_/msg_) — Codex /responses can't resolve when store=false
+    stripStoredItemReferences(body);
+    // Flatten function tools + drop unsupported types
+    normalizeCodexTools(body);
+
+    // Ensure streaming is enabled (Codex API requires it)
+    body.stream = true;
+
+    // If no instructions provided, inject default Codex instructions
+    if (!body.instructions || body.instructions.trim() === "") {
+      body.instructions = CODEX_DEFAULT_INSTRUCTIONS;
+    }
+
+    // Ensure store is false (Codex requirement)
+    body.store = false;
+
+    // Inject prompt_cache_key for stable Codex prompt caching
+    if (!body.prompt_cache_key && this._currentSessionId) {
+      body.prompt_cache_key = this._currentSessionId;
+    }
+
+    // Map virtual Codex review models to the upstream Codex model before suffix parsing.
+    body.model = getModelUpstreamId("cx", body.model || model);
+
+    // Extract thinking level from model name suffix
+    // e.g., gpt-5.3-codex-high → high, gpt-5.3-codex → medium (default)
+    const effortLevels = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'];
+    let modelEffort = null;
+    for (const level of effortLevels) {
+      if (body.model.endsWith(`-${level}`)) {
+        modelEffort = level;
+        // Strip suffix from model name for actual API call
+        body.model = body.model.replace(`-${level}`, '');
+        break;
+      }
+    }
+
+    // Priority: explicit reasoning.effort > reasoning_effort param > model suffix > default (medium)
+    if (!body.reasoning) {
+      const effort = normalizeReasoningEffort(body.reasoning_effort || modelEffort || 'low');
+      body.reasoning = { effort, summary: "auto" };
+    } else {
+      body.reasoning.effort = normalizeReasoningEffort(body.reasoning.effort);
+      if (!body.reasoning.summary) body.reasoning.summary = "auto";
+    }
+    delete body.reasoning_effort;
+
+    // Include reasoning encrypted content (required by Codex backend for reasoning models)
+    if (body.reasoning && body.reasoning.effort && body.reasoning.effort !== 'none') {
+      body.include = ["reasoning.encrypted_content"];
+    }
+
+    // Remove unsupported parameters for Codex API
+    delete body.temperature;
+    delete body.top_p;
+    delete body.frequency_penalty;
+    delete body.presence_penalty;
+    delete body.logprobs;
+    delete body.top_logprobs;
+    delete body.n;
+    delete body.seed;
+    delete body.max_tokens;
+    delete body.max_completion_tokens;
+    delete body.max_output_tokens; // Responses API clients send this but Codex rejects it
+    delete body.user; // Cursor sends this but Codex doesn't support it
+    delete body.prompt_cache_retention; // Cursor sends this but Codex doesn't support it
+    delete body.metadata; // Cursor sends this but Codex doesn't support it
+    delete body.stream_options; // Cursor sends this but Codex doesn't support it
+    delete body.safety_identifier; // Droid CLI sends this but Codex doesn't support it
+    delete body.previous_response_id; // store=false → backend can't resolve previous resp; avoid 404
+
+    if (body.service_tier === "fast") body.service_tier = "priority";
+    if (body.service_tier && body.service_tier !== "priority") delete body.service_tier;
+
+    // Final allowlist filter — strip any unknown field that could trigger upstream "routing_unsupported"
+    for (const k of Object.keys(body)) {
+      if (!RESPONSES_API_ALLOWLIST.has(k)) delete body[k];
+    }
+
+    return body;
+  }
+}
diff --git a/open-sse/executors/commandcode.js b/open-sse/executors/commandcode.js
new file mode 100644
index 0000000..aad4043
--- /dev/null
+++ b/open-sse/executors/commandcode.js
@@ -0,0 +1,94 @@
+import { randomUUID } from "crypto";
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { commandCodeToOpenAIResponse } from "../translator/response/commandcode-to-openai.js";
+import { SSE_DONE } from "../utils/sseConstants.js";
+
+/**
+ * CommandCodeExecutor — talks to https://api.commandcode.ai/alpha/generate
+ *
+ * Auth: Bearer <user_xxx> API key (stored as the connection's apiKey).
+ * Adds the per-request `x-session-id` header expected by CommandCode upstream.
+ *
+ * Upstream returns AI SDK v5 NDJSON (one JSON event per line, no `data:` prefix).
+ * We translate each event to an OpenAI chat.completion.chunk and emit it as SSE so
+ * both the streaming and non-streaming (forced SSE → JSON) downstream handlers in
+ * 9router can consume it without further format translation.
+ */
+export class CommandCodeExecutor extends BaseExecutor {
+  constructor() {
+    super("commandcode", PROVIDERS.commandcode);
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    body.stream = true;
+    return body;
+  }
+
+  buildHeaders(credentials, stream = true) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...(this.config.headers || {}),
+      "x-session-id": randomUUID(),
+    };
+
+    const token = credentials?.apiKey || credentials?.accessToken;
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+
+    if (stream) headers["Accept"] = "text/event-stream";
+    return headers;
+  }
+
+  async execute(opts) {
+    const result = await super.execute(opts);
+    if (!result?.response?.ok || !result.response.body) return result;
+    result.response = wrapNdjsonAsOpenAISse(result.response, opts.model);
+    return result;
+  }
+}
+
+function wrapNdjsonAsOpenAISse(originalResponse, model) {
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let buffer = "";
+  const state = { model };
+
+  const emitChunks = (chunks, controller) => {
+    if (!chunks) return;
+    const list = Array.isArray(chunks) ? chunks : [chunks];
+    for (const c of list) {
+      if (c == null) continue;
+      controller.enqueue(encoder.encode(`data: ${JSON.stringify(c)}\n\n`));
+    }
+  };
+
+  const transform = new TransformStream({
+    transform(chunk, controller) {
+      buffer += decoder.decode(chunk, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        // Translate AI SDK v5 NDJSON line to one or more OpenAI chunks
+        emitChunks(commandCodeToOpenAIResponse(trimmed, state), controller);
+      }
+    },
+    flush(controller) {
+      const trimmed = buffer.trim();
+      if (trimmed) {
+        emitChunks(commandCodeToOpenAIResponse(trimmed, state), controller);
+      }
+      controller.enqueue(encoder.encode(SSE_DONE));
+    },
+  });
+
+  const newBody = originalResponse.body.pipeThrough(transform);
+  return new Response(newBody, {
+    status: originalResponse.status,
+    statusText: originalResponse.statusText,
+    headers: originalResponse.headers,
+  });
+}
+
+export default CommandCodeExecutor;
diff --git a/open-sse/executors/cursor.js b/open-sse/executors/cursor.js
new file mode 100644
index 0000000..fe06d80
--- /dev/null
+++ b/open-sse/executors/cursor.js
@@ -0,0 +1,688 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { HTTP_STATUS } from "../config/runtimeConfig.js";
+import {
+  generateCursorBody,
+  parseConnectRPCFrame,
+  extractTextFromResponse
+} from "../utils/cursorProtobuf.js";
+import { buildCursorHeaders } from "../utils/cursorChecksum.js";
+import { estimateUsage } from "../utils/usageTracking.js";
+import { SSE_DONE, SSE_HEADERS } from "../utils/sseConstants.js";
+import { chatChunkSse } from "../utils/sse.js";
+import { FORMATS } from "../translator/formats.js";
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+import zlib from "zlib";
+
+// Detect cloud environment
+const isCloudEnv = () => {
+  if (typeof caches !== "undefined" && typeof caches === "object") return true;
+  if (typeof EdgeRuntime !== "undefined") return true;
+  return false;
+};
+
+// Lazy import http2 (only in Node.js environment)
+let http2 = null;
+if (!isCloudEnv()) {
+  try {
+    http2 = await import("http2");
+  } catch {
+    // http2 not available
+  }
+}
+
+const COMPRESS_FLAG = {
+  NONE: 0x00,
+  GZIP: 0x01,
+  TRAILER: 0x02,
+  GZIP_TRAILER: 0x03
+};
+
+const CURSOR_STREAM_DEBUG = process.env.CURSOR_STREAM_DEBUG === "1";
+const debugLog = (...args) => {
+  if (CURSOR_STREAM_DEBUG) console.log(...args);
+};
+
+function isComposerModel(model) {
+  const modelId = String(model || "").split("/").pop();
+  return /^composer(?:-|$)/i.test(modelId);
+}
+
+function visibleComposerContentFromThinking(thinking) {
+  if (!thinking) return "";
+  const endTag = "</think>";
+  const endIdx = thinking.lastIndexOf(endTag);
+  if (endIdx < 0) return "";
+  return thinking.slice(endIdx + endTag.length).trimStart();
+}
+
+function decompressPayload(payload, flags) {
+  // Check if payload is JSON error (starts with {"error")
+  if (payload.length > 10 && payload[0] === 0x7b && payload[1] === 0x22) {
+    try {
+      const text = payload.toString("utf-8");
+      if (text.startsWith('{"error"')) {
+        debugLog(`[DECOMPRESS] Detected JSON error, skipping decompression`);
+        return payload;
+      }
+    } catch {}
+  }
+
+  if (
+    flags === COMPRESS_FLAG.GZIP ||
+    flags === COMPRESS_FLAG.TRAILER ||
+    flags === COMPRESS_FLAG.GZIP_TRAILER
+  ) {
+    // Primary: try gzip decompression (standard gzip header 0x1f 0x8b)
+    try {
+      return zlib.gunzipSync(payload);
+    } catch (gzipErr) {
+      // Fallback: TRAILER and GZIP_TRAILER frames sometimes use raw zlib deflate format
+      try {
+        return zlib.inflateSync(payload);
+      } catch (deflateErr) {
+        // Last resort: try raw deflate (no zlib header)
+        try {
+          return zlib.inflateRawSync(payload);
+        } catch (rawErr) {
+          debugLog(
+            `[DECOMPRESS ERROR] flags=${flags}, payloadSize=${payload.length}, gzip=${gzipErr.message}, deflate=${deflateErr.message}, raw=${rawErr.message}`
+          );
+          debugLog(
+            `[DECOMPRESS ERROR] First 50 bytes (hex):`,
+            payload.slice(0, 50).toString("hex")
+          );
+          return payload;
+        }
+      }
+    }
+  }
+  return payload;
+}
+
+// Read one cursor protobuf frame: header + bounds + decompress. Returns status + payload + new offset.
+function readCursorFrame(buffer, offset, frameNum, tag) {
+  if (offset + 5 > buffer.length) {
+    debugLog(`[CURSOR BUFFER${tag}] Reached end, offset=${offset}, remaining=${buffer.length - offset}`);
+    return { status: "done" };
+  }
+
+  const flags = buffer[offset];
+  const length = buffer.readUInt32BE(offset + 1);
+  debugLog(`[CURSOR BUFFER${tag}] Frame ${frameNum + 1}: flags=0x${flags.toString(16).padStart(2, "0")}, length=${length}`);
+
+  if (offset + 5 + length > buffer.length) {
+    debugLog(`[CURSOR BUFFER${tag}] Incomplete frame, offset=${offset}, length=${length}, buffer.length=${buffer.length}`);
+    return { status: "done" };
+  }
+
+  let payload = buffer.slice(offset + 5, offset + 5 + length);
+  const newOffset = offset + 5 + length;
+  payload = decompressPayload(payload, flags);
+  if (!payload) {
+    debugLog(`[CURSOR BUFFER${tag}] Frame ${frameNum + 1}: decompression failed, skipping`);
+    return { status: "skip", offset: newOffset };
+  }
+  return { status: "ok", payload, offset: newOffset };
+}
+
+function createErrorResponse(jsonError) {
+  const errorMsg = jsonError?.error?.details?.[0]?.debug?.details?.title
+    || jsonError?.error?.details?.[0]?.debug?.details?.detail
+    || jsonError?.error?.message
+    || "API Error";
+  
+  const isRateLimit = jsonError?.error?.code === "resource_exhausted";
+  
+  return new Response(JSON.stringify({
+    error: {
+      message: errorMsg,
+      type: isRateLimit ? "rate_limit_error" : "api_error",
+      code: jsonError?.error?.details?.[0]?.debug?.error || "unknown"
+    }
+  }), {
+    status: isRateLimit ? HTTP_STATUS.RATE_LIMITED : HTTP_STATUS.BAD_REQUEST,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+
+export class CursorExecutor extends BaseExecutor {
+  constructor() {
+    super("cursor", PROVIDERS.cursor);
+  }
+
+  buildUrl() {
+    return `${this.config.baseUrl}${this.config.chatPath}`;
+  }
+
+  buildHeaders(credentials) {
+    const accessToken = credentials.accessToken;
+    const machineId = credentials.providerSpecificData?.machineId;
+    const ghostMode = credentials.providerSpecificData?.ghostMode !== false;
+
+    if (!machineId) {
+      throw new Error("Machine ID is required for Cursor API");
+    }
+
+    return buildCursorHeaders(accessToken, machineId, ghostMode);
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    // Messages are already translated by chatCore (claude→openai→cursor)
+    // Do NOT call openaiToCursorRequest again — double-translation drops tool_results
+    const messages = body.messages || [];
+    const tools = body.tools || [];
+    const reasoningEffort = body.reasoning_effort || null;
+    // Detect Claude Code UA to force Agent mode (issue #643)
+    const ua = credentials?.rawHeaders?.["user-agent"] || "";
+    const forceAgentMode = ua.includes("claude-cli") || ua.includes("claude-code") || ua.includes("Claude Code");
+    return generateCursorBody(messages, model, tools, reasoningEffort, forceAgentMode);
+  }
+
+  async makeFetchRequest(url, headers, body, signal, proxyOptions = null) {
+    const response = await proxyAwareFetch(url, {
+      method: "POST",
+      headers,
+      body,
+      signal
+    }, proxyOptions);
+
+    return {
+      status: response.status,
+      headers: Object.fromEntries(response.headers.entries()),
+      body: Buffer.from(await response.arrayBuffer())
+    };
+  }
+
+  makeHttp2Request(url, headers, body, signal) {
+    if (!http2) {
+      throw new Error("http2 module not available");
+    }
+
+    const HTTP2_TIMEOUT_MS = 60000; // 60s max — prevent hung sessions
+
+    return new Promise((resolve, reject) => {
+      const urlObj = new URL(url);
+      const client = http2.connect(`https://${urlObj.host}`);
+      const chunks = [];
+      let responseHeaders = {};
+      let settled = false;
+
+      // Ensure client is always closed on settle
+      const finish = (fn) => (...args) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(hangTimeout);
+        client.close();
+        fn(...args);
+      };
+
+      // Hard timeout: close session if server never responds
+      const hangTimeout = setTimeout(finish(() => {
+        reject(new Error("HTTP/2 request timed out"));
+      }), HTTP2_TIMEOUT_MS);
+
+      client.on("error", finish(reject));
+
+      const req = client.request({
+        ":method": "POST",
+        ":path": urlObj.pathname,
+        ":authority": urlObj.host,
+        ":scheme": "https",
+        ...headers
+      });
+
+      req.on("response", (hdrs) => { responseHeaders = hdrs; });
+      req.on("data", (chunk) => { chunks.push(chunk); });
+      req.on("end", finish(() => {
+        resolve({
+          status: responseHeaders[":status"],
+          headers: responseHeaders,
+          body: Buffer.concat(chunks)
+        });
+      }));
+      req.on("error", finish(reject));
+
+      if (signal) {
+        const onAbort = finish(() => reject(new Error("Request aborted")));
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+
+      req.write(body);
+      req.end();
+    });
+  }
+
+  async execute({ model, body, stream, credentials, signal, log, proxyOptions = null }) {
+    const url = this.buildUrl();
+    const headers = this.buildHeaders(credentials);
+    const transformedBody = this.transformRequest(model, body, stream, credentials);
+
+    try {
+      const shouldForceFetch = proxyOptions?.enabled === true || proxyOptions?.connectionProxyEnabled === true || !!proxyOptions?.vercelRelayUrl;
+      const response = (http2 && !shouldForceFetch)
+        ? await this.makeHttp2Request(url, headers, transformedBody, signal)
+        : await this.makeFetchRequest(url, headers, transformedBody, signal, proxyOptions);
+
+      if (response.status !== 200) {
+        const errorText = response.body?.toString() || "Unknown error";
+        const errorResponse = new Response(JSON.stringify({
+          error: {
+            message: `[${response.status}]: ${errorText}`,
+            type: "invalid_request_error",
+            code: ""
+          }
+        }), {
+          status: response.status,
+          headers: { "Content-Type": "application/json" }
+        });
+        return { response: errorResponse, url, headers, transformedBody: body };
+      }
+
+      const transformedResponse = stream !== false
+        ? this.transformProtobufToSSE(response.body, model, body)
+        : this.transformProtobufToJSON(response.body, model, body);
+
+      return { response: transformedResponse, url, headers, transformedBody: body };
+    } catch (error) {
+      const errorResponse = new Response(JSON.stringify({
+        error: {
+          message: error.message,
+          type: "connection_error",
+          code: ""
+        }
+      }), {
+        status: HTTP_STATUS.SERVER_ERROR,
+        headers: { "Content-Type": "application/json" }
+      });
+      return { response: errorResponse, url, headers, transformedBody: body };
+    }
+  }
+
+  transformProtobufToJSON(buffer, model, body) {
+    const responseId = `chatcmpl-cursor-${Date.now()}`;
+    const created = Math.floor(Date.now() / 1000);
+
+    let offset = 0;
+    let totalContent = "";
+    let totalThinking = "";
+    const toolCalls = [];
+    const toolCallsMap = new Map(); // Track streaming tool calls by ID
+    const finalizedIds = new Set();
+    let frameCount = 0;
+
+    debugLog(`[CURSOR BUFFER] Total length: ${buffer.length} bytes`);
+
+    while (offset < buffer.length) {
+      const frame = readCursorFrame(buffer, offset, frameCount, "");
+      if (frame.status === "done") break;
+      offset = frame.offset;
+      frameCount++;
+      if (frame.status === "skip") continue;
+      const payload = frame.payload;
+
+      // Check for JSON error frames (byte guard: skip toString on non-JSON frames)
+      if (payload.length > 0 && payload[0] === 0x7b) {
+        try {
+          const text = payload.toString("utf-8");
+          if (text.includes('"error"')) {
+            const hasContent = totalContent || toolCallsMap.size > 0;
+            debugLog(
+              `[CURSOR BUFFER] Error frame (hasContent=${hasContent}): ${text.slice(0, 500)}`
+            );
+            if (hasContent) {
+              break;
+            }
+            return createErrorResponse(JSON.parse(text));
+          }
+        } catch {}
+      }
+
+      const result = extractTextFromResponse(new Uint8Array(payload));
+      debugLog(`[CURSOR DECODED] Frame ${frameCount}:`, result);
+
+      if (result.error) {
+        const hasContent = totalContent || toolCallsMap.size > 0;
+        debugLog(`[CURSOR BUFFER] Decoded error (hasContent=${hasContent}): ${result.error}`);
+        if (hasContent) {
+          break;
+        }
+        return new Response(
+          JSON.stringify({
+            error: {
+              message: result.error,
+              type: "rate_limit_error",
+              code: "rate_limited"
+            }
+          }),
+          {
+            status: HTTP_STATUS.RATE_LIMITED,
+            headers: { "Content-Type": "application/json" }
+          }
+        );
+      }
+
+      if (result.toolCall) {
+        const tc = result.toolCall;
+
+        if (toolCallsMap.has(tc.id)) {
+          // Accumulate arguments for existing tool call
+          const existing = toolCallsMap.get(tc.id);
+          existing.function.arguments += tc.function.arguments;
+          existing.isLast = tc.isLast;
+        } else {
+          // New tool call
+          toolCallsMap.set(tc.id, { ...tc });
+        }
+
+        // Push to final array when isLast is true
+        if (tc.isLast) {
+          const finalToolCall = toolCallsMap.get(tc.id);
+          finalizedIds.add(tc.id);
+          toolCalls.push({
+            id: finalToolCall.id,
+            type: finalToolCall.type,
+            function: {
+              name: finalToolCall.function.name,
+              arguments: finalToolCall.function.arguments
+            }
+          });
+        }
+      }
+
+      if (result.text) totalContent += result.text;
+      if (result.thinking) totalThinking += result.thinking;
+    }
+
+    const visibleComposerContent = isComposerModel(model)
+      ? visibleComposerContentFromThinking(totalThinking)
+      : "";
+    const finalContent = totalContent || visibleComposerContent;
+
+    debugLog(
+      `[CURSOR BUFFER] Parsed ${frameCount} frames, toolCallsMap size: ${toolCallsMap.size}, finalized toolCalls: ${toolCalls.length}`
+    );
+
+    // Finalize all remaining tool calls in map (in case stream ended without isLast=true)
+    for (const [id, tc] of toolCallsMap.entries()) {
+      // Check if already in final array
+      if (!finalizedIds.has(id)) {
+        debugLog(`[CURSOR BUFFER] Finalizing incomplete tool call: ${id}, isLast=${tc.isLast}`);
+        toolCalls.push({
+          id: tc.id,
+          type: tc.type,
+          function: {
+            name: tc.function.name,
+            arguments: tc.function.arguments
+          }
+        });
+      }
+    }
+
+    debugLog(`[CURSOR BUFFER] Final toolCalls count: ${toolCalls.length}`);
+
+
+    const message = {
+      role: "assistant",
+      content: finalContent || null
+    };
+
+    if (toolCalls.length > 0) {
+      message.tool_calls = toolCalls;
+    }
+
+    const usage = estimateUsage(body, finalContent.length, FORMATS.OPENAI);
+
+    const completion = {
+      id: responseId,
+      object: "chat.completion",
+      created,
+      model,
+      choices: [{
+        index: 0,
+        message,
+        finish_reason: toolCalls.length > 0 ? "tool_calls" : "stop"
+      }],
+      usage
+    };
+
+    return new Response(JSON.stringify(completion), {
+      status: 200,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+
+  transformProtobufToSSE(buffer, model, body) {
+    const responseId = `chatcmpl-cursor-${Date.now()}`;
+    const created = Math.floor(Date.now() / 1000);
+
+    const chunks = [];
+    let offset = 0;
+    let totalContent = "";
+    let totalThinking = "";
+    let emittedComposerThinkingContentLength = 0;
+    const toolCalls = [];
+    const toolCallsMap = new Map(); // Track streaming tool calls by ID
+    const finalizedIds = new Set();
+    const emittedToolCallIds = new Set();
+    let frameCount = 0;
+
+    debugLog(`[CURSOR BUFFER SSE] Total length: ${buffer.length} bytes`);
+
+    while (offset < buffer.length) {
+      const frame = readCursorFrame(buffer, offset, frameCount, " SSE");
+      if (frame.status === "done") break;
+      offset = frame.offset;
+      frameCount++;
+      if (frame.status === "skip") continue;
+      const payload = frame.payload;
+
+      // Check for JSON error frames (byte-guard: only decode if starts with '{')
+      if (payload[0] === 0x7b) {
+        try {
+          const text = payload.toString("utf-8");
+          if (text.includes('"error"')) {
+            const hasContent = chunks.length > 0 || totalContent || toolCallsMap.size > 0;
+            debugLog(
+              `[CURSOR BUFFER SSE] Error frame (hasContent=${hasContent}): ${text.slice(0, 500)}`
+            );
+            if (hasContent) {
+              break;
+            }
+            return createErrorResponse(JSON.parse(text));
+          }
+        } catch {}
+      }
+
+      const result = extractTextFromResponse(new Uint8Array(payload));
+      debugLog(`[CURSOR DECODED SSE] Frame ${frameCount}:`, result);
+
+      if (result.error) {
+        const hasContent = chunks.length > 0 || totalContent || toolCallsMap.size > 0;
+        debugLog(`[CURSOR BUFFER SSE] Decoded error (hasContent=${hasContent}): ${result.error}`);
+        if (hasContent) {
+          break;
+        }
+        return new Response(
+          JSON.stringify({
+            error: {
+              message: result.error,
+              type: "rate_limit_error",
+              code: "rate_limited"
+            }
+          }),
+          {
+            status: HTTP_STATUS.RATE_LIMITED,
+            headers: { "Content-Type": "application/json" }
+          }
+        );
+      }
+
+      if (result.toolCall) {
+        const tc = result.toolCall;
+
+        if (chunks.length === 0) {
+          chunks.push(chatChunkSse({ id: responseId, created, model, delta: { role: "assistant", content: "" } }));
+        }
+
+        if (toolCallsMap.has(tc.id)) {
+          // Accumulate arguments for existing tool call
+          const existing = toolCallsMap.get(tc.id);
+          const oldArgsLen = existing.function.arguments.length;
+          existing.function.arguments += tc.function.arguments;
+          existing.isLast = tc.isLast;
+
+          // Stream the delta arguments
+          if (tc.function.arguments) {
+            emittedToolCallIds.add(tc.id);
+            chunks.push(chatChunkSse({
+              id: responseId, created, model,
+              delta: {
+                tool_calls: [
+                  {
+                    index: existing.index,
+                    id: tc.id,
+                    type: "function",
+                    function: {
+                      name: tc.function.name,
+                      arguments: tc.function.arguments
+                    }
+                  }
+                ]
+              }
+            }));
+          }
+        } else {
+          // New tool call - assign index and add to map
+          const toolCallIndex = toolCalls.length;
+          finalizedIds.add(tc.id);
+          toolCalls.push({ ...tc, index: toolCallIndex });
+          toolCallsMap.set(tc.id, { ...tc, index: toolCallIndex });
+
+          // Stream initial tool call with name
+          emittedToolCallIds.add(tc.id);
+          chunks.push(chatChunkSse({
+            id: responseId, created, model,
+            delta: {
+              tool_calls: [
+                {
+                  index: toolCallIndex,
+                  id: tc.id,
+                  type: "function",
+                  function: {
+                    name: tc.function.name,
+                    arguments: tc.function.arguments
+                  }
+                }
+              ]
+            }
+          }));
+        }
+      }
+
+      if (result.text) {
+        totalContent += result.text;
+        chunks.push(chatChunkSse({
+          id: responseId, created, model,
+          delta:
+            chunks.length === 0 && toolCalls.length === 0
+              ? { role: "assistant", content: result.text }
+              : { content: result.text }
+        }));
+      }
+
+      if (isComposerModel(model) && result.thinking) {
+        totalThinking += result.thinking;
+        const visibleContent = visibleComposerContentFromThinking(totalThinking);
+        if (visibleContent.length > emittedComposerThinkingContentLength) {
+          const deltaContent = visibleContent.slice(emittedComposerThinkingContentLength);
+          emittedComposerThinkingContentLength = visibleContent.length;
+          totalContent += deltaContent;
+          chunks.push(chatChunkSse({
+            id: responseId, created, model,
+            delta:
+              chunks.length === 0 && toolCalls.length === 0
+                ? { role: "assistant", content: deltaContent }
+                : { content: deltaContent }
+          }));
+        }
+      }
+    }
+
+    debugLog(
+      `[CURSOR BUFFER SSE] Parsed ${frameCount} frames, toolCallsMap size: ${toolCallsMap.size}, toolCalls array: ${toolCalls.length}`
+    );
+
+    // Finalize all remaining tool calls in map (stream may have ended without isLast=true)
+    for (const [id, tc] of toolCallsMap.entries()) {
+      if (!finalizedIds.has(id)) {
+        debugLog(`[CURSOR BUFFER SSE] Finalizing incomplete tool call: ${id}, isLast=${tc.isLast}`);
+        const toolCallIndex = toolCalls.length;
+        toolCalls.push({
+          id: tc.id,
+          type: tc.type,
+          index: toolCallIndex,
+          function: {
+            name: tc.function.name,
+            arguments: tc.function.arguments
+          }
+        });
+
+        // Emit SSE chunk for the finalized tool call if not already emitted
+        if (!emittedToolCallIds.has(tc.id)) {
+          chunks.push(chatChunkSse({
+            id: responseId, created, model,
+            delta: {
+              tool_calls: [
+                {
+                  index: toolCallIndex,
+                  id: tc.id,
+                  type: "function",
+                  function: {
+                    name: tc.function.name,
+                    arguments: tc.function.arguments
+                  }
+                }
+              ]
+            }
+          }));
+        }
+      }
+    }
+
+    if (chunks.length === 0 && toolCalls.length === 0) {
+      chunks.push(chatChunkSse({ id: responseId, created, model, delta: { role: "assistant", content: "" } }));
+    }
+
+    const usage = estimateUsage(body, totalContent.length, FORMATS.OPENAI);
+
+    chunks.push(
+      `data: ${JSON.stringify({
+        id: responseId,
+        object: "chat.completion.chunk",
+        created,
+        model,
+        choices: [
+          {
+            index: 0,
+            delta: {},
+            finish_reason: toolCalls.length > 0 ? "tool_calls" : "stop"
+          }
+        ],
+        usage
+      })}\n\n`
+    );
+    chunks.push(SSE_DONE);
+
+    return new Response(chunks.join(""), {
+      status: 200,
+      headers: { ...SSE_HEADERS }
+    });
+  }
+
+  async refreshCredentials() {
+    return null;
+  }
+}
+
+export default CursorExecutor;
diff --git a/open-sse/executors/default.js b/open-sse/executors/default.js
new file mode 100644
index 0000000..96a230b
--- /dev/null
+++ b/open-sse/executors/default.js
@@ -0,0 +1,332 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS, PROVIDER_OAUTH } from "../config/providers.js";
+import { ANTHROPIC_API_VERSION, OPENAI_COMPAT_BASE, ANTHROPIC_COMPAT_BASE } from "../providers/shared.js";
+import { OAUTH_ENDPOINTS, buildKimiHeaders } from "../config/appConstants.js";
+import { buildClineHeaders } from "../shared/clineAuth.js";
+import { getCachedClaudeHeaders } from "../utils/claudeHeaderCache.js";
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+import { injectReasoningContent } from "../utils/reasoningContentInjector.js";
+import { stripUnsupportedParams } from "../translator/concerns/paramSupport.js";
+
+// Auth header descriptors — derived from registry transport.auth, fallback to hardcoded defaults.
+const BEARER = { combined: true, header: "Authorization", scheme: "bearer" };
+const XAPIKEY = { combined: true, header: "x-api-key", scheme: "raw" };
+const AUTH_DESCRIPTORS = Object.fromEntries(
+  Object.entries(PROVIDERS)
+    .filter(([, t]) => t.auth)
+    .map(([id, t]) => [id, t.auth])
+);
+
+// Apply a token to a header per scheme (matches legacy: combined always sets, even when undefined).
+function setAuth(headers, spec, token) {
+  headers[spec.header] = spec.scheme === "bearer" ? `Bearer ${token}` : token;
+}
+
+// Resolve auth onto headers from a descriptor.
+function applyAuth(headers, desc, credentials) {
+  if (desc.combined) {
+    // combined providers always set the header (legacy behavior, incl. noAuth → "Bearer undefined")
+    setAuth(headers, desc, credentials.apiKey || credentials.accessToken);
+    if (desc.anthropicVersion && !headers["anthropic-version"]) headers["anthropic-version"] = ANTHROPIC_API_VERSION;
+    return;
+  }
+  // split apiKey/oauth: set only the matching branch (legacy: anthropic-compatible skips when both absent)
+  if (credentials.apiKey) setAuth(headers, desc.apiKey, credentials.apiKey);
+  else if (credentials.accessToken) setAuth(headers, desc.oauth, credentials.accessToken);
+  if (desc.anthropicVersion && !headers["anthropic-version"]) headers["anthropic-version"] = ANTHROPIC_API_VERSION;
+}
+
+// Provider-specific header quirks kept as small hooks (not pure auth).
+const HEADER_HOOKS = {
+  kimiHeaders: (h) => Object.assign(h, buildKimiHeaders()),
+  clineHeaders: (h, c) => Object.assign(h, buildClineHeaders(c.apiKey || c.accessToken)),
+  kilocodeOrg: (h, c) => { if (c.providerSpecificData?.orgId) h["X-Kilocode-OrganizationID"] = c.providerSpecificData.orgId; },
+  claudeOverlay: (h) => {
+    const cached = getCachedClaudeHeaders();
+    if (!cached) return;
+    for (const lcKey of Object.keys(cached)) {
+      const titleKey = lcKey.replace(/(^|-)([a-z])/g, (_, sep, ch) => sep + ch.toUpperCase());
+      if (lcKey === "anthropic-beta") {
+        const staticBetaStr = h[titleKey] || h[lcKey] || "";
+        const flags = new Set(staticBetaStr.split(",").map(f => f.trim()).filter(Boolean));
+        for (const f of cached[lcKey].split(",").map(f => f.trim()).filter(Boolean)) flags.add(f);
+        cached[lcKey] = Array.from(flags).join(",");
+      }
+      if (titleKey !== lcKey && h[titleKey] !== undefined) delete h[titleKey];
+    }
+    Object.assign(h, cached);
+  },
+};
+
+// Config-driven OAuth refresh grants — derived from registry oauth.refresh.
+const REFRESH_GRANTS = Object.fromEntries(
+  Object.entries(PROVIDER_OAUTH)
+    .filter(([, o]) => o.refresh)
+    .map(([id, o]) => {
+      const tokenUrl = o.tokenUrl;
+      const encoding = o.refresh.encoding;
+      const extraParams = o.refresh.scope ? { scope: o.refresh.scope } : {};
+      return [id, {
+        encoding,
+        url: () => tokenUrl,
+        params: (ex) => id === "gemini"
+          ? { client_id: ex.config.clientId, client_secret: ex.config.clientSecret, ...extraParams }
+          : { client_id: o.clientId, ...extraParams },
+      }];
+    })
+);
+
+export class DefaultExecutor extends BaseExecutor {
+  constructor(provider) {
+    super(provider, PROVIDERS[provider] || PROVIDERS.openai);
+  }
+
+  transformRequest(model, body) {
+    const transformed = this.applyJsonSchemaFallback(body);
+
+    if (transformed && typeof transformed === "object") {
+      // quirk: some openai-compatible providers reject Anthropic's client_metadata field
+      if (this.config.quirks?.dropClientMetadata) {
+        delete transformed.client_metadata;
+      }
+      stripUnsupportedParams(this.provider, model, transformed);
+    }
+
+    return injectReasoningContent({ provider: this.provider, model, body: transformed });
+  }
+
+  // Fallback json_schema → json_object for openai-compatible providers without native Structured Output.
+  applyJsonSchemaFallback(body) {
+    if (!this.provider?.startsWith?.("openai-compatible-")) return body;
+    const rf = body?.response_format;
+    if (rf?.type !== "json_schema" || !rf.json_schema?.schema) return body;
+
+    const schemaJson = JSON.stringify(rf.json_schema.schema, null, 2);
+    const prompt = `You must respond with valid JSON that strictly follows this JSON schema:\n\`\`\`json\n${schemaJson}\n\`\`\`\nRespond ONLY with the JSON object, no other text.`;
+
+    const messages = Array.isArray(body.messages) ? body.messages.map(m => ({ ...m })) : [];
+    const sys = messages.find(m => m.role === "system");
+    if (sys) {
+      if (typeof sys.content === "string") sys.content = `${sys.content}\n\n${prompt}`;
+      else if (Array.isArray(sys.content)) sys.content.push({ type: "text", text: `\n\n${prompt}` });
+    } else {
+      messages.unshift({ role: "system", content: prompt });
+    }
+    return { ...body, messages, response_format: { type: "json_object" } };
+  }
+
+  buildUrl(model, stream, urlIndex = 0, credentials = null) {
+    // Runtime transport (multi-endpoint providers): use the sourceFormat-matched endpoint
+    const rt = credentials?.runtimeTransport;
+    if (rt?.baseUrl) {
+      return rt.urlSuffix ? `${rt.baseUrl}${rt.urlSuffix}` : rt.baseUrl;
+    }
+    if (this.provider?.startsWith?.("openai-compatible-")) {
+      const baseUrl = credentials?.providerSpecificData?.baseUrl || OPENAI_COMPAT_BASE;
+      const normalized = baseUrl.replace(/\/$/, "");
+      const path = this.provider.includes("responses") ? "/responses" : "/chat/completions";
+      return `${normalized}${path}`;
+    }
+    if (this.provider?.startsWith?.("anthropic-compatible-")) {
+      const baseUrl = credentials?.providerSpecificData?.baseUrl || ANTHROPIC_COMPAT_BASE;
+      const normalized = baseUrl.replace(/\/$/, "");
+      return `${normalized}/messages`;
+    }
+    // gemini-format: build :streamGenerateContent / :generateContent path
+    if (this.config.format === "gemini") {
+      return `${this.config.baseUrl}/${model}:${stream ? "streamGenerateContent?alt=sse" : "generateContent"}`;
+    }
+    // urlSuffix (e.g. ?beta=true) declared per-provider in registry
+    if (this.config.urlSuffix) {
+      return `${this.config.baseUrl}${this.config.urlSuffix}`;
+    }
+    const url = this.config.baseUrl;
+    if (url?.includes("{accountId}")) {
+      const accountId = credentials?.providerSpecificData?.accountId;
+      if (!accountId) throw new Error(`${this.provider} requires accountId in providerSpecificData`);
+      return url.replace("{accountId}", accountId);
+    }
+    return url;
+  }
+
+  // Fallback descriptor for providers without an explicit entry in AUTH_DESCRIPTORS.
+  resolveAuthDescriptor() {
+    if (this.provider?.startsWith?.("anthropic-compatible-")) {
+      return { apiKey: { header: "x-api-key", scheme: "raw" }, oauth: { header: "Authorization", scheme: "bearer" }, anthropicVersion: true };
+    }
+    if (this.config?.format === "claude") {
+      return { ...XAPIKEY, anthropicVersion: true };
+    }
+    return BEARER;
+  }
+
+  buildHeaders(credentials, stream = true) {
+    const rt = credentials?.runtimeTransport;
+    const headers = { "Content-Type": "application/json", ...(rt ? rt.headers : this.config.headers) };
+    const desc = rt?.auth || AUTH_DESCRIPTORS[this.provider] || this.resolveAuthDescriptor();
+    // Hooks run BEFORE auth so dynamic overlays (claude cached headers) can't clobber the token.
+    for (const hook of desc.hooks || []) HEADER_HOOKS[hook]?.(headers, credentials);
+    applyAuth(headers, desc, credentials);
+
+    // Strip first-party Claude Code identity headers for non-Anthropic anthropic-compatible upstreams
+    if (this.provider?.startsWith?.("anthropic-compatible-")) {
+      const baseUrl = credentials?.providerSpecificData?.baseUrl || "";
+      const isOfficialAnthropic = baseUrl === "" || baseUrl.includes("api.anthropic.com");
+      if (!isOfficialAnthropic) {
+        // Some third-party Anthropic-compatible gateways require Bearer auth in
+        // addition to x-api-key. Send both (x-api-key already set above) so
+        // gateways that read either header succeed.
+        if (credentials.apiKey && !headers["Authorization"]) {
+          headers["Authorization"] = `Bearer ${credentials.apiKey}`;
+        }
+        delete headers["anthropic-dangerous-direct-browser-access"];
+        delete headers["Anthropic-Dangerous-Direct-Browser-Access"];
+        delete headers["x-app"];
+        delete headers["X-App"];
+        // Strip claude-code-20250219 from Anthropic-Beta / anthropic-beta
+        for (const betaKey of ["anthropic-beta", "Anthropic-Beta"]) {
+          if (headers[betaKey]) {
+            const filtered = headers[betaKey]
+              .split(",")
+              .map(s => s.trim())
+              .filter(f => f && f !== "claude-code-20250219")
+              .join(",");
+            if (filtered) {
+              headers[betaKey] = filtered;
+            } else {
+              delete headers[betaKey];
+            }
+          }
+        }
+      }
+    }
+
+    if (stream) headers["Accept"] = "text/event-stream";
+    return headers;
+  }
+
+  // Generic OAuth refresh for the common {grant_type, refresh_token, client_id[, ...]} shape.
+  // grant = REFRESH_GRANTS[provider]; client creds resolved from PROVIDERS or this.config.
+  refreshFromGrant(credentials, proxyOptions) {
+    const grant = REFRESH_GRANTS[this.provider];
+    const params = { grant_type: "refresh_token", refresh_token: credentials.refreshToken, ...grant.params(this) };
+    return grant.encoding === "json"
+      ? this.refreshWithJSON(grant.url(), params, proxyOptions)
+      : this.refreshWithForm(grant.url(), params, proxyOptions);
+  }
+
+  async refreshCredentials(credentials, log, proxyOptions = null) {
+    if (!credentials.refreshToken) return null;
+
+    const refreshers = {
+      claude: () => this.refreshFromGrant(credentials, proxyOptions),
+      codex: () => this.refreshFromGrant(credentials, proxyOptions),
+      qwen: () => this.refreshWithForm(OAUTH_ENDPOINTS.qwen.token, { grant_type: "refresh_token", refresh_token: credentials.refreshToken, client_id: PROVIDERS.qwen.clientId }, proxyOptions),
+      iflow: () => this.refreshIflow(credentials.refreshToken, proxyOptions),
+      gemini: () => this.refreshFromGrant(credentials, proxyOptions),
+      kiro: () => this.refreshKiro(credentials.refreshToken, proxyOptions),
+      cline: () => this.refreshCline(credentials.refreshToken, proxyOptions),
+      clinepass: () => this.refreshCline(credentials.refreshToken, proxyOptions),
+      "kimi-coding": () => this.refreshKimiCoding(credentials.refreshToken, proxyOptions),
+      kilocode: () => this.refreshKilocode(credentials.refreshToken, proxyOptions)
+    };
+
+    const refresher = refreshers[this.provider];
+    if (!refresher) return null;
+
+    try {
+      const result = await refresher();
+      if (result) log?.info?.("TOKEN", `${this.provider} refreshed`);
+      return result;
+    } catch (error) {
+      log?.error?.("TOKEN", `${this.provider} refresh error: ${error.message}`);
+      return null;
+    }
+  }
+
+  async refreshWithJSON(url, body, proxyOptions = null) {
+    const response = await proxyAwareFetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Accept": "application/json" },
+      body: JSON.stringify(body)
+    }, proxyOptions);
+    if (!response.ok) return null;
+    const tokens = await response.json();
+    return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token || body.refresh_token, expiresIn: tokens.expires_in };
+  }
+
+  async refreshWithForm(url, params, proxyOptions = null) {
+    const response = await proxyAwareFetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json" },
+      body: new URLSearchParams(params)
+    }, proxyOptions);
+    if (!response.ok) return null;
+    const tokens = await response.json();
+    return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token || params.refresh_token, expiresIn: tokens.expires_in };
+  }
+
+  async refreshIflow(refreshToken, proxyOptions = null) {
+    const basicAuth = btoa(`${PROVIDERS.iflow.clientId}:${PROVIDERS.iflow.clientSecret}`);
+    const response = await proxyAwareFetch(OAUTH_ENDPOINTS.iflow.token, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json", "Authorization": `Basic ${basicAuth}` },
+      body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: refreshToken, client_id: PROVIDERS.iflow.clientId, client_secret: PROVIDERS.iflow.clientSecret })
+    }, proxyOptions);
+    if (!response.ok) return null;
+    const tokens = await response.json();
+    return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token || refreshToken, expiresIn: tokens.expires_in };
+  }
+
+  async refreshKiro(refreshToken, proxyOptions = null) {
+    const response = await proxyAwareFetch(PROVIDERS.kiro.tokenUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Accept": "application/json", "User-Agent": "kiro-cli/1.0.0" },
+      body: JSON.stringify({ refreshToken })
+    }, proxyOptions);
+    if (!response.ok) return null;
+    const tokens = await response.json();
+    return { accessToken: tokens.accessToken, refreshToken: tokens.refreshToken || refreshToken, expiresIn: tokens.expiresIn };
+  }
+
+  async refreshCline(refreshToken, proxyOptions = null) {
+    const response = await proxyAwareFetch(PROVIDERS.cline.refreshUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Accept": "application/json" },
+      body: JSON.stringify({ refreshToken, grantType: "refresh_token", clientType: "extension" })
+    }, proxyOptions);
+    if (!response.ok) return null;
+    const payload = await response.json();
+    const data = payload?.data || payload;
+    const expiresAtIso = data?.expiresAt;
+    const expiresIn = expiresAtIso ? Math.max(1, Math.floor((new Date(expiresAtIso).getTime() - Date.now()) / 1000)) : undefined;
+    let accessToken = data?.accessToken;
+    if (accessToken && !accessToken.startsWith("workos:")) {
+      accessToken = `workos:${accessToken}`;
+    }
+    return { accessToken, refreshToken: data?.refreshToken || refreshToken, expiresIn };
+  }
+
+  async refreshKimiCoding(refreshToken, proxyOptions = null) {
+    const kimiHeaders = buildKimiHeaders();
+    const response = await proxyAwareFetch(PROVIDERS["kimi-coding"].refreshUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Accept": "application/json",
+        ...kimiHeaders
+      },
+      body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: refreshToken, client_id: PROVIDERS["kimi-coding"].clientId })
+    }, proxyOptions);
+    if (!response.ok) return null;
+    const tokens = await response.json();
+    return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token || refreshToken, expiresIn: tokens.expires_in };
+  }
+
+  async refreshKilocode(refreshToken, proxyOptions = null) {
+    // Kilocode uses device code flow, no refresh token support
+    return null;
+  }
+}
+
+export default DefaultExecutor;
diff --git a/open-sse/executors/gemini-cli.js b/open-sse/executors/gemini-cli.js
new file mode 100644
index 0000000..02b33bf
--- /dev/null
+++ b/open-sse/executors/gemini-cli.js
@@ -0,0 +1,89 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { OAUTH_ENDPOINTS, GEMINI_CLI_API_CLIENT, geminiCLIUserAgent } from "../config/appConstants.js";
+
+export class GeminiCLIExecutor extends BaseExecutor {
+  constructor() {
+    super("gemini-cli", PROVIDERS["gemini-cli"]);
+  }
+
+  buildUrl(model, stream, urlIndex = 0) {
+    const action = stream ? "streamGenerateContent?alt=sse" : "generateContent";
+    return `${this.config.baseUrl}:${action}`;
+  }
+
+  buildHeaders(credentials, stream = true) {
+    return {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${credentials.accessToken}`,
+      "User-Agent": geminiCLIUserAgent(this._currentModel),
+      "X-Goog-Api-Client": GEMINI_CLI_API_CLIENT,
+      "Accept": stream ? "text/event-stream" : "application/json"
+    };
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    // Store model for use in buildHeaders (called by base.execute after transformRequest)
+    this._currentModel = model;
+    // Cloud Code Assist wraps the Gemini payload: { project, model, request: <body> }
+    if (body && body.request && body.model) return body;
+    return {
+      project: credentials?.projectId || body?.project,
+      model,
+      request: body
+    };
+  }
+
+  // Parse RetryInfo.retryDelay from Google API 429 body to surface upstream retry hint
+  parseError(response, bodyText) {
+    const base = super.parseError(response, bodyText);
+    if (response.status !== 429 || !bodyText) return base;
+    try {
+      const parsed = JSON.parse(bodyText);
+      const details = parsed?.error?.details;
+      if (Array.isArray(details)) {
+        for (const d of details) {
+          if (d?.["@type"] === "type.googleapis.com/google.rpc.RetryInfo" && d?.retryDelay) {
+            base.retryAfter = d.retryDelay;
+            break;
+          }
+        }
+      }
+    } catch {}
+    return base;
+  }
+
+  async refreshCredentials(credentials, log) {
+    if (!credentials.refreshToken) return null;
+
+    try {
+      const response = await fetch(OAUTH_ENDPOINTS.google.token, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json" },
+        body: new URLSearchParams({
+          grant_type: "refresh_token",
+          refresh_token: credentials.refreshToken,
+          client_id: this.config.clientId,
+          client_secret: this.config.clientSecret
+        })
+      });
+
+      if (!response.ok) return null;
+
+      const tokens = await response.json();
+      log?.info?.("TOKEN", "Gemini CLI refreshed");
+
+      return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token || credentials.refreshToken,
+        expiresIn: tokens.expires_in,
+        projectId: credentials.projectId
+      };
+    } catch (error) {
+      log?.error?.("TOKEN", `Gemini CLI refresh error: ${error.message}`);
+      return null;
+    }
+  }
+}
+
+export default GeminiCLIExecutor;
diff --git a/open-sse/executors/github.js b/open-sse/executors/github.js
new file mode 100644
index 0000000..2f4d68b
--- /dev/null
+++ b/open-sse/executors/github.js
@@ -0,0 +1,345 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { OAUTH_ENDPOINTS, GITHUB_COPILOT } from "../config/appConstants.js";
+import { HTTP_STATUS } from "../config/runtimeConfig.js";
+import { openaiToOpenAIResponsesRequest } from "../translator/request/openai-responses.js";
+import { openaiResponsesToOpenAIResponse } from "../translator/response/openai-responses.js";
+import { initState } from "../translator/index.js";
+import { parseSSELine, formatSSE } from "../utils/streamHelpers.js";
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+import { stripUnsupportedParams } from "../translator/concerns/paramSupport.js";
+import { SSE_DONE } from "../utils/sseConstants.js";
+import crypto from "crypto";
+
+export class GithubExecutor extends BaseExecutor {
+  constructor() {
+    super("github", PROVIDERS.github);
+    this.knownCodexModels = new Set();
+  }
+
+  buildUrl(model, stream, urlIndex = 0) {
+    return this.config.baseUrl;
+  }
+
+  buildHeaders(credentials, stream = true) {
+    const token = credentials.copilotToken || credentials.accessToken;
+    return {
+      "Authorization": `Bearer ${token}`,
+      "Content-Type": "application/json",
+      "copilot-integration-id": "vscode-chat",
+      "editor-version": `vscode/${GITHUB_COPILOT.VSCODE_VERSION}`,
+      "editor-plugin-version": `copilot-chat/${GITHUB_COPILOT.COPILOT_CHAT_VERSION}`,
+      "user-agent": GITHUB_COPILOT.USER_AGENT,
+      "openai-intent": "conversation-panel",
+      "x-github-api-version": GITHUB_COPILOT.API_VERSION,
+      "x-request-id": crypto.randomUUID?.() || `${Date.now()}-${Math.random().toString(36).slice(2)}`,
+      "x-vscode-user-agent-library-version": "electron-fetch",
+      "X-Initiator": "user",
+      "Accept": stream ? "text/event-stream" : "application/json"
+    };
+  }
+
+  // Sanitize messages for GitHub Copilot /chat/completions endpoint.
+  // The endpoint only accepts 'text' and 'image_url' content part types.
+  // Tool-related content (tool_use, tool_result, thinking) must be serialized as text.
+  sanitizeMessagesForChatCompletions(body) {
+    if (!body?.messages) return body;
+
+    const sanitized = { ...body };
+    
+    // Handle response_format for Claude models via GitHub
+    // GitHub's internal translation doesn't respect response_format, so we inject it as a system prompt
+    // AND prepend a reminder to the last user message for maximum effectiveness
+    if (body.response_format && body.model?.includes('claude')) {
+      const responseFormat = body.response_format;
+      let systemInstruction = '';
+      if (responseFormat.type === 'json_schema' && responseFormat.json_schema?.schema) {
+        systemInstruction = 'CRITICAL: You must ONLY output raw JSON. Never use markdown code blocks. Never use backticks. Never wrap JSON in triple backticks. Output ONLY the raw JSON object.';
+      } else if (responseFormat.type === 'json_object') {
+        systemInstruction = 'CRITICAL: You must ONLY output raw JSON. Never use markdown code blocks. Never use backticks.';
+      }
+      if (systemInstruction) {
+        // Add to system message
+        const systemIdx = body.messages.findIndex(m => m.role === 'system');
+        if (systemIdx >= 0) {
+          body.messages[systemIdx].content = systemInstruction + '\n\n' + body.messages[systemIdx].content;
+        } else {
+          body.messages.unshift({ role: 'system', content: systemInstruction });
+        }
+        
+        // Also prepend to the last user message as a reminder
+        const lastUserIdx = body.messages.map((m, i) => m.role === 'user' ? i : -1).filter(i => i >= 0).pop();
+        if (lastUserIdx >= 0) {
+          const userMsg = body.messages[lastUserIdx];
+          const userContent = typeof userMsg.content === 'string' ? userMsg.content : JSON.stringify(userMsg.content);
+          userMsg.content = 'Respond with ONLY raw JSON (no markdown, no backticks, no code blocks): ' + userContent;
+        }
+      }
+    }
+    sanitized.messages = body.messages.map(msg => {
+      // assistant messages with only tool_calls have content: null — leave as-is
+      if (!msg.content) return msg;
+
+      // String content is always fine
+      if (typeof msg.content === "string") return msg;
+
+      // Array content: filter/convert unsupported part types
+      if (Array.isArray(msg.content)) {
+        const cleanContent = msg.content
+          .map(part => {
+            if (part.type === "text") return part;
+            if (part.type === "image_url") return part;
+            // Serialize tool_use, tool_result, thinking, etc. as text
+            const text = part.text || part.content || JSON.stringify(part);
+            return { type: "text", text: typeof text === "string" ? text : JSON.stringify(text) };
+          })
+          .filter(part => part.text !== ""); // remove empty text parts
+
+        // If all content was stripped (e.g. only tool_result with no text), drop content
+        return { ...msg, content: cleanContent.length > 0 ? cleanContent : null };
+      }
+
+      return msg;
+    });
+
+    return sanitized;
+  }
+
+  // Newer OpenAI models (gpt-5+, o1, o3, o4) require max_completion_tokens instead of max_tokens
+  requiresMaxCompletionTokens(model) {
+    return /gpt-5|o[134]-/i.test(model);
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    const transformed = { ...body };
+    if (this.requiresMaxCompletionTokens(model) && transformed.max_tokens !== undefined) {
+      transformed.max_completion_tokens = transformed.max_tokens;
+      delete transformed.max_tokens;
+    }
+    // "none" means no thinking — strip it so models that don't support "none" don't 400
+    if (transformed.reasoning_effort === "none") {
+      delete transformed.reasoning_effort;
+    }
+    // Config-driven strip of params unsupported by this provider/model
+    stripUnsupportedParams("github", model, transformed);
+    return transformed;
+  }
+
+  // GitHub Copilot's /responses endpoint only serves OpenAI (gpt/codex) models.
+  // Gemini and Claude models are not available there and reject with a 400
+  // "does not support Responses API" (unsupported_api_for_model). They must
+  // therefore never be escalated to /responses, even if /chat/completions
+  // returned a "not supported" error for an unrelated reason. Fixes #1062.
+  supportsResponsesEndpoint(model) {
+    const m = (model || "").toLowerCase();
+    return !(m.includes("gemini") || m.includes("claude"));
+  }
+
+  async execute(options) {
+    const { model, log } = options;
+
+    // Only use /responses for models that are explicitly known to need it (e.g. gpt codex models)
+    // and that the /responses endpoint actually serves (excludes Gemini/Claude, see #1062).
+    if (this.knownCodexModels.has(model) && this.supportsResponsesEndpoint(model)) {
+      log?.debug("GITHUB", `Using cached /responses route for ${model}`);
+      return this.executeWithResponsesEndpoint(options);
+    }
+
+    // Sanitize messages before sending to /chat/completions
+    // This handles Claude models on GitHub Copilot which reject non-text/image_url content types
+    const sanitizedOptions = {
+      ...options,
+      body: this.sanitizeMessagesForChatCompletions(options.body)
+    };
+
+    const result = await super.execute({ ...sanitizedOptions, proxyOptions: options.proxyOptions || null });
+
+    // Only escalate to /responses for models that endpoint can actually serve.
+    // Gemini/Claude would otherwise loop into a misleading "does not support
+    // Responses API" 400 instead of surfacing the real /chat/completions error (#1062).
+    if (result.response.status === HTTP_STATUS.BAD_REQUEST && this.supportsResponsesEndpoint(model)) {
+      const errorBody = await result.response.clone().text();
+
+      if (errorBody.includes("not accessible via the /chat/completions endpoint") || errorBody.includes("The requested model is not supported")) {
+        log?.warn("GITHUB", `Model ${model} requires /responses. Switching...`);
+        this.knownCodexModels.add(model);
+        return this.executeWithResponsesEndpoint(options);
+      }
+    }
+
+    return result;
+  }
+
+  async executeWithResponsesEndpoint({ model, body, stream, credentials, signal, log, proxyOptions = null }) {
+    const url = this.config.responsesUrl;
+    const headers = this.buildHeaders(credentials, stream);
+
+    const transformedBody = openaiToOpenAIResponsesRequest(model, body, stream, credentials);
+
+    log?.debug("GITHUB", "Sending translated request to /responses");
+
+    const response = await proxyAwareFetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(transformedBody),
+      signal
+    }, proxyOptions);
+
+    if (!response.ok) {
+      return { response, url, headers, transformedBody };
+    }
+
+    const state = initState("openai-responses");
+    state.model = model;
+
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    const transformStream = new TransformStream({
+      async transform(chunk, controller) {
+        buffer += decoder.decode(chunk, { stream: true });
+        const lines = buffer.split("\n");
+
+        buffer = lines.pop() || "";
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+
+          const parsed = parseSSELine(trimmed);
+          if (!parsed) continue;
+
+          if (parsed.done && stream === true) {
+            controller.enqueue(new TextEncoder().encode(SSE_DONE));
+            continue;
+          }
+
+          const converted = openaiResponsesToOpenAIResponse(parsed, state);
+          if (converted) {
+            const sseString = formatSSE(converted, "openai");
+            controller.enqueue(new TextEncoder().encode(sseString));
+          }
+        }
+      },
+      flush(controller) {
+        if (buffer.trim()) {
+          const parsed = parseSSELine(buffer.trim());
+          if (parsed && !parsed.done) {
+            const converted = openaiResponsesToOpenAIResponse(parsed, state);
+            if (converted) {
+              controller.enqueue(new TextEncoder().encode(formatSSE(converted, "openai")));
+            }
+          }
+        }
+      }
+    });
+
+    if (!response.body) {
+      return { response: new Response("", { status: response.status, headers: response.headers }), url, headers, transformedBody };
+    }
+    const convertedStream = response.body.pipeThrough(transformStream);
+
+    return {
+      response: new Response(convertedStream, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers
+      }),
+      url,
+      headers,
+      transformedBody
+    };
+  }
+
+  async refreshCopilotToken(githubAccessToken, log, proxyOptions = null) {
+    try {
+      const response = await proxyAwareFetch("https://api.github.com/copilot_internal/v2/token", {
+        headers: {
+          "Authorization": `token ${githubAccessToken}`,
+          "User-Agent": GITHUB_COPILOT.USER_AGENT,
+          "Editor-Version": `vscode/${GITHUB_COPILOT.VSCODE_VERSION}`,
+          "Editor-Plugin-Version": `copilot-chat/${GITHUB_COPILOT.COPILOT_CHAT_VERSION}`,
+          "Accept": "application/json",
+          "x-github-api-version": GITHUB_COPILOT.API_VERSION
+        }
+      }, proxyOptions);
+      if (!response.ok) {
+        const errorText = await response.text();
+        log?.error?.("TOKEN", `Copilot token refresh failed: ${response.status} ${errorText}`);
+        return null;
+      }
+      const data = await response.json();
+      log?.info?.("TOKEN", "Copilot token refreshed");
+      return { token: data.token, expiresAt: data.expires_at };
+    } catch (error) {
+      log?.error?.("TOKEN", `Copilot refresh error: ${error.message}`);
+      return null;
+    }
+  }
+
+  async refreshGitHubToken(refreshToken, log, proxyOptions = null) {
+    try {
+      const params = {
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: this.config.clientId,
+      };
+      if (this.config.clientSecret) {
+        params.client_secret = this.config.clientSecret;
+      }
+
+      const response = await proxyAwareFetch(OAUTH_ENDPOINTS.github.token, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json" },
+        body: new URLSearchParams(params)
+      }, proxyOptions);
+      if (!response.ok) return null;
+      const tokens = await response.json();
+      log?.info?.("TOKEN", "GitHub token refreshed");
+      return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token || refreshToken, expiresIn: tokens.expires_in };
+    } catch (error) {
+      log?.error?.("TOKEN", `GitHub refresh error: ${error.message}`);
+      return null;
+    }
+  }
+
+  async refreshCredentials(credentials, log, proxyOptions = null) {
+    let copilotResult = await this.refreshCopilotToken(credentials.accessToken, log, proxyOptions);
+
+    if (!copilotResult && credentials.refreshToken) {
+      const githubTokens = await this.refreshGitHubToken(credentials.refreshToken, log, proxyOptions);
+      if (githubTokens?.accessToken) {
+        copilotResult = await this.refreshCopilotToken(githubTokens.accessToken, log, proxyOptions);
+        if (copilotResult) {
+          return { ...githubTokens, copilotToken: copilotResult.token, copilotTokenExpiresAt: copilotResult.expiresAt };
+        }
+        return githubTokens;
+      }
+    }
+
+    if (copilotResult) {
+      return { accessToken: credentials.accessToken, refreshToken: credentials.refreshToken, copilotToken: copilotResult.token, copilotTokenExpiresAt: copilotResult.expiresAt };
+    }
+
+    return null;
+  }
+
+  needsRefresh(credentials) {
+    // Always refresh if no copilotToken
+    if (!credentials.copilotToken) return true;
+
+    if (credentials.copilotTokenExpiresAt) {
+      // Handle both Unix timestamp (seconds) and ISO string
+      let expiresAtMs = credentials.copilotTokenExpiresAt;
+      if (typeof expiresAtMs === "number" && expiresAtMs < 1e12) {
+        expiresAtMs = expiresAtMs * 1000; // Convert seconds to ms
+      } else if (typeof expiresAtMs === "string") {
+        expiresAtMs = new Date(expiresAtMs).getTime();
+      }
+      if (expiresAtMs - Date.now() < 5 * 60 * 1000) return true;
+    }
+    return super.needsRefresh(credentials);
+  }
+}
+
+export default GithubExecutor;
diff --git a/open-sse/executors/grok-cli.js b/open-sse/executors/grok-cli.js
new file mode 100644
index 0000000..00684d5
--- /dev/null
+++ b/open-sse/executors/grok-cli.js
@@ -0,0 +1,397 @@
+import crypto from "node:crypto";
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import {
+  refreshProviderCredentials,
+  shouldRefreshCredentials,
+} from "../services/oauthCredentialManager.js";
+import { normalizeResponsesInput } from "../translator/formats/responsesApi.js";
+import { getModelUpstreamId } from "../config/providerModels.js";
+import { resolveSessionId } from "../utils/sessionManager.js";
+import { getConsistentMachineId } from "../shared/machineId.js";
+
+// Server-generated item id prefixes that /responses cannot resolve when store=false
+const SERVER_ID_PATTERN = /^(rs|fc|resp|msg)_/;
+
+// Hosted tool types executed server-side by Grok CLI backend
+const HOSTED_TOOL_TYPES = new Set([
+  "web_search",
+  "x_search",
+  "web_search_preview",
+  "file_search",
+  "image_generation",
+  "code_interpreter",
+  "mcp",
+  "local_shell",
+]);
+
+// Fields accepted by cli-chat-proxy Responses API (mirrors Codex allowlist + Grok extras)
+const RESPONSES_API_ALLOWLIST = new Set([
+  "model",
+  "input",
+  "instructions",
+  "tools",
+  "tool_choice",
+  "stream",
+  "store",
+  "reasoning",
+  "include",
+  "temperature",
+  "top_p",
+  "max_output_tokens",
+  "parallel_tool_calls",
+  "text",
+  "metadata",
+  "prompt_cache_key",
+]);
+
+const EFFORT_LEVELS = ["low", "medium", "high"];
+
+// Per-session last turn index so multi-turn headers never go backwards within this process
+const sessionTurnStore = new Map();
+
+/**
+ * Count user turns in a Responses `input` array.
+ * Official CLI sets x-grok-turn-idx to the 1-based conversation turn (≈ user messages).
+ * HAR: first chat turn → "1".
+ */
+export function countGrokCliUserTurns(input) {
+  if (!Array.isArray(input)) return 1;
+  let n = 0;
+  for (const item of input) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+    const type = typeof item.type === "string" ? item.type : "";
+    // Responses message items (type omitted or "message") with role user
+    if (item.role === "user" && (!type || type === "message")) n += 1;
+  }
+  return Math.max(1, n);
+}
+
+/**
+ * Resolve monotonic turn index for a session.
+ * Prefers user-message count from the payload (full history clients), but never
+ * decreases vs the last index observed for the same sessionId in this process.
+ */
+export function resolveGrokCliTurnIdx(sessionId, input) {
+  const fromInput = countGrokCliUserTurns(input);
+  if (!sessionId) return fromInput;
+  const prev = sessionTurnStore.get(sessionId) || 0;
+  const turn = Math.max(fromInput, prev);
+  sessionTurnStore.set(sessionId, turn);
+  return turn;
+}
+
+/** Test helper — clear in-memory turn counters */
+export function _resetGrokCliTurnStore() {
+  sessionTurnStore.clear();
+}
+
+function stripStoredItemReferences(body) {
+  if (!Array.isArray(body.input)) return;
+  body.input = body.input.filter((item) => {
+    if (typeof item === "string" && SERVER_ID_PATTERN.test(item)) return false;
+    if (item && typeof item === "object" && !Array.isArray(item)) {
+      if (item.type === "item_reference") return false;
+      if (typeof item.id === "string" && SERVER_ID_PATTERN.test(item.id)) delete item.id;
+    }
+    return true;
+  });
+}
+
+/**
+ * Flatten Chat Completions tool shape → Responses flat format.
+ * Keep hosted tools (web_search / x_search) passthrough.
+ */
+function normalizeGrokCliTools(body) {
+  if (!Array.isArray(body.tools)) return;
+  const validNames = new Set();
+  body.tools = body.tools.filter((tool) => {
+    if (!tool || typeof tool !== "object" || Array.isArray(tool)) return false;
+    const type = typeof tool.type === "string" ? tool.type : "";
+
+    if (type !== "function") {
+      // Hosted tools: { type: "web_search" } / { type: "x_search" }
+      if (HOSTED_TOOL_TYPES.has(type)) return true;
+      // Nested function shape without type
+      if (!type && tool.function) {
+        // fall through to function flatten below
+      } else if (!type || typeof tool.name === "string") {
+        // treat as bare function if name present
+      } else {
+        return false;
+      }
+    }
+
+    const isFunction =
+      type === "function" || type === "" || tool.function || typeof tool.name === "string";
+    if (!isFunction || HOSTED_TOOL_TYPES.has(type)) {
+      return HOSTED_TOOL_TYPES.has(type);
+    }
+
+    const fn =
+      tool.function && typeof tool.function === "object" && !Array.isArray(tool.function)
+        ? tool.function
+        : null;
+    const rawName =
+      typeof tool.name === "string" ? tool.name : typeof fn?.name === "string" ? fn.name : "";
+    const name = rawName.trim();
+    if (!name) return false;
+
+    const description =
+      typeof tool.description === "string"
+        ? tool.description
+        : typeof fn?.description === "string"
+          ? fn.description
+          : "";
+    const parameters =
+      tool.parameters && typeof tool.parameters === "object" && !Array.isArray(tool.parameters)
+        ? tool.parameters
+        : fn?.parameters && typeof fn.parameters === "object" && !Array.isArray(fn.parameters)
+          ? fn.parameters
+          : { type: "object", properties: {} };
+
+    for (const k of Object.keys(tool)) delete tool[k];
+    tool.type = "function";
+    tool.name = name.slice(0, 128);
+    if (description) tool.description = description;
+    tool.parameters = parameters;
+    validNames.add(name);
+    return true;
+  });
+
+  if (body.tool_choice && typeof body.tool_choice === "object" && !Array.isArray(body.tool_choice)) {
+    if (body.tool_choice.type === "function") {
+      const n = typeof body.tool_choice.name === "string" ? body.tool_choice.name.trim() : "";
+      if (!n || !validNames.has(n)) delete body.tool_choice;
+    }
+  }
+}
+
+function resolveEffortFromModel(modelId) {
+  if (!modelId || typeof modelId !== "string") return null;
+  for (const level of EFFORT_LEVELS) {
+    if (modelId.endsWith(`-${level}`)) return level;
+  }
+  return null;
+}
+
+/**
+ * Grok CLI Executor — OpenAI Responses API on cli-chat-proxy.grok.com
+ * Auth: OAuth device-code access token (xai-grok-cli).
+ */
+export class GrokCliExecutor extends BaseExecutor {
+  constructor() {
+    super("grok-cli", PROVIDERS["grok-cli"]);
+    this._currentSessionId = null;
+    this._currentReqId = null;
+    this._currentTurnIdx = 1;
+    this._agentId = null;
+  }
+
+  buildUrl() {
+    return this.config.baseUrl;
+  }
+
+  async refreshCredentials(credentials, log) {
+    if (!credentials?.refreshToken) return null;
+    return refreshProviderCredentials("grok-cli", credentials, log);
+  }
+
+  needsRefresh(credentials) {
+    return shouldRefreshCredentials("grok-cli", credentials);
+  }
+
+  buildHeaders(credentials, stream = true) {
+    const headers = super.buildHeaders(credentials, stream);
+
+    // Static fingerprint from registry
+    const staticHeaders = this.config.headers || {};
+    for (const [k, v] of Object.entries(staticHeaders)) {
+      if (v != null && headers[k] === undefined) headers[k] = v;
+    }
+
+    // Ensure token-auth marker is present even if headers map was overridden
+    headers["x-xai-token-auth"] = this.config.tokenAuth || "xai-grok-cli";
+    headers["x-grok-client-identifier"] =
+      this.config.clientIdentifier || headers["x-grok-client-identifier"] || "grok-pager";
+    headers["x-grok-client-version"] =
+      this.config.clientVersion || headers["x-grok-client-version"] || "0.2.93";
+    headers["x-authenticateresponse"] = "authenticate-response";
+
+    const sessionId = this._currentSessionId || credentials?.connectionId || crypto.randomUUID();
+    const reqId = this._currentReqId || crypto.randomUUID();
+    headers["x-grok-session-id"] = sessionId;
+    // CLI uses the same id for conv + session on chat turns
+    headers["x-grok-conv-id"] = sessionId;
+    headers["x-grok-req-id"] = reqId;
+    headers["x-grok-turn-idx"] = String(this._currentTurnIdx || 1);
+
+    if (this._agentId) headers["x-grok-agent-id"] = this._agentId;
+
+    // Surface model override (CLI always sets this)
+    if (this._currentModel) headers["x-grok-model-override"] = this._currentModel;
+
+    if (this.config.compactionAt) {
+      headers["x-compaction-at"] = String(this.config.compactionAt);
+    }
+
+    // Identity: mapTokens stores email top-level AND in providerSpecificData;
+    // fall back either way so OAuth connections always fingerprint like the CLI.
+    const psd = credentials?.providerSpecificData || {};
+    const email = psd.email || credentials?.email;
+    const userId = psd.userId || credentials?.userId || credentials?.providerUserId;
+    if (email) headers["x-email"] = email;
+    if (userId) headers["x-userid"] = userId;
+
+    return headers;
+  }
+
+  parseError(response, bodyText) {
+    // 402 personal-team-blocked:spending-limit → surface as payment/quota for fallback
+    if (response.status === 402 && bodyText) {
+      try {
+        const json = JSON.parse(bodyText);
+        const code = json?.code || "";
+        const msg = json?.error || json?.message || bodyText;
+        return {
+          status: 402,
+          message: typeof msg === "string" ? msg : bodyText,
+          code: typeof code === "string" ? code : undefined,
+        };
+      } catch {
+        /* fall through */
+      }
+    }
+    return super.parseError(response, bodyText);
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    // Session / request ids for headers — stable per client conversation when possible
+    this._currentSessionId = resolveSessionId({
+      headers: credentials?.rawHeaders,
+      body,
+      connectionId: credentials?.connectionId || credentials?.id,
+      workspaceId: credentials?.providerSpecificData?.workspaceId,
+      scope: "grok-cli",
+    });
+    this._currentReqId = crypto.randomUUID();
+    this._agentId =
+      credentials?.providerSpecificData?.deviceId ||
+      credentials?.providerSpecificData?.agentId ||
+      null;
+
+    // Normalize Responses input
+    const normalized = normalizeResponsesInput(body.input);
+    if (normalized) body.input = normalized;
+
+    // Chat Completions clients arrive with messages[] — translator should have
+    // converted already, but guard empty input.
+    if (!body.input || (Array.isArray(body.input) && body.input.length === 0)) {
+      if (Array.isArray(body.messages) && body.messages.length > 0) {
+        // Soft fallback: map messages → input messages (string content only)
+        body.input = body.messages.map((m) => ({
+          type: "message",
+          role: m.role || "user",
+          content: typeof m.content === "string" ? m.content : JSON.stringify(m.content ?? ""),
+        }));
+        delete body.messages;
+      } else {
+        body.input = [{ type: "message", role: "user", content: "..." }];
+      }
+    }
+
+    // Keep role:"system" as-is — official grok-pager HAR sends system, not developer
+    // (Codex converts system→developer; Grok CLI does not).
+    stripStoredItemReferences(body);
+    normalizeGrokCliTools(body);
+
+    // Turn index after input is finalized (user-message count, monotonic per session)
+    this._currentTurnIdx = resolveGrokCliTurnIdx(this._currentSessionId, body.input);
+
+    body.stream = true;
+    body.store = false;
+
+    // Resolve upstream model id (strip effort suffix virtual models)
+    let modelEffort = resolveEffortFromModel(body.model || model);
+    let resolvedModel = body.model || model;
+    if (modelEffort) {
+      resolvedModel = resolvedModel.replace(new RegExp(`-${modelEffort}$`), "");
+    }
+    resolvedModel = getModelUpstreamId("gcli", resolvedModel) || resolvedModel;
+    // Also try provider id key
+    if (resolvedModel === (body.model || model)) {
+      resolvedModel = getModelUpstreamId("grok-cli", resolvedModel) || resolvedModel;
+    }
+    body.model = resolvedModel;
+    this._currentModel = resolvedModel;
+
+    // Reasoning effort priority: explicit > reasoning_effort > model suffix > default high
+    if (!body.reasoning || typeof body.reasoning !== "object") {
+      const effort = body.reasoning_effort || modelEffort || "high";
+      body.reasoning = { effort, summary: "concise" };
+    } else {
+      if (!body.reasoning.effort) {
+        body.reasoning.effort = body.reasoning_effort || modelEffort || "high";
+      }
+      if (!body.reasoning.summary) body.reasoning.summary = "concise";
+    }
+    delete body.reasoning_effort;
+
+    // Encrypted reasoning for multi-turn continuity (CLI always requests this)
+    if (body.reasoning?.effort && body.reasoning.effort !== "none") {
+      const include = Array.isArray(body.include) ? body.include : [];
+      if (!include.includes("reasoning.encrypted_content")) {
+        include.push("reasoning.encrypted_content");
+      }
+      body.include = include;
+    }
+
+    // Drop Chat Completions leftovers that Responses rejects
+    delete body.messages;
+    delete body.max_tokens;
+    delete body.max_completion_tokens;
+    delete body.n;
+    delete body.seed;
+    delete body.logprobs;
+    delete body.top_logprobs;
+    delete body.frequency_penalty;
+    delete body.presence_penalty;
+    delete body.logit_bias;
+    delete body.user;
+    delete body.stream_options;
+    delete body.prompt_cache_retention;
+    delete body.safety_identifier;
+    delete body.previous_response_id; // store=false → cannot resolve
+
+    for (const k of Object.keys(body)) {
+      if (!RESPONSES_API_ALLOWLIST.has(k)) delete body[k];
+    }
+
+    return body;
+  }
+
+  async execute(args) {
+    // Lazy-resolve stable agent id once per process if connection has none
+    if (!this._agentId && !args.credentials?.providerSpecificData?.deviceId) {
+      try {
+        const mid = await getConsistentMachineId("grok-cli-agent");
+        // Format as UUID-ish for header aesthetics
+        this._agentId = [
+          mid.slice(0, 8),
+          mid.slice(8, 12),
+          "5" + mid.slice(13, 16),
+          "a" + mid.slice(17, 20),
+          mid.slice(0, 12).padEnd(12, "0"),
+        ].join("-");
+      } catch {
+        this._agentId = crypto.randomUUID();
+      }
+    } else if (args.credentials?.providerSpecificData?.deviceId) {
+      this._agentId = args.credentials.providerSpecificData.deviceId;
+    }
+
+    return super.execute(args);
+  }
+}
+
+export default GrokCliExecutor;
diff --git a/open-sse/executors/grok-web.js b/open-sse/executors/grok-web.js
new file mode 100644
index 0000000..9e6cdb1
--- /dev/null
+++ b/open-sse/executors/grok-web.js
@@ -0,0 +1,343 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { SSE_DONE, SSE_HEADERS_NO_BUFFER } from "../utils/sseConstants.js";
+import { sseChunk } from "../utils/sse.js";
+
+const GROK_CHAT_API = PROVIDERS["grok-web"].baseUrl;
+const GROK_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36";
+
+const MODEL_MAP = {
+  "grok-3": { grokModel: "grok-3", modelMode: "MODEL_MODE_GROK_3", isThinking: false },
+  "grok-3-mini": { grokModel: "grok-3", modelMode: "MODEL_MODE_GROK_3_MINI_THINKING", isThinking: true },
+  "grok-3-thinking": { grokModel: "grok-3", modelMode: "MODEL_MODE_GROK_3_THINKING", isThinking: true },
+  "grok-4": { grokModel: "grok-4", modelMode: "MODEL_MODE_GROK_4", isThinking: false },
+  "grok-4-mini": { grokModel: "grok-4-mini", modelMode: "MODEL_MODE_GROK_4_MINI_THINKING", isThinking: true },
+  "grok-4-thinking": { grokModel: "grok-4", modelMode: "MODEL_MODE_GROK_4_THINKING", isThinking: true },
+  "grok-4-heavy": { grokModel: "grok-4", modelMode: "MODEL_MODE_HEAVY", isThinking: true },
+  "grok-4.1-mini": { grokModel: "grok-4-1-thinking-1129", modelMode: "MODEL_MODE_GROK_4_1_MINI_THINKING", isThinking: true },
+  "grok-4.1-fast": { grokModel: "grok-4-1-thinking-1129", modelMode: "MODEL_MODE_FAST", isThinking: false },
+  "grok-4.1-expert": { grokModel: "grok-4-1-thinking-1129", modelMode: "MODEL_MODE_EXPERT", isThinking: true },
+  "grok-4.1-thinking": { grokModel: "grok-4-1-thinking-1129", modelMode: "MODEL_MODE_GROK_4_1_THINKING", isThinking: true },
+  "grok-4.2": { grokModel: "grok-420", modelMode: "MODEL_MODE_GROK_420", isThinking: false },
+  "grok-4.20": { grokModel: "grok-420", modelMode: "MODEL_MODE_GROK_420", isThinking: false },
+  "grok-4.20-beta": { grokModel: "grok-420", modelMode: "MODEL_MODE_GROK_420", isThinking: false },
+};
+
+function randomString(length, alphanumeric = false) {
+  const chars = alphanumeric ? "abcdefghijklmnopqrstuvwxyz0123456789" : "abcdefghijklmnopqrstuvwxyz";
+  let result = "";
+  for (let i = 0; i < length; i++) result += chars[Math.floor(Math.random() * chars.length)];
+  return result;
+}
+
+function generateStatsigId() {
+  const msg = Math.random() < 0.5
+    ? `e:TypeError: Cannot read properties of null (reading 'children["${randomString(5, true)}"]')`
+    : `e:TypeError: Cannot read properties of undefined (reading '${randomString(10)}')`;
+  return btoa(msg);
+}
+
+function randomHex(bytes) {
+  const arr = new Uint8Array(bytes);
+  crypto.getRandomValues(arr);
+  return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function parseOpenAIMessages(messages) {
+  const extracted = [];
+  for (const msg of messages) {
+    let role = String(msg.role || "user");
+    if (role === "developer") role = "system";
+    let content = "";
+    if (typeof msg.content === "string") {
+      content = msg.content;
+    } else if (Array.isArray(msg.content)) {
+      content = msg.content.filter((c) => c.type === "text").map((c) => String(c.text || "")).join(" ");
+    }
+    if (!content.trim()) continue;
+    extracted.push({ role, text: content });
+  }
+
+  let lastUserIdx = -1;
+  for (let i = extracted.length - 1; i >= 0; i--) {
+    if (extracted[i].role === "user") { lastUserIdx = i; break; }
+  }
+
+  const parts = [];
+  for (let i = 0; i < extracted.length; i++) {
+    const { role, text } = extracted[i];
+    parts.push(i === lastUserIdx ? text : `${role}: ${text}`);
+  }
+  return parts.join("\n\n");
+}
+
+async function* readGrokNdjsonEvents(body, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      if (signal?.aborted) return;
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      while (true) {
+        const idx = buffer.indexOf("\n");
+        if (idx < 0) break;
+        const line = buffer.slice(0, idx).trim();
+        buffer = buffer.slice(idx + 1);
+        if (!line) continue;
+        try { yield JSON.parse(line); } catch { /* skip */ }
+      }
+    }
+    buffer += decoder.decode();
+    const remaining = buffer.trim();
+    if (remaining) {
+      try { yield JSON.parse(remaining); } catch { /* skip */ }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function* extractContent(eventStream, isThinkingModel, signal) {
+  let fingerprint = "";
+  let responseId = "";
+  let thinkOpened = false;
+
+  for await (const event of readGrokNdjsonEvents(eventStream, signal)) {
+    if (event.error) {
+      yield { error: event.error.message || `Grok error: ${event.error.code}`, done: true };
+      return;
+    }
+    const resp = event.result?.response;
+    if (!resp) continue;
+
+    if (resp.llmInfo?.modelHash && !fingerprint) fingerprint = resp.llmInfo.modelHash;
+    if (resp.responseId) responseId = resp.responseId;
+
+    if (resp.modelResponse) {
+      const mr = resp.modelResponse;
+      if (thinkOpened && isThinkingModel) {
+        if (mr.message) yield { thinking: mr.message };
+        thinkOpened = false;
+      }
+      if (mr.message) yield { fullMessage: mr.message, fingerprint, responseId };
+      if (mr.metadata?.llm_info?.modelHash) fingerprint = mr.metadata.llm_info.modelHash;
+      continue;
+    }
+
+    if (resp.token != null) yield { delta: resp.token, fingerprint, responseId };
+  }
+  yield { done: true, fingerprint, responseId };
+}
+
+function buildStreamingResponse(eventStream, model, cid, created, isThinkingModel, signal) {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        controller.enqueue(encoder.encode(sseChunk({
+          id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: null,
+          choices: [{ index: 0, delta: { role: "assistant" }, finish_reason: null, logprobs: null }],
+        })));
+
+        let fp = "";
+        for await (const chunk of extractContent(eventStream, isThinkingModel, signal)) {
+          if (chunk.fingerprint) fp = chunk.fingerprint;
+
+          if (chunk.error) {
+            controller.enqueue(encoder.encode(sseChunk({
+              id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: fp || null,
+              choices: [{ index: 0, delta: { content: `[Error: ${chunk.error}]` }, finish_reason: null, logprobs: null }],
+            })));
+            break;
+          }
+          if (chunk.thinking) {
+            controller.enqueue(encoder.encode(sseChunk({
+              id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: fp || null,
+              choices: [{ index: 0, delta: { reasoning_content: chunk.thinking }, finish_reason: null, logprobs: null }],
+            })));
+            continue;
+          }
+          if (chunk.done) break;
+          if (chunk.delta) {
+            controller.enqueue(encoder.encode(sseChunk({
+              id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: fp || null,
+              choices: [{ index: 0, delta: { content: chunk.delta }, finish_reason: null, logprobs: null }],
+            })));
+          }
+        }
+
+        controller.enqueue(encoder.encode(sseChunk({
+          id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: fp || null,
+          choices: [{ index: 0, delta: {}, finish_reason: "stop", logprobs: null }],
+        })));
+        controller.enqueue(encoder.encode(SSE_DONE));
+      } catch (err) {
+        controller.enqueue(encoder.encode(sseChunk({
+          id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: null,
+          choices: [{ index: 0, delta: { content: `[Stream error: ${err.message || String(err)}]` }, finish_reason: "stop", logprobs: null }],
+        })));
+        controller.enqueue(encoder.encode(SSE_DONE));
+      } finally {
+        controller.close();
+      }
+    },
+  });
+}
+
+async function buildNonStreamingResponse(eventStream, model, cid, created, isThinkingModel, signal) {
+  let fullContent = "";
+  let fingerprint = "";
+  const thinkingParts = [];
+
+  for await (const chunk of extractContent(eventStream, isThinkingModel, signal)) {
+    if (chunk.fingerprint) fingerprint = chunk.fingerprint;
+    if (chunk.error) {
+      return new Response(JSON.stringify({
+        error: { message: chunk.error, type: "upstream_error", code: "GROK_ERROR" },
+      }), { status: 502, headers: { "Content-Type": "application/json" } });
+    }
+    if (chunk.thinking) { thinkingParts.push(chunk.thinking); continue; }
+    if (chunk.done) break;
+    if (chunk.fullMessage) fullContent = chunk.fullMessage;
+    else if (chunk.delta) fullContent += chunk.delta;
+  }
+
+  const msg = { role: "assistant", content: fullContent };
+  if (thinkingParts.length > 0) msg.reasoning_content = thinkingParts.join("\n");
+
+  const promptTokens = Math.ceil(fullContent.length / 4);
+  const completionTokens = Math.ceil(fullContent.length / 4);
+
+  return new Response(JSON.stringify({
+    id: cid, object: "chat.completion", created, model, system_fingerprint: fingerprint || null,
+    choices: [{ index: 0, message: msg, finish_reason: "stop", logprobs: null }],
+    usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: promptTokens + completionTokens },
+  }), { status: 200, headers: { "Content-Type": "application/json" } });
+}
+
+export class GrokWebExecutor extends BaseExecutor {
+  constructor() {
+    super("grok-web", PROVIDERS["grok-web"]);
+  }
+
+  async execute({ model, body, stream, credentials, signal, log }) {
+    const messages = body?.messages;
+    if (!messages || !Array.isArray(messages) || messages.length === 0) {
+      const errResp = new Response(JSON.stringify({
+        error: { message: "Missing or empty messages array", type: "invalid_request" },
+      }), { status: 400, headers: { "Content-Type": "application/json" } });
+      return { response: errResp, url: GROK_CHAT_API, headers: {}, transformedBody: body };
+    }
+
+    const modelInfo = MODEL_MAP[model];
+    if (!modelInfo) log?.info?.("GROK-WEB", `Unmapped model ${model}, defaulting to grok-4.1-fast`);
+    const { grokModel, modelMode, isThinking } = modelInfo || MODEL_MAP["grok-4.1-fast"];
+
+    const message = parseOpenAIMessages(messages);
+    if (!message.trim()) {
+      const errResp = new Response(JSON.stringify({
+        error: { message: "Empty query after processing", type: "invalid_request" },
+      }), { status: 400, headers: { "Content-Type": "application/json" } });
+      return { response: errResp, url: GROK_CHAT_API, headers: {}, transformedBody: body };
+    }
+
+    const grokPayload = {
+      temporary: true, modelName: grokModel, modelMode, message,
+      fileAttachments: [], imageAttachments: [],
+      disableSearch: false, enableImageGeneration: false, returnImageBytes: false,
+      returnRawGrokInXaiRequest: false, enableImageStreaming: false, imageGenerationCount: 0,
+      forceConcise: false, toolOverrides: {}, enableSideBySide: true, sendFinalMetadata: true,
+      isReasoning: false, disableTextFollowUps: false, disableMemory: true,
+      forceSideBySide: false, isAsyncChat: false, disableSelfHarmShortCircuit: false,
+      deviceEnvInfo: {
+        darkModeEnabled: false, devicePixelRatio: 2,
+        screenWidth: 2056, screenHeight: 1329, viewportWidth: 2056, viewportHeight: 1083,
+      },
+    };
+
+    const traceId = randomHex(16);
+    const spanId = randomHex(8);
+    const headers = {
+      Accept: "*/*",
+      "Accept-Encoding": "gzip, deflate, br, zstd",
+      "Accept-Language": "en-US,en;q=0.9",
+      Baggage: "sentry-environment=production,sentry-release=d6add6fb0460641fd482d767a335ef72b9b6abb8,sentry-public_key=b311e0f2690c81f25e2c4cf6d4f7ce1c",
+      "Cache-Control": "no-cache",
+      "Content-Type": "application/json",
+      Origin: "https://grok.com",
+      Pragma: "no-cache",
+      Referer: "https://grok.com/",
+      "Sec-Ch-Ua": '"Google Chrome";v="136", "Chromium";v="136", "Not(A:Brand";v="24"',
+      "Sec-Ch-Ua-Mobile": "?0",
+      "Sec-Ch-Ua-Platform": '"macOS"',
+      "Sec-Fetch-Dest": "empty",
+      "Sec-Fetch-Mode": "cors",
+      "Sec-Fetch-Site": "same-origin",
+      "User-Agent": GROK_USER_AGENT,
+      "x-statsig-id": generateStatsigId(),
+      "x-xai-request-id": crypto.randomUUID(),
+      traceparent: `00-${traceId}-${spanId}-00`,
+    };
+
+    // Strip "sso=" prefix if user pasted it
+    if (credentials.apiKey) {
+      let token = credentials.apiKey;
+      if (token.startsWith("sso=")) token = token.slice(4);
+      headers["Cookie"] = `sso=${token}`;
+    }
+
+    log?.info?.("GROK-WEB", `Query to ${model} (grok=${grokModel}, mode=${modelMode}), len=${message.length}`);
+
+    let response;
+    try {
+      response = await fetch(GROK_CHAT_API, {
+        method: "POST", headers, body: JSON.stringify(grokPayload), signal,
+      });
+    } catch (err) {
+      log?.error?.("GROK-WEB", `Fetch failed: ${err.message || String(err)}`);
+      const errResp = new Response(JSON.stringify({
+        error: { message: `Grok connection failed: ${err.message || String(err)}`, type: "upstream_error" },
+      }), { status: 502, headers: { "Content-Type": "application/json" } });
+      return { response: errResp, url: GROK_CHAT_API, headers, transformedBody: grokPayload };
+    }
+
+    if (!response.ok) {
+      const status = response.status;
+      let errMsg = `Grok returned HTTP ${status}`;
+      if (status === 401 || status === 403) errMsg = "Grok auth failed — SSO cookie may be expired. Re-paste your sso cookie value from grok.com.";
+      else if (status === 429) errMsg = "Grok rate limited. Wait a moment and retry, or rotate cookies.";
+      log?.warn?.("GROK-WEB", errMsg);
+      const errResp = new Response(JSON.stringify({
+        error: { message: errMsg, type: "upstream_error", code: `HTTP_${status}` },
+      }), { status, headers: { "Content-Type": "application/json" } });
+      return { response: errResp, url: GROK_CHAT_API, headers, transformedBody: grokPayload };
+    }
+
+    if (!response.body) {
+      const errResp = new Response(JSON.stringify({
+        error: { message: "Grok returned empty response body", type: "upstream_error" },
+      }), { status: 502, headers: { "Content-Type": "application/json" } });
+      return { response: errResp, url: GROK_CHAT_API, headers, transformedBody: grokPayload };
+    }
+
+    const cid = `chatcmpl-grok-${crypto.randomUUID().slice(0, 12)}`;
+    const created = Math.floor(Date.now() / 1000);
+
+    let finalResponse;
+    if (stream) {
+      const sseStream = buildStreamingResponse(response.body, model, cid, created, isThinking, signal);
+      finalResponse = new Response(sseStream, {
+        status: 200,
+        headers: { ...SSE_HEADERS_NO_BUFFER },
+      });
+    } else {
+      finalResponse = await buildNonStreamingResponse(response.body, model, cid, created, isThinking, signal);
+    }
+    return { response: finalResponse, url: GROK_CHAT_API, headers, transformedBody: grokPayload };
+  }
+}
+
+export default GrokWebExecutor;
diff --git a/open-sse/executors/iflow.js b/open-sse/executors/iflow.js
new file mode 100644
index 0000000..899477a
--- /dev/null
+++ b/open-sse/executors/iflow.js
@@ -0,0 +1,108 @@
+import crypto from "crypto";
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+
+/**
+ * IFlowExecutor - Executor for iFlow API with HMAC-SHA256 signature
+ */
+export class IFlowExecutor extends BaseExecutor {
+  constructor() {
+    super("iflow", PROVIDERS.iflow);
+  }
+
+  /**
+   * Generate UUID v4
+   * @returns {string} UUID v4 string
+   */
+  generateUUID() {
+    return crypto.randomUUID();
+  }
+
+  /**
+   * Create iFlow signature using HMAC-SHA256
+   * @param {string} userAgent - User agent string
+   * @param {string} sessionID - Session ID
+   * @param {number} timestamp - Unix timestamp in milliseconds
+   * @param {string} apiKey - API key for signing
+   * @returns {string} Hex-encoded signature
+   */
+  createIFlowSignature(userAgent, sessionID, timestamp, apiKey) {
+    if (!apiKey) return "";
+    const payload = `${userAgent}:${sessionID}:${timestamp}`;
+    const hmac = crypto.createHmac("sha256", apiKey);
+    hmac.update(payload);
+    return hmac.digest("hex");
+  }
+
+  /**
+   * Build headers with iFlow-specific signature
+   * @param {object} credentials - Provider credentials
+   * @param {boolean} stream - Whether streaming is enabled
+   * @returns {object} Headers object
+   */
+  buildHeaders(credentials, stream = true) {
+    // Generate session ID and timestamp
+    const sessionID = `session-${this.generateUUID()}`;
+    const timestamp = Date.now();
+
+    // Get user agent from config
+    const userAgent = this.config.headers["User-Agent"] || "iFlow-Cli";
+
+    // Get API key (prefer apiKey, fallback to accessToken)
+    const apiKey = credentials.apiKey || credentials.accessToken || "";
+
+    // Create signature
+    const signature = this.createIFlowSignature(userAgent, sessionID, timestamp, apiKey);
+
+    // Build headers
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.config.headers,
+      "session-id": sessionID,
+      "x-iflow-timestamp": timestamp.toString(),
+      "x-iflow-signature": signature
+    };
+
+    // Add authorization
+    if (credentials.apiKey) {
+      headers["Authorization"] = `Bearer ${credentials.apiKey}`;
+    }
+
+    // Add streaming header
+    if (stream) {
+      headers["Accept"] = "text/event-stream";
+    }
+
+    return headers;
+  }
+
+  /**
+   * Build URL for iFlow API
+   * @param {string} model - Model name
+   * @param {boolean} stream - Whether streaming is enabled
+   * @param {number} urlIndex - URL index for fallback
+   * @param {object} credentials - Provider credentials
+   * @returns {string} API URL
+   */
+  buildUrl(model, stream, urlIndex = 0, credentials = null) {
+    return this.config.baseUrl;
+  }
+
+  /**
+   * Transform request body - inject stream_options for usage data
+   * @param {string} model - Model name
+   * @param {object} body - Request body
+   * @param {boolean} stream - Whether streaming is enabled
+   * @param {object} credentials - Provider credentials
+   * @returns {object} Transformed body
+   */
+  transformRequest(model, body, stream, credentials) {
+    // Inject stream_options for streaming requests to get usage data
+    if (stream && body.messages && !body.stream_options) {
+      body.stream_options = { include_usage: true };
+    }
+    return body;
+  }
+}
+
+export default IFlowExecutor;
diff --git a/open-sse/executors/index.js b/open-sse/executors/index.js
new file mode 100644
index 0000000..b6091b9
--- /dev/null
+++ b/open-sse/executors/index.js
@@ -0,0 +1,90 @@
+import { AntigravityExecutor } from "./antigravity.js";
+import { AzureExecutor } from "./azure.js";
+import { GeminiCLIExecutor } from "./gemini-cli.js";
+import { GithubExecutor } from "./github.js";
+import { IFlowExecutor } from "./iflow.js";
+import { QoderExecutor } from "./qoder.js";
+import { KiroExecutor } from "./kiro.js";
+import { KimchiExecutor } from "./kimchi.js";
+import { CodexExecutor } from "./codex.js";
+import { CursorExecutor } from "./cursor.js";
+import { VertexExecutor } from "./vertex.js";
+import { QwenExecutor } from "./qwen.js";
+import { OpenCodeExecutor } from "./opencode.js";
+import { OpenCodeGoExecutor } from "./opencode-go.js";
+import { GrokWebExecutor } from "./grok-web.js";
+import { GrokCliExecutor } from "./grok-cli.js";
+import { PerplexityWebExecutor } from "./perplexity-web.js";
+import { OllamaLocalExecutor } from "./ollama-local.js";
+import { CommandCodeExecutor } from "./commandcode.js";
+import { XiaomiTokenplanExecutor } from "./xiaomi-tokenplan.js";
+import { MimoFreeExecutor } from "./mimo-free.js";
+import { CodeBuddyExecutor } from "./codebuddy-cn.js";
+import { DefaultExecutor } from "./default.js";
+
+const executors = {
+  antigravity: new AntigravityExecutor(),
+  azure: new AzureExecutor(),
+  "gemini-cli": new GeminiCLIExecutor(),
+  github: new GithubExecutor(),
+  iflow: new IFlowExecutor(),
+  qoder: new QoderExecutor(),
+  kiro: new KiroExecutor(),
+  kimchi: new KimchiExecutor(),
+  codex: new CodexExecutor(),
+  cursor: new CursorExecutor(),
+  cu: new CursorExecutor(), // Alias for cursor
+  vertex: new VertexExecutor("vertex"),
+  "vertex-partner": new VertexExecutor("vertex-partner"),
+  qwen: new QwenExecutor(),
+  opencode: new OpenCodeExecutor(),
+  "opencode-go": new OpenCodeGoExecutor(),
+  "grok-web": new GrokWebExecutor(),
+  "grok-cli": new GrokCliExecutor(),
+  gcli: new GrokCliExecutor(), // Alias
+  gb: new GrokCliExecutor(), // Alias (Grok Build)
+  "perplexity-web": new PerplexityWebExecutor(),
+  "ollama-local": new OllamaLocalExecutor(),
+  commandcode: new CommandCodeExecutor(),
+  "xiaomi-tokenplan": new XiaomiTokenplanExecutor(),
+  "mimo-free": new MimoFreeExecutor(),
+  mmf: new MimoFreeExecutor(), // Alias for mimo-free
+  "codebuddy-cn": new CodeBuddyExecutor(),
+};
+
+const defaultCache = new Map();
+
+export function getExecutor(provider) {
+  if (executors[provider]) return executors[provider];
+  if (!defaultCache.has(provider)) defaultCache.set(provider, new DefaultExecutor(provider));
+  return defaultCache.get(provider);
+}
+
+export function hasSpecializedExecutor(provider) {
+  return !!executors[provider];
+}
+
+export { BaseExecutor } from "./base.js";
+export { AntigravityExecutor } from "./antigravity.js";
+export { AzureExecutor } from "./azure.js";
+export { GeminiCLIExecutor } from "./gemini-cli.js";
+export { GithubExecutor } from "./github.js";
+export { IFlowExecutor } from "./iflow.js";
+export { QoderExecutor } from "./qoder.js";
+export { KiroExecutor } from "./kiro.js";
+export { KimchiExecutor } from "./kimchi.js";
+export { CodexExecutor } from "./codex.js";
+export { CursorExecutor } from "./cursor.js";
+export { VertexExecutor } from "./vertex.js";
+export { DefaultExecutor } from "./default.js";
+export { QwenExecutor } from "./qwen.js";
+export { OpenCodeExecutor } from "./opencode.js";
+export { OpenCodeGoExecutor } from "./opencode-go.js";
+export { GrokWebExecutor } from "./grok-web.js";
+export { GrokCliExecutor } from "./grok-cli.js";
+export { PerplexityWebExecutor } from "./perplexity-web.js";
+export { OllamaLocalExecutor } from "./ollama-local.js";
+export { CommandCodeExecutor } from "./commandcode.js";
+export { XiaomiTokenplanExecutor } from "./xiaomi-tokenplan.js";
+export { MimoFreeExecutor } from "./mimo-free.js";
+export { CodeBuddyExecutor } from "./codebuddy-cn.js";
diff --git a/open-sse/executors/kimchi.js b/open-sse/executors/kimchi.js
new file mode 100644
index 0000000..83fe6a4
--- /dev/null
+++ b/open-sse/executors/kimchi.js
@@ -0,0 +1,123 @@
+import { DefaultExecutor } from "./default.js";
+import { getCachedKimchiModelMetadata } from "../services/kimchiModels.js";
+
+const TOP_LEVEL_OPENAI_GATEWAY_DROPS = [
+  "anthropic_version",
+  "anthropic_beta",
+  "client_metadata",
+  "mcp_servers",
+  "stop_sequences",
+  "thinking",
+  "top_k",
+];
+
+function systemToText(system) {
+  if (typeof system === "string") return system;
+  if (Array.isArray(system)) {
+    return system
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (typeof part?.text === "string") return part.text;
+        return "";
+      })
+      .filter(Boolean)
+      .join("\n");
+  }
+  return "";
+}
+
+function mergeTopLevelSystem(body) {
+  if (!body?.system || !Array.isArray(body.messages)) return;
+  const text = systemToText(body.system).trim();
+  if (!text) return;
+
+  const existing = body.messages.find((msg) => msg?.role === "system");
+  if (!existing) {
+    body.messages.unshift({ role: "system", content: text });
+    return;
+  }
+
+  if (typeof existing.content === "string") {
+    existing.content = `${text}\n\n${existing.content}`;
+  } else if (Array.isArray(existing.content)) {
+    existing.content.unshift({ type: "text", text });
+  }
+}
+
+function stripMessageArtifacts(body) {
+  if (!Array.isArray(body?.messages)) return;
+  for (const msg of body.messages) {
+    if (!msg || typeof msg !== "object") continue;
+    delete msg.cache_control;
+    if (!Array.isArray(msg.content)) continue;
+    msg.content = msg.content.map((part) => {
+      if (!part || typeof part !== "object") return part;
+      const { cache_control, signature, ...clean } = part;
+      return clean;
+    });
+  }
+}
+
+function stripToolArtifacts(body) {
+  if (!Array.isArray(body?.tools)) return;
+  body.tools = body.tools.map((tool) => {
+    if (!tool || typeof tool !== "object") return tool;
+    const { cache_control, ...clean } = tool;
+    return clean;
+  });
+}
+
+// Strip `reasoning_content` echoed by clients on assistant messages — but
+// only when it's a real thinking block. `DefaultExecutor.transformRequest`
+// runs `injectReasoningContent` first and may inject a 1-char placeholder
+// (" ") for upstream validation; the placeholder is small (no token cost
+// worth stripping) and stripping it would re-trigger upstream to complain
+// about missing reasoning on the next turn. Threshold matches the
+// placeholder length with a safety margin.
+const REASONING_PLACEHOLDER_MAX_LEN = 8;
+
+export function stripReasoningContent(body) {
+  if (!Array.isArray(body?.messages)) return;
+  for (const msg of body.messages) {
+    if (msg && msg.role === "assistant" && typeof msg.reasoning_content === "string"
+        && msg.reasoning_content.length > REASONING_PLACEHOLDER_MAX_LEN) {
+      delete msg.reasoning_content;
+    }
+  }
+}
+
+function isAnthropicBackedKimchiModel(model) {
+  const meta = getCachedKimchiModelMetadata(model);
+  if (meta?.provider === "anthropic" || meta?.upstreamProvider === "anthropic") return true;
+  return /(^|[-_/])(?:claude|anthropic)(?:[-_/]|$)/i.test(String(model || ""));
+}
+
+export class KimchiExecutor extends DefaultExecutor {
+  constructor() {
+    super("kimchi");
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    const transformed = super.transformRequest(model, body, stream, credentials);
+    if (!transformed || typeof transformed !== "object") return transformed;
+
+    mergeTopLevelSystem(transformed);
+    for (const key of TOP_LEVEL_OPENAI_GATEWAY_DROPS) {
+      if (transformed[key] !== undefined) delete transformed[key];
+    }
+    delete transformed.system;
+
+    if (isAnthropicBackedKimchiModel(model)) {
+      delete transformed.reasoning_effort;
+      delete transformed.reasoning;
+      delete transformed.thinking;
+    }
+
+    stripMessageArtifacts(transformed);
+    stripToolArtifacts(transformed);
+    stripReasoningContent(transformed);
+    return transformed;
+  }
+}
+
+export default KimchiExecutor;
diff --git a/open-sse/executors/kiro.js b/open-sse/executors/kiro.js
new file mode 100644
index 0000000..556e0c7
--- /dev/null
+++ b/open-sse/executors/kiro.js
@@ -0,0 +1,592 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { resolveKiroModel } from "../config/kiroConstants.js";
+import { v4 as uuidv4 } from "uuid";
+import { refreshKiroToken } from "../services/tokenRefresh.js";
+import { SSE_DONE, SSE_HEADERS } from "../utils/sseConstants.js";
+import { getCapabilitiesForModel } from "../providers/capabilities.js";
+
+/**
+ * KiroExecutor - Executor for Kiro AI (AWS CodeWhisperer)
+ * Uses AWS CodeWhisperer streaming API with AWS EventStream binary format
+ */
+export class KiroExecutor extends BaseExecutor {
+  constructor() {
+    super("kiro", PROVIDERS.kiro);
+  }
+
+  buildHeaders(credentials, stream = true) {
+    const headers = {
+      ...this.config.headers,
+      "Amz-Sdk-Request": "attempt=1; max=3",
+      "Amz-Sdk-Invocation-Id": uuidv4()
+    };
+
+    // API-key auth: the key is stored as accessToken and sent as a bearer token
+    // exactly like an OAuth access token, but with an extra `tokentype: API_KEY`
+    // header so CodeWhisperer treats it as a long-lived API key rather than an
+    // OIDC/social access token. Mirrors the Kiro IDE headless-auth behavior.
+    // Enterprise / Microsoft Entra (external_idp) tokens are OAuth access tokens,
+    // but CodeWhisperer requires TokenType=EXTERNAL_IDP to bind them to profiles.
+    const authMethod = credentials?.providerSpecificData?.authMethod;
+    const isApiKey = authMethod === "api_key";
+    const isExternalIdp = authMethod === "external_idp";
+
+    const apiKey = credentials?.apiKey || (isApiKey ? credentials?.accessToken : null);
+    if (isApiKey && apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
+      headers["tokentype"] = "API_KEY";
+    } else if (credentials.accessToken) {
+      headers["Authorization"] = `Bearer ${credentials.accessToken}`;
+      if (isExternalIdp) {
+        headers["TokenType"] = "EXTERNAL_IDP";
+      }
+    }
+
+    return headers;
+  }
+
+  /**
+   * Auth-aware endpoint ordering.
+   *
+   * API-key Kiro connections store a raw CodeWhisperer credential (validated
+   * against codewhisperer.us-east-1.amazonaws.com via ListAvailableProfiles).
+   * The Kiro IDE gateway (runtime.*.kiro.dev) expects Kiro OIDC/social tokens
+   * and rejects an `tokentype: API_KEY` token with 401/403 — which
+   * BaseExecutor.execute() returns immediately (only 429 / network errors fall
+   * through to the next host). So for api-key auth we must try the *.amazonaws.com
+   * CodeWhisperer hosts FIRST, mirroring the Kiro-Go reference fork which never
+   * routes api-key traffic through kiro.dev. External IdP enterprise tokens also
+   * use the CodeWhisperer surface, with the `TokenType: EXTERNAL_IDP` header.
+   * Other OAuth methods keep the default order (kiro.dev first) since their
+   * tokens are what that gateway accepts.
+   */
+  getOrderedBaseUrls(credentials) {
+    const baseUrls = this.getBaseUrls();
+    const authMethod = credentials?.providerSpecificData?.authMethod;
+    // IAM Identity Center (idc) tokens are AWS SSO access tokens — the same
+    // family as external_idp/api_key. The kiro.dev gateway rejects them with
+    // 403 "bearer token invalid", so they must hit the CodeWhisperer
+    // *.amazonaws.com surface, and in the region the token was minted in
+    // (the baseUrls are hardcoded us-east-1).
+    const isCodeWhispererSurface =
+      authMethod === "api_key" || authMethod === "external_idp" || authMethod === "idc";
+    if (!isCodeWhispererSurface) return baseUrls;
+
+    const region = (credentials?.providerSpecificData?.region || "us-east-1").trim();
+    const regionalize = (u) =>
+      region && region !== "us-east-1" && u.includes("amazonaws.com")
+        ? u.replace(/([a-z]+)\.[a-z0-9-]+\.amazonaws\.com/, `$1.${region}.amazonaws.com`)
+        : u;
+
+    const amazon = baseUrls.filter((u) => u.includes("amazonaws.com")).map(regionalize);
+    const others = baseUrls.filter((u) => !u.includes("amazonaws.com"));
+    return amazon.length > 0 ? [...amazon, ...others] : baseUrls;
+  }
+
+  buildUrl(model, stream, urlIndex = 0, credentials = null) {
+    const baseUrls = this.getOrderedBaseUrls(credentials);
+    return baseUrls[urlIndex] || baseUrls[0] || this.config.baseUrl;
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    return body;
+  }
+
+  /**
+   * Kiro execute — delegate to BaseExecutor for endpoint fallback + retry, then
+   * transform the binary AWS EventStream into OpenAI-shaped SSE on success.
+   *
+   * BaseExecutor.execute() walks config.baseUrls (runtime.us-east-1.kiro.dev →
+   * codewhisperer → q) advancing to the next host on 429 (shouldRetry) and on
+   * network/5xx errors, while tryRetry handles in-place retries per `retry: {429: 2}`.
+   * Note: api-key connections reorder these so the *.amazonaws.com hosts come
+   * first — see getOrderedBaseUrls/buildUrl above.
+   * Note: the baseUrls are alternate surfaces of one regional service, so rotation
+   * is edge-level failover — it does not grant fresh 429 quota. Per-account 429
+   * spreading is handled upstream by account rotation in sse/handlers/chat.js.
+   *
+   * Errors are returned untransformed so the upstream handler can read the body,
+   * classify the status, and trigger account fallback/cooldown.
+   */
+  async execute(args) {
+    const result = await super.execute(args);
+    if (result?.response?.ok) {
+      result.response = this.transformEventStreamToSSE(result.response, args.model);
+    }
+    return result;
+  }
+
+  /**
+   * Transform AWS EventStream binary response to SSE text stream
+   * Using TransformStream instead of ReadableStream.pull() to avoid Workers timeout
+   */
+  transformEventStreamToSSE(response, model) {
+    let buffer = new Uint8Array(0);
+    let chunkIndex = 0;
+    const responseId = `chatcmpl-${Date.now()}`;
+    const created = Math.floor(Date.now() / 1000);
+    const capabilityModel = resolveKiroModel(model).upstream;
+    const contextWindow = getCapabilitiesForModel("kiro", capabilityModel).contextWindow || 200000;
+    const state = {
+      endDetected: false,
+      finishEmitted: false,
+      hasToolCalls: false,
+      hasReasoningContent: false,
+      reasoningChunkCount: 0,
+      toolCallIndex: 0,
+      seenToolIds: new Map(),
+      inThinking: false
+    };
+
+    const transformStream = new TransformStream({
+      async transform(chunk, controller) {
+             // Track output so we can emit a keepalive if this frame yields no chunk.
+        const enqueueCountBefore = chunkIndex;
+        // Append to buffer
+        const newBuffer = new Uint8Array(buffer.length + chunk.length);
+        newBuffer.set(buffer);
+        newBuffer.set(chunk, buffer.length);
+        buffer = newBuffer;
+
+        // Parse events from buffer
+        let iterations = 0;
+        const maxIterations = 1000;
+        while (buffer.length >= 16 && iterations < maxIterations) {
+          iterations++;
+          const view = new DataView(buffer.buffer, buffer.byteOffset);
+          const totalLength = view.getUint32(0, false);
+
+          if (totalLength < 16 || totalLength > buffer.length || buffer.length < totalLength) break;
+
+          const eventData = buffer.slice(0, totalLength);
+          buffer = buffer.slice(totalLength);
+
+          const event = parseEventFrame(eventData);
+          if (!event) continue;
+
+          const eventType = event.headers[":event-type"] || "";
+
+          // Track total content length for token estimation
+          if (!state.totalContentLength) state.totalContentLength = 0;
+          if (!state.contextUsagePercentage) state.contextUsagePercentage = 0;
+
+          // Handle assistantResponseEvent
+          if (eventType === "assistantResponseEvent" && event.payload?.content) {
+            let content = event.payload.content;
+
+            // Kiro Claude models can leak <thinking> blocks into the content stream.
+            // We strip these literal tags to prevent duplication, as the reasoning 
+            // is already routed correctly via reasoningContentEvent.
+            if (state.inThinking) {
+              if (content.includes("</thinking>")) {
+                state.inThinking = false;
+                const after = content.split("</thinking>").slice(1).join("</thinking>");
+                content = after.startsWith("\n") ? after.substring(1) : after;
+              } else {
+                content = ""; // Drop entirely while inside thinking block
+              }
+            } else if (content.includes("<thinking>")) {
+              state.inThinking = true;
+              if (content.includes("</thinking>")) {
+                state.inThinking = false;
+                const before = content.split("<thinking>")[0];
+                const after = content.split("</thinking>").slice(1).join("</thinking>");
+                content = before + (after.startsWith("\n") ? after.substring(1) : after);
+              } else {
+                content = content.split("<thinking>")[0];
+              }
+            }
+
+            if (!content && state.hasReasoningContent) {
+              // If we stripped everything, skip emitting an empty content chunk
+              continue;
+            }
+
+            state.totalContentLength += content.length;
+
+            const chunk = {
+              id: responseId,
+              object: "chat.completion.chunk",
+              created,
+              model,
+              choices: [{
+                index: 0,
+                delta: chunkIndex === 0
+                  ? { role: "assistant", content }
+                  : { content },
+                finish_reason: null
+              }]
+            };
+            chunkIndex++;
+            controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\n\n`));
+          }
+
+          // Handle reasoningContentEvent (Kiro thinking / reasoning)
+          // Kiro returns reasoning as a separate event when the request system
+          // prompt contains <thinking_mode>enabled</thinking_mode>. Surface it
+          // as OpenAI delta.reasoning_content so downstream translators can map
+          // it back to Claude thinking blocks / Anthropic reasoning, etc.
+          if (eventType === "reasoningContentEvent") {
+            const reasoning = event.payload?.reasoningContentEvent || event.payload || {};
+            const reasoningText = (typeof reasoning === "string")
+              ? reasoning
+              : (reasoning.text || reasoning.content || "");
+            if (reasoningText) {
+              state.hasReasoningContent = true;
+              state.totalContentLength += reasoningText.length;
+
+              const reasoningDelta = state.reasoningChunkCount === 0 && chunkIndex === 0
+                ? { role: "assistant", reasoning_content: reasoningText }
+                : { reasoning_content: reasoningText };
+
+              const chunk = {
+                id: responseId,
+                object: "chat.completion.chunk",
+                created,
+                model,
+                choices: [{
+                  index: 0,
+                  delta: reasoningDelta,
+                  finish_reason: null
+                }]
+              };
+              chunkIndex++;
+              state.reasoningChunkCount++;
+              controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\n\n`));
+            }
+          }
+
+          // Handle codeEvent
+          if (eventType === "codeEvent" && event.payload?.content) {
+            const chunk = {
+              id: responseId,
+              object: "chat.completion.chunk",
+              created,
+              model,
+              choices: [{
+                index: 0,
+                delta: { content: event.payload.content },
+                finish_reason: null
+              }]
+            };
+            chunkIndex++;
+            controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\n\n`));
+          }
+
+          // Handle toolUseEvent
+          if (eventType === "toolUseEvent" && event.payload) {
+            state.hasToolCalls = true;
+            const toolUse = event.payload;
+            const toolUses = Array.isArray(toolUse) ? toolUse : [toolUse];
+
+            for (const singleToolUse of toolUses) {
+              const toolCallId = singleToolUse.toolUseId || `call_${Date.now()}`;
+              const toolName = singleToolUse.name || "";
+              const toolInput = singleToolUse.input;
+
+              let toolIndex;
+              const isNewTool = !state.seenToolIds.has(toolCallId);
+
+              if (isNewTool) {
+                toolIndex = state.toolCallIndex++;
+                state.seenToolIds.set(toolCallId, toolIndex);
+
+                const startChunk = {
+                  id: responseId,
+                  object: "chat.completion.chunk",
+                  created,
+                  model,
+                  choices: [{
+                    index: 0,
+                    delta: {
+                      ...(chunkIndex === 0 ? { role: "assistant" } : {}),
+                      tool_calls: [{
+                        index: toolIndex,
+                        id: toolCallId,
+                        type: "function",
+                        function: {
+                          name: toolName,
+                          arguments: ""
+                        }
+                      }]
+                    },
+                    finish_reason: null
+                  }]
+                };
+                chunkIndex++;
+                controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(startChunk)}\n\n`));
+              } else {
+                toolIndex = state.seenToolIds.get(toolCallId);
+              }
+
+              if (toolInput !== undefined) {
+                let argumentsStr;
+
+                if (typeof toolInput === 'string') {
+                  argumentsStr = toolInput;
+                } else if (typeof toolInput === 'object') {
+                  argumentsStr = JSON.stringify(toolInput);
+                } else {
+                  continue;
+                }
+
+                const argsChunk = {
+                  id: responseId,
+                  object: "chat.completion.chunk",
+                  created,
+                  model,
+                  choices: [{
+                    index: 0,
+                    delta: {
+                      tool_calls: [{
+                        index: toolIndex,
+                        function: {
+                          arguments: argumentsStr
+                        }
+                      }]
+                    },
+                    finish_reason: null
+                  }]
+                };
+                chunkIndex++;
+                controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(argsChunk)}\n\n`));
+              }
+            }
+          }
+
+          // Handle messageStopEvent
+          if (eventType === "messageStopEvent") {
+            const chunk = {
+              id: responseId,
+              object: "chat.completion.chunk",
+              created,
+              model,
+              choices: [{
+                index: 0,
+                delta: {},
+                finish_reason: state.hasToolCalls ? "tool_calls" : "stop"
+              }]
+            };
+            state.finishEmitted = true;
+            controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\n\n`));
+          }
+
+          // Handle contextUsageEvent to extract contextUsagePercentage
+          if (eventType === "contextUsageEvent" && event.payload?.contextUsagePercentage) {
+            state.contextUsagePercentage = event.payload.contextUsagePercentage;
+            // Mark that we received context usage event
+            state.hasContextUsage = true;
+          }
+
+          // Handle meteringEvent - mark that we received it
+          if (eventType === "meteringEvent") {
+            state.hasMeteringEvent = true;
+          }
+
+          // Handle metricsEvent for token usage
+          if (eventType === "metricsEvent") {
+            // Extract usage data from metricsEvent payload
+            const metrics = event.payload?.metricsEvent || event.payload;
+            if (metrics && typeof metrics === 'object') {
+              const inputTokens = metrics.inputTokens || 0;
+              const outputTokens = metrics.outputTokens || 0;
+              // ponytail: Amazon Q upstream does not expose cache fields today,
+              // but pick up cache_read_input_tokens / cache_creation_input_tokens
+              // if the event shape grows them so cost tracking stays accurate.
+              const cachedTokens = metrics.cacheReadInputTokens || metrics.cache_read_input_tokens || 0;
+              const cacheCreationInputTokens = metrics.cacheCreationInputTokens || metrics.cache_creation_input_tokens || 0;
+
+              if (inputTokens > 0 || outputTokens > 0) {
+                state.usage = {
+                  prompt_tokens: inputTokens,
+                  completion_tokens: outputTokens,
+                  total_tokens: inputTokens + outputTokens
+                };
+                // Kiro is Claude-backed: inputTokens EXCLUDES cache (Claude convention),
+                // not inclusive like OpenAI's cached_tokens. Emit cache_read_input_tokens
+                // (not cached_tokens) so canonicalizeUsage takes the Claude fold path and
+                // correctly adds cache back into prompt_tokens instead of undercharging.
+                if (cachedTokens > 0) state.usage.cache_read_input_tokens = cachedTokens;
+                if (cacheCreationInputTokens > 0) state.usage.cache_creation_input_tokens = cacheCreationInputTokens;
+              }
+            }
+          }
+
+          // Emit final chunk only after receiving BOTH meteringEvent AND contextUsageEvent
+          if (state.hasMeteringEvent && state.hasContextUsage && !state.finishEmitted) {
+            state.finishEmitted = true;
+
+            // Estimate tokens if not available from events
+            if (!state.usage) {
+              // Estimate output tokens from content length
+              const estimatedOutputTokens = state.totalContentLength > 0
+                ? Math.max(1, Math.floor(state.totalContentLength / 4))
+                : 0;
+
+              // Estimate input tokens from contextUsagePercentage
+              const estimatedInputTokens = state.contextUsagePercentage > 0
+                ? Math.floor(state.contextUsagePercentage * contextWindow / 100)
+                : 0;
+
+              state.usage = {
+                prompt_tokens: estimatedInputTokens,
+                completion_tokens: estimatedOutputTokens,
+                total_tokens: estimatedInputTokens + estimatedOutputTokens
+              };
+            }
+
+            const finishChunk = {
+              id: responseId,
+              object: "chat.completion.chunk",
+              created,
+              model,
+              choices: [{
+                index: 0,
+                delta: {},
+                finish_reason: state.hasToolCalls ? "tool_calls" : "stop"
+              }]
+            };
+
+            // Include usage in final chunk if available
+            if (state.usage) {
+              finishChunk.usage = state.usage;
+            }
+
+            controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(finishChunk)}\n\n`));
+          }
+        }
+
+        if (iterations >= maxIterations) {
+          console.warn("[Kiro] Max iterations reached in event parsing");
+        }
+
+        // No client chunk produced this frame — emit an SSE comment keepalive
+                // so the stall watchdog sees upstream activity (ignored by parser/client).
+                if (chunkIndex === enqueueCountBefore && !state.finishEmitted) {
+                  controller.enqueue(new TextEncoder().encode(": ka\n\n"));
+                }
+      },
+
+      flush(controller) {
+        // Emit finish chunk if not already sent
+        if (!state.finishEmitted) {
+          state.finishEmitted = true;
+          const finishChunk = {
+            id: responseId,
+            object: "chat.completion.chunk",
+            created,
+            model,
+            choices: [{
+              index: 0,
+              delta: {},
+              finish_reason: state.hasToolCalls ? "tool_calls" : "stop"
+            }]
+          };
+          controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(finishChunk)}\n\n`));
+        }
+
+        // Send final done message
+        controller.enqueue(new TextEncoder().encode(SSE_DONE));
+      }
+    });
+
+    // Pipe response body through transform stream
+    if (!response.body) {
+      return new Response(SSE_DONE, { status: response.status, headers: { "Content-Type": "text/event-stream" } });
+    }
+    const transformedStream = response.body.pipeThrough(transformStream);
+
+    return new Response(transformedStream, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: { ...SSE_HEADERS }
+    });
+  }
+
+  async refreshCredentials(credentials, log, proxyOptions = null) {
+    if (!credentials.refreshToken) return null;
+
+    try {
+      // Use centralized refreshKiroToken function (handles both AWS SSO OIDC and Social Auth)
+      const result = await refreshKiroToken(
+        credentials.refreshToken,
+        credentials.providerSpecificData,
+        log,
+        proxyOptions
+      );
+
+      return result;
+    } catch (error) {
+      log?.error?.("TOKEN", `Kiro refresh error: ${error.message}`);
+      return null;
+    }
+  }
+}
+
+/**
+ * Parse AWS EventStream frame
+ */
+function parseEventFrame(data) {
+  try {
+    const view = new DataView(data.buffer, data.byteOffset);
+    const headersLength = view.getUint32(4, false);
+
+    // Parse headers
+    const headers = {};
+    let offset = 12; // After prelude
+    const headerEnd = 12 + headersLength;
+
+    while (offset < headerEnd && offset < data.length) {
+      const nameLen = data[offset];
+      offset++;
+      if (offset + nameLen > data.length) break;
+
+      const name = new TextDecoder().decode(data.slice(offset, offset + nameLen));
+      offset += nameLen;
+
+      const headerType = data[offset];
+      offset++;
+
+      if (headerType === 7) { // String type
+        const valueLen = (data[offset] << 8) | data[offset + 1];
+        offset += 2;
+        if (offset + valueLen > data.length) break;
+
+        const value = new TextDecoder().decode(data.slice(offset, offset + valueLen));
+        offset += valueLen;
+        headers[name] = value;
+      } else {
+        break;
+      }
+    }
+
+    // Parse payload
+    const payloadStart = 12 + headersLength;
+    const payloadEnd = data.length - 4; // Exclude message CRC
+
+    let payload = null;
+    if (payloadEnd > payloadStart) {
+      const payloadStr = new TextDecoder().decode(data.slice(payloadStart, payloadEnd));
+
+      // Skip empty or whitespace-only payloads
+      if (!payloadStr || !payloadStr.trim()) {
+        return { headers, payload: null };
+      }
+
+      try {
+        payload = JSON.parse(payloadStr);
+      } catch (parseError) {
+        // Log parse error for debugging
+        console.warn(`[Kiro] Failed to parse payload: ${parseError.message} | payload: ${payloadStr.substring(0, 100)}`);
+        payload = { raw: payloadStr };
+      }
+    }
+
+    return { headers, payload };
+  } catch {
+    return null;
+  }
+}
+
+export default KiroExecutor;
diff --git a/open-sse/executors/mimo-free.js b/open-sse/executors/mimo-free.js
new file mode 100644
index 0000000..04d4467
--- /dev/null
+++ b/open-sse/executors/mimo-free.js
@@ -0,0 +1,167 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+import { createHash } from "crypto";
+import os from "os";
+
+const BOOTSTRAP_URL = "https://api.xiaomimimo.com/api/free-ai/bootstrap";
+const CHAT_URL = PROVIDERS["mimo-free"].baseUrl;
+const SESSION_AFFINITY_PREFIX = "ses_";
+const SESSION_ID_LENGTH = 24;
+const JWT_FALLBACK_TTL_SEC = 3000;
+const JWT_EXPIRY_BUFFER_MS = 300000;
+const SESSION_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789";
+
+// Anti-abuse gate: upstream rejects requests without a Chrome-like User-Agent with 403 "Illegal access"
+const USER_AGENTS = [
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+  "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+];
+
+// Anti-abuse gate marker: the free chat endpoint returns 403 "Illegal access"
+// unless a system message contains this exact MiMoCode signature substring.
+export const MIMO_SYSTEM_MARKER =
+  "You are MiMoCode, an interactive CLI tool that helps users with software engineering tasks.";
+
+// In-memory JWT cache (per-process, survives across requests but not restarts)
+let cachedJwt = null;
+let jwtExpiresAt = 0;
+
+// Device fingerprint reused as the bootstrap "client" — stable per machine
+function generateFingerprint() {
+  let username = "unknown-user";
+  try {
+    username = os.userInfo().username;
+  } catch {
+    // ignore
+  }
+  const cpu = (os.cpus()[0]?.model || "unknown-cpu").trim();
+  const seed = `${os.hostname()}|${os.platform()}|${os.arch()}|${cpu}|${username}`;
+  return createHash("sha256").update(seed).digest("hex");
+}
+
+function generateSessionId() {
+  let id = SESSION_AFFINITY_PREFIX;
+  for (let i = 0; i < SESSION_ID_LENGTH; i++) {
+    id += SESSION_CHARS[Math.floor(Math.random() * SESSION_CHARS.length)];
+  }
+  return id;
+}
+
+// Derive expiry from the JWT exp claim; fall back to a fixed TTL when unparseable
+function parseJwtExp(jwt) {
+  try {
+    const payload = JSON.parse(Buffer.from(jwt.split(".")[1], "base64").toString());
+    if (payload.exp) return payload.exp * 1000;
+  } catch {
+    // ignore
+  }
+  return Date.now() + JWT_FALLBACK_TTL_SEC * 1000;
+}
+
+// Ensure the body carries the anti-abuse marker in a system message (idempotent)
+function injectSystemMarker(body) {
+  const messages = body?.messages;
+  if (!Array.isArray(messages)) return body;
+  const hasMarker = messages.some(
+    (m) => m?.role === "system" && typeof m.content === "string" && m.content.includes(MIMO_SYSTEM_MARKER)
+  );
+  if (hasMarker) return body;
+  return { ...body, messages: [{ role: "system", content: MIMO_SYSTEM_MARKER }, ...messages] };
+}
+
+function resetJwtCache() {
+  cachedJwt = null;
+  jwtExpiresAt = 0;
+}
+
+async function bootstrapJwt(proxyOptions = null) {
+  if (cachedJwt && Date.now() < jwtExpiresAt - JWT_EXPIRY_BUFFER_MS) {
+    return cachedJwt;
+  }
+
+  const response = await proxyAwareFetch(BOOTSTRAP_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENTS[Math.floor(Math.random() * USER_AGENTS.length)],
+    },
+    body: JSON.stringify({ client: generateFingerprint() }),
+  }, proxyOptions);
+
+  if (!response.ok) {
+    throw new Error(`MiMo bootstrap failed: ${response.status}`);
+  }
+
+  const data = await response.json();
+  if (!data.jwt) {
+    throw new Error("MiMo bootstrap returned no JWT");
+  }
+
+  cachedJwt = data.jwt;
+  jwtExpiresAt = parseJwtExp(data.jwt);
+  return cachedJwt;
+}
+
+export class MimoFreeExecutor extends BaseExecutor {
+  constructor() {
+    super("mimo-free", PROVIDERS["mimo-free"]);
+    this.sessionId = generateSessionId();
+  }
+
+  buildUrl() {
+    return CHAT_URL;
+  }
+
+  buildHeaders(credentials, stream = true) {
+    return {
+      "Content-Type": "application/json",
+      "X-Mimo-Source": "mimocode-cli-free",
+      "User-Agent": USER_AGENTS[Math.floor(Math.random() * USER_AGENTS.length)],
+      "x-session-affinity": this.sessionId,
+      "Accept": stream ? "text/event-stream" : "application/json",
+    };
+  }
+
+  transformRequest(model, body) {
+    return injectSystemMarker(body);
+  }
+
+  async execute({ model, body, stream, credentials, signal, log, proxyOptions = null }) {
+    let jwt;
+    try {
+      jwt = await bootstrapJwt(proxyOptions);
+    } catch (error) {
+      log?.error?.("AUTH", `MiMo bootstrap failed: ${error.message}`);
+      throw error;
+    }
+
+    const url = this.buildUrl();
+    const transformedBody = this.transformRequest(model, body);
+    const headers = { ...this.buildHeaders(credentials, stream), "Authorization": `Bearer ${jwt}` };
+    const bodyStr = JSON.stringify(transformedBody);
+    log?.debug?.("FETCH", `MIMO-FREE → ${url} | body=${bodyStr.length}B`);
+
+    const response = await proxyAwareFetch(url, { method: "POST", headers, body: bodyStr, signal }, proxyOptions);
+
+    // On auth failure, invalidate cache and retry once with a fresh JWT
+    if (response.status === 401 || response.status === 403) {
+      log?.debug?.("AUTH", `MiMo auth failed (${response.status}), re-bootstrapping...`);
+      resetJwtCache();
+      jwt = await bootstrapJwt(proxyOptions);
+      headers["Authorization"] = `Bearer ${jwt}`;
+      const retryResponse = await proxyAwareFetch(url, { method: "POST", headers, body: bodyStr, signal }, proxyOptions);
+      return { response: retryResponse, url, headers, transformedBody };
+    }
+
+    return { response, url, headers, transformedBody };
+  }
+}
+
+export const __test__ = {
+  generateFingerprint, generateSessionId, bootstrapJwt, resetJwtCache, parseJwtExp,
+  injectSystemMarker, MIMO_SYSTEM_MARKER, BOOTSTRAP_URL, CHAT_URL, SESSION_AFFINITY_PREFIX,
+};
+
+export default MimoFreeExecutor;
diff --git a/open-sse/executors/ollama-local.js b/open-sse/executors/ollama-local.js
new file mode 100644
index 0000000..83de7b8
--- /dev/null
+++ b/open-sse/executors/ollama-local.js
@@ -0,0 +1,14 @@
+import { DefaultExecutor } from "./default.js";
+import { resolveOllamaLocalHost } from "../config/providers.js";
+
+export class OllamaLocalExecutor extends DefaultExecutor {
+  constructor() {
+    super("ollama-local");
+  }
+
+  buildUrl(model, stream, urlIndex = 0, credentials = null) {
+    return `${resolveOllamaLocalHost(credentials)}/api/chat`;
+  }
+}
+
+export default OllamaLocalExecutor;
diff --git a/open-sse/executors/opencode-go.js b/open-sse/executors/opencode-go.js
new file mode 100644
index 0000000..7bf47ed
--- /dev/null
+++ b/open-sse/executors/opencode-go.js
@@ -0,0 +1,49 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { injectReasoningContent } from "../utils/reasoningContentInjector.js";
+import { ANTHROPIC_API_VERSION } from "../providers/shared.js";
+
+// Models that use /zen/go/v1/messages (Anthropic/Claude format + x-api-key auth)
+const MESSAGES_FORMAT_MODELS = new Set([
+  "minimax-m3",
+  "minimax-m2.7",
+  "minimax-m2.5",
+  "qwen3.7-max",
+  "qwen3.7-plus",
+  "qwen3.6-plus",
+]);
+
+const BASE = "https://opencode.ai/zen/go/v1";
+
+export class OpenCodeGoExecutor extends BaseExecutor {
+  constructor() {
+    super("opencode-go", PROVIDERS["opencode-go"]);
+  }
+
+  // buildUrl runs before buildHeaders in BaseExecutor.execute, cache model here
+  buildUrl(model) {
+    this._lastModel = model;
+    return MESSAGES_FORMAT_MODELS.has(model)
+      ? `${BASE}/messages`
+      : `${BASE}/chat/completions`;
+  }
+
+  buildHeaders(credentials, stream = true) {
+    const key = credentials?.apiKey || credentials?.accessToken;
+    const headers = { "Content-Type": "application/json" };
+
+    if (MESSAGES_FORMAT_MODELS.has(this._lastModel)) {
+      headers["x-api-key"] = key;
+      headers["anthropic-version"] = ANTHROPIC_API_VERSION;
+    } else {
+      headers["Authorization"] = `Bearer ${key}`;
+    }
+
+    if (stream) headers["Accept"] = "text/event-stream";
+    return headers;
+  }
+
+  transformRequest(model, body) {
+    return injectReasoningContent({ provider: this.provider, model, body });
+  }
+}
diff --git a/open-sse/executors/opencode.js b/open-sse/executors/opencode.js
new file mode 100644
index 0000000..f7aee21
--- /dev/null
+++ b/open-sse/executors/opencode.js
@@ -0,0 +1,32 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { injectReasoningContent } from "../utils/reasoningContentInjector.js";
+
+// Models that use /zen/v1/messages (claude format)
+const MESSAGES_MODELS = new Set();
+
+export class OpenCodeExecutor extends BaseExecutor {
+  constructor() {
+    super("opencode", PROVIDERS.opencode);
+  }
+
+  transformRequest(model, body) {
+    return injectReasoningContent({ provider: this.provider, model, body });
+  }
+
+  buildUrl(model) {
+    const base = this.config.baseUrl;
+    return MESSAGES_MODELS.has(model)
+      ? `${base}/zen/v1/messages`
+      : `${base}/zen/v1/chat/completions`;
+  }
+
+  buildHeaders() {
+    return {
+      "Content-Type": "application/json",
+      "Authorization": "Bearer public",
+      "x-opencode-client": "desktop",
+      "Accept": "text/event-stream"
+    };
+  }
+}
diff --git a/open-sse/executors/perplexity-web.js b/open-sse/executors/perplexity-web.js
new file mode 100644
index 0000000..87d6457
--- /dev/null
+++ b/open-sse/executors/perplexity-web.js
@@ -0,0 +1,505 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { SSE_DONE, SSE_HEADERS_NO_BUFFER } from "../utils/sseConstants.js";
+import { sseChunk } from "../utils/sse.js";
+
+const PPLX_SSE_ENDPOINT = PROVIDERS["perplexity-web"].baseUrl;
+const PPLX_API_VERSION = "2.18";
+const PPLX_USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36";
+
+const MODEL_MAP = {
+  "pplx-auto": ["concise", "pplx_pro"],
+  "pplx-sonar": ["copilot", "experimental"],
+  "pplx-gpt": ["copilot", "gpt54"],
+  "pplx-gemini": ["copilot", "gemini31pro_high"],
+  "pplx-sonnet": ["copilot", "claude46sonnet"],
+  "pplx-opus": ["copilot", "claude46opus"],
+  "pplx-nemotron": ["copilot", "nv_nemotron_3_super"],
+};
+
+const THINKING_MAP = {
+  "pplx-gpt": "gpt54_thinking",
+  "pplx-sonnet": "claude46sonnetthinking",
+  "pplx-opus": "claude46opusthinking",
+};
+
+const CITATION_RE = /\[\d+\]/g;
+const GROK_TAG_RE = /<grok:[^>]*>.*?<\/grok:[^>]*>/gs;
+const GROK_SELF_RE = /<grok:[^>]*\/>/g;
+const XML_DECL_RE = /<[?]xml[^?]*[?]>/g;
+const RESPONSE_TAG_RE = /<\/?response\b[^>]*>/gi;
+const MULTI_SPACE = / {2,}/g;
+const MULTI_NL = /\n{3,}/g;
+
+const SESSION_MAX_AGE_MS = 3600_000;
+const SESSION_MAX_ENTRIES = 200;
+
+const sessionCache = new Map();
+
+// FNV-1a hash for session key lookup
+function sessionKey(history) {
+  const parts = history.map((h) => `${h.role}:${h.content}`).join("\n");
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < parts.length; i++) {
+    hash ^= parts.charCodeAt(i);
+    hash = (hash * 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+function sessionLookup(history) {
+  if (history.length === 0) return null;
+  const key = sessionKey(history);
+  const entry = sessionCache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.ts > SESSION_MAX_AGE_MS) {
+    sessionCache.delete(key);
+    return null;
+  }
+  return entry.backendUuid;
+}
+
+function sessionStore(history, currentMsg, responseText, backendUuid) {
+  if (!backendUuid) return;
+  const full = [...history, { role: "user", content: currentMsg }, { role: "assistant", content: responseText }];
+  const key = sessionKey(full);
+  sessionCache.set(key, { backendUuid, ts: Date.now() });
+  if (sessionCache.size > SESSION_MAX_ENTRIES) {
+    let oldestKey = null;
+    let oldestTs = Infinity;
+    for (const [k, v] of sessionCache) {
+      if (v.ts < oldestTs) { oldestTs = v.ts; oldestKey = k; }
+    }
+    if (oldestKey) sessionCache.delete(oldestKey);
+  }
+}
+
+function cleanResponse(text, strip = true) {
+  let t = text;
+  t = t.replace(XML_DECL_RE, "");
+  t = t.replace(CITATION_RE, "");
+  t = t.replace(GROK_TAG_RE, "");
+  t = t.replace(GROK_SELF_RE, "");
+  t = t.replace(RESPONSE_TAG_RE, "");
+  if (strip) {
+    t = t.replace(MULTI_SPACE, " ");
+    t = t.replace(MULTI_NL, "\n\n");
+    t = t.trim();
+  }
+  return t;
+}
+
+async function* readPplxSseEvents(body, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let dataLines = [];
+
+  function flush() {
+    if (dataLines.length === 0) return null;
+    const payload = dataLines.join("\n");
+    dataLines = [];
+    const trimmed = payload.trim();
+    if (!trimmed || trimmed === "[DONE]") return "done";
+    try { return JSON.parse(trimmed); } catch { return null; }
+  }
+
+  try {
+    while (true) {
+      if (signal?.aborted) return;
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      while (true) {
+        const idx = buffer.indexOf("\n");
+        if (idx < 0) break;
+        const rawLine = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 1);
+        const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+        if (line === "") {
+          const parsed = flush();
+          if (parsed === "done") return;
+          if (parsed) yield parsed;
+          continue;
+        }
+        if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+        if (line === "event: end_of_stream") return;
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer.trim().startsWith("data:")) dataLines.push(buffer.trim().slice(5).trimStart());
+    const tail = flush();
+    if (tail && tail !== "done") yield tail;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function parseOpenAIMessages(messages) {
+  let systemMsg = "";
+  const history = [];
+  for (const msg of messages) {
+    let role = String(msg.role || "user");
+    if (role === "developer") role = "system";
+    let content = "";
+    if (typeof msg.content === "string") content = msg.content;
+    else if (Array.isArray(msg.content)) {
+      content = msg.content.filter((c) => c.type === "text").map((c) => String(c.text || "")).join(" ");
+    }
+    if (!content.trim()) continue;
+    if (role === "system") systemMsg += content + "\n";
+    else if (role === "user" || role === "assistant") history.push({ role, content });
+  }
+  let currentMsg = "";
+  if (history.length > 0 && history[history.length - 1].role === "user") {
+    currentMsg = history.pop().content;
+  }
+  return { systemMsg, history, currentMsg };
+}
+
+function buildPplxRequestBody(query, mode, modelPref, followUpUuid) {
+  const tz = typeof Intl !== "undefined" ? Intl.DateTimeFormat().resolvedOptions().timeZone : "UTC";
+  return {
+    query_str: query,
+    params: {
+      query_str: query,
+      search_focus: "internet",
+      mode,
+      model_preference: modelPref,
+      sources: ["web"],
+      attachments: [],
+      frontend_uuid: crypto.randomUUID(),
+      frontend_context_uuid: crypto.randomUUID(),
+      version: PPLX_API_VERSION,
+      language: "en-US",
+      timezone: tz,
+      search_recency_filter: null,
+      is_incognito: true,
+      use_schematized_api: true,
+      last_backend_uuid: followUpUuid,
+    },
+  };
+}
+
+function formatToolsHint(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) return "";
+  const lines = tools.map((t) => {
+    const fn = t?.function || t || {};
+    const name = fn.name || "unnamed";
+    const desc = (fn.description || "").split("\n")[0].slice(0, 200);
+    return `- ${name}: ${desc}`;
+  });
+  return `Available tools (reference only, cannot invoke):\n${lines.join("\n")}`;
+}
+
+function buildQuery(parsed, followUpUuid, tools) {
+  if (followUpUuid) return parsed.currentMsg;
+  const obj = {};
+  const instr = [];
+  if (parsed.systemMsg.trim()) instr.push(parsed.systemMsg.trim());
+  const toolsHint = formatToolsHint(tools);
+  if (toolsHint) instr.push(toolsHint);
+  instr.push("You have built-in web search. Answer questions directly using search results.");
+  obj.instructions = instr;
+  if (parsed.history.length > 0) obj.history = parsed.history;
+  if (parsed.currentMsg) obj.query = parsed.currentMsg;
+  else if (parsed.history.length === 0) obj.query = "";
+  const json = JSON.stringify(obj);
+  return json.length > 96000 ? json.slice(-96000) : json;
+}
+
+async function* extractContent(eventStream, signal) {
+  let fullAnswer = "";
+  let backendUuid = null;
+  let seenLen = 0;
+  const seenThinking = new Set();
+
+  for await (const event of readPplxSseEvents(eventStream, signal)) {
+    if (event.error_code || event.error_message) {
+      yield { error: event.error_message || `Perplexity error: ${event.error_code}`, done: true };
+      return;
+    }
+    if (event.backend_uuid) backendUuid = event.backend_uuid;
+
+    const blocks = event.blocks ?? [];
+    for (const block of blocks) {
+      const usage = block.intended_usage ?? "";
+
+      if (usage === "pro_search_steps" && block.plan_block?.steps) {
+        for (const step of block.plan_block.steps) {
+          if (step.step_type === "SEARCH_WEB") {
+            for (const q of step.search_web_content?.queries ?? []) {
+              const qr = q.query ?? "";
+              if (qr && !seenThinking.has(qr)) {
+                seenThinking.add(qr);
+                yield { thinking: `Searching: ${qr}`, backendUuid: backendUuid ?? undefined };
+              }
+            }
+          } else if (step.step_type === "READ_RESULTS") {
+            for (const u of (step.read_results_content?.urls ?? []).slice(0, 3)) {
+              if (u && !seenThinking.has(u)) {
+                seenThinking.add(u);
+                yield { thinking: `Reading: ${u}`, backendUuid: backendUuid ?? undefined };
+              }
+            }
+          }
+        }
+      }
+
+      if (usage === "plan" && block.plan_block?.goals) {
+        for (const goal of block.plan_block.goals) {
+          const desc = goal.description ?? "";
+          if (desc && !seenThinking.has(desc)) {
+            seenThinking.add(desc);
+            yield { thinking: desc, backendUuid: backendUuid ?? undefined };
+          }
+        }
+      }
+
+      if (!usage.includes("markdown")) continue;
+      const mb = block.markdown_block;
+      if (!mb) continue;
+      const chunks = mb.chunks ?? [];
+      if (chunks.length === 0) continue;
+
+      if (mb.progress === "DONE") {
+        fullAnswer = chunks.join("");
+      } else {
+        const chunkText = chunks.join("");
+        const cumulative = fullAnswer + chunkText;
+        if (cumulative.length > seenLen) {
+          const delta = cumulative.slice(seenLen);
+          fullAnswer = cumulative;
+          seenLen = cumulative.length;
+          yield { delta, answer: fullAnswer, backendUuid: backendUuid ?? undefined };
+        }
+      }
+    }
+
+    if (blocks.length === 0 && event.text) {
+      const t = event.text.trim();
+      if (t.length > seenLen) {
+        const delta = t.slice(seenLen);
+        fullAnswer = t;
+        seenLen = t.length;
+        yield { delta, answer: fullAnswer, backendUuid: backendUuid ?? undefined };
+      }
+    }
+
+    if (event.final || event.status === "COMPLETED") break;
+  }
+  yield { delta: "", answer: fullAnswer, backendUuid: backendUuid ?? undefined, done: true };
+}
+
+function buildStreamingResponse(eventStream, model, cid, created, history, currentMsg, signal) {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        controller.enqueue(encoder.encode(sseChunk({
+          id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: null,
+          choices: [{ index: 0, delta: { role: "assistant" }, finish_reason: null, logprobs: null }],
+        })));
+
+        let fullAnswer = "";
+        let respBackendUuid = null;
+
+        for await (const chunk of extractContent(eventStream, signal)) {
+          if (chunk.backendUuid) respBackendUuid = chunk.backendUuid;
+          if (chunk.error) {
+            controller.enqueue(encoder.encode(sseChunk({
+              id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: null,
+              choices: [{ index: 0, delta: { content: `[Error: ${chunk.error}]` }, finish_reason: null, logprobs: null }],
+            })));
+            break;
+          }
+          if (chunk.thinking) {
+            controller.enqueue(encoder.encode(sseChunk({
+              id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: null,
+              choices: [{ index: 0, delta: { reasoning_content: chunk.thinking + "\n" }, finish_reason: null, logprobs: null }],
+            })));
+            continue;
+          }
+          if (chunk.done) { fullAnswer = chunk.answer || fullAnswer; break; }
+          let dt = chunk.delta || "";
+          if (dt) {
+            dt = cleanResponse(dt, false);
+            if (dt) {
+              controller.enqueue(encoder.encode(sseChunk({
+                id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: null,
+                choices: [{ index: 0, delta: { content: dt }, finish_reason: null, logprobs: null }],
+              })));
+            }
+          }
+          if (chunk.answer) fullAnswer = chunk.answer;
+        }
+
+        controller.enqueue(encoder.encode(sseChunk({
+          id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: null,
+          choices: [{ index: 0, delta: {}, finish_reason: "stop", logprobs: null }],
+        })));
+        controller.enqueue(encoder.encode(SSE_DONE));
+
+        sessionStore(history, currentMsg, cleanResponse(fullAnswer), respBackendUuid);
+      } catch (err) {
+        controller.enqueue(encoder.encode(sseChunk({
+          id: cid, object: "chat.completion.chunk", created, model, system_fingerprint: null,
+          choices: [{ index: 0, delta: { content: `[Stream error: ${err.message || String(err)}]` }, finish_reason: "stop", logprobs: null }],
+        })));
+        controller.enqueue(encoder.encode(SSE_DONE));
+      } finally {
+        controller.close();
+      }
+    },
+  });
+}
+
+async function buildNonStreamingResponse(eventStream, model, cid, created, history, currentMsg, signal) {
+  let fullAnswer = "";
+  let respBackendUuid = null;
+  const thinkingParts = [];
+
+  for await (const chunk of extractContent(eventStream, signal)) {
+    if (chunk.backendUuid) respBackendUuid = chunk.backendUuid;
+    if (chunk.error) {
+      return new Response(JSON.stringify({
+        error: { message: chunk.error, type: "upstream_error", code: "PPLX_ERROR" },
+      }), { status: 502, headers: { "Content-Type": "application/json" } });
+    }
+    if (chunk.thinking) { thinkingParts.push(chunk.thinking); continue; }
+    if (chunk.done) { fullAnswer = chunk.answer || fullAnswer; break; }
+    if (chunk.answer) fullAnswer = chunk.answer;
+  }
+
+  fullAnswer = cleanResponse(fullAnswer);
+  sessionStore(history, currentMsg, fullAnswer, respBackendUuid);
+
+  const reasoningContent = thinkingParts.length > 0 ? thinkingParts.join("\n") : undefined;
+  const msg = { role: "assistant", content: fullAnswer };
+  if (reasoningContent) msg.reasoning_content = reasoningContent;
+
+  const promptTokens = Math.ceil(currentMsg.length / 4);
+  const completionTokens = Math.ceil(fullAnswer.length / 4);
+
+  return new Response(JSON.stringify({
+    id: cid, object: "chat.completion", created, model, system_fingerprint: null,
+    choices: [{ index: 0, message: msg, finish_reason: "stop", logprobs: null }],
+    usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: promptTokens + completionTokens },
+  }), { status: 200, headers: { "Content-Type": "application/json" } });
+}
+
+export class PerplexityWebExecutor extends BaseExecutor {
+  constructor() {
+    super("perplexity-web", PROVIDERS["perplexity-web"]);
+  }
+
+  async execute({ model, body, stream, credentials, signal, log }) {
+    const messages = body?.messages;
+    if (!messages || !Array.isArray(messages) || messages.length === 0) {
+      const errResp = new Response(JSON.stringify({
+        error: { message: "Missing or empty messages array", type: "invalid_request" },
+      }), { status: 400, headers: { "Content-Type": "application/json" } });
+      return { response: errResp, url: PPLX_SSE_ENDPOINT, headers: {}, transformedBody: body };
+    }
+
+    const thinking = body?.thinking === true || (body?.reasoning_effort != null && body.reasoning_effort !== "none");
+
+    let pplxMode;
+    let modelPref;
+    if (thinking && THINKING_MAP[model]) {
+      pplxMode = "copilot";
+      modelPref = THINKING_MAP[model];
+      log?.info?.("PPLX-WEB", `Thinking mode → ${model} using ${modelPref}`);
+    } else if (MODEL_MAP[model]) {
+      [pplxMode, modelPref] = MODEL_MAP[model];
+    } else {
+      pplxMode = "copilot";
+      modelPref = model;
+      log?.info?.("PPLX-WEB", `Unmapped model ${model}, using as raw preference`);
+    }
+
+    const parsed = parseOpenAIMessages(messages);
+    const followUpUuid = sessionLookup(parsed.history);
+    if (followUpUuid) log?.info?.("PPLX-WEB", `Session continue: ${followUpUuid.slice(0, 12)}...`);
+
+    const query = buildQuery(parsed, followUpUuid, body?.tools);
+    if (!query.trim()) {
+      const errResp = new Response(JSON.stringify({
+        error: { message: "Empty query after processing", type: "invalid_request" },
+      }), { status: 400, headers: { "Content-Type": "application/json" } });
+      return { response: errResp, url: PPLX_SSE_ENDPOINT, headers: {}, transformedBody: body };
+    }
+
+    const pplxBody = buildPplxRequestBody(query, pplxMode, modelPref, followUpUuid);
+
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "text/event-stream",
+      Origin: "https://www.perplexity.ai",
+      Referer: "https://www.perplexity.ai/",
+      "User-Agent": PPLX_USER_AGENT,
+      "X-App-ApiClient": "default",
+      "X-App-ApiVersion": PPLX_API_VERSION,
+    };
+
+    if (credentials.accessToken) {
+      headers["Authorization"] = `Bearer ${credentials.accessToken}`;
+    } else if (credentials.apiKey) {
+      headers["Cookie"] = `__Secure-next-auth.session-token=${credentials.apiKey}`;
+    }
+
+    log?.info?.("PPLX-WEB", `Query to ${model} (pref=${modelPref}, mode=${pplxMode}), len=${query.length}`);
+
+    const fetchOptions = { method: "POST", headers, body: JSON.stringify(pplxBody) };
+    if (signal) fetchOptions.signal = signal;
+
+    let response;
+    try {
+      response = await fetch(PPLX_SSE_ENDPOINT, fetchOptions);
+    } catch (err) {
+      log?.error?.("PPLX-WEB", `Fetch failed: ${err.message || String(err)}`);
+      const errResp = new Response(JSON.stringify({
+        error: { message: `Perplexity connection failed: ${err.message || String(err)}`, type: "upstream_error" },
+      }), { status: 502, headers: { "Content-Type": "application/json" } });
+      return { response: errResp, url: PPLX_SSE_ENDPOINT, headers, transformedBody: pplxBody };
+    }
+
+    if (!response.ok) {
+      const status = response.status;
+      let errMsg = `Perplexity returned HTTP ${status}`;
+      if (status === 401 || status === 403) errMsg = "Perplexity auth failed — session cookie may be expired. Re-paste your __Secure-next-auth.session-token.";
+      else if (status === 429) errMsg = "Perplexity rate limited. Wait a moment and retry.";
+      log?.warn?.("PPLX-WEB", errMsg);
+      const errResp = new Response(JSON.stringify({
+        error: { message: errMsg, type: "upstream_error", code: `HTTP_${status}` },
+      }), { status, headers: { "Content-Type": "application/json" } });
+      return { response: errResp, url: PPLX_SSE_ENDPOINT, headers, transformedBody: pplxBody };
+    }
+
+    if (!response.body) {
+      const errResp = new Response(JSON.stringify({
+        error: { message: "Perplexity returned empty response body", type: "upstream_error" },
+      }), { status: 502, headers: { "Content-Type": "application/json" } });
+      return { response: errResp, url: PPLX_SSE_ENDPOINT, headers, transformedBody: pplxBody };
+    }
+
+    const cid = `chatcmpl-pplx-${crypto.randomUUID().slice(0, 12)}`;
+    const created = Math.floor(Date.now() / 1000);
+
+    let finalResponse;
+    if (stream) {
+      const sseStream = buildStreamingResponse(response.body, model, cid, created, parsed.history, parsed.currentMsg, signal);
+      finalResponse = new Response(sseStream, {
+        status: 200,
+        headers: { ...SSE_HEADERS_NO_BUFFER },
+      });
+    } else {
+      finalResponse = await buildNonStreamingResponse(response.body, model, cid, created, parsed.history, parsed.currentMsg, signal);
+    }
+    return { response: finalResponse, url: PPLX_SSE_ENDPOINT, headers, transformedBody: pplxBody };
+  }
+}
+
+export { parseOpenAIMessages, buildQuery, buildPplxRequestBody, formatToolsHint, sessionKey };
+
+export default PerplexityWebExecutor;
diff --git a/open-sse/executors/qoder.js b/open-sse/executors/qoder.js
new file mode 100644
index 0000000..2a7714b
--- /dev/null
+++ b/open-sse/executors/qoder.js
@@ -0,0 +1,458 @@
+/**
+ * QoderExecutor — sends OpenAI-format chat requests to Qoder's COSY-signed
+ * inference endpoint at api3.qoder.sh, then unwraps Qoder's `{statusCodeValue,
+ * body}` SSE envelope back into plain OpenAI SSE for the rest of the pipeline.
+ *
+ * Differences vs the previous placeholder:
+ *   - URL is api3.qoder.sh/algo/api/v2/service/pro/sse/agent_chat_generation
+ *     with `&Encode=1` so we can ship the body through the WAF-bypass
+ *     encoder.
+ *   - Authentication is COSY (RSA + AES + MD5 + ~17 Cosy-* headers), not
+ *     a static HMAC.
+ *   - The request shape Qoder expects is non-trivial (chat_context with
+ *     mirrored modelConfig, business block with stable IDs, system text
+ *     hoisted out of the messages array). All ported from the reference.
+ *   - Model identifier is one of the canonical Qoder keys (auto / ultimate /
+ *     performance / efficient / lite + frontier "*model" ids); the
+ *     translator layer feeds us "qoder/<key>" so we strip the prefix.
+ *   - Per-model `model_config` is fetched live from /algo/api/v2/model/list
+ *     and cached. Sending the wrong block silently downgrades to a
+ *     different model upstream, so a missing entry is a hard error.
+ */
+
+import { qoderEncodeBody } from "../shared/qoder/encoding.js";
+import { buildCosyHeaders } from "../shared/qoder/cosy.js";
+import { v4 as uuidv4 } from "uuid";
+import { createHash } from "crypto";
+
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+import { SSE_DONE } from "../utils/sseConstants.js";
+import { FETCH_CONNECT_TIMEOUT_MS } from "../config/runtimeConfig.js";
+import {
+  QODER_CHAT_URL_ENCODED,
+  QODER_MODEL_MAP,
+} from "../shared/qoder/constants.js";
+import { getQoderModelConfig, resolveQoderModels } from "../services/qoderModels.js";
+
+/**
+ * Hoist role:"system" messages out of the messages array (Qoder rejects
+ * system in messages) and flatten any multipart content arrays.
+ */
+function normalizeMessages(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return { messages: [], systemText: "" };
+  }
+  const systemParts = [];
+  const out = [];
+  for (const msg of messages) {
+    if (!msg || typeof msg !== "object") continue;
+    const text = extractText(msg.content);
+    if (msg.role === "system") {
+      if (text) systemParts.push(text);
+      continue;
+    }
+    const cloned = { ...msg };
+    cloned.content = text;
+    out.push(cloned);
+  }
+  return { messages: out, systemText: systemParts.join("\n\n") };
+}
+
+function extractText(content) {
+  if (typeof content === "string") return content;
+  if (content == null) return "";
+  if (Array.isArray(content)) {
+    const parts = [];
+    for (const item of content) {
+      if (item && typeof item === "object") {
+        if (item.type === "text" && typeof item.text === "string") {
+          parts.push(item.text);
+        } else if (typeof item.text === "string") {
+          parts.push(item.text);
+        }
+      }
+    }
+    return parts.join("\n");
+  }
+  return String(content);
+}
+
+function lastUserText(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role === "user" && typeof m.content === "string") {
+      return m.content;
+    }
+  }
+  return "";
+}
+
+function stableHash(prefix, ...parts) {
+  const h = createHash("sha256");
+  h.update(prefix);
+  for (const p of parts) {
+    h.update("\0");
+    h.update(String(p ?? ""));
+  }
+  return h.digest("hex").slice(0, 16);
+}
+
+function stableChatRecordId(model, messages, tools, maxTokens) {
+  const h = createHash("sha256");
+  h.update("qoder-record\0");
+  h.update(String(model));
+  for (const m of messages) {
+    if (!m || typeof m !== "object") continue;
+    if (m.role) { h.update("\0"); h.update(m.role); }
+    if (typeof m.content === "string" && m.content) {
+      h.update("\0"); h.update(m.content);
+    }
+  }
+  if (tools) {
+    h.update("\0");
+    try { h.update(JSON.stringify(tools)); } catch {}
+  }
+  h.update(`\0mt=${maxTokens}`);
+  return h.digest("hex").slice(0, 16);
+}
+
+function truncate(s, n) {
+  return s && s.length > n ? `${s.slice(0, n)}...` : s || "";
+}
+
+/**
+ * Map the OpenAI-style request body into the exact shape Qoder expects.
+ */
+async function buildQoderRequestBody({ model, body, credentials, log, proxyOptions, signal }) {
+  const qoderKey = String(model || "").replace(/^qoder\//, "");
+  
+  // Fetch model config from dynamic API instead of relying on static QODER_MODEL_MAP.
+  // This allows support for new Qoder models (e.g., qmodel_latest) without code changes.
+  let modelConfig = await getQoderModelConfig(credentials, qoderKey, { log, proxyOptions, signal });
+  if (!modelConfig) {
+    // Try a forced refresh once before giving up — the cache may simply
+    // not be populated yet on first ever call for this credential.
+    const refreshed = await resolveQoderModels(credentials, { forceRefresh: true, log, proxyOptions, signal });
+    const retried = refreshed?.rawConfigs.get(qoderKey);
+    if (!retried) {
+      throw new Error(
+        `qoder: model_config for "${qoderKey}" not yet known (run a model list fetch or check upstream connectivity)`,
+      );
+    }
+    modelConfig = { ...retried, key: qoderKey };
+  }
+
+  const { messages, systemText } = normalizeMessages(body.messages || []);
+  const tools = body.tools;
+  const isReasoning = !!modelConfig.is_reasoning;
+  const maxOutputTokens = Number(modelConfig.max_output_tokens) || 0;
+
+  let maxTokens = 32_768;
+  if (maxOutputTokens > 0) maxTokens = maxOutputTokens;
+  if (typeof body.max_tokens === "number" && body.max_tokens > 0 && body.max_tokens < maxTokens) {
+    maxTokens = body.max_tokens;
+  }
+  if (typeof body.max_completion_tokens === "number" && body.max_completion_tokens > 0 && body.max_completion_tokens < maxTokens) {
+    maxTokens = body.max_completion_tokens;
+  }
+
+  const lastUser = lastUserText(messages);
+  const psd = credentials.providerSpecificData || {};
+  const sessionId = stableHash("qoder-session", psd.userId, qoderKey);
+  const recordId = stableChatRecordId(qoderKey, messages, tools, maxTokens);
+
+  return {
+    qoderKey,
+    payload: {
+      request_id: uuidv4(),
+      request_set_id: recordId,
+      chat_record_id: recordId,
+      session_id: sessionId,
+      stream: true,
+      chat_task: "FREE_INPUT",
+      is_reply: true,
+      is_retry: false,
+      source: 1,
+      version: "3",
+      session_type: "qodercli",
+      agent_id: "agent_common",
+      task_id: "common",
+      code_language: "",
+      chat_prompt: "",
+      image_urls: null,
+      aliyun_user_type: "",
+      system: systemText,
+      messages,
+      tools: Array.isArray(tools) ? tools : [],
+      parameters: { max_tokens: maxTokens },
+      chat_context: {
+        chatPrompt: "",
+        imageUrls: null,
+        extra: {
+          context: [],
+          modelConfig: { key: qoderKey, is_reasoning: isReasoning },
+          originalContent: lastUser,
+        },
+        features: [],
+        text: lastUser,
+      },
+      model_config: modelConfig,
+      business: {
+        product: "cli",
+        version: "1.0.0",
+        type: "agent",
+        stage: "start",
+        id: uuidv4(),
+        name: truncate(lastUser, 30),
+        begin_at: Date.now(),
+      },
+    },
+    modelConfig,
+  };
+}
+
+/**
+ * Wrap the upstream's `{statusCodeValue, body}` SSE envelope into plain
+ * OpenAI SSE chunks the rest of the chatCore pipeline understands.
+ *
+ * Each upstream line looks like:
+ *   data: {"statusCodeValue":200,"body":"{\"choices\":[{\"delta\":{...}}]}"}
+ * The inner body is an OpenAI streaming chunk (or "[DONE]"). We unwrap it
+ * and re-emit as `data: <inner>\n\n`. Errors become `data: [DONE]\n\n` plus
+ * a synthetic OpenAI error chunk.
+ */
+function wrapQoderSSE(response, model) {
+  if (!response.ok || !response.body) return response;
+
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let buffer = "";
+  let doneEmitted = false;
+
+  // Process one already-extracted SSE line (no trailing newline). Returns
+  // false when the line indicated end-of-stream so the caller can stop
+  // forwarding any remaining chunks after [DONE].
+  const processLine = (line, controller) => {
+    const trimmed = line.replace(/\r$/, "").trim();
+    if (!trimmed) return;
+    if (!trimmed.startsWith("data:")) return;
+    if (doneEmitted) return; // never forward chunks past stream end
+
+    const data = trimmed.slice(5).trimStart();
+    if (data === "[DONE]") {
+      controller.enqueue(encoder.encode(SSE_DONE));
+      doneEmitted = true;
+      return;
+    }
+
+    let envelope;
+    try { envelope = JSON.parse(data); } catch { return; }
+    const statusVal = typeof envelope.statusCodeValue === "number" ? envelope.statusCodeValue : 200;
+    const inner = typeof envelope.body === "string" ? envelope.body : "";
+    if (statusVal !== 200) {
+      const msg = inner || `upstream status ${statusVal}`;
+      const errChunk = JSON.stringify({
+        id: `qoder-error-${Date.now()}`,
+        object: "chat.completion.chunk",
+        created: Math.floor(Date.now() / 1000),
+        model,
+        choices: [{ index: 0, delta: { content: `\n[qoder error ${statusVal}: ${truncate(msg, 200)}]` }, finish_reason: "stop" }],
+      });
+      controller.enqueue(encoder.encode(`data: ${errChunk}\n\n`));
+      controller.enqueue(encoder.encode(SSE_DONE));
+      doneEmitted = true;
+      return;
+    }
+    if (!inner) return;
+    if (inner === "[DONE]") {
+      controller.enqueue(encoder.encode(SSE_DONE));
+      doneEmitted = true;
+      return;
+    }
+    // Inner is an OpenAI-shaped chunk. Strip any embedded newlines so the
+    // SSE frame stays a single event (a literal "\n" inside `inner` would
+    // otherwise split the frame across multiple data: lines and downstream
+    // parsers would reassemble them as separate events).
+    const sanitized = inner.replace(/\r?\n/g, "");
+    controller.enqueue(encoder.encode(`data: ${sanitized}\n\n`));
+  };
+
+  const transform = new TransformStream({
+    transform(chunk, controller) {
+      buffer += decoder.decode(chunk, { stream: true });
+      let nl;
+      while ((nl = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        processLine(line, controller);
+      }
+    },
+    flush(controller) {
+      // Finalize the decoder so any pending multi-byte sequence is
+      // released into `buffer` instead of being silently dropped.
+      buffer += decoder.decode();
+      // Drain any trailing line that arrived without a terminating newline
+      // (e.g. upstream closed the socket immediately after the last write,
+      // or a CDN stripped the final CRLF). Without this, the chunk that
+      // carries finish_reason is silently lost.
+      if (buffer.length > 0) {
+        processLine(buffer, controller);
+        buffer = "";
+      }
+      if (!doneEmitted) {
+        controller.enqueue(encoder.encode(SSE_DONE));
+        doneEmitted = true;
+      }
+    },
+  });
+
+  const transformed = response.body.pipeThrough(transform);
+  // Build a Response with passable headers; the streaming handler reads
+  // `.body` as a ReadableStream regardless of Content-Type.
+  return new Response(transformed, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+    },
+  });
+}
+
+export class QoderExecutor extends BaseExecutor {
+  constructor() {
+    super("qoder", PROVIDERS.qoder);
+  }
+
+  buildUrl() {
+    return QODER_CHAT_URL_ENCODED;
+  }
+
+  // Override execute entirely — Qoder needs:
+  //   - body built from translated chat completion payload
+  //   - body encoded with QoderEncodeBody before signing
+  //   - COSY headers built from the *encoded* body bytes
+  //   - response stream re-wrapped from {statusCodeValue, body} to OpenAI SSE
+  async execute({ model, body, stream, credentials, signal, log, proxyOptions = null }) {
+    const url = this.buildUrl();
+
+    const psd = credentials?.providerSpecificData || {};
+    if (!psd.userId) {
+      // No user id → no way to sign. Surface a 401 so the dashboard nudges
+      // the user back to OAuth.
+      const fakeResp = new Response(
+        JSON.stringify({ error: { message: "qoder credential is missing userId; reconnect the account" } }),
+        { status: 401, headers: { "Content-Type": "application/json" } },
+      );
+      return { response: fakeResp, url, headers: {}, transformedBody: body };
+    }
+    if (!credentials?.accessToken) {
+      // Same shape as the userId guard — clean 401 so chatCore reports
+      // "reconnect" rather than bubbling cosy.js's synchronous throw as 500.
+      const fakeResp = new Response(
+        JSON.stringify({ error: { message: "qoder credential is missing accessToken; reconnect the account" } }),
+        { status: 401, headers: { "Content-Type": "application/json" } },
+      );
+      return { response: fakeResp, url, headers: {}, transformedBody: body };
+    }
+
+    let qoderKey;
+    let payload;
+    try {
+      ({ qoderKey, payload } = await buildQoderRequestBody({ model, body, credentials, log, proxyOptions, signal }));
+    } catch (err) {
+      const fakeResp = new Response(
+        JSON.stringify({ error: { message: err.message } }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+      return { response: fakeResp, url, headers: {}, transformedBody: body };
+    }
+
+    const plainBody = Buffer.from(JSON.stringify(payload), "utf8");
+    const encodedBodyStr = qoderEncodeBody(plainBody);
+    const encodedBodyBuf = Buffer.from(encodedBodyStr, "latin1");
+
+    let cosyHeaders;
+    try {
+      cosyHeaders = buildCosyHeaders(
+        encodedBodyBuf,
+        url,
+        {
+          userId: psd.userId,
+          authToken: credentials.accessToken,
+          name: credentials.displayName || "",
+          email: credentials.email || "",
+          machineId: psd.machineId || "",
+        },
+      );
+    } catch (err) {
+      // cosy.js throws synchronously on missing userId/authToken — surface
+      // as 401 so chatCore prompts re-auth instead of returning a 500.
+      const fakeResp = new Response(
+        JSON.stringify({ error: { message: `qoder cosy signing failed: ${err.message}` } }),
+        { status: 401, headers: { "Content-Type": "application/json" } },
+      );
+      return { response: fakeResp, url, headers: {}, transformedBody: body };
+    }
+
+    const modelSource = (payload.model_config && payload.model_config.source) || "system";
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache",
+      "X-Model-Key": qoderKey,
+      "X-Model-Source": modelSource,
+      // gzip triggers signature validation on Qoder's CDN; force identity.
+      "Accept-Encoding": "identity",
+      ...cosyHeaders,
+    };
+
+    // Abort if upstream doesn't return response headers within connect timeout.
+    const timeoutMs = this.config?.timeoutMs || FETCH_CONNECT_TIMEOUT_MS;
+    const connectCtrl = new AbortController();
+    const connectTimer = setTimeout(() => connectCtrl.abort(new Error("fetch connect timeout")), timeoutMs);
+    const mergedSignal = signal ? AbortSignal.any([signal, connectCtrl.signal]) : connectCtrl.signal;
+
+    let response;
+    try {
+      response = await proxyAwareFetch(
+        url,
+        { method: "POST", headers, body: encodedBodyBuf, signal: mergedSignal },
+        proxyOptions,
+      );
+    } finally {
+      clearTimeout(connectTimer);
+    }
+
+    if (!response.ok) {
+      // Pass error response through unchanged so chatCore can capture it.
+      return { response, url, headers, transformedBody: payload };
+    }
+
+    const wrapped = wrapQoderSSE(response, `qoder/${qoderKey}`);
+    return { response: wrapped, url, headers, transformedBody: payload };
+  }
+
+  // Qoder device tokens don't refresh through OAuth — the upstream returns
+  // 403 for our flow. Surfacing failure via 401-on-chat is enough; the
+  // dashboard tells users to re-login when their token expires (~30 days).
+  async refreshCredentials() {
+    return null;
+  }
+
+  needsRefresh() {
+    return false;
+  }
+}
+
+export default QoderExecutor;
+
+// Internals exposed for unit tests. Not part of the public API — callers
+// should import QoderExecutor and use its public methods.
+export const __test__ = {
+  normalizeMessages,
+  wrapQoderSSE,
+  buildQoderRequestBody,
+};
diff --git a/open-sse/executors/qwen.js b/open-sse/executors/qwen.js
new file mode 100644
index 0000000..ae82811
--- /dev/null
+++ b/open-sse/executors/qwen.js
@@ -0,0 +1,129 @@
+import { DefaultExecutor } from "./default.js";
+import { PROVIDERS } from "../config/providers.js";
+import { OAUTH_ENDPOINTS } from "../config/appConstants.js";
+
+/** portal.qwen.ai — static fingerprint matching stable Qwen Code release */
+const QWEN_USER_AGENT = "QwenCode/0.12.3 (linux; x64)";
+const QWEN_STAINLESS = {
+  os: "Linux",
+  arch: "x64",
+  lang: "js",
+  runtime: "node",
+  runtimeVersion: "v18.19.1",
+  packageVersion: "5.11.0",
+  retryCount: "1"
+};
+const QWEN_DEFAULT_SYSTEM_MESSAGE = {
+  role: "system",
+  content: [{ type: "text", text: "", cache_control: { type: "ephemeral" } }]
+};
+
+function ensureQwenSystemMessage(body) {
+  if (!body || typeof body !== "object") return body;
+  const next = { ...body };
+  if (Array.isArray(next.messages)) {
+    next.messages = [QWEN_DEFAULT_SYSTEM_MESSAGE, ...next.messages];
+  } else {
+    next.messages = [QWEN_DEFAULT_SYSTEM_MESSAGE];
+  }
+  return next;
+}
+
+function isQwenThinkingActive(body) {
+  const thinking = body?.thinking;
+  if (thinking === true || body?.enable_thinking === true) return true;
+  return typeof thinking === "object" && thinking !== null && !Array.isArray(thinking) && thinking.type === "enabled";
+}
+
+// Qwen rejects tool_choice="required" or object forms when thinking is active; neutralize to "auto".
+function sanitizeQwenThinkingToolChoice(body) {
+  if (!isQwenThinkingActive(body)) return body;
+  const tc = body.tool_choice;
+  const incompatible = tc === "required" || (typeof tc === "object" && tc !== null);
+  if (!incompatible) return body;
+  return { ...body, tool_choice: "auto" };
+}
+
+function buildQwenUpstreamHeaders(credentials, stream = true) {
+  const token = credentials?.apiKey || credentials?.accessToken || "";
+  const headers = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${token}`,
+    "User-Agent": QWEN_USER_AGENT,
+    "X-DashScope-AuthType": "qwen-oauth",
+    "X-DashScope-CacheControl": "enable",
+    "X-DashScope-UserAgent": QWEN_USER_AGENT,
+    "X-Stainless-Arch": QWEN_STAINLESS.arch,
+    "X-Stainless-Lang": QWEN_STAINLESS.lang,
+    "X-Stainless-Os": QWEN_STAINLESS.os,
+    "X-Stainless-Package-Version": QWEN_STAINLESS.packageVersion,
+    "X-Stainless-Retry-Count": QWEN_STAINLESS.retryCount,
+    "X-Stainless-Runtime": QWEN_STAINLESS.runtime,
+    "X-Stainless-Runtime-Version": QWEN_STAINLESS.runtimeVersion,
+    Connection: "keep-alive",
+    "Accept-Language": "*",
+    "Sec-Fetch-Mode": "cors"
+  };
+  headers.Accept = stream ? "text/event-stream" : "application/json";
+  return headers;
+}
+
+export class QwenExecutor extends DefaultExecutor {
+  constructor() {
+    super("qwen");
+  }
+
+  // Qwen tokens are bound to a resource_url returned at OAuth time.
+  // Using portal.qwen.ai when the token is issued for another shard returns 401/403.
+  buildUrl(model, stream, urlIndex = 0, credentials = null) {
+    const resourceUrl = credentials?.providerSpecificData?.resourceUrl;
+    const host = resourceUrl ? resourceUrl.replace(/^https?:\/\//, "").replace(/\/$/, "") : "portal.qwen.ai";
+    return `https://${host}/v1/chat/completions`;
+  }
+
+  buildHeaders(credentials, stream = true) {
+    return buildQwenUpstreamHeaders(credentials, stream);
+  }
+
+  transformRequest(model, body, stream, credentials) {
+    let next = body && typeof body === "object" ? { ...body } : body;
+    if (stream && next?.messages && !next.stream_options && !next.thinking && !next.enable_thinking && next.stream !== false) {
+      next.stream_options = { include_usage: true };
+    }
+    next = sanitizeQwenThinkingToolChoice(next);
+    return ensureQwenSystemMessage(next);
+  }
+
+  // Override to capture resource_url from refresh response (required for buildUrl).
+  async refreshCredentials(credentials, log) {
+    if (!credentials?.refreshToken) return null;
+    try {
+      const response = await fetch(OAUTH_ENDPOINTS.qwen.token, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+        body: new URLSearchParams({
+          grant_type: "refresh_token",
+          refresh_token: credentials.refreshToken,
+          client_id: PROVIDERS.qwen.clientId
+        })
+      });
+      if (!response.ok) return null;
+      const tokens = await response.json();
+      log?.info?.("TOKEN", "qwen refreshed");
+      return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token || credentials.refreshToken,
+        expiresIn: tokens.expires_in,
+        providerSpecificData: {
+          ...(credentials.providerSpecificData || {}),
+          ...(tokens.resource_url ? { resourceUrl: tokens.resource_url } : {})
+        }
+      };
+    } catch (error) {
+      log?.error?.("TOKEN", `qwen refresh error: ${error.message}`);
+      return null;
+    }
+  }
+}
+
+export default QwenExecutor;
diff --git a/open-sse/executors/vertex.js b/open-sse/executors/vertex.js
new file mode 100644
index 0000000..4cea2ad
--- /dev/null
+++ b/open-sse/executors/vertex.js
@@ -0,0 +1,177 @@
+import { BaseExecutor } from "./base.js";
+import { PROVIDERS } from "../config/providers.js";
+import { parseVertexSaJson, refreshVertexToken, refreshGoogleToken } from "../services/tokenRefresh.js";
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+
+// Cache project IDs resolved from raw API keys { apiKey → projectId }
+const projectIdCache = new Map();
+
+/**
+ * Parse Google ADC user credential JSON from apiKey string.
+ * This is the format produced by `gcloud auth application-default login`.
+ */
+function parseVertexAdcJson(apiKey) {
+  if (typeof apiKey !== "string") return null;
+  try {
+    const parsed = JSON.parse(apiKey);
+    if (
+      parsed.type === "authorized_user" &&
+      parsed.client_id &&
+      parsed.client_secret &&
+      parsed.refresh_token
+    ) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve GCP project ID from a raw Vertex API key.
+ * Sends a dummy 404 request and parses "projects/{id}" from the error message.
+ */
+async function resolveProjectId(apiKey) {
+  if (projectIdCache.has(apiKey)) return projectIdCache.get(apiKey);
+
+  const res = await fetch(
+    `https://aiplatform.googleapis.com/v1/publishers/google/models/__probe__:generateContent?key=${apiKey}`,
+    { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" }
+  );
+  const json = await res.json().catch(() => null);
+  const msg = json?.[0]?.error?.message || json?.error?.message || "";
+  const match = msg.match(/projects\/([^/]+)\//);
+  const projectId = match?.[1] || null;
+
+  if (projectId) projectIdCache.set(apiKey, projectId);
+  return projectId;
+}
+
+/**
+ * VertexExecutor - Google Cloud Vertex AI
+ *
+ * "vertex"         → Gemini models via regional/global Vertex endpoint
+ * "vertex-partner" → Partner models (Llama, Mistral, GLM, DeepSeek, Qwen)
+ *                    via global OpenAI-compatible endpoint
+ *
+ * Auth: SA JSON (stored as apiKey) → JWT assertion → Bearer token (via jose)
+ * Token is minted/cached in tokenRefresh.js, not here.
+ */
+export class VertexExecutor extends BaseExecutor {
+  constructor(providerId = "vertex") {
+    super(providerId, PROVIDERS[providerId] || {});
+  }
+
+  buildUrl(model, stream, urlIndex = 0, credentials = null) {
+    const saJson = parseVertexSaJson(credentials?.apiKey);
+    const adcJson = parseVertexAdcJson(credentials?.apiKey);
+    const usesOAuth = !!saJson || !!adcJson || !!credentials?.accessToken;
+    const rawKey = !usesOAuth ? credentials?.apiKey : null;
+    const projectId =
+      saJson?.project_id ||
+      adcJson?.quota_project_id ||
+      credentials?.providerSpecificData?.projectId;
+
+    if (this.provider === "vertex-partner") {
+      // Partner models require project_id in path regardless of auth method
+      if (!projectId) throw new Error("Vertex partner models require a project_id. Add it in providerSpecificData or use Service Account JSON.");
+      const url = `https://aiplatform.googleapis.com/v1/projects/${projectId}/locations/global/endpoints/openapi/chat/completions`;
+      return rawKey ? `${url}?key=${rawKey}` : url;
+    }
+
+    // Gemini on Vertex
+    const action = stream ? "streamGenerateContent" : "generateContent";
+
+    if (usesOAuth) {
+      // SA JSON / ADC / pre-set accessToken: must use project-scoped path to avoid RESOURCE_PROJECT_INVALID
+      if (!projectId) {
+        throw new Error(
+          "Vertex OAuth/ADC requires a project_id. " +
+          "Add quota_project_id to your ADC JSON or set providerSpecificData.projectId."
+        );
+      }
+      const location = credentials?.providerSpecificData?.location || "us-central1";
+      let url = `https://aiplatform.googleapis.com/v1/projects/${projectId}/locations/${location}/publishers/google/models/${model}:${action}`;
+      if (stream) url += "?alt=sse";
+      return url;
+    }
+
+    // Raw API key: use global publishers endpoint with ?key= param
+    // ?alt=sse is required for proper SSE streaming (matches every other Gemini executor)
+    let url = `https://aiplatform.googleapis.com/v1/publishers/google/models/${model}:${action}`;
+    if (stream) url += "?alt=sse";
+    if (rawKey) url += stream ? `&key=${rawKey}` : `?key=${rawKey}`;
+    return url;
+  }
+
+  buildHeaders(credentials, stream = true) {
+    const headers = { "Content-Type": "application/json" };
+
+    // Only set Bearer token if using SA JSON flow (raw key goes in URL ?key=)
+    if (credentials.accessToken) {
+      headers["Authorization"] = `Bearer ${credentials.accessToken}`;
+    }
+
+    if (stream) headers["Accept"] = "text/event-stream";
+
+    return headers;
+  }
+
+  async refreshCredentials(credentials, log) {
+    const saJson = parseVertexSaJson(credentials?.apiKey);
+    if (!saJson) return null;
+
+    const result = await refreshVertexToken(saJson, log);
+    if (!result) return null;
+
+    return { accessToken: result.accessToken, expiresAt: result.expiresAt };
+  }
+
+  async execute({ model, body, stream, credentials, signal, log, proxyOptions = null }) {
+    const saJson = parseVertexSaJson(credentials?.apiKey);
+    const adcJson = parseVertexAdcJson(credentials?.apiKey);
+
+    // SA JSON flow: mint Bearer token via JWT assertion (cached)
+    if (saJson) {
+      const result = await refreshVertexToken(saJson, log);
+      if (!result?.accessToken) throw new Error("Vertex: failed to mint access token from Service Account JSON");
+      credentials.accessToken = result.accessToken;
+    }
+
+    // ADC user credential flow: refresh Bearer token via Google OAuth2 token endpoint
+    if (adcJson) {
+      const result = await refreshGoogleToken(
+        adcJson.refresh_token,
+        adcJson.client_id,
+        adcJson.client_secret,
+        log
+      );
+      if (!result?.accessToken) throw new Error("Vertex: failed to refresh access token from ADC JSON (authorized_user)");
+      credentials.accessToken = result.accessToken;
+    }
+
+    // vertex-partner with raw key: auto-resolve project_id if not provided
+    if (this.provider === "vertex-partner" && !saJson && !adcJson && !credentials?.providerSpecificData?.projectId) {
+      const projectId = await resolveProjectId(credentials.apiKey);
+      if (!projectId) throw new Error("Vertex: could not resolve project_id from API key. Please add it manually in provider settings.");
+      log?.debug?.("VERTEX", `Resolved project_id: ${projectId}`);
+      credentials.providerSpecificData = { ...credentials.providerSpecificData, projectId };
+    }
+
+    const url = this.buildUrl(model, stream, 0, credentials);
+    const headers = this.buildHeaders(credentials, stream);
+    const transformedBody = this.transformRequest(model, body, stream, credentials);
+
+    const response = await proxyAwareFetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(transformedBody),
+      signal,
+    }, proxyOptions);
+
+    return { response, url, headers, transformedBody };
+  }
+}
+
+export default VertexExecutor;
diff --git a/open-sse/executors/xiaomi-tokenplan.js b/open-sse/executors/xiaomi-tokenplan.js
new file mode 100644
index 0000000..75799ad
--- /dev/null
+++ b/open-sse/executors/xiaomi-tokenplan.js
@@ -0,0 +1,20 @@
+import { DefaultExecutor } from "./default.js";
+import { resolveXiaomiTokenplanBaseUrl } from "../config/providers.js";
+// import { getModelTargetFormat } from "../config/providerModels.js";
+// import { FORMATS } from "../translator/formats.js";
+
+export class XiaomiTokenplanExecutor extends DefaultExecutor {
+  constructor() {
+    super("xiaomi-tokenplan");
+  }
+
+  // Token Plan keys are region-specific. Route per sourceFormat-matched transport:
+  // claude → Anthropic /anthropic/v1/messages, openai → /chat/completions.
+  buildUrl(model, stream, urlIndex = 0, credentials = null) {
+    const baseUrl = resolveXiaomiTokenplanBaseUrl(credentials);
+    if (credentials?.runtimeTransport?.format === "claude") {
+      return `${baseUrl.replace(/\/v1\/?$/, "")}/anthropic/v1/messages`;
+    }
+    return `${baseUrl}/chat/completions`;
+  }
+}
diff --git a/open-sse/handlers/chatCore.js b/open-sse/handlers/chatCore.js
new file mode 100644
index 0000000..e72235f
--- /dev/null
+++ b/open-sse/handlers/chatCore.js
@@ -0,0 +1,399 @@
+import { detectFormat, getTargetFormat, resolveTransport } from "../services/provider.js";
+import { translateRequest } from "../translator/index.js";
+import { stripThinkingSuffix } from "../translator/concerns/thinkingUnified.js";
+import { FORMATS } from "../translator/formats.js";
+import { normalizeClaudePassthrough } from "../translator/formats/claude.js";
+import { createStreamController } from "../utils/streamHandler.js";
+import { refreshWithRetry } from "../services/tokenRefresh.js";
+import { createRequestLogger } from "../utils/requestLogger.js";
+import { getModelTargetFormat, getModelStrip, getModelUpstreamId, getModelType, PROVIDER_ID_TO_ALIAS } from "../config/providerModels.js";
+import { PROVIDERS } from "../config/providers.js";
+import { createErrorResult, parseUpstreamError, formatProviderError } from "../utils/error.js";
+import { HTTP_STATUS } from "../config/runtimeConfig.js";
+import { handleBypassRequest } from "../utils/bypassHandler.js";
+import { trackPendingRequest, appendRequestLog, saveRequestDetail } from "@/lib/usageDb.js";
+import { getExecutor } from "../executors/index.js";
+import { buildRequestDetail, extractRequestConfig } from "./chatCore/requestDetail.js";
+import { handleForcedSSEToJson } from "./chatCore/sseToJsonHandler.js";
+import { handleNonStreamingResponse } from "./chatCore/nonStreamingHandler.js";
+import { handleStreamingResponse, buildOnStreamComplete } from "./chatCore/streamingHandler.js";
+import { detectClientTool, isNativePassthrough } from "../utils/clientDetector.js";
+import { dedupeTools } from "../utils/toolDeduper.js";
+import { injectCaveman } from "../rtk/caveman.js";
+import { injectPonytail } from "../rtk/ponytail.js";
+import { compressMessages } from "../rtk/index.js";
+import { compressWithHeadroom, formatHeadroomSizeLog, isHeadroomPhantomSavings } from "../rtk/headroom.js";
+import { compressWithPxpipe } from "../rtk/pxpipe.js";
+import { getCapabilitiesForModel } from "../providers/capabilities.js";
+import { stripUnsupportedModalities } from "../translator/concerns/modality.js";
+import { prefetchRemoteImages } from "../translator/concerns/prefetch.js";
+import { extractThinking } from "../translator/concerns/thinkingUnified.js";
+import { resolveSessionId } from "../utils/sessionManager.js";
+
+/**
+ * Core chat handler - shared between SSE and Worker
+ * @param {object} options.body - Request body
+ * @param {object} options.modelInfo - { provider, model }
+ * @param {object} options.credentials - Provider credentials
+ * @param {string} options.sourceFormatOverride - Override detected source format (e.g. "openai-responses")
+ */
+export async function handleChatCore({ body, modelInfo, credentials, log, onCredentialsRefreshed, onRequestSuccess, onDisconnect, clientRawRequest, connectionId, userAgent, apiKey, ccFilterNaming, rtkEnabled, headroomEnabled, headroomUrl, headroomCompressUserMessages, cavemanEnabled, cavemanLevel, ponytailEnabled, ponytailLevel, pxpipeEnabled, pxpipeMinChars, pxpipeTimeoutMs, pxpipeTransform, onPxpipeEvent, sourceFormatOverride, providerThinking }) {
+  const { provider, model } = modelInfo;
+  const requestStartTime = Date.now();
+  // Stable per-session color so all lines of one CLI conversation share a tag
+  const sessionSeed = (() => {
+    try {
+      return resolveSessionId({ headers: clientRawRequest?.headers, body, connectionId, scope: provider });
+    } catch {
+      return connectionId || "";
+    }
+  })();
+  const reqTag = log?.tagForSession ? log.tagForSession(sessionSeed) : (log?.nextTag ? log.nextTag() : "");
+
+  const sourceFormat = sourceFormatOverride || detectFormat(body);
+
+  // Check for bypass patterns (warmup, skip, cc naming)
+  const bypassResponse = handleBypassRequest(body, model, userAgent, ccFilterNaming);
+  if (bypassResponse) return bypassResponse;
+
+  const alias = PROVIDER_ID_TO_ALIAS[provider] || provider;
+  const modelTargetFormat = getModelTargetFormat(alias, model);
+  // Multi-endpoint providers: pick transport matching sourceFormat → zero translation
+  const runtimeTransport = resolveTransport(provider, sourceFormat);
+  const targetFormat = modelTargetFormat || runtimeTransport?.format || getTargetFormat(provider);
+  if (runtimeTransport && credentials) credentials.runtimeTransport = runtimeTransport;
+  const stripList = getModelStrip(alias, model);
+  const upstreamModel = getModelUpstreamId(alias, model);
+
+  // Inject provider-level thinking config override (only if client hasn't set)
+  // on/off → extended type (body.thinking), none/low/medium/high → effort type (body.reasoning_effort)
+  if (providerThinking?.mode && providerThinking.mode !== "auto") {
+    const mode = providerThinking.mode;
+    if (mode === "on" && !body.thinking) {
+      console.log("Injecting provider-level thinking config override: on");
+      body = { ...body, thinking: { type: "enabled", budget_tokens: 10000 } };
+    } else if (mode === "off" && !body.thinking) {
+      body = { ...body, thinking: { type: "disabled" } };
+    } else if (!body.reasoning_effort) {
+      body = { ...body, reasoning_effort: mode };
+    }
+  }
+
+  const clientRequestedStreaming = body.stream === true || sourceFormat === FORMATS.ANTIGRAVITY || sourceFormat === FORMATS.GEMINI || sourceFormat === FORMATS.GEMINI_CLI;
+  const providerRequiresStreaming = PROVIDERS[provider]?.forceStream === true;
+  let stream = providerRequiresStreaming ? true : (body.stream !== false);
+
+  // Image generation models require non-streaming (Google v1internal:generateContent)
+  const modelType = getModelType(alias, model);
+  const isImageGenModel = modelType === "imageGen" || /image|imagen|image-generation/i.test(model);
+  if (isImageGenModel && (provider === "antigravity" || provider === "gemini-cli")) {
+    stream = false;
+  }
+
+  // DeepSeek-TUI: interactive TUI panel sends stream:true and needs SSE.
+  // Non-interactive mode (-p flag) sends without stream and can't parse SSE.
+  // Only force non-streaming when client didn't explicitly request it.
+  const detectedTool = detectClientTool(clientRawRequest?.headers || {}, body);
+  if (detectedTool === "deepseek-tui" && body.stream !== true) stream = false;
+
+  // Check client Accept header preference for non-streaming requests
+  // This fixes AI SDK compatibility where clients send Accept: application/json
+  const acceptHeader = clientRawRequest?.headers?.accept || "";
+  const clientPrefersJson = acceptHeader.includes("application/json");
+  const clientPrefersSSE = acceptHeader.includes("text/event-stream");
+  if (clientPrefersJson && !clientPrefersSSE && body.stream !== true && !providerRequiresStreaming) {
+    stream = false;
+  }
+
+  const reqLogger = await createRequestLogger(sourceFormat, targetFormat, model);
+  if (clientRawRequest) reqLogger.logClientRawRequest(clientRawRequest.endpoint, clientRawRequest.body, clientRawRequest.headers);
+  reqLogger.logRawRequest(body);
+  log?.debug?.("FORMAT", `${sourceFormat} → ${targetFormat} | stream=${stream}`);
+
+  // Native passthrough: CLI tool and provider are the same ecosystem
+  // Skip all translation/normalization — only model and Bearer are swapped
+  const clientTool = detectClientTool(clientRawRequest?.headers || {}, body);
+  const passthrough = isNativePassthrough(clientTool, provider);
+
+  // Expose raw client headers to translators/executors for session-id resolution
+  if (credentials) credentials.rawHeaders = clientRawRequest?.headers || {};
+
+  // Auto-strip media blocks the model can't read (vision/audio/pdf) before translation.
+  if (!passthrough) {
+    const caps = getCapabilitiesForModel(provider, model);
+    if (stripUnsupportedModalities(body, sourceFormat, caps)) {
+      log?.debug?.("MODALITY", `stripped unsupported media for ${provider}/${model}`);
+    }
+    // Convert remote image URLs to base64 for targets that can't fetch URLs.
+    try {
+      const n = await prefetchRemoteImages(body, sourceFormat, targetFormat, { signal: undefined });
+      if (n > 0) log?.debug?.("MODALITY", `prefetched ${n} remote image(s) for ${targetFormat}`);
+    } catch (e) { log?.warn?.("MODALITY", `image prefetch failed: ${e.message}`); }
+  }
+
+  let translatedBody;
+  let toolNameMap;
+  if (passthrough) {
+    log?.debug?.("PASSTHROUGH", `${clientTool} → ${provider} | native lossless`);
+    translatedBody = { ...body, model: stripThinkingSuffix(upstreamModel) };
+    // Normalize newer Cowork/CC beta shapes (adaptive thinking, mid-conversation system) the API rejects
+    if (clientTool === "claude") normalizeClaudePassthrough(translatedBody, translatedBody.model);
+  } else {
+    translatedBody = translateRequest(sourceFormat, targetFormat, upstreamModel, body, stream, credentials, provider, reqLogger, stripList, connectionId, clientTool);
+    if (!translatedBody) {
+      trackPendingRequest(model, provider, connectionId, false, true);
+      return createErrorResult(HTTP_STATUS.BAD_REQUEST, `Failed to translate request for ${sourceFormat} → ${targetFormat}`);
+    }
+    toolNameMap = translatedBody._toolNameMap;
+    delete translatedBody._toolNameMap;
+    translatedBody.model = stripThinkingSuffix(upstreamModel);
+  }
+
+  // Dedupe duplicate built-in tools when equivalent MCP tools are present (Claude clients only).
+  if (clientTool === "claude" && Array.isArray(translatedBody.tools)) {
+    const { tools: deduped, stripped } = dedupeTools(translatedBody.tools);
+    if (stripped.length > 0) {
+      translatedBody.tools = deduped;
+      log?.debug?.("TOOLDEDUP", `stripped ${stripped.length}: ${stripped.slice(0, 3).join(", ")}${stripped.length > 3 ? "..." : ""}`);
+    }
+  }
+
+  // Token savers: applied at the final body just before dispatch
+  // Covers both passthrough (source shape) and translated (target shape) flows
+  const finalFormat = passthrough ? sourceFormat : targetFormat;
+
+  // Request line: one correlated summary (fmt + thinking + counts + account)
+  if (log?.line) {
+    const clientModel = clientRawRequest?.body?.model || `${provider}/${model}`;
+    const msgN = translatedBody.messages?.length || translatedBody.input?.length || translatedBody.contents?.length || body.messages?.length || body.input?.length || 0;
+    const toolN = translatedBody.tools?.length || body.tools?.length || 0;
+    const fmtStr = passthrough ? `FMT: ${sourceFormat} (passthrough)` : `FMT: ${sourceFormat}→${targetFormat}`;
+    const think = log.fmtThink?.(extractThinking(translatedBody));
+    const acc = credentials?.connectionName || credentials?.connectionId?.slice(0, 8) || "-";
+    const parts = [
+      `POST ${clientModel} → ${provider}/${model}`,
+      fmtStr,
+      stream ? "STREAM" : "JSON",
+      `${msgN} MSG`,
+    ];
+    if (toolN) parts.push(`${toolN} TOOL`);
+    if (think) parts.push(`THINK:${think}`);
+    parts.push(`ACC:${acc}`);
+    log.line(reqTag, "▶", parts.join(" · "));
+  }
+
+  // TTS models don't support tool messages/function calling
+  if (getModelType(alias, model) === "tts" && translatedBody.messages) {
+    translatedBody.messages = translatedBody.messages.filter(msg => msg.role !== "tool");
+    delete translatedBody.tools;
+  }
+
+  // Token-saver summary parts, printed as one "⚙" line at the end (only active ones)
+  const xf = [];
+
+  // RTK: compress tool_result content
+  const rtkStats = compressMessages(translatedBody, rtkEnabled);
+  if (rtkStats?.hits?.length) {
+    const saved = rtkStats.bytesBefore - rtkStats.bytesAfter;
+    const pct = rtkStats.bytesBefore > 0 ? ((saved / rtkStats.bytesBefore) * 100).toFixed(0) : "0";
+    xf.push(`RTK −${saved}B(${pct}%)`);
+  }
+
+  // Headroom: optional external proxy compression; fail open if proxy is absent.
+  const headroomDiagnostics = {};
+  const headroomStats = await compressWithHeadroom(translatedBody, { enabled: headroomEnabled, url: headroomUrl, model: upstreamModel, format: finalFormat, compressUserMessages: headroomCompressUserMessages, diagnostics: headroomDiagnostics });
+  if (headroomStats) {
+    const before = headroomStats.tokens_before || 0;
+    const delta = headroomStats.tokens_saved || 0;
+    const pct = before > 0 ? ((delta / before) * 100).toFixed(1) : "0";
+    xf.push(`HEADROOM −${delta}tok(${pct}%)`);
+    if (isHeadroomPhantomSavings(headroomStats, headroomDiagnostics)) {
+      log?.warn?.("HEADROOM", `reported token delta, but outbound JSON shrank <5%; provider may bill near-original payload | ${formatHeadroomSizeLog(headroomDiagnostics)}`);
+    }
+  } else if (headroomEnabled) {
+    log?.warn?.("HEADROOM", `skipped: ${headroomDiagnostics.reason || "compression unavailable"}${headroomDiagnostics.endpoint ? ` (${headroomDiagnostics.endpoint})` : ""}`);
+  }
+
+  // Caveman: inject terse-style system prompt
+  if (cavemanEnabled && cavemanLevel) {
+    injectCaveman(translatedBody, finalFormat, cavemanLevel);
+    xf.push(`CAVEMAN:${cavemanLevel}`);
+  }
+
+  // Ponytail: inject lazy-senior-dev system prompt
+  if (ponytailEnabled && ponytailLevel) {
+    injectPonytail(translatedBody, finalFormat, ponytailLevel);
+    xf.push(`PONYTAIL:${ponytailLevel}`);
+  }
+
+  // PXPIPE: image bulky context (Claude-format bodies only), last saver before dispatch
+  let pxpipeSummary = null;
+  if (pxpipeEnabled) {
+    const pxpipeResult = await compressWithPxpipe(translatedBody, {
+      enabled: true, format: finalFormat, model: upstreamModel,
+      minChars: pxpipeMinChars, timeoutMs: pxpipeTimeoutMs, transform: pxpipeTransform,
+    });
+    pxpipeSummary = pxpipeResult.summary;
+    if (pxpipeResult.body) translatedBody = pxpipeResult.body;
+    if (pxpipeSummary?.applied) xf.push(`PXPIPE:${pxpipeSummary.imageCount}img`);
+    try { onPxpipeEvent?.({ provider, model, ...pxpipeSummary }); } catch { /* stats must not break requests */ }
+  }
+
+  if (xf.length && log?.line) log.line(reqTag, "⚙", xf.join(" · "));
+
+  const executor = getExecutor(provider);
+  trackPendingRequest(model, provider, connectionId, true);
+  appendRequestLog({ model, provider, connectionId, status: "PENDING" }).catch(() => { });
+
+  const msgCount = translatedBody.messages?.length || translatedBody.input?.length || translatedBody.contents?.length || translatedBody.request?.contents?.length || 0;
+  log?.debug?.("REQUEST", `${provider.toUpperCase()} | ${model} | ${msgCount} msgs`);
+
+  const streamController = createStreamController({
+    onDisconnect: (reason) => {
+      trackPendingRequest(model, provider, connectionId, false);
+      if (onDisconnect) onDisconnect(reason);
+    },
+    onError: () => trackPendingRequest(model, provider, connectionId, false),
+    log, provider, model, reqTag
+  });
+
+  const proxyOptions = {
+    connectionProxyEnabled: credentials?.providerSpecificData?.connectionProxyEnabled === true,
+    connectionProxyUrl: credentials?.providerSpecificData?.connectionProxyUrl || "",
+    connectionNoProxy: credentials?.providerSpecificData?.connectionNoProxy || "",
+    vercelRelayUrl: credentials?.providerSpecificData?.vercelRelayUrl || "",
+  };
+
+  if (proxyOptions.vercelRelayUrl) {
+    const connectionName = credentials?.connectionName || credentials?.connectionId || "unknown";
+    const poolId = credentials?.providerSpecificData?.connectionProxyPoolId || "none";
+    log?.info?.("PROXY", `${provider.toUpperCase()} | ${model} | conn=${connectionName} | pool=${poolId} | vercel-relay=${proxyOptions.vercelRelayUrl}`);
+  } else if (proxyOptions.connectionProxyEnabled && proxyOptions.connectionProxyUrl) {
+    let maskedProxyUrl = proxyOptions.connectionProxyUrl;
+    try {
+      const parsed = new URL(proxyOptions.connectionProxyUrl);
+      const host = parsed.hostname || "";
+      const port = parsed.port ? `:${parsed.port}` : "";
+      const protocol = parsed.protocol || "http:";
+      maskedProxyUrl = `${protocol}//${host}${port}`;
+    } catch {
+      // Keep raw if URL parsing fails
+    }
+
+    const poolId = credentials?.providerSpecificData?.connectionProxyPoolId || "none";
+    const connectionName = credentials?.connectionName || credentials?.connectionId || "unknown";
+    log?.info?.("PROXY", `${provider.toUpperCase()} | ${model} | conn=${connectionName} | pool=${poolId} | url=${maskedProxyUrl}`);
+  }
+
+  if (proxyOptions.connectionProxyEnabled && proxyOptions.connectionNoProxy) {
+    const connectionName = credentials?.connectionName || credentials?.connectionId || "unknown";
+    log?.debug?.("PROXY", `${provider.toUpperCase()} | ${model} | conn=${connectionName} | no_proxy=${proxyOptions.connectionNoProxy}`);
+  }
+
+  // Execute request
+  let providerResponse, providerUrl, providerHeaders, finalBody;
+  try {
+    const result = await executor.execute({ model, body: translatedBody, stream, credentials, signal: streamController.signal, log, proxyOptions });
+    providerResponse = result.response;
+    providerUrl = result.url;
+    providerHeaders = result.headers;
+    finalBody = result.transformedBody;
+    reqLogger.logTargetRequest(providerUrl, providerHeaders, finalBody);
+  } catch (error) {
+    trackPendingRequest(model, provider, connectionId, false, true);
+    appendRequestLog({ model, provider, connectionId, status: `FAILED ${error.name === "AbortError" ? 499 : HTTP_STATUS.BAD_GATEWAY}` }).catch(() => { });
+    saveRequestDetail(buildRequestDetail({
+      provider, model, connectionId,
+      latency: { ttft: 0, total: Date.now() - requestStartTime },
+      tokens: { prompt_tokens: 0, completion_tokens: 0 },
+      request: extractRequestConfig(body, stream),
+      providerRequest: translatedBody || null,
+      response: { error: error.message || String(error), status: error.name === "AbortError" ? 499 : 502, thinking: null },
+      pxpipe: pxpipeSummary,
+      status: "error"
+    })).catch(() => { });
+
+    if (error.name === "AbortError") {
+      streamController.handleError(error);
+      return createErrorResult(499, "Request aborted");
+    }
+    const errMsg = formatProviderError(error, provider, model, HTTP_STATUS.BAD_GATEWAY);
+    if (log?.errorLine) {
+      log.errorLine(reqTag, "✗", `ERROR 502 · ${provider}/${model} · ${Date.now() - requestStartTime}ms\n    ${errMsg}${error.stack ? `\n    ${error.stack}` : ""}`);
+    }
+    return createErrorResult(HTTP_STATUS.BAD_GATEWAY, errMsg);
+  }
+
+  // Handle 401/403 - try token refresh (skip for noAuth providers)
+  if (!executor.noAuth && (providerResponse.status === HTTP_STATUS.UNAUTHORIZED || providerResponse.status === HTTP_STATUS.FORBIDDEN)) {
+    try {
+      const newCredentials = await refreshWithRetry(() => executor.refreshCredentials(credentials, log), 3, log);
+      if (newCredentials?.accessToken || newCredentials?.copilotToken) {
+        if (log?.line) log.line(reqTag, "🔑", `TOKEN REFRESHED · ${provider}/${model}`);
+        Object.assign(credentials, newCredentials);
+        if (onCredentialsRefreshed) {
+          try { await onCredentialsRefreshed(newCredentials); } catch (e) { log?.warn?.("TOKEN", `onCredentialsRefreshed failed: ${e.message}`); }
+        }
+        try {
+          const retryResult = await executor.execute({ model, body: translatedBody, stream, credentials, signal: streamController.signal, log, proxyOptions });
+          if (retryResult.response.ok) { providerResponse = retryResult.response; providerUrl = retryResult.url; }
+        } catch { log?.warn?.("TOKEN", `${provider.toUpperCase()} | retry after refresh failed`); }
+      } else {
+        log?.warn?.("TOKEN", `${provider.toUpperCase()} | refresh failed`);
+      }
+    } catch (e) {
+      log?.warn?.("TOKEN", `${provider.toUpperCase()} | refresh threw: ${e.message}`);
+    }
+  }
+
+  // Provider returned error
+  if (!providerResponse.ok) {
+    trackPendingRequest(model, provider, connectionId, false, true);
+    const { statusCode, message, resetsAtMs } = await parseUpstreamError(providerResponse, executor);
+    appendRequestLog({ model, provider, connectionId, status: `FAILED ${statusCode}` }).catch(() => { });
+    saveRequestDetail(buildRequestDetail({
+      provider, model, connectionId,
+      latency: { ttft: 0, total: Date.now() - requestStartTime },
+      tokens: { prompt_tokens: 0, completion_tokens: 0 },
+      request: extractRequestConfig(body, stream),
+      providerRequest: finalBody || translatedBody || null,
+      response: { error: message, status: statusCode, thinking: null },
+      pxpipe: pxpipeSummary,
+      status: "error"
+    })).catch(() => { });
+
+    const errMsg = formatProviderError(new Error(message), provider, model, statusCode);
+    if (log?.errorLine) {
+      const urlStr = providerUrl ? `\n    URL: ${providerUrl}` : "";
+      log.errorLine(reqTag, "✗", `ERROR ${statusCode} · ${provider}/${model} · ${Date.now() - requestStartTime}ms${urlStr}\n    ${errMsg}`);
+    }
+    reqLogger.logError(new Error(message), finalBody || translatedBody);
+    return createErrorResult(statusCode, errMsg, resetsAtMs);
+  }
+
+  const sharedCtx = { provider, model, body, stream, translatedBody, finalBody, requestStartTime, connectionId, apiKey, clientRawRequest, onRequestSuccess, pxpipe: pxpipeSummary, reqTag, log };
+  const appendLog = (extra) => appendRequestLog({ model, provider, connectionId, ...extra }).catch(() => { });
+  const trackDone = () => trackPendingRequest(model, provider, connectionId, false);
+
+  // Provider forced streaming but client wants JSON
+  if (!clientRequestedStreaming && providerRequiresStreaming) {
+    const result = await handleForcedSSEToJson({ ...sharedCtx, providerResponse, sourceFormat, trackDone, appendLog });
+    if (result) { streamController.handleComplete(); return result; }
+  }
+
+  // True non-streaming response
+  if (!stream) {
+    const result = await handleNonStreamingResponse({ ...sharedCtx, providerResponse, sourceFormat, targetFormat, reqLogger, toolNameMap, trackDone, appendLog });
+    streamController.handleComplete();
+    return result;
+  }
+
+  // Streaming response
+  const { onStreamComplete, streamDetailId } = buildOnStreamComplete({ ...sharedCtx });
+  return handleStreamingResponse({ ...sharedCtx, providerResponse, sourceFormat, targetFormat, userAgent, reqLogger, toolNameMap, streamController, onStreamComplete, streamDetailId });
+}
+
+export function isTokenExpiringSoon(expiresAt, bufferMs = 5 * 60 * 1000) {
+  if (!expiresAt) return false;
+  return new Date(expiresAt).getTime() - Date.now() < bufferMs;
+}
diff --git a/open-sse/handlers/chatCore/nonStreamingHandler.js b/open-sse/handlers/chatCore/nonStreamingHandler.js
new file mode 100644
index 0000000..f93058f
--- /dev/null
+++ b/open-sse/handlers/chatCore/nonStreamingHandler.js
@@ -0,0 +1,312 @@
+import { FORMATS } from "../../translator/formats.js";
+import { needsTranslation } from "../../translator/index.js";
+import { fromOpenAIFinish } from "../../translator/concerns/finishReason.js";
+import { ollamaBodyToOpenAI } from "../../translator/response/ollama-to-openai.js";
+import { addBufferToUsage, filterUsageForFormat } from "../../utils/usageTracking.js";
+import { createErrorResult } from "../../utils/error.js";
+import { HTTP_STATUS } from "../../config/runtimeConfig.js";
+import { parseSSEToOpenAIResponse } from "./sseToJsonHandler.js";
+import { buildRequestDetail, extractRequestConfig, extractUsageFromResponse, saveUsageStats, formatDoneLine } from "./requestDetail.js";
+import { appendRequestLog, saveRequestDetail } from "@/lib/usageDb.js";
+import { decloakToolNames } from "../../utils/claudeCloaking.js";
+
+function parseToolArguments(value) {
+  if (!value) return {};
+  if (typeof value === "object") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return {};
+  }
+}
+
+function openAICompletionToClaudeMessage(responseBody) {
+  if (!responseBody?.choices?.[0]) return responseBody;
+  const choice = responseBody.choices[0];
+  const message = choice.message || {};
+  const content = [];
+
+  const reasoning = message.reasoning_content || message.provider_specific_fields?.reasoning_content || "";
+  if (reasoning) {
+    content.push({ type: "thinking", thinking: reasoning });
+  }
+  if (typeof message.content === "string" && message.content.length > 0) {
+    content.push({ type: "text", text: message.content });
+  }
+  for (const toolCall of message.tool_calls || []) {
+    const fn = toolCall.function || {};
+    content.push({
+      type: "tool_use",
+      id: toolCall.id || `toolu_${Date.now()}_${content.length}`,
+      name: fn.name || toolCall.name || "",
+      input: parseToolArguments(fn.arguments || toolCall.arguments),
+    });
+  }
+  if (content.length === 0) content.push({ type: "text", text: "" });
+
+  const usage = responseBody.usage || {};
+  return {
+    id: String(responseBody.id || `msg_${Date.now()}`).replace(/^chatcmpl-/, ""),
+    type: "message",
+    role: "assistant",
+    model: responseBody.model || "unknown",
+    content,
+    stop_reason: fromOpenAIFinish(choice.finish_reason, FORMATS.CLAUDE),
+    stop_sequence: null,
+    usage: {
+      input_tokens: usage.prompt_tokens || usage.input_tokens || 0,
+      output_tokens: usage.completion_tokens || usage.output_tokens || 0,
+    },
+  };
+}
+
+/**
+ * Translate non-streaming response body from provider format → OpenAI format.
+ */
+export function translateNonStreamingResponse(responseBody, targetFormat, sourceFormat) {
+  if (targetFormat === sourceFormat) return responseBody;
+  if (targetFormat === FORMATS.OPENAI && sourceFormat === FORMATS.CLAUDE) {
+    return openAICompletionToClaudeMessage(responseBody);
+  }
+  if (targetFormat === FORMATS.OPENAI) return responseBody;
+
+  // Gemini / Antigravity
+  if (targetFormat === FORMATS.GEMINI || targetFormat === FORMATS.ANTIGRAVITY || targetFormat === FORMATS.GEMINI_CLI || targetFormat === FORMATS.VERTEX) {
+    const response = responseBody.response || responseBody;
+    if (!response?.candidates?.[0]) return responseBody;
+
+    const candidate = response.candidates[0];
+    const content = candidate.content;
+    const usage = response.usageMetadata || responseBody.usageMetadata;
+    let textContent = "", reasoningContent = "";
+    const toolCalls = [];
+
+    if (content?.parts) {
+      for (const part of content.parts) {
+        if (part.thought === true && part.text) reasoningContent += part.text;
+        else if (part.text !== undefined) textContent += part.text;
+        if (part.functionCall) {
+          toolCalls.push({
+            id: `call_${part.functionCall.name}_${Date.now()}_${toolCalls.length}`,
+            type: "function",
+            function: { name: part.functionCall.name, arguments: JSON.stringify(part.functionCall.args || {}) }
+          });
+        }
+        // Handle inline image data (from image generation models)
+        const inlineData = part.inlineData || part.inline_data;
+        if (inlineData?.data) {
+          const mimeType = inlineData.mimeType || inlineData.mime_type || "image/png";
+          textContent += `\n![image](data:${mimeType};base64,${inlineData.data})\n`;
+        }
+      }
+    }
+
+    const message = { role: "assistant" };
+    if (textContent) message.content = textContent;
+    if (reasoningContent) message.reasoning_content = reasoningContent;
+    if (toolCalls.length > 0) message.tool_calls = toolCalls;
+    if (!message.content && !message.tool_calls) message.content = "";
+
+    let finishReason = (candidate.finishReason || "stop").toLowerCase();
+    if (finishReason === "stop" && toolCalls.length > 0) finishReason = "tool_calls";
+
+    const result = {
+      id: `chatcmpl-${response.responseId || Date.now()}`,
+      object: "chat.completion",
+      created: Math.floor(new Date(response.createTime || Date.now()).getTime() / 1000),
+      model: response.modelVersion || "gemini",
+      choices: [{ index: 0, message, finish_reason: finishReason }]
+    };
+
+    if (usage) {
+      result.usage = {
+        prompt_tokens: (usage.promptTokenCount || 0) + (usage.thoughtsTokenCount || 0),
+        completion_tokens: usage.candidatesTokenCount || 0,
+        total_tokens: usage.totalTokenCount || 0
+      };
+      if (usage.thoughtsTokenCount > 0) {
+        result.usage.completion_tokens_details = { reasoning_tokens: usage.thoughtsTokenCount };
+      }
+    }
+    return result;
+  }
+
+  // Claude
+  if (targetFormat === FORMATS.CLAUDE) {
+    // Always translate a Claude-format body to OpenAI, even if `content` is
+    // missing/null (e.g. M3 with max_tokens:1 spends the budget on thinking
+    // and returns `content: null`). Returning the raw body would leave the
+    // OpenAI client without a `choices` array and surface as a UI test error.
+    // Early return if the response is already in OpenAI format (has choices array)
+    // or if it has content as a non-array value (likely a different non-Claude format).
+    // Some providers (e.g. xiaomi-tokenplan) return OpenAI-format responses even when
+    // the request was translated to Claude format — the targetFormat is Claude but the
+    // actual response is OpenAI-native and needs no further translation.
+    if (responseBody.choices || (responseBody.content && !Array.isArray(responseBody.content))) return responseBody;
+
+    let textContent = "", thinkingContent = "";
+    const toolCalls = [];
+
+    for (const block of (responseBody.content || [])) {
+      if (block.type === "text") {
+        // Strip markdown code block markers (e.g. kimi wraps JSON in ```json...```)
+        const raw = block.text ?? "";
+        const text = raw.replace(/^\s*```\s*json\s*\n?/i, "").replace(/\n?\s*```\s*$/i, "");
+        textContent += text;
+      } else if (block.type === "thinking") thinkingContent += block.thinking || "";
+      else if (block.type === "tool_use") {
+        toolCalls.push({ id: block.id, type: "function", function: { name: block.name, arguments: JSON.stringify(block.input || {}) } });
+      }
+    }
+
+    const message = { role: "assistant" };
+    if (textContent) message.content = textContent;
+    if (thinkingContent) message.reasoning_content = thinkingContent;
+    if (toolCalls.length > 0) message.tool_calls = toolCalls;
+    if (!message.content && !message.tool_calls) message.content = "";
+
+    let finishReason = responseBody.stop_reason || "stop";
+    if (finishReason === "end_turn") finishReason = "stop";
+    if (finishReason === "tool_use") finishReason = "tool_calls";
+
+    const result = {
+      id: `chatcmpl-${responseBody.id || Date.now()}`,
+      object: "chat.completion",
+      created: Math.floor(Date.now() / 1000),
+      model: responseBody.model || "claude",
+      choices: [{ index: 0, message, finish_reason: finishReason }]
+    };
+
+    if (responseBody.usage) {
+      result.usage = {
+        prompt_tokens: responseBody.usage.input_tokens || 0,
+        completion_tokens: responseBody.usage.output_tokens || 0,
+        total_tokens: (responseBody.usage.input_tokens || 0) + (responseBody.usage.output_tokens || 0)
+      };
+    }
+    return result;
+  }
+
+  // Ollama
+  if (targetFormat === FORMATS.OLLAMA) {
+    return ollamaBodyToOpenAI(responseBody);
+  }
+
+  return responseBody;
+}
+
+/**
+ * Handle non-streaming response from provider.
+ */
+export async function handleNonStreamingResponse({ providerResponse, provider, model, sourceFormat, targetFormat, body, stream, translatedBody, finalBody, requestStartTime, connectionId, apiKey, clientRawRequest, onRequestSuccess, reqLogger, toolNameMap, trackDone, appendLog, pxpipe, reqTag, log }) {
+  trackDone();
+  const contentType = providerResponse.headers.get("content-type") || "";
+  let responseBody;
+
+  if (contentType.includes("text/event-stream")) {
+    const sseText = await providerResponse.text();
+    const parsed = parseSSEToOpenAIResponse(sseText, model);
+    if (!parsed) {
+      appendLog({ status: `FAILED ${HTTP_STATUS.BAD_GATEWAY}` });
+      return createErrorResult(HTTP_STATUS.BAD_GATEWAY, "Invalid SSE response for non-streaming request");
+    }
+    responseBody = parsed;
+  } else {
+    try {
+      responseBody = await providerResponse.json();
+    } catch (err) {
+      appendLog({ status: `FAILED ${HTTP_STATUS.BAD_GATEWAY}` });
+      console.error(`[ChatCore] Failed to parse JSON from ${provider}:`, err.message);
+      return createErrorResult(HTTP_STATUS.BAD_GATEWAY, `Invalid JSON response from ${provider}`);
+    }
+  }
+
+  reqLogger.logProviderResponse(providerResponse.status, providerResponse.statusText, providerResponse.headers, responseBody);
+  if (onRequestSuccess) {
+    Promise.resolve()
+      .then(onRequestSuccess)
+      .catch(err => {
+        console.error("[ChatCore] onRequestSuccess failed:", err?.message || err);
+      });
+  }
+
+  // Decloak tool_use names once on raw Claude body, before any translation (INPUT side)
+  responseBody = decloakToolNames(responseBody, toolNameMap);
+
+  const usage = extractUsageFromResponse(responseBody);
+  appendLog({ tokens: usage, status: "200 OK" });
+  saveUsageStats({ provider, model, tokens: usage, connectionId, apiKey, endpoint: clientRawRequest?.endpoint, silent: true });
+  if (log?.line) log.line(reqTag, "📊", formatDoneLine({ usage, latency: { total: Date.now() - requestStartTime } }));
+
+  const translatedResponse = needsTranslation(targetFormat, sourceFormat)
+    ? translateNonStreamingResponse(responseBody, targetFormat, sourceFormat)
+    : responseBody;
+  const isClaudeMessageResponse = sourceFormat === FORMATS.CLAUDE && translatedResponse?.type === "message";
+
+  // Fix finish_reason for tool_calls: some providers return non-standard values (e.g. "other")
+  if (translatedResponse?.choices?.[0]) {
+    const choice = translatedResponse.choices[0];
+    const msg = choice.message;
+    const hasToolCalls = Array.isArray(msg?.tool_calls) && msg.tool_calls.length > 0;
+    if (hasToolCalls && choice.finish_reason !== "tool_calls") {
+      choice.finish_reason = "tool_calls";
+    }
+  }
+
+  // Ensure OpenAI-required fields
+  if (!isClaudeMessageResponse) {
+    if (!translatedResponse.object) translatedResponse.object = "chat.completion";
+    if (!translatedResponse.created) translatedResponse.created = Math.floor(Date.now() / 1000);
+  }
+
+  // Strip Azure-specific fields
+  if (!isClaudeMessageResponse) {
+    delete translatedResponse.prompt_filter_results;
+    if (translatedResponse?.choices) {
+      for (const choice of translatedResponse.choices) delete choice.content_filter_results;
+    }
+  }
+
+  if (translatedResponse?.usage) {
+    translatedResponse.usage = filterUsageForFormat(addBufferToUsage(translatedResponse.usage), sourceFormat);
+  }
+
+  // Strip reasoning_content only when content is non-empty.
+  // When content is empty (e.g. thinking models that used all tokens for reasoning),
+  // reasoning_content is the only useful output and must be preserved.
+  if (!isClaudeMessageResponse && translatedResponse?.choices) {
+    for (const choice of translatedResponse.choices) {
+      if (choice?.message?.reasoning_content && choice.message.content) {
+        delete choice.message.reasoning_content;
+      }
+    }
+  }
+
+  reqLogger.logConvertedResponse(translatedResponse);
+
+  const totalLatency = Date.now() - requestStartTime;
+  saveRequestDetail(buildRequestDetail({
+    provider, model, connectionId,
+    latency: { ttft: totalLatency, total: totalLatency },
+    tokens: usage || { prompt_tokens: 0, completion_tokens: 0 },
+    request: extractRequestConfig(body, stream),
+    providerRequest: finalBody || translatedBody || null,
+    providerResponse: responseBody || null,
+    response: {
+      content: translatedResponse?.choices?.[0]?.message?.content || translatedResponse?.content || null,
+      thinking: translatedResponse?.choices?.[0]?.message?.reasoning_content || translatedResponse?.reasoning_content || null,
+      finish_reason: translatedResponse?.choices?.[0]?.finish_reason || "unknown"
+    },
+    pxpipe,
+    status: "success"
+  }, { endpoint: clientRawRequest?.endpoint || null })).catch(err => {
+    console.error("[RequestDetail] Failed to save:", err.message);
+  });
+
+  return {
+    success: true,
+    response: new Response(JSON.stringify(translatedResponse), {
+      headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" }
+    })
+  };
+}
diff --git a/open-sse/handlers/chatCore/requestDetail.js b/open-sse/handlers/chatCore/requestDetail.js
new file mode 100644
index 0000000..b3d2411
--- /dev/null
+++ b/open-sse/handlers/chatCore/requestDetail.js
@@ -0,0 +1,126 @@
+import { saveRequestUsage, appendRequestLog, saveRequestDetail } from "@/lib/usageDb.js";
+import { COLORS } from "../../utils/stream.js";
+import { canonicalizeUsage } from "../../utils/usageTracking.js";
+
+const OPTIONAL_PARAMS = [
+  "temperature", "top_p", "top_k",
+  "max_tokens", "max_completion_tokens",
+  "thinking", "reasoning", "enable_thinking",
+  "presence_penalty", "frequency_penalty",
+  "seed", "stop", "tools", "tool_choice",
+  "response_format", "prediction", "store", "metadata",
+  "n", "logprobs", "top_logprobs", "logit_bias",
+  "user", "parallel_tool_calls"
+];
+
+export function extractRequestConfig(body, stream) {
+  const config = { messages: body.messages || [], model: body.model, stream };
+  for (const param of OPTIONAL_PARAMS) {
+    if (body[param] !== undefined) config[param] = body[param];
+  }
+  return config;
+}
+
+export function extractUsageFromResponse(responseBody) {
+  if (!responseBody || typeof responseBody !== "object") return null;
+
+  // Claude format
+  if (responseBody.usage?.input_tokens !== undefined) {
+    return {
+      prompt_tokens: responseBody.usage.input_tokens || 0,
+      completion_tokens: responseBody.usage.output_tokens || 0,
+      cache_read_input_tokens: responseBody.usage.cache_read_input_tokens,
+      cache_creation_input_tokens: responseBody.usage.cache_creation_input_tokens
+    };
+  }
+
+  // OpenAI format
+  if (responseBody.usage?.prompt_tokens !== undefined) {
+    return {
+      prompt_tokens: responseBody.usage.prompt_tokens || 0,
+      completion_tokens: responseBody.usage.completion_tokens || 0,
+      cached_tokens: responseBody.usage.prompt_tokens_details?.cached_tokens,
+      reasoning_tokens: responseBody.usage.completion_tokens_details?.reasoning_tokens
+    };
+  }
+
+  // Gemini format
+  if (responseBody.usageMetadata) {
+    return {
+      prompt_tokens: responseBody.usageMetadata.promptTokenCount || 0,
+      completion_tokens: responseBody.usageMetadata.candidatesTokenCount || 0,
+      cached_tokens: responseBody.usageMetadata.cachedContentTokenCount || 0,
+      reasoning_tokens: responseBody.usageMetadata.thoughtsTokenCount || 0
+    };
+  }
+
+  return null;
+}
+
+export function buildRequestDetail(base, overrides = {}) {
+  return {
+    provider: base.provider || "unknown",
+    model: base.model || "unknown",
+    connectionId: base.connectionId || undefined,
+    timestamp: new Date().toISOString(),
+    latency: base.latency || { ttft: 0, total: 0 },
+    tokens: base.tokens || { prompt_tokens: 0, completion_tokens: 0 },
+    request: base.request,
+    providerRequest: base.providerRequest || null,
+    providerResponse: base.providerResponse || null,
+    response: base.response || {},
+    pxpipe: base.pxpipe || undefined,
+    status: base.status || "success",
+    ...overrides
+  };
+}
+
+// Build the "done" summary: duration, ttft, in/out tokens with cache breakdown
+export function formatDoneLine({ usage, latency }) {
+  const u = usage || {};
+  const inTok = u.prompt_tokens ?? u.input_tokens ?? 0;
+  const outTok = u.completion_tokens ?? u.output_tokens ?? 0;
+  const cacheRead = u.cache_read_input_tokens ?? u.cached_tokens ?? u.prompt_tokens_details?.cached_tokens ?? 0;
+  const cacheCreate = u.cache_creation_input_tokens ?? 0;
+  let inStr = `IN ${inTok}`;
+  if (cacheRead || cacheCreate) {
+    const parts = [];
+    if (cacheRead) parts.push(`↻${cacheRead}`);
+    if (cacheCreate) parts.push(`+${cacheCreate}`);
+    inStr += ` (CACHE ${parts.join(" ")})`;
+  }
+  const ttftStr = latency?.ttft ? ` · TTFT ${latency.ttft}ms` : "";
+  return `DONE ${latency?.total ?? 0}ms${ttftStr} · ${inStr} · OUT ${outTok}`;
+}
+
+export function saveUsageStats({ provider, model, tokens, connectionId, apiKey, endpoint, label = "USAGE", silent = false }) {
+  if (!tokens || typeof tokens !== "object") return;
+
+  const inTokens = tokens.input_tokens ?? tokens.prompt_tokens ?? 0;
+  const outTokens = tokens.output_tokens ?? tokens.completion_tokens ?? 0;
+
+  if (inTokens === 0 && outTokens === 0) return;
+
+  if (!silent) {
+    const time = new Date().toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit", second: "2-digit" });
+    const accountSuffix = connectionId ? ` | account=${connectionId.slice(0, 8)}...` : "";
+    console.log(`${COLORS.green}[${time}] 📊 [${label}] ${provider.toUpperCase()} | in=${inTokens} | out=${outTokens}${accountSuffix}${COLORS.reset}`);
+  }
+
+  // Canonicalize to one storage convention (prompt_tokens cache-inclusive) so
+  // cached/cache-creation tokens survive to cost calc + stats. See canonicalizeUsage.
+  const normalized = canonicalizeUsage(tokens) || {
+    prompt_tokens: tokens.prompt_tokens ?? tokens.input_tokens ?? 0,
+    completion_tokens: tokens.completion_tokens ?? tokens.output_tokens ?? 0
+  };
+
+  saveRequestUsage({
+    provider: provider || "unknown",
+    model: model || "unknown",
+    tokens: normalized,
+    timestamp: new Date().toISOString(),
+    connectionId: connectionId || undefined,
+    apiKey: apiKey || undefined,
+    endpoint: endpoint || null
+  }).catch(() => {});
+}
diff --git a/open-sse/handlers/chatCore/sseToJsonHandler.js b/open-sse/handlers/chatCore/sseToJsonHandler.js
new file mode 100644
index 0000000..f25986c
--- /dev/null
+++ b/open-sse/handlers/chatCore/sseToJsonHandler.js
@@ -0,0 +1,237 @@
+import { convertResponsesStreamToJson } from "../../transformer/streamToJsonConverter.js";
+import { createErrorResult } from "../../utils/error.js";
+import { HTTP_STATUS } from "../../config/runtimeConfig.js";
+import { FORMATS } from "../../translator/formats.js";
+import { PROVIDERS } from "../../config/providers.js";
+import { buildRequestDetail, extractRequestConfig, saveUsageStats, formatDoneLine } from "./requestDetail.js";
+
+// Responses-API providers (e.g. codex) may emit SSE without content-type + use Responses output shape
+const isResponsesProvider = (p) => PROVIDERS[p]?.format === FORMATS.OPENAI_RESPONSES;
+import { saveRequestDetail, appendRequestLog } from "@/lib/usageDb.js";
+
+function textFromResponsesMessageItem(item) {
+  if (!item?.content || !Array.isArray(item.content)) return "";
+  const byType = item.content.find((c) => c.type === "output_text");
+  if (typeof byType?.text === "string") return byType.text;
+  const anyText = item.content.find((c) => typeof c.text === "string");
+  if (typeof anyText?.text === "string") return anyText.text;
+  return "";
+}
+
+/**
+ * Codex / Responses API may emit many alternating reasoning + message items.
+ * Early message blocks often have empty output_text; the user-visible answer is usually in the last non-empty message.
+ */
+function pickAssistantMessageForChatCompletion(output) {
+  if (!Array.isArray(output)) return { msgItem: null, textContent: null };
+  const messages = output.filter((item) => item?.type === "message");
+  if (messages.length === 0) return { msgItem: null, textContent: null };
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const text = textFromResponsesMessageItem(messages[i]);
+    if (text.length > 0) return { msgItem: messages[i], textContent: text };
+  }
+  const last = messages[messages.length - 1];
+  return { msgItem: last, textContent: textFromResponsesMessageItem(last) };
+}
+
+/**
+ * Parse OpenAI-style SSE text into a single chat completion JSON.
+ * Used when provider forces streaming but client wants non-streaming.
+ */
+export function parseSSEToOpenAIResponse(rawSSE, fallbackModel) {
+  const chunks = [];
+
+  for (const line of String(rawSSE || "").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("data:")) continue;
+    const payload = trimmed.slice(5).trim();
+    if (!payload || payload === "[DONE]") continue;
+    try { chunks.push(JSON.parse(payload)); } catch { /* ignore malformed lines */ }
+  }
+
+  if (chunks.length === 0) return null;
+
+  const first = chunks[0];
+  const contentParts = [];
+  const reasoningParts = [];
+  const toolCallMap = new Map(); // index -> { id, type, function: { name, arguments } }
+  let finishReason = "stop";
+  let usage = null;
+
+  for (const chunk of chunks) {
+    const choice = chunk?.choices?.[0];
+    const delta = choice?.delta || {};
+    if (typeof delta.content === "string" && delta.content.length > 0) contentParts.push(delta.content);
+    if (typeof delta.reasoning_content === "string" && delta.reasoning_content.length > 0) reasoningParts.push(delta.reasoning_content);
+    if (choice?.finish_reason) finishReason = choice.finish_reason;
+    if (chunk?.usage && typeof chunk.usage === "object") usage = chunk.usage;
+
+    // Accumulate tool_calls from streaming deltas
+    if (Array.isArray(delta.tool_calls)) {
+      for (const tc of delta.tool_calls) {
+        const idx = tc.index ?? 0;
+        if (!toolCallMap.has(idx)) {
+          toolCallMap.set(idx, { id: tc.id || "", type: "function", function: { name: "", arguments: "" } });
+        }
+        const existing = toolCallMap.get(idx);
+        if (tc.id) existing.id = tc.id;
+        if (tc.function?.name) existing.function.name += tc.function.name;
+        if (tc.function?.arguments) existing.function.arguments += tc.function.arguments;
+      }
+    }
+  }
+
+  const message = { role: "assistant", content: contentParts.join("") || (toolCallMap.size > 0 ? null : "") };
+  if (reasoningParts.length > 0) message.reasoning_content = reasoningParts.join("");
+  if (toolCallMap.size > 0) {
+    message.tool_calls = [...toolCallMap.entries()].sort((a, b) => a[0] - b[0]).map(([, tc]) => tc);
+  }
+
+  const result = {
+    id: first.id || `chatcmpl-${Date.now()}`,
+    object: "chat.completion",
+    created: first.created || Math.floor(Date.now() / 1000),
+    model: first.model || fallbackModel || "unknown",
+    choices: [{ index: 0, message, finish_reason: finishReason }]
+  };
+  if (usage) result.usage = usage;
+  return result;
+}
+
+/**
+ * Handle case: provider forced streaming but client wants JSON.
+ * Supports both Codex/Responses API SSE and standard Chat Completions SSE.
+ */
+export async function handleForcedSSEToJson({ providerResponse, sourceFormat, provider, model, body, stream, translatedBody, finalBody, requestStartTime, connectionId, apiKey, clientRawRequest, onRequestSuccess, trackDone, appendLog, reqTag, log }) {
+  const contentType = providerResponse.headers.get("content-type") || "";
+  const isSSE = contentType.includes("text/event-stream") || (contentType === "" && isResponsesProvider(provider));
+  if (!isSSE) return null; // not handled here
+
+  trackDone();
+
+  const ctx = {
+    provider, model, connectionId,
+    request: extractRequestConfig(body, stream),
+    providerRequest: finalBody || translatedBody || null
+  };
+
+  // Codex/Responses API SSE path
+  const isCodexResponsesApi = isResponsesProvider(provider) || sourceFormat === FORMATS.OPENAI_RESPONSES;
+  if (isCodexResponsesApi) {
+    try {
+      const jsonResponse = await convertResponsesStreamToJson(providerResponse.body);
+      if (onRequestSuccess) await onRequestSuccess();
+
+      const usage = jsonResponse.usage || {};
+      appendLog({ tokens: usage, status: "200 OK" });
+      saveUsageStats({ provider, model, tokens: usage, connectionId, apiKey, endpoint: clientRawRequest?.endpoint, silent: true });
+      if (log?.line) log.line(reqTag, "📊", formatDoneLine({ usage, latency: { total: Date.now() - requestStartTime } }));
+
+      const { msgItem, textContent } = pickAssistantMessageForChatCompletion(jsonResponse.output);
+      const totalLatency = Date.now() - requestStartTime;
+
+      saveRequestDetail(buildRequestDetail({
+        ...ctx,
+        latency: { ttft: totalLatency, total: totalLatency },
+        tokens: { prompt_tokens: usage.input_tokens || 0, completion_tokens: usage.output_tokens || 0 },
+        response: { content: textContent, thinking: null, finish_reason: jsonResponse.status || "unknown" },
+        status: "success"
+      }, { endpoint: clientRawRequest?.endpoint || null })).catch(() => {});
+
+      // Client is Responses API → return as-is
+      if (sourceFormat === FORMATS.OPENAI_RESPONSES) {
+        return { success: true, response: new Response(JSON.stringify(jsonResponse), { headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" } }) };
+      }
+
+      // Build client-format response
+      const inTokens = usage.input_tokens || 0;
+      const outTokens = usage.output_tokens || 0;
+      let finalResp;
+
+      // Extract tool calls from Responses API output (function_call items)
+      const funcCallItems = (jsonResponse.output || []).filter(item => item.type === "function_call");
+      const toolCalls = funcCallItems.map((item, idx) => ({
+        id: item.call_id || `call_${item.name}_${Date.now()}_${idx}`,
+        type: "function",
+        function: {
+          name: item.name,
+          arguments: typeof item.arguments === "string" ? item.arguments : JSON.stringify(item.arguments || {})
+        }
+      }));
+      const hasToolCalls = toolCalls.length > 0;
+
+      if (sourceFormat === FORMATS.ANTIGRAVITY || sourceFormat === FORMATS.GEMINI || sourceFormat === FORMATS.GEMINI_CLI) {
+        finalResp = {
+          response: {
+            candidates: [{ content: { role: "model", parts: [{ text: textContent || "" }] }, finishReason: "STOP", index: 0 }],
+            usageMetadata: { promptTokenCount: inTokens, candidatesTokenCount: outTokens, totalTokenCount: inTokens + outTokens },
+            modelVersion: model,
+            responseId: jsonResponse.id || `resp_${Date.now()}`
+          }
+        };
+      } else {
+        const message = { role: "assistant", content: textContent || (hasToolCalls ? null : "") };
+        if (hasToolCalls) message.tool_calls = toolCalls;
+        const responseDone = jsonResponse.status === "completed" || jsonResponse.status === "done";
+        const finishReason = hasToolCalls ? "tool_calls" : (responseDone ? "stop" : (jsonResponse.status || "stop"));
+        finalResp = {
+          id: jsonResponse.id || `chatcmpl-${Date.now()}`,
+          object: "chat.completion",
+          created: jsonResponse.created_at || Math.floor(Date.now() / 1000),
+          model: jsonResponse.model || model,
+          choices: [{ index: 0, message, finish_reason: finishReason }],
+          usage: { prompt_tokens: inTokens, completion_tokens: outTokens, total_tokens: inTokens + outTokens }
+        };
+      }
+
+      return { success: true, response: new Response(JSON.stringify(finalResp), { headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" } }) };
+    } catch (err) {
+      console.error("[ChatCore] Responses API SSE→JSON failed:", err);
+      return createErrorResult(HTTP_STATUS.BAD_GATEWAY, "Failed to convert streaming response to JSON");
+    }
+  }
+
+  // Standard Chat Completions SSE path
+  try {
+    const sseText = await providerResponse.text();
+    const parsed = parseSSEToOpenAIResponse(sseText, model);
+    if (!parsed) return createErrorResult(HTTP_STATUS.BAD_GATEWAY, "Invalid SSE response for non-streaming request");
+
+    if (onRequestSuccess) await onRequestSuccess();
+
+    const usage = parsed.usage || {};
+    appendLog({ tokens: usage, status: "200 OK" });
+    saveUsageStats({ provider, model, tokens: usage, connectionId, apiKey, endpoint: clientRawRequest?.endpoint, silent: true });
+    if (log?.line) log.line(reqTag, "📊", formatDoneLine({ usage, latency: { total: Date.now() - requestStartTime } }));
+
+    const totalLatency = Date.now() - requestStartTime;
+    saveRequestDetail(buildRequestDetail({
+      ...ctx,
+      latency: { ttft: totalLatency, total: totalLatency },
+      tokens: usage,
+      response: {
+        content: parsed.choices?.[0]?.message?.content || null,
+        thinking: parsed.choices?.[0]?.message?.reasoning_content || null,
+        finish_reason: parsed.choices?.[0]?.finish_reason || "unknown"
+      },
+      status: "success"
+    }, { endpoint: clientRawRequest?.endpoint || null })).catch(() => {});
+
+    // Strip reasoning_content only when content is non-empty.
+    // When content is empty (e.g. thinking models that used all tokens for reasoning),
+    // reasoning_content is the only useful output and must be preserved.
+    // Previously this was unconditional, which broke Qwen3.5, Claude extended thinking, etc.
+    if (parsed?.choices) {
+      for (const choice of parsed.choices) {
+        if (choice?.message?.reasoning_content && choice.message.content) {
+          delete choice.message.reasoning_content;
+        }
+      }
+    }
+
+    return { success: true, response: new Response(JSON.stringify(parsed), { headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" } }) };
+  } catch (err) {
+    console.error("[ChatCore] Chat Completions SSE→JSON failed:", err);
+    return createErrorResult(HTTP_STATUS.BAD_GATEWAY, "Failed to convert streaming response to JSON");
+  }
+}
diff --git a/open-sse/handlers/chatCore/streamingHandler.js b/open-sse/handlers/chatCore/streamingHandler.js
new file mode 100644
index 0000000..1fb8a32
--- /dev/null
+++ b/open-sse/handlers/chatCore/streamingHandler.js
@@ -0,0 +1,144 @@
+import { FORMATS } from "../../translator/formats.js";
+import { needsTranslation } from "../../translator/index.js";
+import { createSSETransformStreamWithLogger, createPassthroughStreamWithLogger } from "../../utils/stream.js";
+import { pipeWithDisconnect } from "../../utils/streamHandler.js";
+import { PROVIDERS } from "../../config/providers.js";
+import { STREAM_STALL_TIMEOUT_MS } from "../../config/runtimeConfig.js";
+import { buildAbortedResponsesTerminalBytes } from "../../utils/responsesStreamHelpers.js";
+import { buildRequestDetail, extractRequestConfig, saveUsageStats, formatDoneLine } from "./requestDetail.js";
+import { saveRequestDetail } from "@/lib/usageDb.js";
+import { SSE_HEADERS_CORS as SSE_HEADERS } from "../../utils/sseConstants.js";
+
+// Codex returns Responses API SSE → which client format to translate INTO, by request sourceFormat.
+// Gemini-family all map to ANTIGRAVITY decoder; unknown sources fall back to OPENAI.
+const CODEX_SOURCE_TO_TARGET = {
+  [FORMATS.OPENAI_RESPONSES]: FORMATS.OPENAI_RESPONSES,
+  [FORMATS.CLAUDE]: FORMATS.CLAUDE,
+  [FORMATS.ANTIGRAVITY]: FORMATS.ANTIGRAVITY,
+  [FORMATS.GEMINI]: FORMATS.ANTIGRAVITY,
+  [FORMATS.GEMINI_CLI]: FORMATS.ANTIGRAVITY,
+};
+
+/**
+ * Determine which SSE transform stream to use based on provider/format.
+ */
+function buildTransformStream({ provider, sourceFormat, targetFormat, userAgent, reqLogger, toolNameMap, model, connectionId, body, onStreamComplete, apiKey }) {
+  const isDroidCLI = userAgent?.toLowerCase().includes("droid") || userAgent?.toLowerCase().includes("codex-cli");
+  // Responses-API providers (e.g. codex) emit Responses SSE → translate into client format
+  const isResponsesProvider = PROVIDERS[provider]?.format === FORMATS.OPENAI_RESPONSES;
+  const needsCodexTranslation = isResponsesProvider && targetFormat === FORMATS.OPENAI_RESPONSES && !isDroidCLI;
+
+  if (needsCodexTranslation) {
+    const codexTarget = CODEX_SOURCE_TO_TARGET[sourceFormat] || FORMATS.OPENAI;
+    return createSSETransformStreamWithLogger(FORMATS.OPENAI_RESPONSES, codexTarget, provider, reqLogger, toolNameMap, model, connectionId, body, onStreamComplete, apiKey);
+  }
+
+  if (needsTranslation(targetFormat, sourceFormat)) {
+    return createSSETransformStreamWithLogger(targetFormat, sourceFormat, provider, reqLogger, toolNameMap, model, connectionId, body, onStreamComplete, apiKey);
+  }
+
+  return createPassthroughStreamWithLogger(provider, reqLogger, model, connectionId, body, onStreamComplete, apiKey);
+}
+
+/**
+ * Handle streaming response — pipe provider SSE through transform stream to client.
+ */
+export async function handleStreamingResponse({ providerResponse, provider, model, sourceFormat, targetFormat, userAgent, body, stream, translatedBody, finalBody, requestStartTime, connectionId, apiKey, clientRawRequest, onRequestSuccess, reqLogger, toolNameMap, streamController, onStreamComplete, streamDetailId, pxpipe, reqTag, log }) {
+  if (onRequestSuccess) {
+    Promise.resolve()
+      .then(onRequestSuccess)
+      .catch(err => {
+        console.error("[ChatCore] onRequestSuccess failed:", err?.message || err);
+      });
+  }
+
+  // When upstream returns HTML/text instead of SSE (e.g. Cloudflare 5xx error
+  // page), piping it through the SSE transform stream causes Next.js
+  // "failed to pipe response" and crashes the chat router. Read the body,
+  // pull a short human-readable message from the <title>, sanitize it, and
+  // return a clean JSON error instead. The message is stripped of HTML tags
+  // and clamped so untrusted upstream text never reaches the client verbatim
+  // (the UI may render error.message as HTML).
+  const upstreamContentType = (providerResponse.headers.get('content-type') || '').toLowerCase();
+  if (upstreamContentType && !upstreamContentType.includes('text/event-stream') && !upstreamContentType.includes('application/json')) {
+    const bodyText = await providerResponse.text().catch(() => '');
+    const titleMatch = bodyText.match(/<title>([^<]+)<\/title>/i);
+    const sanitizedTitle = (titleMatch?.[1] || '').replace(/<[^>]*>/g, '').replace(/[\r\n]+/g, ' ').trim().slice(0, 160);
+    const shortMsg = sanitizedTitle
+      || (bodyText.length < 200 ? bodyText.replace(/<[^>]*>/g, '').trim().slice(0, 160) : `Upstream returned non-SSE response (${upstreamContentType})`);
+    const status = providerResponse.status || 502;
+    if (log?.errorLine) log.errorLine(reqTag, "✗", `BLOCKED ${status} · ${provider}/${model} · non-SSE (${upstreamContentType})\n    ${shortMsg}`);
+    else console.warn(`[STREAM] ${provider} | ${model} | blocked pipe: ${shortMsg} [${status}]`);
+    streamController?.handleError?.(new Error(`upstream non-SSE: ${status}`));
+    return {
+      success: false,
+      response: new Response(JSON.stringify({ error: { message: `[${status}]: ${shortMsg}` } }), {
+        status,
+        headers: { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' },
+      }),
+    };
+  }
+
+  const transformStream = buildTransformStream({ provider, sourceFormat, targetFormat, userAgent, reqLogger, toolNameMap, model, connectionId, body, onStreamComplete, apiKey });
+
+  // Responses passthrough: synthesize response.failed + [DONE] if the stream aborts/stalls before a terminal event
+  const isResponsesPassthrough = sourceFormat === FORMATS.OPENAI_RESPONSES && targetFormat === FORMATS.OPENAI_RESPONSES;
+  const onAbortTerminal = isResponsesPassthrough ? buildAbortedResponsesTerminalBytes : null;
+  const stallTimeoutMs = PROVIDERS[provider]?.stallTimeoutMs || STREAM_STALL_TIMEOUT_MS;
+  const transformedBody = pipeWithDisconnect(providerResponse, transformStream, streamController, onAbortTerminal, stallTimeoutMs);
+
+  saveRequestDetail(buildRequestDetail({
+    provider, model, connectionId,
+    latency: { ttft: 0, total: Date.now() - requestStartTime },
+    tokens: { prompt_tokens: 0, completion_tokens: 0 },
+    request: extractRequestConfig(body, stream),
+    providerRequest: finalBody || translatedBody || null,
+    providerResponse: "[Streaming - raw response not captured]",
+    response: { content: "[Streaming in progress...]", thinking: null, type: "streaming" },
+    pxpipe,
+    status: "success"
+  }, { id: streamDetailId })).catch(err => {
+    console.error("[RequestDetail] Failed to save streaming request:", err.message);
+  });
+
+  return {
+    success: true,
+    response: new Response(transformedBody, { headers: SSE_HEADERS })
+  };
+}
+
+/**
+ * Build onStreamComplete callback for streaming usage tracking.
+ */
+export function buildOnStreamComplete({ provider, model, connectionId, apiKey, requestStartTime, body, stream, finalBody, translatedBody, clientRawRequest, pxpipe, reqTag, log }) {
+  const streamDetailId = `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+
+  const onStreamComplete = (contentObj, usage, ttftAt) => {
+    const latency = {
+      ttft: ttftAt ? ttftAt - requestStartTime : Date.now() - requestStartTime,
+      total: Date.now() - requestStartTime
+    };
+    const safeContent = contentObj?.content || "[Empty streaming response]";
+    const safeThinking = contentObj?.thinking || null;
+
+    saveRequestDetail(buildRequestDetail({
+      provider, model, connectionId,
+      latency,
+      tokens: usage || { prompt_tokens: 0, completion_tokens: 0 },
+      request: extractRequestConfig(body, stream),
+      providerRequest: finalBody || translatedBody || null,
+      providerResponse: safeContent,
+      response: { content: safeContent, thinking: safeThinking, type: "streaming" },
+      pxpipe,
+      status: "success"
+    }, { id: streamDetailId })).catch(err => {
+      console.error("[RequestDetail] Failed to update streaming content:", err.message);
+    });
+
+    // Persist stream usage to DB (no console line; the "📊 done" line below is authoritative)
+    saveUsageStats({ provider, model, tokens: usage, connectionId, apiKey, endpoint: clientRawRequest?.endpoint, label: "STREAM USAGE", silent: true });
+    if (log?.line) log.line(reqTag, "📊", formatDoneLine({ usage, latency }));
+  };
+
+  return { onStreamComplete, streamDetailId };
+}
diff --git a/open-sse/handlers/embeddingProviders/_base.js b/open-sse/handlers/embeddingProviders/_base.js
new file mode 100644
index 0000000..2a8f399
--- /dev/null
+++ b/open-sse/handlers/embeddingProviders/_base.js
@@ -0,0 +1,4 @@
+// Shared embedding helpers
+export function bearerAuth(creds) {
+  return { "Authorization": `Bearer ${creds.apiKey || creds.accessToken}` };
+}
diff --git a/open-sse/handlers/embeddingProviders/gemini.js b/open-sse/handlers/embeddingProviders/gemini.js
new file mode 100644
index 0000000..885ee30
--- /dev/null
+++ b/open-sse/handlers/embeddingProviders/gemini.js
@@ -0,0 +1,54 @@
+// Google Gemini embeddings — embedContent / batchEmbedContents
+const BASE = "https://generativelanguage.googleapis.com/v1beta";
+
+function modelPath(model) {
+  return model.startsWith("models/") ? model : `models/${model}`;
+}
+
+export default {
+  buildUrl: (model, creds, { input } = {}) => {
+    const apiKey = creds.apiKey || creds.accessToken;
+    const path = modelPath(model);
+    const op = Array.isArray(input) ? "batchEmbedContents" : "embedContent";
+    return `${BASE}/${path}:${op}?key=${encodeURIComponent(apiKey)}`;
+  },
+  buildHeaders: () => ({ "Content-Type": "application/json" }),
+  buildBody: (model, { input, dimensions }) => {
+    const m = modelPath(model);
+    const outputDimensionality = Number(dimensions);
+    const hasOutputDimensionality = Number.isFinite(outputDimensionality) && outputDimensionality > 0;
+    if (Array.isArray(input)) {
+      return {
+        requests: input.map((text) => ({
+          model: m,
+          content: { parts: [{ text: String(text) }] },
+          ...(hasOutputDimensionality ? { outputDimensionality } : {}),
+        })),
+      };
+    }
+    return {
+      model: m,
+      content: { parts: [{ text: String(input) }] },
+      ...(hasOutputDimensionality ? { outputDimensionality } : {}),
+    };
+  },
+  normalize: (responseBody, model) => {
+    if (responseBody.object === "list" && Array.isArray(responseBody.data)) return responseBody;
+    let items = [];
+    if (Array.isArray(responseBody.embeddings)) {
+      items = responseBody.embeddings.map((emb, idx) => ({
+        object: "embedding",
+        index: idx,
+        embedding: emb.values || [],
+      }));
+    } else if (responseBody.embedding?.values) {
+      items = [{ object: "embedding", index: 0, embedding: responseBody.embedding.values }];
+    }
+    return {
+      object: "list",
+      data: items,
+      model,
+      usage: { prompt_tokens: 0, total_tokens: 0 },
+    };
+  },
+};
diff --git a/open-sse/handlers/embeddingProviders/index.js b/open-sse/handlers/embeddingProviders/index.js
new file mode 100644
index 0000000..62e5277
--- /dev/null
+++ b/open-sse/handlers/embeddingProviders/index.js
@@ -0,0 +1,24 @@
+// Embeddings provider adapter registry
+import createOpenAIEmbeddingAdapter from "./openai.js";
+import gemini from "./gemini.js";
+import openaiCompatNode from "./openaiCompatNode.js";
+
+const OPENAI_COMPAT_PROVIDERS = [
+  "openai", "openrouter", "mistral", "voyage-ai", "fireworks",
+  "together", "nebius", "github", "nvidia", "jina-ai",
+  "vercel-ai-gateway",
+];
+
+const ADAPTERS = {
+  ...Object.fromEntries(OPENAI_COMPAT_PROVIDERS.map((id) => [id, createOpenAIEmbeddingAdapter(id)])),
+  gemini,
+  google_ai_studio: gemini,
+};
+
+export function getEmbeddingAdapter(provider) {
+  if (ADAPTERS[provider]) return ADAPTERS[provider];
+  if (provider?.startsWith?.("openai-compatible-") || provider?.startsWith?.("custom-embedding-")) {
+    return openaiCompatNode;
+  }
+  return null;
+}
diff --git a/open-sse/handlers/embeddingProviders/openai.js b/open-sse/handlers/embeddingProviders/openai.js
new file mode 100644
index 0000000..7d61c7e
--- /dev/null
+++ b/open-sse/handlers/embeddingProviders/openai.js
@@ -0,0 +1,31 @@
+// OpenAI-compatible embeddings adapter (most providers)
+import { bearerAuth } from "./_base.js";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+// media-only providers without a registry file keep URL here; rest derive from registry media.embeddingConfig.baseUrl
+const ENDPOINTS = {
+  "jina-ai": "https://api.jina.ai/v1/embeddings",
+};
+
+const embedCfg = (id) => PROVIDER_MEDIA[id]?.embeddingConfig || {};
+const embedUrl = (id) => embedCfg(id).baseUrl || ENDPOINTS[id];
+
+export default function createOpenAIEmbeddingAdapter(providerId) {
+  const cfg = embedCfg(providerId);
+  return {
+    buildUrl: () => embedUrl(providerId),
+    buildHeaders: (creds) => {
+      return { "Content-Type": "application/json", ...bearerAuth(creds), ...(cfg.headers || {}) };
+    },
+    buildBody: (model, { input, encoding_format, dimensions }) => {
+      const body = { model, input };
+      if (encoding_format) body.encoding_format = encoding_format;
+      if (dimensions != null && dimensions !== "") {
+        const dim = Number(dimensions);
+        if (Number.isFinite(dim) && dim > 0) body.dimensions = dim;
+      }
+      return body;
+    },
+    normalize: (responseBody) => responseBody,
+  };
+}
diff --git a/open-sse/handlers/embeddingProviders/openaiCompatNode.js b/open-sse/handlers/embeddingProviders/openaiCompatNode.js
new file mode 100644
index 0000000..6581b45
--- /dev/null
+++ b/open-sse/handlers/embeddingProviders/openaiCompatNode.js
@@ -0,0 +1,13 @@
+// Custom node providers (openai-compatible-* / custom-embedding-*) — baseUrl from credentials
+import createOpenAIEmbeddingAdapter from "./openai.js";
+
+const baseAdapter = createOpenAIEmbeddingAdapter("openai");
+
+export default {
+  ...baseAdapter,
+  buildUrl: (_model, creds) => {
+    const rawBaseUrl = creds?.providerSpecificData?.baseUrl || "https://api.openai.com/v1";
+    const baseUrl = rawBaseUrl.replace(/\/$/, "").replace(/\/embeddings$/, "");
+    return `${baseUrl}/embeddings`;
+  },
+};
diff --git a/open-sse/handlers/embeddingsCore.js b/open-sse/handlers/embeddingsCore.js
new file mode 100644
index 0000000..5a4c92b
--- /dev/null
+++ b/open-sse/handlers/embeddingsCore.js
@@ -0,0 +1,126 @@
+import { createErrorResult, parseUpstreamError, formatProviderError } from "../utils/error.js";
+import { HTTP_STATUS } from "../config/runtimeConfig.js";
+import { getExecutor } from "../executors/index.js";
+import { refreshWithRetry } from "../services/tokenRefresh.js";
+import { getEmbeddingAdapter } from "./embeddingProviders/index.js";
+
+/**
+ * Core embeddings handler — orchestrator only. Provider-specific URL/headers/body/normalize
+ * live in `./embeddingProviders/{id}.js`.
+ *
+ * @returns {Promise<{ success: boolean, response: Response, status?: number, error?: string }>}
+ */
+export async function handleEmbeddingsCore({
+  body,
+  modelInfo,
+  credentials,
+  log,
+  onCredentialsRefreshed,
+  onRequestSuccess,
+}) {
+  const { provider, model } = modelInfo;
+
+  // Validate input
+  const input = body.input;
+  if (!input) {
+    return createErrorResult(HTTP_STATUS.BAD_REQUEST, "Missing required field: input");
+  }
+  if (typeof input !== "string" && !Array.isArray(input)) {
+    return createErrorResult(HTTP_STATUS.BAD_REQUEST, "input must be a string or array of strings");
+  }
+
+  const adapter = getEmbeddingAdapter(provider);
+  if (!adapter) {
+    return createErrorResult(
+      HTTP_STATUS.BAD_REQUEST,
+      `Provider '${provider}' does not support embeddings.`
+    );
+  }
+
+  const ctx = { input };
+  const url = adapter.buildUrl(model, credentials, ctx);
+  const headers = adapter.buildHeaders(credentials, ctx);
+  const requestBody = adapter.buildBody(model, {
+    input,
+    encoding_format: body.encoding_format || "float",
+    dimensions: body.dimensions,
+  });
+
+  log?.debug?.("EMBEDDINGS", `${provider.toUpperCase()} | ${model} | input_type=${Array.isArray(input) ? `array[${input.length}]` : "string"}`);
+
+  let providerResponse;
+  try {
+    providerResponse = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(requestBody),
+    });
+  } catch (error) {
+    const errMsg = formatProviderError(error, provider, model, HTTP_STATUS.BAD_GATEWAY);
+    log?.debug?.("EMBEDDINGS", `Fetch error: ${errMsg}`);
+    return createErrorResult(HTTP_STATUS.BAD_GATEWAY, errMsg);
+  }
+
+  // Handle 401/403 — try token refresh (skip for noAuth providers)
+  const executor = getExecutor(provider);
+  if (
+    !executor?.noAuth &&
+    (providerResponse.status === HTTP_STATUS.UNAUTHORIZED ||
+      providerResponse.status === HTTP_STATUS.FORBIDDEN)
+  ) {
+    const newCredentials = await refreshWithRetry(
+      () => executor.refreshCredentials(credentials, log),
+      3,
+      log
+    );
+
+    if (newCredentials?.accessToken || newCredentials?.apiKey) {
+      log?.info?.("TOKEN", `${provider.toUpperCase()} | refreshed for embeddings`);
+      Object.assign(credentials, newCredentials);
+      if (onCredentialsRefreshed) await onCredentialsRefreshed(newCredentials);
+
+      try {
+        const retryHeaders = adapter.buildHeaders(credentials, ctx);
+        const retryUrl = adapter.buildUrl(model, credentials, ctx);
+        providerResponse = await fetch(retryUrl, {
+          method: "POST",
+          headers: retryHeaders,
+          body: JSON.stringify(requestBody),
+        });
+      } catch {
+        log?.warn?.("TOKEN", `${provider.toUpperCase()} | retry after refresh failed`);
+      }
+    } else {
+      log?.warn?.("TOKEN", `${provider.toUpperCase()} | refresh failed`);
+    }
+  }
+
+  if (!providerResponse.ok) {
+    const { statusCode, message } = await parseUpstreamError(providerResponse);
+    const errMsg = formatProviderError(new Error(message), provider, model, statusCode);
+    log?.debug?.("EMBEDDINGS", `Provider error: ${errMsg}`);
+    return createErrorResult(statusCode, errMsg);
+  }
+
+  let responseBody;
+  try {
+    responseBody = await providerResponse.json();
+  } catch {
+    return createErrorResult(HTTP_STATUS.BAD_GATEWAY, `Invalid JSON response from ${provider}`);
+  }
+
+  if (onRequestSuccess) await onRequestSuccess();
+
+  const normalized = adapter.normalize(responseBody, model);
+  log?.debug?.("EMBEDDINGS", `Success | usage=${JSON.stringify(normalized.usage || {})}`);
+
+  return {
+    success: true,
+    response: new Response(JSON.stringify(normalized), {
+      headers: {
+        "Content-Type": "application/json",
+        "Access-Control-Allow-Origin": "*",
+      },
+    }),
+  };
+}
diff --git a/open-sse/handlers/fetch/index.js b/open-sse/handlers/fetch/index.js
new file mode 100644
index 0000000..da1c230
--- /dev/null
+++ b/open-sse/handlers/fetch/index.js
@@ -0,0 +1,237 @@
+// Web Fetch handler — dispatches to firecrawl, jina-reader, tavily, exa
+// Returns normalized shape across all providers
+
+const DEFAULT_TIMEOUT_MS = 15000;
+const DEFAULT_FORMAT = "markdown";
+
+/**
+ * @typedef {Object} FetchResult
+ * @property {boolean} success
+ * @property {number} [status]
+ * @property {string} [error]
+ * @property {Object} [data]
+ */
+
+/**
+ * Fetch with timeout abort.
+ * @param {string} url
+ * @param {RequestInit} init
+ * @param {number} timeoutMs
+ */
+// Strip non-ASCII chars from header values (HTTP headers must be ByteString).
+function sanitizeHeaders(headers) {
+  if (!headers) return headers;
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    out[k] = typeof v === "string" ? v.replace(/[^\x00-\xFF]/g, "").trim() : v;
+  }
+  return out;
+}
+
+async function tryFetch(url, init, timeoutMs) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { ...init, headers: sanitizeHeaders(init.headers), signal: ctrl.signal });
+    return { ok: true, res };
+  } catch (err) {
+    const isAbort = err?.name === "AbortError";
+    return { ok: false, timeout: isAbort, error: err?.message || String(err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function truncate(text, max) {
+  if (!text || typeof text !== "string") return text || "";
+  if (!max || max <= 0) return text;
+  return text.length > max ? text.slice(0, max) : text;
+}
+
+function parseJinaTitle(text) {
+  const m = String(text || "").match(/^\s*#\s+(.+)$/m);
+  return m ? m[1].trim() : null;
+}
+
+function buildData({ provider, url, title, format, text, costUsd, responseMs, upstreamMs }) {
+  return {
+    provider,
+    url,
+    title: title || null,
+    content: { format, text: text || "", length: (text || "").length },
+    metadata: { author: null, published_at: null, language: null },
+    usage: { fetch_cost_usd: costUsd ?? null },
+    metrics: { response_time_ms: responseMs, upstream_latency_ms: upstreamMs }
+  };
+}
+
+async function readJsonOrText(res) {
+  const ct = res.headers.get("content-type") || "";
+  if (ct.includes("application/json")) {
+    try { return { json: await res.json() }; } catch { return { text: "" }; }
+  }
+  return { text: await res.text() };
+}
+
+/**
+ * Main handler.
+ * @param {Object} params
+ * @param {string} params.url
+ * @param {string} [params.format]
+ * @param {number} [params.maxCharacters]
+ * @param {string} params.provider
+ * @param {Object} [params.providerConfig]
+ * @param {Object} [params.credentials]
+ * @param {Function} [params.log]
+ * @returns {Promise<FetchResult>}
+ */
+export async function handleFetchCore({ url, format, maxCharacters, provider, providerConfig, credentials, log }) {
+  if (!url || typeof url !== "string") {
+    return { success: false, status: 400, error: "url is required" };
+  }
+  if (!provider) {
+    return { success: false, status: 400, error: "provider is required" };
+  }
+
+  const fmt = format || DEFAULT_FORMAT;
+  const timeoutMs = providerConfig?.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const apiKey = credentials?.apiKey || credentials?.key || credentials?.token || "";
+  const costPerQuery = providerConfig?.costPerQuery ?? null;
+  const startedAt = Date.now();
+
+  try {
+    if (provider === "firecrawl") {
+      return await runFirecrawl({ url, fmt, timeoutMs, apiKey, maxCharacters, costPerQuery, startedAt });
+    }
+    if (provider === "jina-reader") {
+      return await runJina({ url, fmt, timeoutMs, apiKey, maxCharacters, costPerQuery, startedAt });
+    }
+    if (provider === "tavily") {
+      return await runTavily({ url, fmt, timeoutMs, apiKey, maxCharacters, costPerQuery, startedAt });
+    }
+    if (provider === "exa") {
+      return await runExa({ url, fmt, timeoutMs, apiKey, maxCharacters, costPerQuery, startedAt });
+    }
+    return { success: false, status: 400, error: `Unsupported provider: ${provider}` };
+  } catch (err) {
+    log?.("fetch handler error:", err?.message || err);
+    return { success: false, status: 502, error: err?.message || "Internal fetch error" };
+  }
+}
+
+async function runFirecrawl({ url, fmt, timeoutMs, apiKey, maxCharacters, costPerQuery, startedAt }) {
+  const upstreamStart = Date.now();
+  const r = await tryFetch("https://api.firecrawl.dev/v1/scrape", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {})
+    },
+    body: JSON.stringify({ url, formats: [fmt] })
+  }, timeoutMs);
+
+  if (!r.ok) {
+    return { success: false, status: r.timeout ? 504 : 502, error: r.error };
+  }
+  const upstreamMs = Date.now() - upstreamStart;
+  const { json } = await readJsonOrText(r.res);
+  if (!r.res.ok) {
+    return { success: false, status: r.res.status, error: json?.error || `Firecrawl error: ${r.res.status}` };
+  }
+  const d = json?.data || {};
+  const text = truncate(d.markdown || d.html || d.text || "", maxCharacters);
+  const title = d.metadata?.title || null;
+  return {
+    success: true,
+    data: buildData({
+      provider: "firecrawl", url, title, format: fmt, text,
+      costUsd: costPerQuery, responseMs: Date.now() - startedAt, upstreamMs
+    })
+  };
+}
+
+async function runJina({ url, fmt, timeoutMs, apiKey, maxCharacters, costPerQuery, startedAt }) {
+  const target = `https://r.jina.ai/${encodeURIComponent(url)}`;
+  const upstreamStart = Date.now();
+  const r = await tryFetch(target, {
+    method: "GET",
+    headers: apiKey ? { authorization: `Bearer ${apiKey}` } : {}
+  }, timeoutMs);
+
+  if (!r.ok) {
+    return { success: false, status: r.timeout ? 504 : 502, error: r.error };
+  }
+  const upstreamMs = Date.now() - upstreamStart;
+  const body = await r.res.text();
+  if (!r.res.ok) {
+    return { success: false, status: r.res.status, error: body?.slice(0, 500) || `Jina error: ${r.res.status}` };
+  }
+  const text = truncate(body, maxCharacters);
+  return {
+    success: true,
+    data: buildData({
+      provider: "jina-reader", url, title: parseJinaTitle(body), format: fmt, text,
+      costUsd: costPerQuery, responseMs: Date.now() - startedAt, upstreamMs
+    })
+  };
+}
+
+async function runTavily({ url, fmt, timeoutMs, apiKey, maxCharacters, costPerQuery, startedAt }) {
+  const upstreamStart = Date.now();
+  const r = await tryFetch("https://api.tavily.com/extract", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {})
+    },
+    body: JSON.stringify({ urls: [url], extract_depth: "basic" })
+  }, timeoutMs);
+
+  if (!r.ok) {
+    return { success: false, status: r.timeout ? 504 : 502, error: r.error };
+  }
+  const upstreamMs = Date.now() - upstreamStart;
+  const { json } = await readJsonOrText(r.res);
+  if (!r.res.ok) {
+    return { success: false, status: r.res.status, error: json?.error || `Tavily error: ${r.res.status}` };
+  }
+  const first = json?.results?.[0] || {};
+  const text = truncate(first.raw_content || "", maxCharacters);
+  return {
+    success: true,
+    data: buildData({
+      provider: "tavily", url, title: null, format: fmt, text,
+      costUsd: costPerQuery, responseMs: Date.now() - startedAt, upstreamMs
+    })
+  };
+}
+
+async function runExa({ url, fmt, timeoutMs, apiKey, maxCharacters, costPerQuery, startedAt }) {
+  const upstreamStart = Date.now();
+  const r = await tryFetch("https://api.exa.ai/contents", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...(apiKey ? { "x-api-key": apiKey } : {})
+    },
+    body: JSON.stringify({ ids: [url], text: true })
+  }, timeoutMs);
+
+  if (!r.ok) {
+    return { success: false, status: r.timeout ? 504 : 502, error: r.error };
+  }
+  const upstreamMs = Date.now() - upstreamStart;
+  const { json } = await readJsonOrText(r.res);
+  if (!r.res.ok) {
+    return { success: false, status: r.res.status, error: json?.error || `Exa error: ${r.res.status}` };
+  }
+  const first = json?.results?.[0] || {};
+  const text = truncate(first.text || "", maxCharacters);
+  return {
+    success: true,
+    data: buildData({
+      provider: "exa", url, title: first.title || null, format: fmt, text,
+      costUsd: costPerQuery, responseMs: Date.now() - startedAt, upstreamMs
+    })
+  };
+}
diff --git a/open-sse/handlers/imageGenerationCore.js b/open-sse/handlers/imageGenerationCore.js
new file mode 100644
index 0000000..d2d0eba
--- /dev/null
+++ b/open-sse/handlers/imageGenerationCore.js
@@ -0,0 +1,230 @@
+import { createErrorResult, parseUpstreamError, formatProviderError } from "../utils/error.js";
+import { HTTP_STATUS } from "../config/runtimeConfig.js";
+import { refreshWithRetry } from "../services/tokenRefresh.js";
+import { getExecutor } from "../executors/index.js";
+import { getImageAdapter } from "./imageProviders/index.js";
+import { urlToBase64 } from "./imageProviders/_base.js";
+
+function serializeRequestBody(requestBody) {
+  if (typeof FormData !== "undefined" && requestBody instanceof FormData) return requestBody;
+  if (typeof requestBody === "string") return requestBody;
+  return JSON.stringify(requestBody);
+}
+
+/**
+ * Core image generation handler — orchestrator only.
+ * Provider-specific URL/headers/body/parse/normalize live in `./imageProviders/{id}.js`.
+ *
+ * @param {object} options
+ * @param {object} options.body - Request body { model, prompt, n, size, ... }
+ * @param {object} options.modelInfo - { provider, model }
+ * @param {object} options.credentials - Provider credentials
+ * @param {object} [options.log] - Logger
+ * @param {boolean} [options.streamToClient] - Pipe SSE to client (codex)
+ * @param {boolean} [options.binaryOutput] - Return raw image bytes
+ * @param {function} [options.onCredentialsRefreshed]
+ * @param {function} [options.onRequestSuccess]
+ * @returns {Promise<{ success: boolean, response: Response, status?: number, error?: string }>}
+ */
+export async function handleImageGenerationCore({
+  body,
+  modelInfo,
+  credentials,
+  log,
+  streamToClient = false,
+  binaryOutput = false,
+  onCredentialsRefreshed,
+  onRequestSuccess,
+}) {
+  const { provider, model } = modelInfo;
+
+  if (!body.prompt) {
+    return createErrorResult(HTTP_STATUS.BAD_REQUEST, "Missing required field: prompt");
+  }
+
+  const adapter = getImageAdapter(provider);
+  if (!adapter) {
+    return createErrorResult(
+      HTTP_STATUS.BAD_REQUEST,
+      `Provider '${provider}' does not support image generation`
+    );
+  }
+
+  // Executor-delegating adapters: skip manual URL/headers/body, use the proven executor flow
+  if (adapter.useExecutor && adapter.executeViaExecutor) {
+    try {
+      log?.debug?.("IMAGE", `${provider.toUpperCase()} | ${model} | prompt="${body.prompt.slice(0, 50)}..." (executor)`);
+      const responseBody = await adapter.executeViaExecutor(model, body, credentials, log);
+      if (onRequestSuccess) await onRequestSuccess();
+      const normalized = adapter.normalize(responseBody, body.prompt);
+      const finalBody = (normalized.created && Array.isArray(normalized.data)) ? normalized : responseBody;
+
+      if (binaryOutput) {
+        const first = finalBody.data?.[0];
+        let b64 = first?.b64_json;
+        if (!b64 && first?.url) {
+          try { b64 = await urlToBase64(first.url); } catch {}
+        }
+        if (b64) {
+          const buf = Buffer.from(b64, "base64");
+          const fmt = (body.output_format || "png").toLowerCase();
+          const mime = fmt === "jpeg" || fmt === "jpg" ? "image/jpeg" : fmt === "webp" ? "image/webp" : "image/png";
+          return {
+            success: true,
+            response: new Response(buf, {
+              headers: { "Content-Type": mime, "Content-Disposition": `inline; filename="image.${fmt === "jpeg" ? "jpg" : fmt}"`, "Access-Control-Allow-Origin": "*" },
+            }),
+          };
+        }
+      }
+
+      return {
+        success: true,
+        response: new Response(JSON.stringify(finalBody), {
+          headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
+        }),
+      };
+    } catch (error) {
+      const errMsg = formatProviderError(error, provider, model, HTTP_STATUS.BAD_GATEWAY);
+      log?.debug?.("IMAGE", `Executor error: ${errMsg}`);
+      return createErrorResult(HTTP_STATUS.BAD_GATEWAY, errMsg);
+    }
+  }
+
+  let url;
+  let headers;
+  let requestBody;
+
+  try {
+    url = adapter.buildUrl(model, credentials);
+    requestBody = await adapter.buildBody(model, body);
+    headers = adapter.buildHeaders(credentials, requestBody, model, body);
+  } catch (error) {
+    return createErrorResult(HTTP_STATUS.BAD_REQUEST, error.message || `Invalid ${provider} image request`);
+  }
+
+  log?.debug?.("IMAGE", `${provider.toUpperCase()} | ${model} | prompt="${body.prompt.slice(0, 50)}..."`);
+
+  let providerResponse;
+  try {
+    providerResponse = await fetch(url, {
+      method: "POST",
+      headers,
+      body: serializeRequestBody(requestBody),
+    });
+  } catch (error) {
+    const errMsg = formatProviderError(error, provider, model, HTTP_STATUS.BAD_GATEWAY);
+    log?.debug?.("IMAGE", `Fetch error: ${errMsg}`);
+    return createErrorResult(HTTP_STATUS.BAD_GATEWAY, errMsg);
+  }
+
+  // Handle 401/403 — try token refresh (skipped for noAuth providers)
+  const executor = getExecutor(provider);
+  if (
+    !executor?.noAuth &&
+    !adapter.noAuth &&
+    (providerResponse.status === HTTP_STATUS.UNAUTHORIZED ||
+      providerResponse.status === HTTP_STATUS.FORBIDDEN)
+  ) {
+    const newCredentials = await refreshWithRetry(
+      () => executor.refreshCredentials(credentials, log),
+      3,
+      log
+    );
+
+    if (newCredentials?.accessToken || newCredentials?.apiKey) {
+      log?.info?.("TOKEN", `${provider.toUpperCase()} | refreshed for image generation`);
+      Object.assign(credentials, newCredentials);
+      if (onCredentialsRefreshed) await onCredentialsRefreshed(newCredentials);
+
+      try {
+        const retryBody = await adapter.buildBody(model, body);
+        const retryHeaders = adapter.buildHeaders(credentials, retryBody, model, body);
+        const retryUrl = adapter.buildUrl(model, credentials);
+        providerResponse = await fetch(retryUrl, {
+          method: "POST",
+          headers: retryHeaders,
+          body: serializeRequestBody(retryBody),
+        });
+      } catch {
+        log?.warn?.("TOKEN", `${provider.toUpperCase()} | retry after refresh failed`);
+      }
+    } else {
+      log?.warn?.("TOKEN", `${provider.toUpperCase()} | refresh failed`);
+    }
+  }
+
+  if (!providerResponse.ok) {
+    const { statusCode, message } = await parseUpstreamError(providerResponse);
+    const errMsg = formatProviderError(new Error(message), provider, model, statusCode);
+    log?.debug?.("IMAGE", `Provider error: ${errMsg}`);
+    return createErrorResult(statusCode, errMsg);
+  }
+
+  // Parse provider response — adapter may override (codex SSE / async polling / binary)
+  let parsed;
+  try {
+    if (adapter.parseResponse) {
+      parsed = await adapter.parseResponse(providerResponse, {
+        headers,
+        log,
+        streamToClient,
+        onRequestSuccess,
+        url,
+        requestBody,
+        model,
+        body,
+      });
+      // Codex streaming case: returns an SSE Response directly
+      if (parsed?.sseResponse) {
+        return { success: true, response: parsed.sseResponse };
+      }
+    } else {
+      parsed = await providerResponse.json();
+    }
+  } catch (parseError) {
+    return createErrorResult(HTTP_STATUS.BAD_GATEWAY, parseError.message || `Invalid response from ${provider}`);
+  }
+
+  if (onRequestSuccess) await onRequestSuccess();
+
+  // Normalize → OpenAI-compatible shape
+  const normalized = adapter.normalize(parsed, body.prompt);
+
+  // Already in OpenAI shape? skip re-normalize
+  const finalBody = (normalized.created && Array.isArray(normalized.data)) ? normalized : parsed;
+
+  // Binary output: decode first b64_json (or fetch url) into raw bytes
+  if (binaryOutput) {
+    const first = finalBody.data?.[0];
+    let b64 = first?.b64_json;
+    if (!b64 && first?.url) {
+      try { b64 = await urlToBase64(first.url); } catch {}
+    }
+    if (b64) {
+      const buf = Buffer.from(b64, "base64");
+      const fmt = (body.output_format || "png").toLowerCase();
+      const mime = fmt === "jpeg" || fmt === "jpg" ? "image/jpeg" : fmt === "webp" ? "image/webp" : "image/png";
+      return {
+        success: true,
+        response: new Response(buf, {
+          headers: {
+            "Content-Type": mime,
+            "Content-Disposition": `inline; filename="image.${fmt === "jpeg" ? "jpg" : fmt}"`,
+            "Access-Control-Allow-Origin": "*",
+          },
+        }),
+      };
+    }
+  }
+
+  return {
+    success: true,
+    response: new Response(JSON.stringify(finalBody), {
+      headers: {
+        "Content-Type": "application/json",
+        "Access-Control-Allow-Origin": "*",
+      },
+    }),
+  };
+}
diff --git a/open-sse/handlers/imageProviders/_base.js b/open-sse/handlers/imageProviders/_base.js
new file mode 100644
index 0000000..f8902de
--- /dev/null
+++ b/open-sse/handlers/imageProviders/_base.js
@@ -0,0 +1,31 @@
+// Shared helpers for image provider adapters
+
+export const POLL_INTERVAL_MS = 1500;
+export const POLL_TIMEOUT_MS = 120000;
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Map OpenAI size to provider-specific aspect ratio
+export function sizeToAspectRatio(size) {
+  if (!size || typeof size !== "string") return "1:1";
+  const map = {
+    "1024x1024": "1:1",
+    "1024x1792": "9:16",
+    "1792x1024": "16:9",
+    "1024x1536": "2:3",
+    "1536x1024": "3:2",
+  };
+  return map[size] || "1:1";
+}
+
+// Fetch URL → base64 (for providers returning image URLs)
+export async function urlToBase64(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Failed to fetch image: ${res.status}`);
+  const buf = await res.arrayBuffer();
+  return Buffer.from(buf).toString("base64");
+}
+
+export function nowSec() {
+  return Math.floor(Date.now() / 1000);
+}
diff --git a/open-sse/handlers/imageProviders/antigravity.js b/open-sse/handlers/imageProviders/antigravity.js
new file mode 100644
index 0000000..a1f9051
--- /dev/null
+++ b/open-sse/handlers/imageProviders/antigravity.js
@@ -0,0 +1,73 @@
+// Antigravity image adapter - delegates to the executor for correct request
+// envelope (project, model, requestType, sessionId) and auth headers.
+import { nowSec } from "./_base.js";
+import { getExecutor } from "../../executors/index.js";
+
+// Convert image input (data URI or raw base64) to Gemini inlineData part
+function resolveImageInput(input) {
+  if (!input || typeof input !== "string") return null;
+  // data:image/png;base64,... format
+  const dataUriMatch = input.match(/^data:(image\/[^;]+);base64,(.+)$/);
+  if (dataUriMatch) {
+    return { inlineData: { mimeType: dataUriMatch[1], data: dataUriMatch[2] } };
+  }
+  // Raw base64 string (assume PNG)
+  if (/^[A-Za-z0-9+/]/.test(input) && input.length > 100 && !input.startsWith("http")) {
+    return { inlineData: { mimeType: "image/png", data: input } };
+  }
+  return null;
+}
+
+export default {
+  // Delegate to executor instead of building URL/headers/body manually
+  useExecutor: true,
+
+  // Stubs - required by imageGenerationCore interface but unused with useExecutor
+  buildUrl: () => "",
+  buildHeaders: () => ({}),
+  buildBody: () => ({}),
+
+  async executeViaExecutor(model, body, credentials, log) {
+    const executor = getExecutor("antigravity");
+    if (!executor) throw new Error("Antigravity executor not found");
+
+    // Build parts: text prompt + optional input image for editing
+    const parts = [{ text: body.prompt }];
+    const imageInput = body.image || (Array.isArray(body.images) && body.images[0]);
+    if (imageInput) {
+      const inlineData = resolveImageInput(imageInput);
+      if (inlineData) parts.unshift(inlineData);
+    }
+
+    const chatBody = {
+      contents: [{ role: "user", parts }],
+    };
+
+    const result = await executor.execute({
+      model,
+      body: chatBody,
+      stream: false,
+      credentials,
+      log,
+    });
+
+    if (!result.response.ok) {
+      const text = await result.response.text();
+      throw new Error(text || `HTTP ${result.response.status}`);
+    }
+
+    return result.response.json();
+  },
+
+  normalize: (responseBody, prompt) => {
+    const candidates = responseBody.candidates || responseBody.response?.candidates || [];
+    const parts = candidates[0]?.content?.parts || [];
+    const images = parts.filter((p) => p.inlineData?.data).map((p) => ({
+      b64_json: p.inlineData.data,
+    }));
+    return {
+      created: nowSec(),
+      data: images.length > 0 ? images : [{ b64_json: "", revised_prompt: prompt }],
+    };
+  },
+};
\ No newline at end of file
diff --git a/open-sse/handlers/imageProviders/blackForestLabs.js b/open-sse/handlers/imageProviders/blackForestLabs.js
new file mode 100644
index 0000000..051e35a
--- /dev/null
+++ b/open-sse/handlers/imageProviders/blackForestLabs.js
@@ -0,0 +1,44 @@
+// Black Forest Labs (FLUX) — async submit + polling_url
+import { sleep, nowSec, POLL_INTERVAL_MS, POLL_TIMEOUT_MS } from "./_base.js";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const BASE_URL = PROVIDER_MEDIA["black-forest-labs"]?.imageConfig?.baseUrl;
+
+export default {
+  async: true,
+  buildUrl: (model) => `${BASE_URL}/${model}`,
+  buildHeaders: (creds) => {
+    const key = creds?.apiKey || creds?.accessToken;
+    return { "Content-Type": "application/json", "x-key": key };
+  },
+  buildBody: (_model, body) => {
+    const req = { prompt: body.prompt };
+    if (body.size) {
+      const [w, h] = body.size.split("x").map(Number);
+      if (w) req.width = w;
+      if (h) req.height = h;
+    }
+    if (body.image) req.image_prompt = body.image;
+    return req;
+  },
+  async parseResponse(response, { headers }) {
+    const data = await response.json();
+    const pollingUrl = data.polling_url;
+    if (!pollingUrl) throw new Error("BFL: no polling_url returned");
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await sleep(POLL_INTERVAL_MS);
+      const r = await fetch(pollingUrl, { headers: { "x-key": headers["x-key"], "Accept": "application/json" } });
+      if (!r.ok) throw new Error(`BFL status ${r.status}`);
+      const s = await r.json();
+      if (s.status === "Ready") return s;
+      if (s.status === "Error" || s.status === "Failed") throw new Error(s.error || "BFL generation failed");
+    }
+    throw new Error("BFL polling timeout");
+  },
+  normalize: (responseBody) => {
+    const sample = responseBody.result?.sample;
+    if (sample) return { created: nowSec(), data: [{ url: sample }] };
+    return { created: nowSec(), data: [] };
+  },
+};
diff --git a/open-sse/handlers/imageProviders/cloudflareAi.js b/open-sse/handlers/imageProviders/cloudflareAi.js
new file mode 100644
index 0000000..d7ecef8
--- /dev/null
+++ b/open-sse/handlers/imageProviders/cloudflareAi.js
@@ -0,0 +1,179 @@
+import { nowSec, urlToBase64 } from "./_base.js";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const BASE_URL = PROVIDER_MEDIA["cloudflare-ai"]?.imageConfig?.baseUrl;
+
+const MULTIPART_MODELS = new Set([
+  "@cf/black-forest-labs/flux-2-dev",
+  "@cf/black-forest-labs/flux-2-klein-4b",
+  "@cf/black-forest-labs/flux-2-klein-9b",
+]);
+
+const OPTIONAL_FIELDS = [
+  "negative_prompt",
+  "guidance",
+  "seed",
+  "num_steps",
+  "steps",
+  "strength",
+];
+
+function sizeToDimensions(size) {
+  const match = /^(\d+)x(\d+)$/.exec(String(size || ""));
+  if (!match) return {};
+  return {
+    width: Number(match[1]),
+    height: Number(match[2]),
+  };
+}
+
+function getDimensions(body) {
+  return {
+    ...sizeToDimensions(body.size),
+    ...(Number.isFinite(Number(body.width)) ? { width: Number(body.width) } : {}),
+    ...(Number.isFinite(Number(body.height)) ? { height: Number(body.height) } : {}),
+  };
+}
+
+async function resolveImageInput(value) {
+  if (Array.isArray(value)) {
+    return { bytes: value, b64: Buffer.from(value).toString("base64") };
+  }
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/^https?:\/\//i.test(trimmed)) {
+    const b64 = await urlToBase64(trimmed);
+    return { bytes: base64ToBytes(b64), b64 };
+  }
+  const match = /^data:image\/[^;]+;base64,(.+)$/i.exec(trimmed);
+  const b64 = match ? match[1] : trimmed;
+  return { bytes: base64ToBytes(b64), b64 };
+}
+
+function base64ToBytes(value) {
+  try {
+    return Array.from(Buffer.from(value, "base64"));
+  } catch {
+    return value;
+  }
+}
+
+function addOptionalFields(target, body, append) {
+  for (const key of OPTIONAL_FIELDS) {
+    const value = body[key];
+    if (value === undefined || value === null || value === "") continue;
+    append(target, key, value);
+  }
+}
+
+async function buildJsonBody(body) {
+  const req = { prompt: body.prompt, ...getDimensions(body) };
+
+  addOptionalFields(req, body, (target, key, value) => {
+    target[key] = value;
+  });
+
+  const imageData = await resolveImageInput(body.image);
+  if (imageData) {
+    req.image_b64 = imageData.b64;
+    req.image = imageData.bytes;
+  }
+
+  const maskData = await resolveImageInput(body.mask_image || body.maskImage || body.mask);
+  if (maskData) {
+    req.mask_b64 = maskData.b64;
+    req.mask = maskData.bytes;
+    req.mask_image = maskData.bytes;
+  }
+
+  return req;
+}
+
+function buildMultipartBody(body) {
+  const form = new FormData();
+  form.append("prompt", body.prompt);
+
+  const dimensions = getDimensions(body);
+  for (const [key, value] of Object.entries(dimensions)) {
+    form.append(key, String(value));
+  }
+
+  addOptionalFields(form, body, (target, key, value) => {
+    target.append(key, String(value));
+  });
+
+  return form;
+}
+
+function imageItemFromString(value) {
+  if (typeof value !== "string" || !value) return null;
+  if (/^data:image\/[^;]+;base64,/i.test(value)) {
+    return { b64_json: value.replace(/^data:image\/[^;]+;base64,/i, "") };
+  }
+  if (/^https?:\/\//i.test(value)) return { url: value };
+  return { b64_json: value };
+}
+
+function normalizeCloudflareResponse(responseBody) {
+  if (responseBody?.created && Array.isArray(responseBody?.data)) return responseBody;
+
+  const result = responseBody?.result ?? responseBody;
+  const queuedResponse = Array.isArray(result?.responses)
+    ? result.responses.find((item) => item?.success !== false)?.result
+    : null;
+  if (queuedResponse) return normalizeCloudflareResponse(queuedResponse);
+
+  const image =
+    (typeof result === "string" ? result : null) ||
+    result?.image ||
+    result?.data?.[0]?.b64_json ||
+    result?.data?.[0]?.url;
+
+  const item = imageItemFromString(image);
+  return {
+    created: nowSec(),
+    data: item ? [item] : [],
+  };
+}
+
+export default {
+  buildUrl: (model, creds) => {
+    const accountId = creds?.providerSpecificData?.accountId;
+    if (!accountId) throw new Error("cloudflare-ai requires accountId in providerSpecificData");
+    return `${BASE_URL}/${accountId}/ai/run/${model}`;
+  },
+
+  buildHeaders: (creds, requestBody) => {
+    const headers = {};
+    const isMultipart = typeof FormData !== "undefined" && requestBody instanceof FormData;
+    if (!isMultipart) {
+      headers["Content-Type"] = "application/json";
+    }
+    const key = creds?.apiKey || creds?.accessToken;
+    if (key) headers.Authorization = `Bearer ${key}`;
+    return headers;
+  },
+
+  buildBody: async (model, body) => (
+    MULTIPART_MODELS.has(model)
+      ? buildMultipartBody(body)
+      : await buildJsonBody(body)
+  ),
+
+  async parseResponse(response) {
+    const contentType = (response.headers.get("Content-Type") || "").toLowerCase();
+    if (contentType.startsWith("image/")) {
+      const buf = await response.arrayBuffer();
+      return {
+        created: nowSec(),
+        data: [{ b64_json: Buffer.from(buf).toString("base64") }],
+      };
+    }
+
+    const json = await response.json();
+    return normalizeCloudflareResponse(json);
+  },
+
+  normalize: normalizeCloudflareResponse,
+};
diff --git a/open-sse/handlers/imageProviders/codex.js b/open-sse/handlers/imageProviders/codex.js
new file mode 100644
index 0000000..218302a
--- /dev/null
+++ b/open-sse/handlers/imageProviders/codex.js
@@ -0,0 +1,199 @@
+// Codex (ChatGPT Plus/Pro) image generation via Responses API + SSE
+import { randomUUID } from "node:crypto";
+import { nowSec } from "./_base.js";
+import { PROVIDERS } from "../../config/providers.js";
+
+const CODEX_RESPONSES_URL = PROVIDERS["codex"].baseUrl;
+const CODEX_USER_AGENT = "codex_cli_rs/0.136.0";
+const CODEX_VERSION = "0.136.0";
+const CODEX_ORIGINATOR = "codex_cli_rs";
+const CODEX_MODEL_SUFFIX = "-image";
+const CODEX_REF_DETAIL = "high";
+
+function decodeAccountId(idToken) {
+  try {
+    const parts = String(idToken || "").split(".");
+    if (parts.length !== 3) return null;
+    const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const pad = (4 - (b64.length % 4)) % 4;
+    const payload = JSON.parse(Buffer.from(b64 + "=".repeat(pad), "base64").toString("utf8"));
+    return payload?.["https://api.openai.com/auth"]?.chatgpt_account_id || null;
+  } catch {
+    return null;
+  }
+}
+
+function stripImageSuffix(model) {
+  return model.endsWith(CODEX_MODEL_SUFFIX) ? model.slice(0, -CODEX_MODEL_SUFFIX.length) : model;
+}
+
+function toDataUrl(input) {
+  if (!input || typeof input !== "string") return null;
+  if (/^data:image\//i.test(input) || /^https?:\/\//i.test(input)) return input;
+  return `data:image/png;base64,${input}`;
+}
+
+function buildContent(prompt, refs, detail = CODEX_REF_DETAIL) {
+  const content = [];
+  refs.forEach((url, index) => {
+    content.push({ type: "input_text", text: `<image name=image${index + 1}>` });
+    content.push({ type: "input_image", image_url: url, detail });
+    content.push({ type: "input_text", text: "</image>" });
+  });
+  content.push({ type: "input_text", text: prompt });
+  return content;
+}
+
+// Parse Codex SSE stream → final base64 image. Optional callbacks for client streaming.
+async function parseStream(response, log, callbacks = {}) {
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let imageB64 = null;
+  let lastEvent = null;
+  let bytesReceived = 0;
+  let lastProgressLogMs = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytesReceived += value?.byteLength || 0;
+    buffer += decoder.decode(value, { stream: true });
+
+    let sepIdx;
+    while ((sepIdx = buffer.indexOf("\n\n")) !== -1) {
+      const block = buffer.slice(0, sepIdx);
+      buffer = buffer.slice(sepIdx + 2);
+
+      const lines = block.split("\n");
+      let eventName = null;
+      let dataStr = "";
+      for (const line of lines) {
+        if (line.startsWith("event:")) eventName = line.slice(6).trim();
+        else if (line.startsWith("data:")) dataStr += line.slice(5).trim();
+      }
+      if (!eventName) continue;
+      if (eventName !== lastEvent) {
+        log?.info?.("IMAGE", `codex progress: ${eventName}`);
+        lastEvent = eventName;
+      }
+
+      const now = Date.now();
+      if (callbacks.onProgress && now - lastProgressLogMs > 200) {
+        lastProgressLogMs = now;
+        callbacks.onProgress({ stage: eventName, bytesReceived });
+      }
+
+      if (eventName === "response.image_generation_call.partial_image" && dataStr) {
+        try {
+          const data = JSON.parse(dataStr);
+          if (callbacks.onPartialImage && data?.partial_image_b64) {
+            callbacks.onPartialImage({ b64_json: data.partial_image_b64, index: data.partial_image_index });
+          }
+        } catch {}
+      }
+
+      if (eventName === "response.output_item.done" && dataStr) {
+        try {
+          const data = JSON.parse(dataStr);
+          const item = data?.item;
+          if (item?.type === "image_generation_call" && item.result) {
+            imageB64 = item.result;
+          }
+        } catch {}
+      }
+    }
+  }
+  return imageB64;
+}
+
+// SSE Response that pipes codex progress + partial + done events to client
+function buildSseResponse(providerResponse, log, onSuccess) {
+  const stream = new ReadableStream({
+    async start(controller) {
+      const enc = new TextEncoder();
+      const send = (event, data) => {
+        controller.enqueue(enc.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+      };
+      try {
+        const b64 = await parseStream(providerResponse, log, {
+          onProgress: (info) => send("progress", info),
+          onPartialImage: (info) => send("partial_image", info),
+        });
+        if (!b64) {
+          send("error", { message: "Codex did not return an image. Account may not be entitled (Plus/Pro required)." });
+        } else {
+          if (onSuccess) await onSuccess();
+          send("done", { created: nowSec(), data: [{ b64_json: b64 }] });
+        }
+      } catch (err) {
+        send("error", { message: err?.message || "Stream failed" });
+      } finally {
+        controller.close();
+      }
+    },
+  });
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no",
+      "Access-Control-Allow-Origin": "*",
+    },
+  });
+}
+
+export default {
+  stream: true,
+  buildUrl: () => CODEX_RESPONSES_URL,
+  buildHeaders: (creds) => {
+    const accountId = creds?.providerSpecificData?.chatgptAccountId || decodeAccountId(creds?.idToken);
+    return {
+      "accept": "text/event-stream, application/json",
+      "authorization": `Bearer ${creds?.accessToken || ""}`,
+      "chatgpt-account-id": accountId || "",
+      "content-type": "application/json",
+      "originator": CODEX_ORIGINATOR,
+      "session_id": randomUUID(),
+      "user-agent": CODEX_USER_AGENT,
+      "version": CODEX_VERSION,
+      "x-client-request-id": randomUUID(),
+    };
+  },
+  buildBody: (model, body) => {
+    const refs = [];
+    if (Array.isArray(body.images)) body.images.forEach((i) => { const u = toDataUrl(i); if (u) refs.push(u); });
+    const single = toDataUrl(body.image);
+    if (single) refs.push(single);
+    const detail = body.image_detail || CODEX_REF_DETAIL;
+    const imgTool = { type: "image_generation", output_format: (body.output_format || "png").toLowerCase() };
+    if (body.size && body.size !== "") imgTool.size = body.size;
+    if (body.quality && body.quality !== "") imgTool.quality = body.quality;
+    if (body.background && body.background !== "") imgTool.background = body.background;
+    return {
+      model: stripImageSuffix(model),
+      instructions: "",
+      input: [{ type: "message", role: "user", content: buildContent(body.prompt, refs, detail) }],
+      tools: [imgTool],
+      tool_choice: "auto",
+      parallel_tool_calls: false,
+      prompt_cache_key: randomUUID(),
+      stream: true,
+      store: false,
+      reasoning: null,
+    };
+  },
+  // Custom: codex parses SSE → either pipe to client or collect b64
+  async parseResponse(response, { log, streamToClient, onRequestSuccess }) {
+    if (streamToClient) {
+      return { sseResponse: buildSseResponse(response, log, onRequestSuccess) };
+    }
+    const b64 = await parseStream(response, log);
+    if (!b64) {
+      throw new Error("Codex did not return an image. Account may not be entitled (Plus/Pro required).");
+    }
+    return { created: nowSec(), data: [{ b64_json: b64 }] };
+  },
+  normalize: (responseBody) => responseBody,
+};
diff --git a/open-sse/handlers/imageProviders/comfyui.js b/open-sse/handlers/imageProviders/comfyui.js
new file mode 100644
index 0000000..767d7de
--- /dev/null
+++ b/open-sse/handlers/imageProviders/comfyui.js
@@ -0,0 +1,12 @@
+// ComfyUI — local, noAuth (placeholder; full graph workflow not implemented)
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const BASE_URL = PROVIDER_MEDIA["comfyui"]?.imageConfig?.baseUrl;
+
+export default {
+  noAuth: true,
+  buildUrl: () => BASE_URL,
+  buildHeaders: () => ({ "Content-Type": "application/json" }),
+  buildBody: (_model, body) => ({ prompt: body.prompt }),
+  normalize: (responseBody) => responseBody,
+};
diff --git a/open-sse/handlers/imageProviders/falAi.js b/open-sse/handlers/imageProviders/falAi.js
new file mode 100644
index 0000000..874c635
--- /dev/null
+++ b/open-sse/handlers/imageProviders/falAi.js
@@ -0,0 +1,42 @@
+// Fal.ai — async submit + queue polling
+import { sleep, nowSec, sizeToAspectRatio, POLL_INTERVAL_MS, POLL_TIMEOUT_MS } from "./_base.js";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const BASE_URL = PROVIDER_MEDIA["fal-ai"]?.imageConfig?.baseUrl;
+
+export default {
+  async: true,
+  buildUrl: (model) => `${BASE_URL}/${model}`,
+  buildHeaders: (creds) => {
+    const key = creds?.apiKey || creds?.accessToken;
+    return { "Content-Type": "application/json", "Authorization": `Key ${key}` };
+  },
+  buildBody: (_model, body) => {
+    const req = { prompt: body.prompt, num_images: body.n || 1 };
+    if (body.size) req.image_size = sizeToAspectRatio(body.size);
+    if (body.image) req.image_url = body.image;
+    return req;
+  },
+  async parseResponse(response, { headers }) {
+    const { status_url, response_url } = await response.json();
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await sleep(POLL_INTERVAL_MS);
+      const r = await fetch(status_url, { headers });
+      if (!r.ok) throw new Error(`Fal status ${r.status}`);
+      const s = await r.json();
+      if (s.status === "COMPLETED") {
+        const fr = await fetch(response_url, { headers });
+        return await fr.json();
+      }
+      if (s.status === "FAILED") throw new Error(s.error || "Fal generation failed");
+    }
+    throw new Error("Fal polling timeout");
+  },
+  normalize: (responseBody) => {
+    const images = Array.isArray(responseBody.images)
+      ? responseBody.images
+      : (responseBody.image ? [responseBody.image] : []);
+    return { created: nowSec(), data: images.map((img) => ({ url: img.url || img })) };
+  },
+};
diff --git a/open-sse/handlers/imageProviders/gemini.js b/open-sse/handlers/imageProviders/gemini.js
new file mode 100644
index 0000000..f1f6a99
--- /dev/null
+++ b/open-sse/handlers/imageProviders/gemini.js
@@ -0,0 +1,26 @@
+// Google Gemini adapter (Nano Banana models)
+import { nowSec } from "./_base.js";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const BASE_URL = PROVIDER_MEDIA["gemini"]?.imageConfig?.baseUrl;
+
+export default {
+  buildUrl: (model, creds) => {
+    const apiKey = creds?.apiKey || creds?.accessToken;
+    const modelId = model.replace(/^models\//, "");
+    return `${BASE_URL}/${modelId}:generateContent?key=${encodeURIComponent(apiKey)}`;
+  },
+  buildHeaders: () => ({ "Content-Type": "application/json" }),
+  buildBody: (_model, body) => ({
+    contents: [{ parts: [{ text: body.prompt }] }],
+    generationConfig: { responseModalities: ["TEXT", "IMAGE"] },
+  }),
+  normalize: (responseBody, prompt) => {
+    const parts = responseBody.candidates?.[0]?.content?.parts || [];
+    const images = parts.filter((p) => p.inlineData?.data).map((p) => ({ b64_json: p.inlineData.data }));
+    return {
+      created: nowSec(),
+      data: images.length > 0 ? images : [{ b64_json: "", revised_prompt: prompt }],
+    };
+  },
+};
diff --git a/open-sse/handlers/imageProviders/huggingface.js b/open-sse/handlers/imageProviders/huggingface.js
new file mode 100644
index 0000000..2093d9c
--- /dev/null
+++ b/open-sse/handlers/imageProviders/huggingface.js
@@ -0,0 +1,23 @@
+// HuggingFace Inference API — returns binary image
+import { nowSec } from "./_base.js";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const BASE_URL = PROVIDER_MEDIA["huggingface"]?.imageConfig?.baseUrl;
+
+export default {
+  buildUrl: (model) => `${BASE_URL}/${model}`,
+  buildHeaders: (creds) => {
+    const headers = { "Content-Type": "application/json" };
+    const key = creds?.apiKey || creds?.accessToken;
+    if (key) headers["Authorization"] = `Bearer ${key}`;
+    return headers;
+  },
+  buildBody: (_model, body) => ({ inputs: body.prompt }),
+  // HF returns raw image bytes — convert to b64_json
+  async parseResponse(response) {
+    const buf = await response.arrayBuffer();
+    const base64 = Buffer.from(buf).toString("base64");
+    return { created: nowSec(), data: [{ b64_json: base64 }] };
+  },
+  normalize: (responseBody) => responseBody,
+};
diff --git a/open-sse/handlers/imageProviders/index.js b/open-sse/handlers/imageProviders/index.js
new file mode 100644
index 0000000..520c3d6
--- /dev/null
+++ b/open-sse/handlers/imageProviders/index.js
@@ -0,0 +1,43 @@
+// Image provider adapter registry
+import createOpenAIAdapter from "./openai.js";
+import gemini from "./gemini.js";
+import codex from "./codex.js";
+import sdwebui from "./sdwebui.js";
+import comfyui from "./comfyui.js";
+import huggingface from "./huggingface.js";
+import nanobanana from "./nanobanana.js";
+import falAi from "./falAi.js";
+import stabilityAi from "./stabilityAi.js";
+import blackForestLabs from "./blackForestLabs.js";
+import runwayml from "./runwayml.js";
+import cloudflareAi from "./cloudflareAi.js";
+import antigravity from "./antigravity.js";
+
+const ADAPTERS = {
+  openai: createOpenAIAdapter("openai"),
+  minimax: createOpenAIAdapter("minimax"),
+  openrouter: createOpenAIAdapter("openrouter"),
+  recraft: createOpenAIAdapter("recraft"),
+  "vercel-ai-gateway": createOpenAIAdapter("vercel-ai-gateway"),
+  xai: createOpenAIAdapter("xai"),
+  gemini,
+  codex,
+  sdwebui,
+  comfyui,
+  huggingface,
+  nanobanana,
+  antigravity,
+  "fal-ai": falAi,
+  "stability-ai": stabilityAi,
+  "black-forest-labs": blackForestLabs,
+  runwayml,
+  "cloudflare-ai": cloudflareAi,
+};
+
+export function getImageAdapter(provider) {
+  return ADAPTERS[provider] || null;
+}
+
+export function isImageProvider(provider) {
+  return provider in ADAPTERS;
+}
diff --git a/open-sse/handlers/imageProviders/nanobanana.js b/open-sse/handlers/imageProviders/nanobanana.js
new file mode 100644
index 0000000..4685fde
--- /dev/null
+++ b/open-sse/handlers/imageProviders/nanobanana.js
@@ -0,0 +1,60 @@
+// NanoBanana API — async submit + poll record-info
+import { sleep, nowSec, sizeToAspectRatio, POLL_INTERVAL_MS, POLL_TIMEOUT_MS } from "./_base.js";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const IMG_CFG = PROVIDER_MEDIA["nanobanana"]?.imageConfig || {};
+const SUBMIT_URL = IMG_CFG.baseUrl;
+const POLL_BASE = IMG_CFG.pollUrl;
+
+export default {
+  async: true,
+  buildUrl: () => SUBMIT_URL,
+  buildHeaders: (creds) => {
+    const headers = { "Content-Type": "application/json" };
+    const key = creds?.apiKey || creds?.accessToken;
+    if (key) headers["Authorization"] = `Bearer ${key}`;
+    return headers;
+  },
+  buildBody: (_model, body) => {
+    const ratio = sizeToAspectRatio(body.size);
+    const isEdit = !!(body.image || (Array.isArray(body.images) && body.images.length));
+    const req = {
+      prompt: body.prompt,
+      type: isEdit ? "IMAGETOIAMGE" : "TEXTTOIAMGE",
+      numImages: body.n || 1,
+      image_size: ratio,
+      // API requires callBackUrl; we poll instead so a dummy URL is fine.
+      callBackUrl: "https://localhost/callback",
+    };
+    if (isEdit) {
+      const urls = Array.isArray(body.images) ? body.images.filter(Boolean) : [];
+      if (body.image) urls.push(body.image);
+      req.imageUrls = urls;
+    }
+    return req;
+  },
+  // Async: parse submit → poll until SUCCESS, return raw poll data
+  async parseResponse(response, { headers }) {
+    const submitData = await response.json();
+    if (submitData.code !== 200) throw new Error(submitData.msg || "NanoBanana submit failed");
+    const taskId = submitData.data?.taskId;
+    if (!taskId) throw new Error("NanoBanana: no taskId returned");
+    const pollUrl = `${POLL_BASE}?taskId=${encodeURIComponent(taskId)}`;
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await sleep(POLL_INTERVAL_MS);
+      const r = await fetch(pollUrl, { headers });
+      if (!r.ok) throw new Error(`NanoBanana status ${r.status}`);
+      const s = await r.json();
+      const flag = s.data?.successFlag;
+      if (flag === 1) return s.data;
+      if (flag === 2 || flag === 3) throw new Error(s.data?.errorMessage || "NanoBanana generation failed");
+    }
+    throw new Error("NanoBanana polling timeout");
+  },
+  normalize: (responseBody, prompt) => {
+    const url = responseBody.response?.resultImageUrl || responseBody.response?.originImageUrl;
+    if (url) return { created: nowSec(), data: [{ url, revised_prompt: prompt }] };
+    return { created: nowSec(), data: [] };
+  },
+};
diff --git a/open-sse/handlers/imageProviders/openai.js b/open-sse/handlers/imageProviders/openai.js
new file mode 100644
index 0000000..5744aa5
--- /dev/null
+++ b/open-sse/handlers/imageProviders/openai.js
@@ -0,0 +1,33 @@
+// OpenAI-compatible adapter (used by openai, minimax, openrouter, recraft)
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const imageCfg = (id) => PROVIDER_MEDIA[id]?.imageConfig || {};
+const imageUrl = (id) => imageCfg(id).baseUrl;
+
+export default function createOpenAIAdapter(providerId) {
+  const cfg = imageCfg(providerId);
+  return {
+    buildUrl: () => imageUrl(providerId),
+    buildHeaders: (creds) => {
+      const headers = { "Content-Type": "application/json", ...(cfg.headers || {}) };
+      const key = creds?.apiKey || creds?.accessToken;
+      if (key) headers["Authorization"] = `Bearer ${key}`;
+      return headers;
+    },
+    buildBody: (model, body) => {
+      const { prompt, n = 1, size = "1024x1024", quality, style, response_format } = body;
+      const full = { model, prompt, n, size };
+      if (quality) full.quality = quality;
+      if (style) full.style = style;
+      if (response_format) full.response_format = response_format;
+      // bodyFields whitelist (e.g. xAI accepts only model/prompt/n/response_format)
+      if (Array.isArray(cfg.bodyFields)) {
+        const req = {};
+        for (const f of cfg.bodyFields) if (full[f] !== undefined) req[f] = full[f];
+        return req;
+      }
+      return full;
+    },
+    normalize: (responseBody) => responseBody,
+  };
+}
diff --git a/open-sse/handlers/imageProviders/runwayml.js b/open-sse/handlers/imageProviders/runwayml.js
new file mode 100644
index 0000000..7eabadb
--- /dev/null
+++ b/open-sse/handlers/imageProviders/runwayml.js
@@ -0,0 +1,48 @@
+// Runway ML — async submit + /tasks/{id} polling
+import { sleep, nowSec, sizeToAspectRatio, POLL_INTERVAL_MS, POLL_TIMEOUT_MS } from "./_base.js";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const BASE_URL = PROVIDER_MEDIA["runwayml"]?.imageConfig?.baseUrl;
+
+export default {
+  async: true,
+  buildUrl: (model) => {
+    // Image models (gen4_image*) → text_to_image; video models → image_to_video
+    return `${BASE_URL}/${model.includes("image") ? "text_to_image" : "image_to_video"}`;
+  },
+  buildHeaders: (creds) => {
+    const key = creds?.apiKey || creds?.accessToken;
+    return {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${key}`,
+      "X-Runway-Version": "2024-11-06",
+    };
+  },
+  buildBody: (model, body) => {
+    const isVideo = !model.includes("image");
+    const ratio = sizeToAspectRatio(body.size);
+    if (isVideo) {
+      return { promptText: body.prompt, model, ratio, duration: 5, ...(body.image ? { promptImage: body.image } : {}) };
+    }
+    return { promptText: body.prompt, model, ratio, ...(body.image ? { referenceImages: [{ uri: body.image }] } : {}) };
+  },
+  async parseResponse(response, { headers }) {
+    const { id } = await response.json();
+    if (!id) throw new Error("Runway: no task id returned");
+    const taskUrl = `${BASE_URL}/tasks/${id}`;
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await sleep(POLL_INTERVAL_MS);
+      const r = await fetch(taskUrl, { headers });
+      if (!r.ok) throw new Error(`Runway status ${r.status}`);
+      const s = await r.json();
+      if (s.status === "SUCCEEDED") return s;
+      if (s.status === "FAILED" || s.status === "CANCELLED") throw new Error(s.failure || "Runway task failed");
+    }
+    throw new Error("Runway polling timeout");
+  },
+  normalize: (responseBody) => {
+    const outputs = Array.isArray(responseBody.output) ? responseBody.output : [];
+    return { created: nowSec(), data: outputs.map((url) => ({ url })) };
+  },
+};
diff --git a/open-sse/handlers/imageProviders/sdwebui.js b/open-sse/handlers/imageProviders/sdwebui.js
new file mode 100644
index 0000000..33e3a69
--- /dev/null
+++ b/open-sse/handlers/imageProviders/sdwebui.js
@@ -0,0 +1,20 @@
+// SD WebUI (AUTOMATIC1111) — local, noAuth
+import { nowSec } from "./_base.js";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const BASE_URL = PROVIDER_MEDIA["sdwebui"]?.imageConfig?.baseUrl;
+
+export default {
+  noAuth: true,
+  buildUrl: () => BASE_URL,
+  buildHeaders: () => ({ "Content-Type": "application/json" }),
+  buildBody: (_model, body) => {
+    const { prompt, n = 1, size = "1024x1024" } = body;
+    const [width, height] = size.split("x").map(Number);
+    return { prompt, width: width || 512, height: height || 512, steps: 20, batch_size: n };
+  },
+  normalize: (responseBody) => {
+    const images = Array.isArray(responseBody.images) ? responseBody.images.map((img) => ({ b64_json: img })) : [];
+    return { created: nowSec(), data: images };
+  },
+};
diff --git a/open-sse/handlers/imageProviders/stabilityAi.js b/open-sse/handlers/imageProviders/stabilityAi.js
new file mode 100644
index 0000000..79f93d5
--- /dev/null
+++ b/open-sse/handlers/imageProviders/stabilityAi.js
@@ -0,0 +1,35 @@
+// Stability AI v2 — sync, returns { image: "<b64>" }
+import { nowSec, sizeToAspectRatio } from "./_base.js";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const BASE_URL = PROVIDER_MEDIA["stability-ai"]?.imageConfig?.baseUrl;
+
+// Map model id → endpoint segment
+function modelToEndpoint(model) {
+  if (model.includes("ultra")) return "ultra";
+  if (model.includes("sd3")) return "sd3";
+  return "core";
+}
+
+export default {
+  buildUrl: (model) => `${BASE_URL}/${modelToEndpoint(model)}`,
+  buildHeaders: (creds) => {
+    const key = creds?.apiKey || creds?.accessToken;
+    return {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${key}`,
+      "Accept": "application/json",
+    };
+  },
+  buildBody: (model, body) => {
+    const req = { prompt: body.prompt, output_format: (body.output_format || "png").toLowerCase() };
+    if (body.size) req.aspect_ratio = sizeToAspectRatio(body.size);
+    if (body.style) req.style_preset = body.style;
+    if (model.includes("sd3")) req.model = model;
+    return req;
+  },
+  normalize: (responseBody) => {
+    if (responseBody.image) return { created: nowSec(), data: [{ b64_json: responseBody.image }] };
+    return { created: nowSec(), data: [] };
+  },
+};
diff --git a/open-sse/handlers/responsesHandler.js b/open-sse/handlers/responsesHandler.js
new file mode 100644
index 0000000..8c17f98
--- /dev/null
+++ b/open-sse/handlers/responsesHandler.js
@@ -0,0 +1,99 @@
+/**
+ * Responses API Handler for Workers
+ * Converts Chat Completions to Codex Responses API format
+ */
+
+import { handleChatCore } from "./chatCore.js";
+import { convertResponsesApiFormat } from "../translator/formats/responsesApi.js";
+import { createResponsesApiTransformStream } from "../transformer/responsesTransformer.js";
+import { convertResponsesStreamToJson } from "../transformer/streamToJsonConverter.js";
+import { SSE_HEADERS_CORS } from "../utils/sseConstants.js";
+
+/**
+ * Handle /v1/responses request
+ * @param {object} options
+ * @param {object} options.body - Request body (Responses API format)
+ * @param {object} options.modelInfo - { provider, model }
+ * @param {object} options.credentials - Provider credentials
+ * @param {object} options.log - Logger instance (optional)
+ * @param {function} options.onCredentialsRefreshed - Callback when credentials are refreshed
+ * @param {function} options.onRequestSuccess - Callback when request succeeds
+ * @param {function} options.onDisconnect - Callback when client disconnects
+ * @param {string} options.connectionId - Connection ID for usage tracking
+ * @returns {Promise<{success: boolean, response?: Response, status?: number, error?: string}>}
+ */
+export async function handleResponsesCore({ body, modelInfo, credentials, log, onCredentialsRefreshed, onRequestSuccess, onDisconnect, connectionId }) {
+  // Convert Responses API format to Chat Completions format
+  const convertedBody = convertResponsesApiFormat(body);
+
+  // Preserve client's stream preference (matches OpenClaw behavior)
+  // Default to false if omitted: Boolean(undefined) = false
+  const clientRequestedStreaming = convertedBody.stream === true;
+  if (convertedBody.stream === undefined) {
+    convertedBody.stream = false;
+  }
+
+  // Call chat core handler — force sourceFormat so streaming path knows this is a Responses API client
+  const result = await handleChatCore({
+    body: convertedBody,
+    modelInfo,
+    credentials,
+    log,
+    onCredentialsRefreshed,
+    onRequestSuccess,
+    onDisconnect,
+    connectionId,
+    sourceFormatOverride: "openai-responses"
+  });
+
+  if (!result.success || !result.response) {
+    return result;
+  }
+
+  const response = result.response;
+  const contentType = response.headers.get("Content-Type") || "";
+
+  // Case 1: Client wants non-streaming, but got SSE (provider forced it, e.g., Codex)
+  if (!clientRequestedStreaming && contentType.includes("text/event-stream")) {
+    try {
+      const jsonResponse = await convertResponsesStreamToJson(response.body);
+
+      return {
+        success: true,
+        response: new Response(JSON.stringify(jsonResponse), {
+          status: 200,
+          headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": "no-cache",
+            "Access-Control-Allow-Origin": "*"
+          }
+        })
+      };
+    } catch (error) {
+      console.error("[Responses API] Stream-to-JSON conversion failed:", error);
+      return {
+        success: false,
+        status: 500,
+        error: "Failed to convert streaming response to JSON"
+      };
+    }
+  }
+
+  // Case 2: Client wants streaming, got SSE - transform it
+  if (clientRequestedStreaming && contentType.includes("text/event-stream")) {
+    const transformStream = createResponsesApiTransformStream(null);
+    const transformedBody = response.body.pipeThrough(transformStream);
+
+    return {
+      success: true,
+      response: new Response(transformedBody, {
+        status: 200,
+        headers: { ...SSE_HEADERS_CORS }
+      })
+    };
+  }
+
+  // Case 3: Non-SSE response (error or non-streaming from provider) - return as-is
+  return result;
+}
+
diff --git a/open-sse/handlers/search/callers.js b/open-sse/handlers/search/callers.js
new file mode 100644
index 0000000..64f045c
--- /dev/null
+++ b/open-sse/handlers/search/callers.js
@@ -0,0 +1,371 @@
+/**
+ * Search Provider Request Builders
+ *
+ * Ported from OmniRoute open-sse/handlers/search.ts (lines 223-610).
+ * Builds HTTP request `{ url, init }` for 10 search providers.
+ *
+ * @typedef {Object} SearchProviderConfig
+ * @property {string} id
+ * @property {string} baseUrl
+ * @property {string} [method]
+ *
+ * @typedef {Object} ContentOptions
+ * @property {boolean} [snippet]
+ * @property {boolean} [full_page]
+ * @property {string}  [format]
+ * @property {number}  [max_characters]
+ *
+ * @typedef {Object} SearchRequestParams
+ * @property {string}   query
+ * @property {string}   searchType
+ * @property {number}   maxResults
+ * @property {string}   [token]
+ * @property {string}   [country]
+ * @property {string}   [language]
+ * @property {string}   [timeRange]
+ * @property {number}   [offset]
+ * @property {string[]} [domainFilter]
+ * @property {ContentOptions}        [contentOptions]
+ * @property {Record<string,unknown>} [providerOptions]
+ * @property {Record<string,unknown>} [providerSpecificData]
+ */
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Split domain filter into includes / excludes (excludes prefixed with "-").
+ * @param {string[]} [domainFilter]
+ * @returns {{includes: string[], excludes: string[]}}
+ */
+export function parseDomainFilter(domainFilter) {
+  if (!domainFilter?.length) return { includes: [], excludes: [] };
+  const includes = domainFilter.filter((d) => !d.startsWith("-"));
+  const excludes = domainFilter.filter((d) => d.startsWith("-")).map((d) => d.slice(1));
+  return { includes, excludes };
+}
+
+/**
+ * Read string setting from providerOptions first, then providerSpecificData.
+ * @param {SearchRequestParams} params
+ * @param {string} key
+ * @returns {string|undefined}
+ */
+export function getProviderSetting(params, key) {
+  const fromOptions = params.providerOptions?.[key];
+  if (typeof fromOptions === "string" && fromOptions.trim().length > 0) {
+    return fromOptions.trim();
+  }
+  const fromProviderData = params.providerSpecificData?.[key];
+  if (typeof fromProviderData === "string" && fromProviderData.trim().length > 0) {
+    return fromProviderData.trim();
+  }
+  return undefined;
+}
+
+/**
+ * Resolve base URL with optional override from providerOptions.baseUrl.
+ * @param {SearchProviderConfig} config
+ * @param {SearchRequestParams} params
+ * @returns {string}
+ */
+export function resolveBaseUrl(config, params) {
+  const override = getProviderSetting(params, "baseUrl");
+  return (override || config.baseUrl).replace(/\/+$/, "");
+}
+
+/**
+ * Convert offset+maxResults to 1-indexed page number.
+ * @param {number|undefined} offset
+ * @param {number} maxResults
+ * @returns {number|undefined}
+ */
+export function toPageNumber(offset, maxResults) {
+  if (typeof offset !== "number" || offset <= 0 || maxResults <= 0) return undefined;
+  return Math.floor(offset / maxResults) + 1;
+}
+
+// ── Provider Request Builders ───────────────────────────────────────────
+
+function buildSerperRequest(config, params) {
+  const endpoint = params.searchType === "news" ? "/news" : "/search";
+  const body = { q: params.query, num: params.maxResults };
+  if (params.country) body.gl = params.country.toLowerCase();
+  if (params.language) body.hl = params.language;
+  return {
+    url: `${resolveBaseUrl(config, params)}${endpoint}`,
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-API-Key": params.token },
+      body: JSON.stringify(body),
+    },
+  };
+}
+
+function buildBraveRequest(config, params) {
+  const endpoint = params.searchType === "news" ? "/news/search" : "/web/search";
+  const qp = new URLSearchParams({ q: params.query, count: String(params.maxResults) });
+  if (params.country) qp.set("country", params.country);
+  if (params.language) qp.set("search_lang", params.language);
+  return {
+    url: `${resolveBaseUrl(config, params)}${endpoint}?${qp}`,
+    init: {
+      method: "GET",
+      headers: { Accept: "application/json", "X-Subscription-Token": params.token },
+    },
+  };
+}
+
+function buildPerplexityRequest(config, params) {
+  const body = { query: params.query, max_results: params.maxResults };
+  if (params.country) body.country = params.country;
+  if (params.language) body.search_language_filter = [params.language];
+  if (params.domainFilter?.length) body.search_domain_filter = params.domainFilter;
+  return {
+    url: resolveBaseUrl(config, params),
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${params.token}` },
+      body: JSON.stringify(body),
+    },
+  };
+}
+
+function buildExaRequest(config, params) {
+  const { includes, excludes } = parseDomainFilter(params.domainFilter);
+  const body = {
+    query: params.query,
+    numResults: params.maxResults,
+    type: "auto",
+    text: true,
+    highlights: true,
+  };
+  if (includes.length) body.includeDomains = includes;
+  if (excludes.length) body.excludeDomains = excludes;
+  if (params.searchType === "news") body.category = "news";
+  return {
+    url: resolveBaseUrl(config, params),
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-api-key": params.token },
+      body: JSON.stringify(body),
+    },
+  };
+}
+
+function buildTavilyRequest(config, params) {
+  const { includes, excludes } = parseDomainFilter(params.domainFilter);
+  const body = {
+    query: params.query,
+    max_results: params.maxResults,
+    topic: params.searchType === "news" ? "news" : "general",
+  };
+  if (includes.length) body.include_domains = includes;
+  if (excludes.length) body.exclude_domains = excludes;
+  if (params.country) body.country = params.country;
+  return {
+    url: resolveBaseUrl(config, params),
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${params.token}` },
+      body: JSON.stringify(body),
+    },
+  };
+}
+
+function buildGooglePseRequest(config, params) {
+  const apiKey = params.token;
+  const cx = getProviderSetting(params, "cx");
+  if (!apiKey || !cx) {
+    throw new Error("Google Programmable Search requires both apiKey and cx");
+  }
+  const qp = new URLSearchParams({
+    key: apiKey,
+    cx,
+    q: params.query,
+    num: String(Math.min(params.maxResults, 10)),
+  });
+  if (params.country) qp.set("gl", params.country.toLowerCase());
+  if (params.language) qp.set("hl", params.language);
+  if (params.timeRange && params.timeRange !== "any") {
+    const dateRestrictMap = { day: "d1", week: "w1", month: "m1", year: "y1" };
+    const dateRestrict = dateRestrictMap[params.timeRange];
+    if (dateRestrict) qp.set("dateRestrict", dateRestrict);
+  }
+  if (typeof params.offset === "number" && params.offset > 0) {
+    qp.set("start", String(Math.min(params.offset + 1, 91)));
+  }
+  return {
+    url: `${resolveBaseUrl(config, params)}?${qp}`,
+    init: {
+      method: "GET",
+      headers: { Accept: "application/json" },
+    },
+  };
+}
+
+function buildLinkupRequest(config, params) {
+  const apiKey = params.token;
+  if (!apiKey) throw new Error("Linkup Search requires an API key");
+
+  const { includes, excludes } = parseDomainFilter(params.domainFilter);
+  const requestedDepth = getProviderSetting(params, "depth");
+  const depth =
+    requestedDepth && ["fast", "standard", "deep"].includes(requestedDepth)
+      ? requestedDepth
+      : "standard";
+
+  const body = {
+    q: params.query,
+    depth,
+    outputType: "searchResults",
+    maxResults: params.maxResults,
+  };
+  if (includes.length) body.includeDomains = includes;
+  if (excludes.length) body.excludeDomains = excludes;
+  if (params.timeRange && params.timeRange !== "any") {
+    const today = new Date();
+    const toDate = today.toISOString().slice(0, 10);
+    const from = new Date(today);
+    if (params.timeRange === "day") from.setUTCDate(from.getUTCDate() - 1);
+    if (params.timeRange === "week") from.setUTCDate(from.getUTCDate() - 7);
+    if (params.timeRange === "month") from.setUTCMonth(from.getUTCMonth() - 1);
+    if (params.timeRange === "year") from.setUTCFullYear(from.getUTCFullYear() - 1);
+    body.fromDate = from.toISOString().slice(0, 10);
+    body.toDate = toDate;
+  }
+
+  return {
+    url: resolveBaseUrl(config, params),
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify(body),
+    },
+  };
+}
+
+function buildSearchApiRequest(config, params) {
+  const apiKey = params.token;
+  if (!apiKey) throw new Error("SearchAPI requires an API key");
+
+  const qp = new URLSearchParams({
+    engine: params.searchType === "news" ? "google_news" : "google",
+    q: params.query,
+    api_key: apiKey,
+  });
+  if (params.country) qp.set("gl", params.country.toLowerCase());
+  if (params.language) qp.set("hl", params.language);
+
+  const page = toPageNumber(params.offset, params.maxResults);
+  if (page) qp.set("page", String(page));
+
+  return {
+    url: `${resolveBaseUrl(config, params)}?${qp}`,
+    init: {
+      method: "GET",
+      headers: { Accept: "application/json" },
+    },
+  };
+}
+
+function buildYouComRequest(config, params) {
+  const apiKey = params.token;
+  if (!apiKey) throw new Error("You.com Search requires an API key");
+
+  const { includes, excludes } = parseDomainFilter(params.domainFilter);
+  const qp = new URLSearchParams({
+    query: params.query,
+    count: String(Math.min(params.maxResults, 100)),
+  });
+
+  if (params.timeRange && params.timeRange !== "any") qp.set("freshness", params.timeRange);
+  if (typeof params.offset === "number" && params.offset > 0 && params.maxResults > 0) {
+    qp.set("offset", String(Math.min(Math.floor(params.offset / params.maxResults), 9)));
+  }
+  if (params.country) qp.set("country", params.country);
+  if (params.language) qp.set("language", params.language);
+  if (includes.length) qp.set("include_domains", includes.join(","));
+  if (excludes.length) qp.set("exclude_domains", excludes.join(","));
+
+  if (params.contentOptions?.full_page) {
+    qp.set("livecrawl", params.searchType === "news" ? "news" : "web");
+    qp.append(
+      "livecrawl_formats",
+      params.contentOptions.format === "markdown" ? "markdown" : "html"
+    );
+  }
+
+  return {
+    url: `${resolveBaseUrl(config, params)}?${qp}`,
+    init: {
+      method: "GET",
+      headers: { Accept: "application/json", "X-API-Key": apiKey },
+    },
+  };
+}
+
+function buildSearxngRequest(config, params) {
+  const baseUrl = resolveBaseUrl(config, params);
+  const url = baseUrl.endsWith("/search") ? baseUrl : `${baseUrl}/search`;
+  const qp = new URLSearchParams({
+    q: params.query,
+    format: "json",
+    categories: params.searchType === "news" ? "news" : "general",
+  });
+  if (params.language) qp.set("language", params.language);
+  if (params.timeRange && params.timeRange !== "any") qp.set("time_range", params.timeRange);
+
+  const page = toPageNumber(params.offset, params.maxResults);
+  if (page) qp.set("pageno", String(page));
+
+  return {
+    url: `${url}?${qp}`,
+    init: {
+      method: "GET",
+      headers: { Accept: "application/json" },
+    },
+  };
+}
+
+// ── Dispatcher ──────────────────────────────────────────────────────────
+
+const BUILDERS = {
+  "serper": buildSerperRequest,
+  "brave-search": buildBraveRequest,
+  "perplexity": buildPerplexityRequest,
+  "exa": buildExaRequest,
+  "tavily": buildTavilyRequest,
+  "google-pse": buildGooglePseRequest,
+  "linkup": buildLinkupRequest,
+  "searchapi": buildSearchApiRequest,
+  "youcom": buildYouComRequest,
+  "searxng": buildSearxngRequest,
+};
+
+/**
+ * Dispatch to the correct provider builder by `provider.id`.
+ * Falls back to generic POST + bearer auth for unknown providers.
+ * @param {SearchProviderConfig} provider
+ * @param {SearchRequestParams} params
+ * @returns {{url: string, init: RequestInit}}
+ */
+export function buildSearchRequest(provider, params) {
+  const builder = BUILDERS[provider.id];
+  if (builder) return builder(provider, params);
+
+  return {
+    url: resolveBaseUrl(provider, params),
+    init: {
+      method: provider.method || "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...(params.token ? { Authorization: `Bearer ${params.token}` } : {}),
+      },
+      body: JSON.stringify({
+        query: params.query,
+        max_results: params.maxResults,
+        search_type: params.searchType,
+      }),
+    },
+  };
+}
diff --git a/open-sse/handlers/search/chatSearch.js b/open-sse/handlers/search/chatSearch.js
new file mode 100644
index 0000000..c5bfb3a
--- /dev/null
+++ b/open-sse/handlers/search/chatSearch.js
@@ -0,0 +1,455 @@
+/**
+ * Wrap chat-completions endpoints (with built-in web search) into the unified
+ * /v1/search response format. Supports gemini, openai, xai, kimi, minimax, perplexity.
+ */
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+// Default search model + endpoint derive from registry searchViaChat (single source)
+const searchModel = (id) => PROVIDER_MEDIA[id]?.searchViaChat?.defaultModel;
+const searchEndpoint = (id, model) =>
+  (PROVIDER_MEDIA[id]?.searchViaChat?.endpoint || "").replace("{model}", model || "");
+
+const REQUEST_TIMEOUT_MS = 15000;
+const DEFAULT_MAX_RESULTS = 10;
+
+/**
+ * Normalize a citation entry into the unified result shape.
+ * @param {{url:string, title?:string, snippet?:string}} c
+ * @param {number} index
+ * @param {string} provider
+ * @param {string} retrievedAt
+ */
+function toResult(c, index, provider, retrievedAt) {
+  return {
+    title: c.title || "",
+    url: c.url,
+    snippet: c.snippet || "",
+    position: index + 1,
+    score: null,
+    published_at: null,
+    favicon_url: null,
+    content: null,
+    metadata: {},
+    citation: { provider, retrieved_at: retrievedAt, rank: index + 1 },
+    provider_raw: null
+  };
+}
+
+/** Coerce a citation that might be a raw URL string or an object. */
+function normalizeCitation(c) {
+  if (!c) return null;
+  if (typeof c === "string") return { url: c };
+  if (typeof c === "object" && c.url) return c;
+  return null;
+}
+
+/**
+ * Provider-specific configuration map. All providers must implement:
+ * { endpoint, defaultModel, buildBody, buildHeaders, extractAnswer }
+ */
+const CHAT_SEARCH_CONFIG = {
+  gemini: {
+    endpoint: (model) => searchEndpoint("gemini", model),
+    buildBody: (query) => ({
+      contents: [{ role: "user", parts: [{ text: query }] }],
+      tools: [{ google_search: {} }]
+    }),
+    buildHeaders: (token) => ({
+      "Content-Type": "application/json",
+      "x-goog-api-key": token
+    }),
+    extractAnswer: (data) => {
+      const candidate = data?.candidates?.[0];
+      const parts = candidate?.content?.parts || [];
+      const text = parts.map((p) => p?.text || "").filter(Boolean).join("");
+      const chunks = candidate?.groundingMetadata?.groundingChunks || [];
+      const citations = chunks
+        .map((ch) => ch?.web)
+        .filter(Boolean)
+        .map((w) => ({ url: w.uri || w.url, title: w.title || "" }))
+        .filter((c) => c.url);
+      const tokens = data?.usageMetadata?.totalTokenCount || 0;
+      return { text, citations, tokens };
+    }
+  },
+
+  openai: {
+    endpoint: () => searchEndpoint("openai"),
+    buildBody: (query, model) => {
+      const body = {
+        model,
+        messages: [{ role: "user", content: query }]
+      };
+      // Non-search-preview models need explicit web_search tool
+      if (!/search/i.test(model)) {
+        body.tools = [{ type: "web_search" }];
+      }
+      return body;
+    },
+    buildHeaders: (token) => ({
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`
+    }),
+    extractAnswer: (data) => {
+      const msg = data?.choices?.[0]?.message || {};
+      const text = msg.content || "";
+      const annotations = Array.isArray(msg.annotations) ? msg.annotations : [];
+      const fromAnn = annotations
+        .map((a) => a?.url_citation)
+        .filter(Boolean)
+        .map((u) => ({ url: u.url, title: u.title || "" }));
+      const fromTop = Array.isArray(data?.citations)
+        ? data.citations.map(normalizeCitation).filter(Boolean)
+        : [];
+      const citations = fromAnn.length ? fromAnn : fromTop;
+      const tokens = data?.usage?.total_tokens || 0;
+      return { text, citations, tokens };
+    }
+  },
+
+  xai: {
+    endpoint: () => searchEndpoint("xai"),
+    buildBody: (query, model) => ({
+      model,
+      input: [{ role: "user", content: query }],
+      tools: [{ type: "web_search" }]
+    }),
+    buildHeaders: (token) => ({
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`
+    }),
+    extractAnswer: (data) => {
+      // /v1/responses returns output[] array of message/tool blocks
+      const output = Array.isArray(data?.output) ? data.output : [];
+      let text = "";
+      const citations = [];
+      for (const item of output) {
+        const parts = Array.isArray(item?.content) ? item.content : [];
+        for (const p of parts) {
+          if (typeof p?.text === "string") text += p.text;
+          const anns = Array.isArray(p?.annotations) ? p.annotations : [];
+          for (const a of anns) {
+            const c = normalizeCitation(a?.url ? a : a?.url_citation);
+            if (c) citations.push(c);
+          }
+        }
+      }
+      // Fallback: top-level citations array (some response variants)
+      if (!citations.length && Array.isArray(data?.citations)) {
+        for (const c of data.citations) {
+          const n = normalizeCitation(c);
+          if (n) citations.push(n);
+        }
+      }
+      const tokens = data?.usage?.total_tokens || 0;
+      return { text, citations, tokens };
+    }
+  },
+
+  kimi: {
+    endpoint: () => searchEndpoint("kimi"),
+    buildBody: (query, model) => ({
+      model,
+      messages: [{ role: "user", content: query }],
+      tools: [
+        { type: "builtin_function", function: { name: "$web_search" } }
+      ]
+    }),
+    buildHeaders: (token) => ({
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`
+    }),
+    extractAnswer: (data) => {
+      const msg = data?.choices?.[0]?.message || {};
+      const text = msg.content || "";
+      const calls = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
+      const citations = [];
+      for (const call of calls) {
+        const argStr = call?.function?.arguments;
+        if (!argStr) continue;
+        let parsed;
+        try {
+          parsed = typeof argStr === "string" ? JSON.parse(argStr) : argStr;
+        } catch {
+          continue;
+        }
+        const items =
+          parsed?.search_results ||
+          parsed?.results ||
+          parsed?.references ||
+          [];
+        if (Array.isArray(items)) {
+          for (const it of items) {
+            const url = it?.url || it?.link;
+            if (!url) continue;
+            citations.push({
+              url,
+              title: it.title || "",
+              snippet: it.snippet || it.summary || ""
+            });
+          }
+        }
+      }
+      const tokens = data?.usage?.total_tokens || 0;
+      return { text, citations, tokens };
+    }
+  },
+
+  minimax: {
+    endpoint: () => searchEndpoint("minimax"),
+    buildBody: (query, model) => ({
+      model,
+      messages: [{ role: "user", content: query }],
+      tools: [{ type: "web_search" }]
+    }),
+    buildHeaders: (token) => ({
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`
+    }),
+    extractAnswer: (data) => {
+      const msg = data?.choices?.[0]?.message || {};
+      const text = msg.content || "";
+      const citations = [];
+      const direct = Array.isArray(data?.web_search_results)
+        ? data.web_search_results
+        : [];
+      for (const it of direct) {
+        const url = it?.url || it?.link;
+        if (url) {
+          citations.push({
+            url,
+            title: it.title || "",
+            snippet: it.snippet || it.summary || ""
+          });
+        }
+      }
+      if (!citations.length) {
+        const calls = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
+        for (const call of calls) {
+          const argStr = call?.function?.arguments;
+          if (!argStr) continue;
+          let parsed;
+          try {
+            parsed = typeof argStr === "string" ? JSON.parse(argStr) : argStr;
+          } catch {
+            continue;
+          }
+          const items = parsed?.results || parsed?.search_results || [];
+          if (Array.isArray(items)) {
+            for (const it of items) {
+              const url = it?.url || it?.link;
+              if (!url) continue;
+              citations.push({
+                url,
+                title: it.title || "",
+                snippet: it.snippet || ""
+              });
+            }
+          }
+        }
+      }
+      const tokens = data?.usage?.total_tokens || 0;
+      return { text, citations, tokens };
+    }
+  },
+
+  perplexity: {
+    endpoint: () => searchEndpoint("perplexity"),
+    buildBody: (query, model) => ({
+      model,
+      messages: [{ role: "user", content: query }]
+    }),
+    buildHeaders: (token) => ({
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`
+    }),
+    extractAnswer: (data) => {
+      const msg = data?.choices?.[0]?.message || {};
+      const text = msg.content || "";
+      const raw = data?.citations || [];
+      const citations = Array.isArray(raw)
+        ? raw.map(normalizeCitation).filter(Boolean)
+        : [];
+      const tokens = data?.usage?.total_tokens || 0;
+      return { text, citations, tokens };
+    }
+  },
+
+  "perplexity-agent": {
+    endpoint: () => searchEndpoint("perplexity-agent"),
+    buildBody: (query, model) => ({
+      model,
+      input: query,
+      tools: [{ type: "web_search" }]
+    }),
+    buildHeaders: (token) => ({
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`
+    }),
+    extractAnswer: (data) => {
+      const output = Array.isArray(data?.output) ? data.output : [];
+      let text = "";
+      const citations = [];
+      for (const item of output) {
+        const parts = Array.isArray(item?.content) ? item.content : [];
+        for (const p of parts) {
+          if (typeof p?.text === "string") text += p.text;
+          const anns = Array.isArray(p?.annotations) ? p.annotations : [];
+          for (const a of anns) {
+            const c = normalizeCitation(a?.url ? a : a?.url_citation);
+            if (c) citations.push(c);
+          }
+        }
+        const results = Array.isArray(item?.results) ? item.results : [];
+        for (const r of results) {
+          const url = r?.url || r?.link;
+          if (!url) continue;
+          citations.push({
+            url,
+            title: r?.title || "",
+            snippet: r?.snippet || ""
+          });
+        }
+      }
+      if (!citations.length && Array.isArray(data?.citations)) {
+        for (const c of data.citations) {
+          const n = normalizeCitation(c);
+          if (n) citations.push(n);
+        }
+      }
+      const tokens = data?.usage?.total_tokens || 0;
+      return { text, citations, tokens };
+    }
+  }
+};
+
+/**
+ * Execute a chat-search request against the chosen provider.
+ * @param {object} params
+ * @param {string} params.provider
+ * @param {string} params.query
+ * @param {number} [params.maxResults]
+ * @param {string} [params.model]
+ * @param {{apiKey?:string, accessToken?:string}} params.credentials
+ * @param {{info?:Function, warn?:Function, error?:Function}} [params.log]
+ * @returns {Promise<{success:boolean, status?:number, error?:string, data?:object}>}
+ */
+export async function handleChatSearch({
+  provider,
+  query,
+  maxResults,
+  model,
+  credentials,
+  log
+}) {
+  const startTime = Date.now();
+  const cfg = CHAT_SEARCH_CONFIG[provider];
+
+  if (!cfg) {
+    return {
+      success: false,
+      status: 400,
+      error: `Unsupported chat-search provider: ${provider}`
+    };
+  }
+
+  if (!query || typeof query !== "string") {
+    return { success: false, status: 400, error: "Missing query" };
+  }
+
+  const token = credentials?.apiKey || credentials?.accessToken;
+  if (!token) {
+    return {
+      success: false,
+      status: 401,
+      error: "Missing credentials (apiKey or accessToken)"
+    };
+  }
+
+  const limit =
+    Number.isFinite(maxResults) && maxResults > 0
+      ? Math.floor(maxResults)
+      : DEFAULT_MAX_RESULTS;
+  const useModel = model || searchModel(provider);
+  const url = cfg.endpoint(useModel);
+  const body = cfg.buildBody(query, useModel);
+  const headers = cfg.buildHeaders(token);
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  let upstreamStart = Date.now();
+  let resp;
+  try {
+    resp = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    if (err?.name === "AbortError") {
+      log?.warn?.(`[chatSearch] timeout provider=${provider}`);
+      return { success: false, status: 504, error: "Upstream timeout" };
+    }
+    log?.error?.(`[chatSearch] network error provider=${provider}: ${err?.message}`);
+    return {
+      success: false,
+      status: 502,
+      error: `Network error: ${err?.message || "unknown"}`
+    };
+  }
+  clearTimeout(timer);
+  const upstreamLatency = Date.now() - upstreamStart;
+
+  let data;
+  try {
+    data = await resp.json();
+  } catch {
+    return {
+      success: false,
+      status: 502,
+      error: `Invalid upstream response (status ${resp.status})`
+    };
+  }
+
+  if (!resp.ok) {
+    const errMsg =
+      data?.error?.message ||
+      data?.error ||
+      data?.message ||
+      `Upstream HTTP ${resp.status}`;
+    log?.warn?.(`[chatSearch] upstream error provider=${provider} status=${resp.status}`);
+    return {
+      success: false,
+      status: resp.status,
+      error: typeof errMsg === "string" ? errMsg : JSON.stringify(errMsg)
+    };
+  }
+
+  const { text, citations, tokens } = cfg.extractAnswer(data);
+  const retrievedAt = new Date().toISOString();
+  const limited = (citations || []).slice(0, limit);
+  const results = limited.map((c, i) => toResult(c, i, provider, retrievedAt));
+
+  return {
+    success: true,
+    status: 200,
+    data: {
+      provider,
+      query,
+      results,
+      answer: { source: provider, text: text || "", model: useModel },
+      usage: { queries_used: 1, search_cost_usd: 0, llm_tokens: tokens || 0 },
+      metrics: {
+        response_time_ms: Date.now() - startTime,
+        upstream_latency_ms: upstreamLatency,
+        total_results_available: null
+      },
+      errors: []
+    }
+  };
+}
+
+export { CHAT_SEARCH_CONFIG };
diff --git a/open-sse/handlers/search/index.js b/open-sse/handlers/search/index.js
new file mode 100644
index 0000000..f581547
--- /dev/null
+++ b/open-sse/handlers/search/index.js
@@ -0,0 +1,201 @@
+/**
+ * Search Dispatcher — routes /v1/search requests to dedicated search APIs
+ * or chat-based LLM search wrappers, with retry-friendly error envelope.
+ *
+ * Dependency map:
+ *   provider.searchConfig    → dedicated search API (callers + normalizers)
+ *   provider.searchViaChat   → wrap chat-completions (chatSearch.js)
+ */
+
+import { buildSearchRequest } from "./callers.js";
+import { normalizeSearchResponse } from "./normalizers.js";
+import { handleChatSearch } from "./chatSearch.js";
+
+const GLOBAL_TIMEOUT_MS = 15000;
+const NON_RETRIABLE = new Set([400, 401, 403, 404]);
+
+const CONTROL_CHAR_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+
+/** Normalize and validate query string. */
+function sanitizeQuery(query) {
+  if (CONTROL_CHAR_RE.test(query)) return { error: "Query contains invalid control characters" };
+  const clean = query.normalize("NFKC").trim().replace(/\s+/g, " ");
+  if (!clean) return { error: "Query is empty after normalization" };
+  return { clean };
+}
+
+// Strip non-ASCII chars from header values (HTTP headers must be ByteString).
+function sanitizeHeaders(headers) {
+  if (!headers) return headers;
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    out[k] = typeof v === "string" ? v.replace(/[^\x00-\xFF]/g, "").trim() : v;
+  }
+  return out;
+}
+
+/** Build a JSON Response wrapper used by the auth layer. */
+function jsonResponse(payload, status = 200) {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" }
+  });
+}
+
+/** Wrap an error result with a Response object so the auth wrapper can return it directly. */
+function errorResult(status, error) {
+  return {
+    success: false,
+    status,
+    error,
+    response: jsonResponse({ error: { message: error, code: status } }, status)
+  };
+}
+
+/** Wrap a success payload. */
+function successResult(data) {
+  return { success: true, data, response: jsonResponse(data, 200) };
+}
+
+/**
+ * Run a single dedicated search provider attempt.
+ * @returns {Promise<{success:boolean, status?:number, error?:string, data?:object}>}
+ */
+async function tryDedicatedProvider({ provider, providerConfig, body, credentials, log, globalStartTime }) {
+  const startTime = Date.now();
+  const token = credentials?.apiKey || credentials?.accessToken || undefined;
+
+  if (providerConfig.authType !== "none" && !token) {
+    return { success: false, status: 401, error: `No credentials for provider: ${provider.id}` };
+  }
+
+  const params = {
+    query: body.query,
+    searchType: body.search_type || (providerConfig.searchTypes?.[0] || "web"),
+    maxResults: Math.min(body.max_results || providerConfig.defaultMaxResults || 5, providerConfig.maxMaxResults || 100),
+    token,
+    country: body.country,
+    language: body.language,
+    timeRange: body.time_range,
+    offset: body.offset,
+    domainFilter: body.domain_filter,
+    contentOptions: body.content_options,
+    providerOptions: body.provider_options,
+    providerSpecificData: credentials?.providerSpecificData
+  };
+
+  let url, init;
+  try {
+    ({ url, init } = buildSearchRequest({ id: provider.id, ...providerConfig }, params));
+  } catch (err) {
+    return { success: false, status: 400, error: err?.message || `Invalid request for ${provider.id}` };
+  }
+
+  // Timeout = min(provider timeout, remaining global)
+  const remaining = GLOBAL_TIMEOUT_MS - (Date.now() - globalStartTime);
+  const timeout = Math.min(providerConfig.timeoutMs || 10000, Math.max(remaining, 1000));
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  log?.info?.("SEARCH", `${provider.id} | "${params.query.slice(0, 80)}" | type=${params.searchType}`);
+
+  try {
+    const resp = await fetch(url, { ...init, headers: sanitizeHeaders(init.headers), signal: controller.signal });
+    clearTimeout(timer);
+    if (!resp.ok) {
+      const errText = await resp.text().catch(() => "");
+      log?.error?.("SEARCH", `${provider.id} ${resp.status}: ${errText.slice(0, 200)}`);
+      return { success: false, status: resp.status, error: `${provider.id} returned ${resp.status}: ${errText.slice(0, 200)}` };
+    }
+    const data = await resp.json();
+    const normalized = normalizeSearchResponse(provider.id, data, params.query, params.searchType);
+    const results = normalized.results.slice(0, params.maxResults);
+    const duration = Date.now() - startTime;
+
+    return {
+      success: true,
+      data: {
+        provider: provider.id,
+        query: params.query,
+        results,
+        answer: null,
+        usage: { queries_used: 1, search_cost_usd: providerConfig.costPerQuery || 0 },
+        metrics: { response_time_ms: duration, upstream_latency_ms: duration, total_results_available: normalized.totalResults },
+        errors: []
+      }
+    };
+  } catch (err) {
+    clearTimeout(timer);
+    const isTimeout = err.name === "AbortError";
+    const status = isTimeout ? 504 : 502;
+    log?.error?.("SEARCH", `${provider.id} ${isTimeout ? "timeout" : "error"}: ${err.message}`);
+    return { success: false, status, error: `${provider.id} ${isTimeout ? "timeout" : "error"}: ${err.message}` };
+  }
+}
+
+/**
+ * Core search handler. Dispatches to dedicated API or chat-based LLM.
+ * Same calling convention as handleEmbeddingsCore: returns `{success, response, status?, error?}`.
+ *
+ * @param {object}   options
+ * @param {object}   options.body            Sanitized body from auth wrapper
+ * @param {object}   options.provider        Provider entry from AI_PROVIDERS
+ * @param {object}   [options.providerConfig] Provider's searchConfig (if dedicated)
+ * @param {object|null} options.credentials  Provider credentials
+ * @param {object}   [options.log]           Logger
+ */
+export async function handleSearchCore({ body, provider, providerConfig, credentials, log }) {
+  const globalStartTime = Date.now();
+
+  // 1. Sanitize query
+  const { clean, error: sanitizeError } = sanitizeQuery(body.query || "");
+  if (sanitizeError) return errorResult(400, sanitizeError);
+  const normalizedBody = { ...body, query: clean };
+
+  // 2. Route: dedicated search API takes priority over chat-based
+  let result;
+  if (providerConfig) {
+    result = await tryDedicatedProvider({
+      provider,
+      providerConfig,
+      body: normalizedBody,
+      credentials,
+      log,
+      globalStartTime
+    });
+  } else if (provider.searchViaChat) {
+    result = await handleChatSearch({
+      provider: provider.id,
+      query: clean,
+      maxResults: normalizedBody.max_results,
+      model: provider.searchViaChat.defaultModel,
+      credentials,
+      log
+    });
+  } else {
+    return errorResult(400, `Provider ${provider.id} does not support web search`);
+  }
+
+  if (result.success) return successResult(result.data);
+
+  // 3. Failover within global timeout for retriable errors
+  if (
+    !NON_RETRIABLE.has(result.status || 0) &&
+    Date.now() - globalStartTime < GLOBAL_TIMEOUT_MS &&
+    provider.searchViaChat &&
+    providerConfig
+  ) {
+    log?.warn?.("SEARCH", `${provider.id} dedicated failed (${result.status}), falling back to chat-based search`);
+    const fallback = await handleChatSearch({
+      provider: provider.id,
+      query: clean,
+      maxResults: normalizedBody.max_results,
+      model: provider.searchViaChat.defaultModel,
+      credentials,
+      log
+    });
+    if (fallback.success) return successResult(fallback.data);
+  }
+
+  return errorResult(result.status || 502, result.error || "Search failed");
+}
diff --git a/open-sse/handlers/search/normalizers.js b/open-sse/handlers/search/normalizers.js
new file mode 100644
index 0000000..da008bf
--- /dev/null
+++ b/open-sse/handlers/search/normalizers.js
@@ -0,0 +1,223 @@
+/**
+ * Search Response Normalizers
+ *
+ * Ported from OmniRoute open-sse/handlers/search.ts.
+ * Each normalizer maps a provider-specific response into the unified SearchResult shape.
+ */
+
+/** Build a unified SearchResult object. */
+function makeResult(providerId, item, idx, now) {
+  const url = item.url || "";
+  return {
+    title: item.title || "",
+    url,
+    display_url: url ? url.replace(/^https?:\/\/(www\.)?/, "").split("?")[0] : undefined,
+    snippet: item.snippet || "",
+    position: idx + 1,
+    score: typeof item.score === "number" ? Math.min(1, Math.max(0, item.score)) : null,
+    published_at: item.published_at || null,
+    favicon_url: item.favicon_url || null,
+    content: item.full_text
+      ? { format: item.text_format || "text", text: item.full_text, length: item.full_text.length }
+      : null,
+    metadata: {
+      author: item.author || null,
+      language: null,
+      source_type: item.source_type || null,
+      image_url: item.image_url || null,
+    },
+    citation: { provider: providerId, retrieved_at: now, rank: idx + 1 },
+    provider_raw: null,
+  };
+}
+
+function normalizeSerper(data, _query, searchType) {
+  const now = new Date().toISOString();
+  const items = searchType === "news" ? data.news : data.organic;
+  if (!Array.isArray(items)) return { results: [], totalResults: null };
+  const results = items.map((item, idx) =>
+    makeResult("serper", { title: item.title, url: item.link, snippet: item.snippet || item.description, published_at: item.date }, idx, now)
+  );
+  const total = data.searchParameters?.totalResults;
+  return { results, totalResults: typeof total === "number" ? total : null };
+}
+
+function normalizeBrave(data, _query, searchType) {
+  const now = new Date().toISOString();
+  const container = searchType === "news" ? data.news || data : data.web;
+  const items = container?.results;
+  if (!Array.isArray(items)) return { results: [], totalResults: null };
+  const results = items.map((item, idx) =>
+    makeResult("brave-search", {
+      title: item.title,
+      url: item.url,
+      snippet: item.description,
+      published_at: item.page_age || item.age,
+      favicon_url: item.meta_url?.favicon || item.favicon,
+    }, idx, now)
+  );
+  return { results, totalResults: container?.totalCount ?? null };
+}
+
+function normalizePerplexity(data, _query, _searchType) {
+  const now = new Date().toISOString();
+  const items = data.results;
+  if (!Array.isArray(items)) return { results: [], totalResults: null };
+  const results = items.map((item, idx) =>
+    makeResult("perplexity", { title: item.title, url: item.url, snippet: item.snippet, published_at: item.date || item.last_updated }, idx, now)
+  );
+  return { results, totalResults: results.length };
+}
+
+function normalizeExa(data, _query, _searchType) {
+  const now = new Date().toISOString();
+  const items = data.results;
+  if (!Array.isArray(items)) return { results: [], totalResults: null };
+  const results = items.map((item, idx) =>
+    makeResult("exa", {
+      title: item.title,
+      url: item.url,
+      snippet: item.highlights?.[0] || item.text?.slice(0, 300) || "",
+      score: item.score,
+      published_at: item.publishedDate,
+      favicon_url: item.favicon,
+      author: item.author,
+      image_url: item.image,
+      full_text: item.text,
+      text_format: "text",
+    }, idx, now)
+  );
+  return { results, totalResults: results.length };
+}
+
+function normalizeTavily(data, _query, _searchType) {
+  const now = new Date().toISOString();
+  const items = data.results;
+  if (!Array.isArray(items)) return { results: [], totalResults: null };
+  const results = items.map((item, idx) =>
+    makeResult("tavily", {
+      title: item.title,
+      url: item.url,
+      snippet: item.content || "",
+      score: item.score,
+      published_at: item.published_date,
+      full_text: item.raw_content,
+      text_format: "text",
+    }, idx, now)
+  );
+  return { results, totalResults: results.length };
+}
+
+function normalizeGooglePse(data, _query, _searchType) {
+  const now = new Date().toISOString();
+  const items = Array.isArray(data.items) ? data.items : [];
+  const results = items.map((item, idx) =>
+    makeResult("google-pse", {
+      title: item.title,
+      url: item.link,
+      snippet: item.snippet,
+      image_url: item.pagemap?.cse_image?.[0]?.src || item.pagemap?.cse_thumbnail?.[0]?.src || item.pagemap?.metatags?.[0]?.["og:image"],
+    }, idx, now)
+  );
+  const raw = data.searchInformation?.totalResults ?? data.queries?.request?.[0]?.totalResults ?? null;
+  const total = typeof raw === "string" ? Number(raw) : raw;
+  return { results, totalResults: Number.isFinite(total) ? total : null };
+}
+
+function normalizeLinkup(data, _query, _searchType) {
+  const now = new Date().toISOString();
+  const items = Array.isArray(data.results) ? data.results : [];
+  const results = items.map((item, idx) =>
+    makeResult("linkup", {
+      title: item.name || item.title,
+      url: item.url,
+      snippet: item.content || item.snippet || "",
+      source_type: item.type || "web",
+      image_url: item.image_url || item.imageUrl || null,
+      full_text: item.content,
+      text_format: "text",
+    }, idx, now)
+  );
+  return { results, totalResults: results.length };
+}
+
+function normalizeSearchApi(data, _query, _searchType) {
+  const now = new Date().toISOString();
+  const items = Array.isArray(data.organic_results) ? data.organic_results : Array.isArray(data.top_stories) ? data.top_stories : [];
+  const results = items.map((item, idx) =>
+    makeResult("searchapi", {
+      title: item.title,
+      url: item.link,
+      snippet: item.snippet || item.description || "",
+      published_at: item.date || item.published_at,
+      favicon_url: item.favicon,
+      author: item.source || null,
+      image_url: item.thumbnail || null,
+    }, idx, now)
+  );
+  const raw = data.search_information?.total_results;
+  const total = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : null;
+  return { results, totalResults: Number.isFinite(total) ? total : results.length };
+}
+
+function normalizeYouCom(data, _query, searchType) {
+  const now = new Date().toISOString();
+  const container = data?.results && typeof data.results === "object" ? data.results : undefined;
+  const section = searchType === "news" ? container?.news || [] : container?.web || [];
+  const items = Array.isArray(section) ? section : [];
+  const results = items.map((item, idx) => {
+    const firstSnippet = Array.isArray(item.snippets) ? item.snippets.find((v) => typeof v === "string") : null;
+    const livecrawlText = typeof item.markdown === "string" ? item.markdown : typeof item.html === "string" ? item.html : undefined;
+    const livecrawlFormat = typeof item.markdown === "string" ? "markdown" : "html";
+    return makeResult("youcom", {
+      title: item.title,
+      url: item.url,
+      snippet: typeof firstSnippet === "string" ? firstSnippet : typeof item.description === "string" ? item.description : "",
+      published_at: item.page_age,
+      favicon_url: item.favicon_url,
+      image_url: item.thumbnail_url,
+      source_type: searchType,
+      full_text: livecrawlText,
+      text_format: livecrawlText ? livecrawlFormat : undefined,
+    }, idx, now);
+  });
+  return { results, totalResults: results.length };
+}
+
+function normalizeSearxng(data, _query, _searchType) {
+  const now = new Date().toISOString();
+  const items = Array.isArray(data.results) ? data.results : [];
+  const results = items.map((item, idx) =>
+    makeResult("searxng", {
+      title: item.title,
+      url: item.url,
+      snippet: item.content || item.snippet || "",
+      published_at: item.publishedDate || item.published_date || null,
+      source_type: Array.isArray(item.engines) ? item.engines.join(", ") : item.engine || item.category || null,
+      image_url: item.thumbnail || item.img_src || null,
+    }, idx, now)
+  );
+  return { results, totalResults: results.length };
+}
+
+const NORMALIZERS = {
+  "serper": normalizeSerper,
+  "brave-search": normalizeBrave,
+  "perplexity": normalizePerplexity,
+  "exa": normalizeExa,
+  "tavily": normalizeTavily,
+  "google-pse": normalizeGooglePse,
+  "linkup": normalizeLinkup,
+  "searchapi": normalizeSearchApi,
+  "youcom": normalizeYouCom,
+  "searxng": normalizeSearxng,
+};
+
+/**
+ * Dispatch to the appropriate normalizer based on providerId.
+ * @returns {{results: Array, totalResults: number|null}}
+ */
+export function normalizeSearchResponse(providerId, data, query, searchType) {
+  const fn = NORMALIZERS[providerId];
+  return fn ? fn(data, query, searchType) : { results: [], totalResults: null };
+}
diff --git a/open-sse/handlers/sttCore.js b/open-sse/handlers/sttCore.js
new file mode 100644
index 0000000..acb7d13
--- /dev/null
+++ b/open-sse/handlers/sttCore.js
@@ -0,0 +1,193 @@
+import { Buffer } from "node:buffer";
+import { createErrorResult } from "../utils/error.js";
+import { HTTP_STATUS } from "../config/runtimeConfig.js";
+
+// Build auth headers from sttConfig + token
+function buildAuthHeaders(cfg, token) {
+  if (!token) return {};
+  switch (cfg.authHeader) {
+    case "bearer":     return { "Authorization": `Bearer ${token}` };
+    case "token":      return { "Authorization": `Token ${token}` };
+    case "x-api-key":  return { "x-api-key": token };
+    case "key":        return { "Authorization": `Key ${token}` };
+    default:           return { "Authorization": `Bearer ${token}` };
+  }
+}
+
+// Map browser file MIME / ext → audio MIME for binary formats (deepgram/HF)
+function resolveAudioContentType(file) {
+  const t = (file.type || "").toLowerCase();
+  if (t.startsWith("audio/")) return t;
+  const name = typeof file.name === "string" ? file.name.toLowerCase() : "";
+  const ext = name.includes(".") ? name.split(".").pop() : "";
+  const map = { mp3: "audio/mpeg", mp4: "audio/mp4", m4a: "audio/mp4", wav: "audio/wav", ogg: "audio/ogg", flac: "audio/flac", webm: "audio/webm", aac: "audio/aac", opus: "audio/opus" };
+  return map[ext] || "application/octet-stream";
+}
+
+async function upstreamError(res) {
+  let txt = "";
+  try { txt = await res.text(); } catch {}
+  let msg = txt || `Upstream error (${res.status})`;
+  try { const j = JSON.parse(txt); msg = j?.error?.message || j?.error || j?.message || msg; } catch {}
+  return createErrorResult(res.status, typeof msg === "string" ? msg : JSON.stringify(msg));
+}
+
+// Deepgram: raw binary POST + model query param
+async function transcribeDeepgram(cfg, file, model, token, formData) {
+  const url = new URL(cfg.baseUrl);
+  url.searchParams.set("model", model);
+  url.searchParams.set("smart_format", "true");
+  url.searchParams.set("punctuate", "true");
+  const lang = formData.get("language");
+  if (typeof lang === "string" && lang.trim()) url.searchParams.set("language", lang.trim());
+  else url.searchParams.set("detect_language", "true");
+
+  const buf = await file.arrayBuffer();
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { ...buildAuthHeaders(cfg, token), "Content-Type": resolveAudioContentType(file) },
+    body: buf,
+  });
+  if (!res.ok) return upstreamError(res);
+  const data = await res.json();
+  const text = data.results?.channels?.[0]?.alternatives?.[0]?.transcript ?? "";
+  return jsonResponse({ text });
+}
+
+// AssemblyAI: upload → submit → poll (max 120s)
+async function transcribeAssemblyAI(cfg, file, model, token) {
+  const auth = buildAuthHeaders(cfg, token);
+  const buf = await file.arrayBuffer();
+  const up = await fetch("https://api.assemblyai.com/v2/upload", {
+    method: "POST", headers: { ...auth, "Content-Type": "application/octet-stream" }, body: buf,
+  });
+  if (!up.ok) return upstreamError(up);
+  const { upload_url } = await up.json();
+
+  const sub = await fetch(cfg.baseUrl, {
+    method: "POST",
+    headers: { ...auth, "Content-Type": "application/json" },
+    body: JSON.stringify({ audio_url: upload_url, speech_models: [model], language_detection: true }),
+  });
+  if (!sub.ok) return upstreamError(sub);
+  const { id } = await sub.json();
+
+  const start = Date.now();
+  while (Date.now() - start < 120_000) {
+    await new Promise((r) => setTimeout(r, 2000));
+    const poll = await fetch(`${cfg.baseUrl}/${id}`, { headers: auth });
+    if (!poll.ok) continue;
+    const r = await poll.json();
+    if (r.status === "completed") return jsonResponse({ text: r.text || "" });
+    if (r.status === "error") return createErrorResult(500, r.error || "AssemblyAI failed");
+  }
+  return createErrorResult(504, "AssemblyAI timeout after 120s");
+}
+
+// Nvidia NIM: multipart, normalize response
+async function transcribeNvidia(cfg, file, model, token) {
+  const fd = new FormData();
+  fd.append("file", file, file.name || "audio.wav");
+  fd.append("model", model);
+  const res = await fetch(cfg.baseUrl, { method: "POST", headers: buildAuthHeaders(cfg, token), body: fd });
+  if (!res.ok) return upstreamError(res);
+  const data = await res.json();
+  return jsonResponse({ text: data.text || data.transcript || "" });
+}
+
+// Gemini: generateContent with inline_data audio + transcription prompt
+async function transcribeGemini(cfg, file, model, token, formData) {
+  const buf = await file.arrayBuffer();
+  const b64 = Buffer.from(buf).toString("base64");
+  const mime = resolveAudioContentType(file);
+  const lang = formData.get("language");
+  const userPrompt = formData.get("prompt");
+  let promptText = userPrompt && typeof userPrompt === "string" && userPrompt.trim()
+    ? userPrompt.trim()
+    : "Generate a transcript of the speech. Return only the transcribed text, no commentary.";
+  if (typeof lang === "string" && lang.trim()) promptText += ` Language: ${lang.trim()}.`;
+
+  const url = `${cfg.baseUrl}/${model}:generateContent?key=${token}`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      contents: [{ parts: [{ text: promptText }, { inline_data: { mime_type: mime, data: b64 } }] }],
+    }),
+  });
+  if (!res.ok) return upstreamError(res);
+  const data = await res.json();
+  const text = data?.candidates?.[0]?.content?.parts?.map((p) => p.text).filter(Boolean).join("") || "";
+  return jsonResponse({ text });
+}
+
+// HuggingFace: POST raw binary to {baseUrl}/{model_id}
+async function transcribeHuggingFace(cfg, file, model, token) {
+  if (model.includes("..") || model.includes("//")) return createErrorResult(400, "Invalid model ID");
+  const url = `${cfg.baseUrl.replace(/\/+$/, "")}/${model}`;
+  const buf = await file.arrayBuffer();
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { ...buildAuthHeaders(cfg, token), "Content-Type": resolveAudioContentType(file) },
+    body: buf,
+  });
+  if (!res.ok) return upstreamError(res);
+  const data = await res.json();
+  return jsonResponse({ text: data.text || "" });
+}
+
+// Default: OpenAI/Groq/Whisper-compatible multipart
+async function transcribeOpenAICompatible(cfg, file, model, token, formData) {
+  const fd = new FormData();
+  fd.append("file", file, file.name || "audio.wav");
+  fd.append("model", model);
+  for (const k of ["language", "prompt", "response_format", "temperature"]) {
+    const v = formData.get(k);
+    if (v !== null && v !== undefined && v !== "") fd.append(k, v);
+  }
+  const res = await fetch(cfg.baseUrl, { method: "POST", headers: buildAuthHeaders(cfg, token), body: fd });
+  if (!res.ok) return upstreamError(res);
+  const ct = res.headers.get("content-type") || "application/json";
+  const txt = await res.text();
+  return { success: true, response: new Response(txt, { status: 200, headers: { "Content-Type": ct, "Access-Control-Allow-Origin": "*" } }) };
+}
+
+function jsonResponse(obj) {
+  return {
+    success: true,
+    response: new Response(JSON.stringify(obj), {
+      status: 200,
+      headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
+    }),
+  };
+}
+
+/**
+ * STT core handler — dispatch by sttConfig.format.
+ * @returns {Promise<{success, response, status?, error?}>}
+ */
+export async function handleSttCore({ provider, model, formData, credentials, sttConfig }) {
+  const file = formData.get("file");
+  if (!file) return createErrorResult(HTTP_STATUS.BAD_REQUEST, "Missing required field: file");
+
+  const cfg = sttConfig;
+  if (!cfg) return createErrorResult(HTTP_STATUS.BAD_REQUEST, `Provider '${provider}' does not support STT`);
+
+  const token = cfg.authType === "none" ? null : (credentials?.apiKey || credentials?.accessToken);
+  if (cfg.authType !== "none" && !token) {
+    return createErrorResult(HTTP_STATUS.UNAUTHORIZED, `No credentials for STT provider: ${provider}`);
+  }
+
+  try {
+    switch (cfg.format) {
+      case "deepgram":        return await transcribeDeepgram(cfg, file, model, token, formData);
+      case "assemblyai":      return await transcribeAssemblyAI(cfg, file, model, token);
+      case "nvidia-asr":      return await transcribeNvidia(cfg, file, model, token);
+      case "huggingface-asr": return await transcribeHuggingFace(cfg, file, model, token);
+      case "gemini-stt":      return await transcribeGemini(cfg, file, model, token, formData);
+      default:                return await transcribeOpenAICompatible(cfg, file, model, token, formData);
+    }
+  } catch (err) {
+    return createErrorResult(HTTP_STATUS.BAD_GATEWAY, err.message || "STT request failed");
+  }
+}
diff --git a/open-sse/handlers/ttsCore.js b/open-sse/handlers/ttsCore.js
new file mode 100644
index 0000000..b4b69ee
--- /dev/null
+++ b/open-sse/handlers/ttsCore.js
@@ -0,0 +1,74 @@
+import { Buffer } from "node:buffer";
+import { createErrorResult } from "../utils/error.js";
+import { HTTP_STATUS } from "../config/runtimeConfig.js";
+import { getTtsAdapter, synthesizeViaConfig } from "./ttsProviders/index.js";
+
+// Re-export voice fetchers + voices APIs for backward compat with existing routes
+export {
+  VOICE_FETCHERS,
+  fetchEdgeTtsVoices,
+  fetchLocalDeviceVoices,
+  fetchElevenLabsVoices,
+} from "./ttsProviders/index.js";
+
+// ── Response Formatter (DRY) ───────────────────────────────────
+function createTtsResponse(base64Audio, format, responseFormat) {
+  const audioBuffer = Buffer.from(base64Audio, "base64");
+
+  // JSON format: return base64 encoded audio
+  if (responseFormat === "json") {
+    return {
+      success: true,
+      response: new Response(JSON.stringify({ audio: base64Audio, format }), {
+        headers: {
+          "Content-Type": "application/json",
+          "Access-Control-Allow-Origin": "*",
+        },
+      }),
+    };
+  }
+
+  // Binary format (default): return raw audio
+  return {
+    success: true,
+    response: new Response(audioBuffer, {
+      headers: {
+        "Content-Type": `audio/${format}`,
+        "Content-Length": String(audioBuffer.length),
+        "Access-Control-Allow-Origin": "*",
+      },
+    }),
+  };
+}
+
+// ── Core handler ───────────────────────────────────────────────
+/**
+ * Synthesize text to audio. Provider logic lives in `./ttsProviders/{id}.js`
+ * or is dispatched generically via `ttsConfig.format`.
+ *
+ * @returns {Promise<{success, response, status?, error?}>}
+ */
+export async function handleTtsCore({ provider, model, input, credentials, responseFormat = "mp3", language }) {
+  if (!input?.trim()) {
+    return createErrorResult(HTTP_STATUS.BAD_REQUEST, "Missing required field: input");
+  }
+
+  try {
+    // Special-case adapters (google-tts, edge-tts, local-device, elevenlabs, openai, openrouter, gemini)
+    const adapter = getTtsAdapter(provider);
+    if (adapter) {
+      const result = await adapter.synthesize(input.trim(), model, credentials, responseFormat, { language });
+      // Adapter may return a full {success, response} (legacy) or {base64, format}
+      if (result.success !== undefined) return result;
+      return createTtsResponse(result.base64, result.format, responseFormat);
+    }
+
+    // Generic config-driven (hyperbolic, deepgram, nvidia, huggingface, inworld, cartesia, playht, coqui, tortoise, qwen, ...)
+    const result = await synthesizeViaConfig(provider, input.trim(), model, credentials);
+    if (result) return createTtsResponse(result.base64, result.format, responseFormat);
+
+    return createErrorResult(HTTP_STATUS.BAD_REQUEST, `Provider '${provider}' does not support TTS via this route.`);
+  } catch (err) {
+    return createErrorResult(HTTP_STATUS.BAD_GATEWAY, err.message || "TTS synthesis failed");
+  }
+}
diff --git a/open-sse/handlers/ttsProviders/_base.js b/open-sse/handlers/ttsProviders/_base.js
new file mode 100644
index 0000000..1c92211
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/_base.js
@@ -0,0 +1,39 @@
+// Shared TTS helpers
+import { Buffer } from "node:buffer";
+
+export const UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";
+
+// Convert upstream Response (binary audio) to { base64, format }
+export async function responseToBase64(res, defaultFormat = "mp3") {
+  const buf = await res.arrayBuffer();
+  if (buf.byteLength < 100) throw new Error("Upstream returned empty audio");
+  const ctype = res.headers.get("content-type") || "";
+  let format = defaultFormat;
+  if (ctype.includes("wav")) format = "wav";
+  else if (ctype.includes("mpeg") || ctype.includes("mp3")) format = "mp3";
+  else if (ctype.includes("ogg")) format = "ogg";
+  return { base64: Buffer.from(buf).toString("base64"), format };
+}
+
+export async function throwUpstreamError(res) {
+  const text = await res.text().catch(() => "");
+  let msg = `Upstream error (${res.status})`;
+  try {
+    const parsed = JSON.parse(text);
+    msg = parsed?.error?.message || parsed?.message || parsed?.detail?.message || (typeof parsed?.detail === "string" ? parsed.detail : null) || text || msg;
+  } catch { msg = text || msg; }
+  throw new Error(msg);
+}
+
+// Parse `model` string as "modelId/voiceId" — match against known model list (longest prefix wins)
+export function parseModelVoice(model, defaultModel = "", defaultVoice = "", knownModels = []) {
+  if (!model) return { modelId: defaultModel, voiceId: defaultVoice };
+  const known = knownModels.map((m) => m.id || m).filter(Boolean).sort((a, b) => b.length - a.length);
+  for (const id of known) {
+    if (model === id) return { modelId: id, voiceId: defaultVoice };
+    if (model.startsWith(`${id}/`)) return { modelId: id, voiceId: model.slice(id.length + 1) };
+  }
+  const idx = model.lastIndexOf("/");
+  if (idx > 0) return { modelId: model.slice(0, idx), voiceId: model.slice(idx + 1) };
+  return { modelId: defaultModel || model, voiceId: defaultVoice || model };
+}
diff --git a/open-sse/handlers/ttsProviders/edgeTts.js b/open-sse/handlers/ttsProviders/edgeTts.js
new file mode 100644
index 0000000..66b1dd9
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/edgeTts.js
@@ -0,0 +1,89 @@
+// Microsoft Edge / Bing TTS (no auth) — via Bing translator endpoint
+import { Buffer } from "node:buffer";
+import { UA } from "./_base.js";
+
+const REFRESH_MS = 5 * 60 * 1000; // token TTL ~1h, refresh early
+const VOICES_TTL = 24 * 60 * 60 * 1000;
+
+const cache = { token: null, tokenTime: 0 };
+let _voicesCache = null;
+let _voicesCacheTime = 0;
+
+async function getToken() {
+  const now = Date.now();
+  if (cache.token && now - cache.tokenTime < REFRESH_MS) return cache.token;
+  const res = await fetch("https://www.bing.com/translator", {
+    headers: { "User-Agent": UA, "Accept-Language": "vi,en-US;q=0.9,en;q=0.8" },
+  });
+  if (!res.ok) throw new Error(`Bing translator fetch failed: ${res.status}`);
+  const rawCookies = res.headers.getSetCookie?.() || [];
+  const cookie = rawCookies.map((c) => c.split(";")[0]).join("; ");
+  const html = await res.text();
+  const match = html.match(/params_AbusePreventionHelper\s*=\s*\[([^,]+),([^,]+),/);
+  if (!match) throw new Error("Failed to parse Bing token");
+  cache.token = { key: match[1], token: match[2].replace(/"/g, ""), cookie };
+  cache.tokenTime = now;
+  return cache.token;
+}
+
+async function ttsRequest(text, voiceId, token) {
+  const parts = voiceId.split("-");
+  const xmlLang = parts.slice(0, 2).join("-");
+  const gender = voiceId.toLowerCase().includes("male") ? "Male" : "Female";
+  const ssml = `<speak version='1.0' xml:lang='${xmlLang}'><voice xml:lang='${xmlLang}' xml:gender='${gender}' name='${voiceId}'><prosody rate='0.00%'>${text}</prosody></voice></speak>`;
+  const body = new URLSearchParams();
+  body.append("ssml", ssml);
+  body.append("token", token.token);
+  body.append("key", token.key);
+  return fetch("https://www.bing.com/tfettts?isVertical=1&&IG=1&IID=translator.5023&SFX=1", {
+    method: "POST",
+    body: body.toString(),
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      "Accept": "*/*",
+      "Origin": "https://www.bing.com",
+      "Referer": "https://www.bing.com/translator",
+      "User-Agent": UA,
+      ...(token.cookie ? { "Cookie": token.cookie } : {}),
+    },
+  });
+}
+
+export async function fetchEdgeTtsVoices() {
+  const now = Date.now();
+  if (_voicesCache && now - _voicesCacheTime < VOICES_TTL) return _voicesCache;
+  const res = await fetch(
+    "https://speech.platform.bing.com/consumer/speech/synthesize/readaloud/voices/list?trustedclienttoken=6A5AA1D4EAFF4E9FB37E23D68491D6F4",
+    { headers: { "User-Agent": UA } }
+  );
+  if (!res.ok) throw new Error(`Edge TTS voices fetch failed: ${res.status}`);
+  const voices = await res.json();
+  _voicesCache = voices;
+  _voicesCacheTime = now;
+  return voices;
+}
+
+export default {
+  noAuth: true,
+  async synthesize(text, model) {
+    const voiceId = model || "vi-VN-HoaiMyNeural";
+    let token = await getToken();
+    let res = await ttsRequest(text, voiceId, token);
+
+    // 429/403: invalidate cache and retry once
+    if (res.status === 429 || res.status === 403) {
+      cache.token = null;
+      cache.tokenTime = 0;
+      token = await getToken();
+      res = await ttsRequest(text, voiceId, token);
+    }
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`Bing TTS failed: ${res.status}${body ? " - " + body : ""}`);
+    }
+    const buf = await res.arrayBuffer();
+    if (buf.byteLength < 1024) throw new Error("Bing TTS returned empty audio");
+    return { base64: Buffer.from(buf).toString("base64"), format: "mp3" };
+  },
+};
diff --git a/open-sse/handlers/ttsProviders/elevenlabs.js b/open-sse/handlers/ttsProviders/elevenlabs.js
new file mode 100644
index 0000000..711a567
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/elevenlabs.js
@@ -0,0 +1,48 @@
+// ElevenLabs TTS — voice id with optional model_id prefix
+import { Buffer } from "node:buffer";
+
+const VOICES_TTL = 24 * 60 * 60 * 1000;
+const _voicesCache = new Map(); // by API key
+
+export async function fetchElevenLabsVoices(apiKey) {
+  if (!apiKey) throw new Error("ElevenLabs API key required");
+  const now = Date.now();
+  const cached = _voicesCache.get(apiKey);
+  if (cached && now - cached.time < VOICES_TTL) return cached.voices;
+
+  const res = await fetch("https://api.elevenlabs.io/v1/voices", {
+    headers: { "xi-api-key": apiKey, "Content-Type": "application/json" },
+  });
+  if (!res.ok) throw new Error(`ElevenLabs voices fetch failed: ${res.status}`);
+  const data = await res.json();
+  // Normalize: derive lang from labels for grouping
+  const voices = (data.voices || []).map((v) => ({ ...v, lang: v.labels?.language || "en" }));
+  _voicesCache.set(apiKey, { voices, time: now });
+  return voices;
+}
+
+export default {
+  async synthesize(text, model, credentials) {
+    if (!credentials?.apiKey) throw new Error("ElevenLabs API key required");
+    let modelId = "eleven_flash_v2_5";
+    let voiceId = model;
+    if (model && model.includes("/")) [modelId, voiceId] = model.split("/");
+
+    const res = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`, {
+      method: "POST",
+      headers: { "xi-api-key": credentials.apiKey, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text,
+        model_id: modelId,
+        voice_settings: { stability: 0.5, similarity_boost: 0.75 },
+      }),
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err?.detail?.message || `ElevenLabs TTS failed: ${res.status}`);
+    }
+    const buf = await res.arrayBuffer();
+    if (buf.byteLength < 1024) throw new Error("ElevenLabs TTS returned empty audio");
+    return { base64: Buffer.from(buf).toString("base64"), format: "mp3" };
+  },
+};
diff --git a/open-sse/handlers/ttsProviders/gemini.js b/open-sse/handlers/ttsProviders/gemini.js
new file mode 100644
index 0000000..15afd88
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/gemini.js
@@ -0,0 +1,128 @@
+// Gemini TTS — generateContent with AUDIO modality returns PCM L16, wrap as WAV
+import { Buffer } from "node:buffer";
+import { PROVIDER_MEDIA, PROVIDER_MODELS } from "../../providers/index.js";
+
+const TTS_CFG = PROVIDER_MEDIA["gemini"]?.ttsConfig || {};
+const TTS_BASE = TTS_CFG.baseUrl;
+const FALLBACK_MODEL = "gemini-3.1-flash-tts-preview";
+const KNOWN_MODELS = [
+  ...(TTS_CFG.models || []),
+  ...(PROVIDER_MODELS["gemini-tts-models"] || []),
+  ...(PROVIDER_MODELS.gemini || []).filter((m) => (m.kind || m.type) === "tts"),
+]
+  .map((m) => m?.id)
+  .filter(Boolean)
+  .filter((id, index, list) => list.indexOf(id) === index);
+const DEFAULT_MODEL = KNOWN_MODELS[0] || FALLBACK_MODEL;
+const DEFAULT_VOICE = "Kore";
+
+// Parse "model/voice" — if input doesn't match a known TTS model, treat it as voice with default model
+function parseGeminiModelVoice(input) {
+  if (!input) return { modelId: DEFAULT_MODEL, voiceId: DEFAULT_VOICE };
+  for (const id of KNOWN_MODELS) {
+    if (input === id) return { modelId: id, voiceId: DEFAULT_VOICE };
+    if (input.startsWith(`${id}/`)) return { modelId: id, voiceId: input.slice(id.length + 1) };
+  }
+  return { modelId: DEFAULT_MODEL, voiceId: input };
+}
+// Gemini returns PCM 16-bit signed mono @ 24kHz
+const SAMPLE_RATE = 24000;
+const CHANNELS = 1;
+const BITS_PER_SAMPLE = 16;
+
+// Build WAV header for raw PCM payload
+function pcmToWav(pcmBuffer) {
+  const dataSize = pcmBuffer.length;
+  const byteRate = SAMPLE_RATE * CHANNELS * BITS_PER_SAMPLE / 8;
+  const blockAlign = CHANNELS * BITS_PER_SAMPLE / 8;
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0);
+  header.writeUInt32LE(36 + dataSize, 4);
+  header.write("WAVE", 8);
+  header.write("fmt ", 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(CHANNELS, 22);
+  header.writeUInt32LE(SAMPLE_RATE, 24);
+  header.writeUInt32LE(byteRate, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(BITS_PER_SAMPLE, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(dataSize, 40);
+  return Buffer.concat([header, pcmBuffer]);
+}
+
+// Build TTS prompt: add "Say [in {language}]:" prefix to force TTS mode
+function buildPrompt(text, language) {
+  if (/:\s/.test(text)) return text; // user already provided style instruction
+  return language ? `Say in ${language}: ${text}` : `Say: ${text}`;
+}
+
+export default {
+  async synthesize(text, model, credentials, _responseFormat, opts = {}) {
+    if (!credentials?.apiKey) throw new Error("No Gemini API key configured");
+    const { modelId, voiceId } = parseGeminiModelVoice(model);
+    const url = `${TTS_BASE}/${modelId}:generateContent?key=${credentials.apiKey}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        contents: [{ parts: [{ text: buildPrompt(text, opts.language) }] }],
+        generationConfig: {
+          responseModalities: ["AUDIO"],
+          speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: voiceId } } },
+        },
+      }),
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err?.error?.message || `Gemini TTS failed: ${res.status}`);
+    }
+    const data = await res.json();
+    const b64 = data?.candidates?.[0]?.content?.parts?.find((p) => p.inlineData?.data)?.inlineData?.data;
+    if (!b64) {
+      const reason = data?.candidates?.[0]?.finishReason || data?.promptFeedback?.blockReason || "unknown";
+      throw new Error(`Gemini TTS returned no audio (finishReason: ${reason}, voice: ${voiceId}, model: ${modelId})`);
+    }
+    const wav = pcmToWav(Buffer.from(b64, "base64"));
+    return { base64: wav.toString("base64"), format: "wav" };
+  },
+};
+
+// Voice fetcher — return prebuilt voices (Gemini has no list API)
+const PREBUILT_VOICES = [
+  { id: "Zephyr", lang: "en", gender: "Female" },
+  { id: "Puck", lang: "en", gender: "Male" },
+  { id: "Charon", lang: "en", gender: "Male" },
+  { id: "Kore", lang: "en", gender: "Female" },
+  { id: "Fenrir", lang: "en", gender: "Male" },
+  { id: "Leda", lang: "en", gender: "Female" },
+  { id: "Orus", lang: "en", gender: "Male" },
+  { id: "Aoede", lang: "en", gender: "Female" },
+  { id: "Callirrhoe", lang: "en", gender: "Female" },
+  { id: "Autonoe", lang: "en", gender: "Female" },
+  { id: "Enceladus", lang: "en", gender: "Male" },
+  { id: "Iapetus", lang: "en", gender: "Male" },
+  { id: "Umbriel", lang: "en", gender: "Male" },
+  { id: "Algieba", lang: "en", gender: "Male" },
+  { id: "Despina", lang: "en", gender: "Female" },
+  { id: "Erinome", lang: "en", gender: "Female" },
+  { id: "Algenib", lang: "en", gender: "Male" },
+  { id: "Rasalgethi", lang: "en", gender: "Male" },
+  { id: "Laomedeia", lang: "en", gender: "Female" },
+  { id: "Achernar", lang: "en", gender: "Female" },
+  { id: "Alnilam", lang: "en", gender: "Male" },
+  { id: "Schedar", lang: "en", gender: "Male" },
+  { id: "Gacrux", lang: "en", gender: "Female" },
+  { id: "Pulcherrima", lang: "en", gender: "Female" },
+  { id: "Achird", lang: "en", gender: "Male" },
+  { id: "Zubenelgenubi", lang: "en", gender: "Male" },
+  { id: "Vindemiatrix", lang: "en", gender: "Female" },
+  { id: "Sadachbia", lang: "en", gender: "Male" },
+  { id: "Sadaltager", lang: "en", gender: "Male" },
+  { id: "Sulafat", lang: "en", gender: "Female" },
+];
+
+export async function fetchGeminiVoices() {
+  return PREBUILT_VOICES.map((v) => ({ voice_id: v.id, name: v.id, labels: { language: v.lang, gender: v.gender } }));
+}
diff --git a/open-sse/handlers/ttsProviders/genericFormats.js b/open-sse/handlers/ttsProviders/genericFormats.js
new file mode 100644
index 0000000..2f27f9e
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/genericFormats.js
@@ -0,0 +1,169 @@
+// Generic config-driven TTS handlers — dispatched by ttsConfig.format.
+// Each handler accepts { baseUrl, apiKey, text, modelId, voiceId } and returns { base64, format }.
+import { responseToBase64, throwUpstreamError } from "./_base.js";
+import minimaxTts from "./minimax.js";
+
+// Hyperbolic: POST { text } → { audio: base64 }
+async function hyperbolic({ baseUrl, apiKey, text }) {
+  const res = await fetch(baseUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
+    body: JSON.stringify({ text }),
+  });
+  if (!res.ok) await throwUpstreamError(res);
+  const data = await res.json();
+  return { base64: data.audio, format: "mp3" };
+}
+
+// Deepgram: model via query, Token auth, returns binary
+async function deepgram({ baseUrl, apiKey, text, modelId }) {
+  const url = new URL(baseUrl);
+  url.searchParams.set("model", modelId || "aura-asteria-en");
+  const res = await fetch(url.toString(), {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "Authorization": `Token ${apiKey}` },
+    body: JSON.stringify({ text }),
+  });
+  if (!res.ok) await throwUpstreamError(res);
+  return responseToBase64(res, "mp3");
+}
+
+// Nvidia NIM: POST { input: { text }, voice, model } → binary
+async function nvidia({ baseUrl, apiKey, text, modelId, voiceId }) {
+  const res = await fetch(baseUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
+    body: JSON.stringify({ input: { text }, voice: voiceId || "default", model: modelId }),
+  });
+  if (!res.ok) await throwUpstreamError(res);
+  return responseToBase64(res, "wav");
+}
+
+// HuggingFace: POST {baseUrl}/{modelId} { inputs: text } → binary
+async function huggingface({ baseUrl, apiKey, text, modelId }) {
+  if (!modelId || modelId.includes("..")) throw new Error("Invalid HuggingFace model ID");
+  const res = await fetch(`${baseUrl}/${modelId}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
+    body: JSON.stringify({ inputs: text }),
+  });
+  if (!res.ok) await throwUpstreamError(res);
+  return responseToBase64(res, "wav");
+}
+
+// Inworld: Basic auth, JSON { audioContent }
+async function inworld({ baseUrl, apiKey, text, modelId, voiceId }) {
+  const res = await fetch(baseUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "Authorization": `Basic ${apiKey}` },
+    body: JSON.stringify({
+      text,
+      voiceId: voiceId || "Alex",
+      modelId: modelId || "inworld-tts-1.5-mini",
+      audioConfig: { audioEncoding: "MP3" },
+    }),
+  });
+  if (!res.ok) await throwUpstreamError(res);
+  const data = await res.json();
+  if (!data.audioContent) throw new Error("Inworld TTS returned no audio");
+  return { base64: data.audioContent, format: "mp3" };
+}
+
+// Cartesia: X-API-Key header
+async function cartesia({ baseUrl, apiKey, text, modelId, voiceId }) {
+  const res = await fetch(baseUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey,
+      "Cartesia-Version": "2024-06-10",
+    },
+    body: JSON.stringify({
+      model_id: modelId || "sonic-2",
+      transcript: text,
+      ...(voiceId ? { voice: { mode: "id", id: voiceId } } : {}),
+      output_format: { container: "mp3", bit_rate: 128000, sample_rate: 44100 },
+    }),
+  });
+  if (!res.ok) await throwUpstreamError(res);
+  return responseToBase64(res, "mp3");
+}
+
+// PlayHT: token format "userId:apiKey", voice = s3 URL
+async function playht({ baseUrl, apiKey, text, modelId, voiceId }) {
+  const [userId, key] = (apiKey || ":").split(":");
+  const res = await fetch(baseUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Accept": "audio/mpeg",
+      "X-USER-ID": userId || "",
+      "Authorization": `Bearer ${key || apiKey}`,
+    },
+    body: JSON.stringify({
+      text,
+      voice: voiceId || "s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json",
+      voice_engine: modelId || "PlayDialog",
+      output_format: "mp3",
+      speed: 1,
+    }),
+  });
+  if (!res.ok) await throwUpstreamError(res);
+  return responseToBase64(res, "mp3");
+}
+
+// Coqui (local, noAuth): POST { text, speaker_id } → WAV
+async function coqui({ baseUrl, text, voiceId }) {
+  const res = await fetch(baseUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ text, ...(voiceId ? { speaker_id: voiceId } : {}) }),
+  });
+  if (!res.ok) await throwUpstreamError(res);
+  return responseToBase64(res, "wav");
+}
+
+// Tortoise (local, noAuth)
+async function tortoise({ baseUrl, text, voiceId }) {
+  const res = await fetch(baseUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ text, voice: voiceId || "random" }),
+  });
+  if (!res.ok) await throwUpstreamError(res);
+  return responseToBase64(res, "wav");
+}
+
+// OpenAI-compatible upstream (qwen3-tts, etc.)
+async function openaiCompat({ baseUrl, apiKey, text, modelId, voiceId }) {
+  const headers = { "Content-Type": "application/json" };
+  if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+  const res = await fetch(baseUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      model: modelId,
+      input: text,
+      voice: voiceId || "alloy",
+      response_format: "mp3",
+      speed: 1.0,
+    }),
+  });
+  if (!res.ok) await throwUpstreamError(res);
+  return responseToBase64(res, "mp3");
+}
+
+// format → handler dispatcher
+export const FORMAT_HANDLERS = {
+  hyperbolic,
+  deepgram,
+  "nvidia-tts": nvidia,
+  "huggingface-tts": huggingface,
+  inworld,
+  cartesia,
+  playht,
+  coqui,
+  tortoise,
+  openai: openaiCompat,
+  "minimax-tts": minimaxTts,
+};
diff --git a/open-sse/handlers/ttsProviders/googleTts.js b/open-sse/handlers/ttsProviders/googleTts.js
new file mode 100644
index 0000000..b77f6d7
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/googleTts.js
@@ -0,0 +1,54 @@
+// Google Translate TTS (no auth) — scrape token + batchexecute RPC
+import { UA } from "./_base.js";
+
+const REFRESH_MS = 11 * 60 * 1000;
+const cache = { token: null, tokenTime: 0 };
+let _idx = 0;
+
+async function getToken() {
+  const now = Date.now();
+  if (cache.token && now - cache.tokenTime < REFRESH_MS) return cache.token;
+  const res = await fetch("https://translate.google.com/", { headers: { "User-Agent": UA } });
+  if (!res.ok) throw new Error(`Google translate fetch failed: ${res.status}`);
+  const html = await res.text();
+  const fSid = html.match(/"FdrFJe":"(.*?)"/)?.[1];
+  const bl = html.match(/"cfb2h":"(.*?)"/)?.[1];
+  if (!fSid || !bl) throw new Error("Failed to parse Google token");
+  cache.token = { "f.sid": fSid, bl };
+  cache.tokenTime = now;
+  return cache.token;
+}
+
+export default {
+  noAuth: true,
+  async synthesize(text, model) {
+    const lang = model || "en";
+    const token = await getToken();
+    const cleanText = text.replace(/[@^*()\\/\-_+=><"'\u201c\u201d\u3010\u3011]/g, " ").replaceAll(", ", ". ");
+    const rpcId = "jQ1olc";
+    const reqId = (++_idx * 100000) + Math.floor(1000 + Math.random() * 9000);
+    const query = new URLSearchParams({
+      rpcids: rpcId,
+      "f.sid": token["f.sid"],
+      bl: token.bl,
+      hl: lang,
+      "soc-app": 1, "soc-platform": 1, "soc-device": 1,
+      _reqid: reqId,
+      rt: "c",
+    });
+    const payload = [cleanText, lang, null, "undefined", [0]];
+    const body = new URLSearchParams();
+    body.append("f.req", JSON.stringify([[[rpcId, JSON.stringify(payload), null, "generic"]]]));
+    const res = await fetch(`https://translate.google.com/_/TranslateWebserverUi/data/batchexecute?${query}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", "Referer": "https://translate.google.com/" },
+      body: body.toString(),
+    });
+    if (!res.ok) throw new Error(`Google TTS failed: ${res.status}`);
+    const data = await res.text();
+    const split = JSON.parse(data.split("\n")[3]);
+    const base64 = JSON.parse(split[0][2])[0];
+    if (!base64 || base64.length < 100) throw new Error("Google TTS returned empty audio");
+    return { base64, format: "mp3" };
+  },
+};
diff --git a/open-sse/handlers/ttsProviders/index.js b/open-sse/handlers/ttsProviders/index.js
new file mode 100644
index 0000000..e1bb8b8
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/index.js
@@ -0,0 +1,52 @@
+// TTS provider registry
+import googleTts from "./googleTts.js";
+import edgeTts, { fetchEdgeTtsVoices } from "./edgeTts.js";
+import localDevice, { fetchLocalDeviceVoices } from "./localDevice.js";
+import elevenlabs, { fetchElevenLabsVoices } from "./elevenlabs.js";
+import openai from "./openai.js";
+import openrouter from "./openrouter.js";
+import gemini, { fetchGeminiVoices } from "./gemini.js";
+import { FORMAT_HANDLERS } from "./genericFormats.js";
+import { parseModelVoice } from "./_base.js";
+
+// Special providers with custom synthesize() logic
+const SPECIAL_ADAPTERS = {
+  "google-tts": googleTts,
+  "edge-tts": edgeTts,
+  "local-device": localDevice,
+  elevenlabs,
+  openai,
+  openrouter,
+  gemini,
+};
+
+export function getTtsAdapter(provider) {
+  return SPECIAL_ADAPTERS[provider] || null;
+}
+
+// Generic config-driven dispatcher (uses ttsConfig.format)
+export async function synthesizeViaConfig(provider, text, model, credentials) {
+  const { AI_PROVIDERS } = await import("@/shared/constants/providers");
+  const cfg = AI_PROVIDERS[provider]?.ttsConfig;
+  if (!cfg) return null;
+  const handler = FORMAT_HANDLERS[cfg.format];
+  if (!handler) return null;
+  const apiKey = credentials?.apiKey;
+  if (cfg.authType !== "none" && !apiKey) throw new Error(`${provider} API key required`);
+  const { PROVIDER_MODELS } = await import("open-sse/config/providerModels.js");
+  const ttsModels = (PROVIDER_MODELS[provider] || []).filter(m => (m.kind || m.type) === "tts");
+  const defaultModel = ttsModels[0]?.id || "";
+  const { modelId, voiceId } = parseModelVoice(model, defaultModel, "", ttsModels);
+  return handler({ baseUrl: cfg.baseUrl, apiKey, text, modelId, voiceId });
+}
+
+// Voice fetchers (used by /api/media-providers/tts/voices route)
+export const VOICE_FETCHERS = {
+  "edge-tts": fetchEdgeTtsVoices,
+  "local-device": fetchLocalDeviceVoices,
+  elevenlabs: fetchElevenLabsVoices,
+  gemini: fetchGeminiVoices,
+};
+
+// Re-export for backward compat
+export { fetchEdgeTtsVoices, fetchLocalDeviceVoices, fetchElevenLabsVoices, fetchGeminiVoices };
diff --git a/open-sse/handlers/ttsProviders/localDevice.js b/open-sse/handlers/ttsProviders/localDevice.js
new file mode 100644
index 0000000..74c5930
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/localDevice.js
@@ -0,0 +1,87 @@
+// Local device TTS — macOS `say` + Windows SAPI + ffmpeg
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const execFileAsync = promisify(execFile);
+
+let _voicesCache = null;
+
+async function fetchVoicesMac() {
+  const { stdout } = await execFileAsync("say", ["-v", "?"]);
+  const voices = [];
+  for (const line of stdout.split("\n")) {
+    const m = line.match(/^([^\s].*?)\s{2,}([a-z]{2}_[A-Z]{2})/);
+    if (!m) continue;
+    const name = m[1].trim();
+    const locale = m[2].trim();
+    const lang = locale.split("_")[0];
+    const country = locale.split("_")[1];
+    voices.push({ id: name, name, locale, lang, country, gender: "" });
+  }
+  return voices;
+}
+
+async function fetchVoicesWin() {
+  const script = [
+    "Add-Type -AssemblyName System.Speech;",
+    "$s = New-Object System.Speech.Synthesis.SpeechSynthesizer;",
+    "$s.GetInstalledVoices() | ForEach-Object { $v = $_.VoiceInfo;",
+    "[PSCustomObject]@{ Name=$v.Name; Culture=$v.Culture.Name; Gender=$v.Gender } }",
+    "| ConvertTo-Json -Compress",
+  ].join(" ");
+  const { stdout } = await execFileAsync(
+    "powershell.exe",
+    ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", script],
+    { windowsHide: true }
+  );
+  const raw = JSON.parse(stdout.trim() || "[]");
+  const list = Array.isArray(raw) ? raw : [raw];
+  return list.map((v) => {
+    const culture = v.Culture || "en-US";
+    const [lang, country = ""] = culture.split("-");
+    const genderMap = { 1: "Male", 2: "Female", Male: "Male", Female: "Female" };
+    return {
+      id: v.Name, name: v.Name,
+      locale: culture.replace("-", "_"),
+      lang, country,
+      gender: genderMap[v.Gender] || "",
+    };
+  });
+}
+
+export async function fetchLocalDeviceVoices() {
+  if (_voicesCache) return _voicesCache;
+  try {
+    const voices = process.platform === "win32" ? await fetchVoicesWin() : await fetchVoicesMac();
+    _voicesCache = voices;
+    return voices;
+  } catch {
+    return [];
+  }
+}
+
+async function synthesizeMacOrWin(text, voiceId) {
+  const dir = await mkdtemp(join(tmpdir(), "tts-"));
+  const aiffPath = join(dir, "out.aiff");
+  const mp3Path = join(dir, "out.mp3");
+  try {
+    const args = voiceId ? ["-v", voiceId, "-o", aiffPath, text] : ["-o", aiffPath, text];
+    await execFileAsync("say", args);
+    await execFileAsync("ffmpeg", ["-y", "-i", aiffPath, "-codec:a", "libmp3lame", "-qscale:a", "4", mp3Path]);
+    const buf = await readFile(mp3Path);
+    return buf.toString("base64");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+export default {
+  noAuth: true,
+  async synthesize(text, model) {
+    const base64 = await synthesizeMacOrWin(text, model);
+    return { base64, format: "mp3" };
+  },
+};
diff --git a/open-sse/handlers/ttsProviders/minimax.js b/open-sse/handlers/ttsProviders/minimax.js
new file mode 100644
index 0000000..b435e2b
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/minimax.js
@@ -0,0 +1,59 @@
+import { Buffer } from "node:buffer";
+
+function hexToBase64(audioHex) {
+  const clean = typeof audioHex === "string" ? audioHex.trim() : "";
+  if (!clean) throw new Error("MiniMax TTS returned no audio");
+  if (clean.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(clean)) {
+    throw new Error("MiniMax TTS returned invalid audio");
+  }
+  return Buffer.from(clean, "hex").toString("base64");
+}
+
+// MiniMax T2A HTTP: returns hex-encoded audio in non-streaming mode.
+export default async function minimaxTts({ baseUrl, apiKey, text, modelId, voiceId }) {
+  const res = await fetch(baseUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
+    body: JSON.stringify({
+      model: modelId || "speech-2.8-hd",
+      text,
+      stream: false,
+      language_boost: "auto",
+      output_format: "hex",
+      voice_setting: {
+        voice_id: voiceId || "English_expressive_narrator",
+        speed: 1,
+        vol: 1,
+        pitch: 0,
+      },
+      audio_setting: {
+        sample_rate: 32000,
+        bitrate: 128000,
+        format: "mp3",
+        channel: 1,
+      },
+    }),
+  });
+
+  const rawText = await res.text();
+  let data = {};
+  if (rawText) {
+    try { data = JSON.parse(rawText); } catch { data = {}; }
+  }
+
+  const baseResp = data.base_resp || data.baseResp || {};
+  const statusCode = Number(baseResp.status_code ?? baseResp.statusCode ?? 0);
+  const statusMessage = baseResp.status_msg || baseResp.statusMsg || data.message || "";
+
+  if (!res.ok) {
+    throw new Error(statusMessage || rawText || `MiniMax TTS error (${res.status})`);
+  }
+  if (statusCode !== 0) {
+    throw new Error(statusMessage || "MiniMax TTS upstream error");
+  }
+
+  return {
+    base64: hexToBase64(data.data?.audio),
+    format: data.extra_info?.audio_format || data.extraInfo?.audioFormat || "mp3",
+  };
+}
diff --git a/open-sse/handlers/ttsProviders/openai.js b/open-sse/handlers/ttsProviders/openai.js
new file mode 100644
index 0000000..b1f680a
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/openai.js
@@ -0,0 +1,33 @@
+// OpenAI TTS — model format: "tts-model/voice"
+import { Buffer } from "node:buffer";
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const DEFAULT_TTS_MODEL = PROVIDER_MEDIA["openai"]?.ttsConfig?.defaultModel;
+
+export default {
+  async synthesize(text, model, credentials) {
+    if (!credentials?.apiKey) throw new Error("No OpenAI API key configured");
+
+    let ttsModel = DEFAULT_TTS_MODEL;
+    let voice = "alloy";
+    if (model && model.includes("/")) {
+      const parts = model.split("/");
+      if (parts.length === 2) [ttsModel, voice] = parts;
+    } else if (model) {
+      voice = model;
+    }
+
+    const baseUrl = (credentials.baseUrl || "https://api.openai.com").replace(/\/+$/, "");
+    const res = await fetch(`${baseUrl}/v1/audio/speech`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Authorization": `Bearer ${credentials.apiKey}` },
+      body: JSON.stringify({ model: ttsModel, voice, input: text }),
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err?.error?.message || `OpenAI TTS failed: ${res.status}`);
+    }
+    const buf = await res.arrayBuffer();
+    return { base64: Buffer.from(buf).toString("base64"), format: "mp3" };
+  },
+};
diff --git a/open-sse/handlers/ttsProviders/openrouter.js b/open-sse/handlers/ttsProviders/openrouter.js
new file mode 100644
index 0000000..84fac0c
--- /dev/null
+++ b/open-sse/handlers/ttsProviders/openrouter.js
@@ -0,0 +1,73 @@
+// OpenRouter TTS — via chat completions + audio modality (SSE stream)
+import { PROVIDER_MEDIA } from "../../providers/index.js";
+
+const TTS_CFG = PROVIDER_MEDIA["openrouter"]?.ttsConfig || {};
+
+export default {
+  async synthesize(text, model, credentials) {
+    if (!credentials?.apiKey) throw new Error("No OpenRouter API key configured");
+
+    // model format: "tts-model/voice" e.g. "openai/gpt-4o-mini-tts/alloy"
+    let ttsModel = TTS_CFG.defaultModel;
+    let voice = "alloy";
+    if (model && model.includes("/")) {
+      const lastSlash = model.lastIndexOf("/");
+      const maybVoice = model.slice(lastSlash + 1);
+      const maybeModel = model.slice(0, lastSlash);
+      if (maybeModel.includes("/")) {
+        ttsModel = maybeModel;
+        voice = maybVoice;
+      } else {
+        voice = model;
+      }
+    } else if (model) {
+      voice = model;
+    }
+
+    const res = await fetch(TTS_CFG.baseUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${credentials.apiKey}`,
+        ...(TTS_CFG.headers || {}),
+      },
+      body: JSON.stringify({
+        model: ttsModel,
+        modalities: ["text", "audio"],
+        audio: { voice, format: "wav" },
+        stream: true,
+        messages: [{ role: "user", content: text }],
+      }),
+    });
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err?.error?.message || `OpenRouter TTS failed: ${res.status}`);
+    }
+
+    // Parse SSE stream, accumulate base64 audio chunks
+    const chunks = [];
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop();
+      for (const line of lines) {
+        if (!line.startsWith("data: ") || line === "data: [DONE]") continue;
+        try {
+          const json = JSON.parse(line.slice(6));
+          const audioData = json.choices?.[0]?.delta?.audio?.data;
+          if (audioData) chunks.push(audioData);
+        } catch {}
+      }
+    }
+
+    if (chunks.length === 0) throw new Error("OpenRouter TTS returned no audio data");
+    return { base64: chunks.join(""), format: "wav" };
+  },
+};
diff --git a/open-sse/index.js b/open-sse/index.js
new file mode 100644
index 0000000..b8181f0
--- /dev/null
+++ b/open-sse/index.js
@@ -0,0 +1,79 @@
+// Patch global fetch with proxy support (must be first)
+import "./utils/proxyFetch.js";
+
+// Config
+export { PROVIDERS } from "./config/providers.js";
+export { OAUTH_ENDPOINTS, CLAUDE_SYSTEM_PROMPT } from "./config/appConstants.js";
+export { CACHE_TTL, DEFAULT_MAX_TOKENS, COOLDOWN_MS, BACKOFF_CONFIG } from "./config/runtimeConfig.js";
+export { 
+  PROVIDER_MODELS, 
+  getProviderModels,
+  getDefaultModel, 
+  isValidModel,
+  findModelName,
+  getModelTargetFormat,
+  PROVIDER_ID_TO_ALIAS,
+  getModelsByProviderId
+} from "./config/providerModels.js";
+
+// Translator
+export { FORMATS } from "./translator/formats.js";
+export { 
+  register, 
+  translateRequest, 
+  translateResponse, 
+  needsTranslation, 
+  initState, 
+  initTranslators 
+} from "./translator/index.js";
+
+// Services
+export { 
+  detectFormat, 
+  getTargetFormat 
+} from "./services/provider.js";
+
+export { parseModel, resolveModelAliasFromMap, getModelInfoCore } from "./services/model.js";
+
+export {
+  checkFallbackError,
+  isAccountUnavailable,
+  getUnavailableUntil,
+  filterAvailableAccounts
+} from "./services/accountFallback.js";
+
+export {
+  TOKEN_EXPIRY_BUFFER_MS,
+  refreshAccessToken,
+  refreshClaudeOAuthToken,
+  refreshGoogleToken,
+  refreshQwenToken,
+  refreshCodexToken,
+  refreshIflowToken,
+  refreshGitHubToken,
+  refreshCopilotToken,
+  getAccessToken,
+  refreshTokenByProvider
+} from "./services/tokenRefresh.js";
+
+export {
+  CODEX_MAX_REFRESH_AGE_MS,
+  shouldRefreshCredentials,
+  refreshProviderCredentials,
+  mergeRefreshedCredentials,
+  mergeProviderSpecificData,
+} from "./services/oauthCredentialManager.js";
+
+// Handlers
+export { handleChatCore, isTokenExpiringSoon } from "./handlers/chatCore.js";
+export { createStreamController, pipeWithDisconnect, createDisconnectAwareStream } from "./utils/streamHandler.js";
+
+// Executors
+export { getExecutor, hasSpecializedExecutor } from "./executors/index.js";
+
+// Utils
+export { errorResponse, formatProviderError } from "./utils/error.js";
+export { 
+  createSSETransformStreamWithLogger, 
+  createPassthroughStreamWithLogger 
+} from "./utils/stream.js";
diff --git a/open-sse/providers/REGISTRY_TEMPLATE.js b/open-sse/providers/REGISTRY_TEMPLATE.js
new file mode 100644
index 0000000..66875cd
--- /dev/null
+++ b/open-sse/providers/REGISTRY_TEMPLATE.js
@@ -0,0 +1,98 @@
+/**
+ * REGISTRY ENTRY TEMPLATE — copy into registry/{id}.js when adding a new provider.
+ *
+ * NOT imported by registry/index.js (lives outside registry/, static-import list ignores it).
+ * Delete every block your provider does not need. Only `id` + `category` are required.
+ * Field contract: see schema.js `@typedef RegistryEntry`. Runtime builders: providers/index.js.
+ *
+ * Quick recipes:
+ *   - Plain API-key LLM      → id, alias, category:"apikey", display, transport{baseUrl}, models.
+ *   - OAuth LLM (device/PKCE)→ add oauth{...}; clientId/tokenUrl auto-inject into transport.
+ *   - Media-only (tts/stt/…) → drop `models`+chat baseUrl, fill media{serviceKinds, *Config}.
+ */
+
+// import { CLAUDE_API_HEADERS, GOOGLE_OAUTH_CLIENT, OPENAI_COMPAT_BASE } from "./shared.js";
+
+export default {
+  // ── identity ────────────────────────────────────────────────────────────
+  id: "example",                 // REQUIRED. kebab-case, unique.
+  alias: "ex",                   // short key for PROVIDER_MODELS (defaults to id if omitted).
+  aliases: ["example-ai"],       // optional extra lookup tokens.
+  uiAlias: "ex",                 // optional UI badge token.
+  category: "apikey",            // REQUIRED. "apikey" | "oauth" | "freeTier" | ...
+
+  // ── auth hints (only when relevant) ──────────────────────────────────────
+  authType: "apikey",            // "apikey" | "oauth".
+  hasOAuth: false,               // true if an OAuth flow exists.
+  authModes: ["apikey"],         // e.g. ["oauth","apikey"] when both supported.
+  // noAuth: true,               // local/free providers needing no credential.
+
+  // ── UI display ───────────────────────────────────────────────────────────
+  display: {
+    name: "Example",
+    icon: "bolt",                // material icon name OR textIcon fallback.
+    color: "#3B82F6",
+    textIcon: "EX",
+    website: "https://example.com",
+    notice: { apiKeyUrl: "https://example.com/keys" }, // or signupUrl.
+    // deprecated: true, deprecationNotice: "RISK_NOTICE",
+    // kindNotice: { image: "Requires paid plan." },
+    // mediaPriority: 1,
+  },
+
+  // ── transport (HTTP runtime) → PROVIDERS[id] ─────────────────────────────
+  // Defaults applied: format:"openai". Declare ONLY what differs.
+  transport: {
+    baseUrl: "https://api.example.com/v1/chat/completions",
+    format: "openai",            // "openai" | "claude" | "gemini" | "openai-responses" | ...
+    // validateUrl: "https://api.example.com/v1/models",
+    // headers: { "User-Agent": "..." },           // static fingerprint (anti-ban) lives here.
+    // auth: { header: "x-api-key", scheme: "raw" },
+    // forceStream: true, urlSuffix: "?beta=true",
+    // quirks: { dropOutputConfig: true },
+    // retry: { 429: { attempts: 6 }, 503: { attempts: 3 } },
+    // usage: { url: "https://api.example.com/usage" }, // or { urls: [...] } for multi-call.
+    // modelsFetcher: { url: "https://api.example.com/models", type: "openai" }, // dynamic model list.
+    // regions: { sgp: "https://sgp...", cn: "https://cn..." }, defaultRegion: "sgp",
+    // NOTE: clientId/clientSecret/tokenUrl are injected from `oauth` — do NOT duplicate here.
+  },
+
+  // ── oauth flow → PROVIDER_OAUTH[id] (omit for pure API-key) ───────────────
+  // oauth: {
+  //   clientId: "app_xxx",
+  //   authorizeUrl: "https://auth.example.com/oauth/authorize", // PKCE/code flow.
+  //   tokenUrl: "https://auth.example.com/oauth/token",
+  //   deviceCodeUrl: "https://auth.example.com/device",          // device-code flow.
+  //   refreshUrl: "https://auth.example.com/oauth/token",
+  //   scope: "openid profile offline_access",                    // or scopes: [...].
+  //   codeChallengeMethod: "S256",
+  //   redirectUri: "http://127.0.0.1:1455/auth/callback", fixedPort: 1455, callbackPath: "/auth/callback",
+  //   extraParams: { foo: "bar" },
+  //   refresh: { encoding: "form", scope: "openid offline_access" }, // "form" | "json".
+  //   refreshLeadMs: 300000,
+  //   userInfoUrl: "https://example.com/userinfo",
+  // },
+
+  // ── media (non-LLM services) → PROVIDER_MEDIA[id] ────────────────────────
+  // media: {
+  //   serviceKinds: ["llm", "tts", "stt", "embedding", "image", "imageToText", "webSearch"],
+  //   ttsConfig:       { baseUrl: "...", authType: "apikey", authHeader: "bearer", format: "openai", defaultModel: "tts-1", models: [{ id: "tts-1", name: "TTS-1" }] },
+  //   sttConfig:       { baseUrl: "...", authType: "apikey", authHeader: "bearer", format: "openai", models: [{ id: "whisper-1", name: "Whisper" }] },
+  //   embeddingConfig: { baseUrl: "...", authType: "apikey", authHeader: "bearer", models: [{ id: "emb-1", name: "Emb", dimensions: 1536 }] },
+  //   imageConfig:     { baseUrl: "https://api.example.com/v1/images/generations" },
+  //   searchViaChat:   { defaultModel: "ex-search", pricingUrl: "https://example.com/pricing" },
+  //   // hiddenKinds: ["image"],
+  // },
+
+  // ── models (omit = no key; [] = explicit empty) ──────────────────────────
+  models: [
+    { id: "example-large", name: "Example Large" },
+    // { id: "example-img", name: "Example Image", type: "image", capabilities: ["text2img"], params: ["size"] },
+    // { id: "example-emb", name: "Example Embed", type: "embedding" },
+  ],
+
+  // ── optional flags ───────────────────────────────────────────────────────
+  // features: { usage: true },
+  // thinkingConfig: { options: ["auto", "none", "low", "high"], defaultMode: "auto" },
+  // passthroughModels: true,
+};
diff --git a/open-sse/providers/capabilities.js b/open-sse/providers/capabilities.js
new file mode 100644
index 0000000..3d30262
--- /dev/null
+++ b/open-sse/providers/capabilities.js
@@ -0,0 +1,293 @@
+// Model capabilities — what each model can read/do beyond plain text.
+//
+// Fallback order (first match wins), result merged over DEFAULT_CAPABILITIES:
+//   1. PROVIDER_CAPABILITIES[provider][model]  — provider-specific override
+//   2. MODEL_CAPABILITIES[model]               — canonical exact id (handles exceptions)
+//   3. PATTERN_CAPABILITIES                     — glob match, ordered specific -> generic
+//   4. DEFAULT_CAPABILITIES                     — safe floor (always returned)
+//
+// ── HOW TO ADD / UPDATE A MODEL ──────────────────────────────────────
+// Authoritative data source: https://models.dev/api.json (145 providers, 4000+
+// models, MIT). Each model exposes the exact fields we map below:
+//   modalities.input  ["text","image","pdf","audio","video"] -> vision / pdf / audioInput / videoInput
+//   modalities.output ["text","image","audio"]               -> imageOutput / audioOutput
+//   reasoning   -> reasoning      tool_call    -> tools
+//   limit.context -> contextWindow   limit.output -> maxOutput
+// Look up the model id, then:
+//   • If a PATTERN below already covers it correctly -> nothing to do.
+//   • If it is an exception (pattern would mis-match) -> add an exact entry to
+//     MODEL_CAPABILITIES (only the fields that differ from DEFAULT).
+//   • If a whole new family -> add an ordered PATTERN (specific before generic).
+// NOTE: models.dev has NO "search" flag (web search is a runtime tool, not a
+// model spec); set `search` from vendor docs (Claude 4.x+, GPT-5.x/4o, Gemini
+// 2.0+, Grok, Perplexity). Verify with: curl -s https://models.dev/api.json
+
+import { matchPattern } from "./pricing.js";
+
+/**
+ * Safe floor — every resolved result is merged over this so consumers
+ * never need null-checks. Most modern LLMs meet these limits.
+ */
+export const DEFAULT_CAPABILITIES = {
+  // input modalities
+  vision: false,        // read images
+  pdf: false,           // read PDF / documents
+  audioInput: false,    // read audio
+  videoInput: false,    // read video
+  // output modalities
+  imageOutput: false,   // generate images
+  audioOutput: false,   // generate audio
+  // features
+  search: false,        // built-in web search tool / grounding
+  tools: true,          // function / tool calling
+  reasoning: false,     // thinking / reasoning
+  // thinking wire format (only meaningful when reasoning:true). null → derive from transport.format.
+  // enum: openai|claude-adaptive|claude-budget|gemini-level|gemini-budget|zai|qwen|deepseek|kimi|minimax|hunyuan|step
+  thinkingFormat: null,
+  thinkingCanDisable: true,  // false → model cannot turn thinking off (clamp to min instead of disable)
+  thinkingRange: null,       // { min, max } for budget formats; null = no clamp
+  // limits (tokens)
+  contextWindow: 200000,
+  maxOutput: 64000,
+};
+
+// User-added model metadata can carry dashboard service kinds instead of the
+// runtime capability names used here. Map those typed model kinds into input /
+// output capabilities so custom vision models are not treated as text-only.
+const SERVICE_KIND_CAPABILITIES = {
+  imageToText: { vision: true },
+  image: { imageOutput: true },
+  stt: { audioInput: true },
+  tts: { audioOutput: true },
+  embedding: { tools: false },
+};
+
+export function capabilitiesFromServiceKind(kind) {
+  return SERVICE_KIND_CAPABILITIES[kind] || null;
+}
+
+/**
+ * Canonical exact-id overrides — used for exceptions that patterns would
+ * otherwise mis-match. Only declare deltas vs DEFAULT.
+ */
+export const MODEL_CAPABILITIES = {
+  // Claude 4.6/4.7/4.8 and Kiro Sonnet 5 have 1M context + adaptive thinking (override generic claude pattern)
+  "claude-opus-4.6":   { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-opus-4.7":   { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-opus-4-7":   { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-opus-4.8":   { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-opus-4-6":   { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-opus-4-8":   { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-opus-4.8-thinking": { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-opus-4-8-thinking": { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-sonnet-4.6": { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-sonnet-4-6": { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-sonnet-5": { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-sonnet-5-thinking": { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-sonnet-5-agentic": { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+  "claude-sonnet-5-thinking-agentic": { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive", contextWindow: 1000000, maxOutput: 128000 },
+
+  // Gemini image-gen / OpenAI image / xai image variants
+  "gpt-image-1":       { imageOutput: true, tools: false },
+
+  // GLM vision variant (text GLM has no vision)
+  "glm-4.6v":          { vision: true, reasoning: true, thinkingFormat: "zai", contextWindow: 128000 },
+
+  // Qwen plain coder/text (no vision) — registry "vision-model" / "coder-model" aliases
+  "vision-model":      { vision: true, reasoning: true, thinkingFormat: "qwen", contextWindow: 1000000 },
+  "coder-model":       { reasoning: true, thinkingFormat: "qwen", contextWindow: 1000000 },
+};
+
+/**
+ * Provider-specific capability overrides. Keyed by provider alias/id.
+ */
+export const PROVIDER_CAPABILITIES = {
+  // NVIDIA NIM is OpenAI-compatible → rejects MiniMax/GLM native `thinking` field.
+  // Force openai reasoning_effort format for its reasoning models. #issue
+  "nvidia": {
+    "minimaxai/minimax-m2.7": { reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 200000, maxOutput: 131072 },
+    "minimaxai/minimax-m3": { vision: true, reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 512000, maxOutput: 131072 },
+    "z-ai/glm-5.2": { reasoning: true, thinkingFormat: "openai", contextWindow: 200000, maxOutput: 128000 },
+    "deepseek-ai/deepseek-v4-pro": { reasoning: true, thinkingFormat: "openai", contextWindow: 1000000, maxOutput: 65536 },
+    "deepseek-ai/deepseek-v4-flash": { reasoning: true, thinkingFormat: "openai", contextWindow: 1000000, maxOutput: 65536 },
+  },
+  // CodeBuddy.cn — authoritative per-model metadata from the gateway's model
+  // config (contextWindow=maxInputTokens, maxOutput=maxOutputTokens, vision=
+  // supportsImages). Every model reasons via OpenAI-style reasoning_effort
+  // (see registry thinkingFormat). `onlyReasoning` models can't turn thinking
+  // off → thinkingCanDisable:false (clamped to minimal instead of disabled).
+  "codebuddy-cn": {
+    "glm-5.2":            { reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 1000000, maxOutput: 48000 },
+    "glm-5.1":            { reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 200000, maxOutput: 48000 },
+    "glm-5.0":            { reasoning: true, thinkingFormat: "openai", contextWindow: 200000, maxOutput: 48000 },
+    "glm-5.0-turbo":      { reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 200000, maxOutput: 48000 },
+    "glm-5v-turbo":       { vision: true, reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 200000, maxOutput: 38000 },
+    "glm-4.7":            { reasoning: true, thinkingFormat: "openai", contextWindow: 200000, maxOutput: 48000 },
+    "minimax-m3":         { vision: true, reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 512000, maxOutput: 48000 },
+    "minimax-m2.7":       { vision: true, reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 200000, maxOutput: 48000 },
+    "kimi-k2.7":          { vision: true, reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 256000, maxOutput: 32000 },
+    "kimi-k2.6":          { vision: true, reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 256000, maxOutput: 32000 },
+    "kimi-k2.5":          { vision: true, reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 164000, maxOutput: 32000 },
+    "hy3-preview":        { vision: true, reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 192000, maxOutput: 64000 },
+    "deepseek-v4-pro":    { vision: true, reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 1000000, maxOutput: 50000 },
+    "deepseek-v4-flash":  { vision: true, reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 1000000, maxOutput: 50000 },
+    "deepseek-v3-2-volc": { reasoning: true, thinkingFormat: "openai", thinkingCanDisable: false, contextWindow: 96000, maxOutput: 32000 },
+  },
+};
+
+/**
+ * Pattern fallback — glob (* = wildcard), matched case-insensitively and
+ * anchored (^...$) so a pattern must match the full model id. ORDER MATTERS:
+ * vision/specific variants first, text-only/generic families last, to avoid
+ * a broad family pattern swallowing an exception (e.g. glm-4.6v vs glm-5).
+ */
+export const PATTERN_CAPABILITIES = [
+  // ── Claude (4.6+ = adaptive thinking; older/haiku = budget) ──────
+  { pattern: "*claude*opus-4.6*",   caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive" } },
+  { pattern: "*claude*opus-4.7*",   caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive" } },
+  { pattern: "*claude*opus-4.8*",   caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive" } },
+  { pattern: "*claude*sonnet-4.6*", caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive" } },
+  { pattern: "*claude*sonnet-4.7*", caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-adaptive" } },
+  { pattern: "*claude*haiku*",  caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-budget" } },
+  { pattern: "*claude*opus*",   caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-budget" } },
+  { pattern: "*claude*sonnet*", caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-budget" } },
+  { pattern: "*claude*fable*",  caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-budget", contextWindow: 1000000, maxOutput: 128000 } },
+  { pattern: "*claude*mythos*", caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-budget", contextWindow: 1000000, maxOutput: 128000 } },
+  { pattern: "*claude-3*",      caps: { vision: true } },
+  { pattern: "*claude*",        caps: { vision: true, reasoning: true, search: true, thinkingFormat: "claude-budget" } },
+
+  // ── Gemini (all 2.0+ multimodal + google_search grounding, 1M ctx) ─
+  { pattern: "*gemini*image*",  caps: { vision: true, imageOutput: true, contextWindow: 1048576 } },
+  { pattern: "*gemini-3*pro*",  caps: { vision: true, audioInput: true, videoInput: true, reasoning: true, search: true, thinkingFormat: "gemini-level", thinkingCanDisable: false, contextWindow: 1048576, maxOutput: 65535 } },
+  { pattern: "*gemini-3*",      caps: { vision: true, audioInput: true, videoInput: true, reasoning: true, search: true, thinkingFormat: "gemini-level", thinkingCanDisable: false, contextWindow: 1048576, maxOutput: 65536 } },
+  { pattern: "*gemini-2.5*",    caps: { vision: true, audioInput: true, videoInput: true, reasoning: true, search: true, thinkingFormat: "gemini-budget", thinkingRange: { min: 0, max: 24576 }, contextWindow: 1048576, maxOutput: 65536 } },
+  { pattern: "*gemini-2*",      caps: { vision: true, audioInput: true, videoInput: true, search: true, contextWindow: 1048576, maxOutput: 65536 } },
+  { pattern: "*gemini*",        caps: { vision: true, search: true, contextWindow: 1048576 } },
+  { pattern: "*gemma*",         caps: { vision: true, contextWindow: 128000 } },
+  { pattern: "*nanobanana*",    caps: { vision: true, imageOutput: true } },
+
+  // ── OpenAI GPT-5.x (vision + thinking + web search) ──────────────
+  { pattern: "*gpt-5*image*",   caps: { imageOutput: true } },
+  { pattern: "*gpt-5*codex*",   caps: { reasoning: true, search: true, thinkingFormat: "openai", contextWindow: 400000, maxOutput: 128000 } },
+  { pattern: "*gpt-5*",         caps: { vision: true, reasoning: true, search: true, thinkingFormat: "openai", contextWindow: 400000, maxOutput: 128000 } },
+  { pattern: "*gpt-4o*",        caps: { vision: true, search: true, contextWindow: 128000, maxOutput: 16384 } },
+  { pattern: "*gpt-4.1*",       caps: { vision: true, contextWindow: 1000000, maxOutput: 32768 } },
+  { pattern: "*gpt-4-turbo*",   caps: { vision: true, contextWindow: 128000 } },
+  { pattern: "*gpt-4*",         caps: { contextWindow: 128000 } },
+  { pattern: "*gpt-3.5*",       caps: { contextWindow: 16385, maxOutput: 4096 } },
+  { pattern: "*gpt-oss*",       caps: { reasoning: true, thinkingFormat: "openai", contextWindow: 128000 } },
+
+  // ── OpenAI o-series (reasoning, vision) ──────────────────────────
+  { pattern: "*o1-mini*",       caps: { reasoning: true, thinkingFormat: "openai", contextWindow: 128000 } },
+  { pattern: "*o1*",            caps: { vision: true, reasoning: true, thinkingFormat: "openai", contextWindow: 200000, maxOutput: 100000 } },
+  { pattern: "*o3*",            caps: { vision: true, reasoning: true, thinkingFormat: "openai", contextWindow: 200000, maxOutput: 100000 } },
+  { pattern: "*o4*",            caps: { vision: true, reasoning: true, thinkingFormat: "openai", contextWindow: 200000, maxOutput: 100000 } },
+
+  // ── Grok (vision + Live Search) ──────────────────────────────────
+  { pattern: "*grok*image*",    caps: { imageOutput: true } },
+  { pattern: "*grok-code*",     caps: { reasoning: true, thinkingFormat: "openai", contextWindow: 256000 } },
+  // Grok 4.5 (Grok CLI / Grok Build): 500k context per cli-chat-proxy /v1/models
+  { pattern: "*grok-4.5*",      caps: { vision: true, reasoning: true, search: true, thinkingFormat: "openai", contextWindow: 500000, maxOutput: 64000 } },
+  { pattern: "*grok-4*",        caps: { vision: true, reasoning: true, search: true, thinkingFormat: "openai", contextWindow: 256000 } },
+  { pattern: "*grok-3*",        caps: { vision: true, reasoning: true, search: true, thinkingFormat: "openai", contextWindow: 131072 } },
+  { pattern: "*grok*",          caps: { vision: true, reasoning: true, search: true, thinkingFormat: "openai", contextWindow: 256000 } },
+
+  // ── Qwen (3.5+ = native vision/video; coder & max = text-only; QwQ = thinking-only) ─
+  { pattern: "*qwen*vl*",       caps: { vision: true, reasoning: true, thinkingFormat: "qwen", contextWindow: 262144 } },
+  { pattern: "*qwen*omni*",     caps: { vision: true, audioInput: true, videoInput: true, reasoning: true, thinkingFormat: "qwen", contextWindow: 262144, maxOutput: 65536 } },
+  { pattern: "*qwen*coder*",    caps: { reasoning: true, thinkingFormat: "qwen", contextWindow: 1000000 } },
+  { pattern: "*qwen*max*",      caps: { reasoning: true, thinkingFormat: "qwen", contextWindow: 1000000, maxOutput: 65536 } },
+  { pattern: "*qwen3.5*",       caps: { vision: true, videoInput: true, reasoning: true, thinkingFormat: "qwen", contextWindow: 1000000, maxOutput: 65536 } },
+  { pattern: "*qwen3.6*",       caps: { vision: true, videoInput: true, reasoning: true, thinkingFormat: "qwen", contextWindow: 1000000, maxOutput: 65536 } },
+  { pattern: "*qwen3.7*",       caps: { vision: true, videoInput: true, reasoning: true, thinkingFormat: "qwen", contextWindow: 1000000, maxOutput: 65536 } },
+  { pattern: "*qwen*plus*",     caps: { vision: true, reasoning: true, thinkingFormat: "qwen", contextWindow: 1000000, maxOutput: 65536 } },
+  { pattern: "*qwen*235b*",     caps: { reasoning: true, thinkingFormat: "qwen", contextWindow: 262144 } },
+  { pattern: "*qwq*",           caps: { reasoning: true, thinkingFormat: "qwen", thinkingCanDisable: false, contextWindow: 131072 } },
+  { pattern: "*qwen*",          caps: { reasoning: true, thinkingFormat: "qwen", contextWindow: 262144 } },
+
+  // ── Kimi (enabled→reasoning_effort; K2.7-code cannot disable) ─────
+  { pattern: "*kimi*k2.7*code*", caps: { vision: true, reasoning: true, thinkingFormat: "kimi", thinkingCanDisable: false, contextWindow: 262144, maxOutput: 262144 } },
+  { pattern: "*kimi*k2*",       caps: { vision: true, reasoning: true, thinkingFormat: "kimi", contextWindow: 262144, maxOutput: 262144 } },
+  { pattern: "*kimi*",          caps: { reasoning: true, thinkingFormat: "kimi", contextWindow: 262144 } },
+
+  // ── GLM / Z.ai (thinking.enabled; disable via enable_thinking:false) ─
+  { pattern: "*glm-5*",         caps: { reasoning: true, thinkingFormat: "zai", contextWindow: 200000, maxOutput: 128000 } },
+  { pattern: "*glm-4.7*",       caps: { reasoning: true, thinkingFormat: "zai", contextWindow: 200000, maxOutput: 128000 } },
+  { pattern: "*glm-4*",         caps: { reasoning: true, thinkingFormat: "zai", contextWindow: 200000 } },
+  { pattern: "*glm*",           caps: { reasoning: true, thinkingFormat: "zai", contextWindow: 200000 } },
+
+  // ── DeepSeek (thinking.enabled + reasoning_effort; r1 = thinking-only) ─
+  { pattern: "*deepseek-v4*",   caps: { reasoning: true, thinkingFormat: "deepseek", contextWindow: 1000000, maxOutput: 384000 } },
+  { pattern: "*reasoner*",      caps: { reasoning: true, thinkingFormat: "deepseek", thinkingCanDisable: false, contextWindow: 128000 } },
+  { pattern: "*deepseek-r*",    caps: { reasoning: true, thinkingFormat: "deepseek", thinkingCanDisable: false, contextWindow: 128000 } },
+  { pattern: "*deepseek-chat*", caps: { contextWindow: 128000 } },
+  { pattern: "*deepseek*",      caps: { reasoning: true, thinkingFormat: "deepseek", contextWindow: 128000 } },
+
+  // ── MiniMax (M3 = adaptive; M2.x cannot disable) ─────────────────
+  { pattern: "*minimax*image*", caps: { imageOutput: true } },
+  { pattern: "*minimax-m3*",    caps: { vision: true, reasoning: true, thinkingFormat: "minimax", contextWindow: 1048576, maxOutput: 512000 } },
+  { pattern: "*minimax-m2.7*",  caps: { reasoning: true, thinkingFormat: "minimax", thinkingCanDisable: false, contextWindow: 204800, maxOutput: 131072 } },
+  { pattern: "*minimax*",       caps: { reasoning: true, thinkingFormat: "minimax", thinkingCanDisable: false, contextWindow: 200000, maxOutput: 131072 } },
+
+  // ── Xiaomi MiMo (vision, 1M / 262K ctx) ──────────────────────────
+  { pattern: "*mimo*v2.5*",     caps: { vision: true, contextWindow: 1048576, maxOutput: 131072 } },
+  { pattern: "*mimo*omni*",     caps: { vision: true, audioInput: true, contextWindow: 262144, maxOutput: 131072 } },
+  { pattern: "*mimo*",          caps: { vision: true, contextWindow: 262144, maxOutput: 131072 } },
+
+  // ── Llama (4 = vision/1M; 3.x = text-only/128K) ──────────────────
+  { pattern: "*llama-4*",       caps: { vision: true, contextWindow: 1000000 } },
+  { pattern: "*llama*",         caps: { contextWindow: 128000 } },
+
+  // ── Mistral (Large 3 = vision/256K; codestral text) ──────────────
+  { pattern: "*codestral*",     caps: { contextWindow: 256000 } },
+  { pattern: "*mistral-large*", caps: { vision: true, contextWindow: 256000 } },
+  { pattern: "*mistral*",       caps: { contextWindow: 128000 } },
+
+  // ── Cohere (Command A Vision = vision; others text) ──────────────
+  { pattern: "*command-a-vision*", caps: { vision: true, contextWindow: 128000 } },
+  { pattern: "*command*",       caps: { contextWindow: 128000 } },
+
+  // ── Perplexity (web search native) ───────────────────────────────
+  { pattern: "*sonar*",         caps: { search: true, contextWindow: 128000 } },
+  { pattern: "*pplx*",          caps: { search: true, contextWindow: 128000 } },
+  { pattern: "*perplexity*",    caps: { search: true, contextWindow: 128000 } },
+
+  // ── Others ───────────────────────────────────────────────────────
+  { pattern: "*hunyuan*",       caps: { reasoning: true, thinkingFormat: "hunyuan", contextWindow: 262144, maxOutput: 262144 } },
+  { pattern: "hy3*",            caps: { reasoning: true, thinkingFormat: "hunyuan", contextWindow: 262144, maxOutput: 262144 } },
+  { pattern: "*step-*",         caps: { reasoning: true, thinkingFormat: "step", contextWindow: 128000 } },
+  { pattern: "*nemotron*",      caps: { reasoning: true, contextWindow: 128000 } },
+  { pattern: "*ling-*",         caps: { reasoning: true, contextWindow: 128000 } },
+];
+
+/**
+ * Resolve capabilities for a model using the 4-step fallback chain,
+ * merged over DEFAULT_CAPABILITIES so the result is always complete.
+ *
+ * @param {string} provider
+ * @param {string} model
+ * @returns {object} full capabilities object
+ */
+export function getCapabilitiesForModel(provider, model) {
+  if (!model) return { ...DEFAULT_CAPABILITIES };
+
+  // 1. Provider-specific override
+  if (provider && PROVIDER_CAPABILITIES[provider]?.[model]) {
+    return { ...DEFAULT_CAPABILITIES, ...PROVIDER_CAPABILITIES[provider][model] };
+  }
+
+  // 2. Canonical exact (strip vendor prefix: "anthropic/claude-opus-4.7" -> "claude-opus-4.7")
+  const baseModel = model.includes("/") ? model.split("/").pop() : model;
+  if (MODEL_CAPABILITIES[baseModel]) return { ...DEFAULT_CAPABILITIES, ...MODEL_CAPABILITIES[baseModel] };
+  if (MODEL_CAPABILITIES[model]) return { ...DEFAULT_CAPABILITIES, ...MODEL_CAPABILITIES[model] };
+
+  // 3. Pattern match (first match wins)
+  for (const { pattern, caps } of PATTERN_CAPABILITIES) {
+    if (matchPattern(pattern, baseModel) || matchPattern(pattern, model)) {
+      return { ...DEFAULT_CAPABILITIES, ...caps };
+    }
+  }
+
+  // 4. Floor
+  return { ...DEFAULT_CAPABILITIES };
+}
diff --git a/open-sse/providers/index.js b/open-sse/providers/index.js
new file mode 100644
index 0000000..ab5123b
--- /dev/null
+++ b/open-sse/providers/index.js
@@ -0,0 +1,51 @@
+// Single source: build PROVIDERS + PROVIDER_MODELS from registry/{id}.js (transport + models co-located).
+import REGISTRY from "./registry/index.js";
+import { PROVIDER_DEFAULTS } from "./schema.js";
+import { normalizeModel } from "./models/schema.js";
+import { buildTtsProviderModels } from "../config/ttsModels.js";
+
+// oauth block is canonical for these fields; inject into transport so executors reading
+// this.config.{clientId,clientSecret,tokenUrl} keep working without duplicating in transport
+const OAUTH_INJECT_FIELDS = ["clientId", "clientSecret", "tokenUrl"];
+
+// transport: re-apply shared default (format:"openai") + inject oauth-canonical fields
+function buildTransport(transport, oauth) {
+  const t = { ...transport };
+  if (!t.format) t.format = PROVIDER_DEFAULTS.format;
+  if (oauth) {
+    for (const f of OAUTH_INJECT_FIELDS) {
+      if (t[f] === undefined && oauth[f] !== undefined) t[f] = oauth[f];
+    }
+  }
+  return t;
+}
+
+const MEDIA_KEYS = new Set([
+  "serviceKinds", "ttsConfig", "sttConfig", "embeddingConfig",
+  "imageConfig", "imageToTextConfig", "videoConfig", "musicConfig",
+  "searchViaChat", "searchConfig", "fetchConfig",
+  "modelsFetcher", "mediaPriority", "hiddenKinds",
+]);
+
+export const PROVIDERS = {};
+export const PROVIDER_MODELS = {};
+export const PROVIDER_OAUTH = {};
+export const PROVIDER_MEDIA = {};
+for (const entry of REGISTRY) {
+  if (entry.transport) {
+    PROVIDERS[entry.id] = buildTransport(entry.transport, entry.oauth);
+    if (entry.transports) PROVIDERS[entry.id].transports = entry.transports;
+  }
+  if (entry.models !== undefined) PROVIDER_MODELS[entry.alias || entry.id] = entry.models.map(normalizeModel);
+  if (entry.oauth) PROVIDER_OAUTH[entry.id] = entry.oauth;
+  // Build PROVIDER_MEDIA from top-level fields (post-migration) + legacy entry.media
+  const mediaFields = {};
+  for (const k of MEDIA_KEYS) {
+    if (entry[k] !== undefined) mediaFields[k] = entry[k];
+  }
+  if (entry.media) Object.assign(mediaFields, entry.media);
+  if (Object.keys(mediaFields).length) PROVIDER_MEDIA[entry.id] = mediaFields;
+}
+
+// TTS model/voice tables keyed by special names (openai-tts-models, ...), not provider ids
+Object.assign(PROVIDER_MODELS, buildTtsProviderModels());
diff --git a/open-sse/providers/models/helpers.js b/open-sse/providers/models/helpers.js
new file mode 100644
index 0000000..a7d273d
--- /dev/null
+++ b/open-sse/providers/models/helpers.js
@@ -0,0 +1,20 @@
+// Codex auto-generates a "-review" variant for each llm model (review quota family)
+export const CODEX_REVIEW_SUFFIX = "-review";
+
+export function withCodexReviewModels(models) {
+  return models.flatMap((model) => {
+    if ((model.kind || model.type || "llm") !== "llm" || model.id.endsWith(CODEX_REVIEW_SUFFIX)) {
+      return [model];
+    }
+    return [
+      model,
+      {
+        ...model,
+        id: `${model.id}${CODEX_REVIEW_SUFFIX}`,
+        name: `${model.name} Review`,
+        upstreamModelId: model.upstreamModelId || model.id,
+        quotaFamily: "review"
+      }
+    ];
+  });
+}
diff --git a/open-sse/providers/models/namePatterns.js b/open-sse/providers/models/namePatterns.js
new file mode 100644
index 0000000..5e0548c
--- /dev/null
+++ b/open-sse/providers/models/namePatterns.js
@@ -0,0 +1,33 @@
+// Derive a display name from a model id when the entry omits `name` (mirrors PATTERN_PRICING).
+// Provider entries that ship their own `name` always win; this is only a fallback for terse entries.
+
+// Capitalize a hyphen/space separated token group: "coder-plus" → "Coder Plus".
+function titleCase(s) {
+  return s
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((w) => (/^\d/.test(w) ? w : w.charAt(0).toUpperCase() + w.slice(1)))
+    .join(" ");
+}
+
+// Ordered: first match wins. Keep specific patterns above generic ones.
+export const NAME_PATTERNS = [
+  [/^kimi-k(\d+(?:\.\d+)?)(-thinking)?$/i, (m) => `Kimi K${m[1]}${m[2] ? " Thinking" : ""}`],
+  [/^glm-(\d+(?:\.\d+)?)(v)?$/i, (m) => `GLM ${m[1]}${m[2] ? "V (Vision)" : ""}`],
+  [/^minimax-m(\d+(?:\.\d+)?)$/i, (m) => `MiniMax M${m[1]}`],
+  [/^gpt-(.+)$/i, (m) => `GPT ${titleCase(m[1])}`],
+  [/^gemini-(.+)$/i, (m) => `Gemini ${titleCase(m[1])}`],
+  [/^grok-(.+)$/i, (m) => `Grok ${titleCase(m[1])}`],
+  [/^deepseek-(.+)$/i, (m) => `DeepSeek ${titleCase(m[1])}`],
+  [/^qwen([\d.]+.*)$/i, (m) => `Qwen ${titleCase(m[1])}`],
+];
+
+// id → display name (regex fallback → id verbatim)
+export function deriveModelName(id) {
+  if (typeof id !== "string") return id;
+  for (const [re, fn] of NAME_PATTERNS) {
+    const m = id.match(re);
+    if (m) return fn(m);
+  }
+  return id;
+}
diff --git a/open-sse/providers/models/schema.js b/open-sse/providers/models/schema.js
new file mode 100644
index 0000000..c14a3d5
--- /dev/null
+++ b/open-sse/providers/models/schema.js
@@ -0,0 +1,40 @@
+import { deriveModelName } from "./namePatterns.js";
+
+// Normalize version separators in a model id: hyphen between two digits becomes a dot.
+// Registry ids use dots for versions ("claude-sonnet-4.5") but clients (CLIs, aliases)
+// often send them with dashes ("claude-sonnet-4-5"). Only digit-digit hyphens are
+// touched, so word/suffix hyphens stay intact ("-thinking", "-agentic", "qwen3-coder-next").
+export function normalizeModelId(modelId) {
+  if (typeof modelId !== "string") return modelId;
+  return modelId.replace(/(\d)-(\d)/g, "$1.$2");
+}
+
+// Model defaults centralized (was scattered as `m.kind || "llm"`, `quotaFamily || "normal"`, etc.)
+export const MODEL_DEFAULTS = {
+  kind: "llm",
+  quotaFamily: "normal",
+  strip: [],
+  targetFormat: null
+};
+
+// Normalize a registry model entry: accept terse "id" string, fill name via regex when omitted.
+// Override always wins (raw spread last); name falls back to regex → id.
+export function normalizeModel(raw) {
+  const model = typeof raw === "string" ? { id: raw } : raw;
+  if (model.name !== undefined) return model;
+  return { ...model, name: deriveModelName(model.id) };
+}
+
+// Resolve model kind with default (accepts legacy `type` field)
+export function modelKind(model) {
+  return model?.kind || model?.type || MODEL_DEFAULTS.kind;
+}
+export function modelQuotaFamily(model) {
+  return model?.quotaFamily || MODEL_DEFAULTS.quotaFamily;
+}
+export function modelStrip(model) {
+  return model?.strip || [];
+}
+export function modelTargetFormat(model) {
+  return model?.targetFormat || MODEL_DEFAULTS.targetFormat;
+}
diff --git a/open-sse/providers/pricing.js b/open-sse/providers/pricing.js
new file mode 100644
index 0000000..943365a
--- /dev/null
+++ b/open-sse/providers/pricing.js
@@ -0,0 +1,308 @@
+// Pricing rates for AI models — all rates in $/1M tokens
+//
+// Fallback order (first match wins):
+//   1. PROVIDER_PRICING[provider][model]  — provider-specific override
+//   2. MODEL_PRICING[model]               — canonical model price (provider-agnostic)
+//   3. PATTERN_PRICING                    — glob pattern match (e.g. "codex-*")
+
+/**
+ * Canonical model pricing — provider-agnostic.
+ * Cover all known models; deduplicated across providers.
+ */
+export const MODEL_PRICING = {
+  // === Anthropic / Claude ===
+  "claude-opus-4-6":              { input: 5.00,  output: 25.00, cached: 0.50,  reasoning: 25.00,  cache_creation: 6.25  },
+  "claude-opus-4-5-20251101":     { input: 5.00,  output: 25.00, cached: 0.50,  reasoning: 25.00,  cache_creation: 6.25  },
+  "claude-sonnet-4-6":            { input: 3.00,  output: 15.00, cached: 0.30,  reasoning: 15.00,  cache_creation: 3.75  },
+  "claude-sonnet-4-5-20250929":   { input: 3.00,  output: 15.00, cached: 0.30,  reasoning: 15.00,  cache_creation: 3.75  },
+  "claude-haiku-4-5-20251001":    { input: 1.00,  output: 5.00,  cached: 0.10,  reasoning: 5.00,   cache_creation: 1.25  },
+  "claude-sonnet-4-20250514":     { input: 3.00,  output: 15.00, cached: 1.50,  reasoning: 15.00,  cache_creation: 3.00  },
+  "claude-opus-4-20250514":       { input: 15.00, output: 25.00, cached: 7.50,  reasoning: 112.50, cache_creation: 15.00 },
+  "claude-3-5-sonnet-20241022":   { input: 3.00,  output: 15.00, cached: 1.50,  reasoning: 15.00,  cache_creation: 3.00  },
+  "claude-haiku-4.5":             { input: 0.50,  output: 2.50,  cached: 0.05,  reasoning: 3.75,   cache_creation: 0.50  },
+  "claude-opus-4.1":              { input: 5.00,  output: 25.00, cached: 0.50,  reasoning: 37.50,  cache_creation: 5.00  },
+  "claude-opus-4.5":              { input: 5.00,  output: 25.00, cached: 0.50,  reasoning: 37.50,  cache_creation: 5.00  },
+  "claude-opus-4.6":              { input: 5.00,  output: 25.00, cached: 0.50,  reasoning: 37.50,  cache_creation: 5.00  },
+  "claude-sonnet-4":              { input: 3.00,  output: 15.00, cached: 0.30,  reasoning: 22.50,  cache_creation: 3.00  },
+  "claude-sonnet-4.5":            { input: 3.00,  output: 15.00, cached: 0.30,  reasoning: 22.50,  cache_creation: 3.00  },
+  "claude-sonnet-4.6":            { input: 3.00,  output: 15.00, cached: 0.30,  reasoning: 22.50,  cache_creation: 3.00  },
+  "claude-opus-4-5-thinking":     { input: 5.00,  output: 25.00, cached: 0.50,  reasoning: 37.50,  cache_creation: 5.00  },
+  "claude-opus-4-6-thinking":     { input: 5.00,  output: 25.00, cached: 0.50,  reasoning: 37.50,  cache_creation: 5.00  },
+  "claude-fable-5":               { input: 10.00, output: 50.00, cached: 1.00,  reasoning: 50.00,  cache_creation: 12.50 },
+
+  // === OpenAI / GPT ===
+  "gpt-3.5-turbo":                { input: 0.50,  output: 1.50,  cached: 0.25,  reasoning: 2.25,   cache_creation: 0.50  },
+  "gpt-4":                        { input: 2.50,  output: 10.00, cached: 1.25,  reasoning: 15.00,  cache_creation: 2.50  },
+  "gpt-4-turbo":                  { input: 10.00, output: 30.00, cached: 5.00,  reasoning: 45.00,  cache_creation: 10.00 },
+  "gpt-4o":                       { input: 2.50,  output: 10.00, cached: 1.25,  reasoning: 15.00,  cache_creation: 2.50  },
+  "gpt-4o-mini":                  { input: 0.15,  output: 0.60,  cached: 0.075, reasoning: 0.90,   cache_creation: 0.15  },
+  "gpt-4.1":                      { input: 2.50,  output: 10.00, cached: 1.25,  reasoning: 15.00,  cache_creation: 2.50  },
+  "gpt-5":                        { input: 1.25,  output: 10.00, cached: 0.625, reasoning: 10.00,  cache_creation: 1.25  },
+  "gpt-5-mini":                   { input: 0.25,  output: 2.00,  cached: 0.125, reasoning: 2.00,   cache_creation: 0.25  },
+  "gpt-5-codex":                  { input: 1.25,  output: 10.00, cached: 0.625, reasoning: 10.00,  cache_creation: 1.25  },
+  "gpt-5.1":                      { input: 1.25,  output: 10.00, cached: 0.625, reasoning: 10.00,  cache_creation: 1.25  },
+  "gpt-5.1-codex":                { input: 1.25,  output: 10.00, cached: 0.625, reasoning: 10.00,  cache_creation: 1.25  },
+  "gpt-5.1-codex-mini":           { input: 1.50,  output: 6.00,  cached: 0.75,  reasoning: 9.00,   cache_creation: 1.50  },
+  "gpt-5.1-codex-mini-high":      { input: 2.00,  output: 8.00,  cached: 1.00,  reasoning: 12.00,  cache_creation: 2.00  },
+  "gpt-5.1-codex-max":            { input: 8.00,  output: 32.00, cached: 4.00,  reasoning: 48.00,  cache_creation: 8.00  },
+  "gpt-5.2":                      { input: 1.75,  output: 14.00, cached: 0.175, reasoning: 14.00,  cache_creation: 1.75  },
+  "gpt-5.2-codex":                { input: 1.75,  output: 14.00, cached: 0.175, reasoning: 14.00,  cache_creation: 1.75  },
+  "gpt-5.3-codex":                { input: 1.75,  output: 14.00, cached: 0.175, reasoning: 14.00,  cache_creation: 1.75  },
+  "gpt-5.3-codex-spark":         { input: 3.00,  output: 12.00, cached: 0.30,  reasoning: 12.00,  cache_creation: 3.00  },
+  "gpt-5.6":                      { input: 2.50,  output: 15.00, cached: 0.25,  reasoning: 15.00,  cache_creation: 2.50  },
+  "gpt-5.6-luna":                 { input: 1.00,  output: 6.00,  cached: 0.10,  reasoning: 6.00,   cache_creation: 1.00  },
+  "gpt-5.6-terra":                { input: 2.50,  output: 15.00, cached: 0.25,  reasoning: 15.00,  cache_creation: 2.50  },
+  "gpt-5.6-sol":                  { input: 5.00,  output: 30.00, cached: 0.50,  reasoning: 30.00,  cache_creation: 5.00  },
+  "o1":                           { input: 15.00, output: 60.00, cached: 7.50,  reasoning: 90.00,  cache_creation: 15.00 },
+  "o1-mini":                      { input: 3.00,  output: 12.00, cached: 1.50,  reasoning: 18.00,  cache_creation: 3.00  },
+
+  // === Gemini ===
+  "gemini-3-flash-preview":       { input: 0.50,  output: 3.00,  cached: 0.03,  reasoning: 4.50,   cache_creation: 0.50  },
+  "gemini-3-pro-preview":         { input: 2.00,  output: 12.00, cached: 0.25,  reasoning: 18.00,  cache_creation: 2.00  },
+  "gemini-3.1-pro-low":           { input: 2.00,  output: 12.00, cached: 0.25,  reasoning: 18.00,  cache_creation: 2.00  },
+  "gemini-3.1-pro-high":          { input: 4.00,  output: 18.00, cached: 0.50,  reasoning: 27.00,  cache_creation: 4.00  },
+  "gemini-pro-agent":             { input: 4.00,  output: 18.00, cached: 0.50,  reasoning: 27.00,  cache_creation: 4.00  },
+  "gemini-3-flash-agent":         { input: 0.50,  output: 3.00,  cached: 0.03,  reasoning: 4.50,   cache_creation: 0.50  },
+  "gemini-3.5-flash-low":         { input: 0.50,  output: 3.00,  cached: 0.03,  reasoning: 4.50,   cache_creation: 0.50  },
+  "gemini-3.5-flash-extra-low":   { input: 0.50,  output: 3.00,  cached: 0.03,  reasoning: 4.50,   cache_creation: 0.50  },
+  "gemini-3-flash":               { input: 0.50,  output: 3.00,  cached: 0.03,  reasoning: 4.50,   cache_creation: 0.50  },
+  "gemini-2.5-pro":               { input: 2.00,  output: 12.00, cached: 0.25,  reasoning: 18.00,  cache_creation: 2.00  },
+  "gemini-2.5-flash":             { input: 0.30,  output: 2.50,  cached: 0.03,  reasoning: 3.75,   cache_creation: 0.30  },
+  "gemini-2.5-flash-lite":        { input: 0.15,  output: 1.25,  cached: 0.015, reasoning: 1.875,  cache_creation: 0.15  },
+
+  // === Qwen ===
+  "qwen3-coder-plus":             { input: 1.00,  output: 4.00,  cached: 0.50,  reasoning: 6.00,   cache_creation: 1.00  },
+  "qwen3-coder-flash":            { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  },
+
+  // === Kimi ===
+  "kimi-k2":                      { input: 1.00,  output: 4.00,  cached: 0.50,  reasoning: 6.00,   cache_creation: 1.00  },
+  "kimi-k2-thinking":             { input: 1.50,  output: 6.00,  cached: 0.75,  reasoning: 9.00,   cache_creation: 1.50  },
+  "kimi-k2.5":                    { input: 1.20,  output: 4.80,  cached: 0.60,  reasoning: 7.20,   cache_creation: 1.20  },
+  "kimi-k2.5-thinking":           { input: 1.80,  output: 7.20,  cached: 0.90,  reasoning: 10.80,  cache_creation: 1.80  },
+  "kimi-latest":                  { input: 1.00,  output: 4.00,  cached: 0.50,  reasoning: 6.00,   cache_creation: 1.00  },
+
+  // === DeepSeek ===
+  "deepseek-chat":                { input: 0.14,  output: 0.28,  cached: 0.0028, reasoning: 0.28,   cache_creation: 0.14  },
+  "deepseek-reasoner":            { input: 0.14,  output: 0.28,  cached: 0.0028, reasoning: 0.28,   cache_creation: 0.14  },
+  "deepseek-r1":                  { input: 0.14,  output: 0.28,  cached: 0.0028, reasoning: 0.28,   cache_creation: 0.14  },
+  "deepseek-v3.2-chat":           { input: 0.14,  output: 0.28,  cached: 0.0028, reasoning: 0.28,   cache_creation: 0.14  },
+  "deepseek-v3.2-reasoner":       { input: 0.14,  output: 0.28,  cached: 0.0028, reasoning: 0.28,   cache_creation: 0.14  },
+  "deepseek-v4-flash":            { input: 0.14,  output: 0.28,  cached: 0.0028, reasoning: 0.28,   cache_creation: 0.14  },
+  "deepseek-v4-pro":              { input: 0.435, output: 0.87,  cached: 0.003625, reasoning: 0.87,  cache_creation: 0.435 },
+
+  // === GLM ===
+  "glm-4.6":                      { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  },
+  "glm-4.6v":                     { input: 0.75,  output: 3.00,  cached: 0.375, reasoning: 4.50,   cache_creation: 0.75  },
+  "glm-4.7":                      { input: 0.75,  output: 3.00,  cached: 0.375, reasoning: 4.50,   cache_creation: 0.75  },
+  "glm-5":                        { input: 1.00,  output: 4.00,  cached: 0.50,  reasoning: 6.00,   cache_creation: 1.00  },
+
+  // === MiniMax ===
+  "MiniMax-M3":                   { input: 0.30,  output: 1.20,  cached: 0.06,  reasoning: 1.80,   cache_creation: 0.30  },
+  "MiniMax-M2.1":                 { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  },
+  "MiniMax-M2.5":                 { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  },
+  "MiniMax-M2.7":                 { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  },
+  "minimax-m2.1":                 { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  },
+  "minimax-m2.5":                 { input: 0.60,  output: 2.40,  cached: 0.30,  reasoning: 3.60,   cache_creation: 0.60  },
+
+  // === Grok ===
+  "grok-code-fast-1":             { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  },
+
+  // === OpenRouter fallback ===
+  "auto":                         { input: 2.00,  output: 8.00,  cached: 1.00,  reasoning: 12.00,  cache_creation: 2.00  },
+
+  // === Misc ===
+  "oswe-vscode-prime":            { input: 1.00,  output: 4.00,  cached: 0.50,  reasoning: 6.00,   cache_creation: 1.00  },
+  "gpt-oss-120b-medium":          { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  },
+  "vision-model":                 { input: 1.50,  output: 6.00,  cached: 0.75,  reasoning: 9.00,   cache_creation: 1.50  },
+  "coder-model":                  { input: 1.50,  output: 6.00,  cached: 0.75,  reasoning: 9.00,   cache_creation: 1.50  },
+};
+
+/**
+ * Provider-specific pricing overrides.
+ * Only include entries where price DIFFERS from MODEL_PRICING.
+ * Keyed by provider alias (cc, cx, gc, gh, ...) or provider id (openai, anthropic, ...).
+ */
+export const PROVIDER_PRICING = {
+  // GitHub Copilot (gh) — explicit override, matches canonical gpt-5.3-codex rate
+  gh: {
+    "gpt-5.3-codex": { input: 1.75, output: 14.00, cached: 0.175, reasoning: 14.00, cache_creation: 1.75 },
+  },
+};
+
+/**
+ * Pattern-based pricing fallback — matched when no exact model entry found.
+ * Patterns use simple glob: "*" matches any substring.
+ * First match wins — order matters.
+ */
+export const PATTERN_PRICING = [
+  // --- Codex variants ---
+  { pattern: "*-codex-xhigh",   pricing: { input: 10.00, output: 40.00, cached: 5.00,  reasoning: 60.00,  cache_creation: 10.00 } },
+  { pattern: "*-codex-high",    pricing: { input: 8.00,  output: 32.00, cached: 4.00,  reasoning: 48.00,  cache_creation: 8.00  } },
+  { pattern: "*-codex-max",     pricing: { input: 8.00,  output: 32.00, cached: 4.00,  reasoning: 48.00,  cache_creation: 8.00  } },
+  { pattern: "*-codex-mini-*",  pricing: { input: 1.50,  output: 6.00,  cached: 0.75,  reasoning: 9.00,   cache_creation: 1.50  } },
+  { pattern: "*-codex-mini",    pricing: { input: 1.50,  output: 6.00,  cached: 0.75,  reasoning: 9.00,   cache_creation: 1.50  } },
+  { pattern: "*-codex-low",     pricing: { input: 1.75,  output: 14.00, cached: 0.175, reasoning: 14.00,  cache_creation: 1.75  } },
+  { pattern: "*-codex-none",    pricing: { input: 1.75,  output: 14.00, cached: 0.175, reasoning: 14.00,  cache_creation: 1.75  } },
+  { pattern: "*-codex-spark",   pricing: { input: 3.00,  output: 12.00, cached: 0.30,  reasoning: 12.00,  cache_creation: 3.00  } },
+  { pattern: "codex-*",         pricing: { input: 1.75,  output: 14.00, cached: 0.175, reasoning: 14.00,  cache_creation: 1.75  } },
+  { pattern: "*-codex",         pricing: { input: 1.75,  output: 14.00, cached: 0.175, reasoning: 14.00,  cache_creation: 1.75  } },
+
+  // --- Claude ---
+  { pattern: "claude-opus-*",   pricing: { input: 5.00,  output: 25.00, cached: 0.50,  reasoning: 25.00,  cache_creation: 6.25  } },
+  { pattern: "claude-sonnet-*", pricing: { input: 3.00,  output: 15.00, cached: 0.30,  reasoning: 15.00,  cache_creation: 3.75  } },
+  { pattern: "claude-haiku-*",  pricing: { input: 1.00,  output: 5.00,  cached: 0.10,  reasoning: 5.00,   cache_creation: 1.25  } },
+  { pattern: "claude-*",        pricing: { input: 3.00,  output: 15.00, cached: 0.30,  reasoning: 15.00,  cache_creation: 3.75  } },
+
+  // --- Gemini (specific first, generic last) ---
+  { pattern: "gemini-*-flash-lite", pricing: { input: 0.15, output: 1.25, cached: 0.015, reasoning: 1.875, cache_creation: 0.15 } },
+  { pattern: "gemini-*-flash",  pricing: { input: 0.30,  output: 2.50,  cached: 0.03,  reasoning: 3.75,   cache_creation: 0.30  } },
+  { pattern: "gemini-*-pro",    pricing: { input: 2.00,  output: 12.00, cached: 0.25,  reasoning: 18.00,  cache_creation: 2.00  } },
+  { pattern: "gemini-3-*",      pricing: { input: 0.50,  output: 3.00,  cached: 0.03,  reasoning: 4.50,   cache_creation: 0.50  } },
+  { pattern: "gemini-2.5-*",    pricing: { input: 0.30,  output: 2.50,  cached: 0.03,  reasoning: 3.75,   cache_creation: 0.30  } },
+  { pattern: "gemini-*",        pricing: { input: 0.50,  output: 3.00,  cached: 0.03,  reasoning: 4.50,   cache_creation: 0.50  } },
+
+  // --- GPT (specific first, generic last) ---
+  { pattern: "gpt-5.6-*",       pricing: { input: 2.50,  output: 15.00, cached: 0.25,  reasoning: 15.00,  cache_creation: 2.50  } },
+  { pattern: "gpt-5.3-*",       pricing: { input: 1.75,  output: 14.00, cached: 0.175, reasoning: 14.00,  cache_creation: 1.75  } },
+  { pattern: "gpt-5.2-*",       pricing: { input: 1.75,  output: 14.00, cached: 0.175, reasoning: 14.00,  cache_creation: 1.75  } },
+  { pattern: "gpt-5.1-*",       pricing: { input: 1.25,  output: 10.00, cached: 0.625, reasoning: 10.00,  cache_creation: 1.25  } },
+  { pattern: "gpt-5-*",         pricing: { input: 1.25,  output: 10.00, cached: 0.625, reasoning: 10.00,  cache_creation: 1.25  } },
+  { pattern: "gpt-5*",          pricing: { input: 1.25,  output: 10.00, cached: 0.625, reasoning: 10.00,  cache_creation: 1.25  } },
+  { pattern: "gpt-4o-*",        pricing: { input: 0.15,  output: 0.60,  cached: 0.075, reasoning: 0.90,   cache_creation: 0.15  } },
+  { pattern: "gpt-4o",          pricing: { input: 2.50,  output: 10.00, cached: 1.25,  reasoning: 15.00,  cache_creation: 2.50  } },
+  { pattern: "gpt-4*",          pricing: { input: 2.50,  output: 10.00, cached: 1.25,  reasoning: 15.00,  cache_creation: 2.50  } },
+
+  // --- o1 / o-series ---
+  { pattern: "o1-*",            pricing: { input: 3.00,  output: 12.00, cached: 1.50,  reasoning: 18.00,  cache_creation: 3.00  } },
+  { pattern: "o1",              pricing: { input: 15.00, output: 60.00, cached: 7.50,  reasoning: 90.00,  cache_creation: 15.00 } },
+  { pattern: "o3-*",            pricing: { input: 10.00, output: 40.00, cached: 5.00,  reasoning: 60.00,  cache_creation: 10.00 } },
+  { pattern: "o4-*",            pricing: { input: 2.00,  output: 8.00,  cached: 1.00,  reasoning: 12.00,  cache_creation: 2.00  } },
+
+  // --- Qwen ---
+  { pattern: "qwen3-coder-*",   pricing: { input: 1.00,  output: 4.00,  cached: 0.50,  reasoning: 6.00,   cache_creation: 1.00  } },
+  { pattern: "qwen*-coder-*",   pricing: { input: 1.00,  output: 4.00,  cached: 0.50,  reasoning: 6.00,   cache_creation: 1.00  } },
+  { pattern: "qwen*",           pricing: { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  } },
+
+  // --- Kimi ---
+  { pattern: "kimi-*-thinking",  pricing: { input: 1.80,  output: 7.20,  cached: 0.90,  reasoning: 10.80,  cache_creation: 1.80  } },
+  { pattern: "kimi-k2*",        pricing: { input: 1.20,  output: 4.80,  cached: 0.60,  reasoning: 7.20,   cache_creation: 1.20  } },
+  { pattern: "kimi-*",          pricing: { input: 1.00,  output: 4.00,  cached: 0.50,  reasoning: 6.00,   cache_creation: 1.00  } },
+
+  // --- DeepSeek ---
+  { pattern: "deepseek-*reasoner*", pricing: { input: 0.14, output: 0.28, cached: 0.0028, reasoning: 0.28, cache_creation: 0.14 } },
+  { pattern: "deepseek-r*",     pricing: { input: 0.14,  output: 0.28,  cached: 0.0028, reasoning: 0.28,   cache_creation: 0.14  } },
+  { pattern: "deepseek-v*",     pricing: { input: 0.14,  output: 0.28,  cached: 0.0028, reasoning: 0.28,   cache_creation: 0.14  } },
+  { pattern: "deepseek-*",      pricing: { input: 0.14,  output: 0.28,  cached: 0.0028, reasoning: 0.28,   cache_creation: 0.14  } },
+
+  // --- GLM ---
+  { pattern: "glm-5*",          pricing: { input: 1.00,  output: 4.00,  cached: 0.50,  reasoning: 6.00,   cache_creation: 1.00  } },
+  { pattern: "glm-4*",          pricing: { input: 0.75,  output: 3.00,  cached: 0.375, reasoning: 4.50,   cache_creation: 0.75  } },
+  { pattern: "glm-*",           pricing: { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  } },
+
+  // --- MiniMax ---
+  { pattern: "MiniMax-*",       pricing: { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  } },
+  { pattern: "minimax-*",       pricing: { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  } },
+
+  // --- Grok ---
+  { pattern: "grok-code-*",     pricing: { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  } },
+  { pattern: "grok-*",          pricing: { input: 0.50,  output: 2.00,  cached: 0.25,  reasoning: 3.00,   cache_creation: 0.50  } },
+];
+
+/**
+ * Match a model ID against a glob pattern (* = wildcard). Case-insensitive:
+ * registry ids mix casing (e.g. "MiniMax-M2.5" vs "minimax-m2.5").
+ */
+export function matchPattern(pattern, model) {
+  const regex = new RegExp("^" + pattern.split("*").map(s => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$", "i");
+  return regex.test(model);
+}
+
+/**
+ * Resolve pricing for a model using the 3-step fallback chain:
+ *   1. PROVIDER_PRICING[provider][model]
+ *   2. MODEL_PRICING[model]
+ *   3. PATTERN_PRICING (glob match)
+ *
+ * @param {string} provider
+ * @param {string} model
+ * @returns {object|null}
+ */
+export function getPricingForModel(provider, model) {
+  if (!model) return null;
+
+  // 1. Provider-specific override
+  if (provider && PROVIDER_PRICING[provider]?.[model]) {
+    return PROVIDER_PRICING[provider][model];
+  }
+
+  // 2. Canonical model pricing (strip vendor prefix if needed: "deepseek/deepseek-chat" → "deepseek-chat")
+  const baseModel = model.includes("/") ? model.split("/").pop() : model;
+  if (MODEL_PRICING[baseModel]) return MODEL_PRICING[baseModel];
+  if (MODEL_PRICING[model]) return MODEL_PRICING[model];
+
+  // 3. Pattern match
+  for (const { pattern, pricing } of PATTERN_PRICING) {
+    if (matchPattern(pattern, baseModel) || matchPattern(pattern, model)) {
+      return pricing;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get all provider pricing (for UI / API).
+ * Returns PROVIDER_PRICING — consumers should fall back to MODEL_PRICING for unlisted models.
+ */
+export function getDefaultPricing() {
+  return PROVIDER_PRICING;
+}
+
+/**
+ * Format cost for display
+ * @param {number} cost
+ * @returns {string}
+ */
+export function formatCost(cost) {
+  if (cost === null || cost === undefined || isNaN(cost)) return "$0.00";
+  return `$${cost.toFixed(2)}`;
+}
+
+/**
+ * Calculate cost from tokens and pricing
+ * @param {object} tokens
+ * @param {object} pricing
+ * @returns {number} cost in dollars
+ */
+export function calculateCostFromTokens(tokens, pricing) {
+  if (!tokens || !pricing) return 0;
+
+  let cost = 0;
+
+  const inputTokens = tokens.prompt_tokens || tokens.input_tokens || 0;
+  const cachedTokens = tokens.cached_tokens || tokens.cache_read_input_tokens || 0;
+  const cacheCreationTokens = tokens.cache_creation_input_tokens || 0;
+  // prompt_tokens is cache-inclusive (see canonicalizeUsage): cached + cache_creation
+  // are subsets, so subtract both to avoid charging them at the full input rate.
+  const nonCachedInput = Math.max(0, inputTokens - cachedTokens - cacheCreationTokens);
+
+  cost += nonCachedInput * (pricing.input / 1000000);
+
+  if (cachedTokens > 0) {
+    cost += cachedTokens * ((pricing.cached || pricing.input) / 1000000);
+  }
+
+  const outputTokens = tokens.completion_tokens || tokens.output_tokens || 0;
+  cost += outputTokens * (pricing.output / 1000000);
+
+  const reasoningTokens = tokens.reasoning_tokens || 0;
+  if (reasoningTokens > 0) {
+    cost += reasoningTokens * ((pricing.reasoning || pricing.output) / 1000000);
+  }
+
+  if (cacheCreationTokens > 0) {
+    cost += cacheCreationTokens * ((pricing.cache_creation || pricing.input) / 1000000);
+  }
+
+  return cost;
+}
diff --git a/open-sse/providers/registry/alicode-intl.js b/open-sse/providers/registry/alicode-intl.js
new file mode 100644
index 0000000..b2eca7d
--- /dev/null
+++ b/open-sse/providers/registry/alicode-intl.js
@@ -0,0 +1,30 @@
+export default {
+  id: "alicode-intl",
+  priority: 10,
+  alias: "alicode-intl",
+  display: {
+    name: "Alibaba Intl",
+    icon: "cloud",
+    color: "#FF6A00",
+    textIcon: "ALi",
+    website: "https://modelstudio.console.alibabacloud.com",
+    notice: {
+      apiKeyUrl: "https://modelstudio.console.alibabacloud.com/?apiKey=1",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://coding-intl.dashscope.aliyuncs.com/v1/chat/completions",
+    headers: {},
+    quirks: { preserveCacheControl: true },
+  },
+  models: [
+    { id: "qwen3.5-plus", name: "Qwen3.5 Plus" },
+    { id: "kimi-k2.5", name: "Kimi K2.5" },
+    { id: "glm-5", name: "GLM 5" },
+    { id: "MiniMax-M2.5", name: "MiniMax M2.5" },
+    { id: "qwen3-coder-next", name: "Qwen3 Coder Next" },
+    { id: "qwen3-coder-plus", name: "Qwen3 Coder Plus" },
+    { id: "glm-4.7", name: "GLM 4.7" },
+  ],
+};
diff --git a/open-sse/providers/registry/alicode.js b/open-sse/providers/registry/alicode.js
new file mode 100644
index 0000000..e572c7e
--- /dev/null
+++ b/open-sse/providers/registry/alicode.js
@@ -0,0 +1,31 @@
+export default {
+  id: "alicode",
+  priority: 20,
+  alias: "alicode",
+  display: {
+    name: "Alibaba",
+    icon: "cloud",
+    color: "#FF6A00",
+    textIcon: "ALi",
+    website: "https://bailian.console.aliyun.com",
+    notice: {
+      apiKeyUrl: "https://bailian.console.aliyun.com/?apiKey=1",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://coding.dashscope.aliyuncs.com/v1/chat/completions",
+    headers: {},
+    quirks: { preserveCacheControl: true },
+  },
+  models: [
+    { id: "qwen3.5-plus", name: "Qwen3.5 Plus" },
+    { id: "kimi-k2.5", name: "Kimi K2.5" },
+    { id: "glm-5", name: "GLM 5" },
+    { id: "MiniMax-M2.5", name: "MiniMax M2.5" },
+    { id: "qwen3-max-2026-01-23", name: "Qwen3 Max" },
+    { id: "qwen3-coder-next", name: "Qwen3 Coder Next" },
+    { id: "qwen3-coder-plus", name: "Qwen3 Coder Plus" },
+    { id: "glm-4.7", name: "GLM 4.7" },
+  ],
+};
diff --git a/open-sse/providers/registry/anthropic.js b/open-sse/providers/registry/anthropic.js
new file mode 100644
index 0000000..1f6a349
--- /dev/null
+++ b/open-sse/providers/registry/anthropic.js
@@ -0,0 +1,32 @@
+import { CLAUDE_API_HEADERS } from "../shared.js";
+
+export default {
+  id: "anthropic",
+  priority: 30,
+  alias: "anthropic",
+  display: {
+    name: "Anthropic",
+    icon: "smart_toy",
+    color: "#D97757",
+    textIcon: "AN",
+    website: "https://console.anthropic.com",
+    notice: {
+      apiKeyUrl: "https://console.anthropic.com/settings/keys",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.anthropic.com/v1/messages",
+    format: "claude",
+    headers: {
+      "Anthropic-Version": "2023-06-01",
+      "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    },
+  },
+  models: [
+    { id: "claude-sonnet-4-20250514", name: "Claude Sonnet 4" },
+    { id: "claude-opus-4-20250514", name: "Claude Opus 4" },
+    { id: "claude-3-5-sonnet-20241022", name: "Claude 3.5 Sonnet" },
+  ],
+  serviceKinds: ["llm","imageToText"],
+};
diff --git a/open-sse/providers/registry/antigravity.js b/open-sse/providers/registry/antigravity.js
new file mode 100644
index 0000000..dd7fbc0
--- /dev/null
+++ b/open-sse/providers/registry/antigravity.js
@@ -0,0 +1,81 @@
+import { ANTIGRAVITY_IDE_BASE_URL, ANTIGRAVITY_IDE_USER_AGENT, ANTIGRAVITY_OAUTH_CLIENT } from "../shared.js";
+
+export default {
+  id: "antigravity",
+  priority: 20,
+  alias: "ag",
+  uiAlias: "ag",
+  display: {
+    name: "Antigravity",
+    icon: "rocket_launch",
+    color: "#F59E0B",
+    website: "https://antigravity.google",
+    notice: {
+      signupUrl: "https://antigravity.google",
+    },
+    deprecated: true,
+    deprecationNotice: "RISK_NOTICE",
+  },
+  category: "oauth",
+  serviceKinds: ["llm", "image"],
+  transport: {
+    baseUrls: [ANTIGRAVITY_IDE_BASE_URL],
+    format: "antigravity",
+    headers: {
+      "User-Agent": ANTIGRAVITY_IDE_USER_AGENT,
+    },
+    retry: {
+      "429": {
+        attempts: 3,
+      },
+      "500": {
+        attempts: 3,
+      },
+      "503": {
+        attempts: 3,
+      },
+    },
+    usage: {
+      quotaApiUrl: "https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels",
+      loadProjectApiUrl: "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+      tokenUrl: "https://oauth2.googleapis.com/token",
+    },
+    clientId: "1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com",
+    clientSecret: "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",
+  },
+  models: [
+    { id: "gemini-3-flash-agent", name: "Gemini 3.5 Flash (High)" },
+    { id: "gemini-3.5-flash-low", name: "Gemini 3.5 Flash (Medium)" },
+    { id: "gemini-3.5-flash-extra-low", name: "Gemini 3.5 Flash (Low)" },
+    { id: "gemini-pro-agent", name: "Gemini 3.1 Pro (High)" },
+    { id: "gemini-3.1-pro-low", name: "Gemini 3.1 Pro (Low)" },
+    { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6 (Thinking)" },
+    { id: "claude-opus-4-6-thinking", name: "Claude Opus 4.6 (Thinking)" },
+    { id: "gpt-oss-120b-medium", name: "GPT-OSS 120B (Medium)" },
+    { id: "gemini-3-flash", name: "Gemini 3 Flash", thinking: false },
+    // Image generation models
+    { id: "gemini-3.1-flash-image", name: "Gemini 3.1 Flash (Image)", kind: "image", imageGen: true, capabilities: ["textToImage"] },
+  ],
+  oauth: {
+    authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenUrl: "https://oauth2.googleapis.com/token",
+    userInfoUrl: "https://www.googleapis.com/oauth2/v1/userinfo",
+    scopes: [
+      "https://www.googleapis.com/auth/cloud-platform",
+      "https://www.googleapis.com/auth/userinfo.email",
+      "https://www.googleapis.com/auth/userinfo.profile",
+      "https://www.googleapis.com/auth/cclog",
+      "https://www.googleapis.com/auth/experimentsandconfigs",
+    ],
+    apiEndpoint: "https://cloudcode-pa.googleapis.com",
+    apiVersion: "v1internal",
+    loadCodeAssistEndpoint: "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+    onboardUserEndpoint: "https://cloudcode-pa.googleapis.com/v1internal:onboardUser",
+    loadCodeAssistUserAgent: "google-api-nodejs-client/9.15.1",
+    loadCodeAssistApiClient: "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    refreshLeadMs: 300000,
+  },
+  features: {
+    usage: true,
+  },
+};
diff --git a/open-sse/providers/registry/assemblyai.js b/open-sse/providers/registry/assemblyai.js
new file mode 100644
index 0000000..bb4eb77
--- /dev/null
+++ b/open-sse/providers/registry/assemblyai.js
@@ -0,0 +1,38 @@
+export default {
+  id: "assemblyai",
+  priority: 30,
+  alias: "assemblyai",
+  aliases: [
+    "aai",
+  ],
+  uiAlias: "aai",
+  display: {
+    name: "AssemblyAI",
+    icon: "record_voice_over",
+    color: "#0062FF",
+    textIcon: "AA",
+    website: "https://assemblyai.com",
+    notice: {
+      apiKeyUrl: "https://www.assemblyai.com/app/api-keys",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: {
+    baseUrl: "https://api.assemblyai.com/v1/audio/transcriptions",
+    validateUrl: "https://api.assemblyai.com/v1/account",
+  },
+  models: [
+    { id: "universal-3-pro", name: "Universal 3 Pro", params: ["language"], kind: "stt" },
+    { id: "universal-2", name: "Universal 2", params: ["language"], kind: "stt" },
+    { id: "best", name: "Best (Nano + Universal)", kind: "stt" },
+    { id: "nano", name: "Nano (Fast)", kind: "stt" },
+  ],
+  serviceKinds: ["stt"],
+  sttConfig: {
+    baseUrl: "https://api.assemblyai.com/v2/transcript",
+    authType: "apikey",
+    authHeader: "authorization",
+    format: "assemblyai",
+  },
+};
diff --git a/open-sse/providers/registry/aws-polly.js b/open-sse/providers/registry/aws-polly.js
new file mode 100644
index 0000000..3e269be
--- /dev/null
+++ b/open-sse/providers/registry/aws-polly.js
@@ -0,0 +1,45 @@
+export default {
+  id: "aws-polly",
+  alias: "polly",
+  display: {
+    name: "AWS Polly",
+    icon: "record_voice_over",
+    color: "#FF9900",
+    textIcon: "PL",
+    website: "https://aws.amazon.com/polly/",
+    notice: {
+      text: "Use AWS Secret Access Key as API key; set providerSpecificData.accessKeyId and optional region.",
+      apiKeyUrl: "https://console.aws.amazon.com/iam/home#/security_credentials"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "tts"
+  ],
+  ttsConfig: {
+    baseUrl: "https://polly.{region}.amazonaws.com/v1/speech",
+    authType: "apikey",
+    authHeader: "aws-sigv4",
+    format: "aws-polly",
+    models: [
+      {
+        id: "standard",
+        name: "Standard"
+      },
+      {
+        id: "neural",
+        name: "Neural"
+      },
+      {
+        id: "long-form",
+        name: "Long-form"
+      },
+      {
+        id: "generative",
+        name: "Generative"
+      }
+    ]
+  },
+  hasProviderSpecificData: true
+};
diff --git a/open-sse/providers/registry/azure.js b/open-sse/providers/registry/azure.js
new file mode 100644
index 0000000..32feca0
--- /dev/null
+++ b/open-sse/providers/registry/azure.js
@@ -0,0 +1,21 @@
+export default {
+  id: "azure",
+  priority: 40,
+  alias: "azure",
+  display: {
+    name: "Azure OpenAI",
+    icon: "cloud",
+    color: "#0078D4",
+    textIcon: "AZ",
+    website: "https://azure.microsoft.com/en-us/products/ai-services/openai-service",
+    notice: {
+      apiKeyUrl: "https://portal.azure.com/#view/Microsoft_Azure_ProjectOxford/CognitiveServicesHub/~/OpenAI",
+    },
+  },
+  category: "apikey",
+  hasProviderSpecificData: true,
+  transport: {
+    baseUrl: "",
+    headers: {},
+  },
+};
diff --git a/open-sse/providers/registry/black-forest-labs.js b/open-sse/providers/registry/black-forest-labs.js
new file mode 100644
index 0000000..720c5ea
--- /dev/null
+++ b/open-sse/providers/registry/black-forest-labs.js
@@ -0,0 +1,32 @@
+export default {
+  id: "black-forest-labs",
+  priority: 50,
+  alias: "black-forest-labs",
+  aliases: [
+    "bfl",
+  ],
+  uiAlias: "bfl",
+  display: {
+    name: "Black Forest Labs",
+    icon: "image",
+    color: "#111827",
+    textIcon: "BF",
+    website: "https://blackforestlabs.ai",
+    notice: {
+      apiKeyUrl: "https://api.bfl.ai",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: null,
+  models: [
+    { id: "flux-pro-1.1", name: "FLUX Pro 1.1", params: ["n","size"], kind: "image" },
+    { id: "flux-pro-1.1-ultra", name: "FLUX Pro 1.1 Ultra", params: ["size"], kind: "image" },
+    { id: "flux-pro", name: "FLUX Pro", params: ["n","size"], kind: "image" },
+    { id: "flux-dev", name: "FLUX Dev", params: ["n","size"], kind: "image" },
+    { id: "flux-kontext-pro", name: "FLUX Kontext Pro (Edit)", params: ["size"], capabilities: ["edit"], kind: "image" },
+    { id: "flux-kontext-max", name: "FLUX Kontext Max (Edit)", params: ["size"], capabilities: ["edit"], kind: "image" },
+  ],
+  serviceKinds: ["image"],
+  imageConfig: { baseUrl: "https://api.bfl.ai/v1" },
+};
diff --git a/open-sse/providers/registry/blackbox.js b/open-sse/providers/registry/blackbox.js
new file mode 100644
index 0000000..2764cdf
--- /dev/null
+++ b/open-sse/providers/registry/blackbox.js
@@ -0,0 +1,41 @@
+export default {
+  id: "blackbox",
+  priority: 50,
+  alias: "blackbox",
+  aliases: [
+    "bb",
+  ],
+  uiAlias: "bb",
+  display: {
+    name: "Blackbox AI",
+    icon: "smart_toy",
+    color: "#5B5FEF",
+    textIcon: "BB",
+    website: "https://blackbox.ai",
+    notice: {
+      apiKeyUrl: "https://www.blackbox.ai/api-management",
+    },
+  },
+  category: "apikey",
+  serviceKinds: ["llm"],
+  thinkingConfig: {
+    options: ["auto", "none", "low", "medium", "high", "xhigh"],
+    defaultMode: "auto",
+  },
+  transport: {
+    baseUrl: "https://api.blackbox.ai/v1/chat/completions",
+    thinkingFormat: "openai",
+  },
+  models: [
+    { id: "claude-fable-5",    name: "Claude Fable 5",    upstreamModelId: "blackboxai/anthropic/claude-fable-5" },
+    { id: "claude-opus-4.8",   name: "Claude Opus 4.8",  upstreamModelId: "blackboxai/anthropic/claude-opus-4.8" },
+    { id: "claude-sonnet-4.6", name: "Claude Sonnet 4.6", upstreamModelId: "blackboxai/anthropic/claude-sonnet-4.6" },
+    { id: "gpt-5.5",           name: "GPT-5.5",           upstreamModelId: "blackboxai/openai/gpt-5.5" },
+    { id: "gpt-5.4-pro",       name: "GPT-5.4 Pro",       upstreamModelId: "blackboxai/openai/gpt-5.4-pro" },
+    { id: "gpt-5.4",           name: "GPT-5.4",           upstreamModelId: "blackboxai/openai/gpt-5.4" },
+    { id: "gpt-5.3-codex",     name: "GPT-5.3 Codex",     upstreamModelId: "blackboxai/openai/gpt-5.3-codex" },
+    { id: "gpt-5.4-nano",      name: "GPT-5.4 Nano",      upstreamModelId: "blackboxai/openai/gpt-5.4-nano" },
+    { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash", upstreamModelId: "blackboxai/deepseek/deepseek-v4-flash" },
+    { id: "grok-4.3",          name: "Grok 4.3",          upstreamModelId: "blackboxai/x-ai/grok-4.3" },
+  ],
+};
diff --git a/open-sse/providers/registry/brave-search.js b/open-sse/providers/registry/brave-search.js
new file mode 100644
index 0000000..6fcad11
--- /dev/null
+++ b/open-sse/providers/registry/brave-search.js
@@ -0,0 +1,35 @@
+export default {
+  id: "brave-search",
+  alias: "brave",
+  display: {
+    name: "Brave Search",
+    icon: "travel_explore",
+    color: "#FB542B",
+    textIcon: "BR",
+    website: "https://brave.com/search/api",
+    notice: {
+      apiKeyUrl: "https://api-dashboard.search.brave.com/app/keys"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "webSearch"
+  ],
+  searchConfig: {
+    baseUrl: "https://api.search.brave.com/res/v1",
+    method: "GET",
+    authType: "apikey",
+    authHeader: "x-subscription-token",
+    costPerQuery: 0.005,
+    freeMonthlyQuota: 1000,
+    searchTypes: [
+      "web",
+      "news"
+    ],
+    defaultMaxResults: 5,
+    maxMaxResults: 20,
+    timeoutMs: 10000,
+    cacheTTLMs: 300000
+  }
+};
diff --git a/open-sse/providers/registry/byteplus.js b/open-sse/providers/registry/byteplus.js
new file mode 100644
index 0000000..6440cc4
--- /dev/null
+++ b/open-sse/providers/registry/byteplus.js
@@ -0,0 +1,35 @@
+export default {
+  id: "byteplus",
+  priority: 70,
+  alias: "byteplus",
+  aliases: [
+    "bpm",
+  ],
+  uiAlias: "bpm",
+  display: {
+    name: "BytePlus ModelArk",
+    icon: "cloud",
+    color: "#2563EB",
+    textIcon: "BP",
+    website: "https://console.byteplus.com/ark",
+    notice: {
+      text: "Free credits for new accounts. Access to Seed 2.0, Kimi K2 Thinking, GLM 4.7, GPT-OSS-120B models.",
+      apiKeyUrl: "https://console.byteplus.com/ark/region:ark+ap-southeast-1/apiKey",
+    },
+  },
+  category: "freeTier",
+  transport: {
+    baseUrl: "https://ark.ap-southeast.bytepluses.com/api/coding/v3/chat/completions",
+    headers: {},
+  },
+  models: [
+    { id: "seed-2-0-pro-260328", name: "Seed 2.0 Pro" },
+    { id: "seed-2-0-code-preview-260328", name: "Seed 2.0 Code Preview" },
+    { id: "seed-2-0-mini-260215", name: "Seed 2.0 Mini" },
+    { id: "seed-2-0-lite-260228", name: "Seed 2.0 Lite" },
+    { id: "kimi-k2-thinking-251104", name: "Kimi K2 Thinking" },
+    { id: "glm-4-7-251222", name: "GLM 4.7" },
+    { id: "gpt-oss-120b-250805", name: "GPT-OSS-120B" },
+  ],
+  serviceKinds: ["llm"],
+};
diff --git a/open-sse/providers/registry/cartesia.js b/open-sse/providers/registry/cartesia.js
new file mode 100644
index 0000000..411925c
--- /dev/null
+++ b/open-sse/providers/registry/cartesia.js
@@ -0,0 +1,36 @@
+export default {
+  id: "cartesia",
+  alias: "cartesia",
+  display: {
+    name: "Cartesia",
+    icon: "spatial_audio",
+    color: "#FF4F8B",
+    textIcon: "CA",
+    website: "https://cartesia.ai",
+    notice: {
+      apiKeyUrl: "https://play.cartesia.ai/keys"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "tts"
+  ],
+  ttsConfig: {
+    baseUrl: "https://api.cartesia.ai/tts/bytes",
+    authType: "apikey",
+    authHeader: "x-api-key",
+    format: "cartesia",
+    models: [
+      {
+        id: "sonic-2",
+        name: "Sonic 2"
+      },
+      {
+        id: "sonic-3",
+        name: "Sonic 3"
+      }
+    ]
+  },
+  hidden: true
+};
diff --git a/open-sse/providers/registry/cerebras.js b/open-sse/providers/registry/cerebras.js
new file mode 100644
index 0000000..964250f
--- /dev/null
+++ b/open-sse/providers/registry/cerebras.js
@@ -0,0 +1,31 @@
+export default {
+  id: "cerebras",
+  priority: 60,
+  alias: "cerebras",
+  display: {
+    name: "Cerebras",
+    icon: "memory",
+    color: "#FF4F00",
+    textIcon: "CB",
+    website: "https://www.cerebras.ai",
+    notice: {
+      apiKeyUrl: "https://cloud.cerebras.ai/platform",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.cerebras.ai/v1/chat/completions",
+    validateUrl: "https://api.cerebras.ai/v1/models",
+    quirks: {
+      dropClientMetadata: true,
+    },
+  },
+  models: [
+    { id: "gpt-oss-120b", name: "GPT OSS 120B" },
+    { id: "zai-glm-4.7", name: "ZAI GLM 4.7" },
+    { id: "llama-3.3-70b", name: "Llama 3.3 70B" },
+    { id: "llama-4-scout-17b-16e-instruct", name: "Llama 4 Scout" },
+    { id: "qwen-3-235b-a22b-instruct-2507", name: "Qwen3 235B A22B" },
+    { id: "qwen-3-32b", name: "Qwen3 32B" },
+  ],
+};
diff --git a/open-sse/providers/registry/chutes.js b/open-sse/providers/registry/chutes.js
new file mode 100644
index 0000000..0eed21b
--- /dev/null
+++ b/open-sse/providers/registry/chutes.js
@@ -0,0 +1,24 @@
+export default {
+  id: "chutes",
+  priority: 70,
+  alias: "chutes",
+  aliases: [
+    "ch",
+  ],
+  uiAlias: "ch",
+  display: {
+    name: "Chutes AI",
+    icon: "water_drop",
+    color: "#ffffffff",
+    textIcon: "CH",
+    website: "https://chutes.ai",
+    notice: {
+      apiKeyUrl: "https://chutes.ai/app/api",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://llm.chutes.ai/v1/chat/completions",
+    validateUrl: "https://llm.chutes.ai/v1/models",
+  },
+};
diff --git a/open-sse/providers/registry/claude.js b/open-sse/providers/registry/claude.js
new file mode 100644
index 0000000..a291270
--- /dev/null
+++ b/open-sse/providers/registry/claude.js
@@ -0,0 +1,87 @@
+import { CLAUDE_CLI_SPOOF_HEADERS } from "../shared.js";
+
+export default {
+  id: "claude",
+  priority: 10,
+  alias: "cc",
+  uiAlias: "cc",
+  display: {
+    name: "Claude Code",
+    icon: "smart_toy",
+    color: "#D97757",
+    website: "https://claude.ai",
+    notice: {
+      signupUrl: "https://claude.ai",
+    },
+    deprecated: true,
+    deprecationNotice: "RISK_NOTICE",
+  },
+  category: "oauth",
+  transport: {
+    baseUrl: "https://api.anthropic.com/v1/messages",
+    format: "claude",
+    urlSuffix: "?beta=true",
+    headers: {
+      "Anthropic-Version": "2023-06-01",
+      "Anthropic-Beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28",
+      "Anthropic-Dangerous-Direct-Browser-Access": "true",
+      "User-Agent": "claude-cli/2.1.92 (external, sdk-cli)",
+      "X-App": "cli",
+      "X-Stainless-Helper-Method": "stream",
+      "X-Stainless-Retry-Count": "0",
+      "X-Stainless-Runtime-Version": "v24.14.0",
+      "X-Stainless-Package-Version": "0.80.0",
+      "X-Stainless-Runtime": "node",
+      "X-Stainless-Lang": "js",
+      "X-Stainless-Arch": "arm64",
+      "X-Stainless-Os": "MacOS",
+      "X-Stainless-Timeout": "600",
+    },
+    quirks: {
+      cloakToolsOnOAuth: true,
+    },
+    auth: {
+      apiKey: {
+        header: "x-api-key",
+        scheme: "raw",
+      },
+      oauth: {
+        header: "Authorization",
+        scheme: "bearer",
+      },
+      hooks: [
+        "claudeOverlay",
+      ],
+    },
+    usage: {
+      oauthUrl: "https://api.anthropic.com/api/oauth/usage",
+      orgUrl: "https://api.anthropic.com/v1/organizations/{org_id}/usage",
+      settingsUrl: "https://api.anthropic.com/v1/settings",
+    },
+  },
+  models: [
+    { id: "claude-fable-5", name: "Claude Fable 5" },
+    { id: "claude-sonnet-5", name: "Claude Sonnet 5" },
+    { id: "claude-opus-4-8", name: "Claude Opus 4.8" },
+    { id: "claude-opus-4-7", name: "Claude Opus 4.7" },
+    { id: "claude-haiku-4-5-20251001", name: "Claude 4.5 Haiku" },
+  ],
+  oauth: {
+    clientId: "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
+    authorizeUrl: "https://claude.ai/oauth/authorize",
+    tokenUrl: "https://api.anthropic.com/v1/oauth/token",
+    scopes: [
+      "org:create_api_key",
+      "user:profile",
+      "user:inference",
+    ],
+    codeChallengeMethod: "S256",
+    refreshLeadMs: 14400000,
+    refresh: {
+      encoding: "json",
+    },
+  },
+  features: {
+    usage: true,
+  },
+};
diff --git a/open-sse/providers/registry/cline.js b/open-sse/providers/registry/cline.js
new file mode 100644
index 0000000..cfa788c
--- /dev/null
+++ b/open-sse/providers/registry/cline.js
@@ -0,0 +1,51 @@
+export default {
+  id: "cline",
+  priority: 80,
+  alias: "cl",
+  uiAlias: "cl",
+  display: {
+    name: "Cline",
+    icon: "smart_toy",
+    color: "#5B9BD5",
+    textIcon: "CL",
+    website: "https://cline.bot",
+    notice: {
+      signupUrl: "https://cline.bot",
+    },
+  },
+  category: "oauth",
+  transport: {
+    baseUrl: "https://api.cline.bot/api/v1/chat/completions",
+    headers: {
+      "HTTP-Referer": "https://cline.bot",
+      "X-Title": "Cline",
+    },
+    tokenUrl: "https://api.cline.bot/api/v1/auth/token",
+    refreshUrl: "https://api.cline.bot/api/v1/auth/refresh",
+    auth: {
+      combined: true,
+      header: "Authorization",
+      scheme: "bearer",
+      hooks: [
+        "clineHeaders",
+      ],
+    },
+  },
+  models: [
+    { id: "anthropic/claude-opus-4.7", name: "Claude Opus 4.7" },
+    { id: "anthropic/claude-sonnet-4.6", name: "Claude Sonnet 4.6" },
+    { id: "anthropic/claude-opus-4.6", name: "Claude Opus 4.6" },
+    { id: "openai/gpt-5.3-codex", name: "GPT-5.3 Codex" },
+    { id: "openai/gpt-5.4", name: "GPT-5.4" },
+    { id: "google/gemini-3.1-pro-preview", name: "Gemini 3.1 Pro Preview" },
+    { id: "google/gemini-3.1-flash-lite-preview", name: "Gemini 3.1 Flash Lite Preview" },
+    { id: "kwaipilot/kat-coder-pro", name: "KAT Coder Pro" },
+  ],
+  oauth: {
+    appBaseUrl: "https://app.cline.bot",
+    apiBaseUrl: "https://api.cline.bot",
+    authorizeUrl: "https://api.cline.bot/api/v1/auth/authorize",
+    tokenExchangeUrl: "https://api.cline.bot/api/v1/auth/token",
+    refreshUrl: "https://api.cline.bot/api/v1/auth/refresh",
+  },
+};
diff --git a/open-sse/providers/registry/clinepass.js b/open-sse/providers/registry/clinepass.js
new file mode 100644
index 0000000..702054a
--- /dev/null
+++ b/open-sse/providers/registry/clinepass.js
@@ -0,0 +1,57 @@
+export default {
+  id: "clinepass",
+  priority: 85,
+  alias: "clinepass",
+  uiAlias: "clinepass",
+  display: {
+    name: "ClinePass",
+    icon: "vpn_key",
+    color: "#5B9BD5",
+    textIcon: "CP",
+    website: "https://cline.bot",
+    notice: {
+      signupUrl: "https://app.cline.bot",
+    },
+  },
+  category: "oauth",
+  authModes: ["oauth", "apikey"],
+  hasOAuth: true,
+  transport: {
+    baseUrl: "https://api.cline.bot/api/v1/chat/completions",
+    headers: {
+      "HTTP-Referer": "https://cline.bot",
+      "X-Title": "Cline",
+    },
+    auth: {
+      combined: true,
+      header: "Authorization",
+      scheme: "bearer",
+      hooks: [
+        "clineHeaders",
+      ],
+    },
+  },
+  models: [
+    { id: "cline-pass/glm-5.2", name: "GLM-5.2 (ClinePass)" },
+    { id: "cline-pass/kimi-k2.7-code", name: "Kimi K2.7 Code (ClinePass)" },
+    { id: "cline-pass/kimi-k2.6", name: "Kimi K2.6 (ClinePass)" },
+    { id: "cline-pass/deepseek-v4-pro", name: "DeepSeek V4 Pro (ClinePass)" },
+    { id: "cline-pass/deepseek-v4-flash", name: "DeepSeek V4 Flash (ClinePass)" },
+    { id: "cline-pass/mimo-v2.5", name: "MiMo-V2.5 (ClinePass)" },
+    { id: "cline-pass/mimo-v2.5-pro", name: "MiMo-V2.5-Pro (ClinePass)" },
+    { id: "cline-pass/minimax-m3", name: "MiniMax M3 (ClinePass)" },
+    { id: "cline-pass/qwen3.7-max", name: "Qwen3.7 Max (ClinePass)" },
+    { id: "cline-pass/qwen3.7-plus", name: "Qwen3.7 Plus (ClinePass)" },
+  ],
+  oauth: {
+    appBaseUrl: "https://app.cline.bot",
+    apiBaseUrl: "https://api.cline.bot",
+    authorizeUrl: "https://api.cline.bot/api/v1/auth/authorize",
+    tokenUrl: "https://api.cline.bot/api/v1/auth/token",
+    refreshUrl: "https://api.cline.bot/api/v1/auth/refresh",
+  },
+  thinkingConfig: {
+    options: ["auto", "on", "off"],
+    defaultMode: "auto",
+  },
+};
diff --git a/open-sse/providers/registry/cloudflare-ai.js b/open-sse/providers/registry/cloudflare-ai.js
new file mode 100644
index 0000000..4d440b7
--- /dev/null
+++ b/open-sse/providers/registry/cloudflare-ai.js
@@ -0,0 +1,55 @@
+export default {
+  id: "cloudflare-ai",
+  priority: 60,
+  hasFree: true,
+  alias: "cloudflare-ai",
+  aliases: [
+    "cf",
+  ],
+  uiAlias: "cf",
+  display: {
+    name: "Cloudflare",
+    icon: "cloud",
+    color: "#F38020",
+    textIcon: "CF",
+    website: "https://developers.cloudflare.com/workers-ai/",
+    notice: {
+      text: "Workers AI free tier. Requires a Cloudflare API token and Account ID.",
+      apiKeyUrl: "https://dash.cloudflare.com/profile/api-tokens",
+    },
+  },
+  category: "freeTier",
+  hasProviderSpecificData: true,
+  transport: {
+    baseUrl: "https://api.cloudflare.com/client/v4/accounts/{accountId}/ai/v1/chat/completions",
+    thinkingFormat: "openai",
+  },
+  models: [
+    { id: "@cf/meta/llama-3.2-1b-instruct", name: "Llama 3.2 1B Instruct" },
+    { id: "@cf/meta/llama-3.2-3b-instruct", name: "Llama 3.2 3B Instruct" },
+    { id: "@cf/meta/llama-3.1-8b-instruct-fp8-fast", name: "Llama 3.1 8B Instruct FP8 Fast" },
+    { id: "@cf/meta/llama-3.1-8b-instruct-awq", name: "Llama 3.1 8B Instruct AWQ" },
+    { id: "@cf/mistralai/mistral-small-3.1-24b-instruct", name: "Mistral Small 3.1 24B Instruct" },
+    { id: "@cf/meta/llama-3.1-70b-instruct-fp8-fast", name: "Llama 3.1 70B Instruct FP8 Fast" },
+    { id: "@cf/meta/llama-3.3-70b-instruct-fp8-fast", name: "Llama 3.3 70B Instruct FP8 Fast" },
+    { id: "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b", name: "DeepSeek R1 Distill Qwen 32B" },
+    { id: "@cf/moonshotai/kimi-k2.5", name: "Kimi K2.5" },
+    { id: "@cf/moonshotai/kimi-k2.6", name: "Kimi K2.6" },
+    { id: "@cf/zai-org/glm-4.7-flash", name: "GLM 4.7 Flash" },
+    { id: "@cf/qwen/qwq-32b", name: "QwQ 32B" },
+    { id: "@cf/qwen/qwen2.5-coder-32b-instruct", name: "Qwen 2.5 Coder 32B Instruct" },
+    { id: "@cf/black-forest-labs/flux-2-klein-9b", name: "FLUX.2 Klein 9B", params: ["size"], kind: "image" },
+    { id: "@cf/black-forest-labs/flux-2-klein-4b", name: "FLUX.2 Klein 4B", params: ["size"], kind: "image" },
+    { id: "@cf/black-forest-labs/flux-2-dev", name: "FLUX.2 Dev", params: ["size"], kind: "image" },
+    { id: "@cf/leonardo/lucid-origin", name: "Lucid Origin", params: ["size"], kind: "image" },
+    { id: "@cf/leonardo/phoenix-1.0", name: "Phoenix 1.0", params: ["size"], kind: "image" },
+    { id: "@cf/black-forest-labs/flux-1-schnell", name: "FLUX.1 Schnell", params: ["size"], kind: "image" },
+    { id: "@cf/bytedance/stable-diffusion-xl-lightning", name: "SDXL Lightning", params: ["size"], kind: "image" },
+    { id: "@cf/lykon/dreamshaper-8-lcm", name: "DreamShaper 8 LCM", params: ["size"], kind: "image" },
+    { id: "@cf/runwayml/stable-diffusion-v1-5-img2img", name: "Stable Diffusion v1.5 Img2Img", params: ["size"], capabilities: ["edit"], kind: "image" },
+    { id: "@cf/runwayml/stable-diffusion-v1-5-inpainting", name: "Stable Diffusion v1.5 Inpainting", params: ["size"], capabilities: ["edit","mask"], kind: "image" },
+    { id: "@cf/stabilityai/stable-diffusion-xl-base-1.0", name: "SDXL Base 1.0", params: ["size"], kind: "image" },
+  ],
+  serviceKinds: ["llm","image"],
+  imageConfig: { baseUrl: "https://api.cloudflare.com/client/v4/accounts" },
+};
diff --git a/open-sse/providers/registry/codebuddy-cn.js b/open-sse/providers/registry/codebuddy-cn.js
new file mode 100644
index 0000000..01a78a3
--- /dev/null
+++ b/open-sse/providers/registry/codebuddy-cn.js
@@ -0,0 +1,77 @@
+export default {
+  id: "codebuddy-cn",
+  // Short model prefix (cbcn/glm-5.2). "cbcn" = CodeBuddy CN; reserve "cbai"
+  // for a future codebuddy-ai (intl) provider. The full id still resolves.
+  alias: "cbcn",
+  uiAlias: "cbcn",
+  hidden: false,
+  priority: 90,
+  display: {
+    name: "CodeBuddy CN",
+    icon: "smart_toy",
+    color: "#006EFF",
+    website: "https://copilot.tencent.com",
+    notice: {
+      signupUrl: "https://copilot.tencent.com",
+    },
+  },
+  category: "oauth",
+  authModes: ["oauth", "apikey"],
+  hasOAuth: true,
+  transport: {
+    baseUrl: "https://copilot.tencent.com/v2/chat/completions",
+    forceStream: true,
+    // CodeBuddy is a unified OpenAI-compatible gateway: every model (GLM, Kimi,
+    // MiniMax, DeepSeek, Hunyuan) takes reasoning via OpenAI-style reasoning_effort,
+    // not its vendor-native thinking shape. Force the openai thinking format.
+    thinkingFormat: "openai",
+    headers: {
+      "User-Agent": "CLI/2.108.1 CodeBuddy/2.108.1",
+      "X-Product": "SaaS",
+      "X-IDE-Type": "CLI",
+      "X-IDE-Name": "CLI",
+      "x-requested-with": "XMLHttpRequest",
+      "x-codebuddy-request": "1",
+    },
+    auth: {
+      combined: true,
+      header: "Authorization",
+      scheme: "bearer",
+    },
+    // Quota endpoint differs from the chat gateway: POST returns nested Tencent
+    // billing payload (data.Response.Data.Accounts[]). See services/usage/codebuddy-cn.js.
+    usage: {
+      url: "https://copilot.tencent.com/v2/billing/meter/get-user-resource",
+    },
+  },
+  models: [
+    { id: "glm-5.2", name: "GLM-5.2" },
+    { id: "glm-5.1", name: "GLM-5.1" },
+    { id: "glm-5.0", name: "GLM-5.0" },
+    { id: "glm-5.0-turbo", name: "GLM-5.0-Turbo" },
+    { id: "glm-5v-turbo", name: "GLM-5v-Turbo" },
+    { id: "glm-4.7", name: "GLM-4.7" },
+    { id: "minimax-m3", name: "MiniMax-M3" },
+    { id: "minimax-m2.7", name: "MiniMax-M2.7" },
+    { id: "kimi-k2.7", name: "Kimi-K2.7-Code" },
+    { id: "kimi-k2.6", name: "Kimi-K2.6" },
+    { id: "kimi-k2.5", name: "Kimi-K2.5" },
+    { id: "hy3-preview", name: "Hy3 Preview" },
+    { id: "deepseek-v4-pro", name: "DeepSeek-V4-Pro" },
+    { id: "deepseek-v4-flash", name: "DeepSeek-V4-Flash" },
+    { id: "deepseek-v3-2-volc", name: "DeepSeek-V3.2" },
+  ],
+  oauth: {
+    baseUrl: "https://copilot.tencent.com",
+    stateUrl: "https://copilot.tencent.com/v2/plugin/auth/state",
+    tokenUrl: "https://copilot.tencent.com/v2/plugin/auth/token",
+    refreshUrl: "https://copilot.tencent.com/v2/plugin/auth/token/refresh",
+    userAgent: "CLI/2.63.2 CodeBuddy/2.63.2",
+    platform: "CLI",
+    pollInterval: 5000,
+  },
+  features: {
+    usage: true,
+    usageApikey: true,
+  },
+};
diff --git a/open-sse/providers/registry/codex.js b/open-sse/providers/registry/codex.js
new file mode 100644
index 0000000..6fc7501
--- /dev/null
+++ b/open-sse/providers/registry/codex.js
@@ -0,0 +1,91 @@
+import { withCodexReviewModels } from "../models/helpers.js";
+
+export default {
+  id: "codex",
+  priority: 30,
+  alias: "cx",
+  uiAlias: "cx",
+  display: {
+    name: "OpenAI Codex",
+    icon: "code",
+    color: "#3B82F6",
+    website: "https://chatgpt.com/codex",
+    notice: {
+      signupUrl: "https://chatgpt.com/codex",
+    },
+    deprecated: true,
+    deprecationNotice: "RISK_NOTICE",
+    kindNotice: {
+      image: "Requires a ChatGPT Plus (or higher) account. Free accounts are not supported for image generation.",
+    },
+  },
+  category: "oauth",
+  thinkingConfig: {
+    options: [
+      "auto",
+      "none",
+      "low",
+      "medium",
+      "high",
+    ],
+    defaultMode: "auto",
+  },
+  transport: {
+    baseUrl: "https://chatgpt.com/backend-api/codex/responses",
+    format: "openai-responses",
+    forceStream: true,
+    headers: {
+      originator: "codex_cli_rs",
+      "User-Agent": "codex_cli_rs/0.136.0",
+    },
+    usage: {
+      url: "https://chatgpt.com/backend-api/wham/usage",
+      resetCreditsUrl: "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits",
+      resetCreditsConsumeUrl: "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume",
+    },
+  },
+  models: [
+    { id: "gpt-5.6-sol", name: "GPT 5.6 Sol" },
+    { id: "gpt-5.6-sol-review", name: "GPT 5.6 Sol Review", upstreamModelId: "gpt-5.6-sol", quotaFamily: "review" },
+    { id: "gpt-5.6-terra", name: "GPT 5.6 Terra" },
+    { id: "gpt-5.6-terra-review", name: "GPT 5.6 Terra Review", upstreamModelId: "gpt-5.6-terra", quotaFamily: "review" },
+    { id: "gpt-5.6-luna", name: "GPT 5.6 Luna" },
+    { id: "gpt-5.6-luna-review", name: "GPT 5.6 Luna Review", upstreamModelId: "gpt-5.6-luna", quotaFamily: "review" },
+    { id: "gpt-5.5", name: "GPT 5.5" },
+    { id: "gpt-5.5-review", name: "GPT 5.5 Review", upstreamModelId: "gpt-5.5", quotaFamily: "review" },
+    { id: "gpt-5.4", name: "GPT 5.4" },
+    { id: "gpt-5.4-review", name: "GPT 5.4 Review", upstreamModelId: "gpt-5.4", quotaFamily: "review" },
+    { id: "gpt-5.4-mini", name: "GPT 5.4 Mini" },
+    { id: "gpt-5.4-mini-review", name: "GPT 5.4 Mini Review", upstreamModelId: "gpt-5.4-mini", quotaFamily: "review" },
+    { id: "gpt-5.3-codex-spark", name: "GPT 5.3 Codex Spark" },
+    { id: "gpt-5.3-codex-spark-review", name: "GPT 5.3 Codex Spark Review", upstreamModelId: "gpt-5.3-codex-spark", quotaFamily: "review" },
+    { id: "gpt-5.5-image", name: "GPT 5.5 Image", capabilities: ["text2img","edit"], params: ["size","quality","background","image_detail","output_format"], kind: "image" },
+    { id: "gpt-5.4-image", name: "GPT 5.4 Image", capabilities: ["text2img","edit"], params: ["size","quality","background","image_detail","output_format"], kind: "image" },
+    { id: "gpt-5.3-image", name: "GPT 5.3 Image", capabilities: ["text2img","edit"], params: ["size","quality","background","image_detail","output_format"], kind: "image" },
+  ],
+  serviceKinds: ["llm","image"],
+  oauth: {
+    clientId: "app_EMoamEEZ73f0CkXaXp7hrann",
+    authorizeUrl: "https://auth.openai.com/oauth/authorize",
+    tokenUrl: "https://auth.openai.com/oauth/token",
+    scope: "openid profile email offline_access",
+    codeChallengeMethod: "S256",
+    fixedPort: 1455,
+    callbackPath: "/auth/callback",
+    extraParams: {
+      id_token_add_organizations: "true",
+      codex_cli_simplified_flow: "true",
+      originator: "codex_cli_rs",
+    },
+    refreshLeadMs: 432000000,
+    refresh: {
+      encoding: "form",
+      scope: "openid profile email offline_access",
+    },
+    maxRefreshAgeMs: 691200000,
+    trackRefreshAt: true,
+  },
+  features: {
+    usage: true,
+  },
+};
diff --git a/open-sse/providers/registry/cohere.js b/open-sse/providers/registry/cohere.js
new file mode 100644
index 0000000..68236bb
--- /dev/null
+++ b/open-sse/providers/registry/cohere.js
@@ -0,0 +1,25 @@
+export default {
+  id: "cohere",
+  priority: 90,
+  alias: "cohere",
+  display: {
+    name: "Cohere",
+    icon: "hub",
+    color: "#39594D",
+    textIcon: "CO",
+    website: "https://cohere.com",
+    notice: {
+      apiKeyUrl: "https://dashboard.cohere.com/api-keys",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.cohere.ai/v1/chat/completions",
+    validateUrl: "https://api.cohere.ai/v1/models",
+  },
+  models: [
+    { id: "command-r-plus-08-2024", name: "Command R+ (Aug 2024)" },
+    { id: "command-r-08-2024", name: "Command R (Aug 2024)" },
+    { id: "command-a-03-2025", name: "Command A (Mar 2025)" },
+  ],
+};
diff --git a/open-sse/providers/registry/comfyui.js b/open-sse/providers/registry/comfyui.js
new file mode 100644
index 0000000..74216fa
--- /dev/null
+++ b/open-sse/providers/registry/comfyui.js
@@ -0,0 +1,20 @@
+export default {
+  id: "comfyui",
+  priority: 120,
+  alias: "comfyui",
+  display: {
+    name: "ComfyUI",
+    icon: "account_tree",
+    color: "#4CAF50",
+    textIcon: "CF",
+    website: "https://github.com/comfyanonymous/ComfyUI",
+  },
+  category: "apikey",
+  transport: null,
+  models: [
+    { id: "flux-dev", name: "FLUX Dev", params: ["n","size"], kind: "image" },
+    { id: "sdxl", name: "SDXL", params: ["n","size"], kind: "image" },
+  ],
+  serviceKinds: ["image"],
+  imageConfig: { baseUrl: "http://localhost:8188" },
+};
diff --git a/open-sse/providers/registry/commandcode.js b/open-sse/providers/registry/commandcode.js
new file mode 100644
index 0000000..3b21fbb
--- /dev/null
+++ b/open-sse/providers/registry/commandcode.js
@@ -0,0 +1,43 @@
+export default {
+  id: "commandcode",
+  priority: 100,
+  alias: "commandcode",
+  aliases: [
+    "cmc",
+  ],
+  uiAlias: "cmc",
+  display: {
+    name: "Command Code",
+    icon: "smart_toy",
+    color: "#000000",
+    textIcon: "CC",
+    website: "https://commandcode.ai",
+    notice: {
+      text: "Use your CommandCode CLI API key (starts with user_...) from ~/.commandcode/auth.json or commandcode.ai/studio.",
+      apiKeyUrl: "https://commandcode.ai/studio",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.commandcode.ai/alpha/generate",
+    format: "commandcode",
+    forceStream: true,
+    headers: {
+      "x-command-code-version": "0.25.7",
+      "x-cli-environment": "cli",
+    },
+  },
+  models: [
+    { id: "deepseek/deepseek-v4-pro", name: "DeepSeek V4 Pro" },
+    { id: "deepseek/deepseek-v4-flash", name: "DeepSeek V4 Flash" },
+    { id: "moonshotai/Kimi-K2.6", name: "Kimi K2.6" },
+    { id: "moonshotai/Kimi-K2.5", name: "Kimi K2.5" },
+    { id: "zai-org/GLM-5.1", name: "GLM 5.1" },
+    { id: "zai-org/GLM-5", name: "GLM 5" },
+    { id: "MiniMaxAI/MiniMax-M2.7", name: "MiniMax M2.7" },
+    { id: "MiniMaxAI/MiniMax-M2.5", name: "MiniMax M2.5" },
+    { id: "Qwen/Qwen3.6-Max-Preview", name: "Qwen 3.6 Max Preview" },
+    { id: "Qwen/Qwen3.6-Plus", name: "Qwen 3.6 Plus" },
+    { id: "stepfun/Step-3.5-Flash", name: "Step 3.5 Flash" },
+  ],
+};
diff --git a/open-sse/providers/registry/coqui.js b/open-sse/providers/registry/coqui.js
new file mode 100644
index 0000000..8f108e2
--- /dev/null
+++ b/open-sse/providers/registry/coqui.js
@@ -0,0 +1,30 @@
+export default {
+  id: "coqui",
+  alias: "coqui",
+  display: {
+    name: "Coqui TTS",
+    icon: "record_voice_over",
+    color: "#10B981",
+    textIcon: "CQ",
+    website: "https://github.com/coqui-ai/TTS"
+  },
+  category: "freeTier",
+  authType: "none",
+  serviceKinds: [
+    "tts"
+  ],
+  noAuth: true,
+  ttsConfig: {
+    baseUrl: "http://localhost:5002/api/tts",
+    authType: "none",
+    authHeader: "none",
+    format: "coqui",
+    models: [
+      {
+        id: "tts_models/en/ljspeech/tacotron2-DDC",
+        name: "Tacotron2 DDC (LJSpeech)"
+      }
+    ]
+  },
+  hidden: true
+};
diff --git a/open-sse/providers/registry/cursor.js b/open-sse/providers/registry/cursor.js
new file mode 100644
index 0000000..ca0ecdb
--- /dev/null
+++ b/open-sse/providers/registry/cursor.js
@@ -0,0 +1,58 @@
+export default {
+  id: "cursor",
+  priority: 50,
+  alias: "cu",
+  uiAlias: "cu",
+  display: {
+    name: "Cursor IDE",
+    icon: "edit_note",
+    color: "#00D4AA",
+    website: "https://cursor.com",
+    notice: {
+      signupUrl: "https://cursor.com",
+    },
+  },
+  category: "oauth",
+  transport: {
+    baseUrl: "https://api2.cursor.sh",
+    chatPath: "/aiserver.v1.ChatService/StreamUnifiedChatWithTools",
+    format: "cursor",
+    headers: {
+      "connect-accept-encoding": "gzip",
+      "connect-protocol-version": "1",
+      "Content-Type": "application/connect+proto",
+      "User-Agent": "connect-es/1.6.1",
+    },
+    clientVersion: "3.1.0",
+  },
+  models: [
+    { id: "default", name: "Auto (Server Picks)" },
+    { id: "claude-4.5-opus-high-thinking", name: "Claude 4.5 Opus High Thinking" },
+    { id: "claude-4.5-opus-high", name: "Claude 4.5 Opus High" },
+    { id: "claude-4.5-sonnet-thinking", name: "Claude 4.5 Sonnet Thinking" },
+    { id: "claude-4.5-sonnet", name: "Claude 4.5 Sonnet" },
+    { id: "claude-4.5-haiku", name: "Claude 4.5 Haiku" },
+    { id: "claude-4.5-opus", name: "Claude 4.5 Opus" },
+    { id: "gpt-5.2-codex", name: "GPT 5.2 Codex" },
+    { id: "claude-4.6-opus-max", name: "Claude 4.6 Opus Max" },
+    { id: "claude-4.6-sonnet-medium-thinking", name: "Claude 4.6 Sonnet Medium Thinking" },
+    { id: "kimi-k2.5", name: "Kimi K2.5" },
+    { id: "gemini-3-flash-preview", name: "Gemini 3 Flash Preview" },
+    { id: "gpt-5.2", name: "GPT 5.2" },
+    { id: "gpt-5.3-codex", name: "GPT 5.3 Codex" },
+  ],
+  oauth: {
+    apiEndpoint: "https://api2.cursor.sh",
+    chatEndpoint: "/aiserver.v1.ChatService/StreamUnifiedChatWithTools",
+    modelsEndpoint: "/aiserver.v1.AiService/GetDefaultModelNudgeData",
+    api3Endpoint: "https://api3.cursor.sh",
+    agentEndpoint: "https://agent.api5.cursor.sh",
+    agentNonPrivacyEndpoint: "https://agentn.api5.cursor.sh",
+    clientVersion: "3.1.0",
+    clientType: "ide",
+    dbKeys: {
+      accessToken: "cursorAuth/accessToken",
+      machineId: "storage.serviceMachineId",
+    },
+  },
+};
diff --git a/open-sse/providers/registry/deepgram.js b/open-sse/providers/registry/deepgram.js
new file mode 100644
index 0000000..9d2b41a
--- /dev/null
+++ b/open-sse/providers/registry/deepgram.js
@@ -0,0 +1,33 @@
+export default {
+  id: "deepgram",
+  priority: 20,
+  alias: "deepgram",
+  aliases: [
+    "dg",
+  ],
+  uiAlias: "dg",
+  display: {
+    name: "Deepgram",
+    icon: "mic",
+    color: "#13EF93",
+    textIcon: "DG",
+    website: "https://deepgram.com",
+    notice: {
+      text: "$200 free credit on signup (no card required). Aura-1: $0.015/1k chars, Aura-2: $0.030/1k chars (Pay-As-You-Go).",
+      apiKeyUrl: "https://console.deepgram.com/api-keys",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: {
+    baseUrl: "https://api.deepgram.com/v1/listen",
+  },
+  models: [
+    { id: "nova-3", name: "Nova 3", params: ["language"], kind: "stt" },
+    { id: "nova-2", name: "Nova 2", params: ["language"], kind: "stt" },
+    { id: "whisper-large", name: "Whisper Large", params: ["language"], kind: "stt" },
+    { id: "nova", name: "Nova", kind: "stt" },
+  ],
+  serviceKinds: ["stt"],
+  sttConfig: { baseUrl: "https://api.deepgram.com/v1/listen", authType: "apikey", authHeader: "token", format: "deepgram" },
+};
diff --git a/open-sse/providers/registry/deepseek.js b/open-sse/providers/registry/deepseek.js
new file mode 100644
index 0000000..5c167f7
--- /dev/null
+++ b/open-sse/providers/registry/deepseek.js
@@ -0,0 +1,51 @@
+import { CLAUDE_API_HEADERS } from "../shared.js";
+
+export default {
+  id: "deepseek",
+  priority: 110,
+  alias: "deepseek",
+  aliases: [
+    "ds",
+  ],
+  uiAlias: "ds",
+  display: {
+    name: "DeepSeek",
+    icon: "bolt",
+    color: "#4D6BFE",
+    textIcon: "DS",
+    website: "https://deepseek.com",
+    notice: {
+      apiKeyUrl: "https://platform.deepseek.com/api_keys",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.deepseek.com/chat/completions",
+    validateUrl: "https://api.deepseek.com/models",
+    reasoningInject: {
+      scope: "all",
+    },
+  },
+  // Multi-endpoint: pick the transport matching client sourceFormat to skip translation.
+  transports: [
+    {
+      format: "openai",
+      baseUrl: "https://api.deepseek.com/chat/completions",
+      auth: { combined: true, header: "Authorization", scheme: "bearer" },
+    },
+    {
+      format: "claude",
+      baseUrl: "https://api.deepseek.com/anthropic/v1/messages",
+      headers: { ...CLAUDE_API_HEADERS },
+      auth: { combined: true, header: "x-api-key", scheme: "raw" },
+    },
+  ],
+  models: [
+    { id: "deepseek-v4-pro", name: "DeepSeek V4 Pro" },
+    { id: "deepseek-v4-pro-max", name: "DeepSeek V4 Pro Max", upstreamModelId: "deepseek-v4-pro" },
+    { id: "deepseek-v4-pro-none", name: "DeepSeek V4 Pro No Thinking", upstreamModelId: "deepseek-v4-pro" },
+    { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash" },
+    { id: "deepseek-chat", name: "DeepSeek V3.2 Chat" },
+    { id: "deepseek-reasoner", name: "DeepSeek V3.2 Reasoner" },
+  ],
+};
diff --git a/open-sse/providers/registry/edge-tts.js b/open-sse/providers/registry/edge-tts.js
new file mode 100644
index 0000000..74781e8
--- /dev/null
+++ b/open-sse/providers/registry/edge-tts.js
@@ -0,0 +1,24 @@
+export default {
+  id: "edge-tts",
+  alias: "edge-tts",
+  display: {
+    name: "Edge TTS",
+    icon: "record_voice_over",
+    color: "#0078D4",
+    textIcon: "ET"
+  },
+  category: "freeTier",
+  authType: "none",
+  serviceKinds: [
+    "tts"
+  ],
+  mediaPriority: 5,
+  noAuth: true,
+  ttsConfig: {
+    baseUrl: "edge-tts",
+    authType: "none",
+    authHeader: "none",
+    format: "edge-tts",
+    models: []
+  }
+};
diff --git a/open-sse/providers/registry/elevenlabs.js b/open-sse/providers/registry/elevenlabs.js
new file mode 100644
index 0000000..fad3227
--- /dev/null
+++ b/open-sse/providers/registry/elevenlabs.js
@@ -0,0 +1,35 @@
+export default {
+  id: "elevenlabs",
+  alias: "el",
+  display: {
+    name: "ElevenLabs",
+    icon: "record_voice_over",
+    color: "#6C47FF",
+    textIcon: "EL",
+    website: "https://elevenlabs.io",
+    notice: {
+      apiKeyUrl: "https://elevenlabs.io/app/settings/api-keys"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "tts"
+  ],
+  ttsConfig: {
+    baseUrl: "https://api.elevenlabs.io/v1/text-to-speech",
+    authType: "apikey",
+    authHeader: "xi-api-key",
+    format: "elevenlabs",
+    models: [
+      {
+        id: "eleven_multilingual_v2",
+        name: "Eleven Multilingual v2"
+      },
+      {
+        id: "eleven_turbo_v2_5",
+        name: "Eleven Turbo v2.5"
+      }
+    ]
+  }
+};
diff --git a/open-sse/providers/registry/exa.js b/open-sse/providers/registry/exa.js
new file mode 100644
index 0000000..75b8bf0
--- /dev/null
+++ b/open-sse/providers/registry/exa.js
@@ -0,0 +1,50 @@
+export default {
+  id: "exa",
+  alias: "exa",
+  display: {
+    name: "Exa",
+    icon: "manage_search",
+    color: "#2563EB",
+    textIcon: "EX",
+    website: "https://exa.ai",
+    notice: {
+      apiKeyUrl: "https://dashboard.exa.ai/api-keys"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "webSearch",
+    "webFetch"
+  ],
+  searchConfig: {
+    baseUrl: "https://api.exa.ai/search",
+    method: "POST",
+    authType: "apikey",
+    authHeader: "x-api-key",
+    costPerQuery: 0.007,
+    freeMonthlyQuota: 1000,
+    searchTypes: [
+      "web",
+      "news"
+    ],
+    defaultMaxResults: 5,
+    maxMaxResults: 100,
+    timeoutMs: 10000,
+    cacheTTLMs: 300000
+  },
+  fetchConfig: {
+    baseUrl: "https://api.exa.ai/contents",
+    method: "POST",
+    authType: "apikey",
+    authHeader: "x-api-key",
+    costPerQuery: 0.001,
+    freeMonthlyQuota: 1000,
+    formats: [
+      "text",
+      "markdown"
+    ],
+    maxCharacters: 100000,
+    timeoutMs: 15000
+  }
+};
diff --git a/open-sse/providers/registry/fal-ai.js b/open-sse/providers/registry/fal-ai.js
new file mode 100644
index 0000000..a18d7d0
--- /dev/null
+++ b/open-sse/providers/registry/fal-ai.js
@@ -0,0 +1,34 @@
+export default {
+  id: "fal-ai",
+  priority: 90,
+  hasFree: true,
+  alias: "fal-ai",
+  aliases: [
+    "fal",
+  ],
+  uiAlias: "fal",
+  display: {
+    name: "Fal.ai",
+    icon: "image",
+    color: "#2563EB",
+    textIcon: "FL",
+    website: "https://fal.ai",
+    notice: {
+      apiKeyUrl: "https://fal.ai/dashboard/keys",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: null,
+  models: [
+    { id: "fal-ai/flux/schnell", name: "FLUX Schnell", params: ["n","size"], kind: "image" },
+    { id: "fal-ai/flux/dev", name: "FLUX Dev", params: ["n","size"], kind: "image" },
+    { id: "fal-ai/flux-pro/v1.1", name: "FLUX Pro v1.1", params: ["n","size"], kind: "image" },
+    { id: "fal-ai/flux-pro/v1.1-ultra", name: "FLUX Pro v1.1 Ultra", params: ["n","size"], kind: "image" },
+    { id: "fal-ai/recraft-v3", name: "Recraft V3", params: ["n","size","style"], kind: "image" },
+    { id: "fal-ai/ideogram/v2", name: "Ideogram V2", params: ["n","size","style"], kind: "image" },
+    { id: "fal-ai/stable-diffusion-v35-large", name: "SD 3.5 Large", params: ["n","size"], kind: "image" },
+  ],
+  serviceKinds: ["image"],
+  imageConfig: { baseUrl: "https://queue.fal.run" },
+};
diff --git a/open-sse/providers/registry/featherless.js b/open-sse/providers/registry/featherless.js
new file mode 100644
index 0000000..85240df
--- /dev/null
+++ b/open-sse/providers/registry/featherless.js
@@ -0,0 +1,34 @@
+export default {
+  id: "featherless",
+  priority: 65,
+  alias: "featherless",
+  aliases: [
+    "fl",
+  ],
+  uiAlias: "fl",
+  display: {
+    name: "Featherless",
+    icon: "flutter_dash",
+    color: "#111827",
+    textIcon: "FL",
+    website: "https://featherless.ai",
+    notice: {
+      apiKeyUrl: "https://featherless.ai/account/api-keys",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: {
+    baseUrl: "https://api.featherless.ai/v1/chat/completions",
+    validateUrl: "https://api.featherless.ai/v1/models",
+  },
+  models: [
+    { id: "deepseek-ai/DeepSeek-V4-Pro", name: "DeepSeek V4 Pro" },
+    { id: "deepseek-ai/DeepSeek-V4-Flash", name: "DeepSeek V4 Flash" },
+    { id: "zai-org/GLM-5.2", name: "GLM 5.2" },
+    { id: "zai-org/GLM-5.1", name: "GLM 5.1" },
+    { id: "moonshotai/Kimi-K2.7-Code", name: "Kimi K2.7 Code" },
+    { id: "moonshotai/Kimi-K2.6", name: "Kimi K2.6" },
+    { id: "moonshotai/Kimi-K2.5", name: "Kimi K2.5" },
+  ],
+};
diff --git a/open-sse/providers/registry/firecrawl.js b/open-sse/providers/registry/firecrawl.js
new file mode 100644
index 0000000..fab98fd
--- /dev/null
+++ b/open-sse/providers/registry/firecrawl.js
@@ -0,0 +1,34 @@
+export default {
+  id: "firecrawl",
+  alias: "firecrawl",
+  display: {
+    name: "Firecrawl",
+    icon: "local_fire_department",
+    color: "#F59E0B",
+    textIcon: "FC",
+    website: "https://firecrawl.dev",
+    notice: {
+      apiKeyUrl: "https://www.firecrawl.dev/app/api-keys"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "webFetch"
+  ],
+  fetchConfig: {
+    baseUrl: "https://api.firecrawl.dev/v1/scrape",
+    method: "POST",
+    authType: "apikey",
+    authHeader: "bearer",
+    costPerQuery: 0.002,
+    freeMonthlyQuota: 500,
+    formats: [
+      "markdown",
+      "html",
+      "text"
+    ],
+    maxCharacters: 200000,
+    timeoutMs: 30000
+  }
+};
diff --git a/open-sse/providers/registry/fireworks.js b/open-sse/providers/registry/fireworks.js
new file mode 100644
index 0000000..211fd59
--- /dev/null
+++ b/open-sse/providers/registry/fireworks.js
@@ -0,0 +1,29 @@
+export default {
+  id: "fireworks",
+  priority: 50,
+  alias: "fireworks",
+  display: {
+    name: "Fireworks AI",
+    icon: "local_fire_department",
+    color: "#7B2EF2",
+    textIcon: "FW",
+    website: "https://fireworks.ai",
+    notice: {
+      apiKeyUrl: "https://fireworks.ai/account/api-keys",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: {
+    baseUrl: "https://api.fireworks.ai/inference/v1/chat/completions",
+    validateUrl: "https://api.fireworks.ai/inference/v1/models",
+  },
+  models: [
+    { id: "accounts/fireworks/models/deepseek-v3p1", name: "DeepSeek V3.1" },
+    { id: "accounts/fireworks/models/llama-v3p3-70b-instruct", name: "Llama 3.3 70B" },
+    { id: "accounts/fireworks/models/qwen3-235b-a22b", name: "Qwen3 235B" },
+    { id: "nomic-ai/nomic-embed-text-v1.5", name: "Nomic Embed Text v1.5", kind: "embedding" },
+  ],
+  serviceKinds: ["llm", "embedding"],
+  embeddingConfig: { baseUrl: "https://api.fireworks.ai/inference/v1/embeddings" },
+};
diff --git a/open-sse/providers/registry/gemini-cli.js b/open-sse/providers/registry/gemini-cli.js
new file mode 100644
index 0000000..3e4a94c
--- /dev/null
+++ b/open-sse/providers/registry/gemini-cli.js
@@ -0,0 +1,58 @@
+import { GOOGLE_OAUTH_CLIENT } from "../shared.js";
+
+export default {
+  id: "gemini-cli",
+  priority: 20,
+  hasFree: true,
+  alias: "gc",
+  uiAlias: "gc",
+  display: {
+    name: "Gemini CLI",
+    icon: "terminal",
+    color: "#4285F4",
+    website: "https://github.com/google-gemini/gemini-cli",
+    notice: {
+      signupUrl: "https://github.com/google-gemini/gemini-cli",
+    },
+    deprecated: true,
+    deprecationNotice: "RISK_NOTICE",
+  },
+  category: "free",
+  transport: {
+    baseUrl: "https://cloudcode-pa.googleapis.com/v1internal",
+    format: "gemini-cli",
+    cliVersion: "0.34.0",
+    apiClient: "google-genai-sdk/1.41.0 gl-node/v22.19.0",
+    usage: {
+      quotaUrl: "https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuota",
+      loadCodeAssistUrl: "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+    },
+    clientId: "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com",
+    clientSecret: "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",
+  },
+  models: [
+    { id: "gemini-3.1-pro-preview", name: "Gemini 3.1 Pro Preview" },
+    { id: "gemini-3-pro-preview", name: "Gemini 3 Pro Preview" },
+    { id: "gemini-3-flash-preview", name: "Gemini 3 Flash Preview" },
+    { id: "gemini-3.1-flash-lite-preview", name: "Gemini 3.1 Flash Lite Preview" },
+    { id: "gemini-2.5-pro", name: "Gemini 2.5 Pro" },
+    { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
+    { id: "gemini-2.5-flash-lite", name: "Gemini 2.5 Flash Lite" },
+  ],
+  oauth: {
+    authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenUrl: "https://oauth2.googleapis.com/token",
+    userInfoUrl: "https://www.googleapis.com/oauth2/v1/userinfo",
+    scopes: [
+      "https://www.googleapis.com/auth/cloud-platform",
+      "https://www.googleapis.com/auth/userinfo.email",
+      "https://www.googleapis.com/auth/userinfo.profile",
+    ],
+    refresh: {
+      encoding: "form",
+    },
+  },
+  features: {
+    usage: true,
+  },
+};
diff --git a/open-sse/providers/registry/gemini.js b/open-sse/providers/registry/gemini.js
new file mode 100644
index 0000000..5c81104
--- /dev/null
+++ b/open-sse/providers/registry/gemini.js
@@ -0,0 +1,81 @@
+import { GOOGLE_OAUTH_CLIENT } from "../shared.js";
+
+export default {
+  id: "gemini",
+  priority: 50,
+  hasFree: true,
+  alias: "gemini",
+  display: {
+    name: "Gemini",
+    icon: "diamond",
+    color: "#4285F4",
+    textIcon: "GE",
+    website: "https://ai.google.dev",
+    notice: {
+      apiKeyUrl: "https://aistudio.google.com/app/apikey",
+    },
+  },
+  category: "freeTier",
+  mediaPriority: 1,
+  transport: {
+    baseUrl: "https://generativelanguage.googleapis.com/v1beta/models",
+    format: "gemini",
+    clientId: "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com",
+    clientSecret: "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",
+    auth: {
+      apiKey: {
+        header: "x-goog-api-key",
+        scheme: "raw",
+      },
+      oauth: {
+        header: "Authorization",
+        scheme: "bearer",
+      },
+    },
+  },
+  models: [
+    { id: "gemini-3.1-pro-preview", name: "Gemini 3.1 Pro Preview" },
+    { id: "gemini-3.1-flash-lite-preview", name: "Gemini 3.1 Flash Lite Preview" },
+    { id: "gemini-3-flash-preview", name: "Gemini 3 Flash Preview" },
+    { id: "gemini-2.5-pro", name: "Gemini 2.5 Pro" },
+    { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
+    { id: "gemini-2.5-flash-lite", name: "Gemini 2.5 Flash Lite" },
+    { id: "gemma-4-31b-it", name: "Gemma 4 31B IT" },
+    { id: "gemini-embedding-2-preview", name: "Gemini Embedding 2 Preview", kind: "embedding" },
+    { id: "gemini-embedding-001", name: "Gemini Embedding 001", kind: "embedding" },
+    { id: "text-embedding-005", name: "Text Embedding 005", kind: "embedding" },
+    { id: "text-embedding-004", name: "Text Embedding 004 (Legacy)", kind: "embedding" },
+    { id: "gemini-3.1-flash-image-preview", name: "Gemini 3.1 Flash Image (Nano Banana 2)", params: [], kind: "image" },
+    { id: "gemini-3-pro-image-preview", name: "Gemini 3 Pro Image (Nano Banana Pro)", params: [], kind: "image" },
+    { id: "gemini-2.5-flash-image", name: "Gemini 2.5 Flash Image (Nano Banana)", params: [], kind: "image" },
+    { id: "gemini-2.5-pro", name: "Gemini 2.5 Pro (Best)", params: ["language","prompt"], kind: "stt" },
+    { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash", params: ["language","prompt"], kind: "stt" },
+    { id: "gemini-2.5-flash-lite", name: "Gemini 2.5 Flash Lite (Cheapest)", params: ["language","prompt"], kind: "stt" },
+    { id: "gemini-2.0-flash", name: "Gemini 2.0 Flash", params: ["language","prompt"], kind: "stt" },
+    { id: "gemini-3.1-flash-tts-preview", name: "Gemini 3.1 Flash TTS", kind: "tts" },
+    { id: "gemini-2.5-flash-preview-tts", name: "Gemini 2.5 Flash TTS", kind: "tts" },
+    { id: "gemini-2.5-pro-preview-tts", name: "Gemini 2.5 Pro TTS", kind: "tts" },
+    { id: "embedding-001", name: "Embedding 001", dimensions: 768, kind: "embedding" },
+  ],
+  serviceKinds: ["llm","embedding","image","imageToText","webSearch","tts","stt"],
+  ttsConfig: {
+    baseUrl: "https://generativelanguage.googleapis.com/v1beta/models",
+    authType: "apikey",
+    authHeader: "key",
+    format: "gemini-tts",
+  },
+  sttConfig: {
+    baseUrl: "https://generativelanguage.googleapis.com/v1beta/models",
+    authType: "apikey",
+    authHeader: "key",
+    format: "gemini-stt",
+  },
+  embeddingConfig: { baseUrl: "https://generativelanguage.googleapis.com/v1beta/models", authType: "apikey", authHeader: "key" },
+  imageConfig: { baseUrl: "https://generativelanguage.googleapis.com/v1beta/models" },
+  searchViaChat: {
+    defaultModel: "gemini-2.5-flash",
+    endpoint: "https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent",
+    pricingUrl: "https://ai.google.dev/pricing",
+    freeTier: "Free tier: 15 RPM, 1M tokens/day on gemini-2.5-flash via AI Studio.",
+  },
+};
diff --git a/open-sse/providers/registry/github.js b/open-sse/providers/registry/github.js
new file mode 100644
index 0000000..95169eb
--- /dev/null
+++ b/open-sse/providers/registry/github.js
@@ -0,0 +1,82 @@
+export default {
+  id: "github",
+  priority: 40,
+  alias: "gh",
+  uiAlias: "gh",
+  display: {
+    name: "GitHub Copilot",
+    icon: "code",
+    color: "#333333",
+    website: "https://github.com/features/copilot",
+    notice: {
+      signupUrl: "https://github.com/features/copilot",
+    },
+    deprecated: true,
+    deprecationNotice: "RISK_NOTICE",
+  },
+  category: "oauth",
+  transport: {
+    baseUrl: "https://api.githubcopilot.com/chat/completions",
+    responsesUrl: "https://api.githubcopilot.com/responses",
+    headers: {
+      "copilot-integration-id": "vscode-chat",
+      "editor-version": "vscode/1.110.0",
+      "editor-plugin-version": "copilot-chat/0.38.0",
+      "user-agent": "GitHubCopilotChat/0.38.0",
+      "openai-intent": "conversation-panel",
+      "x-github-api-version": "2025-04-01",
+      "x-vscode-user-agent-library-version": "electron-fetch",
+      "X-Initiator": "user",
+      Accept: "application/json",
+      "Content-Type": "application/json",
+    },
+    copilot: {
+      vscodeVersion: "1.110.0",
+      chatVersion: "0.38.0",
+      userAgent: "GitHubCopilotChat/0.38.0",
+      apiVersion: "2025-04-01",
+    },
+    usage: {
+      url: "https://api.github.com/copilot_internal/user",
+    },
+  },
+  models: [
+    { id: "gpt-5.2", name: "GPT-5.2" },
+    { id: "gpt-5.2-codex", name: "GPT-5.2 Codex" },
+    { id: "gpt-5.3-codex", name: "GPT-5.3 Codex" },
+    { id: "gpt-5.4", name: "GPT-5.4" },
+    { id: "gpt-5.4-mini", name: "GPT-5.4 Mini" },
+    { id: "claude-haiku-4.5", name: "Claude Haiku 4.5" },
+    { id: "claude-opus-4.5", name: "Claude Opus 4.5" },
+    { id: "claude-sonnet-4.5", name: "Claude Sonnet 4.5" },
+    { id: "claude-sonnet-4.6", name: "Claude Sonnet 4.6" },
+    { id: "claude-opus-4.6", name: "Claude Opus 4.6" },
+    { id: "claude-opus-4.7", name: "Claude Opus 4.7" },
+    { id: "gemini-2.5-pro", name: "Gemini 2.5 Pro" },
+    { id: "gemini-3-flash-preview", name: "Gemini 3 Flash" },
+    { id: "gemini-3.1-pro-preview", name: "Gemini 3.1 Pro" },
+    { id: "grok-code-fast-1", name: "Grok Code Fast 1" },
+    { id: "oswe-vscode-prime", name: "Raptor Mini" },
+    { id: "goldeneye-free-auto", name: "GoldenEye" },
+    { id: "text-embedding-3-small", name: "Text Embedding 3 Small (GitHub)", kind: "embedding" },
+    { id: "text-embedding-3-large", name: "Text Embedding 3 Large (GitHub)", kind: "embedding" },
+  ],
+  serviceKinds: ["llm","embedding"],
+  embeddingConfig: { baseUrl: "https://models.github.ai/inference/embeddings", authType: "apikey", authHeader: "bearer" },
+  oauth: {
+    clientId: "Iv1.b507a08c87ecfe98",
+    authorizeUrl: "https://github.com/login/oauth/authorize",
+    deviceCodeUrl: "https://github.com/login/device/code",
+    tokenUrl: "https://github.com/login/oauth/access_token",
+    userInfoUrl: "https://api.github.com/user",
+    scopes: "read:user",
+    apiVersion: "2022-11-28",
+    copilotTokenUrl: "https://api.github.com/copilot_internal/v2/token",
+    userAgent: "GitHubCopilotChat/0.26.7",
+    editorVersion: "vscode/1.85.0",
+    editorPluginVersion: "copilot-chat/0.26.7",
+  },
+  features: {
+    usage: true,
+  },
+};
diff --git a/open-sse/providers/registry/gitlab.js b/open-sse/providers/registry/gitlab.js
new file mode 100644
index 0000000..319379f
--- /dev/null
+++ b/open-sse/providers/registry/gitlab.js
@@ -0,0 +1,32 @@
+export default {
+  id: "gitlab",
+  hidden: true,
+  priority: 100,
+  display: {
+    name: "GitLab Duo",
+    icon: "code",
+    color: "#FC6D26",
+    textIcon: "GL",
+    website: "https://gitlab.com",
+    notice: {
+      signupUrl: "https://gitlab.com",
+    },
+  },
+  category: "oauth",
+  transport: {
+    baseUrl: "https://gitlab.com/api/v4/chat/completions",
+    auth: {
+      combined: true,
+      header: "Authorization",
+      scheme: "bearer",
+    },
+  },
+  oauth: {
+    defaultBaseUrl: "https://gitlab.com",
+    authorizeUrlPath: "/oauth/authorize",
+    tokenUrlPath: "/oauth/token",
+    userInfoUrlPath: "/api/v4/user",
+    scope: "api read_user",
+    codeChallengeMethod: "S256",
+  },
+};
diff --git a/open-sse/providers/registry/glm-cn.js b/open-sse/providers/registry/glm-cn.js
new file mode 100644
index 0000000..90a71b4
--- /dev/null
+++ b/open-sse/providers/registry/glm-cn.js
@@ -0,0 +1,35 @@
+export default {
+  id: "glm-cn",
+  priority: 130,
+  alias: "glm-cn",
+  display: {
+    name: "GLM (China)",
+    icon: "code",
+    color: "#DC2626",
+    textIcon: "GC",
+    website: "https://open.bigmodel.cn",
+    notice: {
+      apiKeyUrl: "https://open.bigmodel.cn/usercenter/apikeys",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4/chat/completions",
+    headers: {},
+    usage: {
+      url: "https://open.bigmodel.cn/api/monitor/usage/quota/limit",
+    },
+  },
+  models: [
+    { id: "glm-5.2", name: "GLM 5.2" },
+    { id: "glm-5.1", name: "GLM 5.1" },
+    { id: "glm-5", name: "GLM 5" },
+    { id: "glm-4.7", name: "GLM-4.7" },
+    { id: "glm-4.6", name: "GLM-4.6" },
+    { id: "glm-4.5-air", name: "GLM-4.5-Air" },
+  ],
+  features: {
+    usage: true,
+    usageApikey: true,
+  },
+};
diff --git a/open-sse/providers/registry/glm.js b/open-sse/providers/registry/glm.js
new file mode 100644
index 0000000..95e1153
--- /dev/null
+++ b/open-sse/providers/registry/glm.js
@@ -0,0 +1,58 @@
+import { CLAUDE_API_HEADERS } from "../shared.js";
+
+export default {
+  id: "glm",
+  priority: 140,
+  alias: "glm",
+  display: {
+    name: "GLM Coding",
+    icon: "code",
+    color: "#2563EB",
+    textIcon: "GL",
+    website: "https://open.bigmodel.cn",
+    notice: {
+      apiKeyUrl: "https://open.bigmodel.cn/usercenter/apikeys",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.z.ai/api/anthropic/v1/messages",
+    format: "claude",
+    urlSuffix: "?beta=true",
+    headers: { ...CLAUDE_API_HEADERS },
+    auth: {
+      combined: true,
+      header: "x-api-key",
+      scheme: "raw",
+    },
+    usage: {
+      url: "https://api.z.ai/api/monitor/usage/quota/limit",
+    },
+  },
+  // Multi-endpoint: pick the transport matching client sourceFormat to skip translation.
+  transports: [
+    {
+      format: "openai",
+      baseUrl: "https://api.z.ai/api/coding/paas/v4/chat/completions",
+      auth: { combined: true, header: "Authorization", scheme: "bearer" },
+    },
+    {
+      format: "claude",
+      baseUrl: "https://api.z.ai/api/anthropic/v1/messages",
+      urlSuffix: "?beta=true",
+      headers: { ...CLAUDE_API_HEADERS },
+      auth: { combined: true, header: "x-api-key", scheme: "raw" },
+    },
+  ],
+  models: [
+    { id: "glm-5.2", name: "GLM 5.2" },
+    { id: "glm-5.1", name: "GLM 5.1" },
+    { id: "glm-5", name: "GLM 5" },
+    { id: "glm-4.7", name: "GLM 4.7" },
+    { id: "glm-4.6v", name: "GLM 4.6V (Vision)" },
+  ],
+  features: {
+    usage: true,
+    usageApikey: true,
+  },
+};
diff --git a/open-sse/providers/registry/google-pse.js b/open-sse/providers/registry/google-pse.js
new file mode 100644
index 0000000..f2a1c0b
--- /dev/null
+++ b/open-sse/providers/registry/google-pse.js
@@ -0,0 +1,35 @@
+export default {
+  id: "google-pse",
+  alias: "gpse",
+  display: {
+    name: "Google PSE",
+    icon: "search",
+    color: "#4285F4",
+    textIcon: "GP",
+    website: "https://programmablesearchengine.google.com",
+    notice: {
+      apiKeyUrl: "https://programmablesearchengine.google.com/controlpanel/create"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "webSearch"
+  ],
+  searchConfig: {
+    baseUrl: "https://www.googleapis.com/customsearch/v1",
+    method: "GET",
+    authType: "apikey",
+    authHeader: "key",
+    costPerQuery: 0.005,
+    freeMonthlyQuota: 3000,
+    searchTypes: [
+      "web",
+      "news"
+    ],
+    defaultMaxResults: 5,
+    maxMaxResults: 10,
+    timeoutMs: 10000,
+    cacheTTLMs: 300000
+  }
+};
diff --git a/open-sse/providers/registry/google-tts.js b/open-sse/providers/registry/google-tts.js
new file mode 100644
index 0000000..0b4d748
--- /dev/null
+++ b/open-sse/providers/registry/google-tts.js
@@ -0,0 +1,24 @@
+export default {
+  id: "google-tts",
+  alias: "google-tts",
+  display: {
+    name: "Google TTS",
+    icon: "record_voice_over",
+    color: "#4285F4",
+    textIcon: "GT"
+  },
+  category: "freeTier",
+  authType: "none",
+  serviceKinds: [
+    "tts"
+  ],
+  mediaPriority: 5,
+  noAuth: true,
+  ttsConfig: {
+    baseUrl: "google-tts",
+    authType: "none",
+    authHeader: "none",
+    format: "google-tts",
+    models: []
+  }
+};
diff --git a/open-sse/providers/registry/grok-cli.js b/open-sse/providers/registry/grok-cli.js
new file mode 100644
index 0000000..bc769e1
--- /dev/null
+++ b/open-sse/providers/registry/grok-cli.js
@@ -0,0 +1,86 @@
+/**
+ * Grok CLI / Grok Build (cli-chat-proxy.grok.com)
+ *
+ * Source of truth: HAR capture of official grok-shell/grok-pager 0.2.93
+ * talking to https://cli-chat-proxy.grok.com (OpenAI Responses API).
+ *
+ * Distinct from:
+ *  - `xai`      → api.x.ai (API key / Grok Build OAuth PKCE)
+ *  - `grok-web` → grok.com web SSO cookie
+ */
+export default {
+  id: "grok-cli",
+  priority: 275,
+  alias: "gcli",
+  aliases: ["grok-build", "gb"],
+  uiAlias: "gcli",
+  display: {
+    name: "Grok CLI (Grok Build)",
+    icon: "auto_awesome",
+    color: "#1DA1F2",
+    textIcon: "GC",
+    website: "https://x.ai",
+    notice: {
+      text: "Sign in with your xAI / Grok account via device code. Uses Grok Build subscription credits (cli-chat-proxy.grok.com).",
+      signupUrl: "https://grok.com/supergrok",
+    },
+  },
+  category: "oauth",
+  authModes: ["oauth"],
+  hasOAuth: true,
+  thinkingConfig: {
+    options: ["low", "medium", "high"],
+    defaultMode: "high",
+  },
+  transport: {
+    baseUrl: "https://cli-chat-proxy.grok.com/v1/responses",
+    format: "openai-responses",
+    forceStream: true,
+    modelsUrl: "https://cli-chat-proxy.grok.com/v1/models",
+    userUrl: "https://cli-chat-proxy.grok.com/v1/user",
+    billingUrl: "https://cli-chat-proxy.grok.com/v1/billing",
+    clientVersion: "0.2.93",
+    clientIdentifier: "grok-pager",
+    tokenAuth: "xai-grok-cli",
+    headers: {
+      "User-Agent": "grok-pager/0.2.93 grok-shell/0.2.93 (linux; x86_64)",
+      "x-xai-token-auth": "xai-grok-cli",
+      "x-grok-client-identifier": "grok-pager",
+      "x-grok-client-version": "0.2.93",
+      "x-authenticateresponse": "authenticate-response",
+    },
+    // Compaction threshold mirrored from CLI (x-compaction-at)
+    compactionAt: 400000,
+    // Quota tracker: official CLI polls billing?format=credits + user?include=subscription
+    usage: {
+      url: "https://cli-chat-proxy.grok.com/v1/billing?format=credits",
+      userUrl: "https://cli-chat-proxy.grok.com/v1/user?include=subscription",
+    },
+    retry: {
+      429: { attempts: 2, delayMs: 2000 },
+      502: { attempts: 2, delayMs: 1500 },
+      503: { attempts: 2, delayMs: 1500 },
+    },
+  },
+  models: [
+    { id: "grok-4.5", name: "Grok 4.5" },
+    { id: "grok-4.5-high", name: "Grok 4.5 (High)", upstreamModelId: "grok-4.5" },
+    { id: "grok-4.5-medium", name: "Grok 4.5 (Medium)", upstreamModelId: "grok-4.5" },
+    { id: "grok-4.5-low", name: "Grok 4.5 (Low)", upstreamModelId: "grok-4.5" },
+  ],
+  features: {
+    usage: true,
+  },
+  oauth: {
+    // Same public client_id as Grok CLI / existing xai OAuth
+    clientId: "b1a00492-073a-47ea-816f-4c329264a828",
+    deviceCodeUrl: "https://auth.x.ai/oauth2/device/code",
+    tokenUrl: "https://auth.x.ai/oauth2/token",
+    refreshUrl: "https://auth.x.ai/oauth2/token",
+    // HAR scope includes conversations read/write beyond the api-only xai scope
+    scope:
+      "openid profile email offline_access grok-cli:access api:access conversations:read conversations:write",
+    referrer: "grok-build",
+    refreshLeadMs: 5 * 60 * 1000,
+  },
+};
diff --git a/open-sse/providers/registry/grok-web.js b/open-sse/providers/registry/grok-web.js
new file mode 100644
index 0000000..0fbaa45
--- /dev/null
+++ b/open-sse/providers/registry/grok-web.js
@@ -0,0 +1,39 @@
+export default {
+  id: "grok-web",
+  priority: 150,
+  alias: "grok-web",
+  aliases: [
+    "gw",
+  ],
+  uiAlias: "gw",
+  display: {
+    name: "Grok Web (Subscription)",
+    icon: "auto_awesome",
+    color: "#1DA1F2",
+    textIcon: "GW",
+    website: "https://grok.com",
+  },
+  category: "webCookie",
+  authType: "cookie",
+  authHint: "Paste your sso= cookie value from grok.com",
+  transport: {
+    baseUrl: "https://grok.com/rest/app-chat/conversations/new",
+    format: "grok-web",
+    authType: "cookie",
+  },
+  models: [
+    { id: "grok-3", name: "Grok 3" },
+    { id: "grok-3-mini", name: "Grok 3 Mini (Thinking)" },
+    { id: "grok-3-thinking", name: "Grok 3 Thinking" },
+    { id: "grok-4", name: "Grok 4" },
+    { id: "grok-4-mini", name: "Grok 4 Mini (Thinking)" },
+    { id: "grok-4-thinking", name: "Grok 4 Thinking" },
+    { id: "grok-4-heavy", name: "Grok 4 Heavy (SuperGrok)" },
+    { id: "grok-4.1-mini", name: "Grok 4.1 Mini (Thinking)" },
+    { id: "grok-4.1-fast", name: "Grok 4.1 Fast" },
+    { id: "grok-4.1-expert", name: "Grok 4.1 Expert" },
+    { id: "grok-4.1-thinking", name: "Grok 4.1 Thinking" },
+    { id: "grok-4.2", name: "Grok 4.2 (4.20 Beta)" },
+  ],
+  passthroughModels: true,
+};
diff --git a/open-sse/providers/registry/groq.js b/open-sse/providers/registry/groq.js
new file mode 100644
index 0000000..2ad8a6d
--- /dev/null
+++ b/open-sse/providers/registry/groq.js
@@ -0,0 +1,37 @@
+export default {
+  id: "groq",
+  priority: 60,
+  hasFree: true,
+  alias: "groq",
+  display: {
+    name: "Groq",
+    icon: "speed",
+    color: "#F55036",
+    textIcon: "GQ",
+    website: "https://groq.com",
+    notice: {
+      apiKeyUrl: "https://console.groq.com/keys",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.groq.com/openai/v1/chat/completions",
+    validateUrl: "https://api.groq.com/openai/v1/models",
+  },
+  models: [
+    { id: "llama-3.3-70b-versatile", name: "Llama 3.3 70B" },
+    { id: "meta-llama/llama-4-maverick-17b-128e-instruct", name: "Llama 4 Maverick" },
+    { id: "qwen/qwen3-32b", name: "Qwen3 32B" },
+    { id: "openai/gpt-oss-120b", name: "GPT-OSS 120B" },
+    { id: "whisper-large-v3", name: "Whisper Large v3", params: ["language","response_format","temperature","prompt"], kind: "stt" },
+    { id: "whisper-large-v3-turbo", name: "Whisper Large v3 Turbo", params: ["language","response_format","temperature","prompt"], kind: "stt" },
+    { id: "distil-whisper-large-v3-en", name: "Distil Whisper Large v3 EN", params: ["language","response_format","temperature","prompt"], kind: "stt" },
+  ],
+  serviceKinds: ["llm","imageToText","stt"],
+  sttConfig: {
+    baseUrl: "https://api.groq.com/openai/v1/audio/transcriptions",
+    authType: "apikey",
+    authHeader: "bearer",
+    format: "openai",
+  },
+};
diff --git a/open-sse/providers/registry/huggingface.js b/open-sse/providers/registry/huggingface.js
new file mode 100644
index 0000000..768b0de
--- /dev/null
+++ b/open-sse/providers/registry/huggingface.js
@@ -0,0 +1,34 @@
+export default {
+  id: "huggingface",
+  priority: 70,
+  hasFree: true,
+  alias: "huggingface",
+  aliases: [
+    "hf",
+  ],
+  uiAlias: "hf",
+  display: {
+    name: "HuggingFace",
+    icon: "face",
+    color: "#FFD21E",
+    textIcon: "HF",
+    website: "https://huggingface.co",
+    notice: {
+      apiKeyUrl: "https://huggingface.co/settings/tokens",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  hiddenKinds: [
+    "tts",
+  ],
+  transport: null,
+  models: [
+    { id: "black-forest-labs/FLUX.1-schnell", name: "FLUX.1 Schnell", params: [], kind: "image" },
+    { id: "stabilityai/stable-diffusion-xl-base-1.0", name: "SDXL Base 1.0", params: [], kind: "image" },
+    { id: "openai/whisper-large-v3", name: "Whisper Large v3 (HF)", params: ["language"], kind: "stt" },
+    { id: "openai/whisper-small", name: "Whisper Small (HF)", params: ["language"], kind: "stt" },
+  ],
+  serviceKinds: ["image", "stt"],
+  imageConfig: { baseUrl: "https://api-inference.huggingface.co/models" },
+};
diff --git a/open-sse/providers/registry/hyperbolic.js b/open-sse/providers/registry/hyperbolic.js
new file mode 100644
index 0000000..9796cc9
--- /dev/null
+++ b/open-sse/providers/registry/hyperbolic.js
@@ -0,0 +1,35 @@
+export default {
+  id: "hyperbolic",
+  priority: 160,
+  alias: "hyperbolic",
+  aliases: [
+    "hyp",
+  ],
+  uiAlias: "hyp",
+  display: {
+    name: "Hyperbolic",
+    icon: "bolt",
+    color: "#00D4FF",
+    textIcon: "HY",
+    website: "https://hyperbolic.xyz",
+    notice: {
+      apiKeyUrl: "https://app.hyperbolic.xyz/settings",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: {
+    baseUrl: "https://api.hyperbolic.xyz/v1/chat/completions",
+    validateUrl: "https://api.hyperbolic.xyz/v1/models",
+  },
+  models: [
+    { id: "Qwen/QwQ-32B", name: "QwQ 32B" },
+    { id: "deepseek-ai/DeepSeek-R1", name: "DeepSeek R1" },
+    { id: "deepseek-ai/DeepSeek-V3", name: "DeepSeek V3" },
+    { id: "meta-llama/Llama-3.3-70B-Instruct", name: "Llama 3.3 70B" },
+    { id: "meta-llama/Llama-3.2-3B-Instruct", name: "Llama 3.2 3B" },
+    { id: "Qwen/Qwen2.5-72B-Instruct", name: "Qwen 2.5 72B" },
+    { id: "Qwen/Qwen2.5-Coder-32B-Instruct", name: "Qwen 2.5 Coder 32B" },
+    { id: "NousResearch/Hermes-3-Llama-3.1-70B", name: "Hermes 3 70B" },
+  ],
+};
diff --git a/open-sse/providers/registry/iflow.js b/open-sse/providers/registry/iflow.js
new file mode 100644
index 0000000..00f550e
--- /dev/null
+++ b/open-sse/providers/registry/iflow.js
@@ -0,0 +1,52 @@
+export default {
+  id: "iflow",
+  hidden: true,
+  priority: 110,
+  alias: "if",
+  display: {
+    name: "iFlow AI",
+    icon: "water_drop",
+    color: "#6366F1",
+    website: "https://iflow.cn",
+    notice: {
+      signupUrl: "https://iflow.cn",
+    },
+  },
+  category: "oauth",
+  transport: {
+    baseUrl: "https://apis.iflow.cn/v1/chat/completions",
+    thinkingFormat: "openai",
+    headers: {
+      "User-Agent": "iFlow-Cli",
+    },
+  },
+  models: [
+    { id: "qwen3-coder-plus", name: "Qwen3 Coder Plus" },
+    { id: "qwen3-max", name: "Qwen3 Max" },
+    { id: "qwen3-vl-plus", name: "Qwen3 VL Plus" },
+    { id: "qwen3-max-preview", name: "Qwen3 Max Preview" },
+    { id: "qwen3-235b", name: "Qwen3 235B A22B" },
+    { id: "qwen3-235b-a22b-instruct", name: "Qwen3 235B A22B Instruct" },
+    { id: "qwen3-235b-a22b-thinking-2507", name: "Qwen3 235B A22B Thinking" },
+    { id: "qwen3-32b", name: "Qwen3 32B" },
+    { id: "kimi-k2", name: "Kimi K2" },
+    { id: "deepseek-v3.2", name: "DeepSeek V3.2 Exp" },
+    { id: "deepseek-v3.1", name: "DeepSeek V3.1 Terminus" },
+    { id: "deepseek-v3", name: "DeepSeek V3 671B" },
+    { id: "deepseek-r1", name: "DeepSeek R1" },
+    { id: "glm-4.7", name: "GLM 4.7" },
+    { id: "iflow-rome-30ba3b", name: "iFlow ROME" },
+  ],
+  oauth: {
+    clientId: "10009311001",
+    clientSecret: "4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW",
+    authorizeUrl: "https://iflow.cn/oauth",
+    tokenUrl: "https://iflow.cn/oauth/token",
+    userInfoUrl: "https://iflow.cn/api/oauth/getUserInfo",
+    extraParams: {
+      loginMethod: "phone",
+      type: "phone",
+    },
+    refreshLeadMs: 86400000,
+  },
+};
diff --git a/open-sse/providers/registry/index.js b/open-sse/providers/registry/index.js
new file mode 100644
index 0000000..e4cf543
--- /dev/null
+++ b/open-sse/providers/registry/index.js
@@ -0,0 +1,204 @@
+// Auto-generated: static imports for all registry entries
+import p0 from "./alicode-intl.js";
+import p1 from "./alicode.js";
+import p2 from "./anthropic.js";
+import p3 from "./antigravity.js";
+import p4 from "./assemblyai.js";
+import p5 from "./aws-polly.js";
+import p6 from "./azure.js";
+import p7 from "./black-forest-labs.js";
+import p8 from "./blackbox.js";
+import p9 from "./brave-search.js";
+import p10 from "./byteplus.js";
+import p11 from "./cartesia.js";
+import p12 from "./cerebras.js";
+import p13 from "./chutes.js";
+import p14 from "./claude.js";
+import p15 from "./cline.js";
+import p16 from "./clinepass.js";
+import p17 from "./cloudflare-ai.js";
+import p18 from "./codebuddy-cn.js";
+import p19 from "./codex.js";
+import p20 from "./cohere.js";
+import p21 from "./comfyui.js";
+import p22 from "./commandcode.js";
+import p23 from "./coqui.js";
+import p24 from "./cursor.js";
+import p25 from "./deepgram.js";
+import p26 from "./deepseek.js";
+import p27 from "./edge-tts.js";
+import p28 from "./elevenlabs.js";
+import p29 from "./exa.js";
+import p30 from "./fal-ai.js";
+import p31 from "./featherless.js";
+import p32 from "./firecrawl.js";
+import p33 from "./fireworks.js";
+import p34 from "./gemini-cli.js";
+import p35 from "./gemini.js";
+import p36 from "./github.js";
+import p37 from "./gitlab.js";
+import p38 from "./glm-cn.js";
+import p39 from "./glm.js";
+import p40 from "./google-pse.js";
+import p41 from "./google-tts.js";
+import p42 from "./grok-cli.js";
+import p43 from "./grok-web.js";
+import p44 from "./groq.js";
+import p45 from "./huggingface.js";
+import p46 from "./hyperbolic.js";
+import p47 from "./iflow.js";
+import p48 from "./inworld.js";
+import p49 from "./jina-ai.js";
+import p50 from "./jina-reader.js";
+import p51 from "./kilocode.js";
+import p52 from "./kimchi.js";
+import p53 from "./kimi-coding.js";
+import p54 from "./kimi.js";
+import p55 from "./kiro.js";
+import p56 from "./linkup.js";
+import p57 from "./local-device.js";
+import p58 from "./mimo-free.js";
+import p59 from "./minimax-cn.js";
+import p60 from "./minimax.js";
+import p61 from "./mistral.js";
+import p62 from "./mmf.js";
+import p63 from "./nanobanana.js";
+import p64 from "./nebius.js";
+import p65 from "./nvidia.js";
+import p66 from "./ollama-local.js";
+import p67 from "./ollama.js";
+import p68 from "./openai.js";
+import p69 from "./opencode-go.js";
+import p70 from "./opencode.js";
+import p71 from "./openrouter.js";
+import p72 from "./perplexity-web.js";
+import p73 from "./perplexity.js";
+import p74 from "./perplexity-agent.js";
+import p75 from "./playht.js";
+import p76 from "./qoder.js";
+import p77 from "./qwen.js";
+import p78 from "./recraft.js";
+import p79 from "./runwayml.js";
+import p80 from "./sdwebui.js";
+import p81 from "./searchapi.js";
+import p82 from "./searxng.js";
+import p83 from "./serper.js";
+import p84 from "./siliconflow.js";
+import p85 from "./stability-ai.js";
+import p86 from "./tavily.js";
+import p87 from "./together.js";
+import p88 from "./topaz.js";
+import p89 from "./tortoise.js";
+import p90 from "./venice.js";
+import p91 from "./vercel-ai-gateway.js";
+import p92 from "./vertex-partner.js";
+import p93 from "./vertex.js";
+import p94 from "./volcengine-ark.js";
+import p95 from "./voyage-ai.js";
+import p96 from "./xai.js";
+import p97 from "./xiaomi-mimo.js";
+import p98 from "./xiaomi-tokenplan.js";
+import p99 from "./youcom.js";
+
+export default [
+  p0,
+  p1,
+  p2,
+  p3,
+  p4,
+  p5,
+  p6,
+  p7,
+  p8,
+  p9,
+  p10,
+  p11,
+  p12,
+  p13,
+  p14,
+  p15,
+  p16,
+  p17,
+  p18,
+  p19,
+  p20,
+  p21,
+  p22,
+  p23,
+  p24,
+  p25,
+  p26,
+  p27,
+  p28,
+  p29,
+  p30,
+  p31,
+  p32,
+  p33,
+  p34,
+  p35,
+  p36,
+  p37,
+  p38,
+  p39,
+  p40,
+  p41,
+  p42,
+  p43,
+  p44,
+  p45,
+  p46,
+  p47,
+  p48,
+  p49,
+  p50,
+  p51,
+  p52,
+  p53,
+  p54,
+  p55,
+  p56,
+  p57,
+  p58,
+  p59,
+  p60,
+  p61,
+  p62,
+  p63,
+  p64,
+  p65,
+  p66,
+  p67,
+  p68,
+  p69,
+  p70,
+  p71,
+  p72,
+  p73,
+  p74,
+  p75,
+  p76,
+  p77,
+  p78,
+  p79,
+  p80,
+  p81,
+  p82,
+  p83,
+  p84,
+  p85,
+  p86,
+  p87,
+  p88,
+  p89,
+  p90,
+  p91,
+  p92,
+  p93,
+  p94,
+  p95,
+  p96,
+  p97,
+  p98,
+  p99
+];
diff --git a/open-sse/providers/registry/inworld.js b/open-sse/providers/registry/inworld.js
new file mode 100644
index 0000000..bc9bad5
--- /dev/null
+++ b/open-sse/providers/registry/inworld.js
@@ -0,0 +1,36 @@
+export default {
+  id: "inworld",
+  alias: "inworld",
+  display: {
+    name: "Inworld TTS",
+    icon: "record_voice_over",
+    color: "#FF6B6B",
+    textIcon: "IW",
+    website: "https://inworld.ai",
+    notice: {
+      text: "Free tier: 40 minutes/month TTS. Paid: TTS-1.5 Mini $0.01/min ($15/1M chars), TTS-1.5 Max $0.025/min ($30/1M chars). 270+ voices, 15 languages.",
+      apiKeyUrl: "https://platform.inworld.ai/api-keys"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "tts"
+  ],
+  ttsConfig: {
+    baseUrl: "https://api.inworld.ai/tts/v1/voice",
+    authType: "apikey",
+    authHeader: "basic",
+    format: "inworld",
+    models: [
+      {
+        id: "inworld-tts-1.5-mini",
+        name: "Inworld TTS 1.5 Mini ($0.01/min)"
+      },
+      {
+        id: "inworld-tts-1.5-max",
+        name: "Inworld TTS 1.5 Max ($0.025/min)"
+      }
+    ]
+  }
+};
diff --git a/open-sse/providers/registry/jina-ai.js b/open-sse/providers/registry/jina-ai.js
new file mode 100644
index 0000000..90c7da2
--- /dev/null
+++ b/open-sse/providers/registry/jina-ai.js
@@ -0,0 +1,42 @@
+export default {
+  id: "jina-ai",
+  alias: "jina",
+  display: {
+    name: "Jina AI",
+    icon: "blur_on",
+    color: "#2563EB",
+    textIcon: "JA",
+    website: "https://jina.ai",
+    notice: {
+      text: "10M free tokens on signup (non-commercial), no credit card required.",
+      apiKeyUrl: "https://jina.ai/?sui=apikey"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "embedding"
+  ],
+  embeddingConfig: {
+    baseUrl: "https://api.jina.ai/v1/embeddings",
+    authType: "apikey",
+    authHeader: "bearer",
+    models: [
+      {
+        id: "jina-embeddings-v3",
+        name: "Jina Embeddings v3",
+        dimensions: 1024
+      },
+      {
+        id: "jina-embeddings-v2-base-en",
+        name: "Jina Embeddings v2 Base EN",
+        dimensions: 768
+      },
+      {
+        id: "jina-embeddings-v2-base-code",
+        name: "Jina Embeddings v2 Base Code",
+        dimensions: 768
+      }
+    ]
+  }
+};
diff --git a/open-sse/providers/registry/jina-reader.js b/open-sse/providers/registry/jina-reader.js
new file mode 100644
index 0000000..35ffae9
--- /dev/null
+++ b/open-sse/providers/registry/jina-reader.js
@@ -0,0 +1,34 @@
+export default {
+  id: "jina-reader",
+  alias: "jina-reader",
+  display: {
+    name: "Jina Reader",
+    icon: "menu_book",
+    color: "#000000",
+    textIcon: "JR",
+    website: "https://jina.ai/reader",
+    notice: {
+      apiKeyUrl: "https://jina.ai/?sui=apikey"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "webFetch"
+  ],
+  fetchConfig: {
+    baseUrl: "https://r.jina.ai",
+    method: "GET",
+    authType: "apikey",
+    authHeader: "bearer",
+    costPerQuery: 0,
+    freeMonthlyQuota: 1000000,
+    formats: [
+      "markdown",
+      "text",
+      "html"
+    ],
+    maxCharacters: 200000,
+    timeoutMs: 30000
+  }
+};
diff --git a/open-sse/providers/registry/kilocode.js b/open-sse/providers/registry/kilocode.js
new file mode 100644
index 0000000..abf6af0
--- /dev/null
+++ b/open-sse/providers/registry/kilocode.js
@@ -0,0 +1,51 @@
+export default {
+  id: "kilocode",
+  priority: 70,
+  alias: "kc",
+  uiAlias: "kc",
+  display: {
+    name: "Kilo Code",
+    icon: "code",
+    color: "#FF6B35",
+    textIcon: "KC",
+    website: "https://kilocode.ai",
+    notice: {
+      signupUrl: "https://kilocode.ai",
+    },
+  },
+  category: "oauth",
+  transport: {
+    baseUrl: "https://api.kilo.ai/api/openrouter/chat/completions",
+    headers: {},
+    auth: {
+      combined: true,
+      header: "Authorization",
+      scheme: "bearer",
+      hooks: [
+        "kilocodeOrg",
+      ],
+    },
+  },
+  models: [
+    { id: "anthropic/claude-sonnet-4-20250514", name: "Claude Sonnet 4" },
+    { id: "anthropic/claude-opus-4-20250514", name: "Claude Opus 4" },
+    { id: "google/gemini-2.5-pro", name: "Gemini 2.5 Pro" },
+    { id: "google/gemini-2.5-flash", name: "Gemini 2.5 Flash" },
+    { id: "openai/gpt-4.1", name: "GPT-4.1" },
+    { id: "openai/o3", name: "o3" },
+    { id: "deepseek/deepseek-chat", name: "DeepSeek Chat" },
+    { id: "deepseek/deepseek-reasoner", name: "DeepSeek Reasoner" },
+  ],
+  // Kilo Code proxies the OpenRouter catalog (334 models at time of writing),
+  // so the hardcoded list above is only a fallback. Surfacing the full catalog
+  // requires a fetcher + passthroughModels, matching how openrouter.js is set up.
+  // Without these, only the 8 hardcoded models appear in the combo model picker,
+  // hiding dynamic models like cohere/north-mini-code:free and poolside/laguna-m.1:free.
+  modelsFetcher: { url: "https://api.kilo.ai/api/gateway/models", type: "openrouter-free" },
+  passthroughModels: true,
+  oauth: {
+    apiBaseUrl: "https://api.kilo.ai",
+    initiateUrl: "https://api.kilo.ai/api/device-auth/codes",
+    pollUrlBase: "https://api.kilo.ai/api/device-auth/codes",
+  },
+};
diff --git a/open-sse/providers/registry/kimchi.js b/open-sse/providers/registry/kimchi.js
new file mode 100644
index 0000000..99facd5
--- /dev/null
+++ b/open-sse/providers/registry/kimchi.js
@@ -0,0 +1,49 @@
+export default {
+  id: "kimchi",
+  priority: 95,
+  alias: "kimchi",
+  uiAlias: "kimchi",
+  display: {
+    name: "Kimchi",
+    icon: "restaurant",
+    color: "#FF521D",
+    textIcon: "KC",
+    website: "https://kimchi.dev",
+    notice: {
+      signupUrl: "https://app.kimchi.dev",
+    },
+  },
+  category: "oauth",
+  authModes: ["oauth"],
+  hasOAuth: true,
+  transport: {
+    baseUrl: "https://llm.kimchi.dev/openai/v1/chat/completions",
+    format: "openai",
+    headers: {
+      "User-Agent": "kimchi/0.1.50",
+    },
+    auth: {
+      combined: true,
+      header: "Authorization",
+      scheme: "bearer",
+    },
+  },
+  models: [
+    { id: "minimax-m3", name: "MiniMax-M3" },
+    { id: "kimi-k2.7", name: "Kimi-K2.7" },
+    { id: "kimi-k2.6", name: "Kimi-K2.6" },
+    { id: "kimi-k2.5", name: "Kimi-K2.5" },
+    { id: "nemotron-3-ultra-fp4", name: "Nemotron 3 Ultra FP4" },
+    { id: "minimax-m2.7", name: "MiniMax-M2.7" },
+    { id: "claude-opus-4-6", name: "Claude Opus 4.6" },
+    { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
+  ],
+  serviceKinds: ["llm", "imageToText"],
+  oauth: {
+    webAppUrl: "https://app.kimchi.dev",
+    validationUrl: "https://api.cast.ai/v1/llm/openai/supported-providers",
+    userInfoUrl: "https://app.kimchi.dev/api/v1/me",
+    modelsUrl: "https://llm.kimchi.dev/v1/models/metadata?include_in_cli=true",
+  },
+  passthroughModels: true,
+};
diff --git a/open-sse/providers/registry/kimi-coding.js b/open-sse/providers/registry/kimi-coding.js
new file mode 100644
index 0000000..15705a8
--- /dev/null
+++ b/open-sse/providers/registry/kimi-coding.js
@@ -0,0 +1,65 @@
+import { CLAUDE_API_HEADERS, KIMI_CODING_BASE_URL } from "../shared.js";
+
+export default {
+  id: "kimi-coding",
+  hidden: true,
+  priority: 120,
+  alias: "kmc",
+  display: {
+    name: "Kimi Coding",
+    icon: "psychology",
+    color: "#1E40AF",
+    textIcon: "KC",
+    website: "https://kimi.moonshot.cn",
+    notice: {
+      signupUrl: "https://kimi.moonshot.cn",
+    },
+  },
+  category: "oauth",
+  transport: {
+    baseUrl: "https://api.kimi.com/coding/v1/messages",
+    format: "claude",
+    urlSuffix: "?beta=true",
+    headers: { ...CLAUDE_API_HEADERS },
+    clientId: "17e5f671-d194-4dfb-9706-5516cb48c098",
+    tokenUrl: "https://auth.kimi.com/api/oauth/token",
+    refreshUrl: "https://auth.kimi.com/api/oauth/token",
+    auth: {
+      combined: true,
+      header: "x-api-key",
+      scheme: "raw",
+      hooks: [
+        "kimiHeaders",
+      ],
+    },
+  },
+  // Multi-endpoint: pick the transport matching client sourceFormat to skip translation.
+  transports: [
+    {
+      format: "openai",
+      baseUrl: "https://api.kimi.com/coding/v1/chat/completions",
+      auth: { combined: true, header: "Authorization", scheme: "bearer", hooks: ["kimiHeaders"] },
+    },
+    {
+      format: "claude",
+      baseUrl: "https://api.kimi.com/coding/v1/messages",
+      urlSuffix: "?beta=true",
+      headers: { ...CLAUDE_API_HEADERS },
+      auth: { combined: true, header: "x-api-key", scheme: "raw", hooks: ["kimiHeaders"] },
+    },
+  ],
+  models: [
+    { id: "kimi-k2.6", name: "Kimi K2.6" },
+    { id: "kimi-k2.5", name: "Kimi K2.5" },
+    { id: "kimi-k2.5-thinking", name: "Kimi K2.5 Thinking" },
+    { id: "kimi-latest", name: "Kimi Latest" },
+  ],
+  oauth: {
+    deviceCodeUrl: "https://auth.kimi.com/api/oauth/device_authorization",
+    tokenUrl: "https://auth.kimi.com/api/oauth/token",
+    refreshLeadMs: 300000,
+  },
+  features: {
+    usage: true,
+  },
+};
diff --git a/open-sse/providers/registry/kimi.js b/open-sse/providers/registry/kimi.js
new file mode 100644
index 0000000..e22286b
--- /dev/null
+++ b/open-sse/providers/registry/kimi.js
@@ -0,0 +1,56 @@
+import { CLAUDE_API_HEADERS, KIMI_CODING_BASE_URL } from "../shared.js";
+
+export default {
+  id: "kimi",
+  priority: 170,
+  alias: "kimi",
+  display: {
+    name: "Kimi",
+    icon: "psychology",
+    color: "#1E3A8A",
+    textIcon: "KM",
+    website: "https://kimi.moonshot.cn",
+    notice: {
+      apiKeyUrl: "https://platform.moonshot.ai/console/api-keys",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.kimi.com/coding/v1/messages",
+    format: "claude",
+    urlSuffix: "?beta=true",
+    headers: { ...CLAUDE_API_HEADERS },
+    auth: {
+      combined: true,
+      header: "x-api-key",
+      scheme: "raw",
+    },
+  },
+  // Multi-endpoint: pick the transport matching client sourceFormat to skip translation.
+  transports: [
+    {
+      format: "openai",
+      baseUrl: "https://api.kimi.com/coding/v1/chat/completions",
+      auth: { combined: true, header: "Authorization", scheme: "bearer" },
+    },
+    {
+      format: "claude",
+      baseUrl: "https://api.kimi.com/coding/v1/messages",
+      urlSuffix: "?beta=true",
+      headers: { ...CLAUDE_API_HEADERS },
+      auth: { combined: true, header: "x-api-key", scheme: "raw" },
+    },
+  ],
+  models: [
+    { id: "kimi-k2.6", name: "Kimi K2.6" },
+    { id: "kimi-k2.5", name: "Kimi K2.5" },
+    { id: "kimi-k2.5-thinking", name: "Kimi K2.5 Thinking" },
+    { id: "kimi-latest", name: "Kimi Latest" },
+  ],
+  serviceKinds: ["llm","webSearch"],
+  searchViaChat: {
+    defaultModel: "kimi-k2.5",
+    endpoint: "https://api.moonshot.cn/v1/chat/completions",
+    pricingUrl: "https://platform.moonshot.ai/docs/pricing/chat",
+  },
+};
diff --git a/open-sse/providers/registry/kiro.js b/open-sse/providers/registry/kiro.js
new file mode 100644
index 0000000..dab23a3
--- /dev/null
+++ b/open-sse/providers/registry/kiro.js
@@ -0,0 +1,115 @@
+export default {
+  id: "kiro",
+  priority: 10,
+  alias: "kr",
+  uiAlias: "kr",
+  display: {
+    name: "Kiro AI",
+    icon: "psychology_alt",
+    color: "#FF6B35",
+    website: "https://kiro.dev",
+    notice: {
+      signupUrl: "https://kiro.dev",
+    },
+    deprecated: true,
+    deprecationNotice: "RISK_NOTICE",
+  },
+  category: "free",
+  transport: {
+    baseUrl: "https://runtime.us-east-1.kiro.dev/generateAssistantResponse",
+    baseUrls: [
+      "https://runtime.us-east-1.kiro.dev/generateAssistantResponse",
+      "https://codewhisperer.us-east-1.amazonaws.com/generateAssistantResponse",
+      "https://q.us-east-1.amazonaws.com/generateAssistantResponse",
+    ],
+    format: "kiro",
+    retry: {
+      "429": 0,
+    },
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/vnd.amazon.eventstream",
+      "X-Amz-Target": "AmazonCodeWhispererStreamingService.GenerateAssistantResponse",
+      "User-Agent": "AWS-SDK-JS/3.0.0 kiro-ide/1.0.0",
+      "X-Amz-User-Agent": "aws-sdk-js/3.0.0 kiro-ide/1.0.0",
+    },
+    tokenUrl: "https://prod.us-east-1.auth.desktop.kiro.dev/refreshToken",
+    authUrl: "https://prod.us-east-1.auth.desktop.kiro.dev",
+    usage: {
+      cwHost: "https://codewhisperer.us-east-1.amazonaws.com",
+      qHost: "https://q.us-east-1.amazonaws.com",
+      limitsPath: "/getUsageLimits",
+    },
+  },
+  models: [
+    // Opus (added per kiro.dev/changelog/models and kiro.dev/docs/models)
+    { id: "claude-opus-4.8", name: "Claude Opus 4.8" },
+    { id: "claude-opus-4.8-thinking", name: "Claude Opus 4.8 (Thinking)" },
+    { id: "claude-opus-4.8-agentic", name: "Claude Opus 4.8 (Agentic)" },
+    { id: "claude-opus-4.8-thinking-agentic", name: "Claude Opus 4.8 (Thinking + Agentic)" },
+    { id: "claude-opus-4.7", name: "Claude Opus 4.7" },
+    { id: "claude-opus-4.7-thinking", name: "Claude Opus 4.7 (Thinking)" },
+    { id: "claude-opus-4.7-agentic", name: "Claude Opus 4.7 (Agentic)" },
+    { id: "claude-opus-4.7-thinking-agentic", name: "Claude Opus 4.7 (Thinking + Agentic)" },
+    { id: "claude-opus-4.5", name: "Claude Opus 4.5" },
+    { id: "claude-opus-4.5-thinking", name: "Claude Opus 4.5 (Thinking)" },
+    { id: "claude-opus-4.5-agentic", name: "Claude Opus 4.5 (Agentic)" },
+    { id: "claude-opus-4.5-thinking-agentic", name: "Claude Opus 4.5 (Thinking + Agentic)" },
+    // Sonnet
+    { id: "claude-sonnet-5", name: "Claude Sonnet 5" },
+    { id: "claude-sonnet-4.5", name: "Claude Sonnet 4.5" },
+    // Haiku
+    { id: "claude-haiku-4.5", name: "Claude Haiku 4.5" },
+    // Non-Anthropic
+    { id: "deepseek-3.2", name: "DeepSeek 3.2", strip: ["image","audio"] },
+    { id: "qwen3-coder-next", name: "Qwen3 Coder Next", strip: ["image","audio"] },
+    { id: "glm-5", name: "GLM 5" },
+    { id: "MiniMax-M2.5", name: "MiniMax M2.5" },
+    // Thinking variants
+    { id: "claude-sonnet-5-thinking", name: "Claude Sonnet 5 (Thinking)" },
+    { id: "claude-sonnet-4.5-thinking", name: "Claude Sonnet 4.5 (Thinking)" },
+    { id: "claude-haiku-4.5-thinking", name: "Claude Haiku 4.5 (Thinking)" },
+    // Agentic variants
+    { id: "claude-sonnet-5-agentic", name: "Claude Sonnet 5 (Agentic)" },
+    { id: "claude-sonnet-4.5-agentic", name: "Claude Sonnet 4.5 (Agentic)" },
+    { id: "claude-haiku-4.5-agentic", name: "Claude Haiku 4.5 (Agentic)" },
+    // Thinking + Agentic variants
+    { id: "claude-sonnet-5-thinking-agentic", name: "Claude Sonnet 5 (Thinking + Agentic)" },
+    { id: "claude-sonnet-4.5-thinking-agentic", name: "Claude Sonnet 4.5 (Thinking + Agentic)" },
+    { id: "claude-haiku-4.5-thinking-agentic", name: "Claude Haiku 4.5 (Thinking + Agentic)" },
+  ],
+  oauth: {
+    ssoOidcEndpoint: "https://oidc.us-east-1.amazonaws.com",
+    registerClientUrl: "https://oidc.us-east-1.amazonaws.com/client/register",
+    deviceAuthUrl: "https://oidc.us-east-1.amazonaws.com/device_authorization",
+    tokenUrl: "https://oidc.us-east-1.amazonaws.com/token",
+    startUrl: "https://view.awsapps.com/start",
+    clientName: "kiro-oauth-client",
+    clientType: "public",
+    scopes: [
+      "codewhisperer:completions",
+      "codewhisperer:analysis",
+      "codewhisperer:conversations",
+    ],
+    grantTypes: [
+      "urn:ietf:params:oauth:grant-type:device_code",
+      "refresh_token",
+    ],
+    issuerUrl: "https://identitycenter.amazonaws.com/ssoins-722374e8c3c8e6c6",
+    socialAuthEndpoint: "https://prod.us-east-1.auth.desktop.kiro.dev",
+    socialLoginUrl: "https://prod.us-east-1.auth.desktop.kiro.dev/login",
+    socialTokenUrl: "https://prod.us-east-1.auth.desktop.kiro.dev/oauth/token",
+    socialRefreshUrl: "https://prod.us-east-1.auth.desktop.kiro.dev/refreshToken",
+    authMethods: [
+      "builder-id",
+      "idc",
+      "google",
+      "github",
+      "import",
+    ],
+  },
+  features: {
+    usage: true,
+    usageApikey: true,
+  },
+};
diff --git a/open-sse/providers/registry/linkup.js b/open-sse/providers/registry/linkup.js
new file mode 100644
index 0000000..19be6bb
--- /dev/null
+++ b/open-sse/providers/registry/linkup.js
@@ -0,0 +1,34 @@
+export default {
+  id: "linkup",
+  alias: "linkup",
+  display: {
+    name: "Linkup",
+    icon: "link",
+    color: "#0EA5E9",
+    textIcon: "LK",
+    website: "https://linkup.so",
+    notice: {
+      apiKeyUrl: "https://app.linkup.so/api-keys"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "webSearch"
+  ],
+  searchConfig: {
+    baseUrl: "https://api.linkup.so/v1/search",
+    method: "POST",
+    authType: "apikey",
+    authHeader: "bearer",
+    costPerQuery: 0.005,
+    freeMonthlyQuota: 1000,
+    searchTypes: [
+      "web"
+    ],
+    defaultMaxResults: 5,
+    maxMaxResults: 50,
+    timeoutMs: 10000,
+    cacheTTLMs: 300000
+  }
+};
diff --git a/open-sse/providers/registry/local-device.js b/open-sse/providers/registry/local-device.js
new file mode 100644
index 0000000..b24fc2d
--- /dev/null
+++ b/open-sse/providers/registry/local-device.js
@@ -0,0 +1,24 @@
+export default {
+  id: "local-device",
+  alias: "local-device",
+  display: {
+    name: "Local Device",
+    icon: "speaker",
+    color: "#64748B",
+    textIcon: "LD"
+  },
+  category: "freeTier",
+  authType: "none",
+  serviceKinds: [
+    "tts"
+  ],
+  mediaPriority: 5,
+  noAuth: true,
+  ttsConfig: {
+    baseUrl: "local-device",
+    authType: "none",
+    authHeader: "none",
+    format: "local-device",
+    models: []
+  }
+};
diff --git a/open-sse/providers/registry/mimo-free.js b/open-sse/providers/registry/mimo-free.js
new file mode 100644
index 0000000..4b9074d
--- /dev/null
+++ b/open-sse/providers/registry/mimo-free.js
@@ -0,0 +1,24 @@
+export default {
+  id: "mimo-free",
+  priority: 50,
+  hasFree: true,
+  alias: "mmf",
+  uiAlias: "mmf",
+  display: {
+    name: "MiMo Code Free",
+    icon: "smart_toy",
+    color: "#FF6900",
+    textIcon: "MF",
+  },
+  category: "free",
+  noAuth: true,
+  transport: {
+    baseUrl: "https://api.xiaomimimo.com/api/free-ai/openai/chat",
+    noAuth: true,
+  },
+  models: [
+    { id: "mimo-auto", name: "MiMo Auto" },
+  ],
+  modelsFetcher: { url: "https://models.dev/api.json", type: "mimo-free" },
+  passthroughModels: true,
+};
diff --git a/open-sse/providers/registry/minimax-cn.js b/open-sse/providers/registry/minimax-cn.js
new file mode 100644
index 0000000..19aa312
--- /dev/null
+++ b/open-sse/providers/registry/minimax-cn.js
@@ -0,0 +1,76 @@
+import { CLAUDE_API_HEADERS } from "../shared.js";
+
+export default {
+  id: "minimax-cn",
+  priority: 190,
+  alias: "minimax-cn",
+  display: {
+    name: "Minimax (China)",
+    icon: "memory",
+    color: "#DC2626",
+    textIcon: "MC",
+    website: "https://www.minimaxi.com",
+    notice: {
+      apiKeyUrl: "https://platform.minimaxi.com/user-center/basic-information/interface-key",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.minimaxi.com/anthropic/v1/messages",
+    format: "claude",
+    urlSuffix: "?beta=true",
+    headers: { ...CLAUDE_API_HEADERS },
+    quirks: {
+      dropOutputConfig: true,
+    },
+    reasoningInject: {
+      scope: "all",
+    },
+    auth: {
+      combined: true,
+      header: "x-api-key",
+      scheme: "raw",
+    },
+    usage: {
+      urls: [
+        "https://www.minimaxi.com/v1/api/openplatform/coding_plan/remains",
+        "https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains",
+      ],
+    },
+  },
+  // Multi-endpoint: pick the transport matching client sourceFormat to skip translation.
+  transports: [
+    {
+      format: "openai",
+      baseUrl: "https://api.minimaxi.com/v1/chat/completions",
+      auth: { combined: true, header: "Authorization", scheme: "bearer" },
+    },
+    {
+      format: "claude",
+      baseUrl: "https://api.minimaxi.com/anthropic/v1/messages",
+      urlSuffix: "?beta=true",
+      headers: { ...CLAUDE_API_HEADERS },
+      auth: { combined: true, header: "x-api-key", scheme: "raw" },
+    },
+  ],
+  models: [
+    { id: "MiniMax-M3", name: "MiniMax M3", targetFormat: "claude" },
+    { id: "MiniMax-M2.7", name: "MiniMax M2.7" },
+    { id: "MiniMax-M2.5", name: "MiniMax M2.5" },
+    { id: "MiniMax-M2.1", name: "MiniMax M2.1" },
+    { id: "speech-2.8-hd", name: "Speech 2.8 HD", kind: "tts" },
+    { id: "speech-2.8-turbo", name: "Speech 2.8 Turbo", kind: "tts" },
+    { id: "speech-2.6-hd", name: "Speech 2.6 HD", kind: "tts" },
+    { id: "speech-2.6-turbo", name: "Speech 2.6 Turbo", kind: "tts" },
+    { id: "speech-02-hd", name: "Speech 02 HD", kind: "tts" },
+    { id: "speech-02-turbo", name: "Speech 02 Turbo", kind: "tts" },
+    { id: "speech-01-hd", name: "Speech 01 HD", kind: "tts" },
+    { id: "speech-01-turbo", name: "Speech 01 Turbo", kind: "tts" },
+  ],
+  serviceKinds: ["llm","tts"],
+  ttsConfig: { baseUrl: "https://api.minimaxi.com/v1/t2a_v2", authType: "apikey", authHeader: "bearer", format: "minimax-tts" },
+  features: {
+    usage: true,
+    usageApikey: true,
+  },
+};
diff --git a/open-sse/providers/registry/minimax.js b/open-sse/providers/registry/minimax.js
new file mode 100644
index 0000000..47b82c8
--- /dev/null
+++ b/open-sse/providers/registry/minimax.js
@@ -0,0 +1,83 @@
+import { CLAUDE_API_HEADERS } from "../shared.js";
+
+export default {
+  id: "minimax",
+  priority: 90,
+  alias: "minimax",
+  display: {
+    name: "Minimax Coding",
+    icon: "memory",
+    color: "#7C3AED",
+    textIcon: "MM",
+    website: "https://www.minimaxi.com",
+    notice: {
+      apiKeyUrl: "https://platform.minimaxi.com/user-center/basic-information/interface-key",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.minimax.io/anthropic/v1/messages",
+    format: "claude",
+    urlSuffix: "?beta=true",
+    headers: { ...CLAUDE_API_HEADERS },
+    quirks: {
+      dropOutputConfig: true,
+    },
+    reasoningInject: {
+      scope: "all",
+    },
+    auth: {
+      combined: true,
+      header: "x-api-key",
+      scheme: "raw",
+    },
+    usage: {
+      urls: [
+        "https://www.minimax.io/v1/token_plan/remains",
+        "https://api.minimax.io/v1/api/openplatform/coding_plan/remains",
+      ],
+    },
+  },
+  // Multi-endpoint: pick the transport matching client sourceFormat to skip translation.
+  transports: [
+    {
+      format: "openai",
+      baseUrl: "https://api.minimax.io/v1/chat/completions",
+      auth: { combined: true, header: "Authorization", scheme: "bearer" },
+    },
+    {
+      format: "claude",
+      baseUrl: "https://api.minimax.io/anthropic/v1/messages",
+      urlSuffix: "?beta=true",
+      headers: { ...CLAUDE_API_HEADERS },
+      auth: { combined: true, header: "x-api-key", scheme: "raw" },
+    },
+  ],
+  models: [
+    { id: "MiniMax-M3", name: "MiniMax M3", targetFormat: "claude" },
+    { id: "MiniMax-M2.7", name: "MiniMax M2.7" },
+    { id: "MiniMax-M2.5", name: "MiniMax M2.5" },
+    { id: "MiniMax-M2.1", name: "MiniMax M2.1" },
+    { id: "minimax-image-01", name: "MiniMax Image 01", params: ["n","size","response_format"], kind: "image" },
+    { id: "speech-2.8-hd", name: "Speech 2.8 HD", kind: "tts" },
+    { id: "speech-2.8-turbo", name: "Speech 2.8 Turbo", kind: "tts" },
+    { id: "speech-2.6-hd", name: "Speech 2.6 HD", kind: "tts" },
+    { id: "speech-2.6-turbo", name: "Speech 2.6 Turbo", kind: "tts" },
+    { id: "speech-02-hd", name: "Speech 02 HD", kind: "tts" },
+    { id: "speech-02-turbo", name: "Speech 02 Turbo", kind: "tts" },
+    { id: "speech-01-hd", name: "Speech 01 HD", kind: "tts" },
+    { id: "speech-01-turbo", name: "Speech 01 Turbo", kind: "tts" },
+  ],
+  serviceKinds: ["llm","image","imageToText","webSearch","tts"],
+  ttsConfig: { baseUrl: "https://api.minimax.io/v1/t2a_v2", authType: "apikey", authHeader: "bearer", format: "minimax-tts" },
+  imageConfig: { baseUrl: "https://api.minimaxi.com/v1/images/generations" },
+  searchViaChat: {
+    defaultModel: "MiniMax-M2.7",
+    endpoint: "https://api.minimaxi.com/v1/text/chatcompletion_v2",
+    pricingUrl: "https://www.minimaxi.com/document/price",
+  },
+  features: {
+    usage: true,
+    usageApikey: true,
+  },
+};
diff --git a/open-sse/providers/registry/mistral.js b/open-sse/providers/registry/mistral.js
new file mode 100644
index 0000000..b586913
--- /dev/null
+++ b/open-sse/providers/registry/mistral.js
@@ -0,0 +1,31 @@
+export default {
+  id: "mistral",
+  priority: 80,
+  alias: "mistral",
+  display: {
+    name: "Mistral",
+    icon: "air",
+    color: "#FF7000",
+    textIcon: "MI",
+    website: "https://mistral.ai",
+    notice: {
+      apiKeyUrl: "https://console.mistral.ai/api-keys",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.mistral.ai/v1/chat/completions",
+    validateUrl: "https://api.mistral.ai/v1/models",
+    quirks: {
+      dropClientMetadata: true,
+    },
+  },
+  models: [
+    { id: "mistral-large-latest", name: "Mistral Large 3" },
+    { id: "codestral-latest", name: "Codestral" },
+    { id: "mistral-medium-latest", name: "Mistral Medium 3" },
+    { id: "mistral-embed", name: "Mistral Embed", kind: "embedding" },
+  ],
+  serviceKinds: ["llm","imageToText","embedding"],
+  embeddingConfig: { baseUrl: "https://api.mistral.ai/v1/embeddings", authType: "apikey", authHeader: "bearer" },
+};
diff --git a/open-sse/providers/registry/mmf.js b/open-sse/providers/registry/mmf.js
new file mode 100644
index 0000000..63c776f
--- /dev/null
+++ b/open-sse/providers/registry/mmf.js
@@ -0,0 +1,19 @@
+export default {
+  id: "mmf",
+  hidden: true,
+  priority: 200,
+  display: {
+    name: "MMF",
+    icon: "hub",
+    color: "#6366F1",
+    textIcon: "MF",
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.xiaomimimo.com/api/free-ai/openai/chat",
+    noAuth: true,
+  },
+  models: [
+    { id: "mimo-auto", name: "MiMo Auto" },
+  ],
+};
diff --git a/open-sse/providers/registry/nanobanana.js b/open-sse/providers/registry/nanobanana.js
new file mode 100644
index 0000000..f57b49a
--- /dev/null
+++ b/open-sse/providers/registry/nanobanana.js
@@ -0,0 +1,35 @@
+export default {
+  id: "nanobanana",
+  priority: 80,
+  hasFree: true,
+  alias: "nanobanana",
+  aliases: [
+    "nb",
+  ],
+  uiAlias: "nb",
+  display: {
+    name: "NanoBanana API",
+    icon: "extension",
+    color: "#FFD700",
+    textIcon: "🍌",
+    website: "https://nanobananaapi.ai",
+    notice: {
+      text: "3rd-party proxy for Google Nano Banana (Gemini 2.5/3 Flash Image). For official, use Gemini provider.",
+      apiKeyUrl: "https://nanobananaapi.ai/dashboard",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.nanobananaapi.ai/v1/chat/completions",
+    validateUrl: "https://api.nanobananaapi.ai/v1/models",
+  },
+  models: [
+    { id: "nanobanana-flash", name: "NanoBanana Flash", params: ["n","size"], kind: "image" },
+    { id: "nanobanana-pro", name: "NanoBanana Pro", params: ["n","size"], kind: "image" },
+  ],
+  serviceKinds: ["image"],
+  imageConfig: {
+    baseUrl: "https://api.nanobananaapi.ai/api/v1/nanobanana/generate",
+    pollUrl: "https://api.nanobananaapi.ai/api/v1/nanobanana/record-info",
+  },
+};
diff --git a/open-sse/providers/registry/nebius.js b/open-sse/providers/registry/nebius.js
new file mode 100644
index 0000000..bcfdd25
--- /dev/null
+++ b/open-sse/providers/registry/nebius.js
@@ -0,0 +1,27 @@
+export default {
+  id: "nebius",
+  priority: 70,
+  alias: "nebius",
+  display: {
+    name: "Nebius AI",
+    icon: "cloud",
+    color: "#6C5CE7",
+    textIcon: "NB",
+    website: "https://nebius.com",
+    notice: {
+      apiKeyUrl: "https://studio.nebius.com/settings/api-keys",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: {
+    baseUrl: "https://api.studio.nebius.ai/v1/chat/completions",
+    validateUrl: "https://api.studio.nebius.ai/v1/models",
+  },
+  models: [
+    { id: "meta-llama/Llama-3.3-70B-Instruct", name: "Llama 3.3 70B Instruct" },
+    { id: "Qwen/Qwen3-Embedding-8B", name: "Qwen3 Embedding 8B", kind: "embedding" },
+  ],
+  serviceKinds: ["llm", "embedding"],
+  embeddingConfig: { baseUrl: "https://api.tokenfactory.nebius.com/v1/embeddings" },
+};
diff --git a/open-sse/providers/registry/nvidia.js b/open-sse/providers/registry/nvidia.js
new file mode 100644
index 0000000..9522611
--- /dev/null
+++ b/open-sse/providers/registry/nvidia.js
@@ -0,0 +1,43 @@
+export default {
+  id: "nvidia",
+  priority: 20,
+  hasFree: true,
+  alias: "nvidia",
+  display: {
+    name: "NVIDIA NIM",
+    icon: "developer_board",
+    color: "#76B900",
+    textIcon: "NV",
+    website: "https://developer.nvidia.com/nim",
+    notice: {
+      text: "Free access for NVIDIA Developer Program members (prototyping & testing).",
+      apiKeyUrl: "https://build.nvidia.com/settings/api-keys",
+    },
+  },
+  category: "freeTier",
+  transport: {
+    baseUrl: "https://integrate.api.nvidia.com/v1/chat/completions",
+    validateUrl: "https://integrate.api.nvidia.com/v1/models",
+  },
+  models: [
+    { id: "minimaxai/minimax-m2.7", name: "MiniMax M2.7" },
+    { id: "minimaxai/minimax-m3", name: "MiniMax M3" },
+    { id: "z-ai/glm-5.2", name: "GLM 5.2" },
+    { id: "deepseek-ai/deepseek-v4-pro", name: "DeepSeek V4 Pro" },
+    { id: "deepseek-ai/deepseek-v4-flash", name: "DeepSeek V4 Flash" },
+    { id: "moonshotai/kimi-k2.6", name: "Kimi K2.6" },
+    { id: "nvidia/nemotron-3-ultra-550b-a55b", name: "Nemotron 3 Ultra" },
+    { id: "nvidia/nv-embedqa-e5-v5", name: "NV EmbedQA E5 v5", kind: "embedding" },
+    { id: "nvidia/parakeet-ctc-1.1b-asr", name: "Parakeet CTC 1.1B", params: ["language"], kind: "stt" },
+    { id: "fastpitch", name: "FastPitch", kind: "tts" },
+    { id: "tacotron2", name: "Tacotron2", kind: "tts" },
+  ],
+  serviceKinds: ["llm","tts","embedding"],
+  ttsConfig: {
+    baseUrl: "https://integrate.api.nvidia.com/v1/audio/speech",
+    authType: "apikey",
+    authHeader: "bearer",
+    format: "nvidia-tts",
+  },
+  embeddingConfig: { baseUrl: "https://integrate.api.nvidia.com/v1/embeddings", authType: "apikey", authHeader: "bearer" },
+};
diff --git a/open-sse/providers/registry/ollama-local.js b/open-sse/providers/registry/ollama-local.js
new file mode 100644
index 0000000..1d83238
--- /dev/null
+++ b/open-sse/providers/registry/ollama-local.js
@@ -0,0 +1,19 @@
+export default {
+  id: "ollama-local",
+  priority: 50,
+  hasFree: true,
+  alias: "ollama-local",
+  display: {
+    name: "Ollama Local",
+    icon: "cloud",
+    color: "#ffffffff",
+    textIcon: "OL",
+    website: "https://ollama.com",
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "http://localhost:11434/api/chat",
+    format: "ollama",
+  },
+  serviceKinds: ["llm"],
+};
diff --git a/open-sse/providers/registry/ollama.js b/open-sse/providers/registry/ollama.js
new file mode 100644
index 0000000..69923aa
--- /dev/null
+++ b/open-sse/providers/registry/ollama.js
@@ -0,0 +1,36 @@
+export default {
+  id: "ollama",
+  priority: 30,
+  hasFree: true,
+  alias: "ollama",
+  display: {
+    name: "Ollama Cloud",
+    icon: "cloud",
+    color: "#ffffffff",
+    textIcon: "OL",
+    website: "https://ollama.com",
+    notice: {
+      text: "Free tier: light usage, 1 cloud model at a time (limits reset every 5h & 7d). Pro $20/mo · Max $100/mo.",
+      apiKeyUrl: "https://ollama.com/settings/keys",
+    },
+  },
+  category: "freeTier",
+  transport: {
+    baseUrl: "https://ollama.com/api/chat",
+    validateUrl: "https://ollama.com/api/tags",
+    format: "ollama",
+  },
+  models: [
+    { id: "gpt-oss:120b", name: "GPT OSS 120B" },
+    { id: "kimi-k2.5", name: "Kimi K2.5" },
+    { id: "glm-5", name: "GLM 5" },
+    { id: "minimax-m2.5", name: "MiniMax M2.5" },
+    { id: "glm-4.7-flash", name: "GLM 4.7 Flash" },
+    { id: "qwen3.5", name: "Qwen3.5" },
+    { id: "minimax-m3", name: "MiniMax M3" },
+  ],
+  serviceKinds: ["llm"],
+  features: {
+    usage: true,
+  },
+};
diff --git a/open-sse/providers/registry/openai.js b/open-sse/providers/registry/openai.js
new file mode 100644
index 0000000..9a1ca57
--- /dev/null
+++ b/open-sse/providers/registry/openai.js
@@ -0,0 +1,81 @@
+export default {
+  id: "openai",
+  priority: 30,
+  alias: "openai",
+  display: {
+    name: "OpenAI",
+    icon: "auto_awesome",
+    color: "#10A37F",
+    textIcon: "OA",
+    website: "https://platform.openai.com",
+    notice: {
+      apiKeyUrl: "https://platform.openai.com/api-keys",
+    },
+  },
+  category: "apikey",
+  thinkingConfig: {
+    options: [
+      "auto",
+      "none",
+      "low",
+      "medium",
+      "high",
+    ],
+    defaultMode: "auto",
+  },
+  transport: {
+    baseUrl: "https://api.openai.com/v1/chat/completions",
+    forceStream: true,
+  },
+  models: [
+    { id: "gpt-5.4", name: "GPT-5.4" },
+    { id: "gpt-5.4-mini", name: "GPT-5.4 Mini" },
+    { id: "gpt-5.4-nano", name: "GPT-5.4 Nano" },
+    { id: "gpt-5.2", name: "GPT-5.2" },
+    { id: "gpt-5.1", name: "GPT-5.1" },
+    { id: "gpt-5", name: "GPT-5" },
+    { id: "gpt-5-mini", name: "GPT-5 Mini" },
+    { id: "gpt-5-nano", name: "GPT-5 Nano" },
+    { id: "gpt-4o", name: "GPT-4o" },
+    { id: "gpt-4o-mini", name: "GPT-4o Mini" },
+    { id: "gpt-4-turbo", name: "GPT-4 Turbo" },
+    { id: "gpt-4.1", name: "GPT-4.1" },
+    { id: "gpt-4.1-mini", name: "GPT-4.1 Mini" },
+    { id: "gpt-4.1-nano", name: "GPT-4.1 Nano" },
+    { id: "o3", name: "O3" },
+    { id: "o3-mini", name: "O3 Mini" },
+    { id: "o3-pro", name: "O3 Pro" },
+    { id: "o4-mini", name: "O4 Mini" },
+    { id: "o1", name: "O1" },
+    { id: "o1-mini", name: "O1 Mini" },
+    { id: "text-embedding-3-large", name: "Text Embedding 3 Large", kind: "embedding" },
+    { id: "text-embedding-3-small", name: "Text Embedding 3 Small", kind: "embedding" },
+    { id: "text-embedding-ada-002", name: "Text Embedding Ada 002", kind: "embedding" },
+    { id: "tts-1", name: "TTS-1", kind: "tts" },
+    { id: "tts-1-hd", name: "TTS-1 HD", kind: "tts" },
+    { id: "gpt-4o-mini-tts", name: "GPT-4o Mini TTS", kind: "tts" },
+    { id: "whisper-1", name: "Whisper 1", params: ["language","response_format","temperature","prompt"], kind: "stt" },
+    { id: "gpt-4o-transcribe", name: "GPT-4o Transcribe", params: ["language","response_format","temperature","prompt"], kind: "stt" },
+    { id: "gpt-4o-mini-transcribe", name: "GPT-4o Mini Transcribe", params: ["language","response_format","temperature","prompt"], kind: "stt" },
+    { id: "gpt-image-1", name: "GPT Image 1", params: ["n","size","quality","response_format"], kind: "image" },
+    { id: "dall-e-3", name: "DALL-E 3", params: ["size","quality","style","response_format"], kind: "image" },
+    { id: "dall-e-2", name: "DALL-E 2", params: ["n","size","response_format"], kind: "image" },
+  ],
+  serviceKinds: ["llm","embedding","tts","stt","image","imageToText","webSearch"],
+  ttsConfig: {
+    baseUrl: "https://api.openai.com/v1/audio/speech",
+    authType: "apikey",
+    authHeader: "bearer",
+    format: "openai",
+    defaultModel: "gpt-4o-mini-tts",
+  },
+  sttConfig: {
+    baseUrl: "https://api.openai.com/v1/audio/transcriptions",
+    authType: "apikey",
+    authHeader: "bearer",
+    format: "openai",
+  },
+  embeddingConfig: { baseUrl: "https://api.openai.com/v1/embeddings", authType: "apikey", authHeader: "bearer" },
+  imageConfig: { baseUrl: "https://api.openai.com/v1/images/generations" },
+  searchViaChat: { defaultModel: "gpt-4o-mini", pricingUrl: "https://openai.com/api/pricing" },
+};
diff --git a/open-sse/providers/registry/opencode-go.js b/open-sse/providers/registry/opencode-go.js
new file mode 100644
index 0000000..c980cc8
--- /dev/null
+++ b/open-sse/providers/registry/opencode-go.js
@@ -0,0 +1,41 @@
+export default {
+  id: "opencode-go",
+  priority: 210,
+  alias: "opencode-go",
+  aliases: [
+    "ocg",
+  ],
+  uiAlias: "ocg",
+  display: {
+    name: "OpenCode Go",
+    icon: "terminal",
+    color: "#E87040",
+    textIcon: "OC",
+    website: "https://opencode.ai/auth",
+    notice: {
+      text: "OpenCode Go subscription: $5/mo (then  0/mo). Access to Kimi, GLM, Qwen, MiMo, MiniMax models.",
+      apiKeyUrl: "https://opencode.ai/auth",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://opencode.ai/zen/go/v1/chat/completions",
+    headers: {},
+  },
+  models: [
+    { id: "glm-5.2", name: "GLM 5.2" },
+    { id: "glm-5.1", name: "GLM 5.1" },
+    { id: "kimi-k2.7-code", name: "Kimi K2.7 Code" },
+    { id: "kimi-k2.6", name: "Kimi K2.6" },
+    { id: "deepseek-v4-pro", name: "DeepSeek V4 Pro" },
+    { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash" },
+    { id: "mimo-v2.5", name: "MiMo V2.5" },
+    { id: "mimo-v2.5-pro", name: "MiMo V2.5 Pro" },
+    { id: "minimax-m3", name: "MiniMax M3", targetFormat: "claude" },
+    { id: "minimax-m2.7", name: "MiniMax M2.7", targetFormat: "claude" },
+    { id: "minimax-m2.5", name: "MiniMax M2.5", targetFormat: "claude" },
+    { id: "qwen3.7-max", name: "Qwen 3.7 Max", targetFormat: "claude" },
+    { id: "qwen3.7-plus", name: "Qwen 3.7 Plus", targetFormat: "claude" },
+    { id: "qwen3.6-plus", name: "Qwen 3.6 Plus", targetFormat: "claude" },
+  ],
+};
diff --git a/open-sse/providers/registry/opencode.js b/open-sse/providers/registry/opencode.js
new file mode 100644
index 0000000..e83ad3a
--- /dev/null
+++ b/open-sse/providers/registry/opencode.js
@@ -0,0 +1,25 @@
+export default {
+  id: "opencode",
+  priority: 40,
+  hasFree: true,
+  alias: "oc",
+  uiAlias: "oc",
+  display: {
+    name: "OpenCode Free",
+    icon: "terminal",
+    color: "#E87040",
+    textIcon: "OC",
+  },
+  category: "free",
+  noAuth: true,
+  transport: {
+    baseUrl: "https://opencode.ai",
+    headers: {
+      "x-opencode-client": "desktop",
+    },
+    noAuth: true,
+  },
+  models: [],
+  modelsFetcher: { url: "https://opencode.ai/zen/v1/models", type: "opencode-free" },
+  passthroughModels: true,
+};
diff --git a/open-sse/providers/registry/openrouter.js b/open-sse/providers/registry/openrouter.js
new file mode 100644
index 0000000..4ac0364
--- /dev/null
+++ b/open-sse/providers/registry/openrouter.js
@@ -0,0 +1,60 @@
+export default {
+  id: "openrouter",
+  priority: 10,
+  hasFree: true,
+  alias: "openrouter",
+  display: {
+    name: "OpenRouter",
+    icon: "router",
+    color: "#F97316",
+    textIcon: "OR",
+    website: "https://openrouter.ai",
+    notice: {
+      text: "Free tier: 27+ free models, no credit card needed, 200 req/day. After  0 credit: 1,000 req/day.",
+      apiKeyUrl: "https://openrouter.ai/settings/keys",
+    },
+  },
+  category: "freeTier",
+  transport: {
+    baseUrl: "https://openrouter.ai/api/v1/chat/completions",
+    thinkingFormat: "openai",
+    headers: {
+      "HTTP-Referer": "https://endpoint-proxy.local",
+      "X-Title": "Endpoint Proxy",
+    },
+  },
+  models: [
+    { id: "openai/text-embedding-3-large", name: "OpenAI Text Embedding 3 Large", kind: "embedding" },
+    { id: "openai/text-embedding-3-small", name: "OpenAI Text Embedding 3 Small", kind: "embedding" },
+    { id: "openai/text-embedding-ada-002", name: "OpenAI Text Embedding Ada 002", kind: "embedding" },
+    { id: "qwen/qwen3-embedding-8b", name: "Qwen3 Embedding 8B", kind: "embedding" },
+    { id: "perplexity/pplx-embed-v1-4b", name: "Perplexity Embed V1 4B", kind: "embedding" },
+    { id: "perplexity/pplx-embed-v1-0.6b", name: "Perplexity Embed V1 0.6B", kind: "embedding" },
+    { id: "nvidia/llama-nemotron-embed-vl-1b-v2:free", name: "NVIDIA Nemotron Embed VL 1B V2 (Free)", kind: "embedding" },
+    { id: "openai/gpt-4o-mini-tts", name: "GPT-4o Mini TTS", kind: "tts" },
+    { id: "openai/tts-1-hd", name: "TTS-1 HD", kind: "tts" },
+    { id: "openai/tts-1", name: "TTS-1", kind: "tts" },
+    { id: "openai/dall-e-3", name: "DALL-E 3 (via OpenRouter)", params: ["size","quality","style","response_format"], kind: "image" },
+    { id: "openai/gpt-image-1", name: "GPT Image 1 (via OpenRouter)", params: ["n","size","quality","response_format"], kind: "image" },
+    { id: "google/imagen-3.0-generate-002", name: "Imagen 3 (via OpenRouter)", params: ["n","size"], kind: "image" },
+    { id: "black-forest-labs/FLUX.1-schnell", name: "FLUX.1 Schnell (via OpenRouter)", params: ["n","size"], kind: "image" },
+  ],
+  serviceKinds: ["llm","embedding","tts","imageToText"],
+  ttsConfig: {
+    baseUrl: "https://openrouter.ai/api/v1/chat/completions",
+    defaultModel: "openai/gpt-4o-mini-tts",
+    headers: {"HTTP-Referer":"https://endpoint-proxy.local","X-Title":"Endpoint Proxy"},
+  },
+  embeddingConfig: {
+    baseUrl: "https://openrouter.ai/api/v1/embeddings",
+    authType: "apikey",
+    authHeader: "bearer",
+    headers: {"HTTP-Referer":"https://endpoint-proxy.local","X-Title":"Endpoint Proxy"},
+  },
+  imageConfig: {
+    baseUrl: "https://openrouter.ai/api/v1/images/generations",
+    headers: {"HTTP-Referer":"https://endpoint-proxy.local","X-Title":"Endpoint Proxy"},
+  },
+  modelsFetcher: { url: "https://openrouter.ai/api/v1/models", type: "openrouter-free" },
+  passthroughModels: true,
+};
diff --git a/open-sse/providers/registry/perplexity-agent.js b/open-sse/providers/registry/perplexity-agent.js
new file mode 100644
index 0000000..5c8785e
--- /dev/null
+++ b/open-sse/providers/registry/perplexity-agent.js
@@ -0,0 +1,49 @@
+export default {
+  id: "perplexity-agent",
+  priority: 181,
+  alias: "perplexity-agent",
+  aliases: [
+    "pplx-agent",
+    "pplx-responses",
+  ],
+  uiAlias: "pa",
+  display: {
+    name: "Perplexity Agent",
+    icon: "travel_explore",
+    color: "#20808D",
+    textIcon: "PA",
+    website: "https://www.perplexity.ai",
+    notice: {
+      text: "Perplexity Agent API exposes GPT, Claude, Gemini, Grok, GLM, Kimi, and Sonar models through one OpenAI-compatible Responses API.",
+      apiKeyUrl: "https://www.perplexity.ai/settings/api",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: {
+    baseUrl: "https://api.perplexity.ai/v1/responses",
+    validateUrl: "https://api.perplexity.ai/v1/models",
+    format: "openai-responses",
+  },
+  models: [
+    { id: "perplexity/sonar", name: "Perplexity Sonar" },
+    { id: "openai/gpt-5.5", name: "GPT-5.5" },
+    { id: "openai/gpt-5.4", name: "GPT-5.4" },
+    { id: "openai/gpt-5.4-mini", name: "GPT-5.4 Mini" },
+    { id: "anthropic/claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
+    { id: "anthropic/claude-opus-4-8", name: "Claude Opus 4.8" },
+    { id: "google/gemini-3.1-pro-preview", name: "Gemini 3.1 Pro" },
+    { id: "xai/grok-4.20-reasoning", name: "Grok 4.20 Reasoning" },
+    { id: "perplexity/glm-5.2", name: "GLM 5.2" },
+    { id: "perplexity/kimi-k2.7-code", name: "Kimi K2.7 Code" },
+    { id: "nvidia/nemotron-3-super-120b-a12b", name: "Nemotron 3 Super 120B" },
+  ],
+  serviceKinds: ["llm", "webSearch"],
+  searchViaChat: {
+    defaultModel: "perplexity/sonar",
+    endpoint: "https://api.perplexity.ai/v1/responses",
+    pricingUrl: "https://docs.perplexity.ai/docs/agent-api/models",
+  },
+  modelsFetcher: { url: "https://api.perplexity.ai/v1/models", type: "openai" },
+  passthroughModels: true,
+};
diff --git a/open-sse/providers/registry/perplexity-web.js b/open-sse/providers/registry/perplexity-web.js
new file mode 100644
index 0000000..fcaa357
--- /dev/null
+++ b/open-sse/providers/registry/perplexity-web.js
@@ -0,0 +1,33 @@
+export default {
+  id: "perplexity-web",
+  priority: 220,
+  alias: "perplexity-web",
+  aliases: [
+    "pw",
+  ],
+  uiAlias: "pw",
+  display: {
+    name: "Perplexity Web (Pro/Max)",
+    icon: "search",
+    color: "#20808D",
+    textIcon: "PW",
+    website: "https://www.perplexity.ai",
+  },
+  category: "webCookie",
+  authType: "cookie",
+  authHint: "Paste your __Secure-next-auth.session-token cookie value from perplexity.ai",
+  transport: {
+    baseUrl: "https://www.perplexity.ai/rest/sse/perplexity_ask",
+    format: "perplexity-web",
+    authType: "cookie",
+  },
+  models: [
+    { id: "pplx-auto", name: "Perplexity Auto (Free)" },
+    { id: "pplx-sonar", name: "Perplexity Sonar" },
+    { id: "pplx-gpt", name: "GPT-5.4 (via Perplexity)" },
+    { id: "pplx-gemini", name: "Gemini 3.1 Pro (via Perplexity)" },
+    { id: "pplx-sonnet", name: "Claude Sonnet 4.6 (via Perplexity)" },
+    { id: "pplx-opus", name: "Claude Opus 4.6 (via Perplexity)" },
+    { id: "pplx-nemotron", name: "Nemotron 3 Super (via Perplexity)" },
+  ],
+};
diff --git a/open-sse/providers/registry/perplexity.js b/open-sse/providers/registry/perplexity.js
new file mode 100644
index 0000000..f594b50
--- /dev/null
+++ b/open-sse/providers/registry/perplexity.js
@@ -0,0 +1,35 @@
+export default {
+  id: "perplexity",
+  priority: 180,
+  alias: "perplexity",
+  aliases: [
+    "pplx",
+  ],
+  uiAlias: "pplx",
+  display: {
+    name: "Perplexity",
+    icon: "search",
+    color: "#20808D",
+    textIcon: "PP",
+    website: "https://www.perplexity.ai",
+    notice: {
+      apiKeyUrl: "https://www.perplexity.ai/settings/api",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: {
+    baseUrl: "https://api.perplexity.ai/chat/completions",
+    validateUrl: "https://api.perplexity.ai/models",
+  },
+  models: [
+    { id: "sonar-pro", name: "Sonar Pro" },
+    { id: "sonar", name: "Sonar" },
+  ],
+  serviceKinds: ["llm","webSearch"],
+  searchViaChat: {
+    defaultModel: "sonar",
+    endpoint: "https://api.perplexity.ai/chat/completions",
+    pricingUrl: "https://docs.perplexity.ai/guides/pricing",
+  },
+};
diff --git a/open-sse/providers/registry/playht.js b/open-sse/providers/registry/playht.js
new file mode 100644
index 0000000..1373e56
--- /dev/null
+++ b/open-sse/providers/registry/playht.js
@@ -0,0 +1,36 @@
+export default {
+  id: "playht",
+  alias: "playht",
+  display: {
+    name: "PlayHT",
+    icon: "play_circle",
+    color: "#00B4D8",
+    textIcon: "PH",
+    website: "https://play.ht",
+    notice: {
+      apiKeyUrl: "https://play.ht/studio/api-access"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "tts"
+  ],
+  ttsConfig: {
+    baseUrl: "https://api.play.ht/api/v2/tts/stream",
+    authType: "apikey",
+    authHeader: "playht",
+    format: "playht",
+    models: [
+      {
+        id: "PlayDialog",
+        name: "PlayDialog"
+      },
+      {
+        id: "Play3.0-mini",
+        name: "Play 3.0 Mini"
+      }
+    ]
+  },
+  hidden: true
+};
diff --git a/open-sse/providers/registry/qoder.js b/open-sse/providers/registry/qoder.js
new file mode 100644
index 0000000..4ee2b52
--- /dev/null
+++ b/open-sse/providers/registry/qoder.js
@@ -0,0 +1,54 @@
+export default {
+  id: "qoder",
+  priority: 30,
+  alias: "qd",
+  uiAlias: "qd",
+  display: {
+    name: "Qoder",
+    icon: "water_drop",
+    color: "#EC4899",
+    website: "https://qoder.com",
+    notice: {
+      signupUrl: "https://qoder.com",
+    },
+    deprecated: true,
+    deprecationNotice: "RISK_NOTICE",
+  },
+  category: "free",
+  transport: {
+    baseUrl: "https://api3.qoder.sh/algo/api/v2/service/pro/sse/agent_chat_generation",
+    headers: {},
+    timeoutMs: 120000,
+    stallTimeoutMs: 120000,
+    usage: {
+      url: "https://openapi.qoder.sh/api/v2/quota/usage",
+    },
+  },
+  models: [
+    // { id: "auto", name: "Qoder Auto" },
+    // { id: "ultimate", name: "Qoder Ultimate" },
+    // { id: "performance", name: "Qoder Performance" },
+    // { id: "efficient", name: "Qoder Efficient" },
+    // { id: "lite", name: "Qoder Lite" },
+    // { id: "qmodel", name: "Qwen 3.6 Plus (Qoder)" },
+    { id: "qmodel_latest", name: "Qoder Qwen 3.7 Max" },
+    // { id: "dmodel", name: "DeepSeek V4 Pro (Qoder)" },
+    // { id: "dfmodel", name: "DeepSeek V4 Flash (Qoder)" },
+    // { id: "gm51model", name: "GLM 5.1 (Qoder)" },
+    // { id: "kmodel", name: "Kimi K2.6 (Qoder)" },
+    // { id: "mmodel", name: "MiniMax M2.7 (Qoder)" },
+  ],
+  oauth: {
+    openApiBaseUrl: "https://openapi.qoder.sh",
+    centerBaseUrl: "https://center.qoder.sh",
+    chatBaseUrl: "https://api3.qoder.sh",
+    deviceTokenUrl: "https://openapi.qoder.sh/api/v1/deviceToken/poll",
+    refreshUrl: "https://center.qoder.sh/algo/api/v3/user/refresh_token",
+    userInfoUrl: "https://openapi.qoder.sh/api/v1/userinfo",
+    quotaUsageUrl: "https://openapi.qoder.sh/api/v2/quota/usage",
+    loginUrl: "https://qoder.com/device/selectAccounts",
+  },
+  features: {
+    usage: true,
+  },
+};
diff --git a/open-sse/providers/registry/qwen.js b/open-sse/providers/registry/qwen.js
new file mode 100644
index 0000000..0df381a
--- /dev/null
+++ b/open-sse/providers/registry/qwen.js
@@ -0,0 +1,33 @@
+export default {
+  id: "qwen",
+  hidden: true,
+  priority: 130,
+  alias: "qw",
+  display: {
+    name: "Qwen Code",
+    icon: "psychology",
+    color: "#10B981",
+    website: "https://chat.qwen.ai",
+    notice: {
+      signupUrl: "https://chat.qwen.ai",
+    },
+  },
+  category: "oauth",
+  transport: {
+    baseUrl: "https://portal.qwen.ai/v1/chat/completions",
+  },
+  models: [
+    { id: "qwen3-coder-plus", name: "Qwen3 Coder Plus" },
+    { id: "qwen3-coder-flash", name: "Qwen3 Coder Flash" },
+    { id: "vision-model", name: "Qwen3 Vision Model" },
+    { id: "coder-model", name: "Qwen3.6 Coder Model" },
+  ],
+  oauth: {
+    clientId: "f0304373b74a44d2b584a3fb70ca9e56",
+    deviceCodeUrl: "https://chat.qwen.ai/api/v1/oauth2/device/code",
+    tokenUrl: "https://chat.qwen.ai/api/v1/oauth2/token",
+    scope: "openid profile email model.completion",
+    codeChallengeMethod: "S256",
+    refreshLeadMs: 1200000,
+  },
+};
diff --git a/open-sse/providers/registry/recraft.js b/open-sse/providers/registry/recraft.js
new file mode 100644
index 0000000..e64a70a
--- /dev/null
+++ b/open-sse/providers/registry/recraft.js
@@ -0,0 +1,24 @@
+export default {
+  id: "recraft",
+  priority: 70,
+  alias: "recraft",
+  display: {
+    name: "Recraft",
+    icon: "image",
+    color: "#EC4899",
+    textIcon: "RC",
+    website: "https://recraft.ai",
+    notice: {
+      apiKeyUrl: "https://www.recraft.ai/profile/api",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: null,
+  models: [
+    { id: "recraftv3", name: "Recraft V3", params: ["n","size","style"], kind: "image" },
+    { id: "recraftv2", name: "Recraft V2", params: ["n","size","style"], kind: "image" },
+  ],
+  serviceKinds: ["image"],
+  imageConfig: { baseUrl: "https://external.api.recraft.ai/v1/images/generations" },
+};
diff --git a/open-sse/providers/registry/runwayml.js b/open-sse/providers/registry/runwayml.js
new file mode 100644
index 0000000..4c86e52
--- /dev/null
+++ b/open-sse/providers/registry/runwayml.js
@@ -0,0 +1,30 @@
+export default {
+  id: "runwayml",
+  priority: 80,
+  alias: "runwayml",
+  aliases: [
+    "runway",
+  ],
+  uiAlias: "runway",
+  display: {
+    name: "Runway ML",
+    icon: "movie",
+    color: "#000000",
+    textIcon: "RW",
+    website: "https://runwayml.com",
+    notice: {
+      apiKeyUrl: "https://dev.runwayml.com",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: null,
+  models: [
+    { id: "gen4_image", name: "Gen-4 Image", params: ["size"], kind: "image" },
+    { id: "gen4_image_turbo", name: "Gen-4 Image Turbo", params: ["size"], kind: "image" },
+    { id: "gen4_turbo", name: "Gen-4 Turbo", params: [], kind: "video" },
+    { id: "gen3a_turbo", name: "Gen-3 Alpha Turbo", params: [], kind: "video" },
+  ],
+  serviceKinds: ["image"],
+  imageConfig: { baseUrl: "https://api.dev.runwayml.com/v1" },
+};
diff --git a/open-sse/providers/registry/sdwebui.js b/open-sse/providers/registry/sdwebui.js
new file mode 100644
index 0000000..f253c92
--- /dev/null
+++ b/open-sse/providers/registry/sdwebui.js
@@ -0,0 +1,20 @@
+export default {
+  id: "sdwebui",
+  priority: 110,
+  alias: "sdwebui",
+  display: {
+    name: "SD WebUI",
+    icon: "brush",
+    color: "#FF7043",
+    textIcon: "SD",
+    website: "https://github.com/AUTOMATIC1111/stable-diffusion-webui",
+  },
+  category: "apikey",
+  transport: null,
+  models: [
+    { id: "stable-diffusion-v1-5", name: "Stable Diffusion v1.5", params: ["n","size"], kind: "image" },
+    { id: "sdxl-base-1.0", name: "SDXL Base 1.0", params: ["n","size"], kind: "image" },
+  ],
+  serviceKinds: ["image"],
+  imageConfig: { baseUrl: "http://localhost:7860/sdapi/v1/txt2img" },
+};
diff --git a/open-sse/providers/registry/searchapi.js b/open-sse/providers/registry/searchapi.js
new file mode 100644
index 0000000..c558ba9
--- /dev/null
+++ b/open-sse/providers/registry/searchapi.js
@@ -0,0 +1,35 @@
+export default {
+  id: "searchapi",
+  alias: "searchapi",
+  display: {
+    name: "SearchAPI",
+    icon: "search",
+    color: "#0EA5A4",
+    textIcon: "SA",
+    website: "https://www.searchapi.io",
+    notice: {
+      apiKeyUrl: "https://www.searchapi.io/dashboard"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "webSearch"
+  ],
+  searchConfig: {
+    baseUrl: "https://www.searchapi.io/api/v1/search",
+    method: "GET",
+    authType: "apikey",
+    authHeader: "api_key",
+    costPerQuery: 0.004,
+    freeMonthlyQuota: 100,
+    searchTypes: [
+      "web",
+      "news"
+    ],
+    defaultMaxResults: 5,
+    maxMaxResults: 100,
+    timeoutMs: 10000,
+    cacheTTLMs: 300000
+  }
+};
diff --git a/open-sse/providers/registry/searxng.js b/open-sse/providers/registry/searxng.js
new file mode 100644
index 0000000..bfbe4fd
--- /dev/null
+++ b/open-sse/providers/registry/searxng.js
@@ -0,0 +1,35 @@
+import { SEARXNG_URL } from "../../config/runtimeConfig.js";
+
+export default {
+  id: "searxng",
+  alias: "searxng",
+  display: {
+    name: "SearXNG",
+    icon: "saved_search",
+    color: "#3B82F6",
+    textIcon: "SX",
+    website: "https://docs.searxng.org"
+  },
+  category: "freeTier",
+  authType: "none",
+  serviceKinds: [
+    "webSearch"
+  ],
+  noAuth: true,
+  searchConfig: {
+    baseUrl: SEARXNG_URL,
+    method: "GET",
+    authType: "none",
+    authHeader: "none",
+    costPerQuery: 0,
+    freeMonthlyQuota: 999999,
+    searchTypes: [
+      "web",
+      "news"
+    ],
+    defaultMaxResults: 5,
+    maxMaxResults: 50,
+    timeoutMs: 10000,
+    cacheTTLMs: 180000
+  }
+};
diff --git a/open-sse/providers/registry/serper.js b/open-sse/providers/registry/serper.js
new file mode 100644
index 0000000..b98d5af
--- /dev/null
+++ b/open-sse/providers/registry/serper.js
@@ -0,0 +1,35 @@
+export default {
+  id: "serper",
+  alias: "serper",
+  display: {
+    name: "Serper",
+    icon: "search",
+    color: "#4F46E5",
+    textIcon: "SP",
+    website: "https://serper.dev",
+    notice: {
+      apiKeyUrl: "https://serper.dev/api-key"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "webSearch"
+  ],
+  searchConfig: {
+    baseUrl: "https://google.serper.dev",
+    method: "POST",
+    authType: "apikey",
+    authHeader: "x-api-key",
+    costPerQuery: 0.001,
+    freeMonthlyQuota: 2500,
+    searchTypes: [
+      "web",
+      "news"
+    ],
+    defaultMaxResults: 5,
+    maxMaxResults: 100,
+    timeoutMs: 10000,
+    cacheTTLMs: 300000
+  }
+};
diff --git a/open-sse/providers/registry/siliconflow.js b/open-sse/providers/registry/siliconflow.js
new file mode 100644
index 0000000..902cd81
--- /dev/null
+++ b/open-sse/providers/registry/siliconflow.js
@@ -0,0 +1,39 @@
+export default {
+  id: "siliconflow",
+  priority: 250,
+  alias: "siliconflow",
+  display: {
+    name: "SiliconFlow",
+    icon: "cloud_queue",
+    color: "#5B6EF5",
+    textIcon: "SF",
+    website: "https://cloud.siliconflow.com",
+    notice: {
+      apiKeyUrl: "https://cloud.siliconflow.com/account/ak",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.siliconflow.com/v1/chat/completions",
+    validateUrl: "https://api.siliconflow.com/v1/models",
+    thinkingFormat: "openai",
+  },
+  models: [
+    { id: "deepseek-ai/DeepSeek-V4-Pro", name: "DeepSeek V4 Pro" },
+    { id: "deepseek-ai/DeepSeek-V4-Flash", name: "DeepSeek V4 Flash" },
+    { id: "deepseek-ai/DeepSeek-V3.2", name: "DeepSeek V3.2" },
+    { id: "deepseek-ai/DeepSeek-V3.2-Exp", name: "DeepSeek V3.2 Exp" },
+    { id: "deepseek-ai/DeepSeek-V3.1", name: "DeepSeek V3.1" },
+    { id: "deepseek-ai/DeepSeek-V3.1-Terminus", name: "DeepSeek V3.1 Terminus" },
+    { id: "deepseek-ai/DeepSeek-R1", name: "DeepSeek R1" },
+    { id: "Qwen/Qwen3.5-397B-A17B", name: "Qwen 3.5 397B A17B" },
+    { id: "Qwen/Qwen3.5-122B-A10B", name: "Qwen 3.5 122B A10B" },
+    { id: "zai-org/GLM-5.1", name: "GLM 5.1" },
+    { id: "zai-org/GLM-5", name: "GLM 5" },
+    { id: "moonshotai/Kimi-K2.6", name: "Kimi K2.6" },
+    { id: "moonshotai/Kimi-K2.5", name: "Kimi K2.5" },
+    { id: "openai/gpt-oss-120b", name: "GPT OSS 120B" },
+    { id: "MiniMaxAI/MiniMax-M2.5", name: "MiniMax M2.5" },
+    { id: "inclusionAI/Ling-flash-2.0", name: "Ling Flash 2.0" },
+  ],
+};
diff --git a/open-sse/providers/registry/stability-ai.js b/open-sse/providers/registry/stability-ai.js
new file mode 100644
index 0000000..7b0368f
--- /dev/null
+++ b/open-sse/providers/registry/stability-ai.js
@@ -0,0 +1,31 @@
+export default {
+  id: "stability-ai",
+  priority: 60,
+  alias: "stability-ai",
+  aliases: [
+    "stability",
+  ],
+  uiAlias: "stability",
+  display: {
+    name: "Stability AI",
+    icon: "image",
+    color: "#8B5CF6",
+    textIcon: "SA",
+    website: "https://stability.ai",
+    notice: {
+      apiKeyUrl: "https://platform.stability.ai/account/keys",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: null,
+  models: [
+    { id: "stable-image-ultra", name: "Stable Image Ultra", params: ["size"], kind: "image" },
+    { id: "stable-image-core", name: "Stable Image Core", params: ["size","style"], kind: "image" },
+    { id: "sd3.5-large", name: "Stable Diffusion 3.5 Large", params: ["size"], kind: "image" },
+    { id: "sd3.5-large-turbo", name: "Stable Diffusion 3.5 Large Turbo", params: ["size"], kind: "image" },
+    { id: "sd3.5-medium", name: "Stable Diffusion 3.5 Medium", params: ["size"], kind: "image" },
+  ],
+  serviceKinds: ["image"],
+  imageConfig: { baseUrl: "https://api.stability.ai/v2beta/stable-image/generate" },
+};
diff --git a/open-sse/providers/registry/tavily.js b/open-sse/providers/registry/tavily.js
new file mode 100644
index 0000000..4386c97
--- /dev/null
+++ b/open-sse/providers/registry/tavily.js
@@ -0,0 +1,50 @@
+export default {
+  id: "tavily",
+  alias: "tavily",
+  display: {
+    name: "Tavily",
+    icon: "search",
+    color: "#5B21B6",
+    textIcon: "TV",
+    website: "https://tavily.com",
+    notice: {
+      apiKeyUrl: "https://app.tavily.com/home"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "webSearch",
+    "webFetch"
+  ],
+  searchConfig: {
+    baseUrl: "https://api.tavily.com/search",
+    method: "POST",
+    authType: "apikey",
+    authHeader: "bearer",
+    costPerQuery: 0.008,
+    freeMonthlyQuota: 1000,
+    searchTypes: [
+      "web",
+      "news"
+    ],
+    defaultMaxResults: 5,
+    maxMaxResults: 20,
+    timeoutMs: 10000,
+    cacheTTLMs: 300000
+  },
+  fetchConfig: {
+    baseUrl: "https://api.tavily.com/extract",
+    method: "POST",
+    authType: "apikey",
+    authHeader: "bearer",
+    costPerQuery: 0.008,
+    freeMonthlyQuota: 1000,
+    formats: [
+      "markdown",
+      "text"
+    ],
+    maxCharacters: 100000,
+    timeoutMs: 15000
+  }
+};
diff --git a/open-sse/providers/registry/together.js b/open-sse/providers/registry/together.js
new file mode 100644
index 0000000..85b06f6
--- /dev/null
+++ b/open-sse/providers/registry/together.js
@@ -0,0 +1,31 @@
+export default {
+  id: "together",
+  priority: 60,
+  alias: "together",
+  display: {
+    name: "Together AI",
+    icon: "group_work",
+    color: "#0F6FFF",
+    textIcon: "TG",
+    website: "https://www.together.ai",
+    notice: {
+      apiKeyUrl: "https://api.together.xyz/settings/api-keys",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: {
+    baseUrl: "https://api.together.xyz/v1/chat/completions",
+    validateUrl: "https://api.together.xyz/v1/models",
+  },
+  models: [
+    { id: "meta-llama/Llama-3.3-70B-Instruct-Turbo", name: "Llama 3.3 70B Turbo" },
+    { id: "deepseek-ai/DeepSeek-R1", name: "DeepSeek R1" },
+    { id: "Qwen/Qwen3-235B-A22B", name: "Qwen3 235B" },
+    { id: "meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8", name: "Llama 4 Maverick" },
+    { id: "BAAI/bge-large-en-v1.5", name: "BGE Large EN v1.5", kind: "embedding" },
+    { id: "togethercomputer/m2-bert-80M-8k-retrieval", name: "M2 BERT 80M 8K", kind: "embedding" },
+  ],
+  serviceKinds: ["llm", "embedding"],
+  embeddingConfig: { baseUrl: "https://api.together.xyz/v1/embeddings" },
+};
diff --git a/open-sse/providers/registry/topaz.js b/open-sse/providers/registry/topaz.js
new file mode 100644
index 0000000..1a4bb7a
--- /dev/null
+++ b/open-sse/providers/registry/topaz.js
@@ -0,0 +1,19 @@
+export default {
+  id: "topaz",
+  alias: "topaz",
+  display: {
+    name: "Topaz",
+    icon: "image",
+    color: "#059669",
+    textIcon: "TP",
+    website: "https://topazlabs.com",
+    notice: {
+      apiKeyUrl: "https://topazlabs.com/account"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "image"
+  ]
+};
diff --git a/open-sse/providers/registry/tortoise.js b/open-sse/providers/registry/tortoise.js
new file mode 100644
index 0000000..4d3b87c
--- /dev/null
+++ b/open-sse/providers/registry/tortoise.js
@@ -0,0 +1,30 @@
+export default {
+  id: "tortoise",
+  alias: "tortoise",
+  display: {
+    name: "Tortoise TTS",
+    icon: "record_voice_over",
+    color: "#7C3AED",
+    textIcon: "TT",
+    website: "https://github.com/neonbjb/tortoise-tts"
+  },
+  category: "freeTier",
+  authType: "none",
+  serviceKinds: [
+    "tts"
+  ],
+  noAuth: true,
+  ttsConfig: {
+    baseUrl: "http://localhost:5000/api/tts",
+    authType: "none",
+    authHeader: "none",
+    format: "tortoise",
+    models: [
+      {
+        id: "tortoise-v2",
+        name: "Tortoise v2"
+      }
+    ]
+  },
+  hidden: true
+};
diff --git a/open-sse/providers/registry/venice.js b/open-sse/providers/registry/venice.js
new file mode 100644
index 0000000..cd68646
--- /dev/null
+++ b/open-sse/providers/registry/venice.js
@@ -0,0 +1,56 @@
+export default {
+  id: "venice",
+  priority: 115,
+  alias: "venice",
+  aliases: [
+    "vn",
+  ],
+  uiAlias: "venice",
+  display: {
+    name: "Venice AI",
+    icon: "shield",
+    color: "#DC2626",
+    textIcon: "VE",
+    website: "https://venice.ai",
+    notice: {
+      text: "OpenAI-compatible. Private inference + uncensored models (Venice Uncensored, GLM, Qwen, DeepSeek, Llama).",
+      apiKeyUrl: "https://venice.ai/settings/api",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.venice.ai/api/v1/chat/completions",
+    validateUrl: "https://api.venice.ai/api/v1/models",
+    thinkingFormat: "openai",
+  },
+  // Curated seed; the full live catalogue (90+ text models) is fetched via
+  // modelsFetcher and any other id is accepted via passthroughModels.
+  models: [
+    { id: "venice-uncensored-1-2", name: "Venice Uncensored 1.2" },
+    { id: "zai-org-glm-5", name: "GLM-5" },
+    { id: "qwen3-235b-a22b-instruct-2507", name: "Qwen3 235B A22B Instruct" },
+    { id: "qwen3-coder-480b-a35b-instruct-turbo", name: "Qwen3 Coder 480B A35B Turbo" },
+    { id: "qwen3-vl-235b-a22b", name: "Qwen3 VL 235B A22B" },
+    { id: "deepseek-v4-pro", name: "DeepSeek V4 Pro" },
+    { id: "llama-3.3-70b", name: "Llama 3.3 70B" },
+    { id: "hermes-3-llama-3.1-405b", name: "Hermes 3 Llama 3.1 405B" },
+    { id: "mistral-small-3-2-24b-instruct", name: "Mistral Small 3.2 24B" },
+    { id: "text-embedding-3-large", name: "Text Embedding 3 Large", kind: "embedding" },
+    { id: "text-embedding-bge-m3", name: "BGE-M3 Embedding", kind: "embedding" },
+    { id: "text-embedding-qwen3-8b", name: "Qwen3 8B Embedding", kind: "embedding" },
+    { id: "venice-sd35", name: "Venice SD3.5", params: ["n", "size"], kind: "image" },
+    { id: "flux-2-pro", name: "FLUX.2 Pro", params: ["n", "size"], kind: "image" },
+    { id: "gpt-image-2", name: "GPT Image 2 (via Venice)", params: ["n", "size", "quality"], kind: "image" },
+  ],
+  serviceKinds: ["llm", "embedding", "image"],
+  embeddingConfig: {
+    baseUrl: "https://api.venice.ai/api/v1/embeddings",
+    authType: "apikey",
+    authHeader: "bearer",
+  },
+  imageConfig: {
+    baseUrl: "https://api.venice.ai/api/v1/images/generations",
+  },
+  modelsFetcher: { url: "https://api.venice.ai/api/v1/models", type: "openai" },
+  passthroughModels: true,
+};
diff --git a/open-sse/providers/registry/vercel-ai-gateway.js b/open-sse/providers/registry/vercel-ai-gateway.js
new file mode 100644
index 0000000..798d94c
--- /dev/null
+++ b/open-sse/providers/registry/vercel-ai-gateway.js
@@ -0,0 +1,41 @@
+export default {
+  id: "vercel-ai-gateway",
+  priority: 160,
+  alias: "vercel-ai-gateway",
+  aliases: [
+    "vercel",
+  ],
+  uiAlias: "vercel",
+  display: {
+    name: "Vercel AI Gateway",
+    icon: "deployed_code",
+    color: "#111827",
+    textIcon: "VG",
+    website: "https://vercel.com/ai-gateway",
+    notice: {
+      text: "Unified OpenAI-compatible endpoint from Vercel. Use your AI Gateway API key, then pick models with provider/model IDs like anthropic/claude-sonnet-4.6 or openai/gpt-5.4.",
+      apiKeyUrl: "https://vercel.com/dashboard/~/ai-gateway",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://ai-gateway.vercel.sh/v1/chat/completions",
+    thinkingFormat: "openai",
+    retry: {
+      "429": 2,
+    },
+    usage: {
+      url: "https://ai-gateway.vercel.sh/v1/credits",
+    },
+  },
+  serviceKinds: ["llm","embedding","image","imageToText","webSearch"],
+  embeddingConfig: { baseUrl: "https://ai-gateway.vercel.sh/v1/embeddings" },
+  imageConfig: { baseUrl: "https://ai-gateway.vercel.sh/v1/images/generations" },
+  searchViaChat: { defaultModel: "openai/gpt-4o-mini", pricingUrl: "https://vercel.com/docs/ai-gateway/pricing" },
+  modelsFetcher: { url: "https://ai-gateway.vercel.sh/v1/models", type: "openai" },
+  passthroughModels: true,
+  features: {
+    usage: true,
+    usageApikey: true,
+  },
+};
diff --git a/open-sse/providers/registry/vertex-partner.js b/open-sse/providers/registry/vertex-partner.js
new file mode 100644
index 0000000..6e49494
--- /dev/null
+++ b/open-sse/providers/registry/vertex-partner.js
@@ -0,0 +1,29 @@
+export default {
+  id: "vertex-partner",
+  priority: 260,
+  alias: "vertex-partner",
+  aliases: [
+    "vxp",
+  ],
+  uiAlias: "vxp",
+  display: {
+    name: "Vertex Partner",
+    icon: "cloud",
+    color: "#34A853",
+    textIcon: "VP",
+    website: "https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models",
+    notice: {
+      apiKeyUrl: "https://console.cloud.google.com/iam-admin/serviceaccounts",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://aiplatform.googleapis.com",
+  },
+  models: [
+    { id: "deepseek-ai/deepseek-v3.2-maas", name: "DeepSeek V3.2 (Vertex)" },
+    { id: "qwen/qwen3-next-80b-a3b-thinking-maas", name: "Qwen3 Next 80B Thinking (Vertex)" },
+    { id: "qwen/qwen3-next-80b-a3b-instruct-maas", name: "Qwen3 Next 80B Instruct (Vertex)" },
+    { id: "zai-org/glm-5-maas", name: "GLM-5 (Vertex)" },
+  ],
+};
diff --git a/open-sse/providers/registry/vertex.js b/open-sse/providers/registry/vertex.js
new file mode 100644
index 0000000..b8765de
--- /dev/null
+++ b/open-sse/providers/registry/vertex.js
@@ -0,0 +1,32 @@
+export default {
+  id: "vertex",
+  priority: 40,
+  alias: "vertex",
+  aliases: [
+    "vx",
+  ],
+  uiAlias: "vx",
+  display: {
+    name: "Vertex AI",
+    icon: "cloud",
+    color: "#4285F4",
+    textIcon: "VX",
+    website: "https://cloud.google.com/vertex-ai",
+    notice: {
+      text: "New Google Cloud accounts get $300 free credits. Requires GCP project + Service Account with Vertex AI API enabled.",
+      apiKeyUrl: "https://console.cloud.google.com/iam-admin/serviceaccounts",
+    },
+  },
+  category: "freeTier",
+  transport: {
+    baseUrl: "https://aiplatform.googleapis.com",
+    format: "vertex",
+  },
+  models: [
+    { id: "gemini-3.1-pro-preview", name: "Gemini 3.1 Pro Preview" },
+    { id: "gemini-3.1-flash-lite-preview", name: "Gemini 3.1 Flash Lite Preview" },
+    { id: "gemini-3-flash-preview", name: "Gemini 3 Flash Preview" },
+    { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
+  ],
+  serviceKinds: ["llm","imageToText"],
+};
diff --git a/open-sse/providers/registry/volcengine-ark.js b/open-sse/providers/registry/volcengine-ark.js
new file mode 100644
index 0000000..16ad8b8
--- /dev/null
+++ b/open-sse/providers/registry/volcengine-ark.js
@@ -0,0 +1,35 @@
+export default {
+  id: "volcengine-ark",
+  priority: 270,
+  alias: "volcengine-ark",
+  aliases: [
+    "ark",
+  ],
+  uiAlias: "ark",
+  display: {
+    name: "Volcengine Ark",
+    icon: "cloud",
+    color: "#1677FF",
+    textIcon: "ARK",
+    website: "https://ark.cn-beijing.volces.com",
+    notice: {
+      apiKeyUrl: "https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions",
+    headers: {},
+  },
+  models: [
+    { id: "Doubao-Seed-2.0-Code", name: "Doubao-Seed-2.0-Code" },
+    { id: "Doubao-Seed-2.0-pro", name: "Doubao-Seed-2.0-pro" },
+    { id: "Doubao-Seed-2.0-lite", name: "Doubao-Seed-2.0-lite" },
+    { id: "Doubao-Seed-Code", name: "Doubao-Seed-Code" },
+    { id: "DeepSeek-V4-Flash", name: "DeepSeek-V4-Flash" },
+    { id: "DeepSeek-V4-Pro", name: "DeepSeek-V4-Pro" },
+    { id: "GLM-5.1", name: "GLM-5.1" },
+    { id: "MiniMax-M2.7", name: "MiniMax-M2.7" },
+    { id: "Kimi-K2.6", name: "Kimi-K2.6" },
+  ],
+};
diff --git a/open-sse/providers/registry/voyage-ai.js b/open-sse/providers/registry/voyage-ai.js
new file mode 100644
index 0000000..b27a6d4
--- /dev/null
+++ b/open-sse/providers/registry/voyage-ai.js
@@ -0,0 +1,30 @@
+export default {
+  id: "voyage-ai",
+  priority: 40,
+  alias: "voyage-ai",
+  uiAlias: "voyage",
+  display: {
+    name: "Voyage AI",
+    icon: "data_array",
+    color: "#0EA5E9",
+    textIcon: "VG",
+    website: "https://www.voyageai.com",
+    notice: {
+      apiKeyUrl: "https://dash.voyageai.com/api-keys",
+    },
+  },
+  category: "apikey",
+  authType: "apikey",
+  transport: null,
+  models: [
+    { id: "voyage-3-large", name: "Voyage 3 Large", kind: "embedding" },
+    { id: "voyage-3.5", name: "Voyage 3.5", kind: "embedding" },
+    { id: "voyage-3.5-lite", name: "Voyage 3.5 Lite", kind: "embedding" },
+    { id: "voyage-code-3", name: "Voyage Code 3", kind: "embedding" },
+    { id: "voyage-finance-2", name: "Voyage Finance 2", kind: "embedding" },
+    { id: "voyage-law-2", name: "Voyage Law 2", kind: "embedding" },
+    { id: "voyage-multilingual-2", name: "Voyage Multilingual 2", kind: "embedding" },
+  ],
+  serviceKinds: ["embedding"],
+  embeddingConfig: { baseUrl: "https://api.voyageai.com/v1/embeddings" },
+};
diff --git a/open-sse/providers/registry/xai.js b/open-sse/providers/registry/xai.js
new file mode 100644
index 0000000..efe13bd
--- /dev/null
+++ b/open-sse/providers/registry/xai.js
@@ -0,0 +1,43 @@
+export default {
+  id: "xai",
+  priority: 280,
+  alias: "xai",
+  display: {
+    name: "xAI (Grok)",
+    icon: "auto_awesome",
+    color: "#1DA1F2",
+    textIcon: "XA",
+    website: "https://x.ai",
+    notice: {
+      apiKeyUrl: "https://console.x.ai",
+    },
+  },
+  category: "oauth",
+  authModes: [
+    "oauth",
+    "apikey",
+  ],
+  hasOAuth: true,
+  transport: {
+    baseUrl: "https://api.x.ai/v1/chat/completions",
+    validateUrl: "https://api.x.ai/v1/models",
+    responsesUrl: "https://api.x.ai/v1/responses",
+    clientId: "b1a00492-073a-47ea-816f-4c329264a828",
+    tokenUrl: "https://auth.x.ai/oauth2/token",
+    refreshUrl: "https://auth.x.ai/oauth2/token",
+  },
+  models: [
+    { id: "grok-4", name: "Grok 4" },
+    { id: "grok-4-fast-reasoning", name: "Grok 4 Fast Reasoning" },
+    { id: "grok-code-fast-1", name: "Grok Code Fast" },
+    { id: "grok-3", name: "Grok 3" },
+    { id: "grok-2-image-1212", name: "Grok 2 Image", params: ["n","response_format"], kind: "image" },
+  ],
+  serviceKinds: ["llm","imageToText","webSearch","image"],
+  imageConfig: { baseUrl: "https://api.x.ai/v1/images/generations", bodyFields: ["model","prompt","n","response_format"] },
+  searchViaChat: {
+    defaultModel: "grok-4.20-reasoning",
+    endpoint: "https://api.x.ai/v1/responses",
+    pricingUrl: "https://x.ai/api#pricing",
+  },
+};
diff --git a/open-sse/providers/registry/xiaomi-mimo.js b/open-sse/providers/registry/xiaomi-mimo.js
new file mode 100644
index 0000000..fcef7af
--- /dev/null
+++ b/open-sse/providers/registry/xiaomi-mimo.js
@@ -0,0 +1,46 @@
+import { CLAUDE_API_HEADERS } from "../shared.js";
+
+export default {
+  id: "xiaomi-mimo",
+  priority: 290,
+  alias: "xiaomi-mimo",
+  aliases: [
+    "mimo",
+  ],
+  uiAlias: "mimo",
+  display: {
+    name: "Xiaomi MiMo",
+    icon: "smart_toy",
+    color: "#FF6900",
+    textIcon: "XM",
+    website: "https://xiaomimimo.com",
+    notice: {
+      apiKeyUrl: "https://xiaomimimo.com",
+    },
+  },
+  category: "apikey",
+  transport: {
+    baseUrl: "https://api.xiaomimimo.com/v1/chat/completions",
+    validateUrl: "https://api.xiaomimimo.com/v1/models",
+  },
+  // Multi-endpoint: pick the transport matching client sourceFormat to skip translation.
+  transports: [
+    {
+      format: "openai",
+      baseUrl: "https://api.xiaomimimo.com/v1/chat/completions",
+      auth: { combined: true, header: "Authorization", scheme: "bearer" },
+    },
+    {
+      format: "claude",
+      baseUrl: "https://api.xiaomimimo.com/anthropic/v1/messages",
+      headers: { ...CLAUDE_API_HEADERS },
+      auth: { combined: true, header: "x-api-key", scheme: "raw" },
+    },
+  ],
+  models: [
+    { id: "mimo-v2.5-pro", name: "MiMo V2.5 Pro" },
+    { id: "mimo-v2.5", name: "MiMo V2.5" },
+    { id: "mimo-v2-omni", name: "MiMo V2 Omni" },
+    { id: "mimo-v2-flash", name: "MiMo V2 Flash" },
+  ],
+};
diff --git a/open-sse/providers/registry/xiaomi-tokenplan.js b/open-sse/providers/registry/xiaomi-tokenplan.js
new file mode 100644
index 0000000..8503d25
--- /dev/null
+++ b/open-sse/providers/registry/xiaomi-tokenplan.js
@@ -0,0 +1,63 @@
+import { CLAUDE_API_HEADERS } from "../shared.js";
+
+export default {
+  id: "xiaomi-tokenplan",
+  priority: 300,
+  alias: "xiaomi-tokenplan",
+  aliases: [
+    "xmtp",
+  ],
+  uiAlias: "xmtp",
+  display: {
+    name: "Xiaomi MiMo (Token Plan)",
+    icon: "smart_toy",
+    color: "#FF6700",
+    textIcon: "XT",
+    website: "https://mimo.xiaomi.com",
+    notice: {
+      text: "Xiaomi MiMo Token Plan subscription (API key starts with tp-). Token Plan keys are cluster-specific — select the region matching your subscription.",
+      apiKeyUrl: "https://mimo.xiaomi.com",
+    },
+  },
+  category: "apikey",
+  hasProviderSpecificData: true,
+  regions: [
+    { id: "sgp", label: "Singapore (新加坡)" },
+    { id: "cn", label: "China (中国大陆)" },
+    { id: "ams", label: "Amsterdam (阿姆斯特丹)" },
+  ],
+  defaultRegion: "sgp",
+  transport: {
+    baseUrl: "https://token-plan-sgp.xiaomimimo.com/v1/chat/completions",
+    regions: {
+      sgp: "https://token-plan-sgp.xiaomimimo.com/v1",
+      cn: "https://token-plan-cn.xiaomimimo.com/v1",
+      ams: "https://token-plan-ams.xiaomimimo.com/v1",
+    },
+    defaultRegion: "sgp",
+  },
+  // Multi-endpoint: pick the transport matching client sourceFormat to skip translation.
+  // baseUrl omitted — region-dynamic, resolved in the executor's buildUrl.
+  transports: [
+    {
+      format: "openai",
+      auth: { combined: true, header: "Authorization", scheme: "bearer" },
+    },
+    {
+      format: "claude",
+      headers: { ...CLAUDE_API_HEADERS },
+      auth: { combined: true, header: "x-api-key", scheme: "raw" },
+    },
+  ],
+  models: [
+    { id: "mimo-v2.5-pro", name: "MiMo V2.5 Pro" },
+    { id: "mimo-v2.5-pro-claude", name: "MiMo V2.5 Pro (Claude Native)", targetFormat: "claude", upstreamModelId: "mimo-v2.5-pro" },
+    { id: "mimo-v2.5", name: "MiMo V2.5" },
+    { id: "mimo-v2-pro", name: "MiMo V2 Pro" },
+    { id: "mimo-v2-omni", name: "MiMo V2 Omni" },
+    { id: "mimo-v2-tts", name: "MiMo V2 TTS" },
+    { id: "mimo-v2.5-tts", name: "MiMo V2.5 TTS" },
+    { id: "mimo-v2.5-tts-voiceclone", name: "MiMo V2.5 TTS Voice Clone" },
+    { id: "mimo-v2.5-tts-voicedesign", name: "MiMo V2.5 TTS Voice Design" },
+  ],
+};
diff --git a/open-sse/providers/registry/youcom.js b/open-sse/providers/registry/youcom.js
new file mode 100644
index 0000000..d090c63
--- /dev/null
+++ b/open-sse/providers/registry/youcom.js
@@ -0,0 +1,35 @@
+export default {
+  id: "youcom",
+  alias: "youcom",
+  display: {
+    name: "You.com Search",
+    icon: "search",
+    color: "#7C3AED",
+    textIcon: "YC",
+    website: "https://you.com",
+    notice: {
+      apiKeyUrl: "https://api.you.com"
+    }
+  },
+  category: "apikey",
+  authType: "apikey",
+  serviceKinds: [
+    "webSearch"
+  ],
+  searchConfig: {
+    baseUrl: "https://ydc-index.io/v1/search",
+    method: "GET",
+    authType: "apikey",
+    authHeader: "x-api-key",
+    costPerQuery: 0.005,
+    freeMonthlyQuota: 0,
+    searchTypes: [
+      "web",
+      "news"
+    ],
+    defaultMaxResults: 5,
+    maxMaxResults: 100,
+    timeoutMs: 10000,
+    cacheTTLMs: 300000
+  }
+};
diff --git a/open-sse/providers/schema.js b/open-sse/providers/schema.js
new file mode 100644
index 0000000..e8b5ddd
--- /dev/null
+++ b/open-sse/providers/schema.js
@@ -0,0 +1,76 @@
+// Provider transport schema: shared defaults + endpoint defaults + resolver (skeleton, not wired)
+import { DEFAULT_RETRY_CONFIG, FETCH_CONNECT_TIMEOUT_MS } from "../config/runtimeConfig.js";
+
+/**
+ * RegistryEntry shape — full contract for registry/{id}.js. See REGISTRY_TEMPLATE.js for a worked example.
+ * Only `id` + `category` are strictly required; everything else is optional/derived.
+ *
+ * @typedef {Object} RegistryEntry
+ * @property {string}   id            Unique provider id (kebab-case). REQUIRED.
+ * @property {string}  [alias]        Short key for PROVIDER_MODELS (defaults to id).
+ * @property {string[]}[aliases]      Extra lookup tokens resolving to this provider.
+ * @property {string}  [uiAlias]      Token shown in UI badges.
+ * @property {string}   category      "apikey"|"oauth"|"freeTier"|... drives UI grouping. REQUIRED.
+ * @property {string}  [authType]     "apikey"|"oauth" auth hint.
+ * @property {string[]}[authModes]    Allowed auth modes when provider supports both.
+ * @property {boolean} [hasOAuth]     Provider exposes an OAuth flow.
+ * @property {boolean} [noAuth]       Provider needs no credentials (local/free).
+ * @property {Object}  [display]      UI: {name,icon,color,textIcon,website,notice,deprecated,deprecationNotice,kindNotice,mediaPriority}.
+ * @property {Object}  [transport]    Runtime HTTP config (see TransportConfig below). Builds PROVIDERS[id].
+ * @property {Object}  [oauth]        OAuth flow config (see OAuthConfig). Builds PROVIDER_OAUTH[id].
+ * @property {Object}  [media]        Non-LLM services (see MediaConfig). Builds PROVIDER_MEDIA[id].
+ * @property {Array}   [models]       Model list; omit = no model key, [] = explicit empty.
+ * @property {Object}  [features]     Feature flags, e.g. {usage:true}.
+ * @property {Object}  [thinkingConfig] Reasoning UI: {options:[...],defaultMode}.
+ * @property {boolean} [passthroughModels] Forward client model id untouched.
+ *
+ * TransportConfig: { baseUrl, format, headers, auth, forceStream, urlSuffix, quirks, retry, timeoutMs,
+ *   executor, clientId, clientSecret, tokenUrl, refreshUrl, usage, cliVersion, apiClient, regions,
+ *   defaultRegion, modelsFetcher, validateUrl, responsesUrl } — clientId/clientSecret/tokenUrl are
+ *   injected from `oauth` automatically (single source); declare them in `oauth`, not here.
+ *
+ * OAuthConfig: { clientId, authorizeUrl, tokenUrl, deviceCodeUrl, refreshUrl, scope|scopes, redirectUri,
+ *   callbackPath, fixedPort, codeChallengeMethod, extraParams, refresh:{encoding,scope}, refreshLeadMs,
+ *   userInfoUrl }.
+ *
+ * MediaConfig: { serviceKinds:[...], ttsConfig, sttConfig, embeddingConfig, imageConfig,
+ *   searchViaChat:{defaultModel,pricingUrl}, hiddenKinds } — each *Config: {baseUrl,authType,authHeader,
+ *   format,defaultModel,models:[{id,name,dimensions?}]}.
+ */
+
+// Shared transport defaults — provider only overrides fields that differ.
+// NOTE: runtime (index.js buildTransport) only re-applies `format`; the rest documents the contract
+// and feeds the (currently unwired) resolveProvider(). Adding keys here does NOT change PROVIDERS.
+export const PROVIDER_DEFAULTS = {
+  baseUrl: "",
+  format: "openai",
+  headers: {},
+  auth: { header: "Authorization", scheme: "bearer", source: ["accessToken", "apiKey"] },
+  forceStream: false,
+  urlSuffix: "",
+  quirks: {},
+  passthroughModels: false,
+  retry: DEFAULT_RETRY_CONFIG,
+  timeoutMs: FETCH_CONNECT_TIMEOUT_MS,
+  executor: "default"
+};
+
+// Default endpoints per format (provider only overrides what differs)
+export const ENDPOINT_DEFAULTS = {
+  openai: { chat: "/chat/completions", test: "/models", models: "/models" },
+  claude: { chat: "/messages", test: "/models", countTokens: "/messages/count_tokens" },
+  gemini: { chat: "/{model}:streamGenerateContent", models: "/models", test: "/models" }
+};
+
+// Deep-merge a provider entry over PROVIDER_DEFAULTS (defensive for missing transport)
+export function resolveProvider(entry) {
+  const transport = (entry && entry.transport) || {};
+  return {
+    ...PROVIDER_DEFAULTS,
+    ...transport,
+    headers: { ...PROVIDER_DEFAULTS.headers, ...transport.headers },
+    auth: { ...PROVIDER_DEFAULTS.auth, ...transport.auth },
+    quirks: { ...PROVIDER_DEFAULTS.quirks, ...transport.quirks },
+    retry: { ...PROVIDER_DEFAULTS.retry, ...transport.retry }
+  };
+}
diff --git a/open-sse/providers/shared.js b/open-sse/providers/shared.js
new file mode 100644
index 0000000..6f6a2c2
--- /dev/null
+++ b/open-sse/providers/shared.js
@@ -0,0 +1,74 @@
+import { platform, arch } from "os";
+
+// === OS/Arch helpers (Stainless fingerprint) ===
+export function mapStainlessOs() {
+  switch (platform()) {
+    case "darwin": return "MacOS";
+    case "win32": return "Windows";
+    case "linux": return "Linux";
+    case "freebsd": return "FreeBSD";
+    default: return `Other::${platform()}`;
+  }
+}
+
+export function mapStainlessArch() {
+  switch (arch()) {
+    case "x64": return "x64";
+    case "arm64": return "arm64";
+    case "ia32": return "x86";
+    default: return `other::${arch()}`;
+  }
+}
+
+// Anthropic API version (single source — reused across claude-format providers/executors)
+export const ANTHROPIC_API_VERSION = "2023-06-01";
+
+// Shared Claude-compatible API headers (reused across claude-format providers)
+export const CLAUDE_API_HEADERS = {
+  "Anthropic-Version": ANTHROPIC_API_VERSION,
+  "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+};
+
+// Full Claude CLI fingerprint — required by providers that gate on client identity (e.g. agentrouter)
+export const CLAUDE_CLI_SPOOF_HEADERS = {
+  "Anthropic-Version": ANTHROPIC_API_VERSION,
+  "Anthropic-Beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28",
+  "Anthropic-Dangerous-Direct-Browser-Access": "true",
+  "User-Agent": "claude-cli/2.1.92 (external, sdk-cli)",
+  "X-App": "cli",
+  "X-Stainless-Helper-Method": "stream",
+  "X-Stainless-Retry-Count": "0",
+  "X-Stainless-Runtime-Version": "v24.14.0",
+  "X-Stainless-Package-Version": "0.80.0",
+  "X-Stainless-Runtime": "node",
+  "X-Stainless-Lang": "js",
+  "X-Stainless-Arch": mapStainlessArch(),
+  "X-Stainless-Os": mapStainlessOs(),
+  "X-Stainless-Timeout": "600"
+};
+
+// Shared baseUrls
+export const KIMI_CODING_BASE_URL = "https://api.kimi.com/coding/v1/messages";
+
+// Default base for dynamic compat providers (openai-compatible-* / anthropic-compatible-*) when user gives no baseUrl
+export const OPENAI_COMPAT_BASE = "https://api.openai.com/v1";
+export const ANTHROPIC_COMPAT_BASE = "https://api.anthropic.com/v1";
+
+// Official Antigravity IDE Desktop 2.1.1 fingerprint captured from macOS arm64.
+// Keep this static even when 9router runs on Linux: the provider profile is
+// intentionally matching the IDE client, not the server host.
+export const ANTIGRAVITY_IDE_VERSION = "2.1.1";
+export const ANTIGRAVITY_IDE_BASE_URL = "https://cloudcode-pa.googleapis.com";
+export const ANTIGRAVITY_IDE_USER_AGENT = `antigravity/ide/${ANTIGRAVITY_IDE_VERSION} darwin/arm64`;
+
+// Antigravity OAuth client credentials (public CLI client — duplicated in usage.js + src/lib/oauth)
+export const ANTIGRAVITY_OAUTH_CLIENT = {
+  clientId: "1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com",
+  clientSecret: "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"
+};
+
+// Gemini (Google) OAuth client credentials (public CLI client — shared by gemini, gemini-cli, src/lib/oauth)
+export const GOOGLE_OAUTH_CLIENT = {
+  clientId: "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com",
+  clientSecret: "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"
+};
diff --git a/open-sse/providers/thinkingLevels.js b/open-sse/providers/thinkingLevels.js
new file mode 100644
index 0000000..ba998ee
--- /dev/null
+++ b/open-sse/providers/thinkingLevels.js
@@ -0,0 +1,48 @@
+// Resolve valid thinking levels per model — drives UI level picker (suffix "model(level)").
+// Reuses capabilities.js (thinkingFormat/canDisable) so this file only maps format→levels (DRY).
+import { getCapabilitiesForModel } from "./capabilities.js";
+import { matchPattern } from "./pricing.js";
+
+// Shared level sets (deduped) — verified against provider docs + wire in thinkingUnified.applyFormat.
+const L = {
+  base: ["none", "low", "medium", "high"],                          // qwen, step, hunyuan, gemini-budget
+  onOff: ["none", "thinking"],                                      // zai (binary), minimax (adaptive)
+  openai: ["none", "minimal", "low", "medium", "high", "xhigh"],    // GPT-5.x / o-series (no "max")
+  levelMax: ["none", "low", "medium", "high", "max"],               // claude-adaptive, kimi
+  budgetX: ["none", "low", "medium", "high", "xhigh", "max"],       // claude-budget
+  gemini: ["minimal", "low", "medium", "high"],                     // gemini-3 thinkingLevel (no disable)
+  hiMax: ["none", "high", "max"],                                   // deepseek (low/med→high, xhigh→max)
+};
+
+// thinkingFormat → valid selectable levels (source of truth for UI options).
+const FORMAT_LEVELS = {
+  openai: L.openai,
+  "claude-adaptive": L.levelMax,
+  "claude-budget": L.budgetX,
+  "gemini-level": L.gemini,
+  "gemini-budget": L.base,
+  zai: L.onOff,
+  qwen: L.base,
+  kimi: L.levelMax,
+  deepseek: L.hiMax,
+  minimax: L.onOff,
+  hunyuan: L.base,
+  step: L.base,
+};
+
+// Model-name pattern overrides (glob, first match wins) — more precise than format default.
+const PATTERN_THINKING = [
+  // gpt-5.6-sol accepts max (maps to xhigh on wire); live probe rejected ultra.
+  { pattern: "*gpt-5.6-sol*", levels: ["none", "minimal", "low", "medium", "high", "xhigh", "max"] },
+  { pattern: "*codex*", levels: ["low", "medium", "high", "xhigh"] }, // codex cannot disable thinking
+];
+
+// Returns valid thinking levels for a model, or null when the model has no reasoning.
+export function getThinkingLevels(provider, model) {
+  const caps = getCapabilitiesForModel(provider, model);
+  if (!caps.reasoning) return null;
+  const hit = PATTERN_THINKING.find((p) => matchPattern(p.pattern, model));
+  let levels = hit?.levels || FORMAT_LEVELS[caps.thinkingFormat] || L.base;
+  if (caps.thinkingCanDisable === false) levels = levels.filter((l) => l !== "none");
+  return levels;
+}
diff --git a/open-sse/rtk/applyFilter.js b/open-sse/rtk/applyFilter.js
new file mode 100644
index 0000000..9de34ac
--- /dev/null
+++ b/open-sse/rtk/applyFilter.js
@@ -0,0 +1,15 @@
+// Port of apply_filter (rtk/src/cmds/system/pipe_cmd.rs) — catch_unwind equivalent
+// On panic/error: passthrough raw output + warn to stderr
+export function safeApply(fn, text) {
+  if (typeof fn !== "function") return text;
+  try {
+    const out = fn(text);
+    if (typeof out !== "string") return text;
+    return out;
+  } catch (err) {
+    // Rust: eprintln!("[rtk] warning: filter panicked — passing through raw output")
+    const name = fn.filterName || fn.name || "anonymous";
+    console.warn(`[rtk] warning: filter '${name}' panicked — passing through raw output: ${err?.message || err}`);
+    return text;
+  }
+}
diff --git a/open-sse/rtk/autodetect.js b/open-sse/rtk/autodetect.js
new file mode 100644
index 0000000..8199203
--- /dev/null
+++ b/open-sse/rtk/autodetect.js
@@ -0,0 +1,119 @@
+// Port of auto_detect_filter (rtk/src/cmds/system/pipe_cmd.rs:132-188) + JS extras
+// Detection order: git-log → git-diff → git-status → build-output → grep → find → tree → ls → search-list
+//                  → read-numbered → dedup-log → smart-truncate → null
+import { DETECT_WINDOW, READ_NUMBERED_MIN_HIT_RATIO, SMART_TRUNCATE_MIN_LINES } from "./constants.js";
+import { gitDiff } from "./filters/gitDiff.js";
+import { gitStatus } from "./filters/gitStatus.js";
+import { gitLog } from "./filters/gitLog.js";
+import { buildOutput } from "./filters/buildOutput.js";
+import { grep } from "./filters/grep.js";
+import { find } from "./filters/find.js";
+import { dedupLog } from "./filters/dedupLog.js";
+import { ls } from "./filters/ls.js";
+import { tree } from "./filters/tree.js";
+import { smartTruncate } from "./filters/smartTruncate.js";
+import { readNumbered, READ_NUMBERED_LINE_RE } from "./filters/readNumbered.js";
+import { searchList, SEARCH_LIST_HEADER_RE } from "./filters/searchList.js";
+
+const RE_GIT_DIFF = /^diff --git /m;
+const RE_GIT_DIFF_HUNK = /^@@ /m;
+const RE_GIT_STATUS = /^On branch |^nothing to commit|^Changes (not |to be )|^Untracked files:/m;
+const RE_GIT_LOG = /^[*|/\\ ]*commit [0-9a-f]{7,40}$/m;
+const RE_PORCELAIN = /^[ MADRCU?!][ MADRCU?!] \S/m;
+const RE_BUILD_OUTPUT = /^(npm (warn|error|ERR!)|yarn (warn|error)|\s*Compiling\s+\S+|\s*Downloading\s+\S+|added \d+ package|\[ERROR\]|BUILD (SUCCESS|FAILED)|\s*Finished\s+|Successfully (installed|built)|ERROR:)/im;
+const RE_TREE_GLYPH = /[├└]──|│  /;
+const RE_LS_ROW = /^[-dlbcps][rwx-]{9}/m;
+const RE_LS_TOTAL = /^total \d+$/m;
+
+export function autoDetectFilter(text) {
+  // Rust: floor_char_boundary to avoid UTF-8 split — JS .slice() by char is safe
+  const head = text.length > DETECT_WINDOW ? text.slice(0, DETECT_WINDOW) : text;
+
+  if (RE_GIT_LOG.test(head)) return gitLog;
+  if (RE_GIT_DIFF.test(head) || RE_GIT_DIFF_HUNK.test(head)) return gitDiff;
+  if (RE_GIT_STATUS.test(head)) return gitStatus;
+
+  // Build output BEFORE porcelain check: prevents cargo "Compiling" misdetection as git-status
+  if (RE_BUILD_OUTPUT.test(head)) return buildOutput;
+
+  if (isMostlyPorcelain(head)) return gitStatus;
+
+  const lines = head.split("\n");
+  const nonEmpty = lines.filter(l => l.trim().length > 0);
+
+  // Rust grep rule: first 5 non-empty lines, ANY matches "file:number:content"
+  const first5 = nonEmpty.slice(0, 5);
+  if (first5.some(isGrepLine)) return grep;
+
+  // Rust find rule: ALL non-empty lines path-like (no ':'), >=3 lines
+  if (nonEmpty.length >= 3 && nonEmpty.every(isPathLike)) return find;
+
+  // Tree: contains box-drawing glyphs typical of `tree` command
+  if (RE_TREE_GLYPH.test(head)) return tree;
+
+  // ls -la: has "total N" header or >=3 rows starting with perms string
+  if (RE_LS_TOTAL.test(head) || countMatches(head, RE_LS_ROW) >= 3) return ls;
+
+  // Cursor Glob search list header
+  if (SEARCH_LIST_HEADER_RE.test(head)) return searchList;
+
+  // Line-numbered file dump ("  N|content") — fire only if many lines match
+  if (lines.length >= SMART_TRUNCATE_MIN_LINES && isLineNumbered(lines)) {
+    return readNumbered;
+  }
+
+  // Fallback: dedupLog for generic multi-line noise with duplicates
+  if (nonEmpty.length >= 5) return dedupLog;
+
+  // Last resort: big blob with no structure — smart truncate
+  if (text.split("\n").length >= SMART_TRUNCATE_MIN_LINES) return smartTruncate;
+
+  return null;
+}
+
+function isGrepLine(line) {
+  // Rust: splitn(3, ':') → parts.len()==3 && parts[1].parse::<usize>().is_ok()
+  const first = line.indexOf(":");
+  if (first === -1) return false;
+  const second = line.indexOf(":", first + 1);
+  if (second === -1) return false;
+  const lineno = line.slice(first + 1, second);
+  return /^\d+$/.test(lineno);
+}
+
+function isPathLike(line) {
+  const t = line.trim();
+  if (t.length === 0) return false;
+  // A drive-letter prefix (e.g. "C:\Users\me" or "C:/Users/me") marks a
+  // Windows absolute path, so treat the whole line as path-like. Trailing
+  // colons (e.g. "C:\path\file.js:10") are tolerated, matching grep-style
+  // suffixes on Windows dumps.
+  if (/^[A-Za-z]:[\\/]/.test(t)) return true;
+  if (t.includes(":")) return false;
+  return t.startsWith(".") || t.startsWith("/") || t.includes("/");
+}
+
+function isMostlyPorcelain(head) {
+  const lines = head.split("\n").filter(l => l.trim());
+  if (lines.length < 3) return false;
+  const hits = lines.filter(l => RE_PORCELAIN.test(l)).length;
+  return hits / lines.length >= 0.6;
+}
+
+function isLineNumbered(lines) {
+  let hits = 0;
+  let nonEmpty = 0;
+  const sample = lines.slice(0, 100);
+  for (const l of sample) {
+    if (l.length === 0) continue;
+    nonEmpty++;
+    if (READ_NUMBERED_LINE_RE.test(l)) hits++;
+  }
+  if (nonEmpty < 5) return false;
+  return hits / nonEmpty >= READ_NUMBERED_MIN_HIT_RATIO;
+}
+
+function countMatches(text, re) {
+  const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g");
+  return (text.match(g) || []).length;
+}
diff --git a/open-sse/rtk/caveman.js b/open-sse/rtk/caveman.js
new file mode 100644
index 0000000..9c9a206
--- /dev/null
+++ b/open-sse/rtk/caveman.js
@@ -0,0 +1,9 @@
+// Caveman injector: appends a caveman-style instruction into the system message
+// of the final request body, just before it is dispatched to the provider executor.
+
+import { injectSystemPrompt } from "./systemInject.js";
+import { CAVEMAN_PROMPTS } from "./cavemanPrompts.js";
+
+export function injectCaveman(body, format, level) {
+  injectSystemPrompt(body, format, CAVEMAN_PROMPTS[level]);
+}
diff --git a/open-sse/rtk/cavemanPrompts.js b/open-sse/rtk/cavemanPrompts.js
new file mode 100644
index 0000000..7b533d8
--- /dev/null
+++ b/open-sse/rtk/cavemanPrompts.js
@@ -0,0 +1,110 @@
+// Caveman intensity-level prompts injected into system message to reduce output tokens.
+// Adapted from caveman skill (https://github.com/JuliusBrussee/caveman).
+
+export const CAVEMAN_LEVELS = {
+  LITE: "lite",
+  FULL: "full",
+  ULTRA: "ultra",
+  WENYAN_LITE: "wenyan-lite",
+  WENYAN: "wenyan",
+  WENYAN_ULTRA: "wenyan-ultra",
+};
+
+const SHARED_BOUNDARIES = "Code blocks, file paths, commands, errors, URLs: keep exact. Security warnings, irreversible action confirmations, multi-step ordered sequences: write normal. Resume terse style after.";
+
+const SHARED_EXAMPLES = "Not: \"Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by...\" Yes: \"Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:\"";
+
+const SHARED_AUTO_CLARITY = "Auto-Clarity: drop caveman for security warnings, irreversible actions, multi-step sequences where fragment ambiguity risks misread, or when user repeats a question. Resume after the clear part.";
+
+const SHARED_PERSISTENCE = "ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift. Still active if unsure.";
+
+const SHARED_NO_INVENTED_ABBREV = "No invented abbreviations. Standard well-known tech acronyms (DB, API, HTTP, URL, JSON, ID, OS, CPU) OK. Names of code symbols, function names, API names, error strings: keep verbatim.";
+
+const SHARED_PRESERVE_LANGUAGE = "Preserve the user's dominant language. User wrote Vietnamese, reply Vietnamese. User wrote English, reply English. Wenyan/classical-Chinese levels override this language-preservation rule. Code identifiers, error strings, file paths, commands: keep in their original form regardless of language.";
+
+const SHARED_NO_SELF_REFERENCE = 'No self-reference. Do not name or announce the style (no "caveman mode", no "me caveman think", no "compressed mode active"). Just respond.';
+
+const SHARED_NO_DECORATION = 'No decorative emoji. No narrating tool calls ("I will now search", "I used X to find Y"). No status phrases ("Sure!", "Of course!", "I\'d be happy to"). No causal arrow shorthand ("A -> B -> fails"). State the thing, the action, the reason. Then next step.';
+
+export const CAVEMAN_PROMPTS = {
+  [CAVEMAN_LEVELS.LITE]: [
+    "Respond tersely. Keep grammar and full sentences but drop filler, hedging and pleasantries (just/really/basically/sure/of course/I'd be happy to).",
+    "Pattern: state the thing, the action, the reason. Then next step.",
+    SHARED_EXAMPLES,
+    SHARED_BOUNDARIES,
+    SHARED_AUTO_CLARITY,
+    SHARED_PERSISTENCE,
+    SHARED_NO_INVENTED_ABBREV,
+    SHARED_PRESERVE_LANGUAGE,
+    SHARED_NO_SELF_REFERENCE,
+    SHARED_NO_DECORATION,
+  ].join(" "),
+
+  [CAVEMAN_LEVELS.FULL]: [
+    "Respond like terse caveman. All technical substance stay exact, only fluff die.",
+    "Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries, hedging. Fragments OK. Short synonyms (big not extensive, fix not implement a solution for).",
+    "Pattern: [thing] [action] [reason]. [next step].",
+    SHARED_EXAMPLES,
+    SHARED_BOUNDARIES,
+    SHARED_AUTO_CLARITY,
+    SHARED_PERSISTENCE,
+    SHARED_NO_INVENTED_ABBREV,
+    SHARED_PRESERVE_LANGUAGE,
+    SHARED_NO_SELF_REFERENCE,
+    SHARED_NO_DECORATION,
+  ].join(" "),
+
+  [CAVEMAN_LEVELS.ULTRA]: [
+    "Respond ultra-terse. Maximum compression. Telegraphic.",
+    "Strip conjunctions. One word when one word enough.",
+    "Pattern: [thing] [action] [reason]. [next step].",
+    SHARED_EXAMPLES,
+    SHARED_BOUNDARIES,
+    SHARED_AUTO_CLARITY,
+    SHARED_PERSISTENCE,
+    SHARED_NO_INVENTED_ABBREV,
+    SHARED_PRESERVE_LANGUAGE,
+    SHARED_NO_SELF_REFERENCE,
+    SHARED_NO_DECORATION,
+  ].join(" "),
+
+  [CAVEMAN_LEVELS.WENYAN_LITE]: [
+    "Respond semi-classical. Drop filler/hedging but keep grammar structure, classical register.",
+    "Use classical Chinese sentence patterns where natural. Keep English for technical terms.",
+    SHARED_EXAMPLES,
+    SHARED_BOUNDARIES,
+    SHARED_AUTO_CLARITY,
+    SHARED_PERSISTENCE,
+    SHARED_NO_INVENTED_ABBREV,
+    SHARED_PRESERVE_LANGUAGE,
+    SHARED_NO_SELF_REFERENCE,
+    SHARED_NO_DECORATION,
+  ].join(" "),
+
+  [CAVEMAN_LEVELS.WENYAN]: [
+    "Respond classical Chinese (文言文). Maximum classical terseness. 80-90% character reduction.",
+    "Classical sentence patterns, verbs precede objects, subjects often omitted, classical particles (之/乃/為/其).",
+    "Keep English for code, commands, function names, API names, error strings.",
+    SHARED_EXAMPLES,
+    SHARED_BOUNDARIES,
+    SHARED_AUTO_CLARITY,
+    SHARED_PERSISTENCE,
+    SHARED_NO_INVENTED_ABBREV,
+    SHARED_PRESERVE_LANGUAGE,
+    SHARED_NO_SELF_REFERENCE,
+    SHARED_NO_DECORATION,
+  ].join(" "),
+
+  [CAVEMAN_LEVELS.WENYAN_ULTRA]: [
+    "Respond extreme classical compression (文言文 ultra). Maximum compression, ultra terse.",
+    "Same classical rules as wenyan-full but even more compressed. One classical particle per clause.",
+    SHARED_EXAMPLES,
+    SHARED_BOUNDARIES,
+    SHARED_AUTO_CLARITY,
+    SHARED_PERSISTENCE,
+    SHARED_NO_INVENTED_ABBREV,
+    SHARED_PRESERVE_LANGUAGE,
+    SHARED_NO_SELF_REFERENCE,
+    SHARED_NO_DECORATION,
+  ].join(" "),
+};
diff --git a/open-sse/rtk/constants.js b/open-sse/rtk/constants.js
new file mode 100644
index 0000000..bc80c23
--- /dev/null
+++ b/open-sse/rtk/constants.js
@@ -0,0 +1,60 @@
+// RTK port constants (mirror Rust defaults)
+export const RAW_CAP = 10 * 1024 * 1024;      // 10 MiB
+export const MIN_COMPRESS_SIZE = 500;          // bytes; skip tiny blobs
+export const DETECT_WINDOW = 1024;             // autodetect peeks first N chars
+export const GIT_DIFF_HUNK_MAX_LINES = 100;    // per-hunk line cap
+export const GIT_DIFF_CONTEXT_KEEP = 3;        // context lines around changes
+export const GIT_LOG_MAX_LINES = 200;          // gitLog line cap
+export const DEDUP_LINE_MAX = 2000;            // dedupLog truncation cap
+
+// Rust pipe_cmd.rs parity caps
+export const GREP_PER_FILE_MAX = 10;           // match rust: matches.iter().take(10)
+export const FIND_PER_DIR_MAX = 10;            // match rust: files.iter().take(10)
+export const FIND_TOTAL_DIR_MAX = 20;          // match rust: dirs.iter().take(20)
+
+// git status caps (rust config::limits())
+export const STATUS_MAX_FILES = 10;            // config::limits().status_max_files
+export const STATUS_MAX_UNTRACKED = 10;        // config::limits().status_max_untracked
+
+// ls compact_ls (rtk/src/cmds/system/ls.rs)
+export const LS_EXT_SUMMARY_TOP = 5;           // top-N extensions in summary
+export const LS_NOISE_DIRS = [
+  "node_modules", ".git", "target", "__pycache__",
+  ".next", "dist", "build", ".cache", ".turbo",
+  ".vercel", ".pytest_cache", ".mypy_cache", ".tox",
+  ".venv", "venv",
+  "env", // Python legacy virtualenv; .env (dotenv) intentionally excluded
+  "coverage", ".nyc_output", ".DS_Store", "Thumbs.db",
+  ".idea", ".vscode", ".vs", "*.egg-info", ".eggs"
+];
+
+// tree filter_tree_output cap (no rust cap, we add one to be safe)
+export const TREE_MAX_LINES = 200;
+
+// Cursor Glob "Result of search in '...' (total N files):" list
+export const SEARCH_LIST_PER_DIR_MAX = 10;
+export const SEARCH_LIST_TOTAL_DIR_MAX = 20;
+
+// Smart truncate (port of filter.rs smart_truncate fallback)
+export const SMART_TRUNCATE_HEAD = 120;        // lines kept from top
+export const SMART_TRUNCATE_TAIL = 60;         // lines kept from bottom
+export const SMART_TRUNCATE_MIN_LINES = 250;   // only kick in above this
+
+// readNumbered (files with "  N|content" lines, e.g. Cursor read_file)
+export const READ_NUMBERED_MIN_HIT_RATIO = 0.7;
+
+// Filter name strings (Rust parity + JS extras)
+export const FILTERS = {
+  GIT_DIFF: "git-diff",
+  GIT_STATUS: "git-status",
+  GIT_LOG: "git-log",
+  GREP: "grep",
+  FIND: "find",
+  LS: "ls",
+  TREE: "tree",
+  DEDUP_LOG: "dedup-log",
+  SMART_TRUNCATE: "smart-truncate",
+  READ_NUMBERED: "read-numbered",
+  SEARCH_LIST: "search-list",
+  BUILD_OUTPUT: "build-output"
+};
diff --git a/open-sse/rtk/filters/buildOutput.js b/open-sse/rtk/filters/buildOutput.js
new file mode 100644
index 0000000..4d3dde9
--- /dev/null
+++ b/open-sse/rtk/filters/buildOutput.js
@@ -0,0 +1,127 @@
+// Compress build tool output (npm, cargo, pip, maven, gradle, etc.)
+// Keeps: errors, warnings, final summary
+// Strips: progress logs, verbose "Compiling X" lists, download logs
+
+// Cargo/rustc error continuation: " --> file:line", "  |", "N | code", "  = note: ..."
+const RE_CARGO_ERR_CONT = /^\s*(-->|\||\d+\s*\||=)/;
+const DEPRECATION_KEEP = 3;
+
+export function buildOutput(input) {
+  const lines = input.split("\n");
+  if (lines.length === 0) return input;
+
+  const errors = [];
+  const warnings = [];
+  const deprecations = [];
+  let summary = null;
+  let compilingCount = 0;
+  let downloadingCount = 0;
+  let inCargoError = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Continuation of cargo error block: keep verbatim while in block
+    if (inCargoError) {
+      if (!trimmed) { inCargoError = false; continue; }
+      if (RE_CARGO_ERR_CONT.test(line)) { errors.push(line); continue; }
+      inCargoError = false;
+    }
+
+    if (!trimmed) continue;
+
+    if (/^npm (ERR!|error)/i.test(trimmed) || /^yarn error/i.test(trimmed)) {
+      errors.push(line);
+      continue;
+    }
+
+    if (/^npm warn deprecated/i.test(trimmed)) {
+      deprecations.push(line);
+      continue;
+    }
+    if (/^npm warn/i.test(trimmed) || /^yarn warn/i.test(trimmed)) {
+      warnings.push(line);
+      continue;
+    }
+
+    if (/^error(\[|:)/i.test(trimmed) || trimmed.startsWith("error -->")) {
+      errors.push(line);
+      inCargoError = true;
+      continue;
+    }
+
+    if (/^warning(\[|:)/i.test(trimmed) || trimmed.startsWith("warning -->")) {
+      warnings.push(line);
+      inCargoError = true;
+      continue;
+    }
+
+    if (/^ERROR:/i.test(trimmed)) {
+      errors.push(line);
+      continue;
+    }
+
+    if (/^\[ERROR\]/i.test(trimmed) || /^BUILD FAILED/i.test(trimmed)) {
+      errors.push(line);
+      continue;
+    }
+
+    if (/^\[WARNING\]/i.test(trimmed)) {
+      warnings.push(line);
+      continue;
+    }
+
+    if (/^\s*Compiling\s+\S+/i.test(trimmed)) {
+      compilingCount++;
+      continue;
+    }
+    if (/^\s*Downloading\s+\S+/i.test(trimmed) || /^Fetching\s+/i.test(trimmed)) {
+      downloadingCount++;
+      continue;
+    }
+
+    if (
+      /^(added|removed|changed|audited|installed)\s+\d+\s+package/i.test(trimmed) ||
+      /^\s*Finished\s+/i.test(trimmed) ||
+      /^BUILD SUCCESS/i.test(trimmed) ||
+      /^\d+\s+(vulnerabilities|packages?|warnings?|errors?)/i.test(trimmed) ||
+      /^Successfully (installed|built)/i.test(trimmed) ||
+      /^To address .* issues/i.test(trimmed) ||
+      /^Run `npm (audit|fund)`/i.test(trimmed) ||
+      /packages are looking for funding/i.test(trimmed)
+    ) {
+      summary = summary ? `${summary}\n${line}` : line;
+      continue;
+    }
+  }
+
+  let out = "";
+
+  // Keep first N deprecations verbatim (package name + reason), count the rest
+  const keepDep = deprecations.slice(0, DEPRECATION_KEEP);
+  for (const d of keepDep) out += `${d}\n`;
+  if (deprecations.length > DEPRECATION_KEEP) {
+    out += `... +${deprecations.length - DEPRECATION_KEEP} more deprecated packages\n`;
+  }
+
+  if (compilingCount > 0) {
+    out += `Compiled ${compilingCount} packages\n`;
+  }
+  if (downloadingCount > 0) {
+    out += `Downloaded ${downloadingCount} packages\n`;
+  }
+
+  for (const e of errors) out += `${e}\n`;
+
+  const keepWarnings = warnings.slice(0, 5);
+  for (const w of keepWarnings) out += `${w}\n`;
+  if (warnings.length > 5) {
+    out += `... +${warnings.length - 5} more warnings\n`;
+  }
+
+  if (summary) out += `${summary}\n`;
+
+  return out.replace(/\n+$/, "") || input;
+}
+
+buildOutput.filterName = "build-output";
diff --git a/open-sse/rtk/filters/dedupLog.js b/open-sse/rtk/filters/dedupLog.js
new file mode 100644
index 0000000..f971c16
--- /dev/null
+++ b/open-sse/rtk/filters/dedupLog.js
@@ -0,0 +1,44 @@
+// Generic fallback: collapse consecutive duplicate lines + blank-line dedupe + hard line cap
+import { DEDUP_LINE_MAX } from "../constants.js";
+
+export function dedupLog(input) {
+  const lines = input.split("\n");
+  const out = [];
+  let prev = null;
+  let runCount = 0;
+  let blankStreak = 0;
+
+  const flushRun = () => {
+    if (prev !== null && runCount > 1) {
+      out.push(`  ... (${runCount - 1} duplicate lines)`);
+    }
+  };
+
+  for (const line of lines) {
+    if (line.trim() === "") {
+      if (blankStreak < 1) out.push(line);
+      blankStreak += 1;
+      flushRun();
+      prev = null;
+      runCount = 0;
+      continue;
+    }
+    blankStreak = 0;
+    if (line === prev) {
+      runCount += 1;
+      continue;
+    }
+    flushRun();
+    out.push(line);
+    prev = line;
+    runCount = 1;
+    if (out.length >= DEDUP_LINE_MAX) {
+      out.push(`... (truncated at ${DEDUP_LINE_MAX} lines)`);
+      return out.join("\n");
+    }
+  }
+  flushRun();
+  return out.join("\n");
+}
+
+dedupLog.filterName = "dedup-log";
diff --git a/open-sse/rtk/filters/find.js b/open-sse/rtk/filters/find.js
new file mode 100644
index 0000000..4b64169
--- /dev/null
+++ b/open-sse/rtk/filters/find.js
@@ -0,0 +1,50 @@
+// Port of find_wrapper (rtk/src/cmds/system/pipe_cmd.rs:89-128)
+// Group by parent dir, show basenames, cap 10/dir and 20 dirs total
+import { FIND_PER_DIR_MAX, FIND_TOTAL_DIR_MAX } from "../constants.js";
+
+export function find(input) {
+  const lines = input.split("\n").filter(l => l.trim());
+  if (lines.length === 0) return input;
+
+  const byDir = new Map();
+
+  for (const path of lines) {
+    // Accept both Unix ("/a/b") and Windows ("C:\a\b") separators
+    const lastSep = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+    let dir;
+    let basename;
+    if (lastSep === -1) {
+      dir = ".";
+      basename = path;
+    } else {
+      // Rust: PathBuf::from(path).parent().display() + file_name().display()
+      dir = path.slice(0, lastSep) || "/";
+      basename = path.slice(lastSep + 1);
+    }
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir).push(basename);
+  }
+
+  // Rust: dirs.sort_by_key(|(d, _)| d.clone())
+  const dirs = Array.from(byDir.keys()).sort();
+  let out = `${lines.length} files in ${dirs.length} dirs:\n\n`;
+
+  const showDirs = dirs.slice(0, FIND_TOTAL_DIR_MAX);
+  for (const dir of showDirs) {
+    const files = byDir.get(dir);
+    const dirLabel = dir.replace(/\\/g, "/");
+    out += `${dirLabel}/  (${files.length})\n`;
+    const showFiles = files.slice(0, FIND_PER_DIR_MAX);
+    for (const f of showFiles) out += `  ${f}\n`;
+    if (files.length > FIND_PER_DIR_MAX) {
+      out += `  +${files.length - FIND_PER_DIR_MAX}\n`;
+    }
+  }
+  if (dirs.length > FIND_TOTAL_DIR_MAX) {
+    out += `\n+${dirs.length - FIND_TOTAL_DIR_MAX} more dirs\n`;
+  }
+
+  return out;
+}
+
+find.filterName = "find";
diff --git a/open-sse/rtk/filters/gitDiff.js b/open-sse/rtk/filters/gitDiff.js
new file mode 100644
index 0000000..eaf8227
--- /dev/null
+++ b/open-sse/rtk/filters/gitDiff.js
@@ -0,0 +1,92 @@
+// Port of Rust git::compact_diff (src/cmds/git/git.rs L325-413)
+// Compacts unified diff: file headers, hunk-level truncation at 100 lines, +/-/context counting
+import { GIT_DIFF_HUNK_MAX_LINES } from "../constants.js";
+
+export function gitDiff(diff, maxLines = 500) {
+  const result = [];
+  let currentFile = "";
+  let added = 0;
+  let removed = 0;
+  let inHunk = false;
+  let hunkShown = 0;
+  let hunkSkipped = 0;
+  let wasTruncated = false;
+  const maxHunkLines = GIT_DIFF_HUNK_MAX_LINES;
+
+  const lines = diff.split("\n");
+
+  outer: for (const line of lines) {
+    if (line.startsWith("diff --git")) {
+      if (hunkSkipped > 0) {
+        result.push(`  ... (${hunkSkipped} lines truncated)`);
+        wasTruncated = true;
+        hunkSkipped = 0;
+      }
+      if (currentFile && (added > 0 || removed > 0)) {
+        result.push(`  +${added} -${removed}`);
+      }
+      const parts = line.split(" b/");
+      currentFile = parts.length > 1 ? parts.slice(1).join(" b/") : "unknown";
+      result.push(`\n${currentFile}`);
+      added = 0;
+      removed = 0;
+      inHunk = false;
+      hunkShown = 0;
+    } else if (line.startsWith("@@")) {
+      if (hunkSkipped > 0) {
+        result.push(`  ... (${hunkSkipped} lines truncated)`);
+        wasTruncated = true;
+        hunkSkipped = 0;
+      }
+      inHunk = true;
+      hunkShown = 0;
+      result.push(`  ${line}`);
+    } else if (inHunk) {
+      if (line.startsWith("+") && !line.startsWith("+++")) {
+        added += 1;
+        if (hunkShown < maxHunkLines) {
+          result.push(`  ${line}`);
+          hunkShown += 1;
+        } else {
+          hunkSkipped += 1;
+        }
+      } else if (line.startsWith("-") && !line.startsWith("---")) {
+        removed += 1;
+        if (hunkShown < maxHunkLines) {
+          result.push(`  ${line}`);
+          hunkShown += 1;
+        } else {
+          hunkSkipped += 1;
+        }
+      } else if (hunkShown < maxHunkLines && !line.startsWith("\\")) {
+        if (hunkShown > 0) {
+          result.push(`  ${line}`);
+          hunkShown += 1;
+        }
+      }
+    }
+
+    if (result.length >= maxLines) {
+      result.push("\n... (more changes truncated)");
+      wasTruncated = true;
+      break outer;
+    }
+  }
+
+  if (hunkSkipped > 0) {
+    result.push(`  ... (${hunkSkipped} lines truncated)`);
+    wasTruncated = true;
+  }
+
+  if (currentFile && (added > 0 || removed > 0)) {
+    result.push(`  +${added} -${removed}`);
+  }
+
+  if (wasTruncated) {
+    result.push("[full diff: rtk git diff --no-compact]");
+  }
+
+  return result.join("\n");
+}
+
+gitDiff.filterName = "git-diff";
diff --git a/open-sse/rtk/filters/gitLog.js b/open-sse/rtk/filters/gitLog.js
new file mode 100644
index 0000000..9769c6d
--- /dev/null
+++ b/open-sse/rtk/filters/gitLog.js
@@ -0,0 +1,99 @@
+// JS-native git-log filter
+// Compresses `git log` output: keeps commit headers, subjects, Author/Date;
+// drops body padding, decoration, embedded diff lines.
+import { GIT_LOG_MAX_LINES } from "../constants.js";
+
+export function gitLog(text, maxLines = GIT_LOG_MAX_LINES) {
+  if (!text) return "";
+
+  const input = String(text);
+  const lines = input.split("\n");
+  const out = [];
+  let skipped = 0;
+  let inCommit = false;
+  let subjectSeen = false;
+
+  function pushLine(l) {
+    if (out.length < maxLines) {
+      out.push(l);
+      return true;
+    }
+    skipped++;
+    return false;
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const line = raw.trimEnd();
+    const trimmed = line.trim();
+
+    // commit <sha> header — starts new commit entry
+    // Also matched with leading graph decoration (`*   commit abc1234...` — --graph without --oneline)
+    if (/^commit [0-9a-f]{7,40}$/i.test(trimmed) || /^[*|/\\ ]+commit [0-9a-f]{7,40}/i.test(trimmed)) {
+      inCommit = true;
+      subjectSeen = false;
+      pushLine(line);
+      continue;
+    }
+
+    if (inCommit) {
+      // Author / Date — keep as-is (already column 0 in raw, or graph-prefix stripped by commit-header match)
+      if (/^[*|/\\ ]*(Author|Date):/i.test(trimmed)) {
+        pushLine(trimmed);
+        continue;
+      }
+      // blank — skip
+      if (trimmed === "") continue;
+      // indented subject (4 spaces, optionally preceded by graph decoration) — first one is subject
+      if (!subjectSeen && /^[*|/\\ ]*    \S/.test(line)) {
+        pushLine("  Subject: " + trimmed);
+        subjectSeen = true;
+        continue;
+      }
+      // stat summary: "N file(s) changed, N insertions(+), N deletions(-)"
+      if (/^\d+ file\w* changed/.test(trimmed)) {
+        pushLine("  " + trimmed);
+        continue;
+      }
+      // embedded diff header — one-line marker
+      if (/^diff --git /.test(trimmed)) {
+        pushLine("  ... diff body omitted");
+        continue;
+      }
+      // everything else in commit body — drop
+      continue;
+    }
+
+    // Not in a commit block (--oneline / --graph modes):
+
+    // Graph decoration + sha + subject: "*|/\\ <sha7> <subject>"
+    const graphMatch = trimmed.match(/^[*|/\\ ]+([0-9a-f]{7,40}\s+.+)/i);
+    if (graphMatch) {
+      pushLine(graphMatch[1]);
+      continue;
+    }
+
+    // Plain oneline: "<sha7> <subject>"
+    if (/^[0-9a-f]{7,40}\s+/.test(trimmed)) {
+      pushLine(trimmed);
+      continue;
+    }
+
+    // Pure graph decoration (no sha) — drop
+    if (/^[*|/\\ ]+$/.test(trimmed) && /[*|/\\]/.test(trimmed)) {
+      continue;
+    }
+
+    // catch-all pass-through
+    pushLine(trimmed);
+  }
+
+  if (skipped > 0) out.push(`... (${skipped} more lines)`);
+
+  const result = out.join("\n");
+  if (!result && input) return input;
+  if (result.length > input.length) return input;
+  return result;
+}
+
+gitLog.filterName = "git-log";
diff --git a/open-sse/rtk/filters/gitStatus.js b/open-sse/rtk/filters/gitStatus.js
new file mode 100644
index 0000000..3784d86
--- /dev/null
+++ b/open-sse/rtk/filters/gitStatus.js
@@ -0,0 +1,117 @@
+// Port of git::format_status_output (rtk/src/cmds/git/git.rs:619-730)
+// Output format:
+//   * <branch>
+//   + Staged: N files
+//      path1
+//      ... +K more
+//   ~ Modified: N files
+//   ? Untracked: N files
+//   conflicts: N files
+//   clean — nothing to commit
+import { STATUS_MAX_FILES, STATUS_MAX_UNTRACKED } from "../constants.js";
+
+export function gitStatus(input) {
+  const lines = input.split("\n");
+  if (lines.length === 0 || (lines.length === 1 && !lines[0].trim())) {
+    return "Clean working tree";
+  }
+
+  let branch = "";
+  const stagedFiles = [];
+  const modifiedFiles = [];
+  const untrackedFiles = [];
+  let staged = 0;
+  let modified = 0;
+  let untracked = 0;
+  let conflicts = 0;
+
+  for (const raw of lines) {
+    if (!raw.trim()) continue;
+
+    // Long-form branch detection (LLM usually sends this, not porcelain)
+    const longBranch = raw.match(/^On branch (\S+)/);
+    if (longBranch) { branch = longBranch[1]; continue; }
+
+    // Porcelain branch header: "## main...origin/main"
+    if (raw.startsWith("##")) { branch = raw.replace(/^##\s*/, ""); continue; }
+
+    // Porcelain status (2 chars + space + path)
+    if (raw.length >= 3 && /^[ MADRCU?!][ MADRCU?!] /.test(raw)) {
+      const x = raw[0];
+      const y = raw[1];
+      const file = raw.slice(3);
+
+      if (raw.slice(0, 2) === "??") {
+        untracked++;
+        untrackedFiles.push(file);
+        continue;
+      }
+
+      if ("MADRC".includes(x)) {
+        staged++;
+        stagedFiles.push(file);
+      } else if (x === "U") {
+        conflicts++;
+      }
+
+      if (y === "M" || y === "D") {
+        modified++;
+        modifiedFiles.push(file);
+      }
+      continue;
+    }
+
+    // Long form fallback ("modified:   path", "new file:   path", ...)
+    const longMatch = raw.match(/^\s*(modified|new file|deleted|renamed|both modified):\s+(.+)$/);
+    if (longMatch) {
+      const kind = longMatch[1];
+      const path = longMatch[2].trim();
+      if (kind === "both modified") { conflicts++; }
+      else if (kind === "modified" || kind === "deleted") { modified++; modifiedFiles.push(path); }
+      else if (kind === "new file" || kind === "renamed") { staged++; stagedFiles.push(path); }
+      continue;
+    }
+
+    // "Untracked files:" section — gather bare paths after this marker
+    // Handled implicitly: plain paths without markers are skipped (safer).
+  }
+
+  let out = "";
+  if (branch) out += `* ${branch}\n`;
+
+  if (staged > 0) {
+    out += `+ Staged: ${staged} files\n`;
+    for (const f of stagedFiles.slice(0, STATUS_MAX_FILES)) out += `   ${f}\n`;
+    if (stagedFiles.length > STATUS_MAX_FILES) {
+      out += `   ... +${stagedFiles.length - STATUS_MAX_FILES} more\n`;
+    }
+  }
+
+  if (modified > 0) {
+    out += `~ Modified: ${modified} files\n`;
+    for (const f of modifiedFiles.slice(0, STATUS_MAX_FILES)) out += `   ${f}\n`;
+    if (modifiedFiles.length > STATUS_MAX_FILES) {
+      out += `   ... +${modifiedFiles.length - STATUS_MAX_FILES} more\n`;
+    }
+  }
+
+  if (untracked > 0) {
+    out += `? Untracked: ${untracked} files\n`;
+    for (const f of untrackedFiles.slice(0, STATUS_MAX_UNTRACKED)) out += `   ${f}\n`;
+    if (untrackedFiles.length > STATUS_MAX_UNTRACKED) {
+      out += `   ... +${untrackedFiles.length - STATUS_MAX_UNTRACKED} more\n`;
+    }
+  }
+
+  if (conflicts > 0) {
+    out += `conflicts: ${conflicts} files\n`;
+  }
+
+  if (staged === 0 && modified === 0 && untracked === 0 && conflicts === 0) {
+    out += "clean — nothing to commit\n";
+  }
+
+  return out.replace(/\n+$/, "");
+}
+
+gitStatus.filterName = "git-status";
diff --git a/open-sse/rtk/filters/grep.js b/open-sse/rtk/filters/grep.js
new file mode 100644
index 0000000..2016688
--- /dev/null
+++ b/open-sse/rtk/filters/grep.js
@@ -0,0 +1,48 @@
+// Port of grep_wrapper (rtk/src/cmds/system/pipe_cmd.rs:50-86)
+// Input format: "file:lineno:content" — splitn(3, ':') in Rust
+import { GREP_PER_FILE_MAX } from "../constants.js";
+
+export function grep(input) {
+  const byFile = new Map();
+  let total = 0;
+
+  for (const line of input.split("\n")) {
+    // splitn(3, ':') — only split on first 2 colons
+    const first = line.indexOf(":");
+    if (first === -1) continue;
+    const second = line.indexOf(":", first + 1);
+    if (second === -1) continue;
+    const file = line.slice(0, first);
+    const lineNumStr = line.slice(first + 1, second);
+    const content = line.slice(second + 1);
+    // Rust: parts[1].parse::<usize>().is_ok()
+    if (!/^\d+$/.test(lineNumStr)) continue;
+    total++;
+    if (!byFile.has(file)) byFile.set(file, []);
+    byFile.get(file).push([lineNumStr, content]);
+  }
+
+  if (total === 0) return input;
+
+  // Rust: files.sort_by_key(|(f, _)| *f)
+  const files = Array.from(byFile.keys()).sort();
+  let out = `${total} matches in ${files.length}F:\n\n`;
+
+  for (const file of files) {
+    const matches = byFile.get(file);
+    out += `[file] ${file} (${matches.length}):\n`;
+    const show = matches.slice(0, GREP_PER_FILE_MAX);
+    for (const [lineNum, content] of show) {
+      // Rust: format!("  {:>4}: {}", line_num, content.trim())
+      out += `  ${lineNum.padStart(4)}: ${content.trim()}\n`;
+    }
+    if (matches.length > GREP_PER_FILE_MAX) {
+      out += `  +${matches.length - GREP_PER_FILE_MAX}\n`;
+    }
+    out += "\n";
+  }
+
+  return out;
+}
+
+grep.filterName = "grep";
diff --git a/open-sse/rtk/filters/ls.js b/open-sse/rtk/filters/ls.js
new file mode 100644
index 0000000..d53927d
--- /dev/null
+++ b/open-sse/rtk/filters/ls.js
@@ -0,0 +1,79 @@
+// Port of compact_ls (rtk/src/cmds/system/ls.rs:154-232)
+// Input: `ls -la` style output. Output: compact "name/  (dirs)\nname  size"
+import { LS_EXT_SUMMARY_TOP, LS_NOISE_DIRS } from "../constants.js";
+
+// Rust LS_DATE_RE: month + day + (year|HH:MM)
+const LS_DATE_RE = /\s+(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+\d{1,2}\s+(\d{4}|\d{2}:\d{2})\s+/;
+
+function humanSize(bytes) {
+  if (bytes >= 1_048_576) return `${(bytes / 1_048_576).toFixed(1)}M`;
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)}K`;
+  return `${bytes}B`;
+}
+
+function parseLsLine(line) {
+  const m = LS_DATE_RE.exec(line);
+  if (!m) return null;
+  const name = line.slice(m.index + m[0].length);
+  const beforeDate = line.slice(0, m.index);
+  const beforeParts = beforeDate.split(/\s+/).filter(Boolean);
+  if (beforeParts.length < 4) return null;
+
+  const perms = beforeParts[0];
+  const fileType = perms.charAt(0);
+
+  // size = rightmost parseable number before the date
+  let size = 0;
+  for (let i = beforeParts.length - 1; i >= 0; i--) {
+    const n = Number(beforeParts[i]);
+    if (Number.isInteger(n) && String(n) === beforeParts[i]) { size = n; break; }
+  }
+  return { fileType, size, name };
+}
+
+export function ls(input) {
+  const dirs = [];
+  const files = [];      // [name, sizeStr]
+  const byExt = new Map();
+
+  for (const line of input.split("\n")) {
+    if (line.startsWith("total ") || line.length === 0) continue;
+    const parsed = parseLsLine(line);
+    if (!parsed) continue;
+    if (parsed.name === "." || parsed.name === "..") continue;
+
+    // Rust ls.rs: show_all flag respected — for LLM context always skip noise
+    if (LS_NOISE_DIRS.includes(parsed.name)) continue;
+
+    if (parsed.fileType === "d") {
+      dirs.push(parsed.name);
+    } else if (parsed.fileType === "-" || parsed.fileType === "l") {
+      const dot = parsed.name.lastIndexOf(".");
+      const ext = dot > 0 ? parsed.name.slice(dot) : "no ext";
+      byExt.set(ext, (byExt.get(ext) || 0) + 1);
+      files.push([parsed.name, humanSize(parsed.size)]);
+    }
+  }
+
+  if (dirs.length === 0 && files.length === 0) return input;
+
+  let out = "";
+  for (const d of dirs) out += `${d}/\n`;
+  for (const [name, size] of files) out += `${name}  ${size}\n`;
+
+  // Summary line (Rust port)
+  let summary = `\nSummary: ${files.length} files, ${dirs.length} dirs`;
+  if (byExt.size > 0) {
+    const ext = Array.from(byExt.entries()).sort((a, b) => b[1] - a[1]);
+    const parts = ext.slice(0, LS_EXT_SUMMARY_TOP).map(([e, c]) => `${c} ${e}`);
+    summary += ` (${parts.join(", ")}`;
+    if (ext.length > LS_EXT_SUMMARY_TOP) {
+      summary += `, +${ext.length - LS_EXT_SUMMARY_TOP} more`;
+    }
+    summary += ")";
+  }
+
+  return out + summary;
+}
+
+ls.filterName = "ls";
diff --git a/open-sse/rtk/filters/readNumbered.js b/open-sse/rtk/filters/readNumbered.js
new file mode 100644
index 0000000..8621059
--- /dev/null
+++ b/open-sse/rtk/filters/readNumbered.js
@@ -0,0 +1,27 @@
+// Handles Cursor/Codex read_file output: "  1|content\n  2|content".
+// Strategy mirrors Rust filter::smart_truncate (filter.rs): keep head+tail, drop middle.
+import { SMART_TRUNCATE_HEAD, SMART_TRUNCATE_TAIL, SMART_TRUNCATE_MIN_LINES } from "../constants.js";
+
+const LINE_RE = /^\s*\d+\|/;
+
+export function readNumbered(input) {
+  const lines = input.split("\n");
+  if (lines.length < SMART_TRUNCATE_MIN_LINES) return input;
+
+  // Count how many lines match "N|content" to verify shape (hit ratio check
+  // already done by autodetect; here we just truncate).
+  const head = lines.slice(0, SMART_TRUNCATE_HEAD);
+  const tail = lines.slice(lines.length - SMART_TRUNCATE_TAIL);
+  const cut = lines.length - head.length - tail.length;
+
+  return [
+    ...head,
+    `... +${cut} lines truncated (file continues)`,
+    ...tail
+  ].join("\n");
+}
+
+readNumbered.filterName = "read-numbered";
+
+// Exposed for autodetect
+export const READ_NUMBERED_LINE_RE = LINE_RE;
diff --git a/open-sse/rtk/filters/searchList.js b/open-sse/rtk/filters/searchList.js
new file mode 100644
index 0000000..4e18449
--- /dev/null
+++ b/open-sse/rtk/filters/searchList.js
@@ -0,0 +1,52 @@
+// Compact "Result of search in '...' (total N files):\n- path\n- path" output
+// (Cursor Glob tool). Groups by parent dir like find, shows basenames.
+import { SEARCH_LIST_PER_DIR_MAX, SEARCH_LIST_TOTAL_DIR_MAX } from "../constants.js";
+
+const HEADER_RE = /^Result of search in '[^']*' \(total (\d+) files?\):/;
+
+export function searchList(input) {
+  const lines = input.split("\n");
+  if (lines.length === 0) return input;
+
+  // First line must be the header (validated by autodetect too)
+  const header = lines[0] || "";
+  const rest = lines.slice(1);
+
+  const paths = [];
+  for (const raw of rest) {
+    const t = raw.trim();
+    if (!t.startsWith("- ")) continue;
+    paths.push(t.slice(2));
+  }
+  if (paths.length === 0) return input;
+
+  const byDir = new Map();
+  for (const p of paths) {
+    const slash = p.lastIndexOf("/");
+    const dir = slash === -1 ? "." : (p.slice(0, slash) || "/");
+    const name = slash === -1 ? p : p.slice(slash + 1);
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir).push(name);
+  }
+
+  const dirs = Array.from(byDir.keys()).sort();
+  let out = `${header}\n${paths.length} files in ${dirs.length} dirs:\n\n`;
+
+  for (const dir of dirs.slice(0, SEARCH_LIST_TOTAL_DIR_MAX)) {
+    const names = byDir.get(dir);
+    out += `${dir}/ (${names.length}):\n`;
+    for (const n of names.slice(0, SEARCH_LIST_PER_DIR_MAX)) out += `  ${n}\n`;
+    if (names.length > SEARCH_LIST_PER_DIR_MAX) {
+      out += `  +${names.length - SEARCH_LIST_PER_DIR_MAX}\n`;
+    }
+    out += "\n";
+  }
+  if (dirs.length > SEARCH_LIST_TOTAL_DIR_MAX) {
+    out += `+${dirs.length - SEARCH_LIST_TOTAL_DIR_MAX} more dirs\n`;
+  }
+
+  return out.replace(/\n+$/, "");
+}
+
+searchList.filterName = "search-list";
+export const SEARCH_LIST_HEADER_RE = HEADER_RE;
diff --git a/open-sse/rtk/filters/smartTruncate.js b/open-sse/rtk/filters/smartTruncate.js
new file mode 100644
index 0000000..f8e3087
--- /dev/null
+++ b/open-sse/rtk/filters/smartTruncate.js
@@ -0,0 +1,15 @@
+// Port concept of filter::smart_truncate (rtk/src/core/filter.rs).
+// Keep HEAD + TAIL lines, replace middle with "... +N lines truncated".
+import { SMART_TRUNCATE_HEAD, SMART_TRUNCATE_TAIL, SMART_TRUNCATE_MIN_LINES } from "../constants.js";
+
+export function smartTruncate(input) {
+  const lines = input.split("\n");
+  if (lines.length < SMART_TRUNCATE_MIN_LINES) return input;
+
+  const head = lines.slice(0, SMART_TRUNCATE_HEAD);
+  const tail = lines.slice(lines.length - SMART_TRUNCATE_TAIL);
+  const cut = lines.length - head.length - tail.length;
+  return [...head, `... +${cut} lines truncated`, ...tail].join("\n");
+}
+
+smartTruncate.filterName = "smart-truncate";
diff --git a/open-sse/rtk/filters/tree.js b/open-sse/rtk/filters/tree.js
new file mode 100644
index 0000000..f0222d1
--- /dev/null
+++ b/open-sse/rtk/filters/tree.js
@@ -0,0 +1,32 @@
+// Port of filter_tree_output (rtk/src/cmds/system/tree.rs:65-94)
+// Removes summary line (e.g. "5 directories, 23 files") and trailing blanks.
+import { TREE_MAX_LINES } from "../constants.js";
+
+export function tree(input) {
+  const lines = input.split("\n");
+  if (lines.length === 0) return input;
+
+  const filtered = [];
+  for (const line of lines) {
+    // Drop "X directories, Y files" summary
+    if (line.includes("director") && line.includes("file")) continue;
+    // Drop leading blanks
+    if (line.trim() === "" && filtered.length === 0) continue;
+    filtered.push(line);
+  }
+
+  // Drop trailing blanks
+  while (filtered.length > 0 && filtered[filtered.length - 1].trim() === "") {
+    filtered.pop();
+  }
+
+  // Cap overly long trees (JS-only safeguard; Rust has no cap)
+  if (filtered.length > TREE_MAX_LINES) {
+    const cut = filtered.length - TREE_MAX_LINES;
+    return filtered.slice(0, TREE_MAX_LINES).join("\n") + `\n... +${cut} more lines`;
+  }
+
+  return filtered.join("\n");
+}
+
+tree.filterName = "tree";
diff --git a/open-sse/rtk/headroom.js b/open-sse/rtk/headroom.js
new file mode 100644
index 0000000..880195f
--- /dev/null
+++ b/open-sse/rtk/headroom.js
@@ -0,0 +1,348 @@
+import { claudeToOpenAIRequest } from "../translator/request/claude-to-openai.js";
+import { openaiToClaudeRequest } from "../translator/request/openai-to-claude.js";
+import {
+  openaiResponsesToOpenAIRequest,
+  openaiToOpenAIResponsesRequest,
+} from "../translator/request/openai-responses.js";
+
+const DEFAULT_TIMEOUT_MS = 3000;
+
+function jsonBytes(value) {
+  try {
+    return new TextEncoder().encode(JSON.stringify(value) || "").length;
+  } catch {
+    return 0;
+  }
+}
+
+function messagePayload(body) {
+  if (Array.isArray(body?.messages)) return body.messages;
+  if (Array.isArray(body?.input)) return body.input;
+  const kiro = collectKiroHeadroomMessages(body);
+  if (kiro) return kiro.messages;
+  return null;
+}
+
+function captureSizeSnapshot(body) {
+  const messages = messagePayload(body);
+  return {
+    bodyBytes: jsonBytes(body),
+    messageBytes: messages ? jsonBytes(messages) : 0,
+  };
+}
+
+function setDiagnostic(diagnostics, reason) {
+  if (diagnostics && !diagnostics.reason) diagnostics.reason = reason;
+}
+
+function scrubSensitiveUrlText(text) {
+  return String(text)
+    .replace(/\/\/[^/@\s]+@/g, "//")
+    .replace(/(https?:\/\/[^\s?#]+)[?#][^\s)]*/g, "$1");
+}
+
+function describeFetchError(error) {
+  const cause = error?.cause;
+  const code = cause?.code || error?.code;
+  const message = scrubSensitiveUrlText(cause?.message || error?.message || String(error));
+  return code ? `${code}: ${message}` : message;
+}
+
+function buildCompressEndpoint(url) {
+  try {
+    const parsed = new URL(url);
+    parsed.pathname = `${parsed.pathname.replace(/\/$/, "")}/v1/compress`;
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    const raw = String(url).replace(/#.*$/, "");
+    const [base, query = ""] = raw.split("?", 2);
+    const endpoint = `${base.replace(/\/$/, "")}/v1/compress`;
+    return query ? `${endpoint}?${query}` : endpoint;
+  }
+}
+
+function maskEndpoint(endpoint) {
+  try {
+    const parsed = new URL(endpoint);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return String(endpoint).replace(/\/\/[^/@\s]+@/, "//").replace(/[?#].*$/, "");
+  }
+}
+
+function hasUnsafeResponsesInputForCompression(body) {
+  if (!Array.isArray(body?.input)) return false;
+  return body.input.some((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return false;
+    return typeof item.type === "string" && item.type !== "message";
+  });
+}
+
+function collectKiroHeadroomMessages(body) {
+  const state = body?.conversationState;
+  if (!state || typeof state !== "object") return null;
+
+  const messages = [];
+  const targets = [];
+
+  const addTextTarget = (role, text, target, extra = {}) => {
+    if (typeof text !== "string") return;
+    messages.push({ role, content: text, ...extra });
+    targets.push(target);
+  };
+
+  const toToolCalls = (toolUses) => {
+    if (!Array.isArray(toolUses) || toolUses.length === 0) return undefined;
+    const calls = toolUses.map((toolUse) => ({
+      id: toolUse?.toolUseId,
+      type: "function",
+      function: {
+        name: toolUse?.name || "",
+        arguments: JSON.stringify(toolUse?.input || {}),
+      },
+    })).filter((call) => call.id || call.function.name);
+    return calls.length > 0 ? calls : undefined;
+  };
+
+  const visit = (item) => {
+    const user = item?.userInputMessage;
+    if (user) {
+      addTextTarget("system", user.systemInstruction, { object: user, key: "systemInstruction" });
+      addTextTarget("user", user.content, { object: user, key: "content" });
+
+      const toolResults = user.userInputMessageContext?.toolResults;
+      if (Array.isArray(toolResults)) {
+        for (const toolResult of toolResults) {
+          const content = toolResult?.content;
+          if (!Array.isArray(content)) continue;
+          for (const part of content) {
+            addTextTarget(
+              "tool",
+              part?.text,
+              { object: part, key: "text" },
+              toolResult?.toolUseId ? { tool_call_id: toolResult.toolUseId } : {}
+            );
+          }
+        }
+      }
+      return;
+    }
+
+    const assistant = item?.assistantResponseMessage;
+    if (assistant) {
+      const toolCalls = toToolCalls(assistant.toolUses);
+      addTextTarget(
+        "assistant",
+        assistant.content,
+        { object: assistant, key: "content" },
+        toolCalls ? { tool_calls: toolCalls } : {}
+      );
+    }
+  };
+
+  if (Array.isArray(state.history)) {
+    for (const item of state.history) visit(item);
+  }
+  if (state.currentMessage) visit(state.currentMessage);
+
+  return messages.length > 0 ? { messages, targets } : null;
+}
+
+function textFromHeadroomMessage(message) {
+  const content = message?.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return null;
+
+  const parts = [];
+  for (const part of content) {
+    if (typeof part === "string") {
+      parts.push(part);
+    } else if (typeof part?.text === "string") {
+      parts.push(part.text);
+    }
+  }
+  return parts.length > 0 ? parts.join("\n") : null;
+}
+
+function applyKiroHeadroomMessages(projection, compressedMessages, diagnostics) {
+  if (!Array.isArray(compressedMessages) || compressedMessages.length !== projection.messages.length) {
+    setDiagnostic(diagnostics, "proxy response did not match Kiro message count");
+    return false;
+  }
+
+  const updates = [];
+  for (let i = 0; i < projection.messages.length; i++) {
+    const expected = projection.messages[i];
+    const actual = compressedMessages[i];
+    if (!actual || actual.role !== expected.role) {
+      setDiagnostic(diagnostics, "proxy response did not preserve Kiro message order");
+      return false;
+    }
+
+    const text = textFromHeadroomMessage(actual);
+    if (text === null) {
+      setDiagnostic(diagnostics, "proxy response missing Kiro text content");
+      return false;
+    }
+    updates.push({ target: projection.targets[i], text });
+  }
+
+  for (const update of updates) {
+    update.target.object[update.target.key] = update.text;
+  }
+  return true;
+}
+
+// POST messages to Headroom /v1/compress; returns compressed messages + stats or null.
+async function callCompress(url, messages, model, timeoutMs, compressUserMessages, diagnostics) {
+  const endpoint = buildCompressEndpoint(url);
+  diagnostics.endpoint = maskEndpoint(endpoint);
+  const payload = { messages, model };
+  if (compressUserMessages) payload.config = { compress_user_messages: true };
+  let res;
+  try {
+    res = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    setDiagnostic(diagnostics, `request failed: ${describeFetchError(error)}`);
+    return null;
+  }
+  if (!res.ok) {
+    setDiagnostic(diagnostics, `proxy returned HTTP ${res.status}`);
+    return null;
+  }
+  const data = await res.json();
+  if (!Array.isArray(data?.messages)) {
+    setDiagnostic(diagnostics, "proxy response missing messages[]");
+    return null;
+  }
+  return data;
+}
+
+// Compress request body via Headroom proxy. Fail-open: returns null on any error.
+// /v1/compress only understands OpenAI shape, so Claude bodies are translated
+// to OpenAI, compressed, then translated back using 9Router's own translators.
+export async function compressWithHeadroom(body, { enabled, url, model, format, compressUserMessages, timeoutMs = DEFAULT_TIMEOUT_MS, diagnostics = null } = {}) {
+  if (!enabled) {
+    setDiagnostic(diagnostics, "disabled");
+    return null;
+  }
+  if (!url) {
+    setDiagnostic(diagnostics, "missing proxy URL");
+    return null;
+  }
+  if (!body) {
+    setDiagnostic(diagnostics, "missing request body");
+    return null;
+  }
+
+  try {
+    if (diagnostics) diagnostics.before = captureSizeSnapshot(body);
+
+    // Claude shape: translate → OpenAI → compress → translate back.
+    if (format === "claude") {
+      const oai = claudeToOpenAIRequest(model, body, false);
+      if (!Array.isArray(oai?.messages)) {
+        setDiagnostic(diagnostics, "Claude request did not translate to messages[]");
+        return null;
+      }
+      const data = await callCompress(url, oai.messages, model, timeoutMs, compressUserMessages, diagnostics || {});
+      if (!data) return null;
+      const claudeBody = openaiToClaudeRequest(model, { ...oai, messages: data.messages }, false);
+      if (Array.isArray(claudeBody?.messages)) body.messages = claudeBody.messages;
+      if (claudeBody?.system !== undefined) body.system = claudeBody.system;
+      if (diagnostics) diagnostics.after = captureSizeSnapshot(body);
+      return data;
+    }
+
+    // OpenAI Responses shape (Codex): body.input holds Responses items, NOT OpenAI
+    // messages. Translate input -> OpenAI -> compress -> translate back to input so
+    // body.input keeps the Responses contract (the proxy only understands OpenAI). (#1998)
+    if (format === "openai-responses") {
+      if (hasUnsafeResponsesInputForCompression(body)) {
+        setDiagnostic(diagnostics, "skipped: openai-responses tool/reasoning input is not safe to compress");
+        return null;
+      }
+      const oai = openaiResponsesToOpenAIRequest(model, body, false);
+      if (!Array.isArray(oai?.messages)) return null;
+      const data = await callCompress(url, oai.messages, model, timeoutMs, compressUserMessages, diagnostics || {});
+      if (!data) return null;
+      // input: undefined so the translator rebuilds input from the compressed
+      // messages instead of returning the original input unchanged.
+      const responsesBody = openaiToOpenAIResponsesRequest(
+        model,
+        { ...oai, input: undefined, messages: data.messages },
+        false
+      );
+      if (Array.isArray(responsesBody?.input)) body.input = responsesBody.input;
+      if (diagnostics) diagnostics.after = captureSizeSnapshot(body);
+      return data;
+    }
+
+    // Kiro shape: conversationState.history/currentMessage are projected to
+    // OpenAI messages for the proxy, then copied back into the original Kiro
+    // fields. Keep the provider payload shape intact for Kiro's executor.
+    if (format === "kiro") {
+      const projection = collectKiroHeadroomMessages(body);
+      if (!projection) {
+        setDiagnostic(diagnostics, "Kiro request did not project to messages[]");
+        return null;
+      }
+      const data = await callCompress(url, projection.messages, model, timeoutMs, compressUserMessages, diagnostics || {});
+      if (!data) return null;
+      if (!applyKiroHeadroomMessages(projection, data.messages, diagnostics)) return null;
+      if (diagnostics) diagnostics.after = captureSizeSnapshot(body);
+      return data;
+    }
+
+    // OpenAI shape: messages/input go straight to the proxy.
+    const key = Array.isArray(body.messages) ? "messages"
+      : Array.isArray(body.input) ? "input"
+      : null;
+    if (!key) {
+      setDiagnostic(diagnostics, `unsupported ${format || "unknown"} request shape`);
+      return null;
+    }
+    const data = await callCompress(url, body[key], model, timeoutMs, compressUserMessages, diagnostics || {});
+    if (!data) return null;
+    body[key] = data.messages;
+    if (diagnostics) diagnostics.after = captureSizeSnapshot(body);
+    return data;
+  } catch (error) {
+    setDiagnostic(diagnostics, `unexpected error: ${error?.message || String(error)}`);
+    return null;
+  }
+}
+
+export function formatHeadroomLog(stats) {
+  if (!stats) return null;
+  const before = stats.tokens_before || 0;
+  const after = stats.tokens_after || 0;
+  const delta = stats.tokens_saved || 0;
+  const pct = before > 0 ? ((delta / before) * 100).toFixed(1) : "0";
+  return `reported token delta=${delta} before=${before}${after ? ` after=${after}` : ""} (${pct}%)`.trim();
+}
+
+export function formatHeadroomSizeLog(diagnostics) {
+  const before = diagnostics?.before;
+  const after = diagnostics?.after;
+  if (!before || !after) return "";
+  return `body=${before.bodyBytes}B→${after.bodyBytes}B messages=${before.messageBytes}B→${after.messageBytes}B`;
+}
+
+export function isHeadroomPhantomSavings(stats, diagnostics, minShrinkRatio = 0.05) {
+  if (!stats?.tokens_saved || stats.tokens_saved <= 0) return false;
+  const before = diagnostics?.before?.bodyBytes || 0;
+  const after = diagnostics?.after?.bodyBytes || 0;
+  if (before <= 0 || after <= 0) return false;
+  return after >= before * (1 - minShrinkRatio);
+}
diff --git a/open-sse/rtk/index.js b/open-sse/rtk/index.js
new file mode 100644
index 0000000..dd1e501
--- /dev/null
+++ b/open-sse/rtk/index.js
@@ -0,0 +1,155 @@
+// RTK port: compress tool_result content in LLM request bodies
+// Injected at the top of translateRequest (before any format translation)
+import { RAW_CAP, MIN_COMPRESS_SIZE } from "./constants.js";
+import { autoDetectFilter } from "./autodetect.js";
+import { safeApply } from "./applyFilter.js";
+
+// Compress tool_result content in-place. Returns stats or null if disabled/failed.
+export function compressMessages(body, enabled) {
+  if (!enabled) return null;
+  if (!body) return null;
+
+  // Kiro format: conversationState.history + conversationState.currentMessage
+  if (body.conversationState) {
+    return compressKiroFormat(body, enabled);
+  }
+
+  // Support both OpenAI/Claude "messages" and OpenAI Responses "input"
+  const items = Array.isArray(body.messages) ? body.messages
+    : Array.isArray(body.input) ? body.input
+    : null;
+  if (!items) return null;
+
+  const stats = { bytesBefore: 0, bytesAfter: 0, hits: [] };
+  try {
+    for (let i = 0; i < items.length; i++) {
+      const msg = items[i];
+      if (!msg) continue;
+
+      // Shape 4: OpenAI Responses — top-level { type:"function_call_output", output: string | [{type:"input_text", text}] }
+      if (msg.type === "function_call_output") {
+        if (typeof msg.output === "string") {
+          msg.output = compressText(msg.output, stats, "openai-responses-string");
+        } else if (Array.isArray(msg.output)) {
+          for (let k = 0; k < msg.output.length; k++) {
+            const part = msg.output[k];
+            if (part && part.type === "input_text" && typeof part.text === "string") {
+              part.text = compressText(part.text, stats, "openai-responses-array");
+            }
+          }
+        }
+        continue;
+      }
+
+      // Shape 1: OpenAI tool message — { role:"tool", content: "string" }
+      if (msg.role === "tool" && typeof msg.content === "string") {
+        msg.content = compressText(msg.content, stats, "openai-tool");
+        continue;
+      }
+
+      if (!Array.isArray(msg.content)) continue;
+
+      // Shape 1b: OpenAI tool message — { role:"tool", content:[{type:"text", text:"..."}] }
+      if (msg.role === "tool") {
+        for (let k = 0; k < msg.content.length; k++) {
+          const part = msg.content[k];
+          if (part && part.type === "text" && typeof part.text === "string") {
+            part.text = compressText(part.text, stats, "openai-tool-array");
+          }
+        }
+        continue;
+      }
+
+      // Shape 2/3: blocks array with tool_result entries
+      for (let j = 0; j < msg.content.length; j++) {
+        const block = msg.content[j];
+        if (!block || block.type !== "tool_result") continue;
+        if (block.is_error === true) continue; // preserve error traces
+
+        if (typeof block.content === "string") {
+          // Shape 2: claude string form
+          block.content = compressText(block.content, stats, "claude-string");
+        } else if (Array.isArray(block.content)) {
+          // Shape 3: claude array form — compress each text part
+          for (let k = 0; k < block.content.length; k++) {
+            const part = block.content[k];
+            if (part && part.type === "text" && typeof part.text === "string") {
+              part.text = compressText(part.text, stats, "claude-array");
+            }
+          }
+        }
+      }
+    }
+  } catch (e) {
+    console.warn("[RTK] compressMessages error:", e.message);
+    return null;
+  }
+  return stats;
+}
+
+// Compress Kiro format: conversationState.history[].userInputMessage.userInputMessageContext.toolResults[].content[].text
+function compressKiroFormat(body, enabled) {
+  const stats = { bytesBefore: 0, bytesAfter: 0, hits: [] };
+  try {
+    const state = body.conversationState;
+    const allMessages = [...(Array.isArray(state?.history) ? state.history : [])];
+    if (state?.currentMessage) allMessages.push(state.currentMessage);
+
+    for (const msg of allMessages) {
+      const toolResults = msg?.userInputMessage?.userInputMessageContext?.toolResults;
+      if (!Array.isArray(toolResults)) continue;
+
+      for (const tr of toolResults) {
+        if (tr.status === "error") continue; // preserve error traces
+        if (!Array.isArray(tr.content)) continue;
+
+        for (const part of tr.content) {
+          if (part && typeof part.text === "string") {
+            part.text = compressText(part.text, stats, "kiro-tool-result");
+          }
+        }
+      }
+    }
+  } catch (e) {
+    console.warn("[RTK] compressKiroFormat error:", e.message);
+    return null;
+  }
+  return stats;
+}
+
+function compressText(text, stats, shape) {
+  const bytesIn = text.length;
+  stats.bytesBefore += bytesIn;
+
+  if (bytesIn < MIN_COMPRESS_SIZE || bytesIn > RAW_CAP) {
+    stats.bytesAfter += bytesIn;
+    return text;
+  }
+
+  const fn = autoDetectFilter(text);
+  if (!fn) {
+    stats.bytesAfter += bytesIn;
+    return text;
+  }
+
+  const out = safeApply(fn, text);
+
+  // Safety: never return empty, never grow the input
+  if (!out || out.length === 0 || out.length >= bytesIn) {
+    stats.bytesAfter += bytesIn;
+    return text;
+  }
+
+  stats.bytesAfter += out.length;
+  stats.hits.push({ shape, filter: fn.filterName || fn.name, saved: bytesIn - out.length });
+  return out;
+}
+
+// Convenience: format a log line from stats
+export function formatRtkLog(stats) {
+  if (!stats || !stats.hits || stats.hits.length === 0) return null;
+  const saved = stats.bytesBefore - stats.bytesAfter;
+  const pct = stats.bytesBefore > 0 ? ((saved / stats.bytesBefore) * 100).toFixed(1) : "0";
+  const filters = Array.from(new Set(stats.hits.map(h => h.filter))).join(",");
+  return `[RTK] saved ${saved}B / ${stats.bytesBefore}B (${pct}%) via [${filters}] hits=${stats.hits.length}`;
+}
diff --git a/open-sse/rtk/ponytail.js b/open-sse/rtk/ponytail.js
new file mode 100644
index 0000000..1af6a1a
--- /dev/null
+++ b/open-sse/rtk/ponytail.js
@@ -0,0 +1,9 @@
+// Ponytail injector: appends the "lazy senior dev" instruction into the system
+// message of the final request body, just before dispatch to the provider executor.
+
+import { injectSystemPrompt } from "./systemInject.js";
+import { PONYTAIL_PROMPTS } from "./ponytailPrompt.js";
+
+export function injectPonytail(body, format, level) {
+  injectSystemPrompt(body, format, PONYTAIL_PROMPTS[level]);
+}
diff --git a/open-sse/rtk/ponytailPrompt.js b/open-sse/rtk/ponytailPrompt.js
new file mode 100644
index 0000000..1de2066
--- /dev/null
+++ b/open-sse/rtk/ponytailPrompt.js
@@ -0,0 +1,52 @@
+// Ponytail intensity-level prompts injected into system message to bias toward minimal code.
+// Adapted from ponytail skill (https://github.com/DietrichGebert/ponytail).
+
+export const PONYTAIL_LEVELS = {
+  LITE: "lite",
+  FULL: "full",
+  ULTRA: "ultra",
+};
+
+const SHARED_PERSONA = "You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.";
+
+const SHARED_LADDER = "Before writing code, stop at the first rung that holds: 1) Does this need to exist at all? (YAGNI) 2) Stdlib does it? Use it. 3) Native platform feature covers it? Use it (CSS over JS, DB constraint over app code). 4) Already-installed dependency solves it? Use it; never add a new one for what a few lines can do. 5) Can it be one line? One line. 6) Only then: the minimum code that works.";
+
+const SHARED_RULES = "No unrequested abstractions (no interface with one implementation, no factory for one product, no config for a value that never changes). No boilerplate or scaffolding \"for later\". Deletion over addition. Boring over clever. Fewest files possible; shortest working diff wins. Two stdlib options the same size: take the edge-case-correct one. Mark deliberate simplifications with a `ponytail:` comment naming the ceiling and upgrade path.";
+
+const SHARED_OUTPUT = "Code first. Then at most three short lines: what was skipped, when to add it. No essays or design notes. Pattern: `[code] → skipped: [X], add when [Y].`";
+
+const SHARED_NOT_LAZY = "Never simplify away: input validation at trust boundaries, error handling that prevents data loss, security, accessibility, anything explicitly requested. Non-trivial logic leaves ONE runnable check behind (an assert-based self-check or one small test file; no frameworks). Trivial one-liners need no test.";
+
+const SHARED_PERSISTENCE = "ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if unsure.";
+
+export const PONYTAIL_PROMPTS = {
+  [PONYTAIL_LEVELS.LITE]: [
+    SHARED_PERSONA,
+    "Lite: build what's asked, but name the lazier alternative in one line. User picks.",
+    SHARED_LADDER,
+    SHARED_RULES,
+    SHARED_OUTPUT,
+    SHARED_NOT_LAZY,
+    SHARED_PERSISTENCE,
+  ].join(" "),
+
+  [PONYTAIL_LEVELS.FULL]: [
+    SHARED_PERSONA,
+    "Full: the ladder enforced. Stdlib and native first. Shortest diff, shortest explanation.",
+    SHARED_LADDER,
+    SHARED_RULES,
+    SHARED_OUTPUT,
+    SHARED_NOT_LAZY,
+    SHARED_PERSISTENCE,
+  ].join(" "),
+
+  [PONYTAIL_LEVELS.ULTRA]: [
+    SHARED_PERSONA,
+    "Ultra: YAGNI extremist. Deletion before addition. Ship the one-liner and challenge the rest of the requirement in the same response.",
+    SHARED_LADDER,
+    SHARED_RULES,
+    SHARED_OUTPUT,
+    SHARED_NOT_LAZY,
+    SHARED_PERSISTENCE,
+  ].join(" "),
+};
diff --git a/open-sse/rtk/pxpipe.js b/open-sse/rtk/pxpipe.js
new file mode 100644
index 0000000..04ac8f4
--- /dev/null
+++ b/open-sse/rtk/pxpipe.js
@@ -0,0 +1,104 @@
+// PXPIPE: render bulky Claude-format context as dense PNGs via pxpipe-proxy's
+// library API (transformAnthropicMessages). Fail-open like every token saver:
+// any error/timeout returns { body: null, summary } and leaves the request untouched.
+import { FORMATS } from "../translator/formats.js";
+
+const DEFAULT_TIMEOUT_MS = 15000;
+const DEFAULT_MIN_CHARS = 25000;
+// pxpipe's own profitability gate assumes ~4 chars/token; reuse it for the
+// estimated before/after numbers surfaced in stats (marked "estimated" in UI).
+const EST_CHARS_PER_TOKEN = 4;
+
+function bodyChars(body) {
+  try {
+    return JSON.stringify(body)?.length || 0;
+  } catch {
+    return 0;
+  }
+}
+
+function estTokens(chars) {
+  return Math.round(chars / EST_CHARS_PER_TOKEN);
+}
+
+function skipped(reason, extra = {}) {
+  return { body: null, summary: { applied: false, reason, ...extra } };
+}
+
+// Transform a Claude-format request body through pxpipe. Returns
+// { body: <new body object> | null, summary } — body is null when nothing changed.
+// opts.transform is injected by the host (src side) so open-sse stays free of
+// filesystem/install concerns and remains usable standalone.
+export async function compressWithPxpipe(body, { enabled, format, model, minChars, timeoutMs, transform } = {}) {
+  if (!enabled) return skipped("disabled");
+  if (typeof transform !== "function") return skipped("not_installed");
+  if (!body) return skipped("missing_body");
+  if (format !== FORMATS.CLAUDE) return skipped("unsupported_format", { detail: format });
+
+  const startedAt = Date.now();
+  const originalChars = bodyChars(body);
+  const threshold = Number(minChars) > 0 ? Number(minChars) : DEFAULT_MIN_CHARS;
+  if (originalChars < threshold) {
+    return skipped("below_threshold", { originalChars, threshold });
+  }
+
+  try {
+    const encoded = new TextEncoder().encode(JSON.stringify(body));
+    const budget = Number(timeoutMs) > 0 ? Number(timeoutMs) : DEFAULT_TIMEOUT_MS;
+    // transformAnthropicMessages is local CPU work and can't be aborted; race a
+    // timer and discard the result if it loses (input body is never mutated).
+    const result = await Promise.race([
+      transform({
+        body: encoded,
+        model,
+        options: { minCompressChars: threshold },
+      }),
+      new Promise((resolve) => setTimeout(() => resolve(null), budget)),
+    ]);
+    if (!result) return skipped("timeout", { originalChars, durationMs: Date.now() - startedAt });
+    if (!result.applied) {
+      return skipped(result.reason || "passthrough", {
+        detail: result.detail,
+        originalChars,
+        durationMs: Date.now() - startedAt,
+      });
+    }
+
+    const newBody = JSON.parse(new TextDecoder().decode(result.body));
+    const compressedBodyChars = bodyChars(newBody);
+    const info = result.info || {};
+    const imagedChars = info.compressedChars || 0;
+    // The transformed body is BIGGER in bytes (base64 PNGs) but cheaper in tokens:
+    // images bill by pixels (Anthropic: pixels/750), not by encoded length. So the
+    // after-estimate is remaining-text tokens + image tokens — never chars/4 of the
+    // new body. Provider-billed usage recorded per request stays the ground truth.
+    const imageTokensEst = info.imageTokens
+      || (info.imagePixels ? Math.round(info.imagePixels / 750) : (info.imageCount || 0) * 4761);
+    const summary = {
+      applied: true,
+      reason: "applied",
+      originalChars,
+      compressedBodyChars,
+      imagedChars,
+      imageCount: info.imageCount || 0,
+      imageBytes: info.imageBytes || 0,
+      tokensBeforeEst: info.baselineTokens || estTokens(originalChars),
+      tokensAfterEst: estTokens(Math.max(0, originalChars - imagedChars)) + imageTokensEst,
+      durationMs: Date.now() - startedAt,
+      cacheOwnsControl: result.cache?.ownsCacheControl === true,
+    };
+    summary.tokensSavedEst = Math.max(0, summary.tokensBeforeEst - summary.tokensAfterEst);
+    summary.savedPct = summary.tokensBeforeEst > 0
+      ? +((summary.tokensSavedEst / summary.tokensBeforeEst) * 100).toFixed(2)
+      : 0;
+    return { body: newBody, summary };
+  } catch (e) {
+    return skipped("transform_error", { detail: e?.message || String(e), originalChars, durationMs: Date.now() - startedAt });
+  }
+}
+
+export function formatPxpipeLog(summary) {
+  if (!summary) return null;
+  if (!summary.applied) return null;
+  return `imaged ${summary.imagedChars}ch → ${summary.imageCount} image(s) | est ${summary.tokensBeforeEst}→${summary.tokensAfterEst} tokens (-${summary.savedPct}%) | ${summary.durationMs}ms`;
+}
diff --git a/open-sse/rtk/registry.js b/open-sse/rtk/registry.js
new file mode 100644
index 0000000..5378aab
--- /dev/null
+++ b/open-sse/rtk/registry.js
@@ -0,0 +1,40 @@
+import { FILTERS } from "./constants.js";
+import { gitDiff } from "./filters/gitDiff.js";
+import { gitStatus } from "./filters/gitStatus.js";
+import { gitLog } from "./filters/gitLog.js";
+import { grep } from "./filters/grep.js";
+import { find } from "./filters/find.js";
+import { dedupLog } from "./filters/dedupLog.js";
+import { ls } from "./filters/ls.js";
+import { tree } from "./filters/tree.js";
+import { smartTruncate } from "./filters/smartTruncate.js";
+import { readNumbered } from "./filters/readNumbered.js";
+import { searchList } from "./filters/searchList.js";
+
+const REGISTRY = {
+  [FILTERS.GIT_DIFF]: gitDiff,
+  [FILTERS.GIT_STATUS]: gitStatus,
+  [FILTERS.GIT_LOG]: gitLog,
+  [FILTERS.GREP]: grep,
+  [FILTERS.FIND]: find,
+  [FILTERS.DEDUP_LOG]: dedupLog,
+  [FILTERS.LS]: ls,
+  [FILTERS.TREE]: tree,
+  [FILTERS.SMART_TRUNCATE]: smartTruncate,
+  [FILTERS.READ_NUMBERED]: readNumbered,
+  [FILTERS.SEARCH_LIST]: searchList
+};
+
+// Rust resolve_filter aliases (pipe_cmd.rs): grep|rg, find|fd
+const ALIASES = {
+  rg: grep,
+  fd: find
+};
+
+export function resolveFilter(name) {
+  return REGISTRY[name] || ALIASES[name] || null;
+}
+
+export function allFilters() {
+  return REGISTRY;
+}
diff --git a/open-sse/rtk/systemInject.js b/open-sse/rtk/systemInject.js
new file mode 100644
index 0000000..0d5af72
--- /dev/null
+++ b/open-sse/rtk/systemInject.js
@@ -0,0 +1,98 @@
+// Shared system-prompt injector: appends an instruction into the system message of
+// the final request body, dispatching by format so it works for translated and
+// native-passthrough flows. Used by caveman.js and ponytail.js.
+
+import { FORMATS } from "../translator/formats.js";
+
+const SEP = "\n\n";
+
+export function injectSystemPrompt(body, format, prompt) {
+  if (!body || !prompt) return;
+
+  switch (format) {
+    case FORMATS.CLAUDE:
+      injectClaudeSystem(body, prompt);
+      return;
+    case FORMATS.GEMINI:
+    case FORMATS.GEMINI_CLI:
+    case FORMATS.VERTEX:
+    case FORMATS.ANTIGRAVITY:
+      // Antigravity wraps Gemini shape in body.request → injectGeminiSystem handles it
+      injectGeminiSystem(body, prompt);
+      return;
+    default:
+      // OpenAI and OpenAI-shaped formats (responses/codex/cursor/kiro/ollama)
+      injectMessagesSystem(body, prompt);
+  }
+}
+
+// OpenAI-shaped: messages[] (chat) or input[] (responses) or instructions (responses string)
+function injectMessagesSystem(body, prompt) {
+  // OpenAI Responses API: top-level string field
+  if (typeof body.instructions === "string") {
+    body.instructions = body.instructions
+      ? `${body.instructions}${SEP}${prompt}`
+      : prompt;
+    return;
+  }
+
+  const arr = Array.isArray(body.messages) ? body.messages
+    : Array.isArray(body.input) ? body.input
+    : null;
+  if (!arr) return;
+
+  const idx = arr.findIndex(m => m && (m.role === "system" || m.role === "developer"));
+  if (idx >= 0) {
+    appendToOpenAIMessage(arr[idx], prompt);
+  } else {
+    arr.unshift({ role: "system", content: prompt });
+  }
+}
+
+function appendToOpenAIMessage(msg, prompt) {
+  if (typeof msg.content === "string") {
+    msg.content = `${msg.content}${SEP}${prompt}`;
+  } else if (Array.isArray(msg.content)) {
+    // Responses-style array of parts {type:"input_text"|"text", text}
+    msg.content.push({ type: "input_text", text: prompt });
+  } else {
+    msg.content = prompt;
+  }
+}
+
+// Claude shape: body.system as string | array of {type:"text", text}
+// Insert before the last cache_control block to keep injection inside the cached prefix.
+function injectClaudeSystem(body, prompt) {
+  if (typeof body.system === "string" && body.system.length > 0) {
+    body.system = `${body.system}${SEP}${prompt}`;
+    return;
+  }
+  if (Array.isArray(body.system)) {
+    const block = { type: "text", text: prompt };
+    let lastCacheIdx = -1;
+    for (let i = body.system.length - 1; i >= 0; i--) {
+      if (body.system[i]?.cache_control) { lastCacheIdx = i; break; }
+    }
+    if (lastCacheIdx >= 0) {
+      body.system.splice(lastCacheIdx, 0, block);
+    } else {
+      body.system.push(block);
+    }
+    return;
+  }
+  body.system = prompt;
+}
+
+// Gemini shape: body.system_instruction | body.systemInstruction | body.request.systemInstruction
+// Each shape: { parts: [{ text }] }
+function injectGeminiSystem(body, prompt) {
+  const target = body.request && typeof body.request === "object" ? body.request : body;
+  const useSnake = Object.prototype.hasOwnProperty.call(target, "system_instruction");
+  const key = useSnake ? "system_instruction" : "systemInstruction";
+  const sys = target[key];
+  if (sys && Array.isArray(sys.parts)) {
+    sys.parts.push({ text: prompt });
+    return;
+  }
+  target[key] = { parts: [{ text: prompt }] };
+}
diff --git a/open-sse/services/accountFallback.js b/open-sse/services/accountFallback.js
new file mode 100644
index 0000000..8d280da
--- /dev/null
+++ b/open-sse/services/accountFallback.js
@@ -0,0 +1,215 @@
+import { ERROR_RULES, BACKOFF_CONFIG, TRANSIENT_COOLDOWN_MS } from "../config/errorConfig.js";
+
+/**
+ * Calculate exponential backoff cooldown for rate limits (429)
+ * Level 1: 1s, Level 2: 2s, Level 3: 4s... → max 4 min
+ * @param {number} backoffLevel - Current backoff level
+ * @returns {number} Cooldown in milliseconds
+ */
+export function getQuotaCooldown(backoffLevel = 0) {
+  const level = Math.max(0, backoffLevel - 1);
+  const cooldown = BACKOFF_CONFIG.base * Math.pow(2, level);
+  return Math.min(cooldown, BACKOFF_CONFIG.max);
+}
+
+/**
+ * Check if error should trigger account fallback (switch to next account)
+ * Config-driven: matches ERROR_RULES top-to-bottom (text rules first, then status)
+ * @param {number} status - HTTP status code
+ * @param {string} errorText - Error message text
+ * @param {number} backoffLevel - Current backoff level for exponential backoff
+ * @returns {{ shouldFallback: boolean, cooldownMs: number, newBackoffLevel?: number }}
+ */
+export function checkFallbackError(status, errorText, backoffLevel = 0) {
+  const lowerError = errorText
+    ? (typeof errorText === "string" ? errorText : JSON.stringify(errorText)).toLowerCase()
+    : "";
+
+  for (const rule of ERROR_RULES) {
+    // Text-based rule: match substring in error message
+    if (rule.text && lowerError && lowerError.includes(rule.text)) {
+      if (rule.backoff) {
+        const newLevel = Math.min(backoffLevel + 1, BACKOFF_CONFIG.maxLevel);
+        return { shouldFallback: true, cooldownMs: getQuotaCooldown(newLevel), newBackoffLevel: newLevel };
+      }
+      return { shouldFallback: true, cooldownMs: rule.cooldownMs };
+    }
+
+    // Status-based rule: match HTTP status code
+    if (rule.status && rule.status === status) {
+      if (rule.backoff) {
+        const newLevel = Math.min(backoffLevel + 1, BACKOFF_CONFIG.maxLevel);
+        return { shouldFallback: true, cooldownMs: getQuotaCooldown(newLevel), newBackoffLevel: newLevel };
+      }
+      return { shouldFallback: true, cooldownMs: rule.cooldownMs };
+    }
+  }
+
+  // Default: transient cooldown for any unmatched error
+  return { shouldFallback: true, cooldownMs: TRANSIENT_COOLDOWN_MS };
+}
+
+/**
+ * Check if account is currently unavailable (cooldown not expired)
+ */
+export function isAccountUnavailable(unavailableUntil) {
+  if (!unavailableUntil) return false;
+  return new Date(unavailableUntil).getTime() > Date.now();
+}
+
+/**
+ * Calculate unavailable until timestamp
+ */
+export function getUnavailableUntil(cooldownMs) {
+  return new Date(Date.now() + cooldownMs).toISOString();
+}
+
+/**
+ * Get the earliest rateLimitedUntil from a list of accounts
+ * @param {Array} accounts - Array of account objects with rateLimitedUntil
+ * @returns {string|null} Earliest rateLimitedUntil ISO string, or null
+ */
+export function getEarliestRateLimitedUntil(accounts) {
+  let earliest = null;
+  const now = Date.now();
+  for (const acc of accounts) {
+    if (!acc.rateLimitedUntil) continue;
+    const until = new Date(acc.rateLimitedUntil).getTime();
+    if (until <= now) continue;
+    if (!earliest || until < earliest) earliest = until;
+  }
+  if (!earliest) return null;
+  return new Date(earliest).toISOString();
+}
+
+/**
+ * Format rateLimitedUntil to human-readable "reset after Xm Ys"
+ * @param {string} rateLimitedUntil - ISO timestamp
+ * @returns {string} e.g. "reset after 2m 30s"
+ */
+export function formatRetryAfter(rateLimitedUntil) {
+  if (!rateLimitedUntil) return "";
+  const diffMs = new Date(rateLimitedUntil).getTime() - Date.now();
+  if (diffMs <= 0) return "reset after 0s";
+  const totalSec = Math.ceil(diffMs / 1000);
+  const h = Math.floor(totalSec / 3600);
+  const m = Math.floor((totalSec % 3600) / 60);
+  const s = totalSec % 60;
+  const parts = [];
+  if (h > 0) parts.push(`${h}h`);
+  if (m > 0) parts.push(`${m}m`);
+  if (s > 0 || parts.length === 0) parts.push(`${s}s`);
+  return `reset after ${parts.join(" ")}`;
+}
+
+/** Prefix for model lock flat fields on connection record */
+export const MODEL_LOCK_PREFIX = "modelLock_";
+
+/** Special key used when no model is known (account-level lock) */
+export const MODEL_LOCK_ALL = `${MODEL_LOCK_PREFIX}__all`;
+
+/** Build the flat field key for a model lock */
+export function getModelLockKey(model) {
+  return model ? `${MODEL_LOCK_PREFIX}${model}` : MODEL_LOCK_ALL;
+}
+
+/**
+ * Check if a model lock on a connection is still active.
+ * Reads flat field `modelLock_${model}` (or `modelLock___all` when model=null).
+ */
+export function isModelLockActive(connection, model) {
+  const key = getModelLockKey(model);
+  const expiry = connection[key] || connection[MODEL_LOCK_ALL];
+  if (!expiry) return false;
+  return new Date(expiry).getTime() > Date.now();
+}
+
+/**
+ * Get earliest active model lock expiry across all modelLock_* fields.
+ * Used for UI cooldown display.
+ */
+export function getEarliestModelLockUntil(connection) {
+  if (!connection) return null;
+  let earliest = null;
+  const now = Date.now();
+  for (const [key, val] of Object.entries(connection)) {
+    if (!key.startsWith(MODEL_LOCK_PREFIX) || !val) continue;
+    const t = new Date(val).getTime();
+    if (t <= now) continue;
+    if (!earliest || t < earliest) earliest = t;
+  }
+  return earliest ? new Date(earliest).toISOString() : null;
+}
+
+/**
+ * Build update object to set a model lock on a connection.
+ */
+export function buildModelLockUpdate(model, cooldownMs) {
+  const key = getModelLockKey(model);
+  return { [key]: new Date(Date.now() + cooldownMs).toISOString() };
+}
+
+/**
+ * Build update object to clear all model locks on a connection.
+ */
+export function buildClearModelLocksUpdate(connection) {
+  const cleared = {};
+  for (const key of Object.keys(connection)) {
+    if (key.startsWith(MODEL_LOCK_PREFIX)) cleared[key] = null;
+  }
+  return cleared;
+}
+
+/**
+ * Filter available accounts (not in cooldown)
+ */
+export function filterAvailableAccounts(accounts, excludeId = null) {
+  const now = Date.now();
+  return accounts.filter(acc => {
+    if (excludeId && acc.id === excludeId) return false;
+    if (acc.rateLimitedUntil) {
+      const until = new Date(acc.rateLimitedUntil).getTime();
+      if (until > now) return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Reset account state when request succeeds
+ * Clears cooldown and resets backoff level to 0
+ * @param {object} account - Account object
+ * @returns {object} Updated account with reset state
+ */
+export function resetAccountState(account) {
+  if (!account) return account;
+  return {
+    ...account,
+    rateLimitedUntil: null,
+    backoffLevel: 0,
+    lastError: null,
+    status: "active"
+  };
+}
+
+/**
+ * Apply error state to account
+ * @param {object} account - Account object
+ * @param {number} status - HTTP status code
+ * @param {string} errorText - Error message
+ * @returns {object} Updated account with error state
+ */
+export function applyErrorState(account, status, errorText) {
+  if (!account) return account;
+
+  const backoffLevel = account.backoffLevel || 0;
+  const { cooldownMs, newBackoffLevel } = checkFallbackError(status, errorText, backoffLevel);
+
+  return {
+    ...account,
+    rateLimitedUntil: cooldownMs > 0 ? getUnavailableUntil(cooldownMs) : null,
+    backoffLevel: newBackoffLevel ?? backoffLevel,
+    lastError: { status, message: errorText, timestamp: new Date().toISOString() },
+    status: "error"
+  };
+}
diff --git a/open-sse/services/clinepassModels.js b/open-sse/services/clinepassModels.js
new file mode 100644
index 0000000..4208a4b
--- /dev/null
+++ b/open-sse/services/clinepassModels.js
@@ -0,0 +1,63 @@
+import { buildClineHeaders } from "../shared/clineAuth.js";
+
+const CLINEPASS_MODELS_ENDPOINT = "https://api.cline.bot/api/v1/models";
+const FETCH_TIMEOUT_MS = 5000;
+
+/**
+ * Build request headers for the ClinePass /models endpoint (Cline's upstream API).
+ * - API keys are sent as plain Bearer tokens.
+ * - OAuth access tokens must carry the WorkOS `workos:` prefix (handled by buildClineHeaders).
+ */
+function buildModelListHeaders(token, isApiKey) {
+  if (isApiKey) {
+    return {
+      Accept: "application/json",
+      Authorization: `Bearer ${token}`,
+    };
+  }
+  return buildClineHeaders(token, { Accept: "application/json" });
+}
+
+/**
+ * Fetch ClinePass live model catalog from Cline's /models endpoint.
+ *
+ * @param {object} credentials - Connection credentials ({ accessToken, apiKey })
+ * @returns {Promise<{ models: { id: string, name: string }[] } | null>}
+ */
+export async function resolveClinepassModels(credentials) {
+  const isApiKey = Boolean(credentials?.apiKey);
+  const token = isApiKey ? credentials.apiKey : credentials?.accessToken;
+  if (!token) return null;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    const headers = buildModelListHeaders(token, isApiKey);
+
+    const response = await fetch(CLINEPASS_MODELS_ENDPOINT, {
+      method: "GET",
+      headers,
+      signal: controller.signal,
+    });
+
+    if (!response.ok) return null;
+
+    const json = await response.json();
+    const rawList = Array.isArray(json) ? json : json?.data;
+    if (!Array.isArray(rawList)) return null;
+
+    const models = rawList
+      .filter((m) => typeof m?.id === "string" && m.id.startsWith("cline-pass/"))
+      .map((m) => ({
+        id: m.id,
+        name: m.name || m.id,
+      }));
+
+    return models.length ? { models } : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
diff --git a/open-sse/services/combo.js b/open-sse/services/combo.js
new file mode 100644
index 0000000..9216ab2
--- /dev/null
+++ b/open-sse/services/combo.js
@@ -0,0 +1,571 @@
+/**
+ * Shared combo (model combo) handling with fallback support
+ */
+
+import { checkFallbackError, formatRetryAfter } from "./accountFallback.js";
+import { unavailableResponse } from "../utils/error.js";
+import { getCapabilitiesForModel } from "../providers/capabilities.js";
+import { extractTextContent } from "../translator/formats/gemini.js";
+
+// Hard capabilities = input modalities; missing one drops request data (e.g. image
+// stripped). Must be prioritized. Soft (e.g. search) only degrades a feature.
+const HARD_CAPS = new Set(["vision", "pdf", "audioInput", "videoInput"]);
+
+// Prefixes used when flattening tool turns into plain prose for panel models.
+const TOOL_CALL_PREFIX = "[Called tools: ";
+const TOOL_RESULT_PREFIX = "[Tool result: ";
+
+// Flatten tool turns into prose so panel models keep the context but can't loop
+// on tools: drop the request's tools, turn tool/function results into assistant
+// text, and inline assistant tool_calls names instead of the structured field.
+function flattenToolHistory(messages) {
+  return messages
+    .filter((msg) => msg)
+    .map((msg) => {
+      if (msg.role === "tool" || msg.role === "function") {
+        return { role: "assistant", content: `${TOOL_RESULT_PREFIX}${extractTextContent(msg.content) || String(msg.content ?? "")}]` };
+      }
+      if (msg.role === "assistant" && Array.isArray(msg.tool_calls)) {
+        const { tool_calls, ...rest } = msg;
+        const names = tool_calls.map((c) => c?.function?.name || c?.name || "tool").join(", ");
+        const base = extractTextContent(rest.content) || (typeof rest.content === "string" ? rest.content : "");
+        return { ...rest, content: `${base}${base ? "\n" : ""}${TOOL_CALL_PREFIX}${names}]` };
+      }
+      if (Array.isArray(msg.content)) {
+        const hasToolUse = msg.content.some((c) => c.type === "tool_use");
+        const hasToolResult = msg.content.some((c) => c.type === "tool_result");
+        if (hasToolUse || hasToolResult) {
+          const textParts = [];
+          const toolNames = [];
+          const toolResults = [];
+          for (const block of msg.content) {
+            if (block.type === "text" && block.text) textParts.push(block.text);
+            if (block.type === "tool_use") toolNames.push(block.name || "tool");
+            if (block.type === "tool_result") toolResults.push(extractTextContent(block.content) || String(block.content ?? ""));
+          }
+          const { ...rest } = msg;
+          let newContent = textParts.join("\n");
+          if (toolNames.length > 0) {
+            newContent = `${newContent}${newContent ? "\n" : ""}${TOOL_CALL_PREFIX}${toolNames.join(", ")}]`;
+          }
+          if (toolResults.length > 0) {
+            newContent = `${newContent}${newContent ? "\n" : ""}${TOOL_RESULT_PREFIX}${toolResults.join("\n")}]`;
+          }
+          return { ...rest, content: newContent };
+        }
+      }
+      return msg;
+    });
+}
+
+// Reorder combo models by capability fit. Stable; never drops a model (fallback intact).
+// Tier 0: satisfies all hard + all soft. Tier 1: all hard only. Tier 2: rest.
+export function reorderByCapabilities(models, required) {
+  if (!required || required.size === 0 || !Array.isArray(models) || models.length <= 1) return models;
+  const hard = [...required].filter((c) => HARD_CAPS.has(c));
+  const soft = [...required].filter((c) => !HARD_CAPS.has(c));
+
+  const tierOf = (m) => {
+    const slash = typeof m === "string" ? m.indexOf("/") : -1;
+    const provider = slash > 0 ? m.slice(0, slash) : "";
+    const model = slash > 0 ? m.slice(slash + 1) : m;
+    const caps = getCapabilitiesForModel(provider, model);
+    if (!hard.every((c) => caps[c] === true)) return 2;
+    return soft.every((c) => caps[c] === true) ? 0 : 1;
+  };
+
+  // Stable sort by tier (Array.prototype.sort is stable in modern engines).
+  return models
+    .map((m, i) => ({ m, i, t: tierOf(m) }))
+    .sort((a, b) => a.t - b.t || a.i - b.i)
+    .map((x) => x.m);
+}
+
+/**
+ * Track rotation state per combo (for round-robin strategy)
+ * @type {Map<string, { index: number, consecutiveUseCount: number }>}
+ */
+const comboRotationState = new Map();
+
+// Trailing run of items after the last assistant/model turn = the current user
+// turn. It may span several messages (e.g. text + image split across blocks),
+// so we return all of them. History media (older turns) must not pin the combo
+// to a vision model — those get stripped + placeholdered downstream instead.
+function trailingUserItems(arr) {
+  if (!Array.isArray(arr) || arr.length === 0) return [];
+  const isAssistant = (r) => r === "assistant" || r === "model";
+  let i = arr.length - 1;
+  while (i >= 0 && !isAssistant(arr[i]?.role)) i--;
+  return arr.slice(i + 1);
+}
+
+// Detect which capabilities a request needs. Modalities (vision/pdf) are scanned
+// only on the current user turn; "search" is request-wide (lives in tools).
+// Returns a Set of: "vision" | "pdf" | "search".
+export function detectRequiredCapabilities(body) {
+  const required = new Set();
+  if (!body || typeof body !== "object") return required;
+
+  const scanBlock = (b) => {
+    if (!b || typeof b !== "object") return;
+    const t = b.type;
+    if (t === "image_url" || t === "image" || t === "input_image") required.add("vision");
+    if (t === "file" || t === "document" || t === "input_file") required.add("pdf");
+    // gemini parts: inlineData/fileData carry a mime
+    const mime = b.inlineData?.mimeType || b.fileData?.mimeType;
+    if (typeof mime === "string" && mime.startsWith("image/")) required.add("vision");
+    if (mime === "application/pdf") required.add("pdf");
+  };
+
+  const scanContent = (content) => {
+    if (Array.isArray(content)) for (const b of content) scanBlock(b);
+  };
+
+  // Modalities: current user turn only (trailing user run across each known shape).
+  for (const m of trailingUserItems(body.messages)) scanContent(m.content);      // openai / claude
+  for (const it of trailingUserItems(body.input)) scanContent(it.content);       // responses
+  const contents = body.contents || body.request?.contents;                      // gemini / antigravity
+  for (const c of trailingUserItems(contents)) scanContent(c.parts);
+
+  // search: temporarily disabled in auto-switch (feature not wired yet).
+
+  return required;
+}
+
+function normalizeStickyLimit(stickyLimit) {
+  const parsed = Number.parseInt(stickyLimit, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
+}
+
+function rotateModelsFromIndex(models, currentIndex) {
+  const rotatedModels = [...models];
+  for (let i = 0; i < currentIndex; i++) {
+    const moved = rotatedModels.shift();
+    rotatedModels.push(moved);
+  }
+  return rotatedModels;
+}
+
+/**
+ * Get rotated model list based on strategy
+ * @param {string[]} models - Array of model strings
+ * @param {string} comboName - Name of the combo
+ * @param {string} strategy - "fallback" or "round-robin"
+ * @param {number|string} [stickyLimit=1] - Requests per combo model before switching
+ * @returns {string[]} Rotated models array
+ */
+export function getRotatedModels(models, comboName, strategy, stickyLimit = 1) {
+  if (!models || models.length <= 1 || strategy !== "round-robin") {
+    return models;
+  }
+
+  const rotationKey = comboName || "__default__";
+  const normalizedStickyLimit = normalizeStickyLimit(stickyLimit);
+  const existingState = comboRotationState.get(rotationKey);
+  const state = typeof existingState === "number"
+    ? { index: existingState, consecutiveUseCount: 0 }
+    : (existingState || { index: 0, consecutiveUseCount: 0 });
+
+  const currentIndex = state.index % models.length;
+  const rotatedModels = rotateModelsFromIndex(models, currentIndex);
+  const nextUseCount = state.consecutiveUseCount + 1;
+
+  if (nextUseCount >= normalizedStickyLimit) {
+    comboRotationState.set(rotationKey, {
+      index: (currentIndex + 1) % models.length,
+      consecutiveUseCount: 0,
+    });
+  } else {
+    comboRotationState.set(rotationKey, {
+      index: currentIndex,
+      consecutiveUseCount: nextUseCount,
+    });
+  }
+
+  return rotatedModels;
+}
+
+/**
+ * Reset in-memory rotation state when combo/settings change
+ * @param {string} [comboName] - Combo name to reset; omit to clear all
+ */
+export function resetComboRotation(comboName) {
+  if (comboName) comboRotationState.delete(comboName);
+  else comboRotationState.clear();
+}
+
+/**
+ * Get combo models from combos data
+ * @param {string} modelStr - Model string to check
+ * @param {Array|Object} combosData - Array of combos or object with combos
+ * @returns {string[]|null} Array of models or null if not a combo
+ */
+export function getComboModelsFromData(modelStr, combosData) {
+  // Don't check if it's in provider/model format
+  if (modelStr.includes("/")) return null;
+  
+  // Handle both array and object formats
+  const combos = Array.isArray(combosData) ? combosData : (combosData?.combos || []);
+  
+  const combo = combos.find(c => c.name === modelStr);
+  if (combo && combo.models && combo.models.length > 0) {
+    return combo.models;
+  }
+  return null;
+}
+
+/**
+ * Handle combo chat with fallback
+ * @param {Object} options
+ * @param {Object} options.body - Request body
+ * @param {string[]} options.models - Array of model strings to try
+ * @param {Function} options.handleSingleModel - Function to handle single model: (body, modelStr) => Promise<Response>
+ * @param {Object} options.log - Logger object
+ * @param {string} [options.comboName] - Name of the combo (for round-robin tracking)
+ * @param {string} [options.comboStrategy] - Strategy: "fallback" or "round-robin"
+ * @param {number|string} [options.comboStickyLimit=1] - Requests per combo model before switching
+ * @returns {Promise<Response>}
+ */
+export async function handleComboChat({ body, models, handleSingleModel, log, comboName, comboStrategy, comboStickyLimit = 1, autoSwitch = true }) {
+  // Apply rotation strategy if enabled
+  let rotatedModels = getRotatedModels(models, comboName, comboStrategy, comboStickyLimit);
+
+  // Auto-switch: float models that satisfy the request's required capabilities to the front.
+  if (autoSwitch) {
+    const required = detectRequiredCapabilities(body);
+    if (required.size > 0) {
+      const reordered = reorderByCapabilities(rotatedModels, required);
+      if (reordered[0] !== rotatedModels[0]) {
+        log.info("COMBO", `auto-switch for [${[...required].join(",")}] → ${reordered[0]}`);
+      }
+      rotatedModels = reordered;
+    }
+  }
+  
+  let lastError = null;
+  let earliestRetryAfter = null;
+  let lastStatus = null;
+
+  for (let i = 0; i < rotatedModels.length; i++) {
+    const modelStr = rotatedModels[i];
+    log.info("COMBO", `Trying model ${i + 1}/${rotatedModels.length}: ${modelStr}`);
+
+    try {
+      const result = await handleSingleModel(body, modelStr);
+      
+      // Success (2xx) - return response
+      if (result.ok) {
+        log.info("COMBO", `Model ${modelStr} succeeded`);
+        return result;
+      }
+
+      // Extract error info from response
+      let errorText = result.statusText || "";
+      let retryAfter = null;
+      try {
+        const errorBody = await result.clone().json();
+        errorText = errorBody?.error?.message || errorBody?.error || errorBody?.message || errorText;
+        retryAfter = errorBody?.retryAfter || null;
+      } catch {
+        // Ignore JSON parse errors
+      }
+
+      // Track earliest retryAfter across all combo models
+      if (retryAfter && (!earliestRetryAfter || new Date(retryAfter) < new Date(earliestRetryAfter))) {
+        earliestRetryAfter = retryAfter;
+      }
+
+      // Normalize error text to string (Worker-safe)
+      if (typeof errorText !== "string") {
+        try { errorText = JSON.stringify(errorText); } catch { errorText = String(errorText); }
+      }
+
+      // Check if should fallback to next model
+      const { shouldFallback, cooldownMs } = checkFallbackError(result.status, errorText);
+
+      if (!shouldFallback) {
+        log.warn("COMBO", `Model ${modelStr} failed (no fallback)`, { status: result.status });
+        return result;
+      }
+
+      // For transient errors (503/502/504), wait for cooldown before falling through
+      // so a briefly-overloaded provider gets a chance to recover rather than being
+      // skipped immediately (fixes: combo falls through on transient 503)
+      if (cooldownMs && cooldownMs > 0 && cooldownMs <= 5000 &&
+          (result.status === 503 || result.status === 502 || result.status === 504)) {
+        log.info("COMBO", `Model ${modelStr} transient ${result.status}, waiting ${cooldownMs}ms before next`);
+        await new Promise(r => setTimeout(r, cooldownMs));
+      }
+
+      // Fallback to next model
+      lastError = errorText || String(result.status);
+      if (!lastStatus) lastStatus = result.status;
+      log.warn("COMBO", `Model ${modelStr} failed, trying next`, { status: result.status });
+    } catch (error) {
+      // Catch unexpected exceptions to ensure fallback continues
+      lastError = error.message || String(error);
+      if (!lastStatus) lastStatus = 500;
+      log.warn("COMBO", `Model ${modelStr} threw error, trying next`, { error: lastError });
+    }
+  }
+
+  // All models failed
+  // Use 503 (Service Unavailable) rather than 406 (Not Acceptable) — 406 implies
+  // the request itself is invalid, but here the providers are simply unavailable
+  // or have no active credentials. 503 is more accurate and retryable by clients.
+  const allDisabled = lastError && lastError.toLowerCase().includes("no credentials");
+  const status = allDisabled ? 503 : (lastStatus || 503);
+  const msg = lastError || "All combo models unavailable";
+
+  if (earliestRetryAfter) {
+    const retryHuman = formatRetryAfter(earliestRetryAfter);
+    log.warn("COMBO", `All models failed | ${msg} (${retryHuman})`);
+    return unavailableResponse(status, msg, earliestRetryAfter, retryHuman);
+  }
+
+  log.warn("COMBO", `All models failed | ${msg}`);
+  return new Response(
+    JSON.stringify({ error: { message: msg } }),
+    { status, headers: { "Content-Type": "application/json" } }
+  );
+}
+
+/**
+ * Extract assistant text from a non-stream completion across formats
+ * (OpenAI chat, Claude messages, Gemini, OpenAI Responses). Returns "" if none.
+ * Panel responses are already translated to the client format by chatCore, so the
+ * leaf content→string step reuses the translator's own extractTextContent.
+ */
+function extractPanelText(json) {
+  if (!json || typeof json !== "object") return "";
+
+  // OpenAI chat completion
+  const choice = json.choices?.[0];
+  if (choice) {
+    const msg = choice.message ?? choice.delta ?? {};
+    const t = extractTextContent(msg.content);
+    if (t.trim()) return t;
+    if (typeof choice.text === "string" && choice.text.trim()) return choice.text;
+  }
+
+  // Claude messages (text blocks share OpenAI's {type:"text"} shape)
+  const claudeText = extractTextContent(json.content);
+  if (claudeText.trim()) return claudeText;
+
+  // Gemini (parts carry .text without a type discriminator)
+  const parts = json.candidates?.[0]?.content?.parts;
+  if (Array.isArray(parts)) {
+    const t = parts.map((p) => p?.text || "").join("");
+    if (t.trim()) return t;
+  }
+
+  // OpenAI Responses API
+  if (Array.isArray(json.output)) {
+    const t = json.output
+      .flatMap((o) => (Array.isArray(o.content) ? o.content.map((c) => c?.text || "") : []))
+      .join("");
+    if (t.trim()) return t;
+  }
+
+  return "";
+}
+
+/**
+ * Append a synthesized user turn to whichever message array the request format uses.
+ * Preserves the original conversation + system prompt so the judge has full context.
+ */
+function appendUserTurn(body, text) {
+  const next = { ...body };
+  if (Array.isArray(body.messages)) {
+    next.messages = [...body.messages, { role: "user", content: text }];
+  } else if (Array.isArray(body.input)) {
+    next.input = [...body.input, { role: "user", content: text }];
+  } else if (Array.isArray(body.contents)) {
+    next.contents = [...body.contents, { role: "user", parts: [{ text }] }];
+  } else {
+    next.messages = [{ role: "user", content: text }];
+  }
+  return next;
+}
+
+/**
+ * Build the judge directive. Per OpenRouter's Fusion design, the judge does NOT
+ * merge — it analyzes (consensus / contradictions / partial coverage / unique
+ * insights / blind spots) then writes one answer grounded in that analysis.
+ * ~3/4 of fusion's quality lift comes from this synthesis step.
+ *
+ * Sources are anonymized ("Source N") so the judge weighs substance, not the
+ * reputation of a model brand.
+ */
+function buildJudgePrompt(answers) {
+  const panel = answers
+    .map((a, i) => `[Source ${i + 1}]\n${a.text}`)
+    .join("\n\n");
+
+  return [
+    `You are the JUDGE in a model-fusion panel. ${answers.length} expert models independently answered the user's most recent request. Their responses are below, anonymized by source.`,
+    "",
+    "Do NOT mention that multiple models were used, and do NOT refer to the sources. Produce ONE authoritative final answer addressed directly to the user.",
+    "",
+    "First, internally analyze the panel along these dimensions: consensus (points most sources agree on — treat as higher-confidence), contradictions (where they disagree — resolve with your own judgment), partial coverage, unique insights only one source surfaced, and blind spots every source missed. Then write the best possible final answer grounded in that analysis — more complete and correct than any single response, with no filler.",
+    "",
+    "=== PANEL RESPONSES ===",
+    panel,
+    "=== END PANEL RESPONSES ===",
+    "",
+    "Now write the final answer to the user's original request.",
+  ].join("\n");
+}
+
+// Fusion tuning. Overridable per-combo via settings.comboStrategies[name].
+const FUSION_DEFAULTS = {
+  minPanel: 2,             // answers needed before stragglers get a grace window
+  stragglerGraceMs: 8000,  // wait this long for laggards once quorum is reached
+  panelHardTimeoutMs: 90000, // absolute cap so one hung model can't stall forever
+};
+
+// Resolve a Response (or {__error}) within ms; the loser keeps running but is ignored.
+function withTimeout(promise, ms) {
+  return new Promise((resolve) => {
+    const t = setTimeout(() => resolve({ __timeout: true }), ms);
+    Promise.resolve(promise)
+      .then((v) => { clearTimeout(t); resolve(v); })
+      .catch((e) => { clearTimeout(t); resolve({ __error: e }); });
+  });
+}
+
+/**
+ * Collect panel responses with quorum-grace: as soon as `minPanel` calls succeed,
+ * start a short grace timer for the rest, then proceed with whatever arrived. This
+ * caps the straggler penalty (the slowest model otherwise dominates wall time) while
+ * still preferring a full panel when everyone is fast. Bounded by a hard timeout.
+ * Returns a sparse array aligned to `calls` (undefined = not yet / dropped).
+ */
+function collectPanel(calls, { minPanel, stragglerGraceMs, panelHardTimeoutMs }) {
+  return new Promise((resolve) => {
+    const out = new Array(calls.length);
+    let settled = 0;
+    let ok = 0;
+    let finished = false;
+    let graceTimer = null;
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(hardTimer);
+      if (graceTimer) clearTimeout(graceTimer);
+      resolve(out);
+    };
+    const hardTimer = setTimeout(finish, panelHardTimeoutMs);
+    calls.forEach((p, i) => {
+      Promise.resolve(p)
+        .then((v) => { out[i] = v; })
+        .catch((e) => { out[i] = { __error: e }; })
+        .finally(() => {
+          settled++;
+          if (out[i] && out[i].ok) ok++;
+          if (settled === calls.length) return finish();
+          if (ok >= minPanel && !graceTimer) graceTimer = setTimeout(finish, stragglerGraceMs);
+        });
+    });
+  });
+}
+
+/**
+ * Handle a fusion combo: fan the prompt out to every panel model in parallel,
+ * then a judge model synthesizes one final answer from all panel responses.
+ *
+ * Panel calls are forced non-streaming with tools stripped (the judge needs
+ * complete prose to synthesize). The judge call keeps the client's original
+ * stream flag + tools, so streaming and downstream tool use still work.
+ *
+ * Speed: quorum-grace collection caps the straggler penalty. Quality: the judge
+ * runs the consensus/contradiction/blind-spot analysis before writing.
+ *
+ * Degrades gracefully: 0 panel answers -> 503, exactly 1 -> return it directly.
+ *
+ * @param {Object} options
+ * @param {Object} options.body - Request body (client format)
+ * @param {string[]} options.models - Panel model strings
+ * @param {Function} options.handleSingleModel - (body, modelStr) => Promise<Response>
+ * @param {Object} options.log - Logger
+ * @param {string} [options.comboName] - Combo name (logging)
+ * @param {string} [options.judgeModel] - Judge model; falls back to panel[0]
+ * @param {Object} [options.tuning] - Override FUSION_DEFAULTS (minPanel, grace, timeout)
+ * @returns {Promise<Response>}
+ */
+export async function handleFusionChat({ body, models, handleSingleModel, log, comboName, judgeModel, tuning }) {
+  const panel = Array.isArray(models) ? models.filter(Boolean) : [];
+  if (panel.length === 0) {
+    return new Response(
+      JSON.stringify({ error: { message: "Fusion combo has no models" } }),
+      { status: 400, headers: { "Content-Type": "application/json" } }
+    );
+  }
+
+  // A single-model fusion has nothing to fuse — just answer directly.
+  if (panel.length === 1) {
+    return handleSingleModel(body, panel[0]);
+  }
+
+  const cfg = { ...FUSION_DEFAULTS, ...(tuning || {}) };
+  const minPanel = Math.min(Math.max(2, cfg.minPanel), panel.length);
+  const judge = judgeModel && judgeModel.trim() ? judgeModel.trim() : panel[0];
+  log.info("FUSION", `Combo "${comboName}" | panel=${panel.length} [${panel.join(", ")}] | judge=${judge} | quorum=${minPanel}`);
+
+  // 1. Fan out to the panel in parallel: non-streaming, tools stripped (we want prose).
+  const { tools, tool_choice, ...rest } = body;
+  const panelBody = { ...rest, stream: false };
+
+  // Flatten tool turns to prose so panel models keep context without emitting tool_calls.
+  if (Array.isArray(panelBody.messages)) {
+    panelBody.messages = flattenToolHistory(panelBody.messages);
+  } else if (Array.isArray(panelBody.input)) {
+    panelBody.input = flattenToolHistory(panelBody.input);
+  }
+
+  const t0 = Date.now();
+  const calls = panel.map((m) => withTimeout(handleSingleModel(panelBody, m, true), cfg.panelHardTimeoutMs));
+  const settled = await collectPanel(calls, { ...cfg, minPanel });
+  log.info("FUSION", `fan-out collected in ${Date.now() - t0}ms`);
+
+  // 2. Collect successful answers.
+  const answers = [];
+  for (let i = 0; i < settled.length; i++) {
+    const res = settled[i];
+    const model = panel[i];
+    if (!res) { log.warn("FUSION", `Panel ${model} dropped (straggler/timeout)`); continue; }
+    if (res.__timeout) { log.warn("FUSION", `Panel ${model} timed out`); continue; }
+    if (res.__error) { log.warn("FUSION", `Panel ${model} threw`, { error: res.__error?.message || String(res.__error) }); continue; }
+    if (!res.ok) { log.warn("FUSION", `Panel ${model} failed`, { status: res.status }); continue; }
+    try {
+      const json = await res.clone().json();
+      const text = extractPanelText(json);
+      if (text) {
+        answers.push({ model, text });
+        log.info("FUSION", `Panel ${model} ok (${text.length} chars)`);
+      } else {
+        log.warn("FUSION", `Panel ${model} returned empty content`);
+      }
+    } catch (e) {
+      log.warn("FUSION", `Panel ${model} unparseable`, { error: e.message || String(e) });
+    }
+  }
+
+  // 3. Degrade gracefully when the panel is too thin to fuse.
+  if (answers.length === 0) {
+    log.warn("FUSION", "All panel models failed");
+    return new Response(
+      JSON.stringify({ error: { message: "All fusion panel models failed" } }),
+      { status: 503, headers: { "Content-Type": "application/json" } }
+    );
+  }
+  if (answers.length === 1) {
+    log.info("FUSION", `Only ${answers[0].model} succeeded — answering directly (no fusion)`);
+    return handleSingleModel(body, answers[0].model);
+  }
+
+  // 4. Judge analyzes + writes one final answer (streams to client if requested).
+  const judgeBody = appendUserTurn(body, buildJudgePrompt(answers));
+  log.info("FUSION", `Judging ${answers.length} answers with ${judge}`);
+  return handleSingleModel(judgeBody, judge);
+}
diff --git a/open-sse/services/compact.js b/open-sse/services/compact.js
new file mode 100644
index 0000000..812cd27
--- /dev/null
+++ b/open-sse/services/compact.js
@@ -0,0 +1,71 @@
+/**
+ * Shared combo (model combo) handling with fallback support
+ */
+
+/**
+ * Get combo models from combos data
+ * @param {string} modelStr - Model string to check
+ * @param {Array|Object} combosData - Array of combos or object with combos
+ * @returns {string[]|null} Array of models or null if not a combo
+ */
+export function getComboModelsFromData(modelStr, combosData) {
+  // Don't check if it's in provider/model format
+  if (modelStr.includes("/")) return null;
+  
+  // Handle both array and object formats
+  const combos = Array.isArray(combosData) ? combosData : (combosData?.combos || []);
+  
+  const combo = combos.find(c => c.name === modelStr);
+  if (combo && combo.models && combo.models.length > 0) {
+    return combo.models;
+  }
+  return null;
+}
+
+/**
+ * Handle combo chat with fallback
+ * @param {Object} options
+ * @param {Object} options.body - Request body
+ * @param {string[]} options.models - Array of model strings to try
+ * @param {Function} options.handleSingleModel - Function to handle single model: (body, modelStr) => Promise<Response>
+ * @param {Object} options.log - Logger object
+ * @returns {Promise<Response>}
+ */
+export async function handleComboChat({ body, models, handleSingleModel, log }) {
+  let lastError = null;
+
+  for (let i = 0; i < models.length; i++) {
+    const modelStr = models[i];
+    log.info("COMBO", `Trying model ${i + 1}/${models.length}: ${modelStr}`);
+
+    let result;
+    try {
+      result = await handleSingleModel(body, modelStr);
+    } catch (e) {
+      lastError = `${modelStr}: ${e.message}`;
+      log.warn("COMBO", `Model threw exception, trying next`, { model: modelStr, error: e.message });
+      continue;
+    }
+
+    // Success or client error - return response
+    if (result.ok || result.status < 500) {
+      return result;
+    }
+
+    // 5xx error - try next model
+    lastError = `${modelStr}: ${result.statusText || result.status}`;
+    log.warn("COMBO", `Model failed, trying next`, { model: modelStr, status: result.status });
+  }
+
+  log.warn("COMBO", "All models failed");
+  
+  // Return 503 with last error
+  return new Response(
+    JSON.stringify({ error: lastError || "All combo models unavailable" }),
+    { 
+      status: 503, 
+      headers: { "Content-Type": "application/json" }
+    }
+  );
+}
+
diff --git a/open-sse/services/copilotModels.js b/open-sse/services/copilotModels.js
new file mode 100644
index 0000000..940f8ad
--- /dev/null
+++ b/open-sse/services/copilotModels.js
@@ -0,0 +1,155 @@
+/**
+ * GitHub Copilot model catalog fetcher.
+ *
+ * Calls Copilot's `GET /models` endpoint to get the live catalog for an
+ * authenticated account, so `/v1/models` reflects what the account can
+ * actually use (e.g. newly shipped `claude-opus-4.8`, `gpt-5.5`) instead of
+ * the hand-maintained static registry, which inevitably lags behind.
+ *
+ * Returns chat-capable models the account's policy allows. Embeddings and
+ * disabled models are filtered out.
+ */
+
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+import { GITHUB_COPILOT } from "../config/appConstants.js";
+import { refreshCopilotToken } from "./tokenRefresh.js";
+
+const MODELS_URL = "https://api.githubcopilot.com/models";
+const FETCH_TIMEOUT_MS = 10_000;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes per credential
+
+/** @type {Map<string, { expiresAt: number, models: any[] }>} */
+const catalogCache = new Map();
+
+function cacheKey(credentials) {
+  return credentials?.providerSpecificData?.copilotToken
+    || credentials?.accessToken
+    || "copilot-anonymous";
+}
+
+function buildHeaders(token) {
+  return {
+    "Authorization": `Bearer ${token}`,
+    "Content-Type": "application/json",
+    "Copilot-Integration-Id": "vscode-chat",
+    "editor-version": `vscode/${GITHUB_COPILOT.VSCODE_VERSION}`,
+    "editor-plugin-version": `copilot-chat/${GITHUB_COPILOT.COPILOT_CHAT_VERSION}`,
+    "user-agent": GITHUB_COPILOT.USER_AGENT,
+    "x-github-api-version": GITHUB_COPILOT.API_VERSION,
+  };
+}
+
+async function fetchCatalogRaw(token, signal) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const response = await proxyAwareFetch(MODELS_URL, {
+      method: "GET",
+      headers: buildHeaders(token),
+      cache: "no-store",
+      signal: signal || controller.signal,
+    });
+    if (!response.ok) {
+      const err = new Error(`Copilot /models returned ${response.status}`);
+      err.status = response.status;
+      throw err;
+    }
+    const data = await response.json();
+    return Array.isArray(data?.data) ? data.data : [];
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// Keep only chat models the account is allowed to use. The static registry
+// surfaced disabled/embedding entries inconsistently; here we trust upstream.
+function expandCatalog(raw) {
+  const seen = new Set();
+  const models = [];
+  for (const m of raw) {
+    if (!m || typeof m !== "object") continue;
+    if (m.capabilities?.type !== "chat") continue;
+    if (m.policy && m.policy.state !== "enabled") continue;
+    const id = m.id;
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    models.push({ id, name: m.name || id });
+  }
+  return models;
+}
+
+/**
+ * Resolve the live Copilot model catalog for a connection.
+ *
+ * @param {object} credentials Connection record (accessToken, refreshToken,
+ *   providerSpecificData {copilotToken, copilotTokenExpiresAt}).
+ * @param {object} [options]
+ * @param {boolean} [options.forceRefresh] Bypass the per-credential cache.
+ * @param {object}  [options.log] Logger.
+ * @param {function} [options.onCredentialsRefreshed] Persist a refreshed
+ *   Copilot token back to your store. Called with `{ copilotToken,
+ *   copilotTokenExpiresAt }` whenever a 401 triggers a refresh.
+ * @returns {Promise<{ models: object[] } | null>}
+ */
+export async function resolveCopilotModels(credentials, options = {}) {
+  const token = credentials?.providerSpecificData?.copilotToken || credentials?.accessToken;
+  if (!token) {
+    options.log?.debug?.("COPILOT_MODELS", "No copilotToken/accessToken; skipping live fetch");
+    return null;
+  }
+
+  const key = cacheKey(credentials);
+  const now = Date.now();
+  if (!options.forceRefresh) {
+    const cached = catalogCache.get(key);
+    if (cached && cached.expiresAt > now) {
+      return { models: cached.models };
+    }
+  }
+
+  let raw;
+  try {
+    raw = await fetchCatalogRaw(token, options.signal);
+  } catch (err) {
+    // A 401/403 means the Copilot token is stale — refresh from the GitHub
+    // access token and retry once.
+    if (err && (err.status === 401 || err.status === 403) && credentials.accessToken) {
+      options.log?.info?.("COPILOT_MODELS", `Got ${err.status}; refreshing Copilot token`);
+      const refreshed = await refreshCopilotToken(credentials.accessToken);
+      if (refreshed?.token) {
+        if (typeof options.onCredentialsRefreshed === "function") {
+          try {
+            await options.onCredentialsRefreshed({
+              copilotToken: refreshed.token,
+              copilotTokenExpiresAt: refreshed.expiresAt,
+            });
+          } catch (e) {
+            options.log?.warn?.("COPILOT_MODELS", `onCredentialsRefreshed failed: ${e?.message || e}`);
+          }
+        }
+        try {
+          raw = await fetchCatalogRaw(refreshed.token, options.signal);
+        } catch (err2) {
+          options.log?.warn?.("COPILOT_MODELS", `Retry after refresh failed: ${err2?.message || err2}`);
+          return null;
+        }
+      } else {
+        options.log?.warn?.("COPILOT_MODELS", "Token refresh did not return a token");
+        return null;
+      }
+    } else {
+      options.log?.warn?.("COPILOT_MODELS", `Live model fetch failed: ${err?.message || err}`);
+      return null;
+    }
+  }
+
+  const models = expandCatalog(raw);
+  if (!models.length) return null;
+
+  catalogCache.set(key, { expiresAt: now + CACHE_TTL_MS, models });
+  return { models };
+}
+
+export function clearCopilotModelCache() {
+  catalogCache.clear();
+}
diff --git a/open-sse/services/kimchiModels.js b/open-sse/services/kimchiModels.js
new file mode 100644
index 0000000..15d0936
--- /dev/null
+++ b/open-sse/services/kimchiModels.js
@@ -0,0 +1,176 @@
+import { createHash } from "crypto";
+
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+
+export const KIMCHI_API = "https://llm.kimchi.dev";
+export const KIMCHI_USER_AGENT = "kimchi/0.1.40";
+
+const FETCH_TIMEOUT_MS = 20_000;
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+
+/** @type {Map<string, { expiresAt: number, models: object[], rawModels: object[] }>} */
+const catalogCache = new Map();
+/** @type {Map<string, object>} */
+const metadataByModelId = new Map();
+
+function normalizeKimchiEndpoint(endpoint) {
+  const raw = typeof endpoint === "string" ? endpoint.trim() : "";
+  return (raw || KIMCHI_API).replace(/\/+$/, "");
+}
+
+export function buildKimchiModelsUrl(endpoint) {
+  return `${normalizeKimchiEndpoint(endpoint)}/v1/models/metadata?include_in_cli=true`;
+}
+
+function readToken(credentials) {
+  return (
+    credentials?.accessToken
+    || credentials?.apiKey
+    || credentials?.providerSpecificData?.apiKey
+    || null
+  );
+}
+
+function cacheKey(credentials, endpoint) {
+  const psd = credentials?.providerSpecificData || {};
+  const seed = psd.userId || psd.username || credentials?.refreshToken || readToken(credentials) || "anonymous";
+  return createHash("sha256")
+    .update(`kimchi:${normalizeKimchiEndpoint(endpoint)}:${seed}`)
+    .digest("hex");
+}
+
+function toModelKind(inputModalities) {
+  return Array.isArray(inputModalities) && inputModalities.includes("image")
+    ? "imageToText"
+    : "llm";
+}
+
+export function normalizeKimchiModel(item) {
+  if (!item || typeof item !== "object") return null;
+  const id = item.slug || item.id || item.model || item.name;
+  if (typeof id !== "string" || id.trim() === "") return null;
+
+  const inputModalities = Array.isArray(item.input_modalities)
+    ? item.input_modalities.filter((value) => value === "text" || value === "image")
+    : [];
+  const limits = item.limits && typeof item.limits === "object" ? item.limits : {};
+  const contextLength = Number(limits.context_window || item.contextLength || item.context_length) || undefined;
+  const maxOutputTokens = Number(limits.max_output_tokens || item.maxOutputTokens || item.max_output_tokens) || undefined;
+  const upstreamProvider = typeof item.provider === "string" ? item.provider : "";
+  const reasoning = item.reasoning === true;
+  const kind = toModelKind(inputModalities);
+
+  const model = {
+    ...item,
+    id: id.trim(),
+    name: String(item.display_name || item.displayName || item.name || id).trim(),
+    provider: upstreamProvider,
+    upstreamProvider,
+    reasoning,
+    inputModalities,
+    kind,
+    type: kind,
+    capabilities: {
+      vision: inputModalities.includes("image"),
+      reasoning,
+      ...(contextLength ? { contextWindow: contextLength } : {}),
+      ...(maxOutputTokens ? { maxOutput: maxOutputTokens } : {}),
+      ...(upstreamProvider ? { upstreamProvider } : {}),
+    },
+    ...(contextLength ? { contextLength } : {}),
+    ...(maxOutputTokens ? { maxOutputTokens } : {}),
+  };
+
+  if (upstreamProvider === "anthropic") {
+    model.compat = { supportsReasoningEffort: false, cacheControlFormat: "anthropic" };
+  }
+
+  return model;
+}
+
+function rememberModels(models) {
+  for (const model of models || []) {
+    if (!model?.id) continue;
+    metadataByModelId.set(model.id, model);
+    metadataByModelId.set(model.id.toLowerCase(), model);
+  }
+}
+
+export function getCachedKimchiModelMetadata(modelId) {
+  if (typeof modelId !== "string" || modelId.trim() === "") return null;
+  const raw = modelId.includes("/") ? modelId.split("/").pop() : modelId;
+  return metadataByModelId.get(raw) || metadataByModelId.get(raw.toLowerCase()) || null;
+}
+
+async function fetchKimchiCatalogRaw(token, endpoint, options = {}) {
+  const url = buildKimchiModelsUrl(endpoint);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(new Error("Kimchi models fetch timeout")), FETCH_TIMEOUT_MS);
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, controller.signal])
+    : controller.signal;
+
+  try {
+    const response = await proxyAwareFetch(url, {
+      method: "GET",
+      headers: {
+        "Accept": "application/json",
+        "Authorization": `Bearer ${token}`,
+        "User-Agent": KIMCHI_USER_AGENT,
+      },
+      cache: "no-store",
+      signal,
+    }, options.proxyOptions || null);
+
+    if (!response.ok) {
+      const error = new Error(`Kimchi models ${response.status}: ${response.statusText}`);
+      error.status = response.status;
+      error.retryable = RETRYABLE_STATUSES.has(response.status);
+      throw error;
+    }
+
+    const data = await response.json();
+    return Array.isArray(data?.models) ? data.models : [];
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function resolveKimchiModels(credentials, options = {}) {
+  const token = readToken(credentials);
+  if (!token) return null;
+
+  const endpoint = credentials?.providerSpecificData?.kimchiEndpoint || options.endpoint || KIMCHI_API;
+  const key = cacheKey(credentials, endpoint);
+  const now = Date.now();
+  if (!options.forceRefresh) {
+    const cached = catalogCache.get(key);
+    if (cached && cached.expiresAt > now) return cached;
+  }
+
+  let rawModels;
+  try {
+    rawModels = await fetchKimchiCatalogRaw(token, endpoint, options);
+  } catch (error) {
+    options.log?.warn?.("KIMCHI_MODELS", error.message);
+    return null;
+  }
+
+  const models = rawModels.map(normalizeKimchiModel).filter(Boolean);
+  if (models.length === 0) return null;
+
+  rememberModels(models);
+  const entry = {
+    expiresAt: Date.now() + CACHE_TTL_MS,
+    models,
+    rawModels,
+  };
+  catalogCache.set(key, entry);
+  return entry;
+}
+
+export function clearKimchiCatalog() {
+  catalogCache.clear();
+  metadataByModelId.clear();
+}
diff --git a/open-sse/services/kiroModels.js b/open-sse/services/kiroModels.js
new file mode 100644
index 0000000..6b52413
--- /dev/null
+++ b/open-sse/services/kiroModels.js
@@ -0,0 +1,332 @@
+/**
+ * Kiro model catalog fetcher.
+ *
+ * Calls AWS CodeWhisperer's `ListAvailableModels` endpoint to get the live
+ * catalog for an authenticated Kiro account, then expands each upstream model
+ * into 9router-shaped variants:
+ *
+ *   {upstream}                          - base model
+ *   {upstream}-thinking                 - same model, thinking on at request time
+ *   {upstream}-agentic                  - same model, chunked-write prompt prepended
+ *   {upstream}-thinking-agentic         - both
+ *
+ * The `-thinking` and `-agentic` suffixes do not exist on the Kiro upstream
+ * API. They are 9router fictions and the `openai-to-kiro` translator strips
+ * them before the request leaves this process.
+ *
+ * The runtime UA is built to match what Kiro IDE itself sends, because the
+ * upstream rejects requests with malformed `User-Agent` headers (returns 400
+ * "format of value 'os/win/10 lang/js ...' is invalid").
+ */
+
+import { v4 as uuidv4 } from "uuid";
+import { createHash } from "crypto";
+import { refreshKiroToken } from "./tokenRefresh.js";
+
+const KIRO_RUNTIME_SDK_VERSION = "1.0.0";
+const KIRO_AGENT_OS = "windows";
+const KIRO_AGENT_OS_VERSION = "10.0.26200";
+const KIRO_NODE_VERSION = "22.21.1";
+const KIRO_VERSION = "0.10.32";
+
+const DEFAULT_REGION = "us-east-1";
+const FETCH_TIMEOUT_MS = 30_000;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes per credential
+
+/** @type {Map<string, { expiresAt: number, models: any[] }>} */
+const catalogCache = new Map();
+
+/**
+ * Strip the `-agentic` and/or `-thinking` suffixes from a synthetic id, if
+ * any. Used only for display naming when a Kiro upstream id happens to look
+ * synthetic (defensive).
+ */
+function stripSyntheticSuffixes(id) {
+  let out = id;
+  if (out.endsWith("-agentic")) out = out.slice(0, -"-agentic".length);
+  if (out.endsWith("-thinking")) out = out.slice(0, -"-thinking".length);
+  return out;
+}
+
+/**
+ * Extract region from a profileArn like
+ *   arn:aws:codewhisperer:us-east-1:123456789012:profile/ABC
+ */
+function regionFromProfileArn(profileArn) {
+  if (!profileArn || typeof profileArn !== "string") return DEFAULT_REGION;
+  const parts = profileArn.split(":");
+  if (parts.length >= 4 && parts[3]) return parts[3];
+  return DEFAULT_REGION;
+}
+
+/**
+ * Build the per-account fingerprint headers Kiro upstream validates.
+ * Keyed off whatever stable identifier we have for this credential, so the
+ * same account always presents the same machineId.
+ */
+function buildKiroFingerprintHeaders(credentials) {
+  const seed =
+    credentials?.providerSpecificData?.clientId
+    || credentials?.refreshToken
+    || credentials?.providerSpecificData?.profileArn
+    || credentials?.accessToken
+    || "kiro-anonymous";
+  const machineId = createHash("sha256").update(String(seed)).digest("hex");
+
+  const userAgent =
+    `aws-sdk-js/${KIRO_RUNTIME_SDK_VERSION} ua/2.1 ` +
+    `os/${KIRO_AGENT_OS}#${KIRO_AGENT_OS_VERSION} ` +
+    `lang/js md/nodejs#${KIRO_NODE_VERSION} ` +
+    `api/codewhispererruntime#${KIRO_RUNTIME_SDK_VERSION} m/N,E ` +
+    `KiroIDE-${KIRO_VERSION}-${machineId}`;
+  const amzUserAgent = `aws-sdk-js/${KIRO_RUNTIME_SDK_VERSION} KiroIDE-${KIRO_VERSION}-${machineId}`;
+
+  return {
+    "User-Agent": userAgent,
+    "x-amz-user-agent": amzUserAgent,
+    "x-amzn-kiro-agent-mode": "vibe",
+    "x-amzn-codewhisperer-optout": "true",
+    "amz-sdk-request": "attempt=1; max=1",
+    "amz-sdk-invocation-id": uuidv4(),
+    "Accept": "application/json"
+  };
+}
+
+/**
+ * Build the synthetic 9router variant set for a single upstream Kiro model.
+ *
+ * Returns objects shaped for `PROVIDER_MODELS` (`{ id, name }`) so they can
+ * be slotted directly into the existing model registry.
+ *
+ * The `auto` model is special: Kiro picks the underlying model server-side,
+ * so the chunked-write `-agentic` prompt is not meaningful (the prompt
+ * targets coding-agent file writes). Match CLIProxyAPIPlus and skip
+ * `-agentic` / `-thinking-agentic` for `auto`.
+ */
+function buildVariants(upstream, displayName) {
+  const safeUpstream = stripSyntheticSuffixes(upstream);
+  const display = displayName || `Kiro ${safeUpstream}`;
+  const isAuto = safeUpstream === "auto";
+
+  const variants = [
+    {
+      id: safeUpstream,
+      name: display,
+      capabilities: { thinking: false, agentic: false }
+    },
+    {
+      id: `${safeUpstream}-thinking`,
+      name: `${display} (Thinking)`,
+      capabilities: { thinking: true, agentic: false }
+    }
+  ];
+
+  if (!isAuto) {
+    variants.push({
+      id: `${safeUpstream}-agentic`,
+      name: `${display} (Agentic)`,
+      capabilities: { thinking: false, agentic: true }
+    });
+    variants.push({
+      id: `${safeUpstream}-thinking-agentic`,
+      name: `${display} (Thinking + Agentic)`,
+      capabilities: { thinking: true, agentic: true }
+    });
+  }
+
+  return variants;
+}
+
+/**
+ * Format the human-friendly display name for a Kiro model, including the
+ * rate multiplier when it is something other than 1.0x.
+ */
+function formatDisplayName(modelName, modelId, rateMultiplier) {
+  const base = (modelName || modelId || "Kiro").trim();
+  const rate = Number(rateMultiplier);
+  if (!Number.isFinite(rate) || Math.abs(rate - 1.0) < 1e-9 || rate <= 0) {
+    return `Kiro ${base}`;
+  }
+  // Locale-independent decimal formatting.
+  const rateStr = rate.toFixed(1).replace(",", ".");
+  return `Kiro ${base} (${rateStr}x credit)`;
+}
+
+/**
+ * Fetch the raw model catalog from Kiro. Returns the array under `.models`
+ * from the API response, or throws on network/HTTP error.
+ */
+async function fetchKiroCatalogRaw(credentials, signal) {
+  const profileArn = credentials?.providerSpecificData?.profileArn || "";
+  const region = regionFromProfileArn(profileArn);
+  const params = new URLSearchParams();
+  params.set("origin", "AI_EDITOR");
+  if (profileArn) params.set("profileArn", profileArn);
+  const url = `https://q.${region}.amazonaws.com/ListAvailableModels?${params.toString()}`;
+
+  const headers = {
+    ...buildKiroFingerprintHeaders(credentials),
+    "Authorization": `Bearer ${credentials?.accessToken || ""}`
+  };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort("timeout"), FETCH_TIMEOUT_MS);
+  // Forward outer cancellation if any.
+  if (signal && typeof signal.addEventListener === "function") {
+    signal.addEventListener("abort", () => controller.abort(signal.reason));
+  }
+
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      headers,
+      signal: controller.signal
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    const err = new Error(`Kiro ListAvailableModels ${response.status}: ${text || response.statusText}`);
+    err.status = response.status;
+    err.body = text;
+    throw err;
+  }
+
+  const data = await response.json();
+  const models = Array.isArray(data?.models) ? data.models : [];
+  return models;
+}
+
+/**
+ * Build a stable cache key for a Kiro credential. Uses the most stable id we
+ * have available so different login sessions for the same account share a
+ * cache entry.
+ */
+function cacheKey(credentials) {
+  const psd = credentials?.providerSpecificData || {};
+  const seed =
+    psd.profileArn
+    || psd.clientId
+    || credentials?.refreshToken
+    || credentials?.accessToken
+    || "anonymous";
+  return createHash("sha256").update(`kiro:${seed}`).digest("hex");
+}
+
+/**
+ * Resolve the live Kiro model catalog for a credential and expand each entry
+ * into 9router variants (`-thinking`, `-agentic`, `-thinking-agentic`).
+ *
+ * On any error (network, 4xx, 5xx), returns `null` so callers can fall back
+ * to the static catalog without taking down the dashboard or `/v1/models`.
+ *
+ * @param {object} credentials Connection record (accessToken, refreshToken,
+ *   providerSpecificData {profileArn, authMethod, clientId, clientSecret, region})
+ * @param {object} [options]
+ * @param {boolean} [options.forceRefresh] Bypass the per-credential cache.
+ * @param {object}  [options.log] Logger.
+ * @param {function} [options.onCredentialsRefreshed] Persist refreshed token
+ *   back to your credential store. Called with `{ accessToken, refreshToken,
+ *   expiresIn }` whenever a 401 triggers a token refresh.
+ * @returns {Promise<{ models: object[], rawModels: object[] } | null>}
+ */
+export async function resolveKiroModels(credentials, options = {}) {
+  if (!credentials || !credentials.accessToken) {
+    options.log?.debug?.("KIRO_MODELS", "No accessToken; skipping live fetch");
+    return null;
+  }
+
+  const key = cacheKey(credentials);
+  const now = Date.now();
+  if (!options.forceRefresh) {
+    const cached = catalogCache.get(key);
+    if (cached && cached.expiresAt > now) {
+      return { models: cached.models, rawModels: cached.rawModels };
+    }
+  }
+
+  let raw;
+  try {
+    raw = await fetchKiroCatalogRaw(credentials, options.signal);
+  } catch (err) {
+    if (err && err.status === 401 && credentials.refreshToken) {
+      options.log?.info?.("KIRO_MODELS", "Got 401 from Kiro; refreshing token");
+      const refreshed = await refreshKiroToken(
+        credentials.refreshToken,
+        credentials.providerSpecificData,
+        options.log
+      );
+      if (refreshed?.accessToken) {
+        const next = { ...credentials, ...refreshed };
+        if (typeof options.onCredentialsRefreshed === "function") {
+          try { await options.onCredentialsRefreshed(refreshed); } catch (e) {
+            options.log?.warn?.("KIRO_MODELS", `onCredentialsRefreshed failed: ${e?.message || e}`);
+          }
+        }
+        try {
+          raw = await fetchKiroCatalogRaw(next, options.signal);
+          // Update the in-memory credential reference too so retry logic uses
+          // the fresh token consistently.
+          credentials.accessToken = next.accessToken;
+          if (next.refreshToken) credentials.refreshToken = next.refreshToken;
+        } catch (err2) {
+          options.log?.warn?.("KIRO_MODELS", `Retry after refresh failed: ${err2?.message || err2}`);
+          return null;
+        }
+      } else {
+        options.log?.warn?.("KIRO_MODELS", "Token refresh did not return accessToken");
+        return null;
+      }
+    } else {
+      options.log?.warn?.("KIRO_MODELS", `ListAvailableModels failed: ${err?.message || err}`);
+      return null;
+    }
+  }
+
+  const expanded = [];
+  for (const m of raw) {
+    if (!m || typeof m !== "object") continue;
+    const upstreamId = m.modelId || m.id;
+    if (!upstreamId) continue;
+    const display = formatDisplayName(m.modelName, upstreamId, m.rateMultiplier);
+    const ctx = Number(m?.tokenLimits?.maxInputTokens) || 200_000;
+    for (const v of buildVariants(upstreamId, display)) {
+      expanded.push({
+        ...v,
+        // Carry over context window + raw upstream metadata so the caller
+        // (e.g. the dashboard models endpoint) can render it.
+        contextLength: ctx,
+        rateMultiplier: Number.isFinite(Number(m.rateMultiplier)) ? Number(m.rateMultiplier) : 1.0,
+        upstreamModelId: upstreamId,
+        description: m.description || ""
+      });
+    }
+  }
+
+  catalogCache.set(key, {
+    expiresAt: now + CACHE_TTL_MS,
+    models: expanded,
+    rawModels: raw
+  });
+
+  return { models: expanded, rawModels: raw };
+}
+
+/**
+ * Drop any cached catalog for this credential. Call this after rotating /
+ * importing tokens so the next fetch is fresh.
+ */
+export function invalidateKiroModelCache(credentials) {
+  if (!credentials) return;
+  catalogCache.delete(cacheKey(credentials));
+}
+
+/**
+ * Drop the entire in-memory cache. Mostly for tests / manual debug.
+ */
+export function clearKiroModelCache() {
+  catalogCache.clear();
+}
diff --git a/open-sse/services/model.js b/open-sse/services/model.js
new file mode 100644
index 0000000..6558d70
--- /dev/null
+++ b/open-sse/services/model.js
@@ -0,0 +1,136 @@
+import REGISTRY from "../providers/registry/index.js";
+
+// Alias→id derived from registry single-source: id→id, alias→id, aliases[]→id.
+// Media-only providers without a registry transport entry keep explicit aliases here.
+const MEDIA_ONLY_ALIASES = {
+  el: "elevenlabs",
+  jina: "jina-ai",
+  "jina-ai": "jina-ai",
+  polly: "aws-polly",
+  "aws-polly": "aws-polly",
+};
+
+const ALIAS_TO_PROVIDER_ID = { ...MEDIA_ONLY_ALIASES };
+for (const entry of REGISTRY) {
+  ALIAS_TO_PROVIDER_ID[entry.id] = entry.id;
+  if (entry.alias) ALIAS_TO_PROVIDER_ID[entry.alias] = entry.id;
+  for (const a of entry.aliases || []) ALIAS_TO_PROVIDER_ID[a] = entry.id;
+}
+
+/**
+ * Resolve provider alias to provider ID
+ */
+export function resolveProviderAlias(aliasOrId) {
+  return ALIAS_TO_PROVIDER_ID[aliasOrId] || aliasOrId;
+}
+
+/**
+ * Parse model string: "alias/model" or "provider/model" or just alias
+ */
+export function parseModel(modelStr) {
+  if (!modelStr) {
+    return { provider: null, model: null, isAlias: false, providerAlias: null };
+  }
+
+  // Check if standard format: provider/model or alias/model
+  if (modelStr.includes("/")) {
+    const firstSlash = modelStr.indexOf("/");
+    const providerOrAlias = modelStr.slice(0, firstSlash);
+    const model = modelStr.slice(firstSlash + 1);
+    const provider = resolveProviderAlias(providerOrAlias);
+    return { provider, model, isAlias: false, providerAlias: providerOrAlias };
+  }
+
+  // Alias format (model alias, not provider alias)
+  return {
+    provider: null,
+    model: modelStr,
+    isAlias: true,
+    providerAlias: null,
+  };
+}
+
+/**
+ * Resolve model alias from aliases object
+ * Format: { "alias": "provider/model" }
+ */
+export function resolveModelAliasFromMap(alias, aliases) {
+  if (!aliases) return null;
+
+  // Check if alias exists
+  const resolved = aliases[alias];
+  if (!resolved) return null;
+
+  // Resolved value is "provider/model" format
+  if (typeof resolved === "string" && resolved.includes("/")) {
+    const firstSlash = resolved.indexOf("/");
+    const providerOrAlias = resolved.slice(0, firstSlash);
+    return {
+      provider: resolveProviderAlias(providerOrAlias),
+      model: resolved.slice(firstSlash + 1),
+    };
+  }
+
+  // Or object { provider, model }
+  if (typeof resolved === "object" && resolved.provider && resolved.model) {
+    return {
+      provider: resolveProviderAlias(resolved.provider),
+      model: resolved.model,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Get full model info (parse or resolve)
+ * @param {string} modelStr - Model string
+ * @param {object|function} aliasesOrGetter - Aliases object or async function to get aliases
+ */
+export async function getModelInfoCore(modelStr, aliasesOrGetter) {
+  const parsed = parseModel(modelStr);
+
+  if (!parsed.isAlias) {
+    return {
+      provider: parsed.provider,
+      model: parsed.model,
+    };
+  }
+
+  // Get aliases (from object or function)
+  const aliases =
+    typeof aliasesOrGetter === "function"
+      ? await aliasesOrGetter()
+      : aliasesOrGetter;
+
+  // Resolve alias
+  const resolved = resolveModelAliasFromMap(parsed.model, aliases);
+  if (resolved) {
+    return resolved;
+  }
+
+  // Fallback: infer provider from model name prefix
+  return {
+    provider: inferProviderFromModelName(parsed.model),
+    model: parsed.model,
+  };
+}
+
+// Config-driven prefix → provider inference (first match wins, fallback "openai").
+const MODEL_PREFIX_PROVIDERS = [
+  [/^claude-/, "anthropic"],
+  [/^gemini-/, "gemini"],
+  [/^gpt-/, "openai"],
+  [/^o[134]/, "openai"],
+  [/^deepseek-/, "openrouter"],
+];
+
+/**
+ * Infer provider from model name prefix
+ * Used as fallback when no provider prefix or alias is given
+ */
+function inferProviderFromModelName(modelName) {
+  if (!modelName) return "openai";
+  const m = modelName.toLowerCase();
+  return MODEL_PREFIX_PROVIDERS.find(([re]) => re.test(m))?.[1] || "openai";
+}
diff --git a/open-sse/services/oauthCredentialManager.js b/open-sse/services/oauthCredentialManager.js
new file mode 100644
index 0000000..75bebd5
--- /dev/null
+++ b/open-sse/services/oauthCredentialManager.js
@@ -0,0 +1,156 @@
+import {
+  getRefreshLeadMs,
+  isUnrecoverableRefreshError,
+  refreshTokenByProvider,
+} from "./tokenRefresh.js";
+import { PROVIDER_OAUTH } from "../providers/index.js";
+
+// Single source: codex.oauth.maxRefreshAgeMs (8 days) — proactive refresh window
+export const CODEX_MAX_REFRESH_AGE_MS = PROVIDER_OAUTH["codex"]?.maxRefreshAgeMs;
+
+const refreshLocks = new Map();
+
+function parseTimeMs(value) {
+  if (value === undefined || value === null || value === "") return null;
+  if (typeof value === "number") {
+    return value < 1e12 ? value * 1000 : value;
+  }
+
+  const parsed = new Date(value).getTime();
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function toExpiresAt(expiresIn, nowMs = Date.now()) {
+  if (!expiresIn) return null;
+  return new Date(nowMs + expiresIn * 1000).toISOString();
+}
+
+export function getCredentialExpiryMs(credentials) {
+  return parseTimeMs(credentials?.expiresAt ?? credentials?.tokenExpiresAt);
+}
+
+export function getCredentialLastRefreshMs(credentials) {
+  return parseTimeMs(
+    credentials?.lastRefreshAt ??
+    credentials?.lastRefresh ??
+    credentials?.providerSpecificData?.lastRefreshAt
+  );
+}
+
+export function isCodexRefreshStale(credentials, nowMs = Date.now(), maxAgeMs = CODEX_MAX_REFRESH_AGE_MS) {
+  const lastRefreshMs = getCredentialLastRefreshMs(credentials);
+  return !lastRefreshMs || nowMs - lastRefreshMs >= maxAgeMs;
+}
+
+export function shouldRefreshCredentials(provider, credentials, nowMs = Date.now()) {
+  if (!credentials) return false;
+
+  const expiresAtMs = getCredentialExpiryMs(credentials);
+  if (expiresAtMs !== null && expiresAtMs - nowMs < getRefreshLeadMs(provider)) {
+    return true;
+  }
+
+  // Proactive stale refresh for providers declaring oauth.maxRefreshAgeMs (e.g. codex)
+  const maxAgeMs = PROVIDER_OAUTH[provider]?.maxRefreshAgeMs;
+  if (maxAgeMs && credentials.refreshToken && isCodexRefreshStale(credentials, nowMs, maxAgeMs)) {
+    return true;
+  }
+
+  return false;
+}
+
+export function mergeProviderSpecificData(existing, next) {
+  if (!next || typeof next !== "object") return existing;
+  return {
+    ...(existing || {}),
+    ...next,
+  };
+}
+
+export function mergeRefreshedCredentials(provider, currentCredentials, refreshedCredentials, nowMs = Date.now()) {
+  if (!refreshedCredentials) return null;
+  if (isUnrecoverableRefreshError(refreshedCredentials)) return refreshedCredentials;
+
+  const next = {};
+  const nowIso = new Date(nowMs).toISOString();
+
+  if (refreshedCredentials.accessToken) next.accessToken = refreshedCredentials.accessToken;
+  if (refreshedCredentials.apiKey) next.apiKey = refreshedCredentials.apiKey;
+  if (refreshedCredentials.token) next.token = refreshedCredentials.token;
+
+  const refreshToken = refreshedCredentials.refreshToken ?? currentCredentials?.refreshToken;
+  if (refreshToken) next.refreshToken = refreshToken;
+
+  const idToken = refreshedCredentials.idToken ?? currentCredentials?.idToken;
+  if (idToken) next.idToken = idToken;
+
+  if (refreshedCredentials.expiresIn) {
+    next.expiresIn = refreshedCredentials.expiresIn;
+    next.expiresAt = toExpiresAt(refreshedCredentials.expiresIn, nowMs);
+  } else if (refreshedCredentials.expiresAt) {
+    next.expiresAt = refreshedCredentials.expiresAt;
+  }
+
+  if (refreshedCredentials.projectId) next.projectId = refreshedCredentials.projectId;
+
+  if (refreshedCredentials.providerSpecificData) {
+    next.providerSpecificData = mergeProviderSpecificData(
+      currentCredentials?.providerSpecificData,
+      refreshedCredentials.providerSpecificData
+    );
+  }
+
+  if (refreshedCredentials.copilotToken) next.copilotToken = refreshedCredentials.copilotToken;
+  if (refreshedCredentials.copilotTokenExpiresAt) {
+    next.copilotTokenExpiresAt = refreshedCredentials.copilotTokenExpiresAt;
+  }
+
+  // trackRefreshAt providers (e.g. codex) always stamp lastRefreshAt for staleness tracking
+  if (
+    PROVIDER_OAUTH[provider]?.trackRefreshAt ||
+    next.accessToken ||
+    next.apiKey ||
+    next.token ||
+    next.refreshToken ||
+    next.copilotToken
+  ) {
+    next.lastRefreshAt = refreshedCredentials.lastRefreshAt || nowIso;
+  }
+
+  return next;
+}
+
+function getRefreshLockKey(provider, credentials) {
+  const stableId =
+    credentials?.connectionId ||
+    credentials?.id ||
+    credentials?.email ||
+    credentials?.name ||
+    credentials?.refreshToken?.slice?.(-16) ||
+    "default";
+  return `${provider}:${stableId}`;
+}
+
+export async function withCredentialRefreshLock(provider, credentials, refreshFn) {
+  const key = getRefreshLockKey(provider, credentials);
+  const existing = refreshLocks.get(key);
+  if (existing) return existing;
+
+  const pending = Promise.resolve()
+    .then(refreshFn)
+    .finally(() => {
+      refreshLocks.delete(key);
+    });
+
+  refreshLocks.set(key, pending);
+  return pending;
+}
+
+export async function refreshProviderCredentials(provider, credentials, log) {
+  if (!credentials) return null;
+
+  return withCredentialRefreshLock(provider, credentials, async () => {
+    const refreshed = await refreshTokenByProvider(provider, credentials, log);
+    return mergeRefreshedCredentials(provider, credentials, refreshed);
+  });
+}
diff --git a/open-sse/services/projectId.js b/open-sse/services/projectId.js
new file mode 100644
index 0000000..f9a24e1
--- /dev/null
+++ b/open-sse/services/projectId.js
@@ -0,0 +1,306 @@
+/**
+ * Project ID Service - Fetch and cache real Project IDs from Google Cloud Code API
+ *
+ *
+ * Instead of generating random project IDs (e.g. "useful-spark-a1b2c"),
+ * this service fetches the real Project ID bound to the authenticated user's account.
+ * This significantly reduces the risk of being flagged by Google's anti-abuse systems.
+ */
+
+import { CLOUD_CODE_API, LOAD_CODE_ASSIST_HEADERS, LOAD_CODE_ASSIST_METADATA } from "../config/appConstants.js";
+
+// ─── Cache ────────────────────────────────────────────────────────────────────
+// connectionId -> { projectId: string, fetchedAt: number }
+const projectIdCache = new Map();
+
+/** How long a cached project ID is considered fresh (1 hour). */
+const CACHE_TTL_MS = 60 * 60 * 1000;
+
+// ─── Pending-fetch deduplication ─────────────────────────────────────────────
+// connectionId -> { promise: Promise<string|null>, controller: AbortController, startedAt: number }
+const pendingFetches = new Map();
+
+/** Abort and evict a pending fetch that has been running longer than this (2 min). */
+const PENDING_TTL_MS = 2 * 60 * 1000;
+
+// ─── Periodic cleanup ────────────────────────────────────────────────────────
+/** How often the background sweep runs (10 min). */
+const CLEANUP_INTERVAL_MS = 10 * 60 * 1000;
+
+let _cleanupTimer = null;
+
+/** Run one sweep immediately: evict stale cache entries and abort orphaned pending fetches. */
+export function cleanupNow() {
+    const now = Date.now();
+
+    for (const [id, entry] of projectIdCache) {
+        if (!entry || now - entry.fetchedAt >= CACHE_TTL_MS) {
+            projectIdCache.delete(id);
+        }
+    }
+
+    for (const [id, item] of pendingFetches) {
+        if (!item || typeof item.startedAt !== "number") {
+            pendingFetches.delete(id);
+            continue;
+        }
+        if (now - item.startedAt > PENDING_TTL_MS) {
+            try { item.controller.abort(); } catch (_) { /* ignore */ }
+            pendingFetches.delete(id);
+        }
+    }
+}
+
+/** Start the periodic background cleanup (idempotent). Called automatically on module load. */
+export function startCacheCleanup() {
+    if (_cleanupTimer) return;
+    _cleanupTimer = setInterval(() => {
+        try { cleanupNow(); } catch (e) {
+            console.warn("[ProjectId] cleanup sweep error:", e?.message ?? e);
+        }
+    }, CLEANUP_INTERVAL_MS);
+    // Unref so the timer doesn't prevent Node from exiting when it is otherwise idle
+    _cleanupTimer?.unref?.();
+}
+
+/** Stop the periodic background cleanup (e.g. during graceful shutdown). */
+export function stopCacheCleanup() {
+    if (!_cleanupTimer) return;
+    clearInterval(_cleanupTimer);
+    _cleanupTimer = null;
+}
+
+// Start automatically when the module is first imported
+startCacheCleanup();
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Get the Project ID for a connection, with caching.
+ * Returns null on failure (callers should fall back to random generation).
+ *
+ * @param {string} connectionId - The connection identifier for cache keying
+ * @param {string} accessToken  - Valid OAuth access token
+ * @returns {Promise<string|null>} Real project ID or null
+ */
+export async function getProjectIdForConnection(connectionId, accessToken) {
+    if (!connectionId || !accessToken) return null;
+
+    // Return cached value if still fresh
+    const cached = projectIdCache.get(connectionId);
+    if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+        return cached.projectId;
+    }
+
+    // Deduplicate concurrent fetches for the same connection
+    if (pendingFetches.has(connectionId)) {
+        return pendingFetches.get(connectionId).promise;
+    }
+
+    // Each fetch gets its own AbortController so it can be canceled via removeConnection()
+    const controller = new AbortController();
+
+    const promise = (async () => {
+        try {
+            const projectId = await fetchProjectId(accessToken, controller.signal);
+            if (projectId) {
+                projectIdCache.set(connectionId, {projectId, fetchedAt: Date.now()});
+                return projectId;
+            }
+            console.warn("[ProjectId] could not fetch projectId for connection", connectionId.slice(0, 8));
+            return null;
+        } catch (error) {
+            console.warn(`[ProjectId] Error fetching project ID: ${error.message}`);
+            return null;
+        } finally {
+            pendingFetches.delete(connectionId);
+        }
+    })();
+
+    pendingFetches.set(connectionId, {promise, controller, startedAt: Date.now()});
+    return promise;
+}
+
+/**
+ * Invalidate the cached project ID for a connection.
+ * Call this when a connection's credentials are fully revoked or refreshed.
+ */
+export function invalidateProjectId(connectionId) {
+    projectIdCache.delete(connectionId);
+}
+
+/**
+ * Fully remove a connection: abort any in-flight fetch and delete its cached project ID.
+ * Wire this into your connection close / disconnect lifecycle events to prevent memory leaks.
+ *
+ * @param {string} connectionId
+ */
+export function removeConnection(connectionId) {
+    if (!connectionId) return;
+    projectIdCache.delete(connectionId);
+    const pending = pendingFetches.get(connectionId);
+    if (pending) {
+        try { pending.controller.abort(); } catch (_) { /* ignore */ }
+        pendingFetches.delete(connectionId);
+    }
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Fetch project ID via loadCodeAssist endpoint.
+ * Falls back to onboardUser when loadCodeAssist returns no project.
+ *
+ * @param {string}      accessToken
+ * @param {AbortSignal} signal
+ * @returns {Promise<string|null>}
+ */
+async function fetchProjectId(accessToken, signal) {
+    const response = await fetch(CLOUD_CODE_API.loadCodeAssist, {
+        method: "POST",
+        headers: { ...LOAD_CODE_ASSIST_HEADERS, "Authorization": `Bearer ${accessToken}` },
+        body: JSON.stringify({ metadata: LOAD_CODE_ASSIST_METADATA }),
+        signal
+    });
+
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        throw new Error(`loadCodeAssist failed: HTTP ${response.status} ${errorText.slice(0, 200)}`);
+    }
+
+    const data = await response.json();
+    const projectId = extractProjectId(data);
+    if (projectId) return projectId;
+
+    // Determine the tier to use for onboarding
+    let tierID = "legacy-tier";
+    if (Array.isArray(data.allowedTiers)) {
+        for (const tier of data.allowedTiers) {
+            if (tier && typeof tier === "object" && tier.isDefault === true) {
+                if (tier.id && typeof tier.id === "string" && tier.id.trim()) {
+                    tierID = tier.id.trim();
+                    break;
+                }
+            }
+        }
+    }
+
+    return onboardUser(accessToken, tierID, signal);
+}
+
+/**
+ * Fetch project ID via onboardUser endpoint (polls until done).
+ *
+ * @param {string}      accessToken
+ * @param {string}      tierID
+ * @param {AbortSignal} externalSignal  – propagated from the connection's AbortController
+ * @returns {Promise<string|null>}
+ */
+async function onboardUser(accessToken, tierID, externalSignal) {
+    console.log(`[ProjectId] Onboarding user with tier: ${tierID}`);
+
+    const reqBody = { tierId: tierID, metadata: LOAD_CODE_ASSIST_METADATA };
+    const MAX_ATTEMPTS = 5;
+
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        // Bail out immediately if the connection was removed
+        if (externalSignal?.aborted) return null;
+
+        // Per-attempt timeout controller; forwards external abort as well
+        const localCtrl = new AbortController();
+        const timeoutId = setTimeout(() => localCtrl.abort(), 30_000);
+        const forwardAbort = () => localCtrl.abort();
+        externalSignal?.addEventListener("abort", forwardAbort);
+
+        try {
+            const response = await fetch(CLOUD_CODE_API.onboardUser, {
+                method: "POST",
+                headers: { ...LOAD_CODE_ASSIST_HEADERS, "Authorization": `Bearer ${accessToken}` },
+                body: JSON.stringify(reqBody),
+                signal: localCtrl.signal
+            });
+
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                throw new Error(`onboardUser HTTP ${response.status}: ${errorText.slice(0, 200)}`);
+            }
+
+            const data = await response.json();
+
+            if (data.done === true) {
+                const projectId = extractProjectIdFromOnboard(data);
+                if (projectId) {
+                    console.log(`[ProjectId] Successfully onboarded, project ID: ${projectId}`);
+                    return projectId;
+                }
+                throw new Error("onboardUser done but no project_id in response");
+            }
+
+            // Server not done yet – wait and retry
+            console.log(`[ProjectId] Onboard attempt ${attempt}/${MAX_ATTEMPTS}: not done yet, waiting...`);
+            await new Promise(resolve => setTimeout(resolve, 2000));
+
+        } catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === "AbortError") {
+                console.warn(`[ProjectId] onboardUser attempt ${attempt} aborted (timeout or connection removed)`);
+                if (externalSignal?.aborted) return null;   // connection gone – stop retrying
+                continue;
+            }
+            if (attempt === MAX_ATTEMPTS) {
+                console.warn(`[ProjectId] onboardUser failed after ${MAX_ATTEMPTS} attempts: ${error.message}`);
+                return null;
+            }
+            // Continue to next attempt instead of throwing (which would skip remaining retries)
+            console.warn(`[ProjectId] onboardUser attempt ${attempt} failed: ${error.message}, retrying...`);
+            await new Promise(resolve => setTimeout(resolve, 2000));
+        } finally {
+            clearTimeout(timeoutId);
+            externalSignal?.removeEventListener("abort", forwardAbort);
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Extract project ID from loadCodeAssist response.
+ */
+function extractProjectId(data) {
+    if (!data) return null;
+
+    if (typeof data.cloudaicompanionProject === "string") {
+        const id = data.cloudaicompanionProject.trim();
+        if (id) return id;
+    }
+
+    if (data.cloudaicompanionProject && typeof data.cloudaicompanionProject === "object") {
+        const id = data.cloudaicompanionProject.id;
+        if (typeof id === "string" && id.trim()) return id.trim();
+    }
+
+    return null;
+}
+
+/**
+ * Extract project ID from onboardUser response.
+ */
+function extractProjectIdFromOnboard(data) {
+    if (!data?.response) return null;
+
+    const project = data.response.cloudaicompanionProject;
+
+    if (typeof project === "string") {
+        const id = project.trim();
+        if (id) return id;
+    }
+
+    if (project && typeof project === "object") {
+        const id = project.id;
+        if (typeof id === "string" && id.trim()) return id.trim();
+    }
+
+    return null;
+}
diff --git a/open-sse/services/provider.js b/open-sse/services/provider.js
new file mode 100644
index 0000000..1b02cd8
--- /dev/null
+++ b/open-sse/services/provider.js
@@ -0,0 +1,169 @@
+import { PROVIDERS } from "../config/providers.js";
+import { OPENAI_COMPAT_BASE, ANTHROPIC_COMPAT_BASE } from "../providers/shared.js";
+
+const OPENAI_COMPATIBLE_PREFIX = "openai-compatible-";
+const OPENAI_COMPATIBLE_DEFAULTS = {
+  baseUrl: OPENAI_COMPAT_BASE,
+};
+
+const ANTHROPIC_COMPATIBLE_PREFIX = "anthropic-compatible-";
+const ANTHROPIC_COMPATIBLE_DEFAULTS = {
+  baseUrl: ANTHROPIC_COMPAT_BASE,
+};
+
+function isOpenAICompatible(provider) {
+  return typeof provider === "string" && provider.startsWith(OPENAI_COMPATIBLE_PREFIX);
+}
+
+function isAnthropicCompatible(provider) {
+  return typeof provider === "string" && provider.startsWith(ANTHROPIC_COMPATIBLE_PREFIX);
+}
+
+function getOpenAICompatibleType(provider) {
+  if (!isOpenAICompatible(provider)) return "chat";
+  return provider.includes("responses") ? "responses" : "chat";
+}
+
+// Detect request format from body structure
+export function detectFormat(body) {
+  // OpenAI Responses API: has input (array or string) instead of messages[]
+  // The Responses API accepts both input as array and input as a plain string
+  if (body.input && (Array.isArray(body.input) || typeof body.input === "string") && !body.messages) {
+    return "openai-responses";
+  }
+
+  // Antigravity format: Gemini wrapped in body.request
+  if (body.request?.contents && body.userAgent === "antigravity") {
+    return "antigravity";
+  }
+
+  // Gemini format: has contents array
+  if (body.contents && Array.isArray(body.contents)) {
+    return "gemini";
+  }
+
+  // OpenAI-specific indicators (check BEFORE Claude)
+  // These fields are OpenAI-specific and never appear in Claude format
+  if (
+    body.stream_options ||           // OpenAI streaming options
+    body.response_format ||           // JSON mode, etc.
+    body.logprobs !== undefined ||    // Log probabilities
+    body.top_logprobs !== undefined ||
+    body.n !== undefined ||           // Number of completions
+    body.presence_penalty !== undefined ||  // Penalties
+    body.frequency_penalty !== undefined ||
+    body.logit_bias ||                // Token biasing
+    body.user                         // User identifier
+  ) {
+    return "openai";
+  }
+
+  // Claude format: messages with content as array of objects with type
+  // Claude requires content to be array with specific structure
+  if (body.messages && Array.isArray(body.messages)) {
+    const firstMsg = body.messages[0];
+    
+    // If content is array, check if it follows Claude structure
+    if (firstMsg?.content && Array.isArray(firstMsg.content)) {
+      const firstContent = firstMsg.content[0];
+      
+      // Claude format has specific types: text, image, tool_use, tool_result
+      // OpenAI multimodal has: text, image_url (note the difference)
+      if (firstContent?.type === "text" && !body.model?.includes("/")) {
+        // Could be Claude or OpenAI multimodal
+        // Check for Claude-specific fields
+        if (body.system || body.anthropic_version) {
+          return "claude";
+        }
+        // Check if image format is Claude (source.type) vs OpenAI (image_url.url)
+        const hasClaudeImage = firstMsg.content.some(c => 
+          c.type === "image" && c.source?.type === "base64"
+        );
+        const hasOpenAIImage = firstMsg.content.some(c => 
+          c.type === "image_url" && c.image_url?.url
+        );
+        if (hasClaudeImage) return "claude";
+        if (hasOpenAIImage) return "openai";
+        
+        // If still unclear, check for tool format
+        const hasClaudeTool = firstMsg.content.some(c => 
+          c.type === "tool_use" || c.type === "tool_result"
+        );
+        if (hasClaudeTool) return "claude";
+      }
+    }
+    
+    // If content is string, it's likely OpenAI (Claude also supports this)
+    // Check for other Claude-specific indicators
+    if (body.system !== undefined || body.anthropic_version) {
+      return "claude";
+    }
+  }
+
+  // Default to OpenAI format
+  return "openai";
+}
+
+// Get provider config (internal — no external runtime consumer)
+function getProviderConfig(provider) {
+  if (isOpenAICompatible(provider)) {
+    const apiType = getOpenAICompatibleType(provider);
+    return {
+      ...PROVIDERS.openai,
+      format: apiType === "responses" ? "openai-responses" : "openai",
+      baseUrl: OPENAI_COMPATIBLE_DEFAULTS.baseUrl,
+    };
+  }
+  if (isAnthropicCompatible(provider)) {
+    return {
+      ...PROVIDERS.anthropic, // Use Anthropic defaults (header: x-api-key)
+      format: "claude",
+      baseUrl: ANTHROPIC_COMPATIBLE_DEFAULTS.baseUrl,
+    };
+  }
+  return PROVIDERS[provider] || PROVIDERS.openai;
+}
+
+// Get target format for provider
+export function getTargetFormat(provider) {
+  if (isOpenAICompatible(provider)) {
+    return getOpenAICompatibleType(provider) === "responses" ? "openai-responses" : "openai";
+  }
+  if (isAnthropicCompatible(provider)) {
+    return "claude";
+  }
+  const config = getProviderConfig(provider);
+  return config.format || "openai";
+}
+
+// Resolve which transport to use for a provider given the client sourceFormat.
+// Multi-endpoint providers (transport.transports[]) pick the entry matching sourceFormat
+// to avoid lossy translation; falls back to the default transport when no match.
+export function resolveTransport(provider, sourceFormat) {
+  const config = PROVIDERS[provider];
+  const transports = config?.transports;
+  if (!Array.isArray(transports) || !transports.length) return null;
+  return transports.find(t => t.format === sourceFormat) || null;
+}
+
+// Check if last message is from user
+export function isLastMessageFromUser(body) {
+  const messages = body.messages || body.contents;
+  if (!messages?.length) return true;
+  const lastMsg = messages[messages.length - 1];
+  return lastMsg?.role === "user";
+}
+
+// Check if request has thinking config
+export function hasThinkingConfig(body) {
+  return !!(body.reasoning_effort || body.thinking?.type === "enabled");
+}
+
+// Normalize provider-native thinking config based on last message role.
+// OpenAI reasoning_effort is request-level and must survive tool-result turns.
+export function normalizeThinkingConfig(body) {
+  if (!isLastMessageFromUser(body)) {
+    delete body.thinking;
+  }
+  return body;
+}
diff --git a/open-sse/services/qoderModels.js b/open-sse/services/qoderModels.js
new file mode 100644
index 0000000..01e6fb1
--- /dev/null
+++ b/open-sse/services/qoderModels.js
@@ -0,0 +1,214 @@
+/**
+ * Qoder model catalog fetcher.
+ *
+ * Calls /algo/api/v2/model/list (COSY-signed) on the inference host to get
+ * the live catalog for an authenticated Qoder account, then caches the
+ * per-model `model_config` blocks by key. Chat requests later look up the
+ * exact server-published metadata for the model they want — Qoder's chat
+ * endpoint silently downgrades to a different model when the wrong
+ * model_config is sent.
+ *
+ * On any error the live cache stays empty and chatExecuteCall surfaces the
+ * problem to the user as "model config not yet fetched, retry shortly".
+ */
+
+import { createHash } from "crypto";
+
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+import { buildCosyHeaders } from "../shared/qoder/cosy.js";
+import {
+  QODER_MODEL_LIST_URL,
+} from "../shared/qoder/constants.js";
+
+const FETCH_TIMEOUT_MS = 15_000;
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1h, same as the Kiro catalog
+
+/** @type {Map<string, { expiresAt: number, models: any[], rawConfigs: Map<string, object>, fetched: boolean }>} */
+const catalogCache = new Map();
+
+/**
+ * In-flight fetch promises keyed by cacheKey. Concurrent first-time
+ * callers (parallel chat windows) all observe the same Promise so we
+ * fan-out exactly one upstream request per credential per miss.
+ * @type {Map<string, Promise<{ expiresAt: number, models: any[], rawConfigs: Map<string, object>, fetched: boolean } | null>>}
+ */
+const inflight = new Map();
+
+/**
+ * Stable cache key per credential (so different login sessions for the same
+ * account share an entry).
+ */
+function cacheKey(credentials) {
+  const psd = credentials?.providerSpecificData || {};
+  const seed = psd.userId || credentials?.refreshToken || credentials?.accessToken || "anonymous";
+  return createHash("sha256").update(`qoder:${seed}`).digest("hex");
+}
+
+/**
+ * Strip credential -> COSY creds for buildCosyHeaders.
+ */
+function cosyCredsFromConnection(credentials) {
+  const psd = credentials?.providerSpecificData || {};
+  return {
+    userId: psd.userId,
+    authToken: credentials.accessToken,
+    name: credentials.displayName || "",
+    email: credentials.email || "",
+    machineId: psd.machineId || "",
+  };
+}
+
+/**
+ * Fetch the live model list for this credential. Returns:
+ *   { models: [{ id, name, contextLength, isVL, isReasoning, ... }, ...],
+ *     rawConfigs: Map<modelKey, modelConfigObject> }
+ * or `null` on any error.
+ */
+async function fetchQoderCatalogRaw(credentials, signal, proxyOptions = null) {
+  const creds = cosyCredsFromConnection(credentials);
+  if (!creds.userId || !creds.authToken) return null;
+
+  const headers = {
+    Accept: "application/json",
+    "Accept-Encoding": "identity",
+    ...buildCosyHeaders(Buffer.alloc(0), QODER_MODEL_LIST_URL, creds),
+  };
+
+  const controller = new AbortController();
+  let timer = null;
+  let abortListener = null;
+  let response;
+  try {
+    timer = setTimeout(() => controller.abort("timeout"), FETCH_TIMEOUT_MS);
+    if (signal && typeof signal.addEventListener === "function") {
+      // If the parent signal already aborted before we got here, the
+      // 'abort' event has already fired and addEventListener won't
+      // re-trigger it. Propagate the cancellation immediately.
+      if (signal.aborted) {
+        controller.abort(signal.reason);
+      } else {
+        abortListener = () => controller.abort(signal.reason);
+        signal.addEventListener("abort", abortListener);
+      }
+    }
+    response = await proxyAwareFetch(
+      QODER_MODEL_LIST_URL,
+      {
+        method: "GET",
+        headers,
+        signal: controller.signal,
+      },
+      proxyOptions,
+    );
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (signal && abortListener) signal.removeEventListener("abort", abortListener);
+  }
+
+  if (!response.ok) return null;
+
+  const body = await response.json().catch(() => null);
+  if (!body || !Array.isArray(body.chat)) return null;
+
+  const models = [];
+  const rawConfigs = new Map();
+  for (const entry of body.chat) {
+    if (!entry || typeof entry !== "object") continue;
+    const key = entry.key;
+    if (!key) continue;
+
+    // Always cache the config — chat needs model_config even for UI-hidden
+    // models (enable:false). Upstream still accepts chat for these keys.
+    rawConfigs.set(key, entry);
+    if (entry.enable === false) continue;
+
+    const display = entry.display_name || key;
+    const ctx = Number(entry.max_input_tokens) || 131_072;
+    models.push({
+      id: key,
+      name: `${display}`,
+      contextLength: ctx,
+      isVL: !!entry.is_vl,
+      isReasoning: !!entry.is_reasoning,
+      maxOutputTokens: Number(entry.max_output_tokens) || 0,
+      description: entry.description || "",
+    });
+  }
+
+  return { models, rawConfigs };
+}
+
+/**
+ * Get the cached model_config block for a given model key, fetching the
+ * catalog first if needed. Returns null when the catalog can't be fetched
+ * (so callers can fall back to the static registry).
+ */
+export async function getQoderModelConfig(credentials, modelKey, options = {}) {
+  const cached = await resolveQoderModels(credentials, options);
+  if (!cached) return null;
+  const config = cached.rawConfigs.get(modelKey);
+  if (!config) return null;
+  // Defensive copy — chat code may mutate `key` to align with the alias path.
+  return { ...config, key: modelKey };
+}
+
+/**
+ * Resolve the live model catalog + raw configs for a credential. Caches
+ * results for CACHE_TTL_MS so repeated chat requests don't re-fetch, and
+ * deduplicates concurrent misses so parallel chat windows fan-out exactly
+ * one upstream request per credential.
+ */
+export async function resolveQoderModels(credentials, options = {}) {
+  if (!credentials?.accessToken) return null;
+  const psd = credentials.providerSpecificData || {};
+  if (!psd.userId) return null;
+
+  const key = cacheKey(credentials);
+  const now = Date.now();
+  if (!options.forceRefresh) {
+    const cached = catalogCache.get(key);
+    if (cached && cached.expiresAt > now) {
+      return cached;
+    }
+  }
+
+  // Coalesce concurrent misses on the same credential into one upstream call.
+  // forceRefresh callers still get their own fetch (they wanted fresh data).
+  const existing = inflight.get(key);
+  if (existing && !options.forceRefresh) {
+    return existing;
+  }
+
+  const fetchPromise = (async () => {
+    const fetched = await fetchQoderCatalogRaw(credentials, options.signal, options.proxyOptions);
+    if (!fetched) return null;
+    const entry = {
+      expiresAt: Date.now() + CACHE_TTL_MS,
+      models: fetched.models,
+      rawConfigs: fetched.rawConfigs,
+      fetched: true,
+    };
+    catalogCache.set(key, entry);
+    return entry;
+  })();
+
+  inflight.set(key, fetchPromise);
+  try {
+    return await fetchPromise;
+  } finally {
+    // Clear only if this is still the in-flight entry — a forceRefresh
+    // call that started later may have replaced it.
+    if (inflight.get(key) === fetchPromise) {
+      inflight.delete(key);
+    }
+  }
+}
+
+export function invalidateQoderCatalog(credentials) {
+  if (!credentials) return;
+  catalogCache.delete(cacheKey(credentials));
+}
+
+export function clearQoderCatalog() {
+  catalogCache.clear();
+}
diff --git a/open-sse/services/tokenRefresh.js b/open-sse/services/tokenRefresh.js
new file mode 100644
index 0000000..c8d264c
--- /dev/null
+++ b/open-sse/services/tokenRefresh.js
@@ -0,0 +1,254 @@
+import { PROVIDERS } from "../config/providers.js";
+import { OAUTH_ENDPOINTS, REFRESH_LEAD_MS } from "../config/appConstants.js";
+import {
+  refreshXaiToken,
+  refreshAccessToken,
+  refreshClaudeOAuthToken,
+  refreshGoogleToken,
+  refreshQwenToken,
+  refreshCodexToken,
+  refreshKiroToken,
+  refreshIflowToken,
+  refreshGitHubToken,
+  refreshCopilotToken,
+  refreshCodebuddyToken,
+  classifyOAuthRefreshError,
+} from "./tokenRefresh/providers.js";
+
+// Re-export all provider refresh functions (preserves public API for all consumers)
+export {
+  refreshAccessToken,
+  refreshClaudeOAuthToken,
+  refreshGoogleToken,
+  refreshQwenToken,
+  refreshCodexToken,
+  refreshKiroToken,
+  refreshIflowToken,
+  refreshGitHubToken,
+  refreshCopilotToken,
+  refreshCodebuddyToken,
+  classifyOAuthRefreshError,
+};
+
+export const TOKEN_EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+
+export function isUnrecoverableRefreshError(result) {
+  return (
+    result &&
+    typeof result === "object" &&
+    (result.error === "unrecoverable_refresh_error" ||
+      result.error === "refresh_token_reused" ||
+      result.error === "invalid_request" ||
+      result.error === "invalid_grant")
+  );
+}
+
+export function getRefreshLeadMs(provider) {
+  return REFRESH_LEAD_MS[provider] || TOKEN_EXPIRY_BUFFER_MS;
+}
+
+export function parseVertexSaJson(apiKey) {
+  if (typeof apiKey !== "string") return null;
+  try {
+    const parsed = JSON.parse(apiKey);
+    if (parsed.type === "service_account" && parsed.client_email && parsed.private_key && parsed.project_id) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// Cache Vertex tokens keyed by service account email { token, expiresAt }
+const vertexTokenCache = new Map();
+
+export async function refreshVertexToken(saJson, log) {
+  const cacheKey = saJson.client_email;
+  const cached = vertexTokenCache.get(cacheKey);
+
+  if (cached && cached.expiresAt - Date.now() > 5 * 60 * 1000) {
+    return { accessToken: cached.token, expiresAt: cached.expiresAt };
+  }
+
+  try {
+    const { SignJWT, importPKCS8 } = await import("jose");
+    log?.debug?.("TOKEN_REFRESH", `Vertex minting token for ${saJson.client_email}`);
+    const privateKey = await importPKCS8(saJson.private_key.replace(/\\n/g, "\n"), "RS256");
+    const now = Math.floor(Date.now() / 1000);
+
+    const jwt = await new SignJWT({ scope: "https://www.googleapis.com/auth/cloud-platform" })
+      .setProtectedHeader({ alg: "RS256" })
+      .setIssuer(saJson.client_email)
+      .setAudience(OAUTH_ENDPOINTS.google.token)
+      .setIssuedAt(now)
+      .setExpirationTime(now + 3600)
+      .sign(privateKey);
+
+    const res = await fetch(OAUTH_ENDPOINTS.google.token, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+        assertion: jwt,
+      }),
+    });
+
+    if (!res.ok) {
+      const err = await res.text();
+      log?.error?.("TOKEN_REFRESH", `Vertex token mint failed: ${err}`);
+      return null;
+    }
+
+    const { access_token, expires_in } = await res.json();
+    const expiresAt = Date.now() + (expires_in ?? 3600) * 1000;
+
+    vertexTokenCache.set(cacheKey, { token: access_token, expiresAt });
+    log?.info?.("TOKEN_REFRESH", `Vertex token minted for ${saJson.client_email}`);
+
+    return { accessToken: access_token, expiresAt };
+  } catch (error) {
+    log?.error?.("TOKEN_REFRESH", `Vertex token error: ${error.message}`);
+    return null;
+  }
+}
+
+function vertexRefreshHandler(c, log) {
+  const saJson = parseVertexSaJson(c.apiKey);
+  if (!saJson) return null;
+  return refreshVertexToken(saJson, log);
+}
+
+const REFRESH_HANDLERS = {
+  "gemini-cli": (c, log) => refreshGoogleToken(c.refreshToken, PROVIDERS["gemini-cli"].clientId, PROVIDERS["gemini-cli"].clientSecret, log),
+  antigravity: (c, log) => refreshGoogleToken(c.refreshToken, PROVIDERS.antigravity.clientId, PROVIDERS.antigravity.clientSecret, log),
+  claude: (c, log) => refreshClaudeOAuthToken(c.refreshToken, log),
+  codex: (c, log) => refreshCodexToken(c.refreshToken, log),
+  qwen: (c, log) => refreshQwenToken(c.refreshToken, log),
+  iflow: (c, log) => refreshIflowToken(c.refreshToken, log),
+  github: (c, log) => refreshGitHubToken(c.refreshToken, log),
+  kiro: (c, log) => refreshKiroToken(c.refreshToken, c.providerSpecificData, log),
+  xai: (c, log) => refreshXaiToken(c.refreshToken, log),
+  // Grok CLI shares xAI OAuth client + token endpoint (device-code tokens refresh the same way)
+  "grok-cli": (c, log) => refreshXaiToken(c.refreshToken, log),
+  gcli: (c, log) => refreshXaiToken(c.refreshToken, log),
+  "codebuddy-cn": (c, log) => refreshCodebuddyToken(c.refreshToken, log),
+  vertex: vertexRefreshHandler,
+  "vertex-partner": vertexRefreshHandler
+};
+
+export async function getAccessToken(provider, credentials, log) {
+  if (!credentials || !credentials.refreshToken || typeof credentials.refreshToken !== "string") {
+    log?.warn?.("TOKEN_REFRESH", `No valid refresh token available for provider: ${provider}`);
+    return null;
+  }
+  return _getAccessTokenInternal(provider, credentials, log);
+}
+
+async function _getAccessTokenInternal(provider, credentials, log) {
+  if (provider === "gemini") {
+    return refreshGoogleToken(credentials.refreshToken, PROVIDERS.gemini.clientId, PROVIDERS.gemini.clientSecret, log);
+  }
+  const handler = REFRESH_HANDLERS[provider];
+  if (!handler) {
+    log?.warn?.("TOKEN_REFRESH", `Unsupported provider for token refresh: ${provider}`);
+    return null;
+  }
+  return handler(credentials, log);
+}
+
+export async function refreshTokenByProvider(provider, credentials, log) {
+  if (!credentials.refreshToken) return null;
+  const handler = REFRESH_HANDLERS[provider];
+  return handler ? handler(credentials, log) : refreshAccessToken(provider, credentials.refreshToken, credentials, log);
+}
+
+export function formatProviderCredentials(provider, credentials, log) {
+  const config = PROVIDERS[provider];
+  if (!config) {
+    log?.warn?.("TOKEN_REFRESH", `No configuration found for provider: ${provider}`);
+    return null;
+  }
+
+  switch (provider) {
+    case "gemini":
+      return {
+        apiKey: credentials.apiKey,
+        accessToken: credentials.accessToken,
+        projectId: credentials.projectId
+      };
+
+    case "claude":
+      return {
+        apiKey: credentials.apiKey,
+        accessToken: credentials.accessToken
+      };
+
+    case "codex":
+    case "qwen":
+    case "iflow":
+    case "openai":
+    case "openrouter":
+    case "xai":
+    case "grok-cli":
+      return {
+        apiKey: credentials.apiKey,
+        accessToken: credentials.accessToken
+      };
+
+    case "antigravity":
+    case "gemini-cli":
+      return {
+        accessToken: credentials.accessToken,
+        refreshToken: credentials.refreshToken,
+        projectId: credentials.projectId
+      };
+
+    default:
+      return {
+        apiKey: credentials.apiKey,
+        accessToken: credentials.accessToken,
+        refreshToken: credentials.refreshToken
+      };
+  }
+}
+
+export async function getAllAccessTokens(userInfo, log) {
+  const results = {};
+
+  if (userInfo.connections && Array.isArray(userInfo.connections)) {
+    for (const connection of userInfo.connections) {
+      if (connection.isActive && connection.provider) {
+        const token = await getAccessToken(connection.provider, {
+          refreshToken: connection.refreshToken
+        }, log);
+
+        if (token) {
+          results[connection.provider] = token;
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+export async function refreshWithRetry(refreshFn, maxRetries = 3, log = null) {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    if (attempt > 0) {
+      const delay = attempt * 1000;
+      log?.debug?.("TOKEN_REFRESH", `Retry ${attempt}/${maxRetries} after ${delay}ms`);
+      await new Promise(r => setTimeout(r, delay));
+    }
+
+    try {
+      const result = await refreshFn();
+      if (result) return result;
+    } catch (error) {
+      log?.warn?.("TOKEN_REFRESH", `Attempt ${attempt + 1}/${maxRetries} failed: ${error.message}`);
+    }
+  }
+
+  log?.error?.("TOKEN_REFRESH", `All ${maxRetries} retry attempts failed`);
+  return null;
+}
diff --git a/open-sse/services/tokenRefresh/dedup.js b/open-sse/services/tokenRefresh/dedup.js
new file mode 100644
index 0000000..ea4666c
--- /dev/null
+++ b/open-sse/services/tokenRefresh/dedup.js
@@ -0,0 +1,31 @@
+const REFRESH_RESULT_TTL_MS = 10_000;
+const refreshDedupCache = new Map();
+
+export async function dedupRefresh(provider, oldToken, fn, log) {
+  if (!oldToken) return fn();
+  const key = `${provider}:${oldToken}`;
+  const hit = refreshDedupCache.get(key);
+  if (hit) {
+    if (hit.promise) {
+      log?.info?.("TOKEN_REFRESH", `Reusing in-flight refresh for ${provider}`);
+      return hit.promise;
+    }
+    if (hit.expiresAt > Date.now()) {
+      log?.info?.("TOKEN_REFRESH", `Reusing recent refresh result for ${provider}`);
+      return hit.result;
+    }
+    refreshDedupCache.delete(key);
+  }
+  const promise = (async () => {
+    try {
+      const result = await fn();
+      refreshDedupCache.set(key, { result, expiresAt: Date.now() + REFRESH_RESULT_TTL_MS });
+      return result;
+    } catch (err) {
+      refreshDedupCache.delete(key);
+      throw err;
+    }
+  })();
+  refreshDedupCache.set(key, { promise });
+  return promise;
+}
diff --git a/open-sse/services/tokenRefresh/providers.js b/open-sse/services/tokenRefresh/providers.js
new file mode 100644
index 0000000..54c2fa0
--- /dev/null
+++ b/open-sse/services/tokenRefresh/providers.js
@@ -0,0 +1,624 @@
+import { PROVIDERS, PROVIDER_OAUTH } from "../../config/providers.js";
+import { OAUTH_ENDPOINTS, GITHUB_COPILOT } from "../../config/appConstants.js";
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { dedupRefresh } from "./dedup.js";
+import { buildExternalIdpRefreshParams } from "../../../src/lib/oauth/kiroExternalIdp.js";
+
+let _xaiServiceSingleton = null;
+export async function refreshXaiToken(refreshToken, log) {
+  if (!refreshToken) return null;
+  return dedupRefresh("xai", refreshToken, async () => {
+    try {
+      if (!_xaiServiceSingleton) {
+        const mod = await import("../../../src/lib/oauth/services/xai.js");
+        _xaiServiceSingleton = new mod.XaiService();
+      }
+      const tokens = await _xaiServiceSingleton.refreshAccessToken(refreshToken);
+      return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token || refreshToken,
+        expiresIn: tokens.expires_in,
+        idToken: tokens.id_token,
+      };
+    } catch (e) {
+      log?.warn?.("TOKEN_REFRESH", `xai refresh failed: ${e?.message || e}`);
+      const msg = String(e?.message || "");
+      if (msg.includes("invalid_grant") || msg.includes("invalid_request")) {
+        return { error: "invalid_grant" };
+      }
+      return null;
+    }
+  }, log);
+}
+
+export async function refreshAccessToken(provider, refreshToken, credentials, log) {
+  const config = PROVIDERS[provider];
+
+  if (!config || !config.refreshUrl) {
+    log?.warn?.("TOKEN_REFRESH", `No refresh URL configured for provider: ${provider}`);
+    return null;
+  }
+
+  if (!refreshToken) {
+    log?.warn?.("TOKEN_REFRESH", `No refresh token available for provider: ${provider}`);
+    return null;
+  }
+
+  return dedupRefresh(provider, refreshToken, async () => {
+  try {
+    const response = await fetch(config.refreshUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log?.error?.("TOKEN_REFRESH", `Failed to refresh token for ${provider}`, {
+        status: response.status,
+        error: errorText,
+      });
+      return null;
+    }
+
+    const tokens = await response.json();
+
+    log?.info?.("TOKEN_REFRESH", `Successfully refreshed token for ${provider}`, {
+      hasNewAccessToken: !!tokens.access_token,
+      hasNewRefreshToken: !!tokens.refresh_token,
+      expiresIn: tokens.expires_in,
+    });
+
+    return {
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token || refreshToken,
+      expiresIn: tokens.expires_in,
+    };
+  } catch (error) {
+    log?.error?.("TOKEN_REFRESH", `Error refreshing token for ${provider}`, {
+      error: error.message,
+    });
+    return null;
+  }
+  }, log);
+}
+
+export async function refreshClaudeOAuthToken(refreshToken, log) {
+  if (!refreshToken) return null;
+  return dedupRefresh("claude", refreshToken, async () => {
+  try {
+    const response = await fetch(OAUTH_ENDPOINTS.anthropic.token, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: PROVIDERS.claude.clientId,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log?.error?.("TOKEN_REFRESH", "Failed to refresh Claude OAuth token", { status: response.status, error: errorText });
+      return null;
+    }
+
+    const tokens = await response.json();
+    log?.info?.("TOKEN_REFRESH", "Successfully refreshed Claude OAuth token", { hasNewAccessToken: !!tokens.access_token, expiresIn: tokens.expires_in });
+    return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token || refreshToken, expiresIn: tokens.expires_in };
+  } catch (error) {
+    log?.error?.("TOKEN_REFRESH", `Network error refreshing Claude token: ${error.message}`);
+    return null;
+  }
+  }, log);
+}
+
+export async function refreshGoogleToken(refreshToken, clientId, clientSecret, log) {
+  if (!refreshToken) return null;
+  return dedupRefresh(`google:${clientId}`, refreshToken, async () => {
+  try {
+    const response = await fetch(OAUTH_ENDPOINTS.google.token, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: clientId,
+        client_secret: clientSecret,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log?.error?.("TOKEN_REFRESH", "Failed to refresh Google token", { status: response.status, error: errorText });
+      return null;
+    }
+
+    const tokens = await response.json();
+    log?.info?.("TOKEN_REFRESH", "Successfully refreshed Google token", { hasNewAccessToken: !!tokens.access_token, expiresIn: tokens.expires_in });
+    return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token || refreshToken, expiresIn: tokens.expires_in };
+  } catch (error) {
+    log?.error?.("TOKEN_REFRESH", `Network error refreshing Google token: ${error.message}`);
+    return null;
+  }
+  }, log);
+}
+
+export async function refreshQwenToken(refreshToken, log) {
+  if (!refreshToken) return null;
+  return dedupRefresh("qwen", refreshToken, async () => {
+  const endpoint = OAUTH_ENDPOINTS.qwen.token;
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: PROVIDERS.qwen.clientId,
+      }),
+    });
+
+    if (response.status === 200) {
+      const tokens = await response.json();
+
+      log?.info?.("TOKEN_REFRESH", "Successfully refreshed Qwen token", {
+        hasNewAccessToken: !!tokens.access_token,
+        hasNewRefreshToken: !!tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+      });
+
+      return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token || refreshToken,
+        expiresIn: tokens.expires_in,
+        providerSpecificData: tokens.resource_url
+          ? { resourceUrl: tokens.resource_url }
+          : undefined,
+      };
+    } else {
+      const errorText = await response.text().catch(() => "");
+      log?.warn?.("TOKEN_REFRESH", `Error with Qwen endpoint`, {
+        status: response.status,
+        error: errorText,
+      });
+    }
+  } catch (error) {
+    log?.warn?.("TOKEN_REFRESH", `Network error trying Qwen endpoint`, {
+      error: error.message,
+    });
+  }
+
+  log?.error?.("TOKEN_REFRESH", "Failed to refresh Qwen token");
+  return null;
+  }, log);
+}
+
+export function classifyOAuthRefreshError(errorText = "", status = 0) {
+  let parsed = null;
+  try {
+    parsed = errorText ? JSON.parse(errorText) : null;
+  } catch {
+    parsed = null;
+  }
+
+  const code = parsed?.error?.code || parsed?.error || parsed?.error_code || "";
+  const description = parsed?.error_description || parsed?.message || errorText || "";
+  const combined = `${code} ${description}`.toLowerCase();
+  const permanent = [
+    "refresh_token_expired",
+    "refresh_token_reused",
+    "refresh_token_invalidated",
+    "invalid_grant",
+  ].some((marker) => combined.includes(marker));
+
+  return { status, code, description, permanent };
+}
+
+export async function refreshCodexToken(refreshToken, log) {
+  if (!refreshToken) return null;
+  return dedupRefresh("codex", refreshToken, async () => {
+    try {
+      const response = await fetch(OAUTH_ENDPOINTS.openai.token, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body: JSON.stringify({
+          client_id: PROVIDERS.codex.clientId,
+          grant_type: "refresh_token",
+          refresh_token: refreshToken,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        const failure = classifyOAuthRefreshError(errorText, response.status);
+        if (failure.permanent) {
+          log?.error?.("TOKEN_REFRESH", "Codex refresh token already used or invalid. Re-auth required.", {
+            status: response.status,
+            code: failure.code,
+          });
+          return { error: "unrecoverable_refresh_error", code: failure.code };
+        }
+
+        log?.error?.("TOKEN_REFRESH", "Failed to refresh Codex token", {
+          status: response.status,
+          error: errorText,
+          code: failure.code,
+          permanent: failure.permanent,
+        });
+        return null;
+      }
+
+      const tokens = await response.json();
+
+      log?.info?.("TOKEN_REFRESH", "Successfully refreshed Codex token", {
+        hasNewAccessToken: !!tokens.access_token,
+        hasNewRefreshToken: !!tokens.refresh_token,
+        hasIdToken: !!tokens.id_token,
+        expiresIn: tokens.expires_in,
+      });
+
+      return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token || refreshToken,
+        idToken: tokens.id_token,
+        expiresIn: tokens.expires_in,
+      };
+    } catch (error) {
+      log?.error?.("TOKEN_REFRESH", `Network error refreshing Codex token: ${error.message}`);
+      return null;
+    }
+  }, log);
+}
+
+async function resolveKiroProfileArnPatch(providerSpecificData, accessToken, refreshedArn) {
+  if (providerSpecificData?.profileArn) return {};
+  let profileArn = refreshedArn?.trim?.() || null;
+  if (!profileArn) {
+    const { fetchKiroProfileArn } = await import("../../../src/lib/oauth/providers.js");
+    profileArn = await fetchKiroProfileArn(accessToken);
+  }
+  return profileArn ? { providerSpecificData: { profileArn } } : {};
+}
+
+export async function refreshKiroToken(refreshToken, providerSpecificData, log, proxyOptions = null) {
+  if (!refreshToken) return null;
+  return dedupRefresh("kiro", refreshToken, async () => {
+  const authMethod = providerSpecificData?.authMethod;
+  const clientId = providerSpecificData?.clientId;
+  const clientSecret = providerSpecificData?.clientSecret;
+  const region = providerSpecificData?.region;
+
+  if (authMethod === "external_idp") {
+    let refreshRequest;
+    try {
+      refreshRequest = buildExternalIdpRefreshParams(refreshToken, providerSpecificData);
+    } catch (error) {
+      log?.warn?.("TOKEN_REFRESH", `Invalid Kiro external_idp refresh config: ${error.message}`);
+      return null;
+    }
+
+    const response = await proxyAwareFetch(refreshRequest.tokenEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: refreshRequest.body,
+    }, proxyOptions);
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log?.error?.("TOKEN_REFRESH", "Failed to refresh Kiro external_idp token", {
+        status: response.status,
+        error: errorText,
+      });
+      return null;
+    }
+
+    const tokens = await response.json();
+
+    log?.info?.("TOKEN_REFRESH", "Successfully refreshed Kiro external_idp token", {
+      hasNewAccessToken: !!tokens.access_token,
+      hasNewRefreshToken: !!tokens.refresh_token,
+      expiresIn: tokens.expires_in,
+    });
+
+    return {
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token || refreshToken,
+      expiresIn: tokens.expires_in,
+      providerSpecificData: refreshRequest.providerSpecificData,
+    };
+  }
+
+  if (clientId && clientSecret) {
+    const isIDC = authMethod === "idc";
+    const endpoint = isIDC && region
+      ? `https://oidc.${region}.amazonaws.com/token`
+      : "https://oidc.us-east-1.amazonaws.com/token";
+
+    const response = await proxyAwareFetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify({
+        clientId: clientId,
+        clientSecret: clientSecret,
+        refreshToken: refreshToken,
+        grantType: "refresh_token",
+      }),
+    }, proxyOptions);
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log?.error?.("TOKEN_REFRESH", "Failed to refresh Kiro AWS token", {
+        status: response.status,
+        error: errorText,
+      });
+      return null;
+    }
+
+    const tokens = await response.json();
+
+    log?.info?.("TOKEN_REFRESH", "Successfully refreshed Kiro AWS token", {
+      hasNewAccessToken: !!tokens.accessToken,
+      expiresIn: tokens.expiresIn,
+    });
+
+    return {
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken || refreshToken,
+      expiresIn: tokens.expiresIn,
+      ...(await resolveKiroProfileArnPatch(providerSpecificData, tokens.accessToken, tokens.profileArn)),
+    };
+  }
+
+  const response = await proxyAwareFetch(PROVIDERS.kiro.tokenUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": "kiro-cli/1.0.0",
+    },
+    body: JSON.stringify({
+      refreshToken: refreshToken,
+    }),
+  }, proxyOptions);
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    log?.error?.("TOKEN_REFRESH", "Failed to refresh Kiro social token", {
+      status: response.status,
+      error: errorText,
+    });
+    return null;
+  }
+
+  const tokens = await response.json();
+
+  log?.info?.("TOKEN_REFRESH", "Successfully refreshed Kiro social token", {
+    hasNewAccessToken: !!tokens.accessToken,
+    expiresIn: tokens.expiresIn,
+  });
+
+  return {
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken || refreshToken,
+    expiresIn: tokens.expiresIn,
+    ...(await resolveKiroProfileArnPatch(providerSpecificData, tokens.accessToken, tokens.profileArn)),
+  };
+  }, log);
+}
+
+export async function refreshIflowToken(refreshToken, log) {
+  if (!refreshToken) return null;
+  return dedupRefresh("iflow", refreshToken, async () => {
+  const basicAuth = btoa(`${PROVIDERS.iflow.clientId}:${PROVIDERS.iflow.clientSecret}`);
+
+  const response = await fetch(OAUTH_ENDPOINTS.iflow.token, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+      Authorization: `Basic ${basicAuth}`,
+    },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: PROVIDERS.iflow.clientId,
+      client_secret: PROVIDERS.iflow.clientSecret,
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    log?.error?.("TOKEN_REFRESH", "Failed to refresh iFlow token", {
+      status: response.status,
+      error: errorText,
+    });
+    return null;
+  }
+
+  const tokens = await response.json();
+
+  log?.info?.("TOKEN_REFRESH", "Successfully refreshed iFlow token", {
+    hasNewAccessToken: !!tokens.access_token,
+    hasNewRefreshToken: !!tokens.refresh_token,
+    expiresIn: tokens.expires_in,
+  });
+
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token || refreshToken,
+    expiresIn: tokens.expires_in,
+  };
+  }, log);
+}
+
+export async function refreshGitHubToken(refreshToken, log) {
+  if (!refreshToken) return null;
+  return dedupRefresh("github", refreshToken, async () => {
+  const params = {
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: PROVIDERS.github.clientId,
+  };
+  if (PROVIDERS.github.clientSecret) {
+    params.client_secret = PROVIDERS.github.clientSecret;
+  }
+
+  const response = await fetch(OAUTH_ENDPOINTS.github.token, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    },
+    body: new URLSearchParams(params),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    log?.error?.("TOKEN_REFRESH", "Failed to refresh GitHub token", {
+      status: response.status,
+      error: errorText,
+    });
+    return null;
+  }
+
+  const tokens = await response.json();
+
+  log?.info?.("TOKEN_REFRESH", "Successfully refreshed GitHub token", {
+    hasNewAccessToken: !!tokens.access_token,
+    hasNewRefreshToken: !!tokens.refresh_token,
+    expiresIn: tokens.expires_in,
+  });
+
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token || refreshToken,
+    expiresIn: tokens.expires_in,
+  };
+  }, log);
+}
+
+export async function refreshCopilotToken(githubAccessToken, log) {
+  if (!githubAccessToken) return null;
+  return dedupRefresh("copilot", githubAccessToken, async () => {
+  try {
+    const response = await fetch(PROVIDER_OAUTH["github"]?.copilotTokenUrl, {
+      headers: {
+        "Authorization": `token ${githubAccessToken}`,
+        "User-Agent": GITHUB_COPILOT.USER_AGENT,
+        "Editor-Version": `vscode/${GITHUB_COPILOT.VSCODE_VERSION}`,
+        "Editor-Plugin-Version": `copilot-chat/${GITHUB_COPILOT.COPILOT_CHAT_VERSION}`,
+        "Accept": "application/json",
+        "x-github-api-version": GITHUB_COPILOT.API_VERSION
+      }
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log?.error?.("TOKEN_REFRESH", "Failed to refresh Copilot token", {
+        status: response.status,
+        error: errorText
+      });
+      return null;
+    }
+
+    const data = await response.json();
+
+    log?.info?.("TOKEN_REFRESH", "Successfully refreshed Copilot token", {
+      hasToken: !!data.token,
+      expiresAt: data.expires_at
+    });
+
+    return {
+      token: data.token,
+      expiresAt: data.expires_at
+    };
+  } catch (error) {
+    log?.error?.("TOKEN_REFRESH", "Error refreshing Copilot token", {
+      error: error.message
+    });
+    return null;
+  }
+  }, log);
+}
+
+// CodeBuddy (Tencent) refresh — POST /v2/plugin/auth/token/refresh with the
+// refresh token carried in the X-Refresh-Token header (not a form body),
+// matching the official CodeBuddy CLI. Response: { code: 0, data: <token> }.
+export async function refreshCodebuddyToken(refreshToken, log) {
+  if (!refreshToken) return null;
+  return dedupRefresh("codebuddy-cn", refreshToken, async () => {
+    const oauth = PROVIDER_OAUTH["codebuddy-cn"] || {};
+    const response = await fetch(oauth.refreshUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "User-Agent": oauth.userAgent,
+        "X-Requested-With": "XMLHttpRequest",
+        "X-Domain": "copilot.tencent.com",
+        "X-Refresh-Token": refreshToken,
+        "X-Auth-Refresh-Source": "plugin",
+        "X-Product": "SaaS",
+      },
+      body: "{}",
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log?.error?.("TOKEN_REFRESH", "Failed to refresh CodeBuddy token", {
+        status: response.status,
+        error: errorText,
+      });
+      return null;
+    }
+
+    const data = await response.json();
+    if (data.code !== 0 || !data.data?.accessToken) {
+      log?.error?.("TOKEN_REFRESH", "CodeBuddy token refresh returned no token", {
+        code: data.code,
+        msg: data.msg,
+      });
+      return null;
+    }
+
+    log?.info?.("TOKEN_REFRESH", "Successfully refreshed CodeBuddy token", {
+      hasNewAccessToken: !!data.data.accessToken,
+      hasNewRefreshToken: !!data.data.refreshToken,
+      expiresIn: data.data.expiresIn,
+    });
+
+    return {
+      accessToken: data.data.accessToken,
+      refreshToken: data.data.refreshToken || refreshToken,
+      expiresIn: data.data.expiresIn,
+    };
+  }, log);
+}
diff --git a/open-sse/services/usage.js b/open-sse/services/usage.js
new file mode 100644
index 0000000..43bfc8e
--- /dev/null
+++ b/open-sse/services/usage.js
@@ -0,0 +1,60 @@
+/**
+ * Usage Fetcher - Get usage data from provider APIs
+ */
+
+import { getGitHubUsage } from "./usage/github.js";
+import { getGeminiUsage, getAntigravityUsage } from "./usage/google.js";
+import { getClaudeUsage } from "./usage/claude.js";
+import { getCodexUsage, consumeCodexRateLimitResetCredit, getCodexRateLimitResetCredits } from "./usage/codex.js";
+
+export { consumeCodexRateLimitResetCredit, getCodexRateLimitResetCredits };
+import { getKiroUsage } from "./usage/kiro.js";
+import { getMiniMaxUsage } from "./usage/minimax.js";
+import { getCodeBuddyCnUsage } from "./usage/codebuddy-cn.js";
+import { getGrokCliUsage } from "./usage/grok-cli.js";
+import {
+  getQwenUsage,
+  getIflowUsage,
+  getOllamaUsage,
+  getGlmUsage,
+  getVercelAiGatewayUsage,
+  getQoderUsage,
+} from "./usage/misc.js";
+
+/**
+ * Get usage data for a provider connection
+ * @param {Object} connection - Provider connection with accessToken
+ * @returns {Object} Usage data with quotas
+ */
+// provider → usage handler (ctx carries every arg each handler needs)
+const USAGE_HANDLERS = {
+  github: (c) => getGitHubUsage(c.accessToken, c.providerSpecificData, c.proxyOptions),
+  "gemini-cli": (c) => getGeminiUsage(c.accessToken, c.providerDataWithProjectId, c.proxyOptions),
+  antigravity: (c) => getAntigravityUsage(c.accessToken, c.providerSpecificData, c.proxyOptions),
+  claude: (c) => getClaudeUsage(c.accessToken, c.proxyOptions),
+  codex: (c) => getCodexUsage(c.accessToken, c.proxyOptions),
+  kiro: (c) => getKiroUsage(c.accessToken, c.providerSpecificData, c.proxyOptions),
+  qoder: (c) => getQoderUsage(c.accessToken, c.proxyOptions),
+  qwen: (c) => getQwenUsage(c.accessToken, c.providerSpecificData),
+  iflow: (c) => getIflowUsage(c.accessToken),
+  ollama: (c) => getOllamaUsage(c.accessToken),
+  glm: (c) => getGlmUsage(c.apiKey, c.provider, c.proxyOptions),
+  "glm-cn": (c) => getGlmUsage(c.apiKey, c.provider, c.proxyOptions),
+  minimax: (c) => getMiniMaxUsage(c.apiKey, c.provider, c.proxyOptions),
+  "minimax-cn": (c) => getMiniMaxUsage(c.apiKey, c.provider, c.proxyOptions),
+  "vercel-ai-gateway": (c) => getVercelAiGatewayUsage(c.apiKey, c.proxyOptions),
+  "codebuddy-cn": (c) => getCodeBuddyCnUsage(c.accessToken, c.apiKey, c.providerSpecificData, c.proxyOptions),
+  "grok-cli": (c) => getGrokCliUsage(c.accessToken, c.providerSpecificData, c.proxyOptions),
+};
+
+export async function getUsageForProvider(connection, proxyOptions = null) {
+  const { provider, accessToken, apiKey, providerSpecificData, projectId } = connection;
+  const providerDataWithProjectId = {
+    ...(providerSpecificData || {}),
+    ...(projectId ? { projectId } : {}),
+  };
+
+  const handler = USAGE_HANDLERS[provider];
+  if (!handler) return { message: `Usage API not implemented for ${provider}` };
+  return await handler({ provider, accessToken, apiKey, providerSpecificData, providerDataWithProjectId, proxyOptions });
+}
diff --git a/open-sse/services/usage/claude.js b/open-sse/services/usage/claude.js
new file mode 100644
index 0000000..85ab8e6
--- /dev/null
+++ b/open-sse/services/usage/claude.js
@@ -0,0 +1,147 @@
+/**
+ * Claude usage handler
+ */
+
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { ANTHROPIC_API_VERSION } from "../../providers/shared.js";
+import { U, parseResetTime } from "./shared.js";
+
+// Claude API config (urls from registry, apiVersion is header logic kept here)
+const CLAUDE_CONFIG = {
+  oauthUsageUrl: U("claude").oauthUrl,
+  usageUrl: U("claude").orgUrl,
+  settingsUrl: U("claude").settingsUrl,
+  apiVersion: ANTHROPIC_API_VERSION,
+};
+
+// OAuth usage endpoint rate-limits (429); cool down per-token to stop hammering it.
+// Only the quota endpoint is affected — chat with the same token still works.
+const OAUTH_429_COOLDOWN_MS = 180000;
+const oauthCooldown = new Map();
+
+export async function getClaudeUsage(accessToken, proxyOptions = null) {
+  try {
+    // Skip OAuth usage call while this token is cooling down from a recent 429
+    const cooldownUntil = oauthCooldown.get(accessToken);
+    if (cooldownUntil && Date.now() < cooldownUntil) {
+      return await getClaudeUsageLegacy(accessToken, proxyOptions);
+    }
+
+    // Primary: OAuth usage endpoint (Claude Code consumer OAuth tokens)
+    const oauthResponse = await proxyAwareFetch(CLAUDE_CONFIG.oauthUsageUrl, {
+      method: "GET",
+      headers: {
+        "Authorization": `Bearer ${accessToken}`,
+        "anthropic-beta": "oauth-2025-04-20",
+        "anthropic-version": CLAUDE_CONFIG.apiVersion,
+      },
+    }, proxyOptions);
+
+    if (oauthResponse.ok) {
+      const data = await oauthResponse.json();
+      const quotas = {};
+
+      // utilization = % USED (e.g. 87 means 87% used, 13% remaining)
+      const hasUtilization = (window) =>
+        window && typeof window === "object" && typeof window.utilization === "number";
+
+      const createQuotaObject = (window) => {
+        const used = window.utilization;
+        const remaining = Math.max(0, 100 - used);
+        return {
+          used,
+          total: 100,
+          remaining,
+          remainingPercentage: remaining,
+          resetAt: parseResetTime(window.resets_at),
+          unlimited: false,
+        };
+      };
+
+      if (hasUtilization(data.five_hour)) {
+        quotas["session (5h)"] = createQuotaObject(data.five_hour);
+      }
+
+      if (hasUtilization(data.seven_day)) {
+        quotas["weekly (7d)"] = createQuotaObject(data.seven_day);
+      }
+
+      // Parse model-specific weekly windows (e.g. seven_day_sonnet, seven_day_opus)
+      for (const [key, value] of Object.entries(data)) {
+        if (key.startsWith("seven_day_") && key !== "seven_day" && hasUtilization(value)) {
+          const modelName = key.replace("seven_day_", "");
+          quotas[`weekly ${modelName} (7d)`] = createQuotaObject(value);
+        }
+      }
+
+      return {
+        plan: "Claude Code",
+        extraUsage: data.extra_usage ?? null,
+        quotas,
+      };
+    }
+
+    // Cool down OAuth usage polling after a 429 (quota endpoint only)
+    if (oauthResponse.status === 429) {
+      oauthCooldown.set(accessToken, Date.now() + OAUTH_429_COOLDOWN_MS);
+    }
+
+    // Fallback: legacy settings + org usage endpoint
+    console.warn(`[Claude Usage] OAuth endpoint returned ${oauthResponse.status}, falling back to legacy`);
+    return await getClaudeUsageLegacy(accessToken, proxyOptions);
+  } catch (error) {
+    return { message: `Claude connected. Unable to fetch usage: ${error.message}` };
+  }
+}
+
+/**
+ * Legacy Claude usage for API key / org admin users
+ */
+async function getClaudeUsageLegacy(accessToken, proxyOptions = null) {
+  try {
+    const settingsResponse = await proxyAwareFetch(CLAUDE_CONFIG.settingsUrl, {
+      method: "GET",
+      headers: {
+        "Authorization": `Bearer ${accessToken}`,
+        "anthropic-version": CLAUDE_CONFIG.apiVersion,
+      },
+    }, proxyOptions);
+
+    if (settingsResponse.ok) {
+      const settings = await settingsResponse.json();
+
+      if (settings.organization_id) {
+        const usageResponse = await proxyAwareFetch(
+          CLAUDE_CONFIG.usageUrl.replace("{org_id}", settings.organization_id),
+          {
+            method: "GET",
+            headers: {
+              "Authorization": `Bearer ${accessToken}`,
+              "anthropic-version": CLAUDE_CONFIG.apiVersion,
+            },
+          },
+          proxyOptions
+        );
+
+        if (usageResponse.ok) {
+          const usage = await usageResponse.json();
+          return {
+            plan: settings.plan || "Unknown",
+            organization: settings.organization_name,
+            quotas: usage,
+          };
+        }
+      }
+
+      return {
+        plan: settings.plan || "Unknown",
+        organization: settings.organization_name,
+        message: "Claude connected. Usage details require admin access.",
+      };
+    }
+
+    return { message: "Claude connected. Usage API requires admin permissions." };
+  } catch (error) {
+    return { message: `Claude connected. Unable to fetch usage: ${error.message}` };
+  }
+}
diff --git a/open-sse/services/usage/codebuddy-cn.js b/open-sse/services/usage/codebuddy-cn.js
new file mode 100644
index 0000000..d355c72
--- /dev/null
+++ b/open-sse/services/usage/codebuddy-cn.js
@@ -0,0 +1,138 @@
+/**
+ * CodeBuddy CN usage handler
+ *
+ * Scoped to the "codebuddy-cn" provider specifically — a future "codebuddy-intl"
+ * variant would get its own handler/endpoint, so keep this CN-only.
+ *
+ * Quota lives behind a Tencent billing endpoint (POST, payload wrapped twice
+ * under data.Response.Data). It mixes two credit types that must NOT be merged:
+ *
+ *  - Refill / base ("基础体验包"): a recurring allowance whose cycle resets long
+ *    before the resource itself expires (CycleEndTime << DeductionEndTime). The
+ *    live numbers live in the *Cycle* fields (e.g. CycleCapacityUsed 6.54 / 500)
+ *    and resetAt is the next monthly refresh.
+ *  - Bonus ("活动赠送包"): one-shot credits that run a single cycle and then
+ *    expire for good (CycleEndTime == DeductionEndTime). Numbers live in the
+ *    plain Capacity fields.
+ *
+ * We surface one quota row per package — a cadence label (Monthly/Weekly/Daily)
+ * for refill packs, "Bonus Pack N" for bonus packs (soonest-expiring first).
+ */
+
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { PROVIDERS } from "../../providers/index.js";
+import { U, parseResetTime } from "./shared.js";
+
+const PROVIDER_ID = "codebuddy-cn";
+
+// Prefer the *Precise string fields (exact), fall back to the numeric ones.
+function num(precise, plain) {
+  const n = Number(precise ?? plain);
+  return Number.isFinite(n) ? n : 0;
+}
+
+// Label a refill pack by its cycle length (Monthly is the common CodeBuddy case).
+function refillCadence(acc) {
+  const start = parseResetTime(acc.CycleStartTime);
+  const end = parseResetTime(acc.CycleEndTime);
+  if (start && end) {
+    const days = (new Date(end).getTime() - new Date(start).getTime()) / 86400000;
+    if (days <= 1.5) return "Daily";
+    if (days <= 10) return "Weekly";
+  }
+  return "Monthly";
+}
+
+export async function getCodeBuddyCnUsage(accessToken, apiKey, providerSpecificData, proxyOptions = null) {
+  const token = accessToken || apiKey;
+  if (!token) {
+    return { message: "CodeBuddy CN credential not available." };
+  }
+
+  try {
+    const response = await proxyAwareFetch(U(PROVIDER_ID).url, {
+      method: "POST",
+      headers: {
+        ...(PROVIDERS[PROVIDER_ID]?.headers || {}),
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: "{}",
+    }, proxyOptions);
+
+    if (response.status === 401 || response.status === 403) {
+      return { message: "CodeBuddy CN credential invalid or expired." };
+    }
+    if (!response.ok) {
+      return { message: `CodeBuddy CN quota API error (${response.status}).` };
+    }
+
+    const json = await response.json();
+    if (json?.code !== 0) {
+      return { message: `CodeBuddy CN quota error: ${json?.msg || "unknown"}` };
+    }
+
+    const data = json?.data?.Response?.Data || {};
+    const accounts = Array.isArray(data.Accounts) ? data.Accounts : [];
+    if (accounts.length === 0) {
+      return { message: "CodeBuddy CN connected. No credit package found." };
+    }
+
+    const cycleEndMs = (acc) => {
+      const r = parseResetTime(acc.CycleEndTime);
+      return r ? new Date(r).getTime() : Number.POSITIVE_INFINITY;
+    };
+    // Refill packs roll into a new cycle before the resource expires; bonus packs
+    // end exactly at expiry. >2d gap between cycle end and validity end = refill.
+    const REFILL_GAP_MS = 2 * 24 * 60 * 60 * 1000;
+    const isRefill = (acc) => {
+      const ce = cycleEndMs(acc);
+      const de = Number(acc.DeductionEndTime);
+      return Number.isFinite(ce) && Number.isFinite(de) && de - ce > REFILL_GAP_MS;
+    };
+    const byExpiry = (a, b) => cycleEndMs(a) - cycleEndMs(b);
+
+    const refills = accounts.filter(isRefill).sort(byExpiry);
+    const bonuses = accounts.filter((a) => !isRefill(a)).sort(byExpiry);
+
+    const quotas = {};
+    // Refill packs first: cadence-labelled, using the *Cycle* balance and
+    // resetting at the next refresh.
+    const seenRefill = {};
+    refills.forEach((acc) => {
+      const base = refillCadence(acc);
+      seenRefill[base] = (seenRefill[base] || 0) + 1;
+      const name = seenRefill[base] > 1 ? `${base} ${seenRefill[base]}` : base;
+      quotas[name] = {
+        used: num(acc.CycleCapacityUsedPrecise, acc.CycleCapacityUsed),
+        total: num(acc.CycleCapacitySizePrecise, acc.CycleCapacitySize),
+        resetAt: parseResetTime(acc.CycleEndTime),
+        unlimited: false,
+        // Recurring allowance: the CycleEndTime is the next refresh, not the
+        // final expiry. The UI must show "Resets in", not "Expires in".
+        recurring: true,
+      };
+    });
+    // Bonus packs: use the lifetime Capacity balance; resetAt is the expiry.
+    // These are one-shot credits (CycleEndTime == DeductionEndTime), so they
+    // never replenish — mark recurring:false so the UI shows "Expires in"
+    // instead of implying a monthly refill.
+    bonuses.forEach((acc, i) => {
+      quotas[`Bonus Pack ${i + 1}`] = {
+        used: num(acc.CapacityUsedPrecise, acc.CapacityUsed),
+        total: num(acc.CapacitySizePrecise, acc.CapacitySize),
+        resetAt: parseResetTime(acc.CycleEndTime),
+        unlimited: false,
+        recurring: false,
+      };
+    });
+
+    const basePkg = refills[0] || accounts[0] || {};
+    const plan = basePkg.PackageName || basePkg.SubProductName || "CodeBuddy CN";
+
+    return { plan, quotas };
+  } catch (error) {
+    return { message: `CodeBuddy CN error: ${error.message}` };
+  }
+}
diff --git a/open-sse/services/usage/codex.js b/open-sse/services/usage/codex.js
new file mode 100644
index 0000000..960af33
--- /dev/null
+++ b/open-sse/services/usage/codex.js
@@ -0,0 +1,201 @@
+/**
+ * Codex (OpenAI) usage handler
+ */
+
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { U, parseResetTime, toFiniteNumber } from "./shared.js";
+
+// Codex (OpenAI) API config
+const CODEX_CONFIG = {
+  usageUrl: U("codex").url,
+  resetCreditsUrl: U("codex").resetCreditsUrl,
+  resetCreditsConsumeUrl: U("codex").resetCreditsConsumeUrl,
+};
+
+function toIsoDate(value) {
+  if (!value) return null;
+  const date = value instanceof Date
+    ? value
+    : new Date(typeof value === "number" && value < 1e12 ? value * 1000 : value);
+  const time = date.getTime();
+  return Number.isFinite(time) ? date.toISOString() : null;
+}
+
+function getCodexAccountId(providerSpecificData) {
+  return providerSpecificData?.workspaceId || providerSpecificData?.accountId || providerSpecificData?.chatgptAccountId || null;
+}
+
+function getCodexRateLimitBody(snapshot) {
+  if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) return null;
+  return snapshot.rate_limit && typeof snapshot.rate_limit === "object"
+    ? snapshot.rate_limit
+    : snapshot;
+}
+
+function formatCodexWindow(window) {
+  const used = Math.max(0, Math.min(100, toFiniteNumber(window?.used_percent ?? window?.percent_used, 0)));
+  return {
+    used,
+    total: 100,
+    remaining: Math.max(0, 100 - used),
+    resetAt: parseResetTime(window?.reset_at ?? window?.resets_at ?? window?.resetAt ?? null),
+    unlimited: false,
+  };
+}
+
+function appendCodexQuotaWindows(quotas, prefix, snapshot) {
+  const rateLimit = getCodexRateLimitBody(snapshot);
+  if (!rateLimit) return false;
+
+  const primary = rateLimit.primary_window || rateLimit.primary || snapshot.primary_window || snapshot.primary;
+  const secondary = rateLimit.secondary_window || rateLimit.secondary || snapshot.secondary_window || snapshot.secondary;
+  let added = false;
+
+  if (primary) {
+    quotas[prefix ? `${prefix}_session` : "session"] = formatCodexWindow(primary);
+    added = true;
+  }
+  if (secondary) {
+    quotas[prefix ? `${prefix}_weekly` : "weekly"] = formatCodexWindow(secondary);
+    added = true;
+  }
+
+  return added;
+}
+
+function getCodexReviewRateLimit(data) {
+  if (data.code_review_rate_limit || data.review_rate_limit) {
+    return data.code_review_rate_limit || data.review_rate_limit;
+  }
+
+  const byLimitId = data.rate_limits_by_limit_id;
+  if (byLimitId && typeof byLimitId === "object" && !Array.isArray(byLimitId)) {
+    return byLimitId.code_review || byLimitId.codex_review || byLimitId.review || null;
+  }
+
+  const additional = Array.isArray(data.additional_rate_limits) ? data.additional_rate_limits : [];
+  return additional.find((entry) => {
+    const id = String(entry?.limit_name || entry?.metered_feature || entry?.id || "").toLowerCase();
+    return id === "code_review" || id === "codex_review" || id === "review" || id.includes("review");
+  }) || null;
+}
+
+export async function getCodexUsage(accessToken, proxyOptions = null) {
+  try {
+    const response = await proxyAwareFetch(CODEX_CONFIG.usageUrl, {
+      method: "GET",
+      headers: {
+        "Authorization": `Bearer ${accessToken}`,
+        "Accept": "application/json",
+      },
+    }, proxyOptions);
+
+    if (!response.ok) {
+      return { message: `Codex connected. Usage API temporarily unavailable (${response.status}).` };
+    }
+
+    const data = await response.json();
+    const normalRateLimit = data.rate_limit || data.rate_limits || data.rate_limits_by_limit_id?.codex || {};
+    const reviewRateLimit = getCodexReviewRateLimit(data);
+    const availableResetCredits = Math.max(0, toFiniteNumber(data.rate_limit_reset_credits?.available_count, 0));
+    const quotas = {};
+
+    appendCodexQuotaWindows(quotas, "", normalRateLimit);
+    appendCodexQuotaWindows(quotas, "review", reviewRateLimit);
+
+    return {
+      plan: data.plan_type || data.summary?.plan || "unknown",
+      limitReached: getCodexRateLimitBody(normalRateLimit)?.limit_reached || false,
+      reviewLimitReached: getCodexRateLimitBody(reviewRateLimit)?.limit_reached || false,
+      resetCredits: { availableCount: availableResetCredits },
+      quotas,
+    };
+  } catch (error) {
+    throw new Error(`Failed to fetch Codex usage: ${error.message}`);
+  }
+}
+
+export async function getCodexRateLimitResetCredits(accessToken, proxyOptions = null, providerSpecificData = null) {
+  if (!accessToken) {
+    throw new Error("No Codex access token available. Please re-authorize the connection.");
+  }
+
+  const accountId = getCodexAccountId(providerSpecificData);
+  const headers = {
+    "Authorization": `Bearer ${accessToken}`,
+    "Accept": "application/json",
+    "OpenAI-Beta": "codex-1",
+    "originator": "codex_cli_rs",
+  };
+  if (accountId) headers["ChatGPT-Account-ID"] = accountId;
+
+  const response = await proxyAwareFetch(CODEX_CONFIG.resetCreditsUrl, {
+    method: "GET",
+    headers,
+  }, proxyOptions);
+
+  let data = null;
+  try {
+    data = await response.json();
+  } catch {
+    data = null;
+  }
+
+  if (!response.ok) {
+    const message = data?.message || data?.error || data?.detail || `Codex reset credits API unavailable (${response.status}).`;
+    throw new Error(message);
+  }
+
+  const credits = Array.isArray(data?.credits) ? data.credits : [];
+  return {
+    availableCount: Math.max(0, toFiniteNumber(data?.available_count ?? data?.availableCount, 0)),
+    credits: credits.map((credit) => ({
+      status: String(credit?.status || "unknown"),
+      grantedAt: toIsoDate(credit?.granted_at ?? credit?.grantedAt),
+      expiresAt: toIsoDate(credit?.expires_at ?? credit?.expiresAt),
+    })),
+  };
+}
+
+// Consume one Codex rate-limit reset credit (irreversible, spends 1 credit)
+export async function consumeCodexRateLimitResetCredit(accessToken, redeemRequestId, proxyOptions = null) {
+  if (!accessToken) {
+    throw new Error("No Codex access token available. Please re-authorize the connection.");
+  }
+  if (!redeemRequestId || typeof redeemRequestId !== "string") {
+    throw new Error("A redeem request id is required to consume a Codex reset credit.");
+  }
+
+  let response;
+  let data = null;
+  try {
+    response = await proxyAwareFetch(CODEX_CONFIG.resetCreditsConsumeUrl, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${accessToken}`,
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ redeem_request_id: redeemRequestId }),
+    }, proxyOptions);
+
+    const text = await response.text();
+    data = text ? JSON.parse(text) : null;
+  } catch (error) {
+    throw new Error(`Failed to consume Codex reset credit: ${error.message}`);
+  }
+
+  const code = data?.code || null;
+  const windowsReset = toFiniteNumber(data?.windows_reset, 0);
+  const success = response.ok && (code === "reset" || windowsReset > 0);
+
+  return {
+    ok: success,
+    noCredit: response.ok && code === "no_credit",
+    status: response.status,
+    code,
+    windowsReset,
+    message: data?.message || null,
+    raw: data,
+  };
+}
diff --git a/open-sse/services/usage/github.js b/open-sse/services/usage/github.js
new file mode 100644
index 0000000..8eec3b6
--- /dev/null
+++ b/open-sse/services/usage/github.js
@@ -0,0 +1,100 @@
+/**
+ * GitHub Copilot usage handler
+ */
+
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { PROVIDER_OAUTH } from "../../providers/index.js";
+import { U, parseResetTime } from "./shared.js";
+
+// GitHub API config — single source from registry oauth block
+const GITHUB_CONFIG = {
+  apiVersion: PROVIDER_OAUTH.github?.apiVersion,
+  userAgent: PROVIDER_OAUTH.github?.userAgent,
+};
+
+/**
+ * GitHub Copilot Usage
+ * Uses GitHub accessToken (not copilotToken) to call copilot_internal/user API
+ */
+export async function getGitHubUsage(accessToken, providerSpecificData, proxyOptions = null) {
+  try {
+    if (!accessToken) {
+      throw new Error("No GitHub access token available. Please re-authorize the connection.");
+    }
+
+    // copilot_internal/user API requires GitHub OAuth token, not copilotToken
+    const response = await proxyAwareFetch(U("github").url, {
+      headers: {
+        "Authorization": `token ${accessToken}`,
+        "Accept": "application/json",
+        "X-GitHub-Api-Version": GITHUB_CONFIG.apiVersion,
+        "User-Agent": GITHUB_CONFIG.userAgent,
+        "Editor-Version": "vscode/1.100.0",
+        "Editor-Plugin-Version": "copilot-chat/0.26.7",
+      },
+    }, proxyOptions);
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`GitHub API error: ${error}`);
+    }
+
+    const data = await response.json();
+
+    // Handle different response formats (paid vs free)
+    if (data.quota_snapshots) {
+      // Paid plan format
+      const snapshots = data.quota_snapshots;
+      const resetAt = parseResetTime(data.quota_reset_date);
+
+      return {
+        plan: data.copilot_plan,
+        resetDate: data.quota_reset_date,
+        quotas: {
+          chat: { ...formatGitHubQuotaSnapshot(snapshots.chat), resetAt },
+          completions: { ...formatGitHubQuotaSnapshot(snapshots.completions), resetAt },
+          premium_interactions: { ...formatGitHubQuotaSnapshot(snapshots.premium_interactions), resetAt },
+        },
+      };
+    } else if (data.monthly_quotas || data.limited_user_quotas) {
+      // Free/limited plan format
+      const monthlyQuotas = data.monthly_quotas || {};
+      const usedQuotas = data.limited_user_quotas || {};
+      const resetAt = parseResetTime(data.limited_user_reset_date);
+
+      return {
+        plan: data.copilot_plan || data.access_type_sku,
+        resetDate: data.limited_user_reset_date,
+        quotas: {
+          chat: {
+            used: usedQuotas.chat || 0,
+            total: monthlyQuotas.chat || 0,
+            unlimited: false,
+            resetAt,
+          },
+          completions: {
+            used: usedQuotas.completions || 0,
+            total: monthlyQuotas.completions || 0,
+            unlimited: false,
+            resetAt,
+          },
+        },
+      };
+    }
+
+    return { message: "GitHub Copilot connected. Unable to parse quota data." };
+  } catch (error) {
+    throw new Error(`Failed to fetch GitHub usage: ${error.message}`);
+  }
+}
+
+function formatGitHubQuotaSnapshot(quota) {
+  if (!quota) return { used: 0, total: 0, unlimited: true };
+
+  return {
+    used: quota.entitlement - quota.remaining,
+    total: quota.entitlement,
+    remaining: quota.remaining,
+    unlimited: quota.unlimited || false,
+  };
+}
diff --git a/open-sse/services/usage/google.js b/open-sse/services/usage/google.js
new file mode 100644
index 0000000..f0e4d23
--- /dev/null
+++ b/open-sse/services/usage/google.js
@@ -0,0 +1,241 @@
+/**
+ * Google usage handlers (Gemini CLI + Antigravity)
+ */
+
+import { CLIENT_METADATA } from "../../config/appConstants.js";
+import { ANTIGRAVITY_IDE_USER_AGENT, ANTIGRAVITY_IDE_VERSION, ANTIGRAVITY_OAUTH_CLIENT } from "../../providers/shared.js";
+import { U, parseResetTime, normalizeCloudCodeProjectId, fetchWithTimeout } from "./shared.js";
+
+// Antigravity API config (from Quotio) — urls from registry, oauth client + dynamic UA kept here
+const ANTIGRAVITY_CONFIG = {
+  ...U("antigravity"),
+  ...ANTIGRAVITY_OAUTH_CLIENT,
+  userAgent: ANTIGRAVITY_IDE_USER_AGENT,
+};
+
+/**
+ * Gemini CLI Usage — fetch per-model quota via Cloud Code Assist API.
+ * Uses retrieveUserQuota (same endpoint as `gemini /stats`) returning
+ * per-model buckets with remainingFraction + resetTime.
+ */
+export async function getGeminiUsage(accessToken, providerSpecificData, proxyOptions = null) {
+  if (!accessToken) {
+    return { plan: "Free", message: "Gemini CLI access token not available." };
+  }
+
+  try {
+    // Resolve project id: prefer connection-stored id, else loadCodeAssist lookup.
+    // #1271: OAuth save stores projectId on the connection, not providerSpecificData.
+    let projectId = normalizeCloudCodeProjectId(providerSpecificData?.projectId);
+    let plan = "Free";
+
+    if (!projectId) {
+      const subInfo = await getGeminiSubscriptionInfo(accessToken, proxyOptions);
+      projectId = normalizeCloudCodeProjectId(subInfo?.cloudaicompanionProject);
+      plan = subInfo?.currentTier?.name || plan;
+    }
+
+    if (!projectId) {
+      return {
+        plan,
+        message: "Gemini CLI project ID not available. Reconnect Gemini CLI, or configure a Google Cloud project with Gemini Code Assist access before checking quota.",
+      };
+    }
+
+    const response = await fetchWithTimeout(
+      U("gemini-cli").quotaUrl,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ project: projectId }),
+      },
+      10000,
+      proxyOptions
+    );
+
+    if (!response.ok) {
+      return { plan, message: `Gemini CLI quota error (${response.status}).` };
+    }
+
+    const data = await response.json();
+    const quotas = {};
+
+    if (Array.isArray(data.buckets)) {
+      for (const bucket of data.buckets) {
+        if (!bucket.modelId || bucket.remainingFraction == null) continue;
+
+        const remainingFraction = Number(bucket.remainingFraction) || 0;
+        const total = 1000; // Normalized base, matches antigravity convention
+        const remaining = Math.round(total * remainingFraction);
+        const used = Math.max(0, total - remaining);
+
+        quotas[bucket.modelId] = {
+          used,
+          total,
+          resetAt: parseResetTime(bucket.resetTime),
+          remainingPercentage: remainingFraction * 100,
+          unlimited: false,
+        };
+      }
+    }
+
+    return { plan, quotas };
+  } catch (error) {
+    return { message: `Gemini CLI error: ${error.message}` };
+  }
+}
+
+/**
+ * Get Gemini CLI subscription info via loadCodeAssist
+ */
+async function getGeminiSubscriptionInfo(accessToken, proxyOptions = null) {
+  try {
+    const response = await fetchWithTimeout(
+      U("gemini-cli").loadCodeAssistUrl,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ metadata: CLIENT_METADATA }),
+      },
+      10000,
+      proxyOptions
+    );
+    if (!response.ok) return null;
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Antigravity Usage - Fetch quota from Google Cloud Code API
+ */
+export async function getAntigravityUsage(accessToken, providerSpecificData, proxyOptions = null) {
+  try {
+    // Fetch subscription info once — reuse for both projectId and plan
+    const subscriptionInfo = await getAntigravitySubscriptionInfo(accessToken, proxyOptions);
+    const projectId = subscriptionInfo?.cloudaicompanionProject || null;
+
+    const response = await fetchWithTimeout(ANTIGRAVITY_CONFIG.quotaApiUrl, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${accessToken}`,
+        "User-Agent": ANTIGRAVITY_CONFIG.userAgent,
+        "Content-Type": "application/json",
+        "X-Client-Name": "antigravity",
+        "X-Client-Version": ANTIGRAVITY_IDE_VERSION,
+      },
+      body: JSON.stringify({
+        ...(projectId ? { project: projectId } : {})
+      }),
+    }, 10000, proxyOptions);
+
+    if (response.status === 403) {
+      return {
+        message: "Antigravity quota API access forbidden. Chat may still work.",
+        quotas: {}
+      };
+    }
+
+    if (response.status === 401) {
+      return {
+        message: "Antigravity quota API authentication expired. Chat may still work.",
+        quotas: {}
+      };
+    }
+
+    if (!response.ok) {
+      throw new Error(`Antigravity API error: ${response.status}`);
+    }
+
+    const data = await response.json();
+    const quotas = {};
+
+    // Parse model quotas (inspired by vscode-antigravity-cockpit)
+    if (data.models) {
+      // Filter only recommended/important models (must match PROVIDER_MODELS ag ids)
+      const importantModels = [
+        'gemini-3-flash-agent',
+        'gemini-3.5-flash-low',
+        'gemini-3.5-flash-extra-low',
+        'gemini-pro-agent',
+        'gemini-3.1-pro-low',
+        'claude-sonnet-4-6',
+        'claude-opus-4-6-thinking',
+        'gpt-oss-120b-medium',
+        'gemini-3-flash',
+        // Image generation models
+        'gemini-3.1-flash-image',
+        'gemini-3-pro-image',
+      ];
+
+      for (const [modelKey, info] of Object.entries(data.models)) {
+        // Skip models without quota info
+        if (!info.quotaInfo) {
+          continue;
+        }
+
+        // Skip internal models and non-important models
+        if (info.isInternal || !importantModels.includes(modelKey)) {
+          continue;
+        }
+
+        const remainingFraction = info.quotaInfo.remainingFraction || 0;
+        const remainingPercentage = remainingFraction * 100;
+
+        // Convert percentage to used/total for UI compatibility
+        const total = 1000; // Normalized base
+        const remaining = Math.round(total * remainingFraction);
+        const used = total - remaining;
+
+        // Use modelKey as key (matches PROVIDER_MODELS id)
+        quotas[modelKey] = {
+          used,
+          total,
+          resetAt: parseResetTime(info.quotaInfo.resetTime),
+          remainingPercentage,
+          unlimited: false,
+          displayName: info.displayName || modelKey,
+        };
+      }
+    }
+
+    return {
+      plan: subscriptionInfo?.currentTier?.name || "Unknown",
+      quotas,
+      subscriptionInfo,
+    };
+  } catch (error) {
+    console.error("[Antigravity Usage] Error:", error.message, error.cause);
+    return { message: `Antigravity error: ${error.message}` };
+  }
+}
+
+/**
+ * Get Antigravity subscription info
+ */
+async function getAntigravitySubscriptionInfo(accessToken, proxyOptions = null) {
+  try {
+    const response = await fetchWithTimeout(ANTIGRAVITY_CONFIG.loadProjectApiUrl, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${accessToken}`,
+        "User-Agent": ANTIGRAVITY_CONFIG.userAgent,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ metadata: CLIENT_METADATA, mode: 1 }),
+    }, 10000, proxyOptions);
+
+    if (!response.ok) return null;
+    return await response.json();
+  } catch (error) {
+    console.error("[Antigravity Subscription] Error:", error.message);
+    return null;
+  }
+}
diff --git a/open-sse/services/usage/grok-cli.js b/open-sse/services/usage/grok-cli.js
new file mode 100644
index 0000000..b412b5e
--- /dev/null
+++ b/open-sse/services/usage/grok-cli.js
@@ -0,0 +1,274 @@
+/**
+ * Grok CLI / Grok Build usage handler
+ *
+ * Source of truth: official grok-shell/grok-pager traffic to cli-chat-proxy.grok.com
+ *   GET /v1/billing?format=credits
+ *   GET /v1/user?include=subscription
+ *
+ * Observed billing shape (protobuf-json style `{ val: number }`):
+ * {
+ *   config: {
+ *     currentPeriod: { type: "USAGE_PERIOD_TYPE_WEEKLY", start, end },
+ *     onDemandCap: { val },
+ *     onDemandUsed: { val },
+ *     prepaidBalance: { val },
+ *     isUnifiedBillingUser: true,
+ *     billingPeriodStart, billingPeriodEnd
+ *   }
+ * }
+ *
+ * Exhausted free/promo accounts return cap=0/used=0/prepaid=0 and chat 402s with
+ * personal-team-blocked:spending-limit. Paid/sub accounts surface non-zero cap
+ * or prepaidBalance; richer credit fields are parsed opportunistically if present.
+ */
+
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { U, parseResetTime, toFiniteNumber } from "./shared.js";
+
+const USAGE = U("grok-cli");
+const BILLING_URL = USAGE.url || "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+const USER_URL = USAGE.userUrl || "https://cli-chat-proxy.grok.com/v1/user?include=subscription";
+
+/** Unwrap protobuf-json `{ val: n }` or plain numbers/strings. */
+function unwrapVal(value, fallback = 0) {
+  if (value == null) return fallback;
+  if (typeof value === "object" && !Array.isArray(value) && "val" in value) {
+    return toFiniteNumber(value.val, fallback);
+  }
+  return toFiniteNumber(value, fallback);
+}
+
+function buildGrokCliHeaders(accessToken, providerSpecificData = {}) {
+  const psd = providerSpecificData || {};
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    Accept: "application/json",
+    "User-Agent": "grok-pager/0.2.93 grok-shell/0.2.93 (linux; x86_64)",
+    "x-xai-token-auth": "xai-grok-cli",
+    "x-grok-client-identifier": "grok-pager",
+    "x-grok-client-version": "0.2.93",
+  };
+  const email = psd.email;
+  const userId = psd.userId || psd.principalId;
+  if (email) headers["x-email"] = email;
+  if (userId) headers["x-userid"] = userId;
+  return headers;
+}
+
+function resolvePlan(user, config) {
+  const tier = typeof user?.subscriptionTier === "string" ? user.subscriptionTier.trim() : "";
+  if (tier) {
+    return tier
+      .replace(/[_-]+/g, " ")
+      .replace(/\b\w/g, (c) => c.toUpperCase());
+  }
+  if (user?.hasGrokCodeAccess === true) return "Grok Code";
+  if (config?.isUnifiedBillingUser === true) return "Grok Build";
+  return "Grok Build";
+}
+
+function makeQuota({ used, total, resetAt, unlimited = false }) {
+  const safeTotal = Math.max(0, toFiniteNumber(total, 0));
+  const safeUsed = Math.max(0, toFiniteNumber(used, 0));
+  // Do NOT set absolute `remaining` — QuotaTable's getRemainingPercentage treats
+  // `remaining` as a 0–100 percentage (same trap as Qoder credits).
+  if (unlimited || safeTotal === 0) {
+    return {
+      used: safeUsed,
+      total: 0,
+      remainingPercentage: unlimited ? 100 : 0,
+      resetAt: resetAt || null,
+      unlimited: true,
+    };
+  }
+  const remaining = Math.max(0, safeTotal - safeUsed);
+  const remainingPercentage = (remaining / safeTotal) * 100;
+  return {
+    used: safeUsed,
+    total: safeTotal,
+    remainingPercentage,
+    resetAt: resetAt || null,
+    unlimited: false,
+  };
+}
+
+/**
+ * Map billing JSON → normalized quotas object for the dashboard.
+ * Returns { quotas, periodEnd, exhaustedHint } or empty quotas when nothing usable.
+ */
+export function parseGrokCliBilling(billing, user = null) {
+  const root = billing && typeof billing === "object" ? billing : {};
+  const config =
+    root.config && typeof root.config === "object" && !Array.isArray(root.config)
+      ? root.config
+      : root;
+
+  const periodEnd =
+    parseResetTime(config.billingPeriodEnd) ||
+    parseResetTime(config.currentPeriod?.end) ||
+    parseResetTime(root.billingPeriodEnd) ||
+    null;
+
+  const quotas = {};
+
+  // Primary: on-demand spending window (subscription / promo credits)
+  const onDemandCap = unwrapVal(config.onDemandCap ?? root.onDemandCap, NaN);
+  const onDemandUsed = unwrapVal(config.onDemandUsed ?? root.onDemandUsed, NaN);
+  if (Number.isFinite(onDemandCap) && onDemandCap > 0) {
+    const used = Number.isFinite(onDemandUsed) ? Math.max(0, onDemandUsed) : 0;
+    quotas["On-demand"] = makeQuota({
+      used,
+      total: onDemandCap,
+      resetAt: periodEnd,
+    });
+  } else if (Number.isFinite(onDemandCap) && onDemandCap === 0 && Number.isFinite(onDemandUsed)) {
+    // Cap 0 is the exhausted free/promo state (chat returns 402 spending-limit).
+    // UI treats total===0 as unlimited, so use a synthetic 1/1 depleted row.
+    quotas["On-demand"] = {
+      used: 1,
+      total: 1,
+      remainingPercentage: 0,
+      resetAt: periodEnd,
+      unlimited: false,
+    };
+  }
+
+  // Prepaid top-up balance (remaining credits; no fixed allotment known)
+  const prepaid = unwrapVal(config.prepaidBalance ?? root.prepaidBalance, NaN);
+  if (Number.isFinite(prepaid) && prepaid > 0) {
+    // Show full bar against the current balance (0 spent of this remaining pot).
+    quotas["Prepaid"] = {
+      used: 0,
+      total: prepaid,
+      remainingPercentage: 100,
+      resetAt: null,
+      unlimited: false,
+    };
+  }
+
+  // Opportunistic richer credit envelopes (future / other account types)
+  const creditBags = [
+    root.credits,
+    root.creditBalance,
+    root.usage,
+    config.credits,
+    config.includedCredits,
+    config.subscriptionCredits,
+  ].filter((bag) => bag && typeof bag === "object" && !Array.isArray(bag));
+
+  for (const bag of creditBags) {
+    const total = unwrapVal(
+      bag.total ?? bag.limit ?? bag.cap ?? bag.allocation ?? bag.amount,
+      NaN,
+    );
+    const used = unwrapVal(bag.used ?? bag.spent ?? bag.consumed, NaN);
+    const remaining = unwrapVal(bag.remaining ?? bag.balance ?? bag.left, NaN);
+    if (Number.isFinite(total) && total > 0) {
+      const resolvedUsed = Number.isFinite(used)
+        ? used
+        : Number.isFinite(remaining)
+          ? Math.max(0, total - remaining)
+          : 0;
+      if (!quotas.Credits) {
+        quotas.Credits = makeQuota({
+          used: resolvedUsed,
+          total,
+          resetAt: parseResetTime(bag.resetAt || bag.resetsAt || bag.end) || periodEnd,
+        });
+      }
+    } else if (Number.isFinite(remaining) && remaining >= 0 && !quotas.Credits) {
+      quotas.Credits = {
+        used: 0,
+        total: remaining > 0 ? remaining : 1,
+        remainingPercentage: remaining > 0 ? 100 : 0,
+        resetAt: periodEnd,
+        unlimited: false,
+      };
+    }
+  }
+
+  // Exhausted when every finite quota bar is at 0% remaining
+  const exhausted =
+    Object.keys(quotas).length > 0 &&
+    Object.values(quotas).every(
+      (q) => q.unlimited !== true && (q.remainingPercentage ?? 100) <= 0,
+    );
+
+  return {
+    plan: resolvePlan(user, config),
+    quotas,
+    periodEnd,
+    exhausted,
+    rawConfig: config,
+  };
+}
+
+/**
+ * @param {string} accessToken
+ * @param {object|null} providerSpecificData
+ * @param {object|null} proxyOptions
+ */
+export async function getGrokCliUsage(accessToken, providerSpecificData = null, proxyOptions = null) {
+  if (!accessToken) {
+    return { message: "Grok CLI access token not available." };
+  }
+
+  const headers = buildGrokCliHeaders(accessToken, providerSpecificData);
+
+  try {
+    // Fetch billing + user profile in parallel (same pattern as official CLI startup)
+    const [billingRes, userRes] = await Promise.all([
+      proxyAwareFetch(
+        BILLING_URL,
+        { method: "GET", headers },
+        proxyOptions,
+      ),
+      proxyAwareFetch(
+        USER_URL,
+        { method: "GET", headers },
+        proxyOptions,
+      ).catch(() => null),
+    ]);
+
+    if (billingRes.status === 401 || billingRes.status === 403) {
+      return { message: "Grok CLI authentication expired. Please re-authorize." };
+    }
+
+    if (!billingRes.ok) {
+      const errText = await billingRes.text().catch(() => "");
+      const trimmed = errText ? `: ${errText.slice(0, 200)}` : "";
+      return { message: `Grok CLI billing API error (${billingRes.status})${trimmed}` };
+    }
+
+    const billing = await billingRes.json().catch(() => null);
+    if (!billing || typeof billing !== "object") {
+      return { message: "Grok CLI billing response was not JSON." };
+    }
+
+    let user = null;
+    if (userRes?.ok) {
+      user = await userRes.json().catch(() => null);
+    }
+
+    const parsed = parseGrokCliBilling(billing, user);
+
+    if (!parsed.quotas || Object.keys(parsed.quotas).length === 0) {
+      return {
+        plan: parsed.plan,
+        message:
+          "Grok Build connected, but no credit allotment was returned. Free promo may be exhausted — upgrade at https://grok.com/supergrok or add credits at https://grok.com/?_s=usage.",
+        quotas: {},
+      };
+    }
+
+    // Dashboard hides QuotaTable whenever `message` is set, so only attach a
+    // message when there are no quota rows to render. Depleted accounts keep
+    // the 0% On-demand bar without a blocking message.
+    return {
+      plan: parsed.plan,
+      quotas: parsed.quotas,
+    };
+  } catch (error) {
+    return { message: `Grok CLI usage error: ${error.message}` };
+  }
+}
diff --git a/open-sse/services/usage/kiro.js b/open-sse/services/usage/kiro.js
new file mode 100644
index 0000000..f517d0c
--- /dev/null
+++ b/open-sse/services/usage/kiro.js
@@ -0,0 +1,188 @@
+/**
+ * Kiro (AWS CodeWhisperer) usage handler
+ */
+
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { resolveDefaultProfileArn } from "../../config/kiroConstants.js";
+import { U, parseResetTime } from "./shared.js";
+
+/**
+ * Kiro (AWS CodeWhisperer) Usage
+ */
+function parseKiroQuotaData(data) {
+  const usageList = data.usageBreakdownList || [];
+  const quotaInfo = {};
+  const resetAt = parseResetTime(data.nextDateReset || data.resetDate);
+
+  usageList.forEach((breakdown) => {
+    const resourceType = breakdown.resourceType?.toLowerCase() || "unknown";
+    const used = breakdown.currentUsageWithPrecision || 0;
+    const total = breakdown.usageLimitWithPrecision || 0;
+
+    quotaInfo[resourceType] = {
+      used,
+      total,
+      remaining: total - used,
+      resetAt,
+      unlimited: false,
+    };
+
+    // Add free trial if available
+    if (breakdown.freeTrialInfo) {
+      const freeUsed = breakdown.freeTrialInfo.currentUsageWithPrecision || 0;
+      const freeTotal = breakdown.freeTrialInfo.usageLimitWithPrecision || 0;
+
+      quotaInfo[`${resourceType}_freetrial`] = {
+        used: freeUsed,
+        total: freeTotal,
+        remaining: freeTotal - freeUsed,
+        resetAt: parseResetTime(breakdown.freeTrialInfo.freeTrialExpiry || resetAt),
+        unlimited: false,
+      };
+    }
+  });
+
+  return {
+    plan: data.subscriptionInfo?.subscriptionTitle || "Kiro",
+    quotas: quotaInfo,
+  };
+}
+
+export async function getKiroUsage(accessToken, providerSpecificData, proxyOptions = null) {
+  const authMethod = providerSpecificData?.authMethod || "builder-id";
+  // API-key Kiro connections authenticate the quota API the same way the chat
+  // executor does: a bearer token plus a `tokentype: API_KEY` header so
+  // CodeWhisperer treats it as a long-lived API key rather than an OIDC token.
+  // Without this header the GetUsageLimits call is rejected (401/403).
+  const isApiKey = authMethod === "api_key";
+  const isExternalIdp = authMethod === "external_idp";
+  const apiKeyHeaders = isApiKey ? { tokentype: "API_KEY" } : {};
+  const externalIdpHeaders = isExternalIdp ? { TokenType: "EXTERNAL_IDP" } : {};
+
+  // For api-key auth, never inject the shared default placeholder profileArn —
+  // CodeWhisperer 403s a request whose profileArn isn't owned by the key's
+  // account. Only send a profileArn actually resolved for this connection.
+  const profileArn = isApiKey
+    ? (providerSpecificData?.profileArn || "")
+    : (providerSpecificData?.profileArn || resolveDefaultProfileArn(authMethod));
+
+  const getUsageParams = new URLSearchParams({
+    isEmailRequired: "true",
+    origin: "AI_EDITOR",
+    resourceType: "AGENTIC_REQUEST",
+  });
+
+  // For compatibility, try multiple known Kiro usage endpoints
+  const attempts = [
+    {
+      name: "codewhisperer-get",
+      run: async () => proxyAwareFetch(
+        `${U("kiro").cwHost}${U("kiro").limitsPath}?${getUsageParams.toString()}`,
+        {
+          method: "GET",
+          headers: {
+            "Authorization": `Bearer ${accessToken}`,
+            "Accept": "application/json",
+            "x-amz-user-agent": "aws-sdk-js/1.0.0 KiroIDE",
+            "user-agent": "aws-sdk-js/1.0.0 KiroIDE",
+            ...apiKeyHeaders,
+            ...externalIdpHeaders,
+          },
+        },
+        proxyOptions
+      ),
+    },
+    {
+      name: "codewhisperer-post",
+      run: async () => proxyAwareFetch(U("kiro").cwHost, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${accessToken}`,
+          "Content-Type": "application/x-amz-json-1.0",
+          "x-amz-target": "AmazonCodeWhispererService.GetUsageLimits",
+          "Accept": "application/json",
+          ...apiKeyHeaders,
+          ...externalIdpHeaders,
+        },
+        body: JSON.stringify({
+          origin: "AI_EDITOR",
+          ...(profileArn ? { profileArn } : {}),
+          resourceType: "AGENTIC_REQUEST",
+        }),
+      }, proxyOptions),
+    },
+    {
+      name: "q-get",
+      run: async () => {
+        const params = new URLSearchParams({
+          origin: "AI_EDITOR",
+          ...(profileArn ? { profileArn } : {}),
+          resourceType: "AGENTIC_REQUEST",
+        });
+        return proxyAwareFetch(`${U("kiro").qHost}${U("kiro").limitsPath}?${params}`, {
+          method: "GET",
+          headers: {
+            "Authorization": `Bearer ${accessToken}`,
+            "Accept": "application/json",
+            ...apiKeyHeaders,
+            ...externalIdpHeaders,
+          },
+        }, proxyOptions);
+      },
+    },
+  ];
+
+  let sawAuthError = false;
+  const errors = [];
+
+  for (const attempt of attempts) {
+    try {
+      const response = await attempt.run();
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        if (response.status === 401 || response.status === 403) {
+          sawAuthError = true;
+        }
+        errors.push(`${attempt.name}:${response.status}${errorText ? `:${errorText}` : ""}`);
+        continue;
+      }
+
+      const data = await response.json();
+      return parseKiroQuotaData(data);
+    } catch (error) {
+      errors.push(`${attempt.name}:${error.message}`);
+    }
+  }
+
+  if (sawAuthError && authMethod === "idc") {
+    return {
+      message: "Kiro quota API is unavailable for the current AWS IAM Identity Center session. Chat may still work. If this persists after renewing your session, reconnect Kiro.",
+      quotas: {},
+    };
+  }
+
+  // Social auth (Google/GitHub) - these use a different token format that may not work with AWS CodeWhisperer quota APIs
+  if (sawAuthError && (authMethod === "google" || authMethod === "github")) {
+    return {
+      message: "Kiro quota API authentication expired. Chat may still work.",
+      quotas: {},
+    };
+  }
+
+  if (sawAuthError) {
+    return {
+      message: "Kiro quota API rejected the current token. Chat may still work.",
+      quotas: {},
+    };
+  }
+
+  const fallbackMessage =
+    errors.length > 0
+      ? `Unable to fetch Kiro usage right now. (${errors[errors.length - 1]})`
+      : "Unable to fetch Kiro usage right now.";
+
+  return {
+    message: fallbackMessage,
+    quotas: {},
+  };
+}
diff --git a/open-sse/services/usage/minimax.js b/open-sse/services/usage/minimax.js
new file mode 100644
index 0000000..81a6087
--- /dev/null
+++ b/open-sse/services/usage/minimax.js
@@ -0,0 +1,234 @@
+/**
+ * MiniMax usage handler
+ */
+
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { U, parseResetTime } from "./shared.js";
+
+// MiniMax usage endpoints (try in order, fallback on transient errors)
+const MINIMAX_USAGE_URLS = {
+  minimax: U("minimax").urls,
+  "minimax-cn": U("minimax-cn").urls,
+};
+
+// ── MiniMax helpers ──────────────────────────────────────────────────────
+function getMiniMaxField(model, snakeKey, camelKey) {
+  if (!model || typeof model !== "object") return null;
+  return model[snakeKey] ?? model[camelKey] ?? null;
+}
+
+function getMiniMaxModelName(model) {
+  return String(getMiniMaxField(model, "model_name", "modelName") || "").trim();
+}
+
+function formatMiniMaxQuotaName(model) {
+  const rawName = getMiniMaxModelName(model);
+  if (!rawName) return "MiniMax";
+
+  // M3+ shared quota pool: MiniMax reports M-series as a single wildcard
+  // bucket ("MiniMax-M*"). Newer responses rename it to plain "general".
+  // Render both as a friendly series label rather than leaking the
+  // asterisk or the vague "general" word to the UI.
+  if (rawName === "MiniMax-M*" || rawName === "general") return "M-series";
+
+  return rawName
+    .replace(/[_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/\b\w/g, (ch) => ch.toUpperCase())
+    .replace(/\bTo\b/g, "to")
+    .replace(/\bTts\b/g, "TTS")
+    .replace(/\bHd\b/g, "HD");
+}
+
+function getMiniMaxProvidedPercent(model, snakeKey, camelKey) {
+  if (!model || typeof model !== "object") return null;
+  const raw = model[snakeKey] ?? model[camelKey];
+  if (raw === null || raw === undefined) return null;
+  const num = Number(raw);
+  if (!Number.isFinite(num)) return null;
+  return Math.max(0, Math.min(100, num));
+}
+
+function getMiniMaxSessionTotal(model) {
+  return Math.max(0, Number(getMiniMaxField(model, "current_interval_total_count", "currentIntervalTotalCount")) || 0);
+}
+
+function getMiniMaxWeeklyTotal(model) {
+  return Math.max(0, Number(getMiniMaxField(model, "current_weekly_total_count", "currentWeeklyTotalCount")) || 0);
+}
+
+function hasMiniMaxQuota(model) {
+  // Old format has real count totals; M3-era M-series buckets ship percent-only
+  // (count fields are 0) so accept those too.
+  if (getMiniMaxSessionTotal(model) > 0 || getMiniMaxWeeklyTotal(model) > 0) return true;
+  if (getMiniMaxProvidedPercent(model, "current_interval_remaining_percent", "currentIntervalRemainingPercent") !== null) return true;
+  if (getMiniMaxProvidedPercent(model, "current_weekly_remaining_percent", "currentWeeklyRemainingPercent") !== null) return true;
+  return false;
+}
+
+function getMiniMaxResetAt(model, capturedAtMs, remainsSnake, remainsCamel, endSnake, endCamel) {
+  const remainsMs = Number(getMiniMaxField(model, remainsSnake, remainsCamel)) || 0;
+  if (remainsMs > 0) return new Date(capturedAtMs + remainsMs).toISOString();
+  return parseResetTime(getMiniMaxField(model, endSnake, endCamel));
+}
+
+function buildMiniMaxQuota(total, count, resetAt, countMeansRemaining, providedPercent = null) {
+  const safeTotal = Math.max(0, total);
+  const used = countMeansRemaining ? Math.max(safeTotal - count, 0) : Math.min(Math.max(0, count), safeTotal);
+  const remaining = Math.max(safeTotal - used, 0);
+  // M-series buckets ship percent-only (count = 0). Prefer the upstream value
+  // when present, otherwise fall back to the computed percentage. When the
+  // quota is unbounded (no count) and no upstream percent is available, surface
+  // the percent anyway as long as it is defined.
+  const remainingPercentage = providedPercentage(providedPercent, remaining, safeTotal);
+  return {
+    used,
+    total: safeTotal,
+    remaining,
+    remainingPercentage,
+    resetAt,
+    unlimited: false,
+  };
+}
+
+function providedPercentage(provided, remaining, total) {
+  if (provided !== null && provided !== undefined && Number.isFinite(provided)) {
+    return Math.max(0, Math.min(100, provided));
+  }
+  return total > 0 ? Math.max(0, Math.min(100, (remaining / total) * 100)) : 0;
+}
+
+function addMiniMaxQuota(quotas, key, model, getTotal, countSnake, countCamel, percentSnake, percentCamel, resetArgs, countMeansRemaining) {
+  const total = getTotal(model);
+  const providedPercent = getMiniMaxProvidedPercent(model, percentSnake, percentCamel);
+  if (total <= 0 && providedPercent === null) return;
+
+  const count = Math.max(0, Number(getMiniMaxField(model, countSnake, countCamel)) || 0);
+  let effectiveTotal = total;
+  let effectiveCount = count;
+  if (total <= 0) {
+    // M-series bucket: API only ships *_remaining_percent (count = 0). Normalize
+    // to total=100. The downstream buildMiniMaxQuota treats the count as
+    // "used" or "remaining" depending on countMeansRemaining, so the synthetic
+    // count has to match that semantic — otherwise the UI flips the percentage.
+    effectiveTotal = 100;
+    const pct = providedPercent;
+    effectiveCount = countMeansRemaining
+      ? Math.round(effectiveTotal * (pct / 100))
+      : Math.round(effectiveTotal * (1 - pct / 100));
+  }
+  quotas[key] = buildMiniMaxQuota(
+    effectiveTotal,
+    effectiveCount,
+    getMiniMaxResetAt(model, ...resetArgs),
+    countMeansRemaining,
+    providedPercent
+  );
+}
+
+/**
+ * MiniMax Token Plan / Coding Plan usage
+ */
+export async function getMiniMaxUsage(apiKey, provider, proxyOptions = null) {
+  if (!apiKey) {
+    return { message: "MiniMax API key not available." };
+  }
+
+  const usageUrls = MINIMAX_USAGE_URLS[provider] || [];
+  let lastErrorMessage = "";
+
+  for (let index = 0; index < usageUrls.length; index += 1) {
+    const usageUrl = usageUrls[index];
+    const canFallback = index < usageUrls.length - 1;
+
+    try {
+      const response = await proxyAwareFetch(usageUrl, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          Accept: "application/json",
+          "Content-Type": "application/json",
+        },
+      }, proxyOptions);
+
+      const rawText = await response.text();
+      let payload = {};
+      if (rawText) {
+        try { payload = JSON.parse(rawText); } catch { payload = {}; }
+      }
+
+      const baseResp = (payload?.base_resp ?? payload?.baseResp) || {};
+      const apiStatusCode = Number(baseResp.status_code ?? baseResp.statusCode) || 0;
+      const apiStatusMessage = String(baseResp.status_msg ?? baseResp.statusMsg ?? "").trim();
+      const combined = `${apiStatusMessage} ${rawText}`.trim();
+      const authLike = /token plan|coding plan|invalid api key|invalid key|unauthorized|inactive/i;
+
+      if (response.status === 401 || response.status === 403 || apiStatusCode === 1004 || authLike.test(combined)) {
+        return { message: "MiniMax API key invalid or inactive. Use an active Token/Coding Plan key." };
+      }
+
+      if (!response.ok) {
+        lastErrorMessage = `MiniMax usage endpoint error (${response.status})`;
+        if ((response.status === 404 || response.status === 405 || response.status >= 500) && canFallback) continue;
+        return { message: `MiniMax connected. ${lastErrorMessage}` };
+      }
+
+      if (apiStatusCode !== 0) {
+        return { message: `MiniMax connected. ${apiStatusMessage || "Upstream quota API error"}` };
+      }
+
+      const modelRemains = payload?.model_remains ?? payload?.modelRemains;
+      const allModels = Array.isArray(modelRemains) ? modelRemains : [];
+      const quotaModels = allModels.filter(hasMiniMaxQuota);
+
+      if (quotaModels.length === 0) {
+        return { message: "MiniMax connected. No quota data was returned." };
+      }
+
+      const capturedAtMs = Date.now();
+      const countMeansRemaining = usageUrl.includes("/coding_plan/remains");
+      const quotas = {};
+
+      for (const model of quotaModels) {
+        const displayName = formatMiniMaxQuotaName(model);
+        addMiniMaxQuota(
+          quotas,
+          `${displayName} (5h)`,
+          model,
+          getMiniMaxSessionTotal,
+          "current_interval_usage_count",
+          "currentIntervalUsageCount",
+          "current_interval_remaining_percent",
+          "currentIntervalRemainingPercent",
+          [capturedAtMs, "remains_time", "remainsTime", "end_time", "endTime"],
+          countMeansRemaining
+        );
+
+        addMiniMaxQuota(
+          quotas,
+          `${displayName} (7d)`,
+          model,
+          getMiniMaxWeeklyTotal,
+          "current_weekly_usage_count",
+          "currentWeeklyUsageCount",
+          "current_weekly_remaining_percent",
+          "currentWeeklyRemainingPercent",
+          [capturedAtMs, "weekly_remains_time", "weeklyRemainsTime", "weekly_end_time", "weeklyEndTime"],
+          countMeansRemaining
+        );
+      }
+
+      if (Object.keys(quotas).length === 0) {
+        return { message: "MiniMax connected. Unable to extract quota usage." };
+      }
+
+      return { quotas };
+    } catch (error) {
+      lastErrorMessage = error.message;
+      if (!canFallback) break;
+    }
+  }
+
+  return { message: lastErrorMessage ? `MiniMax connected. Unable to fetch usage: ${lastErrorMessage}` : "MiniMax connected. Unable to fetch usage." };
+}
diff --git a/open-sse/services/usage/misc.js b/open-sse/services/usage/misc.js
new file mode 100644
index 0000000..6ce012f
--- /dev/null
+++ b/open-sse/services/usage/misc.js
@@ -0,0 +1,269 @@
+/**
+ * Misc usage handlers (Qwen, iFlow, Ollama, GLM, Vercel AI Gateway, Qoder)
+ */
+
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { U } from "./shared.js";
+
+// GLM quota endpoints (region-aware) — url from registry transport.usage
+const GLM_QUOTA_URLS = {
+  international: U("glm").url,
+  china: U("glm-cn").url,
+};
+
+// Vercel AI Gateway credits endpoint
+// Returns { balance: "95.50", total_used: "4.50" } (USD as decimal strings).
+const VERCEL_AI_GATEWAY_CREDITS_URL = U("vercel-ai-gateway").url;
+
+/**
+ * Qwen Usage
+ */
+export async function getQwenUsage(accessToken, providerSpecificData) {
+  try {
+    const resourceUrl = providerSpecificData?.resourceUrl;
+    if (!resourceUrl) {
+      return { message: "Qwen connected. No resource URL available." };
+    }
+
+    // Qwen may have usage endpoint at resource URL
+    return { message: "Qwen connected. Usage tracked per request." };
+  } catch (error) {
+    return { message: "Unable to fetch Qwen usage." };
+  }
+}
+
+/**
+ * iFlow Usage
+ */
+export async function getIflowUsage(accessToken) {
+  try {
+    // iFlow may have usage endpoint
+    return { message: "iFlow connected. Usage tracked per request." };
+  } catch (error) {
+    return { message: "Unable to fetch iFlow usage." };
+  }
+}
+
+/**
+ * Ollama Cloud Usage
+ * Ollama Cloud uses an API key from ollama.com/settings/keys
+ * and has no public usage API — free tier has light usage limits (resets every 5h & 7d).
+ * This returns an informational message with the plan details.
+ */
+export async function getOllamaUsage(accessToken, providerSpecificData) {
+  try {
+    // Ollama Cloud does not expose a public quota/usage API.
+    // The provider is configured as noAuth with a notice explaining limits.
+    // We return a graceful message so the UI shows a friendly state instead of an error.
+    const plan = providerSpecificData?.plan || "Free";
+    return {
+      plan,
+      message: "Ollama Cloud uses a free tier with light usage limits (resets every 5h & 7d). For detailed usage tracking, visit ollama.com/settings/keys.",
+      quotas: [],
+    };
+  } catch (error) {
+    return { message: "Unable to fetch Ollama Cloud usage." };
+  }
+}
+
+/**
+ * GLM Coding Plan usage (international + China regions)
+ */
+export async function getGlmUsage(apiKey, provider, proxyOptions = null) {
+  if (!apiKey) {
+    return { message: "GLM API key not available." };
+  }
+
+  const region = provider === "glm-cn" ? "china" : "international";
+  const quotaUrl = GLM_QUOTA_URLS[region];
+
+  try {
+    const response = await proxyAwareFetch(quotaUrl, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json",
+      },
+    }, proxyOptions);
+
+    if (!response.ok) {
+      if (response.status === 401) {
+        return { message: "GLM API key invalid or expired." };
+      }
+      return { message: `GLM quota API error (${response.status}).` };
+    }
+
+    const json = await response.json();
+    const data = json?.data && typeof json.data === "object" ? json.data : {};
+    const limits = Array.isArray(data.limits) ? data.limits : [];
+    const quotas = {};
+
+    for (const limit of limits) {
+      if (!limit || limit.type !== "TOKENS_LIMIT") continue;
+      const usedPercent = Number(limit.percentage) || 0;
+      const resetMs = Number(limit.nextResetTime) || 0;
+      const remaining = Math.max(0, 100 - usedPercent);
+
+      quotas["session"] = {
+        used: usedPercent,
+        total: 100,
+        remaining,
+        remainingPercentage: remaining,
+        resetAt: resetMs > 0 ? new Date(resetMs).toISOString() : null,
+        unlimited: false,
+      };
+    }
+
+    const levelRaw = typeof data.level === "string" ? data.level : "";
+    const plan = levelRaw
+      ? levelRaw.charAt(0).toUpperCase() + levelRaw.slice(1).toLowerCase()
+      : "Unknown";
+
+    return { plan, quotas };
+  } catch (error) {
+    return { message: `GLM error: ${error.message}` };
+  }
+}
+
+/**
+ * Vercel AI Gateway usage — credit balance for the API key
+ *
+ * Calls GET /v1/credits which returns:
+ *   { "balance": "95.50", "total_used": "4.50" }   (USD as decimal strings)
+ *
+ * We surface this as a single "Balance ($)" quota row so the existing
+ * QuotaTable / progress-bar UI can render it. used = total_used,
+ * total = balance + total_used (the original credit allotment), so the
+ * remaining percentage equals balance / total.
+ *
+ * Docs: https://vercel.com/docs/ai-gateway/usage
+ */
+export async function getVercelAiGatewayUsage(apiKey, proxyOptions = null) {
+  if (!apiKey) {
+    return { message: "Vercel AI Gateway API key not available." };
+  }
+
+  try {
+    const response = await proxyAwareFetch(VERCEL_AI_GATEWAY_CREDITS_URL, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json",
+      },
+    }, proxyOptions);
+
+    if (response.status === 401 || response.status === 403) {
+      return { message: "Vercel AI Gateway API key invalid or expired." };
+    }
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      const trimmed = errorText ? `: ${errorText.slice(0, 200)}` : "";
+      return { message: `Vercel AI Gateway credits API error (${response.status})${trimmed}` };
+    }
+
+    const data = await response.json();
+
+    // Vercel returns numeric strings; coerce safely.
+    const balance = Number(data?.balance) || 0;
+    const totalUsed = Number(data?.total_used) || 0;
+
+    // Vercel gives $5/month free credit. The API doesn't return the
+    // monthly allocation so we use the known constant as the denominator.
+    const MONTHLY_CREDIT = 5;
+    const remainingPercentage = (balance / MONTHLY_CREDIT) * 100;
+
+    if (balance <= 0 && totalUsed <= 0) {
+      return {
+        plan: "Pay-as-you-go",
+        message: "Vercel AI Gateway connected. No credit allocation found (BYOK or unfunded account).",
+        quotas: {},
+      };
+    }
+
+    // "Used (USD)": how much has been spent this month (no fixed cap → unlimited).
+    // "Remaining (USD)": balance remaining out of the $5 monthly allocation.
+    return {
+      plan: "Pay-as-you-go",
+      quotas: {
+        "Used (USD)": {
+          used: totalUsed,
+          total: 0,
+          remaining: 0,
+          remainingPercentage: 100,
+          unlimited: true,
+        },
+        "Remaining (USD)": {
+          used: balance,
+          total: MONTHLY_CREDIT,
+          remaining: balance,
+          remainingPercentage,
+          unlimited: false,
+        },
+      },
+    };
+  } catch (error) {
+    return { message: `Vercel AI Gateway error: ${error.message}` };
+  }
+}
+
+export async function getQoderUsage(accessToken, proxyOptions = null) {
+  if (!accessToken) {
+    return { message: "Qoder usage unavailable: no access token" };
+  }
+  try {
+    const response = await proxyAwareFetch(
+      U("qoder").url,
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          Accept: "application/json",
+        },
+      },
+      proxyOptions,
+    );
+    if (!response.ok) {
+      return { message: `Qoder connected. Usage fetch returned ${response.status}.` };
+    }
+    const body = await response.json().catch(() => null);
+    if (!body) {
+      return { message: "Qoder connected. Usage response was not JSON." };
+    }
+    // Quota records live under `quotas`; scalar metadata
+    // (totalUsagePercentage, isQuotaExceeded, expiresAt) are surfaced as
+    // siblings so the dashboard parser doesn't try to render them as rows.
+    const userQuota = body.userQuota || {};
+    const orgQuota = body.orgResourcePackage || {};
+    // Qoder publishes a single absolute reset timestamp (`expiresAt` in ms);
+    // surface it on every quota record as ISO so the table can render
+    // "resets at" alongside used/total.
+    const expiresAtMs = Number.isFinite(Number(body.expiresAt)) && Number(body.expiresAt) > 0
+      ? Number(body.expiresAt)
+      : null;
+    const resetAt = expiresAtMs ? new Date(expiresAtMs).toISOString() : null;
+    const quotas = {
+      user: {
+        total: Number(userQuota.total) || 0,
+        used: Number(userQuota.used) || 0,
+        remaining: Number(userQuota.remaining) || 0,
+        unit: userQuota.unit || "credits",
+        resetAt,
+      },
+      organization: {
+        total: Number(orgQuota.total) || 0,
+        used: Number(orgQuota.used) || 0,
+        remaining: Number(orgQuota.remaining) || 0,
+        unit: orgQuota.unit || "credits",
+        resetAt,
+      },
+    };
+    return {
+      quotas,
+      totalUsagePercentage: Number(body.totalUsagePercentage) || 0,
+      isQuotaExceeded: !!body.isQuotaExceeded,
+      expiresAt: expiresAtMs,
+    };
+  } catch (error) {
+    return { message: `Qoder connected. Unable to fetch usage: ${error.message}` };
+  }
+}
diff --git a/open-sse/services/usage/shared.js b/open-sse/services/usage/shared.js
new file mode 100644
index 0000000..7ca59f7
--- /dev/null
+++ b/open-sse/services/usage/shared.js
@@ -0,0 +1,70 @@
+/**
+ * Shared usage helpers (cross-provider)
+ */
+
+import { PROVIDERS } from "../../providers/index.js";
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+
+// usage endpoints: single source from registry transport.usage
+export const U = (id) => PROVIDERS[id]?.usage || {};
+
+/**
+ * Parse reset date/time to ISO string
+ * Handles multiple formats: Unix timestamp (ms), ISO date string, etc.
+ */
+export function parseResetTime(resetValue) {
+  if (!resetValue) return null;
+
+  try {
+    // If it's already a Date object
+    if (resetValue instanceof Date) {
+      return resetValue.toISOString();
+    }
+
+    // Unix timestamps from provider APIs may be seconds or milliseconds.
+    if (typeof resetValue === 'number') {
+      return new Date(resetValue < 1e12 ? resetValue * 1000 : resetValue).toISOString();
+    }
+
+    // If it's a numeric string, treat it like a Unix timestamp too.
+    if (typeof resetValue === 'string') {
+      if (/^\d+$/.test(resetValue)) {
+        const timestamp = Number(resetValue);
+        return new Date(timestamp < 1e12 ? timestamp * 1000 : timestamp).toISOString();
+      }
+      return new Date(resetValue).toISOString();
+    }
+
+    return null;
+  } catch (error) {
+    console.warn(`Failed to parse reset time: ${resetValue}`, error);
+    return null;
+  }
+}
+
+export function toFiniteNumber(value, fallback = 0) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return fallback;
+}
+
+export function normalizeCloudCodeProjectId(project) {
+  if (typeof project === "string") return project.trim() || null;
+  if (project && typeof project === "object" && typeof project.id === "string") {
+    return project.id.trim() || null;
+  }
+  return null;
+}
+
+export async function fetchWithTimeout(url, opts, ms = 10000, proxyOptions = null) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), ms);
+  try {
+    return await proxyAwareFetch(url, { ...opts, signal: controller.signal }, proxyOptions);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
diff --git a/open-sse/shared/clineAuth.js b/open-sse/shared/clineAuth.js
new file mode 100644
index 0000000..1b2b7df
--- /dev/null
+++ b/open-sse/shared/clineAuth.js
@@ -0,0 +1,37 @@
+import pkg from "../../package.json" with { type: "json" };
+
+const APP_VERSION = pkg.version || "0.0.0";
+
+export function getClineAccessToken(token) {
+  if (typeof token !== "string") return "";
+  const trimmed = token.trim();
+  if (!trimmed) return "";
+  return trimmed.startsWith("workos:") ? trimmed : `workos:${trimmed}`;
+}
+
+export function getClineAuthorizationHeader(token) {
+  const accessToken = getClineAccessToken(token);
+  return accessToken ? `Bearer ${accessToken}` : "";
+}
+
+export function buildClineHeaders(token, extraHeaders = {}) {
+  const authorization = getClineAuthorizationHeader(token);
+  const headers = {
+    "HTTP-Referer": "https://cline.bot",
+    "X-Title": "Cline",
+    "User-Agent": `9Router/${APP_VERSION}`,
+    "X-PLATFORM": process.platform || "unknown",
+    "X-PLATFORM-VERSION": process.version || "unknown",
+    "X-CLIENT-TYPE": "9router",
+    "X-CLIENT-VERSION": APP_VERSION,
+    "X-CORE-VERSION": APP_VERSION,
+    "X-IS-MULTIROOT": "false",
+    ...extraHeaders,
+  };
+
+  if (authorization) {
+    headers.Authorization = authorization;
+  }
+
+  return headers;
+}
diff --git a/open-sse/shared/machineId.js b/open-sse/shared/machineId.js
new file mode 100644
index 0000000..76c2a8d
--- /dev/null
+++ b/open-sse/shared/machineId.js
@@ -0,0 +1,19 @@
+import { machineIdSync } from "node-machine-id";
+import crypto from "node:crypto";
+
+let cachedRawId = null;
+
+function loadRawMachineId() {
+  if (cachedRawId) return cachedRawId;
+  try {
+    cachedRawId = machineIdSync();
+  } catch {
+    cachedRawId = crypto.randomUUID();
+  }
+  return cachedRawId;
+}
+
+export async function getConsistentMachineId(salt = "endpoint-proxy-salt") {
+  const rawId = loadRawMachineId();
+  return crypto.createHash("sha256").update(rawId + salt).digest("hex").substring(0, 16);
+}
diff --git a/open-sse/shared/qoder/constants.js b/open-sse/shared/qoder/constants.js
new file mode 100644
index 0000000..1d9ce30
--- /dev/null
+++ b/open-sse/shared/qoder/constants.js
@@ -0,0 +1,64 @@
+/**
+ * Qoder API constants ported from CLIProxyAPIPlus qoder-provider branch.
+ *
+ * Endpoint set:
+ *   openapi.qoder.sh   - device flow + userinfo + quota usage
+ *   center.qoder.sh    - token refresh (best-effort, currently 403 for device tokens)
+ *   api3.qoder.sh      - inference (chat) + model list, requires COSY signing
+ *   qoder.com/device   - browser landing page for device authorization
+ */
+
+export const QODER_OPENAPI_BASE = "https://openapi.qoder.sh";
+export const QODER_CENTER_BASE = "https://center.qoder.sh";
+export const QODER_CHAT_BASE = "https://api3.qoder.sh";
+
+export const QODER_LOGIN_URL = "https://qoder.com/device/selectAccounts";
+
+// Device flow endpoints
+export const QODER_DEVICE_TOKEN_URL = `${QODER_OPENAPI_BASE}/api/v1/deviceToken/poll`;
+export const QODER_USERINFO_URL = `${QODER_OPENAPI_BASE}/api/v1/userinfo`;
+export const QODER_QUOTA_USAGE_URL = `${QODER_OPENAPI_BASE}/api/v2/quota/usage`;
+export const QODER_REFRESH_TOKEN_URL = `${QODER_CENTER_BASE}/algo/api/v3/user/refresh_token`;
+
+// Inference endpoints (under /algo on api3.qoder.sh, all COSY-signed)
+export const QODER_CHAT_SIG_PATH = "/api/v2/service/pro/sse/agent_chat_generation";
+export const QODER_CHAT_URL = `${QODER_CHAT_BASE}/algo${QODER_CHAT_SIG_PATH}?FetchKeys=llm_model_result&AgentId=agent_common`;
+export const QODER_CHAT_URL_ENCODED = `${QODER_CHAT_URL}&Encode=1`;
+export const QODER_MODEL_LIST_URL = `${QODER_CHAT_BASE}/algo/api/v2/model/list`;
+
+// COSY header constants. These are not arbitrary — the upstream signature
+// validation matches them against the values used at signing time.
+export const QODER_IDE_VERSION = "1.0.0";
+export const QODER_CLIENT_TYPE = "5";
+export const QODER_DATA_POLICY = "disagree";
+export const QODER_LOGIN_VERSION = "v2";
+export const QODER_MACHINE_OS = "x86_64_windows";
+export const QODER_MACHINE_TYPE = "5";
+
+// Canonical model identifiers. Identity map — keep as a map so callers can
+// cheaply test "is this a known qoder model?" before sending the request.
+export const QODER_MODEL_MAP = {
+  // Tier models
+  auto: "auto",
+  ultimate: "ultimate",
+  performance: "performance",
+  efficient: "efficient",
+  lite: "lite",
+  // Frontier models
+  qmodel: "qmodel",
+  qmodel_latest: "qmodel_latest",
+  dmodel: "dmodel",
+  dfmodel: "dfmodel",
+  gm51model: "gm51model",
+  kmodel: "kmodel",
+  mmodel: "mmodel",
+};
+
+// RSA public key for COSY encryption (extracted from Qoder IDE v0.9).
+// Matches the CLIProxyAPIPlus branch and live qodercli traffic.
+export const QODER_RSA_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDA8iMH5c02LilrsERw9t6Pv5Nc
+4k6Pz1EaDicBMpdpxKduSZu5OANqUq8er4GM95omAGIOPOh+Nx0spthYA2BqGz+l
+6HRkPJ7S236FZz73In/KVuLnwI8JJ2CbuJap8kvheCCZpmAWpb/cPx/3Vr/J6I17
+XcW+ML9FoCI6AOvOzwIDAQAB
+-----END PUBLIC KEY-----`;
diff --git a/open-sse/shared/qoder/cosy.js b/open-sse/shared/qoder/cosy.js
new file mode 100644
index 0000000..d5d59af
--- /dev/null
+++ b/open-sse/shared/qoder/cosy.js
@@ -0,0 +1,175 @@
+/**
+ * Qoder COSY (hybrid RSA+AES+MD5) signing, ported from CLIProxyAPIPlus
+ * qoder-provider branch (internal/auth/qoder/cosy.go).
+ *
+ * Every signed request carries:
+ *   - an AES-128-CBC payload of the user info, the AES key wrapped in RSA
+ *   - an MD5 signature over `payload || cosyKey || timestamp || body || sigPath`
+ *   - the body's MD5 hash + length so the server can validate integrity
+ *   - 17 Cosy-* / X-* headers fingerprinting the client (machine id, IDE
+ *     version, organization id, etc.)
+ *
+ * The on-the-wire header keys use the same casing as qodercli:
+ *   Cosy-Machineid, not Cosy-MachineID.
+ */
+
+import crypto from "crypto";
+import { v4 as uuidv4 } from "uuid";
+
+import {
+  QODER_CLIENT_TYPE,
+  QODER_DATA_POLICY,
+  QODER_IDE_VERSION,
+  QODER_LOGIN_VERSION,
+  QODER_MACHINE_OS,
+  QODER_MACHINE_TYPE,
+  QODER_RSA_PUBLIC_KEY,
+} from "./constants.js";
+
+// AES-128 wants a 16-byte key. Match qodercli/Veria: take the first 16 chars
+// of a fresh UUID's canonical string (hyphens included). The key is fresh
+// per request so even though the IV reuses the key bytes, each request still
+// has a unique IV.
+function generateAesKey() {
+  return uuidv4().slice(0, 16);
+}
+
+function pkcs7Pad(data, blockSize) {
+  const padding = blockSize - (data.length % blockSize);
+  const padded = Buffer.alloc(data.length + padding, padding);
+  data.copy(padded, 0);
+  return padded;
+}
+
+function aesEncryptCbcBase64(plaintext, keyStr) {
+  const keyBytes = Buffer.from(keyStr, "utf8");
+  if (keyBytes.length !== 16) {
+    throw new Error(`aes key must be 16 bytes, got ${keyBytes.length}`);
+  }
+  const iv = keyBytes.subarray(0, 16);
+  const cipher = crypto.createCipheriv("aes-128-cbc", keyBytes, iv);
+  cipher.setAutoPadding(false);
+  const padded = pkcs7Pad(Buffer.from(plaintext, "utf8"), 16);
+  const encrypted = Buffer.concat([cipher.update(padded), cipher.final()]);
+  return encrypted.toString("base64");
+}
+
+function rsaEncryptBase64(data) {
+  const encrypted = crypto.publicEncrypt(
+    { key: QODER_RSA_PUBLIC_KEY, padding: crypto.constants.RSA_PKCS1_PADDING },
+    Buffer.from(data, "utf8"),
+  );
+  return encrypted.toString("base64");
+}
+
+function encryptUserInfo(userInfo) {
+  const aesKey = generateAesKey();
+  const plaintext = JSON.stringify(userInfo);
+  const infoB64 = aesEncryptCbcBase64(plaintext, aesKey);
+  const cosyKeyB64 = rsaEncryptBase64(aesKey);
+  return { cosyKey: cosyKeyB64, info: infoB64 };
+}
+
+function md5Hex(input) {
+  return crypto.createHash("md5").update(input).digest("hex");
+}
+
+/**
+ * Strip the leading "/algo" prefix from the request path. Matches qodercli
+ * convention. Empty input returns "".
+ */
+function computeSigPath(requestUrl) {
+  let pathname;
+  try {
+    pathname = new URL(requestUrl).pathname || "";
+  } catch {
+    return "";
+  }
+  if (pathname.startsWith("/algo")) {
+    return pathname.slice("/algo".length);
+  }
+  return pathname;
+}
+
+/**
+ * Generate a fresh machine UUID. Persisted on the connection record so
+ * every request from the same auth carries the same machineId.
+ */
+export function generateMachineId() {
+  return uuidv4();
+}
+
+/**
+ * Build the full Cosy-* header set for a single Qoder request.
+ *
+ * @param {Buffer|Uint8Array|string} body  The exact bytes that will be sent.
+ *   For GET requests pass an empty Buffer / "".
+ * @param {string} requestUrl              Full request URL (used for sigPath).
+ * @param {object} creds
+ * @param {string} creds.userId            Stable Qoder user id.
+ * @param {string} creds.authToken         Device access token (`dt-...`).
+ * @param {string} [creds.name]            Display name (optional).
+ * @param {string} [creds.email]           Email (optional, can be empty).
+ * @param {string} [creds.machineId]       Persisted machine UUID.
+ * @returns {Record<string, string>} Header map ready to merge onto fetch().
+ */
+export function buildCosyHeaders(body, requestUrl, creds) {
+  if (!creds?.userId) throw new Error("cosy: user id is empty");
+  if (!creds?.authToken) throw new Error("cosy: auth token is empty");
+
+  const bodyBuf = Buffer.isBuffer(body)
+    ? body
+    : typeof body === "string"
+      ? Buffer.from(body, "latin1")
+      : Buffer.from(body || []);
+
+  const { cosyKey, info } = encryptUserInfo({
+    uid: creds.userId,
+    security_oauth_token: creds.authToken,
+    name: creds.name || "",
+    aid: "",
+    email: creds.email || "",
+  });
+
+  const timestamp = String(Math.floor(Date.now() / 1000));
+  const requestId = uuidv4();
+
+  const payloadJson = JSON.stringify({
+    version: "v1",
+    requestId,
+    info,
+    cosyVersion: QODER_IDE_VERSION,
+    ideVersion: "",
+  });
+  const payloadB64 = Buffer.from(payloadJson, "utf8").toString("base64");
+
+  const sigPath = computeSigPath(requestUrl);
+  const sigInput = `${payloadB64}\n${cosyKey}\n${timestamp}\n${bodyBuf.toString("latin1")}\n${sigPath}`;
+  const sig = md5Hex(Buffer.from(sigInput, "latin1"));
+
+  const machineId = creds.machineId || generateMachineId();
+  const bodyHash = md5Hex(bodyBuf);
+  const bodyLength = String(bodyBuf.length);
+
+  return {
+    Authorization: `Bearer COSY.${payloadB64}.${sig}`,
+    "Cosy-Key": cosyKey,
+    "Cosy-User": creds.userId,
+    "Cosy-Date": timestamp,
+    "Cosy-Version": QODER_IDE_VERSION,
+    "Cosy-Machineid": machineId,
+    "Cosy-Machinetoken": machineId,
+    "Cosy-Machinetype": QODER_MACHINE_TYPE,
+    "Cosy-Machineos": QODER_MACHINE_OS,
+    "Cosy-Clienttype": QODER_CLIENT_TYPE,
+    "Cosy-Clientip": "127.0.0.1",
+    "Cosy-Bodyhash": bodyHash,
+    "Cosy-Bodylength": bodyLength,
+    "Cosy-Sigpath": sigPath,
+    "Cosy-Data-Policy": QODER_DATA_POLICY,
+    "Cosy-Organization-Id": "",
+    "Cosy-Organization-Tags": "",
+    "Login-Version": QODER_LOGIN_VERSION,
+    "X-Request-Id": uuidv4(),
+  };
+}
diff --git a/open-sse/shared/qoder/encoding.js b/open-sse/shared/qoder/encoding.js
new file mode 100644
index 0000000..31449e8
--- /dev/null
+++ b/open-sse/shared/qoder/encoding.js
@@ -0,0 +1,55 @@
+/**
+ * Qoder body encoding ported from qoder2api's QoderEncoding.java (via the
+ * CLIProxyAPIPlus qoder-provider branch).
+ *
+ * Algorithm:
+ *   1. base64-encode the plaintext bytes (standard alphabet).
+ *   2. Rearrange: split into thirds, reorder as [tail][mid][head].
+ *   3. Substitute each character via a custom alphabet mapping.
+ *
+ * The encoded body must be sent with `&Encode=1` appended to the URL so the
+ * server decodes in reverse. The obfuscation prevents Alibaba Cloud WAF from
+ * pattern-matching the plaintext request body.
+ */
+
+const QODER_STD_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const QODER_CUSTOM_ALPHABET = "_doRTgHZBKcGVjlvpC,@aFSx#DPuNJme&i*MzLOEn)sUrthbf%Y^w.(kIQyXqWA!";
+
+const QODER_S2C = (() => {
+  const table = new Int16Array(128).fill(-1);
+  for (let i = 0; i < 64; i++) {
+    table[QODER_STD_ALPHABET.charCodeAt(i)] = QODER_CUSTOM_ALPHABET.charCodeAt(i);
+  }
+  table["=".charCodeAt(0)] = "$".charCodeAt(0);
+  return table;
+})();
+
+/**
+ * Encode plaintext bytes/string using Qoder's WAF-bypass scheme.
+ * @param {Buffer|Uint8Array|string} plaintext
+ * @returns {string} encoded string
+ */
+export function qoderEncodeBody(plaintext) {
+  const buf = Buffer.isBuffer(plaintext)
+    ? plaintext
+    : typeof plaintext === "string"
+      ? Buffer.from(plaintext, "utf8")
+      : Buffer.from(plaintext);
+
+  const std = buf.toString("base64");
+  const n = std.length;
+  const a = Math.floor(n / 3);
+  // [tail][mid][head]
+  const rearranged = std.slice(n - a) + std.slice(a, n - a) + std.slice(0, a);
+
+  const out = Buffer.alloc(n);
+  for (let i = 0; i < n; i++) {
+    const c = rearranged.charCodeAt(i);
+    if (c < 128 && QODER_S2C[c] >= 0) {
+      out[i] = QODER_S2C[c];
+    } else {
+      out[i] = c;
+    }
+  }
+  return out.toString("latin1");
+}
diff --git a/open-sse/transformer/responsesTransformer.js b/open-sse/transformer/responsesTransformer.js
new file mode 100644
index 0000000..ac84db2
--- /dev/null
+++ b/open-sse/transformer/responsesTransformer.js
@@ -0,0 +1,439 @@
+/**
+ * Responses API Transformer
+ * Converts OpenAI Chat Completions SSE to Codex Responses API SSE format
+ * Can be used in both Next.js and Cloudflare Workers
+ */
+
+import fs from "fs";
+import path from "path";
+
+// Create log directory for responses (Node.js only)
+export function createResponsesLogger(model, logsDir = null) {
+  // Skip logging in worker environment (no fs)
+  if (typeof fs.mkdirSync !== "function") {
+    return null;
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "").slice(0, 15);
+  const uniqueId = Math.random().toString(36).slice(2, 8);
+  const baseDir = logsDir || (typeof process !== "undefined" ? process.cwd() : ".");
+  const logDir = path.join(baseDir, "logs", `responses_${model}_${timestamp}_${uniqueId}`);
+  
+  try {
+    fs.mkdirSync(logDir, { recursive: true });
+  } catch {
+    return null;
+  }
+
+  let inputEvents = [];
+  let outputEvents = [];
+
+  return {
+    logInput: (event) => {
+      inputEvents.push(event);
+    },
+    logOutput: (event) => {
+      outputEvents.push(event);
+    },
+    flush: () => {
+      try {
+        fs.writeFileSync(path.join(logDir, "1_input_stream.txt"), inputEvents.join("\n"));
+        fs.writeFileSync(path.join(logDir, "2_output_stream.txt"), outputEvents.join("\n"));
+      } catch (e) {
+        console.log("[RESPONSES] Failed to write logs:", e.message);
+      }
+    }
+  };
+}
+
+/**
+ * Create TransformStream that converts Chat Completions SSE to Responses API SSE
+ * @param {Object} logger - Optional logger instance
+ * @returns {TransformStream}
+ */
+export function createResponsesApiTransformStream(logger = null) {
+  const state = {
+    seq: 0,
+    responseId: `resp_${Date.now()}`,
+    created: Math.floor(Date.now() / 1000),
+    started: false,
+    msgTextBuf: {},
+    msgItemAdded: {},
+    msgContentAdded: {},
+    msgItemDone: {},
+    reasoningId: "",
+    reasoningIndex: -1,
+    reasoningBuf: "",
+    reasoningPartAdded: false,
+    reasoningDone: false,
+    inThinking: false,
+    funcArgsBuf: {},
+    funcNames: {},
+    funcCallIds: {},
+    funcArgsDone: {},
+    funcItemDone: {},
+    buffer: "",
+    completedSent: false
+  };
+
+  const encoder = new TextEncoder();
+  const nextSeq = () => ++state.seq;
+  
+  const emit = (controller, eventType, data) => {
+    data.sequence_number = nextSeq();
+    const output = `event: ${eventType}\ndata: ${JSON.stringify(data)}\n\n`;
+    logger?.logOutput(output.trim());
+    controller.enqueue(encoder.encode(output));
+  };
+
+  // Helper to start reasoning
+  const startReasoning = (controller, idx) => {
+    if (!state.reasoningId) {
+      state.reasoningId = `rs_${state.responseId}_${idx}`;
+      state.reasoningIndex = idx;
+      
+      emit(controller, "response.output_item.added", {
+        type: "response.output_item.added",
+        output_index: idx,
+        item: {
+          id: state.reasoningId,
+          type: "reasoning",
+          summary: []
+        }
+      });
+
+      emit(controller, "response.reasoning_summary_part.added", {
+        type: "response.reasoning_summary_part.added",
+        item_id: state.reasoningId,
+        output_index: idx,
+        summary_index: 0,
+        part: { type: "summary_text", text: "" }
+      });
+      state.reasoningPartAdded = true;
+    }
+  };
+
+  const emitReasoningDelta = (controller, text) => {
+    if (!text) return;
+    state.reasoningBuf += text;
+    emit(controller, "response.reasoning_summary_text.delta", {
+      type: "response.reasoning_summary_text.delta",
+      item_id: state.reasoningId,
+      output_index: state.reasoningIndex,
+      summary_index: 0,
+      delta: text
+    });
+  };
+
+  const closeReasoning = (controller) => {
+    if (state.reasoningId && !state.reasoningDone) {
+      state.reasoningDone = true;
+      
+      emit(controller, "response.reasoning_summary_text.done", {
+        type: "response.reasoning_summary_text.done",
+        item_id: state.reasoningId,
+        output_index: state.reasoningIndex,
+        summary_index: 0,
+        text: state.reasoningBuf
+      });
+
+      emit(controller, "response.reasoning_summary_part.done", {
+        type: "response.reasoning_summary_part.done",
+        item_id: state.reasoningId,
+        output_index: state.reasoningIndex,
+        summary_index: 0,
+        part: { type: "summary_text", text: state.reasoningBuf }
+      });
+
+      emit(controller, "response.output_item.done", {
+        type: "response.output_item.done",
+        output_index: state.reasoningIndex,
+        item: {
+          id: state.reasoningId,
+          type: "reasoning",
+          summary: [{ type: "summary_text", text: state.reasoningBuf }]
+        }
+      });
+    }
+  };
+
+  const closeMessage = (controller, idx) => {
+    if (state.msgItemAdded[idx] && !state.msgItemDone[idx]) {
+      state.msgItemDone[idx] = true;
+      const fullText = state.msgTextBuf[idx] || "";
+      const msgId = `msg_${state.responseId}_${idx}`;
+
+      emit(controller, "response.output_text.done", {
+        type: "response.output_text.done",
+        item_id: msgId,
+        output_index: parseInt(idx),
+        content_index: 0,
+        text: fullText,
+        logprobs: []
+      });
+
+      emit(controller, "response.content_part.done", {
+        type: "response.content_part.done",
+        item_id: msgId,
+        output_index: parseInt(idx),
+        content_index: 0,
+        part: { type: "output_text", annotations: [], logprobs: [], text: fullText }
+      });
+
+      emit(controller, "response.output_item.done", {
+        type: "response.output_item.done",
+        output_index: parseInt(idx),
+        item: {
+          id: msgId,
+          type: "message",
+          content: [{ type: "output_text", annotations: [], logprobs: [], text: fullText }],
+          role: "assistant"
+        }
+      });
+    }
+  };
+
+  const closeToolCall = (controller, idx) => {
+    const callId = state.funcCallIds[idx];
+    if (callId && !state.funcItemDone[idx]) {
+      const args = state.funcArgsBuf[idx] || "{}";
+      
+      emit(controller, "response.function_call_arguments.done", {
+        type: "response.function_call_arguments.done",
+        item_id: `fc_${callId}`,
+        output_index: parseInt(idx),
+        arguments: args
+      });
+
+      emit(controller, "response.output_item.done", {
+        type: "response.output_item.done",
+        output_index: parseInt(idx),
+        item: {
+          id: `fc_${callId}`,
+          type: "function_call",
+          arguments: args,
+          call_id: callId,
+          name: state.funcNames[idx] || ""
+        }
+      });
+
+      state.funcItemDone[idx] = true;
+      state.funcArgsDone[idx] = true;
+    }
+  };
+
+  const sendCompleted = (controller) => {
+    if (!state.completedSent) {
+      state.completedSent = true;
+      emit(controller, "response.completed", {
+        type: "response.completed",
+        response: {
+          id: state.responseId,
+          object: "response",
+          created_at: state.created,
+          status: "completed",
+          background: false,
+          error: null
+        }
+      });
+    }
+  };
+
+  return new TransformStream({
+    transform(chunk, controller) {
+      const text = new TextDecoder().decode(chunk);
+      logger?.logInput(text.trim());
+      state.buffer += text;
+
+      const messages = state.buffer.split("\n\n");
+      state.buffer = messages.pop() || "";
+
+      for (const msg of messages) {
+        if (!msg.trim()) continue;
+
+        const dataMatch = msg.match(/^data:\s*(.+)$/m);
+        if (!dataMatch) continue;
+
+        const dataStr = dataMatch[1].trim();
+        if (dataStr === "[DONE]") continue;
+
+        let parsed;
+        try {
+          parsed = JSON.parse(dataStr);
+        } catch {
+          continue;
+        }
+
+        if (!parsed.choices?.length) continue;
+        
+        const choice = parsed.choices[0];
+        const idx = choice.index || 0;
+        const delta = choice.delta || {};
+
+        // Emit initial events
+        if (!state.started) {
+          state.started = true;
+          state.responseId = parsed.id ? `resp_${parsed.id}` : state.responseId;
+          
+          emit(controller, "response.created", {
+            type: "response.created",
+            response: {
+              id: state.responseId,
+              object: "response",
+              created_at: state.created,
+              status: "in_progress",
+              background: false,
+              error: null,
+              output: []
+            }
+          });
+
+          emit(controller, "response.in_progress", {
+            type: "response.in_progress",
+            response: {
+              id: state.responseId,
+              object: "response",
+              created_at: state.created,
+              status: "in_progress"
+            }
+          });
+        }
+
+        // Handle reasoning_content (OpenAI native format)
+        if (delta.reasoning_content) {
+          startReasoning(controller, idx);
+          emitReasoningDelta(controller, delta.reasoning_content);
+        }
+
+        // Handle text content (may contain <think> tags)
+        if (delta.content) {
+          let content = delta.content;
+
+          if (content.includes("<think>")) {
+            state.inThinking = true;
+            content = content.replace("<think>", "");
+            startReasoning(controller, idx);
+          }
+
+          if (content.includes("</think>")) {
+            const parts = content.split("</think>");
+            const thinkPart = parts[0];
+            const textPart = parts.slice(1).join("</think>");
+            
+            if (thinkPart) emitReasoningDelta(controller, thinkPart);
+            closeReasoning(controller);
+            state.inThinking = false;
+            content = textPart;
+          }
+
+          if (state.inThinking && content) {
+            emitReasoningDelta(controller, content);
+            continue;
+          }
+
+          // Regular text content
+          if (content) {
+            if (!state.msgItemAdded[idx]) {
+              state.msgItemAdded[idx] = true;
+              const msgId = `msg_${state.responseId}_${idx}`;
+              
+              emit(controller, "response.output_item.added", {
+                type: "response.output_item.added",
+                output_index: idx,
+                item: { id: msgId, type: "message", content: [], role: "assistant" }
+              });
+            }
+
+            if (!state.msgContentAdded[idx]) {
+              state.msgContentAdded[idx] = true;
+              
+              emit(controller, "response.content_part.added", {
+                type: "response.content_part.added",
+                item_id: `msg_${state.responseId}_${idx}`,
+                output_index: idx,
+                content_index: 0,
+                part: { type: "output_text", annotations: [], logprobs: [], text: "" }
+              });
+            }
+
+            emit(controller, "response.output_text.delta", {
+              type: "response.output_text.delta",
+              item_id: `msg_${state.responseId}_${idx}`,
+              output_index: idx,
+              content_index: 0,
+              delta: content,
+              logprobs: []
+            });
+
+            if (!state.msgTextBuf[idx]) state.msgTextBuf[idx] = "";
+            state.msgTextBuf[idx] += content;
+          }
+        }
+
+        // Handle tool_calls
+        if (delta.tool_calls) {
+          closeMessage(controller, idx);
+
+          for (const tc of delta.tool_calls) {
+            const tcIdx = tc.index ?? 0;
+            const newCallId = tc.id;
+            const funcName = tc.function?.name;
+
+            if (funcName) state.funcNames[tcIdx] = funcName;
+
+            if (!state.funcCallIds[tcIdx] && newCallId) {
+              state.funcCallIds[tcIdx] = newCallId;
+              
+              emit(controller, "response.output_item.added", {
+                type: "response.output_item.added",
+                output_index: tcIdx,
+                item: {
+                  id: `fc_${newCallId}`,
+                  type: "function_call",
+                  arguments: "",
+                  call_id: newCallId,
+                  name: state.funcNames[tcIdx] || ""
+                }
+              });
+            }
+
+            if (!state.funcArgsBuf[tcIdx]) state.funcArgsBuf[tcIdx] = "";
+
+            if (tc.function?.arguments) {
+              const refCallId = state.funcCallIds[tcIdx] || newCallId;
+              if (refCallId) {
+                emit(controller, "response.function_call_arguments.delta", {
+                  type: "response.function_call_arguments.delta",
+                  item_id: `fc_${refCallId}`,
+                  output_index: tcIdx,
+                  delta: tc.function.arguments
+                });
+              }
+              state.funcArgsBuf[tcIdx] += tc.function.arguments;
+            }
+          }
+        }
+
+        // Handle finish_reason
+        if (choice.finish_reason) {
+          for (const i in state.msgItemAdded) closeMessage(controller, i);
+          closeReasoning(controller);
+          for (const i in state.funcCallIds) closeToolCall(controller, i);
+          sendCompleted(controller);
+        }
+      }
+    },
+
+    flush(controller) {
+      for (const i in state.msgItemAdded) closeMessage(controller, i);
+      closeReasoning(controller);
+      for (const i in state.funcCallIds) closeToolCall(controller, i);
+      sendCompleted(controller);
+
+      logger?.logOutput("data: [DONE]");
+      controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+      logger?.flush();
+    }
+  });
+}
+
diff --git a/open-sse/transformer/streamToJsonConverter.js b/open-sse/transformer/streamToJsonConverter.js
new file mode 100644
index 0000000..c08acb2
--- /dev/null
+++ b/open-sse/transformer/streamToJsonConverter.js
@@ -0,0 +1,103 @@
+/**
+ * Stream-to-JSON Converter
+ * Converts Responses API SSE stream to single JSON response
+ * Used when client requests non-streaming but provider forces streaming (e.g., Codex)
+ */
+
+/**
+ * Process a single SSE message and update state accordingly.
+ */
+function processSSEMessage(msg, state) {
+  if (!msg.trim()) return;
+
+  const eventMatch = msg.match(/^event:\s*(.+)$/m);
+  const dataMatch = msg.match(/^data:\s*(.+)$/m);
+  if (!eventMatch || !dataMatch) return;
+
+  const eventType = eventMatch[1].trim();
+  const dataStr = dataMatch[1].trim();
+  if (dataStr === "[DONE]") return;
+
+  let parsed;
+  try { parsed = JSON.parse(dataStr); }
+  catch { return; }
+
+  if (eventType === "response.created") {
+    state.responseId = parsed.response?.id || state.responseId;
+    state.created = parsed.response?.created_at || state.created;
+  } else if (eventType === "response.output_item.done") {
+    state.items.set(parsed.output_index ?? 0, parsed.item);
+  } else if (eventType === "response.completed" || eventType === "response.done") {
+    state.status = "completed";
+    if (parsed.response?.usage) {
+      state.usage.input_tokens = parsed.response.usage.input_tokens || 0;
+      state.usage.output_tokens = parsed.response.usage.output_tokens || 0;
+      state.usage.total_tokens = parsed.response.usage.total_tokens || 0;
+    }
+  } else if (eventType === "response.failed") {
+    state.status = "failed";
+  }
+}
+
+const EMPTY_RESPONSE = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
+
+/**
+ * Convert Responses API SSE stream to single JSON response
+ * @param {ReadableStream} stream - SSE stream from provider
+ * @returns {Promise<Object>} Final JSON response in Responses API format
+ */
+export async function convertResponsesStreamToJson(stream) {
+  if (!stream || typeof stream.getReader !== "function") {
+    return { id: `resp_${Date.now()}`, object: "response", created_at: Math.floor(Date.now() / 1000), status: "failed", output: [], usage: { ...EMPTY_RESPONSE } };
+  }
+
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  const state = {
+    responseId: "",
+    created: Math.floor(Date.now() / 1000),
+    status: "in_progress",
+    usage: { ...EMPTY_RESPONSE },
+    items: new Map()
+  };
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const messages = buffer.split("\n\n");
+      buffer = messages.pop() || "";
+
+      for (const msg of messages) {
+        processSSEMessage(msg, state);
+      }
+    }
+
+    // Flush remaining buffer (last event may not end with \n\n)
+    if (buffer.trim()) {
+      processSSEMessage(buffer, state);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  // Build output array from accumulated items (ordered by index)
+  const output = [];
+  const maxIndex = state.items.size > 0 ? Math.max(...state.items.keys()) : -1;
+  for (let i = 0; i <= maxIndex; i++) {
+    output.push(state.items.get(i) || { type: "message", content: [], role: "assistant" });
+  }
+
+  return {
+    id: state.responseId || `resp_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    object: "response",
+    created_at: state.created,
+    status: state.status || "completed",
+    output,
+    usage: state.usage
+  };
+}
diff --git a/open-sse/translator/concerns/chunk.js b/open-sse/translator/concerns/chunk.js
new file mode 100644
index 0000000..35d9753
--- /dev/null
+++ b/open-sse/translator/concerns/chunk.js
@@ -0,0 +1,11 @@
+// Build OpenAI chat.completion.chunk. Caller supplies id/created/model so each
+// translator keeps its exact id-generation + created semantics (no Date.now here).
+export function buildChunk({ id, created, model }, delta, finishReason = null) {
+  return {
+    id,
+    object: "chat.completion.chunk",
+    created,
+    model,
+    choices: [{ index: 0, delta, finish_reason: finishReason }],
+  };
+}
diff --git a/open-sse/translator/concerns/finishReason.js b/open-sse/translator/concerns/finishReason.js
new file mode 100644
index 0000000..684a700
--- /dev/null
+++ b/open-sse/translator/concerns/finishReason.js
@@ -0,0 +1,63 @@
+// Concern #6: finish_reason / stop_reason mapping.
+// One entry per direction; switch by special format, default handles common providers.
+import { OPENAI_FINISH, CLAUDE_STOP, GEMINI_FINISH } from "../schema/finishReasons.js";
+
+// upstream finish/stop reason → OpenAI finish_reason
+export function toOpenAIFinish(reason, format) {
+  switch (format) {
+    case "claude":
+      switch (reason) {
+        case CLAUDE_STOP.END_TURN: return OPENAI_FINISH.STOP;
+        case CLAUDE_STOP.MAX_TOKENS: return OPENAI_FINISH.LENGTH;
+        case CLAUDE_STOP.TOOL_USE: return OPENAI_FINISH.TOOL_CALLS;
+        case CLAUDE_STOP.STOP_SEQUENCE: return OPENAI_FINISH.STOP;
+        default: return OPENAI_FINISH.STOP;
+      }
+    case "commandcode":
+      switch (reason) {
+        case "stop": return OPENAI_FINISH.STOP;
+        case "length": return OPENAI_FINISH.LENGTH;
+        case "tool-calls":
+        case "tool_use": return OPENAI_FINISH.TOOL_CALLS;
+        case "content-filter": return OPENAI_FINISH.CONTENT_FILTER;
+        case "error": return OPENAI_FINISH.STOP;
+        default: return reason || OPENAI_FINISH.STOP;
+      }
+    case "gemini":
+      switch (String(reason).toUpperCase()) {
+        case GEMINI_FINISH.STOP: return OPENAI_FINISH.STOP;
+        case GEMINI_FINISH.MAX_TOKENS: return OPENAI_FINISH.LENGTH;
+        case GEMINI_FINISH.SAFETY:
+        case GEMINI_FINISH.RECITATION:
+        case GEMINI_FINISH.BLOCKLIST:
+        case GEMINI_FINISH.PROHIBITED_CONTENT: return OPENAI_FINISH.CONTENT_FILTER;
+        default: return OPENAI_FINISH.STOP;
+      }
+    case "kiro":
+    case "ollama":
+      switch (reason) {
+        case "tool_calls":
+        case "tool_use": return OPENAI_FINISH.TOOL_CALLS;
+        case "length":
+        case "max_tokens": return OPENAI_FINISH.LENGTH;
+        default: return OPENAI_FINISH.STOP;
+      }
+    default:
+      return reason || OPENAI_FINISH.STOP;
+  }
+}
+
+// OpenAI finish_reason → upstream stop reason
+export function fromOpenAIFinish(reason, format) {
+  switch (format) {
+    case "claude":
+      switch (reason) {
+        case OPENAI_FINISH.STOP: return CLAUDE_STOP.END_TURN;
+        case OPENAI_FINISH.LENGTH: return CLAUDE_STOP.MAX_TOKENS;
+        case OPENAI_FINISH.TOOL_CALLS: return CLAUDE_STOP.TOOL_USE;
+        default: return CLAUDE_STOP.END_TURN;
+      }
+    default:
+      return reason;
+  }
+}
diff --git a/open-sse/translator/concerns/image.js b/open-sse/translator/concerns/image.js
new file mode 100644
index 0000000..73864b5
--- /dev/null
+++ b/open-sse/translator/concerns/image.js
@@ -0,0 +1,124 @@
+// Build a base64 data URI from mime + base64 payload
+export function encodeDataUri(mimeType, base64) {
+  return `data:${mimeType};base64,${base64}`;
+}
+
+// Parse a base64 data URI → { mimeType, base64 }, or null if not a data URI.
+// [\s\S] tolerates newlines inside the base64 payload.
+const DATA_URI_RE = /^data:([^;]+);base64,([\s\S]+)$/;
+export function parseDataUri(url) {
+  if (typeof url !== "string") return null;
+  const m = url.match(DATA_URI_RE);
+  return m ? { mimeType: m[1], base64: m[2] } : null;
+}
+
+import { lookup } from "node:dns/promises";
+import { Agent } from "undici";
+import { MAX_IMAGE_BYTES, FETCH_TIMEOUT_MS, IMAGE_SIGNATURES, BLOCKED_HOSTS } from "../../config/mediaConfig.js";
+
+// True if an IPv4/IPv6 address is private/reserved (SSRF target).
+function isPrivateIp(ip) {
+  if (!ip) return true;
+  // IPv6 loopback / unique-local / link-local
+  if (ip === "::1" || ip.startsWith("fc") || ip.startsWith("fd") || ip.startsWith("fe80")) return true;
+  // IPv4-mapped IPv6 (::ffff:a.b.c.d) -> extract tail
+  const v4 = ip.includes(".") ? ip.split(":").pop() : ip;
+  const parts = v4.split(".").map((n) => Number.parseInt(n, 10));
+  if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return ip.includes(":") ? false : true;
+  const [a, b] = parts;
+  if (a === 10 || a === 127 || a === 0) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 169 && b === 254) return true; // link-local + cloud metadata
+  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT
+  return false;
+}
+
+// Resolve host once and return only public IPs (SSRF guard).
+// Rejects if any resolved record is private/reserved (defeats multi-A tricks).
+async function resolvePinnedIps(hostname) {
+  if (!hostname || BLOCKED_HOSTS.has(hostname.toLowerCase())) return null;
+  try {
+    const records = await lookup(hostname, { all: true });
+    if (!records.length || records.some((r) => isPrivateIp(r.address))) return null;
+    return records;
+  } catch {
+    return null;
+  }
+}
+
+// Verify buffer magic bytes match a known image signature; return its mime or null.
+function detectImageMime(buf) {
+  for (const { sig, offset, mime, verifyWebp } of IMAGE_SIGNATURES) {
+    if (buf.length < offset + sig.length) continue;
+    let match = true;
+    for (let i = 0; i < sig.length; i++) {
+      if (buf[offset + i] !== sig[i]) { match = false; break; }
+    }
+    if (!match) continue;
+    // WEBP: RIFF....WEBP — bytes 8..11 must be "WEBP".
+    if (verifyWebp && !(buf.length >= 12 && buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50)) continue;
+    return mime;
+  }
+  return null;
+}
+
+/**
+ * Fetch a remote image URL and return it as a base64 data URI.
+ * Hardened against SSRF (private/metadata IPs), memory DoS (size cap),
+ * and disguised non-image payloads (magic-byte verification).
+ * Returns null on any failure or rejection.
+ *
+ * @param {string} imageUrl - HTTP(S) URL of the image
+ * @param {object} options - { signal, timeoutMs, maxBytes }
+ * @returns {Promise<{url: string, mimeType: string}|null>}
+ */
+export async function fetchImageAsBase64(imageUrl, options = {}) {
+  const { signal, timeoutMs = FETCH_TIMEOUT_MS, maxBytes = MAX_IMAGE_BYTES } = options;
+  if (!imageUrl || (!imageUrl.startsWith("http://") && !imageUrl.startsWith("https://"))) {
+    return null;
+  }
+
+  let url;
+  try { url = new URL(imageUrl); } catch { return null; }
+  const pinnedIps = await resolvePinnedIps(url.hostname);
+  if (!pinnedIps) return null;
+
+  const controller = new AbortController();
+  const timeout = signal ? null : setTimeout(() => controller.abort(), timeoutMs);
+  const fetchSignal = signal || controller.signal;
+
+  // Pin connect to the validated IP so no second DNS resolution can rebind (TOCTOU fix).
+  const dispatcher = new Agent({
+    connect: { lookup: (_h, _o, cb) => cb(null, [{ address: pinnedIps[0].address, family: pinnedIps[0].family }]) },
+  });
+
+  try {
+    // redirect:"manual" prevents a public URL redirecting to a private one (SSRF bypass).
+    const response = await fetch(imageUrl, { signal: fetchSignal, redirect: "manual", dispatcher });
+    if (!response.ok || !response.body) return null;
+
+    // Stream-read with a hard byte cap to avoid loading huge payloads into memory.
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.length;
+      if (total > maxBytes) { try { await reader.cancel(); } catch { /* ignore */ } return null; }
+      chunks.push(value);
+    }
+
+    const buf = Buffer.concat(chunks.map((c) => Buffer.from(c)));
+    const mimeType = detectImageMime(buf);
+    if (!mimeType) return null; // not a recognized image — reject disguised payloads
+
+    return { url: `data:${mimeType};base64,${buf.toString("base64")}`, mimeType };
+  } catch {
+    return null;
+  } finally {
+    if (timeout) clearTimeout(timeout);
+    dispatcher.close().catch(() => {});
+  }
+}
diff --git a/open-sse/translator/concerns/json.js b/open-sse/translator/concerns/json.js
new file mode 100644
index 0000000..36c1b71
--- /dev/null
+++ b/open-sse/translator/concerns/json.js
@@ -0,0 +1,5 @@
+// Safe JSON.parse: non-string passthrough; on parse error return caller-chosen `fallback`.
+export function safeParseJSON(str, fallback) {
+  if (typeof str !== "string") return str;
+  try { return JSON.parse(str); } catch { return fallback; }
+}
diff --git a/open-sse/translator/concerns/message.js b/open-sse/translator/concerns/message.js
new file mode 100644
index 0000000..169aeaf
--- /dev/null
+++ b/open-sse/translator/concerns/message.js
@@ -0,0 +1,7 @@
+import { OPENAI_BLOCK } from "../schema/index.js";
+
+// Collapse an OpenAI content-part array: a lone text part becomes a plain string,
+// otherwise the array is returned as-is. Matches existing translator behavior.
+export function collapseTextParts(parts) {
+  return parts.length === 1 && parts[0].type === OPENAI_BLOCK.TEXT ? parts[0].text : parts;
+}
diff --git a/open-sse/translator/concerns/modality.js b/open-sse/translator/concerns/modality.js
new file mode 100644
index 0000000..b3bba2d
--- /dev/null
+++ b/open-sse/translator/concerns/modality.js
@@ -0,0 +1,155 @@
+// Strip multimodal content blocks a model cannot read, BEFORE translation.
+// Driven by getCapabilitiesForModel: vision/audioInput/pdf. Replaces removed
+// media with a short text placeholder so messages never become empty.
+import { FORMATS } from "../formats.js";
+
+// Placeholder text inserted where a media block was removed.
+// Current turn: explain the active model can't read what the user just sent.
+const PLACEHOLDER_CURRENT = {
+  vision: "[image omitted: model has no vision support]",
+  audioInput: "[audio omitted: model has no audio support]",
+  pdf: "[file omitted: model has no document support]",
+};
+// Earlier turns: neutral (a combo may route to a different model each turn).
+const PLACEHOLDER_PREV = {
+  vision: "[Previous image omitted from context.]",
+  audioInput: "[Previous audio omitted from context.]",
+  pdf: "[Previous file omitted from context.]",
+};
+const ph = (cap, isLast) => (isLast ? PLACEHOLDER_CURRENT : PLACEHOLDER_PREV)[cap];
+
+// Map gemini inlineData/fileData mime prefix -> capability it requires.
+function capForMime(mime) {
+  if (typeof mime !== "string") return null;
+  if (mime.startsWith("image/")) return "vision";
+  if (mime.startsWith("audio/")) return "audioInput";
+  if (mime === "application/pdf") return "pdf";
+  return null;
+}
+
+// OpenAI chat content block -> required capability (null = plain text/other, keep).
+function capForOpenAIBlock(block) {
+  const t = block?.type;
+  if (t === "image_url" || t === "image") return "vision";
+  if (t === "input_audio" || t === "audio_url") return "audioInput";
+  if (t === "file") return "pdf";
+  return null;
+}
+
+// Claude content block -> required capability.
+function capForClaudeBlock(block) {
+  const t = block?.type;
+  if (t === "image") return "vision";
+  if (t === "document") return "pdf";
+  return null;
+}
+
+// Filter an array of content blocks; drop unsupported, inject one placeholder per kind.
+// isLast = block belongs to the current user turn (picks the explanatory placeholder).
+function filterBlocks(blocks, capOf, caps, removed, isLast) {
+  const out = [];
+  for (const block of blocks) {
+    const cap = capOf(block);
+    if (cap && caps[cap] === false) { removed.add(cap); continue; }
+    out.push(block);
+  }
+  for (const cap of removed) out.push({ type: "text", text: ph(cap, isLast) });
+  return out;
+}
+
+// OpenAI / OpenAI-compatible chat messages[].content[].
+function stripOpenAI(body, caps) {
+  if (!Array.isArray(body.messages)) return;
+  const last = body.messages.length - 1;
+  body.messages.forEach((msg, i) => {
+    if (!Array.isArray(msg.content)) return;
+    const removed = new Set();
+    msg.content = filterBlocks(msg.content, capForOpenAIBlock, caps, removed, i === last);
+  });
+}
+
+// Claude messages[].content[].
+function stripClaude(body, caps) {
+  if (!Array.isArray(body.messages)) return;
+  const last = body.messages.length - 1;
+  body.messages.forEach((msg, i) => {
+    if (!Array.isArray(msg.content)) return;
+    const removed = new Set();
+    msg.content = filterBlocks(msg.content, capForClaudeBlock, caps, removed, i === last);
+  });
+}
+
+// OpenAI Responses input[].content[] (input_image / input_file).
+function stripResponses(body, caps) {
+  if (!Array.isArray(body.input)) return;
+  const last = body.input.length - 1;
+  body.input.forEach((item, i) => {
+    if (!Array.isArray(item.content)) return;
+    const removed = new Set();
+    item.content = item.content.filter((b) => {
+      const cap = b?.type === "input_image" ? "vision" : b?.type === "input_file" ? "pdf" : null;
+      if (cap && caps[cap] === false) { removed.add(cap); return false; }
+      return true;
+    });
+    for (const cap of removed) item.content.push({ type: "input_text", text: ph(cap, i === last) });
+  });
+}
+
+// Gemini / gemini-cli contents[].parts[] (inlineData / fileData by mime).
+function stripGeminiParts(contents, caps) {
+  if (!Array.isArray(contents)) return;
+  const last = contents.length - 1;
+  contents.forEach((c, i) => {
+    if (!Array.isArray(c.parts)) return;
+    const removed = new Set();
+    c.parts = c.parts.filter((p) => {
+      const mime = p?.inlineData?.mimeType || p?.fileData?.mimeType;
+      const cap = capForMime(mime);
+      if (cap && caps[cap] === false) { removed.add(cap); return false; }
+      return true;
+    });
+    for (const cap of removed) c.parts.push({ text: ph(cap, i === last) });
+  });
+}
+
+/**
+ * Remove media blocks the model can't read, in-place on the source-format body.
+ * @param {object} body - request body (source format)
+ * @param {string} sourceFormat - one of FORMATS
+ * @param {object} caps - capabilities from getCapabilitiesForModel
+ * @returns {boolean} true if anything was stripped-eligible (cap false for some modality)
+ */
+export function stripUnsupportedModalities(body, sourceFormat, caps) {
+  if (!body || !caps) return false;
+  // Fast exit: model supports everything we'd strip.
+  if (caps.vision !== false && caps.audioInput !== false && caps.pdf !== false) return false;
+
+  switch (sourceFormat) {
+    case FORMATS.OPENAI:
+    case FORMATS.OLLAMA:
+    case FORMATS.KIRO:
+    case FORMATS.CURSOR:
+    case FORMATS.COMMANDCODE:
+      stripOpenAI(body, caps);
+      break;
+    case FORMATS.CLAUDE:
+      stripClaude(body, caps);
+      break;
+    case FORMATS.OPENAI_RESPONSES:
+    case FORMATS.OPENAI_RESPONSE:
+    case FORMATS.CODEX:
+      stripResponses(body, caps);
+      break;
+    case FORMATS.GEMINI:
+    case FORMATS.GEMINI_CLI:
+    case FORMATS.VERTEX:
+      stripGeminiParts(body.contents, caps);
+      break;
+    case FORMATS.ANTIGRAVITY:
+      stripGeminiParts(body?.request?.contents, caps);
+      break;
+    default:
+      stripOpenAI(body, caps);
+  }
+  return true;
+}
diff --git a/open-sse/translator/concerns/paramSupport.js b/open-sse/translator/concerns/paramSupport.js
new file mode 100644
index 0000000..7f7283b
--- /dev/null
+++ b/open-sse/translator/concerns/paramSupport.js
@@ -0,0 +1,75 @@
+import { getCapabilitiesForModel } from "../../providers/capabilities.js";
+
+// Strip request params a given provider/model rejects upstream (e.g. HTTP 400).
+// Config-driven: add a rule instead of scattering `delete body.x` across executors.
+
+// Each rule: optional provider, regex match on model, list of params to drop.
+// A param is removed only when it is present (!== undefined).
+const STRIP_RULES = [
+  // claude-opus-4 series: temperature is deprecated (Anthropic 400). #1748
+  { match: /claude-opus-4/i, drop: ["temperature"] },
+  // GitHub Copilot gpt-5.4: temperature unsupported.
+  { provider: "github", match: /gpt-5\.4/i, drop: ["temperature"] },
+  // GitHub Copilot Claude (except opus/sonnet 4.6): thinking + reasoning_effort rejected. #713
+  { provider: "github", match: (m) => /claude/i.test(m) && !/claude.*(opus|sonnet).*4\.6/i.test(m), drop: ["thinking", "reasoning_effort"] },
+  // Cloudflare Workers AI: content must be plain string, rejects OpenAI content-part array (#1926)
+  { provider: "cloudflare-ai", flattenContent: true },
+  { provider: "volcengine-ark", match: /glm-5/i, clampToModelMaxOutput: true },
+  // VolcEngine Ark caps the Kimi family at max_tokens <= 32768, but the model's
+  // advertised ceiling is far higher (Kimi-K2.7-Code resolves to maxOutput 262144),
+  // so clampToModelMaxOutput alone leaves it uncapped and the request 400s with
+  // "integer above maximum value, expected <= 32768". Pin an explicit endpoint cap;
+  // min() with the model ceiling still applies if a variant's own limit is lower.
+  { provider: "volcengine-ark", match: /kimi/i, maxOutputCap: 32768, clampToModelMaxOutput: true },
+];
+
+// Test a rule's match (regex or predicate) against the model id.
+function matches(rule, model) {
+  if (!rule.match) return true;
+  return typeof rule.match === "function" ? rule.match(model) : rule.match.test(model);
+}
+
+function clampNumber(body, key, ceiling) {
+  if (typeof body[key] === "number" && Number.isFinite(body[key]) && body[key] > ceiling) {
+    body[key] = ceiling;
+  }
+}
+
+// Remove unsupported params from body in place; returns body.
+export function stripUnsupportedParams(provider, model, body) {
+  if (!model || !body || typeof body !== "object") return body;
+  for (const rule of STRIP_RULES) {
+    if (rule.provider && rule.provider !== provider) continue;
+    if (!matches(rule, model)) continue;
+    for (const key of rule.drop || []) {
+      if (body[key] !== undefined) delete body[key];
+    }
+    // CF Workers AI oneOf root schema only accepts content as plain string (#1926)
+    if (rule.flattenContent && Array.isArray(body.messages)) {
+      for (const msg of body.messages) {
+        if (msg && Array.isArray(msg.content)) {
+          msg.content = msg.content
+            .map(b => (b?.type === "text" && typeof b.text === "string") ? b.text : "")
+            .join("");
+        }
+      }
+    }
+    if (rule.clampToModelMaxOutput || Number.isFinite(rule.maxOutputCap)) {
+      const modelCeiling = getCapabilitiesForModel(provider, model).maxOutput;
+      const candidates = [];
+      if (rule.clampToModelMaxOutput && Number.isFinite(modelCeiling) && modelCeiling > 0) {
+        candidates.push(modelCeiling);
+      }
+      if (Number.isFinite(rule.maxOutputCap) && rule.maxOutputCap > 0) {
+        candidates.push(rule.maxOutputCap);
+      }
+      if (candidates.length > 0) {
+        const ceiling = Math.min(...candidates);
+        clampNumber(body, "max_tokens", ceiling);
+        clampNumber(body, "max_completion_tokens", ceiling);
+        clampNumber(body, "max_output_tokens", ceiling);
+      }
+    }
+  }
+  return body;
+}
diff --git a/open-sse/translator/concerns/prefetch.js b/open-sse/translator/concerns/prefetch.js
new file mode 100644
index 0000000..5055be3
--- /dev/null
+++ b/open-sse/translator/concerns/prefetch.js
@@ -0,0 +1,96 @@
+// Pre-fetch remote image URLs into base64 BEFORE translation, for target
+// formats whose upstream providers cannot fetch remote URLs themselves
+// (they require inline base64). Runs on the source-format body.
+import { FORMATS } from "../formats.js";
+import { fetchImageAsBase64, parseDataUri } from "./image.js";
+
+// Targets that require inline base64 images (cannot accept remote URLs).
+const TARGETS_NEED_BASE64 = new Set([
+  FORMATS.GEMINI, FORMATS.GEMINI_CLI, FORMATS.VERTEX,
+  FORMATS.ANTIGRAVITY, FORMATS.OLLAMA, FORMATS.KIRO,
+]);
+
+function isRemoteUrl(url) {
+  return typeof url === "string" && (url.startsWith("http://") || url.startsWith("https://"));
+}
+
+// Collect {get,set} accessors for every remote image URL in a source body.
+function collectImageRefs(body, sourceFormat) {
+  const refs = [];
+  const pushOpenAI = (messages) => {
+    for (const msg of messages || []) {
+      if (!Array.isArray(msg.content)) continue;
+      for (const block of msg.content) {
+        if (block?.type === "image_url") {
+          const url = typeof block.image_url === "string" ? block.image_url : block.image_url?.url;
+          if (isRemoteUrl(url)) refs.push({ get: () => url, set: (v) => {
+            if (typeof block.image_url === "string") block.image_url = v; else block.image_url.url = v;
+          } });
+        }
+      }
+    }
+  };
+  const pushGemini = (contents) => {
+    for (const c of contents || []) {
+      for (const p of c.parts || []) {
+        const uri = p?.fileData?.fileUri;
+        if (isRemoteUrl(uri)) refs.push({ get: () => uri, part: p });
+      }
+    }
+  };
+
+  switch (sourceFormat) {
+    case FORMATS.OPENAI:
+    case FORMATS.OLLAMA:
+    case FORMATS.KIRO:
+    case FORMATS.CURSOR:
+    case FORMATS.COMMANDCODE:
+      pushOpenAI(body.messages);
+      break;
+    case FORMATS.CLAUDE:
+      for (const msg of body.messages || []) {
+        if (!Array.isArray(msg.content)) continue;
+        for (const block of msg.content) {
+          if (block?.type === "image" && block.source?.type === "url" && isRemoteUrl(block.source.url)) {
+            refs.push({ get: () => block.source.url, claudeBlock: block });
+          }
+        }
+      }
+      break;
+    case FORMATS.GEMINI:
+    case FORMATS.GEMINI_CLI:
+    case FORMATS.VERTEX:
+      pushGemini(body.contents);
+      break;
+    case FORMATS.ANTIGRAVITY:
+      pushGemini(body?.request?.contents);
+      break;
+    default:
+      pushOpenAI(body.messages);
+  }
+  return refs;
+}
+
+/**
+ * Replace remote image URLs with base64 data when the target needs inline data.
+ * No-op when target accepts remote URLs (e.g. openai, claude) or body has none.
+ * @returns {Promise<number>} count of images converted
+ */
+export async function prefetchRemoteImages(body, sourceFormat, targetFormat, options = {}) {
+  if (!body || !TARGETS_NEED_BASE64.has(targetFormat)) return 0;
+  const refs = collectImageRefs(body, sourceFormat);
+  if (!refs.length) return 0;
+
+  let converted = 0;
+  for (const ref of refs) {
+    const url = ref.get();
+    if (parseDataUri(url)) continue; // already inline
+    const fetched = await fetchImageAsBase64(url, options);
+    if (!fetched) continue;
+    if (ref.set) ref.set(fetched.url);
+    else if (ref.part) { delete ref.part.fileData; ref.part.inlineData = { mimeType: fetched.mimeType, data: fetched.url.split(",")[1] }; }
+    else if (ref.claudeBlock) ref.claudeBlock.source = { type: "base64", media_type: fetched.mimeType, data: fetched.url.split(",")[1] };
+    converted++;
+  }
+  return converted;
+}
diff --git a/open-sse/translator/concerns/reasoning.js b/open-sse/translator/concerns/reasoning.js
new file mode 100644
index 0000000..f4855eb
--- /dev/null
+++ b/open-sse/translator/concerns/reasoning.js
@@ -0,0 +1,24 @@
+import { ROLE } from "../schema/index.js";
+
+// Build OpenAI delta carrying reasoning_content (optional leading assistant role)
+export function reasoningDelta(text, withRole = false) {
+  return withRole
+    ? { role: ROLE.ASSISTANT, reasoning_content: text }
+    : { reasoning_content: text };
+}
+
+// Extract reasoning text from a streamed OpenAI-compatible delta across vendor shapes:
+//   - reasoning_content (GLM, Qwen, DeepSeek, Kimi, Step, Hunyuan)
+//   - reasoning (some compat layers)
+//   - reasoning_details[] (MiniMax reasoning_split=true): [{ text|content }]
+// Returns concatenated reasoning string, or "" when none.
+export function extractReasoningText(delta) {
+  if (!delta || typeof delta !== "object") return "";
+  if (typeof delta.reasoning_content === "string" && delta.reasoning_content) return delta.reasoning_content;
+  if (typeof delta.reasoning === "string" && delta.reasoning) return delta.reasoning;
+  const details = delta.reasoning_details;
+  if (Array.isArray(details)) {
+    return details.map((d) => (typeof d === "string" ? d : d?.text || d?.content || "")).join("");
+  }
+  return "";
+}
diff --git a/open-sse/translator/concerns/thinking.js b/open-sse/translator/concerns/thinking.js
new file mode 100644
index 0000000..3db892c
--- /dev/null
+++ b/open-sse/translator/concerns/thinking.js
@@ -0,0 +1,53 @@
+// Concern: reasoning_effort ↔ provider-native thinking config.
+// Central source of truth for level↔budget maps (web-standard values).
+// Provider-specific application lives in thinkingUnified.js; this file is maps-only.
+
+// Discrete effort levels, ordered low→high.
+export const EFFORT_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"];
+
+// Web-standard level → budget_tokens (Anthropic/Gemini docs).
+export const LEVEL_TO_BUDGET = {
+  none: 0,
+  minimal: 512,
+  low: 1024,
+  medium: 8192,
+  high: 24576,
+  xhigh: 32768,
+  max: 128000,
+};
+
+// Returns budget_tokens for an effort level, or undefined if unknown.
+// 0 means "no thinking"; undefined means "effort not recognized".
+export function effortToBudget(effort) {
+  if (!effort) return undefined;
+  return LEVEL_TO_BUDGET[String(effort).toLowerCase()];
+}
+
+// OpenAI reasoning_effort → Gemini thinkingLevel (gemini-3 enum: minimal|low|medium|high).
+// Gemini 3 cannot fully disable thinking; "none"/"off" map to "minimal".
+export function effortToThinkingLevel(effort) {
+  const e = String(effort).toLowerCase().trim();
+  if (e === "none" || e === "off") return "minimal";
+  if (e === "xhigh" || e === "max") return "high";
+  return e;
+}
+
+// Numeric budget → nearest discrete level (reverse map via thresholds).
+// Returns null when budget <= 0 (no reasoning).
+export function budgetToLevel(budget) {
+  const b = Number(budget);
+  if (!b || b <= 0) return null;
+  if (b <= 768) return "minimal";
+  if (b <= 4096) return "low";
+  if (b <= 16384) return "medium";
+  if (b <= 28672) return "high";
+  return "xhigh";
+}
+
+// Gemini thinkingBudget (numeric) → OpenAI reasoning_effort (antigravity reverse map).
+export function budgetToEffort(budget) {
+  if (!budget || budget <= 0) return null;
+  if (budget <= 2048) return "low";
+  if (budget <= 16384) return "medium";
+  return "high";
+}
diff --git a/open-sse/translator/concerns/thinkingUnified.js b/open-sse/translator/concerns/thinkingUnified.js
new file mode 100644
index 0000000..0c98b07
--- /dev/null
+++ b/open-sse/translator/concerns/thinkingUnified.js
@@ -0,0 +1,329 @@
+// Unified thinking normalization: extract client intent → apply provider-native format.
+// Config-driven: thinking format/limits come from capabilities.js + registry transport,
+// never hardcoded per-model here. See .docs/thinking/plan.md MATRIX VI-A.
+
+import { getCapabilitiesForModel } from "../../providers/capabilities.js";
+import { PROVIDERS } from "../../providers/index.js";
+import { LEVEL_TO_BUDGET, budgetToLevel, effortToBudget, effortToThinkingLevel } from "./thinking.js";
+
+// Map a target wire-format to its native thinking format (when capability has none).
+const FORMAT_TO_NATIVE = {
+  openai: "openai",
+  "openai-responses": "openai",
+  "openai-response": "openai",
+  codex: "openai",
+  claude: "claude-budget",
+  gemini: "gemini-budget",
+  "gemini-cli": "gemini-budget",
+  vertex: "gemini-budget",
+  antigravity: "gemini-budget",
+  kiro: "kiro",
+};
+
+// Strip a trailing thinking suffix "model(value)" → "model" (no-op when absent).
+export function stripThinkingSuffix(model) {
+  if (typeof model !== "string") return model;
+  const m = model.match(/^(.*)\([^()]+\)\s*$/);
+  return m ? m[1].trim() : model;
+}
+
+// Parse model-name suffix "model(value)" → { cleanModel, override }.
+// value: level name (high) | number (8192) | auto | none. null override when absent.
+export function parseSuffix(model) {
+  if (typeof model !== "string") return { cleanModel: model, override: null };
+  const m = model.match(/^(.*)\(([^()]+)\)\s*$/);
+  if (!m) return { cleanModel: model, override: null };
+  const cleanModel = m[1].trim();
+  const raw = m[2].trim().toLowerCase();
+  if (raw === "none" || raw === "off") return { cleanModel, override: { mode: "none" } };
+  if (raw === "auto") return { cleanModel, override: { mode: "auto" } };
+  if (/^\d+$/.test(raw)) return { cleanModel, override: { mode: "budget", budget: Number(raw) } };
+  if (LEVEL_TO_BUDGET[raw] !== undefined) return { cleanModel, override: { mode: "level", level: raw } };
+  return { cleanModel, override: null };
+}
+
+// Extract unified thinking intent from a request body (post-translation, mixed shapes).
+// Returns { mode, budget?, level? } or null when no thinking intent present.
+export function extractThinking(body) {
+  if (!body || typeof body !== "object") return null;
+
+  // Claude output_config.effort (explicit) — priority over adaptive thinking
+  const oc = body.output_config?.effort;
+  if (typeof oc === "string" && oc) {
+    const e = oc.toLowerCase();
+    if (e === "none" || e === "off") return { mode: "none" };
+    if (e === "auto") return { mode: "auto" };
+    return { mode: "level", level: e };
+  }
+
+  // Claude shape
+  const t = body.thinking;
+  if (t && typeof t === "object") {
+    if (t.type === "disabled") return { mode: "none" };
+    if (t.type === "adaptive" || t.type === "enabled") {
+      const budget = Number(t.budget_tokens);
+      if (Number.isFinite(budget) && budget > 0) return { mode: "budget", budget };
+      return { mode: "auto" };
+    }
+  }
+
+  // OpenAI chat / Responses shape
+  const effort = body.reasoning_effort ?? (typeof body.reasoning === "object" ? body.reasoning?.effort : null);
+  if (typeof effort === "string" && effort) {
+    const e = effort.toLowerCase();
+    if (e === "none" || e === "off") return { mode: "none" };
+    if (e === "auto") return { mode: "auto" };
+    return { mode: "level", level: e };
+  }
+
+  // Gemini shape (top-level, generationConfig, or request envelope)
+  const tc = body.thinkingConfig || body.generationConfig?.thinkingConfig || body.request?.generationConfig?.thinkingConfig;
+  if (tc && typeof tc === "object") {
+    if (typeof tc.thinkingLevel === "string") return { mode: "level", level: tc.thinkingLevel.toLowerCase() };
+    const tb = Number(tc.thinkingBudget);
+    if (Number.isFinite(tb)) {
+      if (tb === 0) return { mode: "none" };
+      if (tb < 0) return { mode: "auto" };
+      return { mode: "budget", budget: tb };
+    }
+  }
+
+  // Qwen shape
+  if (body.enable_thinking === false) return { mode: "none" };
+  if (body.enable_thinking === true) {
+    const tb = Number(body.thinking_budget);
+    if (Number.isFinite(tb) && tb > 0) return { mode: "budget", budget: tb };
+    return { mode: "auto" };
+  }
+
+  return null;
+}
+
+// Capture thinking intent from a body. Alias of extractThinking, named for clarity
+// at the call-site where intent is snapshotted before format translation.
+export const captureThinking = extractThinking;
+
+// Resolve thinking format: provider override > capability > derive(targetFormat).
+function resolveFormat(targetFormat, model, provider) {
+  const providerFmt = provider ? PROVIDERS[provider]?.thinkingFormat : null;
+  if (providerFmt) return providerFmt;
+  const caps = getCapabilitiesForModel(provider, model);
+  if (caps.thinkingFormat) return caps.thinkingFormat;
+  return FORMAT_TO_NATIVE[targetFormat] || "openai";
+}
+
+// Convert unified config to a budget number (for budget-based formats).
+function toBudget(cfg, range) {
+  let budget;
+  if (cfg.mode === "budget") budget = cfg.budget;
+  else if (cfg.mode === "level") budget = effortToBudget(cfg.level);
+  else if (cfg.mode === "auto") return -1;
+  if (!Number.isFinite(budget)) return undefined;
+  if (range) {
+    if (range.min != null && budget < range.min) budget = range.min;
+    if (range.max != null && budget > range.max) budget = range.max;
+  }
+  return budget;
+}
+
+// Convert unified config to a discrete level string.
+function toLevel(cfg) {
+  if (cfg.mode === "level") return cfg.level;
+  if (cfg.mode === "budget") return budgetToLevel(cfg.budget) || "medium";
+  if (cfg.mode === "auto") return "auto";
+  return null;
+}
+
+function toGeminiThinkingLevel(cfg) {
+  const raw = cfg.mode === "auto" ? "high" : (toLevel(cfg) || "high");
+  return effortToThinkingLevel(raw);
+}
+
+function toKimiReasoningEffort(cfg) {
+  const level = toLevel(cfg);
+  if (level === "auto") return "high";
+  if (level === "minimal") return "low";
+  if (level === "xhigh") return "max";
+  if (["low", "medium", "high", "max"].includes(level)) return level;
+  return null;
+}
+
+const GEMINI_LEVEL_OUTPUT_FLOOR = {
+  minimal: 4096,
+  low: 8192,
+  medium: 16384,
+  high: 65535,
+};
+
+function geminiBudgetOutputFloor(budget) {
+  if (budget === -1) return 32768;
+  if (!Number.isFinite(budget)) return 32768;
+  if (budget <= 1024) return 8192;
+  if (budget <= 8192) return 16384;
+  if (budget <= 24576) return 32768;
+  return 65535;
+}
+
+function geminiLevelOutputFloor(level) {
+  return GEMINI_LEVEL_OUTPUT_FLOOR[level] || GEMINI_LEVEL_OUTPUT_FLOOR.high;
+}
+
+// Gemini nests thinkingConfig under generationConfig. gemini-cli / antigravity wrap
+// the whole request in a { request: { generationConfig } } envelope — target the
+// envelope's generationConfig when present, else the top-level one.
+function getGeminiGenerationConfig(body) {
+  if (body.request && typeof body.request === "object") {
+    if (!body.request.generationConfig || typeof body.request.generationConfig !== "object") {
+      body.request.generationConfig = {};
+    }
+    return body.request.generationConfig;
+  }
+  if (!body.generationConfig || typeof body.generationConfig !== "object") {
+    body.generationConfig = {};
+  }
+  return body.generationConfig;
+}
+
+function setGeminiThinking(body, tc) {
+  const gc = getGeminiGenerationConfig(body);
+  gc.thinkingConfig = tc;
+}
+
+function ensureGeminiOutputFloor(body, floor, caps) {
+  const cap = Number.isFinite(caps?.maxOutput) ? caps.maxOutput : floor;
+  const target = Math.min(floor, cap);
+  const gc = getGeminiGenerationConfig(body);
+  const current = Number(gc.maxOutputTokens);
+  if (!Number.isFinite(current) || current < target) {
+    gc.maxOutputTokens = target;
+  }
+}
+
+// Strip every known thinking field from a body (used before re-applying / when unsupported).
+function stripAll(body) {
+  delete body.thinking;
+  delete body.reasoning_effort;
+  delete body.reasoning;
+  delete body.thinkingConfig;
+  delete body.enable_thinking;
+  delete body.thinking_budget;
+  delete body.output_config;
+  if (body.generationConfig) delete body.generationConfig.thinkingConfig;
+  if (body.request?.generationConfig) delete body.request.generationConfig.thinkingConfig;
+}
+
+// Apply unified thinking config to body in the resolved provider-native format.
+function applyFormat(fmt, body, cfg, caps) {
+  const none = cfg.mode === "none";
+  const canDisable = caps.thinkingCanDisable !== false;
+  // Model cannot disable thinking → clamp "none" to minimal effort instead.
+  const eff = none && !canDisable ? { mode: "level", level: "minimal" } : cfg;
+
+  switch (fmt) {
+    case "openai": {
+      if (none && canDisable) { body.reasoning_effort = "none"; break; }
+      const level = toLevel(eff);
+      // OpenAI reasoning_effort enum caps at "xhigh" (no "max"); clamp Claude Code's "max".
+      if (level) body.reasoning_effort = level === "max" ? "xhigh" : level;
+      break;
+    }
+    case "claude-adaptive": {
+      if (none && canDisable) { body.thinking = { type: "disabled" }; break; }
+      const level = toLevel(eff);
+      body.output_config = { effort: level === "xhigh" ? "high" : level };
+      break;
+    }
+    case "claude-budget": {
+      if (none && canDisable) { body.thinking = { type: "disabled" }; break; }
+      const budget = toBudget(eff, caps.thinkingRange);
+      body.thinking = budget === -1 ? { type: "enabled" } : { type: "enabled", budget_tokens: budget || 8192 };
+      break;
+    }
+    case "gemini-level": {
+      const level = none ? "minimal" : toGeminiThinkingLevel(eff);
+      setGeminiThinking(body, { thinkingLevel: level, includeThoughts: level !== "minimal" });
+      ensureGeminiOutputFloor(body, geminiLevelOutputFloor(level), caps);
+      break;
+    }
+    case "gemini-budget": {
+      if (none && canDisable) { setGeminiThinking(body, { thinkingBudget: 0, includeThoughts: false }); break; }
+      const budget = toBudget(eff, caps.thinkingRange);
+      setGeminiThinking(body, { thinkingBudget: budget ?? -1, includeThoughts: true });
+      ensureGeminiOutputFloor(body, geminiBudgetOutputFloor(budget ?? -1), caps);
+      break;
+    }
+    case "zai": {
+      // Z.ai ignores thinking.disabled → must use enable_thinking:false to turn off.
+      if (none && canDisable) { body.enable_thinking = false; delete body.thinking; break; }
+      body.thinking = { type: "enabled" };
+      break;
+    }
+    case "qwen": {
+      if (none && canDisable) { body.enable_thinking = false; break; }
+      body.enable_thinking = true;
+      const budget = toBudget(eff, caps.thinkingRange);
+      if (Number.isFinite(budget) && budget > 0) body.thinking_budget = budget;
+      break;
+    }
+    case "deepseek": {
+      if (none && canDisable) { body.thinking = { type: "disabled" }; break; }
+      body.thinking = { type: "enabled" };
+      // DeepSeek: low/medium→high, xhigh/max→max.
+      const level = toLevel(eff);
+      body.reasoning_effort = level === "xhigh" || level === "max" ? "max" : "high";
+      break;
+    }
+    case "kimi": {
+      if (none && canDisable) { body.thinking = { type: "disabled" }; break; }
+      const effort = toKimiReasoningEffort(eff);
+      if (effort) body.reasoning_effort = effort;
+      break;
+    }
+    case "minimax": {
+      // M3 adaptive; M2.x cannot disable (handled via canDisable clamp).
+      body.thinking = { type: none && canDisable ? "disabled" : "adaptive" };
+      break;
+    }
+    case "hunyuan": {
+      if (none && canDisable) { body.thinking = { type: "disabled" }; break; }
+      const budget = toBudget(eff, caps.thinkingRange);
+      body.thinking = budget === -1 ? { type: "enabled" } : { type: "enabled", budget_tokens: budget || 8192 };
+      break;
+    }
+    case "step": {
+      if (none && canDisable) break;
+      const level = toLevel(eff);
+      if (level) body.reasoning_effort = level === "xhigh" || level === "max" ? "high" : level;
+      break;
+    }
+    case "kiro":
+      // Kiro thinking handled via system-tag injection in openai-to-kiro.js; no body field here.
+      break;
+    default:
+      break;
+  }
+}
+
+// Public entry: normalize thinking for the resolved target format.
+// Mutates and returns body. No-op when model has no reasoning capability.
+// `intent` is a pre-captured config (from captureThinking on the original body);
+// falls back to extracting from the current body when omitted.
+export function applyThinking(targetFormat, model, body, provider = null, intent = undefined) {
+  if (!body || typeof body !== "object") return body;
+
+  const { cleanModel, override } = parseSuffix(model);
+  const cfg = override || intent || extractThinking(body);
+  const caps = getCapabilitiesForModel(provider, cleanModel);
+
+  // Model cannot reason → strip any stray thinking fields.
+  if (!caps.reasoning) {
+    stripAll(body);
+    return body;
+  }
+  if (!cfg) return body;
+
+  const fmt = resolveFormat(targetFormat, cleanModel, provider);
+  stripAll(body);
+  applyFormat(fmt, body, cfg, caps);
+  return body;
+}
diff --git a/open-sse/translator/concerns/toolCall.js b/open-sse/translator/concerns/toolCall.js
new file mode 100644
index 0000000..8de82f7
--- /dev/null
+++ b/open-sse/translator/concerns/toolCall.js
@@ -0,0 +1,153 @@
+// Tool call helper functions for translator
+
+// Anthropic tool_use.id must match: ^[a-zA-Z0-9_-]+$
+const TOOL_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+
+// Fallback streaming tool_call id when provider omits one (index optional)
+export function fallbackToolCallId(index) {
+  return index === undefined ? `call_${Date.now()}` : `call_${index}_${Date.now()}`;
+}
+
+// Generate deterministic tool call ID from position + tool name (cache-friendly)
+export function generateToolCallId(msgIndex = 0, tcIndex = 0, toolName = "") {
+  const name = toolName ? `_${toolName.replace(/[^a-zA-Z0-9_-]/g, "")}` : "";
+  return `call_msg${msgIndex}_tc${tcIndex}${name}`;
+}
+
+// Sanitize ID to match Anthropic pattern: keep only alphanumeric, underscore, hyphen
+function sanitizeToolId(id) {
+  if (!id || typeof id !== "string") return null;
+  const sanitized = id.replace(/[^a-zA-Z0-9_-]/g, "");
+  return sanitized.length > 0 ? sanitized : null;
+}
+
+// Ensure all tool_calls have valid id field and arguments is string (some providers require it)
+export function ensureToolCallIds(body) {
+  if (!body.messages || !Array.isArray(body.messages)) return body;
+
+  for (let i = 0; i < body.messages.length; i++) {
+    const msg = body.messages[i];
+    if (msg.role === "assistant" && msg.tool_calls && Array.isArray(msg.tool_calls)) {
+      for (let j = 0; j < msg.tool_calls.length; j++) {
+        const tc = msg.tool_calls[j];
+        // Validate or regenerate ID for Anthropic compatibility
+        if (!tc.id || !TOOL_ID_PATTERN.test(tc.id)) {
+          const sanitized = sanitizeToolId(tc.id);
+          tc.id = sanitized || generateToolCallId(i, j, tc.function?.name);
+        }
+        if (!tc.type) {
+          tc.type = "function";
+        }
+        // Ensure arguments is JSON string, not object
+        if (tc.function?.arguments && typeof tc.function.arguments !== "string") {
+          tc.function.arguments = JSON.stringify(tc.function.arguments);
+        }
+      }
+    }
+
+    // Validate tool_call_id in tool messages (role: "tool")
+    if (msg.role === "tool" && msg.tool_call_id && !TOOL_ID_PATTERN.test(msg.tool_call_id)) {
+      const sanitized = sanitizeToolId(msg.tool_call_id);
+      msg.tool_call_id = sanitized || generateToolCallId(i, 0);
+    }
+
+    // Also validate tool_use blocks in content (Claude format)
+    if (Array.isArray(msg.content)) {
+      for (let k = 0; k < msg.content.length; k++) {
+        const block = msg.content[k];
+        if (block.type === "tool_use" && block.id && !TOOL_ID_PATTERN.test(block.id)) {
+          const sanitized = sanitizeToolId(block.id);
+          block.id = sanitized || generateToolCallId(i, k, block.name);
+        }
+        // Validate tool_use_id in tool_result blocks
+        if (block.type === "tool_result" && block.tool_use_id && !TOOL_ID_PATTERN.test(block.tool_use_id)) {
+          const sanitized = sanitizeToolId(block.tool_use_id);
+          block.tool_use_id = sanitized || generateToolCallId(i, k);
+        }
+      }
+    }
+  }
+
+  return body;
+}
+
+// Get tool_call ids from assistant message (OpenAI format: tool_calls, Claude format: tool_use in content)
+export function getToolCallIds(msg) {
+  if (msg.role !== "assistant") return [];
+
+  const ids = [];
+
+  // OpenAI format: tool_calls array
+  if (msg.tool_calls && Array.isArray(msg.tool_calls)) {
+    for (const tc of msg.tool_calls) {
+      if (tc.id) ids.push(tc.id);
+    }
+  }
+
+  // Claude format: tool_use blocks in content
+  if (Array.isArray(msg.content)) {
+    for (const block of msg.content) {
+      if (block.type === "tool_use" && block.id) {
+        ids.push(block.id);
+      }
+    }
+  }
+
+  return ids;
+}
+
+// Check if user message has tool_result for given ids (OpenAI format: role=tool, Claude format: tool_result in content)
+export function hasToolResults(msg, toolCallIds) {
+  if (!msg || !toolCallIds.length) return false;
+
+  // OpenAI format: role = "tool" with tool_call_id
+  if (msg.role === "tool" && msg.tool_call_id) {
+    return toolCallIds.includes(msg.tool_call_id);
+  }
+
+  // Claude format: tool_result blocks in user message content
+  if (msg.role === "user" && Array.isArray(msg.content)) {
+    for (const block of msg.content) {
+      if (block.type === "tool_result" && toolCallIds.includes(block.tool_use_id)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+// Fix missing tool responses - insert empty tool_result if assistant has tool_use but next message has no tool_result
+export function fixMissingToolResponses(body) {
+  if (!body.messages || !Array.isArray(body.messages)) return body;
+
+  const newMessages = [];
+
+  for (let i = 0; i < body.messages.length; i++) {
+    const msg = body.messages[i];
+    const nextMsg = body.messages[i + 1];
+
+    newMessages.push(msg);
+
+    // Check if this is assistant with tool_calls/tool_use
+    const toolCallIds = getToolCallIds(msg);
+    if (toolCallIds.length === 0) continue;
+
+    // Check if next message has tool_result
+    if (nextMsg && !hasToolResults(nextMsg, toolCallIds)) {
+      // Insert tool responses for each tool_call
+      for (const id of toolCallIds) {
+        // OpenAI format: role = "tool"
+        newMessages.push({
+          role: "tool",
+          tool_call_id: id,
+          content: ""
+        });
+      }
+    }
+  }
+
+  body.messages = newMessages;
+  return body;
+}
+
diff --git a/open-sse/translator/concerns/usage.js b/open-sse/translator/concerns/usage.js
new file mode 100644
index 0000000..3ace306
--- /dev/null
+++ b/open-sse/translator/concerns/usage.js
@@ -0,0 +1,69 @@
+// Build OpenAI usage object. Caller computes prompt/completion/total (provider math).
+// Optional details added only when > 0 (matches existing claude/gemini/codex behavior).
+export function buildUsage({ promptTokens, completionTokens, totalTokens, cachedTokens = 0, cacheCreationTokens = 0, reasoningTokens = 0 }) {
+  const usage = { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: totalTokens };
+  if (cachedTokens > 0 || cacheCreationTokens > 0) {
+    usage.prompt_tokens_details = {};
+    if (cachedTokens > 0) usage.prompt_tokens_details.cached_tokens = cachedTokens;
+    if (cacheCreationTokens > 0) usage.prompt_tokens_details.cache_creation_tokens = cacheCreationTokens;
+  }
+  if (reasoningTokens > 0) {
+    usage.completion_tokens_details = { reasoning_tokens: reasoningTokens };
+  }
+  return usage;
+}
+
+const n = (v) => (typeof v === "number" ? v : 0);
+
+// Per-provider raw token field-map + math. Returns buildUsage() args (NOT the usage object).
+// Keeps each provider's exact semantics: claude/gemini fold cache+reasoning, others don't.
+const USAGE_EXTRACTORS = {
+  claude(raw) {
+    const input = n(raw.input_tokens), output = n(raw.output_tokens);
+    const cacheRead = n(raw.cache_read_input_tokens), cacheCreate = n(raw.cache_creation_input_tokens);
+    const prompt = input + cacheRead + cacheCreate;
+    return { promptTokens: prompt, completionTokens: output, totalTokens: prompt + output, cachedTokens: cacheRead, cacheCreationTokens: cacheCreate };
+  },
+  gemini(raw) {
+    const cached = n(raw.cachedContentTokenCount);
+    const prompt = n(raw.promptTokenCount);
+    const thoughts = n(raw.thoughtsTokenCount);
+    const total = n(raw.totalTokenCount);
+    let candidates = n(raw.candidatesTokenCount);
+    // Fallback: derive candidates from total when upstream omits it
+    if (candidates === 0 && total > 0) {
+      candidates = total - prompt - thoughts;
+      if (candidates < 0) candidates = 0;
+    }
+    return { promptTokens: prompt, completionTokens: candidates + thoughts, totalTokens: total, cachedTokens: cached, reasoningTokens: thoughts };
+  },
+  kiro(raw) {
+    const input = n(raw.inputTokens), output = n(raw.outputTokens);
+    // ponytail: Amazon Q (Kiro upstream) does not expose cache fields today,
+    // but pass through any cache_read/cache_creation/cached_tokens if the
+    // event shape grows them later so cost tracking keeps working without
+    // a second pass.
+    const cached = n(raw.cache_read_input_tokens) || n(raw.cachedTokens) || n(raw.cached_tokens);
+    const cacheCreation = n(raw.cache_creation_input_tokens);
+    const out = { promptTokens: input, completionTokens: output, totalTokens: input + output };
+    if (cached > 0) out.cachedTokens = cached;
+    if (cacheCreation > 0) out.cacheCreationTokens = cacheCreation;
+    return out;
+  },
+  ollama(raw) {
+    const input = n(raw.prompt_eval_count), output = n(raw.eval_count);
+    return { promptTokens: input, completionTokens: output, totalTokens: input + output };
+  },
+  commandcode(raw) {
+    const input = n(raw.inputTokens), output = n(raw.outputTokens);
+    const total = typeof raw.totalTokens === "number" ? raw.totalTokens : input + output;
+    return { promptTokens: input, completionTokens: output, totalTokens: total };
+  },
+};
+
+// Convert provider-native usage object → OpenAI usage. Returns null if no extractor/raw.
+export function toOpenAIUsage(raw, kind) {
+  const extract = USAGE_EXTRACTORS[kind];
+  if (!extract || !raw || typeof raw !== "object") return null;
+  return buildUsage(extract(raw));
+}
diff --git a/open-sse/translator/formats.js b/open-sse/translator/formats.js
new file mode 100644
index 0000000..89367d0
--- /dev/null
+++ b/open-sse/translator/formats.js
@@ -0,0 +1,36 @@
+// Format identifiers
+export const FORMATS = {
+  OPENAI: "openai",
+  OPENAI_RESPONSES: "openai-responses",
+  OPENAI_RESPONSE: "openai-response",
+  CLAUDE: "claude",
+  GEMINI: "gemini",
+  GEMINI_CLI: "gemini-cli",
+  VERTEX: "vertex",
+  CODEX: "codex",
+  ANTIGRAVITY: "antigravity",
+  KIRO: "kiro",
+  CURSOR: "cursor",
+  OLLAMA: "ollama",
+  COMMANDCODE: "commandcode"
+};
+
+/**
+ * Detect source format from request URL pathname + body.
+ * Returns null to fall back to body-based detection.
+ */
+export function detectFormatByEndpoint(pathname, body) {
+  // /v1/responses is always openai-responses
+  if (pathname.includes("/v1/responses")) return FORMATS.OPENAI_RESPONSES;
+
+  // /v1/messages is always Claude
+  if (pathname.includes("/v1/messages")) return FORMATS.CLAUDE;
+
+  // /v1/chat/completions + input[] → treat as openai (Cursor CLI sends Responses body via chat endpoint)
+  if (pathname.includes("/v1/chat/completions") && Array.isArray(body?.input)) {
+    return FORMATS.OPENAI;
+  }
+
+  return null;
+}
+
diff --git a/open-sse/translator/formats/claude.js b/open-sse/translator/formats/claude.js
new file mode 100644
index 0000000..adbd3ce
--- /dev/null
+++ b/open-sse/translator/formats/claude.js
@@ -0,0 +1,368 @@
+// Claude helper functions for translator
+import { DEFAULT_THINKING_CLAUDE_SIGNATURE } from "../../config/defaultThinkingSignature.js";
+import { ROLE, CLAUDE_BLOCK } from "../schema/index.js";
+import { adjustMaxTokens } from "./maxTokens.js";
+import { applyCloaking } from "../../utils/claudeCloaking.js";
+import { resolveSessionId } from "../../utils/sessionManager.js";
+import { isValidClaudeSignature } from "../../utils/claudeSignature.js";
+import { PROVIDERS } from "../../providers/index.js";
+import { getCapabilitiesForModel } from "../../providers/capabilities.js";
+import { DEFAULT_MAX_TOKENS } from "../../config/runtimeConfig.js";
+
+// Check if message has valid non-empty content
+export function hasValidContent(msg) {
+  if (typeof msg.content === "string" && msg.content.trim()) return true;
+  if (Array.isArray(msg.content)) {
+    return msg.content.some(block =>
+      (block.type === CLAUDE_BLOCK.TEXT && block.text?.trim()) ||
+      block.type === CLAUDE_BLOCK.TOOL_USE ||
+      block.type === CLAUDE_BLOCK.TOOL_RESULT
+    );
+  }
+  return false;
+}
+
+// Fix tool_use/tool_result ordering for Claude API
+// 1. Assistant message with tool_use: remove text AFTER tool_use (Claude doesn't allow)
+// 2. Merge consecutive same-role messages
+export function fixToolUseOrdering(messages) {
+  if (messages.length <= 1) return messages;
+
+  // Pass 1: Fix assistant messages with tool_use - remove text after tool_use
+  for (const msg of messages) {
+    if (msg.role === ROLE.ASSISTANT && Array.isArray(msg.content)) {
+      const hasToolUse = msg.content.some(b => b.type === CLAUDE_BLOCK.TOOL_USE);
+      if (hasToolUse) {
+        // Keep only: thinking blocks + tool_use blocks (remove text blocks after tool_use)
+        const newContent = [];
+        let foundToolUse = false;
+
+        for (const block of msg.content) {
+          if (block.type === CLAUDE_BLOCK.TOOL_USE) {
+            foundToolUse = true;
+            newContent.push(block);
+          } else if (block.type === CLAUDE_BLOCK.THINKING || block.type === CLAUDE_BLOCK.REDACTED_THINKING) {
+            newContent.push(block);
+          } else if (!foundToolUse) {
+            // Keep text blocks BEFORE tool_use
+            newContent.push(block);
+          }
+          // Skip text blocks AFTER tool_use
+        }
+
+        msg.content = newContent;
+      }
+    }
+  }
+
+  // Pass 2: Merge consecutive same-role messages
+  const merged = [];
+
+  for (const msg of messages) {
+    const last = merged[merged.length - 1];
+
+    if (last && last.role === msg.role) {
+      // Merge content arrays
+      const lastContent = Array.isArray(last.content) ? last.content : [{ type: CLAUDE_BLOCK.TEXT, text: last.content }];
+      const msgContent = Array.isArray(msg.content) ? msg.content : [{ type: CLAUDE_BLOCK.TEXT, text: msg.content }];
+
+      // Put tool_result first, then other content
+      const toolResults = [...lastContent.filter(b => b.type === CLAUDE_BLOCK.TOOL_RESULT), ...msgContent.filter(b => b.type === CLAUDE_BLOCK.TOOL_RESULT)];
+      const otherContent = [...lastContent.filter(b => b.type !== CLAUDE_BLOCK.TOOL_RESULT), ...msgContent.filter(b => b.type !== CLAUDE_BLOCK.TOOL_RESULT)];
+
+      last.content = [...toolResults, ...otherContent];
+    } else {
+      // Ensure content is array
+      const content = Array.isArray(msg.content) ? msg.content : [{ type: CLAUDE_BLOCK.TEXT, text: msg.content }];
+      merged.push({ role: msg.role, content: [...content] });
+    }
+  }
+
+  return merged;
+}
+
+// Models that reject thinking.type "adaptive" + output_config.effort (Opus 4.5+/Sonnet 4.6+ only)
+const ADAPTIVE_THINKING_UNSUPPORTED = /haiku/i;
+
+function handlesThinkingBlocks(provider) {
+  return provider === "claude" || provider?.startsWith("anthropic-compatible") || provider === "deepseek";
+}
+
+function buildThinkingPlaceholder(provider) {
+  const block = {
+    type: CLAUDE_BLOCK.THINKING,
+    thinking: ".",
+  };
+
+  // DeepSeek's Anthropic-compatible endpoint requires a thinking block in
+  // thinking mode, but it does not need Anthropic's signed-thinking fallback.
+  if (provider !== "deepseek") {
+    block.signature = DEFAULT_THINKING_CLAUDE_SIGNATURE;
+  }
+
+  return block;
+}
+
+// Normalize a native Claude passthrough body to match Anthropic Messages API spec.
+// Newer Cowork/Claude Code clients emit beta-only shapes that OAuth endpoints reject:
+// 1. thinking.type "adaptive" → unsupported on Haiku
+// 2. output_config.effort → unsupported on Haiku
+// 3. role "system" messages (mid-conversation-system beta) → only top-level system is allowed
+export function normalizeClaudePassthrough(body, model = "") {
+  if (!body || typeof body !== "object") return body;
+
+  // 1. Downgrade adaptive thinking for models that don't support it
+  if (body.thinking?.type === "adaptive" && ADAPTIVE_THINKING_UNSUPPORTED.test(model)) {
+    body.thinking = { type: "enabled", budget_tokens: 10000 };
+  }
+
+  // 2. Strip effort param for models that don't support it (keep other output_config fields)
+  if (ADAPTIVE_THINKING_UNSUPPORTED.test(model) && body.output_config?.effort != null) {
+    delete body.output_config.effort;
+    if (Object.keys(body.output_config).length === 0) delete body.output_config;
+  }
+
+  // 2. Hoist mid-conversation system messages into the top-level system field
+  if (Array.isArray(body.messages)) {
+    const systemBlocks = [];
+    const messages = [];
+    for (const msg of body.messages) {
+      if (msg.role === ROLE.SYSTEM) {
+        const text = typeof msg.content === "string"
+          ? msg.content
+          : Array.isArray(msg.content)
+            ? msg.content.map(b => (typeof b === "string" ? b : b?.text || "")).join("\n")
+            : "";
+        if (text.trim()) systemBlocks.push({ type: CLAUDE_BLOCK.TEXT, text });
+        continue;
+      }
+      messages.push(msg);
+    }
+
+    if (systemBlocks.length > 0) {
+      const existing = Array.isArray(body.system)
+        ? body.system
+        : typeof body.system === "string" && body.system.trim()
+          ? [{ type: "text", text: body.system }]
+          : [];
+      body.system = [...existing, ...systemBlocks];
+      body.messages = messages;
+    }
+  }
+
+  // 3. Drop thinking blocks whose signature is not Claude's (combo mixes models,
+  // so foreign signatures leak into history and Anthropic rejects them).
+  const thinkingEnabled = body.thinking?.type === "enabled";
+  if (Array.isArray(body.messages)) {
+    for (const msg of body.messages) {
+      if (msg.role !== ROLE.ASSISTANT || !Array.isArray(msg.content)) continue;
+      let hasToolUse = false;
+      let hasKeptThinking = false;
+      const kept = [];
+      for (const block of msg.content) {
+        if (block.type === CLAUDE_BLOCK.THINKING || block.type === CLAUDE_BLOCK.REDACTED_THINKING) {
+          if (isValidClaudeSignature(block.signature)) {
+            hasKeptThinking = true;
+            kept.push(block);
+          }
+          continue;
+        }
+        if (block.type === CLAUDE_BLOCK.TOOL_USE) hasToolUse = true;
+        kept.push(block);
+      }
+      msg.content = kept;
+      if (thinkingEnabled && !hasKeptThinking && hasToolUse) {
+        msg.content.unshift(buildThinkingPlaceholder("claude"));
+      }
+    }
+  }
+
+  return body;
+}
+
+// Prepare request for Claude format endpoints
+// - Cleanup cache_control
+// - Filter empty messages
+// - Add thinking block for Anthropic endpoint (provider === "claude")
+// - Fix tool_use/tool_result ordering
+// - Apply cloaking (billing header + fake user ID) for OAuth tokens
+export function prepareClaudeRequest(body, provider = null, apiKey = null, connectionId = null, rawHeaders = null, sessionId = null) {
+  // quirk: MiniMax's Claude-compatible endpoint rejects Anthropic's output_config (400 invalid params)
+  if (PROVIDERS[provider]?.quirks?.dropOutputConfig) {
+    delete body.output_config;
+  }
+
+  // Clamp max_tokens to the model's real output ceiling. Models whose caps
+  // declare a higher maxOutput (e.g. Opus 4.8 / Sonnet 4.6 = 128000) are allowed
+  // up to it, so max-effort thinking gets full budget; others fall back to the
+  // conservative 64000 default.
+  if (body.max_tokens) {
+    const ceiling = getCapabilitiesForModel(provider, body.model).maxOutput || DEFAULT_MAX_TOKENS;
+    if (body.max_tokens > ceiling) body.max_tokens = ceiling;
+
+    // Reconcile against thinking budget. applyThinking (thinkingUnified.js) runs
+    // AFTER adjustMaxTokens capped max_tokens, and the claude-budget format maps
+    // max effort → budget_tokens 128000 — larger than the clamped max_tokens.
+    // Anthropic requires max_tokens strictly greater than budget_tokens (else 400).
+    // Prefer raising max_tokens to preserve the requested thinking depth; if the
+    // budget alone meets/exceeds the ceiling, cap output and shrink the budget so
+    // some tokens remain for the answer.
+    if (body.thinking?.type === "enabled" && body.thinking.budget_tokens && body.thinking.budget_tokens >= body.max_tokens) {
+      body.max_tokens = Math.min(body.thinking.budget_tokens + 1024, ceiling);
+      if (body.thinking.budget_tokens >= body.max_tokens) {
+        body.thinking.budget_tokens = Math.max(1024, body.max_tokens - 1024);
+      }
+    }
+  }
+
+  // 1. System: remove all cache_control, add only to last block with ttl 1h
+  if (body.system && Array.isArray(body.system)) {
+    body.system = body.system.map((block, i) => {
+      const { cache_control, ...rest } = block;
+      if (i === body.system.length - 1) {
+        return { ...rest, cache_control: { type: "ephemeral", ttl: "1h" } };
+      }
+      return rest;
+    });
+  }
+
+  // 2. Messages: process in optimized passes
+  if (body.messages && Array.isArray(body.messages)) {
+    const len = body.messages.length;
+    let filtered = [];
+
+    // Pass 1: remove cache_control + filter empty messages
+    for (let i = 0; i < len; i++) {
+      const msg = body.messages[i];
+
+      // Remove cache_control from content blocks
+      if (Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+          delete block.cache_control;
+        }
+      }
+
+      // Keep final assistant even if empty, otherwise check valid content
+      const isFinalAssistant = i === len - 1 && msg.role === "assistant";
+      if (isFinalAssistant || hasValidContent(msg)) {
+        filtered.push(msg);
+      }
+    }
+
+    // Pass 1.5: Fix tool_use/tool_result ordering
+    // Each tool_use must have tool_result in the NEXT message (not same message with other content)
+    filtered = fixToolUseOrdering(filtered);
+
+    body.messages = filtered;
+
+    // Check if thinking is enabled AND last message is from user
+    const lastMessage = filtered[filtered.length - 1];
+    const lastMessageIsUser = lastMessage?.role === "user";
+    const thinkingEnabled = body.thinking?.type === "enabled" && lastMessageIsUser;
+
+    // Pass 2 (reverse): add cache_control to last assistant + handle thinking for Anthropic
+    let lastAssistantProcessed = false;
+    for (let i = filtered.length - 1; i >= 0; i--) {
+      const msg = filtered[i];
+
+      if (msg.role === "assistant" && Array.isArray(msg.content)) {
+        // Add cache_control to last non-thinking block of first (from end) assistant with content
+        // thinking/redacted_thinking blocks do not support cache_control
+        if (!lastAssistantProcessed && msg.content.length > 0) {
+          for (let j = msg.content.length - 1; j >= 0; j--) {
+            const block = msg.content[j];
+            if (block.type !== CLAUDE_BLOCK.THINKING && block.type !== CLAUDE_BLOCK.REDACTED_THINKING) {
+              block.cache_control = { type: "ephemeral" };
+              break;
+            }
+          }
+          lastAssistantProcessed = true;
+        }
+
+        // Handle thinking blocks for Anthropic-compatible endpoints.
+        if (handlesThinkingBlocks(provider)) {
+          let hasToolUse = false;
+          let hasKeptThinking = false;
+
+          // Claude native: preserve valid signatures, drop invalid blocks.
+          // anthropic-compatible: replace with default (safe fallback for lenient upstreams).
+          // DeepSeek: keep existing thinking as-is; add an unsigned placeholder only if missing.
+          const isClaudeNative = provider === "claude";
+          const isDeepSeek = provider === "deepseek";
+          const kept = [];
+          for (const block of msg.content) {
+            const isThinking = block.type === CLAUDE_BLOCK.THINKING || block.type === CLAUDE_BLOCK.REDACTED_THINKING;
+            if (isThinking) {
+              if (isClaudeNative) {
+                if (isValidClaudeSignature(block.signature)) {
+                  hasKeptThinking = true;
+                  kept.push(block);
+                }
+              } else if (isDeepSeek) {
+                hasKeptThinking = true;
+                kept.push(block);
+              } else {
+                block.signature = DEFAULT_THINKING_CLAUDE_SIGNATURE;
+                hasKeptThinking = true;
+                kept.push(block);
+              }
+              continue;
+            }
+            if (block.type === CLAUDE_BLOCK.TOOL_USE) hasToolUse = true;
+            kept.push(block);
+          }
+          msg.content = kept;
+
+          // Add thinking block if thinking enabled + has tool_use but no thinking
+          if (thinkingEnabled && !hasKeptThinking && hasToolUse) {
+            msg.content.unshift(buildThinkingPlaceholder(provider));
+          }
+        }
+      }
+    }
+  }
+
+  // 3. Tools: filter built-in tools for non-Anthropic providers, then handle cache_control
+  if (body.tools && Array.isArray(body.tools)) {
+    // Strip built-in tools (e.g. web_search_20250305) and normalize to Anthropic-native shape
+    // (drop `type` field, fold `function.{name,description,parameters}`) for non-Anthropic providers
+    if (provider !== "claude") {
+      body.tools = body.tools
+        .filter(tool => !tool.type || tool.type === "function")
+        .map(tool => {
+          if (tool.function) {
+            return {
+              name: tool.function.name,
+              description: tool.function.description,
+              input_schema: tool.function.parameters,
+            };
+          }
+          const { type, ...rest } = tool;
+          return rest;
+        });
+    }
+
+    body.tools = body.tools.map((tool, i) => {
+      const { cache_control, ...rest } = tool;
+      if (i === body.tools.length - 1) {
+        return { ...rest, cache_control: { type: "ephemeral", ttl: "1h" } };
+      }
+      return rest;
+    });
+
+    // Remove tools array and tool_choice if empty after filtering
+    if (body.tools.length === 0) {
+      delete body.tools;
+      delete body.tool_choice;
+    }
+  }
+
+  // Apply cloaking for OAuth tokens (billing header + fake user ID)
+  // session_id in user_id must match X-Claude-Code-Session-Id for fingerprint consistency
+  if ((provider === "claude" || provider?.startsWith("anthropic-compatible")) && apiKey) {
+    const sid = sessionId || resolveSessionId({ headers: rawHeaders, body, connectionId, scope: "claude" });
+    body = applyCloaking(body, apiKey, sid);
+  }
+
+  return body;
+}
diff --git a/open-sse/translator/formats/gemini.js b/open-sse/translator/formats/gemini.js
new file mode 100644
index 0000000..bf6c458
--- /dev/null
+++ b/open-sse/translator/formats/gemini.js
@@ -0,0 +1,380 @@
+// Gemini helper functions for translator
+
+import { safeParseJSON } from "../concerns/json.js";
+import { OPENAI_BLOCK } from "../schema/index.js";
+
+// Unsupported JSON Schema constraints that should be removed for Antigravity
+export const UNSUPPORTED_SCHEMA_CONSTRAINTS = [
+  // Basic constraints (not supported by Gemini API)
+  "minLength", "maxLength", "exclusiveMinimum", "exclusiveMaximum",
+  "minItems", "maxItems", "format",
+  // Claude rejects these in VALIDATED mode
+  "default", "examples",
+  // JSON Schema meta keywords
+  "$schema", "$defs", "definitions", "const", "$ref", "$comment",
+  // Annotation keywords (rejected by Gemini/Antigravity - e.g. MCP tool schemas set these)
+  "deprecated", "readOnly", "writeOnly",
+  // Object validation keywords (not supported)
+  "additionalProperties", "propertyNames", "patternProperties", "enumDescriptions",
+  // Complex schema keywords (handled by flattenAnyOfOneOf/mergeAllOf)
+  "anyOf", "oneOf", "allOf", "not",
+  // Dependency keywords (not supported)
+  "dependencies", "dependentSchemas", "dependentRequired",
+  // Other unsupported keywords
+  "title", "optional", "deprecated", "if", "then", "else", "contentMediaType", "contentEncoding",
+  // UI/Styling properties (from Cursor tools - NOT JSON Schema standard)
+  "cornerRadius", "fillColor", "fontFamily", "fontSize", "fontWeight",
+  "gap", "padding", "strokeColor", "strokeThickness", "textColor"
+];
+
+// Default safety settings
+export const DEFAULT_SAFETY_SETTINGS = [
+  { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "OFF" },
+  { category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "OFF" },
+  { category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold: "OFF" },
+  { category: "HARM_CATEGORY_HARASSMENT", threshold: "OFF" },
+  { category: "HARM_CATEGORY_CIVIC_INTEGRITY", threshold: "OFF" }
+];
+
+// Convert OpenAI content to Gemini parts
+export function convertOpenAIContentToParts(content) {
+  const parts = [];
+
+  if (typeof content === "string") {
+    parts.push({ text: content });
+  } else if (Array.isArray(content)) {
+    for (const item of content) {
+      if (item.type === OPENAI_BLOCK.TEXT) {
+        parts.push({ text: item.text });
+      } else if (item.type === OPENAI_BLOCK.IMAGE_URL && item.image_url?.url?.startsWith("data:")) {
+        const url = item.image_url.url;
+        const commaIndex = url.indexOf(",");
+        if (commaIndex !== -1) {
+          const mimePart = url.substring(5, commaIndex); // skip "data:"
+          const data = url.substring(commaIndex + 1);
+          const mimeType = mimePart.split(";")[0];
+
+          parts.push({
+            inlineData: { mime_type: mimeType, data: data }
+          });
+        }
+      } else if (item.type === OPENAI_BLOCK.IMAGE_URL && item.image_url?.url && (item.image_url.url.startsWith("http://") || item.image_url.url.startsWith("https://"))) {
+        parts.push({
+          fileData: { fileUri: item.image_url.url, mimeType: "image/*" }
+        });
+      } else if (item.type === OPENAI_BLOCK.INPUT_AUDIO && item.input_audio?.data) {
+        const format = item.input_audio.format || "wav";
+        const mimeType = format === "mp3" ? "audio/mpeg" : `audio/${format}`;
+        parts.push({
+          inlineData: { mime_type: mimeType, data: item.input_audio.data }
+        });
+      } else if (item.type === OPENAI_BLOCK.AUDIO_URL && item.audio_url?.url?.startsWith("data:")) {
+        const url = item.audio_url.url;
+        const commaIndex = url.indexOf(",");
+        if (commaIndex !== -1) {
+          const mimePart = url.substring(5, commaIndex);
+          const data = url.substring(commaIndex + 1);
+          const mimeType = mimePart.split(";")[0];
+          parts.push({
+            inlineData: { mime_type: mimeType, data: data }
+          });
+        }
+      } else if (item.type === OPENAI_BLOCK.FILE && item.file?.file_data?.startsWith("data:")) {
+        const url = item.file.file_data;
+        const commaIndex = url.indexOf(",");
+        if (commaIndex !== -1) {
+          const mimeType = url.substring(5, commaIndex).split(";")[0];
+          const data = url.substring(commaIndex + 1);
+          parts.push({ inlineData: { mime_type: mimeType, data: data } });
+        }
+      }
+    }
+  }
+
+  return parts;
+}
+
+// Extract text content from OpenAI content
+export function extractTextContent(content, separator = "") {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.filter(c => c.type === OPENAI_BLOCK.TEXT).map(c => c.text).join(separator);
+  }
+  return "";
+}
+
+// Try parse JSON safely (null fallback on parse error; re-export keeps legacy API)
+export function tryParseJSON(str) {
+  return safeParseJSON(str, null);
+}
+
+// Generate request ID
+export function generateRequestId() {
+  return `agent-${crypto.randomUUID()}`;
+}
+
+// Generate session ID (binary-compatible format: UUID + timestamp)
+export function generateSessionId() {
+  return crypto.randomUUID() + Date.now().toString();
+}
+
+// Generate project ID
+export function generateProjectId() {
+  const adjectives = ["useful", "bright", "swift", "calm", "bold"];
+  const nouns = ["fuze", "wave", "spark", "flow", "core"];
+  const adj = adjectives[Math.floor(Math.random() * adjectives.length)];
+  const noun = nouns[Math.floor(Math.random() * nouns.length)];
+  return `${adj}-${noun}-${crypto.randomUUID().slice(0, 5)}`;
+}
+
+// Helper: Remove unsupported keywords recursively from object/array
+// Also strips all vendor extension fields (x- prefixed) not supported by Gemini
+function removeUnsupportedKeywords(obj, keywords) {
+  if (!obj || typeof obj !== "object") return;
+
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      removeUnsupportedKeywords(item, keywords);
+    }
+    return;
+  }
+
+  for (const key of Object.keys(obj)) {
+    if (keywords.includes(key) || key.startsWith("x-")) {
+      delete obj[key];
+      continue;
+    }
+
+    const value = obj[key];
+    if (value && typeof value === "object") {
+      removeUnsupportedKeywords(value, keywords);
+    }
+  }
+}
+
+// Convert const to enum
+function convertConstToEnum(obj) {
+  if (!obj || typeof obj !== "object") return;
+
+  if (obj.const !== undefined && !obj.enum) {
+    obj.enum = [obj.const];
+    delete obj.const;
+  }
+
+  for (const value of Object.values(obj)) {
+    if (value && typeof value === "object") {
+      convertConstToEnum(value);
+    }
+  }
+}
+
+// Convert enum values to strings (Gemini requires string enum values + explicit type:"string")
+function convertEnumValuesToStrings(obj) {
+  if (!obj || typeof obj !== "object") return;
+
+  if (obj.enum && Array.isArray(obj.enum)) {
+    obj.enum = obj.enum.map(v => String(v));
+    // Gemini API requires type:"string" when enum is present — without it returns 400
+    if (!obj.type) {
+      obj.type = "string";
+    }
+  }
+
+  for (const value of Object.values(obj)) {
+    if (value && typeof value === "object") {
+      convertEnumValuesToStrings(value);
+    }
+  }
+}
+
+// Merge allOf schemas
+function mergeAllOf(obj) {
+  if (!obj || typeof obj !== "object") return;
+
+  if (obj.allOf && Array.isArray(obj.allOf)) {
+    const merged = {};
+
+    for (const item of obj.allOf) {
+      if (item.properties) {
+        if (!merged.properties) merged.properties = {};
+        Object.assign(merged.properties, item.properties);
+      }
+      if (item.required && Array.isArray(item.required)) {
+        if (!merged.required) merged.required = [];
+        for (const req of item.required) {
+          if (!merged.required.includes(req)) {
+            merged.required.push(req);
+          }
+        }
+      }
+    }
+
+    delete obj.allOf;
+    if (merged.properties) obj.properties = { ...obj.properties, ...merged.properties };
+    if (merged.required) obj.required = [...(obj.required || []), ...merged.required];
+  }
+
+  for (const value of Object.values(obj)) {
+    if (value && typeof value === "object") {
+      mergeAllOf(value);
+    }
+  }
+}
+
+// Select best schema from anyOf/oneOf
+function selectBest(items) {
+  let bestIdx = 0;
+  let bestScore = -1;
+
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    let score = 0;
+    const type = item.type;
+
+    if (type === "object" || item.properties) {
+      score = 3;
+    } else if (type === "array" || item.items) {
+      score = 2;
+    } else if (type && type !== "null") {
+      score = 1;
+    }
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestIdx = i;
+    }
+  }
+
+  return bestIdx;
+}
+
+// Flatten anyOf/oneOf
+function flattenAnyOfOneOf(obj) {
+  if (!obj || typeof obj !== "object") return;
+
+  if (obj.anyOf && Array.isArray(obj.anyOf) && obj.anyOf.length > 0) {
+    const nonNullSchemas = obj.anyOf.filter(s => s && s.type !== "null");
+    if (nonNullSchemas.length > 0) {
+      const bestIdx = selectBest(nonNullSchemas);
+      const selected = nonNullSchemas[bestIdx];
+      delete obj.anyOf;
+      Object.assign(obj, selected);
+    }
+  }
+
+  if (obj.oneOf && Array.isArray(obj.oneOf) && obj.oneOf.length > 0) {
+    const nonNullSchemas = obj.oneOf.filter(s => s && s.type !== "null");
+    if (nonNullSchemas.length > 0) {
+      const bestIdx = selectBest(nonNullSchemas);
+      const selected = nonNullSchemas[bestIdx];
+      delete obj.oneOf;
+      Object.assign(obj, selected);
+    }
+  }
+
+  for (const value of Object.values(obj)) {
+    if (value && typeof value === "object") {
+      flattenAnyOfOneOf(value);
+    }
+  }
+}
+
+// Flatten type arrays
+function flattenTypeArrays(obj) {
+  if (!obj || typeof obj !== "object") return;
+
+  if (obj.type && Array.isArray(obj.type)) {
+    const nonNullTypes = obj.type.filter(t => t !== "null");
+    obj.type = nonNullTypes.length > 0 ? nonNullTypes[0] : "string";
+  }
+
+  for (const value of Object.values(obj)) {
+    if (value && typeof value === "object") {
+      flattenTypeArrays(value);
+    }
+  }
+}
+
+// Infer missing type=object when properties exist (Gemini requires explicit type)
+function ensureObjectType(obj) {
+  if (!obj || typeof obj !== "object") return;
+  if (obj.properties && !obj.type) obj.type = "object";
+  for (const v of Object.values(obj)) if (v && typeof v === "object") ensureObjectType(v);
+}
+
+// Clean JSON Schema for Antigravity API compatibility - removes unsupported keywords recursively
+export function cleanJSONSchemaForAntigravity(schema) {
+  if (!schema || typeof schema !== "object") return schema;
+
+  // Mutate directly (schema is only used once per request)
+  let cleaned = schema;
+
+  // Phase 1: Convert and prepare
+  convertConstToEnum(cleaned);
+  convertEnumValuesToStrings(cleaned);
+
+  // Phase 2: Flatten complex structures
+  mergeAllOf(cleaned);
+  flattenAnyOfOneOf(cleaned);
+  flattenTypeArrays(cleaned);
+
+  // Phase 2.5: Infer missing type=object when properties exist (Gemini requirement)
+  ensureObjectType(cleaned);
+
+  // Phase 3: Remove all unsupported keywords at ALL levels (including inside arrays)
+  removeUnsupportedKeywords(cleaned, UNSUPPORTED_SCHEMA_CONSTRAINTS);
+
+  // Phase 4: Cleanup required fields recursively
+  function cleanupRequired(obj) {
+    if (!obj || typeof obj !== "object") return;
+
+    if (obj.required && Array.isArray(obj.required) && obj.properties) {
+      const validRequired = obj.required.filter(field =>
+        Object.prototype.hasOwnProperty.call(obj.properties, field)
+      );
+      if (validRequired.length === 0) {
+        delete obj.required;
+      } else {
+        obj.required = validRequired;
+      }
+    }
+
+    // Recurse into nested objects
+    for (const value of Object.values(obj)) {
+      if (value && typeof value === "object") {
+        cleanupRequired(value);
+      }
+    }
+  }
+
+  cleanupRequired(cleaned);
+
+  // Phase 5: Add placeholder for empty object schemas (Antigravity requirement)
+  function addPlaceholders(obj) {
+    if (!obj || typeof obj !== "object") return;
+
+    if (obj.type === "object") {
+      if (!obj.properties || Object.keys(obj.properties).length === 0) {
+        obj.properties = {
+          reason: {
+            type: "string",
+            description: "Brief explanation of why you are calling this tool"
+          }
+        };
+        obj.required = ["reason"];
+      }
+    }
+
+    // Recurse into nested objects
+    for (const value of Object.values(obj)) {
+      if (value && typeof value === "object") {
+        addPlaceholders(value);
+      }
+    }
+  }
+
+  addPlaceholders(cleaned);
+
+  return cleaned;
+}
+
diff --git a/open-sse/translator/formats/maxTokens.js b/open-sse/translator/formats/maxTokens.js
new file mode 100644
index 0000000..4d2cd20
--- /dev/null
+++ b/open-sse/translator/formats/maxTokens.js
@@ -0,0 +1,34 @@
+import { DEFAULT_MAX_TOKENS, DEFAULT_MIN_TOKENS } from "../../config/runtimeConfig.js";
+
+/**
+ * Adjust max_tokens based on request context
+ * @param {object} body - Request body
+ * @param {number} [ceiling=DEFAULT_MAX_TOKENS] - Upper bound for max_tokens.
+ *   Callers with model context (e.g. openai-to-claude) pass the model's real
+ *   maxOutput so high-output models (Opus 4.8 = 128000) aren't pre-clamped to
+ *   the conservative 64000 default before the model-aware step sees them.
+ * @returns {number} Adjusted max_tokens
+ */
+export function adjustMaxTokens(body, ceiling = DEFAULT_MAX_TOKENS) {
+  let maxTokens = body.max_tokens || DEFAULT_MAX_TOKENS;
+
+  // Auto-increase for tool calling to prevent truncated arguments (min never above max)
+  if (body.tools && Array.isArray(body.tools) && body.tools.length > 0) {
+    if (maxTokens < DEFAULT_MIN_TOKENS) {
+      maxTokens = DEFAULT_MIN_TOKENS;
+    }
+  }
+
+  // Ensure max_tokens > thinking.budget_tokens (Claude API requirement)
+  // Claude API requires strictly greater, so add buffer instead of using the
+  // ceiling which could equal budget_tokens when budget_tokens >= ceiling
+  if (body.thinking?.budget_tokens && maxTokens <= body.thinking.budget_tokens) {
+    maxTokens = body.thinking.budget_tokens + 1024;
+  }
+
+  // Never exceed the ceiling
+  if (maxTokens > ceiling) maxTokens = ceiling;
+
+  return maxTokens;
+}
+
diff --git a/open-sse/translator/formats/openai.js b/open-sse/translator/formats/openai.js
new file mode 100644
index 0000000..3252568
--- /dev/null
+++ b/open-sse/translator/formats/openai.js
@@ -0,0 +1,134 @@
+// OpenAI helper functions for translator
+import { ROLE, OPENAI_BLOCK, CLAUDE_BLOCK, VALID_OPENAI_CONTENT_TYPES, VALID_OPENAI_MESSAGE_TYPES } from "../schema/index.js";
+
+// Re-export valid-type lists (moved to schema/blocks.js) to keep existing importers working.
+export { VALID_OPENAI_CONTENT_TYPES, VALID_OPENAI_MESSAGE_TYPES };
+
+// Filter messages to OpenAI standard format
+// Remove: thinking, redacted_thinking, signature, and other non-OpenAI blocks
+// opts.preserveCacheControl: keep cache_control on content blocks (e.g. for DashScope/alicode)
+export function filterToOpenAIFormat(body, opts = {}) {
+  if (!body.messages || !Array.isArray(body.messages)) return body;
+  const keepCache = !!opts.preserveCacheControl;
+
+  function stripBlock(block) {
+    const { signature, cache_control, ...rest } = block;
+    return keepCache && cache_control ? { ...rest, cache_control } : rest;
+  }
+
+  body.messages = body.messages.map(msg => {
+    // Normalize developer role to system (many providers don't support developer)
+    if (msg.role === ROLE.DEVELOPER) msg = { ...msg, role: ROLE.SYSTEM };
+
+    // Keep tool messages as-is (OpenAI format)
+    if (msg.role === ROLE.TOOL) return msg;
+
+    // Keep assistant messages with tool_calls as-is
+    if (msg.role === ROLE.ASSISTANT && msg.tool_calls) return msg;
+
+    // Handle string content
+    if (typeof msg.content === "string") return msg;
+
+    // Handle array content
+    if (Array.isArray(msg.content)) {
+      const filteredContent = [];
+
+      for (const block of msg.content) {
+        // Skip thinking blocks
+        if (block.type === CLAUDE_BLOCK.THINKING || block.type === CLAUDE_BLOCK.REDACTED_THINKING) continue;
+
+        // Only keep valid OpenAI content types
+        if (VALID_OPENAI_CONTENT_TYPES.includes(block.type)) {
+          filteredContent.push(stripBlock(block));
+        } else if (block.type === CLAUDE_BLOCK.TOOL_USE) {
+          // Convert tool_use to tool_calls format (handled separately)
+          continue;
+        } else if (block.type === CLAUDE_BLOCK.TOOL_RESULT) {
+          // Keep tool_result but clean it
+          filteredContent.push(stripBlock(block));
+        }
+      }
+      
+      // If all content was filtered, add empty text
+      if (filteredContent.length === 0) {
+        filteredContent.push({ type: OPENAI_BLOCK.TEXT, text: "" });
+      }
+      
+      return { ...msg, content: filteredContent };
+    }
+    
+    return msg;
+  });
+  
+  // Filter out messages with only empty text (but NEVER filter tool messages)
+  body.messages = body.messages.filter(msg => {
+    // Always keep tool messages
+    if (msg.role === ROLE.TOOL) return true;
+    // Always keep assistant messages with tool_calls
+    if (msg.role === ROLE.ASSISTANT && msg.tool_calls) return true;
+    
+    if (typeof msg.content === "string") return msg.content.trim() !== "";
+    if (Array.isArray(msg.content)) {
+      return msg.content.some(b => 
+        (b.type === OPENAI_BLOCK.TEXT && b.text?.trim()) ||
+        b.type !== OPENAI_BLOCK.TEXT
+      );
+    }
+    return true;
+  });
+
+  // Remove empty tools array (some providers like QWEN reject it)
+  if (body.tools && Array.isArray(body.tools) && body.tools.length === 0) {
+    delete body.tools;
+  }
+
+  // Normalize tools to OpenAI format (from Claude, Gemini, etc.)
+  if (body.tools && Array.isArray(body.tools) && body.tools.length > 0) {
+    body.tools = body.tools.map(tool => {
+      // Already OpenAI format
+      if (tool.type === OPENAI_BLOCK.FUNCTION && tool.function) return tool;
+      
+      // Claude format: {name, description, input_schema}
+      if (tool.name && (tool.input_schema || tool.description)) {
+        return {
+          type: OPENAI_BLOCK.FUNCTION,
+          function: {
+            name: tool.name,
+            description: String(tool.description || ""),
+            parameters: tool.input_schema || { type: "object", properties: {} }
+          }
+        };
+      }
+      
+      // Gemini format: {functionDeclarations: [{name, description, parameters}]}
+      if (tool.functionDeclarations && Array.isArray(tool.functionDeclarations)) {
+        return tool.functionDeclarations.map(fn => ({
+          type: OPENAI_BLOCK.FUNCTION,
+          function: {
+            name: fn.name,
+            description: String(fn.description || ""),
+            parameters: fn.parameters || { type: "object", properties: {} }
+          }
+        }));
+      }
+      
+      return tool;
+    }).flat();
+  }
+
+  // Normalize tool_choice to OpenAI format
+  if (body.tool_choice && typeof body.tool_choice === "object") {
+    const choice = body.tool_choice;
+    // Claude format: {type: "auto|any|tool", name?: "..."}
+    if (choice.type === "auto") {
+      body.tool_choice = "auto";
+    } else if (choice.type === "any") {
+      body.tool_choice = "required";
+    } else if (choice.type === "tool" && choice.name) {
+      body.tool_choice = { type: OPENAI_BLOCK.FUNCTION, function: { name: choice.name } };
+    }
+  }
+
+  return body;
+}
+
diff --git a/open-sse/translator/formats/responsesApi.js b/open-sse/translator/formats/responsesApi.js
new file mode 100644
index 0000000..c41ee47
--- /dev/null
+++ b/open-sse/translator/formats/responsesApi.js
@@ -0,0 +1,141 @@
+import { ROLE, OPENAI_BLOCK, RESPONSES_ITEM } from "../schema/index.js";
+
+/**
+ * Normalize Responses API input to array format.
+ * Accepts string or array, returns array of message items.
+ * An empty array is treated like an empty string — providers require at least one user
+ * message, so we inject a placeholder rather than forwarding an empty messages[].
+ * @param {string|Array} input - raw input from Responses API body
+ * @returns {Array|null} normalized array or null if invalid
+ */
+export function normalizeResponsesInput(input) {
+  if (typeof input === "string") {
+    const text = input.trim() === "" ? "..." : input;
+    return [{ type: RESPONSES_ITEM.MESSAGE, role: ROLE.USER, content: [{ type: RESPONSES_ITEM.INPUT_TEXT, text }] }];
+  }
+  if (Array.isArray(input)) {
+    // Empty input[] would produce messages:[] which all providers reject (#389)
+    if (input.length === 0) {
+      return [{ type: RESPONSES_ITEM.MESSAGE, role: ROLE.USER, content: [{ type: RESPONSES_ITEM.INPUT_TEXT, text: "..." }] }];
+    }
+    return input;
+  }
+  return null;
+}
+
+/**
+ * Convert OpenAI Responses API format to standard chat completions format
+ * Responses API uses: { input: [...], instructions: "..." }
+ * Chat API uses: { messages: [...] }
+ */
+export function convertResponsesApiFormat(body) {
+  if (!body.input) return body;
+
+  const result = { ...body };
+  result.messages = [];
+
+  // Convert instructions to system message
+  if (body.instructions) {
+    result.messages.push({ role: ROLE.SYSTEM, content: body.instructions });
+  }
+
+  // Group items by conversation turn
+  let currentAssistantMsg = null;
+  let pendingToolCalls = [];
+  let pendingToolResults = [];
+
+  const inputItems = normalizeResponsesInput(body.input);
+  if (!inputItems) return body;
+
+  for (const item of inputItems) {
+    // Determine item type - Droid CLI sends role-based items without 'type' field
+    // Fallback: if no type but has role property, treat as message
+    const itemType = item.type || (item.role ? RESPONSES_ITEM.MESSAGE : null);
+
+    if (itemType === RESPONSES_ITEM.MESSAGE) {
+      // Flush any pending assistant message with tool calls
+      if (currentAssistantMsg) {
+        result.messages.push(currentAssistantMsg);
+        currentAssistantMsg = null;
+      }
+      // Flush pending tool results
+      if (pendingToolResults.length > 0) {
+        for (const tr of pendingToolResults) {
+          result.messages.push(tr);
+        }
+        pendingToolResults = [];
+      }
+
+      // Convert content: input_text → text, output_text → text, input_image → image_url
+      const content = Array.isArray(item.content)
+        ? item.content.map(c => {
+          if (c.type === RESPONSES_ITEM.INPUT_TEXT) return { type: OPENAI_BLOCK.TEXT, text: c.text };
+          if (c.type === RESPONSES_ITEM.OUTPUT_TEXT) return { type: OPENAI_BLOCK.TEXT, text: c.text };
+          if (c.type === RESPONSES_ITEM.INPUT_IMAGE) {
+            const url = c.image_url || c.file_id || "";
+            return { type: OPENAI_BLOCK.IMAGE_URL, image_url: { url, detail: c.detail || "auto" } };
+          }
+          return c;
+        })
+        : item.content;
+      result.messages.push({ role: item.role, content });
+    }
+    else if (itemType === RESPONSES_ITEM.FUNCTION_CALL) {
+      // Start or append to assistant message with tool_calls
+      if (!currentAssistantMsg) {
+        currentAssistantMsg = {
+          role: ROLE.ASSISTANT,
+          content: null,
+          tool_calls: []
+        };
+      }
+      // Skip items with empty/missing name — upstream APIs reject nameless tool calls (#444)
+      if (!item.name || typeof item.name !== "string" || item.name.trim() === "") continue;
+      currentAssistantMsg.tool_calls.push({
+        id: item.call_id,
+        type: OPENAI_BLOCK.FUNCTION,
+        function: {
+          name: item.name,
+          arguments: item.arguments
+        }
+      });
+    }
+    else if (itemType === RESPONSES_ITEM.FUNCTION_CALL_OUTPUT) {
+      // Flush assistant message first if exists
+      if (currentAssistantMsg) {
+        result.messages.push(currentAssistantMsg);
+        currentAssistantMsg = null;
+      }
+      // Add tool result
+      pendingToolResults.push({
+        role: ROLE.TOOL,
+        tool_call_id: item.call_id,
+        content: typeof item.output === "string" ? item.output : JSON.stringify(item.output)
+      });
+    }
+    else if (itemType === RESPONSES_ITEM.REASONING) {
+      // Skip reasoning items - they are for display only
+      continue;
+    }
+  }
+
+  // Flush remaining
+  if (currentAssistantMsg) {
+    result.messages.push(currentAssistantMsg);
+  }
+  if (pendingToolResults.length > 0) {
+    for (const tr of pendingToolResults) {
+      result.messages.push(tr);
+    }
+  }
+
+  // Cleanup Responses API specific fields
+  delete result.input;
+  delete result.instructions;
+  delete result.include;
+  delete result.prompt_cache_key;
+  delete result.store;
+  delete result.reasoning;
+
+  return result;
+}
diff --git a/open-sse/translator/index.js b/open-sse/translator/index.js
new file mode 100644
index 0000000..e9c8497
--- /dev/null
+++ b/open-sse/translator/index.js
@@ -0,0 +1,284 @@
+import { FORMATS } from "./formats.js";
+import { ensureToolCallIds, fixMissingToolResponses } from "./concerns/toolCall.js";
+import { prepareClaudeRequest } from "./formats/claude.js";
+import { cloakClaudeTools } from "../utils/claudeCloaking.js";
+import { filterToOpenAIFormat } from "./formats/openai.js";
+import { normalizeThinkingConfig } from "../services/provider.js";
+import { applyThinking, captureThinking } from "./concerns/thinkingUnified.js";
+import { captureSessionId } from "../utils/sessionManager.js";
+import { AntigravityExecutor } from "../executors/antigravity.js";
+import { PROVIDERS } from "../providers/index.js";
+
+// Registry for translators. Lazy-init guards against circular-import order:
+// translator modules call register() (side-effect) before this module's body runs.
+// var (not let): hoisted as undefined so register() can run during circular import (no TDZ).
+var requestRegistry;
+var responseRegistry;
+
+// Register translator
+export function register(from, to, requestFn, responseFn) {
+  requestRegistry ??= new Map();
+  responseRegistry ??= new Map();
+  const key = `${from}:${to}`;
+  if (requestFn) {
+    requestRegistry.set(key, requestFn);
+  }
+  if (responseFn) {
+    responseRegistry.set(key, responseFn);
+  }
+}
+
+// No-op: translators self-register via the static imports at the bottom of this file.
+function ensureInitialized() {}
+
+// Strip specific content types from messages (explicit opt-in via strip[] in PROVIDER_MODELS)
+function stripContentTypes(body, stripList = []) {
+  if (!stripList.length || !body.messages || !Array.isArray(body.messages)) return;
+  const imageTypes = new Set(["image_url", "image"]);
+  const audioTypes = new Set(["audio_url", "input_audio"]);
+  const shouldStrip = (type) => {
+    if (imageTypes.has(type)) return stripList.includes("image");
+    if (audioTypes.has(type)) return stripList.includes("audio");
+    return false;
+  };
+  for (const msg of body.messages) {
+    if (!Array.isArray(msg.content)) continue;
+    msg.content = msg.content.filter(part => !shouldStrip(part.type));
+    if (msg.content.length === 0) msg.content = "";
+  }
+}
+
+// Translate request: source -> openai -> target
+export function translateRequest(sourceFormat, targetFormat, model, body, stream = true, credentials = null, provider = null, reqLogger = null, stripList = [], connectionId = null, clientTool = null) {
+  ensureInitialized();
+  let result = body;
+
+  // Strip explicit content types (opt-in via strip[] in PROVIDER_MODELS entry)
+  stripContentTypes(result, stripList);
+
+  // Normalize thinking config: remove if lastMessage is not user
+  normalizeThinkingConfig(result);
+
+  // Always ensure tool_calls have id (some providers require it)
+  ensureToolCallIds(result);
+  
+  // Fix missing tool responses (insert empty tool_result if needed)
+  fixMissingToolResponses(result);
+
+  // Capture thinking intent from the original (pre-translation) body, before any
+  // format conversion strips/renames the fields. Applied after translation.
+  const thinkingIntent = captureThinking(result);
+
+  // Capture session id from the original body (envelope still intact, e.g. antigravity request.sessionId)
+  const clientSessionId = captureSessionId(result, credentials, connectionId, targetFormat);
+  // Expose to downstream translators (gemini-cli/antigravity envelopes) that run after envelope is stripped
+  if (credentials) credentials._clientSessionId = clientSessionId;
+
+  // If same format, skip translation steps
+  if (sourceFormat !== targetFormat) {
+    // Direct route: if a translator is registered for this exact source:target
+    // pair, use it instead of pivoting through OpenAI. This is lossless for
+    // pairs like claude:kiro (avoids the claude->openai->kiro double-hop).
+    const directFn = requestRegistry.get(`${sourceFormat}:${targetFormat}`);
+    if (directFn) {
+      result = directFn(model, result, stream, credentials);
+    } else {
+      // Step 1: source -> openai (if source is not openai)
+      if (sourceFormat !== FORMATS.OPENAI) {
+        const toOpenAI = requestRegistry.get(`${sourceFormat}:${FORMATS.OPENAI}`);
+        if (toOpenAI) {
+          result = toOpenAI(model, result, stream, credentials);
+          // Log OpenAI intermediate format
+          reqLogger?.logOpenAIRequest?.(result);
+        }
+      }
+
+      // Step 2: openai -> target (if target is not openai)
+      if (targetFormat !== FORMATS.OPENAI) {
+        const fromOpenAI = requestRegistry.get(`${FORMATS.OPENAI}:${targetFormat}`);
+        if (fromOpenAI) {
+          result = fromOpenAI(model, result, stream, credentials);
+        }
+      }
+    }
+  }
+
+  // Normalize thinking to the target provider-native format (config-driven, capability-aware)
+  applyThinking(targetFormat, model, result, provider, thinkingIntent);
+
+  // Always normalize to clean OpenAI format when target is OpenAI
+  // This handles hybrid requests (e.g., OpenAI messages + Claude tools)
+  if (targetFormat === FORMATS.OPENAI) {
+    result = filterToOpenAIFormat(result, {
+      preserveCacheControl: !!PROVIDERS[provider]?.quirks?.preserveCacheControl,
+    });
+  }
+
+  // Final step: prepare request for Claude format endpoints
+  if (targetFormat === FORMATS.CLAUDE) {
+    const apiKey = credentials?.accessToken || credentials?.apiKey || null;
+    result = prepareClaudeRequest(result, provider, apiKey, connectionId, credentials?.rawHeaders, clientSessionId);
+  }
+
+  // Claude cloaking: rename client tools with _cc suffix (anti-ban)
+  // quirk: only providers flagged cloakToolsOnOAuth, and only with an OAuth token
+  if (PROVIDERS[provider]?.quirks?.cloakToolsOnOAuth) {
+    const apiKey = credentials?.accessToken || credentials?.apiKey || null;
+    if (apiKey?.includes("sk-ant-oat")) {
+      const { body: cloakedBody, toolNameMap } = cloakClaudeTools(result);
+      result = cloakedBody;
+      if (toolNameMap?.size > 0) {
+        result._toolNameMap = toolNameMap;
+      }
+    }
+  }
+
+  // Antigravity cloaking disabled
+  // if (provider === FORMATS.ANTIGRAVITY && body.userAgent !== FORMATS.ANTIGRAVITY) {
+  //   const { cloakedBody, toolNameMap } = AntigravityExecutor.cloakTools(result);
+  //   result = cloakedBody;
+  //   if (toolNameMap?.size > 0) {
+  //     result._toolNameMap = toolNameMap;
+  //   }
+  // }
+
+  return result;
+}
+
+// Translate response chunk: target -> openai -> source
+export function translateResponse(targetFormat, sourceFormat, chunk, state) {
+  ensureInitialized();
+  // If same format, return as-is
+  if (sourceFormat === targetFormat) {
+    return [chunk];
+  }
+
+  let results = [chunk];
+  let openaiResults = null; // Store OpenAI intermediate results
+
+  // Direct route: if a response translator is registered for this exact
+  // target:source pair, use it instead of pivoting through OpenAI. Mirrors the
+  // request-side direct route (e.g. kiro:claude — KiroExecutor already emits
+  // OpenAI-shaped chunks, so this converts them straight to Claude SSE).
+  const directFn = responseRegistry.get(`${targetFormat}:${sourceFormat}`);
+  if (directFn) {
+    const converted = directFn(chunk, state);
+    return converted ? (Array.isArray(converted) ? converted : [converted]) : [];
+  }
+
+  // Step 1: target -> openai (if target is not openai)
+  if (targetFormat !== FORMATS.OPENAI) {
+    const toOpenAI = responseRegistry.get(`${targetFormat}:${FORMATS.OPENAI}`);
+    if (toOpenAI) {
+      results = [];
+      const converted = toOpenAI(chunk, state);
+      if (converted) {
+        results = Array.isArray(converted) ? converted : [converted];
+        openaiResults = results; // Store OpenAI intermediate
+      }
+    }
+  }
+
+  // Step 2: openai -> source (if source is not openai)
+  if (sourceFormat !== FORMATS.OPENAI) {
+    const fromOpenAI = responseRegistry.get(`${FORMATS.OPENAI}:${sourceFormat}`);
+    if (fromOpenAI) {
+      const finalResults = [];
+      for (const r of results) {
+        const converted = fromOpenAI(r, state);
+        if (converted) {
+          finalResults.push(...(Array.isArray(converted) ? converted : [converted]));
+        }
+      }
+      results = finalResults;
+    }
+  }
+
+  // Attach OpenAI intermediate results for logging
+  if (openaiResults && sourceFormat !== FORMATS.OPENAI && targetFormat !== FORMATS.OPENAI) {
+    results._openaiIntermediate = openaiResults;
+  }
+
+  return results;
+}
+
+// Check if translation needed
+export function needsTranslation(sourceFormat, targetFormat) {
+  return sourceFormat !== targetFormat;
+}
+
+// Initialize state for streaming response based on format
+export function initState(sourceFormat) {
+  // Base state for all formats
+  const base = {
+    messageId: null,
+    model: null,
+    textBlockStarted: false,
+    thinkingBlockStarted: false,
+    inThinkingBlock: false,
+    currentBlockIndex: null,
+    toolCalls: new Map(),
+    finishReason: null,
+    finishReasonSent: false,
+    usage: null,
+    contentBlockIndex: -1
+  };
+
+  // Add openai-responses specific fields
+  if (sourceFormat === FORMATS.OPENAI_RESPONSES) {
+    return {
+      ...base,
+      seq: 0,
+      responseId: `resp_${Date.now()}`,
+      created: Math.floor(Date.now() / 1000),
+      started: false,
+      msgTextBuf: {},
+      msgItemAdded: {},
+      msgContentAdded: {},
+      msgItemDone: {},
+      reasoningId: "",
+      reasoningIndex: -1,
+      reasoningBuf: "",
+      reasoningPartAdded: false,
+      reasoningDone: false,
+      inThinking: false,
+      funcArgsBuf: {},
+      funcNames: {},
+      funcCallIds: {},
+      funcArgsDone: {},
+      funcItemDone: {},
+      completedSent: false
+    };
+  }
+
+  return base;
+}
+
+// Kept for backward compatibility; translators are already registered at import time.
+export function initTranslators() {
+  ensureInitialized();
+}
+
+// Static side-effect imports: each module calls register() at load (works in ESM + bundler).
+import "./request/claude-to-openai.js";
+import "./request/openai-to-claude.js";
+import "./request/gemini-to-openai.js";
+import "./request/openai-to-gemini.js";
+import "./request/openai-to-vertex.js";
+import "./request/antigravity-to-openai.js";
+import "./request/openai-responses.js";
+import "./request/openai-to-kiro.js";
+import "./request/openai-to-cursor.js";
+import "./request/openai-to-ollama.js";
+import "./request/openai-to-commandcode.js";
+import "./request/claude-to-kiro.js";
+import "./response/claude-to-openai.js";
+import "./response/openai-to-claude.js";
+import "./response/gemini-to-openai.js";
+import "./response/openai-to-antigravity.js";
+import "./response/openai-responses.js";
+import "./response/kiro-to-openai.js";
+import "./response/cursor-to-openai.js";
+import "./response/ollama-to-openai.js";
+import "./response/commandcode-to-openai.js";
+import "./response/kiro-to-claude.js";
diff --git a/open-sse/translator/request/antigravity-to-openai.js b/open-sse/translator/request/antigravity-to-openai.js
new file mode 100644
index 0000000..374bb54
--- /dev/null
+++ b/open-sse/translator/request/antigravity-to-openai.js
@@ -0,0 +1,242 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { adjustMaxTokens } from "../formats/maxTokens.js";
+import { encodeDataUri } from "../concerns/image.js";
+import { ROLE, GEMINI_ROLE, OPENAI_BLOCK } from "../schema/index.js";
+import { budgetToEffort } from "../concerns/thinking.js";
+import { collapseTextParts } from "../concerns/message.js";
+
+// Convert Antigravity request to OpenAI format
+// Antigravity body: { project, model, userAgent, requestType, requestId, request: { contents, systemInstruction, tools, toolConfig, generationConfig, sessionId } }
+export function antigravityToOpenAIRequest(model, body, stream) {
+  const req = body.request || body;
+  const result = {
+    model: model,
+    messages: [],
+    stream: stream
+  };
+
+  // Generation config
+  if (req.generationConfig) {
+    const config = req.generationConfig;
+    if (config.maxOutputTokens) {
+      const tempBody = { max_tokens: config.maxOutputTokens, tools: req.tools };
+      result.max_tokens = adjustMaxTokens(tempBody);
+    }
+    if (config.temperature !== undefined) {
+      result.temperature = config.temperature;
+    }
+    if (config.topP !== undefined) {
+      result.top_p = config.topP;
+    }
+    if (config.topK !== undefined) {
+      result.top_k = config.topK;
+    }
+
+    // Thinking config → reasoning_effort
+    if (config.thinkingConfig) {
+      const effort = budgetToEffort(config.thinkingConfig.thinkingBudget || 0);
+      if (effort) result.reasoning_effort = effort;
+    }
+  }
+
+  // System instruction
+  if (req.systemInstruction) {
+    const systemText = extractText(req.systemInstruction);
+    if (systemText) {
+      result.messages.push({ role: ROLE.SYSTEM, content: systemText });
+    }
+  }
+
+  // Convert contents to messages
+  if (req.contents && Array.isArray(req.contents)) {
+    for (const content of req.contents) {
+      const converted = convertContent(content);
+      if (converted) {
+        if (Array.isArray(converted)) {
+          result.messages.push(...converted);
+        } else {
+          result.messages.push(converted);
+        }
+      }
+    }
+  }
+
+  // Tools
+  if (req.tools && Array.isArray(req.tools)) {
+    result.tools = [];
+    for (const tool of req.tools) {
+      if (tool.functionDeclarations) {
+        for (const func of tool.functionDeclarations) {
+          result.tools.push({
+            type: OPENAI_BLOCK.FUNCTION,
+            function: {
+              name: func.name,
+              description: func.description || "",
+              parameters: normalizeSchemaTypes(func.parameters) || { type: "object", properties: {} }
+            }
+          });
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+// Recursively convert Antigravity schema types (OBJECT, STRING, etc.) to lowercase
+// and strip unsupported fields like enumDescriptions
+function normalizeSchemaTypes(schema) {
+  if (!schema || typeof schema !== "object") return schema;
+
+  const result = Array.isArray(schema) ? [...schema] : { ...schema };
+
+
+  if (typeof result.type === "string") {
+    result.type = result.type.toLowerCase();
+  }
+
+  // Strip enumDescriptions — not supported by upstream APIs
+  delete result.enumDescriptions;
+
+
+  if (result.properties) {
+    const normalized = {};
+    for (const [key, val] of Object.entries(result.properties)) {
+      normalized[key] = normalizeSchemaTypes(val);
+    }
+    result.properties = normalized;
+  }
+
+  if (result.items) {
+    result.items = normalizeSchemaTypes(result.items);
+  }
+
+  return result;
+}
+
+// Convert Antigravity content to OpenAI message
+// Handles: text, thought, thoughtSignature, functionCall, functionResponse, inlineData
+function convertContent(content) {
+  const role = content.role === GEMINI_ROLE.MODEL ? ROLE.ASSISTANT : content.role === GEMINI_ROLE.USER ? ROLE.USER : content.role;
+
+  if (!content.parts || !Array.isArray(content.parts)) {
+    return null;
+  }
+
+  const textParts = [];
+  const toolCalls = [];
+  const toolResults = [];
+  let reasoningContent = "";
+
+  for (const part of content.parts) {
+    // Thinking content (thought: true)
+    if (part.thought === true && part.text) {
+      reasoningContent += part.text;
+      continue;
+    }
+
+    // Text with thoughtSignature = regular text after thinking
+    if (part.thoughtSignature && part.text !== undefined) {
+      if (part.text) {
+        textParts.push({ type: OPENAI_BLOCK.TEXT, text: part.text });
+      }
+      continue;
+    }
+
+    // Regular text
+    if (part.text !== undefined && part.text !== "") {
+      textParts.push({ type: OPENAI_BLOCK.TEXT, text: part.text });
+    }
+
+    // Inline data (images)
+    if (part.inlineData) {
+      textParts.push({
+        type: OPENAI_BLOCK.IMAGE_URL,
+        image_url: {
+          url: encodeDataUri(part.inlineData.mimeType, part.inlineData.data)
+        }
+      });
+    }
+
+    // Function call
+    if (part.functionCall) {
+      toolCalls.push({
+        // Deterministic id from name so the matching functionResponse pairs correctly.
+        id: part.functionCall.id || `call_${part.functionCall.name}`,
+        type: OPENAI_BLOCK.FUNCTION,
+        function: {
+          name: part.functionCall.name,
+          arguments: JSON.stringify(part.functionCall.args || {})
+        }
+      });
+    }
+
+    // Function response → collect all, each becomes a separate tool message
+    if (part.functionResponse) {
+      toolResults.push({
+        role: ROLE.TOOL,
+        tool_call_id: part.functionResponse.id || `call_${part.functionResponse.name}`,
+        content: JSON.stringify(part.functionResponse.response?.result || part.functionResponse.response || {})
+      });
+    }
+  }
+
+  // Content with functionResponses — return array of tool result messages,
+  // plus an assistant message for any co-located tool calls / text.
+  if (toolResults.length > 0) {
+    if (toolCalls.length > 0 || textParts.length > 0 || reasoningContent) {
+      const assistantMsg = { role: ROLE.ASSISTANT };
+      if (textParts.length > 0) {
+        assistantMsg.content = collapseTextParts(textParts);
+      }
+      if (reasoningContent) {
+        assistantMsg.reasoning_content = reasoningContent;
+      }
+      if (toolCalls.length > 0) {
+        assistantMsg.tool_calls = toolCalls;
+      }
+      return [...toolResults, assistantMsg];
+    }
+    return toolResults;
+  }
+
+  // Assistant with tool calls
+  if (toolCalls.length > 0) {
+    const msg = { role: ROLE.ASSISTANT };
+    if (textParts.length > 0) {
+      msg.content = collapseTextParts(textParts);
+    }
+    if (reasoningContent) {
+      msg.reasoning_content = reasoningContent;
+    }
+    msg.tool_calls = toolCalls;
+    return msg;
+  }
+
+  // Regular message
+  if (textParts.length > 0 || reasoningContent) {
+    const msg = { role };
+    if (textParts.length > 0) {
+      msg.content = collapseTextParts(textParts);
+    }
+    if (reasoningContent) {
+      msg.reasoning_content = reasoningContent;
+    }
+    return msg;
+  }
+
+  return null;
+}
+
+// Extract text from systemInstruction
+function extractText(instruction) {
+  if (typeof instruction === "string") return instruction;
+  if (instruction.parts && Array.isArray(instruction.parts)) {
+    return instruction.parts.map(p => p.text || "").join("");
+  }
+  return "";
+}
+
+// Register
+register(FORMATS.ANTIGRAVITY, FORMATS.OPENAI, antigravityToOpenAIRequest, null);
diff --git a/open-sse/translator/request/claude-to-kiro.js b/open-sse/translator/request/claude-to-kiro.js
new file mode 100644
index 0000000..c42823b
--- /dev/null
+++ b/open-sse/translator/request/claude-to-kiro.js
@@ -0,0 +1,478 @@
+/**
+ * Claude → Kiro Request Translator (DIRECT route, no OpenAI pivot)
+ *
+ * Converts Anthropic Messages API requests straight to Kiro / AWS
+ * CodeWhisperer `GenerateAssistantResponse` payloads. This is the function the
+ * direct `claude:kiro` route in ../index.js uses; it is NOT reached through the
+ * claude→openai→kiro pivot.
+ *
+ * It reproduces the two 400-guards that live in openai-to-kiro.js so that a
+ * Claude client which omits the `tools` array on a follow-up turn (typical
+ * after client-side compaction) does not trip Kiro's schema validator and get
+ * "Improperly formed request" (HTTP 400):
+ *
+ *   1. flattenClaudeToolInteractions — when the client sent NO tools, collapse
+ *      every tool_use / tool_result block to plain text so no structured tool
+ *      reference survives to trigger the "tools required" rule.
+ *   2. reconcileOrphanedToolResults — when tools ARE present, fold any
+ *      tool_result whose tool_use_id has no matching tool_use back into the
+ *      user text instead of leaving a dangling structured reference.
+ *
+ * It also handles the 9router-synthetic `-agentic` / `-thinking` suffixes and
+ * the `<thinking_mode>enabled</thinking_mode>` reasoning trigger, matching
+ * buildKiroPayload.
+ */
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { v4 as uuidv4 } from "uuid";
+import {
+  resolveKiroModel,
+  resolveKiroThinkingBudget,
+  buildThinkingSystemPrefix,
+  KIRO_AGENTIC_SYSTEM_PROMPT,
+  resolveDefaultProfileArn,
+} from "../../config/kiroConstants.js";
+import { DEFAULT_IMAGE_MIME } from "../schema/index.js";
+import { ROLE, CLAUDE_BLOCK } from "../schema/index.js";
+
+/** Stringify a tool_use input as a readable line. */
+function toolUseToText(name, input) {
+  let argStr;
+  try {
+    argStr = typeof input === "string" ? input : JSON.stringify(input ?? {});
+  } catch {
+    argStr = "{}";
+  }
+  return `[Tool call: ${name || "unknown"}(${argStr})]`;
+}
+
+/** Render a Claude tool_result block's content as a readable line. */
+function toolResultBlockToText(content) {
+  let text = "";
+  if (typeof content === "string") {
+    text = content;
+  } else if (Array.isArray(content)) {
+    text = content
+      .map((c) => (typeof c === "string" ? c : c?.text || ""))
+      .filter(Boolean)
+      .join("\n");
+  } else if (content) {
+    try {
+      text = JSON.stringify(content);
+    } catch {
+      text = "";
+    }
+  }
+  return `[Tool result: ${text}]`;
+}
+
+/**
+ * When the client sent no tools, rewrite every tool_use (assistant) and
+ * tool_result (user) content block into plain text. Keeps text + images.
+ * Returns a new messages array; never mutates the input.
+ */
+function flattenClaudeToolInteractions(messages) {
+  const out = [];
+  for (const msg of messages) {
+    if (!msg) continue;
+
+    if (msg.role === ROLE.ASSISTANT && Array.isArray(msg.content)) {
+      const parts = [];
+      for (const block of msg.content) {
+        if (block.type === CLAUDE_BLOCK.TEXT && block.text) {
+          parts.push(block.text);
+        } else if (block.type === CLAUDE_BLOCK.TOOL_USE) {
+          parts.push(toolUseToText(block.name, block.input));
+        }
+      }
+      out.push({ ...msg, content: parts.join("\n") });
+      continue;
+    }
+
+    if (msg.role === ROLE.USER && Array.isArray(msg.content)) {
+      const newContent = msg.content.map((block) =>
+        block.type === CLAUDE_BLOCK.TOOL_RESULT
+          ? { type: CLAUDE_BLOCK.TEXT, text: toolResultBlockToText(block.content) }
+          : block
+      );
+      out.push({ ...msg, content: newContent });
+      continue;
+    }
+
+    out.push(msg);
+  }
+  return out;
+}
+
+/**
+ * Convert Claude messages to Kiro history + currentMessage.
+ * Kiro requires alternating user/assistant turns; consecutive same-role
+ * messages are merged.
+ */
+function convertClaudeMessagesToKiro(messages, tools, model) {
+  const history = [];
+  let currentMessage = null;
+
+  let pendingUserContent = [];
+  let pendingAssistantContent = [];
+  let pendingToolResults = [];
+  let pendingImages = [];
+  let currentRole = null;
+  let toolsInjected = false;
+
+  const clientProvidedTools = Array.isArray(tools) && tools.length > 0;
+
+  const buildToolSpecs = () =>
+    tools.map((t) => {
+      const name = t.name;
+      const description = t.description || `Tool: ${name}`;
+      const schema = t.input_schema || {};
+      const normalizedSchema =
+        Object.keys(schema).length === 0
+          ? { type: "object", properties: {}, required: [] }
+          : { ...schema, required: schema.required ?? [] };
+      return {
+        toolSpecification: {
+          name,
+          description,
+          inputSchema: { json: normalizedSchema },
+        },
+      };
+    });
+
+  const flushPending = () => {
+    if (currentRole === ROLE.USER) {
+      const content = pendingUserContent.join("\n\n").trim() || "continue";
+      const userMsg = { userInputMessage: { content, modelId: model } };
+
+      if (pendingImages.length > 0) {
+        userMsg.userInputMessage.images = pendingImages;
+      }
+      if (pendingToolResults.length > 0) {
+        userMsg.userInputMessage.userInputMessageContext = {
+          toolResults: pendingToolResults,
+        };
+      }
+      // Attach tools to the first user turn only.
+      if (clientProvidedTools && !toolsInjected) {
+        if (!userMsg.userInputMessage.userInputMessageContext) {
+          userMsg.userInputMessage.userInputMessageContext = {};
+        }
+        userMsg.userInputMessage.userInputMessageContext.tools = buildToolSpecs();
+        toolsInjected = true;
+      }
+
+      history.push(userMsg);
+      currentMessage = userMsg;
+      pendingUserContent = [];
+      pendingToolResults = [];
+      pendingImages = [];
+    } else if (currentRole === ROLE.ASSISTANT) {
+      const content = pendingAssistantContent.join("\n\n").trim() || "...";
+      history.push({ assistantResponseMessage: { content } });
+      pendingAssistantContent = [];
+    }
+  };
+
+  for (const msg of messages) {
+    const role = msg.role;
+    if (role !== currentRole && currentRole !== null) flushPending();
+    currentRole = role;
+
+    if (role === ROLE.USER) {
+      if (typeof msg.content === "string") {
+        pendingUserContent.push(msg.content);
+      } else if (Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+          if (block.type === CLAUDE_BLOCK.TEXT) {
+            pendingUserContent.push(block.text);
+          } else if (block.type === CLAUDE_BLOCK.IMAGE && block.source?.type === "base64") {
+            const mediaType = block.source.media_type || DEFAULT_IMAGE_MIME;
+            const format = mediaType.split("/")[1] || mediaType;
+            pendingImages.push({ format, source: { bytes: block.source.data } });
+          } else if (block.type === CLAUDE_BLOCK.TOOL_RESULT) {
+            let resultContent = "";
+            if (typeof block.content === "string") {
+              resultContent = block.content;
+            } else if (Array.isArray(block.content)) {
+              resultContent =
+                block.content
+                  .filter((c) => c.type === CLAUDE_BLOCK.TEXT)
+                  .map((c) => c.text)
+                  .join("\n") || JSON.stringify(block.content);
+            } else if (block.content) {
+              resultContent = JSON.stringify(block.content);
+            }
+            pendingToolResults.push({
+              toolUseId: block.tool_use_id,
+              status: "success",
+              content: [{ text: resultContent }],
+            });
+          }
+        }
+      }
+    } else if (role === ROLE.ASSISTANT) {
+      let textContent = "";
+      const toolUses = [];
+      if (typeof msg.content === "string") {
+        textContent = msg.content;
+      } else if (Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+          if (block.type === CLAUDE_BLOCK.TEXT) {
+            textContent += block.text;
+          } else if (block.type === CLAUDE_BLOCK.TOOL_USE) {
+            toolUses.push({
+              toolUseId: block.id,
+              name: block.name,
+              input: block.input || {},
+            });
+          }
+        }
+      }
+      if (textContent) pendingAssistantContent.push(textContent);
+
+      if (toolUses.length > 0) {
+        flushPending();
+        const lastMsg = history[history.length - 1];
+        if (lastMsg?.assistantResponseMessage) {
+          lastMsg.assistantResponseMessage.toolUses = toolUses;
+        }
+        currentRole = null;
+      }
+    }
+  }
+
+  if (currentRole !== null) flushPending();
+
+  // Pop the last user turn as currentMessage (skip trailing assistant turns).
+  for (let i = history.length - 1; i >= 0; i--) {
+    if (history[i].userInputMessage) {
+      currentMessage = history.splice(i, 1)[0];
+      break;
+    }
+  }
+
+  // Grab tools from the first history user turn before cleanup strips them.
+  const firstHistoryTools =
+    history[0]?.userInputMessage?.userInputMessageContext?.tools;
+
+  history.forEach((item) => {
+    if (item.userInputMessage?.userInputMessageContext?.tools) {
+      delete item.userInputMessage.userInputMessageContext.tools;
+    }
+    if (
+      item.userInputMessage?.userInputMessageContext &&
+      Object.keys(item.userInputMessage.userInputMessageContext).length === 0
+    ) {
+      delete item.userInputMessage.userInputMessageContext;
+    }
+    if (item.userInputMessage && !item.userInputMessage.modelId) {
+      item.userInputMessage.modelId = model;
+    }
+  });
+
+  // Merge consecutive user turns (Kiro requires alternating roles).
+  const mergedHistory = [];
+  for (const current of history) {
+    const prev = mergedHistory[mergedHistory.length - 1];
+    if (current.userInputMessage && prev?.userInputMessage) {
+      prev.userInputMessage.content += "\n\n" + current.userInputMessage.content;
+      const prevCtx = prev.userInputMessage.userInputMessageContext;
+      const curCtx = current.userInputMessage.userInputMessageContext;
+      if (curCtx) {
+        if (!prevCtx) {
+          prev.userInputMessage.userInputMessageContext = curCtx;
+        } else {
+          if (curCtx.toolResults?.length > 0) {
+            prevCtx.toolResults = [
+              ...(prevCtx.toolResults || []),
+              ...curCtx.toolResults,
+            ];
+          }
+          if (curCtx.tools?.length > 0) {
+            prevCtx.tools = [...(prevCtx.tools || []), ...curCtx.tools];
+          }
+        }
+      }
+    } else {
+      mergedHistory.push(current);
+    }
+  }
+
+  if (!currentMessage) {
+    currentMessage = { userInputMessage: { content: "", modelId: model } };
+  }
+
+  // Inject tools into currentMessage after cleanup if not already present.
+  if (
+    firstHistoryTools?.length > 0 &&
+    !currentMessage.userInputMessage.userInputMessageContext?.tools
+  ) {
+    if (!currentMessage.userInputMessage.userInputMessageContext) {
+      currentMessage.userInputMessage.userInputMessageContext = {};
+    }
+    currentMessage.userInputMessage.userInputMessageContext.tools =
+      firstHistoryTools;
+  }
+
+  return { history: mergedHistory, currentMessage };
+}
+
+/**
+ * Fold orphaned toolResults (those whose toolUseId has no matching toolUse in
+ * any assistant turn) back into the user text, removing the dangling
+ * structured reference that makes Kiro 400.
+ */
+function reconcileOrphanedToolResults(history, currentMessage) {
+  const validIds = new Set();
+  for (const h of history) {
+    const arm = h.assistantResponseMessage;
+    if (!arm) continue;
+    for (const tu of arm.toolUses || []) {
+      if (tu.toolUseId) validIds.add(tu.toolUseId);
+    }
+  }
+
+  const carriers = currentMessage ? [...history, currentMessage] : history;
+  for (const item of carriers) {
+    const uim = item.userInputMessage;
+    const ctx = uim?.userInputMessageContext;
+    if (!ctx?.toolResults?.length) continue;
+
+    const kept = [];
+    const salvaged = [];
+    for (const tr of ctx.toolResults) {
+      if (validIds.has(tr.toolUseId)) {
+        kept.push(tr);
+      } else {
+        const text = Array.isArray(tr.content)
+          ? tr.content.map((c) => c?.text || "").join("\n")
+          : "";
+        salvaged.push(`[Tool result: ${text}]`);
+      }
+    }
+
+    if (salvaged.length === 0) continue;
+
+    const extra = salvaged.join("\n");
+    uim.content = uim.content ? `${uim.content}\n\n${extra}` : extra;
+    ctx.toolResults = kept;
+    if (kept.length === 0 && !ctx.tools?.length) {
+      delete uim.userInputMessageContext;
+    }
+  }
+}
+
+/**
+ * Build a Kiro payload directly from a Claude Messages API request body.
+ */
+export function claudeToKiroRequest(model, body, stream, credentials) {
+  let messages = Array.isArray(body.messages) ? body.messages : [];
+  const tools = Array.isArray(body.tools) ? body.tools : [];
+  const clientProvidedTools = tools.length > 0;
+  const maxTokens = body.max_tokens || 32000;
+  const temperature = body.temperature;
+  const topP = body.top_p;
+
+  const { upstream: upstreamModel, agentic } = resolveKiroModel(model);
+  const thinkingBudget = resolveKiroThinkingBudget(body, credentials?.rawHeaders, model);
+
+  // Guard 1: no client tools → flatten all tool interactions to text.
+  if (!clientProvidedTools) {
+    messages = flattenClaudeToolInteractions(messages);
+  }
+
+  const { history, currentMessage } = convertClaudeMessagesToKiro(
+    messages,
+    tools,
+    upstreamModel
+  );
+
+  // Guard 2: tools present → reconcile dangling tool_results.
+  if (clientProvidedTools) {
+    reconcileOrphanedToolResults(history, currentMessage);
+  }
+
+  // api_key / idc / external_idp must never use the shared default ARN (belongs
+  // to another account → 403 "bearer token invalid"); OAuth/social fall back to it.
+  const authMethod = credentials?.providerSpecificData?.authMethod;
+  const accountBoundAuth =
+    authMethod === "api_key" || authMethod === "idc" || authMethod === "external_idp";
+  const profileArn = accountBoundAuth
+    ? (credentials?.providerSpecificData?.profileArn || "")
+    : (credentials?.providerSpecificData?.profileArn || resolveDefaultProfileArn(authMethod));
+
+  let finalContent = currentMessage?.userInputMessage?.content || "";
+
+  // System prompt: pass via native systemInstruction field (Kiro/Q API supports it)
+  // and also prepend as <instructions> in user content as fallback for upstreams
+  // that don't support the native field.
+  let systemInstruction = undefined;
+  if (body.system) {
+    let systemText = "";
+    if (typeof body.system === "string") {
+      systemText = body.system;
+    } else if (Array.isArray(body.system)) {
+      systemText = body.system.map((s) => s.text || "").join("\n");
+    }
+    if (systemText) {
+      systemInstruction = systemText;
+      finalContent = `<instructions>\n${systemText}\n</instructions>\n\n${finalContent}`;
+    }
+  }
+
+  // Prefix order: thinking_mode tag, timestamp marker, then agentic prompt.
+  const timestamp = new Date().toISOString();
+  const prefixParts = [];
+  if (thinkingBudget !== null) prefixParts.push(buildThinkingSystemPrefix(thinkingBudget));
+  prefixParts.push(`[Context: Current time is ${timestamp}]`);
+  if (agentic) prefixParts.push(KIRO_AGENTIC_SYSTEM_PROMPT);
+  finalContent = `${prefixParts.join("\n\n")}\n\n${finalContent}`;
+
+  const userInputMessage = {
+    content: finalContent,
+    modelId: upstreamModel,
+    origin: "AI_EDITOR",
+    ...(currentMessage?.userInputMessage?.userInputMessageContext && {
+      userInputMessageContext:
+        currentMessage.userInputMessage.userInputMessageContext,
+    }),
+    ...(currentMessage?.userInputMessage?.images && {
+      images: currentMessage.userInputMessage.images,
+    }),
+  };
+
+  if (systemInstruction) {
+    userInputMessage.systemInstruction = systemInstruction;
+  }
+
+  const payload = {
+    conversationState: {
+      chatTriggerType: "MANUAL",
+      conversationId: uuidv4(),
+      currentMessage: {
+        userInputMessage,
+      },
+      history,
+    },
+  };
+
+  if (profileArn) payload.profileArn = profileArn;
+
+  if (maxTokens || temperature !== undefined || topP !== undefined) {
+    payload.inferenceConfig = {};
+    if (maxTokens) payload.inferenceConfig.maxTokens = maxTokens;
+    if (temperature !== undefined) payload.inferenceConfig.temperature = temperature;
+    if (topP !== undefined) payload.inferenceConfig.topP = topP;
+  }
+
+  // Non-enumerable hint so the executor can route the upstream model id.
+  Object.defineProperty(payload, "_kiroUpstreamModel", {
+    value: upstreamModel,
+    enumerable: false,
+  });
+
+  return payload;
+}
+
+register(FORMATS.CLAUDE, FORMATS.KIRO, claudeToKiroRequest, null);
diff --git a/open-sse/translator/request/claude-to-openai.js b/open-sse/translator/request/claude-to-openai.js
new file mode 100644
index 0000000..3956f82
--- /dev/null
+++ b/open-sse/translator/request/claude-to-openai.js
@@ -0,0 +1,263 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { adjustMaxTokens } from "../formats/maxTokens.js";
+import { encodeDataUri } from "../concerns/image.js";
+import { ROLE, OPENAI_BLOCK, CLAUDE_BLOCK } from "../schema/index.js";
+import { collapseTextParts } from "../concerns/message.js";
+
+function stripAnthropicBillingHeader(text) {
+  if (typeof text !== "string") return "";
+  return text.replace(/^x-anthropic-billing-header:[^\n]*(?:\r?\n)?/i, "");
+}
+
+// Convert Claude request to OpenAI format
+export function claudeToOpenAIRequest(model, body, stream) {
+  const result = {
+    model: model,
+    messages: [],
+    stream: stream
+  };
+
+  // Max tokens
+  if (body.max_tokens) {
+    result.max_tokens = adjustMaxTokens(body);
+  }
+
+  // Temperature
+  if (body.temperature !== undefined) {
+    result.temperature = body.temperature;
+  }
+
+  // System message
+  if (body.system) {
+    const systemContent = Array.isArray(body.system)
+      ? body.system.map(s => stripAnthropicBillingHeader(s.text || "")).filter(Boolean).join("\n")
+      : stripAnthropicBillingHeader(body.system);
+    
+    if (systemContent) {
+      result.messages.push({
+        role: ROLE.SYSTEM,
+        content: systemContent
+      });
+    }
+  }
+
+  // Convert messages
+  if (body.messages && Array.isArray(body.messages)) {
+    for (let i = 0; i < body.messages.length; i++) {
+      const msg = body.messages[i];
+      const converted = convertClaudeMessage(msg);
+      if (converted) {
+        // Handle array of messages (multiple tool results)
+        if (Array.isArray(converted)) {
+          result.messages.push(...converted);
+        } else {
+          result.messages.push(converted);
+        }
+      }
+    }
+  }
+
+  // Fix missing tool responses - OpenAI requires every tool_call to have a response.
+  // Local variant: scans contiguous tool replies + inserts "[No response received]"
+  // (distinct from the global immediate-next check in concerns/toolCall, runs on the openai leg).
+  fixMissingToolResponsesOpenAI(result.messages);
+
+  // Tools
+  if (body.tools && Array.isArray(body.tools)) {
+    result.tools = body.tools.map(tool => ({
+      type: OPENAI_BLOCK.FUNCTION,
+      function: {
+        name: tool.name,
+        description: String(tool.description || ""),
+        parameters: tool.input_schema || { type: "object", properties: {} }
+      }
+    }));
+  }
+
+  // Tool choice
+  if (body.tool_choice) {
+    result.tool_choice = convertToolChoice(body.tool_choice);
+  }
+
+  if (body.reasoning_effort !== undefined) {
+    result.reasoning_effort = body.reasoning_effort;
+  } else if (body.reasoning?.effort !== undefined) {
+    result.reasoning_effort = body.reasoning.effort;
+  }
+
+  if (body.reasoning !== undefined) {
+    result.reasoning = body.reasoning;
+  }
+
+  return result;
+}
+
+// Fix missing tool responses - add empty responses for tool_calls without responses
+function fixMissingToolResponsesOpenAI(messages) {
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (msg.role === ROLE.ASSISTANT && msg.tool_calls && msg.tool_calls.length > 0) {
+      const toolCallIds = msg.tool_calls.map(tc => tc.id);
+      
+      // Collect all tool response IDs that IMMEDIATELY follow this assistant message
+      const respondedIds = new Set();
+      let insertPosition = i + 1;
+      for (let j = i + 1; j < messages.length; j++) {
+        const nextMsg = messages[j];
+        if (nextMsg.role === ROLE.TOOL && nextMsg.tool_call_id) {
+          respondedIds.add(nextMsg.tool_call_id);
+          insertPosition = j + 1;
+        } else {
+          break;
+        }
+      }
+      
+      // Find missing responses and insert them
+      const missingIds = toolCallIds.filter(id => !respondedIds.has(id));
+      
+      if (missingIds.length > 0) {
+        const missingResponses = missingIds.map(id => ({
+          role: ROLE.TOOL,
+          tool_call_id: id,
+          content: "[No response received]"
+        }));
+        messages.splice(insertPosition, 0, ...missingResponses);
+        i = insertPosition + missingResponses.length - 1;
+      }
+    }
+  }
+}
+
+// Wrap mid-conversation system text so it ends as a user turn (avoids Anthropic prefill 400).
+// Uses <instructions> tags that Claude models treat as authoritative directives.
+function systemReminderText(content) {
+  const parts = Array.isArray(content)
+    ? content.filter(c => c?.type === CLAUDE_BLOCK.TEXT).map(c => c.text || "")
+    : [typeof content === "string" ? content : ""];
+  const text = parts.filter(Boolean).join("\n");
+  if (!text.trim()) return "";
+  return `<instructions>\n${text}\n</instructions>`;
+}
+
+// Convert single Claude message - returns single message or array of messages
+function convertClaudeMessage(msg) {
+  // Mid-conversation system message -> user (per Anthropic placement rules)
+  if (msg.role === ROLE.SYSTEM) {
+    const text = systemReminderText(msg.content);
+    return text ? { role: ROLE.USER, content: text } : null;
+  }
+
+  const role = msg.role === ROLE.USER || msg.role === ROLE.TOOL ? ROLE.USER : ROLE.ASSISTANT;
+  
+  // Simple string content
+  if (typeof msg.content === "string") {
+    return { role, content: msg.content };
+  }
+
+  // Array content
+  if (Array.isArray(msg.content)) {
+    const parts = [];
+    const toolCalls = [];
+    const toolResults = [];
+
+    for (const block of msg.content) {
+      switch (block.type) {
+        case CLAUDE_BLOCK.TEXT:
+          parts.push({ type: OPENAI_BLOCK.TEXT, text: block.text });
+          break;
+
+        case CLAUDE_BLOCK.IMAGE:
+          if (block.source?.type === "base64") {
+            parts.push({
+              type: OPENAI_BLOCK.IMAGE_URL,
+              image_url: {
+                url: encodeDataUri(block.source.media_type, block.source.data)
+              }
+            });
+          }
+          break;
+
+        case CLAUDE_BLOCK.TOOL_USE:
+          toolCalls.push({
+            id: block.id,
+            type: OPENAI_BLOCK.FUNCTION,
+            function: {
+              name: block.name,
+              arguments: JSON.stringify(block.input || {})
+            }
+          });
+          break;
+
+        case CLAUDE_BLOCK.TOOL_RESULT:
+          let resultContent = "";
+          if (typeof block.content === "string") {
+            resultContent = block.content;
+          } else if (Array.isArray(block.content)) {
+            resultContent = block.content
+              .filter(c => c.type === CLAUDE_BLOCK.TEXT)
+              .map(c => c.text)
+              .join("\n") || JSON.stringify(block.content);
+          } else if (block.content) {
+            resultContent = JSON.stringify(block.content);
+          }
+          
+          toolResults.push({
+            role: ROLE.TOOL,
+            tool_call_id: block.tool_use_id,
+            content: resultContent
+          });
+          break;
+      }
+    }
+
+    // If has tool results, return array of tool messages
+    if (toolResults.length > 0) {
+      if (parts.length > 0) {
+        return [...toolResults, { role: ROLE.USER, content: collapseTextParts(parts) }];
+      }
+      return toolResults;
+    }
+
+    // If has tool calls, return assistant message with tool_calls
+    if (toolCalls.length > 0) {
+      const result = { role: ROLE.ASSISTANT };
+      if (parts.length > 0) {
+        result.content = collapseTextParts(parts);
+      }
+      result.tool_calls = toolCalls;
+      return result;
+    }
+
+    // Return content
+    if (parts.length > 0) {
+      return {
+        role,
+        content: collapseTextParts(parts)
+      };
+    }
+    
+    // Empty content array
+    if (msg.content.length === 0) {
+      return { role, content: "" };
+    }
+  }
+
+  return null;
+}
+
+// Convert tool choice
+function convertToolChoice(choice) {
+  if (!choice) return "auto";
+  if (typeof choice === "string") return choice;
+  
+  switch (choice.type) {
+    case "auto": return "auto";
+    case "any": return "required";
+    case "tool": return { type: OPENAI_BLOCK.FUNCTION, function: { name: choice.name } };
+    default: return "auto";
+  }
+}
+
+// Register
+register(FORMATS.CLAUDE, FORMATS.OPENAI, claudeToOpenAIRequest, null);
diff --git a/open-sse/translator/request/gemini-to-openai.js b/open-sse/translator/request/gemini-to-openai.js
new file mode 100644
index 0000000..161ea9b
--- /dev/null
+++ b/open-sse/translator/request/gemini-to-openai.js
@@ -0,0 +1,152 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { adjustMaxTokens } from "../formats/maxTokens.js";
+import { encodeDataUri } from "../concerns/image.js";
+import { collapseTextParts } from "../concerns/message.js";
+import { ROLE, GEMINI_ROLE, OPENAI_BLOCK } from "../schema/index.js";
+
+// Convert Gemini request to OpenAI format
+export function geminiToOpenAIRequest(model, body, stream) {
+  const result = {
+    model: model,
+    messages: [],
+    stream: stream
+  };
+
+  // Generation config
+  if (body.generationConfig) {
+    const config = body.generationConfig;
+    if (config.maxOutputTokens) {
+      const tempBody = { max_tokens: config.maxOutputTokens, tools: body.tools };
+      result.max_tokens = adjustMaxTokens(tempBody);
+    }
+    if (config.temperature !== undefined) {
+      result.temperature = config.temperature;
+    }
+    if (config.topP !== undefined) {
+      result.top_p = config.topP;
+    }
+  }
+
+  // System instruction
+  if (body.systemInstruction) {
+    const systemText = extractGeminiText(body.systemInstruction);
+    if (systemText) {
+      result.messages.push({
+        role: ROLE.SYSTEM,
+        content: systemText
+      });
+    }
+  }
+
+  // Convert contents to messages
+  if (body.contents && Array.isArray(body.contents)) {
+    for (const content of body.contents) {
+      const converted = convertGeminiContent(content);
+      if (converted) {
+        result.messages.push(converted);
+      }
+    }
+  }
+
+  // Tools
+  if (body.tools && Array.isArray(body.tools)) {
+    result.tools = [];
+    for (const tool of body.tools) {
+      if (tool.functionDeclarations) {
+        for (const func of tool.functionDeclarations) {
+          result.tools.push({
+            type: OPENAI_BLOCK.FUNCTION,
+            function: {
+              name: func.name,
+              description: func.description || "",
+              parameters: func.parameters || { type: "object", properties: {} }
+            }
+          });
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+// Convert Gemini content to OpenAI message
+function convertGeminiContent(content) {
+  const role = content.role === GEMINI_ROLE.USER ? ROLE.USER : ROLE.ASSISTANT;
+  
+  if (!content.parts || !Array.isArray(content.parts)) {
+    return null;
+  }
+
+  const parts = [];
+  const toolCalls = [];
+
+  for (const part of content.parts) {
+    if (part.text !== undefined) {
+      parts.push({ type: OPENAI_BLOCK.TEXT, text: part.text });
+    }
+
+    if (part.inlineData) {
+      parts.push({
+        type: OPENAI_BLOCK.IMAGE_URL,
+        image_url: {
+          url: encodeDataUri(part.inlineData.mimeType, part.inlineData.data)
+        }
+      });
+    }
+
+    if (part.functionCall) {
+      // Gemini lacks a native call id; derive a deterministic one from the name so the
+      // matching functionResponse maps to the same tool_call_id (providers require pairing).
+      toolCalls.push({
+        id: part.functionCall.id || `call_${part.functionCall.name}`,
+        type: OPENAI_BLOCK.FUNCTION,
+        function: {
+          name: part.functionCall.name,
+          arguments: JSON.stringify(part.functionCall.args || {})
+        }
+      });
+    }
+
+    if (part.functionResponse) {
+      return {
+        role: ROLE.TOOL,
+        tool_call_id: part.functionResponse.id || `call_${part.functionResponse.name}`,
+        content: JSON.stringify(part.functionResponse.response?.result || part.functionResponse.response || {})
+      };
+    }
+  }
+
+  if (toolCalls.length > 0) {
+    const result = { role: ROLE.ASSISTANT };
+    if (parts.length > 0) {
+      result.content = parts.length === 1 ? parts[0].text : parts;
+    }
+    result.tool_calls = toolCalls;
+    return result;
+  }
+
+  if (parts.length > 0) {
+    return {
+      role,
+      content: collapseTextParts(parts)
+    };
+  }
+
+  return null;
+}
+
+// Extract text from Gemini content
+function extractGeminiText(content) {
+  if (typeof content === "string") return content;
+  if (content.parts && Array.isArray(content.parts)) {
+    return content.parts.map(p => p.text || "").join("");
+  }
+  return "";
+}
+
+// Register
+register(FORMATS.GEMINI, FORMATS.OPENAI, geminiToOpenAIRequest, null);
+register(FORMATS.GEMINI_CLI, FORMATS.OPENAI, geminiToOpenAIRequest, null);
+
diff --git a/open-sse/translator/request/openai-responses.js b/open-sse/translator/request/openai-responses.js
new file mode 100644
index 0000000..abd79a4
--- /dev/null
+++ b/open-sse/translator/request/openai-responses.js
@@ -0,0 +1,385 @@
+/**
+ * Translator: OpenAI Responses API → OpenAI Chat Completions
+ * 
+ * Responses API uses: { input: [...], instructions: "..." }
+ * Chat API uses: { messages: [...] }
+ */
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { normalizeResponsesInput } from "../formats/responsesApi.js";
+import { ROLE, OPENAI_BLOCK, RESPONSES_ITEM } from "../schema/index.js";
+
+// Responses API enforces max 64 chars on call_id (#393)
+const MAX_CALL_ID_LEN = 64;
+const clampCallId = (id) => (typeof id === "string" && id.length > MAX_CALL_ID_LEN ? id.substring(0, MAX_CALL_ID_LEN) : id);
+
+/**
+ * Convert OpenAI Responses API request to OpenAI Chat Completions format
+ */
+export function openaiResponsesToOpenAIRequest(model, body, stream, credentials) {
+  if (!body.input) return body;
+
+  const result = { ...body };
+  result.messages = [];
+
+  // Convert instructions to system message
+  if (body.instructions) {
+    result.messages.push({ role: ROLE.SYSTEM, content: body.instructions });
+  }
+
+  // Group items by conversation turn
+  let currentAssistantMsg = null;
+  let pendingToolResults = [];
+  let pendingReasoning = "";
+  let pendingReasoningEncrypted = "";
+
+  const inputItems = normalizeResponsesInput(body.input);
+  if (!inputItems) return body;
+
+  // Extract reasoning text from summary[].text (encrypted_content is continuity-only)
+  const extractReasoningText = (item) => {
+    if (Array.isArray(item.summary)) {
+      const txt = item.summary.map(s => s?.text || "").filter(Boolean).join("\n");
+      if (txt) return txt;
+    }
+    if (Array.isArray(item.content)) {
+      const txt = item.content.map(c => c?.text || "").filter(Boolean).join("\n");
+      if (txt) return txt;
+    }
+    return "";
+  };
+
+  const attachPendingReasoning = (msg) => {
+    if (pendingReasoning) msg.reasoning_content = pendingReasoning;
+    if (pendingReasoningEncrypted) msg.encrypted_content = pendingReasoningEncrypted;
+    pendingReasoning = "";
+    pendingReasoningEncrypted = "";
+  };
+
+  for (const item of inputItems) {
+    // Determine item type - Droid CLI sends role-based items without 'type' field
+    // Fallback: if no type but has role property, treat as message
+    const itemType = item.type || (item.role ? RESPONSES_ITEM.MESSAGE : null);
+
+    if (itemType === RESPONSES_ITEM.MESSAGE) {
+      // Flush any pending assistant message with tool calls
+      if (currentAssistantMsg) {
+        result.messages.push(currentAssistantMsg);
+        currentAssistantMsg = null;
+      }
+      // Flush pending tool results
+      if (pendingToolResults.length > 0) {
+        for (const tr of pendingToolResults) {
+          result.messages.push(tr);
+        }
+        pendingToolResults = [];
+      }
+
+      // Convert content: input_text → text, output_text → text, input_image → image_url
+      const content = Array.isArray(item.content)
+        ? item.content.map(c => {
+          if (c.type === RESPONSES_ITEM.INPUT_TEXT) return { type: OPENAI_BLOCK.TEXT, text: c.text };
+          if (c.type === RESPONSES_ITEM.OUTPUT_TEXT) return { type: OPENAI_BLOCK.TEXT, text: c.text };
+          if (c.type === RESPONSES_ITEM.INPUT_IMAGE) {
+            const url = c.image_url || c.file_id || "";
+            return { type: OPENAI_BLOCK.IMAGE_URL, image_url: { url, detail: c.detail || "auto" } };
+          }
+          return c;
+        })
+        : item.content;
+      const msg = { role: item.role, content };
+      // Attach buffered reasoning to assistant turn (required by xiaomi-mimo + store=false continuity)
+      if (item.role === ROLE.ASSISTANT) attachPendingReasoning(msg);
+      else {
+        pendingReasoning = "";
+        pendingReasoningEncrypted = "";
+      }
+      result.messages.push(msg);
+    }
+    else if (itemType === RESPONSES_ITEM.FUNCTION_CALL) {
+      // Start or append to assistant message with tool_calls
+      if (!currentAssistantMsg) {
+        currentAssistantMsg = {
+          role: ROLE.ASSISTANT,
+          content: null,
+          tool_calls: []
+        };
+        attachPendingReasoning(currentAssistantMsg);
+      }
+      // Skip items with empty/missing name — Codex/OpenAI reject nameless tool calls (#444)
+      if (!item.name || typeof item.name !== "string" || item.name.trim() === "") continue;
+      currentAssistantMsg.tool_calls.push({
+        id: item.call_id,
+        type: OPENAI_BLOCK.FUNCTION,
+        function: {
+          name: item.name,
+          arguments: item.arguments
+        }
+      });
+    }
+    else if (itemType === RESPONSES_ITEM.FUNCTION_CALL_OUTPUT) {
+      // Flush assistant message first if exists
+      if (currentAssistantMsg) {
+        result.messages.push(currentAssistantMsg);
+        currentAssistantMsg = null;
+      }
+      // Flush any pending tool results first
+      if (pendingToolResults.length > 0) {
+        for (const tr of pendingToolResults) {
+          result.messages.push(tr);
+        }
+        pendingToolResults = [];
+      }
+      // Add tool result immediately
+      result.messages.push({
+        role: ROLE.TOOL,
+        tool_call_id: item.call_id,
+        content: typeof item.output === "string" ? item.output : JSON.stringify(item.output)
+      });
+    }
+    else if (itemType === RESPONSES_ITEM.REASONING) {
+      // Buffer reasoning text; attached to next assistant message/function_call.
+      // Also stash encrypted_content so a later openai→responses hop can restore
+      // the store=false continuity blob (Grok CLI / Codex multi-turn).
+      const txt = extractReasoningText(item);
+      if (txt) pendingReasoning = pendingReasoning ? `${pendingReasoning}\n${txt}` : txt;
+      if (typeof item.encrypted_content === "string" && item.encrypted_content) {
+        // Prefer attaching to the next assistant message we create
+        pendingReasoningEncrypted = item.encrypted_content;
+      }
+      continue;
+    }
+  }
+
+  // Flush remaining
+  if (currentAssistantMsg) {
+    result.messages.push(currentAssistantMsg);
+  }
+  if (pendingToolResults.length > 0) {
+    for (const tr of pendingToolResults) {
+      result.messages.push(tr);
+    }
+  }
+
+  // Convert tools format.
+  // Responses API supports "hosted" tools (e.g. { type: "request_user_input" }) that carry no
+  // explicit `name` field and cannot be represented as Chat Completions function declarations.
+  // Filter them out to avoid sending nameless functionDeclarations to downstream providers
+  // such as Gemini, which strictly validates function names.
+  if (body.tools && Array.isArray(body.tools)) {
+    result.tools = body.tools
+      .map(tool => {
+        // Already in Chat Completions format: { type: "function", function: { name, ... } }
+        if (tool.function) return tool;
+        // Responses API function tool: { type: "function", name, description, parameters }
+        // Only convert when a non-empty name is present; skip hosted tools without one.
+        const name = tool.name;
+        if (!name || typeof name !== "string" || name.trim() === "") return null;
+        return {
+          type: OPENAI_BLOCK.FUNCTION,
+          function: {
+            name,
+            description: String(tool.description || ""),
+            parameters: normalizeToolParameters(tool.parameters),
+            strict: tool.strict
+          }
+        };
+      })
+      .filter(Boolean);
+  }
+
+  // Cleanup Responses API specific fields
+  // Map Responses-only max_output_tokens to Chat max_tokens (avoid leaking unknown field upstream)
+  if (result.max_output_tokens !== undefined) {
+    if (result.max_tokens === undefined) result.max_tokens = result.max_output_tokens;
+    delete result.max_output_tokens;
+  }
+
+  delete result.input;
+  delete result.instructions;
+  delete result.include;
+  delete result.prompt_cache_key;
+  delete result.store;
+  delete result.reasoning;
+
+  return result;
+}
+
+/**
+ * Ensure object schema always has properties field (required by Codex Responses API)
+ */
+function normalizeToolParameters(params) {
+  if (!params) return { type: "object", properties: {} };
+  if (params.type === "object" && !params.properties) return { ...params, properties: {} };
+  return params;
+}
+
+/**
+ * Build a Responses `reasoning` input item from Chat Completions assistant fields.
+ * Preserves encrypted blobs needed by store=false multi-turn (Grok CLI / Codex).
+ * Returns null when the message has nothing useful to re-send.
+ */
+function buildReasoningInputItem(msg) {
+  if (!msg || typeof msg !== "object") return null;
+
+  const encrypted =
+    (typeof msg.encrypted_content === "string" && msg.encrypted_content) ||
+    (typeof msg.reasoning_encrypted_content === "string" && msg.reasoning_encrypted_content) ||
+    (typeof msg.reasoning?.encrypted_content === "string" && msg.reasoning.encrypted_content) ||
+    "";
+
+  let summaryText = "";
+  if (typeof msg.reasoning_content === "string" && msg.reasoning_content.trim()) {
+    summaryText = msg.reasoning_content;
+  } else if (typeof msg.reasoning === "string" && msg.reasoning.trim()) {
+    summaryText = msg.reasoning;
+  } else if (Array.isArray(msg.reasoning_details)) {
+    summaryText = msg.reasoning_details
+      .map((d) => (typeof d?.text === "string" ? d.text : typeof d?.content === "string" ? d.content : ""))
+      .filter(Boolean)
+      .join("\n");
+  }
+
+  if (!encrypted && !summaryText) return null;
+
+  const item = { type: RESPONSES_ITEM.REASONING };
+  if (summaryText) {
+    item.summary = [{ type: RESPONSES_ITEM.SUMMARY_TEXT, text: summaryText }];
+  }
+  // encrypted_content is the continuity token for store=false backends
+  if (encrypted) item.encrypted_content = encrypted;
+  return item;
+}
+
+/**
+ * Convert OpenAI Chat Completions to OpenAI Responses API format
+ */
+export function openaiToOpenAIResponsesRequest(model, body, stream, credentials) {
+  // Body already in Responses API format (e.g. Cursor CLI calling /chat/completions with input[])
+  if (body.input) return { ...body, model, stream: true };
+
+  const result = {
+    model,
+    input: [],
+    stream: true,
+    store: false
+  };
+
+  // Extract system message as instructions
+  let hasSystemMessage = false;
+  const messages = body.messages || [];
+
+  for (const msg of messages) {
+    if (msg.role === ROLE.SYSTEM || msg.role === ROLE.DEVELOPER) {
+      // Use the first instruction-bearing message as instructions.
+      // OpenAI recommends role="developer" for GPT-5/Codex as the system-level prompt.
+      if (!hasSystemMessage) {
+        result.instructions = typeof msg.content === "string" ? msg.content : "";
+        hasSystemMessage = true;
+      }
+      continue; // Skip instruction messages in input
+    }
+
+    // Convert user/assistant messages to input items
+    if (msg.role === ROLE.USER || msg.role === ROLE.ASSISTANT) {
+      // Multi-turn continuity for store=false Responses backends (Codex / Grok CLI):
+      // re-emit a reasoning item before the assistant message when the chat-format
+      // history carried reasoning text and/or encrypted_content from a prior turn.
+      if (msg.role === ROLE.ASSISTANT) {
+        const reasoningItem = buildReasoningInputItem(msg);
+        if (reasoningItem) result.input.push(reasoningItem);
+      }
+
+      const contentType = msg.role === ROLE.USER ? RESPONSES_ITEM.INPUT_TEXT : RESPONSES_ITEM.OUTPUT_TEXT;
+      const content = typeof msg.content === "string"
+        ? [{ type: contentType, text: msg.content }]
+        : Array.isArray(msg.content)
+          ? msg.content.map(c => {
+            if (c.type === OPENAI_BLOCK.TEXT) return { type: contentType, text: c.text };
+            // Convert Chat Completions image_url → Responses API input_image
+            // Responses API expects: { type: "input_image", image_url: "<url string>" }
+            // Chat Completions sends: { type: "image_url", image_url: { url: "...", detail: "..." } }
+            if (c.type === OPENAI_BLOCK.IMAGE_URL) {
+              const url = typeof c.image_url === "string" ? c.image_url : c.image_url?.url;
+              return { type: RESPONSES_ITEM.INPUT_IMAGE, image_url: url, detail: c.image_url?.detail || "auto" };
+            }
+            if (c.type === RESPONSES_ITEM.INPUT_IMAGE) return c;
+            // Serialize any unknown type (tool_use, tool_result, thinking, etc.) as text
+            const text = c.text || c.content || JSON.stringify(c);
+            return { type: contentType, text: typeof text === "string" ? text : JSON.stringify(text) };
+          })
+          : [];
+
+      // Only push a message block if content is non-empty.
+      // Assistant messages with only tool_calls have content: null — skip the
+      // message block in that case; the tool_calls are pushed separately below.
+      if (content.length > 0) {
+        result.input.push({
+          type: RESPONSES_ITEM.MESSAGE,
+          role: msg.role,
+          content
+        });
+      }
+    }
+
+    // Convert tool calls
+    if (msg.role === ROLE.ASSISTANT && msg.tool_calls) {
+      for (const tc of msg.tool_calls) {
+        result.input.push({
+          type: RESPONSES_ITEM.FUNCTION_CALL,
+          call_id: clampCallId(tc.id),
+          name: tc.function?.name || "_unknown",
+          arguments: tc.function?.arguments || "{}"
+        });
+      }
+    }
+
+    // Convert tool results - output must be a string for Responses API
+    if (msg.role === ROLE.TOOL) {
+      const output = typeof msg.content === "string"
+        ? msg.content
+        : Array.isArray(msg.content)
+          ? msg.content.map(c => c.text || JSON.stringify(c)).join("")
+          : JSON.stringify(msg.content);
+      result.input.push({
+        type: RESPONSES_ITEM.FUNCTION_CALL_OUTPUT,
+        call_id: clampCallId(msg.tool_call_id),
+        output
+      });
+    }
+  }
+
+  // If no system message, leave instructions empty (will be filled by executor)
+  if (!hasSystemMessage) {
+    result.instructions = "";
+  }
+
+  // Convert tools format
+  if (body.tools && Array.isArray(body.tools)) {
+    result.tools = body.tools.map(tool => {
+      if (tool.type === OPENAI_BLOCK.FUNCTION) {
+        return {
+          type: OPENAI_BLOCK.FUNCTION,
+          name: tool.function.name,
+          description: String(tool.function.description || ""),
+          parameters: normalizeToolParameters(tool.function.parameters),
+          strict: tool.function.strict
+        };
+      }
+      return tool;
+    });
+  }
+
+  // Pass through other relevant fields
+  if (body.temperature !== undefined) result.temperature = body.temperature;
+  if (body.max_tokens !== undefined) result.max_tokens = body.max_tokens;
+  if (body.top_p !== undefined) result.top_p = body.top_p;
+  if (body.reasoning !== undefined) result.reasoning = body.reasoning;
+  if (body.reasoning_effort !== undefined) result.reasoning = { effort: body.reasoning_effort, summary: "auto" };
+
+  return result;
+}
+
+// Register both directions
+register(FORMATS.OPENAI_RESPONSES, FORMATS.OPENAI, openaiResponsesToOpenAIRequest, null);
+register(FORMATS.OPENAI, FORMATS.OPENAI_RESPONSES, openaiToOpenAIResponsesRequest, null);
diff --git a/open-sse/translator/request/openai-to-claude.js b/open-sse/translator/request/openai-to-claude.js
new file mode 100644
index 0000000..580debf
--- /dev/null
+++ b/open-sse/translator/request/openai-to-claude.js
@@ -0,0 +1,383 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { CLAUDE_SYSTEM_PROMPT } from "../../config/appConstants.js";
+import { adjustMaxTokens } from "../formats/maxTokens.js";
+import { safeParseJSON } from "../concerns/json.js";
+import { parseDataUri } from "../concerns/image.js";
+import { extractTextContent } from "../formats/gemini.js";
+import { ROLE, OPENAI_BLOCK, CLAUDE_BLOCK } from "../schema/index.js";
+import { getCapabilitiesForModel } from "../../providers/capabilities.js";
+
+// Empty prefix matches real Claude Code behavior (no tool name prefix).
+// Previously "proxy_" was used but this is a detectable fingerprint difference.
+const CLAUDE_OAUTH_TOOL_PREFIX = "";
+
+// Convert OpenAI request to Claude format
+export function openaiToClaudeRequest(model, body, stream) {
+  // Tool name mapping for Claude OAuth (capitalizedName → originalName)
+  const toolNameMap = new Map();
+  // Cap max_tokens at the model's real output ceiling (e.g. Opus 4.8 = 128000),
+  // not the conservative 64000 default — otherwise a high-output model is
+  // pre-clamped here before prepareClaudeRequest's model-aware step runs.
+  const modelCeiling = getCapabilitiesForModel(null, model).maxOutput || undefined;
+  const result = {
+    model: model,
+    max_tokens: adjustMaxTokens(body, modelCeiling),
+    stream: stream
+  };
+
+  // Temperature
+  if (body.temperature !== undefined) {
+    result.temperature = body.temperature;
+  }
+
+  // Messages
+  result.messages = [];
+  const systemParts = [];
+
+  if (body.messages && Array.isArray(body.messages)) {
+    // Extract system messages
+    for (const msg of body.messages) {
+      if (msg.role === ROLE.SYSTEM) {
+        systemParts.push(typeof msg.content === "string" ? msg.content : extractTextContent(msg.content, "\n"));
+      }
+    }
+
+    // Filter out system messages for separate processing
+    const nonSystemMessages = body.messages.filter(m => m.role !== ROLE.SYSTEM);
+
+    // Process messages with merging logic
+    // CRITICAL: tool_result must be in separate message immediately after tool_use
+    let currentRole = undefined;
+    let currentParts = [];
+
+    const flushCurrentMessage = () => {
+      if (currentRole && currentParts.length > 0) {
+        result.messages.push({ role: currentRole, content: currentParts });
+        currentParts = [];
+      }
+    };
+
+    for (const msg of nonSystemMessages) {
+      const newRole = (msg.role === ROLE.USER || msg.role === ROLE.TOOL) ? ROLE.USER : ROLE.ASSISTANT;
+      const blocks = getContentBlocksFromMessage(msg, toolNameMap);
+      const hasToolUse = blocks.some(b => b.type === CLAUDE_BLOCK.TOOL_USE);
+      const hasToolResult = blocks.some(b => b.type === CLAUDE_BLOCK.TOOL_RESULT);
+
+      // Separate tool_result from other content
+      if (hasToolResult) {
+        const toolResultBlocks = blocks.filter(b => b.type === CLAUDE_BLOCK.TOOL_RESULT);
+        const otherBlocks = blocks.filter(b => b.type !== CLAUDE_BLOCK.TOOL_RESULT);
+
+        flushCurrentMessage();
+
+        if (toolResultBlocks.length > 0) {
+          result.messages.push({ role: ROLE.USER, content: toolResultBlocks });
+        }
+
+        if (otherBlocks.length > 0) {
+          currentRole = newRole;
+          currentParts.push(...otherBlocks);
+        }
+        continue;
+      }
+
+      if (currentRole !== newRole) {
+        flushCurrentMessage();
+        currentRole = newRole;
+      }
+
+      currentParts.push(...blocks);
+
+      if (hasToolUse) {
+        flushCurrentMessage();
+      }
+    }
+
+    flushCurrentMessage();
+
+    // Add cache_control to last assistant message
+    for (let i = result.messages.length - 1; i >= 0; i--) {
+      const message = result.messages[i];
+      if (message.role === ROLE.ASSISTANT && Array.isArray(message.content) && message.content.length > 0) {
+        // Find the last block that can have cache_control (not thinking blocks)
+        const validBlockTypes = [CLAUDE_BLOCK.TEXT, CLAUDE_BLOCK.TOOL_USE, CLAUDE_BLOCK.TOOL_RESULT, CLAUDE_BLOCK.IMAGE];
+        for (let j = message.content.length - 1; j >= 0; j--) {
+          const block = message.content[j];
+          if (validBlockTypes.includes(block.type)) {
+            block.cache_control = { type: "ephemeral" };
+            break;
+          }
+        }
+        break;
+      }
+    }
+  }
+
+  // Handle response_format for JSON mode
+  if (body.response_format) {
+    const responseFormat = body.response_format;
+    if (responseFormat.type === "json_schema" && responseFormat.json_schema?.schema) {
+      const schemaJson = JSON.stringify(responseFormat.json_schema.schema, null, 2);
+      systemParts.push(`You must respond with valid JSON that strictly follows this JSON schema:
+\`\`\`json
+${schemaJson}
+\`\`\`
+Respond ONLY with the JSON object, no other text.`);
+    } else if (responseFormat.type === "json_object") {
+      systemParts.push("You must respond with valid JSON. Respond ONLY with a JSON object, no other text.");
+    }
+  }
+
+  // System with Claude Code prompt and cache_control
+  const claudeCodePrompt = { type: CLAUDE_BLOCK.TEXT, text: CLAUDE_SYSTEM_PROMPT };
+
+  if (systemParts.length > 0) {
+    const systemText = systemParts.join("\n");
+    result.system = [
+      claudeCodePrompt,
+      { type: CLAUDE_BLOCK.TEXT, text: systemText, cache_control: { type: "ephemeral", ttl: "1h" } }
+    ];
+  } else {
+    result.system = [claudeCodePrompt];
+  }
+
+  // Tools - convert from OpenAI format to Claude format with prefix for OAuth
+  if (body.tools && Array.isArray(body.tools)) {
+    result.tools = [];
+    for (const tool of body.tools) {
+      // Pass-through built-in tools (e.g. web_search_20250305) without prefix or conversion
+      const toolType = tool.type;
+      if (toolType && toolType !== OPENAI_BLOCK.FUNCTION) {
+        result.tools.push(tool);
+        continue;
+      }
+
+      // Function-shaped tools arrive in two flavors from real clients:
+      //   (a) openai-spec: { type: "function", function: { name, ... } }
+      //   (b) legacy/loose: { function: { name, ... } }   (no parent `type`)
+      // Both must yield toolData.name = "echo". Treat the bare-function shape
+      // as a function tool too — Anthropic-compatible gateways (notably
+      // MiniMax M3 at api.minimaxi.com) reject payloads where this branch
+      // falls through with `toolData.name === undefined`, returning their
+      // upstream code (2013) "invalid tool type". See #2435.
+      const toolData = tool.function ?? tool;
+      const originalName = toolData.name;
+
+      // Claude OAuth requires prefixed tool names to avoid conflicts
+      const toolName = CLAUDE_OAUTH_TOOL_PREFIX + originalName;
+
+      // Store mapping for response translation (prefixed → original)
+      toolNameMap.set(toolName, originalName);
+
+      result.tools.push({
+        name: toolName,
+        description: toolData.description || "",
+        input_schema: toolData.parameters || toolData.input_schema || { type: "object", properties: {}, required: [] }
+      });
+    }
+
+    if (result.tools.length > 0) {
+      result.tools[result.tools.length - 1].cache_control = { type: "ephemeral", ttl: "1h" };
+    }
+  }
+
+  // Tool choice
+  if (body.tool_choice) {
+    result.tool_choice = convertOpenAIToolChoice(body.tool_choice);
+  }
+
+  // Thinking is normalized centrally by applyThinking (thinkingUnified.js) after translation.
+
+  // Attach toolNameMap to result for response translation
+  if (toolNameMap.size > 0) {
+    result._toolNameMap = toolNameMap;
+  }
+
+  return result;
+}
+
+// Get content blocks from single message
+function getContentBlocksFromMessage(msg, toolNameMap = new Map()) {
+  const blocks = [];
+
+  if (msg.role === ROLE.TOOL) {
+    blocks.push({
+      type: CLAUDE_BLOCK.TOOL_RESULT,
+      tool_use_id: msg.tool_call_id,
+      content: msg.content
+    });
+  } else if (msg.role === ROLE.USER) {
+    if (typeof msg.content === "string") {
+      if (msg.content) {
+        blocks.push({ type: CLAUDE_BLOCK.TEXT, text: msg.content });
+      }
+    } else if (Array.isArray(msg.content)) {
+      for (const part of msg.content) {
+        if (part.type === OPENAI_BLOCK.TEXT && part.text) {
+          blocks.push({ type: CLAUDE_BLOCK.TEXT, text: part.text });
+        } else if (part.type === CLAUDE_BLOCK.TOOL_RESULT) {
+          blocks.push({
+            type: CLAUDE_BLOCK.TOOL_RESULT,
+            tool_use_id: part.tool_use_id,
+            content: part.content,
+            ...(part.is_error && { is_error: part.is_error })
+          });
+        } else if (part.type === OPENAI_BLOCK.IMAGE_URL) {
+          const url = part.image_url.url;
+          const parsed = parseDataUri(url);
+          if (parsed) {
+            blocks.push({
+              type: CLAUDE_BLOCK.IMAGE,
+              source: { type: "base64", media_type: parsed.mimeType, data: parsed.base64 }
+            });
+          } else if (url.startsWith("http://") || url.startsWith("https://")) {
+            blocks.push({
+              type: CLAUDE_BLOCK.IMAGE,
+              source: { type: "url", url }
+            });
+          }
+        } else if (part.type === OPENAI_BLOCK.IMAGE && part.source) {
+          blocks.push({ type: CLAUDE_BLOCK.IMAGE, source: part.source });
+        } else if (part.type === OPENAI_BLOCK.FILE && part.file) {
+          // OpenAI file block -> Claude document (PDF only; Claude rejects other mimes).
+          const fileData = part.file.file_data;
+          const parsed = parseDataUri(fileData);
+          if (parsed && parsed.mimeType === "application/pdf") {
+            blocks.push({
+              type: CLAUDE_BLOCK.DOCUMENT,
+              source: { type: "base64", media_type: parsed.mimeType, data: parsed.base64 }
+            });
+          }
+        }
+      }
+    }
+  } else if (msg.role === ROLE.ASSISTANT) {
+    if (Array.isArray(msg.content)) {
+      for (const part of msg.content) {
+        if (part.type === OPENAI_BLOCK.TEXT && part.text) {
+          blocks.push({ type: CLAUDE_BLOCK.TEXT, text: part.text });
+        } else if (part.type === CLAUDE_BLOCK.TOOL_USE) {
+          // Tool name already has prefix from tool declarations, keep as-is
+          blocks.push({ type: CLAUDE_BLOCK.TOOL_USE, id: part.id, name: part.name, input: part.input });
+        } else if (part.type === CLAUDE_BLOCK.THINKING) {
+          // Include thinking block but strip cache_control (not allowed on thinking blocks)
+          const { cache_control, ...thinkingBlock } = part;
+          blocks.push(thinkingBlock);
+        }
+      }
+    } else if (msg.content) {
+      const text = typeof msg.content === "string" ? msg.content : extractTextContent(msg.content, "\n");
+      if (text) {
+        blocks.push({ type: CLAUDE_BLOCK.TEXT, text });
+      }
+    }
+
+    if (msg.tool_calls && Array.isArray(msg.tool_calls)) {
+      for (const tc of msg.tool_calls) {
+        if (tc.type === OPENAI_BLOCK.FUNCTION) {
+          // Apply prefix to tool name
+          const toolName = CLAUDE_OAUTH_TOOL_PREFIX + tc.function.name;
+          blocks.push({
+            type: CLAUDE_BLOCK.TOOL_USE,
+            id: tc.id,
+            name: toolName,
+            input: safeParseJSON(tc.function.arguments, tc.function.arguments)
+          });
+        }
+      }
+    }
+  }
+
+  return blocks;
+}
+
+// Convert OpenAI tool choice to Claude format.
+// Claude only accepts tool_choice.type of "auto" | "any" | "tool" | "none";
+// anything else (e.g. OpenAI's "function") triggers a 400, so we never pass an
+// unrecognized type through.
+const CLAUDE_TOOL_CHOICE_TYPES = new Set(["auto", "any", "tool", "none"]);
+
+function convertOpenAIToolChoice(choice) {
+  if (!choice) return { type: "auto" };
+
+  // OpenAI string forms: "auto" | "none" | "required"
+  if (typeof choice === "string") {
+    if (choice === "required") return { type: "any" };
+    return { type: "auto" }; // "auto", "none", or anything unexpected
+  }
+
+  if (typeof choice === "object") {
+    // OpenAI forced tool: { type: "function", function: { name } }.
+    // Checked before the native pass-through below, because the OpenAI shape
+    // also carries a `.type` ("function") that Claude rejects.
+    if (choice.function?.name) {
+      return { type: "tool", name: choice.function.name };
+    }
+    // Already Claude-native — only pass through types Claude actually accepts,
+    // so a malformed or unknown type can never leak into the upstream request.
+    if (CLAUDE_TOOL_CHOICE_TYPES.has(choice.type)) {
+      return choice;
+    }
+  }
+
+  return { type: "auto" };
+}
+
+// OpenAI -> Claude format for Antigravity (without system prompt modifications)
+function openaiToClaudeRequestForAntigravity(model, body, stream) {
+  const result = openaiToClaudeRequest(model, body, stream);
+
+  // Remove Claude Code system prompt, keep only user's system messages
+  if (result.system && Array.isArray(result.system)) {
+    result.system = result.system.filter(block =>
+      !block.text || !block.text.includes("You are Claude Code")
+    );
+    if (result.system.length === 0) {
+      delete result.system;
+    }
+  }
+
+  // Strip prefix from tool names for Antigravity (doesn't use Claude OAuth)
+  if (result.tools && Array.isArray(result.tools)) {
+    result.tools = result.tools.map(tool => {
+      if (tool.name && tool.name.startsWith(CLAUDE_OAUTH_TOOL_PREFIX)) {
+        return {
+          ...tool,
+          name: tool.name.slice(CLAUDE_OAUTH_TOOL_PREFIX.length)
+        };
+      }
+      return tool;
+    });
+  }
+
+  // Strip prefix from tool_use in messages
+  if (result.messages && Array.isArray(result.messages)) {
+    result.messages = result.messages.map(msg => {
+      if (!msg.content || !Array.isArray(msg.content)) {
+        return msg;
+      }
+
+      const updatedContent = msg.content.map(block => {
+        if (block.type === CLAUDE_BLOCK.TOOL_USE && block.name && block.name.startsWith(CLAUDE_OAUTH_TOOL_PREFIX)) {
+          return {
+            ...block,
+            name: block.name.slice(CLAUDE_OAUTH_TOOL_PREFIX.length)
+          };
+        }
+        return block;
+      });
+
+      return { ...msg, content: updatedContent };
+    });
+  }
+
+  return result;
+}
+
+// Export for use in other translators
+export { openaiToClaudeRequestForAntigravity };
+
+// Register
+register(FORMATS.OPENAI, FORMATS.CLAUDE, openaiToClaudeRequest, null);
+
diff --git a/open-sse/translator/request/openai-to-commandcode.js b/open-sse/translator/request/openai-to-commandcode.js
new file mode 100644
index 0000000..9825048
--- /dev/null
+++ b/open-sse/translator/request/openai-to-commandcode.js
@@ -0,0 +1,172 @@
+/**
+ * OpenAI → CommandCode request translator
+ *
+ * Upstream `/alpha/generate` schema (verified live with curl 2026-05-07):
+ *  - params.system: STRING at top level (Anthropic-style; system messages NOT allowed in messages[])
+ *  - params.messages[*].role ∈ {"user","assistant","tool"}
+ *  - params.messages[*].content: Array of content blocks (NEVER a string)
+ *  - tool_use blocks (assistant): {type:"tool-call", toolCallId, toolName, input}
+ *  - tool_result blocks (role=user): {type:"tool-result", toolCallId, toolName, output}
+ *  - tools[*]: Anthropic plain {name, description, input_schema}
+ */
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { randomUUID } from "crypto";
+import { ROLE, OPENAI_BLOCK } from "../schema/index.js";
+import { DEFAULT_MAX_TOKENS } from "../../config/runtimeConfig.js";
+
+function flattenText(content) {
+  if (content == null) return "";
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    const parts = [];
+    for (const p of content) {
+      if (typeof p === "string") parts.push(p);
+      else if (p && typeof p === "object" && typeof p.text === "string") parts.push(p.text);
+    }
+    return parts.join("\n");
+  }
+  return String(content);
+}
+
+function toContentBlocks(content) {
+  if (content == null) return [{ type: OPENAI_BLOCK.TEXT, text: "" }];
+  if (typeof content === "string") return [{ type: OPENAI_BLOCK.TEXT, text: content }];
+  if (Array.isArray(content)) {
+    const blocks = [];
+    for (const part of content) {
+      if (typeof part === "string") {
+        blocks.push({ type: OPENAI_BLOCK.TEXT, text: part });
+      } else if (part && typeof part === "object") {
+        if (part.type === OPENAI_BLOCK.TEXT && typeof part.text === "string") {
+          blocks.push({ type: OPENAI_BLOCK.TEXT, text: part.text });
+        } else if (part.type === OPENAI_BLOCK.IMAGE_URL || part.type === OPENAI_BLOCK.IMAGE) {
+          blocks.push({ type: OPENAI_BLOCK.TEXT, text: "[image omitted]" });
+        } else if (typeof part.text === "string") {
+          blocks.push({ type: OPENAI_BLOCK.TEXT, text: part.text });
+        }
+      }
+    }
+    return blocks.length ? blocks : [{ type: OPENAI_BLOCK.TEXT, text: "" }];
+  }
+  return [{ type: OPENAI_BLOCK.TEXT, text: String(content) }];
+}
+
+function safeParseJson(s) {
+  if (s == null) return {};
+  if (typeof s !== "string") return s;
+  try { return JSON.parse(s); } catch { return {}; }
+}
+
+function convertMessages(messages = []) {
+  const out = [];
+  const systemTexts = [];
+
+  for (const m of messages) {
+    if (!m) continue;
+    const role = m.role;
+
+    if (role === ROLE.SYSTEM) {
+      const t = flattenText(m.content);
+      if (t) systemTexts.push(t);
+      continue;
+    }
+
+    if (role === ROLE.TOOL) {
+      const value = typeof m.content === "string" ? m.content : flattenText(m.content);
+      out.push({
+        role: ROLE.TOOL,
+        content: [{
+          type: "tool-result",
+          toolCallId: m.tool_call_id || "",
+          toolName: m.name || "",
+          output: { type: "text", value },
+        }],
+      });
+      continue;
+    }
+
+    if (role === ROLE.ASSISTANT) {
+      const blocks = [];
+      const text = flattenText(m.content);
+      if (text) blocks.push({ type: OPENAI_BLOCK.TEXT, text });
+      if (Array.isArray(m.tool_calls)) {
+        for (const tc of m.tool_calls) {
+          const fn = tc.function || {};
+          blocks.push({
+            type: "tool-call",
+            toolCallId: tc.id || "",
+            toolName: fn.name || "",
+            input: safeParseJson(fn.arguments),
+          });
+        }
+      }
+      out.push({ role: ROLE.ASSISTANT, content: blocks.length ? blocks : [{ type: OPENAI_BLOCK.TEXT, text: "" }] });
+      continue;
+    }
+
+    out.push({ role: ROLE.USER, content: toContentBlocks(m.content) });
+  }
+
+  return { messages: out, system: systemTexts.join("\n\n") };
+}
+
+function convertTools(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) return undefined;
+  const result = [];
+  for (const t of tools) {
+    if (!t) continue;
+    if (t.type === OPENAI_BLOCK.FUNCTION && t.function) {
+      result.push({
+        name: t.function.name,
+        description: t.function.description,
+        input_schema: t.function.parameters || { type: "object" },
+      });
+    } else if (t.name && (t.input_schema || t.parameters)) {
+      result.push({
+        name: t.name,
+        description: t.description,
+        input_schema: t.input_schema || t.parameters,
+      });
+    }
+  }
+  return result.length ? result : undefined;
+}
+
+export function openaiToCommandCodeRequest(model, body, stream /* , credentials */) {
+  const { messages, system } = convertMessages(body.messages);
+  const params = {
+    model,
+    messages,
+    stream: stream !== false,
+    max_tokens: body.max_tokens ?? body.max_output_tokens ?? DEFAULT_MAX_TOKENS,
+    temperature: body.temperature ?? 0.3,
+  };
+
+  if (system) params.system = system;
+
+  const tools = convertTools(body.tools);
+  if (tools) params.tools = tools;
+  if (body.top_p != null) params.top_p = body.top_p;
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  return {
+    threadId: randomUUID(),
+    memory: "",
+    config: {
+      workingDir: process.cwd(),
+      date: today,
+      environment: process.platform,
+      structure: [],
+      isGitRepo: false,
+      currentBranch: "",
+      mainBranch: "",
+      gitStatus: "",
+      recentCommits: [],
+    },
+    params,
+  };
+}
+
+register(FORMATS.OPENAI, FORMATS.COMMANDCODE, openaiToCommandCodeRequest, null);
diff --git a/open-sse/translator/request/openai-to-cursor.js b/open-sse/translator/request/openai-to-cursor.js
new file mode 100644
index 0000000..02c55b3
--- /dev/null
+++ b/open-sse/translator/request/openai-to-cursor.js
@@ -0,0 +1,185 @@
+/**
+ * OpenAI to Cursor Request Translator
+ * Converts OpenAI messages to Cursor ask/agent format.
+ *
+ * Important: Cursor can loop when tool outputs are sent via protobuf tool_results
+ * with partial schema mismatches. For stability, tool outputs are represented as
+ * structured text blocks in user messages.
+ */
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { ROLE, OPENAI_BLOCK, CLAUDE_BLOCK } from "../schema/index.js";
+import { DEFAULT_MIN_TOKENS } from "../../config/runtimeConfig.js";
+
+function extractContent(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter(part => {
+        if (!part || typeof part !== "object") return false;
+        return part.type === OPENAI_BLOCK.TEXT && typeof part.text === "string";
+      })
+      .map(part => part.text || "")
+      .join("");
+  }
+  return "";
+}
+
+function sanitizeToolResultText(text) {
+  // Strip non-printable control chars that can produce backend request errors
+  return text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "");
+}
+
+function escapeXml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function buildToolResultBlock(toolName, toolCallId, resultText) {
+  const cleanResult = sanitizeToolResultText(resultText || "");
+  return [
+    "<tool_result>",
+    `<tool_name>${escapeXml(toolName || "tool")}</tool_name>`,
+    `<tool_call_id>${escapeXml(toolCallId || "")}</tool_call_id>`,
+    `<result>${escapeXml(cleanResult)}</result>`,
+    "</tool_result>"
+  ].join("\n");
+}
+
+function normalizeToolCallId(id) {
+  return typeof id === "string" ? id.split("\n")[0] : "";
+}
+
+function convertMessages(messages) {
+  const result = [];
+  
+  // Build a map of tool_call_id -> tool name from assistant tool calls
+  const toolCallMetaMap = new Map();
+  const rememberToolMeta = (toolCallId, toolName) => {
+    if (!toolCallId) return;
+    const name = toolName || "tool";
+    toolCallMetaMap.set(toolCallId, { name });
+    const normalized = normalizeToolCallId(toolCallId);
+    if (normalized && normalized !== toolCallId) {
+      toolCallMetaMap.set(normalized, { name });
+    }
+  };
+
+  for (const msg of messages) {
+    if (msg.role === ROLE.ASSISTANT && msg.tool_calls) {
+      for (const tc of msg.tool_calls) {
+        rememberToolMeta(tc.id || "", tc.function?.name || "tool");
+      }
+    }
+    if (msg.role === ROLE.ASSISTANT && Array.isArray(msg.content)) {
+      for (const part of msg.content) {
+        if (part?.type !== CLAUDE_BLOCK.TOOL_USE) continue;
+        rememberToolMeta(part.id || "", part.name || "tool");
+      }
+    }
+  }
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+
+    if (msg.role === ROLE.SYSTEM) {
+      result.push({
+        role: ROLE.USER,
+        content: `[System Instructions]\n${extractContent(msg.content)}`
+      });
+      continue;
+    }
+
+    if (msg.role === ROLE.TOOL) {
+      const toolContent = extractContent(msg.content);
+      const toolCallId = msg.tool_call_id || "";
+      const toolMeta = toolCallMetaMap.get(toolCallId) || {};
+      const toolName = msg.name || toolMeta.name || "tool";
+      result.push({
+        role: ROLE.USER,
+        content: buildToolResultBlock(toolName, toolCallId, toolContent)
+      });
+      continue;
+    }
+
+    if (msg.role === ROLE.USER || msg.role === ROLE.ASSISTANT) {
+      if (msg.role === ROLE.USER && Array.isArray(msg.content)) {
+        const parts = [];
+        for (const block of msg.content) {
+          if (!block || typeof block !== "object") continue;
+          if (block.type === CLAUDE_BLOCK.TEXT) {
+            if (typeof block.text === "string") {
+              parts.push(block.text || "");
+            }
+            continue;
+          }
+          if (block.type === CLAUDE_BLOCK.TOOL_RESULT) {
+            const toolCallId = block.tool_use_id || "";
+            const toolMeta =
+              toolCallMetaMap.get(toolCallId) ||
+              toolCallMetaMap.get(normalizeToolCallId(toolCallId));
+            const toolName = toolMeta?.name || "tool";
+            const toolContent = extractContent(block.content);
+            parts.push(buildToolResultBlock(toolName, toolCallId, toolContent));
+          }
+        }
+        const joined = parts.filter(Boolean).join("\n");
+        if (joined) result.push({ role: ROLE.USER, content: joined });
+        continue;
+      }
+
+      const content = extractContent(msg.content);
+
+      if (msg.role === ROLE.ASSISTANT && msg.tool_calls && msg.tool_calls.length > 0) {
+        const assistantMsg = { role: ROLE.ASSISTANT, content: content || "" };
+        assistantMsg.tool_calls = msg.tool_calls.map(tc => {
+          const { index, ...rest } = tc || {};
+          return rest;
+        });
+        result.push(assistantMsg);
+      } else if (msg.role === ROLE.ASSISTANT && Array.isArray(msg.content)) {
+        const extractedToolCalls = msg.content
+          .filter(b => b?.type === CLAUDE_BLOCK.TOOL_USE)
+          .map(b => ({
+            id: b.id || "",
+            type: OPENAI_BLOCK.FUNCTION,
+            function: {
+              name: b.name || "tool",
+              arguments: JSON.stringify(b.input || {})
+            }
+          }))
+          .filter(tc => tc.id);
+
+        if (extractedToolCalls.length > 0) {
+          result.push({
+            role: ROLE.ASSISTANT,
+            content: content || "",
+            tool_calls: extractedToolCalls
+          });
+        } else if (content) {
+          result.push({ role: ROLE.ASSISTANT, content });
+        }
+      } else {
+        if (content) {
+          result.push({ role: msg.role, content });
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+export function openaiToCursorRequest(model, body, stream, credentials) {
+  const messages = convertMessages(body.messages || []);
+
+  // Strip fields irrelevant to Cursor (OpenAI/Anthropic-specific)
+  const { user, metadata, tool_choice, stream_options, system, ...rest } = body;
+
+  return {
+    ...rest,
+    messages,
+    max_tokens: DEFAULT_MIN_TOKENS
+  };
+}
+
+register(FORMATS.OPENAI, FORMATS.CURSOR, openaiToCursorRequest, null);
diff --git a/open-sse/translator/request/openai-to-gemini.js b/open-sse/translator/request/openai-to-gemini.js
new file mode 100644
index 0000000..9e029e2
--- /dev/null
+++ b/open-sse/translator/request/openai-to-gemini.js
@@ -0,0 +1,442 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { DEFAULT_THINKING_AG_SIGNATURE, DEFAULT_THINKING_GEMINI_CLI_SIGNATURE } from "../../config/defaultThinkingSignature.js";
+import { openaiToClaudeRequestForAntigravity } from "./openai-to-claude.js";
+function generateUUID() {
+  return crypto.randomUUID();
+}
+
+import {
+  DEFAULT_SAFETY_SETTINGS,
+  convertOpenAIContentToParts,
+  extractTextContent,
+  tryParseJSON,
+  generateRequestId,
+  generateSessionId,
+  generateProjectId,
+  cleanJSONSchemaForAntigravity
+} from "../formats/gemini.js";
+import { deriveSessionId, toNumericSessionId } from "../../utils/sessionManager.js";
+import { ROLE, GEMINI_ROLE, OPENAI_BLOCK, CLAUDE_BLOCK } from "../schema/index.js";
+
+// Sanitize function names for Gemini API.
+// Gemini requires: starts with [a-zA-Z_], followed by [a-zA-Z0-9_.:\-], max 64 chars.
+// Replace any invalid character with '_' and truncate to 64.
+function sanitizeGeminiFunctionName(name) {
+  if (!name) return "_unknown";
+  // Replace any char not in [a-zA-Z0-9_.:\-] with '_'
+  let sanitized = name.replace(/[^a-zA-Z0-9_.:\-]/g, "_");
+  // First char must be letter or underscore
+  if (!/^[a-zA-Z_]/.test(sanitized)) {
+    sanitized = "_" + sanitized;
+  }
+  // Truncate to 64 chars
+  return sanitized.substring(0, 64);
+}
+
+function normalizeGeminiContents(contents) {
+  const out = [];
+  for (const c of contents || []) {
+    if (!c?.role || !Array.isArray(c.parts) || c.parts.length === 0) continue;
+    const last = out.at(-1);
+    if (last?.role === c.role) last.parts.push(...c.parts);
+    else out.push({ ...c, parts: [...c.parts] });
+  }
+  return out;
+}
+
+// Core: Convert OpenAI request to Gemini format (base for all variants)
+function openaiToGeminiBase(model, body, stream, signature = DEFAULT_THINKING_AG_SIGNATURE) {
+  const result = {
+    model: model,
+    contents: [],
+    generationConfig: {},
+    safetySettings: DEFAULT_SAFETY_SETTINGS
+  };
+
+  // Generation config
+  if (body.temperature !== undefined) {
+    result.generationConfig.temperature = body.temperature;
+  }
+  if (body.top_p !== undefined) {
+    result.generationConfig.topP = body.top_p;
+  }
+  if (body.top_k !== undefined) {
+    result.generationConfig.topK = body.top_k;
+  }
+  if (body.max_tokens !== undefined) {
+    result.generationConfig.maxOutputTokens = body.max_tokens;
+  }
+
+  // Build tool_call_id -> name map
+  const tcID2Name = {};
+  if (body.messages && Array.isArray(body.messages)) {
+    for (const msg of body.messages) {
+      if (msg.role === ROLE.ASSISTANT && msg.tool_calls) {
+        for (const tc of msg.tool_calls) {
+          if (tc.type === OPENAI_BLOCK.FUNCTION && tc.id && tc.function?.name) {
+            tcID2Name[tc.id] = tc.function.name;
+          }
+        }
+      }
+    }
+  }
+
+  // Build tool responses cache
+  const toolResponses = {};
+  if (body.messages && Array.isArray(body.messages)) {
+    for (const msg of body.messages) {
+      if (msg.role === ROLE.TOOL && msg.tool_call_id) {
+        toolResponses[msg.tool_call_id] = msg.content;
+      }
+    }
+  }
+
+  // Convert messages
+  if (body.messages && Array.isArray(body.messages)) {
+    for (let i = 0; i < body.messages.length; i++) {
+      const msg = body.messages[i];
+      const role = msg.role;
+      const content = msg.content;
+
+      if (role === ROLE.SYSTEM && body.messages.length > 1) {
+        result.systemInstruction = {
+          role: GEMINI_ROLE.USER,
+          parts: [{ text: typeof content === "string" ? content : extractTextContent(content) }]
+        };
+      } else if (role === ROLE.USER || (role === ROLE.SYSTEM && body.messages.length === 1)) {
+        const parts = convertOpenAIContentToParts(content);
+        if (parts.length > 0) {
+          result.contents.push({ role: GEMINI_ROLE.USER, parts });
+        }
+      } else if (role === ROLE.ASSISTANT) {
+        const parts = [];
+
+        // Thinking/reasoning → thought part with signature
+        if (msg.reasoning_content) {
+          parts.push({
+            thought: true,
+            text: msg.reasoning_content
+          });
+          parts.push({
+            thoughtSignature: signature,
+            text: ""
+          });
+        }
+
+        if (content) {
+          const text = typeof content === "string" ? content : extractTextContent(content);
+          if (text) {
+            parts.push({ text });
+          }
+        }
+
+        if (msg.tool_calls && Array.isArray(msg.tool_calls)) {
+          const toolCallIds = [];
+          for (const tc of msg.tool_calls) {
+            if (tc.type !== OPENAI_BLOCK.FUNCTION) continue;
+
+            const args = tryParseJSON(tc.function?.arguments || "{}");
+            parts.push({
+              thoughtSignature: signature,
+              functionCall: {
+                id: tc.id,
+                name: sanitizeGeminiFunctionName(tc.function.name),
+                args: args
+              }
+            });
+            toolCallIds.push(tc.id);
+          }
+
+          if (parts.length > 0) {
+            result.contents.push({ role: GEMINI_ROLE.MODEL, parts });
+          }
+
+          // Check if there are actual tool responses in the next messages
+          const hasActualResponses = toolCallIds.some(fid => toolResponses[fid]);
+
+          if (hasActualResponses) {
+            const toolParts = [];
+            for (const fid of toolCallIds) {
+              if (!toolResponses[fid]) continue;
+
+              let name = tcID2Name[fid];
+              if (!name) {
+                const idParts = fid.split("-");
+                if (idParts.length > 2) {
+                  name = idParts.slice(0, -2).join("-");
+                } else {
+                  name = fid;
+                }
+              }
+
+              let resp = toolResponses[fid];
+              let parsedResp = tryParseJSON(resp);
+              if (parsedResp === null) {
+                parsedResp = { result: resp };
+              } else if (typeof parsedResp !== "object") {
+                parsedResp = { result: parsedResp };
+              }
+
+              toolParts.push({
+                functionResponse: {
+                  id: fid,
+                  name: sanitizeGeminiFunctionName(name),
+                  response: { result: parsedResp }
+                }
+              });
+            }
+            if (toolParts.length > 0) {
+              result.contents.push({ role: GEMINI_ROLE.USER, parts: toolParts });
+            }
+          }
+        } else if (parts.length > 0) {
+          result.contents.push({ role: GEMINI_ROLE.MODEL, parts });
+        }
+      }
+    }
+  }
+
+  // Convert tools
+  if (body.tools && Array.isArray(body.tools) && body.tools.length > 0) {
+    const functionDeclarations = [];
+    for (const t of body.tools) {
+      // Check if already in Anthropic/Claude format (no type field, direct name/description/input_schema)
+      if (t.name && t.input_schema) {
+        const cleanedSchema = cleanJSONSchemaForAntigravity(structuredClone(t.input_schema || { type: "object", properties: {} }));
+        functionDeclarations.push({
+          name: sanitizeGeminiFunctionName(t.name),
+          description: t.description || "",
+          parameters: cleanedSchema
+        });
+      }
+      // OpenAI format
+      else if (t.type === OPENAI_BLOCK.FUNCTION && t.function) {
+        const fn = t.function;
+        const cleanedSchema = cleanJSONSchemaForAntigravity(structuredClone(fn.parameters || { type: "object", properties: {} }));
+        functionDeclarations.push({
+          name: sanitizeGeminiFunctionName(fn.name),
+          description: fn.description || "",
+          parameters: cleanedSchema
+        });
+      }
+    }
+
+    if (functionDeclarations.length > 0) {
+      result.tools = [{ functionDeclarations }];
+    }
+  }
+
+  result.contents = normalizeGeminiContents(result.contents);
+  return result;
+}
+
+// OpenAI -> Gemini (standard API)
+export function openaiToGeminiRequest(model, body, stream) {
+  return openaiToGeminiBase(model, body, stream);
+}
+
+// OpenAI -> Gemini CLI (Cloud Code Assist)
+export function openaiToGeminiCLIRequest(model, body, stream) {
+  const gemini = openaiToGeminiBase(model, body, stream, DEFAULT_THINKING_GEMINI_CLI_SIGNATURE);
+  // Thinking is normalized centrally by applyThinking (thinkingUnified.js) after translation.
+
+  // Clean schema for tools
+  if (gemini.tools?.[0]?.functionDeclarations) {
+    for (const fn of gemini.tools[0].functionDeclarations) {
+      if (fn.parameters) {
+        const cleanedSchema = cleanJSONSchemaForAntigravity(fn.parameters);
+        fn.parameters = cleanedSchema;
+        // if (isClaude) {
+        //   fn.parameters = cleanedSchema;
+        // } else {
+        //   fn.parametersJsonSchema = cleanedSchema;
+        //   delete fn.parameters;
+        // }
+      }
+    }
+  }
+
+  return gemini;
+}
+
+// Wrap Gemini CLI format in Cloud Code wrapper
+function wrapInCloudCodeEnvelope(model, geminiCLI, credentials = null, isAntigravity = false) {
+  const projectId = credentials?.projectId || generateProjectId();
+
+  const envelope = {
+    project: projectId,
+    model: model,
+    userAgent: isAntigravity ? "antigravity" : "gemini-cli",
+    requestId: isAntigravity ? `agent-${generateUUID()}` : generateRequestId(),
+    request: {
+      sessionId: toNumericSessionId(credentials?._clientSessionId) || (isAntigravity ? deriveSessionId(credentials?.email || credentials?.connectionId) : generateSessionId()),
+      contents: geminiCLI.contents,
+      systemInstruction: geminiCLI.systemInstruction,
+      generationConfig: geminiCLI.generationConfig,
+      tools: geminiCLI.tools,
+    }
+  };
+
+  // Antigravity specific fields
+  if (isAntigravity) {
+    envelope.requestType = "agent";
+  } else {
+    // Keep safetySettings for Gemini CLI
+    envelope.request.safetySettings = geminiCLI.safetySettings;
+  }
+
+  if (geminiCLI.tools?.length > 0) {
+    envelope.request.toolConfig = {
+      functionCallingConfig: { mode: "VALIDATED" }
+    };
+  }
+
+  return envelope;
+}
+
+// Wrap Claude format in Cloud Code envelope for Antigravity
+function wrapInCloudCodeEnvelopeForClaude(model, claudeRequest, credentials = null, signature = DEFAULT_THINKING_AG_SIGNATURE) {
+  const projectId = credentials?.projectId || generateProjectId();
+
+  const envelope = {
+    project: projectId,
+    model: model,
+    userAgent: "antigravity",
+    requestId: `agent-${generateUUID()}`,
+    requestType: "agent",
+    request: {
+      sessionId: toNumericSessionId(credentials?._clientSessionId) || deriveSessionId(credentials?.email || credentials?.connectionId),
+      contents: [],
+      generationConfig: {
+        temperature: claudeRequest.temperature || 1,
+        maxOutputTokens: claudeRequest.max_tokens || 4096
+      }
+    }
+  };
+
+  // Build tool_use id -> name map so functionResponse can use the correct name
+  const toolUseIdToName = {};
+  if (claudeRequest.messages && Array.isArray(claudeRequest.messages)) {
+    for (const msg of claudeRequest.messages) {
+      if (Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+          if (block.type === CLAUDE_BLOCK.TOOL_USE && block.id && block.name) {
+            toolUseIdToName[block.id] = block.name;
+          }
+        }
+      }
+    }
+  }
+
+  // Convert Claude messages to Gemini contents
+  if (claudeRequest.messages && Array.isArray(claudeRequest.messages)) {
+    for (const msg of claudeRequest.messages) {
+      const parts = [];
+
+      if (Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+          if (block.type === CLAUDE_BLOCK.TEXT) {
+            parts.push({ text: block.text });
+          } else if (block.type === CLAUDE_BLOCK.TOOL_USE) {
+            parts.push({
+              thoughtSignature: signature,
+              functionCall: {
+                id: block.id,
+                name: sanitizeGeminiFunctionName(block.name),
+                args: block.input || {}
+              }
+            });
+          } else if (block.type === CLAUDE_BLOCK.TOOL_RESULT) {
+            let content = block.content;
+            if (Array.isArray(content)) {
+              content = content.map(c => c.type === CLAUDE_BLOCK.TEXT ? c.text : JSON.stringify(c)).join("\n");
+            }
+            // Resolve the original tool name from the id — Gemini requires it to match the functionCall name
+            const resolvedName = toolUseIdToName[block.tool_use_id]
+              ? sanitizeGeminiFunctionName(toolUseIdToName[block.tool_use_id])
+              : "tool";
+            parts.push({
+              functionResponse: {
+                id: block.tool_use_id,
+                name: resolvedName,
+                response: { result: tryParseJSON(content) || content }
+              }
+            });
+          }
+        }
+      } else if (typeof msg.content === "string") {
+        parts.push({ text: msg.content });
+      }
+
+      if (parts.length > 0) {
+        envelope.request.contents.push({
+          role: msg.role === ROLE.ASSISTANT ? GEMINI_ROLE.MODEL : GEMINI_ROLE.USER,
+          parts
+        });
+      }
+    }
+  }
+
+  // Convert Claude tools to Gemini functionDeclarations
+  if (claudeRequest.tools && Array.isArray(claudeRequest.tools)) {
+    const functionDeclarations = [];
+    for (const tool of claudeRequest.tools) {
+      if (tool.name && tool.input_schema) {
+        const cleanedSchema = cleanJSONSchemaForAntigravity(tool.input_schema);
+        functionDeclarations.push({
+          name: sanitizeGeminiFunctionName(tool.name),
+          description: tool.description || "",
+          parameters: cleanedSchema
+        });
+      }
+    }
+    if (functionDeclarations.length > 0) {
+      envelope.request.tools = [{ functionDeclarations }];
+      envelope.request.toolConfig = {
+        functionCallingConfig: { mode: "VALIDATED" }
+      };
+    }
+  }
+
+  const systemParts = [];
+  // Merge user system prompt from claudeRequest
+  if (claudeRequest.system) {
+    if (Array.isArray(claudeRequest.system)) {
+      for (const block of claudeRequest.system) {
+        if (block.text) systemParts.push({ text: block.text });
+      }
+    } else if (typeof claudeRequest.system === "string") {
+      systemParts.push({ text: claudeRequest.system });
+    }
+  }
+
+  if (systemParts.length > 0) {
+    envelope.request.systemInstruction = { role: GEMINI_ROLE.USER, parts: systemParts };
+  }
+
+  envelope.request.contents = normalizeGeminiContents(envelope.request.contents);
+  return envelope;
+}
+
+// Detect if model should use Claude backend in Antigravity
+// Claude models have specific ID patterns — more reliable than caps at routing level
+function isClaudeModel(model) {
+  return model.toLowerCase().includes("claude");
+}
+
+// OpenAI -> Antigravity (Sandbox Cloud Code with wrapper)
+export function openaiToAntigravityRequest(model, body, stream, credentials = null) {
+  if (isClaudeModel(model)) {
+    const claudeRequest = openaiToClaudeRequestForAntigravity(model, body, stream);
+    return wrapInCloudCodeEnvelopeForClaude(model, claudeRequest, credentials);
+  }
+
+  const geminiCLI = openaiToGeminiCLIRequest(model, body, stream);
+  return wrapInCloudCodeEnvelope(model, geminiCLI, credentials, true);
+}
+
+// Register
+register(FORMATS.OPENAI, FORMATS.GEMINI, openaiToGeminiRequest, null);
+register(FORMATS.OPENAI, FORMATS.GEMINI_CLI, (model, body, stream, credentials) => wrapInCloudCodeEnvelope(model, openaiToGeminiCLIRequest(model, body, stream), credentials), null);
+register(FORMATS.OPENAI, FORMATS.ANTIGRAVITY, openaiToAntigravityRequest, null);
diff --git a/open-sse/translator/request/openai-to-kiro.js b/open-sse/translator/request/openai-to-kiro.js
new file mode 100644
index 0000000..5c8cc00
--- /dev/null
+++ b/open-sse/translator/request/openai-to-kiro.js
@@ -0,0 +1,607 @@
+/**
+ * OpenAI to Kiro Request Translator
+ * Converts OpenAI Chat Completions format to Kiro/AWS CodeWhisperer format
+ */
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { v4 as uuidv4 } from "uuid";
+import { resolveSessionId } from "../../utils/sessionManager.js";
+import {
+  resolveKiroModel,
+  resolveKiroThinkingBudget,
+  buildThinkingSystemPrefix,
+  KIRO_AGENTIC_SYSTEM_PROMPT,
+  resolveDefaultProfileArn
+} from "../../config/kiroConstants.js";
+import { parseDataUri } from "../concerns/image.js";
+import { DEFAULT_IMAGE_MIME } from "../schema/index.js";
+import { ROLE, OPENAI_BLOCK, CLAUDE_BLOCK } from "../schema/index.js";
+
+/** Render a single tool call as a readable text line. */
+function toolCallToText(name, input) {
+  let argStr;
+  try {
+    argStr = typeof input === "string" ? input : JSON.stringify(input ?? {});
+  } catch {
+    argStr = "{}";
+  }
+  return `[Tool call: ${name || "unknown"}(${argStr})]`;
+}
+
+/** Render a tool result (string or content-block array) as a text line. */
+function toolResultToText(content) {
+  const text = Array.isArray(content)
+    ? content.map(c => (typeof c === "string" ? c : c.text || "")).join("\n")
+    : (typeof content === "string" ? content : "");
+  return `[Tool result: ${text}]`;
+}
+
+/**
+ * Flatten all tool calls/results in a conversation into plain text.
+ *
+ * Kiro's schema validator requires a non-empty
+ * currentMessage.userInputMessageContext.tools array whenever the history
+ * references any tool use; otherwise it returns "Improperly formed request"
+ * (HTTP 400). A client can hit this by omitting the `tools` array on a
+ * follow-up request — typically after client-side compaction (e.g. OpenCode).
+ *
+ * Rather than fabricate stub tool specs — which would advertise tool-calling
+ * capability the client never requested and may not handle, risking a phantom
+ * tool call on an otherwise plain turn — we collapse the tool interaction into
+ * text. The request stays honest, and since no structured tool content
+ * remains, the validator's "tools required" rule never fires.
+ *
+ * Only invoked when the client did NOT send tools; when tools are present the
+ * structured form is preserved.
+ */
+function flattenToolInteractions(messages) {
+  const out = [];
+
+  for (const msg of messages) {
+    // OpenAI tool-result message → user text line
+    if (msg.role === ROLE.TOOL) {
+      out.push({ role: ROLE.USER, content: toolResultToText(msg.content) });
+      continue;
+    }
+
+    if (msg.role === ROLE.ASSISTANT) {
+      const parts = [];
+      if (Array.isArray(msg.content)) {
+        for (const c of msg.content) {
+          if (c.type === CLAUDE_BLOCK.TOOL_USE) {
+            parts.push(toolCallToText(c.name, c.input));
+          } else if (c.type === OPENAI_BLOCK.TEXT || c.text) {
+            parts.push(c.text || "");
+          }
+        }
+      } else if (typeof msg.content === "string") {
+        parts.push(msg.content);
+      }
+      for (const tc of msg.tool_calls || []) {
+        parts.push(toolCallToText(tc.function?.name, tc.function?.arguments));
+      }
+      out.push({ role: ROLE.ASSISTANT, content: parts.filter(Boolean).join("\n") });
+      continue;
+    }
+
+    // User messages: replace tool_result blocks with text, keep text + images.
+    if (msg.role === ROLE.USER && Array.isArray(msg.content)) {
+      const newContent = msg.content.map(c =>
+        c.type === CLAUDE_BLOCK.TOOL_RESULT
+          ? { type: OPENAI_BLOCK.TEXT, text: toolResultToText(c.content) }
+          : c
+      );
+      out.push({ ...msg, content: newContent });
+      continue;
+    }
+
+    out.push(msg);
+  }
+
+  return out;
+}
+
+/**
+ * Reconcile orphaned toolResults — those whose toolUseId has no matching
+ * toolUse in any assistant message. This happens when client-side compaction
+ * truncates the conversation and removes the assistant message containing the
+ * tool_use, but keeps the user message with the corresponding tool_result.
+ *
+ * A dangling structured reference makes Kiro return 400, so it must be removed.
+ * But the client deliberately kept the result content through compaction, so
+ * rather than discard it we fold it back into the user message as text — the
+ * same shape flattenToolInteractions() produces. The 400 trigger (the
+ * structured reference) is gone; the content survives.
+ *
+ * `messages` is every carrier that can hold toolResults — both history items
+ * and the popped-out currentMessage (orphans can land on either).
+ */
+function reconcileOrphanedToolResults(history, currentMessage) {
+  // Phase 1: collect all valid toolUseIds from assistant messages in history.
+  // (currentMessage is always a user turn, so it carries no toolUses.)
+  const validIds = new Set();
+  for (const h of history) {
+    const arm = h.assistantResponseMessage;
+    if (!arm) continue;
+    for (const tu of arm.toolUses || []) {
+      if (tu.toolUseId) validIds.add(tu.toolUseId);
+    }
+  }
+
+  // Phase 2: across history + currentMessage, keep results with a matching
+  // toolUse and salvage the rest as text.
+  const carriers = currentMessage ? [...history, currentMessage] : history;
+  for (const item of carriers) {
+    const uim = item.userInputMessage;
+    const ctx = uim?.userInputMessageContext;
+    if (!ctx?.toolResults?.length) continue;
+
+    const kept = [];
+    const salvaged = [];
+    for (const tr of ctx.toolResults) {
+      if (validIds.has(tr.toolUseId)) {
+        kept.push(tr);
+      } else {
+        salvaged.push(toolResultToText(tr.content));
+      }
+    }
+
+    if (salvaged.length === 0) continue; // no orphans — leave untouched
+
+    // Fold orphaned result content into the user text so it is not lost
+    const extra = salvaged.join("\n");
+    uim.content = uim.content ? `${uim.content}\n\n${extra}` : extra;
+
+    ctx.toolResults = kept;
+    if (kept.length === 0 && !ctx.tools?.length) {
+      delete uim.userInputMessageContext;
+    }
+  }
+}
+
+/**
+ * Safely parse JSON string, returning fallback on failure.
+ */
+function safeJSONParse(str, fallback) {
+  if (typeof str !== "string") return str ?? fallback;
+  try { return JSON.parse(str); } catch { return fallback; }
+}
+
+/**
+ * Convert OpenAI messages to Kiro format
+ * Rules: system/tool/user -> user role, merge consecutive same roles.
+ *
+ * Returns { history, currentMessage }.
+ */
+function convertMessages(messages, tools, model) {
+  let history = [];
+  let currentMessage = null;
+
+  const clientProvidedTools = tools && tools.length > 0;
+
+  // When the client did not send tools, flatten any tool calls/results in the
+  // history into plain text (see flattenToolInteractions). This keeps the
+  // request honest and sidesteps Kiro's "tools required" 400, since no
+  // structured tool content survives to trigger it.
+  if (!clientProvidedTools) {
+    messages = flattenToolInteractions(messages);
+  }
+
+  let pendingUserContent = [];
+  let pendingAssistantContent = [];
+  let pendingToolResults = [];
+  let pendingImages = [];
+  let currentRole = null;
+  let toolsInjectedToFirstUserMsg = false;
+
+  const flushPending = () => {
+    if (currentRole === "user") {
+      const content = pendingUserContent.join("\n\n").trim() || "continue";
+      const userMsg = {
+        userInputMessage: {
+          content: content,
+          modelId: ""
+        }
+      };
+
+      // Attach images if present (Kiro API supports images field)
+      if (pendingImages.length > 0) {
+        userMsg.userInputMessage.images = pendingImages;
+      }
+
+      if (pendingToolResults.length > 0) {
+        userMsg.userInputMessage.userInputMessageContext = {
+          toolResults: pendingToolResults
+        };
+      }
+
+      // Add tools to the user message that has no preceding assistant messages,
+      // OR the first user message (whichever comes first after any opening
+      // assistant messages). We track whether any user message has already
+      // received tools via a flag on the history array.
+      if (clientProvidedTools && !toolsInjectedToFirstUserMsg) {
+        if (!userMsg.userInputMessage.userInputMessageContext) {
+          userMsg.userInputMessage.userInputMessageContext = {};
+        }
+        userMsg.userInputMessage.userInputMessageContext.tools = tools.map(t => {
+          const name = t.function?.name || t.name;
+          let description = t.function?.description || t.description || "";
+
+          if (!description.trim()) {
+            description = `Tool: ${name}`;
+          }
+
+          const schema = t.function?.parameters || t.parameters || t.input_schema || {};
+          // Normalize schema: Kiro requires required[] and proper type/properties
+          const normalizedSchema = Object.keys(schema).length === 0
+            ? { type: "object", properties: {}, required: [] }
+            : { ...schema, required: schema.required ?? [] };
+
+          return {
+            toolSpecification: {
+              name,
+              description,
+              inputSchema: { json: normalizedSchema }
+            }
+          };
+        });
+        toolsInjectedToFirstUserMsg = true;
+      }
+
+      history.push(userMsg);
+      currentMessage = userMsg;
+      pendingUserContent = [];
+      pendingToolResults = [];
+      pendingImages = [];
+    } else if (currentRole === "assistant") {
+      const content = pendingAssistantContent.join("\n\n").trim() || "...";
+      const assistantMsg = {
+        assistantResponseMessage: {
+          content: content
+        }
+      };
+      history.push(assistantMsg);
+      pendingAssistantContent = [];
+    }
+  };
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    let role = msg.role;
+
+    // Normalize: system/tool -> user
+    const wasSystem = role === ROLE.SYSTEM;
+    if (role === ROLE.SYSTEM || role === ROLE.TOOL) {
+      role = ROLE.USER;
+    }
+
+    // If role changes, flush pending
+    if (role !== currentRole && currentRole !== null) {
+      flushPending();
+    }
+    currentRole = role;
+
+    if (role === ROLE.USER) {
+      // Extract content
+      let content = "";
+      if (typeof msg.content === "string") {
+        content = msg.content;
+      } else if (Array.isArray(msg.content)) {
+        const textParts = [];
+        for (const c of msg.content) {
+          if (c.type === OPENAI_BLOCK.TEXT || c.text) {
+            textParts.push(c.text || "");
+          } else if (c.type === OPENAI_BLOCK.IMAGE_URL) {
+            // OpenAI format: image_url.url with data URI
+            const url = c.image_url?.url || "";
+            const parsed = parseDataUri(url);
+            if (parsed) {
+              const format = parsed.mimeType.split("/")[1] || parsed.mimeType;
+              pendingImages.push({ format, source: { bytes: parsed.base64 } });
+            } else if (url.startsWith("http://") || url.startsWith("https://")) {
+              // Kiro only supports base64 — fallback to URL text
+              textParts.push(`[Image: ${url}]`);
+            }
+          } else if (c.type === CLAUDE_BLOCK.IMAGE) {
+            // Claude format: source.type = "base64", source.media_type, source.data
+            if (c.source?.type === "base64" && c.source?.data) {
+              const mediaType = c.source.media_type || DEFAULT_IMAGE_MIME;
+              const format = mediaType.split("/")[1] || mediaType;
+              pendingImages.push({ format, source: { bytes: c.source.data } });
+            }
+          }
+        }
+        content = textParts.join("\n");
+
+        // Check for tool_result blocks
+        const toolResultBlocks = msg.content.filter(c => c.type === CLAUDE_BLOCK.TOOL_RESULT);
+        if (toolResultBlocks.length > 0) {
+          toolResultBlocks.forEach(block => {
+            const text = Array.isArray(block.content)
+              ? block.content.map(c => c.text || "").join("\n")
+              : (typeof block.content === "string" ? block.content : "");
+
+            pendingToolResults.push({
+              toolUseId: block.tool_use_id,
+              status: "success",
+              content: [{ text: text }]
+            });
+          });
+        }
+      }
+
+      // Handle tool role (from normalized)
+      if (msg.role === ROLE.TOOL) {
+        const toolContent = typeof msg.content === "string" ? msg.content : "";
+        pendingToolResults.push({
+          toolUseId: msg.tool_call_id,
+          status: "success",
+          content: [{ text: toolContent }]
+        });
+      } else if (content) {
+        // <instructions> tags: Claude models treat these as authoritative directives.
+        pendingUserContent.push(
+          wasSystem ? `<instructions>\n${content}\n</instructions>` : content
+        );
+      }
+    } else if (role === ROLE.ASSISTANT) {
+      // Extract text content and tool uses
+      let textContent = "";
+      let toolUses = [];
+
+      if (Array.isArray(msg.content)) {
+        const textBlocks = msg.content.filter(c => c.type === OPENAI_BLOCK.TEXT);
+        textContent = textBlocks.map(b => b.text).join("\n").trim();
+
+        const toolUseBlocks = msg.content.filter(c => c.type === CLAUDE_BLOCK.TOOL_USE);
+        toolUses = toolUseBlocks;
+      } else if (typeof msg.content === "string") {
+        textContent = msg.content.trim();
+      }
+
+      if (msg.tool_calls && msg.tool_calls.length > 0) {
+        toolUses = msg.tool_calls;
+      }
+
+      if (textContent) {
+        pendingAssistantContent.push(textContent);
+      }
+
+      // Store tool uses in last assistant message
+      if (toolUses.length > 0) {
+        // Flush to create assistant message with toolUses
+        flushPending();
+
+        const lastMsg = history[history.length - 1];
+        if (lastMsg?.assistantResponseMessage) {
+          lastMsg.assistantResponseMessage.toolUses = toolUses.map(tc => {
+            if (tc.function) {
+              return {
+                toolUseId: tc.id || uuidv4(),
+                name: tc.function.name,
+                input: safeJSONParse(tc.function.arguments, {})
+              };
+            } else {
+              return {
+                toolUseId: tc.id || uuidv4(),
+                name: tc.name,
+                input: tc.input || {}
+              };
+            }
+          });
+        }
+
+        currentRole = null;
+      }
+    }
+  }
+
+  // Flush remaining
+  if (currentRole !== null) {
+    flushPending();
+  }
+
+  // Pop last userInputMessage as currentMessage (search from end, skip trailing assistant messages)
+  for (let i = history.length - 1; i >= 0; i--) {
+    if (history[i].userInputMessage) {
+      currentMessage = history.splice(i, 1)[0];
+      break;
+    }
+  }
+
+  // Grab tools from first history item BEFORE cleanup removes them
+  const firstHistoryTools = history[0]?.userInputMessage?.userInputMessageContext?.tools;
+
+  // Clean up history for Kiro API compatibility
+  history.forEach(item => {
+    if (item.userInputMessage?.userInputMessageContext?.tools) {
+      delete item.userInputMessage.userInputMessageContext.tools;
+    }
+    if (item.userInputMessage?.userInputMessageContext &&
+        Object.keys(item.userInputMessage.userInputMessageContext).length === 0) {
+      delete item.userInputMessage.userInputMessageContext;
+    }
+    if (item.userInputMessage && !item.userInputMessage.modelId) {
+      item.userInputMessage.modelId = model;
+    }
+  });
+
+  // Merge consecutive user messages (Kiro requires alternating user/assistant)
+  // When merging, also combine userInputMessageContext fields so toolResults
+  // and images from the second message are not silently dropped.
+  const mergedHistory = [];
+  for (let i = 0; i < history.length; i++) {
+    const current = history[i];
+    if (current.userInputMessage &&
+        mergedHistory.length > 0 &&
+        mergedHistory[mergedHistory.length - 1].userInputMessage) {
+      const prev = mergedHistory[mergedHistory.length - 1];
+      prev.userInputMessage.content += "\n\n" + current.userInputMessage.content;
+      // Merge context: combine toolResults, images, etc.
+      const prevCtx = prev.userInputMessage.userInputMessageContext;
+      const curCtx = current.userInputMessage.userInputMessageContext;
+      if (curCtx) {
+        if (!prevCtx) {
+          prev.userInputMessage.userInputMessageContext = curCtx;
+        } else {
+          if (curCtx.toolResults?.length > 0) {
+            prevCtx.toolResults = [...(prevCtx.toolResults || []), ...curCtx.toolResults];
+          }
+          if (curCtx.tools?.length > 0) {
+            prevCtx.tools = [...(prevCtx.tools || []), ...curCtx.tools];
+          }
+        }
+      }
+    } else {
+      mergedHistory.push(current);
+    }
+  }
+
+  // When currentMessage is null (no user messages at all — edge case where
+  // input is only assistant messages), create a minimal currentMessage so
+  // tools and content can be injected.
+  if (!currentMessage) {
+    currentMessage = {
+      userInputMessage: {
+        content: "",
+        modelId: model,
+      }
+    };
+  }
+
+  // Reconcile orphaned toolResults across history AND currentMessage — when
+  // client-side compaction removes assistant messages containing tool_use but
+  // keeps the tool_result, the dangling reference triggers a Kiro 400. Fold the
+  // content back into the user text instead of discarding it. Run after
+  // currentMessage is finalized (an orphan can be merged into it) and before
+  // tool injection (which may re-add userInputMessageContext).
+  //
+  // Only needed on the tools-present path: when the client sent no tools,
+  // flattenToolInteractions already collapsed every toolResult to text, so
+  // there is nothing structured left to orphan.
+  if (clientProvidedTools) {
+    reconcileOrphanedToolResults(mergedHistory, currentMessage);
+  }
+
+  // Inject tools into currentMessage AFTER cleanup. Tools only exist here when
+  // the client explicitly sent them (otherwise flattenToolInteractions already
+  // collapsed all tool content to text upstream, so there is nothing to carry).
+  const resolvedTools = firstHistoryTools;
+
+  if (resolvedTools?.length > 0 &&
+      !currentMessage.userInputMessage.userInputMessageContext?.tools) {
+    if (!currentMessage.userInputMessage.userInputMessageContext) {
+      currentMessage.userInputMessage.userInputMessageContext = {};
+    }
+    currentMessage.userInputMessage.userInputMessageContext.tools = resolvedTools;
+  }
+
+  return { history: mergedHistory, currentMessage };
+}
+
+/**
+ * Build Kiro payload from OpenAI format
+ *
+ * Two 9router-specific behaviours implemented here:
+ *
+ * 1. `-agentic` model suffix. Synthetic variant — same upstream model, but we
+ *    inject a chunked-write system prompt to keep large file writes under
+ *    Kiro's 2-3 minute server timeout. The suffix is stripped before being
+ *    sent upstream.
+ *
+ * 2. Thinking / reasoning. Kiro does not accept `thinking.type` or
+ *    `reasoning_effort` natively. The only way to enable reasoning is to
+ *    inject `<thinking_mode>enabled</thinking_mode>` into the user content
+ *    sent upstream. Detection covers Anthropic-Beta header, Claude API
+ *    `thinking`, OpenAI `reasoning_effort`, AMP/Cursor magic tags, and model
+ *    name hints.
+ */
+export function openaiToKiroRequest(model, body, stream, credentials) {
+  const messages = body.messages || [];
+  const tools = body.tools || [];
+  const maxTokens = 32000;
+  const temperature = body.temperature;
+  const topP = body.top_p;
+
+  const { upstream: upstreamModel, agentic } = resolveKiroModel(model);
+  const thinkingBudget = resolveKiroThinkingBudget(body, credentials?.rawHeaders, model);
+
+  const { history, currentMessage } = convertMessages(messages, tools, upstreamModel);
+
+  // API-key (headless) auth uses a raw CodeWhisperer credential whose profile is
+  // account-specific. Injecting the shared builder-id/social *default* placeholder
+  // ARN makes CodeWhisperer reject the request with 403 "bearer token invalid"
+  // (the ARN doesn't belong to the key's account). So for api_key, only send a
+  // profileArn that was actually resolved for this connection — never the default.
+  // OAuth/social keep the default fallback (their tokens accept it).
+  // api_key / idc / external_idp carry an account-specific (or token-bound)
+  // profile. The shared builder-id/social default ARN belongs to a different
+  // account and triggers 403 "bearer token invalid", so never fall back to it —
+  // send the resolved ARN, or an empty string so CodeWhisperer uses the token's
+  // own default profile. Only OAuth/social keep the shared placeholder.
+  const authMethod = credentials?.providerSpecificData?.authMethod;
+  const accountBoundAuth =
+    authMethod === "api_key" || authMethod === "idc" || authMethod === "external_idp";
+  const profileArn = accountBoundAuth
+    ? (credentials?.providerSpecificData?.profileArn || "")
+    : (credentials?.providerSpecificData?.profileArn || resolveDefaultProfileArn(authMethod));
+
+  let finalContent = currentMessage?.userInputMessage?.content || "";
+
+  const timestamp = new Date().toISOString();
+
+  // Build the system-prompt prefix that goes ABOVE the user message body.
+  // Order: thinking_mode tag first (so Kiro sees it before any user text),
+  // then context/timestamp marker, then optional agentic chunked-write prompt.
+  const prefixParts = [];
+  if (thinkingBudget !== null) {
+    prefixParts.push(buildThinkingSystemPrefix(thinkingBudget));
+  }
+  prefixParts.push(`[Context: Current time is ${timestamp}]`);
+  if (agentic) {
+    prefixParts.push(KIRO_AGENTIC_SYSTEM_PROMPT);
+  }
+  finalContent = `${prefixParts.join("\n\n")}\n\n${finalContent}`;
+
+  const payload = {
+    conversationState: {
+      chatTriggerType: "MANUAL",
+      conversationId: resolveSessionId({ headers: credentials?.rawHeaders, body, connectionId: credentials?.connectionId, scope: "kiro" }),
+      currentMessage: {
+        userInputMessage: {
+          content: finalContent,
+          modelId: upstreamModel,
+          origin: "AI_EDITOR",
+          ...(currentMessage?.userInputMessage?.images?.length > 0 && {
+            images: currentMessage.userInputMessage.images
+          }),
+          ...(currentMessage?.userInputMessage?.userInputMessageContext && {
+            userInputMessageContext: currentMessage.userInputMessage.userInputMessageContext
+          })
+        }
+      },
+      history: history
+    }
+  };
+
+  if (profileArn) {
+    payload.profileArn = profileArn;
+  }
+
+  if (maxTokens || temperature !== undefined || topP !== undefined) {
+    payload.inferenceConfig = {};
+    if (maxTokens) payload.inferenceConfig.maxTokens = maxTokens;
+    if (temperature !== undefined) payload.inferenceConfig.temperature = temperature;
+    if (topP !== undefined) payload.inferenceConfig.topP = topP;
+  }
+
+  // Tag payload so the executor can route the upstream model id correctly.
+  Object.defineProperty(payload, "_kiroUpstreamModel", {
+    value: upstreamModel,
+    enumerable: false
+  });
+
+  return payload;
+}
+
+register(FORMATS.OPENAI, FORMATS.KIRO, openaiToKiroRequest, null);
diff --git a/open-sse/translator/request/openai-to-ollama.js b/open-sse/translator/request/openai-to-ollama.js
new file mode 100644
index 0000000..9ecdb67
--- /dev/null
+++ b/open-sse/translator/request/openai-to-ollama.js
@@ -0,0 +1,195 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { parseDataUri } from "../concerns/image.js";
+import { safeParseJSON } from "../concerns/json.js";
+import { ROLE, OPENAI_BLOCK } from "../schema/index.js";
+
+/**
+ * Convert OpenAI request to Ollama format
+ *
+ * Ollama expects:
+ * - model: string
+ * - messages: Array<{role: string, content: string, images?: string[] }>
+ * - stream: boolean
+ * - options?: {temperature?: number, num_predict?: number}
+ *
+ * Key differences from OpenAI:
+ * - Content must be string, not array
+ * - Multimodal images should be mapped to `message.images[]` (raw base64, no data: prefix)
+ * - tool role maps to tool (Ollama supports tool messages)
+ */
+export function openaiToOllamaRequest(model, body, stream) {
+  const result = {
+    model: model,
+    messages: normalizeMessages(body.messages),
+    stream: stream
+  };
+
+  // Temperature
+  if (body.temperature !== undefined) {
+    result.options = result.options || {};
+    result.options.temperature = body.temperature;
+  }
+
+  // Max tokens (Ollama uses num_predict)
+  if (body.max_tokens !== undefined) {
+    result.options = result.options || {};
+    result.options.num_predict = body.max_tokens;
+  }
+
+  // Top_p
+  if (body.top_p !== undefined) {
+    result.options = result.options || {};
+    result.options.top_p = body.top_p;
+  }
+
+  // Tools (Ollama supports tools in OpenAI format)
+  if (body.tools && Array.isArray(body.tools)) {
+    result.tools = body.tools;
+  }
+
+  // Tool choice
+  if (body.tool_choice) {
+    result.tool_choice = body.tool_choice;
+  }
+
+  return result;
+}
+
+/**
+ * Normalize messages to Ollama format
+ * - Content must be string
+ * - tool messages: convert tool_call_id to tool_name
+ * - assistant messages: keep tool_calls as-is
+ */
+function normalizeMessages(messages) {
+  if (!Array.isArray(messages)) return messages;
+
+  const result = [];
+  const toolCallMap = new Map(); // Map tool_call_id -> tool_name
+
+  // First pass: build tool_call_id -> tool_name map from assistant messages
+  for (const msg of messages) {
+    if (msg.role === ROLE.ASSISTANT && msg.tool_calls) {
+      for (const tc of msg.tool_calls) {
+        if (tc.id && tc.function?.name) {
+          toolCallMap.set(tc.id, tc.function.name);
+        }
+      }
+    }
+  }
+
+  // Second pass: convert messages
+  for (const msg of messages) {
+    // Handle tool result messages (OpenAI format -> Ollama format)
+    if (msg.role === ROLE.TOOL) {
+      const toolResult = normalizeContent(msg.content);
+      if (!toolResult) continue;
+
+      // Get tool_name from map or use msg.name as fallback
+      const toolName = toolCallMap.get(msg.tool_call_id) || msg.name || "unknown_tool";
+
+      result.push({
+        role: ROLE.TOOL,
+        tool_name: toolName,
+        content: toolResult
+      });
+      continue;
+    }
+
+    // Handle assistant messages with tool_calls
+    if (msg.role === ROLE.ASSISTANT && msg.tool_calls) {
+      const content = normalizeContent(msg.content) || "";
+      
+      // Convert OpenAI tool_calls format to Ollama format
+      const ollamaToolCalls = msg.tool_calls.map(tc => ({
+        type: OPENAI_BLOCK.FUNCTION,
+        function: {
+          index: tc.index || 0,
+          name: tc.function?.name || "",
+          arguments: typeof tc.function?.arguments === "string" 
+            ? safeParseJSON(tc.function.arguments || "{}", {})
+            : tc.function?.arguments || {}
+        }
+      }));
+
+      result.push({
+        role: ROLE.ASSISTANT,
+        content: content,
+        tool_calls: ollamaToolCalls
+      });
+      continue;
+    }
+
+    // Normal messages
+    const role = msg.role;
+    const content = normalizeContent(msg.content);
+    const images = extractImagesFromContent(msg.content);
+
+    // Skip empty messages (except assistant)
+    if (!content && role !== ROLE.ASSISTANT) continue;
+
+    const out = {
+      role: role,
+      content: content
+    };
+
+    if (images.length > 0) {
+      out.images = images;
+    }
+
+    result.push(out);
+  }
+
+  return result;
+}
+
+/**
+ * Normalize content to string
+ * Ollama only accepts string content
+ */
+function normalizeContent(content) {
+  if (typeof content === "string") {
+    return content;
+  }
+
+  if (Array.isArray(content)) {
+    // Extract text from content array
+    const textParts = content
+      .filter(block => block && block.type === OPENAI_BLOCK.TEXT && block.text)
+      .map(block => block.text);
+
+    return textParts.join("\n") || "";
+  }
+
+  return "";
+}
+
+/**
+ * Extract base64 images from OpenAI multimodal content blocks.
+ * OpenAI image block format:
+ *   { type: "image_url", image_url: { url: "data:image/png;base64,..." } }
+ * Ollama expects raw base64 strings in message.images[].
+ */
+function extractImagesFromContent(content) {
+  if (!Array.isArray(content)) return [];
+
+  const images = [];
+
+  for (const block of content) {
+    if (!block || block.type !== OPENAI_BLOCK.IMAGE_URL) continue;
+
+    const url = typeof block.image_url === "string" ? block.image_url : block.image_url?.url;
+    if (typeof url !== "string" || !url) continue;
+
+    const parsed = parseDataUri(url);
+    if (!parsed) continue;
+
+    images.push(parsed.base64);
+  }
+
+  return images;
+}
+
+// Register translator
+register(FORMATS.OPENAI, FORMATS.OLLAMA, openaiToOllamaRequest, null);
diff --git a/open-sse/translator/request/openai-to-vertex.js b/open-sse/translator/request/openai-to-vertex.js
new file mode 100644
index 0000000..8fe8e63
--- /dev/null
+++ b/open-sse/translator/request/openai-to-vertex.js
@@ -0,0 +1,42 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { openaiToGeminiRequest } from "./openai-to-gemini.js";
+import { DEFAULT_THINKING_VERTEX_SIGNATURE } from "../../config/defaultThinkingSignature.js";
+
+/**
+ * Post-process a Gemini-format body for Vertex AI compatibility:
+ *
+ * 1. Replace all synthetic thoughtSignatures with Vertex-native signature.
+ * 2. Strip `id` from functionCall and functionResponse (Vertex rejects these).
+ */
+function postProcessForVertex(body) {
+  if (!body?.contents) return body;
+
+  for (const turn of body.contents) {
+    if (!Array.isArray(turn.parts)) continue;
+
+    for (const part of turn.parts) {
+      // Replace any synthetic signature with Vertex-native one
+      if (part.thoughtSignature !== undefined) {
+        part.thoughtSignature = DEFAULT_THINKING_VERTEX_SIGNATURE;
+      }
+      // Strip id from functionCall
+      if (part.functionCall && "id" in part.functionCall) {
+        delete part.functionCall.id;
+      }
+      // Strip id from functionResponse
+      if (part.functionResponse && "id" in part.functionResponse) {
+        delete part.functionResponse.id;
+      }
+    }
+  }
+
+  return body;
+}
+
+export function openaiToVertexRequest(model, body, stream, credentials) {
+  const gemini = openaiToGeminiRequest(model, body, stream, credentials);
+  return postProcessForVertex(gemini);
+}
+
+register(FORMATS.OPENAI, FORMATS.VERTEX, openaiToVertexRequest, null);
diff --git a/open-sse/translator/response/claude-to-openai.js b/open-sse/translator/response/claude-to-openai.js
new file mode 100644
index 0000000..4651d3c
--- /dev/null
+++ b/open-sse/translator/response/claude-to-openai.js
@@ -0,0 +1,195 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { ROLE, OPENAI_BLOCK, CLAUDE_BLOCK, OPENAI_FINISH } from "../schema/index.js";
+import { buildChunk } from "../concerns/chunk.js";
+import { toOpenAIUsage } from "../concerns/usage.js";
+import { reasoningDelta } from "../concerns/reasoning.js";
+import { toOpenAIFinish } from "../concerns/finishReason.js";
+
+// Create OpenAI chunk helper
+function createChunk(state, delta, finishReason = null) {
+  return buildChunk(
+    { id: `chatcmpl-${state.messageId}`, created: Math.floor(Date.now() / 1000), model: state.model },
+    delta,
+    finishReason
+  );
+}
+
+// Convert Claude stream chunk to OpenAI format
+export function claudeToOpenAIResponse(chunk, state) {
+  if (!chunk) return null;
+
+  const results = [];
+  const event = chunk.type;
+
+  switch (event) {
+    case "message_start": {
+      state.messageId = chunk.message?.id || `msg_${Date.now()}`;
+      state.model = chunk.message?.model;
+      state.toolCallIndex = 0;
+      // Claude sends input_tokens + cache_read + cache_creation here; message_delta
+      // later carries only the final output_tokens. Capture cache now so the
+      // delta (output-only) doesn't reset it to zero.
+      const startUsage = chunk.message?.usage;
+      if (startUsage && typeof startUsage === "object") {
+        const inputTokens = typeof startUsage.input_tokens === "number" ? startUsage.input_tokens : 0;
+        const cacheReadTokens = typeof startUsage.cache_read_input_tokens === "number" ? startUsage.cache_read_input_tokens : 0;
+        const cacheCreationTokens = typeof startUsage.cache_creation_input_tokens === "number" ? startUsage.cache_creation_input_tokens : 0;
+        const promptTokens = inputTokens + cacheReadTokens + cacheCreationTokens;
+        state.usage = {
+          prompt_tokens: promptTokens,
+          completion_tokens: 0,
+          total_tokens: promptTokens,
+          input_tokens: inputTokens,
+          output_tokens: 0
+        };
+        if (cacheReadTokens > 0) state.usage.cache_read_input_tokens = cacheReadTokens;
+        if (cacheCreationTokens > 0) state.usage.cache_creation_input_tokens = cacheCreationTokens;
+      }
+      results.push(createChunk(state, { role: ROLE.ASSISTANT }));
+      break;
+    }
+
+    case "content_block_start": {
+      const block = chunk.content_block;
+      if (block?.type === "server_tool_use") {
+        // Built-in tool (web search) - Claude handles internally, skip
+        state.serverToolBlockIndex = chunk.index;
+        break;
+      }
+      if (block?.type === CLAUDE_BLOCK.TEXT) {
+        state.textBlockStarted = true;
+      } else if (block?.type === CLAUDE_BLOCK.THINKING) {
+        state.inThinkingBlock = true;
+        state.currentBlockIndex = chunk.index;
+        results.push(createChunk(state, { content: "<think>" }));
+      } else if (block?.type === CLAUDE_BLOCK.TOOL_USE) {
+        const toolCallIndex = state.toolCallIndex++;
+        // Restore original tool name from mapping (Claude OAuth)
+        const toolName = state.toolNameMap?.get(block.name) || block.name;
+        const toolCall = {
+          index: toolCallIndex,
+          id: block.id,
+          type: OPENAI_BLOCK.FUNCTION,
+          function: {
+            name: toolName,
+            arguments: ""
+          }
+        };
+        state.toolCalls.set(chunk.index, toolCall);
+        results.push(createChunk(state, { tool_calls: [toolCall] }));
+      }
+      break;
+    }
+
+    case "content_block_delta": {
+      // Skip deltas for built-in server tool blocks (web search)
+      if (chunk.index === state.serverToolBlockIndex) break;
+      const delta = chunk.delta;
+      if (delta?.type === "text_delta" && delta.text) {
+        results.push(createChunk(state, { content: delta.text }));
+      } else if (delta?.type === "thinking_delta" && delta.thinking) {
+        results.push(createChunk(state, reasoningDelta(delta.thinking)));
+      } else if (delta?.type === "input_json_delta" && delta.partial_json) {
+        const toolCall = state.toolCalls.get(chunk.index);
+        if (toolCall) {
+          toolCall.function.arguments += delta.partial_json;
+          results.push(createChunk(state, {
+            tool_calls: [{
+              index: toolCall.index,
+              id: toolCall.id,
+              function: { arguments: delta.partial_json }
+            }]
+          }));
+        }
+      }
+      break;
+    }
+
+    case "content_block_stop": {
+      // Skip stop for built-in server tool blocks (web search)
+      if (chunk.index === state.serverToolBlockIndex) {
+        state.serverToolBlockIndex = -1;
+        break;
+      }
+      if (state.inThinkingBlock && chunk.index === state.currentBlockIndex) {
+        results.push(createChunk(state, { content: "</think>" }));
+        state.inThinkingBlock = false;
+      }
+      state.textBlockStarted = false;
+      state.thinkingBlockStarted = false;
+      break;
+    }
+
+    case "message_delta": {
+      // Extract usage from message_delta event (Claude native format).
+      // Anthropic sends input/cache in message_start and only output here, so
+      // fall back to cache captured in message_start when the delta omits it.
+      if (chunk.usage && typeof chunk.usage === "object") {
+        const prev = state.usage || {};
+        const inputTokens = typeof chunk.usage.input_tokens === "number" ? chunk.usage.input_tokens : (prev.input_tokens || 0);
+        const outputTokens = typeof chunk.usage.output_tokens === "number" ? chunk.usage.output_tokens : 0;
+        const cacheReadTokens = typeof chunk.usage.cache_read_input_tokens === "number" ? chunk.usage.cache_read_input_tokens : (prev.cache_read_input_tokens || 0);
+        const cacheCreationTokens = typeof chunk.usage.cache_creation_input_tokens === "number" ? chunk.usage.cache_creation_input_tokens : (prev.cache_creation_input_tokens || 0);
+
+        // prompt_tokens = input_tokens + cache_read + cache_creation (all prompt-side tokens)
+        const promptTokens = inputTokens + cacheReadTokens + cacheCreationTokens;
+
+        state.usage = {
+          prompt_tokens: promptTokens,
+          completion_tokens: outputTokens,
+          total_tokens: promptTokens + outputTokens,
+          input_tokens: inputTokens,
+          output_tokens: outputTokens
+        };
+
+        if (cacheReadTokens > 0) state.usage.cache_read_input_tokens = cacheReadTokens;
+        if (cacheCreationTokens > 0) state.usage.cache_creation_input_tokens = cacheCreationTokens;
+      }
+
+      if (chunk.delta?.stop_reason) {
+        state.finishReason = convertStopReason(chunk.delta.stop_reason);
+        const finalChunk = createChunk(state, {}, state.finishReason);
+
+        if (state.usage) {
+          // Build OpenAI usage from the merged state (cache from message_start +
+          // output from message_delta), not the delta chunk alone.
+          finalChunk.usage = toOpenAIUsage({
+            input_tokens: state.usage.input_tokens || 0,
+            output_tokens: state.usage.output_tokens || 0,
+            cache_read_input_tokens: state.usage.cache_read_input_tokens,
+            cache_creation_input_tokens: state.usage.cache_creation_input_tokens
+          }, "claude");
+        }
+
+        results.push(finalChunk);
+        state.finishReasonSent = true;
+      }
+      break;
+    }
+
+    case "message_stop": {
+      if (!state.finishReasonSent) {
+        const finishReason = state.finishReason || (state.toolCalls?.size > 0 ? OPENAI_FINISH.TOOL_CALLS : OPENAI_FINISH.STOP);
+        const usageObj = (state.usage && typeof state.usage === 'object') ? {
+          usage: {
+            prompt_tokens: state.usage.input_tokens || 0,
+            completion_tokens: state.usage.output_tokens || 0,
+            total_tokens: (state.usage.input_tokens || 0) + (state.usage.output_tokens || 0)
+          }
+        } : {};
+        results.push({ ...createChunk(state, {}, finishReason), ...usageObj });
+        state.finishReasonSent = true;
+      }
+      break;
+    }
+  }
+
+  return results.length > 0 ? results : null;
+}
+
+const convertStopReason = (reason) => toOpenAIFinish(reason, "claude");
+
+// Register
+register(FORMATS.CLAUDE, FORMATS.OPENAI, null, claudeToOpenAIResponse);
+
diff --git a/open-sse/translator/response/commandcode-to-openai.js b/open-sse/translator/response/commandcode-to-openai.js
new file mode 100644
index 0000000..ab3d7d7
--- /dev/null
+++ b/open-sse/translator/response/commandcode-to-openai.js
@@ -0,0 +1,184 @@
+/**
+ * CommandCode → OpenAI response translator
+ *
+ * CommandCode upstream emits NDJSON-style AI SDK v5 stream events:
+ *   {"type":"start"} {"type":"start-step", ...}
+ *   {"type":"reasoning-start","id":"..."} {"type":"reasoning-delta","text":"..."}
+ *   {"type":"text-start","id":"..."}     {"type":"text-delta","text":"..."}
+ *   {"type":"tool-input-start","id","toolName"}
+ *   {"type":"tool-input-delta","id","delta"}
+ *   {"type":"tool-input-end","id"}
+ *   {"type":"tool-call","toolCallId","toolName","input"}
+ *   {"type":"finish-step","finishReason","usage": {...}, ...}
+ *   {"type":"finish",...}
+ *
+ * Each upstream "event" arrives as one JSON object per line — we receive it as a string chunk
+ * already split per line by the upstream SSE/JSON-line reader in 9router.
+ */
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { ROLE, OPENAI_BLOCK, OPENAI_FINISH } from "../schema/index.js";
+import { buildChunk } from "../concerns/chunk.js";
+import { toOpenAIUsage } from "../concerns/usage.js";
+import { reasoningDelta } from "../concerns/reasoning.js";
+import { fallbackToolCallId } from "../concerns/toolCall.js";
+import { toOpenAIFinish } from "../concerns/finishReason.js";
+
+function ensureState(state, model) {
+  if (!state.responseId) {
+    state.responseId = `chatcmpl-${Date.now()}`;
+    state.created = Math.floor(Date.now() / 1000);
+    state.model = state.model || model || "commandcode";
+    state.chunkIndex = 0;
+    state.toolIndex = 0;
+    state.toolIndexById = new Map();
+    state.openTools = new Set();
+    state.openText = false;
+    state.finishReason = null;
+    state.usage = null;
+  }
+}
+
+function makeChunk(state, delta, finishReason = null) {
+  return buildChunk(
+    { id: state.responseId, created: state.created, model: state.model },
+    delta,
+    finishReason
+  );
+}
+
+const mapFinishReason = (reason) => toOpenAIFinish(reason, "commandcode");
+
+export function commandCodeToOpenAIResponse(chunk, state) {
+  if (!chunk) return null;
+
+  // Already-OpenAI chunk: pass through
+  if (chunk && typeof chunk === "object" && chunk.object === "chat.completion.chunk") {
+    return chunk;
+  }
+
+  // Parse string lines coming out of upstream
+  let event = chunk;
+  if (typeof chunk === "string") {
+    const line = chunk.trim();
+    if (!line) return null;
+    // Tolerate raw "data: {...}" framing if the upstream wrapper inserts it
+    const json = line.startsWith("data:") ? line.slice(5).trim() : line;
+    if (!json || json === "[DONE]") return null;
+    try {
+      event = JSON.parse(json);
+    } catch {
+      return null;
+    }
+  }
+
+  if (!event || typeof event !== "object" || !event.type) return null;
+
+  ensureState(state, event.model);
+  const out = [];
+
+  switch (event.type) {
+    case "text-delta": {
+      const text = event.text || event.delta || "";
+      if (!text) break;
+      const delta = state.chunkIndex === 0 ? { role: ROLE.ASSISTANT, content: text } : { content: text };
+      state.chunkIndex++;
+      state.openText = true;
+      out.push(makeChunk(state, delta));
+      break;
+    }
+    case "reasoning-delta": {
+      const text = event.text || "";
+      if (!text) break;
+      // Map reasoning to OpenAI "reasoning_content" field (used by deepseek-reasoner-style clients).
+      const delta = reasoningDelta(text, state.chunkIndex === 0);
+      state.chunkIndex++;
+      out.push(makeChunk(state, delta));
+      break;
+    }
+    case "tool-input-start": {
+      const id = event.id || event.toolCallId || fallbackToolCallId(state.toolIndex);
+      let idx = state.toolIndexById.get(id);
+      if (idx == null) {
+        idx = state.toolIndex++;
+        state.toolIndexById.set(id, idx);
+      }
+      state.openTools.add(id);
+      const delta = {
+        ...(state.chunkIndex === 0 ? { role: ROLE.ASSISTANT } : {}),
+        tool_calls: [{
+          index: idx,
+          id,
+          type: OPENAI_BLOCK.FUNCTION,
+          function: { name: event.toolName || "", arguments: "" },
+        }],
+      };
+      state.chunkIndex++;
+      out.push(makeChunk(state, delta));
+      break;
+    }
+    case "tool-input-delta": {
+      const id = event.id || event.toolCallId;
+      const idx = state.toolIndexById.get(id);
+      if (idx == null) break;
+      const delta = {
+        tool_calls: [{
+          index: idx,
+          function: { arguments: event.delta || event.inputTextDelta || "" },
+        }],
+      };
+      out.push(makeChunk(state, delta));
+      break;
+    }
+    case "tool-call": {
+      // Final consolidated tool call — only emit if we never saw tool-input-* deltas.
+      const id = event.toolCallId;
+      if (state.toolIndexById.has(id)) break;
+      const idx = state.toolIndex++;
+      state.toolIndexById.set(id, idx);
+      const argsStr = typeof event.input === "string" ? event.input : JSON.stringify(event.input ?? {});
+      const delta = {
+        ...(state.chunkIndex === 0 ? { role: ROLE.ASSISTANT } : {}),
+        tool_calls: [{
+          index: idx,
+          id,
+          type: OPENAI_BLOCK.FUNCTION,
+          function: { name: event.toolName || "", arguments: argsStr },
+        }],
+      };
+      state.chunkIndex++;
+      out.push(makeChunk(state, delta));
+      break;
+    }
+    case "finish-step": {
+      state.finishReason = mapFinishReason(event.finishReason);
+      if (event.usage) state.usage = event.usage;
+      break;
+    }
+    case "finish": {
+      const finishReason = state.finishReason || mapFinishReason(event.finishReason || "stop");
+      const finalChunk = makeChunk(state, {}, finishReason);
+      const totalUsage = event.totalUsage || state.usage;
+      const usage = toOpenAIUsage(totalUsage, "commandcode");
+      if (usage) finalChunk.usage = usage;
+      out.push(finalChunk);
+      break;
+    }
+    case "error": {
+      state.finishReason = OPENAI_FINISH.STOP;
+      const errVal = event.error ?? event.message ?? "unknown";
+      const errStr = typeof errVal === "string" ? errVal : JSON.stringify(errVal);
+      out.push(makeChunk(state, { content: `\n\n[CommandCode error: ${errStr}]` }));
+      out.push(makeChunk(state, {}, OPENAI_FINISH.STOP));
+      break;
+    }
+    // Silently ignore: start, start-step, reasoning-start, reasoning-end, text-start, text-end,
+    // provider-metadata, message-metadata, etc. They carry no client-visible content.
+    default:
+      break;
+  }
+
+  return out.length ? out : null;
+}
+
+register(FORMATS.COMMANDCODE, FORMATS.OPENAI, null, commandCodeToOpenAIResponse);
diff --git a/open-sse/translator/response/cursor-to-openai.js b/open-sse/translator/response/cursor-to-openai.js
new file mode 100644
index 0000000..012abcc
--- /dev/null
+++ b/open-sse/translator/response/cursor-to-openai.js
@@ -0,0 +1,30 @@
+/**
+ * Cursor to OpenAI Response Translator
+ * CursorExecutor already emits OpenAI format - this is a passthrough
+ */
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+
+/**
+ * Convert Cursor response to OpenAI format
+ * Since CursorExecutor.transformProtobufToSSE/JSON already emits OpenAI chunks,
+ * this is a passthrough translator (similar to Kiro pattern)
+ */
+export function cursorToOpenAIResponse(chunk, state) {
+  if (!chunk) return null;
+
+  // If chunk is already in OpenAI format (from executor transform), return as-is
+  if (chunk.object === "chat.completion.chunk" && chunk.choices) {
+    return chunk;
+  }
+
+  // If chunk is a completion object (non-streaming), return as-is
+  if (chunk.object === "chat.completion" && chunk.choices) {
+    return chunk;
+  }
+
+  // Fallback: return chunk as-is (should not reach here)
+  return chunk;
+}
+
+register(FORMATS.CURSOR, FORMATS.OPENAI, null, cursorToOpenAIResponse);
diff --git a/open-sse/translator/response/gemini-to-openai.js b/open-sse/translator/response/gemini-to-openai.js
new file mode 100644
index 0000000..8f04ffd
--- /dev/null
+++ b/open-sse/translator/response/gemini-to-openai.js
@@ -0,0 +1,147 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { ROLE, OPENAI_BLOCK, OPENAI_FINISH, DEFAULT_IMAGE_MIME } from "../schema/index.js";
+import { buildChunk } from "../concerns/chunk.js";
+import { toOpenAIUsage } from "../concerns/usage.js";
+import { reasoningDelta } from "../concerns/reasoning.js";
+import { encodeDataUri } from "../concerns/image.js";
+import { toOpenAIFinish } from "../concerns/finishReason.js";
+
+// Build chunk meta for current gemini state
+function chunkMeta(state) {
+  return { id: `chatcmpl-${state.messageId}`, created: Math.floor(Date.now() / 1000), model: state.model };
+}
+
+// Build a tool_call chunk from a gemini functionCall part (shared by sig/non-sig branches)
+function emitFunctionCall(functionCall, state) {
+  const rawName = functionCall.name;
+  // Restore original tool name from mapping (AG cloaking)
+  const fcName = state.toolNameMap?.get(rawName) || rawName;
+  const fcArgs = functionCall.args || {};
+  const toolCallIndex = state.functionIndex++;
+  const toolCall = {
+    id: `${fcName}-${Date.now()}-${toolCallIndex}`,
+    index: toolCallIndex,
+    type: OPENAI_BLOCK.FUNCTION,
+    function: { name: fcName, arguments: JSON.stringify(fcArgs) },
+  };
+  // Keep Gemini bookkeeping separate from the shared translator state.toolCalls map.
+  // The downstream OpenAI→Claude translator uses state.toolCalls for Claude block
+  // metadata; pre-populating it here makes Anthropic tool deltas lose index.
+  state.geminiToolCallCount = (state.geminiToolCallCount || 0) + 1;
+  return buildChunk(chunkMeta(state), { tool_calls: [toolCall] }, null);
+}
+
+// Convert Gemini response chunk to OpenAI format
+export function geminiToOpenAIResponse(chunk, state) {
+  if (!chunk) return null;
+  
+  // Handle Antigravity wrapper
+  const response = chunk.response || chunk;
+  if (!response || !response.candidates?.[0]) return null;
+
+  const results = [];
+  const candidate = response.candidates[0];
+  const content = candidate.content;
+
+  // Initialize state
+  if (!state.messageId) {
+    state.messageId = response.responseId || `msg_${Date.now()}`;
+    state.model = response.modelVersion || "gemini";
+    state.functionIndex = 0;
+    state.geminiToolCallCount = 0;
+    results.push(buildChunk(chunkMeta(state), { role: ROLE.ASSISTANT }, null));
+  }
+
+  // Process parts
+  if (content?.parts) {
+    for (const part of content.parts) {
+      const hasThoughtSig = part.thoughtSignature || part.thought_signature;
+      const isThought = part.thought === true;
+      
+      // Handle thought signature (thinking mode)
+      if (hasThoughtSig) {
+        const hasTextContent = part.text !== undefined && part.text !== "";
+        const hasFunctionCall = !!part.functionCall;
+        
+        if (hasTextContent) {
+          results.push(buildChunk(
+            chunkMeta(state),
+            isThought ? reasoningDelta(part.text) : { content: part.text },
+            null
+          ));
+        }
+        
+        if (hasFunctionCall) {
+          results.push(emitFunctionCall(part.functionCall, state));
+        }
+        continue;
+      }
+
+      // Text content. Gemini marks model-internal thinking with `thought: true`.
+      // Some responses include a thoughtSignature, but Google AI Studio/Gemini API
+      // can also stream thought parts without a signature; those must not be
+      // surfaced as normal assistant content in OpenAI-compatible clients.
+      if (part.text !== undefined && part.text !== "") {
+        results.push(buildChunk(
+          chunkMeta(state),
+          isThought ? reasoningDelta(part.text) : { content: part.text },
+          null
+        ));
+      }
+
+      // Function call
+      if (part.functionCall) {
+        results.push(emitFunctionCall(part.functionCall, state));
+      }
+
+      // Inline data (images)
+      const inlineData = part.inlineData || part.inline_data;
+      if (inlineData?.data) {
+        const mimeType = inlineData.mimeType || inlineData.mime_type || DEFAULT_IMAGE_MIME;
+        results.push(buildChunk(
+          chunkMeta(state),
+          {
+            images: [{
+              type: OPENAI_BLOCK.IMAGE_URL,
+              image_url: { url: encodeDataUri(mimeType, inlineData.data) }
+            }]
+          },
+          null
+        ));
+      }
+    }
+  }
+
+  // Usage metadata - extract before finish reason so we can include it
+  const usageMeta = response.usageMetadata || chunk.usageMetadata;
+  const geminiUsage = toOpenAIUsage(usageMeta, "gemini");
+  if (geminiUsage) state.usage = geminiUsage;
+
+  // Finish reason - include usage in final chunk
+  if (candidate.finishReason) {
+    let finishReason = toOpenAIFinish(candidate.finishReason, "gemini");
+    if (finishReason === OPENAI_FINISH.STOP && state.geminiToolCallCount > 0) {
+      finishReason = OPENAI_FINISH.TOOL_CALLS;
+    }
+    
+    const finalChunk = buildChunk(chunkMeta(state), {}, finishReason);
+    
+    // Include usage in final chunk for downstream translators
+    if (state.usage) {
+      finalChunk.usage = state.usage;
+    }
+    
+    results.push(finalChunk);
+    state.finishReason = finishReason;
+  }
+
+  return results.length > 0 ? results : null;
+}
+
+// Register
+register(FORMATS.GEMINI, FORMATS.OPENAI, null, geminiToOpenAIResponse);
+register(FORMATS.GEMINI_CLI, FORMATS.OPENAI, null, geminiToOpenAIResponse);
+register(FORMATS.ANTIGRAVITY, FORMATS.OPENAI, null, geminiToOpenAIResponse);
+register(FORMATS.VERTEX, FORMATS.OPENAI, null, geminiToOpenAIResponse);
+
diff --git a/open-sse/translator/response/kiro-to-claude.js b/open-sse/translator/response/kiro-to-claude.js
new file mode 100644
index 0000000..1c9ece5
--- /dev/null
+++ b/open-sse/translator/response/kiro-to-claude.js
@@ -0,0 +1,261 @@
+/**
+ * Kiro → Claude Response Translator (DIRECT route, no OpenAI pivot)
+ *
+ * IMPORTANT: This translator does NOT receive raw Kiro AWS-EventStream frames.
+ * KiroExecutor.transformEventStreamToSSE() (open-sse/executors/kiro.js) already
+ * parses the binary EventStream and emits OpenAI-shaped
+ * `chat.completion.chunk` objects. So the chunks arriving here are OpenAI
+ * streaming chunks, and our job is OpenAI-chunk → Claude SSE events — the same
+ * transformation openai-to-claude.js performs. We re-implement it here so the
+ * direct `kiro:claude` route is self-contained and lossless (reasoning_content
+ * → thinking blocks, tool_calls → tool_use blocks, usage → message_delta).
+ *
+ * Registered on the direct route by ../index.js; reached only when source
+ * format is Claude and target is Kiro.
+ */
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+
+function stopThinkingBlock(state, results) {
+  if (!state.thinkingBlockStarted) return;
+  results.push({ type: "content_block_stop", index: state.thinkingBlockIndex });
+  state.thinkingBlockStarted = false;
+}
+
+function stopTextBlock(state, results) {
+  if (!state.textBlockStarted || state.textBlockClosed) return;
+  state.textBlockClosed = true;
+  results.push({ type: "content_block_stop", index: state.textBlockIndex });
+  state.textBlockStarted = false;
+}
+
+function convertFinishReason(reason) {
+  switch (reason) {
+    case "stop":
+      return "end_turn";
+    case "length":
+      return "max_tokens";
+    case "tool_calls":
+      return "tool_use";
+    default:
+      return "end_turn";
+  }
+}
+
+/**
+ * Convert one OpenAI-format chunk (from KiroExecutor) into Claude SSE events.
+ * Returns an array of Claude events, or null when the chunk yields nothing.
+ */
+export function kiroToClaudeResponse(chunk, state) {
+  // KiroExecutor emits chat.completion.chunk objects; tolerate string chunks
+  // by attempting a parse (defensive — the direct path is always objects).
+  let data = chunk;
+  if (typeof chunk === "string") {
+    const trimmed = chunk.trim();
+    if (!trimmed || trimmed === "[DONE]") return null;
+    try {
+      data = JSON.parse(trimmed.startsWith("data:") ? trimmed.slice(5).trim() : trimmed);
+    } catch {
+      return null;
+    }
+  }
+
+  if (!data || !data.choices?.[0]) return null;
+
+  const results = [];
+  const choice = data.choices[0];
+  const delta = choice.delta || {};
+
+  // Track usage if present on the chunk.
+  if (data.usage && typeof data.usage === "object") {
+    const promptTokens =
+      typeof data.usage.prompt_tokens === "number" ? data.usage.prompt_tokens : 0;
+    const outputTokens =
+      typeof data.usage.completion_tokens === "number"
+        ? data.usage.completion_tokens
+        : 0;
+    state.usage = { input_tokens: promptTokens, output_tokens: outputTokens };
+  }
+
+  // First chunk → emit message_start.
+  if (!state.messageStartSent) {
+    state.messageStartSent = true;
+    state.messageId =
+      (typeof data.id === "string" && data.id.replace("chatcmpl-", "")) ||
+      `msg_${Date.now()}`;
+    state.model = data.model || "kiro";
+    state.nextBlockIndex = 0;
+    results.push({
+      type: "message_start",
+      message: {
+        id: state.messageId,
+        type: "message",
+        role: "assistant",
+        model: state.model,
+        content: [],
+        stop_reason: null,
+        stop_sequence: null,
+        usage: { input_tokens: 0, output_tokens: 0 },
+      },
+    });
+  }
+
+  // Reasoning / thinking content (Kiro reasoningContentEvent → reasoning_content).
+  const reasoningContent = delta.reasoning_content || delta.reasoning;
+  if (reasoningContent) {
+    stopTextBlock(state, results);
+    if (!state.thinkingBlockStarted) {
+      state.thinkingBlockIndex = state.nextBlockIndex++;
+      state.thinkingBlockStarted = true;
+      results.push({
+        type: "content_block_start",
+        index: state.thinkingBlockIndex,
+        content_block: { type: "thinking", thinking: "" },
+      });
+    }
+    results.push({
+      type: "content_block_delta",
+      index: state.thinkingBlockIndex,
+      delta: { type: "thinking_delta", thinking: reasoningContent },
+    });
+  }
+
+  // Regular text content.
+  if (delta.content) {
+    stopThinkingBlock(state, results);
+    if (!state.textBlockStarted) {
+      state.textBlockIndex = state.nextBlockIndex++;
+      state.textBlockStarted = true;
+      state.textBlockClosed = false;
+      results.push({
+        type: "content_block_start",
+        index: state.textBlockIndex,
+        content_block: { type: "text", text: "" },
+      });
+    }
+    results.push({
+      type: "content_block_delta",
+      index: state.textBlockIndex,
+      delta: { type: "text_delta", text: delta.content },
+    });
+  }
+
+  // Tool calls.
+  if (delta.tool_calls) {
+    if (!state.toolCalls) state.toolCalls = new Map();
+    if (!state.toolArgBuffers) state.toolArgBuffers = new Map();
+    for (const tc of delta.tool_calls) {
+      const idx = tc.index ?? 0;
+      if (tc.id) {
+        stopThinkingBlock(state, results);
+        stopTextBlock(state, results);
+        const toolBlockIndex = state.nextBlockIndex++;
+        state.toolCalls.set(idx, {
+          id: tc.id,
+          name: tc.function?.name || "",
+          blockIndex: toolBlockIndex,
+        });
+        results.push({
+          type: "content_block_start",
+          index: toolBlockIndex,
+          content_block: {
+            type: "tool_use",
+            id: tc.id,
+            name: tc.function?.name || "",
+            input: {},
+          },
+        });
+      }
+      if (tc.function?.arguments) {
+        const toolInfo = state.toolCalls.get(idx);
+        if (toolInfo) {
+          state.toolArgBuffers.set(
+            idx,
+            (state.toolArgBuffers.get(idx) || "") + tc.function.arguments
+          );
+        }
+      }
+    }
+  }
+
+  // Finish.
+  if (choice.finish_reason) {
+    stopThinkingBlock(state, results);
+    stopTextBlock(state, results);
+
+    if (state.toolCalls) {
+      for (const [idx, toolInfo] of state.toolCalls) {
+        const buffered = state.toolArgBuffers?.get(idx);
+        if (buffered) {
+          results.push({
+            type: "content_block_delta",
+            index: toolInfo.blockIndex,
+            delta: { type: "input_json_delta", partial_json: buffered },
+          });
+        }
+        results.push({ type: "content_block_stop", index: toolInfo.blockIndex });
+      }
+    }
+
+    state.finishReason = choice.finish_reason;
+    const finalUsage = state.usage || { input_tokens: 0, output_tokens: 0 };
+    results.push({
+      type: "message_delta",
+      delta: { stop_reason: convertFinishReason(choice.finish_reason) },
+      usage: finalUsage,
+    });
+    results.push({ type: "message_stop" });
+  }
+
+  return results.length > 0 ? results : null;
+}
+
+/**
+ * Non-streaming Kiro → Claude. KiroExecutor only produces a stream, so this is
+ * a defensive helper for any non-streaming caller that hands us an aggregated
+ * OpenAI-shaped completion.
+ */
+export function kiroToClaudeNonStreaming(data) {
+  const content = [];
+  const choice = data?.choices?.[0];
+  const message = choice?.message || {};
+
+  if (message.content) {
+    content.push({ type: "text", text: message.content });
+  }
+  if (Array.isArray(message.tool_calls)) {
+    for (const tc of message.tool_calls) {
+      let input = {};
+      try {
+        input =
+          typeof tc.function?.arguments === "string"
+            ? JSON.parse(tc.function.arguments)
+            : tc.function?.arguments || {};
+      } catch {
+        input = {};
+      }
+      content.push({
+        type: "tool_use",
+        id: tc.id || `toolu_${Date.now()}`,
+        name: tc.function?.name || "",
+        input,
+      });
+    }
+  }
+
+  const usage = data?.usage || {};
+  return {
+    id: `msg_${Date.now()}`,
+    type: "message",
+    role: "assistant",
+    content,
+    model: data?.model || "kiro",
+    stop_reason: convertFinishReason(choice?.finish_reason || "stop"),
+    usage: {
+      input_tokens: usage.prompt_tokens || 0,
+      output_tokens: usage.completion_tokens || 0,
+    },
+  };
+}
+
+register(FORMATS.KIRO, FORMATS.CLAUDE, null, kiroToClaudeResponse);
diff --git a/open-sse/translator/response/kiro-to-openai.js b/open-sse/translator/response/kiro-to-openai.js
new file mode 100644
index 0000000..7059a85
--- /dev/null
+++ b/open-sse/translator/response/kiro-to-openai.js
@@ -0,0 +1,160 @@
+/**
+ * Kiro to OpenAI Response Translator
+ * Converts Kiro/AWS CodeWhisperer streaming events to OpenAI SSE format
+ */
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { ROLE, OPENAI_BLOCK } from "../schema/index.js";
+import { buildChunk } from "../concerns/chunk.js";
+import { toOpenAIUsage } from "../concerns/usage.js";
+import { fallbackToolCallId } from "../concerns/toolCall.js";
+import { reasoningDelta } from "../concerns/reasoning.js";
+import { toOpenAIFinish } from "../concerns/finishReason.js";
+
+// Build chunk meta for current kiro state
+function chunkMeta(state) {
+  return { id: state.responseId, created: state.created, model: state.model || "kiro" };
+}
+
+/**
+ * Parse Kiro SSE event and convert to OpenAI format
+ * Kiro events: assistantResponseEvent, codeEvent, supplementaryWebLinksEvent, etc.
+ */
+export function kiroToOpenAIResponse(chunk, state) {
+  
+  if (!chunk) return null;
+
+  // If chunk is already in OpenAI format (from executor transform), return as-is
+  if (chunk.object === "chat.completion.chunk" && chunk.choices) {
+    return chunk;
+  }
+  
+  // Handle string chunk (raw SSE data)
+  let data = chunk;
+  if (typeof chunk === "string") {
+    // Parse SSE format: event:xxx\ndata:xxx
+    const lines = chunk.split("\n");
+    let eventType = "";
+    let eventData = "";
+
+    for (const line of lines) {
+      if (line.startsWith("event:")) {
+        eventType = line.slice(6).trim();
+      } else if (line.startsWith(":event-type:")) {
+        eventType = line.slice(12).trim();
+      } else if (line.startsWith("data:")) {
+        eventData = line.slice(5).trim();
+      } else if (line.startsWith(":content-type:")) {
+        // Skip content-type header
+      } else if (line.trim() && !line.startsWith(":")) {
+        // Raw JSON data
+        eventData = line.trim();
+      }
+    }
+
+    if (!eventData) return null;
+
+    try {
+      data = JSON.parse(eventData);
+      data._eventType = eventType;
+    } catch {
+      // Not JSON, might be raw text
+      data = { text: eventData, _eventType: eventType };
+    }
+  }
+
+  // Initialize state if needed
+  if (!state.responseId) {
+    state.responseId = `chatcmpl-${Date.now()}`;
+    state.created = Math.floor(Date.now() / 1000);
+    state.chunkIndex = 0;
+  }
+
+  const eventType = data._eventType || data.event || "";
+
+  // Handle different Kiro event types
+  if (eventType === "assistantResponseEvent" || data.assistantResponseEvent) {
+    const content = data.assistantResponseEvent?.content || data.content || "";
+    if (!content) return null;
+
+    const openaiChunk = buildChunk(chunkMeta(state), {
+      ...(state.chunkIndex === 0 ? { role: ROLE.ASSISTANT } : {}),
+      content: content
+    }, null);
+
+    state.chunkIndex++;
+    return openaiChunk;
+  }
+
+  // Handle reasoning/thinking events.
+  // Kiro emits reasoningContentEvent when the request enabled thinking via
+  // the <thinking_mode>enabled</thinking_mode> system-prompt tag. We surface
+  // this as OpenAI delta.reasoning_content so downstream translators can map
+  // it to Claude thinking blocks / Anthropic reasoning / etc.
+  if (eventType === "reasoningContentEvent" || data.reasoningContentEvent) {
+    const reasoning = data.reasoningContentEvent || data;
+    const content = (typeof reasoning === "string")
+      ? reasoning
+      : (reasoning.text || reasoning.content || data.content || "");
+    if (!content) return null;
+
+    const openaiChunk = buildChunk(chunkMeta(state), reasoningDelta(content, state.chunkIndex === 0), null);
+
+    state.chunkIndex++;
+    return openaiChunk;
+  }
+
+  // Handle tool use events
+  if (eventType === "toolUseEvent" || data.toolUseEvent) {
+    state.hadToolUse = true;
+    const toolUse = data.toolUseEvent || data;
+    const toolCallId = toolUse.toolUseId || fallbackToolCallId();
+    const toolName = toolUse.name || "";
+    const toolInput = toolUse.input || {};
+
+    const openaiChunk = buildChunk(chunkMeta(state), {
+      ...(state.chunkIndex === 0 ? { role: ROLE.ASSISTANT } : {}),
+      tool_calls: [{
+        index: 0,
+        id: toolCallId,
+        type: OPENAI_BLOCK.FUNCTION,
+        function: {
+          name: toolName,
+          arguments: JSON.stringify(toolInput)
+        }
+      }]
+    }, null);
+
+    state.chunkIndex++;
+    return openaiChunk;
+  }
+
+  // Handle completion/done events
+  if (eventType === "messageStopEvent" || eventType === "done" || data.messageStopEvent) {
+    // tool_calls when a tool was used this turn, else stop (kiro upstream has no explicit reason)
+    const finishReason = toOpenAIFinish(state.hadToolUse ? "tool_use" : "stop", "kiro");
+    state.finishReason = finishReason; // Mark for usage injection in stream.js
+
+    const openaiChunk = buildChunk(chunkMeta(state), {}, finishReason);
+
+    // Include usage in final chunk if available
+    if (state.usage && typeof state.usage === "object") {
+      openaiChunk.usage = state.usage;
+    }
+
+    return openaiChunk;
+  }
+
+// Handle usage events
+  if (eventType === "usageEvent" || data.usageEvent) {
+    const usage = toOpenAIUsage(data.usageEvent || data, "kiro");
+    if (usage) state.usage = usage;
+    return null;
+  }
+
+  // Unknown event type - skip
+  return null;
+}
+
+// Register translator
+register(FORMATS.KIRO, FORMATS.OPENAI, null, kiroToOpenAIResponse);
diff --git a/open-sse/translator/response/ollama-to-openai.js b/open-sse/translator/response/ollama-to-openai.js
new file mode 100644
index 0000000..f0a2004
--- /dev/null
+++ b/open-sse/translator/response/ollama-to-openai.js
@@ -0,0 +1,134 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { ROLE, OPENAI_BLOCK, OPENAI_FINISH } from "../schema/index.js";
+import { buildChunk } from "../concerns/chunk.js";
+import { toOpenAIUsage } from "../concerns/usage.js";
+import { fallbackToolCallId } from "../concerns/toolCall.js";
+import { toOpenAIFinish } from "../concerns/finishReason.js";
+
+/**
+ * Convert Ollama NDJSON response to OpenAI SSE format
+ *
+ * Ollama response format:
+ * {"model": "...", "message": {"role": "assistant", "content": "..."}, "done": false}
+ * {"model": "...", "done": true, "prompt_eval_count": 123, "eval_count": 456}
+ *
+ * OpenAI format:
+ * {"id": "...", "object": "chat.completion.chunk", "created": 123, "model": "...",
+ *  "choices": [{"index": 0, "delta": {"content": "..."}, "finish_reason": null}]}
+ */
+export function ollamaToOpenAIResponse(chunk, state) {
+  if (!chunk || typeof chunk !== "object") return null;
+
+  // Initialize state on first chunk
+  if (!state.ollama) {
+    state.ollama = {
+      id: `chatcmpl-${Date.now()}`,
+      created: Math.floor(Date.now() / 1000),
+      model: chunk.model || state.model
+    };
+  }
+
+  const { id, created, model } = state.ollama;
+
+  // Final chunk with done=true
+  if (chunk.done) {
+    const usage = extractUsage(chunk);
+    
+    // Determine finish_reason: map upstream done_reason, override to tool_calls if tools used
+    let finishReason = toOpenAIFinish(chunk.done_reason, "ollama");
+    if (chunk.done_reason === OPENAI_FINISH.TOOL_CALLS || state.hadToolCalls) {
+      finishReason = OPENAI_FINISH.TOOL_CALLS;
+    }
+
+    const doneChunk = buildChunk({ id, created, model }, {}, finishReason);
+    doneChunk.usage = usage;
+    return doneChunk;
+  }
+
+  // Content chunk
+  const message = chunk.message;
+  if (!message) return null;
+
+  const content = typeof message.content === "string" ? message.content : "";
+  const thinking = typeof message.thinking === "string" ? message.thinking : "";
+  const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : null;
+
+  // Skip empty chunks
+  if (!content && !thinking && !toolCalls) return null;
+
+  // Accumulate content in state
+  if (content) {
+    state.accumulatedContent = (state.accumulatedContent || "") + content;
+  }
+  if (thinking) {
+    state.accumulatedThinking = (state.accumulatedThinking || "") + thinking;
+  }
+
+  const delta = {};
+  if (content) delta.content = content;
+  if (thinking) delta.reasoning_content = thinking;
+  
+  // Convert Ollama tool_calls to OpenAI format
+  if (toolCalls) {
+    state.hadToolCalls = true;
+    delta.tool_calls = convertToolCalls(toolCalls);
+  }
+
+  return buildChunk({ id, created, model }, delta, null);
+}
+
+/**
+ * Extract usage stats from Ollama response
+ */
+function extractUsage(ollamaChunk) {
+  return toOpenAIUsage(ollamaChunk, "ollama");
+}
+
+/**
+ * Convert tool_calls from Ollama format to OpenAI format
+ */
+function convertToolCalls(toolCalls) {
+  return toolCalls.map((tc, i) => ({
+    index: tc.function?.index ?? i,
+    id: tc.id || fallbackToolCallId(i),
+    type: OPENAI_BLOCK.FUNCTION,
+    function: {
+      name: tc.function?.name || "",
+      arguments: typeof tc.function?.arguments === "string"
+        ? tc.function.arguments
+        : JSON.stringify(tc.function?.arguments || {})
+    }
+  }));
+}
+
+/**
+ * Convert Ollama non-streaming response body to OpenAI chat.completion format
+ */
+export function ollamaBodyToOpenAI(body) {
+  const msg = body.message || {};
+  const content = msg.content || "";
+  const thinking = msg.thinking || "";
+  const toolCalls = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
+
+  const message = { role: ROLE.ASSISTANT };
+  if (content) message.content = content;
+  if (thinking) message.reasoning_content = thinking;
+  if (toolCalls.length > 0) message.tool_calls = convertToolCalls(toolCalls);
+  if (!message.content && !message.tool_calls) message.content = "";
+
+  let finishReason = toOpenAIFinish(body.done_reason, "ollama");
+  if (toolCalls.length > 0) finishReason = OPENAI_FINISH.TOOL_CALLS;
+
+  return {
+    id: `chatcmpl-${Date.now()}`,
+    object: "chat.completion",
+    created: Math.floor(Date.now() / 1000),
+    model: body.model || "ollama",
+    choices: [{ index: 0, message, finish_reason: finishReason }],
+    usage: extractUsage(body)
+  };
+}
+
+// Register translator
+register(FORMATS.OLLAMA, FORMATS.OPENAI, null, ollamaToOpenAIResponse);
diff --git a/open-sse/translator/response/openai-responses.js b/open-sse/translator/response/openai-responses.js
new file mode 100644
index 0000000..b933678
--- /dev/null
+++ b/open-sse/translator/response/openai-responses.js
@@ -0,0 +1,535 @@
+/**
+ * Translator: OpenAI Chat Completions → OpenAI Responses API (response)
+ * Converts streaming chunks from Chat Completions to Responses API events
+ */
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { buildChunk } from "../concerns/chunk.js";
+import { buildUsage } from "../concerns/usage.js";
+import { fallbackToolCallId } from "../concerns/toolCall.js";
+import { reasoningDelta, extractReasoningText } from "../concerns/reasoning.js";
+import { ROLE, OPENAI_BLOCK, RESPONSES_ITEM, OPENAI_FINISH, MODEL_FALLBACK } from "../schema/index.js";
+
+/**
+ * Translate OpenAI chunk to Responses API events
+ * @returns {Array} Array of events with { event, data } structure
+ */
+export function openaiToOpenAIResponsesResponse(chunk, state) {
+  if (!chunk) {
+    return flushEvents(state);
+  }
+  
+  if (!chunk.choices?.length) return [];
+  
+  const events = [];
+  const nextSeq = () => ++state.seq;
+  
+  const emit = (eventType, data) => {
+    data.sequence_number = nextSeq();
+    events.push({ event: eventType, data });
+  };
+
+  const choice = chunk.choices[0];
+  const idx = choice.index || 0;
+  const delta = choice.delta || {};
+
+  // Emit initial events
+  if (!state.started) {
+    state.started = true;
+    state.responseId = chunk.id ? `resp_${chunk.id}` : state.responseId;
+    
+    emit("response.created", {
+      type: "response.created",
+      response: {
+        id: state.responseId,
+        object: "response",
+        created_at: state.created,
+        status: "in_progress",
+        background: false,
+        error: null,
+        output: []
+      }
+    });
+
+    emit("response.in_progress", {
+      type: "response.in_progress",
+      response: {
+        id: state.responseId,
+        object: "response",
+        created_at: state.created,
+        status: "in_progress"
+      }
+    });
+  }
+
+  // Handle reasoning across vendor shapes (reasoning_content / reasoning / reasoning_details)
+  const reasoningText = extractReasoningText(delta);
+  if (reasoningText) {
+    startReasoning(state, emit, idx);
+    emitReasoningDelta(state, emit, reasoningText);
+  }
+
+  // Handle text content
+  if (delta.content) {
+    let content = delta.content;
+
+    if (content.includes("<think>")) {
+      state.inThinking = true;
+      content = content.replace("<think>", "");
+      startReasoning(state, emit, idx);
+    }
+
+    if (content.includes("</think>")) {
+      const parts = content.split("</think>");
+      const thinkPart = parts[0];
+      const textPart = parts.slice(1).join("</think>");
+      if (thinkPart) emitReasoningDelta(state, emit, thinkPart);
+      closeReasoning(state, emit);
+      state.inThinking = false;
+      content = textPart;
+    }
+
+    if (state.inThinking && content) {
+      emitReasoningDelta(state, emit, content);
+      return events;
+    }
+
+    if (content) {
+      emitTextContent(state, emit, idx, content);
+    }
+  }
+
+  // Handle tool_calls
+  if (delta.tool_calls) {
+    closeMessage(state, emit, idx);
+    for (const tc of delta.tool_calls) {
+      emitToolCall(state, emit, tc);
+    }
+  }
+
+  // Handle finish_reason
+  if (choice.finish_reason) {
+    for (const i in state.msgItemAdded) closeMessage(state, emit, i);
+    closeReasoning(state, emit);
+    for (const i in state.funcCallIds) closeToolCall(state, emit, i);
+    sendCompleted(state, emit);
+  }
+
+  return events;
+}
+
+// Helper functions
+function startReasoning(state, emit, idx) {
+  if (!state.reasoningId) {
+    state.reasoningId = `rs_${state.responseId}_${idx}`;
+    state.reasoningIndex = idx;
+    
+    emit("response.output_item.added", {
+      type: "response.output_item.added",
+      output_index: idx,
+      item: { id: state.reasoningId, type: RESPONSES_ITEM.REASONING, summary: [] }
+    });
+
+    emit("response.reasoning_summary_part.added", {
+      type: "response.reasoning_summary_part.added",
+      item_id: state.reasoningId,
+      output_index: idx,
+      summary_index: 0,
+      part: { type: RESPONSES_ITEM.SUMMARY_TEXT, text: "" }
+    });
+    state.reasoningPartAdded = true;
+  }
+}
+
+function emitReasoningDelta(state, emit, text) {
+  if (!text) return;
+  state.reasoningBuf += text;
+  emit("response.reasoning_summary_text.delta", {
+    type: "response.reasoning_summary_text.delta",
+    item_id: state.reasoningId,
+    output_index: state.reasoningIndex,
+    summary_index: 0,
+    delta: text
+  });
+}
+
+function closeReasoning(state, emit) {
+  if (state.reasoningId && !state.reasoningDone) {
+    state.reasoningDone = true;
+    
+    emit("response.reasoning_summary_text.done", {
+      type: "response.reasoning_summary_text.done",
+      item_id: state.reasoningId,
+      output_index: state.reasoningIndex,
+      summary_index: 0,
+      text: state.reasoningBuf
+    });
+
+    emit("response.reasoning_summary_part.done", {
+      type: "response.reasoning_summary_part.done",
+      item_id: state.reasoningId,
+      output_index: state.reasoningIndex,
+      summary_index: 0,
+      part: { type: RESPONSES_ITEM.SUMMARY_TEXT, text: state.reasoningBuf }
+    });
+
+    emit("response.output_item.done", {
+      type: "response.output_item.done",
+      output_index: state.reasoningIndex,
+      item: {
+        id: state.reasoningId,
+        type: RESPONSES_ITEM.REASONING,
+        summary: [{ type: RESPONSES_ITEM.SUMMARY_TEXT, text: state.reasoningBuf }]
+      }
+    });
+  }
+}
+
+function emitTextContent(state, emit, idx, content) {
+  if (!state.msgItemAdded[idx]) {
+    state.msgItemAdded[idx] = true;
+    const msgId = `msg_${state.responseId}_${idx}`;
+    
+    emit("response.output_item.added", {
+      type: "response.output_item.added",
+      output_index: idx,
+      item: { id: msgId, type: RESPONSES_ITEM.MESSAGE, content: [], role: ROLE.ASSISTANT }
+    });
+  }
+
+  if (!state.msgContentAdded[idx]) {
+    state.msgContentAdded[idx] = true;
+    
+    emit("response.content_part.added", {
+      type: "response.content_part.added",
+      item_id: `msg_${state.responseId}_${idx}`,
+      output_index: idx,
+      content_index: 0,
+      part: { type: RESPONSES_ITEM.OUTPUT_TEXT, annotations: [], logprobs: [], text: "" }
+    });
+  }
+
+  emit("response.output_text.delta", {
+    type: "response.output_text.delta",
+    item_id: `msg_${state.responseId}_${idx}`,
+    output_index: idx,
+    content_index: 0,
+    delta: content,
+    logprobs: []
+  });
+
+  if (!state.msgTextBuf[idx]) state.msgTextBuf[idx] = "";
+  state.msgTextBuf[idx] += content;
+}
+
+function closeMessage(state, emit, idx) {
+  if (state.msgItemAdded[idx] && !state.msgItemDone[idx]) {
+    state.msgItemDone[idx] = true;
+    const fullText = state.msgTextBuf[idx] || "";
+    const msgId = `msg_${state.responseId}_${idx}`;
+
+    emit("response.output_text.done", {
+      type: "response.output_text.done",
+      item_id: msgId,
+      output_index: parseInt(idx),
+      content_index: 0,
+      text: fullText,
+      logprobs: []
+    });
+
+    emit("response.content_part.done", {
+      type: "response.content_part.done",
+      item_id: msgId,
+      output_index: parseInt(idx),
+      content_index: 0,
+      part: { type: RESPONSES_ITEM.OUTPUT_TEXT, annotations: [], logprobs: [], text: fullText }
+    });
+
+    emit("response.output_item.done", {
+      type: "response.output_item.done",
+      output_index: parseInt(idx),
+      item: {
+        id: msgId,
+        type: RESPONSES_ITEM.MESSAGE,
+        content: [{ type: RESPONSES_ITEM.OUTPUT_TEXT, annotations: [], logprobs: [], text: fullText }],
+        role: ROLE.ASSISTANT
+      }
+    });
+  }
+}
+
+function emitToolCall(state, emit, tc) {
+  const tcIdx = tc.index ?? 0;
+  const newCallId = tc.id;
+  const funcName = tc.function?.name;
+
+  if (funcName) state.funcNames[tcIdx] = funcName;
+
+  if (!state.funcCallIds[tcIdx] && newCallId) {
+    state.funcCallIds[tcIdx] = newCallId;
+    
+    emit("response.output_item.added", {
+      type: "response.output_item.added",
+      output_index: tcIdx,
+      item: {
+        id: `fc_${newCallId}`,
+        type: RESPONSES_ITEM.FUNCTION_CALL,
+        arguments: "",
+        call_id: newCallId,
+        name: state.funcNames[tcIdx] || ""
+      }
+    });
+  }
+
+  if (!state.funcArgsBuf[tcIdx]) state.funcArgsBuf[tcIdx] = "";
+
+  if (tc.function?.arguments) {
+    const refCallId = state.funcCallIds[tcIdx] || newCallId;
+    if (refCallId) {
+      emit("response.function_call_arguments.delta", {
+        type: "response.function_call_arguments.delta",
+        item_id: `fc_${refCallId}`,
+        output_index: tcIdx,
+        delta: tc.function.arguments
+      });
+    }
+    state.funcArgsBuf[tcIdx] += tc.function.arguments;
+  }
+}
+
+function closeToolCall(state, emit, idx) {
+  const callId = state.funcCallIds[idx];
+  if (callId && !state.funcItemDone[idx]) {
+    const args = state.funcArgsBuf[idx] || "{}";
+    
+    emit("response.function_call_arguments.done", {
+      type: "response.function_call_arguments.done",
+      item_id: `fc_${callId}`,
+      output_index: parseInt(idx),
+      arguments: args
+    });
+
+    emit("response.output_item.done", {
+      type: "response.output_item.done",
+      output_index: parseInt(idx),
+      item: {
+        id: `fc_${callId}`,
+        type: RESPONSES_ITEM.FUNCTION_CALL,
+        arguments: args,
+        call_id: callId,
+        name: state.funcNames[idx] || ""
+      }
+    });
+
+    state.funcItemDone[idx] = true;
+    state.funcArgsDone[idx] = true;
+  }
+}
+
+function sendCompleted(state, emit) {
+  if (!state.completedSent) {
+    state.completedSent = true;
+    emit("response.completed", {
+      type: "response.completed",
+      response: {
+        id: state.responseId,
+        object: "response",
+        created_at: state.created,
+        status: "completed",
+        background: false,
+        error: null
+      }
+    });
+  }
+}
+
+function flushEvents(state) {
+  if (state.completedSent) return [];
+  
+  const events = [];
+  const nextSeq = () => ++state.seq;
+  const emit = (eventType, data) => {
+    data.sequence_number = nextSeq();
+    events.push({ event: eventType, data });
+  };
+
+  for (const i in state.msgItemAdded) closeMessage(state, emit, i);
+  closeReasoning(state, emit);
+  for (const i in state.funcCallIds) closeToolCall(state, emit, i);
+  sendCompleted(state, emit);
+  
+  return events;
+}
+
+// currentToolCallId is intentionally sticky for the current turn so flush/completion
+  // can still finalize as tool_calls even if the tool call was emitted before stream end.
+function computeFinishReason(state) {
+   return state.toolCallIndex > 0 || state.currentToolCallId
+    ? OPENAI_FINISH.TOOL_CALLS
+    : OPENAI_FINISH.STOP;
+}
+
+/**
+ * Translate OpenAI Responses API chunk to OpenAI Chat Completions format
+ * This is for when Codex returns data and we need to send it to an OpenAI-compatible client
+ */
+export function openaiResponsesToOpenAIResponse(chunk, state) {
+  if (!chunk) {
+    // Flush: send final chunk with finish_reason
+    if (state.finishReasonSent || !state.started) return null;
+
+    const finishReason = computeFinishReason(state);
+
+    state.finishReasonSent = true;
+    state.finishReason = finishReason;
+
+    const finalChunk = buildChunk(
+      { id: state.chatId || `chatcmpl-${Date.now()}`, created: state.created || Math.floor(Date.now() / 1000), model: state.model || MODEL_FALLBACK },
+      {},
+      finishReason
+    );
+
+    if (state.usage && typeof state.usage === "object") {
+      finalChunk.usage = state.usage;
+    }
+
+    return finalChunk;
+  }
+
+  // Handle different event types from Responses API
+  const eventType = chunk.type || chunk.event;
+  const data = chunk.data || chunk;
+
+  // Initialize state
+  if (!state.started) {
+    state.started = true;
+    state.chatId = `chatcmpl-${Date.now()}`;
+    state.created = Math.floor(Date.now() / 1000);
+    state.toolCallIndex = 0;
+    state.currentToolCallId = null;
+  }
+
+  // Text content delta
+  if (eventType === "response.output_text.delta") {
+    const delta = data.delta || "";
+    if (!delta) return null;
+
+    return buildChunk(
+      { id: state.chatId, created: state.created, model: state.model || MODEL_FALLBACK },
+      { content: delta }
+    );
+  }
+
+  // Text content done (ignore, we handle via delta)
+  if (eventType === "response.output_text.done") {
+    return null;
+  }
+
+  // Function call started (standard function_call or custom_tool_call)
+  if (eventType === "response.output_item.added" && (data.item?.type === RESPONSES_ITEM.FUNCTION_CALL || data.item?.type === "custom_tool_call")) {
+    const item = data.item;
+    state.currentToolCallId = item.call_id || fallbackToolCallId();
+
+    return buildChunk(
+      { id: state.chatId, created: state.created, model: state.model || MODEL_FALLBACK },
+      {
+        tool_calls: [{
+          index: state.toolCallIndex,
+          id: state.currentToolCallId,
+          type: OPENAI_BLOCK.FUNCTION,
+          function: { name: item.name || "", arguments: "" }
+        }]
+      }
+    );
+  }
+
+  // Function call arguments delta (standard or custom_tool_call variant)
+  if (eventType === "response.function_call_arguments.delta" || eventType === "response.custom_tool_call_input.delta") {
+    const argsDelta = data.delta || "";
+    if (!argsDelta) return null;
+
+    return buildChunk(
+      { id: state.chatId, created: state.created, model: state.model || MODEL_FALLBACK },
+      { tool_calls: [{ index: state.toolCallIndex, function: { arguments: argsDelta } }] }
+    );
+  }
+
+  // Function call done (standard or custom_tool_call variant)
+  if (eventType === "response.output_item.done" && (data.item?.type === RESPONSES_ITEM.FUNCTION_CALL || data.item?.type === "custom_tool_call")) {
+    state.toolCallIndex++;
+    return null;
+  }
+
+  // Response completed
+  if (eventType === "response.completed" || eventType === "response.done") {
+    // Extract usage from response.completed event
+    const responseUsage = data.response?.usage;
+    if (responseUsage && typeof responseUsage === "object") {
+      const inputTokens = responseUsage.input_tokens || responseUsage.prompt_tokens || 0;
+      const outputTokens = responseUsage.output_tokens || responseUsage.completion_tokens || 0;
+      // OpenAI Responses API: input_tokens already includes cached_tokens
+      // Cache info is in input_tokens_details.cached_tokens
+      const cacheReadTokens = responseUsage.input_tokens_details?.cached_tokens || responseUsage.cache_read_input_tokens || 0;
+      
+      state.usage = buildUsage({ promptTokens: inputTokens, completionTokens: outputTokens, totalTokens: inputTokens + outputTokens, cachedTokens: cacheReadTokens });
+    }
+    
+    if (!state.finishReasonSent) {
+      const finishReason = computeFinishReason(state);
+
+      state.finishReasonSent = true;
+      state.finishReason = finishReason; // Mark for usage injection in stream.js
+      
+      const finalChunk = buildChunk(
+        { id: state.chatId, created: state.created, model: state.model || MODEL_FALLBACK },
+        {},
+        finishReason
+      );
+
+      // Include usage in final chunk if available
+      if (state.usage && typeof state.usage === "object") {
+        finalChunk.usage = state.usage;
+      }
+      
+      return finalChunk;
+    }
+    return null;
+  }
+
+  // Error events from Responses API (e.g. model_not_found)
+  if (eventType === "error" || eventType === "response.failed") {
+    // Avoid emitting duplicate errors (error + response.failed arrive back-to-back)
+    if (state.finishReasonSent) return null;
+
+    const error = data.error || data.response?.error;
+    if (error) {
+      state.error = error;
+      state.finishReasonSent = true;
+
+      // Surface the error as an OpenAI-compatible error chunk
+      return buildChunk(
+        { id: state.chatId || `chatcmpl-${Date.now()}`, created: state.created || Math.floor(Date.now() / 1000), model: state.model || MODEL_FALLBACK },
+        { content: `[Error] ${error.message || JSON.stringify(error)}` },
+        OPENAI_FINISH.STOP
+      );
+    }
+    return null;
+  }
+
+  // Reasoning summary delta → emit as reasoning_content for client thinking display
+  if (eventType === "response.reasoning_summary_text.delta") {
+    const delta = data.delta || "";
+    if (!delta) return null;
+    return buildChunk(
+      { id: state.chatId, created: state.created, model: state.model || MODEL_FALLBACK },
+      reasoningDelta(delta)
+    );
+  }
+
+  // Ignore other events
+  return null;
+}
+
+// Register both directions
+register(FORMATS.OPENAI, FORMATS.OPENAI_RESPONSES, null, openaiToOpenAIResponsesResponse);
+register(FORMATS.OPENAI_RESPONSES, FORMATS.OPENAI, null, openaiResponsesToOpenAIResponse);
diff --git a/open-sse/translator/response/openai-to-antigravity.js b/open-sse/translator/response/openai-to-antigravity.js
new file mode 100644
index 0000000..b0b360a
--- /dev/null
+++ b/open-sse/translator/response/openai-to-antigravity.js
@@ -0,0 +1,123 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { GEMINI_ROLE, OPENAI_FINISH, GEMINI_FINISH } from "../schema/index.js";
+
+// Convert OpenAI SSE chunk to Antigravity SSE format
+// Real Antigravity format:
+//   data: {"response":{"candidates":[{"content":{"role":"model","parts":[...]}, "finishReason":"STOP"}], "usageMetadata":{...}, "modelVersion":"...", "responseId":"..."}}
+// Tool calls: OpenAI sends incremental args across chunks → accumulate and emit ONCE at finish
+export function openaiToAntigravityResponse(chunk, state) {
+  if (!chunk) return null;
+
+  const choice = chunk.choices?.[0];
+  if (!choice) {
+    if (chunk.usage) {
+      state._usage = chunk.usage;
+    }
+    return null;
+  }
+
+  const delta = choice.delta || {};
+  const finishReason = choice.finish_reason;
+
+  // Init state
+  if (!state._toolCallAccum) state._toolCallAccum = {};
+  if (!state._responseId) state._responseId = chunk.id || `resp_${Date.now()}`;
+  if (!state._modelVersion) state._modelVersion = chunk.model || "";
+
+  const parts = [];
+
+  // Thinking/reasoning → thought part
+  if (delta.reasoning_content) {
+    parts.push({ thought: true, text: delta.reasoning_content });
+  }
+
+  // Text content
+  if (delta.content) {
+    parts.push({ text: delta.content });
+  }
+
+  // Accumulate tool calls silently (no emit until finish)
+  if (delta.tool_calls) {
+    for (const tc of delta.tool_calls) {
+      const idx = tc.index ?? 0;
+      if (!state._toolCallAccum[idx]) {
+        state._toolCallAccum[idx] = { id: "", name: "", arguments: "" };
+      }
+      const accum = state._toolCallAccum[idx];
+      if (tc.id) accum.id = tc.id;
+      if (tc.function?.name) accum.name += tc.function.name;
+      if (tc.function?.arguments) accum.arguments += tc.function.arguments;
+    }
+    // Skip emit — wait for finish_reason
+    if (parts.length === 0 && !finishReason) return null;
+  }
+
+  // On finish, emit accumulated tool calls as complete functionCall parts
+  if (finishReason) {
+    const indices = Object.keys(state._toolCallAccum);
+    for (const idx of indices) {
+      const accum = state._toolCallAccum[idx];
+      let args = {};
+      try { args = JSON.parse(accum.arguments); } catch { /* empty */ }
+      // Restore original tool name if it was prefixed during cloaking
+      const originalName = state.toolNameMap?.get(accum.name) || accum.name;
+      parts.push({
+        functionCall: {
+          name: originalName,
+          args
+        }
+      });
+    }
+  }
+
+  // Skip empty non-finish chunks
+  if (parts.length === 0 && !finishReason) return null;
+
+  // Ensure at least empty text part on finish with no content
+  if (parts.length === 0 && finishReason) {
+    parts.push({ text: "" });
+  }
+
+  // Build candidate
+  const candidate = { content: { role: GEMINI_ROLE.MODEL, parts } };
+
+  // Finish reason mapping
+  if (finishReason) {
+    const reasonMap = {
+      [OPENAI_FINISH.STOP]: GEMINI_FINISH.STOP,
+      [OPENAI_FINISH.LENGTH]: GEMINI_FINISH.MAX_TOKENS,
+      [OPENAI_FINISH.TOOL_CALLS]: GEMINI_FINISH.STOP,
+      [OPENAI_FINISH.CONTENT_FILTER]: GEMINI_FINISH.SAFETY
+    };
+    candidate.finishReason = reasonMap[finishReason] || GEMINI_FINISH.STOP;
+  }
+
+  // Build response
+  const response = {
+    candidates: [candidate],
+    modelVersion: state._modelVersion,
+    responseId: state._responseId
+  };
+
+  // Usage metadata
+  const usage = chunk.usage || state._usage;
+  if (usage) {
+    response.usageMetadata = {
+      promptTokenCount: usage.prompt_tokens || 0,
+      candidatesTokenCount: usage.completion_tokens || 0,
+      totalTokenCount: usage.total_tokens || 0
+    };
+    if (usage.completion_tokens_details?.reasoning_tokens) {
+      response.usageMetadata.thoughtsTokenCount = usage.completion_tokens_details.reasoning_tokens;
+    }
+    if (usage.prompt_tokens_details?.cached_tokens) {
+      response.usageMetadata.cachedContentTokenCount = usage.prompt_tokens_details.cached_tokens;
+    }
+  }
+
+  return { response };
+}
+
+// Register
+register(FORMATS.OPENAI, FORMATS.ANTIGRAVITY, null, openaiToAntigravityResponse);
diff --git a/open-sse/translator/response/openai-to-claude.js b/open-sse/translator/response/openai-to-claude.js
new file mode 100644
index 0000000..3998cc8
--- /dev/null
+++ b/open-sse/translator/response/openai-to-claude.js
@@ -0,0 +1,265 @@
+import { register } from "../index.js";
+import { FORMATS } from "../formats.js";
+import { ROLE, CLAUDE_BLOCK, MODEL_FALLBACK } from "../schema/index.js";
+import { fromOpenAIFinish } from "../concerns/finishReason.js";
+import { extractReasoningText } from "../concerns/reasoning.js";
+
+// Legacy "proxy_" prefix used by older request translators. Response strips it
+// defensively so tool names from such turns resolve back (e.g. proxy_Read → Read
+// for arg sanitization). Current request translator emits no prefix ("") — strip
+// is then a no-op. Kept intentionally; do NOT couple to request's empty prefix.
+const CLAUDE_OAUTH_TOOL_PREFIX = "proxy_";
+
+// Sanitize tool call arguments to fix bad params from non-Anthropic models
+function sanitizeToolArgs(toolName, argsJson) {
+  try {
+    const args = JSON.parse(argsJson);
+    const name = toolName.startsWith(CLAUDE_OAUTH_TOOL_PREFIX)
+      ? toolName.slice(CLAUDE_OAUTH_TOOL_PREFIX.length)
+      : toolName;
+    if (name === "Read") sanitizeReadArgs(args);
+    return JSON.stringify(args);
+  } catch {
+    return argsJson;
+  }
+}
+
+function sanitizeReadArgs(args) {
+  if (typeof args.limit === "string" && /^\d+$/.test(args.limit)) args.limit = Number(args.limit);
+  if (typeof args.offset === "string" && /^-?\d+$/.test(args.offset)) args.offset = Number(args.offset);
+
+  if (typeof args.limit === "number") {
+    if (args.limit > 2000) args.limit = 2000;
+    if (args.limit < 1) delete args.limit;
+  }
+  if (typeof args.offset === "number" && args.offset < 0) args.offset = 0;
+
+  if ("pages" in args && !isValidPdfPagesArg(args.file_path, args.pages)) {
+    delete args.pages;
+  }
+}
+
+function isValidPdfPagesArg(filePath, pages) {
+  return typeof filePath === "string" &&
+    filePath.toLowerCase().endsWith(".pdf") &&
+    typeof pages === "string" &&
+    /^\d+(?:-\d+)?$/.test(pages);
+}
+
+// Helper: stop thinking block if started
+function stopThinkingBlock(state, results) {
+  if (!state.thinkingBlockStarted) return;
+  results.push({
+    type: "content_block_stop",
+    index: state.thinkingBlockIndex
+  });
+  state.thinkingBlockStarted = false;
+}
+
+// Helper: stop text block if started
+function stopTextBlock(state, results) {
+  if (!state.textBlockStarted || state.textBlockClosed) return;
+  state.textBlockClosed = true;
+  results.push({
+    type: "content_block_stop",
+    index: state.textBlockIndex
+  });
+  state.textBlockStarted = false;
+}
+
+// Convert OpenAI stream chunk to Claude format
+export function openaiToClaudeResponse(chunk, state) {
+  if (!chunk || !chunk.choices?.[0]) return null;
+
+  const results = [];
+  const choice = chunk.choices[0];
+  const delta = choice.delta;
+
+  // Track usage from OpenAI chunk if available
+  if (chunk.usage && typeof chunk.usage === "object") {
+    const promptTokens = typeof chunk.usage.prompt_tokens === "number" ? chunk.usage.prompt_tokens : 0;
+    const outputTokens = typeof chunk.usage.completion_tokens === "number" ? chunk.usage.completion_tokens : 0;
+
+    // Extract cache tokens from prompt_tokens_details
+    const cachedTokens = chunk.usage.prompt_tokens_details?.cached_tokens;
+    const cacheCreationTokens = chunk.usage.prompt_tokens_details?.cache_creation_tokens;
+    const cacheReadTokens = typeof cachedTokens === "number" ? cachedTokens : 0;
+    const cacheCreateTokens = typeof cacheCreationTokens === "number" ? cacheCreationTokens : 0;
+
+    // input_tokens = prompt_tokens - cached_tokens - cache_creation_tokens
+    // Because OpenAI's prompt_tokens includes all prompt-side tokens
+    const inputTokens = promptTokens - cacheReadTokens - cacheCreateTokens;
+
+    state.usage = {
+      input_tokens: inputTokens,
+      output_tokens: outputTokens
+    };
+
+    // Add cache_read_input_tokens if present
+    if (cacheReadTokens > 0) {
+      state.usage.cache_read_input_tokens = cacheReadTokens;
+    }
+
+    // Add cache_creation_input_tokens if present
+    if (cacheCreateTokens > 0) {
+      state.usage.cache_creation_input_tokens = cacheCreateTokens;
+    }
+
+    // Note: completion_tokens_details.reasoning_tokens is already included in output_tokens
+    // No need to add separately as Claude expects total output_tokens
+  }
+
+  // First chunk - ALWAYS send message_start first
+  if (!state.messageStartSent) {
+    state.messageStartSent = true;
+    state.messageId = chunk.id?.replace("chatcmpl-", "") || `msg_${Date.now()}`;
+    if (!state.messageId || state.messageId === "chat" || state.messageId.length < 8) {
+      state.messageId = chunk.extend_fields?.requestId ||
+        chunk.extend_fields?.traceId ||
+        `msg_${Date.now()}`;
+    }
+    state.model = chunk.model || MODEL_FALLBACK;
+    state.nextBlockIndex = 0;
+    results.push({
+      type: "message_start",
+      message: {
+        id: state.messageId,
+        type: "message",
+        role: ROLE.ASSISTANT,
+        model: state.model,
+        content: [],
+        stop_reason: null,
+        stop_sequence: null,
+        usage: { input_tokens: 0, output_tokens: 0 }
+      }
+    });
+  }
+
+  // Handle reasoning (thinking) across vendor shapes - GLM/DeepSeek/Qwen/MiniMax/etc.
+  const reasoningContent = extractReasoningText(delta);
+  if (reasoningContent) {
+    stopTextBlock(state, results);
+
+    if (!state.thinkingBlockStarted) {
+      state.thinkingBlockIndex = state.nextBlockIndex++;
+      state.thinkingBlockStarted = true;
+      results.push({
+        type: "content_block_start",
+        index: state.thinkingBlockIndex,
+        content_block: { type: CLAUDE_BLOCK.THINKING, thinking: "" }
+      });
+    }
+
+    results.push({
+      type: "content_block_delta",
+      index: state.thinkingBlockIndex,
+      delta: { type: "thinking_delta", thinking: reasoningContent }
+    });
+  }
+
+  // Handle regular content
+  if (delta?.content) {
+    stopThinkingBlock(state, results);
+
+    if (!state.textBlockStarted) {
+      state.textBlockIndex = state.nextBlockIndex++;
+      state.textBlockStarted = true;
+      state.textBlockClosed = false;
+      results.push({
+        type: "content_block_start",
+        index: state.textBlockIndex,
+        content_block: { type: CLAUDE_BLOCK.TEXT, text: "" }
+      });
+    }
+
+    results.push({
+      type: "content_block_delta",
+      index: state.textBlockIndex,
+      delta: { type: "text_delta", text: delta.content }
+    });
+  }
+
+  // Tool calls
+  if (delta?.tool_calls) {
+    for (const tc of delta.tool_calls) {
+      const idx = tc.index ?? 0;
+
+      // GLM/fireworks repeats id+null-name on every arg chunk; open block once per idx
+      if (tc.id && !state.toolCalls.has(idx)) {
+        stopThinkingBlock(state, results);
+        stopTextBlock(state, results);
+
+        const toolBlockIndex = state.nextBlockIndex++;
+        state.toolCalls.set(idx, { id: tc.id, name: tc.function?.name || "", blockIndex: toolBlockIndex });
+
+        // Strip prefix from tool name for response
+        let toolName = tc.function?.name || "";
+        if (toolName.startsWith(CLAUDE_OAUTH_TOOL_PREFIX)) {
+          toolName = toolName.slice(CLAUDE_OAUTH_TOOL_PREFIX.length);
+        }
+
+        results.push({
+          type: "content_block_start",
+          index: toolBlockIndex,
+          content_block: {
+            type: CLAUDE_BLOCK.TOOL_USE,
+            id: tc.id,
+            name: toolName,
+            input: {}
+          }
+        });
+      }
+
+      if (tc.function?.arguments) {
+        const toolInfo = state.toolCalls.get(idx);
+        if (toolInfo) {
+          // Buffer args instead of streaming — sanitize at finish to fix bad params
+          if (!state.toolArgBuffers) state.toolArgBuffers = new Map();
+          state.toolArgBuffers.set(idx, (state.toolArgBuffers.get(idx) || "") + tc.function.arguments);
+        }
+      }
+    }
+  }
+
+  // Finish
+  if (choice.finish_reason) {
+    stopThinkingBlock(state, results);
+    stopTextBlock(state, results);
+
+    for (const [idx, toolInfo] of state.toolCalls) {
+      // Emit buffered + sanitized args as single delta before stop
+      const buffered = state.toolArgBuffers?.get(idx);
+      if (buffered) {
+        const sanitized = sanitizeToolArgs(toolInfo.name, buffered);
+        results.push({
+          type: "content_block_delta",
+          index: toolInfo.blockIndex,
+          delta: { type: "input_json_delta", partial_json: sanitized }
+        });
+      }
+      results.push({
+        type: "content_block_stop",
+        index: toolInfo.blockIndex
+      });
+    }
+
+    // Mark finish for later usage injection in stream.js
+    state.finishReason = choice.finish_reason;
+
+    // Use tracked usage (will be estimated in stream.js if not valid)
+    const finalUsage = state.usage || { input_tokens: 0, output_tokens: 0 };
+    results.push({
+      type: "message_delta",
+      delta: { stop_reason: convertFinishReason(choice.finish_reason) },
+      usage: finalUsage
+    });
+    results.push({ type: "message_stop" });
+  }
+
+  return results.length > 0 ? results : null;
+}
+
+const convertFinishReason = (reason) => fromOpenAIFinish(reason, "claude");
+
+// Register
+register(FORMATS.OPENAI, FORMATS.CLAUDE, null, openaiToClaudeResponse);
diff --git a/open-sse/translator/schema/blocks.js b/open-sse/translator/schema/blocks.js
new file mode 100644
index 0000000..61c2564
--- /dev/null
+++ b/open-sse/translator/schema/blocks.js
@@ -0,0 +1,43 @@
+// Content-block "type" discriminators — fixed per format. Pure data (no logic).
+
+// OpenAI chat content blocks + tool_call wrapper.
+export const OPENAI_BLOCK = {
+  TEXT: "text",
+  IMAGE_URL: "image_url",
+  IMAGE: "image",
+  INPUT_AUDIO: "input_audio",
+  AUDIO_URL: "audio_url",
+  FILE: "file",
+  FUNCTION: "function",
+};
+
+// Claude content blocks.
+export const CLAUDE_BLOCK = {
+  TEXT: "text",
+  IMAGE: "image",
+  DOCUMENT: "document",
+  TOOL_USE: "tool_use",
+  TOOL_RESULT: "tool_result",
+  THINKING: "thinking",
+  REDACTED_THINKING: "redacted_thinking",
+};
+
+// OpenAI Responses API item types.
+export const RESPONSES_ITEM = {
+  MESSAGE: "message",
+  FUNCTION_CALL: "function_call",
+  FUNCTION_CALL_OUTPUT: "function_call_output",
+  REASONING: "reasoning",
+  OUTPUT_TEXT: "output_text",
+  INPUT_TEXT: "input_text",
+  INPUT_IMAGE: "input_image",
+  SUMMARY_TEXT: "summary_text",
+};
+
+// Valid OpenAI block types (used by filterToOpenAIFormat).
+export const VALID_OPENAI_CONTENT_TYPES = [
+  OPENAI_BLOCK.TEXT, OPENAI_BLOCK.IMAGE_URL, OPENAI_BLOCK.IMAGE, OPENAI_BLOCK.INPUT_AUDIO, OPENAI_BLOCK.AUDIO_URL, OPENAI_BLOCK.FILE,
+];
+export const VALID_OPENAI_MESSAGE_TYPES = [
+  OPENAI_BLOCK.TEXT, OPENAI_BLOCK.IMAGE_URL, OPENAI_BLOCK.IMAGE, "tool_calls", CLAUDE_BLOCK.TOOL_RESULT,
+];
diff --git a/open-sse/translator/schema/defaults.js b/open-sse/translator/schema/defaults.js
new file mode 100644
index 0000000..9601a47
--- /dev/null
+++ b/open-sse/translator/schema/defaults.js
@@ -0,0 +1,7 @@
+// Shared translator default values (magic strings used across multiple translators).
+
+// Fallback model id when upstream chunk omits one.
+export const MODEL_FALLBACK = "unknown";
+
+// Default image mime when source omits it (base64 blobs without a declared type).
+export const DEFAULT_IMAGE_MIME = "image/png";
diff --git a/open-sse/translator/schema/finishReasons.js b/open-sse/translator/schema/finishReasons.js
new file mode 100644
index 0000000..73535da
--- /dev/null
+++ b/open-sse/translator/schema/finishReasons.js
@@ -0,0 +1,27 @@
+// Finish/stop reason enums. Pure data — mapping LOGIC lives in concerns/finishReason.js.
+
+// OpenAI finish_reason values (the hub format; shared across all response translators).
+export const OPENAI_FINISH = {
+  STOP: "stop",
+  LENGTH: "length",
+  TOOL_CALLS: "tool_calls",
+  CONTENT_FILTER: "content_filter",
+};
+
+// Claude stop_reason values.
+export const CLAUDE_STOP = {
+  END_TURN: "end_turn",
+  MAX_TOKENS: "max_tokens",
+  TOOL_USE: "tool_use",
+  STOP_SEQUENCE: "stop_sequence",
+};
+
+// Gemini finishReason values.
+export const GEMINI_FINISH = {
+  STOP: "STOP",
+  MAX_TOKENS: "MAX_TOKENS",
+  SAFETY: "SAFETY",
+  RECITATION: "RECITATION",
+  BLOCKLIST: "BLOCKLIST",
+  PROHIBITED_CONTENT: "PROHIBITED_CONTENT",
+};
diff --git a/open-sse/translator/schema/index.js b/open-sse/translator/schema/index.js
new file mode 100644
index 0000000..3fada8c
--- /dev/null
+++ b/open-sse/translator/schema/index.js
@@ -0,0 +1,8 @@
+// Translator schema barrel — pure data enums (roles, blocks). No logic here.
+export { ROLE, GEMINI_ROLE } from "./roles.js";
+export {
+  OPENAI_BLOCK, CLAUDE_BLOCK, RESPONSES_ITEM,
+  VALID_OPENAI_CONTENT_TYPES, VALID_OPENAI_MESSAGE_TYPES,
+} from "./blocks.js";
+export { OPENAI_FINISH, CLAUDE_STOP, GEMINI_FINISH } from "./finishReasons.js";
+export { MODEL_FALLBACK, DEFAULT_IMAGE_MIME } from "./defaults.js";
diff --git a/open-sse/translator/schema/roles.js b/open-sse/translator/schema/roles.js
new file mode 100644
index 0000000..1fe91a6
--- /dev/null
+++ b/open-sse/translator/schema/roles.js
@@ -0,0 +1,16 @@
+// Role enums — fixed per format. Pure data (no logic).
+// OpenAI chat / Claude share these; mapping between them stays in translators.
+
+export const ROLE = {
+  USER: "user",
+  ASSISTANT: "assistant",
+  TOOL: "tool",
+  SYSTEM: "system",
+  DEVELOPER: "developer",
+};
+
+// Gemini / Antigravity use "model" instead of "assistant".
+export const GEMINI_ROLE = {
+  USER: "user",
+  MODEL: "model",
+};
diff --git a/open-sse/utils/bypassHandler.js b/open-sse/utils/bypassHandler.js
new file mode 100644
index 0000000..906ce72
--- /dev/null
+++ b/open-sse/utils/bypassHandler.js
@@ -0,0 +1,313 @@
+import { detectFormat } from "../services/provider.js";
+import { translateResponse, initState } from "../translator/index.js";
+import { FORMATS } from "../translator/formats.js";
+import { SKIP_PATTERNS } from "../config/runtimeConfig.js";
+import { formatSSE } from "./stream.js";
+
+/**
+ * Check for bypass patterns - return fake response without calling provider
+ * Only works for Claude CLI requests
+ */
+export function handleBypassRequest(body, model, userAgent = "", ccFilterNaming = false) {
+  if (!userAgent.includes("claude-cli")) return null;
+  if (!body.messages?.length) return null;
+
+  const messages = body.messages;
+  const getText = (content) => {
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      return content.filter(c => c.type === "text").map(c => c.text).join(" ");
+    }
+    return "";
+  };
+
+  let shouldBypass = false;
+  let namingBypass = false;
+
+  // Pattern 1: Title extraction (assistant message = "{")
+  const lastMsg = messages[messages.length - 1];
+  if (lastMsg?.role === "assistant" && lastMsg.content?.[0]?.text === "{") {
+    shouldBypass = true;
+  }
+
+  // Pattern 2: Warmup
+  if (!shouldBypass) {
+    const firstText = getText(messages[0]?.content);
+    if (firstText === "Warmup") {
+      shouldBypass = true;
+    }
+  }
+
+  // Pattern 3: Count
+  if (!shouldBypass && messages.length === 1 && messages[0]?.role === "user") {
+    const firstText = getText(messages[0]?.content);
+    if (firstText === "count") {
+      shouldBypass = true;
+    }
+  }
+
+  // Pattern 4: Skip patterns
+  if (!shouldBypass && SKIP_PATTERNS?.length) {
+    const userMessages = messages.filter(m => m.role === "user");
+    const userText = userMessages.map(m => getText(m.content)).join(" ");
+    if (SKIP_PATTERNS.some(p => userText.includes(p))) {
+      shouldBypass = true;
+    }
+  }
+
+  // Pattern 5: CC naming request (topic title extraction by Claude Code CLI)
+  // Claude format: system is top-level body.system field, not inside messages
+  if (!shouldBypass && ccFilterNaming) {
+    const systemMsg = messages.find(m => m.role === "system");
+    const systemFromMessages = getText(systemMsg?.content);
+    const systemFromBody = Array.isArray(body.system)
+      ? body.system.filter(s => s.type === "text").map(s => s.text).join(" ")
+      : (typeof body.system === "string" ? body.system : "");
+    const systemText = systemFromMessages || systemFromBody;
+    if (systemText.includes("isNewTopic")) {
+      shouldBypass = true;
+      namingBypass = true;
+    }
+  }
+
+  if (!shouldBypass) return null;
+
+  const sourceFormat = detectFormat(body);
+  const stream = body.stream !== false;
+
+  // For naming bypass, generate title from user message
+  if (namingBypass) {
+    const userMsg = messages.find(m => m.role === "user");
+    const userText = getText(userMsg?.content);
+    const title = userText.trim().split(/\s+/).slice(0, 3).join(" ");
+    const namingText = JSON.stringify({ isNewTopic: true, title });
+    return stream
+      ? createStreamingResponse(sourceFormat, model, namingText)
+      : createNonStreamingResponse(sourceFormat, model, namingText);
+  }
+
+  return stream 
+    ? createStreamingResponse(sourceFormat, model)
+    : createNonStreamingResponse(sourceFormat, model);
+}
+
+const DEFAULT_BYPASS_TEXT = "CLI Command Execution: Clear Terminal";
+
+/**
+ * Create OpenAI standard format response
+ */
+function createOpenAIResponse(model, text = DEFAULT_BYPASS_TEXT) {
+  const id = `chatcmpl-${Date.now()}`;
+  const created = Math.floor(Date.now() / 1000);
+
+  return {
+    id,
+    object: "chat.completion",
+    created,
+    model,
+    choices: [{
+      index: 0,
+      message: {
+        role: "assistant",
+        content: text
+      },
+      finish_reason: "stop"
+    }],
+    usage: {
+      prompt_tokens: 1,
+      completion_tokens: 1,
+      total_tokens: 2
+    }
+  };
+}
+
+/**
+ * Create non-streaming response with translation
+ * Use translator to convert OpenAI → sourceFormat
+ */
+function createNonStreamingResponse(sourceFormat, model, text) {
+  const openaiResponse = createOpenAIResponse(model, text);
+
+  // If sourceFormat is OpenAI, return directly
+  if (sourceFormat === FORMATS.OPENAI) {
+    return {
+      success: true,
+      response: new Response(JSON.stringify(openaiResponse), {
+        headers: {
+          "Content-Type": "application/json",
+          "Access-Control-Allow-Origin": "*"
+        }
+      })
+    };
+  }
+
+  // Use translator to convert: simulate streaming then collect all chunks
+  const state = initState(sourceFormat);
+  state.model = model;
+
+  const openaiChunks = createOpenAIStreamingChunks(openaiResponse);
+  const allTranslated = [];
+
+  for (const chunk of openaiChunks) {
+    const translated = translateResponse(FORMATS.OPENAI, sourceFormat, chunk, state);
+    if (translated?.length > 0) {
+      allTranslated.push(...translated);
+    }
+  }
+
+  // Flush remaining
+  const flushed = translateResponse(FORMATS.OPENAI, sourceFormat, null, state);
+  if (flushed?.length > 0) {
+    allTranslated.push(...flushed);
+  }
+
+  // For non-streaming, merge all chunks into final response
+  const finalResponse = mergeChunksToResponse(allTranslated, sourceFormat);
+
+  return {
+    success: true,
+    response: new Response(JSON.stringify(finalResponse), {
+      headers: {
+        "Content-Type": "application/json",
+        "Access-Control-Allow-Origin": "*"
+      }
+    })
+  };
+}
+
+/**
+ * Create streaming response with translation
+ * Use translator to convert OpenAI chunks → sourceFormat
+ */
+function createStreamingResponse(sourceFormat, model, text) {
+  const openaiResponse = createOpenAIResponse(model, text);
+  const state = initState(sourceFormat);
+  state.model = model;
+
+  // Create OpenAI streaming chunks
+  const openaiChunks = createOpenAIStreamingChunks(openaiResponse);
+
+  // Translate each chunk to sourceFormat using translator
+  const translatedChunks = [];
+
+  for (const chunk of openaiChunks) {
+    const translated = translateResponse(FORMATS.OPENAI, sourceFormat, chunk, state);
+    if (translated?.length > 0) {
+      for (const item of translated) {
+        translatedChunks.push(formatSSE(item, sourceFormat));
+      }
+    }
+  }
+
+  // Flush remaining events
+  const flushed = translateResponse(FORMATS.OPENAI, sourceFormat, null, state);
+  if (flushed?.length > 0) {
+    for (const item of flushed) {
+      translatedChunks.push(formatSSE(item, sourceFormat));
+    }
+  }
+
+  // Add [DONE]
+  translatedChunks.push("data: [DONE]\n\n");
+
+  return {
+    success: true,
+    response: new Response(translatedChunks.join(""), {
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+        "Access-Control-Allow-Origin": "*"
+      }
+    })
+  };
+}
+
+/**
+ * Merge translated chunks into final response object (for non-streaming)
+ * Takes the last complete chunk as the final response
+ */
+function mergeChunksToResponse(chunks, sourceFormat) {
+  if (!chunks || chunks.length === 0) {
+    return createOpenAIResponse("unknown");
+  }
+
+  // For most formats, the last chunk before done contains the complete response
+  // Find the most complete chunk (usually the last one with content)
+  let finalChunk = chunks[chunks.length - 1];
+
+  // For Claude format, find the message_stop or final message
+  if (sourceFormat === FORMATS.CLAUDE) {
+    const messageStop = chunks.find(c => c.type === "message_stop");
+    if (messageStop) {
+      // Reconstruct complete message from chunks
+      const contentDelta = chunks.find(c => c.type === "content_block_delta");
+      const messageDelta = chunks.find(c => c.type === "message_delta");
+      const messageStart = chunks.find(c => c.type === "message_start");
+
+      if (messageStart?.message) {
+        finalChunk = messageStart.message;
+        // message_start.usage has input + cache; message_delta.usage has the
+        // final output_tokens. Merge so cache survives (delta omits it).
+        const startUsage = messageStart.message.usage;
+        const deltaUsage = messageDelta?.usage;
+        if (startUsage || deltaUsage) {
+          finalChunk.usage = {
+            ...(startUsage || {}),
+            ...(deltaUsage || {}),
+            ...(startUsage?.cache_read_input_tokens !== undefined
+              ? { cache_read_input_tokens: startUsage.cache_read_input_tokens }
+              : {}),
+            ...(startUsage?.cache_creation_input_tokens !== undefined
+              ? { cache_creation_input_tokens: startUsage.cache_creation_input_tokens }
+              : {}),
+            ...(startUsage?.input_tokens !== undefined
+              ? { input_tokens: startUsage.input_tokens }
+              : {})
+          };
+        }
+      }
+    }
+  }
+
+  return finalChunk;
+}
+
+/**
+ * Create OpenAI streaming chunks from complete response
+ */
+function createOpenAIStreamingChunks(completeResponse) {
+  const { id, created, model, choices } = completeResponse;
+  const content = choices[0].message.content;
+
+  return [
+    // Chunk with content
+    {
+      id,
+      object: "chat.completion.chunk",
+      created,
+      model,
+      choices: [{
+        index: 0,
+        delta: {
+          role: "assistant",
+          content
+        },
+        finish_reason: null
+      }]
+    },
+    // Final chunk with finish_reason
+    {
+      id,
+      object: "chat.completion.chunk",
+      created,
+      model,
+      choices: [{
+        index: 0,
+        delta: {},
+        finish_reason: "stop"
+      }],
+      usage: completeResponse.usage
+    }
+  ];
+}
diff --git a/open-sse/utils/claudeCloaking.js b/open-sse/utils/claudeCloaking.js
new file mode 100644
index 0000000..46a44e4
--- /dev/null
+++ b/open-sse/utils/claudeCloaking.js
@@ -0,0 +1,165 @@
+import { createHash, randomBytes, randomUUID } from "crypto";
+import { CLAUDE_TOOL_SUFFIX, CC_DEFAULT_TOOLS } from "../config/appConstants.js";
+
+const CLAUDE_VERSION = "2.1.92";
+const CC_ENTRYPOINT = "sdk-cli";
+
+// Generate billing header matching real Claude Code 2.1.92+ format:
+// x-anthropic-billing-header: cc_version=<ver>.<build>; cc_entrypoint=sdk-cli; cch=<hash>;
+function generateBillingHeader(payload) {
+  const content = JSON.stringify(payload);
+  const cch = createHash("sha256").update(content).digest("hex").slice(0, 5);
+  const buildHash = randomBytes(2).toString("hex").slice(0, 3);
+  return `x-anthropic-billing-header: cc_version=${CLAUDE_VERSION}.${buildHash}; cc_entrypoint=${CC_ENTRYPOINT}; cch=${cch};`;
+}
+
+// Derive a deterministic UUID-v4-shaped string from a seed (stable per account)
+function deriveUuid(seed) {
+  const h = createHash("sha256").update(seed).digest("hex");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${((parseInt(h[16], 16) & 0x3) | 0x8).toString(16)}${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+
+// Generate fake user ID in Claude Code 2.1.92+ JSON format:
+// {"device_id":"<64hex>","account_uuid":"<uuid>","session_id":"<uuid>"}
+// device_id/account_uuid derive from apiKey (stable per account), session_id per-conversation
+function generateFakeUserID(sessionId, apiKey) {
+  const deviceId = apiKey ? createHash("sha256").update(`device:${apiKey}`).digest("hex") : randomBytes(32).toString("hex");
+  const accountUuid = apiKey ? deriveUuid(`account:${apiKey}`) : randomUUID();
+  const sessionUuid = sessionId || randomUUID();
+  return `{"device_id":"${deviceId}","account_uuid":"${accountUuid}","session_id":"${sessionUuid}"}`;
+}
+
+/**
+ * Cloak tools before sending to Claude provider (anti-ban):
+ * - Rename non-CC client tools with _cc suffix in tools[] and messages[]
+ * - Skip tools that are already CC default names (they become decoys as-is)
+ * - Inject CC_DECOY_TOOLS after client tools
+ * Returns { body, toolNameMap } where toolNameMap maps suffixed → original
+ * @param {object} body - Claude API request body
+ * @returns {{ body: object, toolNameMap: Map|null }}
+ */
+export function cloakClaudeTools(body) {
+  const tools = body.tools;
+  if (!tools || tools.length === 0) return { body, toolNameMap: null };
+
+  const suffix = (name) => `${name}${CLAUDE_TOOL_SUFFIX}`;
+  const toolNameMap = new Map();
+  const clientToolNames = new Set();
+  const clientDeclarations = [];
+
+  // All client tools get renamed with suffix.
+  // Built-in server tools (web_search_20250305, etc.) carry a `type` and require
+  // an exact reserved `name` — never suffix those or Claude rejects the request.
+  for (const tool of tools) {
+    if (tool.type) { clientDeclarations.push(tool); continue; }
+    const suffixed = suffix(tool.name);
+    toolNameMap.set(suffixed, tool.name);
+    clientToolNames.add(tool.name);
+    clientDeclarations.push({ ...tool, name: suffixed });
+  }
+
+  // Client tools first, then CC decoy tools (no overlap: client tools all have _cc suffix)
+  const allTools = [...clientDeclarations, ...CC_DECOY_TOOLS];
+
+  // Rename tool_use in message history (all client tools get suffix)
+  const renamedMessages = body.messages?.map(msg => {
+    if (!Array.isArray(msg.content)) return msg;
+    const renamedContent = msg.content.map(block =>
+      block.type === "tool_use" ? { ...block, name: suffix(block.name) } : block
+    );
+    return { ...msg, content: renamedContent };
+  });
+
+  const cloakedBody = { ...body, tools: allTools, messages: renamedMessages || body.messages };
+
+  // A forced tool_choice ({ type: "tool", name }) must point at the suffixed
+  // tool name, otherwise Claude rejects it: "Tool '<name>' not found in provided tools".
+  // Only rewrite when the choice targets one of the client tools we actually
+  // renamed — never a decoy/built-in name (those are sent unsuffixed).
+  if (
+    body.tool_choice?.type === "tool" &&
+    clientToolNames.has(body.tool_choice.name)
+  ) {
+    cloakedBody.tool_choice = { ...body.tool_choice, name: suffix(body.tool_choice.name) };
+  }
+
+  return {
+    body: cloakedBody,
+    toolNameMap: toolNameMap.size > 0 ? toolNameMap : null
+  };
+}
+
+// Decloak tool_use names in non-streaming Claude response body (INPUT side)
+export function decloakToolNames(body, toolNameMap) {
+  if (!toolNameMap?.size || !Array.isArray(body?.content)) return body;
+  const content = body.content.map(block => {
+    if (block?.type === "tool_use" && toolNameMap.has(block.name)) {
+      return { ...block, name: toolNameMap.get(block.name) };
+    }
+    return block;
+  });
+  return { ...body, content };
+}
+
+// CC decoy tools — Claude Code native tool names, marked unavailable
+const CC_DECOY_TOOLS = [
+  { name: "Task", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "TaskOutput", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "TaskStop", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "TaskCreate", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "TaskGet", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "TaskUpdate", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "TaskList", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "Bash", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "Glob", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "Grep", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "Read", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "Edit", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "Write", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "NotebookEdit", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "WebFetch", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "WebSearch", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "AskUserQuestion", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "Skill", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "EnterPlanMode", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+  { name: "ExitPlanMode", description: "This tool is currently unavailable.", input_schema: { type: "object", properties: {} } },
+];
+
+/**
+ * Apply Claude cloaking to request body:
+ * 1. Inject billing header as first system block
+ * 2. Inject fake user ID into metadata (JSON format, session_id aligned with X-Claude-Code-Session-Id)
+ * Only applies when using OAuth token (sk-ant-oat).
+ * @param {object} body - Claude API request body
+ * @param {string} apiKey - API key or OAuth token
+ * @param {string} [sessionId] - Session ID to align with X-Claude-Code-Session-Id header
+ * @returns {object} Modified body
+ */
+export function applyCloaking(body, apiKey, sessionId) {
+  if (!apiKey || !apiKey.includes("sk-ant-oat")) return body;
+
+  const result = { ...body };
+
+  // Inject billing header as system[0], preserve existing system blocks
+  const billingText = generateBillingHeader(body);
+  const billingBlock = { type: "text", text: billingText };
+
+  if (Array.isArray(result.system)) {
+    // Skip if already injected
+    if (!result.system[0]?.text?.startsWith("x-anthropic-billing-header:")) {
+      result.system = [billingBlock, ...result.system];
+    }
+  } else if (typeof result.system === "string") {
+    result.system = [billingBlock, { type: "text", text: result.system }];
+  } else {
+    result.system = [billingBlock];
+  }
+
+  // Inject fake user ID into metadata (session_id must match X-Claude-Code-Session-Id)
+  const existingUserId = result.metadata?.user_id;
+  if (!existingUserId) {
+    result.metadata = { ...result.metadata, user_id: generateFakeUserID(sessionId, apiKey) };
+  }
+
+  return result;
+}
diff --git a/open-sse/utils/claudeHeaderCache.js b/open-sse/utils/claudeHeaderCache.js
new file mode 100644
index 0000000..11b2eb8
--- /dev/null
+++ b/open-sse/utils/claudeHeaderCache.js
@@ -0,0 +1,70 @@
+/**
+ * Singleton cache for real Claude Code client headers.
+ * Captures headers from authentic Claude Code requests and makes them available
+ * for forwarding to api.anthropic.com, replacing static hardcoded values.
+ */
+
+const CLAUDE_IDENTITY_HEADERS = [
+  "user-agent",
+  "anthropic-beta",
+  "anthropic-version",
+  "anthropic-dangerous-direct-browser-access",
+  "x-app",
+  "x-stainless-helper-method",
+  "x-stainless-retry-count",
+  "x-stainless-runtime-version",
+  "x-stainless-package-version",
+  "x-stainless-runtime",
+  "x-stainless-lang",
+  "x-stainless-arch",
+  "x-stainless-os",
+  "x-stainless-timeout",
+  "x-claude-code-session-id",
+  "package-version",
+  "runtime-version",
+  "os",
+  "arch",
+];
+
+let cachedHeaders = null;
+
+/**
+ * Detect if request headers look like a real Claude Code client.
+ * @param {object} headers - Lowercase header key/value object
+ */
+function isClaudeCodeClient(headers) {
+  const ua = (headers["user-agent"] || "").toLowerCase();
+  const xApp = (headers["x-app"] || "").toLowerCase();
+  return ua.includes("claude-cli") || ua.includes("claude-code") || xApp === "cli";
+}
+
+/**
+ * Store Claude Code identity headers if this looks like a real client request.
+ * Called at the entry point before any translation/forwarding.
+ * @param {object} headers - Lowercase header key/value object (from request.headers.entries())
+ */
+export function cacheClaudeHeaders(headers) {
+  if (!headers || typeof headers !== "object") return;
+  if (!isClaudeCodeClient(headers)) return;
+
+  const captured = {};
+  for (const key of CLAUDE_IDENTITY_HEADERS) {
+    if (headers[key] !== undefined && headers[key] !== null) {
+      captured[key] = headers[key];
+    }
+  }
+
+  if (Object.keys(captured).length > 0) {
+    cachedHeaders = captured;
+    console.log(`[ClaudeHeaders] Cached ${Object.keys(captured).length} identity headers from Claude Code client`);
+  }
+}
+
+/**
+ * Get the most recently cached Claude Code identity headers.
+ * Returns null if no authentic client request has been seen yet (cold start).
+ * @returns {object|null}
+ */
+export function getCachedClaudeHeaders() {
+  return cachedHeaders;
+}
diff --git a/open-sse/utils/claudeSignature.js b/open-sse/utils/claudeSignature.js
new file mode 100644
index 0000000..1a18696
--- /dev/null
+++ b/open-sse/utils/claudeSignature.js
@@ -0,0 +1,41 @@
+// Claude thinking signature validation (ported from CLIProxyAPI internal/signature).
+// E-form: single-layer base64, decoded[0] == 0x12 (Claude marker).
+// R-form: double-layer base64, outer decoded[0] == 'E', inner decoded[0] == 0x12.
+// Cache prefix "...#sig" stripped before validation.
+
+const MAX_CLAUDE_SIGNATURE_LEN = 32 * 1024 * 1024;
+const CLAUDE_SIGNATURE_MARKER = 0x12;
+
+function stripCachePrefix(rawSignature) {
+  const sig = (rawSignature || "").trim();
+  if (!sig) return "";
+  const idx = sig.indexOf("#");
+  return idx >= 0 ? sig.slice(idx + 1).trim() : sig;
+}
+
+export function hasClaudeSignaturePrefix(rawSignature) {
+  const sig = stripCachePrefix(rawSignature);
+  return sig.length > 0 && (sig[0] === "E" || sig[0] === "R");
+}
+
+// Strict-ish: validates base64 layers + Claude marker byte.
+export function isValidClaudeSignature(rawSignature) {
+  const sig = stripCachePrefix(rawSignature);
+  if (!sig || sig.length > MAX_CLAUDE_SIGNATURE_LEN) return false;
+
+  try {
+    if (sig[0] === "E") {
+      const decoded = Buffer.from(sig, "base64");
+      return decoded.length > 0 && decoded[0] === CLAUDE_SIGNATURE_MARKER;
+    }
+    if (sig[0] === "R") {
+      const outer = Buffer.from(sig, "base64");
+      if (!outer.length || outer[0] !== 0x45) return false; // 'E'
+      const inner = Buffer.from(outer.toString(), "base64");
+      return inner.length > 0 && inner[0] === CLAUDE_SIGNATURE_MARKER;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
diff --git a/open-sse/utils/clientDetector.js b/open-sse/utils/clientDetector.js
new file mode 100644
index 0000000..2d1381b
--- /dev/null
+++ b/open-sse/utils/clientDetector.js
@@ -0,0 +1,63 @@
+/**
+ * Detect CLI tool identity from request headers/body.
+ * Used to determine if a request can be passed through losslessly.
+ */
+
+// Map of CLI tool identifiers to provider IDs they are "native" to
+const NATIVE_PAIRS = {
+  "claude": ["claude", "anthropic"],
+  "gemini-cli": ["gemini-cli"],
+  "antigravity": ["antigravity"],
+  "codex": ["codex"],
+};
+
+/**
+ * Detect which CLI tool is making the request.
+ * Returns one of: "claude" | "gemini-cli" | "antigravity" | "codex" | null
+ * @param {object} headers - Lowercase header key/value object
+ * @param {object} body    - Parsed request body
+ */
+export function detectClientTool(headers = {}, body = {}) {
+  const ua = (headers["user-agent"] || "").toLowerCase();
+  const xApp = (headers["x-app"] || "").toLowerCase();
+  const openaiIntent = (headers["openai-intent"] || "").toLowerCase();
+  const initiator = (headers["x-initiator"] || headers["X-Initiator"] || "").toLowerCase();
+
+  // Antigravity: detected via body field (not header)
+  if (body.userAgent === "antigravity") return "antigravity";
+
+  // GitHub Copilot / OAI compatible extension using Copilot chat headers
+  if (ua.includes("githubcopilotchat") || openaiIntent === "conversation-panel" || initiator === "user") {
+    return "github-copilot";
+  }
+
+  // Claude Code / Claude CLI
+  if (ua.includes("claude-cli") || ua.includes("claude-code") || xApp === "cli") return "claude";
+
+  // Gemini CLI
+  if (ua.includes("gemini-cli")) return "gemini-cli";
+
+  // Codex CLI
+  if (ua.includes("codex-cli")) return "codex";
+
+  // DeepSeek TUI
+  if (ua.includes("deepseek-tui")) return "deepseek-tui";
+
+  return null;
+}
+
+/**
+ * Check if this CLI tool + provider pair should be passed through losslessly.
+ * @param {string|null} clientTool - Result of detectClientTool()
+ * @param {string} provider        - Provider ID (e.g. "claude", "gemini-cli")
+ */
+export function isNativePassthrough(clientTool, provider) {
+  if (!clientTool) return false;
+  const nativeProviders = NATIVE_PAIRS[clientTool];
+  if (!nativeProviders) return false;
+  // Support anthropic-compatible-* variants
+  const normalizedProvider = provider.startsWith("anthropic-compatible")
+    ? "anthropic"
+    : provider;
+  return nativeProviders.includes(normalizedProvider);
+}
diff --git a/open-sse/utils/cursorChecksum.js b/open-sse/utils/cursorChecksum.js
new file mode 100644
index 0000000..961df7a
--- /dev/null
+++ b/open-sse/utils/cursorChecksum.js
@@ -0,0 +1,149 @@
+/**
+ * Cursor Checksum Utility (Jyh Cipher)
+ *
+ * Generates the x-cursor-checksum header required for Cursor API authentication.
+ * Based on the JavaScript implementation from Cursor IDE.
+ */
+
+import crypto from "crypto";
+import { v5 as uuidv5 } from "uuid";
+
+/**
+ * Generate SHA-256 hash like generateHashed64Hex
+ * @param {string} input - Input string
+ * @param {string} salt - Optional salt
+ * @returns {string} - 64-character hex string
+ */
+export function generateHashed64Hex(input, salt = "") {
+  return crypto.createHash("sha256").update(input + salt).digest("hex");
+}
+
+/**
+ * Generate session ID using UUID v5 with DNS namespace
+ * @param {string} authToken - Auth token
+ * @returns {string} - UUID string
+ */
+export function generateSessionId(authToken) {
+  return uuidv5(authToken, uuidv5.DNS);
+}
+
+/**
+ * Generate cursor checksum (Jyh cipher)
+ *
+ * Algorithm:
+ * 1. Get Unix timestamp in specific format
+ * 2. XOR each byte with key (starting 165)
+ * 3. Update key: key = (key + byte) & 0xFF
+ * 4. URL-safe base64 encode
+ * 5. Format: {base64_encoded}{machineId}
+ *
+ * @param {string} machineId - Machine ID from Cursor storage or generated
+ * @returns {string} - Checksum string
+ */
+export function generateCursorChecksum(machineId) {
+  // Math.floor(Date.now() / 1e6) - same as Python implementation
+  const timestamp = Math.floor(Date.now() / 1000000);
+
+  // Create byte array from timestamp (6 bytes, big-endian)
+  const byteArray = new Uint8Array([
+    (timestamp >> 40) & 0xFF,
+    (timestamp >> 32) & 0xFF,
+    (timestamp >> 24) & 0xFF,
+    (timestamp >> 16) & 0xFF,
+    (timestamp >> 8) & 0xFF,
+    timestamp & 0xFF
+  ]);
+
+  // Jyh cipher obfuscation
+  let t = 165;
+  for (let i = 0; i < byteArray.length; i++) {
+    byteArray[i] = ((byteArray[i] ^ t) + (i % 256)) & 0xFF;
+    t = byteArray[i];
+  }
+
+  // URL-safe base64 encode (without padding)
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+  let encoded = "";
+
+  for (let i = 0; i < byteArray.length; i += 3) {
+    const a = byteArray[i];
+    const b = i + 1 < byteArray.length ? byteArray[i + 1] : 0;
+    const c = i + 2 < byteArray.length ? byteArray[i + 2] : 0;
+
+    encoded += alphabet[a >> 2];
+    encoded += alphabet[((a & 3) << 4) | (b >> 4)];
+
+    if (i + 1 < byteArray.length) {
+      encoded += alphabet[((b & 15) << 2) | (c >> 6)];
+    }
+    if (i + 2 < byteArray.length) {
+      encoded += alphabet[c & 63];
+    }
+  }
+
+  return `${encoded}${machineId}`;
+}
+
+/**
+ * Build all Cursor API headers
+ *
+ * @param {string} accessToken - Bearer token
+ * @param {string} machineId - Machine ID (or will be generated from token)
+ * @param {boolean} ghostMode - Enable ghost mode (privacy)
+ * @returns {Object} - Headers object
+ */
+export function buildCursorHeaders(accessToken, machineId = null, ghostMode = true) {
+  // Clean token if it has prefix
+  const cleanToken = accessToken.includes("::")
+    ? accessToken.split("::")[1]
+    : accessToken;
+
+  // Generate machine ID if not provided
+  const effectiveMachineId = machineId || generateHashed64Hex(cleanToken, "machineId");
+
+  // Generate derived values
+  const sessionId = generateSessionId(cleanToken);
+  const clientKey = generateHashed64Hex(cleanToken);
+  const checksum = generateCursorChecksum(effectiveMachineId);
+
+  // Detect OS
+  let os = "linux";
+  if (typeof process !== "undefined") {
+    if (process.platform === "win32") os = "windows";
+    else if (process.platform === "darwin") os = "macos";
+  }
+
+  // Detect architecture
+  let arch = "x64";
+  if (typeof process !== "undefined") {
+    if (process.arch === "arm64") arch = "aarch64";
+  }
+
+  return {
+    "authorization": `Bearer ${cleanToken}`,
+    "connect-accept-encoding": "gzip",
+    "connect-protocol-version": "1",
+    "content-type": "application/connect+proto",
+    "user-agent": "connect-es/1.6.1",
+    "x-amzn-trace-id": `Root=${crypto.randomUUID()}`,
+    "x-client-key": clientKey,
+    "x-cursor-checksum": checksum,
+    "x-cursor-client-version": "3.1.0",
+    "x-cursor-client-type": "ide",
+    "x-cursor-client-os": os,
+    "x-cursor-client-arch": arch,
+    "x-cursor-client-device-type": "desktop",
+    "x-cursor-config-version": crypto.randomUUID(),
+    "x-cursor-timezone": Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
+    "x-ghost-mode": ghostMode ? "true" : "false",
+    "x-request-id": crypto.randomUUID(),
+    "x-session-id": sessionId
+  };
+}
+
+export default {
+  generateCursorChecksum,
+  buildCursorHeaders,
+  generateHashed64Hex,
+  generateSessionId
+};
diff --git a/open-sse/utils/cursorProtobuf.js b/open-sse/utils/cursorProtobuf.js
new file mode 100644
index 0000000..c870921
--- /dev/null
+++ b/open-sse/utils/cursorProtobuf.js
@@ -0,0 +1,904 @@
+/**
+ * Cursor Protobuf Encoder/Decoder
+ * Implements ConnectRPC protobuf wire format for Cursor API
+ */
+
+import { v4 as uuidv4 } from "uuid";
+import zlib from "zlib";
+
+const DEBUG = process.env.CURSOR_PROTOBUF_DEBUG === "1";
+const log = (tag, ...args) => DEBUG && console.log(`[PROTOBUF:${tag}]`, ...args);
+const textDecoder = new TextDecoder();
+
+const PROTOBUF_SCHEMA_VERSION = "1.1.3";
+
+// ==================== SCHEMAS ====================
+
+const WIRE_TYPE = { VARINT: 0, FIXED64: 1, LEN: 2, FIXED32: 5 };
+
+const ROLE = { USER: 1, ASSISTANT: 2 };
+
+const UNIFIED_MODE = { CHAT: 1, AGENT: 2 };
+
+const THINKING_LEVEL = { UNSPECIFIED: 0, MEDIUM: 1, HIGH: 2 };
+const CLIENT_SIDE_TOOL_V2 = { MCP: 19 };
+const CLIENT_SIDE_TOOL_V2_MCP = 19;
+
+const FIELD = {
+  // StreamUnifiedChatRequestWithTools (top level)
+  REQUEST: 1,
+
+  // StreamUnifiedChatRequest
+  MESSAGES: 1,
+  UNKNOWN_2: 2,
+  INSTRUCTION: 3,
+  UNKNOWN_4: 4,
+  MODEL: 5,
+  WEB_TOOL: 8,
+  UNKNOWN_13: 13,
+  CURSOR_SETTING: 15,
+  UNKNOWN_19: 19,
+  CONVERSATION_ID: 23,
+  METADATA: 26,
+  IS_AGENTIC: 27,
+  SUPPORTED_TOOLS: 29,
+  MESSAGE_IDS: 30,
+  MCP_TOOLS: 34,
+  LARGE_CONTEXT: 35,
+  UNKNOWN_38: 38,
+  UNIFIED_MODE: 46,
+  UNKNOWN_47: 47,
+  SHOULD_DISABLE_TOOLS: 48,
+  THINKING_LEVEL: 49,
+  UNKNOWN_51: 51,
+  UNKNOWN_53: 53,
+  UNIFIED_MODE_NAME: 54,
+
+  // ConversationMessage
+  MSG_CONTENT: 1,
+  MSG_ROLE: 2,
+  MSG_ID: 13,
+  MSG_TOOL_RESULTS: 18,
+  MSG_IS_AGENTIC: 29,
+  MSG_SERVER_BUBBLE_ID: 32,
+  MSG_UNIFIED_MODE: 47,
+  MSG_SUPPORTED_TOOLS: 51,
+
+  // ConversationMessage.ToolResult
+  TOOL_RESULT_CALL_ID: 1,
+  TOOL_RESULT_NAME: 2,
+  TOOL_RESULT_INDEX: 3,
+  TOOL_RESULT_RAW_ARGS: 5,
+  TOOL_RESULT_RESULT: 8,
+  TOOL_RESULT_TOOL_CALL: 11,
+  TOOL_RESULT_MODEL_CALL_ID: 12,
+
+  // ClientSideToolV2Result (nested inside ToolResult.result)
+  CLIENT_RESULT_TOOL: 1,
+  CLIENT_RESULT_MCP_RESULT: 28,
+  CLIENT_RESULT_TOOL_CALL_ID: 35,
+  CLIENT_RESULT_MODEL_CALL_ID: 48,
+  CLIENT_RESULT_TOOL_INDEX: 49,
+  // Aliases used by encodeClientSideToolV2Result
+  CV2R_TOOL: 1,
+  CV2R_MCP_RESULT: 28,
+  CV2R_CALL_ID: 35,
+  CV2R_MODEL_CALL_ID: 48,
+  CV2R_TOOL_INDEX: 49,
+
+  // MCPResult (nested inside ClientSideToolV2Result.mcp_result)
+  MCP_RESULT_SELECTED_TOOL: 1,
+  MCP_RESULT_RESULT: 2,
+  // Aliases used by encodeMcpResult
+  MCPR_SELECTED_TOOL: 1,
+  MCPR_RESULT: 2,
+
+  // ClientSideToolV2Call (nested inside ToolResult.tool_call)
+  CLIENT_CALL_TOOL: 1,
+  CLIENT_CALL_MCP_PARAMS: 27,
+  CLIENT_CALL_TOOL_CALL_ID: 3,
+  CLIENT_CALL_NAME: 9,
+  CLIENT_CALL_RAW_ARGS: 10,
+  CLIENT_CALL_TOOL_INDEX: 48,
+  CLIENT_CALL_MODEL_CALL_ID: 49,
+  // Aliases used by encodeClientSideToolV2Call
+  CV2C_TOOL: 1,
+  CV2C_MCP_PARAMS: 27,
+  CV2C_CALL_ID: 3,
+  CV2C_NAME: 9,
+  CV2C_RAW_ARGS: 10,
+  CV2C_TOOL_INDEX: 48,
+  CV2C_MODEL_CALL_ID: 49,
+
+  // Model
+  MODEL_NAME: 1,
+  MODEL_EMPTY: 4,
+
+  // Instruction
+  INSTRUCTION_TEXT: 1,
+
+  // CursorSetting
+  SETTING_PATH: 1,
+  SETTING_UNKNOWN_3: 3,
+  SETTING_UNKNOWN_6: 6,
+  SETTING_UNKNOWN_8: 8,
+  SETTING_UNKNOWN_9: 9,
+
+  // CursorSetting.Unknown6
+  SETTING6_FIELD_1: 1,
+  SETTING6_FIELD_2: 2,
+
+  // Metadata
+  META_PLATFORM: 1,
+  META_ARCH: 2,
+  META_VERSION: 3,
+  META_CWD: 4,
+  META_TIMESTAMP: 5,
+
+  // MessageId
+  MSGID_ID: 1,
+  MSGID_SUMMARY: 2,
+  MSGID_ROLE: 3,
+
+  // MCPTool
+  MCP_TOOL_NAME: 1,
+  MCP_TOOL_DESC: 2,
+  MCP_TOOL_PARAMS: 3,
+  MCP_TOOL_SERVER: 4,
+
+  // StreamUnifiedChatResponseWithTools (response)
+  TOOL_CALL: 1,
+  RESPONSE: 2,
+
+  // ClientSideToolV2Call
+  TOOL_ID: 3,
+  TOOL_NAME: 9,
+  TOOL_RAW_ARGS: 10,
+  TOOL_IS_LAST: 11,
+  TOOL_IS_LAST_ALT: 15,
+  TOOL_MCP_PARAMS: 27,
+
+  // MCPParams
+  MCP_TOOLS_LIST: 1,
+
+  // MCPParams.Tool (nested)
+  MCP_NESTED_NAME: 1,
+  MCP_NESTED_PARAMS: 3,
+
+  // StreamUnifiedChatResponse
+  RESPONSE_TEXT: 1,
+  THINKING: 25,
+
+  // Thinking
+  THINKING_TEXT: 1
+};
+
+// Known response field numbers — used to detect unknown fields from protocol updates
+const KNOWN_RESPONSE_FIELDS = new Set([
+  FIELD.TOOL_CALL,
+  FIELD.RESPONSE,
+  FIELD.TOOL_ID,
+  FIELD.TOOL_NAME,
+  FIELD.TOOL_RAW_ARGS,
+  FIELD.TOOL_IS_LAST,
+  FIELD.TOOL_MCP_PARAMS,
+  FIELD.RESPONSE_TEXT,
+  FIELD.THINKING
+]);
+
+// ==================== PRIMITIVE ENCODING ====================
+
+export function encodeVarint(value) {
+  const bytes = [];
+  while (value >= 0x80) {
+    bytes.push((value & 0x7F) | 0x80);
+    value >>>= 7;
+  }
+  bytes.push(value & 0x7F);
+  return new Uint8Array(bytes);
+}
+
+export function encodeField(fieldNum, wireType, value) {
+  const tag = (fieldNum << 3) | wireType;
+  const tagBytes = encodeVarint(tag);
+
+  if (wireType === WIRE_TYPE.VARINT) {
+    const valueBytes = encodeVarint(value);
+    return concatArrays(tagBytes, valueBytes);
+  }
+
+  if (wireType === WIRE_TYPE.LEN) {
+    const dataBytes = typeof value === "string" 
+      ? new TextEncoder().encode(value)
+      : value instanceof Uint8Array ? value
+      : Buffer.isBuffer(value) ? new Uint8Array(value)
+      : new Uint8Array(0);
+    
+    const lengthBytes = encodeVarint(dataBytes.length);
+    return concatArrays(tagBytes, lengthBytes, dataBytes);
+  }
+
+  return new Uint8Array(0);
+}
+
+function concatArrays(...arrays) {
+  const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}
+
+// ==================== MESSAGE ENCODING ====================
+
+/**
+ * Format tool name: "toolName" → "mcp_custom_toolName"
+ * Also handles: "mcp__server__tool" → "mcp_server_tool"
+ */
+function formatToolName(name) {
+  const base = typeof name === "string" && name.length > 0 ? name : "tool";
+
+  if (base.startsWith("mcp__")) {
+    const rest = base.slice("mcp__".length);
+    const splitIdx = rest.indexOf("__");
+    if (splitIdx >= 0) {
+      const server = rest.slice(0, splitIdx) || "custom";
+      const toolName = rest.slice(splitIdx + 2) || "tool";
+      return `mcp_${server}_${toolName}`;
+    }
+    return `mcp_custom_${rest || "tool"}`;
+  }
+
+  if (base.startsWith("mcp_")) return base;
+  return `mcp_custom_${base}`;
+}
+
+/**
+ * Parse formatted tool name: "mcp_server_tool" → { serverName, selectedTool }
+ */
+function parseToolName(formattedName) {
+  if (typeof formattedName !== "string" || !formattedName.startsWith("mcp_")) {
+    return { serverName: "custom", selectedTool: formattedName || "tool" };
+  }
+
+  const tail = formattedName.slice("mcp_".length);
+  const splitIdx = tail.indexOf("_");
+  if (splitIdx < 0) {
+    return { serverName: "custom", selectedTool: tail || "tool" };
+  }
+
+  return {
+    serverName: tail.slice(0, splitIdx) || "custom",
+    selectedTool: tail.slice(splitIdx + 1) || "tool"
+  };
+}
+
+/**
+ * Parse tool_call_id into { toolCallId, modelCallId }
+ * Cursor uses "\nmc_" delimiter for model_call_id
+ */
+function parseToolId(id) {
+  const delimiter = "\nmc_";
+  const idx = id.indexOf(delimiter);
+  if (idx >= 0) {
+    return { toolCallId: id.slice(0, idx), modelCallId: id.slice(idx + delimiter.length) };
+  }
+  return { toolCallId: id, modelCallId: null };
+}
+
+/**
+ * Encode MCPResult proto: { selected_tool, result }
+ */
+function encodeMcpResult(selectedTool, resultContent) {
+  return concatArrays(
+    encodeField(FIELD.MCPR_SELECTED_TOOL, WIRE_TYPE.LEN, selectedTool),
+    encodeField(FIELD.MCPR_RESULT, WIRE_TYPE.LEN, resultContent)
+  );
+}
+
+/**
+ * Encode ClientSideToolV2Result proto: { tool, mcp_result, call_id, model_call_id, tool_index }
+ * Represents the result of executing a tool
+ */
+function encodeClientSideToolV2Result(toolCallId, modelCallId, selectedTool, resultContent, toolIndex = 1) {
+  return concatArrays(
+    encodeField(FIELD.CV2R_TOOL, WIRE_TYPE.VARINT, CLIENT_SIDE_TOOL_V2_MCP),
+    encodeField(FIELD.CV2R_MCP_RESULT, WIRE_TYPE.LEN, encodeMcpResult(selectedTool, resultContent)),
+    encodeField(FIELD.CV2R_CALL_ID, WIRE_TYPE.LEN, toolCallId),
+    ...(modelCallId ? [encodeField(FIELD.CV2R_MODEL_CALL_ID, WIRE_TYPE.LEN, modelCallId)] : []),
+    encodeField(FIELD.CV2R_TOOL_INDEX, WIRE_TYPE.VARINT, toolIndex > 0 ? toolIndex : 1)
+  );
+}
+
+/**
+ * Encode MCPParams.Tool nested inside ClientSideToolV2Call
+ */
+function encodeMcpParamsForCall(toolName, rawArgs, serverName) {
+  const tool = concatArrays(
+    encodeField(FIELD.MCP_TOOL_NAME, WIRE_TYPE.LEN, toolName),
+    encodeField(FIELD.MCP_TOOL_PARAMS, WIRE_TYPE.LEN, rawArgs),
+    encodeField(FIELD.MCP_TOOL_SERVER, WIRE_TYPE.LEN, serverName)
+  );
+  return encodeField(FIELD.MCP_TOOLS_LIST, WIRE_TYPE.LEN, tool);
+}
+
+/**
+ * Encode ClientSideToolV2Call proto: { tool, mcp_params, call_id, name, raw_args, tool_index, model_call_id }
+ * Represents a tool call definition
+ */
+function encodeClientSideToolV2Call(toolCallId, toolName, selectedTool, serverName, rawArgs, modelCallId, toolIndex = 1) {
+  return concatArrays(
+    encodeField(FIELD.CV2C_TOOL, WIRE_TYPE.VARINT, CLIENT_SIDE_TOOL_V2_MCP),
+    encodeField(FIELD.CV2C_MCP_PARAMS, WIRE_TYPE.LEN, encodeMcpParamsForCall(selectedTool, rawArgs, serverName)),
+    encodeField(FIELD.CV2C_CALL_ID, WIRE_TYPE.LEN, toolCallId),
+    encodeField(FIELD.CV2C_NAME, WIRE_TYPE.LEN, toolName),
+    encodeField(FIELD.CV2C_RAW_ARGS, WIRE_TYPE.LEN, rawArgs),
+    encodeField(FIELD.CV2C_TOOL_INDEX, WIRE_TYPE.VARINT, toolIndex > 0 ? toolIndex : 1),
+    ...(modelCallId ? [encodeField(FIELD.CV2C_MODEL_CALL_ID, WIRE_TYPE.LEN, modelCallId)] : [])
+  );
+}
+
+/**
+ * Encode ConversationMessage.ToolResult with full structure
+ * Matches Cursor proto: tool_call_id, tool_name, tool_index, raw_args, result, tool_call
+ */
+export function encodeToolResult(toolResult) {
+  const originalName = toolResult.tool_name || toolResult.name || "";
+  const toolName = formatToolName(originalName);
+  const rawArgs = toolResult.raw_args || "{}";
+  const resultContent = toolResult.result_content || toolResult.result || "";
+  const { toolCallId, modelCallId } = parseToolId(toolResult.tool_call_id || "");
+  const toolIndex = toolResult.tool_index || toolResult.index || 1;
+
+  // Parse tool name to extract server and selected tool
+  const { serverName, selectedTool } = parseToolName(toolName);
+
+  return concatArrays(
+    encodeField(FIELD.TOOL_RESULT_CALL_ID, WIRE_TYPE.LEN, toolCallId),
+    encodeField(FIELD.TOOL_RESULT_NAME, WIRE_TYPE.LEN, toolName),
+    encodeField(FIELD.TOOL_RESULT_INDEX, WIRE_TYPE.VARINT, toolIndex > 0 ? toolIndex : 1),
+    ...(modelCallId ? [encodeField(FIELD.TOOL_RESULT_MODEL_CALL_ID, WIRE_TYPE.LEN, modelCallId)] : []),
+    encodeField(FIELD.TOOL_RESULT_RAW_ARGS, WIRE_TYPE.LEN, rawArgs),
+    encodeField(FIELD.TOOL_RESULT_RESULT, WIRE_TYPE.LEN,
+      encodeClientSideToolV2Result(toolCallId, modelCallId, selectedTool, resultContent, toolIndex)
+    ),
+    encodeField(FIELD.TOOL_RESULT_TOOL_CALL, WIRE_TYPE.LEN,
+      encodeClientSideToolV2Call(toolCallId, toolName, selectedTool, serverName, rawArgs, modelCallId, toolIndex)
+    )
+  );
+}
+
+export function encodeMessage(content, role, messageId, chatModeEnum = null, isLast = false, hasTools = false, toolResults = [], serverBubbleId = null) {
+  const hasToolResults = toolResults.length > 0;
+  return concatArrays(
+    encodeField(FIELD.MSG_CONTENT, WIRE_TYPE.LEN, content),
+    encodeField(FIELD.MSG_ROLE, WIRE_TYPE.VARINT, role),
+    encodeField(FIELD.MSG_ID, WIRE_TYPE.LEN, messageId),
+    // Only include server_bubble_id if explicitly provided (last assistant message only)
+    ...(serverBubbleId ? [encodeField(FIELD.MSG_SERVER_BUBBLE_ID, WIRE_TYPE.LEN, serverBubbleId)] : []),
+    ...(hasToolResults ? toolResults.map(tr =>
+      encodeField(FIELD.MSG_TOOL_RESULTS, WIRE_TYPE.LEN, encodeToolResult(tr))
+    ) : []),
+    encodeField(FIELD.MSG_IS_AGENTIC, WIRE_TYPE.VARINT, hasTools ? 1 : 0),
+    encodeField(FIELD.MSG_UNIFIED_MODE, WIRE_TYPE.VARINT, hasTools ? UNIFIED_MODE.AGENT : UNIFIED_MODE.CHAT),
+    ...(isLast && hasTools ? [encodeField(FIELD.MSG_SUPPORTED_TOOLS, WIRE_TYPE.LEN, encodeVarint(1))] : [])
+  );
+}
+
+export function encodeInstruction(text) {
+  return text ? encodeField(FIELD.INSTRUCTION_TEXT, WIRE_TYPE.LEN, text) : new Uint8Array(0);
+}
+
+export function encodeModel(modelName) {
+  return concatArrays(
+    encodeField(FIELD.MODEL_NAME, WIRE_TYPE.LEN, modelName),
+    encodeField(FIELD.MODEL_EMPTY, WIRE_TYPE.LEN, new Uint8Array(0))
+  );
+}
+
+export function encodeCursorSetting() {
+  const unknown6 = concatArrays(
+    encodeField(FIELD.SETTING6_FIELD_1, WIRE_TYPE.LEN, new Uint8Array(0)),
+    encodeField(FIELD.SETTING6_FIELD_2, WIRE_TYPE.LEN, new Uint8Array(0))
+  );
+
+  return concatArrays(
+    encodeField(FIELD.SETTING_PATH, WIRE_TYPE.LEN, "cursor\\aisettings"),
+    encodeField(FIELD.SETTING_UNKNOWN_3, WIRE_TYPE.LEN, new Uint8Array(0)),
+    encodeField(FIELD.SETTING_UNKNOWN_6, WIRE_TYPE.LEN, unknown6),
+    encodeField(FIELD.SETTING_UNKNOWN_8, WIRE_TYPE.VARINT, 1),
+    encodeField(FIELD.SETTING_UNKNOWN_9, WIRE_TYPE.VARINT, 1)
+  );
+}
+
+export function encodeMetadata() {
+  return concatArrays(
+    encodeField(FIELD.META_PLATFORM, WIRE_TYPE.LEN, process.platform || "linux"),
+    encodeField(FIELD.META_ARCH, WIRE_TYPE.LEN, process.arch || "x64"),
+    encodeField(FIELD.META_VERSION, WIRE_TYPE.LEN, process.version || "v20.0.0"),
+    encodeField(FIELD.META_CWD, WIRE_TYPE.LEN, process.cwd?.() || "/"),
+    encodeField(FIELD.META_TIMESTAMP, WIRE_TYPE.LEN, new Date().toISOString())
+  );
+}
+
+export function encodeMessageId(messageId, role, summaryId = null) {
+  return concatArrays(
+    encodeField(FIELD.MSGID_ID, WIRE_TYPE.LEN, messageId),
+    ...(summaryId ? [encodeField(FIELD.MSGID_SUMMARY, WIRE_TYPE.LEN, summaryId)] : []),
+    encodeField(FIELD.MSGID_ROLE, WIRE_TYPE.VARINT, role)
+  );
+}
+
+export function encodeMcpTool(tool) {
+  const toolName = tool.function?.name || tool.name || "";
+  const toolDesc = tool.function?.description || tool.description || "";
+  const inputSchema = tool.function?.parameters || tool.input_schema || {};
+
+  return concatArrays(
+    ...(toolName ? [encodeField(FIELD.MCP_TOOL_NAME, WIRE_TYPE.LEN, toolName)] : []),
+    ...(toolDesc ? [encodeField(FIELD.MCP_TOOL_DESC, WIRE_TYPE.LEN, toolDesc)] : []),
+    ...(Object.keys(inputSchema).length > 0 ? [encodeField(FIELD.MCP_TOOL_PARAMS, WIRE_TYPE.LEN, JSON.stringify(inputSchema))] : []),
+    encodeField(FIELD.MCP_TOOL_SERVER, WIRE_TYPE.LEN, "custom")
+  );
+}
+
+// ==================== REQUEST BUILDING ====================
+
+export function encodeRequest(messages, modelName, tools = [], reasoningEffort = null, forceAgentMode = false) {
+  const hasTools = tools?.length > 0;
+  const isAgentic = hasTools || forceAgentMode;
+  const formattedMessages = [];
+  const messageIds = [];
+  const normalizedMessages = [];
+
+  // Guardrail: split mixed assistant payload into separate assistant messages
+  // This prevents protobuf encoding errors when tool calls and results are in same message
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    const hasToolCalls = Array.isArray(msg?.tool_calls) && msg.tool_calls.length > 0;
+    const hasToolResults = Array.isArray(msg?.tool_results) && msg.tool_results.length > 0;
+
+    if (msg?.role === "assistant" && hasToolCalls && hasToolResults) {
+      log(
+        "ENCODE",
+        `normalizing mixed assistant tool payload at msg[${i}] (calls=${msg.tool_calls.length}, results=${msg.tool_results.length})`
+      );
+
+      // Keep assistant tool call message without embedded results
+      normalizedMessages.push({
+        ...msg,
+        tool_results: []
+      });
+
+      // Avoid inserting duplicate assistant tool-result message if next one already matches
+      const nextMsg = messages[i + 1];
+      const nextHasToolResults =
+        nextMsg?.role === "assistant" &&
+        Array.isArray(nextMsg?.tool_results) &&
+        nextMsg.tool_results.length > 0;
+      const currentIds = new Set(
+        msg.tool_results.map(tr => tr?.tool_call_id).filter(id => typeof id === "string")
+      );
+      const nextIds = new Set(
+        (nextMsg?.tool_results || [])
+          .map(tr => tr?.tool_call_id)
+          .filter(id => typeof id === "string")
+      );
+      let sameIds = currentIds.size > 0 && currentIds.size === nextIds.size;
+      if (sameIds) {
+        for (const id of currentIds) {
+          if (!nextIds.has(id)) {
+            sameIds = false;
+            break;
+          }
+        }
+      }
+
+      if (!(nextHasToolResults && sameIds)) {
+        normalizedMessages.push({
+          role: "assistant",
+          content: "",
+          tool_results: msg.tool_results
+        });
+      }
+
+      continue;
+    }
+
+    normalizedMessages.push(msg);
+  }
+
+  // Prepare messages
+  for (let i = 0; i < normalizedMessages.length; i++) {
+    const msg = normalizedMessages[i];
+    const role = msg.role === "user" ? ROLE.USER : ROLE.ASSISTANT;
+    const msgId = uuidv4();
+    const isLast = i === normalizedMessages.length - 1;
+
+    formattedMessages.push({
+      content: msg.content,
+      role,
+      messageId: msgId,
+      isLast,
+      hasTools,
+      toolResults: msg.tool_results || []
+    });
+
+    messageIds.push({ messageId: msgId, role });
+  }
+
+  // Map reasoning effort to thinking level
+  let thinkingLevel = THINKING_LEVEL.UNSPECIFIED;
+  if (reasoningEffort === "medium") thinkingLevel = THINKING_LEVEL.MEDIUM;
+  else if (reasoningEffort === "high") thinkingLevel = THINKING_LEVEL.HIGH;
+
+  // Build request
+  return concatArrays(
+    // Messages
+    ...formattedMessages.map(fm => 
+      encodeField(FIELD.MESSAGES, WIRE_TYPE.LEN, 
+        encodeMessage(fm.content, fm.role, fm.messageId, null, fm.isLast, fm.hasTools, fm.toolResults)
+      )
+    ),
+    
+    // Static fields
+    encodeField(FIELD.UNKNOWN_2, WIRE_TYPE.VARINT, 1),
+    encodeField(FIELD.INSTRUCTION, WIRE_TYPE.LEN, encodeInstruction("")),
+    encodeField(FIELD.UNKNOWN_4, WIRE_TYPE.VARINT, 1),
+    encodeField(FIELD.MODEL, WIRE_TYPE.LEN, encodeModel(modelName)),
+    encodeField(FIELD.WEB_TOOL, WIRE_TYPE.LEN, ""),
+    encodeField(FIELD.UNKNOWN_13, WIRE_TYPE.VARINT, 1),
+    encodeField(FIELD.CURSOR_SETTING, WIRE_TYPE.LEN, encodeCursorSetting()),
+    encodeField(FIELD.UNKNOWN_19, WIRE_TYPE.VARINT, 1),
+    encodeField(FIELD.CONVERSATION_ID, WIRE_TYPE.LEN, uuidv4()),
+    encodeField(FIELD.METADATA, WIRE_TYPE.LEN, encodeMetadata()),
+
+    // Tool-related fields
+    encodeField(FIELD.IS_AGENTIC, WIRE_TYPE.VARINT, isAgentic ? 1 : 0),
+    ...(isAgentic ? [encodeField(FIELD.SUPPORTED_TOOLS, WIRE_TYPE.LEN, encodeVarint(1))] : []),
+    
+    // Message IDs
+    ...messageIds.map(mid => 
+      encodeField(FIELD.MESSAGE_IDS, WIRE_TYPE.LEN, encodeMessageId(mid.messageId, mid.role))
+    ),
+
+    // MCP Tools
+    ...(tools?.length > 0 ? tools.map(tool => 
+      encodeField(FIELD.MCP_TOOLS, WIRE_TYPE.LEN, encodeMcpTool(tool))
+    ) : []),
+
+    // Mode fields
+    encodeField(FIELD.LARGE_CONTEXT, WIRE_TYPE.VARINT, 0),
+    encodeField(FIELD.UNKNOWN_38, WIRE_TYPE.VARINT, 0),
+    encodeField(FIELD.UNIFIED_MODE, WIRE_TYPE.VARINT, isAgentic ? UNIFIED_MODE.AGENT : UNIFIED_MODE.CHAT),
+    encodeField(FIELD.UNKNOWN_47, WIRE_TYPE.LEN, ""),
+    encodeField(FIELD.SHOULD_DISABLE_TOOLS, WIRE_TYPE.VARINT, isAgentic ? 0 : 1),
+    encodeField(FIELD.THINKING_LEVEL, WIRE_TYPE.VARINT, thinkingLevel),
+    encodeField(FIELD.UNKNOWN_51, WIRE_TYPE.VARINT, 0),
+    encodeField(FIELD.UNKNOWN_53, WIRE_TYPE.VARINT, 1),
+    encodeField(FIELD.UNIFIED_MODE_NAME, WIRE_TYPE.LEN, isAgentic ? "Agent" : "Ask")
+  );
+}
+
+export function buildChatRequest(messages, modelName, tools = [], reasoningEffort = null, forceAgentMode = false) {
+  return encodeField(FIELD.REQUEST, WIRE_TYPE.LEN, encodeRequest(messages, modelName, tools, reasoningEffort, forceAgentMode));
+}
+
+/**
+ * Encode a tool result as ClientSideToolV2Result (field 2 of StreamUnifiedChatRequestWithTools)
+ * This is sent as a SEPARATE request frame, not inside conversation messages.
+ * Proto: StreamUnifiedChatRequestWithTools.client_side_tool_v2_result = 2
+ */
+export function buildToolResultRequest(toolResult) {
+  const { toolCallId, modelCallId } = parseToolId(toolResult.tool_call_id || "");
+  const rawName = toolResult.tool_name || "";
+  const resultContent = toolResult.result_content || "";
+
+  // selected_tool = raw tool name (e.g. "Write", "Read") per cursor-api Rust source:
+  // McpResult { selected_tool: tool_name, result } where tool_name is the mcpParams.tools[0].name
+  // which is the name AFTER server prefix stripping (e.g. "custom_Write" -> name = "Write")
+  // Actually cursor-api uses: name = tool_name.slice_unchecked(d+1..) → raw name without "custom_"
+  // So selected_tool = raw tool name without any prefix
+  const selectedTool = rawName.startsWith("mcp_custom_")
+    ? rawName.slice("mcp_custom_".length)
+    : rawName.startsWith("mcp_")
+    ? rawName.slice(4)
+    : rawName;
+
+  // ClientSideToolV2Result per proto:
+  //   field 1 (tool): varint = 19 (MCP)
+  //   field 28 (mcp_result): LEN { field 1: selected_tool, field 2: result }
+  //   field 35 (tool_call_id): string
+  //   field 48 (model_call_id): string (optional)
+  //   NO tool_index (None in Rust source: encode_tool_result sets tool_index: None)
+  const cv2Result = concatArrays(
+    encodeField(FIELD.CV2R_TOOL, WIRE_TYPE.VARINT, CLIENT_SIDE_TOOL_V2_MCP),
+    encodeField(FIELD.CV2R_MCP_RESULT, WIRE_TYPE.LEN, encodeMcpResult(selectedTool, resultContent)),
+    encodeField(FIELD.CV2R_CALL_ID, WIRE_TYPE.LEN, toolCallId),
+    ...(modelCallId ? [encodeField(FIELD.CV2R_MODEL_CALL_ID, WIRE_TYPE.LEN, modelCallId)] : [])
+    // tool_index intentionally omitted (None per Rust source)
+  );
+
+  // StreamUnifiedChatRequestWithTools: field 2 = client_side_tool_v2_result
+  return encodeField(2, WIRE_TYPE.LEN, cv2Result);
+}
+
+export function wrapConnectRPCFrame(payload, compress = false) {
+  let finalPayload = payload;
+  let flags = 0x00;
+
+  if (compress) {
+    finalPayload = new Uint8Array(zlib.gzipSync(Buffer.from(payload)));
+    flags = 0x01;
+  }
+
+  const frame = new Uint8Array(5 + finalPayload.length);
+  frame[0] = flags;
+  frame[1] = (finalPayload.length >> 24) & 0xFF;
+  frame[2] = (finalPayload.length >> 16) & 0xFF;
+  frame[3] = (finalPayload.length >> 8) & 0xFF;
+  frame[4] = finalPayload.length & 0xFF;
+  frame.set(finalPayload, 5);
+
+  return frame;
+}
+
+export function generateCursorBody(messages, modelName, tools = [], reasoningEffort = null, forceAgentMode = false) {
+  log("BODY", `Generating: ${messages.length} msgs, model=${modelName}, tools=${tools.length}, reasoning=${reasoningEffort || "none"}, forceAgentMode=${forceAgentMode}`);
+  
+  const protobuf = buildChatRequest(messages, modelName, tools, reasoningEffort, forceAgentMode);
+  const framed = wrapConnectRPCFrame(protobuf, false); // Cursor doesn't support compressed requests
+  
+  log("BODY", `Protobuf=${protobuf.length}B, Framed=${framed.length}B`);
+  return framed;
+}
+
+/**
+ * Generate a framed tool result body to send as a separate request frame.
+ * Uses field 2 (client_side_tool_v2_result) of StreamUnifiedChatRequestWithTools.
+ */
+export function generateToolResultBody(toolResult) {
+  const protobuf = buildToolResultRequest(toolResult);
+  return wrapConnectRPCFrame(protobuf, false);
+}
+
+// ==================== PRIMITIVE DECODING ====================
+
+export function decodeVarint(buffer, offset) {
+  let result = 0;
+  let shift = 0;
+  let pos = offset;
+
+  while (pos < buffer.length) {
+    const b = buffer[pos];
+    result |= (b & 0x7F) << shift;
+    pos++;
+    if (!(b & 0x80)) break;
+    shift += 7;
+  }
+
+  return [result, pos];
+}
+
+export function decodeField(buffer, offset) {
+  if (offset >= buffer.length) return [null, null, null, offset];
+
+  const [tag, pos1] = decodeVarint(buffer, offset);
+  const fieldNum = tag >> 3;
+  const wireType = tag & 0x07;
+
+  let value;
+  let pos = pos1;
+
+  if (wireType === WIRE_TYPE.VARINT) {
+    [value, pos] = decodeVarint(buffer, pos);
+  } else if (wireType === WIRE_TYPE.LEN) {
+    const [length, pos2] = decodeVarint(buffer, pos);
+    value = buffer.slice(pos2, pos2 + length);
+    pos = pos2 + length;
+  } else if (wireType === WIRE_TYPE.FIXED64) {
+    value = buffer.slice(pos, pos + 8);
+    pos += 8;
+  } else if (wireType === WIRE_TYPE.FIXED32) {
+    value = buffer.slice(pos, pos + 4);
+    pos += 4;
+  } else {
+    value = null;
+  }
+
+  return [fieldNum, wireType, value, pos];
+}
+
+export function decodeMessage(data) {
+  const fields = new Map();
+  let pos = 0;
+
+  while (pos < data.length) {
+    const [fieldNum, wireType, value, newPos] = decodeField(data, pos);
+    if (fieldNum === null) break;
+
+    if (!fields.has(fieldNum)) fields.set(fieldNum, []);
+    fields.get(fieldNum).push({ wireType, value });
+    pos = newPos;
+  }
+
+  return fields;
+}
+
+// ==================== RESPONSE PARSING ====================
+
+export function parseConnectRPCFrame(buffer) {
+  if (buffer.length < 5) return null;
+
+  const flags = buffer[0];
+  const length = (buffer[1] << 24) | (buffer[2] << 16) | (buffer[3] << 8) | buffer[4];
+
+  if (buffer.length < 5 + length) return null;
+
+  let payload = buffer.slice(5, 5 + length);
+
+  // Decompress if gzip
+  if (flags === 0x01) {
+    try {
+      payload = new Uint8Array(zlib.gunzipSync(Buffer.from(payload)));
+    } catch (err) {
+      log("PARSE", `Decompression failed: ${err.message}`);
+    }
+  }
+
+  return { flags, length, payload, consumed: 5 + length };
+}
+
+function extractToolCall(toolCallData) {
+  const toolCall = decodeMessage(toolCallData);
+  let toolCallId = "";
+  let toolName = "";
+  let rawArgs = "";
+  let isLast = false;
+
+  // Extract tool call ID
+  if (toolCall.has(FIELD.TOOL_ID)) {
+    const fullId = new TextDecoder().decode(toolCall.get(FIELD.TOOL_ID)[0].value);
+    toolCallId = fullId.split("\n")[0]; // Cursor returns multi-line ID, take first line
+  }
+
+  // Extract tool name
+  if (toolCall.has(FIELD.TOOL_NAME)) {
+    toolName = new TextDecoder().decode(toolCall.get(FIELD.TOOL_NAME)[0].value);
+  }
+
+  // Extract is_last flag
+  if (toolCall.has(FIELD.TOOL_IS_LAST)) {
+    isLast = toolCall.get(FIELD.TOOL_IS_LAST)[0].value !== 0;
+  }
+
+  // Extract MCP params - nested real tool info
+  if (toolCall.has(FIELD.TOOL_MCP_PARAMS)) {
+    try {
+      const mcpParams = decodeMessage(toolCall.get(FIELD.TOOL_MCP_PARAMS)[0].value);
+      
+      if (mcpParams.has(FIELD.MCP_TOOLS_LIST)) {
+        const tool = decodeMessage(mcpParams.get(FIELD.MCP_TOOLS_LIST)[0].value);
+        
+        if (tool.has(FIELD.MCP_NESTED_NAME)) {
+          toolName = new TextDecoder().decode(tool.get(FIELD.MCP_NESTED_NAME)[0].value);
+        }
+        
+        if (tool.has(FIELD.MCP_NESTED_PARAMS)) {
+          rawArgs = new TextDecoder().decode(tool.get(FIELD.MCP_NESTED_PARAMS)[0].value);
+        }
+      }
+    } catch (err) {
+      log("EXTRACT", `MCP parse error: ${err.message}`);
+    }
+  }
+
+  // Fallback to raw_args
+  if (!rawArgs && toolCall.has(FIELD.TOOL_RAW_ARGS)) {
+    rawArgs = new TextDecoder().decode(toolCall.get(FIELD.TOOL_RAW_ARGS)[0].value);
+  }
+
+  if (toolCallId && toolName) {
+    return {
+      id: toolCallId,
+      type: "function",
+      function: {
+        name: toolName,
+        arguments: rawArgs || "{}"
+      },
+      isLast
+    };
+  }
+
+  return null;
+}
+
+function extractTextAndThinking(responseData) {
+  const nested = decodeMessage(responseData);
+  let text = null;
+  let thinking = null;
+
+  // Extract text
+  if (nested.has(FIELD.RESPONSE_TEXT)) {
+    text = new TextDecoder().decode(nested.get(FIELD.RESPONSE_TEXT)[0].value);
+  }
+
+  // Extract thinking
+  if (nested.has(FIELD.THINKING)) {
+    try {
+      const thinkingMsg = decodeMessage(nested.get(FIELD.THINKING)[0].value);
+      if (thinkingMsg.has(FIELD.THINKING_TEXT)) {
+        thinking = new TextDecoder().decode(thinkingMsg.get(FIELD.THINKING_TEXT)[0].value);
+      }
+    } catch (err) {
+      log("EXTRACT", `Thinking parse error: ${err.message}`);
+    }
+  }
+
+  return { text, thinking };
+}
+
+export function extractTextFromResponse(payload) {
+  try {
+    const fields = decodeMessage(payload);
+
+    // Warn about unknown field numbers — may indicate a Cursor protocol update
+    for (const fieldNum of fields.keys()) {
+      if (!KNOWN_RESPONSE_FIELDS.has(fieldNum)) {
+        log(
+          "SCHEMA",
+          `Unknown response field #${fieldNum} detected. Schema v${PROTOBUF_SCHEMA_VERSION} may be outdated.`
+        );
+      }
+    }
+
+    // Field 1: ClientSideToolV2Call
+    if (fields.has(FIELD.TOOL_CALL)) {
+      const toolCall = extractToolCall(fields.get(FIELD.TOOL_CALL)[0].value);
+      if (toolCall) {
+        log("EXTRACT", `Tool call: ${toolCall.function.name}`);
+        return { text: null, error: null, toolCall, thinking: null };
+      }
+    }
+
+    // Field 2: StreamUnifiedChatResponse
+    if (fields.has(FIELD.RESPONSE)) {
+      const { text, thinking } = extractTextAndThinking(fields.get(FIELD.RESPONSE)[0].value);
+
+      if (text || thinking) {
+        return { text, error: null, toolCall: null, thinking };
+      }
+    }
+
+    return { text: null, error: null, toolCall: null, thinking: null };
+  } catch (err) {
+    log("EXTRACT", `Decode failed (schema v${PROTOBUF_SCHEMA_VERSION}): ${err.message}`);
+    return {
+      text: null,
+      error: null,
+      toolCall: null,
+      thinking: null,
+      raw: Buffer.from(payload).toString("base64"),
+      decodeError: err.message
+    };
+  }
+}
+
+// ==================== EXPORTS ====================
+
+export default {
+  encodeVarint,
+  encodeField,
+  encodeMessage,
+  buildChatRequest,
+  wrapConnectRPCFrame,
+  generateCursorBody,
+  decodeVarint,
+  decodeField,
+  decodeMessage,
+  parseConnectRPCFrame,
+  extractTextFromResponse
+};
diff --git a/open-sse/utils/debugLog.js b/open-sse/utils/debugLog.js
new file mode 100644
index 0000000..67cdc31
--- /dev/null
+++ b/open-sse/utils/debugLog.js
@@ -0,0 +1,14 @@
+// Debug logging utility — only active in dev mode (NODE_ENV !== "production")
+// Outputs are tagged with [DBG:tag] for easy grep/filter
+const isDev = process.env.NODE_ENV !== "production";
+
+function ts() {
+  return new Date().toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit", second: "2-digit" });
+}
+
+export function dbg(tag, msg) {
+  if (!isDev) return;
+  console.log(`[${ts()}] 🐛 [DBG:${tag}] ${msg}`);
+}
+
+export const isDebugEnabled = isDev;
diff --git a/open-sse/utils/error.js b/open-sse/utils/error.js
new file mode 100644
index 0000000..315723e
--- /dev/null
+++ b/open-sse/utils/error.js
@@ -0,0 +1,147 @@
+import { ERROR_TYPES, DEFAULT_ERROR_MESSAGES } from "../config/errorConfig.js";
+
+/**
+ * Build OpenAI-compatible error response body
+ * @param {number} statusCode - HTTP status code
+ * @param {string} message - Error message
+ * @returns {object} Error response object
+ */
+export function buildErrorBody(statusCode, message) {
+  const errorInfo = ERROR_TYPES[statusCode] || 
+    (statusCode >= 500 
+      ? { type: "server_error", code: "internal_server_error" }
+      : { type: "invalid_request_error", code: "" });
+
+  return {
+    error: {
+      message: message || DEFAULT_ERROR_MESSAGES[statusCode] || "An error occurred",
+      type: errorInfo.type,
+      code: errorInfo.code
+    }
+  };
+}
+
+/**
+ * Create error Response object (for non-streaming)
+ * @param {number} statusCode - HTTP status code
+ * @param {string} message - Error message
+ * @returns {Response} HTTP Response object
+ */
+export function errorResponse(statusCode, message) {
+  return new Response(JSON.stringify(buildErrorBody(statusCode, message)), {
+    status: statusCode,
+    headers: {
+      "Content-Type": "application/json",
+      "Access-Control-Allow-Origin": "*"
+    }
+  });
+}
+
+/**
+ * Write error to SSE stream (for streaming)
+ * @param {WritableStreamDefaultWriter} writer - Stream writer
+ * @param {number} statusCode - HTTP status code
+ * @param {string} message - Error message
+ */
+export async function writeStreamError(writer, statusCode, message) {
+  const errorBody = buildErrorBody(statusCode, message);
+  const encoder = new TextEncoder();
+  await writer.write(encoder.encode(`data: ${JSON.stringify(errorBody)}\n\n`));
+}
+
+/**
+ * Parse upstream provider error response
+ * @param {Response} response - Fetch response from provider
+ * @param {object} [executor] - Optional executor with parseError() override for provider-specific parsing
+ * @returns {Promise<{statusCode: number, message: string, resetsAtMs?: number}>}
+ */
+export async function parseUpstreamError(response, executor = null) {
+  let bodyText = "";
+  try {
+    bodyText = await response.text();
+  } catch {
+    bodyText = "";
+  }
+
+  // Let executor-specific parser extract provider-specific fields (e.g. codex resetsAtMs)
+  if (executor && typeof executor.parseError === "function") {
+    try {
+      const parsed = executor.parseError(response, bodyText);
+      if (parsed && typeof parsed === "object") {
+        const msg = parsed.message || DEFAULT_ERROR_MESSAGES[response.status] || `Upstream error: ${response.status}`;
+        return { statusCode: parsed.status || response.status, message: msg, resetsAtMs: parsed.resetsAtMs };
+      }
+    } catch { /* fall through to default parsing */ }
+  }
+
+  let message = "";
+  try {
+    const json = JSON.parse(bodyText);
+    message = json.error?.message || json.message || json.error || bodyText;
+  } catch {
+    message = bodyText;
+  }
+
+  const messageStr = typeof message === "string" ? message : JSON.stringify(message);
+  const finalMessage = messageStr || DEFAULT_ERROR_MESSAGES[response.status] || `Upstream error: ${response.status}`;
+
+  return { statusCode: response.status, message: finalMessage };
+}
+
+/**
+ * Create error result for chatCore handler
+ * @param {number} statusCode - HTTP status code
+ * @param {string} message - Error message
+ * @param {number} [resetsAtMs] - Optional precise cooldown expiry (ms epoch) for provider-specific quota errors
+ * @returns {{ success: false, status: number, error: string, response: Response, resetsAtMs?: number }}
+ */
+export function createErrorResult(statusCode, message, resetsAtMs) {
+  return {
+    success: false,
+    status: statusCode,
+    error: message,
+    resetsAtMs,
+    response: errorResponse(statusCode, message)
+  };
+}
+
+/**
+ * Create unavailable response when all accounts are rate limited
+ * @param {number} statusCode - Original error status code
+ * @param {string} message - Error message (without retry info)
+ * @param {string} retryAfter - ISO timestamp when earliest account becomes available
+ * @param {string} retryAfterHuman - Human-readable retry info e.g. "reset after 30s"
+ * @returns {Response}
+ */
+export function unavailableResponse(statusCode, message, retryAfter, retryAfterHuman) {
+  const retryAfterSec = Math.max(Math.ceil((new Date(retryAfter).getTime() - Date.now()) / 1000), 1);
+  const msg = `${message} (${retryAfterHuman})`;
+  return new Response(
+    JSON.stringify({ error: { message: msg } }),
+    {
+      status: statusCode,
+      headers: {
+        "Content-Type": "application/json",
+        "Retry-After": String(retryAfterSec)
+      }
+    }
+  );
+}
+
+/**
+ * Format provider error with context
+ * @param {Error} error - Original error
+ * @param {string} provider - Provider name
+ * @param {string} model - Model name
+ * @param {number|string} statusCode - HTTP status code or error code
+ * @returns {string} Formatted error message
+ */
+export function formatProviderError(error, provider, model, statusCode) {
+  const code = statusCode || error.code || "FETCH_FAILED";
+  const message = error.message || "Unknown error";
+  // Expose low-level cause (e.g. UND_ERR_SOCKET, ECONNRESET, ETIMEDOUT) for diagnosing fetch failures
+  const causeCode = error.cause?.code;
+  const causeMsg = error.cause?.message;
+  const causeStr = causeCode || causeMsg ? ` (cause: ${[causeCode, causeMsg].filter(Boolean).join(": ")})` : "";
+  return `[${code}]: ${message}${causeStr}`;
+}
diff --git a/open-sse/utils/ollamaTransform.js b/open-sse/utils/ollamaTransform.js
new file mode 100644
index 0000000..b4fb6a6
--- /dev/null
+++ b/open-sse/utils/ollamaTransform.js
@@ -0,0 +1,85 @@
+// Transform OpenAI SSE stream to Ollama JSON lines format
+export function transformToOllama(response, model) {
+  let buffer = "";
+  let pendingToolCalls = {};
+  
+  const transform = new TransformStream({
+    transform(chunk, controller) {
+      const text = new TextDecoder().decode(chunk);
+      buffer += text;
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+
+      for (const line of lines) {
+        if (!line.startsWith("data:")) continue;
+        const data = line.slice(5).trim();
+        
+        if (data === "[DONE]") {
+          const ollamaEnd = JSON.stringify({ model, message: { role: "assistant", content: "" }, done: true }) + "\n";
+          controller.enqueue(new TextEncoder().encode(ollamaEnd));
+          return;
+        }
+
+        try {
+          const parsed = JSON.parse(data);
+          const delta = parsed.choices?.[0]?.delta || {};
+          const content = delta.content || "";
+          const toolCalls = delta.tool_calls;
+
+          if (toolCalls) {
+            for (const tc of toolCalls) {
+              const idx = tc.index;
+              if (!pendingToolCalls[idx]) {
+                pendingToolCalls[idx] = { id: tc.id, function: { name: "", arguments: "" } };
+              }
+              if (tc.function?.name) pendingToolCalls[idx].function.name += tc.function.name;
+              if (tc.function?.arguments) pendingToolCalls[idx].function.arguments += tc.function.arguments;
+            }
+          }
+
+          if (content) {
+            const ollama = JSON.stringify({ model, message: { role: "assistant", content }, done: false }) + "\n";
+            controller.enqueue(new TextEncoder().encode(ollama));
+          }
+
+          const finishReason = parsed.choices?.[0]?.finish_reason;
+          if (finishReason === "tool_calls" || finishReason === "stop") {
+            const toolCallsArr = Object.values(pendingToolCalls);
+            if (toolCallsArr.length > 0) {
+              const formattedCalls = toolCallsArr.map(tc => ({
+                function: {
+                  name: tc.function.name,
+                  arguments: (() => { try { return JSON.parse(tc.function.arguments || "{}"); } catch { return {}; } })()
+                }
+              }));
+              const ollama = JSON.stringify({ 
+                model, 
+                message: { role: "assistant", content: "", tool_calls: formattedCalls }, 
+                done: true
+              }) + "\n";
+              controller.enqueue(new TextEncoder().encode(ollama));
+              pendingToolCalls = {};
+            } else if (finishReason === "stop") {
+              const ollamaEnd = JSON.stringify({ model, message: { role: "assistant", content: "" }, done: true }) + "\n";
+              controller.enqueue(new TextEncoder().encode(ollamaEnd));
+            }
+          }
+        } catch (e) {
+          // Silently ignore parse errors
+        }
+      }
+    },
+    flush(controller) {
+      const ollamaEnd = JSON.stringify({ model, message: { role: "assistant", content: "" }, done: true }) + "\n";
+      controller.enqueue(new TextEncoder().encode(ollamaEnd));
+    }
+  });
+
+  if (!response.body) {
+    return new Response("", { status: response.status, headers: { "Content-Type": "application/x-ndjson" } });
+  }
+  return new Response(response.body.pipeThrough(transform), {
+    headers: { "Content-Type": "application/x-ndjson", "Access-Control-Allow-Origin": "*" }
+  });
+}
+
diff --git a/open-sse/utils/proxyFetch.js b/open-sse/utils/proxyFetch.js
new file mode 100644
index 0000000..341b815
--- /dev/null
+++ b/open-sse/utils/proxyFetch.js
@@ -0,0 +1,368 @@
+import { Readable } from "stream";
+import { MEMORY_CONFIG } from "../config/runtimeConfig.js";
+import { dbg } from "./debugLog.js";
+
+const originalFetch = globalThis.fetch;
+const proxyDispatchers = new Map();
+
+// ─── TLS fingerprinting via got-scraping (browser-like JA3) ───────────────
+// Disabled: not in use. Kept commented for future re-enable.
+// Restore the original block to re-enable per-host JA3 spoofing.
+/*
+let _gotScraping = null;
+let _gotScrapingChecked = false;
+const _gotScrapingLoggedHosts = new Set();
+
+async function getGotScraping() {
+  if (_gotScrapingChecked) return _gotScraping;
+  _gotScrapingChecked = true;
+  try {
+    const mod = await import("got-scraping");
+    _gotScraping = typeof mod.gotScraping === "function" ? mod.gotScraping : null;
+    if (_gotScraping) dbg("TLS", "got-scraping loaded (browser-like JA3 enabled)");
+  } catch (e) {
+    console.warn(`[ProxyFetch] got-scraping unavailable, falling back to native fetch: ${e.message}`);
+    _gotScraping = null;
+  }
+  return _gotScraping;
+}
+
+async function gotScrapingFetch(url, options) {
+  const gs = await getGotScraping();
+  if (!gs) return null;
+
+  const method = (options.method || "GET").toUpperCase();
+  const headersInit = options.headers || {};
+  const headers = headersInit instanceof Headers
+    ? Object.fromEntries(headersInit.entries())
+    : { ...headersInit };
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const stream = gs.stream({
+      url,
+      method,
+      headers,
+      body: method === "GET" || method === "HEAD" ? undefined : options.body,
+      throwHttpErrors: false,
+      retry: { limit: 0 },
+      timeout: { request: undefined },
+      followRedirect: false,
+      decompress: true,
+    });
+
+    if (options.signal) {
+      const onAbort = () => { try { stream.destroy(new Error("aborted")); } catch { } };
+      if (options.signal.aborted) onAbort();
+      else options.signal.addEventListener("abort", onAbort, { once: true });
+    }
+
+    stream.once("response", (res) => {
+      if (settled) return;
+      settled = true;
+      const resHeaders = new Headers();
+      for (const [k, v] of Object.entries(res.headers || {})) {
+        if (Array.isArray(v)) v.forEach((x) => resHeaders.append(k, String(x)));
+        else if (v != null) resHeaders.set(k, String(v));
+      }
+      const body = Readable.toWeb(stream);
+      resolve(new Response(body, { status: res.statusCode, statusText: res.statusMessage || "", headers: resHeaders }));
+    });
+
+    stream.once("error", (err) => {
+      if (settled) return;
+      settled = true;
+      reject(err);
+    });
+  });
+}
+
+async function tryGotScrapingFetch(url, options) {
+  try {
+    const res = await gotScrapingFetch(url, options);
+    if (res) {
+      try {
+        const host = new URL(typeof url === "string" ? url : url.toString()).hostname;
+        if (!_gotScrapingLoggedHosts.has(host)) {
+          _gotScrapingLoggedHosts.add(host);
+          dbg("TLS", `using got-scraping for ${host}`);
+        }
+      } catch { }
+    }
+    return res;
+  } catch (e) {
+    console.warn(`[ProxyFetch] got-scraping request failed, fallback to native fetch: ${e.message}`);
+    return null;
+  }
+}
+*/
+
+// DNS cache — use Map to avoid prototype pollution via malformed hostnames
+const DNS_CACHE = new Map();
+const MITM_BYPASS_HOSTS = [
+  "cloudcode-pa.googleapis.com",
+  "daily-cloudcode-pa.googleapis.com",
+  "api.individual.githubcopilot.com",
+  "q.us-east-1.amazonaws.com",
+  "codewhisperer.us-east-1.amazonaws.com",
+  "api2.cursor.sh",
+];
+const GOOGLE_DNS_SERVERS = ["8.8.8.8", "8.8.4.4"];
+const HTTPS_PORT = 443;
+const HTTP_SUCCESS_MIN = 200;
+const HTTP_SUCCESS_MAX = 300;
+
+function normalizeString(value) {
+  if (value === undefined || value === null) return "";
+  return String(value).trim();
+}
+
+/**
+ * Resolve real IP using Google DNS (bypass system DNS)
+ */
+async function resolveRealIP(hostname) {
+  const cached = DNS_CACHE.get(hostname);
+  if (cached && Date.now() < cached.expiry) return cached.ip;
+
+  try {
+    const dns = await import("dns");
+    const { promisify } = await import("util");
+    const resolver = new dns.Resolver();
+    resolver.setServers(GOOGLE_DNS_SERVERS);
+    const resolve4 = promisify(resolver.resolve4.bind(resolver));
+    const addresses = await resolve4(hostname);
+    DNS_CACHE.set(hostname, { ip: addresses[0], expiry: Date.now() + MEMORY_CONFIG.dnsCacheTtlMs });
+    return addresses[0];
+  } catch (error) {
+    console.warn(`[ProxyFetch] DNS resolve failed for ${hostname}:`, error.message);
+    return null;
+  }
+}
+
+/**
+ * Check if request should bypass MITM DNS redirect
+ */
+function shouldBypassMitmDns(url) {
+  try {
+    const hostname = new URL(url).hostname;
+    return MITM_BYPASS_HOSTS.some(host => hostname.includes(host));
+  } catch { return false; }
+}
+
+function shouldBypassByNoProxy(targetUrl, noProxyValue) {
+  const noProxy = normalizeString(noProxyValue);
+  if (!noProxy) return false;
+
+  let hostname;
+  try { hostname = new URL(targetUrl).hostname.toLowerCase(); } catch { return false; }
+  const patterns = noProxy.split(",").map((p) => p.trim().toLowerCase()).filter(Boolean);
+
+  return patterns.some((pattern) => {
+    if (pattern === "*") return true;
+    if (pattern.startsWith(".")) return hostname.endsWith(pattern) || hostname === pattern.slice(1);
+    return hostname === pattern || hostname.endsWith(`.${pattern}`);
+  });
+}
+
+/**
+ * Get proxy URL from environment
+ */
+function getEnvProxyUrl(targetUrl) {
+  const noProxy = process.env.NO_PROXY || process.env.no_proxy;
+  if (shouldBypassByNoProxy(targetUrl, noProxy)) return null;
+
+  let protocol;
+  try { protocol = new URL(targetUrl).protocol; } catch { return null; }
+
+  if (protocol === "https:") {
+    return process.env.HTTPS_PROXY || process.env.https_proxy ||
+      process.env.ALL_PROXY || process.env.all_proxy;
+  }
+
+  return process.env.HTTP_PROXY || process.env.http_proxy ||
+    process.env.ALL_PROXY || process.env.all_proxy;
+}
+
+/**
+ * Normalize proxy URL (allow host:port)
+ */
+function normalizeProxyUrl(proxyUrl) {
+  const normalizedInput = normalizeString(proxyUrl);
+  if (!normalizedInput) return null;
+
+  try {
+
+    new URL(normalizedInput);
+    return normalizedInput;
+  } catch {
+    // Allow "127.0.0.1:7890" style values
+    return `http://${normalizedInput}`;
+  }
+}
+
+function resolveConnectionProxyUrl(targetUrl, proxyOptions) {
+  const enabled = proxyOptions?.enabled === true || proxyOptions?.connectionProxyEnabled === true;
+  if (!enabled) return null;
+
+  const proxyUrlRaw = normalizeString(proxyOptions?.url ?? proxyOptions?.connectionProxyUrl);
+  if (!proxyUrlRaw) return null;
+
+  const noProxy = normalizeString(proxyOptions?.noProxy ?? proxyOptions?.connectionNoProxy);
+  if (noProxy && shouldBypassByNoProxy(targetUrl, noProxy)) return null;
+
+  return normalizeProxyUrl(proxyUrlRaw);
+}
+
+/**
+ * Create proxy dispatcher lazily (undici-compatible)
+ */
+async function getDispatcher(proxyUrl) {
+  const normalized = normalizeProxyUrl(proxyUrl);
+  if (!normalized) return null;
+
+  if (!proxyDispatchers.has(normalized)) {
+    // Evict oldest entry if max size reached
+    if (proxyDispatchers.size >= MEMORY_CONFIG.proxyDispatchersMaxSize) {
+      proxyDispatchers.delete(proxyDispatchers.keys().next().value);
+    }
+    const { ProxyAgent } = await import("undici");
+    proxyDispatchers.set(normalized, new ProxyAgent({ uri: normalized }));
+  }
+
+  return proxyDispatchers.get(normalized);
+}
+
+/**
+ * Create HTTPS request with manual socket connection (bypass DNS)
+ */
+async function createBypassRequest(parsedUrl, realIP, options) {
+  const httpsModule = await import("https");
+  const netModule = await import("net");
+  // CJS modules expose exports via .default in ESM dynamic import context
+  const https = httpsModule.default ?? httpsModule;
+  const net = netModule.default ?? netModule;
+
+  return new Promise((resolve, reject) => {
+    const socket = new net.Socket();
+
+    socket.connect(HTTPS_PORT, realIP, () => {
+      const reqOptions = {
+        socket,
+        // SNI + cert hostname are validated against the hostname the caller
+        // asked for, not the IP we connected to. This keeps the DNS-bypass
+        // (avoiding /etc/hosts MITM) while still rejecting on-path attackers
+        // that present a different cert. The MITM_BYPASS_HOSTS targets are
+        // all public-CA-issued (Google / GitHub / AWS / Cursor) so default
+        // verification works without any extra trust store.
+        servername: parsedUrl.hostname,
+        path: parsedUrl.pathname + parsedUrl.search,
+        method: options.method || "POST",
+        headers: {
+          ...options.headers,
+          Host: parsedUrl.hostname,
+        },
+      };
+
+      const req = https.request(reqOptions, (res) => {
+        const response = {
+          ok: res.statusCode >= HTTP_SUCCESS_MIN && res.statusCode < HTTP_SUCCESS_MAX,
+          status: res.statusCode,
+          statusText: res.statusMessage,
+          headers: new Map(Object.entries(res.headers)),
+          body: Readable.toWeb(res),
+          text: async () => {
+            const chunks = [];
+            for await (const chunk of res) chunks.push(chunk);
+            return Buffer.concat(chunks).toString();
+          },
+          json: async () => JSON.parse(await response.text()),
+        };
+        resolve(response);
+      });
+
+      req.on("error", reject);
+      if (options.body) {
+        req.write(typeof options.body === "string" ? options.body : JSON.stringify(options.body));
+      }
+      req.end();
+    });
+
+    socket.on("error", reject);
+  });
+}
+
+export async function proxyAwareFetch(url, options = {}, proxyOptions = null) {
+  const targetUrl = typeof url === "string" ? url : url.toString();
+
+  // Vercel relay: forward request via relay headers
+  const vercelRelayUrl = normalizeString(proxyOptions?.vercelRelayUrl);
+  if (vercelRelayUrl) {
+    const parsed = new URL(targetUrl);
+    const relayHeaders = {
+      ...options.headers,
+      "x-relay-target": `${parsed.protocol}//${parsed.host}`,
+      "x-relay-path": `${parsed.pathname}${parsed.search}`,
+    };
+    return originalFetch(vercelRelayUrl, { ...options, headers: relayHeaders });
+  }
+
+  const connectionProxyUrl = resolveConnectionProxyUrl(targetUrl, proxyOptions);
+  const envProxyUrl = connectionProxyUrl ? null : normalizeProxyUrl(getEnvProxyUrl(targetUrl));
+  const proxyUrl = connectionProxyUrl || envProxyUrl;
+
+  // MITM DNS bypass: for known MITM-intercepted hosts, resolve real IP to avoid DNS spoof
+  if (shouldBypassMitmDns(targetUrl)) {
+    if (proxyUrl) {
+      // Proxy resolves DNS externally (not affected by /etc/hosts) — use proxy directly
+      try {
+        const dispatcher = await getDispatcher(proxyUrl);
+        return await originalFetch(url, { ...options, dispatcher });
+      } catch (proxyError) {
+        if (proxyOptions?.strictProxy === true) {
+          throw new Error(`[ProxyFetch] Proxy required but failed (strictProxy=true): ${proxyError.message}`);
+        }
+        console.warn(`[ProxyFetch] Proxy failed, falling back to direct bypass: ${proxyError.message}`);
+      }
+    }
+    // No proxy — manually resolve real IP to bypass DNS spoof
+    try {
+      const parsedUrl = new URL(targetUrl);
+      const realIP = await resolveRealIP(parsedUrl.hostname);
+      if (realIP) return await createBypassRequest(parsedUrl, realIP, options);
+    } catch (error) {
+      console.warn(`[ProxyFetch] MITM bypass failed: ${error.message}`);
+    }
+  }
+
+  if (proxyUrl) {
+    try {
+      const dispatcher = await getDispatcher(proxyUrl);
+      return await originalFetch(url, { ...options, dispatcher });
+    } catch (proxyError) {
+      // If strictProxy is enabled, fail hard instead of falling back to direct
+      if (proxyOptions?.strictProxy === true) {
+        throw new Error(`[ProxyFetch] Proxy required but failed (strictProxy=true): ${proxyError.message}`);
+      }
+      console.warn(`[ProxyFetch] Proxy failed, falling back to direct: ${proxyError.message}`);
+      return originalFetch(url, options);
+    }
+  }
+
+  // got-scraping disabled — use native fetch directly
+  // (Re-enable per-host by wrapping with tryGotScrapingFetch when needed)
+  return originalFetch(url, options);
+}
+
+/**
+ * Patched global fetch with env-proxy support and MITM DNS bypass
+ */
+async function patchedFetch(url, options = {}) {
+  return proxyAwareFetch(url, options, null);
+}
+
+// Idempotency guard — only patch once to avoid wrapping multiple times
+if (globalThis.fetch !== patchedFetch) {
+  globalThis.fetch = patchedFetch;
+}
+
+export default patchedFetch;
diff --git a/open-sse/utils/reasoningContentInjector.js b/open-sse/utils/reasoningContentInjector.js
new file mode 100644
index 0000000..14fd27b
--- /dev/null
+++ b/open-sse/utils/reasoningContentInjector.js
@@ -0,0 +1,76 @@
+// Some thinking-mode providers (DeepSeek, Kimi, MiniMax, ...) require reasoning_content
+// to be echoed back on assistant messages. Clients in OpenAI format don't send it,
+// so we inject a non-empty placeholder to satisfy upstream validation.
+import { PROVIDERS } from "../config/providers.js";
+
+const PLACEHOLDER = " ";
+
+// Provider-level rules derive from registry transport.reasoningInject (single source)
+const providerRuleFor = (provider) => PROVIDERS[provider]?.reasoningInject;
+
+// Model-level rules: matched by predicate against model id
+const MODEL_RULES = [
+  { match: m => /^kimi-/i.test(m || ""), scope: "toolCalls" },
+  { match: m => /deepseek/i.test(m || ""), scope: "all" }
+];
+
+const DEEPSEEK_V4_PRO = "deepseek-v4-pro";
+const DEEPSEEK_V4_PRO_ALIASES = {
+  [`${DEEPSEEK_V4_PRO}-max`]: {
+    thinkingType: "enabled",
+    reasoningEffort: "max"
+  },
+  [`${DEEPSEEK_V4_PRO}-none`]: {
+    thinkingType: "disabled",
+    reasoningEffort: null
+  }
+};
+
+function shouldInject(message, scope) {
+  if (message?.role !== "assistant") return false;
+  const rc = message.reasoning_content;
+  if (typeof rc === "string" && rc.length > 0) return false;
+  if (scope === "toolCalls") return Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
+  return true;
+}
+
+function applyRule(body, rule) {
+  if (!rule || !body?.messages) return body;
+  const messages = body.messages.map(m =>
+    shouldInject(m, rule.scope) ? { ...m, reasoning_content: PLACEHOLDER } : m
+  );
+  return { ...body, messages };
+}
+
+function applyDeepSeekV4ProAlias({ provider, model, body }) {
+  const alias = DEEPSEEK_V4_PRO_ALIASES[model];
+  if (provider !== "deepseek" || !alias || !body) return body;
+
+  const nextBody = {
+    ...body,
+    model: DEEPSEEK_V4_PRO,
+    extra_body: {
+      ...(body.extra_body || {}),
+      thinking: {
+        ...(body.extra_body?.thinking || {}),
+        type: alias.thinkingType
+      }
+    }
+  };
+
+  if (alias.reasoningEffort) {
+    nextBody.reasoning_effort = alias.reasoningEffort;
+  } else {
+    delete nextBody.reasoning_effort;
+  }
+
+  return nextBody;
+}
+
+export function injectReasoningContent({ provider, model, body }) {
+  const providerRule = providerRuleFor(provider);
+  const modelRule = MODEL_RULES.find(r => r.match(model));
+  const rule = providerRule || modelRule;
+  const nextBody = applyDeepSeekV4ProAlias({ provider, model, body });
+  return applyRule(nextBody, rule);
+}
diff --git a/open-sse/utils/requestLogger.js b/open-sse/utils/requestLogger.js
new file mode 100644
index 0000000..010153d
--- /dev/null
+++ b/open-sse/utils/requestLogger.js
@@ -0,0 +1,260 @@
+// Check if running in Node.js environment (has fs module)
+const isNode = typeof process !== "undefined" && process.versions?.node && typeof window === "undefined";
+
+// Check if logging is enabled via environment variable (default: false)
+const LOGGING_ENABLED = typeof process !== "undefined" && process.env?.ENABLE_REQUEST_LOGS === 'true';
+
+let fs = null;
+let path = null;
+let LOGS_DIR = null;
+
+// Lazy load Node.js modules (avoid top-level await)
+async function ensureNodeModules() {
+  if (!isNode || !LOGGING_ENABLED || fs) return;
+  try {
+    fs = await import("fs");
+    path = await import("path");
+    LOGS_DIR = path.join(typeof process !== "undefined" && process.cwd ? process.cwd() : ".", "logs");
+  } catch {
+    // Running in non-Node environment (Worker, Browser, etc.)
+  }
+}
+
+// Format timestamp for folder name: 20251228_143045_123
+function formatTimestamp(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  const y = date.getFullYear();
+  const m = pad(date.getMonth() + 1);
+  const d = pad(date.getDate());
+  const h = pad(date.getHours());
+  const min = pad(date.getMinutes());
+  const s = pad(date.getSeconds());
+  const ms = String(date.getMilliseconds()).padStart(3, "0");
+  return `${y}${m}${d}_${h}${min}${s}_${ms}`;
+}
+
+// Create log session folder: {sourceFormat}_{targetFormat}_{model}_{timestamp}
+async function createLogSession(sourceFormat, targetFormat, model) {
+  await ensureNodeModules();
+  if (!fs || !LOGS_DIR) return null;
+  
+  try {
+    if (!fs.existsSync(LOGS_DIR)) {
+      fs.mkdirSync(LOGS_DIR, { recursive: true });
+    }
+    
+    const timestamp = formatTimestamp();
+    const safeModel = (model || "unknown").replace(/[/:]/g, "-");
+    const folderName = `${sourceFormat}_${targetFormat}_${safeModel}_${timestamp}`;
+    const sessionPath = path.join(LOGS_DIR, folderName);
+    
+    fs.mkdirSync(sessionPath, { recursive: true });
+    
+    return sessionPath;
+  } catch (err) {
+    console.log("[LOG] Failed to create log session:", err.message);
+    return null;
+  }
+}
+
+// Write JSON file
+function writeJsonFile(sessionPath, filename, data) {
+  if (!fs || !sessionPath) return;
+  
+  try {
+    const filePath = path.join(sessionPath, filename);
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+  } catch (err) {
+    console.log(`[LOG] Failed to write ${filename}:`, err.message);
+  }
+}
+
+// Mask sensitive data in headers (DISABLED - keep full token for testing)
+function maskSensitiveHeaders(headers) {
+  if (!headers) return {};
+  return { ...headers };
+  
+  // Old masking code (disabled):
+  // const masked = { ...headers };
+  // const sensitiveKeys = ["authorization", "x-api-key", "cookie", "token"];
+  // 
+  // for (const key of Object.keys(masked)) {
+  //   const lowerKey = key.toLowerCase();
+  //   if (sensitiveKeys.some(sk => lowerKey.includes(sk))) {
+  //     const value = masked[key];
+  //     if (value && value.length > 20) {
+  //       masked[key] = value.slice(0, 10) + "..." + value.slice(-5);
+  //     }
+  //   }
+  // }
+  // return masked;
+}
+
+// No-op logger when logging is disabled
+function createNoOpLogger() {
+  return {
+    sessionPath: null,
+    logClientRawRequest() {},
+    logRawRequest() {},
+    logOpenAIRequest() {},
+    logTargetRequest() {},
+    logProviderResponse() {},
+    appendProviderChunk() {},
+    appendOpenAIChunk() {},
+    logConvertedResponse() {},
+    appendConvertedChunk() {},
+    logError() {}
+  };
+}
+
+/**
+ * Create a new log session and return logger functions
+ * @param {string} sourceFormat - Source format from client (claude, openai, etc.)
+ * @param {string} targetFormat - Target format to provider (antigravity, gemini-cli, etc.)
+ * @param {string} model - Model name
+ * @returns {Promise<object>} Promise that resolves to logger object with methods to log each stage
+ */
+export async function createRequestLogger(sourceFormat, targetFormat, model) {
+  // Return no-op logger if logging is disabled
+  if (!LOGGING_ENABLED) {
+    return createNoOpLogger();
+  }
+  
+  // Wait for session to be created before returning logger
+  const sessionPath = await createLogSession(sourceFormat, targetFormat, model);
+  
+  return {
+    get sessionPath() { return sessionPath; },
+    
+    // 1. Log client raw request (before any conversion)
+    logClientRawRequest(endpoint, body, headers = {}) {
+      writeJsonFile(sessionPath, "1_req_client.json", {
+        timestamp: new Date().toISOString(),
+        endpoint,
+        headers: maskSensitiveHeaders(headers),
+        body
+      });
+    },
+    
+    // 2. Log raw request from client (after initial conversion like responsesApi)
+    logRawRequest(body, headers = {}) {
+      writeJsonFile(sessionPath, "2_req_source.json", {
+        timestamp: new Date().toISOString(),
+        headers: maskSensitiveHeaders(headers),
+        body
+      });
+    },
+    
+    // 3. Log OpenAI intermediate format (source → openai)
+    logOpenAIRequest(body) {
+      writeJsonFile(sessionPath, "3_req_openai.json", {
+        timestamp: new Date().toISOString(),
+        body
+      });
+    },
+    
+    // 4. Log target format request (openai → target)
+    logTargetRequest(url, headers, body) {
+      writeJsonFile(sessionPath, "4_req_target.json", {
+        timestamp: new Date().toISOString(),
+        url,
+        headers: maskSensitiveHeaders(headers),
+        body
+      });
+    },
+    
+    // 5. Log provider response (for non-streaming or error)
+    logProviderResponse(status, statusText, headers, body) {
+      const filename = "5_res_provider.json";
+      writeJsonFile(sessionPath, filename, {
+        timestamp: new Date().toISOString(),
+        status,
+        statusText,
+        headers: headers ? (typeof headers.entries === "function" ? Object.fromEntries(headers.entries()) : headers) : {},
+        body
+      });
+    },
+    
+    // 5. Append streaming chunk to provider response
+    appendProviderChunk(chunk) {
+      if (!fs || !sessionPath) return;
+      try {
+        const filePath = path.join(sessionPath, "5_res_provider.txt");
+        fs.appendFileSync(filePath, chunk);
+      } catch (err) {
+        // Ignore append errors
+      }
+    },
+    
+    // 6. Append OpenAI intermediate chunks (target → openai)
+    appendOpenAIChunk(chunk) {
+      if (!fs || !sessionPath) return;
+      try {
+        const filePath = path.join(sessionPath, "6_res_openai.txt");
+        fs.appendFileSync(filePath, chunk);
+      } catch (err) {
+        // Ignore append errors
+      }
+    },
+    
+    // 7. Log converted response to client (for non-streaming)
+    logConvertedResponse(body) {
+      writeJsonFile(sessionPath, "7_res_client.json", {
+        timestamp: new Date().toISOString(),
+        body
+      });
+    },
+    
+    // 7. Append streaming chunk to converted response
+    appendConvertedChunk(chunk) {
+      if (!fs || !sessionPath) return;
+      try {
+        const filePath = path.join(sessionPath, "7_res_client.txt");
+        fs.appendFileSync(filePath, chunk);
+      } catch (err) {
+        // Ignore append errors
+      }
+    },
+    
+    // 6. Log error
+    logError(error, requestBody = null) {
+      writeJsonFile(sessionPath, "6_error.json", {
+        timestamp: new Date().toISOString(),
+        error: error?.message || String(error),
+        stack: error?.stack,
+        requestBody
+      });
+    }
+  };
+}
+
+// Legacy functions for backward compatibility
+export function logRequest() {}
+export function logResponse() {}
+export function logError(provider, { error, url, model, requestBody }) {
+  if (!fs || !LOGS_DIR) return;
+  
+  try {
+    if (!fs.existsSync(LOGS_DIR)) {
+      fs.mkdirSync(LOGS_DIR, { recursive: true });
+    }
+    
+    const date = new Date().toISOString().split("T")[0];
+    const logPath = path.join(LOGS_DIR, `${provider}-${date}.log`);
+    
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      type: "error",
+      provider,
+      model,
+      url,
+      error: error?.message || String(error),
+      stack: error?.stack,
+      requestBody
+    };
+    
+    fs.appendFileSync(logPath, JSON.stringify(logEntry) + "\n");
+  } catch (err) {
+    console.log("[LOG] Failed to write error log:", err.message);
+  }
+}
diff --git a/open-sse/utils/responsesStreamHelpers.js b/open-sse/utils/responsesStreamHelpers.js
new file mode 100644
index 0000000..eaacdcd
--- /dev/null
+++ b/open-sse/utils/responsesStreamHelpers.js
@@ -0,0 +1,50 @@
+// Helpers for OpenAI Responses API streaming termination + event framing
+import { FORMATS } from "../translator/formats.js";
+import { formatSSE } from "./streamHelpers.js";
+
+// Responses API events that signal the stream has reached a terminal state
+const OPENAI_RESPONSES_TERMINAL_EVENTS = new Set([
+  "response.completed",
+  "response.done",
+  "response.failed",
+  "error"
+]);
+
+export function getOpenAIResponsesEventName(eventName, chunk) {
+  if (eventName) return eventName;
+  if (chunk && typeof chunk.type === "string") return chunk.type;
+  return null;
+}
+
+export function isOpenAIResponsesTerminalEvent(eventName, chunk) {
+  const type = getOpenAIResponsesEventName(eventName, chunk);
+  if (OPENAI_RESPONSES_TERMINAL_EVENTS.has(type)) return true;
+  const status = chunk?.response?.status;
+  return status === "completed" || status === "failed";
+}
+
+const sharedEncoder = new TextEncoder();
+
+// Encoded response.failed + [DONE] payload for aborted/stalled Responses passthrough streams
+export function buildAbortedResponsesTerminalBytes() {
+  return sharedEncoder.encode(`${formatIncompleteOpenAIResponsesStreamFailure()}data: [DONE]\n\n`);
+}
+
+// Synthesize a response.failed event for streams that close without a terminal event
+export function formatIncompleteOpenAIResponsesStreamFailure() {
+  return formatSSE({
+    event: "response.failed",
+    data: {
+      type: "response.failed",
+      response: {
+        id: `resp_${Date.now()}`,
+        status: "failed",
+        error: {
+          type: "stream_error",
+          code: "stream_disconnected",
+          message: "stream closed before response.completed"
+        }
+      }
+    }
+  }, FORMATS.OPENAI_RESPONSES);
+}
diff --git a/open-sse/utils/sessionManager.js b/open-sse/utils/sessionManager.js
new file mode 100644
index 0000000..05f9089
--- /dev/null
+++ b/open-sse/utils/sessionManager.js
@@ -0,0 +1,231 @@
+/**
+ * Session Manager for Antigravity Cloud Code
+ *
+ * Handles session ID generation and caching for prompt caching continuity.
+ * Mimics the Antigravity binary behavior: generates a session ID at startup
+ * and keeps it for the process lifetime, scoped per account/connection.
+ *
+ * Reference: antigravity-claude-proxy/src/cloudcode/session-manager.js
+ */
+
+import crypto from "crypto";
+import { MEMORY_CONFIG } from "../config/runtimeConfig.js";
+
+// Runtime storage: Key = connectionId, Value = { sessionId, lastUsed }
+const runtimeSessionStore = new Map();
+
+// Periodically evict entries that haven't been used within TTL
+const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of runtimeSessionStore) {
+        if (now - entry.lastUsed > MEMORY_CONFIG.sessionTtlMs) {
+            runtimeSessionStore.delete(key);
+        }
+    }
+}, MEMORY_CONFIG.sessionCleanupIntervalMs);
+
+// Allow Node.js to exit even if interval is still active
+if (cleanupInterval.unref) cleanupInterval.unref();
+
+/**
+ * Get or create a session ID for the given connection.
+ *
+ * The binary generates a session ID once at startup: `rs() + Date.now()`.
+ * Since 9router is long-running, we simulate this "per-launch" behavior by
+ * storing a generated ID in memory for each connection.
+ *
+ * - If 9router restarts, the ID changes (matching binary restart behavior).
+ * - Within a running instance, the ID is stable for that connection.
+ * - This enables prompt caching while using the EXACT random logic of the binary.
+ *
+ * @param {string} connectionId - The connection identifier (email or unique ID)
+ * @returns {string} A stable session ID string matching binary format
+ */
+export function deriveSessionId(connectionId) {
+    if (!connectionId) {
+        return generateBinaryStyleId();
+    }
+
+    const existing = runtimeSessionStore.get(connectionId);
+    if (existing) {
+        existing.lastUsed = Date.now();
+        return existing.sessionId;
+    }
+
+    // Evict oldest entry if store exceeds max size (safety cap between cleanup cycles)
+    const MAX_SESSIONS = 1000;
+    if (runtimeSessionStore.size >= MAX_SESSIONS) {
+      const oldest = runtimeSessionStore.keys().next().value;
+      runtimeSessionStore.delete(oldest);
+    }
+
+    const sessionId = generateBinaryStyleId();
+    runtimeSessionStore.set(connectionId, { sessionId, lastUsed: Date.now() });
+    return sessionId;
+}
+
+/**
+ * Generate a Session ID using the binary's exact logic.
+ * Format: `rs() + Date.now()` where `rs()` is randomUUID
+ *
+ * @returns {string} A session ID in binary format
+ */
+export function generateBinaryStyleId() {
+    return crypto.randomUUID() + Date.now().toString();
+}
+
+/**
+ * Clears all session IDs (e.g. useful for testing or explicit reset)
+ */
+export function clearSessionStore() {
+    runtimeSessionStore.clear();
+    assistantSessionStore.clear();
+}
+
+// Conversation-stable session store: Key = hash(scope+assistant text), Value = { sessionId, lastUsed }
+const assistantSessionStore = new Map();
+const ASSISTANT_MIN_LEN = 50;
+const ASSISTANT_CAP_LEN = 50;
+const MAX_ASSISTANT_SESSIONS = 5000;
+
+// Client headers/body fields that carry an upstream session id (priority order)
+const SESSION_HEADER_KEYS = ["x-session-id", "session-id", "session_id", "x-amp-thread-id", "x-client-request-id"];
+const CLAUDE_CODE_SESSION_RE = /_session_([a-f0-9-]+)$/;
+
+function sha16(text) {
+    return crypto.createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+// Normalize a session id candidate (trim, length cap)
+function normalizeSessionId(value) {
+    if (typeof value !== "string") return null;
+    const v = value.trim();
+    if (!v || v.length > 256) return null;
+    return v;
+}
+
+// Extract Claude Code session id from metadata.user_id (_session_{uuid} | JSON {session_id})
+function extractClaudeCodeSession(userId) {
+    if (typeof userId !== "string" || !userId) return null;
+    const m = userId.match(CLAUDE_CODE_SESSION_RE);
+    if (m) return m[1];
+    if (userId[0] === "{") {
+        try { return normalizeSessionId(JSON.parse(userId)?.session_id); } catch { /* noop */ }
+    }
+    return null;
+}
+
+// Lowercase-key lookup for raw client headers
+function headerValue(headers, key) {
+    if (!headers || typeof headers !== "object") return null;
+    return normalizeSessionId(headers[key] ?? headers[key.toLowerCase()]);
+}
+
+// Read client-provided session id from headers/body (no generation)
+// Antigravity envelope carries session in request.sessionId; requestId embeds conversation uuid
+const ANTIGRAVITY_CONV_RE = /^[a-z]+\/([0-9a-f-]{36})\//i;
+function extractAntigravitySession(body) {
+    const sid = body?.request?.sessionId;
+    if (sid != null && sid !== "") return normalizeSessionId(String(sid));
+    const m = typeof body?.requestId === "string" ? body.requestId.match(ANTIGRAVITY_CONV_RE) : null;
+    return m ? normalizeSessionId(m[1]) : null;
+}
+
+function extractClientSessionId(headers, body) {
+    const claude = extractClaudeCodeSession(body?.metadata?.user_id);
+    if (claude) return `claude:${claude}`;
+    const antigravity = extractAntigravitySession(body);
+    if (antigravity) return `antigravity:${antigravity}`;
+    for (const key of SESSION_HEADER_KEYS) {
+        const v = headerValue(headers, key);
+        if (v) return v;
+    }
+    const fromBody =
+        normalizeSessionId(body?.prompt_cache_key) ||
+        normalizeSessionId(body?.session_id) ||
+        normalizeSessionId(body?.conversation_id) ||
+        normalizeSessionId(body?.metadata?.user_id);
+    return fromBody || null;
+}
+
+// Accumulate assistant text from OpenAI/Responses-style input/messages (cap-limited)
+function accumulateAssistantText(body) {
+    const items = Array.isArray(body?.input) ? body.input
+        : Array.isArray(body?.messages) ? body.messages : null;
+    if (!items) return "";
+    let text = "";
+    for (const item of items) {
+        if (item?.role !== "assistant") continue;
+        if (typeof item.content === "string") text += item.content;
+        else if (Array.isArray(item.content)) {
+            for (const c of item.content) text += c?.text || c?.output || "";
+        }
+        if (text.length >= ASSISTANT_CAP_LEN) break;
+    }
+    return text;
+}
+
+// Stable session id keyed on accumulated assistant text (avoids collision on identical first user prompt)
+function assistantTextSessionId(scope, body) {
+    const text = accumulateAssistantText(body);
+    if (text.length < ASSISTANT_MIN_LEN) return null;
+    const hash = sha16(`${scope}:${text.slice(0, ASSISTANT_CAP_LEN)}`);
+    const existing = assistantSessionStore.get(hash);
+    if (existing) {
+        existing.lastUsed = Date.now();
+        return existing.sessionId;
+    }
+    if (assistantSessionStore.size >= MAX_ASSISTANT_SESSIONS) {
+        assistantSessionStore.delete(assistantSessionStore.keys().next().value);
+    }
+    const sessionId = generateBinaryStyleId();
+    assistantSessionStore.set(hash, { sessionId, lastUsed: Date.now() });
+    return sessionId;
+}
+
+/**
+ * Resolve a conversation-stable session id (generalizes Codex resolveCacheSessionId).
+ * Priority: client session → accumulated-assistant-text hash → workspaceId → per-connection.
+ *
+ * @param {object} opts
+ * @param {object} [opts.headers] - Raw client request headers (lowercase keys)
+ * @param {object} [opts.body] - Parsed request body
+ * @param {string} [opts.connectionId] - Connection identifier (fallback scope)
+ * @param {string} [opts.workspaceId] - Provider workspace id (account-wide fallback)
+ * @param {string} [opts.scope] - Provider scope to isolate cache keys across providers
+ * @returns {string} A stable session id
+ */
+export function resolveSessionId({ headers, body, connectionId, workspaceId, scope = "" } = {}) {
+    const client = extractClientSessionId(headers, body);
+    if (client) return client;
+    const fromAssistant = assistantTextSessionId(`${scope}:${connectionId || ""}`, body);
+    if (fromAssistant) return fromAssistant;
+    const ws = normalizeSessionId(workspaceId);
+    if (ws) return ws;
+    return deriveSessionId(connectionId);
+}
+
+// Capture session id from request body + credentials (envelope still intact here)
+export function captureSessionId(body, credentials, connectionId, scope = "") {
+    return resolveSessionId({ headers: credentials?.rawHeaders, body, connectionId, scope });
+}
+
+// Convert any session id to Antigravity numeric format "-<int64>" (matches real AG / CLIProxyAPI).
+// Already-numeric ids (native AG sessionId) pass through unchanged.
+export function toNumericSessionId(sessionId) {
+    const v = normalizeSessionId(sessionId);
+    if (!v) return null;
+    if (/^-?\d+$/.test(v)) return v;
+    const h = crypto.createHash("sha256").update(v).digest();
+    const n = h.readBigUInt64BE(0) & 0x7fffffffffffffffn;
+    return `-${n.toString()}`;
+}
+
+// Cleanup expired assistant-session entries
+const assistantCleanup = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of assistantSessionStore) {
+        if (now - entry.lastUsed > MEMORY_CONFIG.sessionTtlMs) assistantSessionStore.delete(key);
+    }
+}, MEMORY_CONFIG.sessionCleanupIntervalMs);
+if (assistantCleanup.unref) assistantCleanup.unref();
diff --git a/open-sse/utils/sse.js b/open-sse/utils/sse.js
new file mode 100644
index 0000000..2fa47e9
--- /dev/null
+++ b/open-sse/utils/sse.js
@@ -0,0 +1,14 @@
+export function sseChunk(data) {
+  return `data: ${JSON.stringify(data)}\n\n`;
+}
+
+// Build OpenAI chat.completion.chunk SSE frame. Key order: id, object, created, model, choices.
+export function chatChunkSse({ id, created, model, delta, finishReason = null }) {
+  return sseChunk({
+    id,
+    object: "chat.completion.chunk",
+    created,
+    model,
+    choices: [{ index: 0, delta, finish_reason: finishReason }],
+  });
+}
diff --git a/open-sse/utils/sseConstants.js b/open-sse/utils/sseConstants.js
new file mode 100644
index 0000000..680a05c
--- /dev/null
+++ b/open-sse/utils/sseConstants.js
@@ -0,0 +1,23 @@
+// Shared SSE primitives (no imports → safe for executors + stream.js)
+export const SSE_DONE = "data: [DONE]\n\n";
+
+export const SSE_HEADERS = {
+  "Content-Type": "text/event-stream",
+  "Cache-Control": "no-cache",
+  "Connection": "keep-alive"
+};
+
+// Variant for web-cookie executors behind nginx (disable proxy buffering)
+export const SSE_HEADERS_NO_BUFFER = {
+  "Content-Type": "text/event-stream",
+  "Cache-Control": "no-cache",
+  "X-Accel-Buffering": "no"
+};
+
+// Variant for client-facing SSE responses (adds permissive CORS)
+export const SSE_HEADERS_CORS = {
+  "Content-Type": "text/event-stream",
+  "Cache-Control": "no-cache",
+  "Connection": "keep-alive",
+  "Access-Control-Allow-Origin": "*"
+};
diff --git a/open-sse/utils/stream.js b/open-sse/utils/stream.js
new file mode 100644
index 0000000..464acde
--- /dev/null
+++ b/open-sse/utils/stream.js
@@ -0,0 +1,494 @@
+import { translateResponse, initState } from "../translator/index.js";
+import { FORMATS } from "../translator/formats.js";
+import { trackPendingRequest, appendRequestLog } from "@/lib/usageDb.js";
+import { extractUsage, mergeUsage, hasValidUsage, estimateUsage, logUsage, addBufferToUsage, filterUsageForFormat, COLORS } from "./usageTracking.js";
+import { parseSSELine, hasValuableContent, fixInvalidId, formatSSE } from "./streamHelpers.js";
+import { getOpenAIResponsesEventName, isOpenAIResponsesTerminalEvent, formatIncompleteOpenAIResponsesStreamFailure } from "./responsesStreamHelpers.js";
+import { dbg, isDebugEnabled } from "./debugLog.js";
+
+import { SSE_DONE, SSE_HEADERS, SSE_HEADERS_NO_BUFFER } from "./sseConstants.js";
+
+export { COLORS, formatSSE };
+export { SSE_DONE, SSE_HEADERS, SSE_HEADERS_NO_BUFFER };
+
+// sharedEncoder is stateless — safe to share across streams
+const sharedEncoder = new TextEncoder();
+
+/**
+ * Stream modes
+ */
+const STREAM_MODE = {
+  TRANSLATE: "translate",    // Full translation between formats
+  PASSTHROUGH: "passthrough" // No translation, normalize output, extract usage
+};
+
+/**
+ * Create unified SSE transform stream
+ * @param {object} options
+ * @param {string} options.mode - Stream mode: translate, passthrough
+ * @param {string} options.targetFormat - Provider format (for translate mode)
+ * @param {string} options.sourceFormat - Client format (for translate mode)
+ * @param {string} options.provider - Provider name
+ * @param {object} options.reqLogger - Request logger instance
+ * @param {string} options.model - Model name
+ * @param {string} options.connectionId - Connection ID for usage tracking
+ * @param {object} options.body - Request body (for input token estimation)
+ * @param {function} options.onStreamComplete - Callback when stream completes (content, usage)
+ * @param {string} options.apiKey - API key for usage tracking
+ */
+export function createSSEStream(options = {}) {
+  const {
+    mode = STREAM_MODE.TRANSLATE,
+    targetFormat,
+    sourceFormat,
+    provider = null,
+    reqLogger = null,
+    toolNameMap = null,
+    model = null,
+    connectionId = null,
+    body = null,
+    onStreamComplete = null,
+    apiKey = null
+  } = options;
+
+  let buffer = "";
+  let usage = null;
+
+  // Per-stream decoder with stream:true to correctly handle multi-byte chars split across chunks
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+
+  const state = mode === STREAM_MODE.TRANSLATE ? { ...initState(sourceFormat), provider, toolNameMap, model } : null;
+
+  let totalContentLength = 0;
+  let accumulatedContent = "";
+  let accumulatedThinking = "";
+  let ttftAt = null;
+  let sseLineCount = 0;
+  let sseEmittedCount = 0;
+  const eventTypeCounts = {};
+
+  // Track Responses API event framing for same-format passthrough (codex)
+  let currentOpenAIResponsesEvent = null;
+  let openAIResponsesTerminalSeen = false;
+  let openAIResponsesDoneSent = false;
+  let streamDoneSent = false;  // track duplicate [DONE] across transform + flush
+
+  return new TransformStream({
+    transform(chunk, controller) {
+      if (!ttftAt) ttftAt = Date.now();
+      const text = decoder.decode(chunk, { stream: true });
+      buffer += text;
+      reqLogger?.appendProviderChunk?.(text);
+
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (isDebugEnabled && trimmed) {
+          sseLineCount++;
+          if (trimmed.startsWith("event:")) {
+            const evt = trimmed.slice(6).trim();
+            eventTypeCounts[evt] = (eventTypeCounts[evt] || 0) + 1;
+          }
+        }
+
+        // Capture Responses API event name to preserve framing in same-format passthrough
+        if (mode === STREAM_MODE.TRANSLATE && targetFormat === FORMATS.OPENAI_RESPONSES && trimmed.startsWith("event:")) {
+          currentOpenAIResponsesEvent = trimmed.slice(6).trim();
+        }
+
+        // Passthrough mode: normalize and forward
+        if (mode === STREAM_MODE.PASSTHROUGH) {
+          let output;
+          let injectedUsage = false;
+
+          if (trimmed.startsWith("data:") && trimmed.slice(5).trim() !== "[DONE]") {
+            try {
+              const parsed = JSON.parse(trimmed.slice(5).trim());
+
+              const idFixed = fixInvalidId(parsed);
+
+              // Ensure OpenAI-required fields are present on streaming chunks (Letta compat)
+              let fieldsInjected = false;
+              if (parsed.choices !== undefined) {
+                if (!parsed.object) { parsed.object = "chat.completion.chunk"; fieldsInjected = true; }
+                if (!parsed.created) { parsed.created = Math.floor(Date.now() / 1000); fieldsInjected = true; }
+              }
+
+              // Strip Azure-specific non-standard fields from streaming chunks
+              if (parsed.prompt_filter_results !== undefined) {
+                delete parsed.prompt_filter_results;
+                fieldsInjected = true;
+              }
+              if (parsed?.choices) {
+                for (const choice of parsed.choices) {
+                  if (choice.content_filter_results !== undefined) {
+                    delete choice.content_filter_results;
+                    fieldsInjected = true;
+                  }
+                }
+              }
+
+              // Strip empty tool_calls arrays that break AI SDK reasoning tracking.
+              // Some providers (e.g. CodeBuddy CN) include `"tool_calls": []` in
+              // every streaming delta. @ai-sdk/openai-compatible checks
+              // `delta.tool_calls != null` — an empty array passes this check,
+              // causing premature `reasoning-end` on every chunk.
+              if (parsed?.choices) {
+                for (const choice of parsed.choices) {
+                  if (choice.delta?.tool_calls && Array.isArray(choice.delta.tool_calls) && choice.delta.tool_calls.length === 0) {
+                    delete choice.delta.tool_calls;
+                    fieldsInjected = true;
+                  }
+                }
+              }
+
+              if (!hasValuableContent(parsed, FORMATS.OPENAI)) {
+                continue;
+              }
+
+              const delta = parsed.choices?.[0]?.delta;
+              const content = delta?.content;
+              const reasoning = delta?.reasoning_content;
+              if (content && typeof content === "string") {
+                totalContentLength += content.length;
+                accumulatedContent += content;
+              }
+              if (reasoning && typeof reasoning === "string") {
+                totalContentLength += reasoning.length;
+                accumulatedThinking += reasoning;
+              }
+
+              const extracted = extractUsage(parsed);
+              if (extracted) {
+                usage = mergeUsage(usage, extracted);
+              }
+
+              const isFinishChunk = parsed.choices?.[0]?.finish_reason;
+              if (isFinishChunk && !hasValidUsage(parsed.usage)) {
+                const estimated = estimateUsage(body, totalContentLength, FORMATS.OPENAI);
+                parsed.usage = filterUsageForFormat(estimated, FORMATS.OPENAI);
+                output = `data: ${JSON.stringify(parsed)}\n`;
+                usage = estimated;
+                injectedUsage = true;
+              } else if (isFinishChunk && usage) {
+                const buffered = addBufferToUsage(usage);
+                parsed.usage = filterUsageForFormat(buffered, FORMATS.OPENAI);
+                output = `data: ${JSON.stringify(parsed)}\n`;
+                injectedUsage = true;
+              } else if (idFixed || fieldsInjected) {
+                output = `data: ${JSON.stringify(parsed)}\n`;
+                injectedUsage = true;
+              }
+            } catch {
+              // Skip non-JSON data lines silently — don't forward garbage to clients.
+              // Upstream providers sometimes return plain-text errors (HTML, rate-limit
+              // messages) in the SSE stream that would break downstream JSON decoders.
+              continue;
+            }
+          }
+
+          if (!injectedUsage) {
+            if (line.startsWith("data:") && !line.startsWith("data: ")) {
+              output = "data: " + line.slice(5) + "\n";
+            } else {
+              output = line + "\n";
+            }
+          }
+
+          reqLogger?.appendConvertedChunk?.(output);
+          controller.enqueue(sharedEncoder.encode(output));
+          continue;
+        }
+
+        // Translate mode
+        if (!trimmed) continue;
+
+        const parsed = parseSSELine(trimmed, targetFormat);
+        if (!parsed) continue;
+
+        // Responses API same-format passthrough: preserve event framing + track terminal state
+        const isOpenAIResponsesStream = targetFormat === FORMATS.OPENAI_RESPONSES;
+        const keepsOpenAIResponsesFormat = isOpenAIResponsesStream && sourceFormat === FORMATS.OPENAI_RESPONSES;
+        const openAIResponsesEventName = isOpenAIResponsesStream
+          ? getOpenAIResponsesEventName(currentOpenAIResponsesEvent, parsed)
+          : null;
+
+        if (isOpenAIResponsesStream && isOpenAIResponsesTerminalEvent(openAIResponsesEventName, parsed)) {
+          openAIResponsesTerminalSeen = true;
+        }
+
+        // For Ollama: done=true is the final chunk with finish_reason/usage, must translate
+        // For other formats: done=true is the [DONE] sentinel, skip
+        if (parsed && parsed.done && targetFormat !== FORMATS.OLLAMA) {
+          // Synthesize response.failed if the Responses stream never sent a terminal event
+          if (keepsOpenAIResponsesFormat && !openAIResponsesTerminalSeen) {
+            const failedOutput = formatIncompleteOpenAIResponsesStreamFailure();
+            reqLogger?.appendConvertedChunk?.(failedOutput);
+            controller.enqueue(sharedEncoder.encode(failedOutput));
+            openAIResponsesTerminalSeen = true;
+            sseEmittedCount++;
+          }
+
+          if (keepsOpenAIResponsesFormat && !streamDoneSent) {
+            const doneOutput = "data: [DONE]\n\n";
+            reqLogger?.appendConvertedChunk?.(doneOutput);
+            controller.enqueue(sharedEncoder.encode(doneOutput));
+          }
+          streamDoneSent = true;
+          if (keepsOpenAIResponsesFormat) openAIResponsesDoneSent = true;
+          continue;
+        }
+
+        // Claude format - content
+        if (parsed.delta?.text) {
+          totalContentLength += parsed.delta.text.length;
+          accumulatedContent += parsed.delta.text;
+        }
+        // Claude format - thinking
+        if (parsed.delta?.thinking) {
+          totalContentLength += parsed.delta.thinking.length;
+          accumulatedThinking += parsed.delta.thinking;
+        }
+        
+        // OpenAI format - content
+        if (parsed.choices?.[0]?.delta?.content) {
+          totalContentLength += parsed.choices[0].delta.content.length;
+          accumulatedContent += parsed.choices[0].delta.content;
+        }
+        // OpenAI format - reasoning
+        if (parsed.choices?.[0]?.delta?.reasoning_content) {
+          totalContentLength += parsed.choices[0].delta.reasoning_content.length;
+          accumulatedThinking += parsed.choices[0].delta.reasoning_content;
+        }
+        
+        // Gemini format
+        if (parsed.candidates?.[0]?.content?.parts) {
+          for (const part of parsed.candidates[0].content.parts) {
+            if (part.text && typeof part.text === "string") {
+              totalContentLength += part.text.length;
+              // Check if this is thinking content
+              if (part.thought === true) {
+                accumulatedThinking += part.text;
+              } else {
+                accumulatedContent += part.text;
+              }
+            }
+          }
+        }
+
+        // Extract usage
+        const extracted = extractUsage(parsed);
+        if (extracted) state.usage = mergeUsage(state.usage, extracted); // Keep original usage for logging
+
+        // Responses same-format passthrough: re-emit with original event framing
+        if (keepsOpenAIResponsesFormat && openAIResponsesEventName) {
+          const output = formatSSE({ event: openAIResponsesEventName, data: parsed }, sourceFormat);
+          reqLogger?.appendConvertedChunk?.(output);
+          controller.enqueue(sharedEncoder.encode(output));
+          currentOpenAIResponsesEvent = null;
+          sseEmittedCount++;
+          continue;
+        }
+
+        currentOpenAIResponsesEvent = null;
+
+        // Translate: targetFormat -> openai -> sourceFormat
+        const translated = translateResponse(targetFormat, sourceFormat, parsed, state);
+
+        // Log OpenAI intermediate chunks (if available)
+        if (translated?._openaiIntermediate) {
+          for (const item of translated._openaiIntermediate) {
+            const openaiOutput = formatSSE(item, FORMATS.OPENAI);
+            reqLogger?.appendOpenAIChunk?.(openaiOutput);
+          }
+        }
+
+        if (translated?.length > 0) {
+          for (const item of translated) {
+            if (item === null || item === undefined) continue;
+            // Filter empty chunks
+            if (!hasValuableContent(item, sourceFormat)) {
+              continue; // Skip this empty chunk
+            }
+
+            // Inject estimated usage if finish chunk has no valid usage
+            const isFinishChunk = item.type === "message_delta" || item.choices?.[0]?.finish_reason;
+            if (state.finishReason && isFinishChunk && !hasValidUsage(item.usage) && totalContentLength > 0) {
+              const estimated = estimateUsage(body, totalContentLength, sourceFormat);
+              item.usage = filterUsageForFormat(estimated, sourceFormat); // Filter + already has buffer
+              state.usage = estimated;
+            } else if (state.finishReason && isFinishChunk && state.usage) {
+              // Add buffer and filter usage for client (but keep original in state.usage for logging)
+              const buffered = addBufferToUsage(state.usage);
+              item.usage = filterUsageForFormat(buffered, sourceFormat);
+            }
+
+            const output = formatSSE(item, sourceFormat);
+            reqLogger?.appendConvertedChunk?.(output);
+            controller.enqueue(sharedEncoder.encode(output));
+            sseEmittedCount++;
+          }
+        }
+      }
+    },
+
+    flush(controller) {
+      const evtSummary = Object.entries(eventTypeCounts).map(([k, v]) => `${k}=${v}`).join(",") || "none";
+      dbg("SSE", `flush | provider=${provider} | model=${model} | recvLines=${sseLineCount} | emitted=${sseEmittedCount} | events=[${evtSummary}]`);
+      trackPendingRequest(model, provider, connectionId, false);
+      try {
+        const remaining = decoder.decode();
+        if (remaining) buffer += remaining;
+
+        if (mode === STREAM_MODE.PASSTHROUGH) {
+          if (buffer) {
+            let output = buffer;
+            if (buffer.startsWith("data:") && !buffer.startsWith("data: ")) {
+              output = "data: " + buffer.slice(5);
+            }
+            reqLogger?.appendConvertedChunk?.(output);
+            controller.enqueue(sharedEncoder.encode(output));
+          }
+
+          if (!hasValidUsage(usage) && totalContentLength > 0) {
+            usage = estimateUsage(body, totalContentLength, FORMATS.OPENAI);
+          }
+
+          if (hasValidUsage(usage)) {
+            logUsage(provider, usage, model, connectionId, apiKey);
+          } else {
+            appendRequestLog({ model, provider, connectionId, tokens: null, status: "200 OK" }).catch(() => { });
+          }
+          
+          // IMPORTANT: In passthrough mode we still must terminate the SSE stream.
+          // Some clients (e.g. OpenClaw) expect the OpenAI-style sentinel:
+          //   data: [DONE]\n\n
+          // Without it they can hang until timeout and trigger failover.
+          // Gemini-family clients (Antigravity, Vertex, Gemini) reject this sentinel with 400 syntax errors.
+          const isGeminiFamily = provider === "antigravity" || provider === "gemini" || provider === "vertex";
+          if (!streamDoneSent && !isGeminiFamily) {
+            const doneOutput = "data: [DONE]\n\n";
+            reqLogger?.appendConvertedChunk?.(doneOutput);
+            controller.enqueue(sharedEncoder.encode(doneOutput));
+          }
+
+          if (onStreamComplete) {
+            onStreamComplete({
+              content: accumulatedContent,
+              thinking: accumulatedThinking
+            }, usage, ttftAt);
+          }
+          return;
+        }
+
+        if (buffer.trim()) {
+          const parsed = parseSSELine(buffer.trim());
+          if (parsed && !parsed.done) {
+            const translated = translateResponse(targetFormat, sourceFormat, parsed, state);
+
+            if (translated?._openaiIntermediate) {
+              for (const item of translated._openaiIntermediate) {
+                const openaiOutput = formatSSE(item, FORMATS.OPENAI);
+                reqLogger?.appendOpenAIChunk?.(openaiOutput);
+              }
+            }
+
+            if (translated?.length > 0) {
+              for (const item of translated) {
+                if (item === null || item === undefined) continue;
+                const output = formatSSE(item, sourceFormat);
+                reqLogger?.appendConvertedChunk?.(output);
+                controller.enqueue(sharedEncoder.encode(output));
+              }
+            }
+          }
+        }
+
+        const flushed = translateResponse(targetFormat, sourceFormat, null, state);
+
+        if (flushed?._openaiIntermediate) {
+          for (const item of flushed._openaiIntermediate) {
+            const openaiOutput = formatSSE(item, FORMATS.OPENAI);
+            reqLogger?.appendOpenAIChunk?.(openaiOutput);
+          }
+        }
+
+        if (flushed?.length > 0) {
+          for (const item of flushed) {
+            if (item === null || item === undefined) continue;
+            const output = formatSSE(item, sourceFormat);
+            reqLogger?.appendConvertedChunk?.(output);
+            controller.enqueue(sharedEncoder.encode(output));
+          }
+        }
+
+        // Synthesize response.failed if a Responses passthrough stream never reached a terminal event
+        const keepsOpenAIResponsesFormat = targetFormat === FORMATS.OPENAI_RESPONSES && sourceFormat === FORMATS.OPENAI_RESPONSES;
+        if (keepsOpenAIResponsesFormat && !openAIResponsesTerminalSeen) {
+          const failedOutput = formatIncompleteOpenAIResponsesStreamFailure();
+          reqLogger?.appendConvertedChunk?.(failedOutput);
+          controller.enqueue(sharedEncoder.encode(failedOutput));
+          openAIResponsesTerminalSeen = true;
+        }
+
+        if (keepsOpenAIResponsesFormat && !openAIResponsesDoneSent && !streamDoneSent) {
+          const doneOutput = "data: [DONE]\n\n";
+          reqLogger?.appendConvertedChunk?.(doneOutput);
+          controller.enqueue(sharedEncoder.encode(doneOutput));
+          openAIResponsesDoneSent = true;
+          streamDoneSent = true;
+        }
+
+        if (!hasValidUsage(state?.usage) && totalContentLength > 0) {
+          state.usage = estimateUsage(body, totalContentLength, sourceFormat);
+        }
+
+        if (hasValidUsage(state?.usage)) {
+          logUsage(state.provider || targetFormat, state.usage, model, connectionId, apiKey);
+        } else {
+          appendRequestLog({ model, provider, connectionId, tokens: null, status: "200 OK" }).catch(() => { });
+        }
+        
+        if (onStreamComplete) {
+          onStreamComplete({
+            content: accumulatedContent,
+            thinking: accumulatedThinking
+          }, state?.usage, ttftAt);
+        }
+      } catch (error) {
+        console.log("Error in flush:", error);
+      }
+    }
+  });
+}
+
+export function createSSETransformStreamWithLogger(targetFormat, sourceFormat, provider = null, reqLogger = null, toolNameMap = null, model = null, connectionId = null, body = null, onStreamComplete = null, apiKey = null) {
+  return createSSEStream({
+    mode: STREAM_MODE.TRANSLATE,
+    targetFormat,
+    sourceFormat,
+    provider,
+    reqLogger,
+    toolNameMap,
+    model,
+    connectionId,
+    body,
+    onStreamComplete,
+    apiKey
+  });
+}
+
+export function createPassthroughStreamWithLogger(provider = null, reqLogger = null, model = null, connectionId = null, body = null, onStreamComplete = null, apiKey = null) {
+  return createSSEStream({
+    mode: STREAM_MODE.PASSTHROUGH,
+    provider,
+    reqLogger,
+    model,
+    connectionId,
+    body,
+    onStreamComplete,
+    apiKey
+  });
+}
diff --git a/open-sse/utils/streamHandler.js b/open-sse/utils/streamHandler.js
new file mode 100644
index 0000000..7f04427
--- /dev/null
+++ b/open-sse/utils/streamHandler.js
@@ -0,0 +1,254 @@
+// Stream handler with disconnect detection - shared for all providers
+import { STREAM_STALL_TIMEOUT_MS } from "../config/runtimeConfig.js";
+import { dbg, isDebugEnabled } from "./debugLog.js";
+
+// Get HH:MM:SS timestamp
+function getTimeString() {
+  return new Date().toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit", second: "2-digit" });
+}
+
+/**
+ * Create stream controller with abort and disconnect detection
+ * @param {object} options
+ * @param {function} options.onDisconnect - Callback when client disconnects
+ * @param {object} options.log - Logger instance
+ * @param {string} options.provider - Provider name
+ * @param {string} options.model - Model name
+ */
+export function createStreamController({ onDisconnect, onError, log, provider, model, reqTag = "" } = {}) {
+  const abortController = new AbortController();
+  const startTime = Date.now();
+  let disconnected = false;
+  let abortTimeout = null;
+
+  // Only abnormal terminations are logged; normal completion is covered by "📊 done".
+  // isError uses errorLine (always shown, ignores LOG_LEVEL) so failures survive quiet levels.
+  const logStream = (symbol, status, isError = false) => {
+    const duration = Date.now() - startTime;
+    const emit = isError ? log?.errorLine : log?.line;
+    if (emit) emit(reqTag, symbol, `${status} · ${provider}/${model} · ${duration}ms`);
+    else console.log(`[${getTimeString()}] ${symbol} ${provider}/${model} · ${status} · ${duration}ms`);
+  };
+
+  return {
+    signal: abortController.signal,
+    startTime,
+
+    isConnected: () => !disconnected,
+
+    // Call when client disconnects
+    handleDisconnect: (reason = "client_closed") => {
+      if (disconnected) return;
+      disconnected = true;
+
+      logStream("⚡", `DISCONNECT: ${reason}`);
+      dbg("CTRL", `${provider}/${model} | disconnect=${reason} | dur=${Date.now() - startTime}ms`);
+
+      // Delay abort to allow cleanup
+      abortTimeout = setTimeout(() => {
+        abortController.abort();
+      }, 500);
+
+      onDisconnect?.({ reason, duration: Date.now() - startTime });
+    },
+
+    // Call when stream completes normally (no line here — "📊 done" is authoritative)
+    handleComplete: () => {
+      if (disconnected) return;
+      disconnected = true;
+
+      if (abortTimeout) {
+        clearTimeout(abortTimeout);
+        abortTimeout = null;
+      }
+    },
+
+    // Call on error
+    handleError: (error) => {
+      if (disconnected) return;
+      disconnected = true;
+
+      if (abortTimeout) {
+        clearTimeout(abortTimeout);
+        abortTimeout = null;
+      }
+
+      if (error.name === "AbortError") {
+        logStream("⚡", "ABORTED");
+        return;
+      }
+
+      logStream("✗", `ERROR: ${error.message}${error.stack ? `\n    ${error.stack}` : ""}`, true);
+      onError?.(error);
+    },
+
+    abort: () => abortController.abort()
+  };
+}
+
+/**
+ * Create transform stream with disconnect detection
+ * Wraps existing transform stream and adds abort capability.
+ *
+ * Stall detection lives in pipeWithDisconnect (tied to upstream byte
+ * activity), not here — output of the transform stream may be silent
+ * for long periods while raw bytes still flow (e.g. Kiro EventStream
+ * binary frames buffering, Claude reasoning streams).
+ */
+export function createDisconnectAwareStream(transformStream, streamController, onAbortTerminal = null) {
+  const reader = transformStream.readable.getReader();
+  const writer = transformStream.writable.getWriter();
+  let terminalEmitted = false;
+
+  // Emit a synthesized terminal payload (e.g. Responses response.failed + [DONE]) once
+  const emitTerminal = (controller) => {
+    if (terminalEmitted || !onAbortTerminal) return;
+    terminalEmitted = true;
+    try {
+      const bytes = onAbortTerminal();
+      if (bytes) controller.enqueue(bytes);
+    } catch { /* best-effort terminal */ }
+  };
+
+  return new ReadableStream({
+    async pull(controller) {
+      if (!streamController.isConnected()) {
+        emitTerminal(controller);
+        controller.close();
+        return;
+      }
+
+      try {
+        const { done, value } = await reader.read();
+
+        if (done) {
+          streamController.handleComplete();
+          controller.close();
+          return;
+        }
+        controller.enqueue(value);
+      } catch (error) {
+        const wasConnected = streamController.isConnected();
+        // Controller already closed = downstream ended; not an upstream error, skip noisy log.
+        const msg0 = error?.message || "";
+        const isControllerClosed = msg0.includes("already closed") || msg0.includes("Invalid state");
+        if (!isControllerClosed) streamController.handleError(error);
+        reader.cancel().catch(() => {});
+        writer.abort().catch(() => {});
+
+        // Treat network resets / socket hang up / abort as graceful close
+        const msg = error?.message || "";
+        const code = error?.code || error?.cause?.code || "";
+        const isNetworkClose =
+          error.name === "AbortError" ||
+          msg.includes("aborted") ||
+          msg.includes("socket hang up") ||
+          msg.includes("ECONNRESET") ||
+          msg.includes("ETIMEDOUT") ||
+          msg.includes("EPIPE") ||
+          code === "ECONNRESET" ||
+          code === "ETIMEDOUT" ||
+          code === "EPIPE" ||
+          code === "UND_ERR_SOCKET";
+
+        // Graceful close on network/abort, or when a structured terminal is available
+        // (Responses passthrough prefers response.failed + [DONE] over a raw transport error)
+        try {
+          if (!wasConnected || isNetworkClose || onAbortTerminal) {
+            emitTerminal(controller);
+            controller.close();
+          } else {
+            controller.error(error);
+          }
+        } catch (e) { /* already closed or cancelled */ }
+      }
+    },
+
+    cancel(reason) {
+      streamController.handleDisconnect(reason || "cancelled");
+      reader.cancel();
+      writer.abort();
+    }
+  });
+}
+
+/**
+ * Pipe provider response through transform with disconnect detection.
+ *
+ * Stall watchdog tracks raw upstream byte activity, not transform output.
+ * Reasoning models (Claude thinking via Kiro, etc.) can produce zero SSE
+ * output for long stretches while partial EventStream frames keep arriving.
+ * Measuring stall on the transform output caused false stalls and the
+ * "failed to pipe response" error in Next.
+ *
+ * Any upstream chunk resets the timer. If no bytes arrive for
+ * STREAM_STALL_TIMEOUT_MS, abort the underlying fetch via the controller.
+ *
+ * @param {Response} providerResponse - Response from provider
+ * @param {TransformStream} transformStream - Transform stream for SSE
+ * @param {object} streamController - Stream controller from createStreamController
+ */
+export function pipeWithDisconnect(providerResponse, transformStream, streamController, onAbortTerminal = null, stallTimeoutMs = STREAM_STALL_TIMEOUT_MS) {
+  let stallTimer = null;
+  let chunkCount = 0;
+  let totalBytes = 0;
+  let lastChunkAt = Date.now();
+  const t0 = Date.now();
+  const tag = "STREAM";
+  const clearStall = () => {
+    if (stallTimer) { clearTimeout(stallTimer); stallTimer = null; }
+  };
+  const armStall = () => {
+    clearStall();
+    stallTimer = setTimeout(() => {
+      stallTimer = null;
+      dbg(tag, `STALL TIMEOUT ${stallTimeoutMs}ms | chunks=${chunkCount} | bytes=${totalBytes} | sinceLast=${Date.now() - lastChunkAt}ms`);
+      streamController.handleError?.(new Error("stream stall timeout"));
+      streamController.abort?.();
+    }, stallTimeoutMs);
+  };
+
+  // Wrap controller so every termination path clears the stall timer.
+  // Without this, abort/cancel/downstream-error paths leave the timer armed
+  // and a stale abort could fire after the request has already ended.
+  const wrappedController = {
+    signal: streamController.signal,
+    startTime: streamController.startTime,
+    isConnected: () => streamController.isConnected(),
+    handleComplete: () => { dbg(tag, `complete | chunks=${chunkCount} | bytes=${totalBytes} | dur=${Date.now() - t0}ms`); clearStall(); streamController.handleComplete(); },
+    handleError: (e) => { dbg(tag, `error: ${e?.message} | chunks=${chunkCount} | bytes=${totalBytes} | dur=${Date.now() - t0}ms`); clearStall(); streamController.handleError(e); },
+    handleDisconnect: (r) => { dbg(tag, `disconnect: ${r} | chunks=${chunkCount} | bytes=${totalBytes} | dur=${Date.now() - t0}ms`); clearStall(); streamController.handleDisconnect(r); },
+    abort: () => { clearStall(); streamController.abort(); }
+  };
+
+  armStall();
+  dbg(tag, `pipe start | stallTimeout=${stallTimeoutMs}ms`);
+
+  const upstreamTap = new TransformStream({
+    transform(chunk, controller) {
+      chunkCount++;
+      const sz = chunk?.byteLength || chunk?.length || 0;
+      totalBytes += sz;
+      const now = Date.now();
+      const gap = now - lastChunkAt;
+      lastChunkAt = now;
+      if (isDebugEnabled && (chunkCount <= 5 || chunkCount % 20 === 0 || gap > 5000)) {
+        dbg(tag, `chunk #${chunkCount} | size=${sz}B | gap=${gap}ms | total=${totalBytes}B`);
+      }
+      armStall();
+      controller.enqueue(chunk);
+    },
+    flush() { dbg(tag, `upstream EOF | chunks=${chunkCount} | bytes=${totalBytes} | dur=${Date.now() - t0}ms`); clearStall(); }
+  });
+
+  const transformedBody = providerResponse.body
+    .pipeThrough(upstreamTap)
+    .pipeThrough(transformStream);
+
+  return createDisconnectAwareStream(
+    { readable: transformedBody, writable: { getWriter: () => ({ abort: () => Promise.resolve() }) } },
+    wrappedController,
+    onAbortTerminal
+  );
+}
+
diff --git a/open-sse/utils/streamHelpers.js b/open-sse/utils/streamHelpers.js
new file mode 100644
index 0000000..a7a1918
--- /dev/null
+++ b/open-sse/utils/streamHelpers.js
@@ -0,0 +1,122 @@
+import { FORMATS } from "../translator/formats.js";
+
+// Parse SSE data line
+export function parseSSELine(line, format = null) {
+  if (!line) return null;
+
+  // NDJSON format (Ollama): raw JSON lines without "data:" prefix
+  if (format === FORMATS.OLLAMA) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("{")) {
+      try {
+        return JSON.parse(trimmed);
+      } catch (error) {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  // Standard SSE format: "data: {...}"
+  if (line.charCodeAt(0) !== 100) return null; // 'd' = 100
+
+  const data = line.slice(5).trim();
+  if (data === "[DONE]") return { done: true };
+
+  try {
+    return JSON.parse(data);
+  } catch (error) {
+    if (data.length > 0 && data.length < 1000) {
+      console.log(`[WARN] Failed to parse SSE line (${data.length} chars): ${data.substring(0, 100)}...`);
+    }
+    return null;
+  }
+}
+
+// Check if chunk has valuable content (not empty)
+export function hasValuableContent(chunk, format) {
+  // OpenAI format
+  if (format === FORMATS.OPENAI && chunk.choices?.[0]?.delta) {
+    const delta = chunk.choices[0].delta;
+    return delta.content && delta.content !== "" ||
+           delta.reasoning_content && delta.reasoning_content !== "" ||
+           delta.tool_calls && delta.tool_calls.length > 0 ||
+           chunk.choices[0].finish_reason ||
+           delta.role;
+  }
+
+  // Claude format
+  if (format === FORMATS.CLAUDE) {
+    const isContentBlockDelta = chunk.type === "content_block_delta";
+    const hasText = chunk.delta?.text && chunk.delta.text !== "";
+    const hasThinking = chunk.delta?.thinking && chunk.delta.thinking !== "";
+    const hasInputJson = chunk.delta?.partial_json && chunk.delta.partial_json !== "";
+    
+    if (isContentBlockDelta && !hasText && !hasThinking && !hasInputJson) {
+      return false;
+    }
+    return true;
+  }
+
+  return true; // Other formats: keep all chunks
+}
+
+// Fix invalid id (generic or too short)
+export function fixInvalidId(parsed) {
+  if (parsed.id && (parsed.id === "chat" || parsed.id === "completion" || parsed.id.length < 8)) {
+    const fallbackId = parsed.extend_fields?.requestId || 
+                      parsed.extend_fields?.traceId || 
+                      Date.now().toString(36);
+    parsed.id = `chatcmpl-${fallbackId}`;
+    return true;
+  }
+  return false;
+}
+
+function cleanUsagePayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return payload;
+  }
+
+  let cleaned = payload;
+
+  if ("usage" in cleaned) {
+    if (cleaned.usage === null) {
+      const { usage, ...payloadWithoutUsage } = cleaned;
+      cleaned = payloadWithoutUsage;
+    } else if (typeof cleaned.usage === "object" && cleaned.usage.perf_metrics === null) {
+      const { perf_metrics, ...usageWithoutPerf } = cleaned.usage;
+      cleaned = { ...cleaned, usage: usageWithoutPerf };
+    }
+  }
+
+  if (cleaned.response && typeof cleaned.response === "object" && !Array.isArray(cleaned.response)) {
+    const cleanedResponse = cleanUsagePayload(cleaned.response);
+    if (cleanedResponse !== cleaned.response) {
+      cleaned = { ...cleaned, response: cleanedResponse };
+    }
+  }
+
+  return cleaned;
+}
+
+// Format output as SSE
+export function formatSSE(data, sourceFormat) {
+  if (data === null || data === undefined) return "data: null\n\n";
+  if (data && data.done) return "data: [DONE]\n\n";
+
+  // OpenAI Responses API format
+  if (data && data.event && data.data) {
+    const cleanedEventData = cleanUsagePayload(data.data);
+    return `event: ${data.event}\ndata: ${JSON.stringify(cleanedEventData)}\n\n`;
+  }
+
+  data = cleanUsagePayload(data);
+
+  // Claude format
+  if (sourceFormat === FORMATS.CLAUDE && data && data.type) {
+    return `event: ${data.type}\ndata: ${JSON.stringify(data)}\n\n`;
+  }
+
+  return `data: ${JSON.stringify(data)}\n\n`;
+}
diff --git a/open-sse/utils/toolDeduper.js b/open-sse/utils/toolDeduper.js
new file mode 100644
index 0000000..20c4740
--- /dev/null
+++ b/open-sse/utils/toolDeduper.js
@@ -0,0 +1,49 @@
+/**
+ * Strip built-in/duplicate tools when equivalent MCP tools are present.
+ * Goal: reduce tool definitions token bloat for Claude clients.
+ */
+
+const DEDUP_RULES = [
+  {
+    // Exa MCP present → drop built-in web tools (Exa is preferred).
+    triggers: ["mcp__exa__web_search_exa", "mcp__exa__web_fetch_exa"],
+    strip: ["WebSearch", "WebFetch", "mcp__workspace__web_fetch"],
+  },
+  {
+    // Tavily MCP present → drop built-in web tools.
+    triggers: ["mcp__tavily__tavily_search", "mcp__tavily__tavily_extract"],
+    strip: ["WebSearch", "WebFetch", "mcp__workspace__web_fetch"],
+  },
+  {
+    // Browser MCP present → drop Cowork's duplicate Claude_in_Chrome connector.
+    triggers: [/^mcp__browsermcp__/],
+    strip: [/^mcp__Claude_in_Chrome__/],
+  },
+];
+
+function getToolName(t) {
+  return t?.name || t?.function?.name || "";
+}
+
+function matches(name, pattern) {
+  if (typeof pattern === "string") return name === pattern;
+  return pattern instanceof RegExp ? pattern.test(name) : false;
+}
+
+function dedupeTools(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) return { tools, stripped: [] };
+  const names = tools.map(getToolName);
+  const toStrip = new Set();
+  for (const rule of DEDUP_RULES) {
+    const hasTrigger = names.some((n) => rule.triggers.some((p) => matches(n, p)));
+    if (!hasTrigger) continue;
+    for (const n of names) {
+      if (rule.strip.some((p) => matches(n, p))) toStrip.add(n);
+    }
+  }
+  if (toStrip.size === 0) return { tools, stripped: [] };
+  const out = tools.filter((t) => !toStrip.has(getToolName(t)));
+  return { tools: out, stripped: Array.from(toStrip) };
+}
+
+export { dedupeTools };
diff --git a/open-sse/utils/usageTracking.js b/open-sse/utils/usageTracking.js
new file mode 100644
index 0000000..24518ef
--- /dev/null
+++ b/open-sse/utils/usageTracking.js
@@ -0,0 +1,438 @@
+/**
+ * Token Usage Tracking - Extract, normalize, estimate and log token usage
+ */
+
+import { FORMATS } from "../translator/formats.js";
+
+// Legacy per-chunk usage console line; off by default (superseded by "📊 done")
+const DEBUG_USAGE = process.env.LOG_USAGE_VERBOSE === "1";
+
+// ANSI color codes
+export const COLORS = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m"
+};
+
+// Buffer tokens to prevent context errors
+const BUFFER_TOKENS = 2000;
+
+// Get HH:MM:SS timestamp
+function getTimeString() {
+  return new Date().toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit", second: "2-digit" });
+}
+
+/**
+ * Add buffer tokens to usage to prevent context errors
+ * @param {object} usage - Usage object (any format)
+ * @returns {object} Usage with buffer added
+ */
+export function addBufferToUsage(usage) {
+  if (!usage || typeof usage !== "object") return usage;
+
+  const result = { ...usage };
+
+  // Claude format
+  if (result.input_tokens !== undefined) {
+    result.input_tokens += BUFFER_TOKENS;
+  }
+
+  // OpenAI format
+  if (result.prompt_tokens !== undefined) {
+    result.prompt_tokens += BUFFER_TOKENS;
+  }
+
+  // Calculate or update total_tokens
+  if (result.total_tokens !== undefined) {
+    result.total_tokens += BUFFER_TOKENS;
+  } else if (result.prompt_tokens !== undefined && result.completion_tokens !== undefined) {
+    // Calculate total_tokens if not exists
+    result.total_tokens = result.prompt_tokens + result.completion_tokens;
+  }
+
+  return result;
+}
+
+export function filterUsageForFormat(usage, targetFormat) {
+  if (!usage || typeof usage !== "object") return usage;
+
+  // Helper to pick only defined fields from usage
+  const pickFields = (fields) => {
+    const filtered = {};
+    for (const field of fields) {
+      if (usage[field] !== undefined) {
+        filtered[field] = usage[field];
+      }
+    }
+    return filtered;
+  };
+
+  // Define allowed fields for each format
+  const formatFields = {
+    [FORMATS.CLAUDE]: [
+      'input_tokens', 'output_tokens', 
+      'cache_read_input_tokens', 'cache_creation_input_tokens',
+      'estimated'
+    ],
+    [FORMATS.GEMINI]: [
+      'promptTokenCount', 'candidatesTokenCount', 'totalTokenCount',
+      'cachedContentTokenCount', 'thoughtsTokenCount',
+      'estimated'
+    ],
+    [FORMATS.OPENAI_RESPONSES]: [
+      'input_tokens', 'output_tokens',
+      'input_tokens_details', 'output_tokens_details',
+      'estimated'
+    ],
+    // OpenAI format (default for OPENAI, CODEX, KIRO, etc.)
+    default: [
+      'prompt_tokens', 'completion_tokens', 'total_tokens',
+      'cached_tokens', 'reasoning_tokens',
+      'prompt_tokens_details', 'completion_tokens_details',
+      'estimated'
+    ]
+  };
+
+  // Get fields for target format
+  let fields = formatFields[targetFormat];
+  
+  // Use same fields for similar formats
+  if (targetFormat === FORMATS.GEMINI_CLI || targetFormat === FORMATS.ANTIGRAVITY) {
+    fields = formatFields[FORMATS.GEMINI];
+  } else if (targetFormat === FORMATS.OPENAI_RESPONSE) {
+    fields = formatFields[FORMATS.OPENAI_RESPONSES];
+  } else if (!fields) {
+    fields = formatFields.default;
+  }
+
+  return pickFields(fields);
+}
+
+/**
+ * Normalize usage object - ensure all values are valid numbers
+ */
+export function normalizeUsage(usage) {
+  if (!usage || typeof usage !== "object" || Array.isArray(usage)) return null;
+
+  const normalized = {};
+  const assignNumber = (key, value) => {
+    if (value === undefined || value === null) return;
+    const numeric = Number(value);
+    if (Number.isFinite(numeric)) normalized[key] = numeric;
+  };
+
+  assignNumber("prompt_tokens", usage?.prompt_tokens);
+  assignNumber("completion_tokens", usage?.completion_tokens);
+  assignNumber("total_tokens", usage?.total_tokens);
+  assignNumber("cache_read_input_tokens", usage?.cache_read_input_tokens);
+  assignNumber("cache_creation_input_tokens", usage?.cache_creation_input_tokens);
+  assignNumber("cached_tokens", usage?.cached_tokens);
+  assignNumber("reasoning_tokens", usage?.reasoning_tokens);
+
+  // Preserve nested details objects for OpenAI format forwarding
+  if (usage?.prompt_tokens_details && typeof usage.prompt_tokens_details === "object") {
+    normalized.prompt_tokens_details = usage.prompt_tokens_details;
+  }
+  if (usage?.completion_tokens_details && typeof usage.completion_tokens_details === "object") {
+    normalized.completion_tokens_details = usage.completion_tokens_details;
+  }
+
+  if (Object.keys(normalized).length === 0) return null;
+  return normalized;
+}
+
+/**
+ * Canonicalize usage into ONE storage/cost convention so token counts and cost
+ * are consistent across providers:
+ *   prompt_tokens               = total input INCLUDING cache read + cache creation
+ *   cached_tokens               = cache-read portion (subset of prompt_tokens)
+ *   cache_creation_input_tokens = cache-write portion (subset of prompt_tokens)
+ *   completion_tokens, reasoning_tokens, total_tokens
+ *
+ * Discriminator: Claude reports cache_read_input_tokens with a prompt that
+ * EXCLUDES cache, so we fold cache into prompt. OpenAI/Gemini report
+ * cached_tokens already counted inside prompt, so we pass through. Idempotent:
+ * once folded the output carries cached_tokens (not cache_read_input_tokens),
+ * so re-running takes the passthrough branch and does not double-add.
+ *
+ * @param {object} usage - a normalizeUsage()-shaped object
+ * @returns {object|null} canonical token object, or null for invalid input
+ */
+export function canonicalizeUsage(usage) {
+  if (!usage || typeof usage !== "object" || Array.isArray(usage)) return null;
+
+  const num = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0);
+  const completion = num(usage.completion_tokens ?? usage.output_tokens);
+  const reasoning = num(usage.reasoning_tokens);
+  // Fall back to the nested prompt_tokens_details.cache_creation_tokens shape
+  // (buildUsage()'s OpenAI-forwarding format) when the top-level field is
+  // absent, so callers that pass a buildUsage() object through don't silently
+  // drop cache_creation.
+  const cacheCreation = num(usage.cache_creation_input_tokens ?? usage.prompt_tokens_details?.cache_creation_tokens);
+
+  let prompt = num(usage.prompt_tokens ?? usage.input_tokens);
+  let cached;
+
+  // Claude path: prompt excludes cache; cache_read_input_tokens and/or
+  // cache_creation_input_tokens are separate. A cache-miss "first write" only
+  // carries cache_creation_input_tokens (no cache_read_input_tokens yet), so
+  // check both fields — otherwise a first-write request falls through to the
+  // OpenAI passthrough branch below and cache_creation never gets folded in.
+  // Guard on the absence of `cached_tokens`: our own canonical output always
+  // sets that key (even to 0), so re-running canonicalizeUsage on an already-
+  // folded result takes the passthrough branch instead of folding again.
+  if (usage.cached_tokens === undefined &&
+      (usage.cache_read_input_tokens !== undefined || usage.cache_creation_input_tokens !== undefined)) {
+    cached = num(usage.cache_read_input_tokens);
+    prompt = prompt + cached + cacheCreation;
+  } else {
+    // OpenAI/Gemini path (or already-canonical input): prompt already includes cached_tokens.
+    cached = num(usage.cached_tokens);
+  }
+
+  const result = {
+    prompt_tokens: prompt,
+    completion_tokens: completion,
+    // Recompute rather than pass through: when the fold branch ran above,
+    // an upstream total_tokens (cache-exclusive) would otherwise be stale.
+    total_tokens: prompt + completion,
+    cached_tokens: cached,
+    cache_creation_input_tokens: cacheCreation,
+  };
+  if (reasoning > 0) result.reasoning_tokens = reasoning;
+  return result;
+}
+
+/**
+ * Check if usage has valid token data
+ * Valid = has at least one token field with value > 0
+ * Invalid = empty object {}, null, undefined, no token fields, or all zeros
+ */
+export function hasValidUsage(usage) {
+  if (!usage || typeof usage !== "object") return false;
+
+  // Check for any known token field with value > 0
+  const tokenFields = [
+    "prompt_tokens", "completion_tokens", "total_tokens",  // OpenAI
+    "input_tokens", "output_tokens",                        // Claude
+    "promptTokenCount", "candidatesTokenCount"              // Gemini
+  ];
+
+  for (const field of tokenFields) {
+    if (typeof usage[field] === "number" && usage[field] > 0) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Extract usage from any format (Claude, OpenAI, Gemini, Responses API)
+ */
+export function extractUsage(chunk) {
+  if (!chunk || typeof chunk !== "object") return null;
+
+  // Claude format (message_start event): carries input_tokens + cache_read +
+  // cache_creation. message_delta later carries only the final output_tokens,
+  // so callers must MERGE (mergeUsage), not overwrite, to keep cache counts.
+  if (chunk.type === "message_start" && chunk.message?.usage && typeof chunk.message.usage === "object") {
+    const u = chunk.message.usage;
+    return normalizeUsage({
+      prompt_tokens: u.input_tokens || 0,
+      completion_tokens: u.output_tokens || 0,
+      cache_read_input_tokens: u.cache_read_input_tokens,
+      cache_creation_input_tokens: u.cache_creation_input_tokens
+    });
+  }
+
+  // Claude format (message_delta event)
+  if (chunk.type === "message_delta" && chunk.usage && typeof chunk.usage === "object") {
+    return normalizeUsage({
+      prompt_tokens: chunk.usage.input_tokens || 0,
+      completion_tokens: chunk.usage.output_tokens || 0,
+      cache_read_input_tokens: chunk.usage.cache_read_input_tokens,
+      cache_creation_input_tokens: chunk.usage.cache_creation_input_tokens
+    });
+  }
+
+  // OpenAI Responses API format (response.completed or response.done)
+  if ((chunk.type === "response.completed" || chunk.type === "response.done") && chunk.response?.usage && typeof chunk.response.usage === "object") {
+    const usage = chunk.response.usage;
+    const cachedTokens = usage.input_tokens_details?.cached_tokens;
+    return normalizeUsage({
+      prompt_tokens: usage.input_tokens || usage.prompt_tokens || 0,
+      completion_tokens: usage.output_tokens || usage.completion_tokens || 0,
+      cached_tokens: cachedTokens,
+      reasoning_tokens: usage.output_tokens_details?.reasoning_tokens,
+      prompt_tokens_details: cachedTokens ? { cached_tokens: cachedTokens } : undefined
+    });
+  }
+
+  // OpenAI format (also covers DeepSeek which uses prompt_cache_hit_tokens)
+  if (chunk.usage && typeof chunk.usage === "object" && chunk.usage.prompt_tokens !== undefined) {
+    return normalizeUsage({
+      prompt_tokens: chunk.usage.prompt_tokens,
+      completion_tokens: chunk.usage.completion_tokens || 0,
+      cached_tokens: chunk.usage.prompt_tokens_details?.cached_tokens || chunk.usage.prompt_cache_hit_tokens,
+      reasoning_tokens: chunk.usage.completion_tokens_details?.reasoning_tokens,
+      prompt_tokens_details: chunk.usage.prompt_tokens_details,
+      completion_tokens_details: chunk.usage.completion_tokens_details
+    });
+  }
+
+  // Gemini format (Antigravity)
+  // Antigravity wraps usageMetadata inside response: { response: { usageMetadata: {...} } }
+  const usageMeta = chunk.usageMetadata || chunk.response?.usageMetadata;
+  if (usageMeta && typeof usageMeta === "object") {
+    return normalizeUsage({
+      prompt_tokens: usageMeta.promptTokenCount || 0,
+      completion_tokens: usageMeta.candidatesTokenCount || 0,
+      total_tokens: usageMeta.totalTokenCount,
+      cached_tokens: usageMeta.cachedContentTokenCount,
+      reasoning_tokens: usageMeta.thoughtsTokenCount
+    });
+  }
+
+  // Ollama NDJSON format (raw from provider, before translation)
+  // Ollama sends: {"model":"...","done":true,"prompt_eval_count":N,"eval_count":M}
+  if (chunk.done === true && typeof chunk.prompt_eval_count === "number") {
+    return normalizeUsage({
+      prompt_tokens: chunk.prompt_eval_count || 0,
+      completion_tokens: chunk.eval_count || 0,
+      total_tokens: (chunk.prompt_eval_count || 0) + (chunk.eval_count || 0)
+    });
+  }
+
+  return null;
+}
+
+// Field-wise max-merge of two usage objects. Anthropic splits usage across
+// events: message_start has real input+cache (output is a placeholder 1),
+// message_delta has the real cumulative output (input/cache absent). Max keeps
+// the meaningful value from each without clobbering. Idempotent for other
+// providers that emit a single complete usage object.
+export function mergeUsage(prev, next) {
+  if (!prev) return next || null;
+  if (!next) return prev;
+  const merged = { ...prev };
+  for (const [k, v] of Object.entries(next)) {
+    // typeof NaN === "number" — guard with Number.isFinite so one malformed
+    // chunk can't poison the whole accumulation (Math.max(x, NaN) is NaN).
+    if (typeof v === "number" && Number.isFinite(v)) {
+      merged[k] = Math.max(typeof merged[k] === "number" ? merged[k] : 0, v);
+    } else if (v && typeof v === "object") {
+      merged[k] = v; // nested details objects: take latest
+    }
+  }
+  return merged;
+}
+
+/**
+ * Estimate input tokens from request body
+ * Calculate total body size for more accurate estimation
+ */
+export function estimateInputTokens(body) {
+  if (!body || typeof body !== "object") return 0;
+
+  try {
+    // Calculate total body size (includes messages, tools, system, thinking config, etc.)
+    const bodyStr = JSON.stringify(body);
+    const totalChars = bodyStr.length;
+
+    // Estimate: ~4 chars per token (rough average across all tokenizers)
+    return Math.ceil(totalChars / 4);
+  } catch (err) {
+    // Fallback if stringify fails
+    return 0;
+  }
+}
+
+/**
+ * Estimate output tokens from content length
+ */
+export function estimateOutputTokens(contentLength) {
+  if (!contentLength || contentLength <= 0) return 0;
+  return Math.max(1, Math.floor(contentLength / 4));
+}
+
+/**
+ * Format usage object based on target format
+ * @param {number} inputTokens - Input/prompt tokens
+ * @param {number} outputTokens - Output/completion tokens
+ * @param {string} targetFormat - Target format from FORMATS
+ */
+export function formatUsage(inputTokens, outputTokens, targetFormat) {
+  // Claude format uses input_tokens/output_tokens
+  if (targetFormat === FORMATS.CLAUDE) {
+    return addBufferToUsage({ 
+      input_tokens: inputTokens, 
+      output_tokens: outputTokens, 
+      estimated: true 
+    });
+  }
+
+  // Default: OpenAI format (works for openai, gemini, responses, etc.)
+  return addBufferToUsage({
+    prompt_tokens: inputTokens,
+    completion_tokens: outputTokens,
+    total_tokens: inputTokens + outputTokens,
+    estimated: true
+  });
+}
+
+/**
+ * Estimate full usage when provider doesn't return it
+ * @param {object} body - Request body for input token estimation
+ * @param {number} contentLength - Content length for output token estimation
+ * @param {string} targetFormat - Target format from FORMATS constant
+ */
+export function estimateUsage(body, contentLength, targetFormat = FORMATS.OPENAI) {
+  return formatUsage(
+    estimateInputTokens(body),
+    estimateOutputTokens(contentLength),
+    targetFormat
+  );
+}
+
+/**
+ * Log usage with cache info (green color)
+ */
+export function logUsage(provider, usage, model = null, connectionId = null, apiKey = null) {
+  if (!usage || typeof usage !== "object") return;
+
+  // Console output moved to the unified "📊 done" line (streamingHandler). Kept as
+  // a no-op hook so callers stay unchanged; usage persistence happens via saveUsageStats.
+  if (!DEBUG_USAGE) return;
+
+  const p = provider?.toUpperCase() || "UNKNOWN";
+
+  // Support both formats:
+  // - OpenAI: prompt_tokens, completion_tokens
+  // - Claude: input_tokens, output_tokens
+  const inTokens = usage?.prompt_tokens || usage?.input_tokens || 0;
+  const outTokens = usage?.completion_tokens || usage?.output_tokens || 0;
+  const accountPrefix = connectionId ? connectionId.slice(0, 8) + "..." : "unknown";
+
+  let msg = `[${getTimeString()}] 📊 ${COLORS.green}[USAGE] ${p} | in=${inTokens} | out=${outTokens} | account=${accountPrefix}${COLORS.reset}`;
+
+  // Add estimated flag if present
+  if (usage.estimated) {
+    msg += ` ${COLORS.yellow}(estimated)${COLORS.reset}`;
+  }
+
+  // Add cache info if present (unified from different formats)
+  const cacheRead = usage.cache_read_input_tokens || usage.cached_tokens || usage.prompt_tokens_details?.cached_tokens;
+  if (cacheRead) msg += ` | cache_read=${cacheRead}`;
+
+  const cacheCreation = usage.cache_creation_input_tokens;
+  if (cacheCreation) msg += ` | cache_create=${cacheCreation}`;
+
+  const reasoning = usage.reasoning_tokens;
+  if (reasoning) msg += ` | reasoning=${reasoning}`;
+
+  console.log(msg);
+}
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..352b661
--- /dev/null
+++ b/package.json
@@ -0,0 +1,60 @@
+{
+  "name": "9router-app",
+  "version": "0.5.30",
+  "description": "9Router web dashboard",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --port 20127",
+    "dev:webpack": "next dev --webpack --port 20127",
+    "build": "next build --webpack",
+    "start": "next start --port 20127",
+    "dev:bun": "bun --bun next dev --webpack --port 20127",
+    "build:bun": "bun --bun next build --webpack",
+    "start:bun": "bun ./.next/standalone/server.js",
+    "cli:pack": "npm --prefix cli run pack:cli",
+    "cli:publish": "npm --prefix cli run publish:cli"
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/modifiers": "^9.0.0",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@monaco-editor/react": "^4.7.0",
+    "@next/third-parties": "^16.2.9",
+    "@xyflow/react": "^12.10.1",
+    "bcryptjs": "^3.0.3",
+    "confbox": "^0.2.4",
+    "express": "^5.2.1",
+    "http-proxy-middleware": "^3.0.5",
+    "jose": "^6.1.3",
+    "marked": "^18.0.1",
+    "material-symbols": "^0.44.6",
+    "monaco-editor": "^0.55.1",
+    "next": "^16.1.6",
+    "node-forge": "^1.3.3",
+    "node-machine-id": "^1.1.12",
+    "open": "^11.0.0",
+    "ora": "^9.1.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-is": "^16.13.1",
+    "recharts": "^3.7.0",
+    "selfsigned": "^5.5.0",
+    "socks-proxy-agent": "^8.0.5",
+    "sql.js": "^1.14.1",
+    "undici": "^7.19.2",
+    "uuid": "^13.0.0",
+    "zustand": "^5.0.10"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^12.6.2"
+  },
+  "comment_better_sqlite3": "kept in optionalDependencies so npm install doesn't fail on systems without build tools — sql.js is used as fallback at runtime",
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.18",
+    "eslint": "^9",
+    "eslint-config-next": "16.1.6",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4"
+  }
+}
diff --git a/postcss.config.mjs b/postcss.config.mjs
new file mode 100644
index 0000000..17fa423
--- /dev/null
+++ b/postcss.config.mjs
@@ -0,0 +1,12 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const projectRoot = path.dirname(fileURLToPath(import.meta.url));
+
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {
+      base: projectRoot,
+    },
+  },
+};
diff --git a/public/favicon.svg b/public/favicon.svg
new file mode 100644
index 0000000..a72e45b
--- /dev/null
+++ b/public/favicon.svg
@@ -0,0 +1,11 @@
+<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="32" height="32" rx="6" fill="url(#gradient)"/>
+  <text x="16" y="24" font-family="system-ui, -apple-system, sans-serif" font-size="20" font-weight="700" fill="white" text-anchor="middle">9</text>
+  <defs>
+    <linearGradient id="gradient" x1="0" y1="0" x2="32" y2="32" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#f97815"/>
+      <stop offset="1" stop-color="#c2590a"/>
+    </linearGradient>
+  </defs>
+</svg>
+
diff --git a/public/file.svg b/public/file.svg
new file mode 100644
index 0000000..004145c
--- /dev/null
+++ b/public/file.svg
@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>
\ No newline at end of file
diff --git a/public/globe.svg b/public/globe.svg
new file mode 100644
index 0000000..567f17b
--- /dev/null
+++ b/public/globe.svg
@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>
\ No newline at end of file
diff --git a/public/i18n/literals/ar.json b/public/i18n/literals/ar.json
new file mode 100644
index 0000000..32b72f8
--- /dev/null
+++ b/public/i18n/literals/ar.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "إلغاء",
+  "Delete": "حذف",
+  "Edit": "تحرير",
+  "Save": "حفظ",
+  "Close": "إغلاق",
+  "Add": "إضافة",
+  "Remove": "إزالة",
+  "Settings": "الإعدادات",
+  "Profile": "الملف الشخصي",
+  "Dashboard": "لوحة التحكم",
+  "Logout": "تسجيل الخروج",
+  "Login": "تسجيل الدخول",
+  "Providers": "الموفرون",
+  "Usage": "الإحصائيات",
+  "API Key": "مفتاح API",
+  "Connected": "متصل",
+  "Disconnected": "غير متصل",
+  "Active": "نشط",
+  "Inactive": "غير نشط",
+  "Success": "نجح",
+  "Failed": "فشل",
+  "Error": "خطأ",
+  "Warning": "تحذير",
+  "Info": "معلومات",
+  "Loading": "جاري التحميل",
+  "Search": "بحث",
+  "Filter": "تصفية",
+  "Sort": "ترتيب",
+  "Export": "تصدير",
+  "Import": "استيراد",
+  "Refresh": "تحديث",
+  "Back": "رجوع",
+  "Next": "التالي",
+  "Previous": "السابق",
+  "Submit": "إرسال",
+  "Confirm": "تأكيد",
+  "Yes": "نعم",
+  "No": "لا",
+  "OK": "حسنا",
+  "Apply": "تطبيق",
+  "Reset": "إعادة تعيين",
+  "Clear": "مسح",
+  "Select": "تحديد",
+  "Upload": "تحميل",
+  "Download": "تنزيل",
+  "Copy": "نسخ",
+  "Paste": "لصق",
+  "Cut": "قص",
+  "Undo": "تراجع",
+  "Redo": "إعادة",
+  "Name": "الاسم",
+  "Description": "الوصف",
+  "Status": "الحالة",
+  "Type": "النوع",
+  "Date": "التاريخ",
+  "Time": "الوقت",
+  "Created": "تم إنشاء",
+  "Updated": "تم التحديث",
+  "Actions": "الإجراءات",
+  "Details": "التفاصيل",
+  "View": "عرض",
+  "New": "جديد",
+  "Total": "الإجمالي",
+  "Count": "العدد",
+  "Price": "السعر",
+  "Cost": "التكلفة",
+  "Free": "مجاني",
+  "Paid": "مدفوع",
+  "Enable": "تفعيل",
+  "Disable": "تعطيل",
+  "Enabled": "مفعل",
+  "Disabled": "معطل",
+  "Online": "متصل",
+  "Offline": "غير متصل",
+  "Available": "متاح",
+  "Unavailable": "غير متاح",
+  "Required": "مطلوب",
+  "Optional": "اختياري",
+  "Default": "افتراضي",
+  "Custom": "مخصص",
+  "Advanced": "متقدم",
+  "Basic": "أساسي",
+  "Help": "مساعدة",
+  "Support": "دعم",
+  "Documentation": "التوثيق",
+  "Version": "الإصدار",
+  "Language": "اللغة",
+  "Theme": "المظهر",
+  "Light": "فاتح",
+  "Dark": "داكن",
+  "Auto": "تلقائي",
+  "Endpoint": "نقطة نهاية",
+  "Combos": "تراكيب",
+  "Quota Tracker": "متتبع الحصة",
+  "MITM": "MITM",
+  "CLI Tools": "أدوات CLI",
+  "Console Log": "سجل وحدة التحكم",
+  "System": "النظام",
+  "Debug": "تصحيح",
+  "Shutdown": "إيقاف",
+  "Close Proxy": "إغلاق الوكيل",
+  "Are you sure you want to close the proxy server?": "هل أنت متأكد من أنك تريد إغلاق خادم الوكيل؟",
+  "Server Disconnected": "خادم غير متصل",
+  "The proxy server has been stopped.": "تم إيقاف خادم الوكيل.",
+  "Reload Page": "إعادة تحميل الصفحة",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "الخدمة تعمل في المحطة الطرفية. يمكنك إغلاق صفحة الويب هذه. سيؤدي الإيقاف إلى إيقاف الخدمة.",
+  "Manage your AI provider connections": "إدارة اتصالات موفر الذكاء الاصطناعي الخاصة بك",
+  "Model combos with fallback": "تراكيب النموذج مع الخيار البديل",
+  "Monitor your API usage, token consumption, and request logs": "راقب استخدام API وتناول الرموز وسجلات الطلب",
+  "Intercept CLI tool traffic and route through 9Router": "اعترض حركة مرور أداة CLI وحجم من خلال 9Router",
+  "Configure CLI tools": "تكوين أدوات CLI",
+  "API endpoint configuration": "تكوين نقطة نهاية API",
+  "Manage your preferences": "إدارة تفضيلاتك",
+  "Debug translation flow between formats": "تصحيح تدفق الترجمة بين الصيغ",
+  "Live server console output": "مخرجات وحدة التحكم على الخادم المباشر",
+  "Create model combos with fallback support": "إنشاء تراكيب نموذج مع دعم الخيار البديل",
+  "Local Mode": "الوضع المحلي",
+  "Running on your machine": "يعمل على جهازك",
+  "Database Location": "موقع قاعدة البيانات",
+  "Download Backup": "تنزيل النسخة الاحتياطية",
+  "Import Backup": "استيراد النسخة الاحتياطية",
+  "Database backup downloaded": "تم تنزيل النسخة الاحتياطية لقاعدة البيانات",
+  "Database imported successfully": "تم استيراد قاعدة البيانات بنجاح",
+  "Security": "الأمان",
+  "Require login": "يتطلب تسجيل الدخول",
+  "When ON, dashboard requires password. When OFF, access without login.": "عند التشغيل، يتطلب لوحة التحكم كلمة مرور. عند الإيقاف، الوصول بدون تسجيل دخول.",
+  "Current Password": "كلمة المرور الحالية",
+  "Enter current password": "أدخل كلمة المرور الحالية",
+  "New Password": "كلمة مرور جديدة",
+  "Enter new password": "أدخل كلمة مرور جديدة",
+  "Confirm New Password": "تأكيد كلمة المرور الجديدة",
+  "Confirm new password": "تأكيد كلمة المرور الجديدة",
+  "Update Password": "تحديث كلمة المرور",
+  "Set Password": "تعيين كلمة المرور",
+  "Password updated successfully": "تم تحديث كلمة المرور بنجاح",
+  "Passwords do not match": "كلمات المرور لا تتطابق",
+  "Routing Strategy": "استراتيجية التوجيه",
+  "Round Robin": "جولة روبن",
+  "Cycle through accounts to distribute load": "الدوران عبر الحسابات لتوزيع الحمل",
+  "Sticky Limit": "حد لزج",
+  "Calls per account before switching": "المكالمات لكل حساب قبل التبديل",
+  "Network": "الشبكة",
+  "Outbound Proxy": "وكيل الخروج",
+  "Enable proxy for OAuth + provider outbound requests.": "تفعيل الوكيل لطلبات OAuth + الخروج من الموفر.",
+  "Proxy URL": "عنوان URL الوكيل",
+  "Leave empty to inherit existing env proxy (if any).": "اترك فارغًا لوراثة وكيل env الموجود (إن وجد).",
+  "No Proxy": "لا يوجد وكيل",
+  "Comma-separated hostnames/domains to bypass the proxy.": "أسماء المضيفين/النطاقات المفصولة بفواصل لتجاوز الوكيل.",
+  "Test proxy URL": "اختبر عنوان URL الوكيل",
+  "Proxy settings applied": "تم تطبيق إعدادات الوكيل",
+  "Proxy enabled": "الوكيل مفعل",
+  "Proxy disabled": "الوكيل معطل",
+  "Proxy test OK": "اختبار الوكيل حسنا",
+  "Proxy test failed": "فشل اختبار الوكيل",
+  "Please enter a Proxy URL to test": "يرجى إدخال عنوان URL الوكيل للاختبار",
+  "Observability": "القابلية للمراقبة",
+  "Enable Observability": "تفعيل القابلية للمراقبة",
+  "Turn request detail recording on/off globally": "تشغيل/إيقاف تسجيل تفاصيل الطلب بشكل عام",
+  "Max Records": "أقصى عدد من السجلات",
+  "Maximum request detail records to keep (older records are auto-deleted)": "الحد الأقصى من سجلات تفاصيل الطلب للاحتفاظ بها (يتم حذف السجلات الأقدم تلقائيًا)",
+  "Batch Size": "حجم الدفعة",
+  "Number of items to accumulate before writing to database (higher = better performance)": "عدد العناصر المراد تجميعها قبل الكتابة إلى قاعدة البيانات (أعلى = أداء أفضل)",
+  "Flush Interval (ms)": "فترة المسح (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "الحد الأقصى للانتظار قبل مسح المخزن المؤقت (يمنع فقدان البيانات أثناء الحركة المنخفضة)",
+  "Max JSON Size (KB)": "أقصى حجم JSON (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "الحد الأقصى لحجم كل حقل JSON (الطلب/الرد) قبل القطع",
+  "All data stored on your machine": "جميع البيانات المخزنة على جهازك",
+  "MITM Server": "خادم MITM",
+  "Running": "يجري",
+  "Stopped": "متوقف",
+  "Cert": "شهادة",
+  "Server": "الخادم",
+  "Purpose:": "الغرض:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "استخدم Antigravity IDE و GitHub Copilot → مع أي موفر/نموذج من 9Router",
+  "How it works:": "كيف يعمل:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "طلب Antigravity/Copilot IDE → إعادة توجيه DNS إلى localhost:443 → يعترض وكيل MITM → 9Router → الرد إلى Antigravity/Copilot",
+  "No API keys — create one in Keys page": "لا توجد مفاتيح API — قم بإنشاء واحدة في صفحة المفاتيح",
+  "sk_9router (default)": "sk_9router (افتراضي)",
+  "Server started": "تم بدء الخادم",
+  "Failed to start server": "فشل في بدء الخادم",
+  "Server stopped — all DNS cleared": "تم إيقاف الخادم — تم مسح جميع DNS",
+  "Failed to stop server": "فشل في إيقاف الخادم",
+  "Sudo password is required": "كلمة مرور sudo مطلوبة",
+  "Stop Server": "إيقاف الخادم",
+  "Start Server": "بدء الخادم",
+  "Enable DNS per tool below to activate interception": "قم بتفعيل DNS لكل أداة أدناه لتفعيل الاعتراض",
+  "Sudo Password Required": "كلمة مرور Sudo مطلوبة",
+  "Enter your sudo password to start/stop MITM server": "أدخل كلمة مرور sudo للبدء/الإيقاف من خادم MITM",
+  "Sudo Password": "كلمة مرور Sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "انقر للإضافة، انقر مرة أخرى للإزالة. يتم حفظ التغييرات تلقائيًا.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ تنبيه مخاطر: يستخدم هذا الموفر اشتراكًا/جلسة OAuth غير مرخصة رسميًا للاستخدام عبر البروكسي/الراوتر. قد يتم تقييد الحساب أو حظره. الاستخدام على مسؤوليتك الخاصة.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ يعترض MITM حركة مرور HTTPS لأدوات IDE (Antigravity، GitHub Copilot، Kiro) عبر CA محلية لإعادة توجيه الطلبات إلى مزوديك. قد ينتهك شروط الخدمة → خطر حظر الحساب. الاستخدام على مسؤوليتك الخاصة.",
+  "Endpoint is exposed without an API key.": "نقطة النهاية مكشوفة بدون مفتاح API."
+}
diff --git a/public/i18n/literals/bn.json b/public/i18n/literals/bn.json
new file mode 100644
index 0000000..ef71ddf
--- /dev/null
+++ b/public/i18n/literals/bn.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "বাতিল করুন",
+  "Delete": "মুছুন",
+  "Edit": "সম্পাদনা করুন",
+  "Save": "সংরক্ষণ করুন",
+  "Close": "বন্ধ করুন",
+  "Add": "যোগ করুন",
+  "Remove": "সরান",
+  "Settings": "সেটিংস",
+  "Profile": "প্রোফাইল",
+  "Dashboard": "ড্যাশবোর্ড",
+  "Logout": "লগ আউট",
+  "Login": "লগ ইন",
+  "Providers": "সরবরাহকারী",
+  "Usage": "ব্যবহারের পরিসংখ্যান",
+  "API Key": "API কী",
+  "Connected": "সংযুক্ত",
+  "Disconnected": "বিচ্ছিন্ন",
+  "Active": "সক্রিয়",
+  "Inactive": "নিষ্ক্রিয়",
+  "Success": "সফল",
+  "Failed": "ব্যর্থ",
+  "Error": "ত্রুটি",
+  "Warning": "সতর্কতা",
+  "Info": "তথ্য",
+  "Loading": "লোড হচ্ছে",
+  "Search": "অনুসন্ধান করুন",
+  "Filter": "ফিল্টার",
+  "Sort": "সাজান",
+  "Export": "রপ্তানি করুন",
+  "Import": "আমদানি করুন",
+  "Refresh": "রিফ্রেশ করুন",
+  "Back": "ফিরে যান",
+  "Next": "পরবর্তী",
+  "Previous": "পূর্ববর্তী",
+  "Submit": "জমা দিন",
+  "Confirm": "নিশ্চিত করুন",
+  "Yes": "হ্যাঁ",
+  "No": "না",
+  "OK": "ঠিক আছে",
+  "Apply": "প্রয়োগ করুন",
+  "Reset": "পুনরায় সেট করুন",
+  "Clear": "সাফ করুন",
+  "Select": "নির্বাচন করুন",
+  "Upload": "আপলোড করুন",
+  "Download": "ডাউনলোড করুন",
+  "Copy": "অনুলিপি করুন",
+  "Paste": "পেস্ট করুন",
+  "Cut": "কাটুন",
+  "Undo": "পূর্বাবস্থায় ফিরিয়ে আনুন",
+  "Redo": "পুনরায় করুন",
+  "Name": "নাম",
+  "Description": "বর্ণনা",
+  "Status": "অবস্থা",
+  "Type": "ধরন",
+  "Date": "তারিখ",
+  "Time": "সময়",
+  "Created": "তৈরি করা হয়েছে",
+  "Updated": "আপডেট করা হয়েছে",
+  "Actions": "পদক্ষেপ",
+  "Details": "বিশদ",
+  "View": "দেখুন",
+  "New": "নতুন",
+  "Total": "মোট",
+  "Count": "গণনা",
+  "Price": "দাম",
+  "Cost": "খরচ",
+  "Free": "বিনামূল্যে",
+  "Paid": "পেইড",
+  "Enable": "সক্ষম করুন",
+  "Disable": "অক্ষম করুন",
+  "Enabled": "সক্ষম",
+  "Disabled": "অক্ষম",
+  "Online": "অনলাইন",
+  "Offline": "অফলাইন",
+  "Available": "উপলব্ধ",
+  "Unavailable": "অনুপলব্ধ",
+  "Required": "প্রয়োজনীয়",
+  "Optional": "ঐচ্ছিক",
+  "Default": "ডিফল্ট",
+  "Custom": "কাস্টম",
+  "Advanced": "উন্নত",
+  "Basic": "মৌলিক",
+  "Help": "সহায়তা",
+  "Support": "সহায়তা",
+  "Documentation": "ডকুমেন্টেশন",
+  "Version": "সংস্করণ",
+  "Language": "ভাষা",
+  "Theme": "থিম",
+  "Light": "হালকা",
+  "Dark": "গাঢ়",
+  "Auto": "স্বয়ংক্রিয়",
+  "Endpoint": "এন্ডপয়েন্ট",
+  "Combos": "কম্বো",
+  "Quota Tracker": "কোটা ট্র্যাকার",
+  "MITM": "MITM",
+  "CLI Tools": "সরঞ্জাম",
+  "Console Log": "কনসোল লগ",
+  "System": "সিস্টেম",
+  "Debug": "ডিবাগ",
+  "Shutdown": "বন্ধ করুন",
+  "Close Proxy": "প্রক্সি বন্ধ করুন",
+  "Are you sure you want to close the proxy server?": "আপনি কি নিশ্চিত যে আপনি প্রক্সি সার্ভার বন্ধ করতে চান?",
+  "Server Disconnected": "সার্ভার সংযোগ বিচ্ছিন্ন",
+  "The proxy server has been stopped.": "প্রক্সি সার্ভার বন্ধ করা হয়েছে।",
+  "Reload Page": "পৃষ্ঠা পুনরায় লোড করুন",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "সেবা টার্মিনালে চলছে। আপনি এই ওয়েব পৃষ্ঠাটি বন্ধ করতে পারেন। শাটডাউন সেবা বন্ধ করবে।",
+  "Manage your AI provider connections": "আপনার AI সরবরাহকারী সংযোগ পরিচালনা করুন",
+  "Model combos with fallback": "ফলব্যাক সহ মডেল কম্বো",
+  "Monitor your API usage, token consumption, and request logs": "আপনার API ব্যবহার, টোকেন খরচ এবং অনুরোধ লগ পর্যবেক্ষণ করুন",
+  "Intercept CLI tool traffic and route through 9Router": "CLI টুল ট্রাফিক ইন্টারসেপ্ট করুন এবং 9Router এর মাধ্যমে রুট করুন",
+  "Configure CLI tools": "CLI সরঞ্জাম কনফিগার করুন",
+  "API endpoint configuration": "API এন্ডপয়েন্ট কনফিগারেশন",
+  "Manage your preferences": "আপনার পছন্দগুলি পরিচালনা করুন",
+  "Debug translation flow between formats": "ফর্ম্যাটগুলির মধ্যে অনুবাদ প্রবাহ ডিবাগ করুন",
+  "Live server console output": "লাইভ সার্ভার কনসোল আউটপুট",
+  "Create model combos with fallback support": "ফলব্যাক সমর্থন সহ মডেল কম্বো তৈরি করুন",
+  "Local Mode": "স্থানীয় মোড",
+  "Running on your machine": "আপনার মেশিনে চলছে",
+  "Database Location": "ডাটাবেস অবস্থান",
+  "Download Backup": "ব্যাকআপ ডাউনলোড করুন",
+  "Import Backup": "ব্যাকআপ আমদানি করুন",
+  "Database backup downloaded": "ডাটাবেস ব্যাকআপ ডাউনলোড করা হয়েছে",
+  "Database imported successfully": "ডাটাবেস সফলভাবে আমদানি করা হয়েছে",
+  "Security": "নিরাপত্তা",
+  "Require login": "লগইন প্রয়োজন",
+  "When ON, dashboard requires password. When OFF, access without login.": "চালু থাকলে, ড্যাশবোর্ড পাসওয়ার্ড প্রয়োজন। বন্ধ থাকলে, লগইন ছাড়াই অ্যাক্সেস করুন।",
+  "Current Password": "বর্তমান পাসওয়ার্ড",
+  "Enter current password": "বর্তমান পাসওয়ার্ড প্রবেশ করুন",
+  "New Password": "নতুন পাসওয়ার্ড",
+  "Enter new password": "নতুন পাসওয়ার্ড প্রবেশ করুন",
+  "Confirm New Password": "নতুন পাসওয়ার্ড নিশ্চিত করুন",
+  "Confirm new password": "নতুন পাসওয়ার্ড নিশ্চিত করুন",
+  "Update Password": "পাসওয়ার্ড আপডেট করুন",
+  "Set Password": "পাসওয়ার্ড সেট করুন",
+  "Password updated successfully": "পাসওয়ার্ড সফলভাবে আপডেট করা হয়েছে",
+  "Passwords do not match": "পাসওয়ার্ড মেলে না",
+  "Routing Strategy": "রাউটিং কৌশল",
+  "Round Robin": "রাউন্ড রবিন",
+  "Cycle through accounts to distribute load": "লোড বিতরণের জন্য অ্যাকাউন্টগুলির মধ্য দিয়ে চক্র",
+  "Sticky Limit": "স্টিকি সীমা",
+  "Calls per account before switching": "স্যুইচিংয়ের আগে অ্যাকাউন্ট প্রতি কল",
+  "Network": "নেটওয়ার্ক",
+  "Outbound Proxy": "আউটবাউন্ড প্রক্সি",
+  "Enable proxy for OAuth + provider outbound requests.": "OAuth + সরবরাহকারী আউটবাউন্ড অনুরোধের জন্য প্রক্সি সক্ষম করুন।",
+  "Proxy URL": "প্রক্সি URL",
+  "Leave empty to inherit existing env proxy (if any).": "বিদ্যমান env প্রক্সি উত্তরাধিকার করতে খালি রেখে দিন (থাকলে)।",
+  "No Proxy": "কোন প্রক্সি নেই",
+  "Comma-separated hostnames/domains to bypass the proxy.": "প্রক্সি বাইপাস করার জন্য কমা-পৃথক হোস্টনাম/ডোমেইন।",
+  "Test proxy URL": "প্রক্সি URL পরীক্ষা করুন",
+  "Proxy settings applied": "প্রক্সি সেটিংস প্রয়োগ করা হয়েছে",
+  "Proxy enabled": "প্রক্সি সক্ষম",
+  "Proxy disabled": "প্রক্সি অক্ষম",
+  "Proxy test OK": "প্রক্সি পরীক্ষা ঠিক আছে",
+  "Proxy test failed": "প্রক্সি পরীক্ষা ব্যর্থ",
+  "Please enter a Proxy URL to test": "পরীক্ষার জন্য দয়া করে একটি প্রক্সি URL প্রবেশ করুন",
+  "Observability": "পর্যবেক্ষণযোগ্যতা",
+  "Enable Observability": "পর্যবেক্ষণযোগ্যতা সক্ষম করুন",
+  "Turn request detail recording on/off globally": "অনুরোধ বিস্তারিত রেকর্ডিং বিশ্বব্যাপী চালু/বন্ধ করুন",
+  "Max Records": "সর্বাধিক রেকর্ড",
+  "Maximum request detail records to keep (older records are auto-deleted)": "রাখার জন্য সর্বাধিক অনুরোধ বিস্তারিত রেকর্ড (পুরানো রেকর্ড স্বয়ংক্রিয়ভাবে মুছে যায়)",
+  "Batch Size": "ব্যাচ আকার",
+  "Number of items to accumulate before writing to database (higher = better performance)": "ডাটাবেসে লেখার আগে জমা করার জন্য আইটেমের সংখ্যা (উচ্চতর = ভাল কর্মক্ষমতা)",
+  "Flush Interval (ms)": "ফ্লাশ ইন্টারভাল (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "বাফার ফ্লাশ করার আগে অপেক্ষা করার সর্বাধিক সময় (কম ট্রাফিক সময় ডেটা হারানো প্রতিরোধ করে)",
+  "Max JSON Size (KB)": "সর্বাধিক JSON আকার (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "ট্রাঙ্কেশনের আগে প্রতিটি JSON ফিল্ডের সর্বাধিক আকার (অনুরোধ/প্রতিক্রিয়া)",
+  "All data stored on your machine": "সমস্ত ডেটা আপনার মেশিনে সংরক্ষিত",
+  "MITM Server": "MITM সার্ভার",
+  "Running": "চলছে",
+  "Stopped": "বন্ধ",
+  "Cert": "সার্টিফিকেট",
+  "Server": "সার্ভার",
+  "Purpose:": "উদ্দেশ্য:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Antigravity IDE এবং GitHub Copilot ব্যবহার করুন → 9Router থেকে যেকোনো সরবরাহকারী/মডেলের সাথে",
+  "How it works:": "এটি কীভাবে কাজ করে:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE অনুরোধ → DNS কে localhost:443 তে রিডিরেক্ট করুন → MITM প্রক্সি ইন্টারসেপ্ট করে → 9Router → Antigravity/Copilot এ প্রতিক্রিয়া",
+  "No API keys — create one in Keys page": "কোন API কী নেই — Keys পৃষ্ঠায় একটি তৈরি করুন",
+  "sk_9router (default)": "sk_9router (ডিফল্ট)",
+  "Server started": "সার্ভার শুরু হয়েছে",
+  "Failed to start server": "সার্ভার শুরু করতে ব্যর্থ",
+  "Server stopped — all DNS cleared": "সার্ভার বন্ধ — সমস্ত DNS সাফ করা হয়েছে",
+  "Failed to stop server": "সার্ভার বন্ধ করতে ব্যর্থ",
+  "Sudo password is required": "Sudo পাসওয়ার্ড প্রয়োজন",
+  "Stop Server": "সার্ভার বন্ধ করুন",
+  "Start Server": "সার্ভার শুরু করুন",
+  "Enable DNS per tool below to activate interception": "ইন্টারসেপশন সক্রিয় করতে নীচে প্রতিটি সরঞ্জামের জন্য DNS সক্ষম করুন",
+  "Sudo Password Required": "Sudo পাসওয়ার্ড প্রয়োজন",
+  "Enter your sudo password to start/stop MITM server": "MITM সার্ভার শুরু/বন্ধ করতে আপনার sudo পাসওয়ার্ড প্রবেশ করুন",
+  "Sudo Password": "Sudo পাসওয়ার্ড",
+  "Click to add, click again to remove. Changes are saved automatically.": "যোগ করতে ক্লিক করুন, সরাতে আবার ক্লিক করুন। পরিবর্তনগুলি স্বয়ংক্রিয়ভাবে সংরক্ষিত হয়।",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ ঝুঁকি বিজ্ঞপ্তি: এই প্রদানকারী একটি সাবস্ক্রিপশন/OAuth সেশন ব্যবহার করে যা প্রক্সি/রাউটার ব্যবহারের জন্য আনুষ্ঠানিকভাবে লাইসেন্সপ্রাপ্ত নয়। অ্যাকাউন্ট সীমাবদ্ধ বা নিষিদ্ধ হতে পারে। নিজের ঝুঁকিতে ব্যবহার করুন।",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM স্থানীয় CA এর মাধ্যমে IDE টুলগুলির (Antigravity, GitHub Copilot, Kiro) HTTPS ট্রাফিক ইন্টারসেপ্ট করে আপনার প্রদানকারীদের কাছে অনুরোধ পুনঃনির্দেশ করতে। ToS লঙ্ঘন করতে পারে → অ্যাকাউন্ট নিষিদ্ধ ঝুঁকি। নিজের ঝুঁকিতে ব্যবহার করুন।",
+  "Endpoint is exposed without an API key.": "এপিআই কী ছাড়াই এন্ডপয়েন্ট উন্মুক্ত।"
+}
diff --git a/public/i18n/literals/cs.json b/public/i18n/literals/cs.json
new file mode 100644
index 0000000..ed0d991
--- /dev/null
+++ b/public/i18n/literals/cs.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Zrušit",
+  "Delete": "Smazat",
+  "Edit": "Upravit",
+  "Save": "Uložit",
+  "Close": "Zavřít",
+  "Add": "Přidat",
+  "Remove": "Odebrat",
+  "Settings": "Nastavení",
+  "Profile": "Profil",
+  "Dashboard": "Řídicí panel",
+  "Logout": "Odhlásit se",
+  "Login": "Přihlásit se",
+  "Providers": "Poskytovatelé",
+  "Usage": "Statistika",
+  "API Key": "Klíč API",
+  "Connected": "Připojeno",
+  "Disconnected": "Odpojeno",
+  "Active": "Aktivní",
+  "Inactive": "Neaktivní",
+  "Success": "Úspěch",
+  "Failed": "Selhalo",
+  "Error": "Chyba",
+  "Warning": "Upozornění",
+  "Info": "Informace",
+  "Loading": "Načítání",
+  "Search": "Hledání",
+  "Filter": "Filtr",
+  "Sort": "Řazení",
+  "Export": "Exportovat",
+  "Import": "Importovat",
+  "Refresh": "Aktualizovat",
+  "Back": "Zpět",
+  "Next": "Další",
+  "Previous": "Předchozí",
+  "Submit": "Odeslat",
+  "Confirm": "Potvrdit",
+  "Yes": "Ano",
+  "No": "Ne",
+  "OK": "OK",
+  "Apply": "Aplikovat",
+  "Reset": "Obnovit",
+  "Clear": "Vymazat",
+  "Select": "Vybrat",
+  "Upload": "Nahrát",
+  "Download": "Stáhnout",
+  "Copy": "Kopírovat",
+  "Paste": "Vložit",
+  "Cut": "Vyjmout",
+  "Undo": "Vrátit zpět",
+  "Redo": "Znovu",
+  "Name": "Název",
+  "Description": "Popis",
+  "Status": "Stav",
+  "Type": "Typ",
+  "Date": "Datum",
+  "Time": "Čas",
+  "Created": "Vytvořeno",
+  "Updated": "Aktualizováno",
+  "Actions": "Akce",
+  "Details": "Podrobnosti",
+  "View": "Zobrazit",
+  "New": "Nový",
+  "Total": "Celkem",
+  "Count": "Počet",
+  "Price": "Cena",
+  "Cost": "Náklady",
+  "Free": "Zdarma",
+  "Paid": "Placené",
+  "Enable": "Povolit",
+  "Disable": "Zakázat",
+  "Enabled": "Povoleno",
+  "Disabled": "Zakázáno",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "K dispozici",
+  "Unavailable": "Není k dispozici",
+  "Required": "Povinné",
+  "Optional": "Volitelné",
+  "Default": "Výchozí",
+  "Custom": "Vlastní",
+  "Advanced": "Pokročilé",
+  "Basic": "Základní",
+  "Help": "Pomoc",
+  "Support": "Podpora",
+  "Documentation": "Dokumentace",
+  "Version": "Verze",
+  "Language": "Jazyk",
+  "Theme": "Motiv",
+  "Light": "Světlý",
+  "Dark": "Tmavý",
+  "Auto": "Automaticky",
+  "Endpoint": "Koncový bod",
+  "Combos": "Kombinace",
+  "Quota Tracker": "Sledování kvót",
+  "MITM": "MITM",
+  "CLI Tools": "Nástroje CLI",
+  "Console Log": "Protokol konzole",
+  "System": "Systém",
+  "Debug": "Ladění",
+  "Shutdown": "Vypnutí",
+  "Close Proxy": "Zavřít proxy",
+  "Are you sure you want to close the proxy server?": "Opravdu chcete zavřít proxy server?",
+  "Server Disconnected": "Server odpojen",
+  "The proxy server has been stopped.": "Proxy server byl zastaven.",
+  "Reload Page": "Obnovit stránku",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Služba běží v terminálu. Tuto webovou stránku si můžete zavřít. Vypnutí zastaví službu.",
+  "Manage your AI provider connections": "Spravujte svá připojení poskytovatele AI",
+  "Model combos with fallback": "Kombinace modelů s zálohou",
+  "Monitor your API usage, token consumption, and request logs": "Monitorujte použití API, spotřebu tokenů a protokoly žádostí",
+  "Intercept CLI tool traffic and route through 9Router": "Zachycujte provoz nástrojů CLI a směrujte jej přes 9Router",
+  "Configure CLI tools": "Konfigurace nástrojů CLI",
+  "API endpoint configuration": "Konfigurace koncového bodu API",
+  "Manage your preferences": "Spravujte své preferences",
+  "Debug translation flow between formats": "Ladění toku překladu mezi formáty",
+  "Live server console output": "Výstup konzole serveru v přímém čase",
+  "Create model combos with fallback support": "Vytvářejte kombinace modelů s podporou zálohy",
+  "Local Mode": "Místní režim",
+  "Running on your machine": "Běží na vašem počítači",
+  "Database Location": "Umístění databáze",
+  "Download Backup": "Stáhnout zálohu",
+  "Import Backup": "Importovat zálohu",
+  "Database backup downloaded": "Záloha databáze stažena",
+  "Database imported successfully": "Databáze byla úspěšně importována",
+  "Security": "Bezpečnost",
+  "Require login": "Vyžadovat přihlášení",
+  "When ON, dashboard requires password. When OFF, access without login.": "Když je ZAPNUTO, řídicí panel vyžaduje heslo. Když je VYPNUTO, přístup bez přihlášení.",
+  "Current Password": "Aktuální heslo",
+  "Enter current password": "Zadejte aktuální heslo",
+  "New Password": "Nové heslo",
+  "Enter new password": "Zadejte nové heslo",
+  "Confirm New Password": "Potvrzení nového hesla",
+  "Confirm new password": "Potvrďte nové heslo",
+  "Update Password": "Aktualizovat heslo",
+  "Set Password": "Nastavit heslo",
+  "Password updated successfully": "Heslo bylo úspěšně aktualizováno",
+  "Passwords do not match": "Hesla se neshodují",
+  "Routing Strategy": "Strategie směrování",
+  "Round Robin": "Round Robin",
+  "Cycle through accounts to distribute load": "Procházejte účty pro distribuci zátěže",
+  "Sticky Limit": "Lepkavý limit",
+  "Calls per account before switching": "Volání na účet před přepnutím",
+  "Network": "Síť",
+  "Outbound Proxy": "Odchozí proxy",
+  "Enable proxy for OAuth + provider outbound requests.": "Povolte proxy pro OAuth + odchozí požadavky poskytovatele.",
+  "Proxy URL": "URL proxy",
+  "Leave empty to inherit existing env proxy (if any).": "Ponechte prázdné pro dědění existujícího env proxy (pokud existuje).",
+  "No Proxy": "Bez proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Čárkou oddělené názvy hostitelů/domény pro obejití proxy.",
+  "Test proxy URL": "Testovat URL proxy",
+  "Proxy settings applied": "Nastavení proxy aplikováno",
+  "Proxy enabled": "Proxy povolena",
+  "Proxy disabled": "Proxy zakázána",
+  "Proxy test OK": "Test proxy OK",
+  "Proxy test failed": "Test proxy se nezdařil",
+  "Please enter a Proxy URL to test": "Zadejte prosím URL proxy k testování",
+  "Observability": "Pozorovatelnost",
+  "Enable Observability": "Povolit pozorovatelnost",
+  "Turn request detail recording on/off globally": "Zapnutí/vypnutí záznamů podrobností požadavku globálně",
+  "Max Records": "Maximální počet záznamů",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Maximální počet záznamů o podrobnostech požadavku k uchování (starší záznamy se automaticky odstraňují)",
+  "Batch Size": "Velikost dávky",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Počet položek k hromadění před zápisem do databáze (vyšší = lepší výkon)",
+  "Flush Interval (ms)": "Interval vyprazdňování (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Maximální čas čekání před vyprazdněním vyrovnávací paměti (zabraňuje ztrátě dat při nízkém provozu)",
+  "Max JSON Size (KB)": "Maximální velikost JSON (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Maximální velikost každého pole JSON (požadavek/odpověď) před zkrácením",
+  "All data stored on your machine": "Všechna data jsou uložena na vašem počítači",
+  "MITM Server": "Server MITM",
+  "Running": "Běžící",
+  "Stopped": "Zastaveno",
+  "Cert": "Certifikát",
+  "Server": "Server",
+  "Purpose:": "Účel:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Použijte Antigravity IDE a GitHub Copilot → s JAKÝMKOLIV poskytovatelem/modelem z 9Router",
+  "How it works:": "Jak to funguje:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Požadavek Antigravity/Copilot IDE → Přesměrování DNS na localhost:443 → Proxy MITM zachycuje → 9Router → odpověď na Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Žádné klíče API — vytvořte jeden na stránce Klíče",
+  "sk_9router (default)": "sk_9router (výchozí)",
+  "Server started": "Server spuštěn",
+  "Failed to start server": "Spuštění serveru se nezdařilo",
+  "Server stopped — all DNS cleared": "Server zastaven — veškerý DNS vymazán",
+  "Failed to stop server": "Zastavení serveru se nezdařilo",
+  "Sudo password is required": "Je vyžadováno heslo sudo",
+  "Stop Server": "Zastavit server",
+  "Start Server": "Spustit server",
+  "Enable DNS per tool below to activate interception": "Povolte DNS pro každý nástroj níže a aktivujte zachycování",
+  "Sudo Password Required": "Je vyžadováno heslo Sudo",
+  "Enter your sudo password to start/stop MITM server": "Zadejte heslo sudo pro spuštění/zastavení serveru MITM",
+  "Sudo Password": "Heslo sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Kliknutím přidáte, dalším kliknutím odeberete. Změny se ukládají automaticky.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Upozornění na riziko: Tento poskytovatel používá předplatné/OAuth relaci, která není oficiálně licencována pro použití přes proxy/router. Účet může být omezen nebo zablokován. Používejte na vlastní riziko.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM zachytává HTTPS provoz IDE nástrojů (Antigravity, GitHub Copilot, Kiro) přes místní CA pro přesměrování požadavků na vaše poskytovatele. Může porušit ToS → riziko zákazu účtu. Používejte na vlastní riziko.",
+  "Endpoint is exposed without an API key.": "Koncový bod je vystaven bez API klíče."
+}
diff --git a/public/i18n/literals/da.json b/public/i18n/literals/da.json
new file mode 100644
index 0000000..c81bbe7
--- /dev/null
+++ b/public/i18n/literals/da.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Annuller",
+  "Delete": "Slet",
+  "Edit": "Rediger",
+  "Save": "Gem",
+  "Close": "Luk",
+  "Add": "Tilføj",
+  "Remove": "Fjern",
+  "Settings": "Indstillinger",
+  "Profile": "Profil",
+  "Dashboard": "Kontrolpanel",
+  "Logout": "Log ud",
+  "Login": "Log ind",
+  "Providers": "Udbydere",
+  "Usage": "Forbrugsstatistik",
+  "API Key": "API-nøgle",
+  "Connected": "Forbundet",
+  "Disconnected": "Afbrudt",
+  "Active": "Aktiv",
+  "Inactive": "Inaktiv",
+  "Success": "Succes",
+  "Failed": "Mislykket",
+  "Error": "Fejl",
+  "Warning": "Advarsel",
+  "Info": "Info",
+  "Loading": "Indlæser",
+  "Search": "Søg",
+  "Filter": "Filter",
+  "Sort": "Sorter",
+  "Export": "Eksporter",
+  "Import": "Importer",
+  "Refresh": "Opdater",
+  "Back": "Tilbage",
+  "Next": "Næste",
+  "Previous": "Forrige",
+  "Submit": "Indsend",
+  "Confirm": "Bekræft",
+  "Yes": "Ja",
+  "No": "Nej",
+  "OK": "OK",
+  "Apply": "Anvend",
+  "Reset": "Nulstil",
+  "Clear": "Ryd",
+  "Select": "Vælg",
+  "Upload": "Upload",
+  "Download": "Download",
+  "Copy": "Kopier",
+  "Paste": "Indsæt",
+  "Cut": "Klip",
+  "Undo": "Fortryd",
+  "Redo": "Gentag",
+  "Name": "Navn",
+  "Description": "Beskrivelse",
+  "Status": "Status",
+  "Type": "Type",
+  "Date": "Dato",
+  "Time": "Tid",
+  "Created": "Oprettet",
+  "Updated": "Opdateret",
+  "Actions": "Handlinger",
+  "Details": "Detaljer",
+  "View": "Vis",
+  "New": "Ny",
+  "Total": "Total",
+  "Count": "Antal",
+  "Price": "Pris",
+  "Cost": "Omkostning",
+  "Free": "Gratis",
+  "Paid": "Betalt",
+  "Enable": "Aktivér",
+  "Disable": "Deaktivér",
+  "Enabled": "Aktiveret",
+  "Disabled": "Deaktiveret",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Tilgængelig",
+  "Unavailable": "Ikke tilgængelig",
+  "Required": "Påkrævet",
+  "Optional": "Valgfrit",
+  "Default": "Standard",
+  "Custom": "Brugerdefineret",
+  "Advanced": "Avanceret",
+  "Basic": "Grundlæggende",
+  "Help": "Hjælp",
+  "Support": "Support",
+  "Documentation": "Dokumentation",
+  "Version": "Version",
+  "Language": "Sprog",
+  "Theme": "Tema",
+  "Light": "Lys",
+  "Dark": "Mørk",
+  "Auto": "Automatisk",
+  "Endpoint": "Slutpunkt",
+  "Combos": "Kombinationer",
+  "Quota Tracker": "Kvotetracker",
+  "MITM": "MITM",
+  "CLI Tools": "Værktøjer",
+  "Console Log": "Konsollog",
+  "System": "System",
+  "Debug": "Debug",
+  "Shutdown": "Luk af",
+  "Close Proxy": "Luk proxy",
+  "Are you sure you want to close the proxy server?": "Er du sikker på, at du vil lukke proxyserveren?",
+  "Server Disconnected": "Server afbrudt",
+  "The proxy server has been stopped.": "Proxyserveren er blevet stoppet.",
+  "Reload Page": "Genindlæs siden",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Tjenesten kører i terminalen. Du kan lukke denne webside. Aflukning stopper tjenesten.",
+  "Manage your AI provider connections": "Administrer dine AI-udbyderforbindelser",
+  "Model combos with fallback": "Modelkombinationer med fallback",
+  "Monitor your API usage, token consumption, and request logs": "Overvåg dit API-forbrug, tokenforbrugning og anmodningslogger",
+  "Intercept CLI tool traffic and route through 9Router": "Aflyt CLI-værktøj trafikk og rute gennem 9Router",
+  "Configure CLI tools": "Konfigurer CLI-værktøjer",
+  "API endpoint configuration": "API-slutpunktkonfiguration",
+  "Manage your preferences": "Administrer dine præferencer",
+  "Debug translation flow between formats": "Debug oversættelsesflow mellem formater",
+  "Live server console output": "Live serverkonsoloutput",
+  "Create model combos with fallback support": "Opret modelkombinationer med fallback-understøttelse",
+  "Local Mode": "Lokalt tilstand",
+  "Running on your machine": "Kørende på din maskine",
+  "Database Location": "Databaseplacering",
+  "Download Backup": "Download sikkerhedskopi",
+  "Import Backup": "Importer sikkerhedskopi",
+  "Database backup downloaded": "Databasesikkerhedskopi downloadet",
+  "Database imported successfully": "Database importeret med succes",
+  "Security": "Sikkerhed",
+  "Require login": "Kræv login",
+  "When ON, dashboard requires password. When OFF, access without login.": "Når TIL kræves adgangskode på kontrolpanelet. Når FRA tillades adgang uden login.",
+  "Current Password": "Nuværende adgangskode",
+  "Enter current password": "Indtast nuværende adgangskode",
+  "New Password": "Ny adgangskode",
+  "Enter new password": "Indtast ny adgangskode",
+  "Confirm New Password": "Bekræft ny adgangskode",
+  "Confirm new password": "Bekræft ny adgangskode",
+  "Update Password": "Opdater adgangskode",
+  "Set Password": "Indstil adgangskode",
+  "Password updated successfully": "Adgangskode opdateret med succes",
+  "Passwords do not match": "Adgangskoderne stemmer ikke overens",
+  "Routing Strategy": "Rutestrategi",
+  "Round Robin": "Rundetabel",
+  "Cycle through accounts to distribute load": "Cyklus gennem konti for at distribuere belastningen",
+  "Sticky Limit": "Klæbrig grænse",
+  "Calls per account before switching": "Opkald pr. konto før skift",
+  "Network": "Netværk",
+  "Outbound Proxy": "Udgående proxy",
+  "Enable proxy for OAuth + provider outbound requests.": "Aktivér proxy til OAuth + udbyder udgående anmodninger.",
+  "Proxy URL": "Proxy-URL",
+  "Leave empty to inherit existing env proxy (if any).": "Lad være tomt for at nedarve eksisterende env-proxy (hvis nogen).",
+  "No Proxy": "Ingen proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Kommaseparerede værtsnavne/domæner for at omgå proxyen.",
+  "Test proxy URL": "Test proxy-URL",
+  "Proxy settings applied": "Proxyindstillinger anvendt",
+  "Proxy enabled": "Proxy aktiveret",
+  "Proxy disabled": "Proxy deaktiveret",
+  "Proxy test OK": "Proxy-test OK",
+  "Proxy test failed": "Proxy-test mislykket",
+  "Please enter a Proxy URL to test": "Indtast en proxy-URL til test",
+  "Observability": "Observerbarhed",
+  "Enable Observability": "Aktivér observerbarhed",
+  "Turn request detail recording on/off globally": "Slå anmodningsdetaljeoptagelse til/fra globalt",
+  "Max Records": "Max-poster",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Maksimum anmodningsdetaljeposter at beholde (ældre poster bliver automatisk slettet)",
+  "Batch Size": "Batch-størrelse",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Antal elementer der skal akkumuleres før skrivning til database (højere = bedre ydeevne)",
+  "Flush Interval (ms)": "Flush-interval (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Maksimal ventetid før bufferrensing (forhindrer datatab ved lavt trafikk)",
+  "Max JSON Size (KB)": "Max JSON-størrelse (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Maksimal størrelse for hvert JSON-felt (anmodning/svar) før afkortning",
+  "All data stored on your machine": "Alle data lagret på din maskine",
+  "MITM Server": "MITM-server",
+  "Running": "Kørende",
+  "Stopped": "Stoppet",
+  "Cert": "Certifikat",
+  "Server": "Server",
+  "Purpose:": "Formål:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Brug Antigravity IDE & GitHub Copilot → med ENHVER udbyder/model fra 9Router",
+  "How it works:": "Sådan virker det:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE-anmodning → DNS-omdirigering til localhost:443 → MITM-proxy aflytter → 9Router → svar til Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Ingen API-nøgler — opret en på Keys-siden",
+  "sk_9router (default)": "sk_9router (standard)",
+  "Server started": "Server startet",
+  "Failed to start server": "Fejl ved start af server",
+  "Server stopped — all DNS cleared": "Server stoppet — alle DNS slettet",
+  "Failed to stop server": "Fejl ved stopning af server",
+  "Sudo password is required": "Sudo-adgangskode er påkrævet",
+  "Stop Server": "Stop server",
+  "Start Server": "Start server",
+  "Enable DNS per tool below to activate interception": "Aktivér DNS for hvert værktøj nedenfor for at aktivere aflytning",
+  "Sudo Password Required": "Sudo-adgangskode påkrævet",
+  "Enter your sudo password to start/stop MITM server": "Indtast din sudo-adgangskode for at starte/stoppe MITM-server",
+  "Sudo Password": "Sudo-adgangskode",
+  "Click to add, click again to remove. Changes are saved automatically.": "Klik for at tilføje, klik igen for at fjerne. Ændringer gemmes automatisk.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Risikomeddelelse: Denne udbyder bruger et abonnement/OAuth-session, der ikke er officielt licenseret til proxy/router-brug. Kontoen kan blive begrænset eller forbudt. Brug på eget ansvar.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM opfanger HTTPS-trafik fra IDE-værktøjer (Antigravity, GitHub Copilot, Kiro) via lokal CA for at omdirigere anmodninger til dine udbydere. Kan overtræde ToS → risiko for kontoforbud. Brug på eget ansvar.",
+  "Endpoint is exposed without an API key.": "Endpointet er eksponeret uden en API-nøgle."
+}
diff --git a/public/i18n/literals/de.json b/public/i18n/literals/de.json
new file mode 100644
index 0000000..57bf3ef
--- /dev/null
+++ b/public/i18n/literals/de.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Abbrechen",
+  "Delete": "Löschen",
+  "Edit": "Bearbeiten",
+  "Save": "Speichern",
+  "Close": "Schließen",
+  "Add": "Hinzufügen",
+  "Remove": "Entfernen",
+  "Settings": "Einstellungen",
+  "Profile": "Profil",
+  "Dashboard": "Dashboard",
+  "Logout": "Abmelden",
+  "Login": "Anmelden",
+  "Providers": "Anbieter",
+  "Usage": "Statistiken",
+  "API Key": "API-Schlüssel",
+  "Connected": "Verbunden",
+  "Disconnected": "Getrennt",
+  "Active": "Aktiv",
+  "Inactive": "Inaktiv",
+  "Success": "Erfolg",
+  "Failed": "Fehlgeschlagen",
+  "Error": "Fehler",
+  "Warning": "Warnung",
+  "Info": "Info",
+  "Loading": "Wird geladen",
+  "Search": "Suche",
+  "Filter": "Filtern",
+  "Sort": "Sortieren",
+  "Export": "Exportieren",
+  "Import": "Importieren",
+  "Refresh": "Aktualisieren",
+  "Back": "Zurück",
+  "Next": "Weiter",
+  "Previous": "Zurück",
+  "Submit": "Absenden",
+  "Confirm": "Bestätigen",
+  "Yes": "Ja",
+  "No": "Nein",
+  "OK": "OK",
+  "Apply": "Anwenden",
+  "Reset": "Zurücksetzen",
+  "Clear": "Löschen",
+  "Select": "Wählen",
+  "Upload": "Hochladen",
+  "Download": "Herunterladen",
+  "Copy": "Kopieren",
+  "Paste": "Einfügen",
+  "Cut": "Ausschneiden",
+  "Undo": "Rückgängig",
+  "Redo": "Wiederherstellen",
+  "Name": "Name",
+  "Description": "Beschreibung",
+  "Status": "Status",
+  "Type": "Typ",
+  "Date": "Datum",
+  "Time": "Uhrzeit",
+  "Created": "Erstellt",
+  "Updated": "Aktualisiert",
+  "Actions": "Aktionen",
+  "Details": "Details",
+  "View": "Anzeigen",
+  "New": "Neu",
+  "Total": "Gesamt",
+  "Count": "Anzahl",
+  "Price": "Preis",
+  "Cost": "Kosten",
+  "Free": "Kostenlos",
+  "Paid": "Bezahlt",
+  "Enable": "Aktivieren",
+  "Disable": "Deaktivieren",
+  "Enabled": "Aktiviert",
+  "Disabled": "Deaktiviert",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Verfügbar",
+  "Unavailable": "Nicht verfügbar",
+  "Required": "Erforderlich",
+  "Optional": "Optional",
+  "Default": "Standard",
+  "Custom": "Benutzerdefiniert",
+  "Advanced": "Erweitert",
+  "Basic": "Grundlagen",
+  "Help": "Hilfe",
+  "Support": "Unterstützung",
+  "Documentation": "Dokumentation",
+  "Version": "Version",
+  "Language": "Sprache",
+  "Theme": "Design",
+  "Light": "Hell",
+  "Dark": "Dunkel",
+  "Auto": "Automatisch",
+  "Endpoint": "Endpunkt",
+  "Combos": "Kombinationen",
+  "Quota Tracker": "Kontingenttracker",
+  "MITM": "MITM",
+  "CLI Tools": "CLI-Tools",
+  "Console Log": "Konsolenprotokoll",
+  "System": "System",
+  "Debug": "Debuggen",
+  "Shutdown": "Herunterfahren",
+  "Close Proxy": "Proxy schließen",
+  "Are you sure you want to close the proxy server?": "Möchten Sie den Proxy-Server wirklich schließen?",
+  "Server Disconnected": "Server getrennt",
+  "The proxy server has been stopped.": "Der Proxy-Server wurde gestoppt.",
+  "Reload Page": "Seite neu laden",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Der Service läuft im Terminal. Sie können diese Webseite schließen. Das Herunterfahren stoppt den Service.",
+  "Manage your AI provider connections": "Verwalten Sie Ihre KI-Anbieterverbindungen",
+  "Model combos with fallback": "Modellkombinationen mit Fallback",
+  "Monitor your API usage, token consumption, and request logs": "Überwachen Sie Ihre API-Nutzung, den Token-Verbrauch und die Anforderungsprotokolle",
+  "Intercept CLI tool traffic and route through 9Router": "CLI-Tool-Verkehr abfangen und über 9Router leiten",
+  "Configure CLI tools": "CLI-Tools konfigurieren",
+  "API endpoint configuration": "API-Endpunkt-Konfiguration",
+  "Manage your preferences": "Verwalten Sie Ihre Vorlieben",
+  "Debug translation flow between formats": "Übersetzungsfluss zwischen Formaten debuggen",
+  "Live server console output": "Ausgabe der Live-Server-Konsole",
+  "Create model combos with fallback support": "Erstellen Sie Modellkombinationen mit Fallback-Unterstützung",
+  "Local Mode": "Lokaler Modus",
+  "Running on your machine": "Wird auf Ihrem Computer ausgeführt",
+  "Database Location": "Datenbankort",
+  "Download Backup": "Sicherung herunterladen",
+  "Import Backup": "Sicherung importieren",
+  "Database backup downloaded": "Datenbanksicherung heruntergeladen",
+  "Database imported successfully": "Datenbank erfolgreich importiert",
+  "Security": "Sicherheit",
+  "Require login": "Login erforderlich",
+  "When ON, dashboard requires password. When OFF, access without login.": "Wenn AN, erfordert das Dashboard ein Passwort. Wenn AUS, Zugriff ohne Login.",
+  "Current Password": "Aktuelles Passwort",
+  "Enter current password": "Aktuelles Passwort eingeben",
+  "New Password": "Neues Passwort",
+  "Enter new password": "Neues Passwort eingeben",
+  "Confirm New Password": "Neues Passwort bestätigen",
+  "Confirm new password": "Neues Passwort bestätigen",
+  "Update Password": "Passwort aktualisieren",
+  "Set Password": "Passwort festlegen",
+  "Password updated successfully": "Passwort erfolgreich aktualisiert",
+  "Passwords do not match": "Passwörter stimmen nicht überein",
+  "Routing Strategy": "Routing-Strategie",
+  "Round Robin": "Round-Robin",
+  "Cycle through accounts to distribute load": "Konten durchlaufen, um die Last zu verteilen",
+  "Sticky Limit": "Klebrige Grenze",
+  "Calls per account before switching": "Anrufe pro Konto vor dem Wechsel",
+  "Network": "Netzwerk",
+  "Outbound Proxy": "Ausgehender Proxy",
+  "Enable proxy for OAuth + provider outbound requests.": "Aktivieren Sie den Proxy für OAuth + Anfragen der ausgehenden Anbieter.",
+  "Proxy URL": "Proxy-URL",
+  "Leave empty to inherit existing env proxy (if any).": "Lassen Sie leer, um einen vorhandenen Umgebungs-Proxy zu erben (falls vorhanden).",
+  "No Proxy": "Kein Proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Kommagetrennte Hostnamen/Domänen zum Umgehen des Proxys.",
+  "Test proxy URL": "Proxy-URL testen",
+  "Proxy settings applied": "Proxy-Einstellungen angewendet",
+  "Proxy enabled": "Proxy aktiviert",
+  "Proxy disabled": "Proxy deaktiviert",
+  "Proxy test OK": "Proxy-Test OK",
+  "Proxy test failed": "Proxy-Test fehlgeschlagen",
+  "Please enter a Proxy URL to test": "Bitte geben Sie eine Proxy-URL zum Testen ein",
+  "Observability": "Beobachtbarkeit",
+  "Enable Observability": "Beobachtbarkeit aktivieren",
+  "Turn request detail recording on/off globally": "Aufzeichnung von Anforderungsdetails global ein-/ausschalten",
+  "Max Records": "Maximale Datensätze",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Maximale Anzahl der zu speichernden Anforderungsdetaildatensätze (ältere Datensätze werden automatisch gelöscht)",
+  "Batch Size": "Batch-Größe",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Anzahl der Elemente, die sich ansammeln, bevor in die Datenbank geschrieben wird (höher = bessere Leistung)",
+  "Flush Interval (ms)": "Leerungsintervall (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Maximale Wartezeit vor dem Leeren des Puffers (verhindert Datenverlust bei niedrigem Datenverkehr)",
+  "Max JSON Size (KB)": "Maximale JSON-Größe (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Maximale Größe für jedes JSON-Feld (Anforderung/Antwort) vor dem Kürzen",
+  "All data stored on your machine": "Alle Daten auf Ihrem Computer gespeichert",
+  "MITM Server": "MITM-Server",
+  "Running": "Läuft",
+  "Stopped": "Gestoppt",
+  "Cert": "Zertifikat",
+  "Server": "Server",
+  "Purpose:": "Zweck:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Verwenden Sie Antigravity IDE und GitHub Copilot → mit JEDEM Anbieter/Modell von 9Router",
+  "How it works:": "So funktioniert es:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE-Anforderung → DNS-Umleitung auf localhost:443 → MITM-Proxy abfangen → 9Router → Antwort auf Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Keine API-Schlüssel — erstellen Sie einen auf der Seite Schlüssel",
+  "sk_9router (default)": "sk_9router (Standard)",
+  "Server started": "Server gestartet",
+  "Failed to start server": "Server konnte nicht gestartet werden",
+  "Server stopped — all DNS cleared": "Server gestoppt — alle DNS gelöscht",
+  "Failed to stop server": "Server konnte nicht gestoppt werden",
+  "Sudo password is required": "Sudo-Passwort erforderlich",
+  "Stop Server": "Server stoppen",
+  "Start Server": "Server starten",
+  "Enable DNS per tool below to activate interception": "Aktivieren Sie DNS für jedes Tool unten, um die Abfangung zu aktivieren",
+  "Sudo Password Required": "Sudo-Passwort erforderlich",
+  "Enter your sudo password to start/stop MITM server": "Geben Sie Ihr Sudo-Passwort ein, um den MITM-Server zu starten/stoppen",
+  "Sudo Password": "Sudo-Passwort",
+  "Click to add, click again to remove. Changes are saved automatically.": "Klicken zum Hinzufügen, erneut klicken zum Entfernen. Änderungen werden automatisch gespeichert.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Risikohinweis: Dieser Anbieter verwendet eine Abonnement-/OAuth-Sitzung, die nicht offiziell für die Proxy-/Router-Nutzung lizenziert ist. Das Konto kann eingeschränkt oder gesperrt werden. Nutzung auf eigene Gefahr.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM fängt HTTPS-Verkehr von IDE-Tools (Antigravity, GitHub Copilot, Kiro) über lokale CA ab, um Anfragen an Ihre Anbieter umzuleiten. Kann gegen ToS verstoßen → Risiko der Kontosperrung. Nutzung auf eigene Gefahr.",
+  "Endpoint is exposed without an API key.": "Der Endpunkt ist ohne API-Schlüssel offengelegt."
+}
diff --git a/public/i18n/literals/el.json b/public/i18n/literals/el.json
new file mode 100644
index 0000000..bfbf888
--- /dev/null
+++ b/public/i18n/literals/el.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Ακύρωση",
+  "Delete": "Διαγραφή",
+  "Edit": "Επεξεργασία",
+  "Save": "Αποθήκευση",
+  "Close": "Κλείσιμο",
+  "Add": "Προσθήκη",
+  "Remove": "Αφαίρεση",
+  "Settings": "Ρυθμίσεις",
+  "Profile": "Προφίλ",
+  "Dashboard": "Πίνακας ελέγχου",
+  "Logout": "Έξοδος",
+  "Login": "Σύνδεση",
+  "Providers": "Παρόχοι",
+  "Usage": "Στατιστικά χρήσης",
+  "API Key": "Κλειδί API",
+  "Connected": "Συνδεδεμένο",
+  "Disconnected": "Αποσυνδεδεμένο",
+  "Active": "Ενεργό",
+  "Inactive": "Ανενεργό",
+  "Success": "Επιτυχία",
+  "Failed": "Απέτυχε",
+  "Error": "Σφάλμα",
+  "Warning": "Προειδοποίηση",
+  "Info": "Πληροφορίες",
+  "Loading": "Φόρτωση",
+  "Search": "Αναζήτηση",
+  "Filter": "Φίλτρο",
+  "Sort": "Ταξινόμηση",
+  "Export": "Εξαγωγή",
+  "Import": "Εισαγωγή",
+  "Refresh": "Ανανέωση",
+  "Back": "Πίσω",
+  "Next": "Επόμενο",
+  "Previous": "Προηγούμενο",
+  "Submit": "Υποβολή",
+  "Confirm": "Επιβεβαίωση",
+  "Yes": "Ναι",
+  "No": "Όχι",
+  "OK": "ΟΚ",
+  "Apply": "Εφαρμογή",
+  "Reset": "Επαναφορά",
+  "Clear": "Εκκαθάριση",
+  "Select": "Επιλογή",
+  "Upload": "Μεταφόρτωση",
+  "Download": "Λήψη",
+  "Copy": "Αντιγραφή",
+  "Paste": "Επικόλληση",
+  "Cut": "Αποκοπή",
+  "Undo": "Αναίρεση",
+  "Redo": "Επανάληψη",
+  "Name": "Όνομα",
+  "Description": "Περιγραφή",
+  "Status": "Κατάσταση",
+  "Type": "Τύπος",
+  "Date": "Ημερομηνία",
+  "Time": "Ώρα",
+  "Created": "Δημιουργήθηκε",
+  "Updated": "Ενημερώθηκε",
+  "Actions": "Ενέργειες",
+  "Details": "Λεπτομέρειες",
+  "View": "Προβολή",
+  "New": "Νέο",
+  "Total": "Σύνολο",
+  "Count": "Μέτρηση",
+  "Price": "Τιμή",
+  "Cost": "Κόστος",
+  "Free": "Δωρεάν",
+  "Paid": "Πληρωμένο",
+  "Enable": "Ενεργοποίηση",
+  "Disable": "Απενεργοποίηση",
+  "Enabled": "Ενεργοποιημένο",
+  "Disabled": "Απενεργοποιημένο",
+  "Online": "Σε σύνδεση",
+  "Offline": "Χωρίς σύνδεση",
+  "Available": "Διαθέσιμο",
+  "Unavailable": "Μη διαθέσιμο",
+  "Required": "Απαιτούμενο",
+  "Optional": "Προαιρετικό",
+  "Default": "Προεπιλεγμένο",
+  "Custom": "Προσαρμοσμένο",
+  "Advanced": "Προχωρημένο",
+  "Basic": "Βασικό",
+  "Help": "Βοήθεια",
+  "Support": "Υποστήριξη",
+  "Documentation": "Τεκμηρίωση",
+  "Version": "Έκδοση",
+  "Language": "Γλώσσα",
+  "Theme": "Θέμα",
+  "Light": "Ανοιχτό",
+  "Dark": "Σκοτεινό",
+  "Auto": "Αυτόματο",
+  "Endpoint": "Τελικό σημείο",
+  "Combos": "Συνδυασμοί",
+  "Quota Tracker": "Παρακολούθηση ποσόστωσης",
+  "MITM": "MITM",
+  "CLI Tools": "Εργαλεία",
+  "Console Log": "Αρχείο καταγραφής κονσόλας",
+  "System": "Σύστημα",
+  "Debug": "Αποσφαλμάτωση",
+  "Shutdown": "Τερματισμός",
+  "Close Proxy": "Κλείσιμο διακομιστή μεσολάβησης",
+  "Are you sure you want to close the proxy server?": "Είστε σίγουρος ότι θέλετε να κλείσετε τον διακομιστή μεσολάβησης;",
+  "Server Disconnected": "Διακομιστής αποσυνδεδεμένος",
+  "The proxy server has been stopped.": "Ο διακομιστής μεσολάβησης έχει σταματήσει.",
+  "Reload Page": "Επαναφόρτωση σελίδας",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Η υπηρεσία εκτελείται στο τερματικό. Μπορείτε να κλείσετε αυτή τη σελίδα ιστού. Ο τερματισμός θα σταματήσει την υπηρεσία.",
+  "Manage your AI provider connections": "Διαχειριστείτε τις συνδέσεις του παρόχου AI σας",
+  "Model combos with fallback": "Συνδυασμοί μοντέλων με αποπροσπέλαση",
+  "Monitor your API usage, token consumption, and request logs": "Παρακολουθήστε τη χρήση API, την κατανάλωση token και τα αρχεία καταγραφής αιτημάτων",
+  "Intercept CLI tool traffic and route through 9Router": "Αναχαίτηση κίνησης εργαλείου CLI και δρομολόγηση μέσω 9Router",
+  "Configure CLI tools": "Ρύθμιση εργαλείων CLI",
+  "API endpoint configuration": "Διαμόρφωση τελικού σημείου API",
+  "Manage your preferences": "Διαχείριση προτιμήσεών σας",
+  "Debug translation flow between formats": "Αποσφαλμάτωση ροής μετάφρασης μεταξύ μορφών",
+  "Live server console output": "Έξοδος κονσόλας διακομιστή σε πραγματικό χρόνο",
+  "Create model combos with fallback support": "Δημιουργήστε συνδυασμούς μοντέλων με υποστήριξη αποπροσπέλασης",
+  "Local Mode": "Τοπική λειτουργία",
+  "Running on your machine": "Εκτελείται στον υπολογιστή σας",
+  "Database Location": "Τοποθεσία βάσης δεδομένων",
+  "Download Backup": "Λήψη ασφαλείας",
+  "Import Backup": "Εισαγωγή ασφαλείας",
+  "Database backup downloaded": "Ασφάλεια βάσης δεδομένων λήφθηκε",
+  "Database imported successfully": "Η βάση δεδομένων εισήχθη με επιτυχία",
+  "Security": "Ασφάλεια",
+  "Require login": "Απαιτείται σύνδεση",
+  "When ON, dashboard requires password. When OFF, access without login.": "Όταν είναι ΕΝ, ο πίνακας ελέγχου απαιτεί κωδικό πρόσβασης. Όταν είναι ΑΠΕΝΕΡΓΟΠΟΙΗΜΕΝΟ, πρόσβαση χωρίς σύνδεση.",
+  "Current Password": "Τρέχων κωδικός πρόσβασης",
+  "Enter current password": "Εισαγάγετε τον τρέχοντα κωδικό πρόσβασης",
+  "New Password": "Νέος κωδικός πρόσβασης",
+  "Enter new password": "Εισαγάγετε τον νέο κωδικό πρόσβασης",
+  "Confirm New Password": "Επιβεβαίωση νέου κωδικού πρόσβασης",
+  "Confirm new password": "Επιβεβαίωση νέου κωδικού πρόσβασης",
+  "Update Password": "Ενημέρωση κωδικού πρόσβασης",
+  "Set Password": "Ορισμός κωδικού πρόσβασης",
+  "Password updated successfully": "Ο κωδικός πρόσβασης ενημερώθηκε με επιτυχία",
+  "Passwords do not match": "Οι κωδικοί πρόσβασης δεν ταιριάζουν",
+  "Routing Strategy": "Στρατηγική δρομολόγησης",
+  "Round Robin": "Κυκλική δρομολόγηση",
+  "Cycle through accounts to distribute load": "Κύκλος μέσω λογαριασμών για κατανομή φορτίου",
+  "Sticky Limit": "Περιορισμός κόλλησης",
+  "Calls per account before switching": "Κλήσεις ανά λογαριασμό πριν από την εναλλαγή",
+  "Network": "Δίκτυο",
+  "Outbound Proxy": "Εξερχόμενος διακομιστής μεσολάβησης",
+  "Enable proxy for OAuth + provider outbound requests.": "Ενεργοποιήστε τον διακομιστή μεσολάβησης για αιτήματα εξόδου OAuth + παρόχου.",
+  "Proxy URL": "URL διακομιστή μεσολάβησης",
+  "Leave empty to inherit existing env proxy (if any).": "Αφήστε κενό για να κληρονομήσετε υπάρχοντα env proxy (εάν υπάρχει).",
+  "No Proxy": "Χωρίς διακομιστή μεσολάβησης",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Ονόματα κεντρικών υπολογιστών/τομείς χωρισμένοι με κόμμα για να παραστούν τον διακομιστή μεσολάβησης.",
+  "Test proxy URL": "Δοκιμή URL διακομιστή μεσολάβησης",
+  "Proxy settings applied": "Ρυθμίσεις διακομιστή μεσολάβησης εφαρμόστηκαν",
+  "Proxy enabled": "Διακομιστής μεσολάβησης ενεργοποιημένος",
+  "Proxy disabled": "Διακομιστής μεσολάβησης απενεργοποιημένος",
+  "Proxy test OK": "Δοκιμή διακομιστή μεσολάβησης OK",
+  "Proxy test failed": "Η δοκιμή διακομιστή μεσολάβησης απέτυχε",
+  "Please enter a Proxy URL to test": "Παρακαλώ εισάγετε ένα URL διακομιστή μεσολάβησης για δοκιμή",
+  "Observability": "Δυνατότητα παρατήρησης",
+  "Enable Observability": "Ενεργοποίηση δυνατότητας παρατήρησης",
+  "Turn request detail recording on/off globally": "Ενεργοποιήστε/απενεργοποιήστε την καταγραφή λεπτομερειών αιτήματος σε παγκόσμιο επίπεδο",
+  "Max Records": "Μέγιστα αρχεία",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Μέγιστα αρχεία λεπτομερειών αιτήματος για διατήρηση (τα παλαιότερα αρχεία διαγράφονται αυτόματα)",
+  "Batch Size": "Μέγεθος δέσμης",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Αριθμός στοιχείων που πρέπει να συσσωρευθούν πριν από τη σύνταξη στη βάση δεδομένων (υψηλότερο = καλύτερη απόδοση)",
+  "Flush Interval (ms)": "Διάστημα ξεπλύματος (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Μέγιστος χρόνος αναμονής πριν από το ξέπλυμα του buffer (αποτρέπει την απώλεια δεδομένων κατά την χαμηλή κίνηση)",
+  "Max JSON Size (KB)": "Μέγιστο μέγεθος JSON (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Μέγιστο μέγεθος για κάθε πεδίο JSON (αίτημα/απάντηση) πριν από την περικοπή",
+  "All data stored on your machine": "Όλα τα δεδομένα αποθηκεύονται στον υπολογιστή σας",
+  "MITM Server": "Διακομιστής MITM",
+  "Running": "Εκτελείται",
+  "Stopped": "Διακοπή",
+  "Cert": "Πιστοποιητικό",
+  "Server": "Διακομιστής",
+  "Purpose:": "Σκοπός:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Χρησιμοποιήστε Antigravity IDE & GitHub Copilot → με ΟΠΟΙΟΝΔΗΠΟΤΕ πάροχο/μοντέλο από 9Router",
+  "How it works:": "Πώς λειτουργεί:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Αίτημα Antigravity/Copilot IDE → Ανακατεύθυνση DNS στο localhost:443 → Ο διακομιστής μεσολάβησης MITM παρεμβαίνει → 9Router → απάντηση στο Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Δεν υπάρχουν κλειδιά API — δημιουργήστε ένα στη σελίδα Keys",
+  "sk_9router (default)": "sk_9router (προεπιλεγμένο)",
+  "Server started": "Ο διακομιστής ξεκίνησε",
+  "Failed to start server": "Αποτυχία εκκίνησης διακομιστή",
+  "Server stopped — all DNS cleared": "Ο διακομιστής σταμάτησε — όλα τα DNS διαγράφηκαν",
+  "Failed to stop server": "Αποτυχία διακοπής διακομιστή",
+  "Sudo password is required": "Απαιτείται κωδικός πρόσβασης sudo",
+  "Stop Server": "Διακοπή διακομιστή",
+  "Start Server": "Διακομιστή ξεκινήματος",
+  "Enable DNS per tool below to activate interception": "Ενεργοποιήστε το DNS για κάθε εργαλείο παρακάτω για ενεργοποίηση παρεμβολής",
+  "Sudo Password Required": "Απαιτείται κωδικός πρόσβασης Sudo",
+  "Enter your sudo password to start/stop MITM server": "Εισαγάγετε τον κωδικό πρόσβασης sudo για να ξεκινήσετε/διακόψετε τον διακομιστή MITM",
+  "Sudo Password": "Κωδικός πρόσβασης Sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Κάντε κλικ για προσθήκη, κάντε ξανά κλικ για αφαίρεση. Οι αλλαγές αποθηκεύονται αυτόματα.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Ειδοποίηση κινδύνου: Αυτός ο πάροχος χρησιμοποιεί συνδρομή/συνεδρία OAuth που δεν έχει επίσημη άδεια για χρήση μέσω proxy/router. Ο λογαριασμός ενδέχεται να περιοριστεί ή να αποκλειστεί. Χρήση με δική σας ευθύνη.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ Το MITM υποκλέπτει την κίνηση HTTPS των εργαλείων IDE (Antigravity, GitHub Copilot, Kiro) μέσω τοπικού CA για ανακατεύθυνση αιτημάτων στους παρόχους σας. Μπορεί να παραβιάσει τους ToS → κίνδυνος αποκλεισμού λογαριασμού. Χρήση με δική σας ευθύνη.",
+  "Endpoint is exposed without an API key.": "Το τελικό σημείο είναι εκτεθειμένο χωρίς κλειδί API."
+}
diff --git a/public/i18n/literals/es.json b/public/i18n/literals/es.json
new file mode 100644
index 0000000..69d71e8
--- /dev/null
+++ b/public/i18n/literals/es.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Cancelar",
+  "Delete": "Eliminar",
+  "Edit": "Editar",
+  "Save": "Guardar",
+  "Close": "Cerrar",
+  "Add": "Añadir",
+  "Remove": "Quitar",
+  "Settings": "Configuración",
+  "Profile": "Perfil",
+  "Dashboard": "Panel de control",
+  "Logout": "Cerrar sesión",
+  "Login": "Iniciar sesión",
+  "Providers": "Proveedores",
+  "Usage": "Estadísticas",
+  "API Key": "Clave API",
+  "Connected": "Conectado",
+  "Disconnected": "Desconectado",
+  "Active": "Activo",
+  "Inactive": "Inactivo",
+  "Success": "Éxito",
+  "Failed": "Fallido",
+  "Error": "Error",
+  "Warning": "Advertencia",
+  "Info": "Información",
+  "Loading": "Cargando",
+  "Search": "Buscar",
+  "Filter": "Filtrar",
+  "Sort": "Ordenar",
+  "Export": "Exportar",
+  "Import": "Importar",
+  "Refresh": "Actualizar",
+  "Back": "Atrás",
+  "Next": "Siguiente",
+  "Previous": "Anterior",
+  "Submit": "Enviar",
+  "Confirm": "Confirmar",
+  "Yes": "Sí",
+  "No": "No",
+  "OK": "OK",
+  "Apply": "Aplicar",
+  "Reset": "Restablecer",
+  "Clear": "Limpiar",
+  "Select": "Seleccionar",
+  "Upload": "Cargar",
+  "Download": "Descargar",
+  "Copy": "Copiar",
+  "Paste": "Pegar",
+  "Cut": "Cortar",
+  "Undo": "Deshacer",
+  "Redo": "Rehacer",
+  "Name": "Nombre",
+  "Description": "Descripción",
+  "Status": "Estado",
+  "Type": "Tipo",
+  "Date": "Fecha",
+  "Time": "Hora",
+  "Created": "Creado",
+  "Updated": "Actualizado",
+  "Actions": "Acciones",
+  "Details": "Detalles",
+  "View": "Ver",
+  "New": "Nuevo",
+  "Total": "Total",
+  "Count": "Cantidad",
+  "Price": "Precio",
+  "Cost": "Costo",
+  "Free": "Gratuito",
+  "Paid": "Pagado",
+  "Enable": "Habilitar",
+  "Disable": "Deshabilitar",
+  "Enabled": "Habilitado",
+  "Disabled": "Deshabilitado",
+  "Online": "En línea",
+  "Offline": "Desconectado",
+  "Available": "Disponible",
+  "Unavailable": "No disponible",
+  "Required": "Requerido",
+  "Optional": "Opcional",
+  "Default": "Predeterminado",
+  "Custom": "Personalizado",
+  "Advanced": "Avanzado",
+  "Basic": "Básico",
+  "Help": "Ayuda",
+  "Support": "Soporte",
+  "Documentation": "Documentación",
+  "Version": "Versión",
+  "Language": "Idioma",
+  "Theme": "Tema",
+  "Light": "Claro",
+  "Dark": "Oscuro",
+  "Auto": "Automático",
+  "Endpoint": "Punto final",
+  "Combos": "Combinaciones",
+  "Quota Tracker": "Rastreador de cuota",
+  "MITM": "MITM",
+  "CLI Tools": "Herramientas CLI",
+  "Console Log": "Registro de consola",
+  "System": "Sistema",
+  "Debug": "Depuración",
+  "Shutdown": "Apagar",
+  "Close Proxy": "Cerrar proxy",
+  "Are you sure you want to close the proxy server?": "¿Está seguro de que desea cerrar el servidor proxy?",
+  "Server Disconnected": "Servidor desconectado",
+  "The proxy server has been stopped.": "El servidor proxy se ha detenido.",
+  "Reload Page": "Recargar página",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "El servicio se está ejecutando en la terminal. Puede cerrar esta página web. El apagado detendrá el servicio.",
+  "Manage your AI provider connections": "Administre sus conexiones de proveedor de IA",
+  "Model combos with fallback": "Combinaciones de modelos con respaldo",
+  "Monitor your API usage, token consumption, and request logs": "Monitoree su uso de API, consumo de tokens y registros de solicitudes",
+  "Intercept CLI tool traffic and route through 9Router": "Interceptar el tráfico de herramientas CLI y enrutar a través de 9Router",
+  "Configure CLI tools": "Configurar herramientas CLI",
+  "API endpoint configuration": "Configuración del punto final de API",
+  "Manage your preferences": "Administrar sus preferencias",
+  "Debug translation flow between formats": "Depurar el flujo de traducción entre formatos",
+  "Live server console output": "Salida de consola del servidor en vivo",
+  "Create model combos with fallback support": "Crear combinaciones de modelos con soporte de respaldo",
+  "Local Mode": "Modo local",
+  "Running on your machine": "En ejecución en su máquina",
+  "Database Location": "Ubicación de la base de datos",
+  "Download Backup": "Descargar respaldo",
+  "Import Backup": "Importar respaldo",
+  "Database backup downloaded": "Respaldo de la base de datos descargado",
+  "Database imported successfully": "Base de datos importada correctamente",
+  "Security": "Seguridad",
+  "Require login": "Requerir inicio de sesión",
+  "When ON, dashboard requires password. When OFF, access without login.": "Cuando está ACTIVADO, el panel requiere contraseña. Cuando está DESACTIVADO, acceso sin iniciar sesión.",
+  "Current Password": "Contraseña actual",
+  "Enter current password": "Ingrese la contraseña actual",
+  "New Password": "Nueva contraseña",
+  "Enter new password": "Ingrese la nueva contraseña",
+  "Confirm New Password": "Confirmar nueva contraseña",
+  "Confirm new password": "Confirme la nueva contraseña",
+  "Update Password": "Actualizar contraseña",
+  "Set Password": "Establecer contraseña",
+  "Password updated successfully": "Contraseña actualizada correctamente",
+  "Passwords do not match": "Las contraseñas no coinciden",
+  "Routing Strategy": "Estrategia de enrutamiento",
+  "Round Robin": "Round Robin",
+  "Cycle through accounts to distribute load": "Ciclo a través de cuentas para distribuir la carga",
+  "Sticky Limit": "Límite pegajoso",
+  "Calls per account before switching": "Llamadas por cuenta antes de cambiar",
+  "Network": "Red",
+  "Outbound Proxy": "Proxy de salida",
+  "Enable proxy for OAuth + provider outbound requests.": "Habilite el proxy para OAuth + solicitudes de salida del proveedor.",
+  "Proxy URL": "URL del proxy",
+  "Leave empty to inherit existing env proxy (if any).": "Deje en blanco para heredar el proxy env existente (si lo hay).",
+  "No Proxy": "Sin proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Nombres de host/dominios separados por comas para omitir el proxy.",
+  "Test proxy URL": "Prueba URL del proxy",
+  "Proxy settings applied": "Configuración de proxy aplicada",
+  "Proxy enabled": "Proxy habilitado",
+  "Proxy disabled": "Proxy deshabilitado",
+  "Proxy test OK": "Prueba de proxy OK",
+  "Proxy test failed": "Falha en la prueba de proxy",
+  "Please enter a Proxy URL to test": "Por favor ingrese una URL de proxy para probar",
+  "Observability": "Observabilidad",
+  "Enable Observability": "Habilitar observabilidad",
+  "Turn request detail recording on/off globally": "Activar/desactivar globalmente el registro de detalles de solicitud",
+  "Max Records": "Número máximo de registros",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Número máximo de registros de detalle de solicitud a mantener (los registros más antiguos se eliminan automáticamente)",
+  "Batch Size": "Tamaño del lote",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Número de elementos a acumular antes de escribir en la base de datos (más alto = mejor rendimiento)",
+  "Flush Interval (ms)": "Intervalo de vaciado (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Tiempo máximo de espera antes de vaciar el búfer (evita pérdida de datos durante tráfico bajo)",
+  "Max JSON Size (KB)": "Tamaño máximo de JSON (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Tamaño máximo para cada campo JSON (solicitud/respuesta) antes del truncamiento",
+  "All data stored on your machine": "Todos los datos almacenados en su máquina",
+  "MITM Server": "Servidor MITM",
+  "Running": "En ejecución",
+  "Stopped": "Detenido",
+  "Cert": "Certificado",
+  "Server": "Servidor",
+  "Purpose:": "Propósito:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Use Antigravity IDE y GitHub Copilot → con CUALQUIER proveedor/modelo de 9Router",
+  "How it works:": "Cómo funciona:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Solicitud de Antigravity/Copilot IDE → Redireccionamiento DNS a localhost:443 → El proxy MITM intercepta → 9Router → respuesta a Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Sin claves API — cree una en la página Claves",
+  "sk_9router (default)": "sk_9router (predeterminado)",
+  "Server started": "Servidor iniciado",
+  "Failed to start server": "Error al iniciar el servidor",
+  "Server stopped — all DNS cleared": "Servidor detenido — todo DNS borrado",
+  "Failed to stop server": "Error al detener el servidor",
+  "Sudo password is required": "Se requiere contraseña de sudo",
+  "Stop Server": "Detener servidor",
+  "Start Server": "Iniciar servidor",
+  "Enable DNS per tool below to activate interception": "Habilite DNS para cada herramienta a continuación para activar la intercepción",
+  "Sudo Password Required": "Contraseña de Sudo requerida",
+  "Enter your sudo password to start/stop MITM server": "Ingrese su contraseña de sudo para iniciar/detener el servidor MITM",
+  "Sudo Password": "Contraseña de sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Haz clic para agregar, haz clic de nuevo para eliminar. Los cambios se guardan automáticamente.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Aviso de Riesgo: Este proveedor usa una sesión de suscripción/OAuth no licenciada oficialmente para uso de proxy/router. La cuenta puede ser restringida o baneada. Use bajo su propio riesgo.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM intercepta el tráfico HTTPS de herramientas IDE (Antigravity, GitHub Copilot, Kiro) mediante CA local para redirigir solicitudes a sus proveedores. Puede violar los ToS → riesgo de baneo de cuenta. Use bajo su propio riesgo.",
+  "Endpoint is exposed without an API key.": "El endpoint está expuesto sin una clave de API."
+}
diff --git a/public/i18n/literals/fa.json b/public/i18n/literals/fa.json
new file mode 100644
index 0000000..770518a
--- /dev/null
+++ b/public/i18n/literals/fa.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "لغو",
+  "Delete": "حذف",
+  "Edit": "ویرایش",
+  "Save": "ذخیره",
+  "Close": "بستن",
+  "Add": "افزودن",
+  "Remove": "حذف",
+  "Settings": "تنظیمات",
+  "Profile": "پروفایل",
+  "Dashboard": "پیش‌خوان",
+  "Logout": "خروج",
+  "Login": "ورود",
+  "Providers": "ارائه‌دهندگان",
+  "Usage": "آمار مصرف",
+  "API Key": "کلید API",
+  "Connected": "متصل",
+  "Disconnected": "قطع شده",
+  "Active": "فعال",
+  "Inactive": "غیرفعال",
+  "Success": "موفق",
+  "Failed": "ناموفق",
+  "Error": "خطا",
+  "Warning": "هشدار",
+  "Info": "اطلاعات",
+  "Loading": "در حال بارگذاری",
+  "Search": "جستجو",
+  "Filter": "فیلتر",
+  "Sort": "مرتب‌سازی",
+  "Export": "خروجی",
+  "Import": "ورودی",
+  "Refresh": "تازه‌سازی",
+  "Back": "بازگشت",
+  "Next": "بعدی",
+  "Previous": "قبلی",
+  "Submit": "ارسال",
+  "Confirm": "تأیید",
+  "Yes": "بله",
+  "No": "خیر",
+  "OK": "تأیید",
+  "Apply": "اعمال",
+  "Reset": "بازنشانی",
+  "Clear": "پاک کردن",
+  "Select": "انتخاب",
+  "Upload": "آپلود",
+  "Download": "دانلود",
+  "Copy": "کپی",
+  "Paste": "چسباندن",
+  "Cut": "برش",
+  "Undo": "بازگشت",
+  "Redo": "انجام مجدد",
+  "Name": "نام",
+  "Description": "توضیحات",
+  "Status": "وضعیت",
+  "Type": "نوع",
+  "Date": "تاریخ",
+  "Time": "زمان",
+  "Created": "ایجاد شده",
+  "Updated": "بروزرسانی شده",
+  "Actions": "عملیات",
+  "Details": "جزئیات",
+  "View": "مشاهده",
+  "New": "جدید",
+  "Total": "مجموع",
+  "Count": "تعداد",
+  "Price": "قیمت",
+  "Cost": "هزینه",
+  "Free": "رایگان",
+  "Paid": "پولی",
+  "Enable": "فعال‌سازی",
+  "Disable": "غیرفعال‌سازی",
+  "Enabled": "فعال شده",
+  "Disabled": "غیرفعال شده",
+  "Online": "آنلاین",
+  "Offline": "آفلاین",
+  "Available": "موجود",
+  "Unavailable": "ناموجود",
+  "Required": "الزامی",
+  "Optional": "اختیاری",
+  "Default": "پیش‌فرض",
+  "Custom": "سفارشی",
+  "Advanced": "پیشرفته",
+  "Basic": "ساده",
+  "Help": "راهنما",
+  "Support": "پشتیبانی",
+  "Documentation": "مستندات",
+  "Version": "نسخه",
+  "Language": "زبان",
+  "Theme": "پوسته",
+  "Light": "روشن",
+  "Dark": "تاریک",
+  "Auto": "خودکار",
+  "Endpoint": "اندپوینت",
+  "Combos": "ترکیبات",
+  "Quota Tracker": "پیگیر سهمیه",
+  "MITM": "MITM",
+  "CLI Tools": "ابزارهای CLI",
+  "Console Log": "لاگ کنسول",
+  "System": "سیستم",
+  "Debug": "اشکال‌زدایی",
+  "Shutdown": "خاموش کردن",
+  "Close Proxy": "بستن پروکسی",
+  "Are you sure you want to close the proxy server?": "آیا مطمئن هستید که می‌خواهید سرور پروکسی را ببندید؟",
+  "Server Disconnected": "سرور قطع شد",
+  "The proxy server has been stopped.": "سرور پروکسی متوقف شده است.",
+  "Reload Page": "بارگذاری مجدد صفحه",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "سرویس در ترمینال در حال اجراست. می‌توانید این صفحه وب را ببندید. خاموش کردن، سرویس را متوقف می‌کند.",
+  "Manage your AI provider connections": "مدیریت اتصالات ارائه‌دهندگان هوش مصنوعی خود",
+  "Model combos with fallback": "ترکیبات مدل با پشتیبان جایگزین",
+  "Monitor your API usage, token consumption, and request logs": "نظارت بر مصرف API، مصرف توکن و لاگ درخواست‌ها",
+  "Intercept CLI tool traffic and route through 9Router": "拦截 ترافیک ابزار CLI و مسیردهی از طریق 9Router",
+  "Configure CLI tools": "پیکربندی ابزارهای CLI",
+  "API endpoint configuration": "پیکربندی نقطه پایانی API",
+  "Manage your preferences": "مدیریت تنظیمات شخصی",
+  "Debug translation flow between formats": "اشکال‌زدایی جریان ترجمه بین فرمت‌ها",
+  "Live server console output": "خروجی کنسول سرور زنده",
+  "Create model combos with fallback support": "ایجاد ترکیبات مدل با پشتیبانی از پشتیبان جایگزین",
+  "Local Mode": "حالت محلی",
+  "Running on your machine": "در حال اجرا روی دستگاه شما",
+  "Database Location": "مکان پایگاه داده",
+  "Download Backup": "دانلود پشتیبان",
+  "Import Backup": "وارد کردن پشتیبان",
+  "Database backup downloaded": "پشتیبان پایگاه داده دانلود شد",
+  "Database imported successfully": "پایگاه داده با موفقیت وارد شد",
+  "Security": "امنیت",
+  "Require login": "نیاز به ورود",
+  "When ON, dashboard requires password. When OFF, access without login.": "در حالت روشن، داشبورد به رمز عبور نیاز دارد. در حالت خاموش، دسترسی بدون نیاز به ورود.",
+  "Current Password": "رمز عبور فعلی",
+  "Enter current password": "رمز عبور فعلی را وارد کنید",
+  "New Password": "رمز عبور جدید",
+  "Enter new password": "رمز عبور جدید را وارد کنید",
+  "Confirm New Password": "تأیید رمز عبور جدید",
+  "Confirm new password": "تأیید رمز عبور جدید",
+  "Update Password": "بروزرسانی رمز عبور",
+  "Set Password": "تنظیم رمز عبور",
+  "Password updated successfully": "رمز عبور با موفقیت بروزرسانی شد",
+  "Passwords do not match": "رمزهای عبور مطابقت ندارند",
+  "Routing Strategy": "استراتژی مسیردهی",
+  "Round Robin": "چرخشی",
+  "Cycle through accounts to distribute load": "چرخش بین حساب‌ها برای توزیع بار",
+  "Sticky Limit": "محدودیت چسبندگی",
+  "Calls per account before switching": "تعداد تماس به ازای هر حساب قبل از تغییر",
+  "Network": "شبکه",
+  "Outbound Proxy": "پروکسی خروجی",
+  "Enable proxy for OAuth + provider outbound requests.": "فعال‌سازی پروکسی برای درخواست‌های خروجی OAuth + ارائه‌دهنده.",
+  "Proxy URL": "آدرس پروکسی",
+  "Leave empty to inherit existing env proxy (if any).": "برای ارث‌بری از پروکسی موجود محیط، خالی بگذارید (در صورت وجود).",
+  "No Proxy": "بدون پروکسی",
+  "Comma-separated hostnames/domains to bypass the proxy.": "نام میزبان/دامنه‌ها با جداکننده ویرگول برای دور زدن پروکسی.",
+  "Test proxy URL": "آزمایش آدرس پروکسی",
+  "Proxy settings applied": "تنظیمات پروکسی اعمال شد",
+  "Proxy enabled": "پروکسی فعال شد",
+  "Proxy disabled": "پروکسی غیرفعال شد",
+  "Proxy test OK": "آزمایش پروکسی موفق",
+  "Proxy test failed": "آزمایش پروکسی ناموفق",
+  "Please enter a Proxy URL to test": "لطفاً یک آدرس پروکسی برای آزمایش وارد کنید",
+  "Observability": "مشاهده‌پذیری",
+  "Enable Observability": "فعال‌سازی مشاهده‌پذیری",
+  "Turn request detail recording on/off globally": "روشن/خاموش کردن ضبط جزئیات درخواست به صورت سراسری",
+  "Max Records": "حداکثر تعداد رکوردها",
+  "Maximum request detail records to keep (older records are auto-deleted)": "حداکثر تعداد رکوردهای جزئیات درخواست برای نگهداری (رکوردهای قدیمی‌تر به صورت خودکار حذف می‌شوند)",
+  "Batch Size": "اندازه دسته",
+  "Number of items to accumulate before writing to database (higher = better performance)": "تعداد موارد قبل از نوشتن در پایگاه داده (بیشتر = عملکرد بهتر)",
+  "Flush Interval (ms)": "فاصله تخلیه (میلی‌ثانیه)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "حداکثر زمان انتظار قبل از تخلیه بافر (از از دست رفتن داده در ترافیک کم جلوگیری می‌کند)",
+  "Max JSON Size (KB)": "حداکثر اندازه JSON (کیلوبایت)",
+  "Maximum size for each JSON field (request/response) before truncation": "حداکثر اندازه برای هر فیلد JSON (درخواست/پاسخ) قبل از برش",
+  "All data stored on your machine": "تمام داده‌ها روی دستگاه شما ذخیره می‌شوند",
+  "MITM Server": "سرور MITM",
+  "Running": "در حال اجرا",
+  "Stopped": "متوقف شده",
+  "Cert": "گواهی",
+  "Server": "سرور",
+  "Purpose:": "هدف:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "استفاده از Antigravity IDE و GitHub Copilot → با هر ارائه‌دهنده/مدلی از 9Router",
+  "How it works:": "نحوه عملکرد:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "درخواست Antigravity/Copilot IDE → تغییر مسیر DNS به localhost:443 → رهگیری پروکسی MITM → 9Router → پاسخ به Antigravity/Copilot",
+  "No API keys — create one in Keys page": "بدون کلید API — یکی در صفحه کلیدها ایجاد کنید",
+  "sk_9router (default)": "sk_9router (پیش‌فرض)",
+  "Server started": "سرور راه‌اندازی شد",
+  "Failed to start server": "خطا در راه‌اندازی سرور",
+  "Server stopped — all DNS cleared": "سرور متوقف شد — تمام DNS پاک شد",
+  "Failed to stop server": "خطا در توقف سرور",
+  "Sudo password is required": "گذرواژه sudo الزامی است",
+  "Stop Server": "توقف سرور",
+  "Start Server": "راه‌اندازی سرور",
+  "Enable DNS per tool below to activate interception": "DNS را برای هر ابزار در زیر فعال کنید تا رهگیری فعال شود",
+  "Sudo Password Required": "گذرواژه sudo الزامی است",
+  "Enter your sudo password to start/stop MITM server": "رمز عبور sudo خود را برای راه‌اندازی/توقف سرور MITM وارد کنید",
+  "Sudo Password": "گذرواژه sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "کلیک برای افزودن، کلیک مجدد برای حذف. تغییرات به صورت خودکار ذخیره می‌شوند.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ اطلاعیه ریسک: این ارائه‌دهنده از اشتراک/جلسه OAuth استفاده می‌کند که به طور رسمی برای استفاده پروکسی/روتر مجوز ندارد. حساب ممکن است محدود یا مسدود شود. با مسئولیت خود استفاده کنید.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM ترافیک HTTPS ابزارهای IDE (Antigravity, GitHub Copilot, Kiro) را از طریق CA محلی رهگیری می‌کند تا درخواست‌ها را به ارائه‌دهندگان شما مسیردهی کند. ممکن است شرایط خدمات را نقض کند → مسدود شدن حساب. با مسئولیت خود استفاده کنید.",
+  "Endpoint is exposed without an API key.": "Endpoint بدون کلید API در معرض دسترسی است."
+}
diff --git a/public/i18n/literals/fi.json b/public/i18n/literals/fi.json
new file mode 100644
index 0000000..dc8b116
--- /dev/null
+++ b/public/i18n/literals/fi.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Peruuta",
+  "Delete": "Poista",
+  "Edit": "Muokkaa",
+  "Save": "Tallenna",
+  "Close": "Sulje",
+  "Add": "Lisää",
+  "Remove": "Poista",
+  "Settings": "Asetukset",
+  "Profile": "Profiili",
+  "Dashboard": "Kojelauta",
+  "Logout": "Kirjaudu ulos",
+  "Login": "Kirjaudu sisään",
+  "Providers": "Palveluntarjoajat",
+  "Usage": "Käyttötilastot",
+  "API Key": "API-avain",
+  "Connected": "Yhdistetty",
+  "Disconnected": "Yhteys katkaistu",
+  "Active": "Aktiivinen",
+  "Inactive": "Passiivinen",
+  "Success": "Onnistui",
+  "Failed": "Epäonnistui",
+  "Error": "Virhe",
+  "Warning": "Varoitus",
+  "Info": "Tiedot",
+  "Loading": "Ladataan",
+  "Search": "Hae",
+  "Filter": "Suodin",
+  "Sort": "Lajittele",
+  "Export": "Vie",
+  "Import": "Tuo",
+  "Refresh": "Päivitä",
+  "Back": "Takaisin",
+  "Next": "Seuraava",
+  "Previous": "Edellinen",
+  "Submit": "Lähetä",
+  "Confirm": "Vahvista",
+  "Yes": "Kyllä",
+  "No": "Ei",
+  "OK": "OK",
+  "Apply": "Käytä",
+  "Reset": "Nollaa",
+  "Clear": "Tyhjennä",
+  "Select": "Valitse",
+  "Upload": "Lataa",
+  "Download": "Lataa",
+  "Copy": "Kopioi",
+  "Paste": "Liitä",
+  "Cut": "Leikkaa",
+  "Undo": "Kumoa",
+  "Redo": "Tee uudelleen",
+  "Name": "Nimi",
+  "Description": "Kuvaus",
+  "Status": "Tila",
+  "Type": "Tyyppi",
+  "Date": "Päivämäärä",
+  "Time": "Aika",
+  "Created": "Luotu",
+  "Updated": "Päivitetty",
+  "Actions": "Toiminnot",
+  "Details": "Tiedot",
+  "View": "Näytä",
+  "New": "Uusi",
+  "Total": "Yhteensä",
+  "Count": "Määrä",
+  "Price": "Hinta",
+  "Cost": "Kustannus",
+  "Free": "Ilmainen",
+  "Paid": "Maksettu",
+  "Enable": "Ota käyttöön",
+  "Disable": "Poista käytöstä",
+  "Enabled": "Käytössä",
+  "Disabled": "Pois käytöstä",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Saatavilla",
+  "Unavailable": "Ei saatavilla",
+  "Required": "Pakollinen",
+  "Optional": "Valinnainen",
+  "Default": "Oletus",
+  "Custom": "Mukautettu",
+  "Advanced": "Lisäasetukset",
+  "Basic": "Perus",
+  "Help": "Apua",
+  "Support": "Tuki",
+  "Documentation": "Dokumentaatio",
+  "Version": "Versio",
+  "Language": "Kieli",
+  "Theme": "Teema",
+  "Light": "Vaalea",
+  "Dark": "Tumma",
+  "Auto": "Automaattinen",
+  "Endpoint": "Pääteeksi",
+  "Combos": "Yhdistelmät",
+  "Quota Tracker": "Kiintiyden seuranta",
+  "MITM": "MITM",
+  "CLI Tools": "Työkalut",
+  "Console Log": "Konsolilokit",
+  "System": "Järjestelmä",
+  "Debug": "Virheenkorjaus",
+  "Shutdown": "Sammuta",
+  "Close Proxy": "Sulje välityspalvelin",
+  "Are you sure you want to close the proxy server?": "Oletko varma, että haluat sulkea välityspalvelimen?",
+  "Server Disconnected": "Palvelin katkaistiin",
+  "The proxy server has been stopped.": "Välityspalvelin on pysäytetty.",
+  "Reload Page": "Päivitä sivu",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Palvelu on käynnissä terminaalissa. Voit sulkea tämän verkkosivun. Sammutus pysäyttää palvelun.",
+  "Manage your AI provider connections": "Hallitse AI-palveluntarjoajayhteyksääsi",
+  "Model combos with fallback": "Mallien yhdistelmät palautuksella",
+  "Monitor your API usage, token consumption, and request logs": "Valvo API-käyttöä, tunnusmerkkien kulutusta ja pyyntölokeja",
+  "Intercept CLI tool traffic and route through 9Router": "Sieppaa CLI-työkaluliikenteen ja reitit 9Routerin kautta",
+  "Configure CLI tools": "Konfiguroi CLI-työkalut",
+  "API endpoint configuration": "API-päätepisteen konfiguraatio",
+  "Manage your preferences": "Hallitse asetuksiasi",
+  "Debug translation flow between formats": "Virheenkorjaus kääntämisvirta formaattien välillä",
+  "Live server console output": "Palvelimen konsolin tulostus reaaliajassa",
+  "Create model combos with fallback support": "Luo malliyhdistelmiä palautustuen kanssa",
+  "Local Mode": "Paikallinen tila",
+  "Running on your machine": "Käynnissä koneellasi",
+  "Database Location": "Tietokannan sijainti",
+  "Download Backup": "Lataa varmuuskopio",
+  "Import Backup": "Tuo varmuuskopio",
+  "Database backup downloaded": "Tietokannan varmuuskopio ladattiin",
+  "Database imported successfully": "Tietokanta tuotiin onnistuneesti",
+  "Security": "Turvallisuus",
+  "Require login": "Vaadi kirjautumista",
+  "When ON, dashboard requires password. When OFF, access without login.": "Kun ON, kojelauta vaatii salasanaa. Kun OFF, pääsy ilman kirjautumista.",
+  "Current Password": "Nykyinen salasana",
+  "Enter current password": "Kirjoita nykyinen salasana",
+  "New Password": "Uusi salasana",
+  "Enter new password": "Kirjoita uusi salasana",
+  "Confirm New Password": "Vahvista uusi salasana",
+  "Confirm new password": "Vahvista uusi salasana",
+  "Update Password": "Päivitä salasana",
+  "Set Password": "Aseta salasana",
+  "Password updated successfully": "Salasana päivitettiin onnistuneesti",
+  "Passwords do not match": "Salasanat eivät täsmää",
+  "Routing Strategy": "Reititysstrategia",
+  "Round Robin": "Kiertelevä robotti",
+  "Cycle through accounts to distribute load": "Kierrä tileillä kuormituksen jakamiseksi",
+  "Sticky Limit": "Kiinteä raja",
+  "Calls per account before switching": "Puhelut tiliä kohti ennen vaihtamista",
+  "Network": "Verkko",
+  "Outbound Proxy": "Lähtevä välityspalvelin",
+  "Enable proxy for OAuth + provider outbound requests.": "Ota käyttöön välityspalvelin OAuth + palveluntarjoajan lähteviin pyyntöihin.",
+  "Proxy URL": "Välityspalvelimen URL",
+  "Leave empty to inherit existing env proxy (if any).": "Jätä tyhjäksi periä olemassa olevaa env-välityspalvelinta (jos sellainen on).",
+  "No Proxy": "Ei välityspalvelinta",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Pilkulla erotetut isäntänimet/etäisyydet välityspalvelimen ohittamiseksi.",
+  "Test proxy URL": "Testaa välityspalvelimen URL",
+  "Proxy settings applied": "Välityspalvelimen asetukset käytössä",
+  "Proxy enabled": "Välityspalvelin otettu käyttöön",
+  "Proxy disabled": "Välityspalvelin poistettu käytöstä",
+  "Proxy test OK": "Välityspalvelimen testi OK",
+  "Proxy test failed": "Välityspalvelimen testi epäonnistui",
+  "Please enter a Proxy URL to test": "Kirjoita testattava välityspalvelimen URL",
+  "Observability": "Havainnointitarkkuus",
+  "Enable Observability": "Ota havainnointitarkkuus käyttöön",
+  "Turn request detail recording on/off globally": "Poista pyynnön yksityiskohtien tallentaminen käyttöön/pois käytöstä maailmanlaajuisesti",
+  "Max Records": "Max-tietueet",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Maksimaalinen pyynnön yksityiskohtitietueet säilytettäväksi (vanhemmat tietueet poistetaan automaattisesti)",
+  "Batch Size": "Erän koko",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Tietokantaan kirjoittamista edeltävien kerättävien kohteiden lukumäärä (korkeampi = parempi suorituskyky)",
+  "Flush Interval (ms)": "Tyhjennysväli (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Enimmäisaika odottaa ennen puskurin tyhjentämistä (estää tietojen menetyksen matalan liikenteen aikana)",
+  "Max JSON Size (KB)": "Maksimaalinen JSON-koko (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Kunkin JSON-kentän (pyynnön/vastauksen) enimmäiskoko ennen katkaisua",
+  "All data stored on your machine": "Kaikki tiedot tallennettu koneellasi",
+  "MITM Server": "MITM-palvelin",
+  "Running": "Käynnissä",
+  "Stopped": "Pysäytetty",
+  "Cert": "Sertifikaatti",
+  "Server": "Palvelin",
+  "Purpose:": "Tarkoitus:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Käytä Antigravity IDE:tä ja GitHub Copilot:ia → minkä tahansa palveluntarjoajan/mallin kanssa 9Routerista",
+  "How it works:": "Kuinka se toimii:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE-pyyntö → DNS-uudelleenohjaus localhost:443:iin → MITM-välityspalvelin sieppaa → 9Router → vastaus Antigravity/Copilot:ille",
+  "No API keys — create one in Keys page": "Ei API-avaimia — luo yksi Keys-sivulla",
+  "sk_9router (default)": "sk_9router (oletus)",
+  "Server started": "Palvelin käynnistetty",
+  "Failed to start server": "Palvelimen käynnistäminen epäonnistui",
+  "Server stopped — all DNS cleared": "Palvelin pysäytetty — kaikki DNS poistettu",
+  "Failed to stop server": "Palvelimen pysäyttäminen epäonnistui",
+  "Sudo password is required": "Sudo-salasana vaaditaan",
+  "Stop Server": "Pysäytä palvelin",
+  "Start Server": "Käynnistä palvelin",
+  "Enable DNS per tool below to activate interception": "Ota DNS käyttöön kunkin alla olevan työkalun osalta aktivoidaksesi sieppauksen",
+  "Sudo Password Required": "Sudo-salasana vaaditaan",
+  "Enter your sudo password to start/stop MITM server": "Kirjoita sudo-salasanasi MITM-palvelimen käynnistämiseksi/pysäyttämiseksi",
+  "Sudo Password": "Sudo-salasana",
+  "Click to add, click again to remove. Changes are saved automatically.": "Napsauta lisätäksesi, napsauta uudelleen poistaaksesi. Muutokset tallennetaan automaattisesti.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Riski-ilmoitus: Tämä palveluntarjoaja käyttää tilaus-/OAuth-istuntoa, jota ei ole virallisesti lisensoitu välityspalvelin-/reititinkäyttöön. Tili voidaan rajoittaa tai estää. Käyttö omalla vastuulla.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM sieppaa IDE-työkalujen (Antigravity, GitHub Copilot, Kiro) HTTPS-liikennettä paikallisen CA:n kautta uudelleenohjatakseen pyyntöjä palveluntarjoajillesi. Voi rikkoa ToS:ää → tilin estoriski. Käyttö omalla vastuulla.",
+  "Endpoint is exposed without an API key.": "Päätepiste on alttiina ilman API-avainta."
+}
diff --git a/public/i18n/literals/fr.json b/public/i18n/literals/fr.json
new file mode 100644
index 0000000..bbf8854
--- /dev/null
+++ b/public/i18n/literals/fr.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Annuler",
+  "Delete": "Supprimer",
+  "Edit": "Modifier",
+  "Save": "Enregistrer",
+  "Close": "Fermer",
+  "Add": "Ajouter",
+  "Remove": "Retirer",
+  "Settings": "Paramètres",
+  "Profile": "Profil",
+  "Dashboard": "Tableau de bord",
+  "Logout": "Déconnexion",
+  "Login": "Connexion",
+  "Providers": "Fournisseurs",
+  "Usage": "Statistiques",
+  "API Key": "Clé API",
+  "Connected": "Connecté",
+  "Disconnected": "Déconnecté",
+  "Active": "Actif",
+  "Inactive": "Inactif",
+  "Success": "Succès",
+  "Failed": "Échoué",
+  "Error": "Erreur",
+  "Warning": "Avertissement",
+  "Info": "Informations",
+  "Loading": "Chargement",
+  "Search": "Rechercher",
+  "Filter": "Filtrer",
+  "Sort": "Trier",
+  "Export": "Exporter",
+  "Import": "Importer",
+  "Refresh": "Actualiser",
+  "Back": "Retour",
+  "Next": "Suivant",
+  "Previous": "Précédent",
+  "Submit": "Soumettre",
+  "Confirm": "Confirmer",
+  "Yes": "Oui",
+  "No": "Non",
+  "OK": "OK",
+  "Apply": "Appliquer",
+  "Reset": "Réinitialiser",
+  "Clear": "Effacer",
+  "Select": "Sélectionner",
+  "Upload": "Télécharger",
+  "Download": "Télécharger",
+  "Copy": "Copier",
+  "Paste": "Coller",
+  "Cut": "Couper",
+  "Undo": "Annuler",
+  "Redo": "Refaire",
+  "Name": "Nom",
+  "Description": "Description",
+  "Status": "Statut",
+  "Type": "Type",
+  "Date": "Date",
+  "Time": "Heure",
+  "Created": "Créé",
+  "Updated": "Modifié",
+  "Actions": "Actions",
+  "Details": "Détails",
+  "View": "Afficher",
+  "New": "Nouveau",
+  "Total": "Total",
+  "Count": "Nombre",
+  "Price": "Prix",
+  "Cost": "Coût",
+  "Free": "Gratuit",
+  "Paid": "Payant",
+  "Enable": "Activer",
+  "Disable": "Désactiver",
+  "Enabled": "Activé",
+  "Disabled": "Désactivé",
+  "Online": "En ligne",
+  "Offline": "Hors ligne",
+  "Available": "Disponible",
+  "Unavailable": "Indisponible",
+  "Required": "Requis",
+  "Optional": "Facultatif",
+  "Default": "Par défaut",
+  "Custom": "Personnalisé",
+  "Advanced": "Avancé",
+  "Basic": "Basique",
+  "Help": "Aide",
+  "Support": "Support",
+  "Documentation": "Documentation",
+  "Version": "Version",
+  "Language": "Langue",
+  "Theme": "Thème",
+  "Light": "Clair",
+  "Dark": "Sombre",
+  "Auto": "Automatique",
+  "Endpoint": "Point final",
+  "Combos": "Combinaisons",
+  "Quota Tracker": "Suivi des quotas",
+  "MITM": "MITM",
+  "CLI Tools": "Outils CLI",
+  "Console Log": "Journaux de console",
+  "System": "Système",
+  "Debug": "Débogage",
+  "Shutdown": "Arrêt",
+  "Close Proxy": "Fermer le proxy",
+  "Are you sure you want to close the proxy server?": "Êtes-vous sûr de vouloir fermer le serveur proxy ?",
+  "Server Disconnected": "Serveur déconnecté",
+  "The proxy server has been stopped.": "Le serveur proxy a été arrêté.",
+  "Reload Page": "Recharger la page",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Le service s'exécute dans le terminal. Vous pouvez fermer cette page web. L'arrêt arrêtera le service.",
+  "Manage your AI provider connections": "Gérez vos connexions de fournisseur IA",
+  "Model combos with fallback": "Combinaisons de modèles avec secours",
+  "Monitor your API usage, token consumption, and request logs": "Surveillez votre utilisation d'API, la consommation de jetons et les journaux de requête",
+  "Intercept CLI tool traffic and route through 9Router": "Interceptez le trafic des outils CLI et acheminez via 9Router",
+  "Configure CLI tools": "Configurer les outils CLI",
+  "API endpoint configuration": "Configuration du point final API",
+  "Manage your preferences": "Gérez vos préférences",
+  "Debug translation flow between formats": "Déboguer le flux de traduction entre les formats",
+  "Live server console output": "Sortie de la console du serveur en direct",
+  "Create model combos with fallback support": "Créer des combinaisons de modèles avec support de secours",
+  "Local Mode": "Mode local",
+  "Running on your machine": "S'exécute sur votre machine",
+  "Database Location": "Emplacement de la base de données",
+  "Download Backup": "Télécharger la sauvegarde",
+  "Import Backup": "Importer la sauvegarde",
+  "Database backup downloaded": "Sauvegarde de la base de données téléchargée",
+  "Database imported successfully": "Base de données importée avec succès",
+  "Security": "Sécurité",
+  "Require login": "Exiger une connexion",
+  "When ON, dashboard requires password. When OFF, access without login.": "Lorsqu'il est ACTIVÉ, le tableau de bord nécessite un mot de passe. Lorsqu'il est DÉSACTIVÉ, accès sans connexion.",
+  "Current Password": "Mot de passe actuel",
+  "Enter current password": "Entrez le mot de passe actuel",
+  "New Password": "Nouveau mot de passe",
+  "Enter new password": "Entrez le nouveau mot de passe",
+  "Confirm New Password": "Confirmer le nouveau mot de passe",
+  "Confirm new password": "Confirmez le nouveau mot de passe",
+  "Update Password": "Mettre à jour le mot de passe",
+  "Set Password": "Définir le mot de passe",
+  "Password updated successfully": "Mot de passe mis à jour avec succès",
+  "Passwords do not match": "Les mots de passe ne correspondent pas",
+  "Routing Strategy": "Stratégie d'acheminement",
+  "Round Robin": "Round Robin",
+  "Cycle through accounts to distribute load": "Parcourir les comptes pour distribuer la charge",
+  "Sticky Limit": "Limite collante",
+  "Calls per account before switching": "Appels par compte avant de changer",
+  "Network": "Réseau",
+  "Outbound Proxy": "Proxy sortant",
+  "Enable proxy for OAuth + provider outbound requests.": "Activez le proxy pour OAuth + les demandes sortantes du fournisseur.",
+  "Proxy URL": "URL du proxy",
+  "Leave empty to inherit existing env proxy (if any).": "Laissez vide pour hériter du proxy env existant (le cas échéant).",
+  "No Proxy": "Pas de proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Noms d'hôtes/domaines séparés par des virgules pour contourner le proxy.",
+  "Test proxy URL": "Tester l'URL du proxy",
+  "Proxy settings applied": "Paramètres de proxy appliqués",
+  "Proxy enabled": "Proxy activé",
+  "Proxy disabled": "Proxy désactivé",
+  "Proxy test OK": "Test de proxy OK",
+  "Proxy test failed": "Échec du test de proxy",
+  "Please enter a Proxy URL to test": "Veuillez entrer une URL de proxy à tester",
+  "Observability": "Observabilité",
+  "Enable Observability": "Activer l'observabilité",
+  "Turn request detail recording on/off globally": "Activer/désactiver l'enregistrement des détails de la requête globalement",
+  "Max Records": "Nombre maximum d'enregistrements",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Nombre maximum d'enregistrements de détails de requête à conserver (les anciens enregistrements sont supprimés automatiquement)",
+  "Batch Size": "Taille du lot",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Nombre d'éléments à accumuler avant d'écrire dans la base de données (plus élevé = meilleures performances)",
+  "Flush Interval (ms)": "Intervalle de vidage (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Temps maximum d'attente avant de vider le tampon (évite la perte de données en cas de faible trafic)",
+  "Max JSON Size (KB)": "Taille JSON maximale (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Taille maximale pour chaque champ JSON (demande/réponse) avant la troncature",
+  "All data stored on your machine": "Toutes les données stockées sur votre machine",
+  "MITM Server": "Serveur MITM",
+  "Running": "En cours d'exécution",
+  "Stopped": "Arrêté",
+  "Cert": "Certificat",
+  "Server": "Serveur",
+  "Purpose:": "Objectif :",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Utilisez Antigravity IDE et GitHub Copilot → avec N'IMPORTE QUEL fournisseur/modèle de 9Router",
+  "How it works:": "Comment ça marche :",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Demande Antigravity/Copilot IDE → Redirection DNS vers localhost:443 → Le proxy MITM intercepte → 9Router → réponse à Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Aucune clé API — créez-en une dans la page Clés",
+  "sk_9router (default)": "sk_9router (par défaut)",
+  "Server started": "Serveur démarré",
+  "Failed to start server": "Impossible de démarrer le serveur",
+  "Server stopped — all DNS cleared": "Serveur arrêté — tout DNS effacé",
+  "Failed to stop server": "Impossible d'arrêter le serveur",
+  "Sudo password is required": "Le mot de passe sudo est requis",
+  "Stop Server": "Arrêter le serveur",
+  "Start Server": "Démarrer le serveur",
+  "Enable DNS per tool below to activate interception": "Activez le DNS pour chaque outil ci-dessous pour activer l'interception",
+  "Sudo Password Required": "Mot de passe Sudo requis",
+  "Enter your sudo password to start/stop MITM server": "Entrez votre mot de passe sudo pour démarrer/arrêter le serveur MITM",
+  "Sudo Password": "Mot de passe sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Cliquez pour ajouter, cliquez à nouveau pour supprimer. Les modifications sont enregistrées automatiquement.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Avis de risque : Ce fournisseur utilise une session d'abonnement/OAuth non officiellement autorisée pour une utilisation proxy/routeur. Le compte peut être restreint ou banni. Utilisez à vos propres risques.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM intercepte le trafic HTTPS des outils IDE (Antigravity, GitHub Copilot, Kiro) via une CA locale pour rediriger les requêtes vers vos fournisseurs. Peut violer les CGU → risque de bannissement de compte. Utilisez à vos propres risques.",
+  "Endpoint is exposed without an API key.": "Le point de terminaison est exposé sans clé API."
+}
diff --git a/public/i18n/literals/he.json b/public/i18n/literals/he.json
new file mode 100644
index 0000000..c144d01
--- /dev/null
+++ b/public/i18n/literals/he.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "ביטול",
+  "Delete": "מחק",
+  "Edit": "עריכה",
+  "Save": "שמור",
+  "Close": "סגור",
+  "Add": "הוספה",
+  "Remove": "הסרה",
+  "Settings": "הגדרות",
+  "Profile": "פרופיל",
+  "Dashboard": "לוח בקרה",
+  "Logout": "התנתקות",
+  "Login": "כניסה",
+  "Providers": "ספקים",
+  "Usage": "סטטיסטיקה",
+  "API Key": "מפתח API",
+  "Connected": "מחובר",
+  "Disconnected": "מנותק",
+  "Active": "פעיל",
+  "Inactive": "לא פעיל",
+  "Success": "הצלחה",
+  "Failed": "נכשל",
+  "Error": "שגיאה",
+  "Warning": "אזהרה",
+  "Info": "מידע",
+  "Loading": "טוען",
+  "Search": "חיפוש",
+  "Filter": "סינון",
+  "Sort": "מיון",
+  "Export": "ייצוא",
+  "Import": "ייבוא",
+  "Refresh": "רענן",
+  "Back": "חזור",
+  "Next": "הבא",
+  "Previous": "הקודם",
+  "Submit": "שלח",
+  "Confirm": "אישור",
+  "Yes": "כן",
+  "No": "לא",
+  "OK": "אישור",
+  "Apply": "החל",
+  "Reset": "אפס",
+  "Clear": "נקה",
+  "Select": "בחר",
+  "Upload": "העלאה",
+  "Download": "הורדה",
+  "Copy": "העתק",
+  "Paste": "הדבק",
+  "Cut": "גזור",
+  "Undo": "ביטול",
+  "Redo": "חזור על",
+  "Name": "שם",
+  "Description": "תיאור",
+  "Status": "סטטוס",
+  "Type": "סוג",
+  "Date": "תאריך",
+  "Time": "זמן",
+  "Created": "נוצר",
+  "Updated": "עודכן",
+  "Actions": "פעולות",
+  "Details": "פרטים",
+  "View": "צפה",
+  "New": "חדש",
+  "Total": "סה\"כ",
+  "Count": "ספירה",
+  "Price": "מחיר",
+  "Cost": "עלות",
+  "Free": "חינם",
+  "Paid": "בתשלום",
+  "Enable": "הפעל",
+  "Disable": "כבה",
+  "Enabled": "הופעל",
+  "Disabled": "מבוטל",
+  "Online": "מחובר",
+  "Offline": "לא מחובר",
+  "Available": "זמין",
+  "Unavailable": "לא זמין",
+  "Required": "נדרש",
+  "Optional": "אופציונלי",
+  "Default": "ברירת מחדל",
+  "Custom": "מותאם",
+  "Advanced": "מתקדם",
+  "Basic": "בסיסי",
+  "Help": "עזרה",
+  "Support": "תמיכה",
+  "Documentation": "תיעוד",
+  "Version": "גרסה",
+  "Language": "שפה",
+  "Theme": "עיצוב",
+  "Light": "בהיר",
+  "Dark": "אפל",
+  "Auto": "אוטומטי",
+  "Endpoint": "נקודת קצה",
+  "Combos": "שילובים",
+  "Quota Tracker": "עוקב הקצאה",
+  "MITM": "MITM",
+  "CLI Tools": "כלים CLI",
+  "Console Log": "יומן קונסול",
+  "System": "מערכת",
+  "Debug": "ניפוי שגיאות",
+  "Shutdown": "כיבוי",
+  "Close Proxy": "סגור פרוקסי",
+  "Are you sure you want to close the proxy server?": "האם אתה בטוח שברצונך לסגור את שרת הפרוקסי?",
+  "Server Disconnected": "השרת מנותק",
+  "The proxy server has been stopped.": "שרת הפרוקסי הופסק.",
+  "Reload Page": "טען מחדש את הדף",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "השירות פועל בטרמינל. אתה יכול לסגור את דף אינטרנט זה. כיבוי יעצור את השירות.",
+  "Manage your AI provider connections": "נהל את חיבורי ספק ה-AI שלך",
+  "Model combos with fallback": "שילובי מודל עם התחזוקה",
+  "Monitor your API usage, token consumption, and request logs": "עקוב אחרי השימוש ב-API, צריכת אסימונים ויומני בקשה",
+  "Intercept CLI tool traffic and route through 9Router": "תקוף את תנועת כלי CLI וניתוב דרך 9Router",
+  "Configure CLI tools": "הגדר כלים CLI",
+  "API endpoint configuration": "הגדרת נקודת קצה של API",
+  "Manage your preferences": "נהל את העדפותיך",
+  "Debug translation flow between formats": "ניפוי זרם התרגום בין פורמטים",
+  "Live server console output": "פלט קונסול שרת חי",
+  "Create model combos with fallback support": "יצור שילובי מודל עם תמיכה בהתחזוקה",
+  "Local Mode": "מצב מקומי",
+  "Running on your machine": "רץ על המחשב שלך",
+  "Database Location": "מיקום מסד הנתונים",
+  "Download Backup": "הורד גיבוי",
+  "Import Backup": "ייבא גיבוי",
+  "Database backup downloaded": "גיבוי מסד הנתונים הורד",
+  "Database imported successfully": "מסד הנתונים יובא בהצלחה",
+  "Security": "אבטחה",
+  "Require login": "דרוש כניסה",
+  "When ON, dashboard requires password. When OFF, access without login.": "כאשר כבוי, לוח הבקרה דורש סיסמה. כאשר מכובה, גישה ללא כניסה.",
+  "Current Password": "סיסמה נוכחית",
+  "Enter current password": "הזן את הסיסמה הנוכחית",
+  "New Password": "סיסמה חדשה",
+  "Enter new password": "הזן סיסמה חדשה",
+  "Confirm New Password": "אשר סיסמה חדשה",
+  "Confirm new password": "אשר סיסמה חדשה",
+  "Update Password": "עדכן סיסמה",
+  "Set Password": "הגדר סיסמה",
+  "Password updated successfully": "הסיסמה עודכנה בהצלחה",
+  "Passwords do not match": "הסיסמאות אינן תואמות",
+  "Routing Strategy": "אסטרטגיית ניתוב",
+  "Round Robin": "Round Robin",
+  "Cycle through accounts to distribute load": "מחזור בחשבונות לחלוקת עומס",
+  "Sticky Limit": "גבול דבוק",
+  "Calls per account before switching": "קריאות לפי חשבון לפני המעבר",
+  "Network": "רשת",
+  "Outbound Proxy": "פרוקסי יוצא",
+  "Enable proxy for OAuth + provider outbound requests.": "הפעל פרוקסי עבור בקשות יוצאות של OAuth + ספק.",
+  "Proxy URL": "URL פרוקסי",
+  "Leave empty to inherit existing env proxy (if any).": "השאר ריק כדי לרשת פרוקסי env קיים (אם יש).",
+  "No Proxy": "ללא פרוקסי",
+  "Comma-separated hostnames/domains to bypass the proxy.": "שמות משדר/תחומים מופרדים בפסיקים לעקיפת הפרוקסי.",
+  "Test proxy URL": "בדוק URL פרוקסי",
+  "Proxy settings applied": "הגדרות פרוקסי הופעלו",
+  "Proxy enabled": "פרוקסי הופעל",
+  "Proxy disabled": "פרוקסי מבוטל",
+  "Proxy test OK": "בדיקת פרוקסי בסדר",
+  "Proxy test failed": "בדיקת פרוקסי נכשלה",
+  "Please enter a Proxy URL to test": "אנא הזן URL פרוקסי לבדיקה",
+  "Observability": "יכולת תצפית",
+  "Enable Observability": "הפעל יכולת תצפית",
+  "Turn request detail recording on/off globally": "הפעל/כבה הקלטת פרטי בקשה בעולם",
+  "Max Records": "מרבי רשומות",
+  "Maximum request detail records to keep (older records are auto-deleted)": "מרבי רשומות פרטי בקשה לשמור (רשומות ישנות יותר נמחקות באופן אוטומטי)",
+  "Batch Size": "גודל אצווה",
+  "Number of items to accumulate before writing to database (higher = better performance)": "מספר הפריטים להצטברות לפני הכתיבה למסד הנתונים (גבוה יותר = ביצועים טובים יותר)",
+  "Flush Interval (ms)": "מרווח שטיפה (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "זמן מקסימום להמתנה לפני שטיפת ביפר (מונע הפסד נתונים תחת תנועה נמוכה)",
+  "Max JSON Size (KB)": "גודל JSON מקסימלי (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "גודל מקסימלי לכל שדה JSON (בקשה/תגובה) לפני חיתוך",
+  "All data stored on your machine": "כל הנתונים מאוחסנים במחשב שלך",
+  "MITM Server": "שרת MITM",
+  "Running": "רץ",
+  "Stopped": "עצור",
+  "Cert": "תעודה",
+  "Server": "שרת",
+  "Purpose:": "מטרה:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "השתמש ב-Antigravity IDE ו-GitHub Copilot → עם כל ספק/מודל מ-9Router",
+  "How it works:": "איך זה עובד:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "בקשת Antigravity/Copilot IDE → הפניה DNS ל-localhost:443 → פרוקסי MITM חוטף → 9Router → תגובה ל-Antigravity/Copilot",
+  "No API keys — create one in Keys page": "אין מפתחות API — צור אחד בעמוד Keys",
+  "sk_9router (default)": "sk_9router (ברירת מחדל)",
+  "Server started": "השרת התחיל",
+  "Failed to start server": "הפעלת השרת נכשלה",
+  "Server stopped — all DNS cleared": "השרת הופסק — כל ה-DNS נוקה",
+  "Failed to stop server": "עצירת השרת נכשלה",
+  "Sudo password is required": "נדרשת סיסמת sudo",
+  "Stop Server": "עצור שרת",
+  "Start Server": "הפעל שרת",
+  "Enable DNS per tool below to activate interception": "הפעל DNS לכל כלי למטה להפעלת היירוט",
+  "Sudo Password Required": "סיסמת Sudo נדרשת",
+  "Enter your sudo password to start/stop MITM server": "הזן את סיסמת sudo שלך כדי להתחיל/עצור שרת MITM",
+  "Sudo Password": "סיסמת Sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "לחץ להוספה, לחץ שוב להסרה. השינויים נשמרים אוטומטית.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ הודעת סיכון: ספק זה משתמש במנוי/הפעלת OAuth שאינה מורשית רשמית לשימוש פרוקסי/ראוטר. החשבון עלול להיות מוגבל או חסום. השימוש על אחריותך בלבד.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM יירוט תעבורת HTTPS של כלי IDE (Antigravity, GitHub Copilot, Kiro) באמצעות CA מקומי כדי להפנות בקשות לספקים שלך. עלול להפר את תנאי השירות → סיכון חסימת חשבון. השימוש על אחריותך.",
+  "Endpoint is exposed without an API key.": "נקודת הקצה חשופה ללא מפתח API."
+}
diff --git a/public/i18n/literals/hi.json b/public/i18n/literals/hi.json
new file mode 100644
index 0000000..2fc6b33
--- /dev/null
+++ b/public/i18n/literals/hi.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "रद्द करें",
+  "Delete": "हटाएं",
+  "Edit": "संपादित करें",
+  "Save": "सहेजें",
+  "Close": "बंद करें",
+  "Add": "जोड़ें",
+  "Remove": "निकालें",
+  "Settings": "सेटिंग्स",
+  "Profile": "प्रोफ़ाइल",
+  "Dashboard": "डैशबोर्ड",
+  "Logout": "लॉग आउट",
+  "Login": "लॉगिन",
+  "Providers": "प्रदाता",
+  "Usage": "उपयोग के आंकड़े",
+  "API Key": "API कुंजी",
+  "Connected": "जुड़ा हुआ",
+  "Disconnected": "डिस्कनेक्ट किया गया",
+  "Active": "सक्रिय",
+  "Inactive": "निष्क्रिय",
+  "Success": "सफल",
+  "Failed": "विफल",
+  "Error": "त्रुटि",
+  "Warning": "चेतावनी",
+  "Info": "जानकारी",
+  "Loading": "लोड हो रहा है",
+  "Search": "खोज",
+  "Filter": "फिल्टर",
+  "Sort": "सॉर्ट करें",
+  "Export": "निर्यात",
+  "Import": "आयात",
+  "Refresh": "रीफ्रेश करें",
+  "Back": "वापस",
+  "Next": "आगे",
+  "Previous": "पिछला",
+  "Submit": "जमा करें",
+  "Confirm": "पुष्टि करें",
+  "Yes": "हां",
+  "No": "नहीं",
+  "OK": "ठीक है",
+  "Apply": "लागू करें",
+  "Reset": "रीसेट करें",
+  "Clear": "साफ़ करें",
+  "Select": "चुनें",
+  "Upload": "अपलोड करें",
+  "Download": "डाउनलोड करें",
+  "Copy": "कॉपी करें",
+  "Paste": "पेस्ट करें",
+  "Cut": "काटें",
+  "Undo": "पूर्ववत करें",
+  "Redo": "फिर से करें",
+  "Name": "नाम",
+  "Description": "विवरण",
+  "Status": "स्थिति",
+  "Type": "प्रकार",
+  "Date": "तारीख",
+  "Time": "समय",
+  "Created": "बनाया गया",
+  "Updated": "अपडेट किया गया",
+  "Actions": "कार्य",
+  "Details": "विवरण",
+  "View": "देखें",
+  "New": "नया",
+  "Total": "कुल",
+  "Count": "गिनती",
+  "Price": "कीमत",
+  "Cost": "लागत",
+  "Free": "मुक्त",
+  "Paid": "भुगतान किया गया",
+  "Enable": "सक्षम करें",
+  "Disable": "अक्षम करें",
+  "Enabled": "सक्षम",
+  "Disabled": "अक्षम",
+  "Online": "ऑनलाइन",
+  "Offline": "ऑफ़लाइन",
+  "Available": "उपलब्ध",
+  "Unavailable": "अनुपलब्ध",
+  "Required": "आवश्यक",
+  "Optional": "वैकल्पिक",
+  "Default": "डिफ़ॉल्ट",
+  "Custom": "कस्टम",
+  "Advanced": "उन्नत",
+  "Basic": "बुनियादी",
+  "Help": "मदद",
+  "Support": "समर्थन",
+  "Documentation": "दस्तावेज़",
+  "Version": "संस्करण",
+  "Language": "भाषा",
+  "Theme": "थीम",
+  "Light": "हल्का",
+  "Dark": "अंधेरा",
+  "Auto": "स्वचालित",
+  "Endpoint": "एंडपॉइंट",
+  "Combos": "कॉम्बो",
+  "Quota Tracker": "कोटा ट्रैकर",
+  "MITM": "MITM",
+  "CLI Tools": "उपकरण",
+  "Console Log": "कंसोल लॉग",
+  "System": "प्रणाली",
+  "Debug": "डीबग",
+  "Shutdown": "बंद करें",
+  "Close Proxy": "प्रॉक्सी बंद करें",
+  "Are you sure you want to close the proxy server?": "क्या आप वाकई प्रॉक्सी सर्वर को बंद करना चाहते हैं?",
+  "Server Disconnected": "सर्वर डिस्कनेक्ट किया गया",
+  "The proxy server has been stopped.": "प्रॉक्सी सर्वर को बंद कर दिया गया है।",
+  "Reload Page": "पृष्ठ को पुनः लोड करें",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "सेवा टर्मिनल में चल रही है। आप इस वेब पृष्ठ को बंद कर सकते हैं। शटडाउन सेवा को बंद कर देगा।",
+  "Manage your AI provider connections": "अपने AI प्रदाता कनेक्शन प्रबंधित करें",
+  "Model combos with fallback": "फॉलबैक के साथ मॉडल कॉम्बो",
+  "Monitor your API usage, token consumption, and request logs": "अपने API उपयोग, टोकन खपत और अनुरोध लॉग की निगरानी करें",
+  "Intercept CLI tool traffic and route through 9Router": "CLI टूल ट्रैफिक को इंटरसेप्ट करें और 9Router के माध्यम से रूट करें",
+  "Configure CLI tools": "CLI उपकरण कॉन्फ़िगर करें",
+  "API endpoint configuration": "API एंडपॉइंट कॉन्फ़िगरेशन",
+  "Manage your preferences": "अपनी प्राथमिकताएं प्रबंधित करें",
+  "Debug translation flow between formats": "फॉर्मेट के बीच अनुवाद प्रवाह डीबग करें",
+  "Live server console output": "लाइव सर्वर कंसोल आउटपुट",
+  "Create model combos with fallback support": "फॉलबैक समर्थन के साथ मॉडल कॉम्बो बनाएं",
+  "Local Mode": "स्थानीय मोड",
+  "Running on your machine": "आपकी मशीन पर चल रहा है",
+  "Database Location": "डेटाबेस स्थान",
+  "Download Backup": "बैकअप डाउनलोड करें",
+  "Import Backup": "बैकअप आयात करें",
+  "Database backup downloaded": "डेटाबेस बैकअप डाउनलोड किया गया",
+  "Database imported successfully": "डेटाबेस सफलतापूर्वक आयात किया गया",
+  "Security": "सुरक्षा",
+  "Require login": "लॉगिन की आवश्यकता है",
+  "When ON, dashboard requires password. When OFF, access without login.": "चालू होने पर, डैशबोर्ड को पासवर्ड की आवश्यकता होती है। बंद होने पर, लॉगिन के बिना एक्सेस करें।",
+  "Current Password": "वर्तमान पासवर्ड",
+  "Enter current password": "वर्तमान पासवर्ड दर्ज करें",
+  "New Password": "नया पासवर्ड",
+  "Enter new password": "नया पासवर्ड दर्ज करें",
+  "Confirm New Password": "नए पासवर्ड की पुष्टि करें",
+  "Confirm new password": "नए पासवर्ड की पुष्टि करें",
+  "Update Password": "पासवर्ड अपडेट करें",
+  "Set Password": "पासवर्ड सेट करें",
+  "Password updated successfully": "पासवर्ड सफलतापूर्वक अपडेट किया गया",
+  "Passwords do not match": "पासवर्ड मेल नहीं खाते",
+  "Routing Strategy": "रूटिंग रणनीति",
+  "Round Robin": "राउंड रॉबिन",
+  "Cycle through accounts to distribute load": "लोड वितरित करने के लिए खातों के माध्यम से साइकिल चलाएं",
+  "Sticky Limit": "स्टिकी सीमा",
+  "Calls per account before switching": "स्विच करने से पहले प्रति खाते कॉल",
+  "Network": "नेटवर्क",
+  "Outbound Proxy": "आउटबाउंड प्रॉक्सी",
+  "Enable proxy for OAuth + provider outbound requests.": "OAuth + प्रदाता आउटबाउंड अनुरोधों के लिए प्रॉक्सी सक्षम करें।",
+  "Proxy URL": "प्रॉक्सी URL",
+  "Leave empty to inherit existing env proxy (if any).": "मौजूदा env प्रॉक्सी को इनहेरिट करने के लिए खाली छोड़ें (यदि कोई हो)।",
+  "No Proxy": "कोई प्रॉक्सी नहीं",
+  "Comma-separated hostnames/domains to bypass the proxy.": "प्रॉक्सी को बायपास करने के लिए अल्पविराम से अलग की गई होस्टनाम/डोमेन।",
+  "Test proxy URL": "प्रॉक्सी URL का परीक्षण करें",
+  "Proxy settings applied": "प्रॉक्सी सेटिंग्स लागू की गई",
+  "Proxy enabled": "प्रॉक्सी सक्षम",
+  "Proxy disabled": "प्रॉक्सी अक्षम",
+  "Proxy test OK": "प्रॉक्सी परीक्षण ठीक है",
+  "Proxy test failed": "प्रॉक्सी परीक्षण विफल",
+  "Please enter a Proxy URL to test": "परीक्षण के लिए कृपया एक प्रॉक्सी URL दर्ज करें",
+  "Observability": "पर्यवेक्षणीयता",
+  "Enable Observability": "पर्यवेक्षणीयता सक्षम करें",
+  "Turn request detail recording on/off globally": "अनुरोध विवरण रिकॉर्डिंग को विश्व स्तर पर चालू/बंद करें",
+  "Max Records": "अधिकतम रिकॉर्ड",
+  "Maximum request detail records to keep (older records are auto-deleted)": "रखने के लिए अधिकतम अनुरोध विवरण रिकॉर्ड (पुराने रिकॉर्ड स्वचालित रूप से हटाए जाते हैं)",
+  "Batch Size": "बैच आकार",
+  "Number of items to accumulate before writing to database (higher = better performance)": "डेटाबेस में लिखने से पहले जमा करने के लिए आइटम की संख्या (अधिक = बेहतर प्रदर्शन)",
+  "Flush Interval (ms)": "फ्लश अंतराल (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "बफर को फ्लश करने से पहले प्रतीक्षा करने का अधिकतम समय (कम ट्रैफिक के दौरान डेटा नुकसान को रोकता है)",
+  "Max JSON Size (KB)": "अधिकतम JSON आकार (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "ट्रंकेशन से पहले प्रत्येक JSON फ़ील्ड (अनुरोध/प्रतिक्रिया) के लिए अधिकतम आकार",
+  "All data stored on your machine": "आपकी मशीन पर सभी डेटा संग्रहीत है",
+  "MITM Server": "MITM सर्वर",
+  "Running": "चल रहा है",
+  "Stopped": "रुका हुआ",
+  "Cert": "प्रमाणपत्र",
+  "Server": "सर्वर",
+  "Purpose:": "उद्देश्य:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Antigravity IDE और GitHub Copilot का उपयोग करें → 9Router से किसी भी प्रदाता/मॉडल के साथ",
+  "How it works:": "यह कैसे काम करता है:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE अनुरोध → DNS को localhost:443 में पुनर्निर्देशित करें → MITM प्रॉक्सी इंटरसेप्ट करता है → 9Router → Antigravity/Copilot को प्रतिक्रिया",
+  "No API keys — create one in Keys page": "कोई API कुंजी नहीं — Keys पृष्ठ में एक बनाएं",
+  "sk_9router (default)": "sk_9router (डिफ़ॉल्ट)",
+  "Server started": "सर्वर शुरू किया गया",
+  "Failed to start server": "सर्वर शुरू करने में विफल",
+  "Server stopped — all DNS cleared": "सर्वर बंद — सभी DNS साफ़ किए गए",
+  "Failed to stop server": "सर्वर को रोकने में विफल",
+  "Sudo password is required": "Sudo पासवर्ड की आवश्यकता है",
+  "Stop Server": "सर्वर बंद करें",
+  "Start Server": "सर्वर शुरू करें",
+  "Enable DNS per tool below to activate interception": "इंटरसेप्शन को सक्रिय करने के लिए नीचे प्रत्येक उपकरण के लिए DNS सक्षम करें",
+  "Sudo Password Required": "Sudo पासवर्ड आवश्यक है",
+  "Enter your sudo password to start/stop MITM server": "MITM सर्वर शुरू/रोकने के लिए अपना sudo पासवर्ड दर्ज करें",
+  "Sudo Password": "Sudo पासवर्ड",
+  "Click to add, click again to remove. Changes are saved automatically.": "जोड़ने के लिए क्लिक करें, हटाने के लिए फिर से क्लिक करें। परिवर्तन स्वचालित रूप से सहेजे जाते हैं।",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ जोखिम सूचना: यह प्रदाता एक सब्सक्रिप्शन/OAuth सत्र का उपयोग करता है जो प्रॉक्सी/राउटर उपयोग के लिए आधिकारिक रूप से लाइसेंस प्राप्त नहीं है। खाता प्रतिबंधित या बैन हो सकता है। अपने जोखिम पर उपयोग करें।",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM स्थानीय CA के माध्यम से IDE टूल्स (Antigravity, GitHub Copilot, Kiro) के HTTPS ट्रैफिक को इंटरसेप्ट करता है ताकि अनुरोधों को आपके प्रदाताओं पर पुनर्निर्देशित किया जा सके। ToS का उल्लंघन हो सकता है → खाता बैन का जोखिम। अपने जोखिम पर उपयोग करें।",
+  "Endpoint is exposed without an API key.": "एंडपॉइंट बिना API कुंजी के उजागर है।"
+}
diff --git a/public/i18n/literals/hu.json b/public/i18n/literals/hu.json
new file mode 100644
index 0000000..8e33929
--- /dev/null
+++ b/public/i18n/literals/hu.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Mégse",
+  "Delete": "Törlés",
+  "Edit": "Szerkesztés",
+  "Save": "Mentés",
+  "Close": "Bezárás",
+  "Add": "Hozzáadás",
+  "Remove": "Eltávolítás",
+  "Settings": "Beállítások",
+  "Profile": "Profil",
+  "Dashboard": "Irányítópult",
+  "Logout": "Kijelentkezés",
+  "Login": "Bejelentkezés",
+  "Providers": "Szolgáltatók",
+  "Usage": "Használati statisztika",
+  "API Key": "API-kulcs",
+  "Connected": "Csatlakoztatva",
+  "Disconnected": "Leválasztva",
+  "Active": "Aktív",
+  "Inactive": "Inaktív",
+  "Success": "Siker",
+  "Failed": "Sikertelen",
+  "Error": "Hiba",
+  "Warning": "Figyelmeztetés",
+  "Info": "Információ",
+  "Loading": "Betöltés",
+  "Search": "Keresés",
+  "Filter": "Szűrő",
+  "Sort": "Rendezés",
+  "Export": "Exportálás",
+  "Import": "Importálás",
+  "Refresh": "Frissítés",
+  "Back": "Vissza",
+  "Next": "Következő",
+  "Previous": "Előző",
+  "Submit": "Küldés",
+  "Confirm": "Megerősítés",
+  "Yes": "Igen",
+  "No": "Nem",
+  "OK": "OK",
+  "Apply": "Alkalmazás",
+  "Reset": "Visszaállítás",
+  "Clear": "Törlés",
+  "Select": "Kiválasztás",
+  "Upload": "Feltöltés",
+  "Download": "Letöltés",
+  "Copy": "Másolás",
+  "Paste": "Beillesztés",
+  "Cut": "Kivágás",
+  "Undo": "Visszavonás",
+  "Redo": "Ismét",
+  "Name": "Név",
+  "Description": "Leírás",
+  "Status": "Állapot",
+  "Type": "Típus",
+  "Date": "Dátum",
+  "Time": "Idő",
+  "Created": "Létrehozva",
+  "Updated": "Frissítve",
+  "Actions": "Műveletek",
+  "Details": "Részletek",
+  "View": "Megtekintés",
+  "New": "Új",
+  "Total": "Összes",
+  "Count": "Darabszám",
+  "Price": "Ár",
+  "Cost": "Költség",
+  "Free": "Ingyenes",
+  "Paid": "Fizetős",
+  "Enable": "Engedélyezés",
+  "Disable": "Letiltás",
+  "Enabled": "Engedélyezve",
+  "Disabled": "Letiltva",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Elérhető",
+  "Unavailable": "Nem elérhető",
+  "Required": "Kötelező",
+  "Optional": "Opcionális",
+  "Default": "Alapértelmezett",
+  "Custom": "Egyéni",
+  "Advanced": "Haladó",
+  "Basic": "Alapvető",
+  "Help": "Súgó",
+  "Support": "Támogatás",
+  "Documentation": "Dokumentáció",
+  "Version": "Verzió",
+  "Language": "Nyelv",
+  "Theme": "Téma",
+  "Light": "Világos",
+  "Dark": "Sötét",
+  "Auto": "Automatikus",
+  "Endpoint": "Végpont",
+  "Combos": "Kombinációk",
+  "Quota Tracker": "Kvóta nyomkövetés",
+  "MITM": "MITM",
+  "CLI Tools": "Eszközök",
+  "Console Log": "Konzol napló",
+  "System": "Rendszer",
+  "Debug": "Hibakeresés",
+  "Shutdown": "Leállítás",
+  "Close Proxy": "Proxy bezárása",
+  "Are you sure you want to close the proxy server?": "Biztosan le akarja zárni a proxy szervert?",
+  "Server Disconnected": "Szerver leválasztva",
+  "The proxy server has been stopped.": "A proxy szerver leállt.",
+  "Reload Page": "Oldal újratöltése",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "A szolgáltatás a terminálon fut. Bezárhatja ezt a weboldalt. A leállítás megállítja a szolgáltatást.",
+  "Manage your AI provider connections": "Az AI-szolgáltatók kapcsolatainak kezelése",
+  "Model combos with fallback": "Modell kombinációk tartalékkal",
+  "Monitor your API usage, token consumption, and request logs": "Az API-használat, a token-fogyasztás és a kérési naplók figyelése",
+  "Intercept CLI tool traffic and route through 9Router": "CLI-eszköz forgalmának elfogása és az 9Router-en keresztüli irányítása",
+  "Configure CLI tools": "CLI-eszközök konfigurálása",
+  "API endpoint configuration": "API-végpont konfigurálása",
+  "Manage your preferences": "Előnyzeteinek kezelése",
+  "Debug translation flow between formats": "A fordítási folyamat hibakeresése a formátumok között",
+  "Live server console output": "Élő kiszolgáló konzol kimenete",
+  "Create model combos with fallback support": "Modell kombinációk létrehozása tartalék támogatással",
+  "Local Mode": "Helyi mód",
+  "Running on your machine": "A gépén futó",
+  "Database Location": "Adatbázis helye",
+  "Download Backup": "Biztonsági másolat letöltése",
+  "Import Backup": "Biztonsági másolat importálása",
+  "Database backup downloaded": "Adatbázis biztonsági másolat letöltve",
+  "Database imported successfully": "Az adatbázis sikeresen importálva",
+  "Security": "Biztonság",
+  "Require login": "Bejelentkezés szükséges",
+  "When ON, dashboard requires password. When OFF, access without login.": "Ha BEKAPCSOLT, az irányítópulthoz jelszó szükséges. Ha KIKAPCSOLT, bejelentkezés nélkül is hozzáférhet.",
+  "Current Password": "Jelenlegi jelszó",
+  "Enter current password": "Adja meg a jelenlegi jelszót",
+  "New Password": "Új jelszó",
+  "Enter new password": "Adja meg az új jelszót",
+  "Confirm New Password": "Új jelszó megerősítése",
+  "Confirm new password": "Erősítse meg az új jelszót",
+  "Update Password": "Jelszó frissítése",
+  "Set Password": "Jelszó beállítása",
+  "Password updated successfully": "A jelszó sikeresen frissítve",
+  "Passwords do not match": "A jelszavak nem egyeznek",
+  "Routing Strategy": "Útválasztási stratégia",
+  "Round Robin": "Fordított körforgalom",
+  "Cycle through accounts to distribute load": "Ciklikus váltakozás a fiókok között a terhelés elosztásához",
+  "Sticky Limit": "Ragadós korlát",
+  "Calls per account before switching": "Hívások fiókonként a váltás előtt",
+  "Network": "Hálózat",
+  "Outbound Proxy": "Kimenő proxy",
+  "Enable proxy for OAuth + provider outbound requests.": "Engedélyezze a proxy-t OAuth + szolgáltató kimenő kérésekhez.",
+  "Proxy URL": "Proxy URL",
+  "Leave empty to inherit existing env proxy (if any).": "Hagyja üresen a meglévő env proxy örökléséhez (ha van).",
+  "No Proxy": "Nincs proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Vesszővel elválasztott gazdanév/tartomány a proxy megkerüléséhez.",
+  "Test proxy URL": "Proxy URL-cím tesztelése",
+  "Proxy settings applied": "Proxy beállítások alkalmazva",
+  "Proxy enabled": "Proxy engedélyezve",
+  "Proxy disabled": "Proxy letiltva",
+  "Proxy test OK": "Proxy teszt OK",
+  "Proxy test failed": "Proxy teszt sikertelen",
+  "Please enter a Proxy URL to test": "Kérjük, adjon meg egy Proxy URL-t teszteléshez",
+  "Observability": "Megfigyelhetőség",
+  "Enable Observability": "Megfigyelhetőség engedélyezése",
+  "Turn request detail recording on/off globally": "Kérés részleteinak rögzítésének be/kikapcsolása globálisan",
+  "Max Records": "Maximális rekordok",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Maximális kérés részleteit tartalmaz (a régebbi rekordok automatikusan törlődnek)",
+  "Batch Size": "Köteg mérete",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Az adatbázisba írás előtt felhalmozandó elemek száma (magasabb = jobb teljesítmény)",
+  "Flush Interval (ms)": "Kiürítési intervallum (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Maximális várakozási idő a puffer kiürítése előtt (megelőzi az adatvesztést alacsony forgalom alatt)",
+  "Max JSON Size (KB)": "Maximális JSON méret (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Maximális méret az egyes JSON-mezőkhöz (kérés/válasz) a csonkítás előtt",
+  "All data stored on your machine": "Az összes adat a gépén tárolt",
+  "MITM Server": "MITM szerver",
+  "Running": "Futó",
+  "Stopped": "Leállítva",
+  "Cert": "Tanúsítvány",
+  "Server": "Kiszolgáló",
+  "Purpose:": "Cél:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Antigravity IDE és GitHub Copilot használata → az 9Router bármelyik szolgáltatójával/modelljével",
+  "How it works:": "Hogyan működik:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE kérés → DNS átirányítás a localhost:443-ra → MITM proxy elfogja → 9Router → válasz Antigravity/Copilot-nak",
+  "No API keys — create one in Keys page": "Nincsenek API-kulcsok — hozzon létre egyet a Keys oldalon",
+  "sk_9router (default)": "sk_9router (alapértelmezett)",
+  "Server started": "Szerver elindult",
+  "Failed to start server": "Nem sikerült elindítani a szervert",
+  "Server stopped — all DNS cleared": "A szerver leállt — az összes DNS törlésre kerül",
+  "Failed to stop server": "Nem sikerült leállítani a szervert",
+  "Sudo password is required": "Sudo jelszó szükséges",
+  "Stop Server": "Szerver leállítása",
+  "Start Server": "Szerver indítása",
+  "Enable DNS per tool below to activate interception": "Engedélyezze az alábbi DNS-t az elfogás aktiválásához",
+  "Sudo Password Required": "Sudo jelszó szükséges",
+  "Enter your sudo password to start/stop MITM server": "Adja meg sudo jelszavát a MITM szerver indításához/leállításához",
+  "Sudo Password": "Sudo jelszó",
+  "Click to add, click again to remove. Changes are saved automatically.": "Kattintson a hozzáadáshoz, kattintson újra az eltávolításhoz. A változtatások automatikusan mentésre kerülnek.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Kockázati figyelmeztetés: Ez a szolgáltató olyan előfizetést/OAuth munkamenetet használ, amely hivatalosan nincs proxy/router használatra engedélyezve. A fiók korlátozható vagy letiltható. Saját felelősségre használja.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ A MITM elfogja az IDE eszközök (Antigravity, GitHub Copilot, Kiro) HTTPS forgalmát helyi CA-n keresztül, hogy átirányítsa a kéréseket a szolgáltatóidhoz. Megsértheti a ToS-t → fiók letiltási kockázat. Saját felelősségre használja.",
+  "Endpoint is exposed without an API key.": "A végpont API-kulcs nélkül van kitéve."
+}
diff --git a/public/i18n/literals/id.json b/public/i18n/literals/id.json
new file mode 100644
index 0000000..3e5097a
--- /dev/null
+++ b/public/i18n/literals/id.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Batalkan",
+  "Delete": "Hapus",
+  "Edit": "Sunting",
+  "Save": "Simpan",
+  "Close": "Tutup",
+  "Add": "Tambah",
+  "Remove": "Hapus",
+  "Settings": "Pengaturan",
+  "Profile": "Profil",
+  "Dashboard": "Dasbor",
+  "Logout": "Keluar",
+  "Login": "Masuk",
+  "Providers": "Penyedia",
+  "Usage": "Statistik Penggunaan",
+  "API Key": "Kunci API",
+  "Connected": "Terhubung",
+  "Disconnected": "Terputus",
+  "Active": "Aktif",
+  "Inactive": "Nonaktif",
+  "Success": "Berhasil",
+  "Failed": "Gagal",
+  "Error": "Kesalahan",
+  "Warning": "Peringatan",
+  "Info": "Informasi",
+  "Loading": "Memuat",
+  "Search": "Cari",
+  "Filter": "Saring",
+  "Sort": "Urutkan",
+  "Export": "Ekspor",
+  "Import": "Impor",
+  "Refresh": "Segarkan",
+  "Back": "Kembali",
+  "Next": "Berikutnya",
+  "Previous": "Sebelumnya",
+  "Submit": "Kirim",
+  "Confirm": "Konfirmasi",
+  "Yes": "Ya",
+  "No": "Tidak",
+  "OK": "OK",
+  "Apply": "Terapkan",
+  "Reset": "Atur Ulang",
+  "Clear": "Hapus",
+  "Select": "Pilih",
+  "Upload": "Unggah",
+  "Download": "Unduh",
+  "Copy": "Salin",
+  "Paste": "Tempel",
+  "Cut": "Potong",
+  "Undo": "Batalkan",
+  "Redo": "Ulangi",
+  "Name": "Nama",
+  "Description": "Deskripsi",
+  "Status": "Status",
+  "Type": "Jenis",
+  "Date": "Tanggal",
+  "Time": "Waktu",
+  "Created": "Dibuat",
+  "Updated": "Diperbarui",
+  "Actions": "Tindakan",
+  "Details": "Detail",
+  "View": "Lihat",
+  "New": "Baru",
+  "Total": "Total",
+  "Count": "Jumlah",
+  "Price": "Harga",
+  "Cost": "Biaya",
+  "Free": "Gratis",
+  "Paid": "Berbayar",
+  "Enable": "Aktifkan",
+  "Disable": "Nonaktifkan",
+  "Enabled": "Diaktifkan",
+  "Disabled": "Dinonaktifkan",
+  "Online": "Daring",
+  "Offline": "Luring",
+  "Available": "Tersedia",
+  "Unavailable": "Tidak Tersedia",
+  "Required": "Diperlukan",
+  "Optional": "Opsional",
+  "Default": "Bawaan",
+  "Custom": "Kustom",
+  "Advanced": "Lanjutan",
+  "Basic": "Dasar",
+  "Help": "Bantuan",
+  "Support": "Dukungan",
+  "Documentation": "Dokumentasi",
+  "Version": "Versi",
+  "Language": "Bahasa",
+  "Theme": "Tema",
+  "Light": "Terang",
+  "Dark": "Gelap",
+  "Auto": "Otomatis",
+  "Endpoint": "Titik Akhir",
+  "Combos": "Kombinasi",
+  "Quota Tracker": "Pelacak Kuota",
+  "MITM": "MITM",
+  "CLI Tools": "Alat",
+  "Console Log": "Log Konsol",
+  "System": "Sistem",
+  "Debug": "Debug",
+  "Shutdown": "Matikan",
+  "Close Proxy": "Tutup Proxy",
+  "Are you sure you want to close the proxy server?": "Apakah Anda yakin ingin menutup server proxy?",
+  "Server Disconnected": "Server Terputus",
+  "The proxy server has been stopped.": "Server proxy telah dihentikan.",
+  "Reload Page": "Muat Ulang Halaman",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Layanan sedang berjalan di terminal. Anda dapat menutup halaman web ini. Shutdown akan menghentikan layanan.",
+  "Manage your AI provider connections": "Kelola koneksi penyedia AI Anda",
+  "Model combos with fallback": "Kombinasi model dengan fallback",
+  "Monitor your API usage, token consumption, and request logs": "Pantau penggunaan API, konsumsi token, dan log permintaan Anda",
+  "Intercept CLI tool traffic and route through 9Router": "Intersep lalu lintas alat CLI dan rute melalui 9Router",
+  "Configure CLI tools": "Konfigurasi alat CLI",
+  "API endpoint configuration": "Konfigurasi titik akhir API",
+  "Manage your preferences": "Kelola preferensi Anda",
+  "Debug translation flow between formats": "Debug alur terjemahan antara format",
+  "Live server console output": "Output konsol server langsung",
+  "Create model combos with fallback support": "Buat kombinasi model dengan dukungan fallback",
+  "Local Mode": "Mode Lokal",
+  "Running on your machine": "Berjalan di mesin Anda",
+  "Database Location": "Lokasi Database",
+  "Download Backup": "Unduh Cadangan",
+  "Import Backup": "Impor Cadangan",
+  "Database backup downloaded": "Cadangan database telah diunduh",
+  "Database imported successfully": "Database berhasil diimpor",
+  "Security": "Keamanan",
+  "Require login": "Memerlukan Login",
+  "When ON, dashboard requires password. When OFF, access without login.": "Ketika AKTIF, dasbor memerlukan kata sandi. Ketika NONAKTIF, akses tanpa login.",
+  "Current Password": "Kata Sandi Saat Ini",
+  "Enter current password": "Masukkan kata sandi saat ini",
+  "New Password": "Kata Sandi Baru",
+  "Enter new password": "Masukkan kata sandi baru",
+  "Confirm New Password": "Konfirmasi Kata Sandi Baru",
+  "Confirm new password": "Konfirmasi kata sandi baru",
+  "Update Password": "Perbarui Kata Sandi",
+  "Set Password": "Atur Kata Sandi",
+  "Password updated successfully": "Kata sandi berhasil diperbarui",
+  "Passwords do not match": "Kata sandi tidak cocok",
+  "Routing Strategy": "Strategi Rute",
+  "Round Robin": "Putaran Bulat",
+  "Cycle through accounts to distribute load": "Siklus melalui akun untuk mendistribusikan beban",
+  "Sticky Limit": "Batas Lengket",
+  "Calls per account before switching": "Panggilan per akun sebelum beralih",
+  "Network": "Jaringan",
+  "Outbound Proxy": "Proxy Keluar",
+  "Enable proxy for OAuth + provider outbound requests.": "Aktifkan proxy untuk permintaan keluar OAuth + penyedia.",
+  "Proxy URL": "URL Proxy",
+  "Leave empty to inherit existing env proxy (if any).": "Biarkan kosong untuk mewarisi proxy env yang ada (jika ada).",
+  "No Proxy": "Tidak Ada Proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Nama host/domain yang dipisahkan koma untuk melewati proxy.",
+  "Test proxy URL": "Uji URL Proxy",
+  "Proxy settings applied": "Pengaturan proxy diterapkan",
+  "Proxy enabled": "Proxy diaktifkan",
+  "Proxy disabled": "Proxy dinonaktifkan",
+  "Proxy test OK": "Tes proxy OK",
+  "Proxy test failed": "Tes proxy gagal",
+  "Please enter a Proxy URL to test": "Masukkan URL Proxy untuk diuji",
+  "Observability": "Observabilitas",
+  "Enable Observability": "Aktifkan Observabilitas",
+  "Turn request detail recording on/off globally": "Aktifkan/nonaktifkan pencatatan detail permintaan secara global",
+  "Max Records": "Rekam Maksimal",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Rekam detail permintaan maksimal untuk disimpan (rekam lama otomatis dihapus)",
+  "Batch Size": "Ukuran Batch",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Jumlah item yang diakumulasikan sebelum menulis ke database (lebih tinggi = performa lebih baik)",
+  "Flush Interval (ms)": "Interval Flush (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Waktu maksimum untuk menunggu sebelum mem-flush buffer (mencegah kehilangan data saat lalu lintas rendah)",
+  "Max JSON Size (KB)": "Ukuran JSON Maks (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Ukuran maksimum untuk setiap bidang JSON (permintaan/respons) sebelum pemotongan",
+  "All data stored on your machine": "Semua data disimpan di mesin Anda",
+  "MITM Server": "Server MITM",
+  "Running": "Berjalan",
+  "Stopped": "Dihentikan",
+  "Cert": "Sertifikat",
+  "Server": "Server",
+  "Purpose:": "Tujuan:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Gunakan Antigravity IDE & GitHub Copilot → dengan PENYEDIA/model APA PUN dari 9Router",
+  "How it works:": "Cara kerjanya:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Permintaan Antigravity/Copilot IDE → Pengalihan DNS ke localhost:443 → Proxy MITM mengintersep → 9Router → respons ke Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Tidak ada kunci API — buat satu di halaman Keys",
+  "sk_9router (default)": "sk_9router (bawaan)",
+  "Server started": "Server dimulai",
+  "Failed to start server": "Gagal memulai server",
+  "Server stopped — all DNS cleared": "Server dihentikan — semua DNS dihapus",
+  "Failed to stop server": "Gagal menghentikan server",
+  "Sudo password is required": "Kata sandi sudo diperlukan",
+  "Stop Server": "Hentikan Server",
+  "Start Server": "Mulai Server",
+  "Enable DNS per tool below to activate interception": "Aktifkan DNS untuk setiap alat di bawah untuk mengaktifkan intersepsi",
+  "Sudo Password Required": "Kata Sandi Sudo Diperlukan",
+  "Enter your sudo password to start/stop MITM server": "Masukkan kata sandi sudo Anda untuk memulai/menghentikan server MITM",
+  "Sudo Password": "Kata Sandi Sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Klik untuk menambah, klik lagi untuk menghapus. Perubahan disimpan secara otomatis.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Pemberitahuan Risiko: Penyedia ini menggunakan sesi langganan/OAuth yang tidak dilisensikan secara resmi untuk penggunaan proxy/router. Akun mungkin dibatasi atau diblokir. Gunakan dengan risiko Anda sendiri.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM mencegat lalu lintas HTTPS alat IDE (Antigravity, GitHub Copilot, Kiro) melalui CA lokal untuk mengalihkan permintaan ke penyedia Anda. Mungkin melanggar ToS → risiko ban akun. Gunakan dengan risiko Anda sendiri.",
+  "Endpoint is exposed without an API key.": "Endpoint terekspos tanpa kunci API."
+}
diff --git a/public/i18n/literals/it.json b/public/i18n/literals/it.json
new file mode 100644
index 0000000..7f684e8
--- /dev/null
+++ b/public/i18n/literals/it.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Annulla",
+  "Delete": "Elimina",
+  "Edit": "Modifica",
+  "Save": "Salva",
+  "Close": "Chiudi",
+  "Add": "Aggiungi",
+  "Remove": "Rimuovi",
+  "Settings": "Impostazioni",
+  "Profile": "Profilo",
+  "Dashboard": "Pannello di controllo",
+  "Logout": "Esci",
+  "Login": "Accedi",
+  "Providers": "Provider",
+  "Usage": "Statistiche di utilizzo",
+  "API Key": "Chiave API",
+  "Connected": "Connesso",
+  "Disconnected": "Disconnesso",
+  "Active": "Attivo",
+  "Inactive": "Inattivo",
+  "Success": "Successo",
+  "Failed": "Non riuscito",
+  "Error": "Errore",
+  "Warning": "Avvertenza",
+  "Info": "Informazioni",
+  "Loading": "Caricamento",
+  "Search": "Cerca",
+  "Filter": "Filtro",
+  "Sort": "Ordina",
+  "Export": "Esporta",
+  "Import": "Importa",
+  "Refresh": "Aggiorna",
+  "Back": "Indietro",
+  "Next": "Avanti",
+  "Previous": "Precedente",
+  "Submit": "Invia",
+  "Confirm": "Conferma",
+  "Yes": "Sì",
+  "No": "No",
+  "OK": "OK",
+  "Apply": "Applica",
+  "Reset": "Ripristina",
+  "Clear": "Cancella",
+  "Select": "Seleziona",
+  "Upload": "Carica",
+  "Download": "Scarica",
+  "Copy": "Copia",
+  "Paste": "Incolla",
+  "Cut": "Taglia",
+  "Undo": "Annulla",
+  "Redo": "Ripeti",
+  "Name": "Nome",
+  "Description": "Descrizione",
+  "Status": "Stato",
+  "Type": "Tipo",
+  "Date": "Data",
+  "Time": "Ora",
+  "Created": "Creato",
+  "Updated": "Aggiornato",
+  "Actions": "Azioni",
+  "Details": "Dettagli",
+  "View": "Visualizza",
+  "New": "Nuovo",
+  "Total": "Totale",
+  "Count": "Conteggio",
+  "Price": "Prezzo",
+  "Cost": "Costo",
+  "Free": "Gratuito",
+  "Paid": "A pagamento",
+  "Enable": "Abilita",
+  "Disable": "Disabilita",
+  "Enabled": "Abilitato",
+  "Disabled": "Disabilitato",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Disponibile",
+  "Unavailable": "Non disponibile",
+  "Required": "Obbligatorio",
+  "Optional": "Opzionale",
+  "Default": "Predefinito",
+  "Custom": "Personalizzato",
+  "Advanced": "Avanzate",
+  "Basic": "Di base",
+  "Help": "Aiuto",
+  "Support": "Supporto",
+  "Documentation": "Documentazione",
+  "Version": "Versione",
+  "Language": "Lingua",
+  "Theme": "Tema",
+  "Light": "Chiaro",
+  "Dark": "Scuro",
+  "Auto": "Automatico",
+  "Endpoint": "Endpoint",
+  "Combos": "Combinazioni",
+  "Quota Tracker": "Tracker quota",
+  "MITM": "MITM",
+  "CLI Tools": "Strumenti",
+  "Console Log": "Log della console",
+  "System": "Sistema",
+  "Debug": "Debug",
+  "Shutdown": "Spegni",
+  "Close Proxy": "Chiudi proxy",
+  "Are you sure you want to close the proxy server?": "Sei sicuro di voler chiudere il server proxy?",
+  "Server Disconnected": "Server disconnesso",
+  "The proxy server has been stopped.": "Il server proxy è stato arrestato.",
+  "Reload Page": "Ricarica pagina",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Il servizio è in esecuzione nel terminale. Puoi chiudere questa pagina web. Lo spegnimento fermerà il servizio.",
+  "Manage your AI provider connections": "Gestisci le connessioni del tuo provider AI",
+  "Model combos with fallback": "Combinazioni di modelli con fallback",
+  "Monitor your API usage, token consumption, and request logs": "Monitora l'utilizzo dell'API, il consumo di token e i log delle richieste",
+  "Intercept CLI tool traffic and route through 9Router": "Intercetta il traffico dello strumento CLI e instradalo attraverso 9Router",
+  "Configure CLI tools": "Configura gli strumenti CLI",
+  "API endpoint configuration": "Configurazione dell'endpoint API",
+  "Manage your preferences": "Gestisci le tue preferenze",
+  "Debug translation flow between formats": "Debug del flusso di traduzione tra i formati",
+  "Live server console output": "Output della console del server in tempo reale",
+  "Create model combos with fallback support": "Crea combinazioni di modelli con supporto fallback",
+  "Local Mode": "Modalità locale",
+  "Running on your machine": "In esecuzione sulla tua macchina",
+  "Database Location": "Posizione del database",
+  "Download Backup": "Scarica backup",
+  "Import Backup": "Importa backup",
+  "Database backup downloaded": "Backup del database scaricato",
+  "Database imported successfully": "Database importato con successo",
+  "Security": "Sicurezza",
+  "Require login": "Richiedi accesso",
+  "When ON, dashboard requires password. When OFF, access without login.": "Quando ATTIVO, il pannello di controllo richiede la password. Quando SPENTO, accedi senza login.",
+  "Current Password": "Password attuale",
+  "Enter current password": "Inserisci la password attuale",
+  "New Password": "Nuova password",
+  "Enter new password": "Inserisci la nuova password",
+  "Confirm New Password": "Conferma nuova password",
+  "Confirm new password": "Conferma la nuova password",
+  "Update Password": "Aggiorna password",
+  "Set Password": "Imposta password",
+  "Password updated successfully": "Password aggiornata con successo",
+  "Passwords do not match": "Le password non corrispondono",
+  "Routing Strategy": "Strategia di routing",
+  "Round Robin": "Round robin",
+  "Cycle through accounts to distribute load": "Scorri gli account per distribuire il carico",
+  "Sticky Limit": "Limite appiccicoso",
+  "Calls per account before switching": "Chiamate per account prima del passaggio",
+  "Network": "Rete",
+  "Outbound Proxy": "Proxy in uscita",
+  "Enable proxy for OAuth + provider outbound requests.": "Abilita il proxy per le richieste in uscita OAuth + provider.",
+  "Proxy URL": "URL proxy",
+  "Leave empty to inherit existing env proxy (if any).": "Lascia vuoto per ereditare il proxy env esistente (se presente).",
+  "No Proxy": "Nessun proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Nomi host/domini separati da virgole per ignorare il proxy.",
+  "Test proxy URL": "Test URL proxy",
+  "Proxy settings applied": "Impostazioni proxy applicate",
+  "Proxy enabled": "Proxy abilitato",
+  "Proxy disabled": "Proxy disabilitato",
+  "Proxy test OK": "Test proxy OK",
+  "Proxy test failed": "Test proxy non riuscito",
+  "Please enter a Proxy URL to test": "Inserisci un URL proxy da testare",
+  "Observability": "Osservabilità",
+  "Enable Observability": "Abilita osservabilità",
+  "Turn request detail recording on/off globally": "Attiva/disattiva la registrazione dei dettagli della richiesta globalmente",
+  "Max Records": "Record massimi",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Record di dettagli della richiesta massimi da mantenere (i record più vecchi vengono eliminati automaticamente)",
+  "Batch Size": "Dimensione batch",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Numero di elementi da accumulare prima di scrivere nel database (più alto = migliori prestazioni)",
+  "Flush Interval (ms)": "Intervallo di scaricamento (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Tempo massimo di attesa prima dello scaricamento del buffer (previene la perdita di dati durante il traffico basso)",
+  "Max JSON Size (KB)": "Dimensione JSON massima (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Dimensione massima per ogni campo JSON (richiesta/risposta) prima del troncamento",
+  "All data stored on your machine": "Tutti i dati memorizzati sulla tua macchina",
+  "MITM Server": "Server MITM",
+  "Running": "In esecuzione",
+  "Stopped": "Arrestato",
+  "Cert": "Certificato",
+  "Server": "Server",
+  "Purpose:": "Scopo:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Usa Antigravity IDE & GitHub Copilot → con QUALSIASI provider/modello da 9Router",
+  "How it works:": "Come funziona:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Richiesta Antigravity/Copilot IDE → Reindirizzamento DNS a localhost:443 → Il proxy MITM intercetta → 9Router → Risposta a Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Nessuna chiave API — crearne una nella pagina Chiavi",
+  "sk_9router (default)": "sk_9router (predefinito)",
+  "Server started": "Server avviato",
+  "Failed to start server": "Impossibile avviare il server",
+  "Server stopped — all DNS cleared": "Server arrestato — tutti i DNS cancellati",
+  "Failed to stop server": "Impossibile arrestare il server",
+  "Sudo password is required": "La password sudo è obbligatoria",
+  "Stop Server": "Arresta server",
+  "Start Server": "Avvia server",
+  "Enable DNS per tool below to activate interception": "Abilita DNS per ogni strumento sottostante per attivare l'intercettazione",
+  "Sudo Password Required": "Password Sudo richiesta",
+  "Enter your sudo password to start/stop MITM server": "Inserisci la tua password sudo per avviare/arrestare il server MITM",
+  "Sudo Password": "Password Sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Clicca per aggiungere, clicca di nuovo per rimuovere. Le modifiche vengono salvate automaticamente.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Avviso di Rischio: Questo provider utilizza una sessione abbonamento/OAuth non ufficialmente autorizzata per l'uso proxy/router. L'account potrebbe essere limitato o bannato. Usa a tuo rischio.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM intercetta il traffico HTTPS degli strumenti IDE (Antigravity, GitHub Copilot, Kiro) tramite CA locale per reindirizzare le richieste ai tuoi provider. Può violare i ToS → rischio ban account. Usa a tuo rischio.",
+  "Endpoint is exposed without an API key.": "L'endpoint è esposto senza una chiave API."
+}
diff --git a/public/i18n/literals/ja.json b/public/i18n/literals/ja.json
new file mode 100644
index 0000000..e448c68
--- /dev/null
+++ b/public/i18n/literals/ja.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "キャンセル",
+  "Delete": "削除",
+  "Edit": "編集",
+  "Save": "保存",
+  "Close": "閉じる",
+  "Add": "追加",
+  "Remove": "削除",
+  "Settings": "設定",
+  "Profile": "プロフィール",
+  "Dashboard": "ダッシュボード",
+  "Logout": "ログアウト",
+  "Login": "ログイン",
+  "Providers": "プロバイダー",
+  "Usage": "統計",
+  "API Key": "APIキー",
+  "Connected": "接続済み",
+  "Disconnected": "未接続",
+  "Active": "アクティブ",
+  "Inactive": "非アクティブ",
+  "Success": "成功",
+  "Failed": "失敗",
+  "Error": "エラー",
+  "Warning": "警告",
+  "Info": "情報",
+  "Loading": "読み込み中",
+  "Search": "検索",
+  "Filter": "フィルター",
+  "Sort": "並べ替え",
+  "Export": "エクスポート",
+  "Import": "インポート",
+  "Refresh": "更新",
+  "Back": "戻る",
+  "Next": "次へ",
+  "Previous": "前へ",
+  "Submit": "送信",
+  "Confirm": "確認",
+  "Yes": "はい",
+  "No": "いいえ",
+  "OK": "OK",
+  "Apply": "適用",
+  "Reset": "リセット",
+  "Clear": "クリア",
+  "Select": "選択",
+  "Upload": "アップロード",
+  "Download": "ダウンロード",
+  "Copy": "コピー",
+  "Paste": "貼り付け",
+  "Cut": "切り取り",
+  "Undo": "元に戻す",
+  "Redo": "やり直す",
+  "Name": "名前",
+  "Description": "説明",
+  "Status": "ステータス",
+  "Type": "タイプ",
+  "Date": "日付",
+  "Time": "時間",
+  "Created": "作成済み",
+  "Updated": "更新済み",
+  "Actions": "アクション",
+  "Details": "詳細",
+  "View": "表示",
+  "New": "新規",
+  "Total": "合計",
+  "Count": "カウント",
+  "Price": "価格",
+  "Cost": "コスト",
+  "Free": "無料",
+  "Paid": "有料",
+  "Enable": "有効",
+  "Disable": "無効",
+  "Enabled": "有効化済み",
+  "Disabled": "無効化済み",
+  "Online": "オンライン",
+  "Offline": "オフライン",
+  "Available": "利用可能",
+  "Unavailable": "利用不可",
+  "Required": "必須",
+  "Optional": "オプション",
+  "Default": "デフォルト",
+  "Custom": "カスタム",
+  "Advanced": "詳細",
+  "Basic": "基本",
+  "Help": "ヘルプ",
+  "Support": "サポート",
+  "Documentation": "ドキュメント",
+  "Version": "バージョン",
+  "Language": "言語",
+  "Theme": "テーマ",
+  "Light": "ライト",
+  "Dark": "ダーク",
+  "Auto": "自動",
+  "Endpoint": "エンドポイント",
+  "Combos": "コンボ",
+  "Quota Tracker": "クォータトラッカー",
+  "MITM": "MITM",
+  "CLI Tools": "CLIツール",
+  "Console Log": "コンソールログ",
+  "System": "システム",
+  "Debug": "デバッグ",
+  "Shutdown": "シャットダウン",
+  "Close Proxy": "プロキシを閉じる",
+  "Are you sure you want to close the proxy server?": "プロキシサーバーを閉じてもよろしいですか？",
+  "Server Disconnected": "サーバーが切断されました",
+  "The proxy server has been stopped.": "プロキシサーバーが停止しました。",
+  "Reload Page": "ページを再読み込み",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "サービスはターミナルで実行されています。このウェブページを閉じることができます。シャットダウンはサービスを停止します。",
+  "Manage your AI provider connections": "AIプロバイダーの接続を管理する",
+  "Model combos with fallback": "フォールバック付きモデルコンボ",
+  "Monitor your API usage, token consumption, and request logs": "APIの使用状況、トークン消費量、およびリクエストログを監視する",
+  "Intercept CLI tool traffic and route through 9Router": "CLIツールのトラフィックをインターセプトし、9Routerを通じてルーティングする",
+  "Configure CLI tools": "CLIツールを構成",
+  "API endpoint configuration": "APIエンドポイント構成",
+  "Manage your preferences": "設定を管理する",
+  "Debug translation flow between formats": "形式間の翻訳フローをデバッグ",
+  "Live server console output": "ライブサーバーコンソール出力",
+  "Create model combos with fallback support": "フォールバックサポート付きモデルコンボを作成",
+  "Local Mode": "ローカルモード",
+  "Running on your machine": "お使いのマシンで実行中",
+  "Database Location": "データベースの場所",
+  "Download Backup": "バックアップをダウンロード",
+  "Import Backup": "バックアップをインポート",
+  "Database backup downloaded": "データベースバックアップがダウンロードされました",
+  "Database imported successfully": "データベースが正常にインポートされました",
+  "Security": "セキュリティ",
+  "Require login": "ログインが必要",
+  "When ON, dashboard requires password. When OFF, access without login.": "ON の場合、ダッシュボードはパスワードが必要です。OFF の場合、ログインなしでアクセスできます。",
+  "Current Password": "現在のパスワード",
+  "Enter current password": "現在のパスワードを入力",
+  "New Password": "新しいパスワード",
+  "Enter new password": "新しいパスワードを入力",
+  "Confirm New Password": "新しいパスワードを確認",
+  "Confirm new password": "新しいパスワードを確認",
+  "Update Password": "パスワードを更新",
+  "Set Password": "パスワードを設定",
+  "Password updated successfully": "パスワードが正常に更新されました",
+  "Passwords do not match": "パスワードが一致しません",
+  "Routing Strategy": "ルーティング戦略",
+  "Round Robin": "ラウンドロビン",
+  "Cycle through accounts to distribute load": "アカウント間を循環してロードを分散",
+  "Sticky Limit": "スティッキーリミット",
+  "Calls per account before switching": "切り替え前のアカウントごとのコール数",
+  "Network": "ネットワーク",
+  "Outbound Proxy": "アウトバウンドプロキシ",
+  "Enable proxy for OAuth + provider outbound requests.": "OAuth + プロバイダーアウトバウンドリクエストのプロキシを有効にします。",
+  "Proxy URL": "プロキシURL",
+  "Leave empty to inherit existing env proxy (if any).": "既存の環境プロキシを継承するには空のままにしてください。",
+  "No Proxy": "プロキシなし",
+  "Comma-separated hostnames/domains to bypass the proxy.": "プロキシをバイパスするためのコンマ区切りのホスト名/ドメイン。",
+  "Test proxy URL": "プロキシURLをテスト",
+  "Proxy settings applied": "プロキシ設定が適用されました",
+  "Proxy enabled": "プロキシが有効になりました",
+  "Proxy disabled": "プロキシが無効になりました",
+  "Proxy test OK": "プロキシテストOK",
+  "Proxy test failed": "プロキシテストが失敗しました",
+  "Please enter a Proxy URL to test": "テストするプロキシURLを入力してください",
+  "Observability": "可観測性",
+  "Enable Observability": "可観測性を有効にする",
+  "Turn request detail recording on/off globally": "リクエスト詳細記録をグローバルにオン/オフにします",
+  "Max Records": "最大レコード数",
+  "Maximum request detail records to keep (older records are auto-deleted)": "保持するリクエスト詳細レコードの最大数（古いレコードは自動削除されます）",
+  "Batch Size": "バッチサイズ",
+  "Number of items to accumulate before writing to database (higher = better performance)": "データベースに書き込む前に蓄積するアイテム数（高い = パフォーマンス向上）",
+  "Flush Interval (ms)": "フラッシュ間隔 (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "バッファをフラッシュする前の最大待機時間（低トラフィック中のデータ損失を防ぎます）",
+  "Max JSON Size (KB)": "最大JSON サイズ (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "切り詰め前の各JSONフィールド（リクエスト/レスポンス）の最大サイズ",
+  "All data stored on your machine": "すべてのデータがお使いのマシンに保存されます",
+  "MITM Server": "MITMサーバー",
+  "Running": "実行中",
+  "Stopped": "停止済み",
+  "Cert": "証明書",
+  "Server": "サーバー",
+  "Purpose:": "目的：",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Antigravity IDE & GitHub Copilot → 9Router の任意のプロバイダー/モデルを使用",
+  "How it works:": "しくみ：",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE リクエスト → localhost:443 への DNS リダイレクト → MITM プロキシが傍受 → 9Router → Antigravity/Copilot への応答",
+  "No API keys — create one in Keys page": "APIキーがありません — キーページで1つ作成してください",
+  "sk_9router (default)": "sk_9router（デフォルト）",
+  "Server started": "サーバーが開始されました",
+  "Failed to start server": "サーバーの開始に失敗しました",
+  "Server stopped — all DNS cleared": "サーバーが停止しました — すべてのDNSがクリアされました",
+  "Failed to stop server": "サーバーの停止に失敗しました",
+  "Sudo password is required": "Sudoパスワードが必要です",
+  "Stop Server": "サーバーを停止",
+  "Start Server": "サーバーを開始",
+  "Enable DNS per tool below to activate interception": "以下の各ツールに対してDNSを有効にして、傍受をアクティブにします",
+  "Sudo Password Required": "Sudoパスワードが必要です",
+  "Enter your sudo password to start/stop MITM server": "MITMサーバーを開始/停止するには、sudoパスワードを入力してください",
+  "Sudo Password": "Sudoパスワード",
+  "Click to add, click again to remove. Changes are saved automatically.": "クリックで追加、もう一度クリックで削除。変更は自動的に保存されます。",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ リスク通知: このプロバイダーは、プロキシ/ルーター使用について公式にライセンスされていないサブスクリプション/OAuthセッションを使用しています。アカウントが制限または禁止される可能性があります。自己責任でご使用ください。",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITMはローカルCAを介してIDEツール (Antigravity, GitHub Copilot, Kiro) のHTTPSトラフィックを傍受し、リクエストをプロバイダーにリダイレクトします。ToS違反の可能性 → アカウントBANリスク。自己責任でご使用ください。",
+  "Endpoint is exposed without an API key.": "API キーなしでエンドポイントが公開されています。"
+}
diff --git a/public/i18n/literals/ko.json b/public/i18n/literals/ko.json
new file mode 100644
index 0000000..1edb094
--- /dev/null
+++ b/public/i18n/literals/ko.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "취소",
+  "Delete": "삭제",
+  "Edit": "편집",
+  "Save": "저장",
+  "Close": "닫기",
+  "Add": "추가",
+  "Remove": "제거",
+  "Settings": "설정",
+  "Profile": "프로필",
+  "Dashboard": "대시보드",
+  "Logout": "로그아웃",
+  "Login": "로그인",
+  "Providers": "제공자",
+  "Usage": "통계",
+  "API Key": "API 키",
+  "Connected": "연결됨",
+  "Disconnected": "연결 해제됨",
+  "Active": "활성",
+  "Inactive": "비활성",
+  "Success": "성공",
+  "Failed": "실패",
+  "Error": "오류",
+  "Warning": "경고",
+  "Info": "정보",
+  "Loading": "로딩 중",
+  "Search": "검색",
+  "Filter": "필터",
+  "Sort": "정렬",
+  "Export": "내보내기",
+  "Import": "가져오기",
+  "Refresh": "새로고침",
+  "Back": "뒤로",
+  "Next": "다음",
+  "Previous": "이전",
+  "Submit": "제출",
+  "Confirm": "확인",
+  "Yes": "예",
+  "No": "아니오",
+  "OK": "확인",
+  "Apply": "적용",
+  "Reset": "재설정",
+  "Clear": "지우기",
+  "Select": "선택",
+  "Upload": "업로드",
+  "Download": "다운로드",
+  "Copy": "복사",
+  "Paste": "붙여넣기",
+  "Cut": "잘라내기",
+  "Undo": "실행 취소",
+  "Redo": "다시 실행",
+  "Name": "이름",
+  "Description": "설명",
+  "Status": "상태",
+  "Type": "유형",
+  "Date": "날짜",
+  "Time": "시간",
+  "Created": "생성됨",
+  "Updated": "업데이트됨",
+  "Actions": "작업",
+  "Details": "세부정보",
+  "View": "보기",
+  "New": "새로 만들기",
+  "Total": "합계",
+  "Count": "개수",
+  "Price": "가격",
+  "Cost": "비용",
+  "Free": "무료",
+  "Paid": "유료",
+  "Enable": "활성화",
+  "Disable": "비활성화",
+  "Enabled": "활성화됨",
+  "Disabled": "비활성화됨",
+  "Online": "온라인",
+  "Offline": "오프라인",
+  "Available": "사용 가능",
+  "Unavailable": "사용 불가",
+  "Required": "필수",
+  "Optional": "선택사항",
+  "Default": "기본값",
+  "Custom": "사용자 지정",
+  "Advanced": "고급",
+  "Basic": "기본",
+  "Help": "도움말",
+  "Support": "지원",
+  "Documentation": "설명서",
+  "Version": "버전",
+  "Language": "언어",
+  "Theme": "테마",
+  "Light": "밝음",
+  "Dark": "어두움",
+  "Auto": "자동",
+  "Endpoint": "엔드포인트",
+  "Combos": "조합",
+  "Quota Tracker": "할당량 추적",
+  "MITM": "MITM",
+  "CLI Tools": "CLI 도구",
+  "Console Log": "콘솔 로그",
+  "System": "시스템",
+  "Debug": "디버깅",
+  "Shutdown": "종료",
+  "Close Proxy": "프록시 닫기",
+  "Are you sure you want to close the proxy server?": "프록시 서버를 닫으시겠습니까?",
+  "Server Disconnected": "서버 연결 해제됨",
+  "The proxy server has been stopped.": "프록시 서버가 중지되었습니다.",
+  "Reload Page": "페이지 다시 로드",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "서비스가 터미널에서 실행 중입니다. 이 웹 페이지를 닫을 수 있습니다. 종료하면 서비스가 중지됩니다.",
+  "Manage your AI provider connections": "AI 제공자 연결 관리",
+  "Model combos with fallback": "폴백 기능이 있는 모델 조합",
+  "Monitor your API usage, token consumption, and request logs": "API 사용, 토큰 소비 및 요청 로그 모니터링",
+  "Intercept CLI tool traffic and route through 9Router": "CLI 도구 트래픽을 가로채고 9Router를 통해 라우팅",
+  "Configure CLI tools": "CLI 도구 구성",
+  "API endpoint configuration": "API 엔드포인트 구성",
+  "Manage your preferences": "기본 설정 관리",
+  "Debug translation flow between formats": "형식 간 변환 흐름 디버깅",
+  "Live server console output": "라이브 서버 콘솔 출력",
+  "Create model combos with fallback support": "폴백 지원이 있는 모델 조합 만들기",
+  "Local Mode": "로컬 모드",
+  "Running on your machine": "컴퓨터에서 실행 중",
+  "Database Location": "데이터베이스 위치",
+  "Download Backup": "백업 다운로드",
+  "Import Backup": "백업 가져오기",
+  "Database backup downloaded": "데이터베이스 백업 다운로드됨",
+  "Database imported successfully": "데이터베이스를 성공적으로 가져왔습니다",
+  "Security": "보안",
+  "Require login": "로그인 필요",
+  "When ON, dashboard requires password. When OFF, access without login.": "ON일 때 대시보드에서 암호가 필요합니다. OFF일 때 로그인 없이 접근할 수 있습니다.",
+  "Current Password": "현재 암호",
+  "Enter current password": "현재 암호 입력",
+  "New Password": "새 암호",
+  "Enter new password": "새 암호 입력",
+  "Confirm New Password": "새 암호 확인",
+  "Confirm new password": "새 암호 확인",
+  "Update Password": "암호 업데이트",
+  "Set Password": "암호 설정",
+  "Password updated successfully": "암호가 성공적으로 업데이트되었습니다",
+  "Passwords do not match": "암호가 일치하지 않습니다",
+  "Routing Strategy": "라우팅 전략",
+  "Round Robin": "라운드 로빈",
+  "Cycle through accounts to distribute load": "계정을 순환하여 로드 분산",
+  "Sticky Limit": "고정 제한",
+  "Calls per account before switching": "전환 전 계정당 호출 수",
+  "Network": "네트워크",
+  "Outbound Proxy": "아웃바운드 프록시",
+  "Enable proxy for OAuth + provider outbound requests.": "OAuth + 제공자 아웃바운드 요청에 대한 프록시를 활성화합니다.",
+  "Proxy URL": "프록시 URL",
+  "Leave empty to inherit existing env proxy (if any).": "기존 환경 프록시를 상속받으려면 비워두세요.",
+  "No Proxy": "프록시 없음",
+  "Comma-separated hostnames/domains to bypass the proxy.": "프록시를 우회하기 위한 쉼표로 구분된 호스트명/도메인입니다.",
+  "Test proxy URL": "프록시 URL 테스트",
+  "Proxy settings applied": "프록시 설정이 적용되었습니다",
+  "Proxy enabled": "프록시 활성화됨",
+  "Proxy disabled": "프록시 비활성화됨",
+  "Proxy test OK": "프록시 테스트 성공",
+  "Proxy test failed": "프록시 테스트 실패",
+  "Please enter a Proxy URL to test": "테스트할 프록시 URL을 입력하세요",
+  "Observability": "관찰 가능성",
+  "Enable Observability": "관찰 가능성 활성화",
+  "Turn request detail recording on/off globally": "요청 세부 정보 기록을 전역적으로 켜기/끄기",
+  "Max Records": "최대 레코드",
+  "Maximum request detail records to keep (older records are auto-deleted)": "보관할 최대 요청 세부 정보 레코드(오래된 레코드는 자동 삭제됨)",
+  "Batch Size": "배치 크기",
+  "Number of items to accumulate before writing to database (higher = better performance)": "데이터베이스에 쓰기 전에 누적할 항목 수(높을수록 더 나은 성능)",
+  "Flush Interval (ms)": "플러시 간격 (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "버퍼를 플러시하기 전 최대 대기 시간(낮은 트래픽 중 데이터 손실 방지)",
+  "Max JSON Size (KB)": "최대 JSON 크기 (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "자르기 전 각 JSON 필드(요청/응답)의 최대 크기",
+  "All data stored on your machine": "모든 데이터가 컴퓨터에 저장됨",
+  "MITM Server": "MITM 서버",
+  "Running": "실행 중",
+  "Stopped": "중지됨",
+  "Cert": "인증서",
+  "Server": "서버",
+  "Purpose:": "목적:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Antigravity IDE 및 GitHub Copilot 사용 → 9Router의 모든 제공자/모델과 함께",
+  "How it works:": "작동 방식:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE 요청 → localhost:443로 DNS 리디렉션 → MITM 프록시가 가로챔 → 9Router → Antigravity/Copilot으로 응답",
+  "No API keys — create one in Keys page": "API 키 없음 — 키 페이지에서 만들기",
+  "sk_9router (default)": "sk_9router (기본값)",
+  "Server started": "서버 시작됨",
+  "Failed to start server": "서버 시작 실패",
+  "Server stopped — all DNS cleared": "서버 중지됨 — 모든 DNS 지워짐",
+  "Failed to stop server": "서버 중지 실패",
+  "Sudo password is required": "Sudo 암호가 필요합니다",
+  "Stop Server": "서버 중지",
+  "Start Server": "서버 시작",
+  "Enable DNS per tool below to activate interception": "아래 각 도구에 대해 DNS를 활성화하여 가로채기 활성화",
+  "Sudo Password Required": "Sudo 암호 필요",
+  "Enter your sudo password to start/stop MITM server": "MITM 서버를 시작/중지하려면 sudo 암호를 입력하세요",
+  "Sudo Password": "Sudo 암호",
+  "Click to add, click again to remove. Changes are saved automatically.": "클릭하여 추가, 다시 클릭하여 제거. 변경 사항은 자동으로 저장됩니다.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ 위험 알림: 이 공급자는 프록시/라우터 사용에 대해 공식적으로 라이선스가 부여되지 않은 구독/OAuth 세션을 사용합니다. 계정이 제한되거나 차단될 수 있습니다. 사용에 대한 책임은 본인에게 있습니다.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM은 로컬 CA를 통해 IDE 도구(Antigravity, GitHub Copilot, Kiro)의 HTTPS 트래픽을 가로채 요청을 공급자로 리다이렉트합니다. ToS 위반 가능성 → 계정 차단 위험. 사용에 대한 책임은 본인에게 있습니다.",
+  "Endpoint is exposed without an API key.": "API 키 없이 엔드포인트가 노출되어 있습니다."
+}
diff --git a/public/i18n/literals/nl.json b/public/i18n/literals/nl.json
new file mode 100644
index 0000000..2eab85b
--- /dev/null
+++ b/public/i18n/literals/nl.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Annuleren",
+  "Delete": "Verwijderen",
+  "Edit": "Bewerken",
+  "Save": "Opslaan",
+  "Close": "Sluiten",
+  "Add": "Toevoegen",
+  "Remove": "Verwijderen",
+  "Settings": "Instellingen",
+  "Profile": "Profiel",
+  "Dashboard": "Dashboard",
+  "Logout": "Afmelden",
+  "Login": "Aanmelden",
+  "Providers": "Providers",
+  "Usage": "Statistieken",
+  "API Key": "API-sleutel",
+  "Connected": "Verbonden",
+  "Disconnected": "Verbroken",
+  "Active": "Actief",
+  "Inactive": "Inactief",
+  "Success": "Succes",
+  "Failed": "Mislukt",
+  "Error": "Fout",
+  "Warning": "Waarschuwing",
+  "Info": "Info",
+  "Loading": "Laden",
+  "Search": "Zoeken",
+  "Filter": "Filteren",
+  "Sort": "Sorteren",
+  "Export": "Exporteren",
+  "Import": "Importeren",
+  "Refresh": "Vernieuwen",
+  "Back": "Terug",
+  "Next": "Volgende",
+  "Previous": "Vorige",
+  "Submit": "Verzenden",
+  "Confirm": "Bevestigen",
+  "Yes": "Ja",
+  "No": "Nee",
+  "OK": "OK",
+  "Apply": "Toepassen",
+  "Reset": "Opnieuw instellen",
+  "Clear": "Wissen",
+  "Select": "Selecteren",
+  "Upload": "Uploaden",
+  "Download": "Downloaden",
+  "Copy": "Kopieëren",
+  "Paste": "Plakken",
+  "Cut": "Knippen",
+  "Undo": "Ongedaan maken",
+  "Redo": "Opnieuw uitvoeren",
+  "Name": "Naam",
+  "Description": "Beschrijving",
+  "Status": "Status",
+  "Type": "Type",
+  "Date": "Datum",
+  "Time": "Tijd",
+  "Created": "Gemaakt",
+  "Updated": "Bijgewerkt",
+  "Actions": "Acties",
+  "Details": "Details",
+  "View": "Weergeven",
+  "New": "Nieuw",
+  "Total": "Totaal",
+  "Count": "Aantal",
+  "Price": "Prijs",
+  "Cost": "Kosten",
+  "Free": "Gratis",
+  "Paid": "Betaald",
+  "Enable": "Inschakelen",
+  "Disable": "Uitschakelen",
+  "Enabled": "Ingeschakeld",
+  "Disabled": "Uitgeschakeld",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Beschikbaar",
+  "Unavailable": "Niet beschikbaar",
+  "Required": "Verplicht",
+  "Optional": "Optioneel",
+  "Default": "Standaard",
+  "Custom": "Aangepast",
+  "Advanced": "Geavanceerd",
+  "Basic": "Basis",
+  "Help": "Help",
+  "Support": "Ondersteuning",
+  "Documentation": "Documentatie",
+  "Version": "Versie",
+  "Language": "Taal",
+  "Theme": "Thema",
+  "Light": "Licht",
+  "Dark": "Donker",
+  "Auto": "Automatisch",
+  "Endpoint": "Eindpunt",
+  "Combos": "Combinaties",
+  "Quota Tracker": "Quotabijhouder",
+  "MITM": "MITM",
+  "CLI Tools": "CLI-tools",
+  "Console Log": "Consolenlogboek",
+  "System": "Systeem",
+  "Debug": "Foutopsporing",
+  "Shutdown": "Afsluiten",
+  "Close Proxy": "Proxy sluiten",
+  "Are you sure you want to close the proxy server?": "Weet u zeker dat u de proxyserver wilt sluiten?",
+  "Server Disconnected": "Server verbroken",
+  "The proxy server has been stopped.": "De proxyserver is gestopt.",
+  "Reload Page": "Pagina vernieuwen",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Service wordt uitgevoerd in terminal. U kunt deze webpagina sluiten. Afsluiten stopt de service.",
+  "Manage your AI provider connections": "Beheer uw AI-providerverbindingen",
+  "Model combos with fallback": "Modelcombinaties met fallback",
+  "Monitor your API usage, token consumption, and request logs": "Controleer uw API-gebruik, tokenverbruik en aanvraaglogboeken",
+  "Intercept CLI tool traffic and route through 9Router": "Onderschep CLI-toolverkeer en stuur het via 9Router",
+  "Configure CLI tools": "CLI-tools configureren",
+  "API endpoint configuration": "Configuratie van API-eindpunt",
+  "Manage your preferences": "Beheer uw voorkeuren",
+  "Debug translation flow between formats": "Debug de vertaalstroom tussen indelingen",
+  "Live server console output": "Live-serverconsoluitvoer",
+  "Create model combos with fallback support": "Maak modelcombinaties met fallback-ondersteuning",
+  "Local Mode": "Lokale modus",
+  "Running on your machine": "Actief op uw machine",
+  "Database Location": "Databaselocatie",
+  "Download Backup": "Backup downloaden",
+  "Import Backup": "Backup importeren",
+  "Database backup downloaded": "Databaseback-up gedownload",
+  "Database imported successfully": "Database succesvol geïmporteerd",
+  "Security": "Beveiliging",
+  "Require login": "Aanmelden vereist",
+  "When ON, dashboard requires password. When OFF, access without login.": "Wanneer AAN, vereist dashboard een wachtwoord. Wanneer UIT, toegang zonder aanmelden.",
+  "Current Password": "Huidig wachtwoord",
+  "Enter current password": "Voer het huidige wachtwoord in",
+  "New Password": "Nieuw wachtwoord",
+  "Enter new password": "Voer een nieuw wachtwoord in",
+  "Confirm New Password": "Nieuw wachtwoord bevestigen",
+  "Confirm new password": "Bevestig het nieuwe wachtwoord",
+  "Update Password": "Wachtwoord bijwerken",
+  "Set Password": "Wachtwoord instellen",
+  "Password updated successfully": "Wachtwoord succesvol bijgewerkt",
+  "Passwords do not match": "Wachtwoorden komen niet overeen",
+  "Routing Strategy": "Routeringsstrategie",
+  "Round Robin": "Round Robin",
+  "Cycle through accounts to distribute load": "Wisselen tussen accounts om belasting te verdelen",
+  "Sticky Limit": "Plakkerige limiet",
+  "Calls per account before switching": "Oproepen per account voordat u overschakelt",
+  "Network": "Netwerk",
+  "Outbound Proxy": "Uitgaande proxy",
+  "Enable proxy for OAuth + provider outbound requests.": "Schakel proxy in voor OAuth + uitgaande verzoeken van provider.",
+  "Proxy URL": "Proxy-URL",
+  "Leave empty to inherit existing env proxy (if any).": "Laat leeg om bestaande env-proxy over te nemen (indien aanwezig).",
+  "No Proxy": "Geen proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Door komma's gescheiden hostnamen/domeinen om de proxy te omzeilen.",
+  "Test proxy URL": "Proxy-URL testen",
+  "Proxy settings applied": "Proxy-instellingen toegepast",
+  "Proxy enabled": "Proxy ingeschakeld",
+  "Proxy disabled": "Proxy uitgeschakeld",
+  "Proxy test OK": "Proxy-test OK",
+  "Proxy test failed": "Proxy-test mislukt",
+  "Please enter a Proxy URL to test": "Voer een proxy-URL in om te testen",
+  "Observability": "Waarneembaarheid",
+  "Enable Observability": "Waarneembaarheid inschakelen",
+  "Turn request detail recording on/off globally": "Recordering van aanvraagdetails globaal in-/uitschakelen",
+  "Max Records": "Maximale records",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Maximale aantal aanvraagdetailrecords om te behouden (oudere records worden automatisch verwijderd)",
+  "Batch Size": "Batchgrootte",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Aantal items dat moet worden verzameld voordat naar database wordt geschreven (hoger = beter prestaties)",
+  "Flush Interval (ms)": "Spoelinterval (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Maximale wachttijd voordat buffer wordt leeggemaakt (voorkomt gegevensverlies bij laag verkeer)",
+  "Max JSON Size (KB)": "Maximale JSON-grootte (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Maximale grootte voor elk JSON-veld (aanvraag/antwoord) voordat afkappen",
+  "All data stored on your machine": "Alle gegevens opgeslagen op uw machine",
+  "MITM Server": "MITM-server",
+  "Running": "Actief",
+  "Stopped": "Gestopt",
+  "Cert": "Certificaat",
+  "Server": "Server",
+  "Purpose:": "Doel:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Gebruik Antigravity IDE en GitHub Copilot → met ELKE provider/model van 9Router",
+  "How it works:": "Hoe het werkt:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE-aanvraag → DNS-omleiding naar localhost:443 → MITM-proxy onderschept → 9Router → antwoord naar Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Geen API-sleutels — maak er één aan op de pagina Sleutels",
+  "sk_9router (default)": "sk_9router (standaard)",
+  "Server started": "Server gestart",
+  "Failed to start server": "Server starten mislukt",
+  "Server stopped — all DNS cleared": "Server gestopt — alle DNS gewist",
+  "Failed to stop server": "Server stoppen mislukt",
+  "Sudo password is required": "Sudo-wachtwoord vereist",
+  "Stop Server": "Server stoppen",
+  "Start Server": "Server starten",
+  "Enable DNS per tool below to activate interception": "Schakel DNS in voor elk hulpmiddel hieronder om onderschepping te activeren",
+  "Sudo Password Required": "Sudo-wachtwoord vereist",
+  "Enter your sudo password to start/stop MITM server": "Voer uw sudo-wachtwoord in om de MITM-server te starten/stoppen",
+  "Sudo Password": "Sudo-wachtwoord",
+  "Click to add, click again to remove. Changes are saved automatically.": "Klik om toe te voegen, klik opnieuw om te verwijderen. Wijzigingen worden automatisch opgeslagen.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Risicokennisgeving: Deze provider gebruikt een abonnement/OAuth-sessie die niet officieel is gelicentieerd voor proxy/router-gebruik. Account kan worden beperkt of verbannen. Gebruik op eigen risico.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM onderschept HTTPS-verkeer van IDE-tools (Antigravity, GitHub Copilot, Kiro) via lokale CA om verzoeken om te leiden naar uw providers. Kan ToS schenden → risico op accountban. Gebruik op eigen risico.",
+  "Endpoint is exposed without an API key.": "Het eindpunt is blootgesteld zonder API-sleutel."
+}
diff --git a/public/i18n/literals/no.json b/public/i18n/literals/no.json
new file mode 100644
index 0000000..e3f5215
--- /dev/null
+++ b/public/i18n/literals/no.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Avbryt",
+  "Delete": "Slett",
+  "Edit": "Rediger",
+  "Save": "Lagre",
+  "Close": "Lukk",
+  "Add": "Legg til",
+  "Remove": "Fjern",
+  "Settings": "Innstillinger",
+  "Profile": "Profil",
+  "Dashboard": "Kontrollpanel",
+  "Logout": "Logg ut",
+  "Login": "Logg inn",
+  "Providers": "Leverandører",
+  "Usage": "Bruksstatistikk",
+  "API Key": "API-nøkkel",
+  "Connected": "Tilkoblet",
+  "Disconnected": "Frakoblet",
+  "Active": "Aktiv",
+  "Inactive": "Inaktiv",
+  "Success": "Suksess",
+  "Failed": "Mislyktes",
+  "Error": "Feil",
+  "Warning": "Advarsel",
+  "Info": "Informasjon",
+  "Loading": "Laster",
+  "Search": "Søk",
+  "Filter": "Filter",
+  "Sort": "Sorter",
+  "Export": "Eksporter",
+  "Import": "Importer",
+  "Refresh": "Oppdater",
+  "Back": "Tilbake",
+  "Next": "Neste",
+  "Previous": "Forrige",
+  "Submit": "Send inn",
+  "Confirm": "Bekreft",
+  "Yes": "Ja",
+  "No": "Nei",
+  "OK": "OK",
+  "Apply": "Bruk",
+  "Reset": "Tilbakestill",
+  "Clear": "Tøm",
+  "Select": "Velg",
+  "Upload": "Last opp",
+  "Download": "Last ned",
+  "Copy": "Kopier",
+  "Paste": "Lim inn",
+  "Cut": "Klipp",
+  "Undo": "Angre",
+  "Redo": "Gjør på nytt",
+  "Name": "Navn",
+  "Description": "Beskrivelse",
+  "Status": "Status",
+  "Type": "Type",
+  "Date": "Dato",
+  "Time": "Tid",
+  "Created": "Opprettet",
+  "Updated": "Oppdatert",
+  "Actions": "Handlinger",
+  "Details": "Detaljer",
+  "View": "Vis",
+  "New": "Ny",
+  "Total": "Total",
+  "Count": "Antall",
+  "Price": "Pris",
+  "Cost": "Kostnad",
+  "Free": "Gratis",
+  "Paid": "Betalt",
+  "Enable": "Aktiver",
+  "Disable": "Deaktiver",
+  "Enabled": "Aktivert",
+  "Disabled": "Deaktivert",
+  "Online": "Pålogget",
+  "Offline": "Frakoblet",
+  "Available": "Tilgjengelig",
+  "Unavailable": "Utilgjengelig",
+  "Required": "Obligatorisk",
+  "Optional": "Valgfritt",
+  "Default": "Standard",
+  "Custom": "Tilpasset",
+  "Advanced": "Avansert",
+  "Basic": "Grunnleggende",
+  "Help": "Hjelp",
+  "Support": "Støtte",
+  "Documentation": "Dokumentasjon",
+  "Version": "Versjon",
+  "Language": "Språk",
+  "Theme": "Tema",
+  "Light": "Lys",
+  "Dark": "Mørk",
+  "Auto": "Automatisk",
+  "Endpoint": "Endepunkt",
+  "Combos": "Kombinasjoner",
+  "Quota Tracker": "Kvotasporer",
+  "MITM": "MITM",
+  "CLI Tools": "Verktøy",
+  "Console Log": "Konsollogg",
+  "System": "System",
+  "Debug": "Feilsøking",
+  "Shutdown": "Slå av",
+  "Close Proxy": "Lukk proxy",
+  "Are you sure you want to close the proxy server?": "Er du sikker på at du vil lukke proxyserveren?",
+  "Server Disconnected": "Server frakoblet",
+  "The proxy server has been stopped.": "Proxyserveren har blitt stoppet.",
+  "Reload Page": "Last inn siden på nytt",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Tjenesten kjører i terminalen. Du kan lukke denne nettsiden. Slå av vil stoppe tjenesten.",
+  "Manage your AI provider connections": "Administrer AI-leverandørforbindelsene dine",
+  "Model combos with fallback": "Modellkombinasjoner med fallback",
+  "Monitor your API usage, token consumption, and request logs": "Overvåk API-bruken, tokenforbruk og anmodningslogger",
+  "Intercept CLI tool traffic and route through 9Router": "Avlytting av CLI-verktøy trafikk og rute gjennom 9Router",
+  "Configure CLI tools": "Konfigurer CLI-verktøy",
+  "API endpoint configuration": "Konfiguration av API-endepunkt",
+  "Manage your preferences": "Administrer dine preferanser",
+  "Debug translation flow between formats": "Feilsøking av oversettelsesflyt mellom formater",
+  "Live server console output": "Direkte serverkonsolresultat",
+  "Create model combos with fallback support": "Opprett modellkombinasjoner med fallback-støtte",
+  "Local Mode": "Lokalt modus",
+  "Running on your machine": "Kjørende på maskinen din",
+  "Database Location": "Databaseplassering",
+  "Download Backup": "Last ned sikkerhetskopi",
+  "Import Backup": "Importer sikkerhetskopi",
+  "Database backup downloaded": "Databasesikkerhetskopi lastet ned",
+  "Database imported successfully": "Database importert med suksess",
+  "Security": "Sikkerhet",
+  "Require login": "Krev innlogging",
+  "When ON, dashboard requires password. When OFF, access without login.": "Når PÅ krever kontrollpanelet passord. Når AV, tilgang uten innlogging.",
+  "Current Password": "Gjeldende passord",
+  "Enter current password": "Skriv inn gjeldende passord",
+  "New Password": "Nytt passord",
+  "Enter new password": "Skriv inn nytt passord",
+  "Confirm New Password": "Bekreft nytt passord",
+  "Confirm new password": "Bekreft nytt passord",
+  "Update Password": "Oppdater passord",
+  "Set Password": "Angi passord",
+  "Password updated successfully": "Passord oppdatert med suksess",
+  "Passwords do not match": "Passordene samsvarer ikke",
+  "Routing Strategy": "Rutestrategi",
+  "Round Robin": "Runderobin",
+  "Cycle through accounts to distribute load": "Syklus gjennom kontoer for å distribuere belastning",
+  "Sticky Limit": "Klebrig grense",
+  "Calls per account before switching": "Anrop per konto før bytte",
+  "Network": "Nettverk",
+  "Outbound Proxy": "Utgående proxy",
+  "Enable proxy for OAuth + provider outbound requests.": "Aktiver proxy for OAuth + leverandør utgående forespørsler.",
+  "Proxy URL": "Proxy-URL",
+  "Leave empty to inherit existing env proxy (if any).": "La være tom for å arve eksisterende env-proxy (hvis noen).",
+  "No Proxy": "Ingen proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Kommaseparerte vertsnavner/domener for å omgå proxyen.",
+  "Test proxy URL": "Test proxy-URL",
+  "Proxy settings applied": "Proxyinnstillinger brukt",
+  "Proxy enabled": "Proxy aktivert",
+  "Proxy disabled": "Proxy deaktivert",
+  "Proxy test OK": "Proxytest OK",
+  "Proxy test failed": "Proxytest mislyktes",
+  "Please enter a Proxy URL to test": "Vennligst skriv inn en proxy-URL å teste",
+  "Observability": "Observerbarhet",
+  "Enable Observability": "Aktiver observerbarhet",
+  "Turn request detail recording on/off globally": "Slå detaljregistrering av forespørsel på/av globalt",
+  "Max Records": "Max-poster",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Maksimum anmodningsdetaljposter å beholde (eldre poster blir automatisk slettet)",
+  "Batch Size": "Batch-størrelse",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Antall elementer som skal akkumuleres før skriving til database (høyere = bedre ytelse)",
+  "Flush Interval (ms)": "Spylt intervall (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Maksimal ventetid før spyling av buffer (forhindrer tap av data under lavt trafikk)",
+  "Max JSON Size (KB)": "Maks JSON-størrelse (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Maksimal størrelse for hvert JSON-felt (forespørsel/svar) før avkutting",
+  "All data stored on your machine": "Alle data lagret på maskinen din",
+  "MITM Server": "MITM-server",
+  "Running": "Kjørende",
+  "Stopped": "Stoppet",
+  "Cert": "Sertifikat",
+  "Server": "Server",
+  "Purpose:": "Formål:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Bruk Antigravity IDE & GitHub Copilot → med ENHVER leverandør/modell fra 9Router",
+  "How it works:": "Slik fungerer det:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE-forespørsel → DNS-omdirigering til localhost:443 → MITM-proxy avlytt → 9Router → svar til Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Ingen API-nøkler — lag en på Keys-siden",
+  "sk_9router (default)": "sk_9router (standard)",
+  "Server started": "Server startet",
+  "Failed to start server": "Klarte ikke å starte server",
+  "Server stopped — all DNS cleared": "Server stoppet — alle DNS ryddet",
+  "Failed to stop server": "Klarte ikke å stoppe server",
+  "Sudo password is required": "Sudo-passord er påkrevd",
+  "Stop Server": "Stopp server",
+  "Start Server": "Start server",
+  "Enable DNS per tool below to activate interception": "Aktiver DNS for hvert verktøy nedenfor for å aktivere avlytting",
+  "Sudo Password Required": "Sudo-passord påkrevd",
+  "Enter your sudo password to start/stop MITM server": "Skriv inn sudo-passordet ditt for å starte/stoppe MITM-server",
+  "Sudo Password": "Sudo-passord",
+  "Click to add, click again to remove. Changes are saved automatically.": "Klikk for å legge til, klikk igjen for å fjerne. Endringer lagres automatisk.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Risikovarsel: Denne leverandøren bruker en abonnements-/OAuth-økt som ikke er offisielt lisensiert for proxy-/ruterbruk. Kontoen kan bli begrenset eller utestengt. Bruk på eget ansvar.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM avskjærer HTTPS-trafikk fra IDE-verktøy (Antigravity, GitHub Copilot, Kiro) via lokal CA for å omdirigere forespørsler til dine leverandører. Kan bryte ToS → risiko for kontoutestengelse. Bruk på eget ansvar.",
+  "Endpoint is exposed without an API key.": "Endepunktet er eksponert uten en API-nøkkel."
+}
diff --git a/public/i18n/literals/pl.json b/public/i18n/literals/pl.json
new file mode 100644
index 0000000..f4b62a6
--- /dev/null
+++ b/public/i18n/literals/pl.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Anuluj",
+  "Delete": "Usuń",
+  "Edit": "Edytuj",
+  "Save": "Zapisz",
+  "Close": "Zamknij",
+  "Add": "Dodaj",
+  "Remove": "Usuń",
+  "Settings": "Ustawienia",
+  "Profile": "Profil",
+  "Dashboard": "Panel kontrolny",
+  "Logout": "Wyloguj się",
+  "Login": "Zaloguj się",
+  "Providers": "Dostawcy",
+  "Usage": "Statystyka",
+  "API Key": "Klucz API",
+  "Connected": "Połączony",
+  "Disconnected": "Rozłączony",
+  "Active": "Aktywny",
+  "Inactive": "Nieaktywny",
+  "Success": "Sukces",
+  "Failed": "Niepowodzenie",
+  "Error": "Błąd",
+  "Warning": "Ostrzeżenie",
+  "Info": "Informacja",
+  "Loading": "Ładowanie",
+  "Search": "Szukaj",
+  "Filter": "Filtruj",
+  "Sort": "Sortuj",
+  "Export": "Eksportuj",
+  "Import": "Importuj",
+  "Refresh": "Odśwież",
+  "Back": "Wstecz",
+  "Next": "Dalej",
+  "Previous": "Wstecz",
+  "Submit": "Prześlij",
+  "Confirm": "Potwierdź",
+  "Yes": "Tak",
+  "No": "Nie",
+  "OK": "OK",
+  "Apply": "Zastosuj",
+  "Reset": "Resetuj",
+  "Clear": "Wyczyść",
+  "Select": "Wybierz",
+  "Upload": "Prześlij",
+  "Download": "Pobierz",
+  "Copy": "Skopiuj",
+  "Paste": "Wklej",
+  "Cut": "Wytnij",
+  "Undo": "Cofnij",
+  "Redo": "Powtórz",
+  "Name": "Nazwa",
+  "Description": "Opis",
+  "Status": "Stan",
+  "Type": "Typ",
+  "Date": "Data",
+  "Time": "Czas",
+  "Created": "Utworzono",
+  "Updated": "Zaktualizowano",
+  "Actions": "Akcje",
+  "Details": "Szczegóły",
+  "View": "Wyświetl",
+  "New": "Nowy",
+  "Total": "Razem",
+  "Count": "Liczba",
+  "Price": "Cena",
+  "Cost": "Koszt",
+  "Free": "Bezpłatny",
+  "Paid": "Płatny",
+  "Enable": "Włącz",
+  "Disable": "Wyłącz",
+  "Enabled": "Włączony",
+  "Disabled": "Wyłączony",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Dostępny",
+  "Unavailable": "Niedostępny",
+  "Required": "Wymagane",
+  "Optional": "Opcjonalne",
+  "Default": "Domyślnie",
+  "Custom": "Niestandardowy",
+  "Advanced": "Zaawansowane",
+  "Basic": "Podstawowy",
+  "Help": "Pomoc",
+  "Support": "Pomoc techniczna",
+  "Documentation": "Dokumentacja",
+  "Version": "Wersja",
+  "Language": "Język",
+  "Theme": "Motyw",
+  "Light": "Jasny",
+  "Dark": "Ciemny",
+  "Auto": "Automatycznie",
+  "Endpoint": "Punkt końcowy",
+  "Combos": "Kombinacje",
+  "Quota Tracker": "Śledzenie limitów",
+  "MITM": "MITM",
+  "CLI Tools": "Narzędzia CLI",
+  "Console Log": "Dziennik konsoli",
+  "System": "System",
+  "Debug": "Debugowanie",
+  "Shutdown": "Wyłączenie",
+  "Close Proxy": "Zamknij serwer proxy",
+  "Are you sure you want to close the proxy server?": "Czy na pewno chcesz zamknąć serwer proxy?",
+  "Server Disconnected": "Serwer rozłączony",
+  "The proxy server has been stopped.": "Serwer proxy został zatrzymany.",
+  "Reload Page": "Odśwież stronę",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Usługa działa w terminalu. Możesz zamknąć tę stronę internetową. Wyłączenie zatrzyma usługę.",
+  "Manage your AI provider connections": "Zarządzaj połączeniami dostawcy sztucznej inteligencji",
+  "Model combos with fallback": "Kombinacje modeli z rezerwą",
+  "Monitor your API usage, token consumption, and request logs": "Monitoruj użycie API, zużycie tokenów i dzienniki żądań",
+  "Intercept CLI tool traffic and route through 9Router": "Przechwytuj ruch narzędzi CLI i kieruj przez 9Router",
+  "Configure CLI tools": "Konfiguruj narzędzia CLI",
+  "API endpoint configuration": "Konfiguracja punktu końcowego API",
+  "Manage your preferences": "Zarządzaj swoimi preferencjami",
+  "Debug translation flow between formats": "Debuguj przepływ tłumaczenia między formatami",
+  "Live server console output": "Wyjście konsoli serwera na żywo",
+  "Create model combos with fallback support": "Twórz kombinacje modeli z obsługą rezerwową",
+  "Local Mode": "Tryb lokalny",
+  "Running on your machine": "Działające na twoim komputerze",
+  "Database Location": "Lokalizacja bazy danych",
+  "Download Backup": "Pobierz kopię zapasową",
+  "Import Backup": "Importuj kopię zapasową",
+  "Database backup downloaded": "Kopia zapasowa bazy danych pobrana",
+  "Database imported successfully": "Baza danych pomyślnie zaimportowana",
+  "Security": "Bezpieczeństwo",
+  "Require login": "Wymagaj logowania",
+  "When ON, dashboard requires password. When OFF, access without login.": "Gdy jest WŁĄCZONY, panel wymaga hasła. Gdy jest WYŁĄCZONY, dostęp bez logowania.",
+  "Current Password": "Obecne hasło",
+  "Enter current password": "Wprowadź obecne hasło",
+  "New Password": "Nowe hasło",
+  "Enter new password": "Wprowadź nowe hasło",
+  "Confirm New Password": "Potwierdź nowe hasło",
+  "Confirm new password": "Potwierdź nowe hasło",
+  "Update Password": "Aktualizuj hasło",
+  "Set Password": "Ustaw hasło",
+  "Password updated successfully": "Hasło zaktualizowane pomyślnie",
+  "Passwords do not match": "Hasła się nie zgadzają",
+  "Routing Strategy": "Strategia routingu",
+  "Round Robin": "Round Robin",
+  "Cycle through accounts to distribute load": "Obracaj kontem w celu rozłożenia obciążenia",
+  "Sticky Limit": "Limit lepki",
+  "Calls per account before switching": "Wywołań na konto przed przełączeniem",
+  "Network": "Sieć",
+  "Outbound Proxy": "Serwer proxy wychodzący",
+  "Enable proxy for OAuth + provider outbound requests.": "Włącz serwer proxy dla żądań wychodzących OAuth + dostawcy.",
+  "Proxy URL": "URL serwera proxy",
+  "Leave empty to inherit existing env proxy (if any).": "Zostaw puste, aby odziedziczyć istniejący serwer proxy env (jeśli istnieje).",
+  "No Proxy": "Bez serwera proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Nazwy hostów/domeny oddzielone przecinkami do pominięcia serwera proxy.",
+  "Test proxy URL": "Przetestuj URL serwera proxy",
+  "Proxy settings applied": "Ustawienia serwera proxy zastosowane",
+  "Proxy enabled": "Serwer proxy włączony",
+  "Proxy disabled": "Serwer proxy wyłączony",
+  "Proxy test OK": "Test serwera proxy OK",
+  "Proxy test failed": "Test serwera proxy nie powiódł się",
+  "Please enter a Proxy URL to test": "Proszę wprowadzić URL serwera proxy do testowania",
+  "Observability": "Obserwacyjność",
+  "Enable Observability": "Włącz obserwacyjność",
+  "Turn request detail recording on/off globally": "Włącz/wyłącz globalnie rejestrowanie szczegółów żądania",
+  "Max Records": "Maksymalna liczba rekordów",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Maksymalna liczba rekordów szczegółów żądania do przechowywania (starsze rekordy są automatycznie usuwane)",
+  "Batch Size": "Rozmiar partii",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Liczba elementów do gromadzenia przed zapisaniem w bazie danych (wyższa = lepsza wydajność)",
+  "Flush Interval (ms)": "Interwał opróżniania (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Maksymalny czas oczekiwania przed opróżnieniem buforu (zapobiega utracie danych podczas małego ruchu)",
+  "Max JSON Size (KB)": "Maksymalny rozmiar JSON (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Maksymalny rozmiar każdego pola JSON (żądanie/odpowiedź) przed obcięciem",
+  "All data stored on your machine": "Wszystkie dane przechowywane na twoim komputerze",
+  "MITM Server": "Serwer MITM",
+  "Running": "Działający",
+  "Stopped": "Zatrzymany",
+  "Cert": "Certyfikat",
+  "Server": "Serwer",
+  "Purpose:": "Cel:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Użyj Antigravity IDE i GitHub Copilot → z DOWOLNYM dostawcą/modelem z 9Router",
+  "How it works:": "Jak to działa:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Żądanie Antigravity/Copilot IDE → Przekierowanie DNS na localhost:443 → Serwer proxy MITM przechwytuje → 9Router → odpowiedź do Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Brak kluczy API — utwórz jeden na stronie Klucze",
+  "sk_9router (default)": "sk_9router (domyślnie)",
+  "Server started": "Serwer uruchomiony",
+  "Failed to start server": "Nie udało się uruchomić serwera",
+  "Server stopped — all DNS cleared": "Serwer zatrzymany — cały DNS usunięty",
+  "Failed to stop server": "Nie udało się zatrzymać serwera",
+  "Sudo password is required": "Wymagane hasło sudo",
+  "Stop Server": "Zatrzymaj serwer",
+  "Start Server": "Uruchom serwer",
+  "Enable DNS per tool below to activate interception": "Włącz DNS dla każdego narzędzia poniżej, aby aktywować przechwytywanie",
+  "Sudo Password Required": "Wymagane hasło Sudo",
+  "Enter your sudo password to start/stop MITM server": "Wprowadź hasło sudo, aby uruchomić/zatrzymać serwer MITM",
+  "Sudo Password": "Hasło sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Kliknij, aby dodać, kliknij ponownie, aby usunąć. Zmiany są zapisywane automatycznie.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Ostrzeżenie o ryzyku: Ten dostawca używa sesji subskrypcji/OAuth, która nie jest oficjalnie licencjonowana do użytku proxy/routera. Konto może zostać ograniczone lub zbanowane. Używaj na własne ryzyko.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM przechwytuje ruch HTTPS narzędzi IDE (Antigravity, GitHub Copilot, Kiro) przez lokalne CA, aby przekierować żądania do twoich dostawców. Może naruszyć ToS → ryzyko zbanowania konta. Używaj na własne ryzyko.",
+  "Endpoint is exposed without an API key.": "Punkt końcowy jest dostępny bez klucza API."
+}
diff --git a/public/i18n/literals/pt-BR.json b/public/i18n/literals/pt-BR.json
new file mode 100644
index 0000000..6edba2e
--- /dev/null
+++ b/public/i18n/literals/pt-BR.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Cancelar",
+  "Delete": "Excluir",
+  "Edit": "Editar",
+  "Save": "Salvar",
+  "Close": "Fechar",
+  "Add": "Adicionar",
+  "Remove": "Remover",
+  "Settings": "Configurações",
+  "Profile": "Perfil",
+  "Dashboard": "Painel de controle",
+  "Logout": "Sair",
+  "Login": "Conectar",
+  "Providers": "Provedores",
+  "Usage": "Estatísticas",
+  "API Key": "Chave API",
+  "Connected": "Conectado",
+  "Disconnected": "Desconectado",
+  "Active": "Ativo",
+  "Inactive": "Inativo",
+  "Success": "Sucesso",
+  "Failed": "Falha",
+  "Error": "Erro",
+  "Warning": "Aviso",
+  "Info": "Informações",
+  "Loading": "Carregando",
+  "Search": "Pesquisar",
+  "Filter": "Filtrar",
+  "Sort": "Classificar",
+  "Export": "Exportar",
+  "Import": "Importar",
+  "Refresh": "Atualizar",
+  "Back": "Voltar",
+  "Next": "Próximo",
+  "Previous": "Anterior",
+  "Submit": "Enviar",
+  "Confirm": "Confirmar",
+  "Yes": "Sim",
+  "No": "Não",
+  "OK": "OK",
+  "Apply": "Aplicar",
+  "Reset": "Redefinir",
+  "Clear": "Limpar",
+  "Select": "Selecionar",
+  "Upload": "Enviar",
+  "Download": "Baixar",
+  "Copy": "Copiar",
+  "Paste": "Colar",
+  "Cut": "Cortar",
+  "Undo": "Desfazer",
+  "Redo": "Refazer",
+  "Name": "Nome",
+  "Description": "Descrição",
+  "Status": "Status",
+  "Type": "Tipo",
+  "Date": "Data",
+  "Time": "Hora",
+  "Created": "Criado",
+  "Updated": "Atualizado",
+  "Actions": "Ações",
+  "Details": "Detalhes",
+  "View": "Visualizar",
+  "New": "Novo",
+  "Total": "Total",
+  "Count": "Contagem",
+  "Price": "Preço",
+  "Cost": "Custo",
+  "Free": "Gratuito",
+  "Paid": "Pago",
+  "Enable": "Ativar",
+  "Disable": "Desativar",
+  "Enabled": "Ativado",
+  "Disabled": "Desativado",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Disponível",
+  "Unavailable": "Indisponível",
+  "Required": "Obrigatório",
+  "Optional": "Opcional",
+  "Default": "Padrão",
+  "Custom": "Personalizado",
+  "Advanced": "Avançado",
+  "Basic": "Básico",
+  "Help": "Ajuda",
+  "Support": "Suporte",
+  "Documentation": "Documentação",
+  "Version": "Versão",
+  "Language": "Idioma",
+  "Theme": "Tema",
+  "Light": "Claro",
+  "Dark": "Escuro",
+  "Auto": "Automático",
+  "Endpoint": "Ponto de extremidade",
+  "Combos": "Combinações",
+  "Quota Tracker": "Rastreador de cota",
+  "MITM": "MITM",
+  "CLI Tools": "Ferramentas CLI",
+  "Console Log": "Log do console",
+  "System": "Sistema",
+  "Debug": "Depuração",
+  "Shutdown": "Desligar",
+  "Close Proxy": "Fechar proxy",
+  "Are you sure you want to close the proxy server?": "Tem certeza de que deseja fechar o servidor proxy?",
+  "Server Disconnected": "Servidor desconectado",
+  "The proxy server has been stopped.": "O servidor proxy foi parado.",
+  "Reload Page": "Recarregar página",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "O serviço está em execução no terminal. Você pode fechar esta página da web. O desligamento interromperá o serviço.",
+  "Manage your AI provider connections": "Gerencie suas conexões de provedor de IA",
+  "Model combos with fallback": "Combinações de modelos com fallback",
+  "Monitor your API usage, token consumption, and request logs": "Monitore seu uso de API, consumo de tokens e logs de solicitação",
+  "Intercept CLI tool traffic and route through 9Router": "Intercepte o tráfego da ferramenta CLI e roteie através do 9Router",
+  "Configure CLI tools": "Configurar ferramentas CLI",
+  "API endpoint configuration": "Configuração do ponto de extremidade da API",
+  "Manage your preferences": "Gerenciar suas preferências",
+  "Debug translation flow between formats": "Depurar fluxo de tradução entre formatos",
+  "Live server console output": "Saída do console do servidor ao vivo",
+  "Create model combos with fallback support": "Crie combinações de modelos com suporte a fallback",
+  "Local Mode": "Modo local",
+  "Running on your machine": "Executando em sua máquina",
+  "Database Location": "Localização do banco de dados",
+  "Download Backup": "Baixar backup",
+  "Import Backup": "Importar backup",
+  "Database backup downloaded": "Backup do banco de dados baixado",
+  "Database imported successfully": "Banco de dados importado com sucesso",
+  "Security": "Segurança",
+  "Require login": "Exigir login",
+  "When ON, dashboard requires password. When OFF, access without login.": "Quando ATIVO, o painel requer senha. Quando DESATIVO, acesso sem login.",
+  "Current Password": "Senha atual",
+  "Enter current password": "Digite a senha atual",
+  "New Password": "Nova senha",
+  "Enter new password": "Digite a nova senha",
+  "Confirm New Password": "Confirmar nova senha",
+  "Confirm new password": "Confirme a nova senha",
+  "Update Password": "Atualizar senha",
+  "Set Password": "Definir senha",
+  "Password updated successfully": "Senha atualizada com sucesso",
+  "Passwords do not match": "As senhas não correspondem",
+  "Routing Strategy": "Estratégia de roteamento",
+  "Round Robin": "Round Robin",
+  "Cycle through accounts to distribute load": "Percorrer contas para distribuir carga",
+  "Sticky Limit": "Limite pegajoso",
+  "Calls per account before switching": "Chamadas por conta antes de alternar",
+  "Network": "Rede",
+  "Outbound Proxy": "Proxy de saída",
+  "Enable proxy for OAuth + provider outbound requests.": "Ativar proxy para OAuth + solicitações de saída do provedor.",
+  "Proxy URL": "URL do proxy",
+  "Leave empty to inherit existing env proxy (if any).": "Deixe em branco para herdar o proxy env existente (se houver).",
+  "No Proxy": "Sem proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Nomes de host/domínios separados por vírgula para contornar o proxy.",
+  "Test proxy URL": "Testar URL do proxy",
+  "Proxy settings applied": "Configurações de proxy aplicadas",
+  "Proxy enabled": "Proxy ativado",
+  "Proxy disabled": "Proxy desativado",
+  "Proxy test OK": "Teste de proxy OK",
+  "Proxy test failed": "Falha no teste de proxy",
+  "Please enter a Proxy URL to test": "Por favor, digite uma URL de proxy para testar",
+  "Observability": "Observabilidade",
+  "Enable Observability": "Ativar observabilidade",
+  "Turn request detail recording on/off globally": "Ativar/desativar globalmente o registro de detalhes da solicitação",
+  "Max Records": "Número máximo de registros",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Número máximo de registros de detalhes de solicitação a manter (registros antigos são excluídos automaticamente)",
+  "Batch Size": "Tamanho do lote",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Número de itens a acumular antes de gravar no banco de dados (maior = melhor desempenho)",
+  "Flush Interval (ms)": "Intervalo de liberação (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Tempo máximo de espera antes de liberar o buffer (evita perda de dados durante baixo tráfego)",
+  "Max JSON Size (KB)": "Tamanho máximo de JSON (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Tamanho máximo para cada campo JSON (solicitação/resposta) antes do truncamento",
+  "All data stored on your machine": "Todos os dados armazenados em sua máquina",
+  "MITM Server": "Servidor MITM",
+  "Running": "Executando",
+  "Stopped": "Parado",
+  "Cert": "Certificado",
+  "Server": "Servidor",
+  "Purpose:": "Propósito:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Use Antigravity IDE e GitHub Copilot → com QUALQUER provedor/modelo do 9Router",
+  "How it works:": "Como funciona:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Solicitação do Antigravity/Copilot IDE → Redirecionamento DNS para localhost:443 → Proxy MITM intercepta → 9Router → resposta para Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Sem chaves de API — crie uma na página Chaves",
+  "sk_9router (default)": "sk_9router (padrão)",
+  "Server started": "Servidor iniciado",
+  "Failed to start server": "Falha ao iniciar o servidor",
+  "Server stopped — all DNS cleared": "Servidor parado — todo DNS foi limpo",
+  "Failed to stop server": "Falha ao parar o servidor",
+  "Sudo password is required": "Senha sudo é necessária",
+  "Stop Server": "Parar servidor",
+  "Start Server": "Iniciar servidor",
+  "Enable DNS per tool below to activate interception": "Ativar DNS para cada ferramenta abaixo para ativar a interceptação",
+  "Sudo Password Required": "Senha Sudo necessária",
+  "Enter your sudo password to start/stop MITM server": "Digite sua senha sudo para iniciar/parar o servidor MITM",
+  "Sudo Password": "Senha sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Clique para adicionar, clique novamente para remover. As alterações são salvas automaticamente.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Aviso de Risco: Este provedor usa uma sessão de assinatura/OAuth não licenciada oficialmente para uso de proxy/roteador. A conta pode ser restrita ou banida. Use por sua conta e risco.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM intercepta tráfego HTTPS de ferramentas IDE (Antigravity, GitHub Copilot, Kiro) via CA local para redirecionar solicitações aos seus provedores. Pode violar ToS → risco de banimento de conta. Use por sua conta e risco.",
+  "Endpoint is exposed without an API key.": "O endpoint está exposto sem uma chave de API."
+}
diff --git a/public/i18n/literals/pt-PT.json b/public/i18n/literals/pt-PT.json
new file mode 100644
index 0000000..c17e932
--- /dev/null
+++ b/public/i18n/literals/pt-PT.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Cancelar",
+  "Delete": "Eliminar",
+  "Edit": "Editar",
+  "Save": "Guardar",
+  "Close": "Fechar",
+  "Add": "Adicionar",
+  "Remove": "Remover",
+  "Settings": "Definições",
+  "Profile": "Perfil",
+  "Dashboard": "Painel de controlo",
+  "Logout": "Terminar sessão",
+  "Login": "Iniciar sessão",
+  "Providers": "Fornecedores",
+  "Usage": "Estatísticas",
+  "API Key": "Chave API",
+  "Connected": "Ligado",
+  "Disconnected": "Desligado",
+  "Active": "Ativo",
+  "Inactive": "Inativo",
+  "Success": "Sucesso",
+  "Failed": "Falha",
+  "Error": "Erro",
+  "Warning": "Aviso",
+  "Info": "Informações",
+  "Loading": "A carregar",
+  "Search": "Pesquisar",
+  "Filter": "Filtrar",
+  "Sort": "Ordenar",
+  "Export": "Exportar",
+  "Import": "Importar",
+  "Refresh": "Atualizar",
+  "Back": "Voltar",
+  "Next": "Seguinte",
+  "Previous": "Anterior",
+  "Submit": "Enviar",
+  "Confirm": "Confirmar",
+  "Yes": "Sim",
+  "No": "Não",
+  "OK": "OK",
+  "Apply": "Aplicar",
+  "Reset": "Repor",
+  "Clear": "Limpar",
+  "Select": "Selecionar",
+  "Upload": "Carregar",
+  "Download": "Descarregar",
+  "Copy": "Copiar",
+  "Paste": "Colar",
+  "Cut": "Cortar",
+  "Undo": "Desfazer",
+  "Redo": "Refazer",
+  "Name": "Nome",
+  "Description": "Descrição",
+  "Status": "Estado",
+  "Type": "Tipo",
+  "Date": "Data",
+  "Time": "Hora",
+  "Created": "Criado",
+  "Updated": "Atualizado",
+  "Actions": "Ações",
+  "Details": "Detalhes",
+  "View": "Ver",
+  "New": "Novo",
+  "Total": "Total",
+  "Count": "Contagem",
+  "Price": "Preço",
+  "Cost": "Custo",
+  "Free": "Gratuito",
+  "Paid": "Pago",
+  "Enable": "Ativar",
+  "Disable": "Desativar",
+  "Enabled": "Ativado",
+  "Disabled": "Desativado",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Disponível",
+  "Unavailable": "Indisponível",
+  "Required": "Obrigatório",
+  "Optional": "Opcional",
+  "Default": "Predefinição",
+  "Custom": "Personalizado",
+  "Advanced": "Avançado",
+  "Basic": "Básico",
+  "Help": "Ajuda",
+  "Support": "Suporte",
+  "Documentation": "Documentação",
+  "Version": "Versão",
+  "Language": "Idioma",
+  "Theme": "Tema",
+  "Light": "Claro",
+  "Dark": "Escuro",
+  "Auto": "Automático",
+  "Endpoint": "Ponto final",
+  "Combos": "Combinações",
+  "Quota Tracker": "Rastreador de quota",
+  "MITM": "MITM",
+  "CLI Tools": "Ferramentas CLI",
+  "Console Log": "Registo da consola",
+  "System": "Sistema",
+  "Debug": "Depuração",
+  "Shutdown": "Encerramento",
+  "Close Proxy": "Fechar proxy",
+  "Are you sure you want to close the proxy server?": "Tem a certeza de que deseja fechar o servidor proxy?",
+  "Server Disconnected": "Servidor desligado",
+  "The proxy server has been stopped.": "O servidor proxy foi parado.",
+  "Reload Page": "Recarregar página",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "O serviço está em execução no terminal. Pode fechar esta página da web. O encerramento irá parar o serviço.",
+  "Manage your AI provider connections": "Gerir as suas ligações de fornecedor de IA",
+  "Model combos with fallback": "Combinações de modelos com contingência",
+  "Monitor your API usage, token consumption, and request logs": "Monitorize a sua utilização de API, consumo de fichas e registos de pedidos",
+  "Intercept CLI tool traffic and route through 9Router": "Intercete o tráfego da ferramenta CLI e encaminhe através do 9Router",
+  "Configure CLI tools": "Configurar ferramentas CLI",
+  "API endpoint configuration": "Configuração do ponto final da API",
+  "Manage your preferences": "Gerir as suas preferências",
+  "Debug translation flow between formats": "Depurar fluxo de tradução entre formatos",
+  "Live server console output": "Saída da consola do servidor em direto",
+  "Create model combos with fallback support": "Criar combinações de modelos com suporte a contingência",
+  "Local Mode": "Modo local",
+  "Running on your machine": "Em execução na sua máquina",
+  "Database Location": "Localização da base de dados",
+  "Download Backup": "Descarregar cópia de segurança",
+  "Import Backup": "Importar cópia de segurança",
+  "Database backup downloaded": "Cópia de segurança da base de dados descarregada",
+  "Database imported successfully": "Base de dados importada com sucesso",
+  "Security": "Segurança",
+  "Require login": "Requer início de sessão",
+  "When ON, dashboard requires password. When OFF, access without login.": "Quando ATIVO, o painel requer palavra-passe. Quando DESATIVO, acesso sem iniciar sessão.",
+  "Current Password": "Palavra-passe atual",
+  "Enter current password": "Introduza a palavra-passe atual",
+  "New Password": "Nova palavra-passe",
+  "Enter new password": "Introduza a nova palavra-passe",
+  "Confirm New Password": "Confirmar nova palavra-passe",
+  "Confirm new password": "Confirme a nova palavra-passe",
+  "Update Password": "Atualizar palavra-passe",
+  "Set Password": "Definir palavra-passe",
+  "Password updated successfully": "Palavra-passe atualizada com sucesso",
+  "Passwords do not match": "As palavras-passe não coincidem",
+  "Routing Strategy": "Estratégia de encaminhamento",
+  "Round Robin": "Round Robin",
+  "Cycle through accounts to distribute load": "Passar por contas para distribuir carga",
+  "Sticky Limit": "Limite aderente",
+  "Calls per account before switching": "Chamadas por conta antes de mudar",
+  "Network": "Rede",
+  "Outbound Proxy": "Proxy de saída",
+  "Enable proxy for OAuth + provider outbound requests.": "Ativar proxy para OAuth + pedidos de saída do fornecedor.",
+  "Proxy URL": "URL do proxy",
+  "Leave empty to inherit existing env proxy (if any).": "Deixe em branco para herdar o proxy env existente (se houver).",
+  "No Proxy": "Sem proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Nomes de host/domínios separados por vírgulas para contornar o proxy.",
+  "Test proxy URL": "Testar URL do proxy",
+  "Proxy settings applied": "Definições de proxy aplicadas",
+  "Proxy enabled": "Proxy ativado",
+  "Proxy disabled": "Proxy desativado",
+  "Proxy test OK": "Teste de proxy OK",
+  "Proxy test failed": "Falha no teste de proxy",
+  "Please enter a Proxy URL to test": "Introduza um URL de proxy para testar",
+  "Observability": "Observabilidade",
+  "Enable Observability": "Ativar observabilidade",
+  "Turn request detail recording on/off globally": "Ativar/desativar globalmente o registo de detalhes de pedidos",
+  "Max Records": "Número máximo de registos",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Número máximo de registos de detalhes de pedidos a manter (registos mais antigos são eliminados automaticamente)",
+  "Batch Size": "Tamanho do lote",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Número de itens a acumular antes de gravar na base de dados (mais alto = melhor desempenho)",
+  "Flush Interval (ms)": "Intervalo de limpeza (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Tempo máximo de espera antes de limpar o buffer (evita perda de dados durante tráfego baixo)",
+  "Max JSON Size (KB)": "Tamanho máximo de JSON (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Tamanho máximo para cada campo JSON (pedido/resposta) antes do truncamento",
+  "All data stored on your machine": "Todos os dados armazenados na sua máquina",
+  "MITM Server": "Servidor MITM",
+  "Running": "Em execução",
+  "Stopped": "Parado",
+  "Cert": "Certificado",
+  "Server": "Servidor",
+  "Purpose:": "Finalidade:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Utilize o Antigravity IDE e GitHub Copilot → com QUALQUER fornecedor/modelo do 9Router",
+  "How it works:": "Como funciona:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Pedido do Antigravity/Copilot IDE → Redirecionamento DNS para localhost:443 → Proxy MITM interceta → 9Router → resposta para Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Sem chaves de API — crie uma na página Chaves",
+  "sk_9router (default)": "sk_9router (predefinição)",
+  "Server started": "Servidor iniciado",
+  "Failed to start server": "Falha ao iniciar o servidor",
+  "Server stopped — all DNS cleared": "Servidor parado — todo DNS foi limpo",
+  "Failed to stop server": "Falha ao parar o servidor",
+  "Sudo password is required": "Palavra-passe sudo é necessária",
+  "Stop Server": "Parar servidor",
+  "Start Server": "Iniciar servidor",
+  "Enable DNS per tool below to activate interception": "Ativar DNS para cada ferramenta abaixo para ativar a interceção",
+  "Sudo Password Required": "Palavra-passe Sudo necessária",
+  "Enter your sudo password to start/stop MITM server": "Introduza a sua palavra-passe sudo para iniciar/parar o servidor MITM",
+  "Sudo Password": "Palavra-passe sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Clique para adicionar, clique novamente para remover. As alterações são guardadas automaticamente.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Aviso de Risco: Este fornecedor utiliza uma sessão de subscrição/OAuth não licenciada oficialmente para uso de proxy/router. A conta pode ser restringida ou banida. Use por sua conta e risco.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM interceta tráfego HTTPS de ferramentas IDE (Antigravity, GitHub Copilot, Kiro) via CA local para redirecionar pedidos para os seus fornecedores. Pode violar ToS → risco de banimento de conta. Use por sua conta e risco.",
+  "Endpoint is exposed without an API key.": "O endpoint está exposto sem uma chave de API."
+}
diff --git a/public/i18n/literals/ro.json b/public/i18n/literals/ro.json
new file mode 100644
index 0000000..0338441
--- /dev/null
+++ b/public/i18n/literals/ro.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Anulare",
+  "Delete": "Ștergere",
+  "Edit": "Editare",
+  "Save": "Salvare",
+  "Close": "Închide",
+  "Add": "Adăugare",
+  "Remove": "Eliminare",
+  "Settings": "Setări",
+  "Profile": "Profil",
+  "Dashboard": "Tablou de bord",
+  "Logout": "Ieșire",
+  "Login": "Conectare",
+  "Providers": "Furnizori",
+  "Usage": "Statistici de utilizare",
+  "API Key": "Cheie API",
+  "Connected": "Conectat",
+  "Disconnected": "Deconectat",
+  "Active": "Activ",
+  "Inactive": "Inactiv",
+  "Success": "Succes",
+  "Failed": "Eşuat",
+  "Error": "Eroare",
+  "Warning": "Avertisment",
+  "Info": "Informații",
+  "Loading": "Se încarcă",
+  "Search": "Căutare",
+  "Filter": "Filtru",
+  "Sort": "Sortare",
+  "Export": "Exportare",
+  "Import": "Importare",
+  "Refresh": "Reîmprospătare",
+  "Back": "Înapoi",
+  "Next": "Următorul",
+  "Previous": "Anterior",
+  "Submit": "Trimitere",
+  "Confirm": "Confirmare",
+  "Yes": "Da",
+  "No": "Nu",
+  "OK": "OK",
+  "Apply": "Aplicare",
+  "Reset": "Resetare",
+  "Clear": "Curățare",
+  "Select": "Selectare",
+  "Upload": "Încărcare",
+  "Download": "Descărcare",
+  "Copy": "Copiere",
+  "Paste": "Lipire",
+  "Cut": "Tăiere",
+  "Undo": "Anulare",
+  "Redo": "Refacere",
+  "Name": "Nume",
+  "Description": "Descriere",
+  "Status": "Status",
+  "Type": "Tip",
+  "Date": "Data",
+  "Time": "Oră",
+  "Created": "Creat",
+  "Updated": "Actualizat",
+  "Actions": "Acțiuni",
+  "Details": "Detalii",
+  "View": "Vizualizare",
+  "New": "Nou",
+  "Total": "Total",
+  "Count": "Număr",
+  "Price": "Preț",
+  "Cost": "Cost",
+  "Free": "Gratuit",
+  "Paid": "Plătit",
+  "Enable": "Activare",
+  "Disable": "Dezactivare",
+  "Enabled": "Activat",
+  "Disabled": "Dezactivat",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Disponibil",
+  "Unavailable": "Indisponibil",
+  "Required": "Necesar",
+  "Optional": "Opțional",
+  "Default": "Implicit",
+  "Custom": "Personalizat",
+  "Advanced": "Avansat",
+  "Basic": "De bază",
+  "Help": "Ajutor",
+  "Support": "Suport",
+  "Documentation": "Documentație",
+  "Version": "Versiune",
+  "Language": "Limbă",
+  "Theme": "Temă",
+  "Light": "Lumină",
+  "Dark": "Întunecat",
+  "Auto": "Automat",
+  "Endpoint": "Punct final",
+  "Combos": "Combinații",
+  "Quota Tracker": "Urmăritor cote",
+  "MITM": "MITM",
+  "CLI Tools": "Instrumente",
+  "Console Log": "Jurnal consolă",
+  "System": "Sistem",
+  "Debug": "Depanare",
+  "Shutdown": "Oprire",
+  "Close Proxy": "Închidere proxy",
+  "Are you sure you want to close the proxy server?": "Sunteti sigur că doriți să închideți serverul proxy?",
+  "Server Disconnected": "Server deconectat",
+  "The proxy server has been stopped.": "Serverul proxy a fost oprit.",
+  "Reload Page": "Reîncărcare pagină",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Serviciul rulează în terminal. Puteți închide această pagină web. Oprirea va opri serviciul.",
+  "Manage your AI provider connections": "Gestionați conexiunile furnizorului dvs. de IA",
+  "Model combos with fallback": "Combinații de modele cu fallback",
+  "Monitor your API usage, token consumption, and request logs": "Monitorizați utilizarea API-ului, consumul de token și jurnalele de solicitare",
+  "Intercept CLI tool traffic and route through 9Router": "Interceptați traficul instrumentului CLI și rutați prin 9Router",
+  "Configure CLI tools": "Configurați instrumentele CLI",
+  "API endpoint configuration": "Configurația punctului final API",
+  "Manage your preferences": "Gestionați preferințele dvs.",
+  "Debug translation flow between formats": "Depanare fluxului de traducere între formate",
+  "Live server console output": "Ieșire consolă server în direct",
+  "Create model combos with fallback support": "Creați combinații de modele cu suport fallback",
+  "Local Mode": "Mod local",
+  "Running on your machine": "Rulează pe mașina dvs.",
+  "Database Location": "Locația bazei de date",
+  "Download Backup": "Descărcare copie de rezervă",
+  "Import Backup": "Importare copie de rezervă",
+  "Database backup downloaded": "Copia de rezervă a bazei de date a fost descărcată",
+  "Database imported successfully": "Baza de date a fost importată cu succes",
+  "Security": "Securitate",
+  "Require login": "Necesită conectare",
+  "When ON, dashboard requires password. When OFF, access without login.": "Când este PORNIT, tabloul de bord necesită parolă. Când este OPRIT, accesați fără conectare.",
+  "Current Password": "Parola actuală",
+  "Enter current password": "Introduceți parola actuală",
+  "New Password": "Parola nouă",
+  "Enter new password": "Introduceți parola nouă",
+  "Confirm New Password": "Confirmați parola nouă",
+  "Confirm new password": "Confirmați parola nouă",
+  "Update Password": "Actualizare parolă",
+  "Set Password": "Setare parolă",
+  "Password updated successfully": "Parola a fost actualizată cu succes",
+  "Passwords do not match": "Parolele nu coincid",
+  "Routing Strategy": "Strategie de rutare",
+  "Round Robin": "Tur în jurul",
+  "Cycle through accounts to distribute load": "Ciclați prin conturi pentru a distribui sarcina",
+  "Sticky Limit": "Limită lipicioasă",
+  "Calls per account before switching": "Apeluri pe cont înainte de comutare",
+  "Network": "Rețea",
+  "Outbound Proxy": "Proxy de ieșire",
+  "Enable proxy for OAuth + provider outbound requests.": "Activați proxy-ul pentru solicitări de ieșire OAuth + furnizor.",
+  "Proxy URL": "URL proxy",
+  "Leave empty to inherit existing env proxy (if any).": "Lăsați gol pentru a moșteni proxy-ul env existent (dacă există).",
+  "No Proxy": "Nicio delegare",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Nume de gazdă/domenii separate prin virgulă pentru a ocoli proxy-ul.",
+  "Test proxy URL": "Testare URL proxy",
+  "Proxy settings applied": "Setările proxy au fost aplicate",
+  "Proxy enabled": "Proxy activat",
+  "Proxy disabled": "Proxy dezactivat",
+  "Proxy test OK": "Testul proxy OK",
+  "Proxy test failed": "Testul proxy a eșuat",
+  "Please enter a Proxy URL to test": "Vă rugăm să introduceți un URL proxy pentru a testa",
+  "Observability": "Observabilitate",
+  "Enable Observability": "Activare observabilitate",
+  "Turn request detail recording on/off globally": "Porniți/opriți înregistrarea detaliilor solicitării la nivel global",
+  "Max Records": "Înregistrări maxime",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Înregistrări de detalii de solicitare maxime de păstrat (înregistrările mai vechi sunt șterse automat)",
+  "Batch Size": "Dimensiune lot",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Numărul de articole de acumulat înainte de a scrie în baza de date (mai mare = performanță mai bună)",
+  "Flush Interval (ms)": "Interval de golire (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Timp maxim de așteptare înainte de golirea bufferului (previne pierderea datelor în condiții de trafic redus)",
+  "Max JSON Size (KB)": "Dimensiune JSON maximă (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Dimensiune maximă pentru fiecare câmp JSON (solicitare/răspuns) înainte de trunchiere",
+  "All data stored on your machine": "Toate datele sunt stocate pe mașina dvs.",
+  "MITM Server": "Server MITM",
+  "Running": "Se execută",
+  "Stopped": "Oprit",
+  "Cert": "Certificat",
+  "Server": "Server",
+  "Purpose:": "Scop:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Folosiți Antigravity IDE & GitHub Copilot → cu ORICE furnizor/model din 9Router",
+  "How it works:": "Cum funcționează:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Solicitare Antigravity/Copilot IDE → Redirecționare DNS la localhost:443 → Proxy MITM interceptează → 9Router → răspuns la Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Nicio cheie API — creați una în pagina Chei",
+  "sk_9router (default)": "sk_9router (implicit)",
+  "Server started": "Server pornit",
+  "Failed to start server": "Nu s-a putut porni serverul",
+  "Server stopped — all DNS cleared": "Server oprit — toate DNS-urile șterse",
+  "Failed to stop server": "Nu s-a putut opri serverul",
+  "Sudo password is required": "Parola sudo este necesară",
+  "Stop Server": "Oprire server",
+  "Start Server": "Server de pornire",
+  "Enable DNS per tool below to activate interception": "Activați DNS pentru fiecare instrument de mai jos pentru a activa interceptarea",
+  "Sudo Password Required": "Parola Sudo este necesară",
+  "Enter your sudo password to start/stop MITM server": "Introduceți parola sudo pentru a porni/opri serverul MITM",
+  "Sudo Password": "Parola Sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Faceți clic pentru a adăuga, faceți clic din nou pentru a elimina. Modificările sunt salvate automat.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Notificare de risc: Acest furnizor folosește un abonament/sesiune OAuth care nu este licențiat oficial pentru utilizare proxy/router. Contul poate fi restricționat sau interzis. Utilizați pe propriul risc.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM interceptează traficul HTTPS al instrumentelor IDE (Antigravity, GitHub Copilot, Kiro) prin CA locală pentru a redirecționa cererile către furnizorii dvs. Poate încălca ToS → risc de interzicere a contului. Utilizați pe propriul risc.",
+  "Endpoint is exposed without an API key.": "Endpointul este expus fără o cheie API."
+}
diff --git a/public/i18n/literals/ru.json b/public/i18n/literals/ru.json
new file mode 100644
index 0000000..92b9f0e
--- /dev/null
+++ b/public/i18n/literals/ru.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Отменить",
+  "Delete": "Удалить",
+  "Edit": "Редактировать",
+  "Save": "Сохранить",
+  "Close": "Закрыть",
+  "Add": "Добавить",
+  "Remove": "Удалить",
+  "Settings": "Настройки",
+  "Profile": "Профиль",
+  "Dashboard": "Панель управления",
+  "Logout": "Выход",
+  "Login": "Вход",
+  "Providers": "Провайдеры",
+  "Usage": "Статистика",
+  "API Key": "Ключ API",
+  "Connected": "Подключено",
+  "Disconnected": "Отключено",
+  "Active": "Активно",
+  "Inactive": "Неактивно",
+  "Success": "Успех",
+  "Failed": "Ошибка",
+  "Error": "Ошибка",
+  "Warning": "Предупреждение",
+  "Info": "Информация",
+  "Loading": "Загрузка",
+  "Search": "Поиск",
+  "Filter": "Фильтр",
+  "Sort": "Сортировка",
+  "Export": "Экспорт",
+  "Import": "Импорт",
+  "Refresh": "Обновить",
+  "Back": "Назад",
+  "Next": "Далее",
+  "Previous": "Назад",
+  "Submit": "Отправить",
+  "Confirm": "Подтвердить",
+  "Yes": "Да",
+  "No": "Нет",
+  "OK": "OK",
+  "Apply": "Применить",
+  "Reset": "Сбросить",
+  "Clear": "Очистить",
+  "Select": "Выбрать",
+  "Upload": "Загрузить",
+  "Download": "Скачать",
+  "Copy": "Копировать",
+  "Paste": "Вставить",
+  "Cut": "Вырезать",
+  "Undo": "Отменить",
+  "Redo": "Повторить",
+  "Name": "Имя",
+  "Description": "Описание",
+  "Status": "Статус",
+  "Type": "Тип",
+  "Date": "Дата",
+  "Time": "Время",
+  "Created": "Создано",
+  "Updated": "Обновлено",
+  "Actions": "Действия",
+  "Details": "Подробности",
+  "View": "Просмотр",
+  "New": "Новый",
+  "Total": "Всего",
+  "Count": "Количество",
+  "Price": "Цена",
+  "Cost": "Стоимость",
+  "Free": "Бесплатно",
+  "Paid": "Платно",
+  "Enable": "Включить",
+  "Disable": "Отключить",
+  "Enabled": "Включено",
+  "Disabled": "Отключено",
+  "Online": "Онлайн",
+  "Offline": "Офлайн",
+  "Available": "Доступно",
+  "Unavailable": "Недоступно",
+  "Required": "Обязательно",
+  "Optional": "Опционально",
+  "Default": "По умолчанию",
+  "Custom": "Пользовательский",
+  "Advanced": "Дополнительно",
+  "Basic": "Основной",
+  "Help": "Справка",
+  "Support": "Поддержка",
+  "Documentation": "Документация",
+  "Version": "Версия",
+  "Language": "Язык",
+  "Theme": "Тема",
+  "Light": "Светлая",
+  "Dark": "Темная",
+  "Auto": "Автоматически",
+  "Endpoint": "Конечная точка",
+  "Combos": "Комбинации",
+  "Quota Tracker": "Отслеживание квоты",
+  "MITM": "MITM",
+  "CLI Tools": "Инструменты CLI",
+  "Console Log": "Журнал консоли",
+  "System": "Система",
+  "Debug": "Отладка",
+  "Shutdown": "Завершение",
+  "Close Proxy": "Закрыть прокси",
+  "Are you sure you want to close the proxy server?": "Вы уверены, что хотите закрыть прокси-сервер?",
+  "Server Disconnected": "Сервер отключен",
+  "The proxy server has been stopped.": "Прокси-сервер был остановлен.",
+  "Reload Page": "Перезагрузить страницу",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Сервис работает в терминале. Вы можете закрыть эту веб-страницу. Завершение остановит сервис.",
+  "Manage your AI provider connections": "Управляйте своими подключениями провайдера ИИ",
+  "Model combos with fallback": "Комбинации моделей с резервным вариантом",
+  "Monitor your API usage, token consumption, and request logs": "Мониторьте использование API, потребление токенов и журналы запросов",
+  "Intercept CLI tool traffic and route through 9Router": "Перехватите трафик инструмента CLI и маршрутизируйте через 9Router",
+  "Configure CLI tools": "Настройка инструментов CLI",
+  "API endpoint configuration": "Конфигурация конечной точки API",
+  "Manage your preferences": "Управляйте своими предпочтениями",
+  "Debug translation flow between formats": "Отладка потока трансляции между форматами",
+  "Live server console output": "Вывод консоли сервера в реальном времени",
+  "Create model combos with fallback support": "Создание комбинаций моделей с поддержкой резервного варианта",
+  "Local Mode": "Локальный режим",
+  "Running on your machine": "Работает на вашем компьютере",
+  "Database Location": "Расположение базы данных",
+  "Download Backup": "Загрузить резервную копию",
+  "Import Backup": "Импортировать резервную копию",
+  "Database backup downloaded": "Резервная копия базы данных загружена",
+  "Database imported successfully": "База данных успешно импортирована",
+  "Security": "Безопасность",
+  "Require login": "Требовать вход",
+  "When ON, dashboard requires password. When OFF, access without login.": "Когда ВКЛЮЧЕНО, панель управления требует пароль. Когда ОТКЛЮЧЕНО, доступ без входа.",
+  "Current Password": "Текущий пароль",
+  "Enter current password": "Введите текущий пароль",
+  "New Password": "Новый пароль",
+  "Enter new password": "Введите новый пароль",
+  "Confirm New Password": "Подтвердить новый пароль",
+  "Confirm new password": "Подтвердите новый пароль",
+  "Update Password": "Обновить пароль",
+  "Set Password": "Установить пароль",
+  "Password updated successfully": "Пароль успешно обновлен",
+  "Passwords do not match": "Пароли не совпадают",
+  "Routing Strategy": "Стратегия маршрутизации",
+  "Round Robin": "Циклическая выборка",
+  "Cycle through accounts to distribute load": "Чередование аккаунтов для распределения нагрузки",
+  "Sticky Limit": "Липкий предел",
+  "Calls per account before switching": "Вызовов на аккаунт перед переключением",
+  "Network": "Сеть",
+  "Outbound Proxy": "Исходящий прокси",
+  "Enable proxy for OAuth + provider outbound requests.": "Включить прокси для OAuth + исходящих запросов провайдера.",
+  "Proxy URL": "URL прокси",
+  "Leave empty to inherit existing env proxy (if any).": "Оставьте пусто, чтобы унаследовать существующий прокси env (если есть).",
+  "No Proxy": "Без прокси",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Разделенные запятыми имена хостов/домены для обхода прокси.",
+  "Test proxy URL": "Протестировать URL прокси",
+  "Proxy settings applied": "Параметры прокси применены",
+  "Proxy enabled": "Прокси включен",
+  "Proxy disabled": "Прокси отключен",
+  "Proxy test OK": "Тест прокси OK",
+  "Proxy test failed": "Тест прокси не пройден",
+  "Please enter a Proxy URL to test": "Пожалуйста, введите URL прокси для тестирования",
+  "Observability": "Наблюдаемость",
+  "Enable Observability": "Включить наблюдаемость",
+  "Turn request detail recording on/off globally": "Включить/отключить запись деталей запроса глобально",
+  "Max Records": "Максимум записей",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Максимальное количество записей деталей запроса для сохранения (старые записи автоматически удаляются)",
+  "Batch Size": "Размер пакета",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Количество элементов для накопления перед записью в базу данных (выше = лучшая производительность)",
+  "Flush Interval (ms)": "Интервал очистки (мс)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Максимальное время ожидания перед очисткой буфера (предотвращает потерю данных при низком трафике)",
+  "Max JSON Size (KB)": "Максимальный размер JSON (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Максимальный размер каждого поля JSON (запрос/ответ) перед усечением",
+  "All data stored on your machine": "Все данные хранятся на вашем компьютере",
+  "MITM Server": "Сервер MITM",
+  "Running": "Работает",
+  "Stopped": "Остановлено",
+  "Cert": "Сертификат",
+  "Server": "Сервер",
+  "Purpose:": "Назначение:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Используйте Antigravity IDE и GitHub Copilot → с ЛЮБЫМ провайдером/моделью от 9Router",
+  "How it works:": "Как это работает:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Запрос Antigravity/Copilot IDE → Перенаправление DNS на localhost:443 → Прокси MITM перехватывает → 9Router → ответ для Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Нет ключей API — создайте один на странице ключей",
+  "sk_9router (default)": "sk_9router (по умолчанию)",
+  "Server started": "Сервер запущен",
+  "Failed to start server": "Ошибка при запуске сервера",
+  "Server stopped — all DNS cleared": "Сервер остановлен — все DNS очищено",
+  "Failed to stop server": "Ошибка при остановке сервера",
+  "Sudo password is required": "Требуется пароль sudo",
+  "Stop Server": "Остановить сервер",
+  "Start Server": "Запустить сервер",
+  "Enable DNS per tool below to activate interception": "Включите DNS для каждого инструмента ниже, чтобы активировать перехват",
+  "Sudo Password Required": "Требуется пароль Sudo",
+  "Enter your sudo password to start/stop MITM server": "Введите пароль sudo для запуска/остановки сервера MITM",
+  "Sudo Password": "Пароль sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Нажмите, чтобы добавить, нажмите ещё раз, чтобы удалить. Изменения сохраняются автоматически.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Уведомление о риске: Этот провайдер использует сессию подписки/OAuth, не имеющую официальной лицензии для использования через прокси/маршрутизатор. Аккаунт может быть ограничен или заблокирован. Используйте на свой страх и риск.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM перехватывает HTTPS-трафик IDE-инструментов (Antigravity, GitHub Copilot, Kiro) через локальный CA для перенаправления запросов вашим провайдерам. Может нарушить ToS → риск блокировки аккаунта. Используйте на свой страх и риск.",
+  "Endpoint is exposed without an API key.": "Эндпоинт открыт без API-ключа."
+}
diff --git a/public/i18n/literals/sv.json b/public/i18n/literals/sv.json
new file mode 100644
index 0000000..0e4c3b4
--- /dev/null
+++ b/public/i18n/literals/sv.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Avbryt",
+  "Delete": "Ta bort",
+  "Edit": "Redigera",
+  "Save": "Spara",
+  "Close": "Stäng",
+  "Add": "Lägg till",
+  "Remove": "Ta bort",
+  "Settings": "Inställningar",
+  "Profile": "Profil",
+  "Dashboard": "Instrumentpanel",
+  "Logout": "Logga ut",
+  "Login": "Logga in",
+  "Providers": "Leverantörer",
+  "Usage": "Användarstatistik",
+  "API Key": "API-nyckel",
+  "Connected": "Ansluten",
+  "Disconnected": "Frånkopplad",
+  "Active": "Aktiv",
+  "Inactive": "Inaktiv",
+  "Success": "Framgång",
+  "Failed": "Misslyckad",
+  "Error": "Fel",
+  "Warning": "Varning",
+  "Info": "Information",
+  "Loading": "Laddar",
+  "Search": "Sök",
+  "Filter": "Filter",
+  "Sort": "Sortera",
+  "Export": "Exportera",
+  "Import": "Importera",
+  "Refresh": "Uppdatera",
+  "Back": "Tillbaka",
+  "Next": "Nästa",
+  "Previous": "Föregående",
+  "Submit": "Skicka",
+  "Confirm": "Bekräfta",
+  "Yes": "Ja",
+  "No": "Nej",
+  "OK": "OK",
+  "Apply": "Verkställ",
+  "Reset": "Återställ",
+  "Clear": "Rensa",
+  "Select": "Välj",
+  "Upload": "Ladda upp",
+  "Download": "Ladda ner",
+  "Copy": "Kopiera",
+  "Paste": "Klistra in",
+  "Cut": "Klipp ut",
+  "Undo": "Ångra",
+  "Redo": "Gör om",
+  "Name": "Namn",
+  "Description": "Beskrivning",
+  "Status": "Status",
+  "Type": "Typ",
+  "Date": "Datum",
+  "Time": "Tid",
+  "Created": "Skapad",
+  "Updated": "Uppdaterad",
+  "Actions": "Åtgärder",
+  "Details": "Detaljer",
+  "View": "Visa",
+  "New": "Ny",
+  "Total": "Totalt",
+  "Count": "Antal",
+  "Price": "Pris",
+  "Cost": "Kostnad",
+  "Free": "Gratis",
+  "Paid": "Betald",
+  "Enable": "Aktivera",
+  "Disable": "Inaktivera",
+  "Enabled": "Aktiverad",
+  "Disabled": "Inaktiverad",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Tillgänglig",
+  "Unavailable": "Inte tillgänglig",
+  "Required": "Krävs",
+  "Optional": "Valfritt",
+  "Default": "Standard",
+  "Custom": "Anpassad",
+  "Advanced": "Avancerat",
+  "Basic": "Grundläggande",
+  "Help": "Hjälp",
+  "Support": "Support",
+  "Documentation": "Dokumentation",
+  "Version": "Version",
+  "Language": "Språk",
+  "Theme": "Tema",
+  "Light": "Ljus",
+  "Dark": "Mörk",
+  "Auto": "Automatisk",
+  "Endpoint": "Slutpunkt",
+  "Combos": "Kombinationer",
+  "Quota Tracker": "Kvotspårare",
+  "MITM": "MITM",
+  "CLI Tools": "Verktyg",
+  "Console Log": "Konsollogg",
+  "System": "System",
+  "Debug": "Felsökning",
+  "Shutdown": "Stänga av",
+  "Close Proxy": "Stäng proxy",
+  "Are you sure you want to close the proxy server?": "Är du säker på att du vill stänga proxyservern?",
+  "Server Disconnected": "Server frånkopplad",
+  "The proxy server has been stopped.": "Proxyservern har stoppats.",
+  "Reload Page": "Läs in sidan på nytt",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Tjänsten körs i terminalen. Du kan stänga denna webbsida. Avstängning stoppar tjänsten.",
+  "Manage your AI provider connections": "Hantera dina AI-leverantörsanslutningar",
+  "Model combos with fallback": "Modellkombinationer med fallback",
+  "Monitor your API usage, token consumption, and request logs": "Övervaka din API-användning, tokenförbrukning och begärandeloggar",
+  "Intercept CLI tool traffic and route through 9Router": "Avlyssna CLI-verktygstrafik och dirigera genom 9Router",
+  "Configure CLI tools": "Konfigurera CLI-verktyg",
+  "API endpoint configuration": "Konfiguration av API-slutpunkt",
+  "Manage your preferences": "Hantera dina inställningar",
+  "Debug translation flow between formats": "Felsöka översättningsflöde mellan format",
+  "Live server console output": "Live-serverkonsoloutdata",
+  "Create model combos with fallback support": "Skapa modellkombinationer med fallback-stöd",
+  "Local Mode": "Lokalt läge",
+  "Running on your machine": "Körs på din maskin",
+  "Database Location": "Databasplats",
+  "Download Backup": "Ladda ner säkerhetskopia",
+  "Import Backup": "Importera säkerhetskopia",
+  "Database backup downloaded": "Databassäkerhetskopia nedladdad",
+  "Database imported successfully": "Databasen importerades framgångsrikt",
+  "Security": "Säkerhet",
+  "Require login": "Kräv inloggning",
+  "When ON, dashboard requires password. When OFF, access without login.": "När ON krävs lösenord för instrumentpanelen. När OFF, åtkomst utan inloggning.",
+  "Current Password": "Aktuellt lösenord",
+  "Enter current password": "Ange aktuellt lösenord",
+  "New Password": "Nytt lösenord",
+  "Enter new password": "Ange nytt lösenord",
+  "Confirm New Password": "Bekräfta nytt lösenord",
+  "Confirm new password": "Bekräfta nytt lösenord",
+  "Update Password": "Uppdatera lösenord",
+  "Set Password": "Ange lösenord",
+  "Password updated successfully": "Lösenord uppdaterades framgångsrikt",
+  "Passwords do not match": "Lösenorden matchar inte",
+  "Routing Strategy": "Routningsstrategi",
+  "Round Robin": "Omväxling",
+  "Cycle through accounts to distribute load": "Cykla genom konton för att distribuera belastningen",
+  "Sticky Limit": "Klibbig gräns",
+  "Calls per account before switching": "Anrop per konto innan byte",
+  "Network": "Nätverk",
+  "Outbound Proxy": "Utgående proxy",
+  "Enable proxy for OAuth + provider outbound requests.": "Aktivera proxy för utgående OAuth + leverantörsförfrågningar.",
+  "Proxy URL": "Proxy-URL",
+  "Leave empty to inherit existing env proxy (if any).": "Lämna tomt för att ärva befintlig env-proxy (om sådan finns).",
+  "No Proxy": "Ingen proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Kommaseparerade värdnamn/domäner för att kringgå proxyn.",
+  "Test proxy URL": "Testa proxy-URL",
+  "Proxy settings applied": "Proxyinställningar tillämpade",
+  "Proxy enabled": "Proxy aktiverad",
+  "Proxy disabled": "Proxy inaktiverad",
+  "Proxy test OK": "Proxy-test OK",
+  "Proxy test failed": "Proxy-test misslyckades",
+  "Please enter a Proxy URL to test": "Ange en proxy-URL att testa",
+  "Observability": "Observerbarhet",
+  "Enable Observability": "Aktivera observerbarhet",
+  "Turn request detail recording on/off globally": "Slå på/av inspelning av förfrågningsdetaljer globalt",
+  "Max Records": "Maximala poster",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Maximala begärandedetaljposter att behålla (äldre poster raderas automatiskt)",
+  "Batch Size": "Batchstorlek",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Antal objekt att ackumulera innan skrivning till databas (högre = bättre prestanda)",
+  "Flush Interval (ms)": "Spölningsintervall (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Maximal väntetid innan buffern spolas (förhindrar dataförlust vid låg trafik)",
+  "Max JSON Size (KB)": "Maximal JSON-storlek (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Maximal storlek för varje JSON-fält (begäran/svar) före trunkering",
+  "All data stored on your machine": "Alla data lagras på din maskin",
+  "MITM Server": "MITM-server",
+  "Running": "Körs",
+  "Stopped": "Stoppad",
+  "Cert": "Certifikat",
+  "Server": "Server",
+  "Purpose:": "Syfte:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Använd Antigravity IDE & GitHub Copilot → med VALFRI leverantör/modell från 9Router",
+  "How it works:": "Hur det fungerar:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE-begäran → DNS-omdirigering till localhost:443 → MITM-proxy avlyssnar → 9Router → svar till Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Inga API-nycklar — skapa en på nyckelsidan",
+  "sk_9router (default)": "sk_9router (standard)",
+  "Server started": "Servern startad",
+  "Failed to start server": "Misslyckades att starta servern",
+  "Server stopped — all DNS cleared": "Server stoppad — all DNS rensad",
+  "Failed to stop server": "Misslyckades att stoppa servern",
+  "Sudo password is required": "Sudo-lösenord krävs",
+  "Stop Server": "Stoppa server",
+  "Start Server": "Starta server",
+  "Enable DNS per tool below to activate interception": "Aktivera DNS för varje verktyg nedan för att aktivera avlyssning",
+  "Sudo Password Required": "Sudo-lösenord krävs",
+  "Enter your sudo password to start/stop MITM server": "Ange ditt sudo-lösenord för att starta/stoppa MITM-servern",
+  "Sudo Password": "Sudo-lösenord",
+  "Click to add, click again to remove. Changes are saved automatically.": "Klicka för att lägga till, klicka igen för att ta bort. Ändringar sparas automatiskt.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Riskmeddelande: Denna leverantör använder en prenumerations-/OAuth-session som inte är officiellt licensierad för proxy-/routeranvändning. Kontot kan begränsas eller bannlysas. Användning sker på egen risk.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM avlyssnar HTTPS-trafik från IDE-verktyg (Antigravity, GitHub Copilot, Kiro) via lokal CA för att omdirigera förfrågningar till dina leverantörer. Kan bryta mot ToS → risk för kontoavstängning. Användning sker på egen risk.",
+  "Endpoint is exposed without an API key.": "Slutpunkten är exponerad utan en API-nyckel."
+}
diff --git a/public/i18n/literals/th.json b/public/i18n/literals/th.json
new file mode 100644
index 0000000..6169829
--- /dev/null
+++ b/public/i18n/literals/th.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "ยกเลิก",
+  "Delete": "ลบ",
+  "Edit": "แก้ไข",
+  "Save": "บันทึก",
+  "Close": "ปิด",
+  "Add": "เพิ่ม",
+  "Remove": "นำออก",
+  "Settings": "การตั้งค่า",
+  "Profile": "โปรไฟล์",
+  "Dashboard": "แดชบอร์ด",
+  "Logout": "ออกจากระบบ",
+  "Login": "เข้าสู่ระบบ",
+  "Providers": "ผู้ให้บริการ",
+  "Usage": "สถิติการใช้งาน",
+  "API Key": "คีย์ API",
+  "Connected": "เชื่อมต่อแล้ว",
+  "Disconnected": "ตัดการเชื่อมต่อ",
+  "Active": "ใช้งาน",
+  "Inactive": "ไม่ใช้งาน",
+  "Success": "สำเร็จ",
+  "Failed": "ล้มเหลว",
+  "Error": "ข้อผิดพลาด",
+  "Warning": "คำเตือน",
+  "Info": "ข้อมูล",
+  "Loading": "กำลังโหลด",
+  "Search": "ค้นหา",
+  "Filter": "ตัวกรอง",
+  "Sort": "เรียงลำดับ",
+  "Export": "ส่งออก",
+  "Import": "นำเข้า",
+  "Refresh": "รีเฟรช",
+  "Back": "ย้อนกลับ",
+  "Next": "ถัดไป",
+  "Previous": "ก่อนหน้า",
+  "Submit": "ส่ง",
+  "Confirm": "ยืนยัน",
+  "Yes": "ใช่",
+  "No": "ไม่",
+  "OK": "ตกลง",
+  "Apply": "ใช้",
+  "Reset": "รีเซ็ต",
+  "Clear": "ล้าง",
+  "Select": "เลือก",
+  "Upload": "อัพโหลด",
+  "Download": "ดาวน์โหลด",
+  "Copy": "คัดลอก",
+  "Paste": "วาง",
+  "Cut": "ตัด",
+  "Undo": "ยกเลิก",
+  "Redo": "ทำซ้ำ",
+  "Name": "ชื่อ",
+  "Description": "คำอธิบาย",
+  "Status": "สถานะ",
+  "Type": "ประเภท",
+  "Date": "วันที่",
+  "Time": "เวลา",
+  "Created": "สร้างแล้ว",
+  "Updated": "อัพเดตแล้ว",
+  "Actions": "การกระทำ",
+  "Details": "รายละเอียด",
+  "View": "ดู",
+  "New": "ใหม่",
+  "Total": "ทั้งหมด",
+  "Count": "จำนวน",
+  "Price": "ราคา",
+  "Cost": "ต้นทุน",
+  "Free": "ฟรี",
+  "Paid": "จ่ายเงิน",
+  "Enable": "เปิดใช้งาน",
+  "Disable": "ปิดใช้งาน",
+  "Enabled": "เปิดใช้งานแล้ว",
+  "Disabled": "ปิดใช้งานแล้ว",
+  "Online": "ออนไลน์",
+  "Offline": "ออฟไลน์",
+  "Available": "พร้อมใช้งาน",
+  "Unavailable": "ไม่พร้อมใช้งาน",
+  "Required": "จำเป็น",
+  "Optional": "ไม่บังคับ",
+  "Default": "ค่าเริ่มต้น",
+  "Custom": "กำหนดเอง",
+  "Advanced": "ขั้นสูง",
+  "Basic": "พื้นฐาน",
+  "Help": "ช่วยเหลือ",
+  "Support": "สนับสนุน",
+  "Documentation": "เอกสาร",
+  "Version": "เวอร์ชัน",
+  "Language": "ภาษา",
+  "Theme": "ธีม",
+  "Light": "สว่าง",
+  "Dark": "มืด",
+  "Auto": "อัตโนมัติ",
+  "Endpoint": "จุดสิ้นสุด",
+  "Combos": "ชุดรวม",
+  "Quota Tracker": "ตัวติดตามโควต้า",
+  "MITM": "MITM",
+  "CLI Tools": "เครื่องมือ",
+  "Console Log": "บันทึกคอนโซล",
+  "System": "ระบบ",
+  "Debug": "ดีบัก",
+  "Shutdown": "ปิดระบบ",
+  "Close Proxy": "ปิด Proxy",
+  "Are you sure you want to close the proxy server?": "คุณแน่ใจหรือว่าต้องการปิดเซิร์ฟเวอร์ proxy?",
+  "Server Disconnected": "เซิร์ฟเวอร์ตัดการเชื่อมต่อ",
+  "The proxy server has been stopped.": "เซิร์ฟเวอร์ proxy ถูกหยุดแล้ว",
+  "Reload Page": "โหลดหน้าใหม่",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "บริการกำลังทำงานในเทอร์มินัล คุณสามารถปิดหน้าเว็บนี้ได้ การปิดระบบจะหยุดบริการ",
+  "Manage your AI provider connections": "จัดการการเชื่อมต่อผู้ให้บริการ AI ของคุณ",
+  "Model combos with fallback": "ชุดรวมโมเดลที่มี fallback",
+  "Monitor your API usage, token consumption, and request logs": "ติดตามการใช้งาน API การใช้งาน token และบันทึกคำขอของคุณ",
+  "Intercept CLI tool traffic and route through 9Router": "สกัดปะท่อ CLI และเส้นทางผ่าน 9Router",
+  "Configure CLI tools": "กำหนดค่าเครื่องมือ CLI",
+  "API endpoint configuration": "การตั้งค่าจุดสิ้นสุด API",
+  "Manage your preferences": "จัดการการตั้งค่าของคุณ",
+  "Debug translation flow between formats": "ดีบักการไหลของการแปลระหว่างรูปแบบ",
+  "Live server console output": "ผลลัพธ์คอนโซลเซิร์ฟเวอร์สด",
+  "Create model combos with fallback support": "สร้างชุดรวมโมเดลที่มีการสนับสนุน fallback",
+  "Local Mode": "โหมดท้องถิ่น",
+  "Running on your machine": "ทำงานบนเครื่องของคุณ",
+  "Database Location": "ตำแหน่งของฐานข้อมูล",
+  "Download Backup": "ดาวน์โหลดการสำรองข้อมูล",
+  "Import Backup": "นำเข้าการสำรองข้อมูล",
+  "Database backup downloaded": "ดาวน์โหลดการสำรองข้อมูลฐานข้อมูลแล้ว",
+  "Database imported successfully": "นำเข้าฐานข้อมูลเสร็จสิ้น",
+  "Security": "ความปลอดภัย",
+  "Require login": "ต้องการการเข้าสู่ระบบ",
+  "When ON, dashboard requires password. When OFF, access without login.": "เมื่อเปิด แดชบอร์ดต้องการรหัสผ่าน เมื่อปิด เข้าถึงโดยไม่ต้องเข้าสู่ระบบ",
+  "Current Password": "รหัสผ่านปัจจุบัน",
+  "Enter current password": "ป้อนรหัสผ่านปัจจุบัน",
+  "New Password": "รหัสผ่านใหม่",
+  "Enter new password": "ป้อนรหัสผ่านใหม่",
+  "Confirm New Password": "ยืนยันรหัสผ่านใหม่",
+  "Confirm new password": "ยืนยันรหัสผ่านใหม่",
+  "Update Password": "อัพเดตรหัสผ่าน",
+  "Set Password": "ตั้งรหัสผ่าน",
+  "Password updated successfully": "อัพเดตรหัสผ่านเสร็จสิ้น",
+  "Passwords do not match": "รหัสผ่านไม่ตรงกัน",
+  "Routing Strategy": "กลยุทธ์การเส้นทาง",
+  "Round Robin": "โรบินรอบ",
+  "Cycle through accounts to distribute load": "วนรอบบัญชีเพื่อกระจายการโหลด",
+  "Sticky Limit": "ขีดจำกัดที่เหนียว",
+  "Calls per account before switching": "การโทรต่อบัญชีก่อนการสลับ",
+  "Network": "เครือข่าย",
+  "Outbound Proxy": "Proxy ขาออก",
+  "Enable proxy for OAuth + provider outbound requests.": "เปิดใช้งาน proxy สำหรับคำขอขาออก OAuth + ผู้ให้บริการ",
+  "Proxy URL": "URL Proxy",
+  "Leave empty to inherit existing env proxy (if any).": "ปล่อยว่างไว้เพื่อสืบทอด proxy env ที่มีอยู่ (หากมี)",
+  "No Proxy": "ไม่มี Proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "ชื่อโฮสต์/โดเมนคั่นด้วยเครื่องหมายจุลภาค เพื่อข้าม proxy",
+  "Test proxy URL": "ทดสอบ URL Proxy",
+  "Proxy settings applied": "ใช้การตั้งค่า proxy แล้ว",
+  "Proxy enabled": "เปิดใช้งาน proxy",
+  "Proxy disabled": "ปิดใช้งาน proxy",
+  "Proxy test OK": "ทดสอบ proxy ตกลง",
+  "Proxy test failed": "ทดสอบ proxy ล้มเหลว",
+  "Please enter a Proxy URL to test": "กรุณาป้อน URL Proxy เพื่อทดสอบ",
+  "Observability": "ความสามารถในการสังเกต",
+  "Enable Observability": "เปิดใช้งานความสามารถในการสังเกต",
+  "Turn request detail recording on/off globally": "เปิด/ปิดการบันทึกรายละเอียดคำขอทั่วโลก",
+  "Max Records": "บันทึกสูงสุด",
+  "Maximum request detail records to keep (older records are auto-deleted)": "บันทึกรายละเอียดคำขอสูงสุดที่จะเก็บ (บันทึกเก่าจะลบโดยอัตโนมัติ)",
+  "Batch Size": "ขนาดแบตช์",
+  "Number of items to accumulate before writing to database (higher = better performance)": "จำนวนรายการที่จะรวบรวมก่อนเขียนลงฐานข้อมูล (สูงกว่า = ประสิทธิภาพดีกว่า)",
+  "Flush Interval (ms)": "ช่วงเวลาล้าง (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "เวลารอสูงสุดก่อนล้างบัฟเฟอร์ (ป้องกันการสูญหายข้อมูลในช่วงจราจรต่ำ)",
+  "Max JSON Size (KB)": "ขนาด JSON สูงสุด (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "ขนาดสูงสุดสำหรับแต่ละช่อง JSON (คำขอ/การตอบสนอง) ก่อนการตัดทอน",
+  "All data stored on your machine": "ข้อมูลทั้งหมดจัดเก็บไว้บนเครื่องของคุณ",
+  "MITM Server": "เซิร์ฟเวอร์ MITM",
+  "Running": "กำลังทำงาน",
+  "Stopped": "หยุดแล้ว",
+  "Cert": "ใบรับรอง",
+  "Server": "เซิร์ฟเวอร์",
+  "Purpose:": "วัตถุประสงค์:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "ใช้ Antigravity IDE & GitHub Copilot → ที่มีผู้ให้บริการ/โมเดลใด ๆ จาก 9Router",
+  "How it works:": "วิธีการทำงาน:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "คำขอ Antigravity/Copilot IDE → เปลี่ยนเส้นทาง DNS เป็น localhost:443 → MITM proxy สกัดปะท่อ → 9Router → ตอบสนอง Antigravity/Copilot",
+  "No API keys — create one in Keys page": "ไม่มีคีย์ API — สร้างคีย์ในหน้า Keys",
+  "sk_9router (default)": "sk_9router (ค่าเริ่มต้น)",
+  "Server started": "เซิร์ฟเวอร์เริ่มต้นแล้ว",
+  "Failed to start server": "ไม่สามารถเริ่มเซิร์ฟเวอร์",
+  "Server stopped — all DNS cleared": "หยุดเซิร์ฟเวอร์ — ล้าง DNS ทั้งหมด",
+  "Failed to stop server": "ไม่สามารถหยุดเซิร์ฟเวอร์",
+  "Sudo password is required": "ต้องการรหัสผ่าน sudo",
+  "Stop Server": "หยุดเซิร์ฟเวอร์",
+  "Start Server": "เริ่มเซิร์ฟเวอร์",
+  "Enable DNS per tool below to activate interception": "เปิดใช้งาน DNS สำหรับแต่ละเครื่องมือด้านล่างเพื่อเปิดใช้งานการสกัดปะท่อ",
+  "Sudo Password Required": "ต้องการรหัสผ่าน Sudo",
+  "Enter your sudo password to start/stop MITM server": "ป้อนรหัสผ่าน sudo ของคุณเพื่อเริ่ม/หยุดเซิร์ฟเวอร์ MITM",
+  "Sudo Password": "รหัสผ่าน Sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "คลิกเพื่อเพิ่ม คลิกอีกครั้งเพื่อลบ การเปลี่ยนแปลงจะถูกบันทึกโดยอัตโนมัติ",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ ประกาศความเสี่ยง: ผู้ให้บริการนี้ใช้เซสชันสมัครสมาชิก/OAuth ที่ไม่ได้รับอนุญาตอย่างเป็นทางการสำหรับการใช้งานพร็อกซี/เราเตอร์ บัญชีอาจถูกจำกัดหรือถูกแบน ใช้งานด้วยความเสี่ยงของคุณเอง",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM ดักจับการรับส่งข้อมูล HTTPS ของเครื่องมือ IDE (Antigravity, GitHub Copilot, Kiro) ผ่าน CA ท้องถิ่นเพื่อเปลี่ยนเส้นทางคำขอไปยังผู้ให้บริการของคุณ อาจละเมิด ToS → เสี่ยงถูกแบนบัญชี ใช้งานด้วยความเสี่ยงของคุณเอง",
+  "Endpoint is exposed without an API key.": "เอนด์พอยต์เปิดให้เข้าถึงโดยไม่มีคีย์ API"
+}
diff --git a/public/i18n/literals/tl.json b/public/i18n/literals/tl.json
new file mode 100644
index 0000000..51af4e2
--- /dev/null
+++ b/public/i18n/literals/tl.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Kanselahin",
+  "Delete": "Tanggalin",
+  "Edit": "Baguhin",
+  "Save": "Salin",
+  "Close": "Isara",
+  "Add": "Magdagdag",
+  "Remove": "Alisin",
+  "Settings": "Mga Setting",
+  "Profile": "Propesyal",
+  "Dashboard": "Dashboard",
+  "Logout": "Maglog out",
+  "Login": "Magsimula ng sesyon",
+  "Providers": "Mga Provider",
+  "Usage": "Mga Istatistika ng Paggamit",
+  "API Key": "Susi ng API",
+  "Connected": "Konektado",
+  "Disconnected": "Hindi Konektado",
+  "Active": "Aktibo",
+  "Inactive": "Hindi Aktibo",
+  "Success": "Matagumpay",
+  "Failed": "Nabigo",
+  "Error": "Kamalian",
+  "Warning": "Babala",
+  "Info": "Impormasyon",
+  "Loading": "Naglo-load",
+  "Search": "Maghanap",
+  "Filter": "Salain",
+  "Sort": "I-sort",
+  "Export": "I-export",
+  "Import": "I-import",
+  "Refresh": "I-refresh",
+  "Back": "Bumalik",
+  "Next": "Susunod",
+  "Previous": "Nakaraan",
+  "Submit": "Ipadala",
+  "Confirm": "Kumpirmahin",
+  "Yes": "Oo",
+  "No": "Hindi",
+  "OK": "OK",
+  "Apply": "Ilapat",
+  "Reset": "I-reset",
+  "Clear": "I-clear",
+  "Select": "Pumili",
+  "Upload": "Mag-upload",
+  "Download": "I-download",
+  "Copy": "Kopyahin",
+  "Paste": "I-paste",
+  "Cut": "Gupitin",
+  "Undo": "Undo",
+  "Redo": "I-redo",
+  "Name": "Pangalan",
+  "Description": "Paglalarawan",
+  "Status": "Kalagayan",
+  "Type": "Uri",
+  "Date": "Petsa",
+  "Time": "Oras",
+  "Created": "Ginawa",
+  "Updated": "Ina-update",
+  "Actions": "Mga Aksyon",
+  "Details": "Mga Detalye",
+  "View": "Tingnan",
+  "New": "Bago",
+  "Total": "Kabuuan",
+  "Count": "Bilang",
+  "Price": "Presyo",
+  "Cost": "Gastos",
+  "Free": "Libre",
+  "Paid": "Bayad",
+  "Enable": "Paganahin",
+  "Disable": "Huwag paganahin",
+  "Enabled": "Pinagana",
+  "Disabled": "Hindi pinagana",
+  "Online": "Online",
+  "Offline": "Offline",
+  "Available": "Available",
+  "Unavailable": "Hindi Available",
+  "Required": "Kinakailangan",
+  "Optional": "Opsyonal",
+  "Default": "Default",
+  "Custom": "Custom",
+  "Advanced": "Advanced",
+  "Basic": "Basic",
+  "Help": "Tulong",
+  "Support": "Suporta",
+  "Documentation": "Dokumentasyon",
+  "Version": "Bersyon",
+  "Language": "Wika",
+  "Theme": "Tema",
+  "Light": "Liwanag",
+  "Dark": "Madilim",
+  "Auto": "Awtomatiko",
+  "Endpoint": "Endpoint",
+  "Combos": "Mga Combo",
+  "Quota Tracker": "Quota Tracker",
+  "MITM": "MITM",
+  "CLI Tools": "Mga Tool",
+  "Console Log": "Console Log",
+  "System": "Sistema",
+  "Debug": "I-debug",
+  "Shutdown": "Patugharin",
+  "Close Proxy": "Isara ang Proxy",
+  "Are you sure you want to close the proxy server?": "Sigurado ka ba na gusto mong isara ang proxy server?",
+  "Server Disconnected": "Ang Server ay Naka-disconnect",
+  "The proxy server has been stopped.": "Ang proxy server ay tumigil na.",
+  "Reload Page": "I-reload ang Pahina",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Ang serbisyo ay tumatakbo sa terminal. Maaari mong isara ang web page na ito. Ang Shutdown ay titigil ng serbisyo.",
+  "Manage your AI provider connections": "Pamahalaan ang iyong mga koneksyon ng AI provider",
+  "Model combos with fallback": "Mga model combo na may fallback",
+  "Monitor your API usage, token consumption, and request logs": "Subaybayan ang iyong paggamit ng API, pagkonsumo ng token, at mga log ng request",
+  "Intercept CLI tool traffic and route through 9Router": "Harangin ang lalu ng CLI tool at i-route sa pamamagitan ng 9Router",
+  "Configure CLI tools": "I-configure ang CLI tools",
+  "API endpoint configuration": "Konfiguration ng API endpoint",
+  "Manage your preferences": "Pamahalaan ang iyong mga kagustuhan",
+  "Debug translation flow between formats": "I-debug ang translation flow sa pagitan ng mga format",
+  "Live server console output": "Live server console output",
+  "Create model combos with fallback support": "Lumikha ng mga model combo na may fallback support",
+  "Local Mode": "Local Mode",
+  "Running on your machine": "Tumatakbo sa iyong machine",
+  "Database Location": "Lokasyon ng Database",
+  "Download Backup": "I-download ang Backup",
+  "Import Backup": "I-import ang Backup",
+  "Database backup downloaded": "Ang database backup ay na-download",
+  "Database imported successfully": "Ang database ay matagumpay na nai-import",
+  "Security": "Seguridad",
+  "Require login": "Kailangan ng login",
+  "When ON, dashboard requires password. When OFF, access without login.": "Kapag ON, ang dashboard ay nangangailangan ng password. Kapag OFF, access nang walang login.",
+  "Current Password": "Kasalukuyang Password",
+  "Enter current password": "Ipasok ang kasalukuyang password",
+  "New Password": "Bagong Password",
+  "Enter new password": "Ipasok ang bagong password",
+  "Confirm New Password": "Kumpirmahin ang Bagong Password",
+  "Confirm new password": "Kumpirmahin ang bagong password",
+  "Update Password": "I-update ang Password",
+  "Set Password": "I-set ang Password",
+  "Password updated successfully": "Ang password ay matagumpay na na-update",
+  "Passwords do not match": "Ang mga password ay hindi tumutugma",
+  "Routing Strategy": "Routing Strategy",
+  "Round Robin": "Round Robin",
+  "Cycle through accounts to distribute load": "Umiikot sa mga account upang ipamahagi ang load",
+  "Sticky Limit": "Sticky Limit",
+  "Calls per account before switching": "Mga tawag bawat account bago mag-switch",
+  "Network": "Network",
+  "Outbound Proxy": "Outbound Proxy",
+  "Enable proxy for OAuth + provider outbound requests.": "Paganahin ang proxy para sa OAuth + provider outbound requests.",
+  "Proxy URL": "Proxy URL",
+  "Leave empty to inherit existing env proxy (if any).": "Iwanan kung walang laman upang mamanin ang umiiral na env proxy (kung mayroon).",
+  "No Proxy": "Walang Proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Mga hostname/domain na pinagseparang komma upang lampasan ang proxy.",
+  "Test proxy URL": "Subukan ang Proxy URL",
+  "Proxy settings applied": "Ang mga setting ng proxy ay inilapat",
+  "Proxy enabled": "Ang proxy ay pinagana",
+  "Proxy disabled": "Ang proxy ay hindi pinagana",
+  "Proxy test OK": "Proxy test OK",
+  "Proxy test failed": "Ang proxy test ay nabigo",
+  "Please enter a Proxy URL to test": "Pakiusap na ipasok ang Proxy URL upang subukan",
+  "Observability": "Observability",
+  "Enable Observability": "Paganahin ang Observability",
+  "Turn request detail recording on/off globally": "I-turn on/off ang request detail recording nang pandaigdig",
+  "Max Records": "Max Records",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Pinakamataas na request detail records na papanatilihin (ang mga lumang record ay awtomatikong tatanggalin)",
+  "Batch Size": "Batch Size",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Bilang ng mga item na mag-ipon bago magsulat sa database (mas mataas = mas magandang performance)",
+  "Flush Interval (ms)": "Flush Interval (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Pinakamataas na oras na paghihintay bago mag-flush ng buffer (pumipigil sa pagkawala ng data sa panahon ng mababang traffic)",
+  "Max JSON Size (KB)": "Max JSON Size (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Pinakamataas na sukat para sa bawat JSON field (request/response) bago ang truncation",
+  "All data stored on your machine": "Lahat ng data ay nakaimbak sa iyong machine",
+  "MITM Server": "MITM Server",
+  "Running": "Tumatakbo",
+  "Stopped": "Tumigil",
+  "Cert": "Cert",
+  "Server": "Server",
+  "Purpose:": "Layunin:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Gamitin ang Antigravity IDE & GitHub Copilot → sa ANUMANG provider/model mula sa 9Router",
+  "How it works:": "Paano ito gumagana:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE request → DNS redirect sa localhost:443 → MITM proxy intercepts → 9Router → response sa Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Walang API keys — lumikha ng isa sa Keys page",
+  "sk_9router (default)": "sk_9router (default)",
+  "Server started": "Ang server ay nagsimula",
+  "Failed to start server": "Nabigo na magsimula ang server",
+  "Server stopped — all DNS cleared": "Ang server ay tumigil — lahat ng DNS ay naka-clear",
+  "Failed to stop server": "Nabigo na ihinto ang server",
+  "Sudo password is required": "Kailangan ng sudo password",
+  "Stop Server": "Ihinto ang Server",
+  "Start Server": "Simulan ang Server",
+  "Enable DNS per tool below to activate interception": "Paganahin ang DNS para sa bawat tool sa ibaba upang aktivahin ang interception",
+  "Sudo Password Required": "Kailangan ng Sudo Password",
+  "Enter your sudo password to start/stop MITM server": "Ipasok ang iyong sudo password upang simulan/ihinto ang MITM server",
+  "Sudo Password": "Sudo Password",
+  "Click to add, click again to remove. Changes are saved automatically.": "I-click para idagdag, i-click muli para alisin. Ang mga pagbabago ay awtomatikong nase-save.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Babala sa Panganib: Ang provider na ito ay gumagamit ng subscription/OAuth session na hindi opisyal na lisensyado para sa proxy/router na paggamit. Maaaring marestrikta o ma-ban ang account. Gamitin sa sarili mong panganib.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ Hinaharang ng MITM ang HTTPS traffic ng mga IDE tool (Antigravity, GitHub Copilot, Kiro) sa pamamagitan ng lokal na CA upang i-redirect ang mga kahilingan sa iyong mga provider. Maaaring lumabag sa ToS → panganib ng pag-ban sa account. Gamitin sa sarili mong panganib.",
+  "Endpoint is exposed without an API key.": "Nakalantad ang endpoint nang walang API key."
+}
diff --git a/public/i18n/literals/tr.json b/public/i18n/literals/tr.json
new file mode 100644
index 0000000..ac4042a
--- /dev/null
+++ b/public/i18n/literals/tr.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "İptal",
+  "Delete": "Sil",
+  "Edit": "Düzenle",
+  "Save": "Kaydet",
+  "Close": "Kapat",
+  "Add": "Ekle",
+  "Remove": "Kaldır",
+  "Settings": "Ayarlar",
+  "Profile": "Profil",
+  "Dashboard": "Kontrol Paneli",
+  "Logout": "Çıkış Yap",
+  "Login": "Giriş Yap",
+  "Providers": "Sağlayıcılar",
+  "Usage": "Kullanım İstatistikleri",
+  "API Key": "API Anahtarı",
+  "Connected": "Bağlı",
+  "Disconnected": "Bağlantısı Kesildi",
+  "Active": "Etkin",
+  "Inactive": "Etkin Değil",
+  "Success": "Başarılı",
+  "Failed": "Başarısız",
+  "Error": "Hata",
+  "Warning": "Uyarı",
+  "Info": "Bilgi",
+  "Loading": "Yükleniyor",
+  "Search": "Ara",
+  "Filter": "Filtre",
+  "Sort": "Sırala",
+  "Export": "Dışa Aktar",
+  "Import": "İçe Aktar",
+  "Refresh": "Yenile",
+  "Back": "Geri",
+  "Next": "İleri",
+  "Previous": "Önceki",
+  "Submit": "Gönder",
+  "Confirm": "Onayla",
+  "Yes": "Evet",
+  "No": "Hayır",
+  "OK": "Tamam",
+  "Apply": "Uygula",
+  "Reset": "Sıfırla",
+  "Clear": "Temizle",
+  "Select": "Seç",
+  "Upload": "Yükle",
+  "Download": "İndir",
+  "Copy": "Kopyala",
+  "Paste": "Yapıştır",
+  "Cut": "Kes",
+  "Undo": "Geri Al",
+  "Redo": "Yinele",
+  "Name": "Ad",
+  "Description": "Açıklama",
+  "Status": "Durum",
+  "Type": "Tür",
+  "Date": "Tarih",
+  "Time": "Saat",
+  "Created": "Oluşturuldu",
+  "Updated": "Güncellendi",
+  "Actions": "İşlemler",
+  "Details": "Ayrıntılar",
+  "View": "Görüntüle",
+  "New": "Yeni",
+  "Total": "Toplam",
+  "Count": "Sayı",
+  "Price": "Fiyat",
+  "Cost": "Maliyet",
+  "Free": "Ücretsiz",
+  "Paid": "Ücretli",
+  "Enable": "Etkinleştir",
+  "Disable": "Devre Dışı Bırak",
+  "Enabled": "Etkinleştirildi",
+  "Disabled": "Devre Dışı Bırakıldı",
+  "Online": "Çevrimiçi",
+  "Offline": "Çevrimdışı",
+  "Available": "Kullanılabilir",
+  "Unavailable": "Kullanılamıyor",
+  "Required": "Gerekli",
+  "Optional": "İsteğe Bağlı",
+  "Default": "Varsayılan",
+  "Custom": "Özel",
+  "Advanced": "Gelişmiş",
+  "Basic": "Temel",
+  "Help": "Yardım",
+  "Support": "Destek",
+  "Documentation": "Belgeler",
+  "Version": "Sürüm",
+  "Language": "Dil",
+  "Theme": "Tema",
+  "Light": "Açık",
+  "Dark": "Koyu",
+  "Auto": "Otomatik",
+  "Endpoint": "Uç Nokta",
+  "Combos": "Kombinasyonlar",
+  "Quota Tracker": "Kota İzleyici",
+  "MITM": "MITM",
+  "CLI Tools": "Araçlar",
+  "Console Log": "Konsol Günlüğü",
+  "System": "Sistem",
+  "Debug": "Hata Ayıkla",
+  "Shutdown": "Kapat",
+  "Close Proxy": "Proxy'yi Kapat",
+  "Are you sure you want to close the proxy server?": "Proxy sunucusunu kapatmak istediğinizden emin misiniz?",
+  "Server Disconnected": "Sunucu Bağlantısı Kesildi",
+  "The proxy server has been stopped.": "Proxy sunucusu durduruldu.",
+  "Reload Page": "Sayfayı Yenile",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Hizmet terminalde çalışıyor. Bu web sayfasını kapatabilirsiniz. Kapatma, hizmeti durduracaktır.",
+  "Manage your AI provider connections": "AI sağlayıcı bağlantılarınızı yönetin",
+  "Model combos with fallback": "Yedek desteğiyle model kombinasyonları",
+  "Monitor your API usage, token consumption, and request logs": "API kullanımınızı, token tüketimini ve istek günlüklerini izleyin",
+  "Intercept CLI tool traffic and route through 9Router": "CLI araç trafiğini yakalayın ve 9Router üzerinden yönlendirin",
+  "Configure CLI tools": "CLI araçlarını yapılandırın",
+  "API endpoint configuration": "API uç noktası yapılandırması",
+  "Manage your preferences": "Tercihlerinizi yönetin",
+  "Debug translation flow between formats": "Formatlar arasındaki çeviri akışında hata ayıklayın",
+  "Live server console output": "Canlı sunucu konsol çıkışı",
+  "Create model combos with fallback support": "Yedek destek ile model kombinasyonları oluşturun",
+  "Local Mode": "Yerel Mod",
+  "Running on your machine": "Makinenizde çalışıyor",
+  "Database Location": "Veritabanı Konumu",
+  "Download Backup": "Yedeklemeyi İndir",
+  "Import Backup": "Yedeklemeyi İçe Aktar",
+  "Database backup downloaded": "Veritabanı yedeklemesi indirildi",
+  "Database imported successfully": "Veritabanı başarıyla içe aktarıldı",
+  "Security": "Güvenlik",
+  "Require login": "Giriş Gerekli",
+  "When ON, dashboard requires password. When OFF, access without login.": "AÇIK olduğunda, kontrol paneli parola gerektirir. KAPAL olduğunda, oturum açmadan erişin.",
+  "Current Password": "Mevcut Parola",
+  "Enter current password": "Mevcut parolayı girin",
+  "New Password": "Yeni Parola",
+  "Enter new password": "Yeni parolayı girin",
+  "Confirm New Password": "Yeni Parolayı Onayla",
+  "Confirm new password": "Yeni parolayı onayla",
+  "Update Password": "Parolayı Güncelle",
+  "Set Password": "Parola Ayarla",
+  "Password updated successfully": "Parola başarıyla güncellendi",
+  "Passwords do not match": "Parolalar eşleşmiyor",
+  "Routing Strategy": "Yönlendirme Stratejisi",
+  "Round Robin": "Dönerektir",
+  "Cycle through accounts to distribute load": "Yükü dağıtmak için hesaplar arasında döngü yapın",
+  "Sticky Limit": "Yapışkan Sınır",
+  "Calls per account before switching": "Geçiş öncesi hesap başına çağrılar",
+  "Network": "Ağ",
+  "Outbound Proxy": "Giden Proxy",
+  "Enable proxy for OAuth + provider outbound requests.": "OAuth + sağlayıcı giden istekleri için proxy'yi etkinleştirin.",
+  "Proxy URL": "Proxy URL'si",
+  "Leave empty to inherit existing env proxy (if any).": "Mevcut ortam proxy'sini (varsa) devralması için boş bırakın.",
+  "No Proxy": "Proxy Yok",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Proxy'yi atlamak için virgülle ayrılmış ana bilgisayar adları/etki alanları.",
+  "Test proxy URL": "Test Proxy URL'si",
+  "Proxy settings applied": "Proxy ayarları uygulandı",
+  "Proxy enabled": "Proxy etkinleştirildi",
+  "Proxy disabled": "Proxy devre dışı bırakıldı",
+  "Proxy test OK": "Proxy testi Tamam",
+  "Proxy test failed": "Proxy testi başarısız",
+  "Please enter a Proxy URL to test": "Test etmek için lütfen bir Proxy URL'si girin",
+  "Observability": "Gözlemlenebilirlik",
+  "Enable Observability": "Gözlemlenebilirliği Etkinleştir",
+  "Turn request detail recording on/off globally": "İstek ayrıntıları kaydını genel olarak aç/kapat",
+  "Max Records": "Maksimum Kayıtlar",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Tutulacak maksimum istek ayrıntı kayıtları (eski kayıtlar otomatik olarak silinir)",
+  "Batch Size": "Toplu İşlem Boyutu",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Veritabanına yazmadan önce biriktirilecek öğe sayısı (daha yüksek = daha iyi performans)",
+  "Flush Interval (ms)": "Temizleme Aralığı (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Arabelleği temizlemeden önce beklenecek maksimum süre (düşük trafikte veri kaybını engeller)",
+  "Max JSON Size (KB)": "Maksimum JSON Boyutu (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Kesilmeden önce her JSON alanı (istek/yanıt) için maksimum boyut",
+  "All data stored on your machine": "Tüm veriler makinenizde depolanır",
+  "MITM Server": "MITM Sunucusu",
+  "Running": "Çalışıyor",
+  "Stopped": "Durduruldu",
+  "Cert": "Sertifika",
+  "Server": "Sunucu",
+  "Purpose:": "Amaç:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Antigravity IDE & GitHub Copilot kullanın → 9Router'dan HERHANGİ bir sağlayıcı/model ile",
+  "How it works:": "Nasıl çalışır:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE isteği → DNS'i localhost:443'e yönlendir → MITM proxy yakalar → 9Router → Antigravity/Copilot'a yanıt",
+  "No API keys — create one in Keys page": "API anahtarı yok — Keys sayfasında bir tane oluşturun",
+  "sk_9router (default)": "sk_9router (varsayılan)",
+  "Server started": "Sunucu başlatıldı",
+  "Failed to start server": "Sunucu başlatılamadı",
+  "Server stopped — all DNS cleared": "Sunucu durduruldu — tüm DNS temizlendi",
+  "Failed to stop server": "Sunucu durdurulamadı",
+  "Sudo password is required": "Sudo parolası gereklidir",
+  "Stop Server": "Sunucuyu Durdur",
+  "Start Server": "Sunucuyu Başlat",
+  "Enable DNS per tool below to activate interception": "Yakalamayı etkinleştirmek için aşağıdaki her araç için DNS'i etkinleştirin",
+  "Sudo Password Required": "Sudo Parolası Gerekli",
+  "Enter your sudo password to start/stop MITM server": "MITM sunucusunu başlatmak/durdurmak için sudo parolanızı girin",
+  "Sudo Password": "Sudo Parolası",
+  "Click to add, click again to remove. Changes are saved automatically.": "Eklemek için tıklayın, kaldırmak için tekrar tıklayın. Değişiklikler otomatik olarak kaydedilir.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Risk Bildirimi: Bu sağlayıcı, proxy/yönlendirici kullanımı için resmi olarak lisanslı olmayan bir abonelik/OAuth oturumu kullanır. Hesap kısıtlanabilir veya yasaklanabilir. Kendi sorumluluğunuzda kullanın.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM, isteklerinizi sağlayıcılarınıza yönlendirmek için yerel CA aracılığıyla IDE araçlarının (Antigravity, GitHub Copilot, Kiro) HTTPS trafiğini engeller. ToS'u ihlal edebilir → hesap yasaklama riski. Kendi sorumluluğunuzda kullanın.",
+  "Endpoint is exposed without an API key.": "Uç nokta API anahtarı olmadan açıkta."
+}
diff --git a/public/i18n/literals/uk.json b/public/i18n/literals/uk.json
new file mode 100644
index 0000000..e238ad2
--- /dev/null
+++ b/public/i18n/literals/uk.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Скасувати",
+  "Delete": "Видалити",
+  "Edit": "Редагувати",
+  "Save": "Зберегти",
+  "Close": "Закрити",
+  "Add": "Додати",
+  "Remove": "Видалити",
+  "Settings": "Налаштування",
+  "Profile": "Профіль",
+  "Dashboard": "Панель керування",
+  "Logout": "Вийти",
+  "Login": "Увійти",
+  "Providers": "Постачальники",
+  "Usage": "Статистика використання",
+  "API Key": "Ключ API",
+  "Connected": "Підключено",
+  "Disconnected": "Відключено",
+  "Active": "Активний",
+  "Inactive": "Неактивний",
+  "Success": "Успіх",
+  "Failed": "Помилка",
+  "Error": "Помилка",
+  "Warning": "Попередження",
+  "Info": "Інформація",
+  "Loading": "Завантаження",
+  "Search": "Пошук",
+  "Filter": "Фільтр",
+  "Sort": "Сортування",
+  "Export": "Експорт",
+  "Import": "Імпорт",
+  "Refresh": "Оновити",
+  "Back": "Назад",
+  "Next": "Далі",
+  "Previous": "Попередній",
+  "Submit": "Надіслати",
+  "Confirm": "Підтвердити",
+  "Yes": "Так",
+  "No": "Ні",
+  "OK": "ОК",
+  "Apply": "Застосувати",
+  "Reset": "Скинути",
+  "Clear": "Очистити",
+  "Select": "Вибрати",
+  "Upload": "Завантажити",
+  "Download": "Завантажити",
+  "Copy": "Копіювати",
+  "Paste": "Вставити",
+  "Cut": "Вирізати",
+  "Undo": "Відмінити",
+  "Redo": "Повторити",
+  "Name": "Назва",
+  "Description": "Опис",
+  "Status": "Статус",
+  "Type": "Тип",
+  "Date": "Дата",
+  "Time": "Час",
+  "Created": "Створено",
+  "Updated": "Оновлено",
+  "Actions": "Дії",
+  "Details": "Деталі",
+  "View": "Перегляд",
+  "New": "Новий",
+  "Total": "Всього",
+  "Count": "Кількість",
+  "Price": "Ціна",
+  "Cost": "Вартість",
+  "Free": "Безплатно",
+  "Paid": "Платно",
+  "Enable": "Увімкнути",
+  "Disable": "Вимкнути",
+  "Enabled": "Увімкнено",
+  "Disabled": "Вимкнено",
+  "Online": "Онлайн",
+  "Offline": "Офлайн",
+  "Available": "Доступно",
+  "Unavailable": "Недоступно",
+  "Required": "Обов'язково",
+  "Optional": "Опційно",
+  "Default": "За замовчуванням",
+  "Custom": "Користувацький",
+  "Advanced": "Розширені",
+  "Basic": "Базовий",
+  "Help": "Допомога",
+  "Support": "Підтримка",
+  "Documentation": "Документація",
+  "Version": "Версія",
+  "Language": "Мова",
+  "Theme": "Тема",
+  "Light": "Світла",
+  "Dark": "Темна",
+  "Auto": "Авто",
+  "Endpoint": "Кінцева точка",
+  "Combos": "Комбо",
+  "Quota Tracker": "Відстеження квоти",
+  "MITM": "MITM",
+  "CLI Tools": "Інструменти",
+  "Console Log": "Журнал консолі",
+  "System": "Система",
+  "Debug": "Налагодження",
+  "Shutdown": "Вимкнення",
+  "Close Proxy": "Закрити проксі",
+  "Are you sure you want to close the proxy server?": "Ви впевнені, що хочете закрити сервер проксі?",
+  "Server Disconnected": "Сервер відключено",
+  "The proxy server has been stopped.": "Сервер проксі було зупинено.",
+  "Reload Page": "Перезавантажити сторінку",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Служба працює в терміналі. Ви можете закрити цю веб-сторінку. Вимкнення призупинить службу.",
+  "Manage your AI provider connections": "Керуйте своїми з'єднаннями постачальника AI",
+  "Model combos with fallback": "Комбо моделей з резервуванням",
+  "Monitor your API usage, token consumption, and request logs": "Відстежуйте використання API, споживання токенів та журнали запитів",
+  "Intercept CLI tool traffic and route through 9Router": "Перехопіть трафік інструменту CLI та маршрутизуйте через 9Router",
+  "Configure CLI tools": "Налаштуйте інструменти CLI",
+  "API endpoint configuration": "Конфігурація кінцевої точки API",
+  "Manage your preferences": "Керуйте своїми уподобаннями",
+  "Debug translation flow between formats": "Налагодити потік перекладу між форматами",
+  "Live server console output": "Вихід консолі живого сервера",
+  "Create model combos with fallback support": "Створіть комбо моделей з підтримкою резервування",
+  "Local Mode": "Локальний режим",
+  "Running on your machine": "Запуск на вашій машині",
+  "Database Location": "Розташування бази даних",
+  "Download Backup": "Завантажити резервну копію",
+  "Import Backup": "Імпортувати резервну копію",
+  "Database backup downloaded": "Резервну копію бази даних завантажено",
+  "Database imported successfully": "Базу даних успішно імпортовано",
+  "Security": "Безпека",
+  "Require login": "Потрібне входження",
+  "When ON, dashboard requires password. When OFF, access without login.": "Коли ВІД, панель керування потребує пароля. Коли ВИМКНЕНО, доступ без входження.",
+  "Current Password": "Поточний пароль",
+  "Enter current password": "Введіть поточний пароль",
+  "New Password": "Новий пароль",
+  "Enter new password": "Введіть новий пароль",
+  "Confirm New Password": "Підтвердіть новий пароль",
+  "Confirm new password": "Підтвердіть новий пароль",
+  "Update Password": "Оновити пароль",
+  "Set Password": "Встановити пароль",
+  "Password updated successfully": "Пароль успішно оновлено",
+  "Passwords do not match": "Паролі не збігаються",
+  "Routing Strategy": "Стратегія маршрутизації",
+  "Round Robin": "Циклічний розподіл",
+  "Cycle through accounts to distribute load": "Циклічне переключення облікових записів для розподілу навантаження",
+  "Sticky Limit": "Обмеження липкості",
+  "Calls per account before switching": "Виклики на обліковий запис перед перемиканням",
+  "Network": "Мережа",
+  "Outbound Proxy": "Вихідний проксі",
+  "Enable proxy for OAuth + provider outbound requests.": "Увімкніть проксі для запитів OAuth + постачальника на виході.",
+  "Proxy URL": "URL проксі",
+  "Leave empty to inherit existing env proxy (if any).": "Залиште порожнім, щоб успадкувати існуючий проксі env (якщо є).",
+  "No Proxy": "Без проксі",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Розділені комами імена хостів/домени для обходу проксі.",
+  "Test proxy URL": "Протестувати URL проксі",
+  "Proxy settings applied": "Параметри проксі застосовані",
+  "Proxy enabled": "Проксі увімкнено",
+  "Proxy disabled": "Проксі вимкнено",
+  "Proxy test OK": "Тест проксі OK",
+  "Proxy test failed": "Тест проксі не вдався",
+  "Please enter a Proxy URL to test": "Будь ласка, введіть URL проксі для тестування",
+  "Observability": "Спостережуваність",
+  "Enable Observability": "Увімкнути спостережуваність",
+  "Turn request detail recording on/off globally": "Увімкніть/вимкніть запис деталей запиту глобально",
+  "Max Records": "Максимальна кількість записів",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Максимальна кількість записів деталей запиту для зберігання (старші записи автоматично видаляються)",
+  "Batch Size": "Розмір пакету",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Кількість елементів для накопичення перед записом у базу даних (вище = краща продуктивність)",
+  "Flush Interval (ms)": "Інтервал промивки (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Максимальний час очікування перед промиванням буфера (запобігає втраті даних під час низького трафіку)",
+  "Max JSON Size (KB)": "Максимальний розмір JSON (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Максимальний розмір для кожного поля JSON (запит/відповідь) перед усіканням",
+  "All data stored on your machine": "Усі дані зберігаються на вашій машині",
+  "MITM Server": "MITM сервер",
+  "Running": "Запущено",
+  "Stopped": "Зупинено",
+  "Cert": "Сертифікат",
+  "Server": "Сервер",
+  "Purpose:": "Мета:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Використовуйте Antigravity IDE & GitHub Copilot → з БУДЬ-ЯКИМ постачальником/моделлю від 9Router",
+  "How it works:": "Як це працює:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Запит Antigravity/Copilot IDE → Перенаправлення DNS на localhost:443 → MITM проксі перехопити → 9Router → відповідь на Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Немає ключів API — створіть один на сторінці ключів",
+  "sk_9router (default)": "sk_9router (за замовчуванням)",
+  "Server started": "Сервер запущено",
+  "Failed to start server": "Не вдалося запустити сервер",
+  "Server stopped — all DNS cleared": "Сервер зупинено — усі DNS очищено",
+  "Failed to stop server": "Не вдалося зупинити сервер",
+  "Sudo password is required": "Потрібен пароль sudo",
+  "Stop Server": "Зупинити сервер",
+  "Start Server": "Запустити сервер",
+  "Enable DNS per tool below to activate interception": "Увімкніть DNS для кожного інструменту нижче, щоб активувати перехоплення",
+  "Sudo Password Required": "Потрібен пароль Sudo",
+  "Enter your sudo password to start/stop MITM server": "Введіть пароль sudo для запуску/зупинення MITM сервера",
+  "Sudo Password": "Пароль Sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Натисніть, щоб додати, натисніть ще раз, щоб видалити. Зміни зберігаються автоматично.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Сповіщення про ризик: Цей провайдер використовує сесію підписки/OAuth, яка офіційно не ліцензована для використання через проксі/маршрутизатор. Обліковий запис може бути обмежений або заблокований. Використовуйте на свій страх і ризик.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM перехоплює HTTPS-трафік IDE-інструментів (Antigravity, GitHub Copilot, Kiro) через локальний CA для перенаправлення запитів до ваших провайдерів. Може порушити ToS → ризик блокування облікового запису. Використовуйте на свій страх і ризик.",
+  "Endpoint is exposed without an API key.": "Кінцеву точку відкрито без API-ключа."
+}
diff --git a/public/i18n/literals/ur.json b/public/i18n/literals/ur.json
new file mode 100644
index 0000000..e592175
--- /dev/null
+++ b/public/i18n/literals/ur.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "منسوخ کریں",
+  "Delete": "حذف کریں",
+  "Edit": "ترمیم کریں",
+  "Save": "محفوظ کریں",
+  "Close": "بند کریں",
+  "Add": "شامل کریں",
+  "Remove": "ہٹائیں",
+  "Settings": "ترتیبات",
+  "Profile": "پروفائل",
+  "Dashboard": "ڈیش بورڈ",
+  "Logout": "لاگ آؤٹ",
+  "Login": "لاگ ان",
+  "Providers": "فراہم کنندگان",
+  "Usage": "استعمال کے اعدادوشمار",
+  "API Key": "API کلید",
+  "Connected": "منسلک",
+  "Disconnected": "منقطع",
+  "Active": "فعال",
+  "Inactive": "غیر فعال",
+  "Success": "کامیاب",
+  "Failed": "ناکام",
+  "Error": "خرابی",
+  "Warning": "انتباہ",
+  "Info": "معلومات",
+  "Loading": "لوڈ ہو رہا ہے",
+  "Search": "تلاش کریں",
+  "Filter": "فلٹر کریں",
+  "Sort": "ترتیب دیں",
+  "Export": "برآمد کریں",
+  "Import": "درآمد کریں",
+  "Refresh": "تازہ کریں",
+  "Back": "واپس",
+  "Next": "آگے",
+  "Previous": "پچھلا",
+  "Submit": "جمع کریں",
+  "Confirm": "تصدیق کریں",
+  "Yes": "جی",
+  "No": "نہیں",
+  "OK": "ٹھیک ہے",
+  "Apply": "لاگو کریں",
+  "Reset": "دوبارہ سیٹ کریں",
+  "Clear": "صاف کریں",
+  "Select": "منتخب کریں",
+  "Upload": "اپ لوڈ کریں",
+  "Download": "ڈاؤن لوڈ کریں",
+  "Copy": "کاپی کریں",
+  "Paste": "پیسٹ کریں",
+  "Cut": "کاٹ دیں",
+  "Undo": "واپسی",
+  "Redo": "دوبارہ کریں",
+  "Name": "نام",
+  "Description": "تفصیل",
+  "Status": "حالت",
+  "Type": "قسم",
+  "Date": "تاریخ",
+  "Time": "وقت",
+  "Created": "بنایا گیا",
+  "Updated": "اپڈیٹ شدہ",
+  "Actions": "اقدامات",
+  "Details": "تفصیلات",
+  "View": "دیکھیں",
+  "New": "نیا",
+  "Total": "کل",
+  "Count": "شمار",
+  "Price": "قیمت",
+  "Cost": "لاگت",
+  "Free": "مفت",
+  "Paid": "ادا شدہ",
+  "Enable": "فعال کریں",
+  "Disable": "غیر فعال کریں",
+  "Enabled": "فعال",
+  "Disabled": "غیر فعال",
+  "Online": "آن لائن",
+  "Offline": "آف لائن",
+  "Available": "دستیاب",
+  "Unavailable": "دستیاب نہیں",
+  "Required": "ضروری",
+  "Optional": "اختیاری",
+  "Default": "ڈیفالٹ",
+  "Custom": "حسب ضرورت",
+  "Advanced": "اعلیٰ",
+  "Basic": "بنیادی",
+  "Help": "مدد",
+  "Support": "معاونت",
+  "Documentation": "دستاویزات",
+  "Version": "ورژن",
+  "Language": "زبان",
+  "Theme": "تھیم",
+  "Light": "روشن",
+  "Dark": "تاریک",
+  "Auto": "خودکار",
+  "Endpoint": "اختتام نقطہ",
+  "Combos": "امتزاجات",
+  "Quota Tracker": "کوٹہ ٹریکر",
+  "MITM": "MITM",
+  "CLI Tools": "آلات",
+  "Console Log": "کنسول لاگ",
+  "System": "نظام",
+  "Debug": "ڈیبگ",
+  "Shutdown": "بند کریں",
+  "Close Proxy": "پروکسی بند کریں",
+  "Are you sure you want to close the proxy server?": "کیا آپ یقیناً پروکسی سرور کو بند کرنا چاہتے ہیں؟",
+  "Server Disconnected": "سرور منقطع",
+  "The proxy server has been stopped.": "پروکسی سرور بند کر دیا گیا ہے۔",
+  "Reload Page": "صفحہ دوبارہ لوڈ کریں",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "خدمت ٹرمینل میں چل رہی ہے۔ آپ یہ ویب صفحہ بند کر سکتے ہیں۔ شٹ ڈاؤن خدمت کو بند کر دے گا۔",
+  "Manage your AI provider connections": "اپنے AI فراہم کنندہ کنکشن کو منیج کریں",
+  "Model combos with fallback": "Fallback کے ساتھ ماڈل امتزاجات",
+  "Monitor your API usage, token consumption, and request logs": "اپنے API استعمال، ٹوکن کھپت، اور درخواست لاگز کی نگرانی کریں",
+  "Intercept CLI tool traffic and route through 9Router": "CLI ٹول ٹریفک کو روکیں اور 9Router کے ذریعے منتقل کریں",
+  "Configure CLI tools": "CLI آلات ترتیب دیں",
+  "API endpoint configuration": "API اختتام نقطہ کی ترتیب",
+  "Manage your preferences": "اپنی ترجیحات منیج کریں",
+  "Debug translation flow between formats": "شکلوں کے درمیان ترجمہ کے بہاؤ کو ڈیبگ کریں",
+  "Live server console output": "لائیو سرور کنسول آؤٹ پٹ",
+  "Create model combos with fallback support": "Fallback معاونت کے ساتھ ماڈل امتزاجات بنائیں",
+  "Local Mode": "مقامی موڈ",
+  "Running on your machine": "آپ کی مشین پر چل رہا ہے",
+  "Database Location": "ڈیٹابیس کی جگہ",
+  "Download Backup": "بیک اپ ڈاؤن لوڈ کریں",
+  "Import Backup": "بیک اپ درآمد کریں",
+  "Database backup downloaded": "ڈیٹابیس بیک اپ ڈاؤن لوڈ کیا گیا",
+  "Database imported successfully": "ڈیٹابیس کامیابی سے درآمد کیا گیا",
+  "Security": "سیکیورٹی",
+  "Require login": "لاگ ان کی ضرورت ہے",
+  "When ON, dashboard requires password. When OFF, access without login.": "جب آن ہو، ڈیش بورڈ کے لیے پاس ورڈ درکار ہے۔ جب آف ہو، بغیر لاگ ان کے رسائی حاصل کریں۔",
+  "Current Password": "موجودہ پاس ورڈ",
+  "Enter current password": "موجودہ پاس ورڈ داخل کریں",
+  "New Password": "نیا پاس ورڈ",
+  "Enter new password": "نیا پاس ورڈ داخل کریں",
+  "Confirm New Password": "نئے پاس ورڈ کی تصدیق کریں",
+  "Confirm new password": "نئے پاس ورڈ کی تصدیق کریں",
+  "Update Password": "پاس ورڈ اپڈیٹ کریں",
+  "Set Password": "پاس ورڈ سیٹ کریں",
+  "Password updated successfully": "پاس ورڈ کامیابی سے اپڈیٹ ہو گیا",
+  "Passwords do not match": "پاس ورڈ مماثل نہیں ہیں",
+  "Routing Strategy": "روٹنگ حکمت عملی",
+  "Round Robin": "دوری رابن",
+  "Cycle through accounts to distribute load": "بوجھ تقسیم کرنے کے لیے اکاؤنٹس کے ذریعے سائیکل کریں",
+  "Sticky Limit": "چپکنے والی حد",
+  "Calls per account before switching": "سوئچنگ سے پہلے فی اکاؤنٹ کالیں",
+  "Network": "نیٹ ورک",
+  "Outbound Proxy": "آؤٹ بائونڈ پروکسی",
+  "Enable proxy for OAuth + provider outbound requests.": "OAuth + فراہم کنندہ آؤٹ بائونڈ درخواستوں کے لیے پروکسی فعال کریں۔",
+  "Proxy URL": "پروکسی URL",
+  "Leave empty to inherit existing env proxy (if any).": "موجودہ env پروکسی کو وراثت میں دینے کے لیے خالی رکھیں (اگر کوئی ہو)۔",
+  "No Proxy": "کوئی پروکسی نہیں",
+  "Comma-separated hostnames/domains to bypass the proxy.": "پروکسی کو نظر انداز کرنے کے لیے کوما سے الگ شدہ ہوسٹ ناموں/ڈومین۔",
+  "Test proxy URL": "پروکسی URL کو ٹیسٹ کریں",
+  "Proxy settings applied": "پروکسی ترتیبات لاگو کی گئیں",
+  "Proxy enabled": "پروکسی فعال",
+  "Proxy disabled": "پروکسی غیر فعال",
+  "Proxy test OK": "پروکسی ٹیسٹ ٹھیک ہے",
+  "Proxy test failed": "پروکسی ٹیسٹ ناکام",
+  "Please enter a Proxy URL to test": "براہ کرم ٹیسٹ کے لیے ایک پروکسی URL داخل کریں",
+  "Observability": "نقطہ نظر کی صلاحیت",
+  "Enable Observability": "نقطہ نظر کی صلاحیت فعال کریں",
+  "Turn request detail recording on/off globally": "درخواست کی تفصیلات ریکارڈنگ کو عالمی طور پر آن/آف کریں",
+  "Max Records": "زیادہ سے زیادہ ریکارڈ",
+  "Maximum request detail records to keep (older records are auto-deleted)": "رکھنے کے لیے زیادہ سے زیادہ درخواست کی تفصیلات ریکارڈ (پرانے ریکارڈ خود بخود حذف ہو جاتے ہیں)",
+  "Batch Size": "بیچ سائز",
+  "Number of items to accumulate before writing to database (higher = better performance)": "ڈیٹابیس میں لکھنے سے پہلے جمع کرنے کے لیے اشیاء کی تعداد (زیادہ = بہتر کارکردگی)",
+  "Flush Interval (ms)": "فلش وقفہ (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "بفر کو فلش کرنے سے پہلے انتظار کرنے کا زیادہ سے زیادہ وقت (کم ٹریفک کے دوران ڈیٹا کے نقصان سے بچاتا ہے)",
+  "Max JSON Size (KB)": "زیادہ سے زیادہ JSON سائز (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "تشکیل سے پہلے ہر JSON فیلڈ کے لیے زیادہ سے زیادہ سائز (درخواست/جواب)",
+  "All data stored on your machine": "تمام ڈیٹا آپ کی مشین پر محفوظ ہے",
+  "MITM Server": "MITM سرور",
+  "Running": "چل رہا ہے",
+  "Stopped": "رکا ہوا",
+  "Cert": "سرٹیفکیٹ",
+  "Server": "سرور",
+  "Purpose:": "مقصد:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Antigravity IDE اور GitHub Copilot استعمال کریں → 9Router سے کسی بھی فراہم کنندہ/ماڈل کے ساتھ",
+  "How it works:": "یہ کیسے کام کرتا ہے:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE درخواست → DNS کو localhost:443 کی طرف ری ڈائریکٹ کریں → MITM پروکسی روکے → 9Router → Antigravity/Copilot کو جواب",
+  "No API keys — create one in Keys page": "کوئی API کلید نہیں — Keys صفحہ میں ایک بنائیں",
+  "sk_9router (default)": "sk_9router (ڈیفالٹ)",
+  "Server started": "سرور شروع ہوگیا",
+  "Failed to start server": "سرور شروع کرنے میں ناکام",
+  "Server stopped — all DNS cleared": "سرور بند — تمام DNS صاف کیے گئے",
+  "Failed to stop server": "سرور بند کرنے میں ناکام",
+  "Sudo password is required": "Sudo پاس ورڈ درکار ہے",
+  "Stop Server": "سرور بند کریں",
+  "Start Server": "سرور شروع کریں",
+  "Enable DNS per tool below to activate interception": "روک تھام کو فعال کرنے کے لیے نیچے ہر ٹول کے لیے DNS فعال کریں",
+  "Sudo Password Required": "Sudo پاس ورڈ درکار ہے",
+  "Enter your sudo password to start/stop MITM server": "MITM سرور شروع/بند کرنے کے لیے اپنا sudo پاس ورڈ داخل کریں",
+  "Sudo Password": "Sudo پاس ورڈ",
+  "Click to add, click again to remove. Changes are saved automatically.": "شامل کرنے کے لیے کلک کریں، ہٹانے کے لیے دوبارہ کلک کریں۔ تبدیلیاں خودکار طور پر محفوظ ہو جاتی ہیں۔",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ خطرے کا نوٹس: یہ فراہم کنندہ ایک سبسکرپشن/OAuth سیشن استعمال کرتا ہے جو پراکسی/راؤٹر استعمال کے لیے سرکاری طور پر لائسنس یافتہ نہیں ہے۔ اکاؤنٹ محدود یا پابند ہو سکتا ہے۔ اپنے خطرے پر استعمال کریں۔",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM آپ کے فراہم کنندگان کو درخواستوں کو ری ڈائریکٹ کرنے کے لیے مقامی CA کے ذریعے IDE ٹولز (Antigravity, GitHub Copilot, Kiro) کے HTTPS ٹریفک کو روکتا ہے۔ ToS کی خلاف ورزی کر سکتا ہے → اکاؤنٹ پابندی کا خطرہ۔ اپنے خطرے پر استعمال کریں۔",
+  "Endpoint is exposed without an API key.": "اینڈ پوائنٹ API کلید کے بغیر بے نقاب ہے۔"
+}
diff --git a/public/i18n/literals/vi.json b/public/i18n/literals/vi.json
new file mode 100644
index 0000000..5358d06
--- /dev/null
+++ b/public/i18n/literals/vi.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "Hủy",
+  "Delete": "Xóa",
+  "Edit": "Sửa",
+  "Save": "Lưu",
+  "Close": "Đóng",
+  "Add": "Thêm",
+  "Remove": "Xóa bỏ",
+  "Settings": "Cài đặt",
+  "Profile": "Hồ sơ",
+  "Dashboard": "Bảng điều khiển",
+  "Logout": "Đăng xuất",
+  "Login": "Đăng nhập",
+  "Providers": "Nhà cung cấp",
+  "Usage": "Thống kê",
+  "API Key": "Khóa API",
+  "Connected": " Đã kết nối",
+  "Disconnected": "Chưa kết nối",
+  "Active": "Hoạt động",
+  "Inactive": "Không hoạt động",
+  "Success": "Thành công",
+  "Failed": "Thất bại",
+  "Error": "Lỗi",
+  "Warning": "Cảnh báo",
+  "Info": "Thông tin",
+  "Loading": "Đang tải",
+  "Search": "Tìm kiếm",
+  "Filter": "Lọc",
+  "Sort": "Sắp xếp",
+  "Export": "Xuất",
+  "Import": "Nhập",
+  "Refresh": "Làm mới",
+  "Back": "Quay lại",
+  "Next": "Tiếp theo",
+  "Previous": "Trước",
+  "Submit": "Gửi",
+  "Confirm": "Xác nhận",
+  "Yes": "Có",
+  "No": "Không",
+  "OK": "OK",
+  "Apply": "Áp dụng",
+  "Reset": "Đặt lại",
+  "Clear": "Xóa",
+  "Select": "Chọn",
+  "Upload": "Tải lên",
+  "Download": "Tải xuống",
+  "Copy": "Sao chép",
+  "Paste": "Dán",
+  "Cut": "Cắt",
+  "Undo": "Hoàn tác",
+  "Redo": "Làm lại",
+  "Name": "Tên",
+  "Description": "Mô tả",
+  "Status": "Trạng thái",
+  "Type": "Loại",
+  "Date": "Ngày",
+  "Time": "Thời gian",
+  "Created": "Đã tạo",
+  "Updated": "Đã cập nhật",
+  "Actions": "Hành động",
+  "Details": "Chi tiết",
+  "View": "Xem",
+  "New": "Mới",
+  "Total": "Tổng",
+  "Count": "Số lượng",
+  "Price": "Giá",
+  "Cost": "Chi phí",
+  "Free": "Miễn phí",
+  "Paid": "Trả phí",
+  "Enable": "Bật",
+  "Disable": "Tắt",
+  "Enabled": "Đã bật",
+  "Disabled": "Đã tắt",
+  "Online": "Trực tuyến",
+  "Offline": "Ngoại tuyến",
+  "Available": "Có sẵn",
+  "Unavailable": "Không có sẵn",
+  "Required": "Bắt buộc",
+  "Optional": "Tùy chọn",
+  "Default": "Mặc định",
+  "Custom": "Tùy chỉnh",
+  "Advanced": "Nâng cao",
+  "Basic": "Cơ bản",
+  "Help": "Trợ giúp",
+  "Support": "Hỗ trợ",
+  "Documentation": "Tài liệu",
+  "Version": "Phiên bản",
+  "Language": "Ngôn ngữ",
+  "Theme": "Giao diện",
+  "Light": "Sáng",
+  "Dark": "Tối",
+  "Auto": "Tự động",
+  "Endpoint": "Điểm cuối",
+  "Combos": "Kết hợp",
+  "Quota Tracker": "Theo dõi hạn mức",
+  "MITM": "MITM",
+  "CLI Tools": "Công cụ",
+  "Console Log": "Nhật ký Console",
+  "System": "Hệ thống",
+  "Debug": "Gỡ lỗi",
+  "Shutdown": "Tắt ứng dụng",
+  "Close Proxy": "Đóng Proxy",
+  "Are you sure you want to close the proxy server?": "Bạn có chắc chắn muốn đóng máy chủ proxy không?",
+  "Server Disconnected": "Máy chủ đã ngắt kết nối",
+  "The proxy server has been stopped.": "Máy chủ proxy đã bị dừng.",
+  "Reload Page": "Tải lại trang",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "Dịch vụ đang chạy trong terminal. Bạn có thể đóng trang web này. Tắt ứng dụng sẽ dừng dịch vụ.",
+  "Manage your AI provider connections": "Quản lý kết nối nhà cung cấp AI của bạn",
+  "Model combos with fallback": "Kết hợp mô hình với dự phòng",
+  "Monitor your API usage, token consumption, and request logs": "Theo dõi việc sử dụng API, tiêu thụ token và nhật ký yêu cầu",
+  "Intercept CLI tool traffic and route through 9Router": "Chặn lưu lượng công cụ CLI và định tuyến qua 9Router",
+  "Configure CLI tools": "Cấu hình công cụ CLI",
+  "API endpoint configuration": "Cấu hình điểm cuối API",
+  "Manage your preferences": "Quản lý tùy chọn của bạn",
+  "Debug translation flow between formats": "Gỡ lỗi luồng dịch giữa các định dạng",
+  "Live server console output": "Đầu ra console máy chủ trực tiếp",
+  "Create model combos with fallback support": "Tạo kết hợp mô hình với hỗ trợ dự phòng",
+  "Local Mode": "Chế độ cục bộ",
+  "Running on your machine": "Chạy trên máy của bạn",
+  "Database Location": "Vị trí cơ sở dữ liệu",
+  "Download Backup": "Tải xuống bản sao lưu",
+  "Import Backup": "Nhập bản sao lưu",
+  "Database backup downloaded": "Đã tải xuống bản sao lưu cơ sở dữ liệu",
+  "Database imported successfully": "Đã nhập cơ sở dữ liệu thành công",
+  "Security": "Bảo mật",
+  "Require login": "Yêu cầu đăng nhập",
+  "When ON, dashboard requires password. When OFF, access without login.": "Khi BẬT, bảng điều khiển yêu cầu mật khẩu. Khi TẮT, truy cập không cần đăng nhập.",
+  "Current Password": "Mật khẩu hiện tại",
+  "Enter current password": "Nhập mật khẩu hiện tại",
+  "New Password": "Mật khẩu mới",
+  "Enter new password": "Nhập mật khẩu mới",
+  "Confirm New Password": "Xác nhận mật khẩu mới",
+  "Confirm new password": "Xác nhận mật khẩu mới",
+  "Update Password": "Cập nhật mật khẩu",
+  "Set Password": "Đặt mật khẩu",
+  "Password updated successfully": "Đã cập nhật mật khẩu thành công",
+  "Passwords do not match": "Mật khẩu không khớp",
+  "Routing Strategy": "Chiến lược định tuyến",
+  "Round Robin": "Vòng tròn",
+  "Cycle through accounts to distribute load": "Luân phiên qua các tài khoản để phân phối tải",
+  "Sticky Limit": "Giới hạn dính",
+  "Calls per account before switching": "Số lần gọi mỗi tài khoản trước khi chuyển",
+  "Network": "Mạng",
+  "Outbound Proxy": "Proxy đi ra",
+  "Enable proxy for OAuth + provider outbound requests.": "Bật proxy cho OAuth + yêu cầu đi ra của nhà cung cấp.",
+  "Proxy URL": "URL Proxy",
+  "Leave empty to inherit existing env proxy (if any).": "Để trống để kế thừa proxy môi trường hiện có (nếu có).",
+  "No Proxy": "Không có Proxy",
+  "Comma-separated hostnames/domains to bypass the proxy.": "Tên máy chủ/tên miền được phân tách bằng dấu phẩy để bỏ qua proxy.",
+  "Test proxy URL": "Kiểm tra URL proxy",
+  "Proxy settings applied": "Đã áp dụng cài đặt proxy",
+  "Proxy enabled": "Đã bật proxy",
+  "Proxy disabled": "Đã tắt proxy",
+  "Proxy test OK": "Kiểm tra proxy OK",
+  "Proxy test failed": "Kiểm tra proxy thất bại",
+  "Please enter a Proxy URL to test": "Vui lòng nhập URL Proxy để kiểm tra",
+  "Observability": "Khả năng quan sát",
+  "Enable Observability": "Bật khả năng quan sát",
+  "Turn request detail recording on/off globally": "Bật/tắt ghi chi tiết yêu cầu toàn cục",
+  "Max Records": "Số bản ghi tối đa",
+  "Maximum request detail records to keep (older records are auto-deleted)": "Số bản ghi chi tiết yêu cầu tối đa để giữ (bản ghi cũ hơn sẽ tự động xóa)",
+  "Batch Size": "Kích thước lô",
+  "Number of items to accumulate before writing to database (higher = better performance)": "Số mục tích lũy trước khi ghi vào cơ sở dữ liệu (cao hơn = hiệu suất tốt hơn)",
+  "Flush Interval (ms)": "Khoảng thời gian xả (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "Thời gian tối đa để chờ trước khi xả bộ đệm (ngăn mất dữ liệu trong lưu lượng thấp)",
+  "Max JSON Size (KB)": "Kích thước JSON tối đa (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "Kích thước tối đa cho mỗi trường JSON (yêu cầu/phản hồi) trước khi cắt bớt",
+  "All data stored on your machine": "Tất cả dữ liệu được lưu trữ trên máy của bạn",
+  "MITM Server": "Máy chủ MITM",
+  "Running": "Đang chạy",
+  "Stopped": "Đã dừng",
+  "Cert": "Chứng chỉ",
+  "Server": "Máy chủ",
+  "Purpose:": "Mục đích:",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "Sử dụng Antigravity IDE & GitHub Copilot → với BẤT KỲ nhà cung cấp/mô hình nào từ 9Router",
+  "How it works:": "Cách hoạt động:",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Yêu cầu Antigravity/Copilot IDE → Chuyển hướng DNS đến localhost:443 → MITM proxy chặn → 9Router → phản hồi đến Antigravity/Copilot",
+  "No API keys — create one in Keys page": "Không có khóa API — tạo một khóa trong trang Keys",
+  "sk_9router (default)": "sk_9router (mặc định)",
+  "Server started": "Đã khởi động máy chủ",
+  "Failed to start server": "Không thể khởi động máy chủ",
+  "Server stopped — all DNS cleared": "Đã dừng máy chủ — đã xóa tất cả DNS",
+  "Failed to stop server": "Không thể dừng máy chủ",
+  "Sudo password is required": "Yêu cầu mật khẩu sudo",
+  "Stop Server": "Dừng máy chủ",
+  "Start Server": "Khởi động máy chủ",
+  "Enable DNS per tool below to activate interception": "Bật DNS cho từng công cụ bên dưới để kích hoạt chặn",
+  "Sudo Password Required": "Yêu cầu mật khẩu Sudo",
+  "Enter your sudo password to start/stop MITM server": "Nhập mật khẩu sudo của bạn để khởi động/dừng máy chủ MITM",
+  "Sudo Password": "Mật khẩu Sudo",
+  "Click to add, click again to remove. Changes are saved automatically.": "Nhấp để thêm, nhấp lại để xóa. Thay đổi được lưu tự động.",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ Cảnh báo rủi ro: Provider này sử dụng subscription/OAuth không được cấp phép chính thức cho mục đích proxy/router. Tài khoản có thể bị hạn chế hoặc cấm. Người dùng tự chịu trách nhiệm.",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM chặn lưu lượng HTTPS của các IDE tools (Antigravity, GitHub Copilot, Kiro) qua CA cục bộ để chuyển hướng request đến providers của bạn. Có thể vi phạm ToS → rủi ro bị ban tài khoản. Sử dụng với rủi ro của bạn.",
+  "Endpoint is exposed without an API key.": "Endpoint đang mở mà không có API key."
+}
diff --git a/public/i18n/literals/zh-CN.json b/public/i18n/literals/zh-CN.json
new file mode 100644
index 0000000..8459ae2
--- /dev/null
+++ b/public/i18n/literals/zh-CN.json
@@ -0,0 +1,1391 @@
+{
+  "($/1M tokens). Example: An input rate of 2.50 means $2.50 per 1,000,000 input tokens.": "（$/100 万 Token）。示例：输入费率 2.50 表示每 1,000,000 个输入 Token 需 2.50 美元。",
+  "($/1M tokens). Example: Input rate of 2.50 means $2.50 per 1,000,000 input tokens.": "（$/100 万 Token）。示例：输入费率 2.50 表示每 1,000,000 个输入 Token 需 2.50 美元。",
+  "(Caveman)": "（Caveman）",
+  "(Headroom)": "（Headroom）",
+  "(Ponytail)": "（Ponytail）",
+  "(RTK)": "（RTK）",
+  "(via inference test)": "（通过推理测试）",
+  "+ Browse": "+ 浏览",
+  "+ Combo": "+ 组合",
+  "+ Custom": "+ 自定义",
+  "+ Save current as...": "+ 另存为...",
+  "-compatible models manually or import them from the /models endpoint.": "- 手动兼容模型或从 /models 端点导入它们。",
+  ". Click \"Apply\" to auto-configure.": "。单击“应用”进行自动配置。",
+  "1. CLI & SDKs": "1. CLI 和 SDK",
+  "1. Client Request (Input)": "1. 客户端请求（输入）",
+  "1. Generates SSL cert & adds to system keychain": "1. 生成 SSL 证书并添加到系统钥匙串",
+  "2. 9Router Hub": "2. 9Router 枢纽",
+  "2. Provider Request (Translated)": "2. 提供商请求（已​​翻译）",
+  "2. Redirects": "2. 重定向",
+  "24h": "24小时",
+  "3. AI Providers": "3. AI 提供商",
+  "3. Maps Antigravity models to any provider via 9Router": "3. 通过 9Router 将Antigravity模型映射到任何提供商",
+  "3. Provider Response (Raw)": "3. 提供商响应（原始）",
+  "30D": "30 天",
+  "4. Client Response (Final)": "4. 客户端响应（最终）",
+  "60D": "60 天",
+  "7D": "7 天",
+  "9Router (Entry)": "9Router（入口）",
+  "9Router Base URL": "9Router 基础 URL",
+  ": Account | Workers Scripts | Edit": "：账号 | Workers 脚本 | 编辑",
+  ": Include | Account |": "：包含 | 账号 |",
+  "AI endpoint proxy with web dashboard - A JavaScript port of CLIProxyAPI. Works seamlessly with Claude Code, OpenAI Codex, Cline, RooCode, and other CLI tools.": "AI 端点代理，附带 Web 仪表盘 — CLIProxyAPI 的 JavaScript 移植版。与 Claude Code、OpenAI Codex、Cline、RooCode 和其他 CLI 工具无缝协作。",
+  "API Endpoint": "API端点",
+  "API Key": "API密钥",
+  "API Key (for Check)": "API 密钥（用于检查）",
+  "API Key Compatible Providers": "API 密钥兼容提供商",
+  "API Key Created": "API 密钥已创建",
+  "API Key Name": "API 密钥名称",
+  "API Key Providers": "API 密钥提供商",
+  "API Keys": "API 密钥",
+  "API Reference": "API参考",
+  "API Token": "API 令牌",
+  "API Tokens": "API 令牌",
+  "API Type": "API类型",
+  "API Version": "API 版本",
+  "API endpoint configuration": "API 端点配置",
+  "AWS Builder ID": "AWS 构建器 ID",
+  "AWS IAM Identity Center": "AWS IAM 身份中心",
+  "AWS Region": "AWS 区域",
+  "AWS region for the key (default: us-east-1)": "密钥的 AWS 区域（默认：us-east-1）",
+  "AWS region for your Identity Center (default: us-east-1)": "您的身份中心的 AWS 区域（默认值：us-east-1）",
+  "About": "关于",
+  "Access Anywhere": "随处访问",
+  "Access Token": "访问令牌",
+  "Access token will be auto-filled...": "访问令牌将自动填充...",
+  "Access your terminal, desktop & files from anywhere": "从任何地方访问您的终端、桌面和文件",
+  "Account": "账号",
+  "Account ID": "账号 ID",
+  "Account Resources": "账号资源",
+  "Accounts per page": "每页账号数",
+  "Action": "操作",
+  "Activate": "激活",
+  "Active": "活跃",
+  "Active All": "全部激活",
+  "Active:": "活跃：",
+  "Add": "添加",
+  "Add API Key": "添加 API 密钥",
+  "Add Anthropic Compatible": "添加Anthropic兼容",
+  "Add Connection": "添加连接",
+  "Add Custom Embedding": "添加自定义嵌入",
+  "Add Custom MCP": "添加自定义 MCP",
+  "Add Custom Model": "添加自定义模型",
+  "Add Model": "添加模型",
+  "Add Model Config": "添加模型配置",
+  "Add Model for GitHub Copilot": "为 GitHub Copilot 添加模型",
+  "Add Model for OpenCode": "为 OpenCode 添加模型",
+  "Add Model to Combo": "将模型添加到组合",
+  "Add New Provider": "添加新提供商",
+  "Add OpenAI Compatible": "添加 OpenAI 兼容",
+  "Add Provider": "添加提供商",
+  "Add Proxy Pool": "添加代理池",
+  "Add Shorthands": "添加简写",
+  "Add a connection to enable importing models.": "添加连接以启用导入模型。",
+  "Add connection using browser cookie": "使用浏览器 cookie 添加连接",
+  "Add model": "添加模型",
+  "Add server": "添加服务器",
+  "Add the following configuration to your models array:": "将以下配置添加到您的 models 数组中：",
+  "Add your first connection to get started": "添加您的第一个连接以开始使用",
+  "Administrator required": "需要管理员权限",
+  "Administrator required — restart 9Router as Administrator to use MITM": "需要管理员权限 — 以管理员身份重新启动 9Router 以使用 MITM",
+  "After authorization, copy the full URL from your browser address bar.": "授权后，从浏览器地址栏中复制完整的 URL。",
+  "After authorization, copy the full URL from your browser.": "授权后，从浏览器复制完整的 URL。",
+  "After installation, run": "安装后，运行",
+  "After login, you'll need to copy the callback URL from your browser and paste it back here.": "登录后，您需要从浏览器复制回调 URL 并将其粘贴回此处。",
+  "Alibaba Qwen Code CLI — supports OpenAI, Anthropic & Gemini providers via 9Router": "阿里巴巴 Qwen Code CLI — 通过 9Router 支持 OpenAI、Anthropic 和 Gemini 提供商",
+  "All": "全部",
+  "All AI Providers": "所有 AI 提供商",
+  "All Providers": "所有提供商",
+  "All models are responding normally.": "所有模型均响应正常。",
+  "All providers": "所有提供商",
+  "All rates are in": "所有费率均在",
+  "All selected currently unbound": "所有选中项当前未绑定",
+  "Allow dashboard access via tunnel": "允许通过隧道访问仪表盘",
+  "Allow either password or OIDC.": "允许密码或 OIDC 登录。",
+  "An error occurred": "发生错误",
+  "An error occurred. Please try again.": "发生错误，请重试。",
+  "Anthropic Claude Code CLI": "Anthropic Claude Code CLI",
+  "Anthropic Compatible (Prod)": "Anthropic 兼容（生产）",
+  "Anthropic Compatible Details": "Anthropic 兼容详情",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE 请求 → DNS 重定向到 localhost:443 → MITM 代理拦截 → 9Router → 响应返回 Antigravity/Copilot",
+  "Any model available in 9Router can be used — not just Qwen models. Select from Qwen, Claude, Gemini, GPT, and more.": "9Router 中可用的任何模型都可以使用——不仅仅是 Qwen 模型。从 Qwen、Claude、Gemini、GPT 等中选择。",
+  "App Name": "应用名称",
+  "Apply": "应用",
+  "Apply Proxy": "应用代理",
+  "Applying...": "应用中...",
+  "Are you sure you want to close the proxy server?": "您确定要关闭代理服务器吗？",
+  "Are you sure you want to disable the tunnel?": "您确定要禁用隧道吗？",
+  "Attempting to reconnect...": "正在尝试重新连接...",
+  "Audio File": "音频文件",
+  "Auth Mode": "认证模式",
+  "Authenticate": "认证",
+  "Authentication Method": "认证方式",
+  "Authentication Successful": "认证成功",
+  "Authentication Successful!": "认证成功！",
+  "Authless": "无需认证",
+  "Authorization Successful!": "授权成功！",
+  "Authorize": "授权",
+  "Auto (by priority)": "自动（按优先级）",
+  "Auto Refresh (3s)": "自动刷新（3秒）",
+  "Auto-detect": "自动检测",
+  "Auto-detecting token...": "自动检测令牌...",
+  "Auto-detecting tokens...": "自动检测令牌...",
+  "Auto-ping": "自动 Ping",
+  "Auto-refresh": "自动刷新",
+  "Auto:": "自动：",
+  "Automatically switch between providers when limits are hit.": "当达到限额时自动切换提供商。",
+  "Available": "可用",
+  "Available Models": "可用模型",
+  "Azure Endpoint": "Azure 端点",
+  "Azure OpenAI Configuration": "Azure OpenAI 配置",
+  "BXAuth=xxx; ...": "BXAuth=xxx；...",
+  "Back": "返回",
+  "Back to CLI Tools": "返回 CLI 工具",
+  "Back to Providers": "返回提供商",
+  "Base URL": "基础 URL",
+  "Batch Import": "批量导入",
+  "Batch Import Proxies": "批量导入代理",
+  "Batch Size": "批量大小",
+  "Beautiful web dashboard for managing providers and monitoring usage.": "精美的 Web 仪表盘，用于管理提供商和监控使用情况。",
+  "Best quality, but costs the most": "质量最佳但成本最高",
+  "Bias the model toward minimal code: YAGNI, reuse stdlib, deletion over addition": "引导模型编写最少代码：YAGNI、重用标准库、删除多于添加",
+  "Binary File": "二进制文件",
+  "Blog": "博客",
+  "Both": "两者",
+  "Browse & edit files": "浏览和编辑文件",
+  "Browse MCP Marketplace": "浏览 MCP 市场",
+  "Browse source, README, and examples.": "浏览源代码、README 和示例。",
+  "Browser Control (Browser MCP)": "浏览器控制（Browser MCP）",
+  "Bulk Add": "批量添加",
+  "CLI Support": "CLI 支持",
+  "CLI Tools": "命令行工具",
+  "CLI on the host →": "主机上的 CLI →",
+  "CLIProxyAPI Auth JSON": "CLIProxyAPI 认证 JSON",
+  "Cache Creation": "缓存创建",
+  "Cache Creation:": "缓存创建：",
+  "Cached": "缓存",
+  "Cached Tokens": "缓存 Token",
+  "Cached Tokens:": "缓存 Token：",
+  "Cached input tokens (typically 50% of input rate)": "缓存输入 Token（通常为输入费率的 50%）",
+  "Cached:": "缓存：",
+  "Calls per account before switching": "切换前每个账号的调用次数",
+  "Calls per combo model before switching": "切换前每个组合模型的调用次数",
+  "Cancel": "取消",
+  "Capacity auto-switch": "容量自动切换",
+  "Cert": "证书",
+  "Change Log": "更新日志",
+  "Changelog": "变更日志",
+  "Chat": "对话",
+  "Chat / code-gen via OpenAI or Anthropic format with streaming.": "通过 OpenAI 或 Anthropic 格式进行聊天/代码生成，支持流式传输。",
+  "Chat Completions": "聊天完成",
+  "Check": "检查",
+  "Checking Claude CLI...": "检查 Claude CLI...",
+  "Checking Claude Cowork...": "正在检查 Claude Cowork...",
+  "Checking Cline...": "正在检查 Cline...",
+  "Checking Codex CLI...": "正在检查 Codex CLI...",
+  "Checking Copilot config...": "正在检查Copilot配置...",
+  "Checking DeepSeek TUI...": "正在检查 DeepSeek TUI...",
+  "Checking Factory Droid CLI...": "检查 Factory Droid CLI...",
+  "Checking Hermes Agent...": "正在检查 Hermes Agent...",
+  "Checking Kilo Code...": "正在检查 Kilo Code...",
+  "Checking Open Claw CLI...": "正在检查 Open Claw CLI...",
+  "Checking OpenCode CLI...": "检查 OpenCode CLI...",
+  "Checking jcode CLI...": "正在检查 jcode CLI...",
+  "Checking...": "检查中...",
+  "Choose API Provider → Ollama": "选择 API 提供商 → Ollama",
+  "Choose how to authenticate with GitLab Duo:": "选择如何通过 GitLab Duo 认证：",
+  "Choose your authentication method:": "选择您的身份验证方法：",
+  "Claude": "Claude",
+  "Claude CLI - Manual Configuration": "Claude CLI - 手动配置",
+  "Claude CLI not detected locally": "未在本地检测到 Claude CLI",
+  "Claude CLI not installed": "Claude CLI 未安装",
+  "Claude Cowork - Manual Configuration": "Claude Cowork - 手动配置",
+  "Claude Desktop (Cowork mode) not detected": "未检测到 Claude Desktop（Cowork 模式）",
+  "Claude Desktop Cowork (third-party inference)": "Claude Desktop Cowork（第三方推理）",
+  "Clear": "清除",
+  "Clear (will use main model)": "清除（将使用主模型）",
+  "Clear Filters": "清除过滤器",
+  "Clear search": "清除搜索",
+  "Click": "点击",
+  "Click \"View All Model\" → \"Add Custom Model\"": "点击「查看所有模型」→「添加自定义模型」",
+  "Click a model to set/clear active": "点击模型以设置/取消活跃状态",
+  "Click to add, click again to remove. Changes are saved automatically.": "点击添加，再次点击删除。更改将自动保存。",
+  "Click to edit": "点击编辑",
+  "Click to retry": "点击重试",
+  "Client ID": "客户端 ID",
+  "Client Request": "客户端请求",
+  "Client Response": "客户端响应",
+  "Client Secret": "客户端密钥",
+  "Cline - Manual Configuration": "Cline - 手动配置",
+  "Cline AI Coding Assistant": "Cline AI 编程助手",
+  "Cline not detected locally": "未在本地检测到 Cline",
+  "Close": "关闭",
+  "Close Proxy": "关闭代理",
+  "Close provider filter": "关闭提供商筛选",
+  "Close reset credit expiry modal": "关闭重置信用有效期弹窗",
+  "Close test results": "关闭测试结果",
+  "Closing in": "即将关闭",
+  "Cloud Sync": "云端同步",
+  "Cloudflare Relay": "Cloudflare Relay",
+  "Cloudflare Tunnel": "Cloudflare 隧道",
+  "Cloudflare Workers AI": "Cloudflare Workers AI",
+  "Codex CLI - Manual Configuration": "Codex CLI - 手动配置",
+  "Codex CLI not detected locally": "未在本地检测到 Codex CLI",
+  "Codex CLI not installed": "Codex CLI 未安装",
+  "Codex Reset Credit Expiry": "Codex 重置信用有效期",
+  "Codex uses": "Codex 使用",
+  "Combo Name": "组合名称",
+  "Combo Round Robin": "组合轮询",
+  "Combo Sticky Limit": "组合粘性限制",
+  "Combos": "组合",
+  "Coming soon...": "即将推出...",
+  "Comma-separated hostnames/domains to bypass the proxy.": "以逗号分隔的主机名/域以绕过代理。",
+  "Comma-separated hosts/domains to bypass proxy": "以逗号分隔的主机名/域以绕过代理",
+  "Company": "公司",
+  "Complete the authorization in the popup window.": "在弹出的窗口中完成授权。",
+  "Completion/response tokens": "补全/响应 Token",
+  "Compress LLM output": "压缩 LLM 输出",
+  "Compress context": "压缩上下文",
+  "Compress prompts via /v1/compress before routing to the model": "在路由到模型之前通过 /v1/compress 压缩提示",
+  "Compress tool output": "压缩工具输出",
+  "Compress tool output to reduce token usage.": "压缩工具输出以减少 Token 使用量。",
+  "Config path: Linux/macOS ~/.deepseek/config.toml • Windows %USERPROFILE%\\.deepseek\\config.toml": "配置路径：Linux/macOS ~/.deepseek/config.toml • Windows %USERPROFILE%\\.deepseek\\config.toml",
+  "Config path: Linux/macOS ~/.qwen/settings.json • Windows %USERPROFILE%\\.qwen\\settings.json": "配置路径：Linux/macOS ~/.qwen/settings.json • Windows %USERPROFILE%\\.qwen\\settings.json",
+  "Configuration": "配置",
+  "Configure 9router as an OpenAI-compatible provider to route all jcode requests through 9router's optimization layer.": "将 9router 配置为 OpenAI 兼容提供商，以通过 9router 的优化层路由所有 jcode 请求。",
+  "Configure CLI tools": "配置 CLI 工具",
+  "Configure a new AI provider to use with your applications.": "配置新的 AI 提供程序以与您的应用程序一起使用。",
+  "Configure pricing rates for cost tracking and calculations": "配置定价以进行成本跟踪和计算",
+  "Configure providers and API keys via web interface": "通过 Web 界面配置提供商和 API 密钥",
+  "Configured": "已配置",
+  "Confirm": "确认",
+  "Confirm New Password": "确认新密码",
+  "Confirm Password": "确认密码",
+  "Confirm new password": "确认新密码",
+  "Connect": "连接",
+  "Connect AI tools remotely": "远程连接AI工具",
+  "Connect Cursor IDE": "连接CursorIDE",
+  "Connect GitLab Duo": "连接 GitLab Duo",
+  "Connect Kiro": "连接Kiro",
+  "Connect to providers with OAuth to track your API quota limits and usage.": "使用 OAuth 连接到提供商以跟踪您的 API 配额限制和使用情况。",
+  "Connect via OAuth or API keys. Securely manage credentials.": "通过 OAuth 或 API 密钥连接。安全管理凭据。",
+  "Connect with OAuth2": "使用 OAuth2 连接",
+  "Connect your account using OAuth2 authentication.": "使用 OAuth2 身份验证连接您的账号。",
+  "Connected": "已连接",
+  "Connected Successfully!": "连接成功！",
+  "Connected providers only": "仅已连接的提供商",
+  "Connecting...": "连接中...",
+  "Connection": "连接",
+  "Connection Details": "连接详情",
+  "Connection Failed": "连接失败",
+  "Connections": "连接",
+  "Console Log": "控制台日志",
+  "Contact": "联系",
+  "Content": "内容",
+  "Continue": "继续",
+  "Continue AI Assistant": "Continue AI 助手",
+  "Continue to summary": "继续到摘要",
+  "Continue with GitHub": "继续使用 GitHub",
+  "Continue with Google": "使用 Google 继续",
+  "Cookie": "Cookie",
+  "Cookie Auth": "Cookie 验证",
+  "Cookie String": "Cookie 字符串",
+  "Cooldown": "冷却",
+  "Copied!": "已复制！",
+  "Copy": "复制",
+  "Copy & Shutdown": "复制并关闭",
+  "Copy This URL": "复制此 URL",
+  "Copy a link and paste to your AI to use 9Router — no install needed": "复制链接并粘贴到您的 AI 以使用 9Router — 无需安装",
+  "Copy combo name": "复制组合名称",
+  "Copy install command": "复制安装命令",
+  "Copy model": "复制模型",
+  "Copy the JSON below to your ~/.qwen/settings.json file.": "将以下 JSON 复制到您的 ~/.qwen/settings.json 文件中。",
+  "Copy the entire cookie string (must include BXAuth)": "复制整个 cookie 字符串（必须包括 BXAuth）",
+  "Cost": "成本",
+  "Cost Calculation:": "成本计算：",
+  "Costs": "成本",
+  "Costs are calculated based on token usage and pricing rates. Each request's cost is determined by: (input_tokens × input_rate) + (output_tokens × output_rate) + (cached_tokens × cached_rate)": "成本根据 Token 用量和费率计算。每个请求的成本由以下公式决定：(input_tokens × input_rate) + (output_tokens × output_rate) + (cached_tokens × cached_rate)",
+  "Could not read Cursor database automatically.": "无法自动读取 Cursor 数据库。",
+  "Create": "创建",
+  "Create API Key": "创建 API 密钥",
+  "Create Combo": "创建组合",
+  "Create Cowork Combo": "创建 Cowork 组合",
+  "Create Key": "创建密钥",
+  "Create Provider": "创建提供商",
+  "Create Token": "创建令牌",
+  "Create a": "创建一个",
+  "Create a proxy pool entry, then assign it to connections.": "创建代理池条目，然后分配到连接。",
+  "Create model combos with fallback support": "创建具有后备支持的模型组合",
+  "Create your first API key to get started": "创建您的第一个 API 密钥以开始使用",
+  "Created": "已创建",
+  "Creating...": "创建中...",
+  "Current": "当前",
+  "Current Password": "当前密码",
+  "Current Pricing Overview": "当前定价概述",
+  "Current password": "当前密码",
+  "Current: Keeps": "当前： 保留",
+  "Currently using accounts in priority order (Fill First).": "当前按优先级顺序使用账号（优先填满）。",
+  "Cursor AI Code Editor": "Cursor AI 代码编辑器",
+  "Cursor IDE not detected. Please paste your tokens manually.": "未检测到Cursor IDE。请手动粘贴您的令牌。",
+  "Cursor routes requests through its own server, so local endpoint is not supported. Please enable Tunnel or Cloud Endpoint in Settings.": "Cursor 通过自己的服务器路由请求，因此不支持本地端点。请在设置中启用隧道或云端点。",
+  "Custom": "自定义",
+  "Custom Pricing:": "定制定价：",
+  "Custom Providers (OpenAI/Anthropic Compatible)": "自定义提供商（OpenAI/Anthropic 兼容）",
+  "Custom Token": "自定义令牌",
+  "Custom accounts per page": "自定义每页账号数",
+  "Custom providers": "自定义提供商",
+  "Custom...": "自定义...",
+  "Cycle through accounts to distribute load": "循环切换账号以分配负载",
+  "Cycle through providers in combos instead of always starting with first": "在组合中循环使用提供商，而不是总是从第一个开始",
+  "DNS off": "DNS 关闭",
+  "Dashboard": "仪表盘",
+  "Dashboard Password": "仪表盘密码",
+  "Dashboard:": "仪表盘：",
+  "Data Location:": "数据位置：",
+  "Data flows seamlessly from your application through our intelligent routing layer to the best provider for the job.": "数据从您的应用程序通过我们的智能路由层无缝流向最适合任务的提供商。",
+  "Data flows seamlessly through our intelligent routing system": "数据通过我们的智能路由系统无缝流转",
+  "Database Location": "数据库位置",
+  "Database backup downloaded": "数据库备份已下载",
+  "Database imported successfully": "数据库导入成功",
+  "DateTime": "日期时间",
+  "Deactivate": "停用",
+  "Debug": "调试",
+  "Debug translation flow between formats": "调试格式之间的翻译流程",
+  "DeepSeek TUI - Manual Configuration": "DeepSeek TUI - 手动配置",
+  "DeepSeek TUI not detected locally": "未在本地检测到 DeepSeek TUI",
+  "DeepSeek TUI uses ~/.deepseek/config.toml for configuration. 9Router will update the provider to 'openai' mode with your base_url, api_key, and model.": "DeepSeek TUI 使用 ~/.deepseek/config.toml 进行配置。9Router 将提供商更新为 'openai' 模式，包含您的 base_url、api_key 和 model。",
+  "DeepSeek Terminal Coding Agent (Rust TUI)": "DeepSeek 终端编程代理（Rust TUI）",
+  "Default Model": "默认模型",
+  "Default password is": "默认密码为",
+  "Default password is 123456": "默认密码为 123456",
+  "Delete": "删除",
+  "Delete API Key": "删除 API 密钥",
+  "Delete connection": "删除连接",
+  "Delete saved endpoint": "删除已保存的端点",
+  "Delete selected preset": "删除选中的预设",
+  "Delete this combo?": "删除此组合？",
+  "Delete this connection?": "删除此连接？",
+  "Deno Deploy API Token": "Deno Deploy API 令牌",
+  "Deno Deploy v2 runs on a high-performance global edge network": "Deno Deploy v2 运行在高性能全球边缘网络上",
+  "Deno Relay": "Deno Relay",
+  "Deploy": "部署",
+  "Deploy Cloudflare Relay": "部署 Cloudflare Relay",
+  "Deploy Deno Relay": "部署 Deno Relay",
+  "Deploy Relay": "部署中继",
+  "Deploy Vercel Relay": "部署 Vercel Relay",
+  "Deploy multiple relays for maximum IP diversity": "部署多个中继以获得最大 IP 多样性",
+  "Deploy multiple relays on different accounts for more IP diversity": "在不同账号上部署多个中继以获得更多 IP 多样性",
+  "Deploying... (may take ~1 min)": "部署中...（可能需要约 1 分钟）",
+  "Deployment Name": "部署名称",
+  "Deploys a Cloudflare Worker as a proxy relay. All AI provider requests will be forwarded through Cloudflare's global edge network.": "将 Cloudflare Worker 部署为代理中继。所有 AI 提供商请求将通过 Cloudflare 的全球边缘网络转发。",
+  "Deploys a relay worker to Deno Deploy's global edge network. All AI provider requests are forwarded through Deno's edge, masking your real IP.": "将中继 Worker 部署到 Deno Deploy 的全球边缘网络。所有 AI 提供商请求通过 Deno 的边缘转发，隐藏您的真实 IP。",
+  "Deploys an edge relay function to Vercel that proxies requests through Vercel's network.": "将边缘中继函数部署到 Vercel，通过 Vercel 的网络代理请求。",
+  "Deploys an edge relay function to Vercel. All AI provider requests will be forwarded through Vercel's edge network, masking your real IP from providers.": "将边缘中继函数部署到 Vercel。所有 AI 提供商请求将通过 Vercel 的边缘网络转发，隐藏您的真实 IP。",
+  "Desktop": "桌面",
+  "Detail": "详情",
+  "Details": "详情",
+  "Dimensions": "维度",
+  "Disable": "禁用",
+  "Disable All": "全部禁用",
+  "Disable Tailscale": "禁用 Tailscale",
+  "Disable Tunnel": "禁用隧道",
+  "Disable connections with depleted quota on the current page": "禁用当前页面上配额已耗尽的连接",
+  "Disable provider": "禁用提供商",
+  "Disable this model": "禁用此模型",
+  "Disabled": "已禁用",
+  "Disabling...": "关闭中...",
+  "Disconnected from server": "与服务器断开连接",
+  "Dismiss notification": "关闭通知",
+  "Display Name": "显示名称",
+  "Display language": "显示语言",
+  "Docs": "文档",
+  "Documentation": "文档",
+  "Domain:": "域名：",
+  "Donate": "捐赠",
+  "Done": "完成",
+  "Download": "下载",
+  "Download Backup": "下载备份",
+  "Drag to reorder": "拖拽以排序",
+  "Easy Setup": "简单设置",
+  "Edit": "编辑",
+  "Edit Combo": "编辑组合",
+  "Edit Connection": "编辑连接",
+  "Edit Pricing": "编辑定价",
+  "Edit Proxy Pool": "编辑代理池",
+  "Edit connection": "编辑连接",
+  "Edit hosts file manually to add the following entries:": "手动编辑 hosts 文件以添加以下条目：",
+  "Email": "邮箱",
+  "Embedding": "嵌入",
+  "Embeddings": "嵌入",
+  "Enable": "启用",
+  "Enable DNS per tool below to activate interception": "启用下面每个工具的 DNS 以激活拦截",
+  "Enable DNS to edit model mappings": "启用 DNS 以编辑模型映射",
+  "Enable Observability": "启用可观察性",
+  "Enable OpenAI API": "启用 OpenAI API",
+  "Enable Tunnel": "启用隧道",
+  "Enable connections that still have quota on the current page": "启用当前页面上仍有配额的连接",
+  "Enable provider": "启用提供商",
+  "Enable proxy for OAuth + provider outbound requests.": "为 OAuth + 提供商出站请求启用代理。",
+  "Encrypted": "已加密",
+  "End Date": "结束日期",
+  "End-to-end TLS via Cloudflare": "通过 Cloudflare 的端到端 TLS",
+  "Endpoint": "端点",
+  "Endpoint & Key": "端点与密钥",
+  "Endpoint is exposed without an API key.": "端点未设置 API 密钥即对外暴露。",
+  "Enter current password": "输入当前密码",
+  "Enter model id": "输入模型 ID",
+  "Enter model id (provider-specific)": "输入模型 ID（提供商特定）",
+  "Enter new API key": "输入新的 API 密钥",
+  "Enter new password": "输入新密码",
+  "Enter or pick API key": "输入或选择 API 密钥",
+  "Enter password": "输入密码",
+  "Enter sudo password": "输入sudo密码",
+  "Enter the model ID exactly as your compatible endpoint expects it. This model will be saved as the connection default.": "输入您的兼容端点所需的模型 ID。此模型将保存为连接的默认模型。",
+  "Enter your API key": "输入您的 API 密钥",
+  "Enter your current password to": "输入当前密码以",
+  "Enter your password to access the dashboard": "输入密码以访问仪表盘",
+  "Error": "错误",
+  "Est. Cost": "预估成本",
+  "Estimated, not actual billing": "预估费用，非实际账单",
+  "Everything you need to manage your AI infrastructure efficiently.": "高效管理 AI 基础设施所需的一切。",
+  "Everything you need to manage your AI infrastructure in one place, built for scale.": "为规模化而构建，在一个地方管理 AI 基础设施所需的一切。",
+  "Example": "示例",
+  "Experimental": "实验性",
+  "Expires At": "过期时间",
+  "Expiring first": "即将过期优先",
+  "Expiring-first currently reorders accounts inside the current page. Cross-page ordering still follows backend pagination.": "「即将过期优先」当前会在当前页面内重新排序账号。跨页面排序仍遵循后端分页。",
+  "Expose your local 9Router to the internet. No port forwarding, no static IP needed. Share endpoint URL with your team or use it in Cursor, Cline, and other AI tools from anywhere.": "将您本地的 9Router 暴露到互联网。无需端口转发，无需静态 IP。与您的团队共享端点 URL 或从任何地方在 Cursor、Cline 和其他 AI 工具中使用它。",
+  "Factory Droid - Manual Configuration": "Factory Droid - 手动配置",
+  "Factory Droid AI Assistant": "Factory Droid AI 助手",
+  "Factory Droid CLI not detected locally": "未在本地检测到 Factory Droid CLI",
+  "Factory Droid CLI not installed": "Factory Droid CLI 未安装",
+  "Fail request if proxy is unreachable instead of falling back to direct.": "当代理不可达时直接失败，而不是回退到直连。",
+  "Failed to apply settings": "应用设置失败",
+  "Failed to create combo": "创建组合失败",
+  "Failed to load changelog:": "加载更新日志失败：",
+  "Failed to load usage statistics.": "无法加载使用情况统计信息。",
+  "Failed to reset settings": "重置设置失败",
+  "Failed to set alias": "设置别名失败",
+  "Failed to update combo": "更新组合失败",
+  "Failed to update password": "更新密码失败",
+  "Failed to update proxy settings": "更新代理设置失败",
+  "Fallback": "回退",
+  "Fallback — tries models in order (next on failure)": "回退 — 按顺序尝试模型（失败时切换到下一个）",
+  "Fallback — try in order": "回退 — 按顺序尝试",
+  "Features": "功能特性",
+  "Fetch Qoder Models": "获取 Qoder 模型",
+  "Fetching...": "获取中...",
+  "Files": "文件",
+  "Filter accounts by status": "按状态筛选账号",
+  "Filter naming": "过滤命名",
+  "Filter naming requests": "过滤命名请求",
+  "Filter quota providers": "筛选配额提供商",
+  "Find MCPs →": "查找 MCP →",
+  "Find your Account ID in the right sidebar of": "在右侧边栏中找到您的账号 ID",
+  "Find your Account ID in the right sidebar of dash.cloudflare.com": "在 dash.cloudflare.com 的右侧边栏中找到您的账号 ID",
+  "First Page": "首页",
+  "Flush Interval (ms)": "刷新间隔（毫秒）",
+  "For enterprise users with custom AWS IAM Identity Center.": "适用于具有自定义 AWS IAM Identity Center 的企业用户。",
+  "Forgot password? Open": "忘记密码？打开",
+  "Format": "格式化",
+  "Found on the right side of the Cloudflare dashboard overview page.": "位于 Cloudflare 仪表盘概览页面的右侧。",
+  "Free": "免费",
+  "Free & Free Tier Providers": "免费及免费额度提供商",
+  "Free Providers": "免费提供商",
+  "Free Tier": "免费额度",
+  "Free Tier Providers": "免费额度提供商",
+  "Free tier: 100,000 requests per day": "免费套餐：每天 10 万次请求",
+  "Free tier: 100GB bandwidth/month, 500K edge invocations": "免费套餐：100GB 带宽/月，50 万次边缘调用",
+  "Free tier: 1M requests & 100GiB outbound traffic per month": "免费套餐：每月 100 万次请求和 100GiB 出站流量",
+  "Fresh API key obtained": "获得新的 API 密钥",
+  "Full shell access": "完整 Shell 访问",
+  "Fusion": "融合",
+  "Fusion — panel + judge": "融合 — 面板 + 裁判",
+  "Fusion — queries all models in parallel, then a judge synthesizes one answer": "融合 — 并行查询所有模型，然后由裁判综合出一个答案",
+  "Get 9Remote": "获取 9Remote",
+  "Get API Key": "获取 API 密钥",
+  "Get API Key →": "获取 API 密钥 →",
+  "Get Started": "开始使用",
+  "Get Started in 30 Seconds": "30 秒快速上手",
+  "Get started": "开始使用",
+  "Get started in seconds. Just install, open, and route.": "几秒钟即可上手。安装、打开、路由。",
+  "Get token →": "获取令牌 →",
+  "GitHub": "GitHub",
+  "GitHub Account": "GitHub 账号",
+  "GitHub Copilot - Manual Configuration": "GitHub Copilot - 手动配置",
+  "GitHub Copilot IDE with MITM": "GitHub Copilot IDE 与 MITM",
+  "GitLab Access Tokens": "GitLab 访问令牌",
+  "GitLab Applications": "GitLab 应用",
+  "GitLab Base URL": "GitLab 基础 URL",
+  "Go to": "前往",
+  "Go to Roo Settings panel": "前往 Roo 设置面板",
+  "Google Account": "Google 账号",
+  "Google Antigravity IDE with MITM": "Google Antigravity IDE 与 MITM",
+  "Granted At": "授予时间",
+  "Group models under one name, then pick a strategy per combo:": "将模型归组到一个名称下，然后为每个组合选择策略：",
+  "Headroom proxy is reachable. You can enable the token saver.": "Headroom 代理可达。您可以启用 Token 节省器。",
+  "Help Center": "帮助中心",
+  "Hermes Agent - Manual Configuration": "Hermes Agent - 手动配置",
+  "Hermes Agent not detected locally": "未在本地检测到 Hermes Agent",
+  "Hide": "隐藏",
+  "Hide key": "隐藏密钥",
+  "High performance global routing and IP masking via Cloudflare Workers": "通过 Cloudflare Workers 实现高性能全局路由和 IP 隐藏",
+  "High-performance Rust-based coding agent harness": "基于 Rust 的高性能编程代理框架",
+  "History": "历史记录",
+  "How 9Router Works": "9Router 工作原理",
+  "How Pricing Works": "定价如何运作",
+  "How it Works": "工作原理",
+  "How it works:": "工作原理：",
+  "How to Install": "如何安装",
+  "How to generate API token:": "如何生成 API 令牌：",
+  "How to generate your API Token:": "如何生成您的 API 令牌：",
+  "How to get cookie:": "如何获取cookie：",
+  "ID:": "ID：",
+  "IDC Start URL": "IDC 起始 URL",
+  "If provider lacks /models endpoint, enter a model ID to validate via chat/completions instead.": "如果提供商不支持 /models 端点，请输入模型 ID 通过 chat/completions 进行验证。",
+  "Image Generation": "图像生成",
+  "Image to Text": "图像转文本",
+  "Import": "导入",
+  "Import Backup": "导入备份",
+  "Import CLIProxyAPI JSON": "导入 CLIProxyAPI JSON",
+  "Import Token": "导入令牌",
+  "Importing...": "导入中...",
+  "In": "输入",
+  "In / Out": "输入/输出",
+  "Inactive": "未激活",
+  "Inactive pools are ignored by runtime resolution.": "未激活的代理池将被运行时解析忽略。",
+  "Inc. All rights reserved.": "公司。保留所有权利。",
+  "Initializing...": "初始化中...",
+  "Input": "输入",
+  "Input Cost": "输入成本",
+  "Input Tokens": "输入 Token",
+  "Input Tokens:": "输入 Token：",
+  "Input:": "输入：",
+  "Install 9Router": "安装 9Router",
+  "Install 9Router, configure your providers via web dashboard, and start routing AI requests.": "安装 9Router，通过 Web 仪表盘配置您的提供商，然后开始路由 AI 请求。",
+  "Install Chrome extension": "安装 Chrome 扩展",
+  "Install Cline VS Code extension or CLI from": "从以下位置安装 Cline VS Code 扩展或 CLI",
+  "Install Kilo Code from": "从以下位置安装 Kilo Code",
+  "Install Qwen Code": "安装 Qwen Code",
+  "Install Tailscale": "安装 Tailscale",
+  "Install command:": "安装命令：",
+  "Install jcode to enable automatic configuration:": "安装 jcode 以启用自动配置：",
+  "Install the Amp CLI using the package manager supported by your environment.": "使用您环境支持的包管理器安装 Amp CLI。",
+  "Install then click Start:": "安装后点击启动：",
+  "Install via npm:": "通过 npm 安装：",
+  "Installation Guide": "安装指南",
+  "Installing Tailscale...": "正在安装 Tailscale...",
+  "Interactive diagram visible on desktop": "桌面上可见的交互式图表",
+  "Intercept CLI tool traffic and route through 9Router": "拦截 CLI 工具流量并通过 9Router 路由",
+  "Intercepts Antigravity traffic via DNS redirect, letting you reroute models through 9Router.": "通过 DNS 重定向拦截Antigravity流量，让您可以通过 9Router 重新路由模型。",
+  "Intercepts Claude Code's topic-naming requests and returns a fake response locally, saving API tokens.": "拦截 Claude Code 的主题命名请求并在本地返回伪响应，节省 API Token。",
+  "Invalid": "无效",
+  "Invalid password": "密码错误",
+  "Issuer URL": "发行者 URL",
+  "JSON Response": "JSON 响应",
+  "Join developers who are streamlining their AI integrations with 9Router. Open source and free to start.": "加入正在使用 9Router 简化 AI 集成的开发者行列。开源且免费。",
+  "Judge": "裁判",
+  "Just now": "刚刚",
+  "KB per field": "每个字段的 KB",
+  "Keep the legacy password login.": "保留原有密码登录方式。",
+  "Key Name": "密钥名称",
+  "KiRo dashboard": "KiRo 仪表盘",
+  "Kill & Start": "终止并启动",
+  "Kill this process to start MITM Server?": "终止此进程以启动 MITM 服务器？",
+  "Kilo Code - Manual Configuration": "Kilo Code - 手动配置",
+  "Kilo Code AI Assistant": "Kilo Code AI 助手",
+  "Kilo Code not detected locally": "未在本地检测到 Kilo Code",
+  "Kimi": "Kimi",
+  "Kiro AI": "Kiro AI",
+  "Kiro IDE not detected. Please paste your refresh token manually.": "未检测到 Kiro IDE。请手动粘贴您的刷新令牌。",
+  "Kiro IDE with MITM": "Kiro IDE 与 MITM",
+  "Language": "语言",
+  "Languages": "语言",
+  "Last Page": "末页",
+  "Last Used": "最后使用",
+  "Last tested:": "上次测试：",
+  "Last updated:": "最后更新：",
+  "Latency": "延迟",
+  "Latency:": "延迟：",
+  "Lazy senior dev": "懒人高级开发者",
+  "Lean": "Lean",
+  "Leave blank to keep existing secret": "留空以保留现有密钥",
+  "Leave blank to use": "留空以使用",
+  "Leave empty for public PKCE app": "公开 PKCE 应用请留空",
+  "Leave empty to inherit existing env proxy (if any).": "留空以继承现有的 env 代理（如果有）。",
+  "Legacy manual proxy fields are still accepted by API for backward compatibility.": "API 仍接受旧版手动代理字段以实现向后兼容。",
+  "Legacy:": "旧版：",
+  "Legal": "法律",
+  "Live server console output": "服务器实时控制台输出",
+  "Load": "加载",
+  "Loading logs...": "正在加载日志...",
+  "Loading models from provider...": "正在从提供商处加载模型...",
+  "Loading pricing data...": "正在加载定价数据...",
+  "Loading registry...": "正在加载注册表...",
+  "Loading reset credits...": "正在加载重置信用...",
+  "Loading...": "加载中...",
+  "Local": "本地",
+  "Local Mode": "本地模式",
+  "Local Mode - All data stored on your machine": "本地模式 - 所有数据都存储在您的计算机上",
+  "Local Plugins": "本地插件",
+  "Locked. Retry in": "已锁定。请在",
+  "Login": "登录",
+  "Login Button Label": "登录按钮标签",
+  "Login URL": "登录 URL",
+  "Login to your account": "登录您的账号",
+  "Login with your GitHub account (manual callback).": "使用您的 GitHub 账号登录（手动回调）。",
+  "Login with your Google account (manual callback).": "使用您的 Google 账号登录（手动回调）。",
+  "Logout": "退出登录",
+  "Logs": "日志",
+  "Logs are loaded from the request history database.": "日志从请求历史数据库中加载。",
+  "Logs are saved to log.txt in the application data directory.": "日志保存在应用程序数据目录下的log.txt中。",
+  "MIT License": "MIT 许可证",
+  "MITM": "MITM",
+  "MITM Proxy": "MITM 代理",
+  "MITM Server": "中间人服务器",
+  "MITM Tools": "MITM 工具",
+  "Machine ID": "机器ID",
+  "Machine ID will be auto-filled...": "机器 ID 将自动填充...",
+  "Make sure Cursor IDE has been opened at least once, then click": "请确保 Cursor IDE 至少已打开过一次，然后点击",
+  "Manage": "管理",
+  "Manage reusable per-connection proxies and bind them to provider connections.": "管理可复用的连接代理并绑定到提供商连接。",
+  "Manage your AI provider connections": "管理您的 AI 提供商连接",
+  "Manage your Embedding providers": "管理您的嵌入提供商",
+  "Manage your Image to Text providers": "管理您的图像转文本提供商",
+  "Manage your Music providers": "管理您的音乐提供商",
+  "Manage your Speech To Text providers": "管理您的语音转文本提供商",
+  "Manage your Text To Speech providers": "管理您的文本转语音提供商",
+  "Manage your Text to Image providers": "管理您的文本转图像提供商",
+  "Manage your Video providers": "管理您的视频提供商",
+  "Manage your Web Fetch providers": "管理您的 Web 抓取提供商",
+  "Manage your Web Search providers": "管理您的 Web 搜索提供商",
+  "Manage your preferences": "管理您的偏好设置",
+  "Manage your proxy pool configurations": "管理您的代理池配置",
+  "Manual / current endpoint": "手动/当前端点",
+  "Manual Callback Required": "需要手动回调",
+  "Manual Config": "手动配置",
+  "Manual configuration is still available if 9router is deployed on a remote server.": "如果 9router 部署在远程服务器上，仍可使用手动配置。",
+  "Map Amp shorthand names such as g25p or cs45 to 9Router aliases in your local config.": "将 Amp 简写名称（如 g25p 或 cs45）映射到本地配置中的 9Router 别名。",
+  "Mask (URL)": "遮罩（URL）",
+  "Max JSON Size (KB)": "最大 JSON 大小 (KB)",
+  "Max Records": "最大记录数",
+  "Maximum request detail records to keep (older records are auto-deleted)": "要保留的最大请求详细记录（较旧的记录会自动删除）",
+  "Maximum size for each JSON field (request/response) before truncation": "截断前每个 JSON 字段（请求/响应）的最大大小",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "刷新缓冲区之前等待的最长时间（防止低流量期间数据丢失）",
+  "Media Providers": "媒体提供商",
+  "Menu": "菜单",
+  "Message AI": "向 AI 发送消息",
+  "Messages": "消息",
+  "Messages API": "消息 API",
+  "MiniMax": "MiniMax",
+  "Model": "模型",
+  "Model Fallback": "模型回退",
+  "Model ID": "模型 ID",
+  "Model ID (from OpenRouter)": "模型 ID（来自 OpenRouter）",
+  "Model ID (optional)": "模型 ID（可选）",
+  "Model Status": "模型状态",
+  "Model combos": "模型组合",
+  "Model combos with fallback": "模型组合及回退",
+  "Model is reachable": "模型可达",
+  "Model list is filtered from connected providers.": "模型列表已从已连接的提供商中筛选。",
+  "Model mappings will be available soon.": "模型映射即将推出。",
+  "Model not reachable": "模型不可达",
+  "Model:": "模型：",
+  "Models": "模型",
+  "Monitor your API usage, token consumption, and request logs": "监控您的 API 使用量、Token 消耗和请求日志",
+  "More on GitHub": "在 GitHub 上查看更多",
+  "Move down": "下移",
+  "Move up": "向上移动",
+  "Music": "音乐",
+  "My Profile": "我的资料",
+  "N/A": "无",
+  "NPM": "NPM",
+  "Name": "名称",
+  "Name is required": "名称为必填项",
+  "Native CLI tool support for Cursor, Claude, Copilot, and more.": "原生支持 Cursor、Claude、Copilot 等 CLI 工具。",
+  "Navigate to home": "导航到首页",
+  "Network": "网络",
+  "Network Error": "网络错误",
+  "Network error": "网络错误",
+  "Never": "从未",
+  "New Password": "新密码",
+  "New password": "新密码",
+  "Next": "下一页",
+  "Next accounts page": "下一页账号",
+  "No API keys - Create one in Keys page": "暂无 API 密钥 - 请在密钥页面创建",
+  "No API keys yet": "还没有 API 密钥",
+  "No MCPs added": "未添加 MCP",
+  "No Providers Connected": "没有连接提供商",
+  "No Proxy": "无代理",
+  "No active connections found for this group.": "未找到该组的活跃连接。",
+  "No active providers": "没有活跃的提供商",
+  "No active proxy pools available. Create one in Proxy Pools page first.": "没有可用的活跃代理池。请先在代理池页面创建一个。",
+  "No authentication required": "无需身份验证",
+  "No combos yet": "还没有组合",
+  "No combos yet.": "暂无组合。",
+  "No compatible providers added yet": "尚未添加兼容的提供商",
+  "No connections": "无连接",
+  "No connections yet": "还没有连接",
+  "No console logs yet.": "还没有控制台日志。",
+  "No conversations yet.": "暂无对话。",
+  "No custom providers": "没有自定义提供商",
+  "No custom providers — use buttons above to add OpenAI/Anthropic compatible endpoints": "没有自定义提供商 — 使用上方按钮添加 OpenAI/Anthropic 兼容端点",
+  "No data for this period": "此期间没有数据",
+  "No key configured": "未配置密钥",
+  "No language selected": "未选择语言",
+  "No languages found.": "未找到语言。",
+  "No logs recorded yet.": "尚未记录任何日志。",
+  "No model selected.": "未选择模型。",
+  "No models": "暂无模型",
+  "No models added yet": "尚未添加模型",
+  "No models configured": "未配置模型",
+  "No models found": "未找到模型",
+  "No models match your filter.": "没有模型匹配您的筛选条件。",
+  "No models selected": "未选择模型",
+  "No port forwarding needed": "无需端口转发",
+  "No pricing data available": "无可用定价数据",
+  "No providers connected": "没有连接提供商",
+  "No providers match your search": "没有匹配搜索结果的提供商",
+  "No providers support": "没有提供商支持",
+  "No providers yet.": "暂无提供商。",
+  "No providers.": "暂无提供商。",
+  "No proxy pool entries yet": "暂无代理池条目",
+  "No proxy:": "无代理：",
+  "No quota data available": "无可用配额数据",
+  "No request details found": "未找到请求详细信息",
+  "No requests yet.": "暂无请求。",
+  "No reset credit details returned for this account.": "此账号没有返回重置信用详情。",
+  "No results": "无结果",
+  "No servers match filter": "没有匹配筛选条件的服务器",
+  "No tools advertised by server.": "服务器未公布任何工具。",
+  "No usage yet.": "暂无使用记录。",
+  "None": "无",
+  "None (unbind all)": "无（解除全部绑定）",
+  "Not configured": "未配置",
+  "Not installed": "未安装",
+  "Notice": "提示",
+  "Nous Research self-improving AI agent": "Nous Research 自我改进的 AI 代理",
+  "Number of items to accumulate before writing to database (higher = better performance)": "写入数据库之前要累积的项目数（越高=性能越好）",
+  "OAuth": "OAuth",
+  "OAuth & API Keys": "OAuth 和 API 密钥",
+  "OAuth Account": "OAuth 账号",
+  "OAuth App": "OAuth 应用",
+  "OAuth Providers": "OAuth 提供商",
+  "OAuth required": "需要 OAuth",
+  "OIDC Dashboard Login": "OIDC 仪表盘登录",
+  "OIDC active": "OIDC 已激活",
+  "OIDC login is currently active. Password login is disabled until you switch back.": "OIDC 登录当前已激活。密码登录已禁用，直到您切换回来。",
+  "OIDC login is enabled, but the issuer/client fields are not configured yet. Password login is still available for recovery.": "OIDC 登录已启用，但发行者/客户端字段尚未配置。密码登录仍可用于恢复。",
+  "OIDC only": "仅 OIDC",
+  "Observability": "可观察性",
+  "Office Proxy": "办公代理",
+  "Ollama Host URL": "Ollama 主机 URL",
+  "One Endpoint for": "统一端点，接入",
+  "One key per line. Format:": "每行一个密钥。格式：",
+  "One-to-one (rotate)": "一对一（轮换）",
+  "Only from connected providers": "仅来自已连接的提供商",
+  "Only letters, numbers, - and _ allowed": "只允许使用字母、数字、- 和 _",
+  "Only letters, numbers, -, _ and .": "仅允许使用字母、数字、-、_ 和 .",
+  "Only letters, numbers, -, _ and . allowed": "仅允许使用字母、数字、-、_ 和 .",
+  "Only one connection is allowed per compatible node. Add another node if you need more connections.": "每个兼容节点仅允许一个连接。如果需要更多连接，请添加另一个节点。",
+  "Open": "打开",
+  "Open Claude Desktop → Help → Troubleshooting → Enable Developer mode → Configure third-party inference, then return here.": "打开 Claude Desktop → 帮助 → 故障排除 → 启用开发者模式 → 配置第三方推理，然后返回此处。",
+  "Open Claw - Manual Configuration": "Open Claw - 手动配置",
+  "Open Claw AI Assistant": "Open Claw AI 助手",
+  "Open Claw CLI not detected locally": "未在本地检测到 Open Claw CLI",
+  "Open Claw CLI not installed": "未安装 Open Claw CLI",
+  "Open Continue configuration file": "打开 Continue 配置文件",
+  "Open Dashboard": "打开仪表盘",
+  "Open DevTools (F12) → Application/Storage → Cookies": "打开 DevTools (F12) → 应用程序/存储 → Cookie",
+  "Open Settings": "打开设置",
+  "Open platform.iflow.cn in your browser": "在浏览器中打开platform.iflow.cn",
+  "OpenAI / ElevenLabs / Edge / Google / Deepgram voices.": "OpenAI / ElevenLabs / Edge / Google / Deepgram 语音。",
+  "OpenAI Codex CLI": "OpenAI Codex CLI",
+  "OpenAI Compatible (Prod)": "OpenAI 兼容（生产）",
+  "OpenAI Compatible Details": "OpenAI 兼容详情",
+  "OpenAI Intermediate": "OpenAI 中间格式",
+  "OpenAI Response": "OpenAI 响应",
+  "OpenCode - Manual Configuration": "OpenCode - 手动配置",
+  "OpenCode AI Terminal Assistant": "OpenCode AI 终端助手",
+  "OpenCode CLI not detected locally": "未在本地检测到 OpenCode CLI",
+  "OpenCode CLI not installed": "未安装 OpenCode CLI",
+  "OpenRouter": "OpenRouter",
+  "OpenRouter supports any model. Add models and create aliases for quick access.": "OpenRouter 支持任何模型。添加模型并创建别名以便快速访问。",
+  "Optional SSO via Authentik/Keycloak/Google": "可选通过 Authentik/Keycloak/Google 的 SSO",
+  "Or paste callback URL manually": "或手动粘贴回调 URL",
+  "Organization": "组织",
+  "Organization Domain": "组织域名",
+  "Organization ID": "组织 ID",
+  "Organization Token": "组织令牌",
+  "Organization Tokens": "组织令牌",
+  "Other": "其他",
+  "Our engine analyzes the prompt and routes through your subscription, cheap, and free provider tiers with automatic fallback.": "我们的引擎分析提示词并通过您的订阅、低价和免费提供商层级路由，自动回退。",
+  "Our engine analyzes the prompt, checks provider health, and routes for lowest latency or cost.": "我们的引擎分析提示词，检查提供商健康状态，并路由到最低延迟或成本的提供商。",
+  "Out": "输出",
+  "Outbound Proxy": "出站代理",
+  "Output": "输出",
+  "Output Cost": "输出成本",
+  "Output Format": "输出格式",
+  "Output Tokens": "输出 Token",
+  "Output Tokens:": "输出 Token：",
+  "Output:": "输出：",
+  "Overview": "概览",
+  "Paid": "付费",
+  "Partial preview": "部分预览",
+  "Password": "密码",
+  "Password + OIDC active": "密码 + OIDC 已激活",
+  "Password and OIDC login are both active.": "密码和 OIDC 登录均已激活。",
+  "Password and OIDC login are both enabled.": "密码和 OIDC 登录均已启用。",
+  "Password only": "仅密码",
+  "Password updated successfully": "密码更新成功",
+  "Passwords do not match": "密码不匹配",
+  "Paste Proxy List (One per line)": "粘贴代理列表（每行一个）",
+  "Paste a long-lived Kiro/CodeWhisperer API key. It is validated against AWS and stored directly as a bearer credential (no refresh).": "粘贴一个长期有效的 Kiro/CodeWhisperer API 密钥。它将通过 AWS 验证并直接存储为 Bearer 凭据（无需刷新）。",
+  "Paste external_idp auth JSON from CLIProxyAPI/Kiro Microsoft login.": "从 CLIProxyAPI/Kiro Microsoft 登录粘贴 external_idp 认证 JSON。",
+  "Paste it below": "粘贴在下面",
+  "Paste refresh token from Kiro IDE.": "从 Kiro IDE 粘贴刷新令牌。",
+  "Paste the Kiro CLIProxyAPI auth JSON containing auth_method=external_idp. Only Microsoft login token endpoints are accepted.": "粘贴包含 auth_method=external_idp 的 Kiro CLIProxyAPI 认证 JSON。仅接受 Microsoft 登录令牌端点。",
+  "Paste the URL from your browser address bar": "从浏览器地址栏粘贴 URL",
+  "Paste the command into your terminal and press Enter.": "将命令粘贴到终端中并按 Enter。",
+  "Paste this to your AI:": "将其粘贴到您的 AI：",
+  "Paste your Kiro API key...": "粘贴您的 Kiro API 密钥...",
+  "Pause API Key": "暂停 API 密钥",
+  "Pause key": "暂停密钥",
+  "Paused": "已暂停",
+  "Permissions": "权限",
+  "Personal Access Token": "个人访问令牌",
+  "Pick the model that fuses panel answers": "选择用于融合面板回答的模型",
+  "Please add an active Qoder connection first": "请先添加一个活跃的 Qoder 连接",
+  "Please add and connect providers first to configure CLI tools.": "请先添加并连接提供商以配置 CLI 工具。",
+  "Please copy the URL from the address bar and paste it in the application.": "请复制地址栏中的 URL 并将其粘贴到应用程序中。",
+  "Please enter a Proxy URL to test": "请输入代理 URL 进行测试",
+  "Please install Claude CLI to use this feature.": "请安装 Claude CLI 才能使用此功能。",
+  "Please install Codex CLI to use auto-apply feature.": "请安装 Codex CLI 以使用自动应用功能。",
+  "Please install Factory Droid CLI to use this feature.": "请安装 Factory Droid CLI 才能使用此功能。",
+  "Please install Open Claw CLI to use this feature.": "请安装 Open Claw CLI 才能使用此功能。",
+  "Please install OpenCode CLI to use auto-apply feature.": "请安装 OpenCode CLI 以使用自动应用功能。",
+  "Please wait while we complete the authorization.": "我们正在完成授权，请稍候。",
+  "Point your CLI tools to http://localhost:20128": "将您的 CLI 工具指向 http://localhost:20128",
+  "Pool:": "代理池：",
+  "Popup blocked? Enter URL manually": "弹出窗口被拦截？请手动输入 URL",
+  "Port 443 Already In Use": "端口 443 已被占用",
+  "Port 443 is currently used by another process:": "端口 443 当前被另一个进程占用：",
+  "Powerful Features": "强大功能",
+  "Prefix": "前缀",
+  "Preset": "预设",
+  "Prev": "上一页",
+  "Preview": "预览",
+  "Previous accounts page": "上一页账号",
+  "Pricing": "定价",
+  "Pricing Configuration": "定价配置",
+  "Pricing Format:": "定价格式：",
+  "Pricing Rates Format": "定价格式",
+  "Pricing Settings": "定价设置",
+  "Priority": "优先级",
+  "Privacy Policy": "隐私政策",
+  "Probing server for tools...": "正在探测服务器工具...",
+  "Processing...": "处理中...",
+  "Product": "产品",
+  "Production Key": "生产密钥",
+  "Project Name": "项目名称",
+  "Prompt": "提示",
+  "Provider": "提供商",
+  "Provider Details": "提供商详情",
+  "Provider Limits": "提供商限制",
+  "Provider Response": "提供商响应",
+  "Provider not found": "未找到提供商",
+  "Provider test failed": "提供商测试失败",
+  "Provider:": "提供商：",
+  "Providers": "提供商",
+  "Proxy": "代理",
+  "Proxy Action": "代理操作",
+  "Proxy Pool": "代理池",
+  "Proxy Pools": "代理池",
+  "Proxy URL": "代理 URL",
+  "Proxy disabled": "代理已禁用",
+  "Proxy enabled": "代理已启用",
+  "Proxy pool created": "代理池已创建",
+  "Proxy pool deleted": "代理池已删除",
+  "Proxy pool updated": "代理池已更新",
+  "Proxy settings applied": "已应用代理设置",
+  "Proxy test OK": "代理测试通过",
+  "Proxy test failed": "代理测试失败",
+  "Proxy test passed": "代理测试通过",
+  "Purpose:": "用途：",
+  "Python >= 3.10 required for local managed mode. Install Python first, or use an external proxy URL.": "本地管理模式需要 Python >= 3.10。请先安装 Python，或使用外部代理 URL。",
+  "Python ≥ 3.10 required for local managed mode. Install Python first, or use an external proxy URL.": "本地管理模式需要 Python ≥ 3.10。请先安装 Python，或使用外部代理 URL。",
+  "Quota Tracker": "配额跟踪器",
+  "Qwen": "Qwen",
+  "Qwen Code supports multiple provider types (openai, anthropic, gemini) via modelProviders in settings.json. 9Router works as an OpenAI-compatible endpoint.": "Qwen Code 通过 settings.json 中的 modelProviders 支持多种提供商类型（openai、anthropic、gemini）。9Router 作为 OpenAI 兼容端点工作。",
+  "Qwen OAuth free tier was discontinued on 2026-04-15. Use 9Router with alicode/openrouter/anthropic/gemini providers instead.": "Qwen OAuth 免费套餐已于 2026-04-15 停止。请改用带有 alicode/openrouter/anthropic/gemini 提供商的 9Router。",
+  "Rate Limited": "被限流",
+  "Read Documentation": "阅读文档",
+  "Reading from AWS SSO cache": "从 AWS SSO 缓存中读取",
+  "Reading from Cursor IDE database": "从 Cursor IDE 数据库读取",
+  "Ready": "就绪",
+  "Ready to Simplify Your AI Infrastructure?": "准备简化您的 AI 基础设施？",
+  "Ready to route! ✓": "准备就绪，可以路由！✓",
+  "Ready! Requests route automatically through your configured providers.": "就绪！请求将自动通过您配置的提供商路由。",
+  "Reasoning": "推理",
+  "Reasoning:": "推理：",
+  "Recent Requests": "最近的请求",
+  "Recent chats": "最近聊天",
+  "Recheck": "重新检查",
+  "Recommended for most users. Free AWS account required.": "推荐给大多数用户。需要免费 AWS 帐户。",
+  "Record request details for inspection in the logs view": "记录请求详情以在日志视图中查看",
+  "Redirect URI": "重定向 URI",
+  "Ref Image (URL)": "参考图片（URL）",
+  "Refresh": "刷新",
+  "Refresh All": "全部刷新",
+  "Refresh Token": "刷新令牌",
+  "Refresh all": "全部刷新",
+  "Refresh quota": "刷新配额",
+  "Region": "区域",
+  "Reload Page": "重新加载页面",
+  "Reload VS Code after applying for changes to take effect.": "应用更改后请重新加载 VS Code 以使其生效。",
+  "Remaining": "剩余",
+  "Remote": "远程",
+  "Remove": "移除",
+  "Remove attachment": "移除附件",
+  "Remove custom model": "删除自定义模型",
+  "Remove model": "删除模型",
+  "Replaces built-in WebSearch/WebFetch. Auto-strips duplicates from tool list.": "替换内置的 WebSearch/WebFetch。自动从工具列表中去除重复项。",
+  "Replay request flow — matches log files": "重放请求流程——匹配日志文件",
+  "Request": "请求",
+  "Request Details": "请求详情",
+  "Request Logs": "请求日志",
+  "Requests": "请求",
+  "Requests without a valid key will be rejected": "没有有效密钥的请求将被拒绝",
+  "Require API key": "需要 API 密钥",
+  "Require OIDC for dashboard access.": "需要 OIDC 才能访问仪表盘。",
+  "Require login": "需要登录",
+  "Required for SSL certificate and DNS configuration": "SSL 证书和 DNS 配置所需",
+  "Required for SSL certificate and server startup": "SSL 证书和服务器启动所需",
+  "Required to modify /etc/hosts and flush DNS cache": "需要修改 /etc/hosts 并刷新 DNS 缓存",
+  "Required. A friendly label for this node.": "必填。为此节点设置一个友好的显示名称。",
+  "Required. Used as the provider prefix for model IDs.": "必填。用作模型 ID 的提供商前缀。",
+  "Requires \"Workers Scripts: Edit\" permission.": "需要 \"Workers Scripts: Edit\" 权限。",
+  "Requires Cloudflare Account ID and a Workers API Token (Edit Workers permission)": "需要 Cloudflare 账号 ID 和 Workers API 令牌（编辑 Workers 权限）",
+  "Requires Cursor Pro account to use this feature.": "需要 Cursor Pro 账号才能使用此功能。",
+  "Requires jcode installed. Install via: curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash": "需要安装 jcode。安装方式：curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash",
+  "Requires outbound port 7844 (TCP/UDP). Connection may take 10-30s.": "需要出站端口 7844 (TCP/UDP)。连接可能需要 10-30 秒。",
+  "Reset": "重置",
+  "Reset Codex limit?": "重置 Codex 限制？",
+  "Reset Password to Default": "重置密码为默认值",
+  "Reset judge to Auto": "重置裁判为自动",
+  "Reset time": "重置时间",
+  "Reset to Defaults": "重置为默认值",
+  "Reset to default": "重置为默认值",
+  "Resources": "资源",
+  "Response": "响应",
+  "Response Format": "响应格式",
+  "Responses": "响应",
+  "Responses API": "响应API",
+  "Restart": "重新启动",
+  "Restore model": "恢复模型",
+  "Resume key": "恢复密钥",
+  "Retry": "重试",
+  "Risk Notice": "风险提示",
+  "Roo AI Assistant": "Roo AI 助手",
+  "Rotate providers across requests instead of strict fallback order.": "在请求间轮换提供商，而不是严格的回退顺序。",
+  "Round Robin": "轮询",
+  "Round Robin — rotate": "轮询 — 轮换",
+  "Round Robin — rotates models across requests to spread load": "轮询 — 在请求间轮换模型以分散负载",
+  "Route AI requests through subscription, cheap, and free tiers with auto-fallback. One endpoint for Claude, GPT, Gemini, and more.": "通过订阅、低价和免费层级路由 AI 请求并自动回退。一个端点接入 Claude、GPT、Gemini 等。",
+  "Route Requests": "路由请求",
+  "Routing Strategy": "路由策略",
+  "Rows:": "行：",
+  "Run": "运行",
+  "Run npx command to start the server instantly": "运行 npx 命令立即启动服务器",
+  "Run this command in your terminal, then click": "在终端中运行此命令，然后单击",
+  "Running": "运行中",
+  "Running on your machine": "在你的机器上运行",
+  "Runtime": "运行时",
+  "SSE URL": "SSE URL",
+  "START HERE": "从这里开始",
+  "Save": "保存",
+  "Save Changes": "保存更改",
+  "Save Config": "保存配置",
+  "Save Mappings": "保存映射",
+  "Save auth mode": "保存认证模式",
+  "Save current Base URL and API key as a browser-local preset": "将当前基础 URL 和 API 密钥保存为浏览器本地预设",
+  "Save this key now!": "立即保存此密钥！",
+  "Saved": "已保存",
+  "Saving": "保存中",
+  "Saving...": "保存中...",
+  "Scan QR to connect instantly": "扫描二维码即刻连接",
+  "Scopes": "权限范围",
+  "Screen sharing": "屏幕共享",
+  "Scroll down to": "向下滚动到",
+  "Search by name or description...": "按名称或描述搜索...",
+  "Search language...": "搜索语言...",
+  "Search model id": "搜索模型 ID",
+  "Search providers...": "搜索提供商...",
+  "Search...": "搜索...",
+  "Security": "安全",
+  "Security required: ": "安全要求：",
+  "Security risk: no password set. You will be asked to set one when logging in remotely.": "安全风险：未设置密码。远程登录时将要求您设置一个密码。",
+  "Select": "选择",
+  "Select All": "全选",
+  "Select Cowork Model": "选择 Cowork 模型",
+  "Select Endpoint": "选择端点",
+  "Select Judge Model": "选择裁判模型",
+  "Select Language": "选择语言",
+  "Select Model": "选择模型",
+  "Select Model for Cline": "选择 Cline 模型",
+  "Select Model for Codex": "选择 Codex 模型",
+  "Select Model for DeepSeek TUI": "选择 DeepSeek TUI 模型",
+  "Select Model for Factory Droid": "选择 Factory Droid 模型",
+  "Select Model for GitHub Copilot": "选择 GitHub Copilot 模型",
+  "Select Model for Hermes Agent": "选择 Hermes Agent 模型",
+  "Select Model for Kilo Code": "选择 Kilo Code 模型",
+  "Select Model for Open Claw": "选择 Open Claw 模型",
+  "Select Model for OpenCode": "选择 OpenCode 模型",
+  "Select Model for jcode": "选择 jcode 模型",
+  "Select Provider": "选择提供商",
+  "Select Subagent Model for Codex": "选择 Codex 子代理模型",
+  "Select Subagent Model for OpenCode": "选择 OpenCode 子代理模型",
+  "Select a provider": "选择提供商",
+  "Select all": "选择全部",
+  "Select language": "选择语言",
+  "Select models to add": "选择要添加的模型",
+  "Select one or more connections, then click Proxy Action.": "选择一个或多个连接，然后点击代理操作。",
+  "Select to pre-fill, then edit model ID in the input": "选择以预填充，然后在输入框中编辑模型 ID",
+  "Select your": "选择您的",
+  "Selected connections have mixed proxy bindings": "所选连接的代理绑定状态不一致",
+  "Selected only": "仅选定",
+  "Selected provider": "选定的提供商",
+  "Selecting None will unbind selected connections from proxy pool.": "选择「无」将解除所选连接与代理池的绑定。",
+  "Send": "发送",
+  "Send to Provider": "发送给提供商",
+  "Sent to provider as:": "发送给提供商：",
+  "Server": "服务器",
+  "Server Disconnected": "服务器已断开",
+  "Server off": "服务器关闭",
+  "Server running on": "服务器运行在",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "服务正在终端中运行。您可以关闭此网页。关闭将停止服务。",
+  "Set Password": "设置密码",
+  "Set a new password before accessing the dashboard remotely.": "在远程访问仪表盘之前设置一个新密码。",
+  "Set password": "设置密码",
+  "Setting password for the first time. Leave current password empty or use default:": "首次设置密码。将当前密码留空或使用默认值：",
+  "Setting up": "设置",
+  "Settings": "设置",
+  "Settings applied successfully!": "设置已成功应用！",
+  "Settings reset successfully!": "设置已成功重置！",
+  "Setup": "设置",
+  "Setup + index of all capabilities. Start here — covers base URL, auth, model discovery, and links to every capability skill.": "所有功能的设置和索引。从这里开始 — 涵盖基础 URL、认证、模型发现，并链接到每个功能技能。",
+  "Share Endpoint": "共享端点",
+  "Share URL with team members": "与团队成员共享 URL",
+  "Show": "显示",
+  "Show all": "显示全部",
+  "Show key": "显示密钥",
+  "Show only selected models": "仅显示选中的模型",
+  "Showing": "显示中",
+  "Shutdown": "关闭",
+  "Sign in with OIDC": "使用 OIDC 登录",
+  "Simple chat interface to interact with any AI model from connected providers. Select a model and start chatting!": "简单的聊天界面，与已连接提供商的任何 AI 模型交互。选择一个模型开始聊天！",
+  "Single": "单个",
+  "Single API endpoint for all major AI providers. Simplify your integration.": "一个 API 端点接入所有主要 AI 提供商。简化集成。",
+  "Some models are not responding": "部分模型未响应",
+  "Sort Codex quotas by remaining": "按剩余量排序 Codex 配额",
+  "Sort accounts by earliest quota reset time": "按最早配额重置时间排序账号",
+  "Source Body": "源请求体",
+  "Sourcegraph Amp coding assistant CLI": "Sourcegraph Amp 编程助手 CLI",
+  "Special reasoning/thinking tokens (fallback to output rate)": "特殊推理/思考 Token（回退至输出费率）",
+  "Speech To Text": "语音转文本",
+  "Speech-to-Text": "语音转文本",
+  "Standard prompt tokens": "标准提示 Token",
+  "Start DNS": "启动 DNS",
+  "Start Date": "开始日期",
+  "Start Free": "免费开始",
+  "Start Headroom": "启动 Headroom",
+  "Start Headroom separately at the configured URL, then recheck.": "在配置的 URL 上单独启动 Headroom，然后重新检查。",
+  "Start MITM": "启动中间人",
+  "Start Server": "启动服务器",
+  "Start Tunnel": "开始隧道",
+  "Start a conversation": "开始一个对话",
+  "Starting 9Router...": "正在启动 9Router...",
+  "Status": "状态",
+  "Status:": "状态：",
+  "Step 1: Open this URL in your browser": "第 1 步：在浏览器中打开此 URL",
+  "Step 2: Paste the callback URL here": "第 2 步：将回调 URL 粘贴到此处",
+  "Sticky Limit": "粘性限制",
+  "Sticky:": "粘滞：",
+  "Stop": "停止",
+  "Stop DNS": "停止 DNS",
+  "Stop Headroom": "停止 Headroom",
+  "Stop MITM": "停止中间人",
+  "Stop Server": "停止服务器",
+  "Stopped": "已停止",
+  "Strict Proxy": "严格代理",
+  "Subagent Model": "子代理模型",
+  "Sudo Password Required": "需要 sudo 密码",
+  "Sudo password is required": "需要 sudo 密码",
+  "Suggested free models (≥200k context):": "推荐的免费模型（≥200k 上下文）：",
+  "Suggested shorthand examples: g25p → gemini/gemini-2.5-pro, g25f → gemini/gemini-2.5-flash, cs45 → cc/claude-sonnet-4-5-20250929.": "建议的简写示例：g25p → gemini/gemini-2.5-pro, g25f → gemini/gemini-2.5-flash, cs45 → cc/claude-sonnet-4-5-20250929。",
+  "Support up to 20 active apps & 50 custom domains": "支持最多 20 个活跃应用和 50 个自定义域名",
+  "Supported formats: protocol://user:pass@host:port, host:port:user:pass": "支持的格式：protocol://user:pass@host:port, host:port:user:pass",
+  "Sync settings across devices with optional cloud storage.": "通过可选的云存储在设备间同步设置。",
+  "System": "系统",
+  "TTFT:": "TTFT：",
+  "Tailscale": "Tailscale",
+  "Tailscale Funnel": "Tailscale Funnel",
+  "Tailscale Funnel will be stopped. Remote access via Tailscale URL will stop working.": "Tailscale Funnel 将停止。通过 Tailscale URL 的远程访问将停止工作。",
+  "Tailscale installed": "Tailscale 已安装",
+  "Tailscale is not installed. Install it to enable Funnel.": "Tailscale 未安装。请安装它以启用 Funnel。",
+  "Target Request": "目标请求",
+  "Tavily / Exa / Brave / Serper / SearXNG / Google PSE / You.com.": "Tavily / Exa / Brave / Serper / SearXNG / Google PSE / You.com。",
+  "Temperature": "温度",
+  "Terminal": "终端",
+  "Terms of Service": "服务条款",
+  "Terse-style system prompt → ~65% fewer output tokens (up to 87%)": "简洁风格系统提示 → ~减少 65% 的输出 Token（最高 87%）",
+  "Test": "测试",
+  "Test Again": "再次测试",
+  "Test All": "全部测试",
+  "Test Example": "测试示例",
+  "Test Results": "测试结果",
+  "Test all API Key connections": "测试所有 API 密钥连接",
+  "Test all Compatible connections": "测试所有兼容连接",
+  "Test all Free connections": "测试所有免费连接",
+  "Test all Free provider connections": "测试所有免费提供商连接",
+  "Test all OAuth connections": "测试所有 OAuth 连接",
+  "Test connection": "测试连接",
+  "Test model": "测试模型",
+  "Test proxy": "测试代理",
+  "Test proxy URL": "测试代理 URL",
+  "Testing...": "测试中...",
+  "Text To Speech": "文本转语音",
+  "Text To Speech combo": "文本转语音组合",
+  "Text to Image": "文本转图像",
+  "Text to Image combo": "文本转图像组合",
+  "Text-to-Speech": "文本转语音",
+  "Text-to-image via DALL-E, Imagen, FLUX, MiniMax, SDWebUI…": "通过 DALL-E、Imagen、FLUX、MiniMax、SDWebUI 等进行文本到图像生成。",
+  "The Cloudflare tunnel will be disconnected. Remote access via tunnel URL will stop working.": "Cloudflare 隧道将被断开。通过隧道 URL 的远程访问将停止工作。",
+  "The proxy server has been stopped.": "代理服务器已停止。",
+  "The request is fulfilled by OpenAI, Anthropic, Gemini, or others instantly.": "请求由 OpenAI、Anthropic、Gemini 或其他提供商即时响应。",
+  "The tunnel will be disconnected. Remote access will stop working.": "隧道将被断开。远程访问将停止工作。",
+  "The unified endpoint for AI generation. Connect, route, and manage your AI providers with ease.": "统一的 AI 生成端点。轻松连接、路由和管理您的 AI 提供商。",
+  "The unified interface for modern AI infrastructure": "现代 AI 基础设施的统一接口",
+  "The unified interface for modern AI infrastructure. Secure, observable, and scalable.": "现代人工智能基础设施的统一接口。安全、可观察且可扩展。",
+  "Theme": "主题",
+  "Thinking": "思考",
+  "Thinking Process": "思考过程",
+  "This is the only time you will see this key. Store it securely.": "这是您唯一一次看到此密钥的机会。请妥善保管。",
+  "This provider is ready to use.": "此提供商已准备就绪。",
+  "This provider is ready to use. Optionally route requests through a proxy pool to bypass IP-based limits.": "此提供商已准备就绪。可选择通过代理池路由请求以绕过 IP 限制。",
+  "This value is write-only after saving.": "此值保存后仅可写入。",
+  "Timestamp": "时间戳",
+  "Timestamp:": "时间戳：",
+  "To get a fresh API key, paste your browser cookie from": "要获取新的 API 密钥，请粘贴您的浏览器 cookie",
+  "Today": "今天",
+  "Toggle DNS to redirect": "切换 DNS 重定向",
+  "Toggle auto-ping": "切换自动 Ping",
+  "Token Saver": "Token 节省器",
+  "Token Types:": "Token 类型：",
+  "Token auto-detected from Kiro IDE successfully!": "已成功从 Kiro IDE 自动检测到令牌！",
+  "Token is used once for deployment and not stored.": "令牌仅用于部署一次，不会被存储。",
+  "Token is used once for deployment, not stored. Found in Organization Settings.": "令牌仅用于部署一次，不会被存储。可在组织设置中找到。",
+  "Token will be auto-filled...": "令牌将自动填充...",
+  "Tokens": "Token",
+  "Tokens auto-detected from Cursor IDE successfully!": "已成功从 Cursor IDE 自动检测到令牌！",
+  "Tokens used to create cache entries (fallback to input rate)": "用于创建缓存条目的 Token（回退至输入费率）",
+  "Tomorrow": "明天",
+  "Tool not found or disabled.": "未找到或工具已禁用。",
+  "Tools": "工具",
+  "Tools:": "工具：",
+  "Total Cost": "总成本",
+  "Total Input Tokens": "输入 Token 总计",
+  "Total Models": "模型总数",
+  "Total Requests": "请求总数",
+  "Total Tokens": "总 Token",
+  "Total:": "总计：",
+  "Track and manage your API quota limits": "跟踪和管理您的 API 配额限制",
+  "Track token usage, costs, and performance across all providers.": "跟踪所有提供商的 Token 使用量、成本和性能。",
+  "Transcribe audio via OpenAI Whisper, Groq, Gemini, Deepgram, AssemblyAI…": "通过 OpenAI Whisper、Groq、Gemini、Deepgram、AssemblyAI 等转录音频。",
+  "Transferring data...": "数据传输中...",
+  "Translator": "翻译器",
+  "Translator Debug": "翻译器调试",
+  "Tried in order (top-down) or rotated when round-robin is on.": "按顺序尝试（从上到下）或开启轮询时轮换。",
+  "Trust Cert": "信任证书",
+  "Trusted": "已信任",
+  "Try Again": "再试一次",
+  "Tunnel": "隧道",
+  "Tunnel connected!": "隧道连通！",
+  "Tunnel disabled": "隧道已禁用",
+  "Turn off Empty": "关闭空账号",
+  "Turn on Available": "开启可用账号",
+  "Turn request detail recording on/off globally": "全局打开/关闭请求详细信息记录",
+  "Twitter": "Twitter",
+  "URL → markdown / text / HTML via Firecrawl, Jina, Tavily, Exa.": "URL → 通过 Firecrawl、Jina、Tavily、Exa 转换为 markdown / text / HTML。",
+  "Unavailable": "不可用",
+  "Under": "在",
+  "Unified Endpoint": "统一端点",
+  "Unknown": "未知",
+  "Unselect all": "取消选择全部",
+  "Update": "更新",
+  "Update 9Router": "更新 9Router",
+  "Update Password": "修改密码",
+  "Update now": "立即更新",
+  "Upstream Auth Error": "上游认证错误",
+  "Upstream Unavailable": "上游不可用",
+  "Usage": "使用情况",
+  "Usage & Analytics": "使用量和分析",
+  "Usage / Limit": "使用量/限制",
+  "Usage Logs": "使用日志",
+  "Usage Tracking": "使用量跟踪",
+  "Usage by API Key": "按 API 密钥统计",
+  "Usage by Account": "按账号统计",
+  "Usage by Endpoint": "按端点统计",
+  "Usage by Model": "按模型统计",
+  "Usage:": "用法：",
+  "Use 9Router model aliases to keep Amp shorthand mappings stable across provider updates.": "使用 9Router 模型别名来保持 Amp 简写映射在提供商更新时稳定。",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "使用 Antigravity IDE 和 GitHub Copilot → 与 9Router 的任何提供商/模型",
+  "Use Authentik or any OIDC provider to sign in to the dashboard.": "使用 Authentik 或任何 OIDC 提供商登录仪表盘。",
+  "Use Authentik or any OIDC provider to sign in to the dashboard. You can enable password-only, OIDC-only, or both for the dashboard; model API access still uses API keys.": "使用 Authentik 或任何 OIDC 提供商登录仪表盘。您可以启用仅密码、仅 OIDC 或两者同时启用；模型 API 访问仍使用 API 密钥。",
+  "Use a GitLab OAuth application": "使用 GitLab OAuth 应用",
+  "Use a GitLab PAT with api scope": "使用具有 api 范围的 GitLab PAT",
+  "Use a direct xAI API key from console.x.ai. This is separate from Grok Build OAuth.": "使用来自 console.x.ai 的直接 xAI API 密钥。这与 Grok Build OAuth 是分开的。",
+  "Use a local proxy for Start/Stop, or an external Docker sidecar like http://headroom:8787.": "使用本地代理进行启动/停止，或使用外部 Docker sidecar 如 http://headroom:8787。",
+  "Use a long-lived Kiro/CodeWhisperer API key (headless auth).": "使用长期有效的 Kiro/CodeWhisperer API 密钥（无头认证）。",
+  "Use in Cursor/Cline": "在Cursor/Cline中使用",
+  "Use the buttons above to add OpenAI or Anthropic compatible endpoints": "使用上面的按钮添加 OpenAI 或 Anthropic 兼容端点",
+  "Use your API from any network": "从任何网络使用您的 API",
+  "Valid": "有效",
+  "Vectors for RAG / semantic search via OpenAI, Gemini, Mistral…": "通过 OpenAI、Gemini、Mistral 等为 RAG/语义搜索提供向量。",
+  "Vercel API Token": "Vercel API Token",
+  "Vercel Relay": "Vercel Relay",
+  "Vercel serves millions of apps — providers can't block Vercel IPs without affecting legitimate traffic": "Vercel 服务数百万应用 — 提供商无法在不影响合法流量的情况下封禁 Vercel IP",
+  "Verification URL": "验证 URL",
+  "Video": "视频",
+  "View Codex reset credit expiry": "查看 Codex 重置信用有效期",
+  "View Full Details": "查看完整详情",
+  "View on GitHub": "在 GitHub 上查看",
+  "Visit the URL below and enter the code:": "访问以下网址并输入代码：",
+  "Visit the login URL below and authorize:": "访问下面的登录 URL 并进行授权：",
+  "Voice": "语音",
+  "Voice ID": "语音 ID",
+  "Voyage AI": "Voyage AI",
+  "Waiting for Authorization": "等待授权",
+  "Waiting for authorization...": "等待授权...",
+  "Warning": "警告",
+  "Web Fetch": "Web 抓取",
+  "Web Fetch & Search": "Web 搜索与抓取",
+  "Web Search": "Web 搜索",
+  "Web Search & Fetch (Exa)": "Web 搜索与抓取（Exa）",
+  "Welcome": "欢迎",
+  "What is Cloudflare Relay?": "什么是 Cloudflare Relay？",
+  "What is Deno Relay?": "什么是 Deno Relay？",
+  "What is Vercel Relay?": "什么是 Vercel Relay？",
+  "When": "时间",
+  "When ON, dashboard requires password. When OFF, access without login.": "当打开时，仪表板需要密码。当关闭时，无需登录即可访问。",
+  "Windows:": "Windows：",
+  "Windows: Run 9Router terminal as Administrator": "Windows：以管理员身份运行 9Router 终端",
+  "Windows: Run terminal (9Router) as Administrator to enable MITM": "Windows：以管理员身份运行终端 (9Router) 以启用 MITM",
+  "Worker Name": "Worker 名称",
+  "Works on any device": "适用于任何设备",
+  "Writes to": "写入到",
+  "You can override default pricing for specific models. Reset to defaults anytime to restore standard rates.": "您可以覆盖特定模型的默认定价。随时重置为默认值以恢复标准费率。",
+  "Your": "你的",
+  "Your Account Name": "您的账号名称",
+  "Your Code": "你的代码",
+  "Your Kiro account via": "您的 Kiro 帐户通过",
+  "Your OAuth application client ID": "您的 OAuth 应用客户端 ID",
+  "Your organization's AWS IAM Identity Center URL": "您组织的 AWS IAM Identity Center URL",
+  "Your requests start from your favorite tools or our unified SDK. Just change the base URL.": "您的请求从您最熟悉的工具或我们的统一 SDK 发起。只需更改基础 URL。",
+  "Your requests start from your favorite tools — Cursor, Claude, Copilot, or any OpenAI-compatible SDK.": "请求从您常用的工具发起——Cursor、Claude、Copilot 或任何 OpenAI 兼容的 SDK。",
+  "account has been connected.": "账号已连接。",
+  "active": "活跃",
+  "add OpenAI/Anthropic compatible endpoints": "添加 OpenAI/Anthropic 兼容端点",
+  "added)": "已添加）",
+  "again after install.": "安装后再次运行。",
+  "and click": "并点击",
+  "apiKey": "apiKey",
+  "below.": "下方。",
+  "bound": "已绑定",
+  "chars)": "字符）",
+  "cloudflare relay": "cloudflare 中继",
+  "connection": "个连接",
+  "connections": "个连接",
+  "daily-cloudcode-pa.googleapis.com": "daily-cloudcode-pa.googleapis.com",
+  "dark": "深色",
+  "disabled": "已禁用",
+  "dollars per million tokens": "美元 / 百万 Token",
+  "e.g. CwhRBWXzGAHq8TQ4Fs17": "例如 CwhRBWXzGAHq8TQ4Fs17",
+  "e.g. claude-opus-4-5": "例如 claude-opus-4-5",
+  "e.g. my-model-id": "例如 my-model-id",
+  "e.g. tts-1-hd": "例如 tts-1-hd",
+  "e.g. voyage-3, embed-english-v3.0, text-embedding-3-small": "例如 voyage-3, embed-english-v3.0, text-embedding-3-small",
+  "e.g., Production API, Dev Environment": "例如，生产 API、开发环境",
+  "every request bills all panel models + the judge": "每次请求会计费所有面板模型 + 裁判",
+  "export": "导出",
+  "failed": "失败",
+  "git/grep/ls/tree/logs → 60-90% fewer input tokens": "git/grep/ls/tree/logs → 减少 60-90% 的输入 Token",
+  "h ago": "小时前",
+  "has been connected.": "已连接。",
+  "iFlow AI": "iFlow AI",
+  "iFlow Cookie Authentication": "iFlow Cookie 身份验证",
+  "import": "导入",
+  "inactive": "未激活",
+  "jcode - Manual Configuration": "jcode - 手动配置",
+  "jcode CLI not detected locally": "未在本地检测到 jcode CLI",
+  "jcode is a Rust-based coding agent with semantic memory, multi-agent swarms, and extreme performance (27.8 MB RAM, 14ms boot).": "jcode 是基于 Rust 的编程代理，具有语义记忆、多代理集群和极致性能（27.8 MB 内存，14ms 启动）。",
+  "kiro://kiro.kiroAgent/authenticate-success?code=...": "kiro://kiro.kiroAgent/authenticate-success?code=...",
+  "light": "浅色",
+  "m ago": "分钟前",
+  "macOS / Linux / Windows:": "macOS / Linux / Windows：",
+  "macOS / Linux:": "macOS / Linux：",
+  "macOS/Linux:": "macOS/Linux：",
+  "more": "更多",
+  "more providers": "更多提供商",
+  "ms / Total": "毫秒/总计",
+  "name|apiKey": "name|apiKey",
+  "no_proxy:": "无代理：",
+  "not detected locally": "未在本地检测到",
+  "npm install -g 9router": "npm install -g 9router",
+  "npx 9router": "npx 9router",
+  "open http://localhost:9099": "open http://localhost:9099",
+  "openid profile email": "openid profile email",
+  "optional context to improve accuracy": "可选的上下文，用于提高准确性",
+  "or VS Code extension marketplace.": "或 VS Code 扩展市场。",
+  "or just": "或仅",
+  "passed": "通过",
+  "platform.iflow.cn": "platform.iflow.cn",
+  "queries all models in parallel, then a judge synthesizes one answer. Best quality, but costs the most: every request bills all panel models + the judge (N+1 calls)": "并行查询所有模型，然后由裁判综合出一个答案。质量最佳但成本最高：每次请求会计费所有面板模型 + 裁判（N+1 次调用）",
+  "records, batches every": "记录，每批",
+  "requests, max": "请求数，最大",
+  "rotates models across requests to spread load": "在请求间轮换模型以分散负载",
+  "s)": "）",
+  "s...": "秒...",
+  "seconds...": "秒...",
+  "sends image/PDF/audio requests to a model that supports them first": "将图片/PDF/音频请求优先发送到支持的模型",
+  "sk-...": "sk-...",
+  "sk_9router (default)": "sk_9router（默认）",
+  "system": "跟随系统",
+  "tested": "已测试",
+  "the database.": "数据库。",
+  "to apply changes": "以使更改生效",
+  "to verify.": "来验证。",
+  "traffic through 9Router via MITM.": "通过 MITM 通过 9Router 的流量。",
+  "tries models in order (next on failure)": "按顺序尝试模型（失败时切换到下一个）",
+  "unknown": "未知",
+  "v1.0 is now live": "v1.0 现已上线",
+  "vercel relay": "vercel 中继",
+  "yet.": "。",
+  "your-org.deno.net": "your-org.deno.net",
+  "© 2025 9Router. All rights reserved.": "© 2025 9Router。保留所有权利。",
+  "— queries all models in parallel, then a judge synthesizes one answer. Best quality, but costs the most: every request bills all panel models + the judge (N+1 calls)": "— 并行查询所有模型，然后由裁判综合出一个答案。质量最佳但成本最高：每次请求会计费所有面板模型 + 裁判（N+1 次调用）",
+  "— rotates models across requests to spread load": "— 在请求间轮换模型以分散负载",
+  "— sends image/PDF/audio requests to a model that supports them first": "— 将图片/PDF/音频请求优先发送到支持的模型",
+  "— tries models in order (next on failure)": "— 按顺序尝试模型（失败时切换到下一个）",
+  "→ OpenAI": "→ OpenAI",
+  "→ Target": "→ 目标",
+  "→ localhost": "→ localhost",
+  "⚠️ Enable DNS to edit model mappings": "⚠️ 启用 DNS 以编辑模型映射",
+  "⚠️ Local plugins run as subprocess via": "⚠️ 本地插件通过子进程运行",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM 通过本地 CA 拦截 IDE 工具（Antigravity、GitHub Copilot、Kiro）的 HTTPS 流量，将请求重定向到您的提供商。可能违反 ToS → 账户封禁风险。使用风险自负。",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ 风险提示：此提供商使用的订阅/OAuth 会话未获官方授权用于代理/路由器使用。账户可能被限制或封禁。使用风险自负。",
+  "✓ Confirm Add": "✓ 确认添加",
+  "📝 Configure providers in dashboard or use environment variables": "📝 在仪表盘中配置提供商或使用环境变量",
+  "🔐 OAuth required. Add now and authenticate after Apply; tool list will be discovered after first connect.": "🔐 需要 OAuth。立即添加并在应用后认证；工具列表将在首次连接后自动发现。"
+}
diff --git a/public/i18n/literals/zh-TW.json b/public/i18n/literals/zh-TW.json
new file mode 100644
index 0000000..ea9183e
--- /dev/null
+++ b/public/i18n/literals/zh-TW.json
@@ -0,0 +1,195 @@
+{
+  "Cancel": "取消",
+  "Delete": "刪除",
+  "Edit": "編輯",
+  "Save": "保存",
+  "Close": "關閉",
+  "Add": "添加",
+  "Remove": "移除",
+  "Settings": "設置",
+  "Profile": "個人資料",
+  "Dashboard": "儀表板",
+  "Logout": "登出",
+  "Login": "登錄",
+  "Providers": "提供者",
+  "Usage": "統計",
+  "API Key": "API 金鑰",
+  "Connected": "已連接",
+  "Disconnected": "未連接",
+  "Active": "活躍",
+  "Inactive": "非活躍",
+  "Success": "成功",
+  "Failed": "失敗",
+  "Error": "錯誤",
+  "Warning": "警告",
+  "Info": "信息",
+  "Loading": "載入中",
+  "Search": "搜尋",
+  "Filter": "篩選",
+  "Sort": "排序",
+  "Export": "導出",
+  "Import": "導入",
+  "Refresh": "刷新",
+  "Back": "返回",
+  "Next": "下一個",
+  "Previous": "上一個",
+  "Submit": "提交",
+  "Confirm": "確認",
+  "Yes": "是",
+  "No": "否",
+  "OK": "確定",
+  "Apply": "應用",
+  "Reset": "重置",
+  "Clear": "清除",
+  "Select": "選擇",
+  "Upload": "上傳",
+  "Download": "下載",
+  "Copy": "複製",
+  "Paste": "粘貼",
+  "Cut": "剪切",
+  "Undo": "撤銷",
+  "Redo": "重做",
+  "Name": "名稱",
+  "Description": "描述",
+  "Status": "狀態",
+  "Type": "類型",
+  "Date": "日期",
+  "Time": "時間",
+  "Created": "已建立",
+  "Updated": "已更新",
+  "Actions": "操作",
+  "Details": "詳細信息",
+  "View": "查看",
+  "New": "新建",
+  "Total": "總計",
+  "Count": "計數",
+  "Price": "價格",
+  "Cost": "成本",
+  "Free": "免費",
+  "Paid": "付費",
+  "Enable": "啟用",
+  "Disable": "禁用",
+  "Enabled": "已啟用",
+  "Disabled": "已禁用",
+  "Online": "在線",
+  "Offline": "離線",
+  "Available": "可用",
+  "Unavailable": "不可用",
+  "Required": "必需",
+  "Optional": "可選",
+  "Default": "默認",
+  "Custom": "自定義",
+  "Advanced": "進階",
+  "Basic": "基本",
+  "Help": "幫助",
+  "Support": "支持",
+  "Documentation": "文檔",
+  "Version": "版本",
+  "Language": "語言",
+  "Theme": "主題",
+  "Light": "淺色",
+  "Dark": "深色",
+  "Auto": "自動",
+  "Endpoint": "端點",
+  "Combos": "組合",
+  "Quota Tracker": "配額跟蹤",
+  "MITM": "MITM",
+  "CLI Tools": "CLI 工具",
+  "Console Log": "控制台日誌",
+  "System": "系統",
+  "Debug": "調試",
+  "Shutdown": "關機",
+  "Close Proxy": "關閉代理",
+  "Are you sure you want to close the proxy server?": "您確定要關閉代理服務器嗎？",
+  "Server Disconnected": "服務器已斷開連接",
+  "The proxy server has been stopped.": "代理服務器已停止。",
+  "Reload Page": "重新加載頁面",
+  "Service is running in terminal. You can close this web page. Shutdown will stop the service.": "服務在終端中運行。您可以關閉此網頁。關機將停止服務。",
+  "Manage your AI provider connections": "管理您的 AI 提供者連接",
+  "Model combos with fallback": "具有備用的模型組合",
+  "Monitor your API usage, token consumption, and request logs": "監控您的 API 使用、令牌消耗和請求日誌",
+  "Intercept CLI tool traffic and route through 9Router": "攔截 CLI 工具流量並通過 9Router 路由",
+  "Configure CLI tools": "配置 CLI 工具",
+  "API endpoint configuration": "API 端點配置",
+  "Manage your preferences": "管理您的首選項",
+  "Debug translation flow between formats": "調試格式之間的轉換流",
+  "Live server console output": "實時服務器控制台輸出",
+  "Create model combos with fallback support": "創建具有備用支持的模型組合",
+  "Local Mode": "本地模式",
+  "Running on your machine": "在您的機器上運行",
+  "Database Location": "數據庫位置",
+  "Download Backup": "下載備份",
+  "Import Backup": "導入備份",
+  "Database backup downloaded": "已下載數據庫備份",
+  "Database imported successfully": "已成功導入數據庫",
+  "Security": "安全性",
+  "Require login": "需要登錄",
+  "When ON, dashboard requires password. When OFF, access without login.": "打開時，儀表板需要密碼。關閉時，無需登錄即可訪問。",
+  "Current Password": "當前密碼",
+  "Enter current password": "輸入當前密碼",
+  "New Password": "新密碼",
+  "Enter new password": "輸入新密碼",
+  "Confirm New Password": "確認新密碼",
+  "Confirm new password": "確認新密碼",
+  "Update Password": "更新密碼",
+  "Set Password": "設置密碼",
+  "Password updated successfully": "已成功更新密碼",
+  "Passwords do not match": "密碼不匹配",
+  "Routing Strategy": "路由策略",
+  "Round Robin": "輪詢",
+  "Cycle through accounts to distribute load": "循環循環帳戶以分配負載",
+  "Sticky Limit": "粘性限制",
+  "Calls per account before switching": "切換前每個帳戶的調用次數",
+  "Network": "網絡",
+  "Outbound Proxy": "出站代理",
+  "Enable proxy for OAuth + provider outbound requests.": "為 OAuth + 提供者出站請求啟用代理。",
+  "Proxy URL": "代理 URL",
+  "Leave empty to inherit existing env proxy (if any).": "留空以繼承現有的環境代理（如果有）。",
+  "No Proxy": "無代理",
+  "Comma-separated hostnames/domains to bypass the proxy.": "逗號分隔的主機名/域以繞過代理。",
+  "Test proxy URL": "測試代理 URL",
+  "Proxy settings applied": "已應用代理設置",
+  "Proxy enabled": "已啟用代理",
+  "Proxy disabled": "已禁用代理",
+  "Proxy test OK": "代理測試成功",
+  "Proxy test failed": "代理測試失敗",
+  "Please enter a Proxy URL to test": "請輸入要測試的代理 URL",
+  "Observability": "可觀測性",
+  "Enable Observability": "啟用可觀測性",
+  "Turn request detail recording on/off globally": "全局打開/關閉請求詳細記錄",
+  "Max Records": "最大記錄數",
+  "Maximum request detail records to keep (older records are auto-deleted)": "要保留的最大請求詳細記錄數（舊記錄自動刪除）",
+  "Batch Size": "批量大小",
+  "Number of items to accumulate before writing to database (higher = better performance)": "寫入數據庫前要積累的項目數（更高 = 更好的性能）",
+  "Flush Interval (ms)": "刷新間隔 (ms)",
+  "Maximum time to wait before flushing buffer (prevents data loss during low traffic)": "刷新緩衝區之前的最大等待時間（防止低流量期間的數據丟失）",
+  "Max JSON Size (KB)": "最大 JSON 大小 (KB)",
+  "Maximum size for each JSON field (request/response) before truncation": "截斷前每個 JSON 字段（請求/響應）的最大大小",
+  "All data stored on your machine": "所有數據存儲在您的機器上",
+  "MITM Server": "MITM 服務器",
+  "Running": "運行中",
+  "Stopped": "已停止",
+  "Cert": "證書",
+  "Server": "服務器",
+  "Purpose:": "目的：",
+  "Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router": "使用 Antigravity IDE 和 GitHub Copilot → 與 9Router 中的任何提供者/模型一起",
+  "How it works:": "工作原理：",
+  "Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot": "Antigravity/Copilot IDE 請求 → DNS 重定向到 localhost:443 → MITM 代理攔截 → 9Router → 响應到 Antigravity/Copilot",
+  "No API keys — create one in Keys page": "沒有 API 金鑰 — 在金鑰頁面中創建一個",
+  "sk_9router (default)": "sk_9router（默認）",
+  "Server started": "服務器已啟動",
+  "Failed to start server": "啟動服務器失敗",
+  "Server stopped — all DNS cleared": "服務器已停止 — 已清除所有 DNS",
+  "Failed to stop server": "停止服務器失敗",
+  "Sudo password is required": "需要 Sudo 密碼",
+  "Stop Server": "停止服務器",
+  "Start Server": "啟動服務器",
+  "Enable DNS per tool below to activate interception": "為下面的每個工具啟用 DNS 以激活攔截",
+  "Sudo Password Required": "需要 Sudo 密碼",
+  "Enter your sudo password to start/stop MITM server": "輸入您的 Sudo 密碼以啟動/停止 MITM 服務器",
+  "Sudo Password": "Sudo 密碼",
+  "Click to add, click again to remove. Changes are saved automatically.": "點擊新增，再次點擊移除。變更將自動儲存。",
+  "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.": "⚠️ 風險提示：此提供商使用的訂閱/OAuth 工作階段未獲官方授權用於代理/路由器使用。帳戶可能被限制或封禁。使用風險自負。",
+  "⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.": "⚠️ MITM 透過本地 CA 攔截 IDE 工具（Antigravity、GitHub Copilot、Kiro）的 HTTPS 流量，將請求重新導向到您的提供商。可能違反 ToS → 帳戶封禁風險。使用風險自負。",
+  "Endpoint is exposed without an API key.": "端點未設定 API 金鑰即對外暴露。"
+}
diff --git a/public/icons/icon-192.svg b/public/icons/icon-192.svg
new file mode 100644
index 0000000..e797891
--- /dev/null
+++ b/public/icons/icon-192.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="192" height="192" viewBox="0 0 192 192">
+  <rect width="192" height="192" rx="24" fill="#0a0a0a"/>
+  <text x="96" y="120" font-family="Arial, sans-serif" font-size="80" font-weight="bold" fill="#ffffff" text-anchor="middle">9R</text>
+</svg>
diff --git a/public/icons/icon-512.svg b/public/icons/icon-512.svg
new file mode 100644
index 0000000..6fef45a
--- /dev/null
+++ b/public/icons/icon-512.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="64" fill="#0a0a0a"/>
+  <text x="256" y="320" font-family="Arial, sans-serif" font-size="200" font-weight="bold" fill="#ffffff" text-anchor="middle">9R</text>
+</svg>
diff --git a/public/next.svg b/public/next.svg
new file mode 100644
index 0000000..5174b28
--- /dev/null
+++ b/public/next.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>
\ No newline at end of file
diff --git a/public/providers/alicode-intl.png b/public/providers/alicode-intl.png
new file mode 100644
index 0000000..9bee7d5
Binary files /dev/null and b/public/providers/alicode-intl.png differ
diff --git a/public/providers/alicode.png b/public/providers/alicode.png
new file mode 100644
index 0000000..9bee7d5
Binary files /dev/null and b/public/providers/alicode.png differ
diff --git a/public/providers/amp.png b/public/providers/amp.png
new file mode 100644
index 0000000..6bacd05
Binary files /dev/null and b/public/providers/amp.png differ
diff --git a/public/providers/anthropic-m.png b/public/providers/anthropic-m.png
new file mode 100644
index 0000000..feea1ed
Binary files /dev/null and b/public/providers/anthropic-m.png differ
diff --git a/public/providers/anthropic.png b/public/providers/anthropic.png
new file mode 100644
index 0000000..dc58142
Binary files /dev/null and b/public/providers/anthropic.png differ
diff --git a/public/providers/antigravity.png b/public/providers/antigravity.png
new file mode 100644
index 0000000..6fe0fea
Binary files /dev/null and b/public/providers/antigravity.png differ
diff --git a/public/providers/assemblyai.png b/public/providers/assemblyai.png
new file mode 100644
index 0000000..d4367af
Binary files /dev/null and b/public/providers/assemblyai.png differ
diff --git a/public/providers/aws-polly.png b/public/providers/aws-polly.png
new file mode 100644
index 0000000..eef2d60
Binary files /dev/null and b/public/providers/aws-polly.png differ
diff --git a/public/providers/azure.png b/public/providers/azure.png
new file mode 100644
index 0000000..9cbd38d
Binary files /dev/null and b/public/providers/azure.png differ
diff --git a/public/providers/black-forest-labs.png b/public/providers/black-forest-labs.png
new file mode 100644
index 0000000..c42a313
Binary files /dev/null and b/public/providers/black-forest-labs.png differ
diff --git a/public/providers/blackbox.png b/public/providers/blackbox.png
new file mode 100644
index 0000000..3dc5d90
Binary files /dev/null and b/public/providers/blackbox.png differ
diff --git a/public/providers/brave-search.png b/public/providers/brave-search.png
new file mode 100644
index 0000000..a70acda
Binary files /dev/null and b/public/providers/brave-search.png differ
diff --git a/public/providers/byteplus.png b/public/providers/byteplus.png
new file mode 100644
index 0000000..cafbf6c
Binary files /dev/null and b/public/providers/byteplus.png differ
diff --git a/public/providers/cartesia.png b/public/providers/cartesia.png
new file mode 100644
index 0000000..45177c0
Binary files /dev/null and b/public/providers/cartesia.png differ
diff --git a/public/providers/cerebras.png b/public/providers/cerebras.png
new file mode 100644
index 0000000..0fbe159
Binary files /dev/null and b/public/providers/cerebras.png differ
diff --git a/public/providers/chutes.png b/public/providers/chutes.png
new file mode 100644
index 0000000..f39a6c2
Binary files /dev/null and b/public/providers/chutes.png differ
diff --git a/public/providers/claude.png b/public/providers/claude.png
new file mode 100644
index 0000000..c223ad4
Binary files /dev/null and b/public/providers/claude.png differ
diff --git a/public/providers/cline.png b/public/providers/cline.png
new file mode 100644
index 0000000..be24189
Binary files /dev/null and b/public/providers/cline.png differ
diff --git a/public/providers/clinepass.png b/public/providers/clinepass.png
new file mode 100644
index 0000000..be24189
Binary files /dev/null and b/public/providers/clinepass.png differ
diff --git a/public/providers/cloudflare-ai.png b/public/providers/cloudflare-ai.png
new file mode 100644
index 0000000..26cda8c
Binary files /dev/null and b/public/providers/cloudflare-ai.png differ
diff --git a/public/providers/codebuddy-cn.png b/public/providers/codebuddy-cn.png
new file mode 100644
index 0000000..eae3f4c
Binary files /dev/null and b/public/providers/codebuddy-cn.png differ
diff --git a/public/providers/codex.png b/public/providers/codex.png
new file mode 100644
index 0000000..41a9dd7
Binary files /dev/null and b/public/providers/codex.png differ
diff --git a/public/providers/cohere.png b/public/providers/cohere.png
new file mode 100644
index 0000000..47e7ab4
Binary files /dev/null and b/public/providers/cohere.png differ
diff --git a/public/providers/comfyui.png b/public/providers/comfyui.png
new file mode 100644
index 0000000..df8116b
Binary files /dev/null and b/public/providers/comfyui.png differ
diff --git a/public/providers/commandcode.png b/public/providers/commandcode.png
new file mode 100644
index 0000000..ed7c8c9
Binary files /dev/null and b/public/providers/commandcode.png differ
diff --git a/public/providers/continue.png b/public/providers/continue.png
new file mode 100644
index 0000000..f54685b
Binary files /dev/null and b/public/providers/continue.png differ
diff --git a/public/providers/copilot.png b/public/providers/copilot.png
new file mode 100644
index 0000000..9907963
Binary files /dev/null and b/public/providers/copilot.png differ
diff --git a/public/providers/coqui.png b/public/providers/coqui.png
new file mode 100644
index 0000000..6e2471e
Binary files /dev/null and b/public/providers/coqui.png differ
diff --git a/public/providers/cursor.png b/public/providers/cursor.png
new file mode 100644
index 0000000..ec02b07
Binary files /dev/null and b/public/providers/cursor.png differ
diff --git a/public/providers/deepgram.png b/public/providers/deepgram.png
new file mode 100644
index 0000000..dc58142
Binary files /dev/null and b/public/providers/deepgram.png differ
diff --git a/public/providers/deepseek-tui.png b/public/providers/deepseek-tui.png
new file mode 100644
index 0000000..fe56671
Binary files /dev/null and b/public/providers/deepseek-tui.png differ
diff --git a/public/providers/deepseek.png b/public/providers/deepseek.png
new file mode 100644
index 0000000..0603621
Binary files /dev/null and b/public/providers/deepseek.png differ
diff --git a/public/providers/droid.png b/public/providers/droid.png
new file mode 100644
index 0000000..28b8350
Binary files /dev/null and b/public/providers/droid.png differ
diff --git a/public/providers/edge-tts.png b/public/providers/edge-tts.png
new file mode 100644
index 0000000..8b1b333
Binary files /dev/null and b/public/providers/edge-tts.png differ
diff --git a/public/providers/elevenlabs.png b/public/providers/elevenlabs.png
new file mode 100644
index 0000000..c36dcfa
Binary files /dev/null and b/public/providers/elevenlabs.png differ
diff --git a/public/providers/exa.png b/public/providers/exa.png
new file mode 100644
index 0000000..03eff2a
Binary files /dev/null and b/public/providers/exa.png differ
diff --git a/public/providers/fal-ai.png b/public/providers/fal-ai.png
new file mode 100644
index 0000000..871855e
Binary files /dev/null and b/public/providers/fal-ai.png differ
diff --git a/public/providers/firecrawl.png b/public/providers/firecrawl.png
new file mode 100644
index 0000000..623235e
Binary files /dev/null and b/public/providers/firecrawl.png differ
diff --git a/public/providers/fireworks.png b/public/providers/fireworks.png
new file mode 100644
index 0000000..2295c0c
Binary files /dev/null and b/public/providers/fireworks.png differ
diff --git a/public/providers/gemini-cli.png b/public/providers/gemini-cli.png
new file mode 100644
index 0000000..5b72946
Binary files /dev/null and b/public/providers/gemini-cli.png differ
diff --git a/public/providers/gemini.png b/public/providers/gemini.png
new file mode 100644
index 0000000..9df2d30
Binary files /dev/null and b/public/providers/gemini.png differ
diff --git a/public/providers/github.png b/public/providers/github.png
new file mode 100644
index 0000000..9907963
Binary files /dev/null and b/public/providers/github.png differ
diff --git a/public/providers/glm-cn.png b/public/providers/glm-cn.png
new file mode 100644
index 0000000..cee2b24
Binary files /dev/null and b/public/providers/glm-cn.png differ
diff --git a/public/providers/glm.png b/public/providers/glm.png
new file mode 100644
index 0000000..cee2b24
Binary files /dev/null and b/public/providers/glm.png differ
diff --git a/public/providers/google-pse.png b/public/providers/google-pse.png
new file mode 100644
index 0000000..465357f
Binary files /dev/null and b/public/providers/google-pse.png differ
diff --git a/public/providers/google-tts.png b/public/providers/google-tts.png
new file mode 100644
index 0000000..68b7743
Binary files /dev/null and b/public/providers/google-tts.png differ
diff --git a/public/providers/grok-cli.png b/public/providers/grok-cli.png
new file mode 100644
index 0000000..ef9d7ab
Binary files /dev/null and b/public/providers/grok-cli.png differ
diff --git a/public/providers/grok-web.png b/public/providers/grok-web.png
new file mode 100644
index 0000000..ef9d7ab
Binary files /dev/null and b/public/providers/grok-web.png differ
diff --git a/public/providers/groq.png b/public/providers/groq.png
new file mode 100644
index 0000000..1773fb6
Binary files /dev/null and b/public/providers/groq.png differ
diff --git a/public/providers/hermes.png b/public/providers/hermes.png
new file mode 100644
index 0000000..d108d0c
Binary files /dev/null and b/public/providers/hermes.png differ
diff --git a/public/providers/huggingface.png b/public/providers/huggingface.png
new file mode 100644
index 0000000..9a36b8f
Binary files /dev/null and b/public/providers/huggingface.png differ
diff --git a/public/providers/hyperbolic.png b/public/providers/hyperbolic.png
new file mode 100644
index 0000000..0b4802d
Binary files /dev/null and b/public/providers/hyperbolic.png differ
diff --git a/public/providers/iflow.png b/public/providers/iflow.png
new file mode 100644
index 0000000..1bddeae
Binary files /dev/null and b/public/providers/iflow.png differ
diff --git a/public/providers/inworld.png b/public/providers/inworld.png
new file mode 100644
index 0000000..579a6c2
Binary files /dev/null and b/public/providers/inworld.png differ
diff --git a/public/providers/jcode.png b/public/providers/jcode.png
new file mode 100644
index 0000000..27e75a9
Binary files /dev/null and b/public/providers/jcode.png differ
diff --git a/public/providers/jina-ai.png b/public/providers/jina-ai.png
new file mode 100644
index 0000000..bb8ee31
Binary files /dev/null and b/public/providers/jina-ai.png differ
diff --git a/public/providers/jina-reader.png b/public/providers/jina-reader.png
new file mode 100644
index 0000000..388d65d
Binary files /dev/null and b/public/providers/jina-reader.png differ
diff --git a/public/providers/kilocode.png b/public/providers/kilocode.png
new file mode 100644
index 0000000..b1272cf
Binary files /dev/null and b/public/providers/kilocode.png differ
diff --git a/public/providers/kimchi.png b/public/providers/kimchi.png
new file mode 100644
index 0000000..8f32815
Binary files /dev/null and b/public/providers/kimchi.png differ
diff --git a/public/providers/kimchi.svg b/public/providers/kimchi.svg
new file mode 100644
index 0000000..cc019be
--- /dev/null
+++ b/public/providers/kimchi.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="104" height="104" viewBox="0 0 104 104">
+<circle cx="52" cy="52" r="52" fill="#FF521D"/>
+<path d="M68.4459 24.9438C69.8639 24.1762 71.6471 23.7178 73.4821 24.2163C73.8278 24.2966 74.1339 24.3916 74.4362 24.5024L75.9186 25.0464L75.5104 26.5727C75.3469 27.1827 75.202 27.723 75.0387 28.3325L74.6442 29.8042L73.1354 29.5972C73.0242 29.5819 72.9246 29.5753 72.8082 29.5747C72.2474 29.5865 71.7542 29.8645 71.2662 30.6772C70.8883 31.307 70.5939 32.1486 70.3815 33.1079C74.871 36.0331 77.8444 41.0994 77.8444 46.8638C77.8443 49.5292 77.2072 52.0505 76.0758 54.2798C71.5108 64.3996 54.1783 84.8815 23.4655 79.0083C21.8797 78.7048 20.9918 77.4165 20.902 76.1245C20.8141 74.8561 21.479 73.487 22.8981 72.8813C31.0698 69.394 35.5884 65.7091 38.5983 61.2329C41.6553 56.6866 43.2606 51.1907 45.3287 43.7251C46.7942 36.1645 53.4462 30.4547 61.4362 30.4546L61.8834 30.4604C62.4398 30.4755 62.9894 30.519 63.5309 30.5884C63.9515 29.7288 64.4424 28.8863 65.0211 28.0659L65.1745 27.8423C65.9623 26.731 67.1108 25.6667 68.4459 24.9438Z" fill="#18181A"/>
+</svg>
diff --git a/public/providers/kimi-coding.png b/public/providers/kimi-coding.png
new file mode 100644
index 0000000..422b7f9
Binary files /dev/null and b/public/providers/kimi-coding.png differ
diff --git a/public/providers/kimi.png b/public/providers/kimi.png
new file mode 100644
index 0000000..422b7f9
Binary files /dev/null and b/public/providers/kimi.png differ
diff --git a/public/providers/kiro.png b/public/providers/kiro.png
new file mode 100644
index 0000000..166c7c7
Binary files /dev/null and b/public/providers/kiro.png differ
diff --git a/public/providers/linkup.png b/public/providers/linkup.png
new file mode 100644
index 0000000..166b1a5
Binary files /dev/null and b/public/providers/linkup.png differ
diff --git a/public/providers/local-device.png b/public/providers/local-device.png
new file mode 100644
index 0000000..201cb10
Binary files /dev/null and b/public/providers/local-device.png differ
diff --git a/public/providers/mimo-free.png b/public/providers/mimo-free.png
new file mode 100644
index 0000000..3fbdd81
Binary files /dev/null and b/public/providers/mimo-free.png differ
diff --git a/public/providers/minimax-cn.png b/public/providers/minimax-cn.png
new file mode 100644
index 0000000..a8b9bf7
Binary files /dev/null and b/public/providers/minimax-cn.png differ
diff --git a/public/providers/minimax.png b/public/providers/minimax.png
new file mode 100644
index 0000000..a8b9bf7
Binary files /dev/null and b/public/providers/minimax.png differ
diff --git a/public/providers/mistral.png b/public/providers/mistral.png
new file mode 100644
index 0000000..4fcbb0c
Binary files /dev/null and b/public/providers/mistral.png differ
diff --git a/public/providers/nanobanana.png b/public/providers/nanobanana.png
new file mode 100644
index 0000000..9df2d30
Binary files /dev/null and b/public/providers/nanobanana.png differ
diff --git a/public/providers/nebius.png b/public/providers/nebius.png
new file mode 100644
index 0000000..c4ebd3c
Binary files /dev/null and b/public/providers/nebius.png differ
diff --git a/public/providers/nvidia.png b/public/providers/nvidia.png
new file mode 100644
index 0000000..d115e36
Binary files /dev/null and b/public/providers/nvidia.png differ
diff --git a/public/providers/oai-cc.png b/public/providers/oai-cc.png
new file mode 100644
index 0000000..56a7a3e
Binary files /dev/null and b/public/providers/oai-cc.png differ
diff --git a/public/providers/oai-r.png b/public/providers/oai-r.png
new file mode 100644
index 0000000..0dbd61c
Binary files /dev/null and b/public/providers/oai-r.png differ
diff --git a/public/providers/ollama-local.png b/public/providers/ollama-local.png
new file mode 100644
index 0000000..302b1b1
Binary files /dev/null and b/public/providers/ollama-local.png differ
diff --git a/public/providers/ollama.png b/public/providers/ollama.png
new file mode 100644
index 0000000..302b1b1
Binary files /dev/null and b/public/providers/ollama.png differ
diff --git a/public/providers/openai.png b/public/providers/openai.png
new file mode 100644
index 0000000..d4367af
Binary files /dev/null and b/public/providers/openai.png differ
diff --git a/public/providers/openclaw.png b/public/providers/openclaw.png
new file mode 100644
index 0000000..7ef77ac
Binary files /dev/null and b/public/providers/openclaw.png differ
diff --git a/public/providers/opencode-go.png b/public/providers/opencode-go.png
new file mode 100644
index 0000000..2e709e1
Binary files /dev/null and b/public/providers/opencode-go.png differ
diff --git a/public/providers/opencode.png b/public/providers/opencode.png
new file mode 100644
index 0000000..2e709e1
Binary files /dev/null and b/public/providers/opencode.png differ
diff --git a/public/providers/openrouter.png b/public/providers/openrouter.png
new file mode 100644
index 0000000..0b4802d
Binary files /dev/null and b/public/providers/openrouter.png differ
diff --git a/public/providers/perplexity-web.png b/public/providers/perplexity-web.png
new file mode 100644
index 0000000..0b5851e
Binary files /dev/null and b/public/providers/perplexity-web.png differ
diff --git a/public/providers/perplexity.png b/public/providers/perplexity.png
new file mode 100644
index 0000000..0b5851e
Binary files /dev/null and b/public/providers/perplexity.png differ
diff --git a/public/providers/playht.png b/public/providers/playht.png
new file mode 100644
index 0000000..1807e9a
Binary files /dev/null and b/public/providers/playht.png differ
diff --git a/public/providers/qoder.png b/public/providers/qoder.png
new file mode 100644
index 0000000..41e81c1
Binary files /dev/null and b/public/providers/qoder.png differ
diff --git a/public/providers/qwen.png b/public/providers/qwen.png
new file mode 100644
index 0000000..0fc2d1b
Binary files /dev/null and b/public/providers/qwen.png differ
diff --git a/public/providers/recraft.png b/public/providers/recraft.png
new file mode 100644
index 0000000..3ed1285
Binary files /dev/null and b/public/providers/recraft.png differ
diff --git a/public/providers/roo.png b/public/providers/roo.png
new file mode 100644
index 0000000..0503577
Binary files /dev/null and b/public/providers/roo.png differ
diff --git a/public/providers/runwayml.png b/public/providers/runwayml.png
new file mode 100644
index 0000000..8f53a14
Binary files /dev/null and b/public/providers/runwayml.png differ
diff --git a/public/providers/sdwebui.png b/public/providers/sdwebui.png
new file mode 100644
index 0000000..89e9ae2
Binary files /dev/null and b/public/providers/sdwebui.png differ
diff --git a/public/providers/searchapi.png b/public/providers/searchapi.png
new file mode 100644
index 0000000..23630ec
Binary files /dev/null and b/public/providers/searchapi.png differ
diff --git a/public/providers/searxng.png b/public/providers/searxng.png
new file mode 100644
index 0000000..3487f02
Binary files /dev/null and b/public/providers/searxng.png differ
diff --git a/public/providers/serper.png b/public/providers/serper.png
new file mode 100644
index 0000000..6a8063c
Binary files /dev/null and b/public/providers/serper.png differ
diff --git a/public/providers/siliconflow.png b/public/providers/siliconflow.png
new file mode 100644
index 0000000..d599df2
Binary files /dev/null and b/public/providers/siliconflow.png differ
diff --git a/public/providers/stability-ai.png b/public/providers/stability-ai.png
new file mode 100644
index 0000000..31cf71c
Binary files /dev/null and b/public/providers/stability-ai.png differ
diff --git a/public/providers/tavily.png b/public/providers/tavily.png
new file mode 100644
index 0000000..b51f3c5
Binary files /dev/null and b/public/providers/tavily.png differ
diff --git a/public/providers/together.png b/public/providers/together.png
new file mode 100644
index 0000000..9acc901
Binary files /dev/null and b/public/providers/together.png differ
diff --git a/public/providers/topaz.png b/public/providers/topaz.png
new file mode 100644
index 0000000..3f86008
Binary files /dev/null and b/public/providers/topaz.png differ
diff --git a/public/providers/tortoise.png b/public/providers/tortoise.png
new file mode 100644
index 0000000..70e93fc
Binary files /dev/null and b/public/providers/tortoise.png differ
diff --git a/public/providers/vertex-partner.png b/public/providers/vertex-partner.png
new file mode 100644
index 0000000..892af45
Binary files /dev/null and b/public/providers/vertex-partner.png differ
diff --git a/public/providers/vertex.png b/public/providers/vertex.png
new file mode 100644
index 0000000..892af45
Binary files /dev/null and b/public/providers/vertex.png differ
diff --git a/public/providers/volcengine-ark.png b/public/providers/volcengine-ark.png
new file mode 100644
index 0000000..e452a09
Binary files /dev/null and b/public/providers/volcengine-ark.png differ
diff --git a/public/providers/voyage-ai.png b/public/providers/voyage-ai.png
new file mode 100644
index 0000000..72c4196
Binary files /dev/null and b/public/providers/voyage-ai.png differ
diff --git a/public/providers/xai.png b/public/providers/xai.png
new file mode 100644
index 0000000..ef9d7ab
Binary files /dev/null and b/public/providers/xai.png differ
diff --git a/public/providers/xiaomi-mimo.png b/public/providers/xiaomi-mimo.png
new file mode 100644
index 0000000..1752aa9
Binary files /dev/null and b/public/providers/xiaomi-mimo.png differ
diff --git a/public/providers/xiaomi-tokenplan.png b/public/providers/xiaomi-tokenplan.png
new file mode 100644
index 0000000..1752aa9
Binary files /dev/null and b/public/providers/xiaomi-tokenplan.png differ
diff --git a/public/providers/youcom.png b/public/providers/youcom.png
new file mode 100644
index 0000000..4f7d429
Binary files /dev/null and b/public/providers/youcom.png differ
diff --git a/public/sw.js b/public/sw.js
new file mode 100644
index 0000000..4c4de80
--- /dev/null
+++ b/public/sw.js
@@ -0,0 +1,22 @@
+self.addEventListener('push', function (event) {
+  if (event.data) {
+    const data = event.data.json()
+    const options = {
+      body: data.body,
+      icon: data.icon || '/icons/icon-192.svg',
+      badge: '/icons/icon-192.svg',
+      vibrate: [100, 50, 100],
+      data: {
+        dateOfArrival: Date.now(),
+        primaryKey: '2',
+      },
+    }
+    event.waitUntil(self.registration.showNotification(data.title, options))
+  }
+})
+
+self.addEventListener('notificationclick', function (event) {
+  console.log('Notification click received.')
+  event.notification.close()
+  event.waitUntil(clients.openWindow('/'))
+})
diff --git a/public/vercel.svg b/public/vercel.svg
new file mode 100644
index 0000000..7705396
--- /dev/null
+++ b/public/vercel.svg
@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>
\ No newline at end of file
diff --git a/public/window.svg b/public/window.svg
new file mode 100644
index 0000000..b2b2a44
--- /dev/null
+++ b/public/window.svg
@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>
\ No newline at end of file
diff --git a/scripts/injectDisplayToRegistry.mjs b/scripts/injectDisplayToRegistry.mjs
new file mode 100644
index 0000000..1da6be5
--- /dev/null
+++ b/scripts/injectDisplayToRegistry.mjs
@@ -0,0 +1,223 @@
+/**
+ * Script: đọc providersDisplay.js + providers.js, inject display+category+uiAlias+extra vào từng registry file.
+ * Chạy: node scripts/injectDisplayToRegistry.mjs
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+const REGISTRY_DIR = path.join(ROOT, "open-sse/providers/registry");
+
+// ── 1. Build DISPLAY map từ providersDisplay.js (parse thủ công để không cần import) ──
+// Đọc file, eval trong sandbox đơn giản
+const displaySrc = fs.readFileSync(path.join(ROOT, "src/shared/constants/providersDisplay.js"), "utf8");
+const RISK_NOTICE = "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.";
+// strip export keywords + inject RISK_NOTICE as param so no redeclaration
+const displayBody = displaySrc
+  .replace(/^export const /gm, "const ")
+  .replace(/^export function /gm, "function ")
+  .replace(/^const RISK_NOTICE\s*=.*$/m, ""); // remove redeclaration
+// eslint-disable-next-line no-new-func
+const getDisplay = new Function("RISK_NOTICE", `${displayBody}; return PROVIDER_DISPLAY;`);
+const DISPLAY = getDisplay(RISK_NOTICE);
+
+// ── 2. Build CATEGORY + EXTRA map từ providers.js ──
+// Map: providerId → { category, uiAlias, extra fields }
+const CATEGORY_MAP = {};
+
+// Đọc providers.js source để extract thủ công từng dòng
+const provSrc = fs.readFileSync(path.join(ROOT, "src/shared/constants/providers.js"), "utf8");
+
+// Detect category blocks
+const CATEGORIES = {
+  free: /export const FREE_PROVIDERS\s*=\s*\{([\s\S]*?)\n\};/,
+  freeTier: /export const FREE_TIER_PROVIDERS\s*=\s*\{([\s\S]*?)\n\};/,
+  oauth: /export const OAUTH_PROVIDERS\s*=\s*\{([\s\S]*?)\n\};/,
+  apikey: /export const APIKEY_PROVIDERS\s*=\s*\{([\s\S]*?)\n\};/,
+  webCookie: /export const WEB_COOKIE_PROVIDERS\s*=\s*\{([\s\S]*?)\n\};/,
+};
+
+// Extract provider ids + uiAlias + extra fields per category
+// Parse dòng dạng: "  openai: { ...D("openai"), id: "openai", alias: "openai", ... }"
+const ENTRY_RE = /^\s{2}["']?([\w-]+)["']?\s*:\s*\{[^}]*?id:\s*["']([\w-]+)["'][^}]*?alias:\s*["']([\w-]+)["']([\s\S]*?)(?=\n\s{2}["']?[\w-]|\n\};)/gm;
+
+// Extra fields cần lấy từ providers.js (không lấy display, id, alias vì đã có nguồn khác)
+const EXTRA_FIELDS = [
+  "thinkingConfig",
+  "regions",
+  "defaultRegion",
+  "hasProviderSpecificData",
+  "authType",
+  "authHint",
+  "passthroughModels",
+  "noAuth",
+  "hiddenKinds",
+  "hasOAuth",
+  "authModes",
+];
+
+// THINKING_CONFIG values để inline
+const THINKING_CONFIG = {
+  extended: { options: ["auto", "on", "off"], defaultMode: "auto", defaultBudgetTokens: 10000 },
+  effort: { options: ["auto", "none", "low", "medium", "high"], defaultMode: "auto" },
+};
+
+// Parse thủ công từng category block
+for (const [cat, re] of Object.entries(CATEGORIES)) {
+  const match = provSrc.match(re);
+  if (!match) continue;
+  const block = match[1];
+
+  // Tìm tất cả entry lines (không comment)
+  const lines = block.split("\n").filter(l => l.trim() && !l.trim().startsWith("//"));
+  for (const line of lines) {
+    // Extract id từ id: "xxx"
+    const idM = line.match(/\bid:\s*["']([\w-]+)["']/);
+    // Extract uiAlias từ alias: "xxx"
+    const aliasM = line.match(/\balias:\s*["']([\w-]+)["']/);
+    if (!idM) continue;
+    const id = idM[1];
+    const uiAlias = aliasM ? aliasM[1] : id;
+
+    const extra = {};
+
+    // thinkingConfig
+    if (line.includes("THINKING_CONFIG.effort")) extra.thinkingConfig = THINKING_CONFIG.effort;
+    else if (line.includes("THINKING_CONFIG.extended")) extra.thinkingConfig = THINKING_CONFIG.extended;
+
+    // hasProviderSpecificData
+    if (line.includes("hasProviderSpecificData: true")) extra.hasProviderSpecificData = true;
+
+    // hasOAuth
+    if (line.includes("hasOAuth: true")) extra.hasOAuth = true;
+
+    // authModes
+    const authModesM = line.match(/authModes:\s*(\[[^\]]+\])/);
+    if (authModesM) {
+      try { extra.authModes = JSON.parse(authModesM[1].replace(/'/g, '"')); } catch {}
+    }
+
+    // authType (webCookie)
+    const authTypeM = line.match(/authType:\s*["']([\w-]+)["']/);
+    if (authTypeM) extra.authType = authTypeM[1];
+
+    // authHint
+    const authHintM = line.match(/authHint:\s*["']([^"']+)["']/);
+    if (authHintM) extra.authHint = authHintM[1];
+
+    // noAuth
+    if (line.includes("noAuth: true")) extra.noAuth = true;
+
+    // passthroughModels
+    if (line.includes("passthroughModels: true")) extra.passthroughModels = true;
+
+    // hiddenKinds
+    const hiddenKindsM = line.match(/hiddenKinds:\s*(\[[^\]]+\])/);
+    if (hiddenKindsM) {
+      try { extra.hiddenKinds = JSON.parse(hiddenKindsM[1].replace(/'/g, '"')); } catch {}
+    }
+
+    // regions (xiaomi-tokenplan)
+    const regionsM = line.match(/regions:\s*(\[[\s\S]*?\])/);
+    if (regionsM) {
+      try { extra.regions = JSON.parse(regionsM[1].replace(/'/g, '"')); } catch {}
+    }
+    const defRegionM = line.match(/defaultRegion:\s*["']([\w-]+)["']/);
+    if (defRegionM) extra.defaultRegion = defRegionM[1];
+
+    CATEGORY_MAP[id] = { category: cat, uiAlias, extra };
+  }
+}
+
+// ── 3. Inject vào từng registry file ──
+const registryFiles = fs.readdirSync(REGISTRY_DIR)
+  .filter(f => f.endsWith(".js") && f !== "index.js")
+  .map(f => f.replace(".js", ""));
+
+let injected = 0;
+let skipped = 0;
+const results = [];
+
+for (const id of registryFiles) {
+  const filePath = path.join(REGISTRY_DIR, `${id}.js`);
+  let src = fs.readFileSync(filePath, "utf8");
+
+  // Bỏ qua nếu đã có display field
+  if (src.includes("display:")) {
+    skipped++;
+    results.push(`⏭️  ${id} (already has display)`);
+    continue;
+  }
+
+  const display = DISPLAY[id];
+  const catInfo = CATEGORY_MAP[id];
+
+  if (!display && !catInfo) {
+    skipped++;
+    results.push(`⚠️  ${id} (no display + no category data)`);
+    continue;
+  }
+
+  // Build display block
+  let displayBlock = "";
+  if (display) {
+    const d = { ...display };
+    // Thay RISK_NOTICE string về const reference khi serialize
+    const RISK = RISK_NOTICE;
+    const displayJson = JSON.stringify(d, null, 4)
+      .replace(new RegExp(JSON.stringify(RISK).slice(1, -1), "g"), "RISK_NOTICE");
+
+    displayBlock = `  display: ${displayJson.replace(/^/gm, "  ").trimStart()},\n`;
+  }
+
+  // Build category line
+  const categoryLine = catInfo ? `  category: "${catInfo.category}",\n` : "";
+
+  // Build uiAlias line (chỉ khi khác với alias routing)
+  let uiAliasLine = "";
+  if (catInfo && catInfo.uiAlias && catInfo.uiAlias !== id) {
+    uiAliasLine = `  uiAlias: "${catInfo.uiAlias}",\n`;
+  }
+
+  // Build extra fields
+  let extraBlock = "";
+  if (catInfo && Object.keys(catInfo.extra).length > 0) {
+    for (const [k, v] of Object.entries(catInfo.extra)) {
+      extraBlock += `  ${k}: ${JSON.stringify(v)},\n`;
+    }
+  }
+
+  // Inject SAU dòng "alias:" hoặc cuối object (trước closing "};")
+  const insertBlock = displayBlock + categoryLine + uiAliasLine + extraBlock;
+
+  if (!insertBlock.trim()) {
+    skipped++;
+    results.push(`⏭️  ${id} (nothing to inject)`);
+    continue;
+  }
+
+  // Tìm vị trí sau field "alias:" để inject
+  const aliasLineRe = /^(\s+"?alias"?\s*:\s*["'][^"']+["'],?\n)/m;
+  if (aliasLineRe.test(src)) {
+    src = src.replace(aliasLineRe, `$1${insertBlock}`);
+  } else {
+    // Fallback: inject trước closing "};"
+    src = src.replace(/^(\}\s*;\s*)$/m, `${insertBlock}$1`);
+  }
+
+  // Thêm RISK_NOTICE import nếu cần
+  if (insertBlock.includes("RISK_NOTICE") && !src.includes("RISK_NOTICE")) {
+    const riskLine = `const RISK_NOTICE = ${JSON.stringify(RISK_NOTICE)};\n\n`;
+    src = riskLine + src;
+  }
+
+  fs.writeFileSync(filePath, src);
+  injected++;
+  results.push(`✅ ${id}`);
+}
+
+console.log(`\n📦 Inject display+category vào registry files:`);
+for (const r of results) console.log(` ${r}`);
+console.log(`\n✅ Injected: ${injected}  |  ⏭️ Skipped: ${skipped}`);
diff --git a/scripts/migrate-registry.mjs b/scripts/migrate-registry.mjs
new file mode 100644
index 0000000..ba1d0e4
--- /dev/null
+++ b/scripts/migrate-registry.mjs
@@ -0,0 +1,271 @@
+/**
+ * migrate-registry.mjs
+ * Migrates all registry files to Model-A schema:
+ *   - models[] = ALL models (chat + media), field `kind` (default "llm")
+ *   - media wrapper removed → fields promoted top-level
+ *   - *Config.models removed (data merged into models[])
+ *   - format: terse, consistent indent
+ *
+ * Run: node --experimental-vm-modules migrate-registry.mjs [--dry]
+ */
+import { readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REGISTRY_DIR = __dirname; // script lives in registry/
+const DRY = process.argv.includes("--dry");
+
+// *Config.models field → kind value
+const CFG_KIND = {
+  ttsConfig:          "tts",
+  sttConfig:          "stt",
+  embeddingConfig:    "embedding",
+  imageConfig:        "image",
+  imageToTextConfig:  "imageToText",
+  videoConfig:        "video",
+  musicConfig:        "music",
+};
+
+// Fields in *Config that are NOT models (keep on config)
+const MODEL_ONLY_KEY = "models";
+
+// Top-level registry fields that are NOT media-config (don't flatten these from media)
+// serviceKinds + *Config + searchViaChat + mediaConfig + passthroughModels are media fields
+// Everything else is already top-level
+const MEDIA_WHITELIST = new Set([
+  "serviceKinds",
+  "ttsConfig", "sttConfig", "embeddingConfig",
+  "imageConfig", "imageToTextConfig", "videoConfig", "musicConfig",
+  "searchViaChat", "searchConfig", "fetchConfig",
+  "modelsFetcher", "hasProviderSpecificData", "passthroughModels",
+  "mediaPriority", "hiddenKinds",
+]);
+
+function migrateEntry(entry, filename) {
+  const out = {};
+
+  // 1. Top-level identity/transport fields (preserve order)
+  const TRANSPORT_KEYS = ["id", "alias", "aliases", "uiAlias", "display", "category",
+    "authType", "authHint", "authModes", "hasOAuth", "noAuth",
+    "hasProviderSpecificData", "thinkingConfig", "hiddenKinds",
+    "regions", "defaultRegion", "passthroughModels", "transport"];
+  for (const k of TRANSPORT_KEYS) {
+    if (entry[k] !== undefined) out[k] = entry[k];
+  }
+
+  // 2. Collect existing models[] (convert type→kind, skip if kind already set)
+  const existingModels = (entry.models || []).map(m => {
+    const { type, ...rest } = m;
+    const kind = m.kind ?? (type && type !== "llm" ? type : undefined);
+    return kind ? { ...rest, kind } : rest;
+  });
+  const existingIds = new Set(existingModels.map(m => m.id));
+
+  // 3. Extract models from *Config.models (merge into models[])
+  const mediaModels = [];
+  const media = entry.media || {};
+  for (const [cfgKey, kind] of Object.entries(CFG_KIND)) {
+    const cfg = media[cfgKey];
+    if (!cfg?.models) continue;
+    for (const m of cfg.models) {
+      // Check if same id+kind combo already exists to avoid true duplicates
+      const dup = existingModels.find(x => x.id === m.id && (x.kind ?? "llm") === kind);
+      if (dup) continue;
+      const { ...mClean } = m;
+      mediaModels.push({ ...mClean, kind });
+    }
+  }
+
+  // 4. Merge models (existing first, then media additions)
+  const allModels = [...existingModels, ...mediaModels];
+  // Only include models key if non-empty or explicitly defined
+  if (allModels.length > 0 || entry.models !== undefined) {
+    out.models = allModels;
+  }
+
+  // 5. Flatten media fields (without .models sub-arrays)
+  for (const [k, v] of Object.entries(media)) {
+    if (!MEDIA_WHITELIST.has(k)) continue;
+    if (CFG_KIND[k]) {
+      // Strip .models from config, keep rest
+      const { models: _m, ...cfgRest } = (v || {});
+      if (Object.keys(cfgRest).length > 0) out[k] = cfgRest;
+    } else {
+      out[k] = v;
+    }
+  }
+
+  // 6. Other top-level fields not in TRANSPORT_KEYS and not media (e.g. features, oauth, usage in transport)
+  const SKIP = new Set([...TRANSPORT_KEYS, "models", "media", ...Object.keys(CFG_KIND),
+    "serviceKinds", "searchViaChat", "searchConfig", "fetchConfig",
+    "modelsFetcher", "passthroughModels", "mediaPriority"]);
+  for (const [k, v] of Object.entries(entry)) {
+    if (!SKIP.has(k)) out[k] = v;
+  }
+
+  return out;
+}
+
+// Format a registry entry as clean JS (no JSON.stringify — write proper ES module)
+function formatValue(v, indent = 0) {
+  const pad = "  ".repeat(indent);
+  const pad1 = "  ".repeat(indent + 1);
+
+  if (v === null || v === undefined) return String(v);
+  if (typeof v === "boolean" || typeof v === "number") return String(v);
+  if (typeof v === "string") return JSON.stringify(v);
+
+  if (Array.isArray(v)) {
+    if (v.length === 0) return "[]";
+    // Model arrays: 1 model per line (compact inline object)
+    const items = v.map(item => {
+      if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+        return `${pad1}${formatInlineObject(item)}`;
+      }
+      return `${pad1}${formatValue(item, indent + 1)}`;
+    });
+    return `[\n${items.join(",\n")},\n${pad}]`;
+  }
+
+  if (typeof v === "object") {
+    const keys = Object.keys(v);
+    if (keys.length === 0) return "{}";
+    const lines = keys.map(k => {
+      const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k) ? k : JSON.stringify(k);
+      return `${pad1}${key}: ${formatValue(v[k], indent + 1)}`;
+    });
+    return `{\n${lines.join(",\n")},\n${pad}}`;
+  }
+
+  return JSON.stringify(v);
+}
+
+// Inline compact object: { id: "x", name: "y", kind: "tts", dimensions: 1536 }
+function formatInlineObject(obj) {
+  const parts = Object.entries(obj).map(([k, v]) => {
+    const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k) ? k : JSON.stringify(k);
+    return `${key}: ${JSON.stringify(v)}`;
+  });
+  return `{ ${parts.join(", ")} }`;
+}
+
+// Config objects (ttsConfig etc) — inline single line if short, else multi-line
+function formatConfig(cfg) {
+  const line = `{ ${Object.entries(cfg).map(([k,v])=>`${k}: ${JSON.stringify(v)}`).join(", ")} }`;
+  if (line.length <= 120) return line;
+  const pad1 = "  ".repeat(2);
+  const lines = Object.entries(cfg).map(([k,v]) => `${pad1}${k}: ${JSON.stringify(v)}`);
+  return `{\n${lines.join(",\n")},\n  }`;
+}
+
+// Top-level registry entry formatter
+function formatEntry(entry, imports = "") {
+  const lines = [];
+  if (imports) lines.push(imports, "");
+  lines.push("export default {");
+
+  const TOP_ORDER = [
+    "id", "alias", "aliases", "uiAlias", "display", "category",
+    "authType", "authHint", "authModes", "hasOAuth", "noAuth",
+    "hasProviderSpecificData", "thinkingConfig", "hiddenKinds",
+    "regions", "defaultRegion", "transport",
+    "models",
+    // media fields
+    "serviceKinds",
+    "ttsConfig", "sttConfig", "embeddingConfig",
+    "imageConfig", "imageToTextConfig", "videoConfig", "musicConfig",
+    "searchViaChat", "searchConfig", "fetchConfig", "modelsFetcher",
+    "passthroughModels", "mediaPriority",
+    // other
+    "oauth", "features",
+  ];
+
+  const emitted = new Set();
+
+  function emitKey(k) {
+    if (!(k in entry) || emitted.has(k)) return;
+    emitted.add(k);
+    const v = entry[k];
+    const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k) ? k : JSON.stringify(k);
+
+    // Config objects (xConfig) — special inline format
+    if (CFG_KIND[k] || k === "searchViaChat" || k === "searchConfig" || k === "fetchConfig" || k === "modelsFetcher") {
+      lines.push(`  ${key}: ${formatConfig(v)},`);
+      return;
+    }
+
+    // models[] — terse per-line
+    if (k === "models" && Array.isArray(v)) {
+      if (v.length === 0) { lines.push(`  models: [],`); return; }
+      lines.push(`  models: [`);
+      for (const m of v) lines.push(`    ${formatInlineObject(m)},`);
+      lines.push(`  ],`);
+      return;
+    }
+
+    // serviceKinds — inline array
+    if (k === "serviceKinds") {
+      lines.push(`  serviceKinds: ${JSON.stringify(v)},`);
+      return;
+    }
+
+    // display — multi-line
+    if (k === "display") {
+      lines.push(`  display: ${formatValue(v, 1)},`);
+      return;
+    }
+
+    // transport — multi-line
+    if (k === "transport") {
+      lines.push(`  transport: ${formatValue(v, 1)},`);
+      return;
+    }
+
+    // Everything else
+    lines.push(`  ${key}: ${formatValue(v, 1)},`);
+  }
+
+  for (const k of TOP_ORDER) emitKey(k);
+  // Emit any remaining keys not in TOP_ORDER
+  for (const k of Object.keys(entry)) emitKey(k);
+
+  lines.push("};");
+  return lines.join("\n") + "\n";
+}
+
+// --- Main ---
+const files = readdirSync(REGISTRY_DIR).filter(f => f.endsWith(".js") && f !== "index.js");
+let count = 0;
+
+for (const file of files) {
+  const path = join(REGISTRY_DIR, file);
+  const src = readFileSync(path, "utf8");
+
+  // Extract import lines (for files that import shared constants)
+  const importLines = src.split("\n").filter(l => l.startsWith("import "));
+  const importSrc = importLines.join("\n");
+
+  // Dynamic import to get entry
+  let entry;
+  try {
+    const mod = await import(`${join(REGISTRY_DIR, file)}?t=${Date.now()}`);
+    entry = mod.default;
+  } catch (e) {
+    console.error(`SKIP ${file}: ${e.message}`);
+    continue;
+  }
+
+  const migrated = migrateEntry(entry, file);
+  const output = formatEntry(migrated, importSrc);
+
+  if (DRY) {
+    console.log(`\n=== ${file} ===\n${output}`);
+  } else {
+    writeFileSync(path, output, "utf8");
+    count++;
+  }
+}
+
+console.log(DRY ? `[DRY] Would migrate ${files.length} files` : `✅ Migrated ${count} files`);
diff --git a/scripts/test-combo-autoswitch.mjs b/scripts/test-combo-autoswitch.mjs
new file mode 100644
index 0000000..358ebcf
--- /dev/null
+++ b/scripts/test-combo-autoswitch.mjs
@@ -0,0 +1,84 @@
+// Live test: combo capacity display + auto-switch routing.
+// Sends text / image / search requests to a combo and reports which member ran.
+//   node scripts/test-combo-autoswitch.mjs
+const BASE = process.env.BASE_URL || "http://localhost:20127";
+const KEY = process.env.API_KEY || "sk-6581be4f05a82b6b-uxy6jn-c8190ea8";
+const COMBO = process.env.COMBO || "haha";
+
+// 16x16 PNG (valid image so vision providers accept it).
+const PNG = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAFklEQVR4nGO4I2JDEmIY1TCqYfhqAAAeBCwQ8YdREQAAAABJRU5ErkJggg==";
+
+function memberFromModel(model) {
+  // Response model usually = upstream id; map back to a combo member by substring.
+  return model || "(none)";
+}
+
+async function send(label, content, extra = {}) {
+  const body = {
+    model: COMBO,
+    stream: false,
+    max_tokens: 64,
+    messages: [{ role: "user", content }],
+    ...extra,
+  };
+  const t0 = Date.now();
+  let res, json, text;
+  try {
+    res = await fetch(`${BASE}/v1/chat/completions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${KEY}` },
+      body: JSON.stringify(body),
+    });
+    text = await res.text();
+    try { json = JSON.parse(text); } catch { /* keep text */ }
+  } catch (e) {
+    console.log(`\n[${label}] NETWORK ERROR: ${e.message}`);
+    return;
+  }
+  const ms = Date.now() - t0;
+  const model = json?.model || "(no model field)";
+  const ok = res.ok;
+  const snippet = (json?.choices?.[0]?.message?.content || text || "").slice(0, 80).replace(/\n/g, " ");
+  console.log(`\n[${label}] ${ok ? "OK" : "FAIL"} ${res.status} (${ms}ms)`);
+  console.log(`  model executed: ${memberFromModel(model)}`);
+  if (!ok) console.log(`  error: ${(json?.error?.message || text || "").slice(0, 160)}`);
+  else console.log(`  reply: ${snippet}`);
+}
+
+async function showCaps() {
+  try {
+    const r = await fetch(`${BASE}/api/models`, { headers: { Authorization: `Bearer ${KEY}` } });
+    if (!r.ok) { console.log("(/api/models needs dashboard auth, skipping caps table)"); return; }
+    const { models } = await r.json();
+    const map = {};
+    for (const m of models || []) if (m.caps) map[m.fullModel] = m.caps;
+    console.log("Capacity of combo members (vision/search):");
+    for (const m of (process.env.MEMBERS || "").split(",").filter(Boolean)) {
+      const c = map[m] || {};
+      console.log(`  ${m}: vision=${!!c.vision} search=${!!c.search}`);
+    }
+  } catch { /* ignore */ }
+}
+
+(async () => {
+  console.log(`Testing combo "${COMBO}" @ ${BASE}\n${"=".repeat(50)}`);
+  await showCaps();
+
+  // 1. Text-only: round-robin order (no capability requirement).
+  await send("text-only #1", "Say hello in one word.");
+  await send("text-only #2", "Say hi in one word.");
+
+  // 2. Image: should auto-switch to a vision-capable member.
+  await send("image (needs vision)", [
+    { type: "text", text: "What color is this image? One word." },
+    { type: "image_url", image_url: { url: PNG } },
+  ]);
+
+  // 3. Search: should auto-switch to a search-capable member.
+  // Claude built-in web search requires a versioned tool type.
+  await send("search (needs search)", "What is the latest news today?", {
+    tools: [{ type: "web_search_20250305", name: "web_search" }],
+  });
+
+  console.log(`\n${"=".repeat(50)}\nDone. Compare 'model executed' across cases to verify auto-switch.`);
+})();
diff --git a/scripts/translate-readme.js b/scripts/translate-readme.js
new file mode 100755
index 0000000..af6a11a
--- /dev/null
+++ b/scripts/translate-readme.js
@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// ============ CONFIGURATION ============
+const API_ENDPOINT = process.env.GLM_API_ENDPOINT || 'https://api.z.ai/api/anthropic/v1/messages';
+const API_MODEL = process.env.GLM_API_MODEL || 'glm-5';
+const API_KEY = process.env.GLM_API_KEY;
+const MAX_TOKENS = parseInt(process.env.GLM_MAX_TOKENS || '32000');
+const TEMPERATURE = parseFloat(process.env.GLM_TEMPERATURE || '0.3');
+const BATCH_SIZE = parseInt(process.env.TRANSLATE_BATCH_SIZE || '2'); // Number of languages to translate in parallel
+
+const SUPPORTED_LANGUAGES = {
+  vi: 'Vietnamese',
+  'zh-CN': 'Simplified Chinese'
+};
+
+// ============ VALIDATION ============
+if (!API_KEY) {
+  console.error('Error: GLM_API_KEY environment variable not set');
+  process.exit(1);
+}
+
+const targetLangs = process.argv.slice(2);
+if (targetLangs.length === 0) {
+  console.error('Usage: node translate-readme.js <lang1> [lang2] ...');
+  console.error(`Supported languages: ${Object.keys(SUPPORTED_LANGUAGES).join(', ')}`);
+  process.exit(1);
+}
+
+for (const lang of targetLangs) {
+  if (!SUPPORTED_LANGUAGES[lang]) {
+    console.error(`Unsupported language: ${lang}`);
+    process.exit(1);
+  }
+}
+
+// ============ TRANSLATION FUNCTION ============
+async function translateToLanguage(readmeContent, targetLang) {
+  const langName = SUPPORTED_LANGUAGES[targetLang];
+  console.log(`\n[${targetLang}] Translating to ${langName}...`);
+  console.log(`[${targetLang}] README size: ${readmeContent.length} characters`);
+  
+  const prompt = `Translate this entire Markdown document to ${langName}.
+
+CRITICAL RULES:
+- Keep ALL markdown syntax EXACTLY as is (##, \`\`\`, -, *, |, tables, etc.)
+- Do NOT modify code blocks, ASCII diagrams, or code fences
+- Only translate human-readable text content
+- Keep all URLs, links, and technical terms unchanged
+
+${readmeContent}`;
+  
+  const response = await fetch(API_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': API_KEY,
+      'anthropic-version': '2023-06-01'
+    },
+    body: JSON.stringify({
+      model: API_MODEL,
+      messages: [{ role: 'user', content: prompt }],
+      temperature: TEMPERATURE,
+      max_tokens: MAX_TOKENS,
+      stream: true
+    })
+  });
+  
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`[${targetLang}] API Error: ${response.status} ${error}`);
+  }
+  
+  console.log(`[${targetLang}] Receiving translation stream...`);
+  
+  let translatedContent = '';
+  let chunkCount = 0;
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    
+    const chunk = decoder.decode(value, { stream: true });
+    const lines = chunk.split('\n');
+    
+    for (const line of lines) {
+      if (line.startsWith('data: ')) {
+        const data = line.slice(6);
+        if (data === '[DONE]') continue;
+        
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
+            translatedContent += parsed.delta.text;
+            chunkCount++;
+            if (chunkCount % 100 === 0) {
+              process.stdout.write(`\r[${targetLang}] Received ${translatedContent.length} chars...`);
+            }
+          }
+        } catch (e) {
+          // Skip invalid JSON
+        }
+      }
+    }
+  }
+  
+  process.stdout.write('\n');
+  
+  console.log(`\n[${targetLang}] Stream complete, received ${translatedContent.length} characters`);
+  
+  if (!translatedContent) {
+    throw new Error(`[${targetLang}] No translation received`);
+  }
+  
+  console.log(`[${targetLang}] Fixing image paths...`);
+  
+  // Fix image paths
+  translatedContent = translatedContent
+    .replace(/!\[([^\]]*)\]\(\.\/images\//g, '![$1](../images/')
+    .replace(/!\[([^\]]*)\]\(\.\/public\//g, '![$1](../public/')
+    .replace(/<img src="\.\/images\//g, '<img src="../images/')
+    .replace(/<img src="\.\/public\//g, '<img src="../public/');
+  
+  const i18nDir = path.join(__dirname, '../i18n');
+  if (!fs.existsSync(i18nDir)) {
+    fs.mkdirSync(i18nDir, { recursive: true });
+  }
+  
+  const outputPath = path.join(i18nDir, `README.${targetLang}.md`);
+  fs.writeFileSync(outputPath, translatedContent, 'utf8');
+  
+  console.log(`[${targetLang}] ✅ Complete: ${outputPath}`);
+  return { lang: targetLang, success: true, path: outputPath };
+}
+
+// ============ MAIN ============
+async function main() {
+  console.log('='.repeat(60));
+  console.log('README Translation Tool (Streaming Mode)');
+  console.log('='.repeat(60));
+  console.log(`API Endpoint: ${API_ENDPOINT}`);
+  console.log(`Model: ${API_MODEL}`);
+  console.log(`Max Tokens: ${MAX_TOKENS}`);
+  console.log(`Batch Size: ${BATCH_SIZE}`);
+  console.log(`Languages: ${targetLangs.join(', ')}`);
+  console.log('='.repeat(60));
+  
+  const readmePath = path.join(__dirname, '../README.md');
+  const readmeContent = fs.readFileSync(readmePath, 'utf8');
+  
+  // Translate languages in batches (parallel within batch)
+  const results = [];
+  for (let i = 0; i < targetLangs.length; i += BATCH_SIZE) {
+    const batch = targetLangs.slice(i, i + BATCH_SIZE);
+    console.log(`\nBatch ${Math.floor(i / BATCH_SIZE) + 1}/${Math.ceil(targetLangs.length / BATCH_SIZE)}: ${batch.join(', ')}`);
+    console.log('Starting translations in parallel...\n');
+    
+    // Start all translations in parallel (don't await yet)
+    const batchPromises = batch.map(lang => translateToLanguage(readmeContent, lang));
+    
+    // Wait for all to complete
+    const batchResults = await Promise.allSettled(batchPromises);
+    
+    results.push(...batchResults);
+    
+    // Wait between batches to avoid rate limit
+    if (i + BATCH_SIZE < targetLangs.length) {
+      console.log('\nWaiting 3s before next batch...');
+      await new Promise(resolve => setTimeout(resolve, 3000));
+    }
+  }
+  
+  console.log('\n' + '='.repeat(60));
+  console.log('SUMMARY');
+  console.log('='.repeat(60));
+  
+  results.forEach((result) => {
+    if (result.status === 'fulfilled') {
+      console.log(`✅ ${result.value.lang}: ${result.value.path}`);
+    } else {
+      console.log(`❌ ${result.lang}: ${result.reason.message}`);
+    }
+  });
+  
+  const failed = results.filter(r => r.status === 'rejected').length;
+  if (failed > 0) {
+    console.log(`\n⚠️  ${failed} translation(s) failed`);
+    process.exit(1);
+  }
+  
+  console.log('\n✅ All translations completed successfully!');
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});
diff --git a/skills/9router-chat/SKILL.md b/skills/9router-chat/SKILL.md
new file mode 100644
index 0000000..d109ac7
--- /dev/null
+++ b/skills/9router-chat/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: 9router-chat
+description: Chat / code generation via 9Router using OpenAI /v1/chat/completions or Anthropic /v1/messages format with streaming + auto-fallback combos. Use when the user wants to ask an LLM, generate code, summarize text, or run prompts through 9Router.
+---
+
+# 9Router — Chat
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Endpoints
+
+- `POST $NINEROUTER_URL/v1/chat/completions` — OpenAI format
+- `POST $NINEROUTER_URL/v1/messages` — Anthropic format
+
+## Discover
+
+```bash
+curl $NINEROUTER_URL/v1/models | jq '.data[].id'
+# Per-model metadata (contextWindow, params)
+curl "$NINEROUTER_URL/v1/models/info?id=openai/gpt-4o"
+```
+
+Combos (e.g. `vip`, `mycodex`) auto-fallback through multiple providers.
+
+## OpenAI format
+
+```bash
+curl -X POST $NINEROUTER_URL/v1/chat/completions \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/gpt-5","messages":[{"role":"user","content":"Hi"}],"stream":false}'
+```
+
+JS (OpenAI SDK):
+
+```js
+import OpenAI from "openai";
+const client = new OpenAI({ baseURL: `${process.env.NINEROUTER_URL}/v1`, apiKey: process.env.NINEROUTER_KEY });
+const res = await client.chat.completions.create({
+  model: "openai/gpt-5",
+  messages: [{ role: "user", content: "Hi" }],
+  stream: true,
+});
+for await (const chunk of res) process.stdout.write(chunk.choices[0]?.delta?.content || "");
+```
+
+## Anthropic format
+
+```bash
+curl -X POST $NINEROUTER_URL/v1/messages \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"cc/claude-opus-4-7","max_tokens":1024,"messages":[{"role":"user","content":"Hi"}]}'
+```
+
+## Response shape
+
+OpenAI (`/v1/chat/completions`):
+```json
+{ "id": "chatcmpl-...", "object": "chat.completion", "model": "openai/gpt-5",
+  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hello!" }, "finish_reason": "stop" }],
+  "usage": { "prompt_tokens": 8, "completion_tokens": 2, "total_tokens": 10 } }
+```
+
+Streaming (`stream:true`) emits SSE: `data: {choices:[{delta:{content:"..."}}]}\n\n` ... `data: [DONE]\n\n`.
+
+Anthropic (`/v1/messages`):
+```json
+{ "id": "msg_...", "type": "message", "role": "assistant", "model": "cc/claude-opus-4-7",
+  "content": [{ "type": "text", "text": "Hello!" }],
+  "stop_reason": "end_turn", "usage": { "input_tokens": 8, "output_tokens": 2 } }
+```
diff --git a/skills/9router-embeddings/SKILL.md b/skills/9router-embeddings/SKILL.md
new file mode 100644
index 0000000..648e4ca
--- /dev/null
+++ b/skills/9router-embeddings/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: 9router-embeddings
+description: Generate vector embeddings via 9Router /v1/embeddings using OpenAI / Gemini / Mistral / Voyage / Nvidia / GitHub embedding models for RAG, semantic search, similarity. Use when the user wants embeddings, vectors, RAG, semantic search, or to embed text.
+---
+
+# 9Router — Embeddings
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $NINEROUTER_URL/v1/models/embedding | jq '.data[].id'
+# Per-model dimensions
+curl "$NINEROUTER_URL/v1/models/info?id=openai/text-embedding-3-small"
+```
+
+## Endpoint
+
+`POST $NINEROUTER_URL/v1/embeddings`
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` | yes | from `/v1/models/embedding` |
+| `input` | yes | string OR array of strings |
+| `encoding_format` | no | `float` (default) / `base64` |
+| `dimensions` | no | OpenAI v3 only |
+
+## Examples
+
+```bash
+curl -X POST $NINEROUTER_URL/v1/embeddings \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/text-embedding-3-small","input":["hello","world"]}'
+```
+
+JS:
+
+```js
+const r = await fetch(`${process.env.NINEROUTER_URL}/v1/embeddings`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.NINEROUTER_KEY}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ model: "gemini/text-embedding-004", input: "RAG chunk text" }),
+});
+const { data } = await r.json();
+console.log(data[0].embedding.length);  // dimension
+```
+
+## Response shape
+
+```json
+{ "object": "list", "model": "openai/text-embedding-3-small",
+  "data": [
+    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.045, ...] },
+    { "object": "embedding", "index": 1, "embedding": [...] }
+  ],
+  "usage": { "prompt_tokens": 5, "total_tokens": 5 } }
+```
+
+## Provider quirks
+
+| Provider | Notes |
+|---|---|
+| `openai`, `openrouter`, `mistral`, `voyage-ai`, `fireworks`, `together`, `nebius`, `github`, `nvidia`, `jina-ai` | Native OpenAI shape — `dimensions` works only on OpenAI v3 (`text-embedding-3-*`) |
+| `gemini`, `google_ai_studio` | Server auto-converts to `embedContent`/`batchEmbedContents` — send OpenAI shape |
+| `openai-compatible-*`, `custom-embedding-*` | Custom `baseUrl` from credentials |
+
+Batch (`input` as array) is faster; some providers cap batch size.
diff --git a/skills/9router-image/SKILL.md b/skills/9router-image/SKILL.md
new file mode 100644
index 0000000..f5bbfad
--- /dev/null
+++ b/skills/9router-image/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: 9router-image
+description: Generate images via 9Router /v1/images/generations using OpenAI / Gemini Imagen / DALL-E / FLUX / MiniMax / SDWebUI / ComfyUI / Codex models. Use when the user wants to create, generate, draw, or render an image, picture, or text-to-image (txt2img).
+---
+
+# 9Router — Image Generation
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $NINEROUTER_URL/v1/models/image | jq '.data[].id'
+# Per-model params/options (size enum, quality enum, capabilities like edit)
+curl "$NINEROUTER_URL/v1/models/info?id=openai/dall-e-3"
+```
+
+## Endpoint
+
+`POST $NINEROUTER_URL/v1/images/generations`
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` | yes | from `/v1/models/image` |
+| `prompt` | yes | image description |
+| `n` | no | count (provider-dependent) |
+| `size` | no | `1024x1024`, `1792x1024`, ... |
+| `quality` | no | `standard` / `hd` (OpenAI) |
+| `response_format` | no | `url` (default) or `b64_json` |
+
+Add query `?response_format=binary` to receive raw image bytes (handy for saving file).
+
+## Examples
+
+Save to file (binary):
+
+```bash
+curl -X POST "$NINEROUTER_URL/v1/images/generations?response_format=binary" \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gemini/gemini-3-pro-image-preview","prompt":"watercolor mountains at sunrise","size":"1024x1024"}' \
+  --output out.png
+```
+
+JS (URL response):
+
+```js
+const r = await fetch(`${process.env.NINEROUTER_URL}/v1/images/generations`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.NINEROUTER_KEY}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ model: "gemini/gemini-3-pro-image-preview", prompt: "neon city", size: "1024x1024" }),
+});
+const { data } = await r.json();
+console.log(data[0].url || data[0].b64_json.slice(0, 40));
+```
+
+## Response shape
+
+JSON (default `response_format=url`):
+```json
+{ "created": 1735000000, "data": [{ "url": "https://..." }] }
+```
+
+`response_format=b64_json`:
+```json
+{ "created": 1735000000, "data": [{ "b64_json": "iVBORw0KGgo..." }] }
+```
+
+Query `?response_format=binary` returns raw image bytes (Content-Type `image/png` or `image/jpeg`).
+
+## Provider quirks
+
+Common fields above work everywhere. These add/override:
+
+| Provider | Extra/changed fields | Notes |
+|---|---|---|
+| `openai`, `minimax`, `openrouter`, `recraft` | `quality`, `style`, `response_format` | Standard OpenAI shape |
+| `gemini` (nano-banana) | — | Only `prompt`; ignores `size`/`n` |
+| `codex` (gpt-5.4-image) | `image`, `images[]`, `image_detail`, `output_format`, `background` | SSE stream; **ChatGPT Plus/Pro required** |
+| `huggingface` | — | Only `prompt`; returns single image |
+| `nanobanana` | `image`, `images[]` (edit mode) | `size` → aspect ratio; async polling |
+| `fal-ai` | `image` (img2img) | `n` → `num_images`; `size` → ratio; async |
+| `stability-ai` | `style` (preset), `output_format` | `size` → `aspect_ratio` |
+| `black-forest-labs` (FLUX) | `image` (ref) | `size` → exact `width`/`height`; async |
+| `runwayml` | `image` (ref) | `size` → ratio; async; video models exist |
+| `sdwebui`, `comfyui` | — | Localhost noAuth (`:7860` / `:8188`) |
diff --git a/skills/9router-stt/SKILL.md b/skills/9router-stt/SKILL.md
new file mode 100644
index 0000000..1561c9d
--- /dev/null
+++ b/skills/9router-stt/SKILL.md
@@ -0,0 +1,79 @@
+---
+name: 9router-stt
+description: Speech-to-text via 9Router /v1/audio/transcriptions using OpenAI Whisper / Groq / Gemini / Deepgram / AssemblyAI / NVIDIA / HuggingFace models. Use when the user wants to transcribe audio, convert speech to text, or get subtitles from audio files.
+---
+
+# 9Router — Speech-to-Text
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $NINEROUTER_URL/v1/models/stt | jq '.data[].id'
+# Per-model params (language, response_format, prompt, temperature support)
+curl "$NINEROUTER_URL/v1/models/info?id=openai/whisper-1"
+```
+
+`model` = STT model ID (e.g. `openai/whisper-1`, `groq/whisper-large-v3`, `deepgram/nova-3`, `gemini/gemini-2.5-flash`).
+
+## Endpoint
+
+`POST $NINEROUTER_URL/v1/audio/transcriptions` (OpenAI Whisper compatible, `multipart/form-data`)
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` | yes | from `/v1/models/stt` |
+| `file` | yes | audio file (mp3, wav, m4a, webm, ogg, flac) |
+| `language` | no | ISO-639-1 (e.g. `en`, `vi`) |
+| `prompt` | no | hint text to guide transcription |
+| `response_format` | no | `json` (default) / `text` / `verbose_json` / `srt` / `vtt` |
+| `temperature` | no | 0–1 |
+
+## Examples
+
+```bash
+curl -X POST "$NINEROUTER_URL/v1/audio/transcriptions" \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -F "model=openai/whisper-1" \
+  -F "file=@audio.mp3" \
+  -F "language=vi"
+```
+
+JS (Node):
+
+```js
+import { createReadStream } from "node:fs";
+const form = new FormData();
+form.append("model", "groq/whisper-large-v3-turbo");
+form.append("file", new Blob([await (await import("node:fs/promises")).readFile("audio.mp3")]), "audio.mp3");
+const r = await fetch(`${process.env.NINEROUTER_URL}/v1/audio/transcriptions`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.NINEROUTER_KEY}` },
+  body: form,
+});
+const { text } = await r.json();
+console.log(text);
+```
+
+## Response shape
+
+Default (`response_format=json`):
+```json
+{ "text": "Xin chào, đây là bản ghi âm." }
+```
+
+`verbose_json` adds `language`, `duration`, `segments[]` with timestamps.
+`srt` / `vtt` return subtitle text.
+
+## Provider quirks
+
+| Provider | `model` format | Notes |
+|---|---|---|
+| `openai` | `whisper-1`, `gpt-4o-transcribe`, `gpt-4o-mini-transcribe` | Native OpenAI shape |
+| `groq` | `whisper-large-v3`, `whisper-large-v3-turbo`, `distil-whisper-large-v3-en` | Fastest; OpenAI shape |
+| `gemini` | `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-2.5-flash-lite` | Server converts to `generateContent` with audio inline |
+| `deepgram` | `nova-3`, `nova-2`, `whisper-large` | Token auth; server adapts response |
+| `assemblyai` | `universal-3-pro`, `universal-2` | Async upload+poll handled server-side |
+| `nvidia` | `nvidia/parakeet-ctc-1.1b-asr` | NIM endpoint |
+| `huggingface` | `openai/whisper-large-v3`, `openai/whisper-small` | HF Inference API |
diff --git a/skills/9router-tts/SKILL.md b/skills/9router-tts/SKILL.md
new file mode 100644
index 0000000..4a9536c
--- /dev/null
+++ b/skills/9router-tts/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: 9router-tts
+description: Text-to-speech via 9Router /v1/audio/speech using OpenAI / ElevenLabs / Deepgram / Edge TTS / Google TTS / Hyperbolic / Inworld voices. Use when the user wants to convert text to speech, generate audio, voiceover, narrate, or read text aloud.
+---
+
+# 9Router — Text-to-Speech
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Discover
+
+```bash
+# 1) List models
+curl $NINEROUTER_URL/v1/models/tts | jq '.data[].id'
+# 2) Per-model metadata (params, voicesUrl if voice-by-id)
+curl "$NINEROUTER_URL/v1/models/info?id=el/eleven_multilingual_v2"
+# 3) List voices (elevenlabs, edge-tts, deepgram, inworld, local-device). Optional ?lang=vi
+curl "$NINEROUTER_URL/v1/audio/voices?provider=edge-tts&lang=vi" | jq '.data[].model'
+```
+
+`model` field in `/v1/audio/speech` = voice ID directly (e.g. `edge-tts/vi-VN-HoaiMyNeural`, `el/<voice_id>`, or `openai/tts-1` model+default voice).
+
+## Endpoint
+
+`POST $NINEROUTER_URL/v1/audio/speech`
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` | yes | voice ID from `/v1/models/tts` |
+| `input` | yes | text to speak |
+
+Query `?response_format=mp3` (default, raw bytes) or `?response_format=json` (`{audio: base64, format}`).
+
+## Examples
+
+Save MP3:
+
+```bash
+curl -X POST "$NINEROUTER_URL/v1/audio/speech" \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/tts-1","input":"Hello world"}' \
+  --output speech.mp3
+```
+
+JS (save file):
+
+```js
+import { writeFile } from "node:fs/promises";
+const r = await fetch(`${process.env.NINEROUTER_URL}/v1/audio/speech`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.NINEROUTER_KEY}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ model: "el/eleven_multilingual_v2", input: "Xin chào" }),
+});
+await writeFile("speech.mp3", Buffer.from(await r.arrayBuffer()));
+```
+
+## Response shape
+
+Default → raw audio bytes (Content-Type `audio/mp3`).
+
+`?response_format=json`:
+```json
+{ "audio": "SUQzBAAAA...", "format": "mp3" }
+```
+
+## Provider quirks (model format)
+
+| Provider | `model` format | Notes |
+|---|---|---|
+| `openai` | `tts-1/alloy` (model/voice) or just voice | Default model `gpt-4o-mini-tts` |
+| `elevenlabs` | `<model_id>/<voice_id>` or `<voice_id>` | Default model `eleven_flash_v2_5`; list voices in Dashboard |
+| `openrouter` | `openai/gpt-4o-mini-tts/alloy` | Streamed via chat-completions audio modality |
+| `edge-tts` | voice id e.g. `vi-VN-HoaiMyNeural` | **noAuth**; default `vi-VN-HoaiMyNeural` |
+| `google-tts` | language code e.g. `en`, `vi` | **noAuth** |
+| `local-device` | OS voice name (`say -v ?` / SAPI) | **noAuth**; needs `ffmpeg` |
+| `deepgram` | `aura-asteria-en` etc | Token auth |
+| `nvidia`, `inworld`, `cartesia`, `playht` | `model/voice` | Provider-specific auth header |
+| `coqui`, `tortoise` | speaker / voice id | Localhost noAuth |
+| `hyperbolic` | model id | Body = `{text}` only |
diff --git a/skills/9router-web-fetch/SKILL.md b/skills/9router-web-fetch/SKILL.md
new file mode 100644
index 0000000..69c41ac
--- /dev/null
+++ b/skills/9router-web-fetch/SKILL.md
@@ -0,0 +1,99 @@
+---
+name: 9router-web-fetch
+description: Fetch URL → markdown / text / HTML via 9Router /v1/web/fetch using Firecrawl / Jina Reader / Tavily Extract / Exa Contents. Use when the user wants to scrape a webpage, extract URL content, read article, or convert a URL to markdown.
+---
+
+# 9Router — Web Fetch
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $NINEROUTER_URL/v1/models/web | jq '.data[] | select(.kind=="webFetch") | .id'
+# Per-provider params
+curl "$NINEROUTER_URL/v1/models/info?id=firecrawl/fetch"
+```
+
+IDs end in `/fetch` (e.g. `firecrawl/fetch`, `jina/fetch`). `fetch-combo` chains providers with auto-fallback.
+
+## Endpoint
+
+`POST $NINEROUTER_URL/v1/web/fetch`
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` (or `provider`) | yes | from `/v1/models/web` (e.g. `firecrawl` or `jina-reader`) |
+| `url` | yes | URL to extract |
+| `format` | no | `markdown` (default) / `text` / `html` |
+| `max_characters` | no | truncate output |
+
+## Examples
+
+### Jina Reader
+```bash
+curl -X POST $NINEROUTER_URL/v1/web/fetch \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"jina-reader","url":"https://9router.com","format":"markdown"}'
+```
+
+### Exa
+```bash
+curl -X POST $NINEROUTER_URL/v1/web/fetch \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"exa","url":"https://example.com","format":"markdown","max_characters":0}'
+```
+
+### Firecrawl
+```bash
+curl -X POST $NINEROUTER_URL/v1/web/fetch \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"firecrawl","url":"https://example.com","format":"markdown","max_characters":0}'
+```
+
+### Tavily
+```bash
+curl -X POST $NINEROUTER_URL/v1/web/fetch \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"tavily","url":"https://example.com","format":"markdown","max_characters":0}'
+```
+
+
+JS:
+
+```js
+const r = await fetch(`${process.env.NINEROUTER_URL}/v1/web/fetch`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.NINEROUTER_KEY}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ model: "fetch-combo", url: "https://example.com", format: "markdown", max_characters: 5000 }),
+});
+const { data } = await r.json();
+console.log(data.title, data.content.length);
+```
+
+## Response shape
+
+```json
+{
+  "provider": "jina-reader",
+  "url": "...",
+  "title": "...",
+  "content": { "format": "markdown", "text": "...", "length": 1234 },
+  "metadata": { "author": null, "published_at": null, "language": null },
+  "usage": { "fetch_cost_usd": 0 },
+  "metrics": { "response_time_ms": 850, "upstream_latency_ms": 700 }
+}
+```
+
+## Provider quirks
+
+| Provider | Auth | Best for |
+|---|---|---|
+| `firecrawl` | Bearer | JS-rendered pages, `format=markdown/html` |
+| `jina-reader` | Bearer (optional) | Free tier (~1M chars/mo); fastest plain markdown |
+| `tavily` | Bearer | Bulk extract; returns `raw_content` |
+| `exa` | `x-api-key` | Pre-indexed pages; fast text extraction |
diff --git a/skills/9router-web-search/SKILL.md b/skills/9router-web-search/SKILL.md
new file mode 100644
index 0000000..ebd3003
--- /dev/null
+++ b/skills/9router-web-search/SKILL.md
@@ -0,0 +1,91 @@
+---
+name: 9router-web-search
+description: Web search via 9Router /v1/search using Tavily / Exa / Brave / Serper / SearXNG / Google PSE / Linkup / SearchAPI / You.com / Perplexity. Use when the user wants to search the web, look up information, find articles, or query a search engine.
+---
+
+# 9Router — Web Search
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $NINEROUTER_URL/v1/models/web | jq '.data[] | select(.kind=="webSearch") | .id'
+# Per-provider params (searchTypes, maxResults, required options like cx for google-pse)
+curl "$NINEROUTER_URL/v1/models/info?id=tavily/search"
+```
+
+IDs end in `/search` (e.g. `tavily/search`). Combos (`owned_by:"combo"`) chain providers with auto-fallback.
+
+## Endpoint
+
+`POST $NINEROUTER_URL/v1/search`
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` (or `provider`) | yes | from `/v1/models/web` (e.g. `tavily` or `brave`) |
+| `query` | yes | search query |
+| `max_results` | no | default 5 |
+| `search_type` | no | `web` (default) / `news` |
+| `country`, `language`, `time_range`, `domain_filter` | no | provider-dependent |
+
+## Examples
+
+```bash
+curl -X POST $NINEROUTER_URL/v1/search \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"tavily","query":"9Router open source","max_results":5}'
+```
+
+JS:
+
+```js
+const r = await fetch(`${process.env.NINEROUTER_URL}/v1/search`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.NINEROUTER_KEY}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ model: "search-combo", query: "latest LLM benchmarks", max_results: 10 }),
+});
+console.log(await r.json());
+```
+
+## Response shape
+
+```json
+{
+  "provider": "tavily",
+  "query": "9Router open source",
+  "results": [
+    {
+      "title": "...", "url": "https://...", "display_url": "github.com/...",
+      "snippet": "...", "position": 1, "score": 0.92,
+      "published_at": null, "favicon_url": null, "content": null,
+      "metadata": { "author": null, "language": null, "source_type": null, "image_url": null },
+      "citation": { "provider": "tavily", "retrieved_at": "2026-...", "rank": 1 }
+    }
+  ],
+  "answer": null,
+  "usage": { "queries_used": 1, "search_cost_usd": 0.008 },
+  "metrics": { "response_time_ms": 850, "upstream_latency_ms": 700, "total_results_available": 12 },
+  "errors": []
+}
+```
+
+## Provider quirks
+
+All accept `query` + `max_results`. Optional fields vary:
+
+| Provider | Supports | Required extras |
+|---|---|---|
+| `tavily` | country, domain_filter, news topic | — |
+| `exa` | domain_filter (incl/excl), news category | — |
+| `brave-search` | country, language | — |
+| `serper` | country, language, news endpoint | — |
+| `perplexity` | country, language, domain_filter | — |
+| `linkup` | domain_filter, time_range | `depth: fast/standard/deep` (option) |
+| `google-pse` | country, language, time_range, offset | **`cx` required** (providerOptions) |
+| `searchapi` | country, language, pagination | — |
+| `youcom` | country, language, time_range, domain_filter, full_page | — |
+| `searxng` | language, time_range | Self-hosted, **noAuth** |
+
+Provider IS the model — `"provider":"tavily" ≡ "model":"tavily"`.
diff --git a/skills/9router/SKILL.md b/skills/9router/SKILL.md
new file mode 100644
index 0000000..ea4c511
--- /dev/null
+++ b/skills/9router/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: 9router
+description: Entry point for 9Router — local/remote AI gateway with OpenAI-compatible REST for chat, image, TTS, embeddings, web search, web fetch. Use when the user mentions 9Router, NINEROUTER_URL, or wants AI without writing provider boilerplate. This skill covers setup + indexes capability skills; fetch the relevant capability SKILL.md from the URLs below when needed.
+---
+
+# 9Router
+
+Local/remote AI gateway exposing OpenAI-compatible REST. One key, many providers, auto-fallback.
+
+## Setup
+
+```bash
+export NINEROUTER_URL="http://localhost:20128"      # or VPS / tunnel URL
+export NINEROUTER_KEY="sk-..."                      # from Dashboard → Keys (only if requireApiKey=true)
+```
+
+All requests: `${NINEROUTER_URL}/v1/...` with header `Authorization: Bearer ${NINEROUTER_KEY}` (omit if auth disabled).
+
+Verify: `curl $NINEROUTER_URL/api/health` → `{"ok":true}`
+
+## Discover models
+
+```bash
+curl $NINEROUTER_URL/v1/models                  # chat/LLM (default)
+curl $NINEROUTER_URL/v1/models/image            # image-gen
+curl $NINEROUTER_URL/v1/models/tts              # text-to-speech
+curl $NINEROUTER_URL/v1/models/embedding        # embeddings
+curl $NINEROUTER_URL/v1/models/web              # web search + fetch (entries have `kind` field)
+curl $NINEROUTER_URL/v1/models/stt              # speech-to-text
+curl $NINEROUTER_URL/v1/models/image-to-text    # vision
+```
+
+Use `data[].id` as `model` field in requests. Combos appear with `owned_by:"combo"`.
+
+Response shape:
+```json
+{ "object": "list", "data": [
+  { "id": "openai/gpt-5", "object": "model", "owned_by": "openai", "created": 1735000000 },
+  { "id": "tavily/search", "object": "model", "kind": "webSearch", "owned_by": "tavily", "created": 1735000000 }
+]}
+```
+
+## Capability skills
+
+When the user needs a specific capability, fetch that skill's `SKILL.md` from its raw URL:
+
+| Capability | Raw URL |
+|---|---|
+| Chat / code-gen | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-chat/SKILL.md |
+| Image generation | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-image/SKILL.md |
+| Text-to-speech | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-tts/SKILL.md |
+| Speech-to-text | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-stt/SKILL.md |
+| Embeddings | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-embeddings/SKILL.md |
+| Web search | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-web-search/SKILL.md |
+| Web fetch (URL → markdown) | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-web-fetch/SKILL.md |
+
+## Errors
+
+- 401 → set/refresh `NINEROUTER_KEY` (Dashboard → Keys)
+- 400 `Invalid model format` → check `model` exists in `/v1/models/<kind>`
+- 503 `All accounts unavailable` → wait `retry-after` or add another provider account
diff --git a/skills/README.md b/skills/README.md
new file mode 100644
index 0000000..f9f06b9
--- /dev/null
+++ b/skills/README.md
@@ -0,0 +1,42 @@
+# 9Router — Agent Skills
+
+Drop-in skills for any AI agent (Claude, Cursor, ChatGPT, custom SDK). Just **copy a link** below and paste it to your AI — it will fetch the skill and use 9Router for you.
+
+> Tip: start with the **9router** entry skill — it covers setup and links to all capability skills.
+
+## Skills
+
+| Capability | Copy link below and paste to your AI |
+|---|---|
+| **Entry / Setup** (start here) | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md |
+| Chat / code-gen | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-chat/SKILL.md |
+| Image generation | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-image/SKILL.md |
+| Text-to-speech | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-tts/SKILL.md |
+| Speech-to-text | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-stt/SKILL.md |
+| Embeddings | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-embeddings/SKILL.md |
+| Web search | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-web-search/SKILL.md |
+| Web fetch (URL → markdown) | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-web-fetch/SKILL.md |
+
+## How to use
+
+Paste to your AI (Claude, Cursor, ChatGPT, …):
+
+```
+Read this skill and use it: https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md
+```
+
+Then ask normally — *"generate an image of a cat"*, *"transcribe this URL"*, etc.
+
+## Configure your shell once
+
+```bash
+export NINEROUTER_URL="http://localhost:20128"   # local default, or your VPS / tunnel URL
+export NINEROUTER_KEY="sk-..."                   # from Dashboard → Keys (only if requireApiKey=true)
+```
+
+Verify: `curl $NINEROUTER_URL/api/health` → `{"ok":true}`.
+
+## Links
+
+- Source: https://github.com/decolua/9router
+- Dashboard: https://9router.com
diff --git a/src/app/(dashboard)/dashboard/basic-chat/BasicChatPageClient.js b/src/app/(dashboard)/dashboard/basic-chat/BasicChatPageClient.js
new file mode 100644
index 0000000..a97d0a5
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/basic-chat/BasicChatPageClient.js
@@ -0,0 +1,967 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Badge, Button } from "@/shared/components";
+import { getModelsByProviderId } from "@/shared/constants/models";
+import { isAnthropicCompatibleProvider, isOpenAICompatibleProvider } from "@/shared/constants/providers";
+
+const STORAGE_KEYS = {
+  sessions: "basic-chat.sessions",
+  activeSessionId: "basic-chat.activeSessionId",
+  activeProviderId: "basic-chat.activeProviderId",
+  draft: "basic-chat.draft",
+};
+
+function createId() {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
+  return `chat_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+}
+
+function safeParse(value, fallback) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
+
+function textValue(value) {
+  if (typeof value === "string") return value;
+  if (value == null) return "";
+  if (Array.isArray(value)) return value.map(textValue).filter(Boolean).join(" ");
+  if (typeof value === "object") {
+    if (typeof value.message === "string") return value.message;
+    if (typeof value.error === "string") return value.error;
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+
+function humanize(value = "") {
+  return String(value)
+    .replace(/[-_]/g, " ")
+    .replace(/\b\w/g, (char) => char.toUpperCase())
+    .trim() || "Unknown";
+}
+
+function formatRelativeTime(value) {
+  if (!value) return "Now";
+  const time = new Date(value).getTime();
+  if (Number.isNaN(time)) return "Now";
+  const diffMinutes = Math.max(1, Math.round((Date.now() - time) / 60000));
+  if (diffMinutes < 60) return `${diffMinutes}m`;
+  const diffHours = Math.round(diffMinutes / 60);
+  if (diffHours < 24) return `${diffHours}h`;
+  return `${Math.round(diffHours / 24)}d`;
+}
+
+function makeSessionTitle(text = "") {
+  const normalized = textValue(text).replace(/\s+/g, " ").trim();
+  if (!normalized) return "New chat";
+  return normalized.length > 52 ? `${normalized.slice(0, 52).trimEnd()}…` : normalized;
+}
+
+function buildUserContent(message) {
+  const text = textValue(message.content).trim();
+  const attachments = Array.isArray(message.attachments) ? message.attachments : [];
+
+  if (attachments.length === 0) return text;
+
+  const content = [];
+  if (text) content.push({ type: "text", text });
+
+  for (const attachment of attachments) {
+    if (attachment?.dataUrl) {
+      content.push({ type: "image_url", image_url: { url: attachment.dataUrl } });
+    }
+  }
+
+  return content.length > 0 ? content : text;
+}
+
+function readAssistantText(chunk) {
+  if (!chunk || typeof chunk !== "object") return "";
+  const choice = chunk.choices?.[0];
+  const delta = choice?.delta || {};
+  const pieces = [delta.content, choice?.message?.content, chunk.output_text, chunk.text]
+    .map(textValue)
+    .filter(Boolean);
+  return pieces[0] || "";
+}
+
+async function fileToDataUrl(file) {
+  return await new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result || ""));
+    reader.onerror = () => reject(reader.error || new Error("Failed to read file"));
+    reader.readAsDataURL(file);
+  });
+}
+
+function cloneSession(session) {
+  return {
+    ...session,
+    messages: Array.isArray(session.messages) ? session.messages.map((message) => ({ ...message })) : [],
+  };
+}
+
+function getProviderLabel(connection) {
+  return connection?.name || humanize(connection?.provider || connection?.id || "provider");
+}
+
+function normalizeStaticModel(model, connection) {
+  if (!model?.id) return null;
+  return {
+    id: `${connection.provider}/${model.id}`,
+    requestModel: `${connection.provider}/${model.id}`,
+    name: model.name || model.id,
+    providerId: connection.provider,
+    providerName: getProviderLabel(connection),
+    source: "static",
+  };
+}
+
+function normalizeLiveModel(model, connection) {
+  const rawId = typeof model === "string" ? model : model?.id || model?.name || model?.model || "";
+  if (!rawId) return null;
+
+  const displayName = typeof model === "string"
+    ? model
+    : model?.name || model?.displayName || rawId;
+
+  let requestModel = rawId;
+  const isCompatible = isOpenAICompatibleProvider(connection.provider) || isAnthropicCompatibleProvider(connection.provider);
+  if (isCompatible && !rawId.includes("/")) {
+    requestModel = `${connection.provider}/${rawId}`;
+  }
+
+  return {
+    id: requestModel,
+    requestModel,
+    name: displayName,
+    providerId: connection.provider,
+    providerName: getProviderLabel(connection),
+    source: "live",
+  };
+}
+
+function parseProviderModelsPayload(data) {
+  if (Array.isArray(data?.models)) return data.models;
+  if (Array.isArray(data?.data)) return data.data;
+  if (Array.isArray(data?.results)) return data.results;
+  if (Array.isArray(data)) return data;
+  return [];
+}
+
+function dedupeModels(models) {
+  const map = new Map();
+  for (const model of models) {
+    if (!model?.id) continue;
+    if (!map.has(model.id)) map.set(model.id, model);
+  }
+  return Array.from(map.values());
+}
+
+export default function BasicChatPageClient() {
+  const [providerGroups, setProviderGroups] = useState([]);
+  const [loadingData, setLoadingData] = useState(true);
+  const [loadError, setLoadError] = useState("");
+  const [sessions, setSessions] = useState(() => {
+    if (typeof window === "undefined") return [];
+    try {
+      const saved = safeParse(globalThis.localStorage.getItem(STORAGE_KEYS.sessions), []);
+      return Array.isArray(saved) ? saved.map((session) => ({
+        ...session,
+        messages: Array.isArray(session.messages) ? session.messages : [],
+      })) : [];
+    } catch { return []; }
+  });
+  const [activeSessionId, setActiveSessionId] = useState(() => {
+    if (typeof window === "undefined") return "";
+    return globalThis.localStorage.getItem(STORAGE_KEYS.activeSessionId) || "";
+  });
+  const [activeProviderId, setActiveProviderId] = useState(() => {
+    if (typeof window === "undefined") return "";
+    return globalThis.localStorage.getItem(STORAGE_KEYS.activeProviderId) || "";
+  });
+  const [activeModelId, setActiveModelId] = useState("");
+  const [draft, setDraft] = useState(() => {
+    if (typeof window === "undefined") return "";
+    return globalThis.localStorage.getItem(STORAGE_KEYS.draft) || "";
+  });
+  const [attachments, setAttachments] = useState([]);
+  const [isSending, setIsSending] = useState(false);
+  const [streamingMessageId, setStreamingMessageId] = useState("");
+  const [streamingText, setStreamingText] = useState("");
+  const [isHydrated, setIsHydrated] = useState(false);
+  const [modelMenuOpen, setModelMenuOpen] = useState(false);
+  const [historyOpen, setHistoryOpen] = useState(false);
+  const fileInputRef = useRef(null);
+  const abortRef = useRef(null);
+  const initializedRef = useRef(false);
+  const modelMenuRef = useRef(null);
+  const historyMenuRef = useRef(null);
+
+  useEffect(() => {
+    setIsHydrated(true);
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function loadData() {
+      setLoadingData(true);
+      setLoadError("");
+
+      try {
+        const providersRes = await fetch("/api/providers", { cache: "no-store" });
+        const providersData = await providersRes.json().catch(() => ({}));
+        const connections = Array.isArray(providersData.connections)
+          ? providersData.connections.filter((connection) => connection?.isActive !== false)
+          : [];
+
+        if (connections.length === 0) {
+          if (!cancelled) {
+            setProviderGroups([]);
+            setLoadError("No providers connected yet.");
+          }
+          return;
+        }
+
+        const providerMap = new Map();
+
+        for (const connection of connections) {
+          const providerId = connection.provider || connection.id;
+          const providerName = getProviderLabel(connection);
+          const providerType = isOpenAICompatibleProvider(providerId)
+            ? "openai-compatible"
+            : isAnthropicCompatibleProvider(providerId)
+              ? "anthropic-compatible"
+              : providerId;
+
+          if (!providerMap.has(providerId)) {
+            providerMap.set(providerId, {
+              providerId,
+              providerName,
+              providerType,
+              connections: [],
+              models: [],
+            });
+          }
+
+          const group = providerMap.get(providerId);
+          group.providerName = group.providerName || providerName;
+          group.providerType = group.providerType || providerType;
+          group.connections.push(connection);
+
+          const staticModels = getModelsByProviderId(providerId)
+            .map((model) => normalizeStaticModel(model, connection))
+            .filter(Boolean);
+          group.models.push(...staticModels);
+        }
+
+        const liveResults = await Promise.all(
+          connections.map(async (connection) => {
+            try {
+              const response = await fetch(`/api/providers/${connection.id}/models`, { cache: "no-store" });
+              const data = await response.json().catch(() => ({}));
+              if (!response.ok) return { connection, models: [] };
+              const models = parseProviderModelsPayload(data)
+                .map((model) => normalizeLiveModel(model, connection))
+                .filter(Boolean);
+              return { connection, models };
+            } catch {
+              return { connection, models: [] };
+            }
+          })
+        );
+
+        for (const result of liveResults) {
+          const providerId = result.connection.provider || result.connection.id;
+          const group = providerMap.get(providerId);
+          if (!group) continue;
+          group.models.push(...result.models);
+        }
+
+        const normalized = Array.from(providerMap.values())
+          .map((group) => ({
+            ...group,
+            models: dedupeModels(group.models).sort((a, b) => a.name.localeCompare(b.name)),
+          }))
+          .filter((group) => group.models.length > 0)
+          .sort((a, b) => a.providerName.localeCompare(b.providerName));
+
+        if (!cancelled) {
+          setProviderGroups(normalized);
+          if (normalized.length === 0) {
+            setLoadError("Providers connected but no models available.");
+          }
+        }
+      } catch (error) {
+        if (!cancelled) {
+          setLoadError(textValue(error?.message) || "Failed to load providers/models.");
+          setProviderGroups([]);
+        }
+      } finally {
+        if (!cancelled) setLoadingData(false);
+      }
+    }
+
+    loadData();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  useEffect(() => {
+    const handleClickOutside = (event) => {
+      if (modelMenuRef.current && !modelMenuRef.current.contains(event.target)) {
+        setModelMenuOpen(false);
+      }
+      if (historyMenuRef.current && !historyMenuRef.current.contains(event.target)) {
+        setHistoryOpen(false);
+      }
+    };
+
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, []);
+
+  const modelIndex = useMemo(() => {
+    const map = new Map();
+    for (const group of providerGroups) {
+      for (const model of group.models) {
+        map.set(model.id, {
+          ...model,
+          providerId: group.providerId,
+          providerName: group.providerName,
+        });
+      }
+    }
+    return map;
+  }, [providerGroups]);
+
+  const activeProviderGroup = useMemo(() => {
+    return providerGroups.find((group) => group.providerId === activeProviderId) || providerGroups[0] || null;
+  }, [providerGroups, activeProviderId]);
+
+  const activeModel = useMemo(() => {
+    if (activeModelId && modelIndex.has(activeModelId)) return modelIndex.get(activeModelId);
+    if (activeSessionId) {
+      const session = sessions.find((item) => item.id === activeSessionId);
+      if (session?.modelId && modelIndex.has(session.modelId)) return modelIndex.get(session.modelId);
+    }
+    return activeProviderGroup?.models?.[0] || null;
+  }, [activeModelId, modelIndex, activeProviderGroup, sessions, activeSessionId]);
+
+  const currentSession = useMemo(() => sessions.find((session) => session.id === activeSessionId) || null, [sessions, activeSessionId]);
+  const currentMessages = currentSession?.messages || [];
+  const sessionItems = useMemo(() => [...sessions].sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()), [sessions]);
+  const canSend = !isSending && !!activeModel && (draft.trim().length > 0 || attachments.length > 0);
+
+  useEffect(() => {
+    if (!isHydrated) return;
+    try {
+      globalThis.localStorage.setItem(STORAGE_KEYS.sessions, JSON.stringify(sessions));
+      globalThis.localStorage.setItem(STORAGE_KEYS.activeSessionId, activeSessionId);
+      globalThis.localStorage.setItem(STORAGE_KEYS.activeProviderId, activeProviderId);
+      globalThis.localStorage.setItem(STORAGE_KEYS.draft, draft);
+    } catch {
+      // Ignore storage errors.
+    }
+  }, [isHydrated, sessions, activeSessionId, activeProviderId, draft]);
+
+  useEffect(() => {
+    if (!isHydrated || loadingData || initializedRef.current) return;
+    if (providerGroups.length === 0) return;
+
+    const savedProvider = providerGroups.find((group) => group.providerId === activeProviderId) || providerGroups[0];
+    const savedModel = activeModelId && modelIndex.has(activeModelId)
+      ? modelIndex.get(activeModelId)
+      : savedProvider.models[0];
+
+    if (sessions.length > 0) {
+      const session = sessions.find((item) => item.id === activeSessionId) || sessions[0];
+      const sessionModel = session?.modelId && modelIndex.has(session.modelId)
+        ? modelIndex.get(session.modelId)
+        : savedModel;
+      initializedRef.current = true;
+      setActiveSessionId(session.id);
+      setActiveProviderId(sessionModel?.providerId || savedProvider.providerId);
+      setActiveModelId(sessionModel?.id || savedModel.id);
+      return;
+    }
+
+    const session = {
+      id: createId(),
+      title: "New chat",
+      providerId: savedProvider.providerId,
+      providerName: savedProvider.providerName,
+      modelId: savedModel.id,
+      modelName: savedModel.name,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      messages: [],
+    };
+
+    initializedRef.current = true;
+    setSessions([session]);
+    setActiveSessionId(session.id);
+    setActiveProviderId(savedProvider.providerId);
+    setActiveModelId(savedModel.id);
+  }, [isHydrated, loadingData, providerGroups, modelIndex, sessions, activeSessionId, activeProviderId, activeModelId]);
+
+  const updateSession = (sessionId, updater) => {
+    setSessions((prev) => prev.map((session) => (session.id === sessionId ? updater(cloneSession(session)) : session)));
+  };
+
+  const ensureSessionForModel = (model) => {
+    if (!model) return null;
+    return {
+      id: createId(),
+      title: "New chat",
+      providerId: model.providerId,
+      providerName: model.providerName,
+      modelId: model.id,
+      modelName: model.name,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      messages: [],
+    };
+  };
+
+  const handleNewChat = () => {
+    if (!activeModel) return;
+    const session = ensureSessionForModel(activeModel);
+    if (!session) return;
+    setSessions((prev) => [session, ...prev]);
+    setActiveSessionId(session.id);
+    setActiveProviderId(session.providerId);
+    setActiveModelId(session.modelId);
+    setDraft("");
+    setAttachments([]);
+    setStreamingMessageId("");
+    setStreamingText("");
+  };
+
+  const handleSelectSession = (sessionId) => {
+    const session = sessions.find((item) => item.id === sessionId);
+    if (!session) return;
+    setActiveSessionId(sessionId);
+    setActiveProviderId(session.providerId || activeProviderId);
+    setActiveModelId(session.modelId || activeModelId);
+    setHistoryOpen(false);
+  };
+
+  const handleDeleteCurrentChat = () => {
+    if (!activeSessionId) return;
+    const nextSessions = sessions.filter((session) => session.id !== activeSessionId);
+    const fallback = nextSessions[0] || null;
+    setSessions(nextSessions);
+    if (fallback) {
+      setActiveSessionId(fallback.id);
+      setActiveProviderId(fallback.providerId);
+      setActiveModelId(fallback.modelId);
+    } else {
+      setActiveSessionId("");
+      setActiveProviderId("");
+      setActiveModelId("");
+    }
+  };
+
+  const handleSelectProvider = (providerId) => {
+    const group = providerGroups.find((item) => item.providerId === providerId);
+    if (!group || group.models.length === 0) return;
+    const nextModel = group.models[0];
+
+    const current = sessions.find((session) => session.id === activeSessionId);
+    if (current && current.messages.length > 0) {
+      const session = ensureSessionForModel(nextModel);
+      if (!session) return;
+      setSessions((prev) => [session, ...prev]);
+      setActiveSessionId(session.id);
+    } else if (current) {
+      setSessions((prev) => prev.map((item) => (item.id === current.id ? {
+        ...item,
+        providerId: group.providerId,
+        providerName: group.providerName,
+        modelId: nextModel.id,
+        modelName: nextModel.name,
+      } : item)));
+      setActiveSessionId(current.id);
+    }
+
+    setActiveProviderId(group.providerId);
+    setActiveModelId(nextModel.id);
+    setModelMenuOpen(false);
+  };
+
+  const handleSelectModel = (modelId) => {
+    const model = modelIndex.get(modelId);
+    if (!model) return;
+
+    const current = sessions.find((session) => session.id === activeSessionId);
+    if (current && current.messages.length > 0) {
+      const session = ensureSessionForModel(model);
+      if (!session) return;
+      setSessions((prev) => [session, ...prev]);
+      setActiveSessionId(session.id);
+    } else if (current) {
+      setSessions((prev) => prev.map((item) => (item.id === current.id ? {
+        ...item,
+        providerId: model.providerId,
+        providerName: model.providerName,
+        modelId: model.id,
+        modelName: model.name,
+      } : item)));
+      setActiveSessionId(current.id);
+    } else {
+      const session = ensureSessionForModel(model);
+      if (!session) return;
+      setSessions((prev) => [session, ...prev]);
+      setActiveSessionId(session.id);
+    }
+
+    setActiveProviderId(model.providerId);
+    setActiveModelId(model.id);
+    setModelMenuOpen(false);
+  };
+
+  const handleAttachFiles = async (event) => {
+    const files = Array.from(event.target.files || []);
+    if (files.length === 0) return;
+
+    const images = files.filter((file) => file.type.startsWith("image/"));
+    if (images.length === 0) {
+      event.target.value = "";
+      return;
+    }
+
+    const converted = await Promise.all(images.map(async (file) => ({
+      id: createId(),
+      name: file.name,
+      type: file.type,
+      size: file.size,
+      dataUrl: await fileToDataUrl(file),
+    })));
+
+    setAttachments((prev) => [...prev, ...converted]);
+    event.target.value = "";
+  };
+
+  const removeAttachment = (attachmentId) => {
+    setAttachments((prev) => prev.filter((attachment) => attachment.id !== attachmentId));
+  };
+
+  const handleStop = () => {
+    abortRef.current?.abort();
+  };
+
+  const finalizeSessionTitle = (sessionId, titleSeed) => {
+    const title = makeSessionTitle(titleSeed);
+    updateSession(sessionId, (session) => ({
+      ...session,
+      title: session.title === "New chat" ? title : session.title,
+      updatedAt: new Date().toISOString(),
+    }));
+  };
+
+  const sendMessage = async () => {
+    const model = activeModel || activeProviderGroup?.models?.[0] || null;
+    if (!model) return;
+
+    const userText = draft.trim();
+    if (!userText && attachments.length === 0) return;
+
+    let sessionId = activeSessionId;
+    let session = sessions.find((item) => item.id === sessionId);
+    if (!session) {
+      session = ensureSessionForModel(model);
+      if (!session) return;
+      sessionId = session.id;
+      setSessions((prev) => [session, ...prev]);
+      setActiveSessionId(sessionId);
+    }
+
+    const userMessage = {
+      id: createId(),
+      role: "user",
+      content: userText,
+      attachments: attachments.map((attachment) => ({
+        id: attachment.id,
+        name: attachment.name,
+        type: attachment.type,
+        dataUrl: attachment.dataUrl,
+      })),
+      createdAt: new Date().toISOString(),
+    };
+
+    const assistantMessageId = createId();
+    const assistantMessage = {
+      id: assistantMessageId,
+      role: "assistant",
+      content: "",
+      createdAt: new Date().toISOString(),
+      status: "streaming",
+    };
+
+    const nextMessages = [...(session.messages || []), userMessage, assistantMessage];
+    setSessions((prev) => prev.map((item) => (item.id === sessionId ? {
+      ...item,
+      providerId: model.providerId,
+      providerName: model.providerName,
+      modelId: model.id,
+      modelName: model.name,
+      messages: nextMessages,
+      updatedAt: new Date().toISOString(),
+      title: item.title === "New chat" ? makeSessionTitle(userText) : item.title,
+    } : item)));
+    setDraft("");
+    setAttachments([]);
+    setIsSending(true);
+    setStreamingMessageId(assistantMessageId);
+    setStreamingText("");
+    abortRef.current?.abort();
+    abortRef.current = new AbortController();
+
+    const requestMessages = nextMessages
+      .filter((message) => !(message.role === "assistant" && message.id === assistantMessageId))
+      .map((message) => ({
+        role: message.role,
+        content: message.role === "user" ? buildUserContent(message) : message.content,
+      }));
+
+    try {
+      const response = await fetch("/api/dashboard/chat/completions", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "text/event-stream",
+        },
+        body: JSON.stringify({
+          model: model.requestModel || model.id,
+          messages: requestMessages,
+          stream: true,
+        }),
+        signal: abortRef.current.signal,
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new Error(textValue(errorData.error || errorData.message || `Request failed (${response.status})`));
+      }
+
+      const reader = response.body?.getReader();
+      if (!reader) {
+        const data = await response.json().catch(() => ({}));
+        const fallbackText = textValue(data?.choices?.[0]?.message?.content || data?.output_text || data?.error || data?.message || "");
+        updateSession(sessionId, (currentSession) => ({
+          ...currentSession,
+          messages: currentSession.messages.map((message) => (message.id === assistantMessageId ? { ...message, content: fallbackText, status: "done" } : message)),
+          updatedAt: new Date().toISOString(),
+        }));
+        return;
+      }
+
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let assistantText = "";
+
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split(/\r?\n/);
+        buffer = lines.pop() || "";
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith("data:")) continue;
+
+          const payload = trimmed.slice(5).trim();
+          if (!payload || payload === "[DONE]") continue;
+
+          try {
+            const chunk = JSON.parse(payload);
+            const text = readAssistantText(chunk);
+            if (!text) continue;
+
+            assistantText += text;
+            setStreamingText(assistantText);
+            updateSession(sessionId, (currentSession) => ({
+              ...currentSession,
+              messages: currentSession.messages.map((message) => (message.id === assistantMessageId ? { ...message, content: assistantText, status: "streaming" } : message)),
+              updatedAt: new Date().toISOString(),
+            }));
+          } catch {
+            // Ignore malformed chunks.
+          }
+        }
+      }
+
+      updateSession(sessionId, (currentSession) => ({
+        ...currentSession,
+        messages: currentSession.messages.map((message) => (message.id === assistantMessageId ? { ...message, content: assistantText || message.content, status: "done" } : message)),
+        updatedAt: new Date().toISOString(),
+      }));
+      finalizeSessionTitle(sessionId, userText);
+    } catch (error) {
+      if (error.name !== "AbortError") {
+        const errorText = textValue(error?.message || error);
+        updateSession(sessionId, (currentSession) => ({
+          ...currentSession,
+          messages: currentSession.messages.map((message) => (message.id === assistantMessageId ? { ...message, content: message.content || `Error: ${errorText}`, status: "error" } : message)),
+          updatedAt: new Date().toISOString(),
+        }));
+        setLoadError(errorText || "Failed to send message.");
+      }
+    } finally {
+      setIsSending(false);
+      setStreamingMessageId("");
+      setStreamingText("");
+      abortRef.current = null;
+    }
+  };
+
+  const handleKeyDown = (event) => {
+    if (event.key === "Enter" && !event.shiftKey) {
+      event.preventDefault();
+      if (canSend) sendMessage();
+    }
+  };
+
+  const modelLabel = activeModel ? `${activeModel.name}` : "Select model";
+  const modelSubLabel = activeModel ? activeModel.requestModel : "Choose from connected providers";
+
+  return (
+    <div className="relative flex-1 flex flex-col h-full min-h-0 min-w-0 bg-[#212121] text-white overflow-hidden">
+      <div className="relative mx-auto flex flex-1 h-full min-h-0 w-full max-w-4xl flex-col">
+        <div className="flex shrink-0 items-center justify-between gap-3 px-4 py-3 lg:px-6">
+          <div ref={modelMenuRef} className="relative">
+            <button
+              type="button"
+              onClick={() => setModelMenuOpen((value) => !value)}
+              className="flex items-center gap-3 rounded-2xl border border-white/10 bg-white/5 px-4 py-3 text-left transition hover:bg-white/8"
+            >
+              <div className="min-w-0">
+                <div className="flex items-center gap-2">
+                  <span className="text-sm font-semibold text-white">{modelLabel}</span>
+                  <span className="material-symbols-outlined text-[18px] text-white/70">expand_more</span>
+                </div>
+                <p className="truncate text-xs text-white/55">{modelSubLabel}</p>
+              </div>
+            </button>
+
+            {modelMenuOpen ? (
+              <div className="absolute left-0 top-[calc(100%+10px)] z-30 w-[min(520px,calc(100vw-2rem))] overflow-hidden rounded-[20px] border border-white/10 bg-[#262626] shadow-2xl shadow-black/50">
+                <div className="border-b border-white/10 px-4 py-3">
+                  <p className="text-xs uppercase tracking-[0.22em] text-white/45">Models</p>
+                  <p className="text-sm text-white/75">Only from connected providers</p>
+                </div>
+                <div className="max-h-[60vh] overflow-y-auto p-2 custom-scrollbar">
+                  {providerGroups.map((group) => (
+                    <div key={group.providerId} className="mb-2 rounded-[16px] border border-white/10 bg-black/20 p-2">
+                      <div className="flex items-center justify-between px-2 py-2">
+                        <p className="text-sm font-semibold text-white">{group.providerName}</p>
+                        <Badge size="sm" variant="default">{group.models.length}</Badge>
+                      </div>
+                      <div className="grid gap-2 sm:grid-cols-2">
+                        {group.models.map((model) => {
+                          const isActive = model.id === activeModelId;
+                          return (
+                            <button
+                              key={model.id}
+                              type="button"
+                              onClick={() => handleSelectModel(model.id)}
+                              className={`rounded-[14px] border px-3 py-3 text-left transition ${isActive ? "border-blue-400/40 bg-blue-500/15" : "border-white/10 bg-white/5 hover:bg-white/8"}`}
+                            >
+                              <div className="flex items-start justify-between gap-3">
+                                <div className="min-w-0">
+                                  <p className="truncate text-sm font-medium text-white">{model.name}</p>
+                                  <p className="truncate text-[11px] text-white/45">{model.requestModel}</p>
+                                </div>
+                                {isActive ? <span className="material-symbols-outlined text-[18px] text-blue-300">check_circle</span> : null}
+                              </div>
+                            </button>
+                          );
+                        })}
+                      </div>
+                    </div>
+                  ))}
+                </div>
+              </div>
+            ) : null}
+          </div>
+
+          <div className="flex items-center gap-2">
+            <button
+              type="button"
+              onClick={() => setHistoryOpen((value) => !value)}
+              className="rounded-2xl border border-white/10 bg-white/5 px-4 py-3 text-sm text-white/80 transition hover:bg-white/8"
+            >
+              History
+            </button>
+            <Button variant="ghost" size="sm" icon="delete" onClick={handleDeleteCurrentChat} disabled={!activeSessionId || sessions.length === 0}>
+              Clear
+            </Button>
+          </div>
+        </div>
+
+        {historyOpen ? (
+          <div ref={historyMenuRef} className="absolute right-4 top-[72px] z-20 w-[min(360px,calc(100vw-2rem))] rounded-[20px] border border-white/10 bg-[#262626] p-2 shadow-2xl shadow-black/50 lg:right-6">
+            <div className="px-3 py-2">
+              <p className="text-xs uppercase tracking-[0.22em] text-white/45">Recent chats</p>
+            </div>
+            <div className="max-h-[48vh] space-y-2 overflow-y-auto p-1 custom-scrollbar">
+              {sessionItems.length === 0 ? (
+                <div className="rounded-[16px] border border-dashed border-white/10 bg-white/5 p-4 text-sm text-white/55">
+                  No conversations yet.
+                </div>
+              ) : sessionItems.map((session) => {
+                const isActive = session.id === activeSessionId;
+                const latestMessage = [...(session.messages || [])].reverse().find((message) => message.role === "user") || session.messages?.[0];
+                return (
+                  <button
+                    key={session.id}
+                    type="button"
+                    onClick={() => handleSelectSession(session.id)}
+                    className={`w-full rounded-[16px] border px-3 py-3 text-left transition ${isActive ? "border-blue-400/40 bg-blue-500/15" : "border-white/10 bg-white/5 hover:bg-white/8"}`}
+                  >
+                    <div className="flex items-start justify-between gap-3">
+                      <div className="min-w-0 flex-1">
+                        <p className="truncate text-sm font-medium text-white">{session.title}</p>
+                        <p className="mt-1 truncate text-xs text-white/50">{textValue(latestMessage?.content) || "Empty chat"}</p>
+                      </div>
+                      <span className="text-[10px] text-white/40 shrink-0">{formatRelativeTime(session.updatedAt)}</span>
+                    </div>
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        ) : null}
+
+        {loadError ? (
+          <div className="mt-4 rounded-[18px] border border-rose-500/20 bg-rose-500/10 px-4 py-3 text-rose-100">
+            <div className="flex items-start gap-3">
+              <span className="material-symbols-outlined text-[20px]">error</span>
+              <p className="text-sm leading-6">{loadError}</p>
+            </div>
+          </div>
+        ) : null}
+
+        <div className="flex flex-1 flex-col min-h-0">
+          <div className="flex-1 overflow-y-auto py-4 custom-scrollbar">
+            {currentMessages.length === 0 ? (
+              <div className="flex min-h-[50vh] items-center justify-center px-4 text-center">
+                <div className="max-w-xl space-y-4">
+                  <div className="mx-auto flex size-16 items-center justify-center rounded-[20px] border border-white/10 bg-white/5 text-white/80">
+                    <span className="material-symbols-outlined text-[30px]">chat</span>
+                  </div>
+                  <div className="space-y-2">
+                    <h2 className="text-2xl font-semibold text-white">Start a conversation</h2>
+                    <p className="text-sm leading-6 text-white/60">
+                      Simple chat interface to interact with any AI model from connected providers. Select a model and start chatting!
+                    </p>
+                  </div>
+                </div>
+              </div>
+            ) : null}
+
+            <div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-4">
+              {currentMessages.map((message) => {
+                const isUser = message.role === "user";
+                const isAssistant = message.role === "assistant";
+                const isStreaming = isAssistant && message.id === streamingMessageId && message.status === "streaming";
+                const content = textValue(message.content) || (isAssistant ? streamingText : "");
+
+                return (
+                  <div key={message.id} className={`flex w-full ${isUser ? "justify-end" : "justify-start"} mb-6`}>
+                    <div className={`max-w-[min(88%,42rem)] ${isUser ? "rounded-3xl bg-[#2f2f2f] px-5 py-3.5 text-white" : "text-white/90"}`}>
+                      <div className="mb-1 flex items-center justify-between gap-3">
+                        <span className="text-xs font-semibold">{isUser ? "You" : activeModel?.name || "Assistant"}</span>
+                      </div>
+
+                      {message.attachments?.length ? (
+                        <div className="mb-3 grid grid-cols-2 gap-2 sm:grid-cols-3 mt-2">
+                          {message.attachments.map((attachment) => (
+                            <a key={attachment.id} href={attachment.dataUrl} target="_blank" rel="noreferrer" className="overflow-hidden rounded-[18px] border border-white/10 bg-black/20">
+                              <img src={attachment.dataUrl} alt={attachment.name} className="h-28 w-full object-cover" />
+                            </a>
+                          ))}
+                        </div>
+                      ) : null}
+
+                      <div className="whitespace-pre-wrap break-words text-[15px] leading-7">
+                        {content}
+                        {isAssistant && isStreaming && !streamingText ? <span className="inline-block animate-pulse">▋</span> : null}
+                      </div>
+                    </div>
+                  </div>
+                );
+              })}
+            </div>
+          </div>
+
+          <div className="shrink-0 pt-2">
+            {attachments.length > 0 ? (
+              <div className="mx-auto mb-3 flex w-full max-w-3xl flex-wrap gap-2 px-4">
+                {attachments.map((attachment) => (
+                  <div key={attachment.id} className="flex items-center gap-2 rounded-full border border-white/10 bg-white/5 px-3 py-2">
+                    <span className="text-xs text-white/80 max-w-[12rem] truncate">{attachment.name}</span>
+                    <button type="button" onClick={() => removeAttachment(attachment.id)} className="text-white/55 hover:text-white" aria-label="Remove attachment">
+                      <span className="material-symbols-outlined text-[18px]">close</span>
+                    </button>
+                  </div>
+                ))}
+              </div>
+            ) : null}
+
+            <div className="mx-auto w-full max-w-3xl px-4 pb-2">
+              <div className="rounded-[26px] bg-[#2f2f2f] px-3 pt-3 pb-2 shadow-[0_0_15px_rgba(0,0,0,0.10)] ring-1 ring-white/5">
+                <textarea
+                  value={draft}
+                  onChange={(event) => setDraft(event.target.value)}
+                  onKeyDown={handleKeyDown}
+                  placeholder="Message AI"
+                  rows={1}
+                  className="w-full resize-none bg-transparent px-2 text-[15px] leading-6 text-white outline-none placeholder:text-white/40 custom-scrollbar max-h-[25vh] overflow-y-auto"
+                />
+
+                <div className="mt-2 flex items-center justify-between gap-3">
+                  <div className="flex items-center gap-2">
+                    <button type="button" onClick={() => fileInputRef.current?.click()} disabled={!activeModel || loadingData} className="p-2 text-white/50 hover:text-white transition rounded-full hover:bg-white/5">
+                      <span className="material-symbols-outlined text-[20px]">attach_file</span>
+                    </button>
+                    <input ref={fileInputRef} type="file" accept="image/*" multiple className="hidden" onChange={handleAttachFiles} />
+                    <span className="text-xs font-medium text-white/30 truncate max-w-[120px]">{activeModel ? activeModel.name : "No model"}</span>
+                  </div>
+
+                  <div className="flex items-center gap-2">
+                    {isSending ? (
+                      <button type="button" onClick={handleStop} className="p-2 text-white bg-white/10 hover:bg-white/20 transition rounded-full h-8 w-8 flex items-center justify-center">
+                        <span className="material-symbols-outlined text-[16px]">stop</span>
+                      </button>
+                    ) : null}
+                    <button onClick={sendMessage} disabled={!canSend} className={`h-8 w-8 rounded-full flex items-center justify-center transition ${canSend ? 'bg-white text-black hover:opacity-90' : 'bg-white/10 text-white/30 cursor-not-allowed'}`}>
+                      <span className="material-symbols-outlined text-[16px]">arrow_upward</span>
+                    </button>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <p className="mx-auto mt-2 max-w-3xl px-4 pb-4 text-center text-[11px] text-white/30">
+            Model list is filtered from connected providers.
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/basic-chat/page.js b/src/app/(dashboard)/dashboard/basic-chat/page.js
new file mode 100644
index 0000000..19c5d87
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/basic-chat/page.js
@@ -0,0 +1,5 @@
+import BasicChatPageClient from "./BasicChatPageClient";
+
+export default function BasicChatPage() {
+  return <BasicChatPageClient />;
+}
\ No newline at end of file
diff --git a/src/app/(dashboard)/dashboard/cli-tools/CLIToolsPageClient.js b/src/app/(dashboard)/dashboard/cli-tools/CLIToolsPageClient.js
new file mode 100644
index 0000000..e8a5245
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/CLIToolsPageClient.js
@@ -0,0 +1,66 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { CardSkeleton } from "@/shared/components";
+import { CLI_TOOLS, MITM_TOOLS } from "@/shared/constants/cliTools";
+import { MitmLinkCard } from "./components";
+import ToolSummaryCard from "./components/ToolSummaryCard";
+
+const ALL_STATUSES_URL = "/api/cli-tools/all-statuses";
+
+export default function CLIToolsPageClient({ machineId }) {
+  const [loading, setLoading] = useState(true);
+  const [toolStatuses, setToolStatuses] = useState({});
+
+  useEffect(() => {
+    let mounted = true;
+    (async () => {
+      try {
+        const res = await fetch(ALL_STATUSES_URL);
+        if (res.ok && mounted) setToolStatuses(await res.json());
+      } catch (error) {
+        console.log("Error fetching tool statuses:", error);
+      } finally {
+        if (mounted) setLoading(false);
+      }
+    })();
+    return () => { mounted = false; };
+  }, []);
+
+  if (loading) {
+    return (
+      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3 sm:gap-4">
+        <CardSkeleton />
+        <CardSkeleton />
+        <CardSkeleton />
+        <CardSkeleton />
+        <CardSkeleton />
+        <CardSkeleton />
+      </div>
+    );
+  }
+
+  const regularTools = Object.entries(CLI_TOOLS);
+  const mitmTools = Object.entries(MITM_TOOLS);
+
+  return (
+    <div className="mx-auto flex w-full max-w-5xl flex-col gap-6 px-1 sm:px-0">
+      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3 sm:gap-4">
+        {regularTools.map(([toolId, tool]) => (
+          <ToolSummaryCard key={toolId} toolId={toolId} tool={tool} status={toolStatuses[toolId]} />
+        ))}
+      </div>
+      <div className="flex flex-col gap-3 sm:gap-4">
+        <div className="flex items-center gap-2 px-1">
+          <span className="material-symbols-outlined text-[18px] text-primary">security</span>
+          <h2 className="text-sm font-semibold text-text-main">MITM Tools</h2>
+        </div>
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3 sm:gap-4">
+          {mitmTools.map(([toolId, tool]) => (
+            <MitmLinkCard key={toolId} tool={tool} />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/[toolId]/ToolDetailClient.js b/src/app/(dashboard)/dashboard/cli-tools/[toolId]/ToolDetailClient.js
new file mode 100644
index 0000000..fa8d711
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/[toolId]/ToolDetailClient.js
@@ -0,0 +1,173 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import Link from "next/link";
+import { CardSkeleton } from "@/shared/components";
+import { CLI_TOOLS } from "@/shared/constants/cliTools";
+import { getModelsByProviderId, PROVIDER_ID_TO_ALIAS } from "@/shared/constants/models";
+import {
+  ClaudeToolCard, CodexToolCard, DroidToolCard, OpenClawToolCard,
+  HermesToolCard, DefaultToolCard, OpenCodeToolCard, CoworkToolCard,
+  CopilotToolCard, ClineToolCard, KiloToolCard, DeepSeekTuiToolCard,
+  JcodeToolCard,
+} from "../components";
+
+const CLOUD_URL = process.env.NEXT_PUBLIC_CLOUD_URL;
+
+export default function ToolDetailClient({ toolId, machineId }) {
+  const tool = CLI_TOOLS[toolId];
+  const [connections, setConnections] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [modelMappings, setModelMappings] = useState({});
+  const [cloudEnabled, setCloudEnabled] = useState(false);
+  const [tunnelEnabled, setTunnelEnabled] = useState(false);
+  const [tunnelPublicUrl, setTunnelPublicUrl] = useState("");
+  const [tailscaleEnabled, setTailscaleEnabled] = useState(false);
+  const [tailscaleUrl, setTailscaleUrl] = useState("");
+  const [apiKeys, setApiKeys] = useState([]);
+
+  useEffect(() => {
+    let mounted = true;
+    (async () => {
+      try {
+        const [provRes, settingsRes, tunnelRes, keysRes] = await Promise.all([
+          fetch("/api/providers"),
+          fetch("/api/settings"),
+          fetch("/api/tunnel/status"),
+          fetch("/api/keys"),
+        ]);
+        if (!mounted) return;
+        if (provRes.ok) {
+          const data = await provRes.json();
+          setConnections(data.connections || []);
+        }
+        if (settingsRes.ok) {
+          const data = await settingsRes.json();
+          setCloudEnabled(data.cloudEnabled || false);
+        }
+        if (tunnelRes.ok) {
+          const data = await tunnelRes.json();
+          setTunnelEnabled(!!(data.tunnel?.enabled || data.tunnel?.settingsEnabled));
+          setTunnelPublicUrl(data.tunnel?.publicUrl || "");
+          setTailscaleEnabled(!!(data.tailscale?.enabled || data.tailscale?.settingsEnabled));
+          setTailscaleUrl(data.tailscale?.tunnelUrl || "");
+        }
+        if (keysRes.ok) {
+          const data = await keysRes.json();
+          setApiKeys(data.keys || []);
+        }
+      } catch (error) {
+        console.log("Error loading tool data:", error);
+      } finally {
+        if (mounted) setLoading(false);
+      }
+    })();
+    return () => { mounted = false; };
+  }, []);
+
+  const getActiveProviders = () => connections.filter(c => c.isActive !== false);
+
+  const getAllAvailableModels = () => {
+    const activeProviders = getActiveProviders();
+    const models = [];
+    const seenModels = new Set();
+    activeProviders.forEach(conn => {
+      const alias = PROVIDER_ID_TO_ALIAS[conn.provider] || conn.provider;
+      const providerModels = getModelsByProviderId(conn.provider);
+      providerModels.forEach(m => {
+        const modelValue = `${alias}/${m.id}`;
+        if (!seenModels.has(modelValue)) {
+          seenModels.add(modelValue);
+          models.push({ value: modelValue, label: `${alias}/${m.id}`, provider: conn.provider, alias, connectionName: conn.name, modelId: m.id });
+        }
+      });
+    });
+    return models;
+  };
+
+  const handleModelMappingChange = useCallback((tId, alias, target) => {
+    setModelMappings(prev => {
+      if (prev[tId]?.[alias] === target) return prev;
+      return { ...prev, [tId]: { ...prev[tId], [alias]: target } };
+    });
+  }, []);
+
+  const getBaseUrl = () => {
+    if (tunnelEnabled && tunnelPublicUrl) return tunnelPublicUrl;
+    if (cloudEnabled && CLOUD_URL) return CLOUD_URL;
+    if (typeof window !== "undefined") return window.location.origin;
+    return "http://localhost:20128";
+  };
+
+  const renderToolCard = () => {
+    const availableModels = getAllAvailableModels();
+    const hasActiveProviders = availableModels.length > 0;
+    const commonProps = {
+      tool,
+      isExpanded: true,
+      onToggle: () => {},
+      baseUrl: getBaseUrl(),
+      apiKeys,
+      tunnelEnabled,
+      tunnelPublicUrl,
+      tailscaleEnabled,
+      tailscaleUrl,
+    };
+
+    switch (toolId) {
+      case "claude":
+        return <ClaudeToolCard {...commonProps} activeProviders={getActiveProviders()} modelMappings={modelMappings[toolId] || {}} onModelMappingChange={(a, t) => handleModelMappingChange(toolId, a, t)} hasActiveProviders={hasActiveProviders} cloudEnabled={cloudEnabled} />;
+      case "codex":
+        return <CodexToolCard {...commonProps} activeProviders={getActiveProviders()} cloudEnabled={cloudEnabled} />;
+      case "opencode":
+        return <OpenCodeToolCard {...commonProps} activeProviders={getActiveProviders()} cloudEnabled={cloudEnabled} />;
+      case "cowork":
+        return <CoworkToolCard {...commonProps} activeProviders={getActiveProviders()} hasActiveProviders={hasActiveProviders} cloudEnabled={cloudEnabled} cloudUrl={CLOUD_URL} tunnelEnabled={tunnelEnabled} tunnelPublicUrl={tunnelPublicUrl} tailscaleEnabled={tailscaleEnabled} tailscaleUrl={tailscaleUrl} />;
+      case "droid":
+        return <DroidToolCard {...commonProps} activeProviders={getActiveProviders()} hasActiveProviders={hasActiveProviders} cloudEnabled={cloudEnabled} />;
+      case "openclaw":
+        return <OpenClawToolCard {...commonProps} activeProviders={getActiveProviders()} hasActiveProviders={hasActiveProviders} cloudEnabled={cloudEnabled} />;
+      case "hermes":
+        return <HermesToolCard {...commonProps} activeProviders={getActiveProviders()} hasActiveProviders={hasActiveProviders} cloudEnabled={cloudEnabled} />;
+      case "copilot":
+        return <CopilotToolCard {...commonProps} activeProviders={getActiveProviders()} cloudEnabled={cloudEnabled} />;
+      case "cline":
+        return <ClineToolCard {...commonProps} activeProviders={getActiveProviders()} cloudEnabled={cloudEnabled} />;
+      case "kilo":
+        return <KiloToolCard {...commonProps} activeProviders={getActiveProviders()} cloudEnabled={cloudEnabled} />;
+      case "deepseek-tui":
+        return <DeepSeekTuiToolCard {...commonProps} activeProviders={getActiveProviders()} hasActiveProviders={hasActiveProviders} cloudEnabled={cloudEnabled} />;
+      case "jcode":
+        return <JcodeToolCard {...commonProps} activeProviders={getActiveProviders()} hasActiveProviders={hasActiveProviders} cloudEnabled={cloudEnabled} />;
+      default:
+        return <DefaultToolCard toolId={toolId} {...commonProps} activeProviders={getActiveProviders()} cloudEnabled={cloudEnabled} tunnelEnabled={tunnelEnabled} />;
+    }
+  };
+
+  // Guard removed/unknown tools (e.g. disabled Cowork) to avoid crash on direct URL.
+  if (!tool) {
+    return (
+      <div className="mx-auto flex w-full max-w-5xl flex-col gap-4 px-1 sm:px-0">
+        <Link href="/dashboard/cli-tools" className="inline-flex items-center gap-1 text-sm text-text-muted hover:text-primary w-fit">
+          <span className="material-symbols-outlined text-[18px]">arrow_back</span>
+          Back to CLI Tools
+        </Link>
+        <p className="text-sm text-text-muted">Tool not found or disabled.</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto flex w-full max-w-5xl flex-col gap-4 px-1 sm:px-0">
+      <Link href="/dashboard/cli-tools" className="inline-flex items-center gap-1 text-sm text-text-muted hover:text-primary w-fit">
+        <span className="material-symbols-outlined text-[18px]">arrow_back</span>
+        Back to CLI Tools
+      </Link>
+      <div className="flex flex-col gap-1">
+        <h1 className="text-xl font-semibold text-text-main sm:text-2xl">{tool.name}</h1>
+        <p className="text-sm text-text-muted">{tool.description}</p>
+      </div>
+      {loading ? <CardSkeleton /> : renderToolCard()}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/[toolId]/page.js b/src/app/(dashboard)/dashboard/cli-tools/[toolId]/page.js
new file mode 100644
index 0000000..1f904d4
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/[toolId]/page.js
@@ -0,0 +1,11 @@
+import { notFound } from "next/navigation";
+import { CLI_TOOLS } from "@/shared/constants/cliTools";
+import { getMachineId } from "@/shared/utils/machine";
+import ToolDetailClient from "./ToolDetailClient";
+
+export default async function ToolDetailPage({ params }) {
+  const { toolId } = await params;
+  if (!CLI_TOOLS[toolId]) notFound();
+  const machineId = await getMachineId();
+  return <ToolDetailClient toolId={toolId} machineId={machineId} />;
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/AntigravityToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/AntigravityToolCard.js
new file mode 100644
index 0000000..48962cc
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/AntigravityToolCard.js
@@ -0,0 +1,481 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card, Button, Badge, Modal, Input, ModelSelectModal } from "@/shared/components";
+import Image from "next/image";
+
+export default function AntigravityToolCard({
+  tool,
+  isExpanded,
+  onToggle,
+  baseUrl,
+  apiKeys,
+  activeProviders,
+  hasActiveProviders,
+  cloudEnabled,
+  initialStatus,
+}) {
+  const [status, setStatus] = useState(initialStatus || null);
+  const [loading, setLoading] = useState(false);
+  const [startingStep, setStartingStep] = useState(null); // "cert" | "server" | "dns" | null
+  const [showPasswordModal, setShowPasswordModal] = useState(false);
+  const [sudoPassword, setSudoPassword] = useState("");
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [message, setMessage] = useState(null);
+  const [modelMappings, setModelMappings] = useState({});
+  const [modalOpen, setModalOpen] = useState(false);
+  const [currentEditingAlias, setCurrentEditingAlias] = useState(null);
+  const [modelAliases, setModelAliases] = useState({});
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !status) {
+      fetchStatus();
+      loadSavedMappings();
+      fetchModelAliases();
+    }
+    if (isExpanded) {
+      loadSavedMappings();
+      fetchModelAliases();
+    }
+  }, [isExpanded]);
+
+  const loadSavedMappings = async () => {
+    try {
+      const res = await fetch("/api/cli-tools/antigravity-mitm/alias?tool=antigravity");
+      if (res.ok) {
+        const data = await res.json();
+        const aliases = data.aliases || {};
+
+        if (Object.keys(aliases).length > 0) {
+          setModelMappings(aliases);
+        }
+      }
+    } catch (error) {
+      console.log("Error loading saved mappings:", error);
+    }
+  };
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  const fetchStatus = async () => {
+    try {
+      const res = await fetch("/api/cli-tools/antigravity-mitm");
+      if (res.ok) {
+        const data = await res.json();
+        setStatus(data);
+      }
+    } catch (error) {
+      console.log("Error fetching status:", error);
+      setStatus({ running: false });
+    }
+  };
+
+  // MITM elevation is decided by the server OS, not by this browser's OS.
+  const serverIsWindows = status?.isWin === true;
+  const canRunWithoutPassword = serverIsWindows || status?.hasCachedPassword || status?.needsSudoPassword === false;
+
+  const handleStart = () => {
+    if (canRunWithoutPassword) {
+      doStart("");
+    } else {
+      setShowPasswordModal(true);
+      setMessage(null);
+    }
+  };
+
+  const handleStop = () => {
+    if (canRunWithoutPassword) {
+      doStop("");
+    } else {
+      setShowPasswordModal(true);
+      setMessage(null);
+    }
+  };
+
+  const doStart = async (password) => {
+    setLoading(true);
+    setMessage(null);
+    // Show steps progressing in order
+    setStartingStep("cert");
+    try {
+      const keyToUse = selectedApiKey?.trim()
+        || (apiKeys?.length > 0 ? apiKeys[0].key : null)
+        || (!cloudEnabled ? "sk_9router" : null);
+
+      const res = await fetch("/api/cli-tools/antigravity-mitm", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ apiKey: keyToUse, sudoPassword: password }),
+      });
+
+      const data = await res.json();
+      if (res.ok) {
+        setStartingStep(null);
+        setMessage({ type: "success", text: "MITM started" });
+        setShowPasswordModal(false);
+        setSudoPassword("");
+        fetchStatus();
+      } else {
+        setStartingStep(null);
+        setMessage({ type: "error", text: data.error || "Failed to start" });
+      }
+    } catch (error) {
+      setStartingStep(null);
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const doStop = async (password) => {
+    setLoading(true);
+    setMessage(null);
+    try {
+      const res = await fetch("/api/cli-tools/antigravity-mitm", {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ sudoPassword: password }),
+      });
+
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "MITM stopped" });
+        setShowPasswordModal(false);
+        setSudoPassword("");
+        fetchStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to stop" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleConfirmPassword = () => {
+    if (!sudoPassword.trim()) {
+      setMessage({ type: "error", text: "Sudo password is required" });
+      return;
+    }
+    if (status?.running) {
+      doStop(sudoPassword);
+    } else {
+      doStart(sudoPassword);
+    }
+  };
+
+  const openModelSelector = (alias) => {
+    setCurrentEditingAlias(alias);
+    setModalOpen(true);
+  };
+
+  const handleModelSelect = (model) => {
+    if (currentEditingAlias) {
+      setModelMappings(prev => ({
+        ...prev,
+        [currentEditingAlias]: model.value,
+      }));
+    }
+  };
+
+  const handleModelMappingChange = (alias, value) => {
+    setModelMappings(prev => ({
+      ...prev,
+      [alias]: value,
+    }));
+  };
+
+  const handleSaveMappings = async () => {
+    setLoading(true);
+    setMessage(null);
+
+    try {
+      const res = await fetch("/api/cli-tools/antigravity-mitm/alias", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ tool: "antigravity", mappings: modelMappings }),
+      });
+
+      if (!res.ok) {
+        const data = await res.json();
+        throw new Error(data.error || "Failed to save mappings");
+      }
+
+      setMessage({ type: "success", text: "Mappings saved!" });
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const isRunning = status?.running;
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image
+              src="/providers/antigravity.png"
+              alt={tool.name}
+              width={32}
+              height={32}
+              className="size-8 object-contain rounded-lg"
+              sizes="32px"
+              onError={(e) => { e.target.style.display = "none"; }}
+            />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {isRunning ? (
+                <Badge variant="success" size="sm">Active</Badge>
+              ) : (
+                <Badge variant="default" size="sm">Inactive</Badge>
+              )}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {/* Status indicators — ordered: Cert → Server → DNS */}
+          <div className="flex items-center gap-1">
+            {[
+              { key: "cert", label: "Cert", ok: status?.certExists },
+              { key: "server", label: "Server", ok: status?.running },
+              { key: "dns", label: "DNS", ok: status?.dnsConfigured },
+            ].map(({ key, label, ok }, i) => {
+              const isLoading = startingStep === key;
+              return (
+                <div key={key} className="flex items-center">
+                  <div className="flex items-center gap-1 px-2 py-1 rounded-md">
+                    {isLoading ? (
+                      <span className="material-symbols-outlined text-[14px] text-primary animate-spin">progress_activity</span>
+                    ) : (
+                      <span className={`material-symbols-outlined text-[14px] ${ok ? "text-green-500" : "text-text-muted"}`}>
+                        {ok ? "check_circle" : "radio_button_unchecked"}
+                      </span>
+                    )}
+                    <span className={`text-xs font-medium ${isLoading ? "text-primary" : ok ? "text-green-500" : "text-text-muted"}`}>
+                      {label}
+                    </span>
+                  </div>
+                  {i < 2 && <span className="material-symbols-outlined text-[12px] text-text-muted">arrow_forward</span>}
+                </div>
+              );
+            })}
+          </div>
+
+          {/* Start/Stop Button */}
+          <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+            {isRunning ? (
+              <button
+                onClick={handleStop}
+                disabled={loading}
+                className="px-4 py-2 rounded-lg bg-red-500/10 border border-red-500/30 text-red-500 font-medium text-sm flex items-center gap-2 hover:bg-red-500/20 transition-colors disabled:opacity-50"
+              >
+                <span className="material-symbols-outlined text-[18px]">stop_circle</span>
+                Stop MITM
+              </button>
+            ) : (
+              <button
+                onClick={handleStart}
+                disabled={loading || !hasActiveProviders}
+                className="px-4 py-2 rounded-lg bg-primary/10 border border-primary/30 text-primary font-medium text-sm flex items-center gap-2 hover:bg-primary/20 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+              >
+                <span className="material-symbols-outlined text-[18px]">play_circle</span>
+                Start MITM
+              </button>
+            )}
+          </div>
+
+          {message?.type === "error" && (
+            <div className="flex items-center gap-2 px-2 py-1.5 rounded text-xs bg-red-500/10 text-red-600">
+              <span className="material-symbols-outlined text-[14px]">error</span>
+              <span>{message.text}</span>
+            </div>
+          )}
+
+          {/* When running: API Key + Model Mappings */}
+          {isRunning && (
+            <>
+              <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                {apiKeys.length > 0 ? (
+                  <select
+                    value={selectedApiKey}
+                    onChange={(e) => setSelectedApiKey(e.target.value)}
+                    className="w-full min-w-0 px-2 py-2 bg-surface rounded text-xs border border-border focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5"
+                  >
+                    {apiKeys.map((key) => <option key={key.id} value={key.key}>{key.key}</option>)}
+                  </select>
+                ) : (
+                  <span className="min-w-0 rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                    {cloudEnabled ? "No API keys - Create one in Keys page" : "sk_9router (default)"}
+                  </span>
+                )}
+              </div>
+
+              {tool.defaultModels.map((model) => (
+                <div key={model.alias} className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">{model.name}</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <div className="relative w-full min-w-0">
+                    <input
+                      type="text"
+                      value={modelMappings[model.alias] || ""}
+                      onChange={(e) => handleModelMappingChange(model.alias, e.target.value)}
+                      placeholder="provider/model-id"
+                      className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5"
+                    />
+                    {modelMappings[model.alias] && (
+                      <button
+                        onClick={() => handleModelMappingChange(model.alias, "")}
+                        className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors"
+                        title="Clear"
+                      >
+                        <span className="material-symbols-outlined text-[14px]">close</span>
+                      </button>
+                    )}
+                  </div>
+                  <button
+                    onClick={() => openModelSelector(model.alias)}
+                    disabled={!hasActiveProviders}
+                    className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${hasActiveProviders ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}
+                  >
+                    Select
+                  </button>
+                </div>
+              ))}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button
+                  variant="primary"
+                  size="sm"
+                  onClick={handleSaveMappings}
+                  disabled={loading || Object.keys(modelMappings).length === 0}
+                >
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>
+                  Save Mappings
+                </Button>
+              </div>
+            </>
+          )}
+
+          {/* Windows admin warning */}
+          {!isRunning && serverIsWindows && (
+            <div className="flex items-center gap-2 px-2 py-1.5 rounded text-xs bg-yellow-500/10 text-yellow-600 border border-yellow-500/20">
+              <span className="material-symbols-outlined text-[14px]">warning</span>
+              <span>Windows: Run terminal (9Router) as Administrator to enable MITM</span>
+            </div>
+          )}
+
+          {/* When stopped: how it works */}
+          {!isRunning && (
+            <div className="flex flex-col gap-1.5 px-1">
+              <p className="text-xs text-text-muted">
+                <span className="font-medium text-text-main">How it works:</span> Intercepts Antigravity traffic via DNS redirect, letting you reroute models through 9Router.
+              </p>
+              <div className="flex flex-col gap-0.5 text-[11px] text-text-muted">
+                <span>1. Generates SSL cert & adds to system keychain</span>
+                <span>2. Redirects <code className="text-[10px] bg-surface px-1 rounded">daily-cloudcode-pa.googleapis.com</code> → localhost</span>
+                <span>3. Maps Antigravity models to any provider via 9Router</span>
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Password Modal */}
+      <Modal
+        isOpen={showPasswordModal}
+        onClose={() => {
+          setShowPasswordModal(false);
+          setSudoPassword("");
+          setMessage(null);
+        }}
+        title="Sudo Password Required"
+        size="sm"
+      >
+        <div className="flex flex-col gap-4">
+          <div className="flex items-start gap-3 p-3 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+            <span className="material-symbols-outlined text-yellow-500 text-[20px]">warning</span>
+            <p className="text-xs text-text-muted">Required for SSL certificate and DNS configuration</p>
+          </div>
+
+          <Input
+            type="password"
+            placeholder="Enter sudo password"
+            value={sudoPassword}
+            onChange={(e) => setSudoPassword(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && !loading) handleConfirmPassword();
+            }}
+          />
+
+          {message && (
+            <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+              <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+              <span>{message.text}</span>
+            </div>
+          )}
+
+          <div className="flex items-center justify-end gap-2">
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => { setShowPasswordModal(false); setSudoPassword(""); setMessage(null); }}
+              disabled={loading}
+            >
+              Cancel
+            </Button>
+            <Button
+              variant="primary"
+              size="sm"
+              onClick={handleConfirmPassword}
+              loading={loading}
+            >
+              Confirm
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      {/* Model Select Modal */}
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => setModalOpen(false)}
+        onSelect={handleModelSelect}
+        selectedModel={currentEditingAlias ? modelMappings[currentEditingAlias] : null}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title={`Select model for ${currentEditingAlias}`}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/ApiKeySelect.js b/src/app/(dashboard)/dashboard/cli-tools/components/ApiKeySelect.js
new file mode 100644
index 0000000..e0f24f3
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/ApiKeySelect.js
@@ -0,0 +1,66 @@
+"use client";
+
+import { useState } from "react";
+
+const CUSTOM_VALUE = "__custom__";
+
+export default function ApiKeySelect({ value, onChange, apiKeys = [], cloudEnabled = false, className = "" }) {
+  const isCustom = !apiKeys.some((k) => k.key === value) && value !== "";
+  const [mode, setMode] = useState(() => {
+    if (!value) return apiKeys.length > 0 ? apiKeys[0].key : CUSTOM_VALUE;
+    if (apiKeys.some((k) => k.key === value)) return value;
+    return CUSTOM_VALUE;
+  });
+  const [customInput, setCustomInput] = useState(isCustom ? value : "");
+
+  const handleSelect = (e) => {
+    const next = e.target.value;
+    setMode(next);
+    if (next === CUSTOM_VALUE) {
+      setCustomInput("");
+      onChange("");
+    } else {
+      onChange(next);
+    }
+  };
+
+  const handleCustomInput = (e) => {
+    const v = e.target.value;
+    setCustomInput(v);
+    onChange(v);
+  };
+
+  const noKeys = apiKeys.length === 0 && mode !== CUSTOM_VALUE;
+
+  if (noKeys && mode !== CUSTOM_VALUE) {
+    return (
+      <span className={`min-w-0 rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5 ${className}`}>
+        {cloudEnabled ? "No API keys - Create one in Keys page" : "sk_9router (default)"}
+      </span>
+    );
+  }
+
+  return (
+    <div className={`flex flex-col gap-1.5 ${className}`}>
+      <select
+        value={mode}
+        onChange={handleSelect}
+        className="w-full min-w-0 px-2 py-2 bg-surface rounded text-xs border border-border focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5"
+      >
+        {apiKeys.map((k) => (
+          <option key={k.id} value={k.key}>{k.key}</option>
+        ))}
+        <option value={CUSTOM_VALUE}>Custom...</option>
+      </select>
+      {mode === CUSTOM_VALUE && (
+        <input
+          type="text"
+          value={customInput}
+          onChange={handleCustomInput}
+          placeholder="sk-..."
+          className="w-full min-w-0 px-2 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5"
+        />
+      )}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/BaseUrlSelect.js b/src/app/(dashboard)/dashboard/cli-tools/components/BaseUrlSelect.js
new file mode 100644
index 0000000..58482a9
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/BaseUrlSelect.js
@@ -0,0 +1,174 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { UPDATER_CONFIG } from "@/shared/constants/config";
+
+const STORAGE_KEY = "9router.cliToolEndpointPresets";
+const CUSTOM_VALUE = "__custom__";
+const SAVE_VALUE = "__save__";
+
+const ensureV1 = (url) => {
+  const trimmed = (url || "").replace(/\/+$/, "");
+  if (!trimmed) return "";
+  return /\/v1$/.test(trimmed) ? trimmed : `${trimmed}/v1`;
+};
+
+const readSavedPresets = () => {
+  if (typeof window === "undefined") return [];
+  try {
+    const raw = JSON.parse(window.localStorage.getItem(STORAGE_KEY) || "[]");
+    if (!Array.isArray(raw)) return [];
+    return raw.filter((p) => p?.name && p?.baseUrl);
+  } catch {
+    return [];
+  }
+};
+
+const writeSavedPresets = (presets) => {
+  if (typeof window === "undefined") return;
+  window.localStorage.setItem(STORAGE_KEY, JSON.stringify(presets));
+};
+
+const buildOptions = ({ requiresExternalUrl, tunnelEnabled, tunnelPublicUrl, tailscaleEnabled, tailscaleUrl, cloudEnabled, cloudUrl, savedPresets, withV1 }) => {
+  const opts = [];
+  const wrap = (url) => (withV1 ? ensureV1(url) : (url || "").replace(/\/+$/, ""));
+  if (!requiresExternalUrl) {
+    const localUrl = wrap(`http://127.0.0.1:${UPDATER_CONFIG.appPort}`);
+    opts.push({ value: "local", label: localUrl, url: localUrl });
+  }
+  if (tunnelEnabled && tunnelPublicUrl) {
+    const u = wrap(tunnelPublicUrl);
+    opts.push({ value: "tunnel", label: u, url: u });
+  }
+  if (tailscaleEnabled && tailscaleUrl) {
+    const u = wrap(tailscaleUrl);
+    opts.push({ value: "tailscale", label: u, url: u });
+  }
+  if (cloudEnabled && cloudUrl) {
+    const u = wrap(cloudUrl);
+    opts.push({ value: "cloud", label: u, url: u });
+  }
+  savedPresets.forEach((p) => {
+    opts.push({ value: `saved:${p.name}`, label: p.baseUrl, url: p.baseUrl, saved: true });
+  });
+  opts.push({ value: CUSTOM_VALUE, label: "Custom URL...", url: "" });
+  return opts;
+};
+
+export default function BaseUrlSelect({
+  value,
+  onChange,
+  requiresExternalUrl = false,
+  tunnelEnabled = false,
+  tunnelPublicUrl = "",
+  tailscaleEnabled = false,
+  tailscaleUrl = "",
+  cloudEnabled = false,
+  cloudUrl = "",
+  withV1 = true,
+}) {
+  const [savedPresets, setSavedPresets] = useState([]);
+  const [mode, setMode] = useState("");
+  const [customInput, setCustomInput] = useState("");
+  const initializedRef = useRef(false);
+
+  useEffect(() => {
+    setSavedPresets(readSavedPresets());
+  }, []);
+
+  const options = useMemo(
+    () => buildOptions({ requiresExternalUrl, tunnelEnabled, tunnelPublicUrl, tailscaleEnabled, tailscaleUrl, cloudEnabled, cloudUrl, savedPresets, withV1 }),
+    [requiresExternalUrl, tunnelEnabled, tunnelPublicUrl, tailscaleEnabled, tailscaleUrl, cloudEnabled, cloudUrl, savedPresets, withV1]
+  );
+
+  // Always default to first option (127.0.0.1) on mount, ignore persisted value
+  useEffect(() => {
+    if (initializedRef.current) return;
+    if (options.length === 0) return;
+    initializedRef.current = true;
+    const first = options.find((o) => o.value !== CUSTOM_VALUE);
+    if (first) {
+      setMode(first.value);
+      onChange(first.url);
+    } else {
+      setMode(CUSTOM_VALUE);
+    }
+  }, [options, onChange]);
+
+  const handleSelect = (e) => {
+    const next = e.target.value;
+    if (next === SAVE_VALUE) {
+      const trimmed = (value || "").trim();
+      if (!trimmed) return;
+      let defaultName = trimmed;
+      try { defaultName = new URL(trimmed).host; } catch {}
+      const name = window.prompt("Save endpoint as:", defaultName);
+      if (!name?.trim()) return;
+      const updated = [...savedPresets.filter((p) => p.name !== name.trim()), { name: name.trim(), baseUrl: trimmed }]
+        .sort((a, b) => a.name.localeCompare(b.name));
+      setSavedPresets(updated);
+      writeSavedPresets(updated);
+      return;
+    }
+    setMode(next);
+    if (next === CUSTOM_VALUE) {
+      setCustomInput("");
+      onChange("");
+      return;
+    }
+    const opt = options.find((o) => o.value === next);
+    if (opt) onChange(opt.url);
+  };
+
+  const handleCustomInput = (e) => {
+    const v = e.target.value;
+    setCustomInput(v);
+    onChange(v);
+  };
+
+  const handleDeleteSaved = () => {
+    if (!mode.startsWith("saved:")) return;
+    const name = mode.slice(6);
+    const updated = savedPresets.filter((p) => p.name !== name);
+    setSavedPresets(updated);
+    writeSavedPresets(updated);
+    setMode(CUSTOM_VALUE);
+    setCustomInput("");
+    onChange("");
+  };
+
+  const isSaved = mode.startsWith("saved:");
+  const isCustom = mode === CUSTOM_VALUE;
+  const canSave = isCustom && (customInput || "").trim().length > 0;
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      <div className="flex items-center gap-2">
+        <select
+          value={mode}
+          onChange={handleSelect}
+          className="flex-1 min-w-0 px-2 py-2 bg-surface rounded text-xs border border-border focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5"
+        >
+          {options.map((o) => (
+            <option key={o.value} value={o.value}>{o.label}</option>
+          ))}
+          {canSave && <option value={SAVE_VALUE}>+ Save current as...</option>}
+        </select>
+        {isSaved && (
+          <button type="button" onClick={handleDeleteSaved} className="p-1 text-text-muted hover:text-red-500 rounded transition-colors shrink-0" title="Delete saved endpoint">
+            <span className="material-symbols-outlined text-[14px]">delete</span>
+          </button>
+        )}
+      </div>
+      {isCustom && (
+        <input
+          type="text"
+          value={customInput}
+          onChange={handleCustomInput}
+          placeholder={withV1 ? "https://example.com/v1" : "https://example.com"}
+          className="w-full min-w-0 px-2 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5"
+        />
+      )}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/ClaudeToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/ClaudeToolCard.js
new file mode 100644
index 0000000..589d847
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/ClaudeToolCard.js
@@ -0,0 +1,390 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal, Tooltip } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+const CLOUD_URL = process.env.NEXT_PUBLIC_CLOUD_URL;
+
+export default function ClaudeToolCard({
+  tool,
+  isExpanded,
+  onToggle,
+  activeProviders,
+  modelMappings,
+  onModelMappingChange,
+  baseUrl,
+  hasActiveProviders,
+  apiKeys,
+  cloudEnabled,
+  initialStatus,
+  tunnelEnabled,
+  tunnelPublicUrl,
+  tailscaleEnabled,
+  tailscaleUrl,
+}) {
+  const [claudeStatus, setClaudeStatus] = useState(initialStatus || null);
+  const [checkingClaude, setCheckingClaude] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [showInstallGuide, setShowInstallGuide] = useState(false);
+  const [modalOpen, setModalOpen] = useState(false);
+  const [currentEditingAlias, setCurrentEditingAlias] = useState(null);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+  const [ccFilterNaming, setCcFilterNaming] = useState(false);
+  const hasInitializedModels = useRef(false);
+
+  const getConfigStatus = () => {
+    if (!claudeStatus?.installed) return null;
+    const currentUrl = claudeStatus.settings?.env?.ANTHROPIC_BASE_URL;
+    if (!currentUrl) return "not_configured";
+    if (matchKnownEndpoint(currentUrl, { tunnelPublicUrl, tailscaleUrl, cloudUrl: cloudEnabled ? CLOUD_URL : null })) return "configured";
+    return "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setClaudeStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !claudeStatus) {
+      checkClaudeStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  useEffect(() => {
+    fetch("/api/settings").then(r => r.json()).then(data => {
+      setCcFilterNaming(!!data.ccFilterNaming);
+    }).catch(() => {});
+  }, []);
+
+  const handleCcFilterNamingToggle = async (e) => {
+    const value = e.target.checked;
+    setCcFilterNaming(value);
+    await fetch("/api/settings", {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ ccFilterNaming: value }),
+    }).catch(() => {});
+  };
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  useEffect(() => {
+    if (claudeStatus?.installed && !hasInitializedModels.current) {
+      hasInitializedModels.current = true;
+      const env = claudeStatus.settings?.env || {};
+
+      tool.defaultModels.forEach((model) => {
+        if (model.envKey) {
+          const value = env[model.envKey] || model.defaultValue || "";
+          // Only sync initial values from file once
+          if (value) {
+            onModelMappingChange(model.alias, value);
+          }
+        }
+      });
+      // Only set selectedApiKey if it exists in apiKeys list
+      const tokenFromFile = env.ANTHROPIC_AUTH_TOKEN;
+      if (tokenFromFile && apiKeys?.some(k => k.key === tokenFromFile)) {
+        setSelectedApiKey(tokenFromFile);
+      }
+    }
+  }, [claudeStatus, apiKeys, tool.defaultModels, onModelMappingChange]);
+
+  const checkClaudeStatus = async () => {
+    setCheckingClaude(true);
+    try {
+      const res = await fetch("/api/cli-tools/claude-settings");
+      const data = await res.json();
+      setClaudeStatus(data);
+    } catch (error) {
+      setClaudeStatus({ installed: false, error: error.message });
+    } finally {
+      setCheckingClaude(false);
+    }
+  };
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || baseUrl;
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const getDisplayUrl = () => {
+    const url = customBaseUrl || baseUrl;
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const handleApplySettings = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      const env = { ANTHROPIC_BASE_URL: getEffectiveBaseUrl() };
+
+      // Get key from dropdown, fallback to first key or sk_9router for localhost
+      const keyToUse = selectedApiKey?.trim()
+        || (apiKeys?.length > 0 ? apiKeys[0].key : null)
+        || (!cloudEnabled ? "sk_9router" : null);
+
+      if (keyToUse) {
+        env.ANTHROPIC_AUTH_TOKEN = keyToUse;
+      }
+
+      tool.defaultModels.forEach((model) => {
+        const targetModel = modelMappings[model.alias];
+        if (targetModel && model.envKey) env[model.envKey] = targetModel;
+      });
+      const res = await fetch("/api/cli-tools/claude-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ env }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied successfully!" });
+        setClaudeStatus(prev => ({ ...prev, hasBackup: true, settings: { ...prev?.settings, env } }));
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleResetSettings = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch("/api/cli-tools/claude-settings", { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        tool.defaultModels.forEach((model) => onModelMappingChange(model.alias, model.defaultValue || ""));
+        setSelectedApiKey("");
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const openModelSelector = (alias) => {
+    setCurrentEditingAlias(alias);
+    setModalOpen(true);
+  };
+
+  const handleModelSelect = (model) => {
+    if (currentEditingAlias) onModelMappingChange(currentEditingAlias, model.value);
+  };
+
+  // Generate settings.json content for manual copy
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+    const env = { ANTHROPIC_BASE_URL: getEffectiveBaseUrl(), ANTHROPIC_AUTH_TOKEN: keyToUse };
+    tool.defaultModels.forEach((model) => {
+      const targetModel = modelMappings[model.alias];
+      if (targetModel && model.envKey) env[model.envKey] = targetModel;
+    });
+
+    return [
+      {
+        filename: "~/.claude/settings.json",
+        content: JSON.stringify({ hasCompletedOnboarding: true, env }, null, 2),
+      },
+    ];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src="/providers/claude.png" alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checkingClaude && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking Claude CLI...</span>
+            </div>
+          )}
+
+          {!checkingClaude && claudeStatus && !claudeStatus.installed && (
+            <div className="flex flex-col gap-4">
+              <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+                <div className="flex items-start gap-3">
+                  <span className="material-symbols-outlined text-yellow-500">warning</span>
+                  <div className="flex-1">
+                    <p className="font-medium text-yellow-600 dark:text-yellow-400">Claude CLI not detected locally</p>
+                    <p className="text-sm text-text-muted">Manual configuration is still available if 9router is deployed on a remote server.</p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-2 pl-9">
+                  <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="!bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                    <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                    Manual Config
+                  </Button>
+                  <Button variant="outline" size="sm" onClick={() => setShowInstallGuide(!showInstallGuide)}>
+                    <span className="material-symbols-outlined text-[18px] mr-1">{showInstallGuide ? "expand_less" : "help"}</span>
+                    {showInstallGuide ? "Hide" : "How to Install"}
+                  </Button>
+                </div>
+              </div>
+              {showInstallGuide && (
+                <div className="p-4 bg-surface border border-border rounded-lg">
+                  <h4 className="font-medium mb-3">Installation Guide</h4>
+                  <div className="space-y-3 text-sm">
+                    <div>
+                      <p className="text-text-muted mb-1">macOS / Linux / Windows:</p>
+                      <code className="block px-3 py-2 bg-black/5 dark:bg-white/5 rounded font-mono text-xs">npm install -g @anthropic-ai/claude-code</code>
+                    </div>
+                    <p className="text-text-muted">After installation, run <code className="px-1 bg-black/5 dark:bg-white/5 rounded">claude</code> to verify.</p>
+                  </div>
+                </div>
+              )}
+            </div>
+          )}
+
+          {!checkingClaude && claudeStatus?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                {/* Endpoint (selector) */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getDisplayUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                {/* Current configured */}
+                {claudeStatus?.settings?.env?.ANTHROPIC_BASE_URL && (
+                  <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Current</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <span className="min-w-0 truncate rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                      {claudeStatus.settings.env.ANTHROPIC_BASE_URL}
+                    </span>
+                  </div>
+                )}
+
+                {/* API Key */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                {/* Model Mappings */}
+                {tool.defaultModels.map((model) => (
+                  <div key={model.alias} className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">{model.name}</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <div className="relative w-full min-w-0">
+                      <input type="text" value={modelMappings[model.alias] || ""} onChange={(e) => onModelMappingChange(model.alias, e.target.value)} placeholder="provider/model-id" className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5" />
+                      {modelMappings[model.alias] && <button onClick={() => onModelMappingChange(model.alias, "")} className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors" title="Clear"><span className="material-symbols-outlined text-[14px]">close</span></button>}
+                    </div>
+                    <button onClick={() => openModelSelector(model.alias)} disabled={!hasActiveProviders} className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${hasActiveProviders ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Select Model</button>
+                  </div>
+                ))}
+
+                {/* CC Filter Naming */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Filter naming</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <label className="flex items-center gap-1.5 cursor-pointer select-none">
+                    <input type="checkbox" checked={ccFilterNaming} onChange={handleCcFilterNamingToggle} className="w-3.5 h-3.5 accent-primary cursor-pointer" />
+                    <span className="text-xs text-text-muted">Filter naming requests</span>
+                    <Tooltip text="Intercepts Claude Code's topic-naming requests and returns a fake response locally, saving API tokens.">
+                      <span className="material-symbols-outlined text-text-muted text-[14px] cursor-help">info</span>
+                    </Tooltip>
+                  </label>
+                </div>
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button variant="primary" size="sm" onClick={handleApplySettings} disabled={!hasActiveProviders} loading={applying}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleResetSettings} disabled={!claudeStatus?.has9Router} loading={restoring}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal isOpen={modalOpen} onClose={() => setModalOpen(false)} onSelect={handleModelSelect} selectedModel={currentEditingAlias ? modelMappings[currentEditingAlias] : null} activeProviders={activeProviders} modelAliases={modelAliases} title={`Select model for ${currentEditingAlias}`} />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="Claude CLI - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/ClineToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/ClineToolCard.js
new file mode 100644
index 0000000..41fd0b1
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/ClineToolCard.js
@@ -0,0 +1,301 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+export default function ClineToolCard({ tool, isExpanded, onToggle, baseUrl, apiKeys, activeProviders, cloudEnabled, initialStatus, tunnelEnabled, tunnelPublicUrl, tailscaleEnabled, tailscaleUrl }) {
+  const [status, setStatus] = useState(initialStatus || null);
+  const [checking, setChecking] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [showInstallGuide, setShowInstallGuide] = useState(false);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [selectedModel, setSelectedModel] = useState("");
+  const [modalOpen, setModalOpen] = useState(false);
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) setSelectedApiKey(apiKeys[0].key);
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !status) {
+      checkStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  useEffect(() => {
+    if (status?.settings?.openAiModelId) setSelectedModel(status.settings.openAiModelId);
+  }, [status]);
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  const getConfigStatus = () => {
+    if (!status?.installed) return null;
+    if (!status.has9Router) return "not_configured";
+    const url = status.settings?.openAiBaseUrl || "";
+    return matchKnownEndpoint(url, { tunnelPublicUrl, tailscaleUrl }) ? "configured" : "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || `${baseUrl}/v1`;
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const getDisplayUrl = () => customBaseUrl || `${baseUrl}/v1`;
+
+  const checkStatus = async () => {
+    setChecking(true);
+    try {
+      const res = await fetch("/api/cli-tools/cline-settings");
+      const data = await res.json();
+      setStatus(data);
+    } catch (error) {
+      setStatus({ installed: false, error: error.message });
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  const handleApply = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      const keyToUse = (selectedApiKey && selectedApiKey.trim())
+        ? selectedApiKey
+        : (!cloudEnabled ? "sk_9router" : selectedApiKey);
+
+      const res = await fetch("/api/cli-tools/cline-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ baseUrl: getEffectiveBaseUrl(), apiKey: keyToUse, model: selectedModel }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied successfully!" });
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleReset = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch("/api/cli-tools/cline-settings", { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        setSelectedModel("");
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+    const effectiveUrl = getEffectiveBaseUrl();
+    const baseWithoutV1 = effectiveUrl.endsWith("/v1") ? effectiveUrl.slice(0, -3) : effectiveUrl;
+
+    return [
+      {
+        filename: "~/.cline/data/globalState.json",
+        content: JSON.stringify({
+          actModeApiProvider: "openai",
+          planModeApiProvider: "openai",
+          openAiBaseUrl: baseWithoutV1,
+          openAiModelId: selectedModel || "provider/model-id",
+          planModeOpenAiModelId: selectedModel || "provider/model-id",
+        }, null, 2),
+      },
+      {
+        filename: "~/.cline/data/secrets.json",
+        content: JSON.stringify({ openAiApiKey: keyToUse }, null, 2),
+      },
+    ];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src="/providers/cline.png" alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checking && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking Cline...</span>
+            </div>
+          )}
+
+          {!checking && status && !status.installed && (
+            <div className="flex flex-col gap-4">
+              <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+                <div className="flex items-start gap-3">
+                  <span className="material-symbols-outlined text-yellow-500">warning</span>
+                  <div className="flex-1">
+                    <p className="font-medium text-yellow-600 dark:text-yellow-400">Cline not detected locally</p>
+                    <p className="text-sm text-text-muted">Manual configuration is still available if 9router is deployed on a remote server.</p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-2 pl-9">
+                  <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="!bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                    <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                    Manual Config
+                  </Button>
+                  <Button variant="outline" size="sm" onClick={() => setShowInstallGuide(!showInstallGuide)}>
+                    <span className="material-symbols-outlined text-[18px] mr-1">{showInstallGuide ? "expand_less" : "help"}</span>
+                    {showInstallGuide ? "Hide" : "How to Install"}
+                  </Button>
+                </div>
+              </div>
+              {showInstallGuide && (
+                <div className="p-4 bg-surface border border-border rounded-lg">
+                  <h4 className="font-medium mb-3">Installation Guide</h4>
+                  <div className="space-y-3 text-sm">
+                    <p className="text-text-muted">Install Cline VS Code extension or CLI from <a className="text-primary underline" href="https://docs.cline.bot/" target="_blank" rel="noreferrer">docs.cline.bot</a>.</p>
+                  </div>
+                </div>
+              )}
+            </div>
+          )}
+
+          {!checking && status?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getDisplayUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                {status?.settings?.openAiBaseUrl && (
+                  <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Current</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <span className="min-w-0 truncate rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                      {status.settings.openAiBaseUrl}
+                    </span>
+                  </div>
+                )}
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Model</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <div className="relative w-full min-w-0">
+                    <input type="text" value={selectedModel} onChange={(e) => setSelectedModel(e.target.value)} placeholder="provider/model-id" className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5" />
+                    {selectedModel && <button onClick={() => setSelectedModel("")} className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors" title="Clear"><span className="material-symbols-outlined text-[14px]">close</span></button>}
+                  </div>
+                  <button onClick={() => setModalOpen(true)} disabled={!activeProviders?.length} className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${activeProviders?.length ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Select Model</button>
+                </div>
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button variant="primary" size="sm" onClick={handleApply} disabled={(!selectedApiKey && (cloudEnabled && apiKeys.length > 0)) || !selectedModel} loading={applying}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleReset} disabled={restoring} loading={restoring}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => setModalOpen(false)}
+        onSelect={(model) => { setSelectedModel(model.value); setModalOpen(false); }}
+        selectedModel={selectedModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Model for Cline"
+      />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="Cline - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/CodexToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/CodexToolCard.js
new file mode 100644
index 0000000..12ef389
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/CodexToolCard.js
@@ -0,0 +1,402 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+export default function CodexToolCard({ tool, isExpanded, onToggle, baseUrl, apiKeys, activeProviders, cloudEnabled, initialStatus, tunnelEnabled, tunnelPublicUrl, tailscaleEnabled, tailscaleUrl }) {
+  const [codexStatus, setCodexStatus] = useState(initialStatus || null);
+  const [checkingCodex, setCheckingCodex] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [showInstallGuide, setShowInstallGuide] = useState(false);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [selectedModel, setSelectedModel] = useState("");
+  const [subagentModel, setSubagentModel] = useState("");
+  const [modalOpen, setModalOpen] = useState(false);
+  const [subagentModalOpen, setSubagentModalOpen] = useState(false);
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setCodexStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !codexStatus) {
+      checkCodexStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  // Parse model and subagent settings from config content
+  useEffect(() => {
+    if (codexStatus?.config) {
+      const modelMatch = codexStatus.config.match(/^model\s*=\s*"([^"]+)"/m);
+      if (modelMatch) setSelectedModel(modelMatch[1]);
+
+      // Parse subagent settings
+      const subagentModelMatch = codexStatus.config.match(/\[agents\.subagent\]\s*\n\s*model\s*=\s*"([^"]+)"/m);
+      if (subagentModelMatch) setSubagentModel(subagentModelMatch[1]);
+    }
+  }, [codexStatus]);
+
+  const getConfigStatus = () => {
+    if (!codexStatus?.installed) return null;
+    if (!codexStatus.config) return "not_configured";
+    const parsed = codexStatus.config.match(/base_url\s*=\s*"([^"]+)"/);
+    const currentUrl = parsed ? parsed[1] : "";
+    return matchKnownEndpoint(currentUrl, { tunnelPublicUrl, tailscaleUrl }) ? "configured" : "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || `${baseUrl}/v1`;
+    // Ensure URL ends with /v1
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const getDisplayUrl = () => customBaseUrl || `${baseUrl}/v1`;
+
+  const checkCodexStatus = async () => {
+    setCheckingCodex(true);
+    try {
+      const res = await fetch("/api/cli-tools/codex-settings");
+      const data = await res.json();
+      setCodexStatus(data);
+    } catch (error) {
+      setCodexStatus({ installed: false, error: error.message });
+    } finally {
+      setCheckingCodex(false);
+    }
+  };
+
+  const handleApplySettings = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      // Use sk_9router for localhost if no key, otherwise use selected key
+      const keyToUse = (selectedApiKey && selectedApiKey.trim())
+        ? selectedApiKey
+        : (!cloudEnabled ? "sk_9router" : selectedApiKey);
+
+      const res = await fetch("/api/cli-tools/codex-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: getEffectiveBaseUrl(),
+          apiKey: keyToUse,
+          model: selectedModel,
+          subagentModel: subagentModel || selectedModel
+        }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied successfully!" });
+        checkCodexStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleResetSettings = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch("/api/cli-tools/codex-settings", { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        setSelectedModel("");
+        setSubagentModel("");
+        checkCodexStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const handleModelSelect = (model) => {
+    setSelectedModel(model.value);
+    // Auto-set subagent model if not set
+    if (!subagentModel) {
+      setSubagentModel(model.value);
+    }
+    setModalOpen(false);
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+
+    const effectiveSubagentModel = subagentModel || selectedModel;
+
+    const configContent = `# 9Router Configuration for Codex CLI
+model = "${selectedModel}"
+model_provider = "9router"
+
+[model_providers.9router]
+name = "9Router"
+base_url = "${getEffectiveBaseUrl()}"
+wire_api = "responses"
+
+[agents.subagent]
+model = "${effectiveSubagentModel}"
+`;
+
+    const authContent = JSON.stringify({
+      auth_mode: "apikey",
+      OPENAI_API_KEY: keyToUse
+    }, null, 2);
+
+    return [
+      {
+        filename: "~/.codex/config.toml",
+        content: configContent,
+      },
+      {
+        filename: "~/.codex/auth.json",
+        content: authContent,
+      },
+    ];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src="/providers/codex.png" alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checkingCodex && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking Codex CLI...</span>
+            </div>
+          )}
+
+          {!checkingCodex && codexStatus && !codexStatus.installed && (
+            <div className="flex flex-col gap-4">
+              <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+                <div className="flex items-start gap-3">
+                  <span className="material-symbols-outlined text-yellow-500">warning</span>
+                  <div className="flex-1">
+                    <p className="font-medium text-yellow-600 dark:text-yellow-400">Codex CLI not detected locally</p>
+                    <p className="text-sm text-text-muted">Manual configuration is still available if 9router is deployed on a remote server.</p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-2 pl-9">
+                  <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="!bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                    <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                    Manual Config
+                  </Button>
+                  <Button variant="outline" size="sm" onClick={() => setShowInstallGuide(!showInstallGuide)}>
+                    <span className="material-symbols-outlined text-[18px] mr-1">{showInstallGuide ? "expand_less" : "help"}</span>
+                    {showInstallGuide ? "Hide" : "How to Install"}
+                  </Button>
+                </div>
+              </div>
+              {showInstallGuide && (
+                <div className="p-4 bg-surface border border-border rounded-lg">
+                  <h4 className="font-medium mb-3">Installation Guide</h4>
+                  <div className="space-y-3 text-sm">
+                    <div>
+                      <p className="text-text-muted mb-1">macOS / Linux / Windows:</p>
+                      <code className="block px-3 py-2 bg-black/5 dark:bg-white/5 rounded font-mono text-xs">npm install -g @openai/codex</code>
+                    </div>
+                    <p className="text-text-muted">After installation, run <code className="px-1 bg-black/5 dark:bg-white/5 rounded">codex</code> to verify.</p>
+                    <div className="pt-2 border-t border-border">
+                      <p className="text-text-muted text-xs">
+                        Codex uses <code className="px-1 bg-black/5 dark:bg-white/5 rounded">~/.codex/auth.json</code> with <code className="px-1 bg-black/5 dark:bg-white/5 rounded">OPENAI_API_KEY</code>.
+                        Click &quot;Apply&quot; to auto-configure.
+                      </p>
+                    </div>
+                  </div>
+                </div>
+              )}
+            </div>
+          )}
+
+          {!checkingCodex && codexStatus?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                {/* Endpoint (selector) */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getDisplayUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                {/* Current configured */}
+                {codexStatus?.config && (() => {
+                  const parsed = codexStatus.config.match(/base_url\s*=\s*"([^"]+)"/);
+                  const currentBaseUrl = parsed ? parsed[1] : null;
+                  return currentBaseUrl ? (
+                    <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                      <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Current</span>
+                      <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                      <span className="min-w-0 truncate rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                        {currentBaseUrl}
+                      </span>
+                    </div>
+                  ) : null;
+                })()}
+
+                {/* API Key */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                {/* Model */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Model</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <div className="relative w-full min-w-0">
+                    <input type="text" value={selectedModel} onChange={(e) => setSelectedModel(e.target.value)} placeholder="provider/model-id" className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5" />
+                    {selectedModel && <button onClick={() => setSelectedModel("")} className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors" title="Clear"><span className="material-symbols-outlined text-[14px]">close</span></button>}
+                  </div>
+                  <button onClick={() => setModalOpen(true)} disabled={!activeProviders?.length} className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${activeProviders?.length ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Select Model</button>
+                </div>
+
+                {/* Subagent Model */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Subagent Model</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <div className="relative w-full min-w-0">
+                    <input
+                      type="text"
+                      value={subagentModel}
+                      onChange={(e) => setSubagentModel(e.target.value)}
+                      placeholder={selectedModel || "provider/model-id (defaults to main model)"}
+                      className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5"
+                    />
+                    {subagentModel && (
+                      <button
+                        onClick={() => setSubagentModel("")}
+                        className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors"
+                        title="Clear (will use main model)"
+                      >
+                        <span className="material-symbols-outlined text-[14px]">close</span>
+                      </button>
+                    )}
+                  </div>
+                  <button
+                    onClick={() => setSubagentModalOpen(true)}
+                    disabled={!activeProviders?.length}
+                    className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${activeProviders?.length ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}
+                  >
+                    Select Model
+                  </button>
+                </div>
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button variant="primary" size="sm" onClick={handleApplySettings} disabled={(!selectedApiKey && (cloudEnabled && apiKeys.length > 0)) || !selectedModel} loading={applying}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleResetSettings} disabled={restoring} loading={restoring}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => setModalOpen(false)}
+        onSelect={handleModelSelect}
+        selectedModel={selectedModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Model for Codex"
+      />
+
+      <ModelSelectModal
+        isOpen={subagentModalOpen}
+        onClose={() => setSubagentModalOpen(false)}
+        onSelect={(model) => { setSubagentModel(model.value); setSubagentModalOpen(false); }}
+        selectedModel={subagentModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Subagent Model for Codex"
+      />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="Codex CLI - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/CopilotToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/CopilotToolCard.js
new file mode 100644
index 0000000..5987688
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/CopilotToolCard.js
@@ -0,0 +1,323 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+export default function CopilotToolCard({ tool, isExpanded, onToggle, baseUrl, apiKeys, activeProviders, cloudEnabled, initialStatus, tunnelEnabled, tunnelPublicUrl, tailscaleEnabled, tailscaleUrl }) {
+  const [status, setStatus] = useState(initialStatus || null);
+  const [checking, setChecking] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [selectedModels, setSelectedModels] = useState([]);
+  const [modalOpen, setModalOpen] = useState(false);
+  const selectedModelsRef = useRef([]);
+
+  useEffect(() => {
+    selectedModelsRef.current = selectedModels;
+  }, [selectedModels]);
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !status) {
+      checkStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  // Pre-fill from existing config
+  useEffect(() => {
+    if (status?.config && Array.isArray(status.config) && selectedModels.length === 0) {
+      const entry = status.config.find((e) => e.name === "9Router");
+      if (entry?.models?.length > 0) {
+        setSelectedModels(entry.models.map((m) => m.id));
+      }
+    }
+  }, [status]);
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  const saveModels = async (models) => {
+    try {
+      const keyToUse = (selectedApiKey && selectedApiKey.trim())
+        ? selectedApiKey
+        : (!cloudEnabled ? "sk_9router" : selectedApiKey);
+      await fetch("/api/cli-tools/copilot-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ baseUrl: getEffectiveBaseUrl(), apiKey: keyToUse, models }),
+      });
+    } catch (error) {
+      console.log("Error saving models:", error);
+    }
+  };
+
+  const getConfigStatus = () => {
+    if (!status) return null;
+    if (!status.has9Router) return "not_configured";
+    const url = status.currentUrl || "";
+    return matchKnownEndpoint(url, { tunnelPublicUrl, tailscaleUrl }) ? "configured" : "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || baseUrl;
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const getDisplayUrl = () => customBaseUrl || `${baseUrl}/v1`;
+
+  const removeModel = (id) => setSelectedModels((prev) => prev.filter((m) => m !== id));
+
+  const checkStatus = async () => {
+    setChecking(true);
+    try {
+      const res = await fetch("/api/cli-tools/copilot-settings");
+      const data = await res.json();
+      setStatus(data);
+    } catch (error) {
+      setStatus({ error: error.message });
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  const handleApply = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      const keyToUse = (selectedApiKey && selectedApiKey.trim())
+        ? selectedApiKey
+        : (!cloudEnabled ? "sk_9router" : selectedApiKey);
+
+      const res = await fetch("/api/cli-tools/copilot-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ baseUrl: getEffectiveBaseUrl(), apiKey: keyToUse, models: selectedModels }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: data.message || "Settings applied! Reload VS Code." });
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleReset = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch("/api/cli-tools/copilot-settings", { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        setSelectedModels([]);
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+    const effectiveBaseUrl = getEffectiveBaseUrl();
+    const modelsToShow = selectedModels.length > 0 ? selectedModels : ["provider/model-id"];
+
+    return [{
+      filename: "~/Library/Application Support/Code/User/chatLanguageModels.json",
+      content: JSON.stringify([{
+        name: "9Router",
+        vendor: "azure",
+        apiKey: keyToUse,
+        models: modelsToShow.map((id) => ({
+          id, name: id,
+          url: `${effectiveBaseUrl}/chat/completions#models.ai.azure.com`,
+          toolCalling: true, vision: false,
+          maxInputTokens: 128000, maxOutputTokens: 16000,
+        })),
+      }], null, 2),
+    }];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src="/providers/copilot.png" alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checking && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking Copilot config...</span>
+            </div>
+          )}
+
+          {!checking && (
+            <>
+              <div className="flex items-start gap-3 p-3 bg-blue-500/10 border border-blue-500/30 rounded-lg">
+                <span className="material-symbols-outlined text-blue-500 text-lg">info</span>
+                <div className="text-xs text-blue-700 dark:text-blue-300">
+                  <p className="font-medium">Writes to <code className="px-1 bg-black/5 dark:bg-white/10 rounded">chatLanguageModels.json</code></p>
+                  <p className="mt-0.5 opacity-80">Reload VS Code after applying for changes to take effect.</p>
+                </div>
+              </div>
+
+              <div className="flex flex-col gap-2">
+                {/* Endpoint */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getDisplayUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                {/* API Key */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                {/* Models */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-start sm:gap-2">
+                  <span className="w-32 shrink-0 text-sm font-semibold text-text-main text-right pt-1">Models</span>
+                  <span className="material-symbols-outlined text-text-muted text-[14px] mt-1.5">arrow_forward</span>
+                  <div className="flex-1 flex flex-col gap-2">
+                    <div className="flex flex-wrap gap-1.5 min-h-[28px] px-2 py-1.5 bg-surface rounded border border-border">
+                      {selectedModels.length === 0 ? (
+                        <span className="text-xs text-text-muted">No models selected</span>
+                      ) : (
+                        selectedModels.map((model) => (
+                          <span key={model} className="inline-flex items-center gap-1 px-2 py-0.5 rounded text-xs bg-black/5 dark:bg-white/5 text-text-muted border border-transparent hover:border-border">
+                            {model}
+                            <button onClick={(e) => { e.stopPropagation(); removeModel(model); }} className="ml-0.5 hover:text-red-500">
+                              <span className="material-symbols-outlined text-[12px]">close</span>
+                            </button>
+                          </span>
+                        ))
+                      )}
+                    </div>
+                    <div>
+                      <button onClick={() => setModalOpen(true)} disabled={!activeProviders?.length} className={`px-2 py-1 rounded border text-xs transition-colors ${activeProviders?.length ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Add Model</button>
+                    </div>
+                  </div>
+                </div>
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button variant="primary" size="sm" onClick={handleApply} disabled={selectedModels.length === 0} loading={applying}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleReset} disabled={!status?.has9Router} loading={restoring}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)} disabled={selectedModels.length === 0}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => {
+          setModalOpen(false);
+          saveModels(selectedModelsRef.current);
+        }}
+        onSelect={(model) => {
+          if (!selectedModels.includes(model.value)) {
+            setSelectedModels([...selectedModels, model.value]);
+          }
+        }}
+        onDeselect={(model) => {
+          setSelectedModels(selectedModels.filter(m => m !== model.value));
+        }}
+        selectedModel={null}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        addedModelValues={selectedModels}
+        closeOnSelect={false}
+        title="Add Model for GitHub Copilot"
+      />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="GitHub Copilot - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/CoworkToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/CoworkToolCard.js
new file mode 100644
index 0000000..07bba26
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/CoworkToolCard.js
@@ -0,0 +1,597 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card, Button, ManualConfigModal, ComboFormModal, McpMarketplaceModal, ModelSelectModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+
+const ENDPOINT = "/api/cli-tools/cowork-settings";
+
+const stripV1 = (url) => (url || "").replace(/\/v1\/?$/, "");
+const ensureV1 = (url) => {
+  const trimmed = (url || "").replace(/\/+$/, "");
+  if (!trimmed) return "";
+  return /\/v1$/.test(trimmed) ? trimmed : `${trimmed}/v1`;
+};
+
+export default function CoworkToolCard({
+  tool,
+  isExpanded,
+  onToggle,
+  baseUrl,
+  apiKeys,
+  activeProviders,
+  hasActiveProviders,
+  cloudEnabled,
+  cloudUrl,
+  tunnelEnabled,
+  tunnelPublicUrl,
+  tailscaleEnabled,
+  tailscaleUrl,
+  initialStatus,
+}) {
+  const [status, setStatus] = useState(initialStatus || null);
+  const [checking, setChecking] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [selectedModels, setSelectedModels] = useState([]);
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+  const [plugins, setPlugins] = useState([]);
+  const [localPlugins, setLocalPlugins] = useState([]);
+  const [customPlugins, setCustomPlugins] = useState([]);
+  const [modelAliases, setModelAliases] = useState({});
+  const [comboModalOpen, setComboModalOpen] = useState(false);
+  const [modelSelectOpen, setModelSelectOpen] = useState(false);
+  const [marketplaceOpen, setMarketplaceOpen] = useState(false);
+  const [addMcpOpen, setAddMcpOpen] = useState(false);
+  const [addMcpForm, setAddMcpForm] = useState({ name: "", url: "" });
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !status) checkStatus();
+  }, [isExpanded]);
+
+  useEffect(() => {
+    if (!isExpanded) return;
+    fetch("/api/models/alias")
+      .then((r) => r.ok ? r.json() : null)
+      .then((data) => {
+        if (data) setModelAliases(data.aliases || {});
+      })
+      .catch(() => {});
+  }, [isExpanded]);
+
+  useEffect(() => {
+    if (status?.cowork?.models?.length) {
+      setSelectedModels(status.cowork.models);
+    }
+    if (status?.cowork?.baseUrl && !customBaseUrl) {
+      setCustomBaseUrl(stripV1(status.cowork.baseUrl));
+    }
+    // Initialize plugins: from current config, fallback to defaultPlugins
+    if (Array.isArray(status?.cowork?.plugins) && status.cowork.plugins.length > 0) {
+      setPlugins(status.cowork.plugins);
+    } else if (plugins.length === 0 && Array.isArray(status?.defaultPlugins)) {
+      setPlugins(status.defaultPlugins);
+    }
+    if (Array.isArray(status?.cowork?.localPlugins)) {
+      setLocalPlugins(status.cowork.localPlugins);
+    }
+    if (Array.isArray(status?.cowork?.customPlugins) && status.cowork.customPlugins.length > 0) {
+      setCustomPlugins(status.cowork.customPlugins);
+    }
+  }, [status]);
+
+  const checkStatus = async () => {
+    setChecking(true);
+    try {
+      const res = await fetch(ENDPOINT);
+      const data = await res.json();
+      setStatus(data);
+    } catch (error) {
+      setStatus({ installed: false, error: error.message });
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  const getEffectiveBaseUrl = () => ensureV1(customBaseUrl);
+
+  const getConfigStatus = () => {
+    if (!status?.installed) return null;
+    const url = status?.cowork?.baseUrl;
+    if (!url) return "not_configured";
+    return status.has9Router ? "configured" : "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  const handleApply = async () => {
+    setMessage(null);
+    const effectiveUrl = getEffectiveBaseUrl();
+
+    if (selectedModels.length === 0) {
+      setMessage({ type: "error", text: "Please select at least one model" });
+      return;
+    }
+
+    setApplying(true);
+    try {
+      const keyToUse = selectedApiKey?.trim()
+        || (apiKeys?.length > 0 ? apiKeys[0].key : null)
+        || (!cloudEnabled ? "sk_9router" : null);
+
+      const res = await fetch(ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: effectiveUrl,
+          apiKey: keyToUse,
+          models: selectedModels,
+          plugins,
+          localPlugins,
+          customPlugins,
+        }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied. Quit & reopen Claude Desktop to load." });
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleCreateCombo = async ({ name, models }) => {
+    try {
+      const res = await fetch("/api/combos", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name, models }),
+      });
+      if (!res.ok) {
+        const err = await res.json();
+        setMessage({ type: "error", text: err.error || "Failed to create combo" });
+        return;
+      }
+      if (!selectedModels.includes(name)) {
+        setSelectedModels([...selectedModels, name]);
+      }
+      setComboModalOpen(false);
+      setMessage({ type: "success", text: `Combo "${name}" created and added.` });
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    }
+  };
+
+  const handleAddModel = (model) => {
+    const value = model?.value || model?.name || model;
+    if (!value || selectedModels.includes(value)) return;
+    setSelectedModels((prev) => [...prev, value]);
+  };
+
+  const handleRemoveModel = (model) => {
+    const value = model?.value || model?.name || model;
+    setSelectedModels((prev) => prev.filter((item) => item !== value));
+  };
+
+  const handleReset = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch(ENDPOINT, { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully" });
+        setSelectedModels([]);
+        setPlugins(status?.defaultPlugins || []);
+        setLocalPlugins([]);
+        setCustomPlugins([]);
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const addPlugin = (p) => {
+    if (plugins.some((x) => x.name === p.name)) return;
+    setPlugins([...plugins, p]);
+  };
+
+  const removePlugin = (name) => {
+    setPlugins(plugins.filter((p) => p.name !== name));
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+
+    const modelsToShow = selectedModels.length > 0 ? selectedModels : ["provider/model-id"];
+    const cfg = {
+      inferenceProvider: "gateway",
+      inferenceGatewayBaseUrl: getEffectiveBaseUrl() || "https://your-public-host/v1",
+      inferenceGatewayApiKey: keyToUse,
+      inferenceModels: modelsToShow.map((name) => ({ name })),
+    };
+
+    return [{
+      filename: "~/Library/Application Support/Claude-3p/configLibrary/<appliedId>.json",
+      content: JSON.stringify(cfg, null, 2),
+    }];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src={tool.image} alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checking && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking Claude Cowork...</span>
+            </div>
+          )}
+
+          {!checking && status && !status.installed && (
+            <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+              <div className="flex items-start gap-3">
+                <span className="material-symbols-outlined text-yellow-500">warning</span>
+                <div className="flex-1">
+                  <p className="font-medium text-yellow-600 dark:text-yellow-400">Claude Desktop (Cowork mode) not detected</p>
+                  <p className="text-sm text-text-muted">Open Claude Desktop → Help → Troubleshooting → Enable Developer mode → Configure third-party inference, then return here.</p>
+                </div>
+              </div>
+              <div className="pl-9">
+                <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="!bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                  <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                  Manual Config
+                </Button>
+              </div>
+            </div>
+          )}
+
+          {!checking && status?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={getEffectiveBaseUrl()}
+                    onChange={(url) => setCustomBaseUrl(stripV1(url))}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                    cloudEnabled={cloudEnabled}
+                    cloudUrl={cloudUrl}
+                  />
+                </div>
+
+                {status?.cowork?.baseUrl && (
+                  <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Current</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <span className="min-w-0 truncate rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                      {status.cowork.baseUrl}
+                    </span>
+                  </div>
+                )}
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="w-32 shrink-0 text-sm font-semibold text-text-main text-right">Models</span>
+                  <span className="material-symbols-outlined text-text-muted text-[14px]">arrow_forward</span>
+                  <div className="flex-1 flex items-center gap-2">
+                    <div className="flex-1 flex flex-wrap gap-1.5 min-h-[28px] px-2 py-1.5 bg-surface rounded border border-border">
+                      {selectedModels.length === 0 ? (
+                        <span className="text-xs text-text-muted">No models selected</span>
+                      ) : (
+                        selectedModels.map((m) => (
+                          <span key={m} className="inline-flex items-center gap-1 px-2 py-0.5 rounded text-xs bg-black/5 dark:bg-white/5 text-text-muted border border-transparent hover:border-border">
+                            {m}
+                            <button onClick={() => handleRemoveModel(m)} className="ml-0.5 hover:text-red-500">
+                              <span className="material-symbols-outlined text-[12px]">close</span>
+                            </button>
+                          </span>
+                        ))
+                      )}
+                    </div>
+                    <button onClick={() => setComboModalOpen(true)} disabled={!hasActiveProviders} className={`shrink-0 px-2 py-1.5 rounded border text-xs whitespace-nowrap transition-colors ${hasActiveProviders ? "bg-primary/10 border-primary/40 text-primary hover:bg-primary/20 cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>+ Combo</button>
+                  </div>
+                </div>
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-start sm:gap-2">
+                  <span className="w-32 shrink-0 text-sm font-semibold text-text-main text-right pt-2">MCP</span>
+                  <span className="material-symbols-outlined text-text-muted text-[14px] mt-2">arrow_forward</span>
+                  <div className="flex-1 flex flex-col gap-1">
+                    {/* Preset plugins */}
+                    {plugins.filter((p) => p.name !== "exa").map((p) => (
+                      <div key={p.name} className="flex items-center gap-2 px-2 py-1 bg-surface rounded border border-border">
+                        <span className="text-xs font-medium min-w-0 truncate flex-shrink-0">{p.title || p.name}</span>
+                        {p.oauth && <span className="text-[8px] text-amber-600 shrink-0">OAuth</span>}
+                        <div className="flex-1 flex flex-wrap gap-1 overflow-hidden" style={{ maxHeight: "1.5rem" }}>
+                          {Array.isArray(p.toolNames) && p.toolNames.slice(0, 6).map((t) => (
+                            <span key={t} className="text-[9px] px-1 py-0.5 rounded bg-black/5 dark:bg-white/5 text-text-muted whitespace-nowrap">{t}</span>
+                          ))}
+                          {Array.isArray(p.toolNames) && p.toolNames.length > 6 && (
+                            <span className="text-[9px] px-1 py-0.5 rounded bg-black/5 dark:bg-white/5 text-text-muted whitespace-nowrap">+{p.toolNames.length - 6}</span>
+                          )}
+                        </div>
+                        <button onClick={() => removePlugin(p.name)} className="shrink-0 hover:text-red-500 ml-auto">
+                          <span className="material-symbols-outlined text-[12px]">close</span>
+                        </button>
+                      </div>
+                    ))}
+                    {/* Custom plugins */}
+                    {customPlugins.map((p) => (
+                      <div key={p.name} className="flex items-center gap-2 px-2 py-1 bg-surface rounded border border-border">
+                        <span className="text-xs font-medium min-w-0 truncate flex-shrink-0">{p.name}</span>
+                        <span className="text-[8px] px-1 py-0.5 rounded bg-blue-500/10 text-blue-500 shrink-0">custom</span>
+                        <span className="flex-1 text-[9px] text-text-muted truncate">{p.url}</span>
+                        <button onClick={() => setCustomPlugins(customPlugins.filter((x) => x.name !== p.name))} className="shrink-0 hover:text-red-500 ml-auto">
+                          <span className="material-symbols-outlined text-[12px]">close</span>
+                        </button>
+                      </div>
+                    ))}
+                    {plugins.filter((p) => p.name !== "exa").length === 0 && customPlugins.length === 0 && (
+                      <div className="px-2 py-1.5 bg-surface rounded border border-border text-xs text-text-muted">No MCPs added</div>
+                    )}
+                    {/* Actions row */}
+                    <div className="flex items-center gap-2 mt-0.5">
+                      <button onClick={() => setMarketplaceOpen(true)} className="px-2 py-1 rounded border text-xs bg-primary/10 border-primary/40 text-primary hover:bg-primary/20 cursor-pointer whitespace-nowrap">
+                        + Browse
+                      </button>
+                      <button onClick={() => { setAddMcpForm({ name: "", url: "" }); setAddMcpOpen(true); }} className="px-2 py-1 rounded border text-xs bg-surface border-border text-text-muted hover:border-primary hover:text-primary cursor-pointer whitespace-nowrap">
+                        + Custom
+                      </button>
+                      <a href="https://mcp.so" target="_blank" rel="noopener noreferrer" className="text-[10px] text-text-muted hover:text-primary underline ml-auto">Find MCPs →</a>
+                    </div>
+                  </div>
+                </div>
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-start sm:gap-2">
+                  <span className="w-32 shrink-0 text-sm font-semibold text-text-main text-right pt-1">Tools</span>
+                  <span className="material-symbols-outlined text-text-muted text-[14px] mt-1.5">arrow_forward</span>
+                  <div className="flex-1 flex flex-col gap-1.5">
+                    {(() => {
+                      const exaEnabled = plugins.some((p) => p.name === "exa");
+                      const exaDef = (status?.defaultPlugins || []).find((d) => d.name === "exa");
+                      return (
+                        <label className="flex items-start gap-2 cursor-pointer px-2 py-1.5 bg-surface rounded border border-border">
+                          <input
+                            type="checkbox"
+                            checked={exaEnabled}
+                            onChange={(e) => {
+                              if (e.target.checked && exaDef) setPlugins([...plugins.filter((p) => p.name !== "exa"), exaDef]);
+                              else setPlugins(plugins.filter((p) => p.name !== "exa"));
+                            }}
+                            className="mt-0.5"
+                          />
+                          <div className="flex-1 min-w-0">
+                            <div className="text-xs font-medium">Web Search & Fetch (Exa)</div>
+                            <p className="text-[10px] text-text-muted leading-snug">Replaces built-in WebSearch/WebFetch. Auto-strips duplicates from tool list.</p>
+                          </div>
+                        </label>
+                      );
+                    })()}
+                    {(() => {
+                      const browserDef = (status?.localStdioPlugins || []).find((p) => p.name === "browsermcp");
+                      if (!browserDef) return null;
+                      const browserEnabled = localPlugins.includes("browsermcp");
+                      return (
+                        <label className="flex items-start gap-2 cursor-pointer px-2 py-1.5 bg-surface rounded border border-border">
+                          <input
+                            type="checkbox"
+                            checked={browserEnabled}
+                            onChange={(e) => setLocalPlugins(e.target.checked ? [...localPlugins, "browsermcp"] : localPlugins.filter((n) => n !== "browsermcp"))}
+                            className="mt-0.5"
+                          />
+                          <div className="flex-1 min-w-0">
+                            <div className="text-xs font-medium">Browser Control (Browser MCP)</div>
+                            <p className="text-[10px] text-text-muted leading-snug">
+                              Controls your running Chrome. Auto-strips Cowork&apos;s built-in browser tools.{" "}
+                              <a href={browserDef.extensionUrl} target="_blank" rel="noopener noreferrer" className="text-primary underline">Install Chrome extension</a>
+                            </p>
+                          </div>
+                        </label>
+                      );
+                    })()}
+                  </div>
+                </div>
+
+                {Array.isArray(status?.localStdioPlugins) && status.localStdioPlugins.filter((p) => p.name !== "browsermcp").length > 0 && (
+                  <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-start sm:gap-2">
+                    <span className="w-32 shrink-0 text-sm font-semibold text-text-main text-right pt-1">Local Plugins</span>
+                    <span className="material-symbols-outlined text-text-muted text-[14px] mt-1.5">arrow_forward</span>
+                    <div className="flex-1 flex flex-col gap-2">
+                      <div className="flex flex-col gap-1.5 px-2 py-1.5 bg-surface rounded border border-border">
+                        {status.localStdioPlugins.filter((p) => p.name !== "browsermcp").map((p) => {
+                          const enabled = localPlugins.includes(p.name);
+                          return (
+                            <label key={p.name} className="flex items-start gap-2 cursor-pointer">
+                              <input
+                                type="checkbox"
+                                checked={enabled}
+                                onChange={(e) => setLocalPlugins(e.target.checked ? [...localPlugins, p.name] : localPlugins.filter((n) => n !== p.name))}
+                                className="mt-0.5"
+                              />
+                              <div className="flex-1 min-w-0">
+                                <div className="flex flex-wrap items-center gap-1.5">
+                                  <span className="text-xs font-medium">{p.title}</span>
+                                  <span className="text-[8px] text-amber-600">stdio</span>
+                                </div>
+                                <p className="text-[10px] text-text-muted leading-snug">{p.description}</p>
+                                {p.extensionUrl && (
+                                  <a href={p.extensionUrl} target="_blank" rel="noopener noreferrer" className="text-[10px] text-primary underline">Install Chrome extension</a>
+                                )}
+                              </div>
+                            </label>
+                          );
+                        })}
+                      </div>
+                      <p className="text-[10px] text-text-muted leading-snug">
+                        ⚠️ Local plugins run as subprocess via <code className="px-1 py-0.5 rounded bg-black/5 dark:bg-white/5">npx</code>. Requires Node.js installed.
+                      </p>
+                    </div>
+                  </div>
+                )}
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="flex flex-col sm:flex-row sm:items-center gap-2">
+                <Button variant="primary" size="sm" onClick={handleApply} disabled={selectedModels.length === 0} loading={applying} className="w-full sm:w-auto">
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleReset} disabled={!status.has9Router} loading={restoring} className="w-full sm:w-auto">
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)} className="w-full sm:w-auto">
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="Claude Cowork - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+
+      <ComboFormModal
+        isOpen={comboModalOpen}
+        combo={null}
+        onClose={() => setComboModalOpen(false)}
+        onSave={handleCreateCombo}
+        activeProviders={activeProviders}
+        forcePrefix="claude-"
+        title="Create Cowork Combo"
+      />
+
+      <ModelSelectModal
+        isOpen={modelSelectOpen}
+        onClose={() => setModelSelectOpen(false)}
+        onSelect={handleAddModel}
+        onDeselect={handleRemoveModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Cowork Model"
+        addedModelValues={selectedModels}
+        closeOnSelect={false}
+      />
+
+      <McpMarketplaceModal
+        isOpen={marketplaceOpen}
+        onClose={() => setMarketplaceOpen(false)}
+        onAdd={addPlugin}
+        addedNames={plugins.map((p) => p.name)}
+      />
+
+      {/* Add Custom MCP modal */}
+      {addMcpOpen && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/40" onClick={() => setAddMcpOpen(false)}>
+          <div className="bg-surface border border-border rounded-xl shadow-xl w-full max-w-sm mx-4 p-5 flex flex-col gap-4" onClick={(e) => e.stopPropagation()}>
+            <div className="flex items-center justify-between">
+              <h3 className="font-semibold text-sm">Add Custom MCP</h3>
+              <button onClick={() => setAddMcpOpen(false)} className="text-text-muted hover:text-text-main">
+                <span className="material-symbols-outlined text-[18px]">close</span>
+              </button>
+            </div>
+
+            <div className="flex flex-col gap-2">
+              <div className="flex flex-col gap-1">
+                <label className="text-[11px] text-text-muted font-medium">Name</label>
+                <input
+                  type="text"
+                  placeholder="my-mcp"
+                  value={addMcpForm.name}
+                  onChange={(e) => setAddMcpForm((f) => ({ ...f, name: e.target.value.replace(/\s+/g, "-").toLowerCase() }))}
+                  className="px-2 py-1.5 rounded border border-border bg-surface text-xs outline-none focus:border-primary"
+                />
+              </div>
+              <div className="flex flex-col gap-1">
+                <label className="text-[11px] text-text-muted font-medium">SSE URL</label>
+                <input
+                  type="text"
+                  placeholder="https://your-mcp-server.com/sse"
+                  value={addMcpForm.url}
+                  onChange={(e) => setAddMcpForm((f) => ({ ...f, url: e.target.value }))}
+                  className="px-2 py-1.5 rounded border border-border bg-surface text-xs outline-none focus:border-primary"
+                />
+              </div>
+            </div>
+
+            <div className="flex gap-2 justify-end">
+              <button onClick={() => setAddMcpOpen(false)} className="px-3 py-1.5 rounded border border-border text-xs text-text-muted hover:bg-surface cursor-pointer">Cancel</button>
+              <button
+                onClick={() => {
+                  const name = addMcpForm.name.trim();
+                  if (!name || !addMcpForm.url.trim()) return;
+                  setCustomPlugins((prev) => [...prev.filter((x) => x.name !== name), { name, url: addMcpForm.url.trim(), transport: "sse", custom: true }]);
+                  setAddMcpOpen(false);
+                }}
+                className="px-3 py-1.5 rounded bg-primary text-white text-xs font-medium hover:opacity-90 cursor-pointer"
+              >Add</button>
+            </div>
+          </div>
+        </div>
+      )}
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/DeepSeekTuiToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/DeepSeekTuiToolCard.js
new file mode 100644
index 0000000..426ca74
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/DeepSeekTuiToolCard.js
@@ -0,0 +1,338 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+const ENDPOINT = "/api/cli-tools/deepseek-tui-settings";
+
+export default function DeepSeekTuiToolCard({
+  tool,
+  isExpanded,
+  onToggle,
+  baseUrl,
+  hasActiveProviders,
+  apiKeys,
+  activeProviders,
+  cloudEnabled,
+  initialStatus,
+  tunnelEnabled,
+  tunnelPublicUrl,
+  tailscaleEnabled,
+  tailscaleUrl,
+}) {
+  const [deepseekStatus, setDeepseekStatus] = useState(initialStatus || null);
+  const [checking, setChecking] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [selectedModel, setSelectedModel] = useState("");
+  const [modalOpen, setModalOpen] = useState(false);
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+  const hasInitializedModel = useRef(false);
+
+  const getConfigStatus = () => {
+    if (!deepseekStatus?.installed) return null;
+    const openaiSection = deepseekStatus.settings?.["providers.openai"];
+    if (!openaiSection?.base_url) return "not_configured";
+    if (matchKnownEndpoint(openaiSection.base_url, { tunnelPublicUrl, tailscaleUrl })) return "configured";
+    return "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setDeepseekStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !deepseekStatus) {
+      checkStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  useEffect(() => {
+    if (deepseekStatus?.installed && !hasInitializedModel.current) {
+      hasInitializedModel.current = true;
+      const openaiSection = deepseekStatus.settings?.["providers.openai"];
+      if (openaiSection?.model) setSelectedModel(openaiSection.model);
+    }
+  }, [deepseekStatus]);
+
+  const checkStatus = async () => {
+    setChecking(true);
+    try {
+      const res = await fetch(ENDPOINT);
+      const data = await res.json();
+      setDeepseekStatus(data);
+    } catch (error) {
+      setDeepseekStatus({ installed: false, error: error.message });
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  const normalizeLocalhost = (url) => url.replace("://localhost", "://127.0.0.1");
+
+  const getLocalBaseUrl = () => {
+    if (typeof window !== "undefined") {
+      return normalizeLocalhost(window.location.origin);
+    }
+    return "http://127.0.0.1:20128";
+  };
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || getLocalBaseUrl();
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const handleApply = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      const keyToUse = selectedApiKey?.trim()
+        || (apiKeys?.length > 0 ? apiKeys[0].key : null)
+        || (!cloudEnabled ? "sk_9router" : null);
+
+      const res = await fetch(ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: getEffectiveBaseUrl(),
+          apiKey: keyToUse,
+          model: selectedModel,
+        }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied successfully!" });
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleReset = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch(ENDPOINT, { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        setSelectedModel("");
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const handleModelSelect = (model) => {
+    setSelectedModel(model.value);
+    setModalOpen(false);
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+
+    const tomlContent = `[providers.openai]
+base_url = "${getEffectiveBaseUrl()}"
+api_key = "${keyToUse}"
+model = "${selectedModel || "provider/model-id"}"
+`;
+
+    return [
+      { filename: "~/.deepseek/config.toml", content: tomlContent },
+    ];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src={tool.image || "/providers/deepseek-tui.png"} alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checking && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking DeepSeek TUI...</span>
+            </div>
+          )}
+
+          {!checking && deepseekStatus && !deepseekStatus.installed && (
+            <div className="flex flex-col gap-4">
+              <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+                <div className="flex items-start gap-3">
+                  <span className="material-symbols-outlined text-yellow-500">warning</span>
+                  <div className="flex-1">
+                    <p className="font-medium text-yellow-600 dark:text-yellow-400">DeepSeek TUI not detected locally</p>
+                    <p className="text-sm text-text-muted mt-1">Install via npm:</p>
+                    <code className="block mt-2 p-2 bg-black/20 rounded text-xs font-mono">npm install -g deepseek-tui</code>
+                    <p className="text-sm text-text-muted mt-2">Manual configuration is still available if 9router is deployed on a remote server.</p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-2 pl-9">
+                  <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="!bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                    <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                    Manual Config
+                  </Button>
+                </div>
+              </div>
+            </div>
+          )}
+
+          {!checking && deepseekStatus?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                {tool.notes && tool.notes.length > 0 && (
+                  <div className="flex flex-col gap-2 mb-2">
+                    {tool.notes.map((note, idx) => (
+                      <div key={idx} className={`flex items-start gap-2 p-2 rounded text-xs ${
+                        note.type === "warning" ? "bg-yellow-500/10 text-yellow-600 dark:text-yellow-400" :
+                        note.type === "error" ? "bg-red-500/10 text-red-600 dark:text-red-400" :
+                        "bg-blue-500/10 text-blue-600 dark:text-blue-400"
+                      }`}>
+                        <span className="material-symbols-outlined text-[14px] mt-0.5">
+                          {note.type === "warning" ? "warning" : note.type === "error" ? "error" : "info"}
+                        </span>
+                        <span>{note.text}</span>
+                      </div>
+                    ))}
+                  </div>
+                )}
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getEffectiveBaseUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                {deepseekStatus?.settings?.["providers.openai"]?.base_url && (
+                  <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Current</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <span className="min-w-0 truncate rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                      {deepseekStatus.settings["providers.openai"].base_url}
+                    </span>
+                  </div>
+                )}
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Default Model</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <div className="relative w-full min-w-0">
+                    <input type="text" value={selectedModel} onChange={(e) => setSelectedModel(e.target.value)} placeholder="provider/model-id" className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5" />
+                    {selectedModel && <button onClick={() => setSelectedModel("")} className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors" title="Clear"><span className="material-symbols-outlined text-[14px]">close</span></button>}
+                  </div>
+                  <button onClick={() => setModalOpen(true)} disabled={!hasActiveProviders} className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${hasActiveProviders ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Select</button>
+                </div>
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button variant="primary" size="sm" onClick={handleApply} disabled={!selectedModel} loading={applying}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleReset} disabled={!deepseekStatus?.has9Router} loading={restoring}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => setModalOpen(false)}
+        onSelect={handleModelSelect}
+        selectedModel={selectedModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Model for DeepSeek TUI"
+      />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="DeepSeek TUI - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/DefaultToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/DefaultToolCard.js
new file mode 100644
index 0000000..28d47d2
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/DefaultToolCard.js
@@ -0,0 +1,271 @@
+"use client";
+
+import { useState } from "react";
+import { Card, ModelSelectModal } from "@/shared/components";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import Image from "next/image";
+import ApiKeySelect from "./ApiKeySelect";
+
+export default function DefaultToolCard({ toolId, tool, isExpanded, onToggle, baseUrl, apiKeys, activeProviders = [], cloudEnabled = false, tunnelEnabled = false }) {
+  const [copiedField, setCopiedField] = useState(null);
+  const [showModelModal, setShowModelModal] = useState(false);
+  const [modelValue, setModelValue] = useState("");
+  
+  // Initialize state directly with computed value - no need for useEffect
+  const [selectedApiKey, setSelectedApiKey] = useState(() => 
+    apiKeys?.length > 0 ? apiKeys[0].key : ""
+  );
+
+  const replaceVars = (text) => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim()) 
+      ? selectedApiKey 
+      : (!cloudEnabled ? "sk_9router" : "your-api-key");
+    
+    // Add /v1 suffix only if not already present (DRY - avoid duplicate)
+    const normalizedBaseUrl = baseUrl || "http://localhost:20128";
+    const baseUrlWithV1 = normalizedBaseUrl.endsWith("/v1") 
+      ? normalizedBaseUrl 
+      : `${normalizedBaseUrl}/v1`;
+    
+    return text
+      .replace(/\{\{baseUrl\}\}/g, baseUrlWithV1)
+      .replace(/\{\{apiKey\}\}/g, keyToUse)
+      .replace(/\{\{model\}\}/g, modelValue || "provider/model-id");
+  };
+
+  const { copy: copyToClipboard } = useCopyToClipboard();
+
+  const handleCopy = async (text, field) => {
+    await copyToClipboard(replaceVars(text), `toolcard-${field}`);
+    setCopiedField(field);
+    setTimeout(() => setCopiedField(null), 2000);
+  };
+
+  const handleSelectModel = (model) => {
+    setModelValue(model.value);
+  };
+
+  const hasActiveProviders = activeProviders.length > 0;
+
+  const renderApiKeySelector = () => (
+    <div className="mt-2 flex flex-col sm:flex-row sm:items-center gap-2">
+      <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} className="flex-1" />
+    </div>
+  );
+
+  const renderModelSelector = () => {
+    return (
+      <div className="mt-2 flex flex-col sm:flex-row sm:items-center gap-2">
+        <input
+          type="text"
+          value={modelValue}
+          onChange={(e) => setModelValue(e.target.value)}
+          placeholder="provider/model-id"
+          className="w-full sm:w-auto flex-1 px-3 py-2 bg-bg-secondary rounded-lg text-sm border border-border focus:outline-none focus:ring-1 focus:ring-primary/50"
+        />
+        <button
+          onClick={() => setShowModelModal(true)}
+          disabled={!hasActiveProviders}
+          className={`shrink-0 px-3 py-2 rounded-lg border text-sm transition-colors ${
+            hasActiveProviders
+              ? "bg-bg-secondary border-border text-text-main hover:border-primary cursor-pointer"
+              : "opacity-50 cursor-not-allowed border-border"
+          }`}
+        >
+          Select Model
+        </button>
+        {modelValue && (
+          <>
+            <button
+              onClick={() => handleCopy(modelValue, "model")}
+              className="shrink-0 px-3 py-2 bg-bg-secondary hover:bg-bg-tertiary rounded-lg border border-border transition-colors"
+            >
+              <span className="material-symbols-outlined text-lg">
+                {copiedField === "model" ? "check" : "content_copy"}
+              </span>
+            </button>
+            <button
+              onClick={() => setModelValue("")}
+              className="p-2 text-text-muted hover:text-red-500 rounded transition-colors"
+              title="Clear"
+            >
+              <span className="material-symbols-outlined text-lg">close</span>
+            </button>
+          </>
+        )}
+      </div>
+    );
+  };
+
+  const renderNotes = () => {
+    if (!tool.notes || tool.notes.length === 0) return null;
+    
+    return (
+      <div className="flex flex-col gap-2 mb-4">
+        {tool.notes.map((note, index) => {
+          // Skip cloudCheck note if tunnel or cloud is enabled
+          if (note.type === "cloudCheck" && (cloudEnabled || tunnelEnabled)) return null;
+          
+          const isWarning = note.type === "warning";
+          const isError = note.type === "cloudCheck" && !cloudEnabled && !tunnelEnabled;
+          
+          let bgClass = "bg-blue-500/10 border-blue-500/30";
+          let textClass = "text-blue-600 dark:text-blue-400";
+          let iconClass = "text-blue-500";
+          let icon = "info";
+          
+          if (isWarning) {
+            bgClass = "bg-yellow-500/10 border-yellow-500/30";
+            textClass = "text-yellow-600 dark:text-yellow-400";
+            iconClass = "text-yellow-500";
+            icon = "warning";
+          } else if (isError) {
+            bgClass = "bg-red-500/10 border-red-500/30";
+            textClass = "text-red-600 dark:text-red-400";
+            iconClass = "text-red-500";
+            icon = "error";
+          }
+          
+          return (
+            <div key={index} className={`flex items-start gap-3 p-3 rounded-lg border ${bgClass}`}>
+              <span className={`material-symbols-outlined text-lg ${iconClass}`}>{icon}</span>
+              <p className={`text-sm ${textClass}`}>{note.text}</p>
+            </div>
+          );
+        })}
+      </div>
+    );
+  };
+
+  const canShowGuide = () => {
+    if (tool.requiresExternalUrl && !cloudEnabled && !tunnelEnabled) return false;
+    if (tool.requiresCloud && !cloudEnabled) return false;
+    return true;
+  };
+
+  const renderGuideSteps = () => {
+    if (!tool.guideSteps) return <p className="text-text-muted text-sm">Coming soon...</p>;
+
+    return (
+      <div className="flex flex-col gap-4">
+        {renderNotes()}
+        {canShowGuide() && tool.guideSteps.map((item) => (
+          <div key={item.step} className="flex items-start gap-4">
+            <div 
+              className="size-8 rounded-full flex items-center justify-center shrink-0 text-sm font-semibold text-white"
+              style={{ backgroundColor: tool.color }}
+            >
+              {item.step}
+            </div>
+            <div className="flex-1 min-w-0">
+              <p className="font-medium text-text">{item.title}</p>
+              {item.desc && <p className="text-sm text-text-muted mt-0.5">{item.desc}</p>}
+              {item.type === "apiKeySelector" && renderApiKeySelector()}
+              {item.type === "modelSelector" && renderModelSelector()}
+              {item.value && (
+                <div className="mt-2 flex flex-col sm:flex-row sm:items-center gap-2">
+                  <code className="w-full sm:w-auto flex-1 px-3 py-2 bg-bg-secondary rounded-lg text-sm font-mono border border-border truncate">
+                    {replaceVars(item.value)}
+                  </code>
+                  {item.copyable && (
+                    <button
+                      onClick={() => handleCopy(item.value, `${item.step}-${item.title}`)}
+                      className="shrink-0 px-3 py-2 bg-bg-secondary hover:bg-bg-tertiary rounded-lg border border-border transition-colors"
+                    >
+                      <span className="material-symbols-outlined text-lg">
+                        {copiedField === `${item.step}-${item.title}` ? "check" : "content_copy"}
+                      </span>
+                    </button>
+                  )}
+                </div>
+              )}
+            </div>
+          </div>
+        ))}
+
+        {canShowGuide() && tool.codeBlock && (
+          <div className="mt-2">
+            <div className="flex items-center justify-between mb-2">
+              <span className="text-xs text-text-muted uppercase tracking-wide">{tool.codeBlock.language}</span>
+              <button
+                onClick={() => handleCopy(tool.codeBlock.code, "codeblock")}
+                className="flex items-center gap-1 px-2 py-1 text-xs bg-bg-secondary hover:bg-bg-tertiary rounded border border-border transition-colors"
+              >
+                <span className="material-symbols-outlined text-sm">
+                  {copiedField === "codeblock" ? "check" : "content_copy"}
+                </span>
+                {copiedField === "codeblock" ? "Copied!" : "Copy"}
+              </button>
+            </div>
+            <pre className="p-4 bg-bg-secondary rounded-lg border border-border overflow-x-auto">
+              <code className="text-sm font-mono whitespace-pre">{replaceVars(tool.codeBlock.code)}</code>
+            </pre>
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  const renderIcon = () => {
+    if (tool.image) {
+      return (
+        <Image
+          src={tool.image}
+          alt={tool.name}
+          width={32}
+          height={32}
+          className="size-8 object-contain rounded-lg"
+          sizes="32px"
+          onError={(e) => { e.target.style.display = "none"; }}
+        />
+      );
+    }
+    if (tool.icon) {
+      return <span className="material-symbols-outlined text-xl" style={{ color: tool.color }}>{tool.icon}</span>;
+    }
+    return (
+      <Image
+        src={`/providers/${toolId}.png`}
+        alt={tool.name}
+        width={32}
+        height={32}
+        className="size-8 object-contain rounded-lg"
+        sizes="32px"
+        onError={(e) => { e.target.style.display = "none"; }}
+      />
+    );
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden overflow-x-hidden">
+      <div className="flex items-center justify-between hover:cursor-pointer" onClick={onToggle}>
+        <div className="flex items-center gap-3">
+          <div className="size-8 rounded-lg flex items-center justify-center shrink-0">
+            {renderIcon()}
+          </div>
+          <div className="min-w-0">
+            <h3 className="font-medium text-sm">{tool.name}</h3>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-6 pt-6 border-t border-border">
+          {renderGuideSteps()}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={showModelModal}
+        onClose={() => setShowModelModal(false)}
+        onSelect={handleSelectModel}
+        selectedModel={modelValue}
+        activeProviders={activeProviders}
+        title="Select Model"
+      />
+    </Card>
+  );
+}
+
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/DroidToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/DroidToolCard.js
new file mode 100644
index 0000000..7e8e2ea
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/DroidToolCard.js
@@ -0,0 +1,410 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+const CLOUD_URL = process.env.NEXT_PUBLIC_CLOUD_URL;
+
+export default function DroidToolCard({
+  tool,
+  isExpanded,
+  onToggle,
+  baseUrl,
+  hasActiveProviders,
+  apiKeys,
+  activeProviders,
+  cloudEnabled,
+  initialStatus,
+  tunnelEnabled,
+  tunnelPublicUrl,
+  tailscaleEnabled,
+  tailscaleUrl,
+}) {
+  const [droidStatus, setDroidStatus] = useState(initialStatus || null);
+  const [checkingDroid, setCheckingDroid] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [modelList, setModelList] = useState([]);
+  const [modelInput, setModelInput] = useState("");
+  const [modalOpen, setModalOpen] = useState(false);
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [showInstallGuide, setShowInstallGuide] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+  const hasInitializedModel = useRef(false);
+
+  const getConfigStatus = () => {
+    if (!droidStatus?.installed) return null;
+    // Check for any 9Router model entry (support multi-model: custom:9Router-0, custom:9Router-1, ...)
+    const currentConfig = droidStatus.settings?.customModels?.find(m => m.id?.startsWith("custom:9Router"));
+    if (!currentConfig) return "not_configured";
+    return matchKnownEndpoint(currentConfig.baseUrl, { tunnelPublicUrl, tailscaleUrl, cloudUrl: cloudEnabled ? CLOUD_URL : null }) ? "configured" : "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setDroidStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !droidStatus) {
+      checkDroidStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  // Pre-fill model list from existing config (supports multi-model)
+  useEffect(() => {
+    if (droidStatus?.installed && !hasInitializedModel.current) {
+      hasInitializedModel.current = true;
+      const existingModels = (droidStatus.settings?.customModels || [])
+        .filter(m => m.id?.startsWith("custom:9Router"))
+        .sort((a, b) => (a.index || 0) - (b.index || 0))
+        .map(m => m.model);
+      if (existingModels.length > 0) {
+        setModelList(existingModels);
+      } else {
+        // Legacy: single model stored as custom:9Router-0
+        const legacy = droidStatus.settings?.customModels?.find(m => m.id === "custom:9Router-0");
+        if (legacy?.model) {
+          setModelList([legacy.model]);
+        }
+      }
+    }
+  }, [droidStatus]);
+
+  const checkDroidStatus = async () => {
+    setCheckingDroid(true);
+    try {
+      const res = await fetch("/api/cli-tools/droid-settings");
+      const data = await res.json();
+      setDroidStatus(data);
+    } catch (error) {
+      setDroidStatus({ installed: false, error: error.message });
+    } finally {
+      setCheckingDroid(false);
+    }
+  };
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || baseUrl;
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const getDisplayUrl = () => {
+    const url = customBaseUrl || baseUrl;
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const addModel = () => {
+    const val = modelInput.trim();
+    if (!val || modelList.includes(val)) return;
+    setModelList((prev) => [...prev, val]);
+    setModelInput("");
+  };
+
+  const removeModel = (id) => setModelList((prev) => prev.filter((m) => m !== id));
+
+  const handleModelSelect = (model) => {
+    if (!model.value || modelList.includes(model.value)) return;
+    setModelList((prev) => [...prev, model.value]);
+    setModalOpen(false);
+  };
+
+  const handleApplySettings = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      const keyToUse = selectedApiKey?.trim()
+        || (apiKeys?.length > 0 ? apiKeys[0].key : null)
+        || (!cloudEnabled ? "sk_9router" : null);
+
+      const res = await fetch("/api/cli-tools/droid-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: getEffectiveBaseUrl(),
+          apiKey: keyToUse,
+          models: modelList,
+          activeModel: modelList[0] || "",
+        }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied successfully!" });
+        checkDroidStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleResetSettings = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch("/api/cli-tools/droid-settings", { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        setModelList([]);
+        checkDroidStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+
+    const settingsContent = {
+      customModels: modelList.map((m, i) => ({
+        model: m,
+        id: `custom:9Router-${i}`,
+        index: i,
+        baseUrl: getEffectiveBaseUrl(),
+        apiKey: keyToUse,
+        displayName: m,
+        maxOutputTokens: 131072,
+        noImageSupport: false,
+        provider: "openai",
+      })),
+    };
+
+    const platform = typeof navigator !== "undefined" && navigator.platform;
+    const isWindows = platform?.toLowerCase().includes("win");
+    const settingsPath = isWindows
+      ? "%USERPROFILE%\\.factory\\settings.json"
+      : "~/.factory/settings.json";
+
+    return [
+      {
+        filename: settingsPath,
+        content: JSON.stringify(settingsContent, null, 2),
+      },
+    ];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src="/providers/droid.png" alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checkingDroid && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking Factory Droid CLI...</span>
+            </div>
+          )}
+
+          {!checkingDroid && droidStatus && !droidStatus.installed && (
+            <div className="flex flex-col gap-4">
+              <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+                <div className="flex items-start gap-3">
+                  <span className="material-symbols-outlined text-yellow-500">warning</span>
+                  <div className="flex-1">
+                    <p className="font-medium text-yellow-600 dark:text-yellow-400">Factory Droid CLI not detected locally</p>
+                    <p className="text-sm text-text-muted">Manual configuration is still available if 9router is deployed on a remote server.</p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-2 pl-9">
+                  <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="!bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                    <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                    Manual Config
+                  </Button>
+                  <Button variant="outline" size="sm" onClick={() => setShowInstallGuide(!showInstallGuide)}>
+                    <span className="material-symbols-outlined text-[18px] mr-1">{showInstallGuide ? "expand_less" : "help"}</span>
+                    {showInstallGuide ? "Hide" : "How to Install"}
+                  </Button>
+                </div>
+              </div>
+              {showInstallGuide && (
+                <div className="p-4 bg-surface border border-border rounded-lg">
+                  <h4 className="font-medium mb-3">Installation Guide</h4>
+                  <div className="space-y-3 text-sm">
+                    <div>
+                      <p className="text-text-muted mb-1">macOS / Linux / Windows:</p>
+                      <code className="block px-3 py-2 bg-black/5 dark:bg-white/5 rounded font-mono text-xs">curl -fsSL https://app.factory.ai/cli | sh</code>
+                    </div>
+                    <p className="text-text-muted">After installation, run <code className="px-1 bg-black/5 dark:bg-white/5 rounded">droid</code> to verify.</p>
+                  </div>
+                </div>
+              )}
+            </div>
+          )}
+
+          {!checkingDroid && droidStatus?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                {/* Endpoint (selector) */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getDisplayUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                {/* Current configured */}
+                {droidStatus?.settings?.customModels?.find(m => m.id?.startsWith("custom:9Router"))?.baseUrl && (
+                  <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Current</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <span className="min-w-0 truncate rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                      {droidStatus.settings.customModels.find(m => m.id?.startsWith("custom:9Router")).baseUrl}
+                    </span>
+                  </div>
+                )}
+
+                {/* API Key */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                {/* Models */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">
+                    Models {modelList.length > 0 && <span className="text-primary">({modelList.length})</span>}
+                  </span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <div className="flex-1 flex flex-col gap-1">
+                    {/* Model list */}
+                    {modelList.length > 0 && (
+                      <div className="flex flex-col gap-0.5 mb-1">
+                        {modelList.map((id) => (
+                          <div key={id} className="flex items-center gap-1.5 px-2 py-1 bg-bg-secondary rounded border border-border">
+                            <span className="flex-1 text-xs font-mono truncate">{id}</span>
+                            <button onClick={() => removeModel(id)} className="text-text-muted hover:text-red-500 transition-colors shrink-0" title="Remove">
+                              <span className="material-symbols-outlined text-[12px]">close</span>
+                            </button>
+                          </div>
+                        ))}
+                      </div>
+                    )}
+                    {/* Model input row */}
+                    <div className="flex items-center gap-1.5">
+                      <input
+                        type="text"
+                        value={modelInput}
+                        onChange={(e) => setModelInput(e.target.value)}
+                        onKeyDown={(e) => { if (e.key === "Enter") { e.preventDefault(); addModel(); } }}
+                        placeholder="provider/model-id"
+                        className="w-full min-w-0 px-2 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5"
+                      />
+                      <button
+                        onClick={() => setModalOpen(true)}
+                        disabled={!hasActiveProviders}
+                        className={`px-2 py-1.5 rounded border text-xs shrink-0 ${hasActiveProviders ? "bg-surface border-border hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}
+                      >
+                        Select
+                      </button>
+                      <button onClick={addModel} disabled={!modelInput.trim()} className="px-2 py-1.5 rounded border bg-surface border-border hover:border-primary text-xs shrink-0 disabled:opacity-50" title="Add model">
+                        <span className="material-symbols-outlined text-[14px]">add</span>
+                      </button>
+                    </div>
+                  </div>
+                </div>
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button variant="primary" size="sm" onClick={handleApplySettings} disabled={modelList.length === 0} loading={applying}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleResetSettings} disabled={!droidStatus?.has9Router} loading={restoring}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => setModalOpen(false)}
+        onSelect={handleModelSelect}
+        selectedModel={null}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Model for Factory Droid"
+      />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="Factory Droid - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/EndpointPresetControl.js b/src/app/(dashboard)/dashboard/cli-tools/components/EndpointPresetControl.js
new file mode 100644
index 0000000..d374d19
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/EndpointPresetControl.js
@@ -0,0 +1,128 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+
+const STORAGE_KEY = "9router.cliToolEndpointPresets";
+
+function maskApiKey(apiKey) {
+  if (!apiKey) return "No API key";
+  if (apiKey.length <= 12) return `${apiKey.slice(0, 4)}...`;
+  return `${apiKey.slice(0, 8)}...${apiKey.slice(-4)}`;
+}
+
+function normalizePresets(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((preset) => preset?.name && preset?.baseUrl && preset?.apiKey);
+}
+
+function readPresets() {
+  if (typeof window === "undefined") return [];
+  try {
+    return normalizePresets(JSON.parse(window.localStorage.getItem(STORAGE_KEY) || "[]"));
+  } catch {
+    return [];
+  }
+}
+
+function writePresets(presets) {
+  if (typeof window === "undefined") return;
+  window.localStorage.setItem(STORAGE_KEY, JSON.stringify(normalizePresets(presets)));
+}
+
+export default function EndpointPresetControl({
+  baseUrl,
+  apiKey,
+  onBaseUrlChange,
+  onApiKeyChange,
+}) {
+  const [presets, setPresets] = useState([]);
+  const [selectedName, setSelectedName] = useState("");
+
+  useEffect(() => {
+    setPresets(readPresets());
+  }, []);
+
+  const selectedPreset = useMemo(
+    () => presets.find((preset) => preset.name === selectedName) || null,
+    [presets, selectedName]
+  );
+
+  const handleSelect = (name) => {
+    setSelectedName(name);
+    const preset = presets.find((item) => item.name === name);
+    if (!preset) return;
+    onBaseUrlChange(preset.baseUrl);
+    onApiKeyChange(preset.apiKey);
+  };
+
+  const handleSave = () => {
+    const trimmedBaseUrl = (baseUrl || "").trim();
+    const trimmedApiKey = (apiKey || "").trim();
+    if (!trimmedBaseUrl || !trimmedApiKey) return;
+
+    let defaultName = selectedPreset?.name || trimmedBaseUrl;
+    try {
+      defaultName = selectedPreset?.name || new URL(trimmedBaseUrl).host;
+    } catch {
+      defaultName = selectedPreset?.name || trimmedBaseUrl;
+    }
+    const name = window.prompt("Preset name", defaultName);
+    if (!name?.trim()) return;
+
+    const nextPreset = { name: name.trim(), baseUrl: trimmedBaseUrl, apiKey: trimmedApiKey };
+    const nextPresets = [
+      ...presets.filter((preset) => preset.name !== nextPreset.name),
+      nextPreset,
+    ].sort((a, b) => a.name.localeCompare(b.name));
+
+    setPresets(nextPresets);
+    setSelectedName(nextPreset.name);
+    writePresets(nextPresets);
+  };
+
+  const handleDelete = () => {
+    if (!selectedPreset) return;
+    const nextPresets = presets.filter((preset) => preset.name !== selectedPreset.name);
+    setPresets(nextPresets);
+    setSelectedName("");
+    writePresets(nextPresets);
+  };
+
+  return (
+    <div className="flex items-center gap-2">
+      <span className="w-32 shrink-0 text-sm font-semibold text-text-main text-right">Preset</span>
+      <span className="material-symbols-outlined text-text-muted text-[14px]">arrow_forward</span>
+      <select
+        value={selectedName}
+        onChange={(event) => handleSelect(event.target.value)}
+        className="flex-1 px-2 py-1.5 bg-surface rounded text-xs border border-border focus:outline-none focus:ring-1 focus:ring-primary/50"
+      >
+        <option value="">Manual / current endpoint</option>
+        {presets.map((preset) => (
+          <option key={preset.name} value={preset.name}>
+            {preset.name} - {preset.baseUrl} ({maskApiKey(preset.apiKey)})
+          </option>
+        ))}
+      </select>
+      <button
+        type="button"
+        onClick={handleSave}
+        disabled={!baseUrl || !apiKey}
+        className="px-2 py-1.5 rounded border text-xs bg-surface border-border text-text-main hover:border-primary disabled:opacity-50 disabled:cursor-not-allowed shrink-0"
+        title="Save current Base URL and API key as a browser-local preset"
+      >
+        Save
+      </button>
+      {selectedPreset && (
+        <button
+          type="button"
+          onClick={handleDelete}
+          className="p-1 text-text-muted hover:text-red-500 rounded transition-colors"
+          title="Delete selected preset"
+        >
+          <span className="material-symbols-outlined text-[14px]">delete</span>
+        </button>
+      )}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/HermesToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/HermesToolCard.js
new file mode 100644
index 0000000..806be6b
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/HermesToolCard.js
@@ -0,0 +1,317 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+const ENDPOINT = "/api/cli-tools/hermes-settings";
+
+export default function HermesToolCard({
+  tool,
+  isExpanded,
+  onToggle,
+  baseUrl,
+  hasActiveProviders,
+  apiKeys,
+  activeProviders,
+  cloudEnabled,
+  initialStatus,
+  tunnelEnabled,
+  tunnelPublicUrl,
+  tailscaleEnabled,
+  tailscaleUrl,
+}) {
+  const [hermesStatus, setHermesStatus] = useState(initialStatus || null);
+  const [checking, setChecking] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [selectedModel, setSelectedModel] = useState("");
+  const [modalOpen, setModalOpen] = useState(false);
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+  const hasInitializedModel = useRef(false);
+
+  const getConfigStatus = () => {
+    if (!hermesStatus?.installed) return null;
+    const cfg = hermesStatus.settings?.model;
+    if (!cfg?.base_url) return "not_configured";
+    if (matchKnownEndpoint(cfg.base_url, { tunnelPublicUrl, tailscaleUrl })) return "configured";
+    return "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setHermesStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !hermesStatus) {
+      checkStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  useEffect(() => {
+    if (hermesStatus?.installed && !hasInitializedModel.current) {
+      hasInitializedModel.current = true;
+      const cfg = hermesStatus.settings?.model;
+      if (cfg?.default) setSelectedModel(cfg.default);
+    }
+  }, [hermesStatus]);
+
+  const checkStatus = async () => {
+    setChecking(true);
+    try {
+      const res = await fetch(ENDPOINT);
+      const data = await res.json();
+      setHermesStatus(data);
+    } catch (error) {
+      setHermesStatus({ installed: false, error: error.message });
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  const normalizeLocalhost = (url) => url.replace("://localhost", "://127.0.0.1");
+
+  const getLocalBaseUrl = () => {
+    if (typeof window !== "undefined") {
+      return normalizeLocalhost(window.location.origin);
+    }
+    return "http://127.0.0.1:20128";
+  };
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || getLocalBaseUrl();
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const handleApply = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      const keyToUse = selectedApiKey?.trim()
+        || (apiKeys?.length > 0 ? apiKeys[0].key : null)
+        || (!cloudEnabled ? "sk_9router" : null);
+
+      const res = await fetch(ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: getEffectiveBaseUrl(),
+          apiKey: keyToUse,
+          model: selectedModel,
+        }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied successfully!" });
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleReset = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch(ENDPOINT, { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        setSelectedModel("");
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const handleModelSelect = (model) => {
+    setSelectedModel(model.value);
+    setModalOpen(false);
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+
+    const yamlContent = `model:\n  default: "${selectedModel || "provider/model-id"}"\n  provider: "custom"\n  base_url: "${getEffectiveBaseUrl()}"\n`;
+    const envContent = `OPENAI_API_KEY=${keyToUse}\n`;
+
+    return [
+      { filename: "~/.hermes/config.yaml", content: yamlContent },
+      { filename: "~/.hermes/.env", content: envContent },
+    ];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src="/providers/hermes.png" alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checking && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking Hermes Agent...</span>
+            </div>
+          )}
+
+          {!checking && hermesStatus && !hermesStatus.installed && (
+            <div className="flex flex-col gap-4">
+              <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+                <div className="flex items-start gap-3">
+                  <span className="material-symbols-outlined text-yellow-500">warning</span>
+                  <div className="flex-1">
+                    <p className="font-medium text-yellow-600 dark:text-yellow-400">Hermes Agent not detected locally</p>
+                    <p className="text-sm text-text-muted">Install: curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash</p>
+                  </div>
+                </div>
+                <div className="flex flex-col sm:flex-row sm:items-center gap-2 pl-0 sm:pl-9">
+                  <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="w-full sm:w-auto !bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                    <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                    Manual Config
+                  </Button>
+                </div>
+              </div>
+            </div>
+          )}
+
+          {!checking && hermesStatus?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getEffectiveBaseUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                {hermesStatus?.settings?.model?.base_url && (
+                  <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Current</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <span className="min-w-0 truncate rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                      {hermesStatus.settings.model.base_url}
+                    </span>
+                  </div>
+                )}
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Default Model</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <div className="relative w-full min-w-0">
+                    <input type="text" value={selectedModel} onChange={(e) => setSelectedModel(e.target.value)} placeholder="provider/model-id" className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5" />
+                    {selectedModel && <button onClick={() => setSelectedModel("")} className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors" title="Clear"><span className="material-symbols-outlined text-[14px]">close</span></button>}
+                  </div>
+                  <button onClick={() => setModalOpen(true)} disabled={!hasActiveProviders} className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${hasActiveProviders ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Select</button>
+                </div>
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="flex flex-col sm:flex-row sm:items-center gap-2">
+                <Button variant="primary" size="sm" onClick={handleApply} disabled={!selectedModel} loading={applying} className="w-full sm:w-auto">
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleReset} disabled={!hermesStatus?.has9Router} loading={restoring} className="w-full sm:w-auto">
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)} className="w-full sm:w-auto">
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => setModalOpen(false)}
+        onSelect={handleModelSelect}
+        selectedModel={selectedModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Model for Hermes Agent"
+      />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="Hermes Agent - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/JcodeToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/JcodeToolCard.js
new file mode 100644
index 0000000..487def9
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/JcodeToolCard.js
@@ -0,0 +1,380 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+export default function JcodeToolCard({
+  tool,
+  isExpanded,
+  onToggle,
+  baseUrl,
+  hasActiveProviders,
+  apiKeys,
+  activeProviders,
+  cloudEnabled,
+  initialStatus,
+  tunnelEnabled,
+  tunnelPublicUrl,
+  tailscaleEnabled,
+  tailscaleUrl,
+}) {
+  const [jcodeStatus, setJcodeStatus] = useState(initialStatus || null);
+  const [checkingJcode, setCheckingJcode] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [selectedModel, setSelectedModel] = useState("");
+  const [modalOpen, setModalOpen] = useState(false);
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+  const hasInitializedModel = useRef(false);
+
+  const getConfigStatus = () => {
+    if (!jcodeStatus?.installed) return null;
+    if (!jcodeStatus?.has9Router) return "not_configured";
+    const currentProvider = jcodeStatus.config?.providers?.["9router"];
+    if (!currentProvider) return "not_configured";
+    return matchKnownEndpoint(currentProvider.base_url, { tunnelPublicUrl, tailscaleUrl }) ? "configured" : "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setJcodeStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !jcodeStatus) {
+      checkJcodeStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  useEffect(() => {
+    if (jcodeStatus?.installed && !hasInitializedModel.current) {
+      hasInitializedModel.current = true;
+      const provider = jcodeStatus.config?.providers?.["9router"];
+      if (provider) {
+        if (provider.default_model) {
+          setSelectedModel(provider.default_model);
+        }
+        // Try to match API key from env file
+        const envApiKey = jcodeStatus.envApiKey;
+        if (envApiKey && apiKeys?.some(k => k.key === envApiKey)) {
+          setSelectedApiKey(envApiKey);
+        }
+      }
+    }
+  }, [jcodeStatus, apiKeys]);
+
+  const checkJcodeStatus = async () => {
+    setCheckingJcode(true);
+    try {
+      const res = await fetch("/api/cli-tools/jcode-settings");
+      const data = await res.json();
+      setJcodeStatus(data);
+    } catch (error) {
+      setJcodeStatus({ installed: false, error: error.message });
+    } finally {
+      setCheckingJcode(false);
+    }
+  };
+
+  const normalizeLocalhost = (url) => url.replace("://localhost", "://127.0.0.1");
+
+  const getLocalBaseUrl = () => {
+    if (typeof window !== "undefined") {
+      return normalizeLocalhost(window.location.origin);
+    }
+    return "http://127.0.0.1:20128";
+  };
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || getLocalBaseUrl();
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const getDisplayUrl = () => {
+    const url = customBaseUrl || getLocalBaseUrl();
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const handleApplySettings = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      const keyToUse = selectedApiKey?.trim()
+        || (apiKeys?.length > 0 ? apiKeys[0].key : null)
+        || (!cloudEnabled ? "sk_9router" : null);
+
+      const res = await fetch("/api/cli-tools/jcode-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: getEffectiveBaseUrl(),
+          apiKey: keyToUse,
+          models: selectedModel ? [selectedModel] : [],
+        }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied successfully!" });
+        checkJcodeStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleResetSettings = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch("/api/cli-tools/jcode-settings", { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        setSelectedModel("");
+        setSelectedApiKey("");
+        checkJcodeStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const handleModelSelect = (model) => {
+    setSelectedModel(model.value);
+    setModalOpen(false);
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+
+    const configToml = `[providers.9router]
+type = "openai-compatible"
+base_url = "${getEffectiveBaseUrl()}"
+auth = "bearer"
+api_key_env = "JCODE_9ROUTER_API_KEY"
+env_file = "provider-9router.env"
+default_model = "${selectedModel || "cc/claude-opus-4-7"}"
+requires_api_key = true
+
+[[providers.9router.models]]
+id = "${selectedModel || "cc/claude-opus-4-7"}"`;
+
+    const envContent = `JCODE_9ROUTER_API_KEY="${keyToUse}"`;
+
+    return [
+      {
+        filename: "~/.jcode/config.toml",
+        content: configToml,
+      },
+      {
+        filename: "~/.config/jcode/provider-9router.env",
+        content: envContent,
+      },
+    ];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src={tool.image || "/providers/jcode.png"} alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checkingJcode && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking jcode CLI...</span>
+            </div>
+          )}
+
+          {!checkingJcode && jcodeStatus && !jcodeStatus.installed && (
+            <div className="flex flex-col gap-4">
+              <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+                <div className="flex items-start gap-3">
+                  <span className="material-symbols-outlined text-yellow-500">warning</span>
+                  <div className="flex-1">
+                    <p className="font-medium text-yellow-600 dark:text-yellow-400">jcode CLI not detected locally</p>
+                    <p className="text-sm text-text-muted mt-1">Install jcode to enable automatic configuration:</p>
+                    <code className="block mt-2 p-2 bg-black/20 rounded text-xs font-mono">
+                      curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash
+                    </code>
+                    <p className="text-sm text-text-muted mt-2">Manual configuration is still available if 9router is deployed on a remote server.</p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-2 pl-9">
+                  <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="!bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                    <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                    Manual Config
+                  </Button>
+                </div>
+              </div>
+            </div>
+          )}
+
+          {!checkingJcode && jcodeStatus?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                {/* Info notes */}
+                {tool.notes && tool.notes.length > 0 && (
+                  <div className="flex flex-col gap-2 mb-2">
+                    {tool.notes.map((note, idx) => (
+                      <div key={idx} className={`flex items-start gap-2 p-2 rounded text-xs ${
+                        note.type === "info" ? "bg-blue-500/10 text-blue-600 dark:text-blue-400" :
+                        note.type === "warning" ? "bg-yellow-500/10 text-yellow-600 dark:text-yellow-400" :
+                        "bg-gray-500/10 text-text-muted"
+                      }`}>
+                        <span className="material-symbols-outlined text-[14px] mt-0.5">
+                          {note.type === "info" ? "info" : note.type === "warning" ? "warning" : "help"}
+                        </span>
+                        <span>{note.text}</span>
+                      </div>
+                    ))}
+                  </div>
+                )}
+
+                {/* Endpoint (selector) */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getDisplayUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                {/* Current configured */}
+                {jcodeStatus?.config?.providers?.["9router"]?.base_url && (
+                  <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Current</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <span className="min-w-0 truncate rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                      {jcodeStatus.config.providers["9router"].base_url}
+                    </span>
+                  </div>
+                )}
+
+                {/* API Key */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                {/* Default Model */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Default Model</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <div className="relative w-full min-w-0">
+                    <input type="text" value={selectedModel} onChange={(e) => setSelectedModel(e.target.value)} placeholder="cc/claude-opus-4-7" className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5" />
+                    {selectedModel && <button onClick={() => setSelectedModel("")} className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors" title="Clear"><span className="material-symbols-outlined text-[14px]">close</span></button>}
+                  </div>
+                  <button onClick={() => setModalOpen(true)} disabled={!hasActiveProviders} className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${hasActiveProviders ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Select</button>
+                </div>
+
+                {/* Usage hint */}
+                <div className="flex flex-col gap-1 p-3 bg-blue-500/5 border border-blue-500/20 rounded-lg">
+                  <p className="text-xs font-medium text-blue-600 dark:text-blue-400">Usage:</p>
+                  <code className="text-xs font-mono text-text-muted">jcode --provider-profile 9router</code>
+                  <code className="text-xs font-mono text-text-muted">jcode --provider-profile 9router --model {selectedModel || "cc/claude-opus-4-7"}</code>
+                </div>
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button variant="primary" size="sm" onClick={handleApplySettings} disabled={!selectedModel} loading={applying}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleResetSettings} disabled={!jcodeStatus?.has9Router} loading={restoring}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => setModalOpen(false)}
+        onSelect={handleModelSelect}
+        selectedModel={selectedModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Model for jcode"
+      />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="jcode - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/KiloToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/KiloToolCard.js
new file mode 100644
index 0000000..2a8a074
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/KiloToolCard.js
@@ -0,0 +1,275 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+export default function KiloToolCard({ tool, isExpanded, onToggle, baseUrl, apiKeys, activeProviders, cloudEnabled, initialStatus, tunnelEnabled, tunnelPublicUrl, tailscaleEnabled, tailscaleUrl }) {
+  const [status, setStatus] = useState(initialStatus || null);
+  const [checking, setChecking] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [showInstallGuide, setShowInstallGuide] = useState(false);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [selectedModel, setSelectedModel] = useState("");
+  const [modalOpen, setModalOpen] = useState(false);
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) setSelectedApiKey(apiKeys[0].key);
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !status) {
+      checkStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  const getConfigStatus = () => {
+    if (!status?.installed) return null;
+    return status.has9Router ? "configured" : "not_configured";
+  };
+
+  const configStatus = getConfigStatus();
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || `${baseUrl}/v1`;
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const getDisplayUrl = () => customBaseUrl || `${baseUrl}/v1`;
+
+  const checkStatus = async () => {
+    setChecking(true);
+    try {
+      const res = await fetch("/api/cli-tools/kilo-settings");
+      const data = await res.json();
+      setStatus(data);
+    } catch (error) {
+      setStatus({ installed: false, error: error.message });
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  const handleApply = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      const keyToUse = (selectedApiKey && selectedApiKey.trim())
+        ? selectedApiKey
+        : (!cloudEnabled ? "sk_9router" : selectedApiKey);
+
+      const res = await fetch("/api/cli-tools/kilo-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ baseUrl: getEffectiveBaseUrl(), apiKey: keyToUse, model: selectedModel }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied successfully!" });
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleReset = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch("/api/cli-tools/kilo-settings", { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        setSelectedModel("");
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+
+    return [{
+      filename: "~/.local/share/kilo/auth.json",
+      content: JSON.stringify({
+        "openai-compatible": {
+          type: "api-key",
+          apiKey: keyToUse,
+          baseUrl: getEffectiveBaseUrl(),
+          model: selectedModel || "provider/model-id",
+        },
+      }, null, 2),
+    }];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src="/providers/kilocode.png" alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checking && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking Kilo Code...</span>
+            </div>
+          )}
+
+          {!checking && status && !status.installed && (
+            <div className="flex flex-col gap-4">
+              <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+                <div className="flex items-start gap-3">
+                  <span className="material-symbols-outlined text-yellow-500">warning</span>
+                  <div className="flex-1">
+                    <p className="font-medium text-yellow-600 dark:text-yellow-400">Kilo Code not detected locally</p>
+                    <p className="text-sm text-text-muted">Manual configuration is still available if 9router is deployed on a remote server.</p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-2 pl-9">
+                  <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="!bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                    <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                    Manual Config
+                  </Button>
+                  <Button variant="outline" size="sm" onClick={() => setShowInstallGuide(!showInstallGuide)}>
+                    <span className="material-symbols-outlined text-[18px] mr-1">{showInstallGuide ? "expand_less" : "help"}</span>
+                    {showInstallGuide ? "Hide" : "How to Install"}
+                  </Button>
+                </div>
+              </div>
+              {showInstallGuide && (
+                <div className="p-4 bg-surface border border-border rounded-lg">
+                  <h4 className="font-medium mb-3">Installation Guide</h4>
+                  <p className="text-sm text-text-muted">Install Kilo Code from <a className="text-primary underline" href="https://kilocode.ai" target="_blank" rel="noreferrer">kilocode.ai</a> or VS Code extension marketplace.</p>
+                </div>
+              )}
+            </div>
+          )}
+
+          {!checking && status?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getDisplayUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Model</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <div className="relative w-full min-w-0">
+                    <input type="text" value={selectedModel} onChange={(e) => setSelectedModel(e.target.value)} placeholder="provider/model-id" className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5" />
+                    {selectedModel && <button onClick={() => setSelectedModel("")} className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors" title="Clear"><span className="material-symbols-outlined text-[14px]">close</span></button>}
+                  </div>
+                  <button onClick={() => setModalOpen(true)} disabled={!activeProviders?.length} className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${activeProviders?.length ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Select Model</button>
+                </div>
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button variant="primary" size="sm" onClick={handleApply} disabled={(!selectedApiKey && (cloudEnabled && apiKeys.length > 0)) || !selectedModel} loading={applying}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleReset} disabled={restoring} loading={restoring}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => setModalOpen(false)}
+        onSelect={(model) => { setSelectedModel(model.value); setModalOpen(false); }}
+        selectedModel={selectedModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Model for Kilo Code"
+      />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="Kilo Code - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/MitmLinkCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/MitmLinkCard.js
new file mode 100644
index 0000000..865128e
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/MitmLinkCard.js
@@ -0,0 +1,40 @@
+"use client";
+
+import Link from "next/link";
+import { Card } from "@/shared/components";
+import Image from "next/image";
+
+/**
+ * Clickable card for MITM tools — navigates to /dashboard/mitm on click.
+ */
+export default function MitmLinkCard({ tool }) {
+  return (
+    <Link href="/dashboard/mitm" className="block">
+      <Card padding="sm" className="overflow-hidden hover:border-primary/50 transition-colors cursor-pointer">
+        <div className="flex items-center justify-between">
+          <div className="flex items-center gap-3">
+            <div className="size-8 flex items-center justify-center shrink-0">
+              <Image
+                src={tool.image}
+                alt={tool.name}
+                width={32}
+                height={32}
+                className="size-8 object-contain rounded-lg"
+                sizes="32px"
+                onError={(e) => { e.target.style.display = "none"; }}
+              />
+            </div>
+            <div className="min-w-0">
+              <div className="flex items-center gap-2">
+                <h3 className="font-medium text-sm">{tool.name}</h3>
+                <span className="px-1.5 py-0.5 text-[10px] font-medium bg-purple-500/10 text-purple-600 dark:text-purple-400 rounded-full">MITM</span>
+              </div>
+              <p className="text-xs text-text-muted truncate">{tool.description}</p>
+            </div>
+          </div>
+          <span className="material-symbols-outlined text-text-muted text-[20px]">chevron_right</span>
+        </div>
+      </Card>
+    </Link>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/MitmServerCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/MitmServerCard.js
new file mode 100644
index 0000000..8b2ab41
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/MitmServerCard.js
@@ -0,0 +1,329 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import { Card, Button, Badge, Input } from "@/shared/components";
+
+const DEFAULT_MITM_ROUTER_BASE = "http://localhost:20128";
+
+/**
+ * Shared MITM infrastructure card — manages SSL cert + server start/stop.
+ * DNS per-tool is handled separately in MitmToolCard.
+ */
+export default function MitmServerCard({ apiKeys, cloudEnabled, onStatusChange }) {
+  const [status, setStatus] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [showPasswordModal, setShowPasswordModal] = useState(false);
+  const [sudoPassword, setSudoPassword] = useState("");
+  const [selectedApiKey, setSelectedApiKey] = useState(() => apiKeys?.[0]?.key || "");
+  const [pendingAction, setPendingAction] = useState(null);
+  const [modalError, setModalError] = useState(null);
+  const [actionError, setActionError] = useState(null);
+  const [mitmRouterBaseUrl, setMitmRouterBaseUrl] = useState(DEFAULT_MITM_ROUTER_BASE);
+  const [port443Conflict, setPort443Conflict] = useState(null);
+
+  const serverIsWindows = status?.isWin === true;
+  const canRunWithoutPassword = serverIsWindows || status?.hasCachedPassword || status?.needsSudoPassword === false;
+  const isAdmin = status?.isAdmin !== false;
+  // No privilege: not admin/root AND (Win OR no cached sudo password)
+  const noPrivilege = !isAdmin && (serverIsWindows || (!status?.hasCachedPassword && status?.needsSudoPassword !== false));
+
+  const fetchStatus = useCallback(async () => {
+    try {
+      const res = await fetch("/api/cli-tools/antigravity-mitm");
+      if (res.ok) {
+        const data = await res.json();
+        setStatus(data);
+        if (data.mitmRouterBaseUrl) {
+          setMitmRouterBaseUrl(data.mitmRouterBaseUrl);
+        }
+        onStatusChange?.(data);
+      }
+    } catch {
+      setStatus({ running: false, certExists: false, dnsStatus: {} });
+    }
+  }, [onStatusChange]);
+
+  useEffect(() => {
+    queueMicrotask(() => {
+      fetchStatus();
+    });
+  }, [fetchStatus]);
+
+  const handleAction = (action) => {
+    setActionError(null);
+    // Wait for status to load before deciding whether to show sudo modal
+    if (!status) return;
+    if (canRunWithoutPassword) {
+      doAction(action, "");
+    } else {
+      setPendingAction(action);
+      setShowPasswordModal(true);
+      setModalError(null);
+    }
+  };
+
+  const doAction = async (action, password, forceKillPort443 = false) => {
+    setLoading(true);
+    setActionError(null);
+    try {
+      let res;
+      if (action === "trust-cert") {
+        res = await fetch("/api/cli-tools/antigravity-mitm", {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ action: "trust-cert", sudoPassword: password }),
+        });
+      } else if (action === "start") {
+        const keyToUse = selectedApiKey?.trim()
+          || (apiKeys?.length > 0 ? apiKeys[0].key : null)
+          || (!cloudEnabled ? "sk_9router" : null);
+        res = await fetch("/api/cli-tools/antigravity-mitm", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            apiKey: keyToUse,
+            sudoPassword: password,
+            mitmRouterBaseUrl: mitmRouterBaseUrl.trim() || DEFAULT_MITM_ROUTER_BASE,
+            forceKillPort443,
+          }),
+        });
+      } else {
+        res = await fetch("/api/cli-tools/antigravity-mitm", {
+          method: "DELETE",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ sudoPassword: password }),
+        });
+      }
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        if (data.code === "PORT_443_BUSY" && data.portOwner) {
+          setShowPasswordModal(false);
+          setPort443Conflict({ owner: data.portOwner, password });
+          return;
+        }
+        setActionError(data.error || `Failed to ${action} MITM server`);
+        return;
+      }
+      setShowPasswordModal(false);
+      setSudoPassword("");
+      setPort443Conflict(null);
+      await fetchStatus();
+    } catch (e) {
+      setActionError(e.message || "Network error");
+    } finally {
+      setLoading(false);
+      setPendingAction(null);
+    }
+  };
+
+  const handleKillAndStart = () => {
+    const pwd = port443Conflict?.password || "";
+    doAction("start", pwd, true);
+  };
+
+  const handleConfirmPassword = () => {
+    if (!sudoPassword.trim()) {
+      setModalError("Sudo password is required");
+      return;
+    }
+    doAction(pendingAction, sudoPassword);
+  };
+
+  const isRunning = status?.running;
+
+  return (
+    <>
+      <Card padding="sm" className="border-primary/20 bg-primary/5">
+        <div className="flex flex-col gap-3">
+          {/* Header */}
+          <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <span className="material-symbols-outlined text-primary text-[20px]">security</span>
+              <span className="font-semibold text-sm text-text-main">MITM Server</span>
+              {isRunning ? (
+                <Badge variant="success" size="sm">Running</Badge>
+              ) : (
+                <Badge variant="default" size="sm">Stopped</Badge>
+              )}
+            </div>
+            <div className="flex flex-wrap items-center gap-1 text-xs text-text-muted" data-i18n-skip="true">
+              {[
+                { label: "Cert", ok: status?.certExists },
+                { label: "Trusted", ok: status?.certTrusted },
+                { label: "Server", ok: isRunning },
+              ].map(({ label, ok }) => (
+                <span key={label} className={`flex items-center gap-0.5 px-1.5 py-0.5 rounded ${ok ? "text-green-600" : "text-text-muted"}`}>
+                  <span className="material-symbols-outlined text-[12px]">
+                    {ok ? "check_circle" : "cancel"}
+                  </span>
+                  {label}
+                </span>
+              ))}
+            </div>
+          </div>
+
+          {/* Purpose & How it works */}
+          <div className="px-2 py-2 rounded-lg bg-surface/50 border border-border/50 flex flex-col gap-2">
+            <p className="text-[11px] text-text-muted leading-relaxed">
+              <span className="font-medium text-text-main">Purpose:</span> Use Antigravity IDE & GitHub Copilot → with ANY provider/model from 9Router
+            </p>
+            <p className="text-[11px] text-text-muted leading-relaxed">
+              <span className="font-medium text-text-main">How it works:</span> Antigravity/Copilot IDE request → DNS redirect to localhost:443 → MITM proxy intercepts → 9Router → response to Antigravity/Copilot
+            </p>
+          </div>
+
+          {/* Base URL + API Key — same row pattern as Claude Code / cli-tools */}
+          <div className="flex flex-col gap-2">
+            <div className="grid gap-1 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+              <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">9Router Base URL</span>
+              <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+              <input
+                type="text"
+                value={mitmRouterBaseUrl}
+                onChange={(e) => setMitmRouterBaseUrl(e.target.value)}
+                placeholder={DEFAULT_MITM_ROUTER_BASE}
+                disabled={isRunning}
+                className="flex-1 min-w-0 px-2 py-1.5 bg-surface rounded border border-border text-xs text-text-main focus:outline-none focus:ring-1 focus:ring-primary/50 disabled:opacity-50"
+              />
+            </div>
+            {!isRunning && (
+              <div className="grid gap-1 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                <input
+                  type="text"
+                  list="mitm-api-keys"
+                  value={selectedApiKey}
+                  onChange={(e) => setSelectedApiKey(e.target.value)}
+                  placeholder={cloudEnabled ? "Enter or pick API key" : "sk_9router (default)"}
+                  className="flex-1 min-w-0 px-2 py-1.5 bg-surface rounded border border-border text-xs text-text-main focus:outline-none focus:ring-1 focus:ring-primary/50"
+                />
+                {apiKeys?.length > 0 && (
+                  <datalist id="mitm-api-keys">
+                    {apiKeys.map((key) => (
+                      <option key={key.id} value={key.key}>{key.name || key.key}</option>
+                    ))}
+                  </datalist>
+                )}
+              </div>
+            )}
+          </div>
+
+          {/* Action buttons */}
+          <div className="flex flex-col gap-2 sm:flex-row sm:flex-wrap sm:items-center" data-i18n-skip="true">
+            {status?.certExists && !status?.certTrusted && (
+              <button
+                onClick={() => handleAction("trust-cert")}
+                disabled={loading}
+                className="flex w-full items-center justify-center gap-1.5 rounded-lg border border-yellow-500/30 bg-yellow-500/10 px-4 py-2 text-xs font-medium text-yellow-600 transition-colors hover:bg-yellow-500/20 disabled:opacity-50 sm:w-auto sm:py-1.5"
+              >
+                <span className="material-symbols-outlined text-[16px]">verified_user</span>
+                Trust Cert
+              </button>
+            )}
+            {isRunning ? (
+              <button
+                onClick={() => handleAction("stop")}
+                disabled={loading}
+                className="flex w-full items-center justify-center gap-1.5 rounded-lg border border-red-500/30 bg-red-500/10 px-4 py-2 text-xs font-medium text-red-500 transition-colors hover:bg-red-500/20 disabled:opacity-50 sm:w-auto sm:py-1.5"
+              >
+                <span className="material-symbols-outlined text-[16px]">stop_circle</span>
+                Stop Server
+              </button>
+            ) : (
+              <button
+                onClick={() => handleAction("start")}
+                disabled={loading || !status || (serverIsWindows && !isAdmin)}
+                title={serverIsWindows && !isAdmin ? "Administrator required" : undefined}
+                className="flex w-full items-center justify-center gap-1.5 rounded-lg border border-primary/30 bg-primary/10 px-4 py-2 text-xs font-medium text-primary transition-colors hover:bg-primary/20 disabled:opacity-50 sm:w-auto sm:py-1.5"
+              >
+                <span className="material-symbols-outlined text-[16px]">play_circle</span>
+                Start Server
+              </button>
+            )}
+            {isRunning && (
+              <p className="text-xs text-text-muted">Enable DNS per tool below to activate interception</p>
+            )}
+          </div>
+
+          {/* Action error */}
+          {actionError && (
+            <div className="flex items-start gap-2 px-2 py-1.5 rounded text-xs bg-red-500/10 text-red-600 dark:text-red-400 border border-red-500/20">
+              <span className="material-symbols-outlined text-[14px] mt-0.5 shrink-0">error</span>
+              <span>{actionError}</span>
+            </div>
+          )}
+
+          {/* Windows admin warning */}
+          {serverIsWindows && !isAdmin && (
+            <div className="flex items-center gap-2 px-2 py-1.5 rounded text-xs bg-red-500/10 text-red-600 border border-red-500/20">
+              <span className="material-symbols-outlined text-[14px]">shield_lock</span>
+              <span>Administrator required — restart 9Router as Administrator to use MITM</span>
+            </div>
+          )}
+        </div>
+      </Card>
+
+      {/* Password Modal */}
+      {showPasswordModal && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 backdrop-blur-sm">
+          <div className="mx-4 flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-surface p-5 shadow-xl sm:p-6">
+            <h3 className="font-semibold text-text-main">Sudo Password Required</h3>
+            <div className="flex items-start gap-3 p-3 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+              <span className="material-symbols-outlined text-yellow-500 text-[20px]">warning</span>
+              <p className="text-xs text-text-muted">Required for SSL certificate and server startup</p>
+            </div>
+            <Input
+              type="password"
+              placeholder="Enter sudo password"
+              value={sudoPassword}
+              onChange={(e) => setSudoPassword(e.target.value)}
+              onKeyDown={(e) => { if (e.key === "Enter" && !loading) handleConfirmPassword(); }}
+            />
+            {modalError && (
+              <div className="flex items-center gap-2 px-2 py-1.5 rounded text-xs bg-red-500/10 text-red-600">
+                <span className="material-symbols-outlined text-[14px]">error</span>
+                <span>{modalError}</span>
+              </div>
+            )}
+            <div className="flex items-center justify-end gap-2">
+              <Button variant="ghost" size="sm" onClick={() => { setShowPasswordModal(false); setSudoPassword(""); setModalError(null); }} disabled={loading}>
+                Cancel
+              </Button>
+              <Button variant="primary" size="sm" onClick={handleConfirmPassword} loading={loading}>
+                Confirm
+              </Button>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Port 443 Conflict Modal */}
+      {port443Conflict && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 backdrop-blur-sm">
+          <div className="mx-4 flex w-full max-w-md flex-col gap-4 rounded-xl border border-border bg-surface p-5 shadow-xl sm:p-6">
+            <h3 className="font-semibold text-text-main">Port 443 Already In Use</h3>
+            <div className="flex items-start gap-3 p-3 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+              <span className="material-symbols-outlined text-yellow-500 text-[20px]">warning</span>
+              <div className="flex flex-col gap-1 text-xs text-text-muted">
+                <p>Port 443 is currently used by another process:</p>
+                <p className="font-mono text-text-main" data-i18n-skip="true">
+                  {port443Conflict.owner.name} (PID {port443Conflict.owner.pid})
+                </p>
+                <p>Kill this process to start MITM Server?</p>
+              </div>
+            </div>
+            <div className="flex items-center justify-end gap-2">
+              <Button variant="ghost" size="sm" onClick={() => { setPort443Conflict(null); setLoading(false); }} disabled={loading}>
+                Cancel
+              </Button>
+              <Button variant="primary" size="sm" onClick={handleKillAndStart} loading={loading}>
+                Kill & Start
+              </Button>
+            </div>
+          </div>
+        </div>
+      )}
+    </>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/MitmToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/MitmToolCard.js
new file mode 100644
index 0000000..8238429
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/MitmToolCard.js
@@ -0,0 +1,318 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import { Card, Button, Badge, Input, ModelSelectModal } from "@/shared/components";
+import { TOOL_HOSTS } from "@/shared/constants/mitmToolHosts";
+import Image from "next/image";
+
+/**
+ * Per-tool MITM card — shows DNS status + model mappings.
+ * - Auto-saves model mapping on blur or modal select
+ * - Skips sudo modal if password is already cached
+ * - Model mappings can only be edited when DNS is active
+ */
+export default function MitmToolCard({
+  tool,
+  isExpanded,
+  onToggle,
+  serverRunning,
+  dnsActive,
+  hasCachedPassword,
+  needsSudoPassword,
+  isWin,
+  apiKeys,
+  activeProviders,
+  hasActiveProviders,
+  modelAliases = {},
+  cloudEnabled,
+  onDnsChange,
+}) {
+  const [loading, setLoading] = useState(false);
+  const [warning, setWarning] = useState(null);
+  const [showPasswordModal, setShowPasswordModal] = useState(false);
+  const [sudoPassword, setSudoPassword] = useState("");
+  const [pendingDnsAction, setPendingDnsAction] = useState(null);
+  const [modalError, setModalError] = useState(null);
+  const [modelMappings, setModelMappings] = useState({});
+  const [modalOpen, setModalOpen] = useState(false);
+  const [currentEditingAlias, setCurrentEditingAlias] = useState(null);
+
+  const mitmHosts = TOOL_HOSTS[tool.id] ?? [];
+  const canRunWithoutPassword = isWin || hasCachedPassword || needsSudoPassword === false;
+
+  useEffect(() => {
+    if (isExpanded) loadSavedMappings();
+  }, [isExpanded]);
+
+  const loadSavedMappings = async () => {
+    try {
+      const res = await fetch(`/api/cli-tools/antigravity-mitm/alias?tool=${tool.id}`);
+      if (res.ok) {
+        const data = await res.json();
+        if (Object.keys(data.aliases || {}).length > 0) setModelMappings(data.aliases);
+      }
+    } catch { /* ignore */ }
+  };
+
+  const saveMappings = useCallback(async (mappings) => {
+    try {
+      await fetch("/api/cli-tools/antigravity-mitm/alias", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ tool: tool.id, mappings }),
+      });
+    } catch { /* ignore */ }
+  }, [tool.id]);
+
+  const handleMappingBlur = (alias, value) => {
+    saveMappings({ ...modelMappings, [alias]: value });
+  };
+
+  const handleModelMappingChange = (alias, value) => {
+    setModelMappings(prev => ({ ...prev, [alias]: value }));
+  };
+
+  const openModelSelector = (alias) => {
+    setCurrentEditingAlias(alias);
+    setModalOpen(true);
+  };
+
+  const handleModelSelect = (model) => {
+    if (!currentEditingAlias || model.isPlaceholder) return;
+    const updated = { ...modelMappings, [currentEditingAlias]: model.value };
+    setModelMappings(updated);
+    saveMappings(updated);
+  };
+
+  const handleDnsToggle = () => {
+    if (!serverRunning) return;
+    const action = dnsActive ? "disable" : "enable";
+    if (canRunWithoutPassword) {
+      doDnsAction(action, "");
+    } else {
+      setPendingDnsAction(action);
+      setShowPasswordModal(true);
+      setModalError(null);
+    }
+  };
+
+  const doDnsAction = async (action, password) => {
+    setLoading(true);
+    setWarning(null);
+    try {
+      const res = await fetch("/api/cli-tools/antigravity-mitm", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ tool: tool.id, action, sudoPassword: password }),
+      });
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error || "Failed to toggle DNS");
+
+      if (action === "enable") {
+        setWarning(`Restart ${tool.name} to apply changes`);
+      }
+
+      setShowPasswordModal(false);
+      setSudoPassword("");
+      onDnsChange?.(data);
+    } catch { /* ignore */ } finally {
+      setLoading(false);
+      setPendingDnsAction(null);
+    }
+  };
+
+  const handleConfirmPassword = () => {
+    if (!sudoPassword.trim()) {
+      setModalError("Sudo password is required");
+      return;
+    }
+    doDnsAction(pendingDnsAction, sudoPassword);
+  };
+
+  return (
+    <>
+      <Card padding="xs" className="overflow-hidden">
+        <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+          <div className="flex min-w-0 items-center gap-3">
+            <div className="size-8 flex items-center justify-center shrink-0">
+              <Image
+                src={tool.image}
+                alt={tool.name}
+                width={32}
+                height={32}
+                className="size-8 object-contain rounded-lg"
+                sizes="32px"
+                onError={(e) => { e.target.style.display = "none"; }}
+              />
+            </div>
+            <div className="min-w-0">
+              <div className="flex flex-wrap items-center gap-2">
+                <h3 className="font-medium text-sm">{tool.name}</h3>
+                {!serverRunning ? (
+                  <Badge variant="default" size="sm">Server off</Badge>
+                ) : dnsActive ? (
+                  <Badge variant="success" size="sm">Active</Badge>
+                ) : (
+                  <Badge variant="warning" size="sm">DNS off</Badge>
+                )}
+              </div>
+              <p className="text-xs text-text-muted sm:truncate">Intercept {tool.name} requests via MITM proxy</p>
+            </div>
+          </div>
+          <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>
+            expand_more
+          </span>
+        </div>
+
+        {isExpanded && (
+          <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+            {/* Hosts */}
+            {mitmHosts.length > 0 && (
+              <div className="mt-2 rounded-md border border-border bg-surface/50 px-2 py-1.5">
+                <p className="text-[10px] font-medium tracking-wide text-text-main/80 mb-1">
+                  Edit hosts file manually to add the following entries:
+                </p>
+                <ul className="list-none space-y-0.5 font-mono text-[10px] text-text-muted break-all">
+                  {mitmHosts.map((h) => (
+                    <li key={h}>127.0.0.1 {h}</li>
+                  ))}
+                </ul>
+              </div>
+            )}
+            {/* Info */}
+            <div className="flex flex-col gap-0.5 text-[11px] text-text-muted px-1">
+              <p>Toggle DNS to redirect {tool.name} traffic through 9Router via MITM.</p>
+              {!dnsActive && (
+                <p className="text-amber-600 text-[10px] mt-1">
+                  ⚠️ Enable DNS to edit model mappings
+                </p>
+              )}
+            </div>
+
+            {/* Model Mappings */}
+            {tool.defaultModels?.length > 0 && (
+              <div className="flex flex-col gap-2">
+                {tool.defaultModels.map((model) => (
+                  <div key={model.alias} className="grid grid-cols-1 gap-1.5 sm:grid-cols-[9rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right">{model.name}</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <div className="relative w-full min-w-0">
+                      <input
+                        type="text"
+                        value={modelMappings[model.alias] || ""}
+                        onChange={(e) => handleModelMappingChange(model.alias, e.target.value)}
+                        onBlur={(e) => handleMappingBlur(model.alias, e.target.value)}
+                        placeholder="provider/model-id"
+                        disabled={!dnsActive}
+                        className={`w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5 ${!dnsActive ? "opacity-50 cursor-not-allowed" : ""}`}
+                      />
+                      {modelMappings[model.alias] && (
+                        <button
+                          onClick={() => {
+                            handleModelMappingChange(model.alias, "");
+                            saveMappings({ ...modelMappings, [model.alias]: "" });
+                          }}
+                          className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors"
+                          title="Clear"
+                        >
+                          <span className="material-symbols-outlined text-[14px]">close</span>
+                        </button>
+                      )}
+                    </div>
+                    <button
+                      onClick={() => openModelSelector(model.alias)}
+                      disabled={!hasActiveProviders || !dnsActive}
+                      className={`rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 ${hasActiveProviders && dnsActive ? "bg-surface border-border hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}
+                    >
+                      Select
+                    </button>
+                  </div>
+                ))}
+              </div>
+            )}
+
+            {tool.defaultModels?.length === 0 && (
+              <p className="text-xs text-text-muted px-1">Model mappings will be available soon.</p>
+            )}
+
+            {/* Start / Stop DNS button */}
+            <div className="flex flex-col gap-2 sm:items-start">
+              {dnsActive ? (
+                <button
+                  onClick={handleDnsToggle}
+                  disabled={!serverRunning || loading}
+                  className="flex w-full items-center justify-center gap-1.5 rounded-lg border border-red-500/30 bg-red-500/10 px-4 py-2 text-xs font-medium text-red-500 transition-colors hover:bg-red-500/20 disabled:cursor-not-allowed disabled:opacity-50 sm:w-auto sm:py-1.5"
+                >
+                  <span className="material-symbols-outlined text-[16px]">stop_circle</span>
+                  Stop DNS
+                </button>
+              ) : (
+                <button
+                  onClick={handleDnsToggle}
+                  disabled={!serverRunning || loading}
+                  className="flex w-full items-center justify-center gap-1.5 rounded-lg border border-primary/30 bg-primary/10 px-4 py-2 text-xs font-medium text-primary transition-colors hover:bg-primary/20 disabled:cursor-not-allowed disabled:opacity-50 sm:w-auto sm:py-1.5"
+                >
+                  <span className="material-symbols-outlined text-[16px]">play_circle</span>
+                  Start DNS
+                </button>
+              )}
+
+              {/* Warning below button */}
+              {warning && (
+                <div className="flex items-center gap-2 px-2 py-1.5 rounded text-xs text-amber-500">
+                  <span className="material-symbols-outlined text-[14px]">warning</span>
+                  <span>{warning}</span>
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+      </Card>
+
+      {/* Password Modal */}
+      {showPasswordModal && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 backdrop-blur-sm">
+          <div className="mx-4 flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-surface p-5 shadow-xl sm:p-6">
+            <h3 className="font-semibold text-text-main">Sudo Password Required</h3>
+            <div className="flex items-start gap-3 p-3 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+              <span className="material-symbols-outlined text-yellow-500 text-[20px]">warning</span>
+              <p className="text-xs text-text-muted">Required to modify /etc/hosts and flush DNS cache</p>
+            </div>
+            <Input
+              type="password"
+              placeholder="Enter sudo password"
+              value={sudoPassword}
+              onChange={(e) => setSudoPassword(e.target.value)}
+              onKeyDown={(e) => { if (e.key === "Enter" && !loading) handleConfirmPassword(); }}
+            />
+            {modalError && (
+              <div className="flex items-center gap-2 px-2 py-1.5 rounded text-xs bg-red-500/10 text-red-600">
+                <span className="material-symbols-outlined text-[14px]">error</span>
+                <span>{modalError}</span>
+              </div>
+            )}
+            <div className="flex items-center justify-end gap-2">
+              <Button variant="ghost" size="sm" onClick={() => { setShowPasswordModal(false); setSudoPassword(""); setModalError(null); }} disabled={loading}>
+                Cancel
+              </Button>
+              <Button variant="primary" size="sm" onClick={handleConfirmPassword} loading={loading}>
+                Confirm
+              </Button>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Model Select Modal */}
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => setModalOpen(false)}
+        onSelect={handleModelSelect}
+        selectedModel={currentEditingAlias ? modelMappings[currentEditingAlias] : null}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title={`Select model for ${currentEditingAlias}`}
+      />
+    </>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/OpenClawToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/OpenClawToolCard.js
new file mode 100644
index 0000000..88a73c6
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/OpenClawToolCard.js
@@ -0,0 +1,388 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+export default function OpenClawToolCard({
+  tool,
+  isExpanded,
+  onToggle,
+  baseUrl,
+  hasActiveProviders,
+  apiKeys,
+  activeProviders,
+  cloudEnabled,
+  initialStatus,
+  tunnelEnabled,
+  tunnelPublicUrl,
+  tailscaleEnabled,
+  tailscaleUrl,
+}) {
+  const [openclawStatus, setOpenclawStatus] = useState(initialStatus || null);
+  const [checkingOpenclaw, setCheckingOpenclaw] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [selectedModel, setSelectedModel] = useState("");
+  const [agentModels, setAgentModels] = useState({}); // { [agentId]: modelId }
+  const [agentModalFor, setAgentModalFor] = useState(null); // agentId opening modal
+  const [modalOpen, setModalOpen] = useState(false);
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+  const hasInitializedModel = useRef(false);
+
+  const getConfigStatus = () => {
+    if (!openclawStatus?.installed) return null;
+    const currentProvider = openclawStatus.settings?.models?.providers?.["9router"];
+    if (!currentProvider) return "not_configured";
+    return matchKnownEndpoint(currentProvider.baseUrl, { tunnelPublicUrl, tailscaleUrl }) ? "configured" : "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setOpenclawStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !openclawStatus) {
+      checkOpenclawStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  useEffect(() => {
+    if (openclawStatus?.installed && !hasInitializedModel.current) {
+      hasInitializedModel.current = true;
+      const provider = openclawStatus.settings?.models?.providers?.["9router"];
+      if (provider) {
+        const primaryModel = openclawStatus.settings?.agents?.defaults?.model?.primary;
+        if (primaryModel) setSelectedModel(primaryModel.replace("9router/", ""));
+        if (provider.apiKey && apiKeys?.some(k => k.key === provider.apiKey)) {
+          setSelectedApiKey(provider.apiKey);
+        }
+      }
+      // Init per-agent models from enriched agents list
+      const agentList = openclawStatus.agents || [];
+      const initAgentModels = {};
+      agentList.forEach((agent) => {
+        if (agent.currentModel) initAgentModels[agent.id] = agent.currentModel;
+      });
+      setAgentModels(initAgentModels);
+    }
+  }, [openclawStatus, apiKeys]);
+
+  const checkOpenclawStatus = async () => {
+    setCheckingOpenclaw(true);
+    try {
+      const res = await fetch("/api/cli-tools/openclaw-settings");
+      const data = await res.json();
+      setOpenclawStatus(data);
+    } catch (error) {
+      setOpenclawStatus({ installed: false, error: error.message });
+    } finally {
+      setCheckingOpenclaw(false);
+    }
+  };
+
+  const normalizeLocalhost = (url) => url.replace("://localhost", "://127.0.0.1");
+
+  const getLocalBaseUrl = () => {
+    if (typeof window !== "undefined") {
+      return normalizeLocalhost(window.location.origin);
+    }
+    return "http://127.0.0.1:20128";
+  };
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || getLocalBaseUrl();
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const getDisplayUrl = () => {
+    const url = customBaseUrl || getLocalBaseUrl();
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const handleApplySettings = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      const keyToUse = selectedApiKey?.trim()
+        || (apiKeys?.length > 0 ? apiKeys[0].key : null)
+        || (!cloudEnabled ? "sk_9router" : null);
+
+      const res = await fetch("/api/cli-tools/openclaw-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: getEffectiveBaseUrl(),
+          apiKey: keyToUse,
+          model: selectedModel,
+          agentModels,
+        }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied successfully!" });
+        checkOpenclawStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleResetSettings = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch("/api/cli-tools/openclaw-settings", { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        setSelectedModel("");
+        setSelectedApiKey("");
+        checkOpenclawStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const handleModelSelect = (model) => {
+    if (agentModalFor) {
+      setAgentModels(prev => ({ ...prev, [agentModalFor]: model.value }));
+      setAgentModalFor(null);
+    } else {
+      setSelectedModel(model.value);
+    }
+    setModalOpen(false);
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+
+    const settingsContent = {
+      agents: {
+        defaults: {
+          model: {
+            primary: `9router/${selectedModel || "provider/model-id"}`,
+          },
+        },
+      },
+      models: {
+        providers: {
+          "9router": {
+            baseUrl: getEffectiveBaseUrl(),
+            apiKey: keyToUse,
+            api: "openai-completions",
+            models: [
+              {
+                id: selectedModel || "provider/model-id",
+                name: (selectedModel || "provider/model-id").split("/").pop(),
+              },
+            ],
+          },
+        },
+      },
+    };
+
+    return [
+      {
+        filename: "~/.openclaw/openclaw.json",
+        content: JSON.stringify(settingsContent, null, 2),
+      },
+    ];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src="/providers/openclaw.png" alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checkingOpenclaw && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking Open Claw CLI...</span>
+            </div>
+          )}
+
+          {!checkingOpenclaw && openclawStatus && !openclawStatus.installed && (
+            <div className="flex flex-col gap-4">
+              <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+                <div className="flex items-start gap-3">
+                  <span className="material-symbols-outlined text-yellow-500">warning</span>
+                  <div className="flex-1">
+                    <p className="font-medium text-yellow-600 dark:text-yellow-400">Open Claw CLI not detected locally</p>
+                    <p className="text-sm text-text-muted">Manual configuration is still available if 9router is deployed on a remote server.</p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-2 pl-9">
+                  <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="!bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                    <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                    Manual Config
+                  </Button>
+                </div>
+              </div>
+            </div>
+          )}
+
+          {!checkingOpenclaw && openclawStatus?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                {/* Endpoint (selector) */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getDisplayUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                {/* Current configured */}
+                {openclawStatus?.settings?.models?.providers?.["9router"]?.baseUrl && (
+                  <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Current</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <span className="min-w-0 truncate rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                      {openclawStatus.settings.models.providers["9router"].baseUrl}
+                    </span>
+                  </div>
+                )}
+
+                {/* API Key */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                {/* Default Model */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Default Model</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <div className="relative w-full min-w-0">
+                    <input type="text" value={selectedModel} onChange={(e) => setSelectedModel(e.target.value)} placeholder="provider/model-id" className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5" />
+                    {selectedModel && <button onClick={() => setSelectedModel("")} className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors" title="Clear"><span className="material-symbols-outlined text-[14px]">close</span></button>}
+                  </div>
+                  <button onClick={() => { setAgentModalFor(null); setModalOpen(true); }} disabled={!hasActiveProviders} className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${hasActiveProviders ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Select</button>
+                </div>
+
+                {/* Per-agent model overrides */}
+                {(openclawStatus.agents || []).filter(a => a.agentDir).map((agent) => (
+                  <div key={agent.id} className="flex items-center gap-2 pl-4">
+                    <span className="w-32 shrink-0 text-xs text-primary text-right truncate" title={agent.name || agent.id}>Agent {agent.name || agent.id}</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <div className="relative w-full min-w-0">
+                      <input
+                        type="text"
+                        value={agentModels[agent.id] || ""}
+                        onChange={(e) => setAgentModels(prev => ({ ...prev, [agent.id]: e.target.value }))}
+                        placeholder={`default (${selectedModel || "provider/model-id"})`}
+                        className="w-full min-w-0 pl-2 pr-7 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5"
+                      />
+                      {agentModels[agent.id] && <button onClick={() => setAgentModels(prev => ({ ...prev, [agent.id]: "" }))} className="absolute right-1 top-1/2 -translate-y-1/2 p-0.5 text-text-muted hover:text-red-500 rounded transition-colors" title="Clear"><span className="material-symbols-outlined text-[14px]">close</span></button>}
+                    </div>
+                    <button onClick={() => { setAgentModalFor(agent.id); setModalOpen(true); }} disabled={!hasActiveProviders} className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${hasActiveProviders ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Select</button>
+                  </div>
+                ))}
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button variant="primary" size="sm" onClick={handleApplySettings} disabled={!selectedModel} loading={applying}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleResetSettings} disabled={!openclawStatus?.has9Router} loading={restoring}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => setModalOpen(false)}
+        onSelect={handleModelSelect}
+        selectedModel={selectedModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Model for Open Claw"
+      />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="Open Claw - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/OpenCodeToolCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/OpenCodeToolCard.js
new file mode 100644
index 0000000..9a4a4b8
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/OpenCodeToolCard.js
@@ -0,0 +1,500 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { Card, Button, ModelSelectModal, ManualConfigModal } from "@/shared/components";
+import Image from "next/image";
+import BaseUrlSelect from "./BaseUrlSelect";
+import ApiKeySelect from "./ApiKeySelect";
+import { matchKnownEndpoint } from "./cliEndpointMatch";
+
+export default function OpenCodeToolCard({ tool, isExpanded, onToggle, baseUrl, apiKeys, activeProviders, cloudEnabled, initialStatus, tunnelEnabled, tunnelPublicUrl, tailscaleEnabled, tailscaleUrl }) {
+  const [status, setStatus] = useState(initialStatus || null);
+  const [checking, setChecking] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const [restoring, setRestoring] = useState(false);
+  const [message, setMessage] = useState(null);
+  const [showInstallGuide, setShowInstallGuide] = useState(false);
+  const [selectedApiKey, setSelectedApiKey] = useState("");
+  const [selectedModel, setSelectedModel] = useState("");
+  const [subagentModel, setSubagentModel] = useState("");
+  const [modalOpen, setModalOpen] = useState(false);
+  const [subagentModalOpen, setSubagentModalOpen] = useState(false);
+  const [modelAliases, setModelAliases] = useState({});
+  const [showManualConfigModal, setShowManualConfigModal] = useState(false);
+  const [customBaseUrl, setCustomBaseUrl] = useState("");
+  const [selectedModels, setSelectedModels] = useState([]);
+  const [activeModel, setActiveModel] = useState("");
+  const selectedModelsRef = useRef([]);
+
+  useEffect(() => {
+    selectedModelsRef.current = selectedModels;
+  }, [selectedModels]);
+
+  useEffect(() => {
+    if (apiKeys?.length > 0 && !selectedApiKey) {
+      setSelectedApiKey(apiKeys[0].key);
+    }
+  }, [apiKeys, selectedApiKey]);
+
+  useEffect(() => {
+    if (initialStatus) setStatus(initialStatus);
+  }, [initialStatus]);
+
+  useEffect(() => {
+    if (isExpanded && !status) {
+      checkStatus();
+      fetchModelAliases();
+    }
+    if (isExpanded) fetchModelAliases();
+  }, [isExpanded]);
+
+  // Sync models from existing config
+  useEffect(() => {
+    if (status?.opencode?.models) {
+      setSelectedModels(status.opencode.models);
+    }
+    if (status?.opencode?.activeModel) {
+      setActiveModel(status.opencode.activeModel);
+    }
+
+    // Parse subagent settings from agent.explorer if exists
+    if (status?.config?.agent?.explorer?.model?.startsWith("9router/")) {
+      setSubagentModel(status.config.agent.explorer.model.replace("9router/", ""));
+    }
+  }, [status]);
+
+  const fetchModelAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) setModelAliases(data.aliases || {});
+    } catch (error) {
+      console.log("Error fetching model aliases:", error);
+    }
+  };
+
+  const saveModels = async (models) => {
+    try {
+      const keyToUse = (selectedApiKey && selectedApiKey.trim())
+        ? selectedApiKey
+        : (!cloudEnabled ? "sk_9router" : selectedApiKey);
+      const validActiveModel = models.includes(activeModel) ? activeModel : (models[0] || "");
+      await fetch("/api/cli-tools/opencode-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: getEffectiveBaseUrl(),
+          apiKey: keyToUse,
+          models,
+          activeModel: validActiveModel,
+          subagentModel,
+        }),
+      });
+    } catch (error) {
+      console.log("Error saving models:", error);
+    }
+  };
+
+  const getConfigStatus = () => {
+    if (!status?.installed) return null;
+    if (!status.config) return "not_configured";
+    if (!status.has9Router) return "not_configured";
+    const url = status.config?.provider?.["9router"]?.options?.baseURL || "";
+    return matchKnownEndpoint(url, { tunnelPublicUrl, tailscaleUrl }) ? "configured" : "other";
+  };
+
+  const configStatus = getConfigStatus();
+
+  const getEffectiveBaseUrl = () => {
+    const url = customBaseUrl || baseUrl;
+    return url.endsWith("/v1") ? url : `${url}/v1`;
+  };
+
+  const getDisplayUrl = () => customBaseUrl || `${baseUrl}/v1`;
+
+  const checkStatus = async () => {
+    setChecking(true);
+    try {
+      const res = await fetch("/api/cli-tools/opencode-settings");
+      const data = await res.json();
+      setStatus(data);
+    } catch (error) {
+      setStatus({ installed: false, error: error.message });
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  const handleApply = async () => {
+    setApplying(true);
+    setMessage(null);
+    try {
+      const keyToUse = (selectedApiKey && selectedApiKey.trim())
+        ? selectedApiKey
+        : (!cloudEnabled ? "sk_9router" : selectedApiKey);
+
+      const res = await fetch("/api/cli-tools/opencode-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: getEffectiveBaseUrl(),
+          apiKey: keyToUse,
+          models: selectedModels,
+          activeModel: activeModel === "" ? "" : (activeModel || selectedModels[0]),
+          subagentModel: subagentModel
+        }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings applied successfully!" });
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to apply settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setApplying(false);
+    }
+  };
+
+  const handleReset = async () => {
+    setRestoring(true);
+    setMessage(null);
+    try {
+      const res = await fetch("/api/cli-tools/opencode-settings", { method: "DELETE" });
+      const data = await res.json();
+      if (res.ok) {
+        setMessage({ type: "success", text: "Settings reset successfully!" });
+        setSelectedModel("");
+        setSubagentModel("");
+        setSelectedModels([]);
+        setActiveModel("");
+        checkStatus();
+      } else {
+        setMessage({ type: "error", text: data.error || "Failed to reset settings" });
+      }
+    } catch (error) {
+      setMessage({ type: "error", text: error.message });
+    } finally {
+      setRestoring(false);
+    }
+  };
+
+  const getManualConfigs = () => {
+    const keyToUse = (selectedApiKey && selectedApiKey.trim())
+      ? selectedApiKey
+      : (!cloudEnabled ? "sk_9router" : "<API_KEY_FROM_DASHBOARD>");
+
+    const modelsToShow = selectedModels.length > 0 ? selectedModels : ["provider/model-id"];
+    const activeModelToShow = activeModel || selectedModels[0] || modelsToShow[0];
+    const effectiveSubagentModel = subagentModel || activeModelToShow;
+
+    const modelsObj = {};
+    modelsToShow.forEach(m => {
+      modelsObj[m] = { name: m, modalities: { input: ["text", "image"], output: ["text"] } };
+    });
+
+    return [{
+      filename: "~/.config/opencode/opencode.json",
+      content: JSON.stringify({
+        provider: {
+          "9router": {
+            npm: "@ai-sdk/openai-compatible",
+            options: { baseURL: getEffectiveBaseUrl(), apiKey: keyToUse },
+            models: modelsObj,
+          },
+        },
+        model: `9router/${activeModelToShow}`,
+        agent: {
+          explorer: {
+            description: "Fast explorer subagent for codebase exploration",
+            mode: "subagent",
+            model: `9router/${effectiveSubagentModel}`
+          }
+        }
+      }, null, 2),
+    }];
+  };
+
+  return (
+    <Card padding="xs" className="overflow-hidden">
+      <div className="flex items-start justify-between gap-3 hover:cursor-pointer sm:items-center" onClick={onToggle}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div className="size-8 flex items-center justify-center shrink-0">
+            <Image src="/providers/opencode.png" alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+          </div>
+          <div className="min-w-0">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <h3 className="font-medium text-sm">{tool.name}</h3>
+              {configStatus === "configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-green-500/10 text-green-600 dark:text-green-400 rounded-full">Connected</span>}
+              {configStatus === "not_configured" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 rounded-full">Not configured</span>}
+              {configStatus === "other" && <span className="px-1.5 py-0.5 text-[10px] font-medium bg-blue-500/10 text-blue-600 dark:text-blue-400 rounded-full">Other</span>}
+            </div>
+            <p className="text-xs text-text-muted truncate">{tool.description}</p>
+          </div>
+        </div>
+        <span className={`material-symbols-outlined text-text-muted text-[20px] transition-transform ${isExpanded ? "rotate-180" : ""}`}>expand_more</span>
+      </div>
+
+      {isExpanded && (
+        <div className="mt-4 pt-4 border-t border-border flex flex-col gap-4">
+          {checking && (
+            <div className="flex items-center gap-2 text-text-muted">
+              <span className="material-symbols-outlined animate-spin">progress_activity</span>
+              <span>Checking OpenCode CLI...</span>
+            </div>
+          )}
+
+          {!checking && status && !status.installed && (
+            <div className="flex flex-col gap-4">
+              <div className="flex flex-col gap-3 p-4 bg-yellow-500/10 border border-yellow-500/30 rounded-lg">
+                <div className="flex items-start gap-3">
+                  <span className="material-symbols-outlined text-yellow-500">warning</span>
+                  <div className="flex-1">
+                    <p className="font-medium text-yellow-600 dark:text-yellow-400">OpenCode CLI not detected locally</p>
+                    <p className="text-sm text-text-muted">Manual configuration is still available if 9router is deployed on a remote server.</p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-2 pl-9">
+                  <Button variant="secondary" size="sm" onClick={() => setShowManualConfigModal(true)} className="!bg-yellow-500/20 !border-yellow-500/40 !text-yellow-700 dark:!text-yellow-300 hover:!bg-yellow-500/30">
+                    <span className="material-symbols-outlined text-[18px] mr-1">content_copy</span>
+                    Manual Config
+                  </Button>
+                  <Button variant="outline" size="sm" onClick={() => setShowInstallGuide(!showInstallGuide)}>
+                    <span className="material-symbols-outlined text-[18px] mr-1">{showInstallGuide ? "expand_less" : "help"}</span>
+                    {showInstallGuide ? "Hide" : "How to Install"}
+                  </Button>
+                </div>
+              </div>
+              {showInstallGuide && (
+                <div className="p-4 bg-surface border border-border rounded-lg">
+                  <h4 className="font-medium mb-3">Installation Guide</h4>
+                  <div className="space-y-3 text-sm">
+                    <div>
+                      <p className="text-text-muted mb-1">macOS / Linux:</p>
+                      <code className="block px-3 py-2 bg-black/5 dark:bg-white/5 rounded font-mono text-xs">npm install -g opencode-ai</code>
+                    </div>
+                    <p className="text-text-muted">After installation, run <code className="px-1 bg-black/5 dark:bg-white/5 rounded">opencode</code> to verify.</p>
+                  </div>
+                </div>
+              )}
+            </div>
+          )}
+
+          {!checking && status?.installed && (
+            <>
+              <div className="flex flex-col gap-2">
+                {/* Current base URL */}
+                {/* Endpoint (selector) */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Select Endpoint</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <BaseUrlSelect
+                    value={customBaseUrl || getDisplayUrl()}
+                    onChange={setCustomBaseUrl}
+                    requiresExternalUrl={tool.requiresExternalUrl}
+                    tunnelEnabled={tunnelEnabled}
+                    tunnelPublicUrl={tunnelPublicUrl}
+                    tailscaleEnabled={tailscaleEnabled}
+                    tailscaleUrl={tailscaleUrl}
+                  />
+                </div>
+
+                {/* Current configured */}
+                {status?.config?.provider?.["9router"]?.options?.baseURL && (
+                  <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                    <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Current</span>
+                    <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                    <span className="min-w-0 truncate rounded bg-surface/40 px-2 py-2 text-xs text-text-muted sm:py-1.5">
+                      {status.config.provider["9router"].options.baseURL}
+                    </span>
+                  </div>
+                )}
+
+                {/* API Key */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">API Key</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <ApiKeySelect value={selectedApiKey} onChange={setSelectedApiKey} apiKeys={apiKeys} cloudEnabled={cloudEnabled} />
+                </div>
+
+                {/* Models */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr] sm:items-start sm:gap-2">
+                  <span className="w-32 shrink-0 text-sm font-semibold text-text-main text-right pt-1">Models</span>
+                  <span className="material-symbols-outlined text-text-muted text-[14px] mt-1.5">arrow_forward</span>
+                  <div className="flex-1 flex flex-col gap-2">
+                    <div className="flex flex-wrap gap-1.5 min-h-[28px] px-2 py-1.5 bg-surface rounded border border-border">
+                      {selectedModels.length === 0 ? (
+                        <span className="text-xs text-text-muted">No models selected</span>
+                      ) : (
+                        selectedModels.map((model) => (
+                          <span
+                            key={model}
+                            onClick={async () => {
+                              if (model === activeModel) {
+                                try {
+                                  const res = await fetch("/api/cli-tools/opencode-settings", {
+                                    method: "PATCH",
+                                    headers: { "Content-Type": "application/json" },
+                                    body: JSON.stringify({ clearActiveModel: true }),
+                                  });
+                                  if (res.ok) {
+                                    setActiveModel("");
+                                    checkStatus();
+                                  }
+                                } catch (error) {
+                                  console.log("Error clearing active model:", error);
+                                }
+                              } else {
+                                setActiveModel(model);
+                              }
+                            }}
+                            className={`inline-flex items-center gap-1 px-2 py-0.5 rounded text-xs cursor-pointer transition-colors ${
+                              model === activeModel
+                                ? "bg-primary/10 text-primary border border-primary"
+                                : "bg-black/5 dark:bg-white/5 text-text-muted border border-transparent hover:border-border"
+                            }`}
+                            title={model === activeModel ? "Click to clear active model" : "Click to set as active"}
+                          >
+                            {model === activeModel && <span className="material-symbols-outlined text-[10px]">star</span>}
+                            {model}
+                            <button
+                              onClick={async (e) => {
+                                e.stopPropagation();
+                                try {
+                                  const res = await fetch(`/api/cli-tools/opencode-settings?model=${encodeURIComponent(model)}`, { method: "DELETE" });
+                                  if (res.ok) {
+                                    const newModels = selectedModels.filter((m) => m !== model);
+                                    setSelectedModels(newModels);
+                                    if (activeModel === model) {
+                                      setActiveModel("");
+                                    }
+                                    checkStatus();
+                                  }
+                                } catch (error) {
+                                  console.log("Error removing model:", error);
+                                }
+                              }}
+                              className="ml-0.5 hover:text-red-500"
+                            >
+                              <span className="material-symbols-outlined text-[12px]">close</span>
+                            </button>
+                          </span>
+                        ))
+                      )}
+                    </div>
+                    <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                      <button onClick={() => setModalOpen(true)} disabled={!activeProviders?.length} className={`px-2 py-1 rounded border text-xs transition-colors ${activeProviders?.length ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}>Add Model</button>
+                      <span className="text-xs text-text-muted">
+                        {selectedModels.length > 0 && activeModel ? (
+                          <>Active: <span className="text-primary">{activeModel}</span></>
+                        ) : selectedModels.length > 0 ? (
+                          <span className="text-yellow-500">Click a model to set/clear active</span>
+                        ) : (
+                          "Select models to add"
+                        )}
+                      </span>
+                    </div>
+                  </div>
+                </div>
+
+                {/* Subagent Model */}
+                <div className="grid grid-cols-1 gap-1.5 sm:grid-cols-[8rem_auto_1fr_auto] sm:items-center sm:gap-2">
+                  <span className="text-xs font-semibold text-text-main sm:text-right sm:text-sm">Subagent Model</span>
+                  <span className="material-symbols-outlined hidden text-text-muted text-[14px] sm:inline">arrow_forward</span>
+                  <input
+                    type="text"
+                    value={subagentModel}
+                    onChange={(e) => setSubagentModel(e.target.value)}
+                    placeholder={selectedModel || "provider/model-id (defaults to main model)"}
+                    className="w-full min-w-0 px-2 py-2 bg-surface rounded border border-border text-xs focus:outline-none focus:ring-1 focus:ring-primary/50 sm:py-1.5"
+                  />
+                  <button
+                    onClick={() => setSubagentModalOpen(true)}
+                    disabled={!activeProviders?.length}
+                    className={`w-full sm:w-auto rounded border px-2 py-2 text-xs transition-colors sm:py-1.5 whitespace-nowrap sm:shrink-0 ${activeProviders?.length ? "bg-surface border-border text-text-main hover:border-primary cursor-pointer" : "opacity-50 cursor-not-allowed border-border"}`}
+                  >
+                    Select Model
+                  </button>
+                  {subagentModel && (
+                    <button
+                      onClick={() => setSubagentModel("")}
+                      className="p-1 text-text-muted hover:text-red-500 rounded transition-colors"
+                      title="Clear (will use main model)"
+                    >
+                      <span className="material-symbols-outlined text-[14px]">close</span>
+                    </button>
+                  )}
+                </div>
+              </div>
+
+              {message && (
+                <div className={`flex items-center gap-2 px-2 py-1.5 rounded text-xs ${message.type === "success" ? "bg-green-500/10 text-green-600" : "bg-red-500/10 text-red-600"}`}>
+                  <span className="material-symbols-outlined text-[14px]">{message.type === "success" ? "check_circle" : "error"}</span>
+                  <span>{message.text}</span>
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+                <Button variant="primary" size="sm" onClick={handleApply} disabled={selectedModels.length === 0} loading={applying}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">save</span>Apply
+                </Button>
+                <Button variant="outline" size="sm" onClick={handleReset} disabled={!status.has9Router} loading={restoring}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">restore</span>Reset
+                </Button>
+                <Button variant="ghost" size="sm" onClick={() => setShowManualConfigModal(true)}>
+                  <span className="material-symbols-outlined text-[14px] mr-1">content_copy</span>Manual Config
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <ModelSelectModal
+        isOpen={modalOpen}
+        onClose={() => {
+          setModalOpen(false);
+          saveModels(selectedModelsRef.current);
+        }}
+        onSelect={(model) => {
+          if (!selectedModels.includes(model.value)) {
+            setSelectedModels([...selectedModels, model.value]);
+            if (!activeModel) setActiveModel(model.value);
+          }
+        }}
+        onDeselect={(model) => {
+          const remaining = selectedModels.filter(m => m !== model.value);
+          setSelectedModels(remaining);
+          if (activeModel === model.value) {
+            setActiveModel(remaining[0] || "");
+          }
+        }}
+        selectedModel={null}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        addedModelValues={selectedModels}
+        closeOnSelect={false}
+        title="Add Model for OpenCode"
+      />
+
+      <ModelSelectModal
+        isOpen={subagentModalOpen}
+        onClose={() => setSubagentModalOpen(false)}
+        onSelect={(model) => { setSubagentModel(model.value); setSubagentModalOpen(false); }}
+        selectedModel={subagentModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Select Subagent Model for OpenCode"
+      />
+
+      <ManualConfigModal
+        isOpen={showManualConfigModal}
+        onClose={() => setShowManualConfigModal(false)}
+        title="OpenCode - Manual Configuration"
+        configs={getManualConfigs()}
+      />
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/ToolSummaryCard.js b/src/app/(dashboard)/dashboard/cli-tools/components/ToolSummaryCard.js
new file mode 100644
index 0000000..ea3d51c
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/ToolSummaryCard.js
@@ -0,0 +1,39 @@
+"use client";
+
+import Link from "next/link";
+import Image from "next/image";
+import { Card } from "@/shared/components";
+
+// Derive simple connected/configured/not-installed status from API payload
+function getStatus(status) {
+  if (!status) return { label: "Unknown", cls: "bg-gray-500/10 text-gray-500" };
+  if (!status.installed) return { label: "Not installed", cls: "bg-gray-500/10 text-gray-500" };
+  if (status.has9Router) return { label: "Connected", cls: "bg-green-500/10 text-green-600 dark:text-green-400" };
+  return { label: "Not configured", cls: "bg-yellow-500/10 text-yellow-600 dark:text-yellow-400" };
+}
+
+export default function ToolSummaryCard({ toolId, tool, status }) {
+  const s = getStatus(status);
+  return (
+    <Link href={`/dashboard/cli-tools/${toolId}`} className="block">
+      <Card padding="sm" className="h-full overflow-hidden hover:border-primary/50 transition-colors cursor-pointer">
+        <div className="flex h-full flex-col gap-2">
+          <div className="flex items-center gap-3">
+            <div className="size-8 flex items-center justify-center shrink-0">
+              {tool.image ? (
+                <Image src={tool.image} alt={tool.name} width={32} height={32} className="size-8 object-contain rounded-lg" sizes="32px" onError={(e) => { e.target.style.display = "none"; }} />
+              ) : tool.icon ? (
+                <span className="material-symbols-outlined text-[28px]" style={{ color: tool.color }}>{tool.icon}</span>
+              ) : null}
+            </div>
+            <div className="min-w-0 flex-1">
+              <h3 className="font-medium text-sm truncate">{tool.name}</h3>
+              <span className={`inline-block mt-1 px-1.5 py-0.5 text-[10px] font-medium rounded-full ${s.cls}`}>{s.label}</span>
+            </div>
+            <span className="material-symbols-outlined text-text-muted text-[18px] shrink-0">chevron_right</span>
+          </div>
+        </div>
+      </Card>
+    </Link>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/cliEndpointMatch.js b/src/app/(dashboard)/dashboard/cli-tools/components/cliEndpointMatch.js
new file mode 100644
index 0000000..0d7b7ca
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/cliEndpointMatch.js
@@ -0,0 +1,13 @@
+// Match a configured CLI base URL against all known endpoints (local/tunnel/tailscale/cloud)
+const stripTrailingSlash = (s) => (s || "").replace(/\/+$/, "");
+
+export function matchKnownEndpoint(currentUrl, opts = {}) {
+  if (!currentUrl) return false;
+  const url = stripTrailingSlash(currentUrl);
+  const { tunnelPublicUrl, tailscaleUrl, cloudUrl } = opts;
+  if (/localhost|127\.0\.0\.1|0\.0\.0\.0/.test(url)) return true;
+  if (tunnelPublicUrl && url.startsWith(stripTrailingSlash(tunnelPublicUrl))) return true;
+  if (tailscaleUrl && url.startsWith(stripTrailingSlash(tailscaleUrl))) return true;
+  if (cloudUrl && url.startsWith(stripTrailingSlash(cloudUrl))) return true;
+  return false;
+}
diff --git a/src/app/(dashboard)/dashboard/cli-tools/components/index.js b/src/app/(dashboard)/dashboard/cli-tools/components/index.js
new file mode 100644
index 0000000..aeca870
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/components/index.js
@@ -0,0 +1,19 @@
+export { default as ClaudeToolCard } from "./ClaudeToolCard";
+export { default as CodexToolCard } from "./CodexToolCard";
+export { default as DroidToolCard } from "./DroidToolCard";
+export { default as OpenClawToolCard } from "./OpenClawToolCard";
+export { default as HermesToolCard } from "./HermesToolCard";
+export { default as DefaultToolCard } from "./DefaultToolCard";
+export { default as AntigravityToolCard } from "./AntigravityToolCard";
+export { default as OpenCodeToolCard } from "./OpenCodeToolCard";
+export { default as CoworkToolCard } from "./CoworkToolCard";
+export { default as CopilotToolCard } from "./CopilotToolCard";
+export { default as ClineToolCard } from "./ClineToolCard";
+export { default as KiloToolCard } from "./KiloToolCard";
+export { default as DeepSeekTuiToolCard } from "./DeepSeekTuiToolCard";
+export { default as JcodeToolCard } from "./JcodeToolCard";
+export { default as MitmServerCard } from "./MitmServerCard";
+export { default as MitmToolCard } from "./MitmToolCard";
+export { default as MitmLinkCard } from "./MitmLinkCard";
+export { default as EndpointPresetControl } from "./EndpointPresetControl";
+export { default as BaseUrlSelect } from "./BaseUrlSelect";
diff --git a/src/app/(dashboard)/dashboard/cli-tools/page.js b/src/app/(dashboard)/dashboard/cli-tools/page.js
new file mode 100644
index 0000000..24f6030
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/cli-tools/page.js
@@ -0,0 +1,7 @@
+import { getMachineId } from "@/shared/utils/machine";
+import CLIToolsPageClient from "./CLIToolsPageClient";
+
+export default async function CLIToolsPage() {
+  const machineId = await getMachineId();
+  return <CLIToolsPageClient machineId={machineId} />;
+}
diff --git a/src/app/(dashboard)/dashboard/combos/page.js b/src/app/(dashboard)/dashboard/combos/page.js
new file mode 100644
index 0000000..abfc215
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/combos/page.js
@@ -0,0 +1,654 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import { DndContext, closestCenter, KeyboardSensor, PointerSensor, useSensor, useSensors } from "@dnd-kit/core";
+import { arrayMove, SortableContext, sortableKeyboardCoordinates, useSortable, verticalListSortingStrategy } from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { restrictToVerticalAxis, restrictToParentElement } from "@dnd-kit/modifiers";
+import { Card, Button, Modal, Input, CardSkeleton, ModelSelectModal, ConfirmModal, CapacityBadges, Select } from "@/shared/components";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import { isOpenAICompatibleProvider, isAnthropicCompatibleProvider } from "@/shared/constants/providers";
+
+// Validate combo name: only a-z, A-Z, 0-9, -, _
+const VALID_NAME_REGEX = /^[a-zA-Z0-9_.\-]+$/;
+
+export default function CombosPage() {
+  const [combos, setCombos] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [showCreateModal, setShowCreateModal] = useState(false);
+  const [editingCombo, setEditingCombo] = useState(null);
+  const [activeProviders, setActiveProviders] = useState([]);
+  const [comboStrategies, setComboStrategies] = useState({});
+  const [modelCaps, setModelCaps] = useState({});
+  const [confirmState, setConfirmState] = useState(null);
+  const { copied, copy } = useCopyToClipboard();
+
+  useEffect(() => {
+    fetchData();
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const fetchData = async () => {
+    try {
+      const [combosRes, providersRes, settingsRes, modelsRes] = await Promise.all([
+        fetch("/api/combos"),
+        fetch("/api/providers"),
+        fetch("/api/settings"),
+        fetch("/api/models"),
+      ]);
+      const combosData = await combosRes.json();
+      const providersData = await providersRes.json();
+      const settingsData = settingsRes.ok ? await settingsRes.json() : {};
+      
+      // Only LLM combos here - webSearch/webFetch combos belong to media-providers/web
+      if (combosRes.ok) setCombos((combosData.combos || []).filter(c => !c.kind || c.kind === "llm"));
+      if (providersRes.ok) {
+        setActiveProviders(providersData.connections || []);
+      }
+      if (modelsRes.ok) {
+        const md = await modelsRes.json();
+        // Build fullModel -> caps map for badge lookup
+        const map = {};
+        for (const m of md.models || []) if (m.caps) map[m.fullModel] = m.caps;
+        setModelCaps(map);
+      }
+      setComboStrategies(settingsData.comboStrategies || {});
+    } catch (error) {
+      console.log("Error fetching data:", error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleCreate = async (data) => {
+    try {
+      const res = await fetch("/api/combos", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(data),
+      });
+      if (res.ok) {
+        await fetchData();
+        setShowCreateModal(false);
+      } else {
+        const err = await res.json();
+        alert(err.error || "Failed to create combo");
+      }
+    } catch (error) {
+      console.log("Error creating combo:", error);
+    }
+  };
+
+  const handleUpdate = async (id, data) => {
+    try {
+      const res = await fetch(`/api/combos/${id}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(data),
+      });
+      if (res.ok) {
+        await fetchData();
+        setEditingCombo(null);
+      } else {
+        const err = await res.json();
+        alert(err.error || "Failed to update combo");
+      }
+    } catch (error) {
+      console.log("Error updating combo:", error);
+    }
+  };
+
+  const handleDelete = async (id) => {
+    setConfirmState({
+      title: "Delete Combo",
+      message: "Delete this combo?",
+      onConfirm: async () => {
+        setConfirmState(null);
+        try {
+          const res = await fetch(`/api/combos/${id}`, { method: "DELETE" });
+          if (res.ok) {
+            setCombos(combos.filter(c => c.id !== id));
+          }
+        } catch (error) {
+          console.log("Error deleting combo:", error);
+        }
+      }
+    });
+  };
+
+  // Merge a per-combo strategy patch into settings.comboStrategies. Passing an empty
+  // patch (strategy back to default "fallback") drops the entry entirely.
+  const handleSetComboStrategy = async (comboName, patch) => {
+    try {
+      const updated = { ...comboStrategies };
+      const next = { ...(updated[comboName] || {}), ...patch };
+      // Prune to keep settings clean: default fallback with no extras = no entry.
+      if (!next.fallbackStrategy || next.fallbackStrategy === "fallback") {
+        delete updated[comboName];
+      } else {
+        updated[comboName] = next;
+      }
+
+      await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ comboStrategies: updated }),
+      });
+
+      setComboStrategies(updated);
+    } catch (error) {
+      console.log("Error updating combo strategy:", error);
+    }
+  };
+
+  if (loading) {
+    return (
+      <div className="flex flex-col gap-6">
+        <CardSkeleton />
+        <CardSkeleton />
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex min-w-0 flex-col gap-6 px-1 sm:px-0">
+      {/* Header */}
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <div className="min-w-0">
+          <p className="text-sm text-text-muted mt-1">
+            Group models under one name, then pick a strategy per combo:
+          </p>
+          <ul className="text-sm text-text-muted mt-2 flex flex-col gap-1">
+            <li><span className="font-medium text-text-main">Fallback</span> — tries models in order (next on failure)</li>
+            <li><span className="font-medium text-text-main">Round Robin</span> — rotates models across requests to spread load</li>
+            <li><span className="font-medium text-text-main">Fusion</span> — queries all models in parallel, then a judge synthesizes one answer. Best quality, but costs the most: every request bills all panel models + the judge (N+1 calls)</li>
+            <li><span className="font-medium text-text-main">Capacity auto-switch</span> — sends image/PDF/audio requests to a model that supports them first</li>
+          </ul>
+        </div>
+        <Button icon="add" onClick={() => setShowCreateModal(true)} className="w-full sm:w-auto whitespace-nowrap">
+          Create Combo
+        </Button>
+      </div>
+
+      {/* Combos List */}
+      {combos.length === 0 ? (
+        <Card>
+          <div className="text-center py-12">
+            <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-primary/10 text-primary mb-4">
+              <span className="material-symbols-outlined text-[32px]">layers</span>
+            </div>
+            <p className="text-text-main font-medium mb-1">No combos yet</p>
+            <p className="text-sm text-text-muted mb-4">Create model combos with fallback support</p>
+            <Button icon="add" onClick={() => setShowCreateModal(true)} className="w-full sm:w-auto">
+              Create Combo
+            </Button>
+          </div>
+        </Card>
+      ) : (
+        <div className="flex flex-col gap-4">
+          {combos.map((combo) => (
+            <ComboCard
+              key={combo.id}
+              combo={combo}
+              modelCaps={modelCaps}
+              activeProviders={activeProviders}
+              copied={copied}
+              onCopy={copy}
+              onEdit={() => setEditingCombo(combo)}
+              onDelete={() => handleDelete(combo.id)}
+              strategy={comboStrategies[combo.name] || {}}
+              onSetStrategy={(patch) => handleSetComboStrategy(combo.name, patch)}
+            />
+          ))}
+        </div>
+      )}
+
+      {/* Create Modal - Use key to force remount and reset state */}
+      <ComboFormModal
+        key="create"
+        isOpen={showCreateModal}
+        onClose={() => setShowCreateModal(false)}
+        onSave={handleCreate}
+        activeProviders={activeProviders}
+      />
+
+      {/* Edit Modal - Use key to force remount and reset state */}
+      <ComboFormModal
+        key={editingCombo?.id || "new"}
+        isOpen={!!editingCombo}
+        combo={editingCombo}
+        onClose={() => setEditingCombo(null)}
+        onSave={(data) => handleUpdate(editingCombo.id, data)}
+        activeProviders={activeProviders}
+      />
+
+      {/* Confirm Delete Modal */}
+      <ConfirmModal
+        isOpen={!!confirmState}
+        onClose={() => setConfirmState(null)}
+        onConfirm={confirmState?.onConfirm}
+        title={confirmState?.title || "Confirm"}
+        message={confirmState?.message}
+        variant="danger"
+      />
+    </div>
+  );
+}
+
+const STRATEGY_OPTIONS = [
+  { value: "fallback", label: "Fallback — try in order" },
+  { value: "round-robin", label: "Round Robin — rotate" },
+  { value: "fusion", label: "Fusion — panel + judge" },
+];
+
+function ComboCard({ combo, modelCaps = {}, activeProviders = [], copied, onCopy, onEdit, onDelete, strategy = {}, onSetStrategy }) {
+  const [showJudgeSelect, setShowJudgeSelect] = useState(false);
+  const current = strategy.fallbackStrategy || "fallback";
+  const judge = strategy.judgeModel || "";
+  const isFusion = current === "fusion";
+
+  return (
+    <Card padding="sm" className="group">
+      <div className="flex min-w-0 flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <div className="flex min-w-0 flex-1 items-start gap-3 sm:items-center">
+          <div className="size-8 rounded-lg bg-primary/10 flex items-center justify-center shrink-0">
+            <span className="material-symbols-outlined text-primary text-[18px]">layers</span>
+          </div>
+          <div className="min-w-0 flex-1">
+            <code className="block truncate font-mono text-sm font-medium">{combo.name}</code>
+            <div className="mt-1 flex min-w-0 flex-wrap items-center gap-1">
+              {combo.models.length === 0 ? (
+                <span className="text-xs text-text-muted italic">No models</span>
+              ) : (
+                combo.models.slice(0, 3).map((model, index) => (
+                  <code key={index} className="inline-flex items-center gap-1 rounded bg-black/5 px-1.5 py-0.5 font-mono text-xs text-text-muted dark:bg-white/5">
+                    <span>{model}</span>
+                    <CapacityBadges caps={modelCaps[model]} />
+                  </code>
+                ))
+              )}
+              {combo.models.length > 3 && (
+                <span className="text-[10px] text-text-muted">+{combo.models.length - 3} more</span>
+              )}
+            </div>
+            {/* Fusion: judge picker (Auto = first model) */}
+            {isFusion && (
+              <div className="mt-2 flex min-w-0 flex-wrap items-center gap-1.5">
+                <span className="text-[11px] font-medium text-text-muted">Judge</span>
+                <button
+                  onClick={() => setShowJudgeSelect(true)}
+                  className="inline-flex max-w-full items-center gap-1 rounded border border-dashed border-primary/40 px-1.5 py-0.5 font-mono text-[11px] text-primary hover:border-primary hover:bg-primary/5 transition-colors"
+                  title="Pick the model that fuses panel answers"
+                >
+                  <span className="material-symbols-outlined text-[13px]">gavel</span>
+                  <span className="truncate">{judge || `Auto — ${combo.models[0] || "first model"}`}</span>
+                </button>
+                {judge && (
+                  <button
+                    onClick={() => onSetStrategy({ judgeModel: "" })}
+                    className="p-0.5 rounded text-text-muted hover:text-red-500 hover:bg-red-500/10 transition-colors"
+                    title="Reset judge to Auto"
+                  >
+                    <span className="material-symbols-outlined text-[13px]">close</span>
+                  </button>
+                )}
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* Actions */}
+        <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center sm:gap-3 sm:shrink-0">
+          {/* Strategy selector — always visible */}
+          <div className="w-full sm:w-[200px]">
+            <Select
+              options={STRATEGY_OPTIONS}
+              value={current}
+              onChange={(e) => onSetStrategy({ fallbackStrategy: e.target.value })}
+              selectClassName="py-1.5 text-xs"
+            />
+          </div>
+
+          <div className="grid grid-cols-3 gap-1 sm:flex">
+            <button
+              onClick={(e) => { e.stopPropagation(); onCopy(combo.name, `combo-${combo.id}`); }}
+              className="flex flex-col items-center rounded px-2 py-1 text-text-muted transition-colors hover:bg-black/5 hover:text-primary dark:hover:bg-white/5"
+              title="Copy combo name"
+            >
+              <span className="material-symbols-outlined text-[18px]">
+                {copied === `combo-${combo.id}` ? "check" : "content_copy"}
+              </span>
+              <span className="text-[10px] leading-tight">Copy</span>
+            </button>
+            <button
+              onClick={onEdit}
+              className="flex flex-col items-center rounded px-2 py-1 text-text-muted transition-colors hover:bg-black/5 hover:text-primary dark:hover:bg-white/5"
+              title="Edit"
+            >
+              <span className="material-symbols-outlined text-[18px]">edit</span>
+              <span className="text-[10px] leading-tight">Edit</span>
+            </button>
+            <button
+              onClick={onDelete}
+              className="flex flex-col items-center rounded px-2 py-1 text-red-500 transition-colors hover:bg-red-500/10"
+              title="Delete"
+            >
+              <span className="material-symbols-outlined text-[18px]">delete</span>
+              <span className="text-[10px] leading-tight">Delete</span>
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {/* Judge model picker (single-select; combo members make natural judges too) */}
+      <ModelSelectModal
+        isOpen={showJudgeSelect}
+        onClose={() => setShowJudgeSelect(false)}
+        onSelect={(m) => { onSetStrategy({ judgeModel: m?.value || "" }); setShowJudgeSelect(false); }}
+        activeProviders={activeProviders}
+        title="Select Judge Model"
+        addedModelValues={judge ? [judge] : []}
+        closeOnSelect={true}
+      />
+    </Card>
+  );
+}
+
+function ModelItem({ id, index, model, isFirst, isLast, onEdit, onMoveUp, onMoveDown, onRemove }) {
+  const { attributes, listeners, setNodeRef, transform, isDragging } = useSortable({ id });
+  const style = {
+    transform: CSS.Transform.toString(transform),
+    // no transition — prevents the CSS settle animation fighting React's re-render on drop
+    opacity: isDragging ? 0.4 : 1,
+    zIndex: isDragging ? 999 : undefined,
+  };
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState(model);
+  const commit = () => {
+    const trimmed = draft.trim();
+    if (trimmed && trimmed !== model) onEdit(trimmed);
+    else setDraft(model);
+    setEditing(false);
+  };
+
+  const handleKeyDown = (e) => {
+    if (e.key === "Enter") commit();
+    if (e.key === "Escape") { setDraft(model); setEditing(false); }
+  };
+
+  return (
+    <div
+      ref={setNodeRef}
+      style={style}
+      className={`group flex min-w-0 items-center gap-1.5 rounded-md px-2 py-1 bg-black/[0.02] hover:bg-black/[0.04] dark:bg-white/[0.02] dark:hover:bg-white/[0.04] transition-colors ${isDragging ? "shadow-md ring-1 ring-primary/30" : ""}`}
+    >
+      {/* Drag handle */}
+      <button
+        {...attributes}
+        {...listeners}
+        type="button"
+        className="cursor-grab touch-none p-0.5 rounded text-text-muted hover:text-primary active:cursor-grabbing shrink-0"
+        title="Drag to reorder"
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
+          <circle cx="9" cy="4" r="2"/><circle cx="15" cy="4" r="2"/>
+          <circle cx="9" cy="12" r="2"/><circle cx="15" cy="12" r="2"/>
+          <circle cx="9" cy="20" r="2"/><circle cx="15" cy="20" r="2"/>
+        </svg>
+      </button>
+
+      {/* Index badge */}
+      <span className="text-[10px] font-medium text-text-muted w-3 text-center shrink-0">{index + 1}</span>
+
+      {/* Inline editable model value */}
+      {editing ? (
+        <input
+          autoFocus
+          value={draft}
+          onChange={(e) => setDraft(e.target.value)}
+          onBlur={commit}
+          onKeyDown={handleKeyDown}
+          className="min-w-0 flex-1 rounded border border-primary/40 bg-white px-1.5 py-0.5 font-mono text-xs text-text-main outline-none dark:bg-black/20"
+        />
+      ) : (
+        <div
+          className="min-w-0 flex-1 cursor-text truncate rounded px-1.5 py-0.5 font-mono text-xs text-text-main hover:bg-black/5 dark:hover:bg-white/5"
+          onClick={() => setEditing(true)}
+          title="Click to edit"
+        >
+          {model}
+        </div>
+      )}
+
+      {/* Priority arrows */}
+      <div className="flex shrink-0 items-center gap-0.5">
+        <button
+          onClick={onMoveUp}
+          disabled={isFirst}
+          className={`p-0.5 rounded ${isFirst ? "text-text-muted/20 cursor-not-allowed" : "text-text-muted hover:text-primary hover:bg-black/5 dark:hover:bg-white/5"}`}
+          title="Move up"
+        >
+          <span className="material-symbols-outlined text-[12px]">arrow_upward</span>
+        </button>
+        <button
+          onClick={onMoveDown}
+          disabled={isLast}
+          className={`p-0.5 rounded ${isLast ? "text-text-muted/20 cursor-not-allowed" : "text-text-muted hover:text-primary hover:bg-black/5 dark:hover:bg-white/5"}`}
+          title="Move down"
+        >
+          <span className="material-symbols-outlined text-[12px]">arrow_downward</span>
+        </button>
+      </div>
+
+      {/* Remove */}
+      <button
+        onClick={onRemove}
+        className="p-0.5 hover:bg-red-500/10 rounded text-text-muted hover:text-red-500 transition-all"
+        title="Remove"
+      >
+        <span className="material-symbols-outlined text-[12px]">close</span>
+      </button>
+    </div>
+  );
+}
+
+function ComboFormModal({ isOpen, combo, onClose, onSave, activeProviders, kindFilter = null }) {
+  // Initialize state with combo values - key prop on parent handles reset on remount
+  const [name, setName] = useState(combo?.name || "");
+  const [models, setModels] = useState(combo?.models || []);
+  const [showModelSelect, setShowModelSelect] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [nameError, setNameError] = useState("");
+  const [modelAliases, setModelAliases] = useState({});
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
+  );
+
+  // Use stable index-based IDs so duplicates and similar names are handled correctly
+  const modelItems = models.map((model, i) => ({ uid: `item-${i}`, model }));
+
+  const handleDragEnd = (event) => {
+    const { active, over } = event;
+    if (over && active.id !== over.id) {
+      const oldIndex = modelItems.findIndex((m) => m.uid === active.id);
+      const newIndex = modelItems.findIndex((m) => m.uid === over.id);
+      if (oldIndex !== -1 && newIndex !== -1) {
+        setModels((prev) => arrayMove(prev, oldIndex, newIndex));
+      }
+    }
+  };
+
+  const fetchModalData = async () => {
+    try {
+      const aliasesRes = await fetch("/api/models/alias");
+      if (!aliasesRes.ok) return;
+      const aliasesData = await aliasesRes.json();
+      setModelAliases(aliasesData.aliases || {});
+    } catch (error) {
+      console.error("Error fetching modal data:", error);
+    }
+  };
+
+  useEffect(() => {
+    if (isOpen) fetchModalData();
+  }, [isOpen]);
+
+  const validateName = (value) => {
+    if (!value.trim()) {
+      setNameError("Name is required");
+      return false;
+    }
+    if (!VALID_NAME_REGEX.test(value)) {
+      setNameError("Only letters, numbers, -, _ and . allowed");
+      return false;
+    }
+    setNameError("");
+    return true;
+  };
+
+  const handleNameChange = (e) => {
+    const value = e.target.value;
+    setName(value);
+    if (value) validateName(value);
+    else setNameError("");
+  };
+
+  const handleAddModel = (model) => {
+    if (!models.includes(model.value)) {
+      setModels([...models, model.value]);
+    }
+  };
+
+  const handleDeselectModel = (model) => {
+    setModels(models.filter((m) => m !== model.value));
+  };
+
+  const handleRemoveModel = (index) => {
+    setModels(models.filter((_, i) => i !== index));
+  };
+
+  const handleMoveUp = (index) => {
+    if (index === 0) return;
+    const newModels = [...models];
+    [newModels[index - 1], newModels[index]] = [newModels[index], newModels[index - 1]];
+    setModels(newModels);
+  };
+
+  const handleMoveDown = (index) => {
+    if (index === models.length - 1) return;
+    const newModels = [...models];
+    [newModels[index], newModels[index + 1]] = [newModels[index + 1], newModels[index]];
+    setModels(newModels);
+  };
+
+  const handleSave = async () => {
+    if (!validateName(name)) return;
+    setSaving(true);
+    await onSave({ name: name.trim(), models });
+    setSaving(false);
+  };
+
+  const isEdit = !!combo;
+
+  return (
+    <>
+      <Modal
+        isOpen={isOpen}
+        onClose={onClose}
+        title={isEdit ? "Edit Combo" : "Create Combo"}
+      >
+        <div className="flex flex-col gap-3">
+          {/* Name */}
+          <div>
+            <Input
+              label="Combo Name"
+              value={name}
+              onChange={handleNameChange}
+              placeholder="my-combo"
+              error={nameError}
+            />
+            <p className="text-[10px] text-text-muted mt-0.5">
+              Only letters, numbers, -, _ and . allowed
+            </p>
+          </div>
+
+          {/* Models */}
+          <div>
+            <label className="text-sm font-medium mb-1.5 block">Models</label>
+
+            {models.length === 0 ? (
+              <div className="text-center py-4 border border-dashed border-black/10 dark:border-white/10 rounded-lg bg-black/[0.01] dark:bg-white/[0.01]">
+                <span className="material-symbols-outlined text-text-muted text-xl mb-1">layers</span>
+                <p className="text-xs text-text-muted">No models added yet</p>
+              </div>
+            ) : (
+            <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd} modifiers={[restrictToVerticalAxis, restrictToParentElement]}>
+              <SortableContext items={modelItems.map((m) => m.uid)} strategy={verticalListSortingStrategy}>
+                <div className="flex max-h-[55vh] min-w-0 flex-col gap-1 overflow-y-auto sm:max-h-[350px]">
+                  {modelItems.map(({ uid, model }, index) => (
+                    <ModelItem
+                      key={uid}
+                      id={uid}
+                      index={index}
+                      model={model}
+                      isFirst={index === 0}
+                      isLast={index === modelItems.length - 1}
+                      onEdit={(newVal) => {
+                        const updated = [...models];
+                        updated[index] = newVal;
+                        setModels(updated);
+                      }}
+                      onMoveUp={() => handleMoveUp(index)}
+                      onMoveDown={() => handleMoveDown(index)}
+                      onRemove={() => handleRemoveModel(index)}
+                    />
+                  ))}
+                </div>
+              </SortableContext>
+            </DndContext>
+            )}
+
+            {/* Add Model button */}
+            <button
+              onClick={() => setShowModelSelect(true)}
+              className="w-full mt-2 py-2 border border-dashed border-black/10 dark:border-white/10 rounded-lg text-xs text-primary font-medium hover:text-primary hover:border-primary/50 transition-colors flex items-center justify-center gap-1"
+            >
+              <span className="material-symbols-outlined text-[16px]">add</span>
+              Add Model
+            </button>
+          </div>
+
+          {/* Actions */}
+          <div className="flex flex-col gap-2 pt-1 sm:flex-row">
+            <Button onClick={onClose} variant="ghost" fullWidth size="sm">
+              Cancel
+            </Button>
+            <Button
+              onClick={handleSave}
+              fullWidth
+              size="sm"
+              disabled={!name.trim() || !!nameError || saving}
+            >
+              {saving ? "Saving..." : isEdit ? "Save" : "Create"}
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      {/* Model Select Modal */}
+      <ModelSelectModal
+        isOpen={showModelSelect}
+        onClose={() => setShowModelSelect(false)}
+        onSelect={handleAddModel}
+        onDeselect={handleDeselectModel}
+        activeProviders={activeProviders}
+        modelAliases={modelAliases}
+        title="Add Model to Combo"
+        kindFilter={kindFilter}
+        addedModelValues={models}
+        closeOnSelect={false}
+      />
+    </>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/console-log/ConsoleLogClient.js b/src/app/(dashboard)/dashboard/console-log/ConsoleLogClient.js
new file mode 100644
index 0000000..01a8a75
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/console-log/ConsoleLogClient.js
@@ -0,0 +1,96 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { Card, Button } from "@/shared/components";
+import { CONSOLE_LOG_CONFIG } from "@/shared/constants/config";
+
+const LOG_LEVEL_COLORS = {
+  LOG: "text-green-400",
+  INFO: "text-blue-400",
+  WARN: "text-yellow-400",
+  ERROR: "text-red-400",
+  DEBUG: "text-purple-400",
+};
+
+function colorLine(line) {
+  const match = line.match(/\[(\w+)\]/g);
+  const levelTag = match ? match[1]?.replace(/\[|\]/g, "") : null;
+  const color = LOG_LEVEL_COLORS[levelTag] || "text-green-400";
+  return <span className={color}>{line}</span>;
+}
+
+export default function ConsoleLogClient() {
+  const [logs, setLogs] = useState([]);
+  const [connected, setConnected] = useState(false);
+  const logRef = useRef(null);
+
+  const handleClear = async () => {
+    try {
+      await fetch("/api/translator/console-logs", { method: "DELETE" });
+      // UI cleared via SSE "clear" event
+    } catch (err) {
+      console.error("Failed to clear console logs:", err);
+    }
+  };
+
+  useEffect(() => {
+    const es = new EventSource("/api/translator/console-logs/stream");
+
+    es.onopen = () => setConnected(true);
+
+    es.onmessage = (e) => {
+      const msg = JSON.parse(e.data);
+      if (msg.type === "init") {
+        setLogs(msg.logs.slice(-CONSOLE_LOG_CONFIG.maxLines));
+      } else if (msg.type === "line") {
+        setLogs((prev) => {
+          const next = [...prev, msg.line];
+          return next.length > CONSOLE_LOG_CONFIG.maxLines ? next.slice(-CONSOLE_LOG_CONFIG.maxLines) : next;
+        });
+      } else if (msg.type === "lines") {
+        setLogs((prev) => {
+          const next = [...prev, ...msg.lines];
+          return next.length > CONSOLE_LOG_CONFIG.maxLines ? next.slice(-CONSOLE_LOG_CONFIG.maxLines) : next;
+        });
+      } else if (msg.type === "clear") {
+        setLogs([]);
+      }
+    };
+
+    es.onerror = () => setConnected(false);
+
+    return () => es.close();
+  }, []);
+
+  // Auto-scroll to bottom on new logs
+  useEffect(() => {
+    if (!logRef.current) return;
+    logRef.current.scrollTop = logRef.current.scrollHeight;
+  }, [logs]);
+
+  return (
+    <div className="">
+      <Card>
+        <div className="flex items-center justify-end px-4 pt-3 pb-2">
+          <Button size="sm" variant="outline" icon="delete" onClick={handleClear}>
+            Clear
+          </Button>
+        </div>
+        <div
+          ref={logRef}
+          className="bg-black rounded-b-lg p-4 text-xs font-mono h-[calc(100vh-220px)] overflow-y-auto"
+        >
+          {logs.length === 0 ? (
+            <span className="text-text-muted">No console logs yet.</span>
+          ) : (
+            <div className="space-y-0.5">
+              {logs.map((line, i) => (
+                <div key={i}>{colorLine(line)}</div>
+              ))}
+            </div>
+          )}
+        </div>
+      </Card>
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/console-log/page.js b/src/app/(dashboard)/dashboard/console-log/page.js
new file mode 100644
index 0000000..863cef8
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/console-log/page.js
@@ -0,0 +1,8 @@
+import ConsoleLogClient from "./ConsoleLogClient";
+
+// Force dynamic so Next.js standalone build includes the server-side JS file
+export const dynamic = "force-dynamic";
+
+export default function ConsoleLogPage() {
+  return <ConsoleLogClient />;
+}
diff --git a/src/app/(dashboard)/dashboard/endpoint/EndpointPageClient.js b/src/app/(dashboard)/dashboard/endpoint/EndpointPageClient.js
new file mode 100644
index 0000000..a718374
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/endpoint/EndpointPageClient.js
@@ -0,0 +1,1295 @@
+"use client";
+
+import { useState, useEffect, useRef, useCallback } from "react";
+import PropTypes from "prop-types";
+import { Card, Button, Input, Modal, CardSkeleton, Toggle, ConfirmModal } from "@/shared/components";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import {
+  TUNNEL_BENEFITS,
+  TUNNEL_PING_INTERVAL_MS,
+  TUNNEL_PING_MAX_MS,
+  STATUS_POLL_FAST_MS,
+  REACHABLE_MISS_THRESHOLD,
+  CLIENT_PING_FAST_MS,
+} from "./endpointConstants";
+import { clientPingUrl, clientPingAny } from "./endpointPing";
+import EndpointRow from "./components/EndpointRow";
+import StatusAlert from "./components/StatusAlert";
+import Tooltip from "./components/Tooltip";
+import SecurityWarning from "./components/SecurityWarning";
+export default function APIPageClient({ machineId }) {
+  const [keys, setKeys] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [showAddModal, setShowAddModal] = useState(false);
+  const [newKeyName, setNewKeyName] = useState("");
+  const [createdKey, setCreatedKey] = useState(null);
+  const [confirmState, setConfirmState] = useState(null);
+
+  const [requireApiKey, setRequireApiKey] = useState(false);
+  const [requireLogin, setRequireLogin] = useState(true);
+  const [hasPassword, setHasPassword] = useState(true);
+ const [tunnelDashboardAccess, setTunnelDashboardAccess] = useState(false);
+
+ // Cloudflare Tunnel state
+  const [tunnelChecking, setTunnelChecking] = useState(true);
+  const [tunnelEnabled, setTunnelEnabled] = useState(false);
+  const [tunnelReachable, setTunnelReachable] = useState(false);
+  const [tunnelUrl, setTunnelUrl] = useState("");
+  const [tunnelPublicUrl, setTunnelPublicUrl] = useState("");
+  const [tunnelLoading, setTunnelLoading] = useState(false);
+  const [tunnelProgress, setTunnelProgress] = useState("");
+  const [tunnelStatus, setTunnelStatus] = useState(null);
+  const [showEnableTunnelModal, setShowEnableTunnelModal] = useState(false);
+  const [showDisableTunnelModal, setShowDisableTunnelModal] = useState(false);
+
+  // Tailscale state
+  const [tsEnabled, setTsEnabled] = useState(false);
+  const [tsReachable, setTsReachable] = useState(false);
+  const [tsUrl, setTsUrl] = useState("");
+  const [tsLoading, setTsLoading] = useState(false);
+  const [tsProgress, setTsProgress] = useState("");
+  const [tsStatus, setTsStatus] = useState(null);
+  const [tsAuthUrl, setTsAuthUrl] = useState("");
+  const [tsAuthLabel, setTsAuthLabel] = useState("");
+  const [tsInstalled, setTsInstalled] = useState(null); // null=checking, true/false
+  const [tsInstalling, setTsInstalling] = useState(false);
+  const [tsInstallLog, setTsInstallLog] = useState([]);
+  const [tsSudoPassword, setTsSudoPassword] = useState("");
+  const [tsConnecting, setTsConnecting] = useState(false);
+  const [showTsModal, setShowTsModal] = useState(false);
+  const [showDisableTsModal, setShowDisableTsModal] = useState(false);
+  const tsLogRef = useRef(null);
+
+  // Debounce reachable=false: server may briefly return false during background refresh.
+  // Only flip UI to "reconnecting" after N consecutive misses to avoid spinner flicker.
+  const tunnelMissRef = useRef(0);
+  const tsMissRef = useRef(0);
+  // Browser-side reachable cache (independent of backend DNS quirks)
+  const tunnelClientReachableRef = useRef(false);
+  const tsClientReachableRef = useRef(false);
+  // Track whether reachable=true was ever observed in this session.
+  // Distinguishes "Checking..." (initial cold cache) from "Reconnecting..." (lost connection).
+  const tunnelEverReachableRef = useRef(false);
+  const tsEverReachableRef = useRef(false);
+  const [tunnelEverReachable, setTunnelEverReachable] = useState(false);
+  const [tsEverReachable, setTsEverReachable] = useState(false);
+
+  // API key visibility toggle state
+  const [visibleKeys, setVisibleKeys] = useState(new Set());
+
+  // Client-side local/remote detection (UI hint only, not a security gate)
+  const [isRemoteHost, setIsRemoteHost] = useState(false);
+  useEffect(() => {
+    if (typeof window !== "undefined")
+      setIsRemoteHost(!["localhost", "127.0.0.1", "::1"].includes(window.location.hostname));
+  }, []);
+
+  const { copied, copy } = useCopyToClipboard();
+
+  // Security gate: block remote exposure while dashboard uses default password or login is off.
+  const isLoginUnsafe = !requireLogin || !hasPassword;
+  const unsafeReason = !requireLogin
+    ? "Enable \"Require login\" and set a custom password before activating the tunnel."
+    : "Change the default dashboard password before activating the tunnel.";
+
+  // Auto-scroll install log
+  useEffect(() => {
+    if (tsLogRef.current) tsLogRef.current.scrollTop = tsLogRef.current.scrollHeight;
+  }, [tsInstallLog]);
+
+  useEffect(() => {
+    fetchData();
+    loadSettings();
+  }, []);
+
+  // Status poll: only while degraded (not yet reachable). Stop once healthy to avoid spam.
+  // Visibility re-check: refresh once when tab becomes visible.
+  useEffect(() => {
+    const anyEnabled = tunnelEnabled || tsEnabled;
+    if (!anyEnabled) return;
+    const tunnelHealthy = !tunnelEnabled || tunnelReachable;
+    const tsHealthy = !tsEnabled || tsReachable;
+    const allHealthy = tunnelHealthy && tsHealthy;
+    const onVisible = () => { if (!document.hidden) syncTunnelStatus(); };
+    document.addEventListener("visibilitychange", onVisible);
+    if (allHealthy) return () => document.removeEventListener("visibilitychange", onVisible);
+    const timer = setInterval(() => { if (!document.hidden) syncTunnelStatus(); }, STATUS_POLL_FAST_MS);
+    return () => {
+      clearInterval(timer);
+      document.removeEventListener("visibilitychange", onVisible);
+    };
+  }, [tunnelEnabled, tsEnabled, tunnelReachable, tsReachable]);
+
+  // Browser-side periodic ping: probes tunnel/tailscale URLs directly so UI stays
+  // "reachable" even when backend DNS (1.1.1.1) hiccups on *.ts.net or *.trycloudflare.com.
+  // Adaptive: slow when healthy, fast when degraded; pause when tab hidden.
+  useEffect(() => {
+    const probeBoth = async () => {
+      if (document.hidden) return;
+      if (tunnelEnabled && (tunnelUrl || tunnelPublicUrl)) {
+        const ok = await clientPingAny(tunnelPublicUrl, tunnelUrl);
+        tunnelClientReachableRef.current = ok;
+        if (ok) { tunnelMissRef.current = 0; setTunnelReachable(true); if (!tunnelEverReachableRef.current) { tunnelEverReachableRef.current = true; setTunnelEverReachable(true); } }
+        else { tunnelMissRef.current += 1; if (tunnelMissRef.current >= REACHABLE_MISS_THRESHOLD) setTunnelReachable(false); }
+      } else {
+        tunnelClientReachableRef.current = false;
+      }
+      if (tsEnabled && tsUrl) {
+        const ok = await clientPingUrl(tsUrl);
+        tsClientReachableRef.current = ok;
+        if (ok) { tsMissRef.current = 0; setTsReachable(true); if (!tsEverReachableRef.current) { tsEverReachableRef.current = true; setTsEverReachable(true); } }
+        else { tsMissRef.current += 1; if (tsMissRef.current >= REACHABLE_MISS_THRESHOLD) setTsReachable(false); }
+      } else {
+        tsClientReachableRef.current = false;
+      }
+    };
+    const anyEnabled = (tunnelEnabled && (tunnelUrl || tunnelPublicUrl)) || (tsEnabled && tsUrl);
+    if (!anyEnabled) return;
+    probeBoth();
+    const tunnelHealthy = !tunnelEnabled || tunnelReachable;
+    const tsHealthy = !tsEnabled || tsReachable;
+    if (tunnelHealthy && tsHealthy) return;
+    const id = setInterval(probeBoth, CLIENT_PING_FAST_MS);
+    return () => clearInterval(id);
+  }, [tunnelEnabled, tunnelUrl, tunnelPublicUrl, tsEnabled, tsUrl, tunnelReachable, tsReachable]);
+
+  // Client-side reachable only (server no longer probes; watchdog handles backend health).
+  // Miss-debounce: only flip to false after N consecutive misses.
+  const updateReachable = useCallback((_unused, clientRef, missRef, setter, everRef, everSetter) => {
+    const reachable = clientRef.current;
+    if (reachable) {
+      missRef.current = 0;
+      setter(true);
+      if (!everRef.current) {
+        everRef.current = true;
+        everSetter(true);
+      }
+    } else {
+      missRef.current += 1;
+      if (missRef.current >= REACHABLE_MISS_THRESHOLD) setter(false);
+    }
+  }, []);
+
+  // Trust user intent (settingsEnabled): UI stays "enabled" while watchdog restarts process
+  const syncTunnelStatus = async () => {
+    try {
+      const statusRes = await fetch("/api/tunnel/status", { cache: "no-store" });
+      if (!statusRes.ok) return;
+      const data = await statusRes.json();
+      const tEnabled = data.tunnel?.settingsEnabled ?? data.tunnel?.enabled ?? false;
+      const tUrl = data.tunnel?.tunnelUrl || "";
+      setTunnelUrl(tUrl);
+      setTunnelPublicUrl(data.tunnel?.publicUrl || "");
+      setTunnelEnabled(tEnabled);
+      updateReachable(null, tunnelClientReachableRef, tunnelMissRef, setTunnelReachable, tunnelEverReachableRef, setTunnelEverReachable);
+
+      const tsEn = data.tailscale?.settingsEnabled ?? data.tailscale?.enabled ?? false;
+      const tsUrlVal = data.tailscale?.tunnelUrl || "";
+      setTsUrl(tsUrlVal);
+      setTsEnabled(tsEn);
+      updateReachable(null, tsClientReachableRef, tsMissRef, setTsReachable, tsEverReachableRef, setTsEverReachable);
+    } catch { /* ignore poll errors */ }
+  };
+
+  const loadSettings = async () => {
+    setTunnelChecking(true);
+    try {
+      const [settingsRes, statusRes] = await Promise.all([
+        fetch("/api/settings"),
+        fetch("/api/tunnel/status", { cache: "no-store" })
+      ]);
+      if (settingsRes.ok) {
+        const data = await settingsRes.json();
+        setRequireApiKey(data.requireApiKey || false);
+        setRequireLogin(data.requireLogin !== false);
+        setHasPassword(data.hasPassword || false);
+        setTunnelDashboardAccess(data.tunnelDashboardAccess || false);
+      }
+      if (statusRes.ok) {
+        const data = await statusRes.json();
+        const tEnabled = data.tunnel?.settingsEnabled ?? data.tunnel?.enabled ?? false;
+        const tUrl = data.tunnel?.tunnelUrl || "";
+        setTunnelUrl(tUrl);
+        setTunnelPublicUrl(data.tunnel?.publicUrl || "");
+        setTunnelEnabled(tEnabled);
+        updateReachable(null, tunnelClientReachableRef, tunnelMissRef, setTunnelReachable, tunnelEverReachableRef, setTunnelEverReachable);
+
+        const tsEn = data.tailscale?.settingsEnabled ?? data.tailscale?.enabled ?? false;
+        const tsUrlVal = data.tailscale?.tunnelUrl || "";
+        setTsUrl(tsUrlVal);
+        setTsEnabled(tsEn);
+        updateReachable(null, tsClientReachableRef, tsMissRef, setTsReachable, tsEverReachableRef, setTsEverReachable);
+      }
+    } catch (error) {
+      console.log("Error loading settings:", error);
+    } finally {
+      setTunnelChecking(false);
+    }
+  };
+
+  const handleTunnelDashboardAccess = async (value) => {
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ tunnelDashboardAccess: value }),
+      });
+      if (res.ok) setTunnelDashboardAccess(value);
+    } catch (error) {
+      console.log("Error updating tunnelDashboardAccess:", error);
+    }
+  };
+
+  const handleRequireApiKey = async (value) => {
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ requireApiKey: value }),
+      });
+      if (res.ok) setRequireApiKey(value);
+    } catch (error) {
+      console.log("Error updating requireApiKey:", error);
+    }
+  };
+
+  const fetchData = async () => {
+    try {
+      const keysRes = await fetch("/api/keys");
+      const keysData = await keysRes.json();
+      if (keysRes.ok) {
+        setKeys(keysData.keys || []);
+      }
+    } catch (error) {
+      console.log("Error fetching data:", error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // u2500u2500u2500 Cloudflare Tunnel handlers
+  // Ping tunnel health until reachable. Race multiple URLs (shortlink + direct) — 1 OK is enough.
+  const pingTunnelHealth = async (...urls) => {
+    setTunnelLoading(true);
+    setTunnelProgress("Waiting for tunnel ready...");
+    const targets = urls.filter(Boolean).map((u) => `${u}/api/health`);
+    const start = Date.now();
+    while (Date.now() - start < TUNNEL_PING_MAX_MS) {
+      await new Promise((r) => setTimeout(r, TUNNEL_PING_INTERVAL_MS));
+      const ok = await Promise.any(targets.map(async (h) => {
+        const p = await fetch(h, { mode: "cors", cache: "no-store" });
+        if (p.ok) return true;
+        throw new Error("not ready");
+      })).catch(() => false);
+      if (ok) {
+        setTunnelEnabled(true);
+        setTunnelLoading(false);
+        setTunnelProgress("");
+        return true;
+      }
+      // Every 5 pings (~10s), check if backend process still alive
+      if ((Date.now() - start) % 10000 < TUNNEL_PING_INTERVAL_MS) {
+        try {
+          const statusRes = await fetch("/api/tunnel/status");
+          if (statusRes.ok) {
+            const status = await statusRes.json();
+            if (!status.tunnel?.enabled) {
+              setTunnelStatus({ type: "error", message: "Tunnel process stopped unexpectedly." });
+              setTunnelLoading(false);
+              setTunnelProgress("");
+              return false;
+            }
+          }
+        } catch { /* ignore */ }
+      }
+    }
+    setTunnelStatus({ type: "error", message: "Tunnel created but not reachable. Please try again." });
+    setTunnelLoading(false);
+    setTunnelProgress("");
+    return false;
+  };
+
+  const handleEnableTunnel = async () => {
+    setShowEnableTunnelModal(false);
+    setTunnelLoading(true);
+    setTunnelStatus(null);
+    setTunnelProgress("Creating tunnel...");
+
+    // Poll download progress while enable request is pending
+    let polling = true;
+    const pollProgress = async () => {
+      while (polling) {
+        try {
+          const r = await fetch("/api/tunnel/status");
+          if (r.ok) {
+            const s = await r.json();
+            if (s.download?.downloading) {
+              setTunnelProgress(`Downloading cloudflared... ${s.download.progress}%`);
+            } else if (polling) {
+              setTunnelProgress("Creating tunnel...");
+            }
+          }
+        } catch { /* ignore */ }
+        await new Promise((r) => setTimeout(r, 1000));
+      }
+    };
+    pollProgress();
+
+    try {
+      const res = await fetch("/api/tunnel/enable", { method: "POST" });
+      polling = false;
+      const data = await res.json();
+      if (!res.ok) {
+        setTunnelStatus({ type: "error", message: data.error || "Failed to enable tunnel" });
+        return;
+      }
+
+      const url = data.tunnelUrl;
+      if (!url) {
+        setTunnelStatus({ type: "error", message: "No tunnel URL returned" });
+        return;
+      }
+
+      setTunnelUrl(url);
+      setTunnelPublicUrl(data.publicUrl || "");
+      await pingTunnelHealth(data.publicUrl, url);
+    } catch (error) {
+      setTunnelStatus({ type: "error", message: error.message });
+    } finally {
+      polling = false;
+      setTunnelLoading(false);
+      setTunnelProgress("");
+    }
+  };
+
+  const handleDisableTunnel = async () => {
+    setTunnelLoading(true);
+    setTunnelStatus(null);
+    try {
+      const res = await fetch("/api/tunnel/disable", { method: "POST" });
+      const data = await res.json();
+      if (res.ok) {
+        setTunnelEnabled(false);
+        setTunnelUrl("");
+        setShowDisableTunnelModal(false);
+        setTunnelStatus({ type: "success", message: "Tunnel disabled" });
+      } else {
+        setTunnelStatus({ type: "error", message: data.error || "Failed to disable tunnel" });
+      }
+    } catch (error) {
+      setTunnelStatus({ type: "error", message: error.message });
+    } finally {
+      setTunnelLoading(false);
+    }
+  };
+
+  // u2500u2500u2500 Tailscale handlers
+  const checkTailscaleInstalled = async () => {
+    setTsInstalled(null);
+    try {
+      const res = await fetch("/api/tunnel/tailscale-check");
+      if (res.ok) {
+        const data = await res.json();
+        setTsInstalled(data.installed);
+        return data;
+      }
+    } catch { /* ignore */ }
+    setTsInstalled(false);
+    return { installed: false };
+  };
+
+  const handleInstallTailscale = async () => {
+    setTsInstalling(true);
+    setTsStatus(null);
+    setTsInstallLog([]);
+    try {
+      const res = await fetch("/api/tunnel/tailscale-install", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ sudoPassword: tsSudoPassword }),
+      });
+      setTsSudoPassword("");
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const parts = buffer.split("\n\n");
+        buffer = parts.pop() || "";
+        for (const part of parts) {
+          const lines = part.split("\n");
+          let event = "progress";
+          let data = null;
+          for (const line of lines) {
+            if (line.startsWith("event: ")) event = line.slice(7).trim();
+            if (line.startsWith("data: ")) {
+              try { data = JSON.parse(line.slice(6)); } catch { /* skip */ }
+            }
+          }
+          if (!data) continue;
+          if (event === "progress") {
+            setTsInstallLog((prev) => [...prev.slice(-50), data.message]);
+          } else if (event === "done") {
+            setTsInstalled(true);
+            setTsInstalling(false);
+            setShowTsModal(false);
+            handleConnectTailscale();
+            return;
+          } else if (event === "error") {
+            setTsStatus({ type: "error", message: data.error || "Install failed" });
+          }
+        }
+      }
+    } catch (e) {
+      setTsStatus({ type: "error", message: e.message });
+    } finally {
+      setTsInstalling(false);
+    }
+  };
+
+  // Ping Tailscale health until reachable
+  const pingTsHealth = async (url) => {
+    setTsProgress("Waiting for Tailscale ready...");
+    const healthUrl = `${url}/api/health`;
+    const start = Date.now();
+    while (Date.now() - start < TUNNEL_PING_MAX_MS) {
+      await new Promise((r) => setTimeout(r, TUNNEL_PING_INTERVAL_MS));
+      try {
+        const ping = await fetch(healthUrl, { mode: "no-cors", cache: "no-store" });
+        if (ping.ok || ping.type === "opaque") return true;
+      } catch { /* not ready yet */ }
+    }
+    return false;
+  };
+
+  // Show inline login button instead of auto-opening popup (browsers block popups
+  // opened after async work because the user gesture is lost).
+  const requestUserAuth = (url, label) => {
+    setTsAuthUrl(url);
+    setTsAuthLabel(label);
+  };
+
+  const clearUserAuth = () => {
+    setTsAuthUrl("");
+    setTsAuthLabel("");
+  };
+
+  const handleConnectTailscale = async () => {
+    setShowTsModal(false);
+    setTsConnecting(true);
+    setTsLoading(true);
+    setTsStatus(null);
+    setTsProgress("Connecting...");
+    clearUserAuth();
+    try {
+      const res = await fetch("/api/tunnel/tailscale-enable", { method: "POST" });
+      const data = await res.json();
+
+      if (res.ok && data.success) {
+        setTsUrl(data.tunnelUrl || "");
+        const reachable = await pingTsHealth(data.tunnelUrl);
+        setTsEnabled(true);
+        setTsStatus(reachable ? null : { type: "warning", message: "Connected but not reachable yet." });
+        return;
+      }
+
+      if (data.needsLogin && data.authUrl) {
+        requestUserAuth(data.authUrl, "Open Login Page");
+        setTsProgress("Login required — click \"Open Login Page\" to continue");
+        for (let i = 0; i < 40; i++) {
+          await new Promise((r) => setTimeout(r, 3000));
+          try {
+            const r2 = await fetch("/api/tunnel/tailscale-check");
+            if (r2.ok) {
+              const check = await r2.json();
+              if (check.loggedIn) {
+                clearUserAuth();
+                setTsProgress("Starting funnel...");
+                const res2 = await fetch("/api/tunnel/tailscale-enable", { method: "POST" });
+                const data2 = await res2.json();
+                if (res2.ok && data2.success) {
+                  setTsUrl(data2.tunnelUrl || "");
+                  const ok2 = await pingTsHealth(data2.tunnelUrl);
+                  setTsEnabled(true);
+                  setTsStatus(ok2 ? null : { type: "warning", message: "Connected but not reachable yet." });
+                } else if (data2.funnelNotEnabled && data2.enableUrl) {
+                  await pollFunnelEnable(data2.enableUrl);
+                } else {
+                  setTsStatus({ type: "error", message: data2.error || "Failed to start funnel" });
+                }
+                return;
+              }
+            }
+          } catch { /* retry */ }
+        }
+        clearUserAuth();
+        setTsStatus({ type: "error", message: "Login timed out. Please try again." });
+        return;
+      }
+
+      if (data.funnelNotEnabled && data.enableUrl) {
+        await pollFunnelEnable(data.enableUrl);
+        return;
+      }
+
+      setTsStatus({ type: "error", message: data.error || "Failed to connect" });
+    } catch (error) {
+      setTsStatus({ type: "error", message: error.message });
+    } finally {
+      setTsLoading(false);
+      setTsConnecting(false);
+      setTsProgress("");
+      clearUserAuth();
+    }
+  };
+
+  const pollFunnelEnable = async (enableUrl) => {
+    requestUserAuth(enableUrl, "Open Funnel Settings");
+    setTsProgress("Click \"Open Funnel Settings\" to enable Funnel...");
+    for (let i = 0; i < 40; i++) {
+      await new Promise((r) => setTimeout(r, 3000));
+      try {
+        const res = await fetch("/api/tunnel/tailscale-enable", { method: "POST" });
+        const data = await res.json();
+        if (res.ok && data.success) {
+          clearUserAuth();
+          setTsUrl(data.tunnelUrl || "");
+          const ok3 = await pingTsHealth(data.tunnelUrl);
+          setTsEnabled(true);
+          setTsStatus(ok3 ? null : { type: "warning", message: "Connected but not reachable yet." });
+          return;
+        }
+        if (data.funnelNotEnabled) continue;
+        if (data.error) {
+          clearUserAuth();
+          setTsStatus({ type: "error", message: data.error });
+          return;
+        }
+      } catch { /* retry */ }
+    }
+    clearUserAuth();
+    setTsStatus({ type: "error", message: "Timed out waiting for Funnel to be enabled." });
+  };
+
+  const handleDisableTailscale = async () => {
+    setTsLoading(true);
+    setTsStatus(null);
+    try {
+      const res = await fetch("/api/tunnel/tailscale-disable", { method: "POST" });
+      const data = await res.json();
+      if (res.ok) {
+        setTsEnabled(false);
+        setTsUrl("");
+        setShowDisableTsModal(false);
+        setTsStatus({ type: "success", message: "Tailscale disabled" });
+      } else {
+        setTsStatus({ type: "error", message: data.error || "Failed to disable Tailscale" });
+      }
+    } catch (e) {
+      setTsStatus({ type: "error", message: e.message });
+    } finally {
+      setTsLoading(false);
+    }
+  };
+
+  const handleOpenTsModal = async () => {
+    setTsStatus(null);
+    setTsInstallLog([]);
+    const data = await checkTailscaleInstalled();
+    if (data?.installed && data?.hasCachedPassword) {
+      handleConnectTailscale();
+    } else {
+      setShowTsModal(true);
+    }
+  };
+
+  const handleCreateKey = async () => {
+    if (!newKeyName.trim()) return;
+
+    try {
+      const res = await fetch("/api/keys", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name: newKeyName }),
+      });
+      const data = await res.json();
+
+      if (res.ok) {
+        setCreatedKey(data.key);
+        await fetchData();
+        setNewKeyName("");
+        setShowAddModal(false);
+      }
+    } catch (error) {
+      console.log("Error creating key:", error);
+    }
+  };
+
+  const handleDeleteKey = async (id) => {
+    setConfirmState({
+      title: "Delete API Key",
+      message: "Delete this API key?",
+      onConfirm: async () => {
+        setConfirmState(null);
+        try {
+          const res = await fetch(`/api/keys/${id}`, { method: "DELETE" });
+          if (res.ok) {
+            setKeys(keys.filter((k) => k.id !== id));
+            setVisibleKeys(prev => {
+              const next = new Set(prev);
+              next.delete(id);
+              return next;
+            });
+          }
+        } catch (error) {
+          console.log("Error deleting key:", error);
+        }
+      }
+    });
+  };
+
+  const handleToggleKey = async (id, isActive) => {
+    try {
+      const res = await fetch(`/api/keys/${id}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ isActive }),
+      });
+      if (res.ok) {
+        setKeys(prev => prev.map(k => k.id === id ? { ...k, isActive } : k));
+      }
+    } catch (error) {
+      console.log("Error toggling key:", error);
+    }
+  };
+
+  const maskKey = (fullKey) => {
+    if (!fullKey || fullKey.length <= 10) return fullKey || "";
+    return fullKey.slice(0, 6) + "•".repeat(fullKey.length - 10) + fullKey.slice(-4);
+  };
+
+  const toggleKeyVisibility = (keyId) => {
+    setVisibleKeys(prev => {
+      const next = new Set(prev);
+      if (next.has(keyId)) next.delete(keyId);
+      else next.add(keyId);
+      return next;
+    });
+  };
+
+  const [baseUrl, setBaseUrl] = useState("/v1");
+
+  // Hydration fix: Only access window on client side
+  useEffect(() => {
+    if (typeof window !== "undefined") {
+      setBaseUrl(`${window.location.origin}/v1`);
+    }
+  }, []);
+
+  if (loading) {
+    return (
+      <div className="flex flex-col gap-8">
+        <CardSkeleton />
+        <CardSkeleton />
+      </div>
+    );
+  }
+
+  const currentEndpoint = baseUrl;
+
+  return (
+    <div className="flex flex-col gap-8">
+      {/* Endpoint Card */}
+      <Card>
+        <h2 className="text-lg font-semibold mb-4 flex items-center gap-2">
+          <span className="material-symbols-outlined text-primary">api</span>
+          API Endpoint
+        </h2>
+
+        {/* Endpoint rows */}
+        <div className="flex flex-col gap-2">
+          {/* Local */}
+          <EndpointRow
+            label="Local"
+            url={currentEndpoint}
+            copyId="local_url"
+            copied={copied}
+            onCopy={copy}
+          />
+          {/* Cloudflare Tunnel */}
+          <div className="flex items-center gap-2">
+            <span className={`text-xs font-mono px-1.5 py-0.5 rounded shrink-0 min-w-[88px] text-center ${
+              tunnelEnabled ? "bg-primary/10 text-primary" : "bg-surface-2 text-text-muted"
+            }`}>Tunnel</span>
+            {tunnelEnabled && !tunnelLoading && tunnelReachable ? (
+              <>
+                <Input value={`${tunnelPublicUrl || tunnelUrl}/v1`} readOnly className="flex-1 font-mono text-sm" />
+                <button
+                  onClick={() => copy(`${tunnelPublicUrl || tunnelUrl}/v1`, "tunnel_url")}
+                  className="p-2 hover:bg-black/5 dark:hover:bg-white/5 rounded text-text-muted hover:text-primary transition-colors shrink-0"
+                >
+                  <span className="material-symbols-outlined text-[18px]">{copied === "tunnel_url" ? "check" : "content_copy"}</span>
+                </button>
+                <button
+                  onClick={() => setShowDisableTunnelModal(true)}
+                  className="p-2 hover:bg-red-500/10 rounded text-red-500 transition-colors shrink-0"
+                  title="Disable Tunnel"
+                >
+                  <span className="material-symbols-outlined text-[18px]">power_settings_new</span>
+                </button>
+              </>
+            ) : tunnelEnabled && !tunnelLoading && !tunnelReachable ? (
+              <>
+                <div className="flex-1 flex items-center gap-2 px-3 py-1.5 rounded border border-amber-300 dark:border-amber-800 bg-amber-500/5 text-sm text-amber-600 dark:text-amber-400">
+                  <span className="material-symbols-outlined animate-spin text-sm">progress_activity</span>
+                  {tunnelEverReachable ? "Tunnel reconnecting..." : "Tunnel checking..."}
+                </div>
+                <button
+                  onClick={() => setShowDisableTunnelModal(true)}
+                  className="p-2 hover:bg-red-500/10 rounded text-red-500 transition-colors shrink-0"
+                  title="Disable Tunnel"
+                >
+                  <span className="material-symbols-outlined text-[18px]">power_settings_new</span>
+                </button>
+              </>
+            ) : tunnelLoading ? (
+              <>
+                <div className="flex-1 flex items-center gap-2 px-3 py-1.5 rounded border border-border bg-input text-sm text-text-muted">
+                  <span className="material-symbols-outlined animate-spin text-sm">progress_activity</span>
+                  {tunnelProgress || "Creating tunnel..."}
+                </div>
+                <button
+                  onClick={() => { setTunnelLoading(false); setTunnelProgress(""); }}
+                  className="p-2 hover:bg-red-500/10 rounded text-red-500 transition-colors shrink-0"
+                  title="Stop"
+                >
+                  <span className="material-symbols-outlined text-[18px]">power_settings_new</span>
+                </button>
+              </>
+            ) : tunnelStatus?.type === "error" ? (
+              <>
+                <div className="flex-1 flex items-center gap-2 px-3 py-1.5 rounded border border-red-300 dark:border-red-800 bg-red-500/5 text-sm text-red-600 dark:text-red-400">
+                  <span className="material-symbols-outlined text-sm">error</span>
+                  {tunnelStatus.message}
+                </div>
+                <Button size="sm" icon="cloud_upload" onClick={() => setShowEnableTunnelModal(true)}>Enable</Button>
+              </>
+            ) : tunnelChecking ? (
+              <>
+                <div className="flex-1 flex items-center gap-2 px-3 py-1.5 rounded border border-border bg-input text-sm text-text-muted">
+                  <span className="material-symbols-outlined animate-spin text-sm">progress_activity</span>
+                  Checking...
+                </div>
+                <button
+                  onClick={() => setTunnelChecking(false)}
+                  className="p-2 hover:bg-red-500/10 rounded text-red-500 transition-colors shrink-0"
+                  title="Stop"
+                >
+                  <span className="material-symbols-outlined text-[18px]">power_settings_new</span>
+                </button>
+              </>
+            ) : (
+              <Button
+                size="sm"
+                icon="cloud_upload"
+                onClick={() => {
+                  if (isLoginUnsafe) {
+                    setTunnelStatus({ type: "error", message: `Security required: ${unsafeReason}` });
+                    return;
+                  }
+                  if (!requireApiKey) {
+                    setTunnelStatus({ type: "error", message: "Security required: Enable \"Require API key\" before activating the tunnel." });
+                    return;
+                  }
+                  setShowEnableTunnelModal(true);
+                }}
+              >
+                Enable
+              </Button>
+            )}
+          </div>
+          {/* Tailscale */}
+          <div className="flex items-center gap-2">
+            <span className={`text-xs font-mono px-1.5 py-0.5 rounded shrink-0 min-w-[88px] text-center ${
+              tsEnabled ? "bg-primary/10 text-primary" : "bg-surface-2 text-text-muted"
+            }`}>Tailscale</span>
+            {tsEnabled && !tsLoading && tsReachable ? (
+              <>
+                <Input value={`${tsUrl}/v1`} readOnly className="flex-1 font-mono text-sm" />
+                <button
+                  onClick={() => copy(`${tsUrl}/v1`, "ts_url")}
+                  className="p-2 hover:bg-black/5 dark:hover:bg-white/5 rounded text-text-muted hover:text-primary transition-colors shrink-0"
+                >
+                  <span className="material-symbols-outlined text-[18px]">{copied === "ts_url" ? "check" : "content_copy"}</span>
+                </button>
+                <button
+                  onClick={() => setShowDisableTsModal(true)}
+                  className="p-2 hover:bg-red-500/10 rounded text-red-500 transition-colors shrink-0"
+                  title="Disable Tailscale"
+                >
+                  <span className="material-symbols-outlined text-[18px]">power_settings_new</span>
+                </button>
+              </>
+            ) : tsEnabled && !tsLoading && !tsReachable ? (
+              <>
+                <div className="flex-1 flex items-center gap-2 px-3 py-1.5 rounded border border-amber-300 dark:border-amber-800 bg-amber-500/5 text-sm text-amber-600 dark:text-amber-400">
+                  <span className="material-symbols-outlined animate-spin text-sm">progress_activity</span>
+                  {tsEverReachable ? "Tailscale reconnecting..." : "Tailscale checking..."}
+                </div>
+                <button
+                  onClick={() => setShowDisableTsModal(true)}
+                  className="p-2 hover:bg-red-500/10 rounded text-red-500 transition-colors shrink-0"
+                  title="Disable Tailscale"
+                >
+                  <span className="material-symbols-outlined text-[18px]">power_settings_new</span>
+                </button>
+              </>
+            ) : (tsLoading || tsConnecting) ? (
+              <>
+                <div className="flex-1 flex items-center gap-2 px-3 py-1.5 rounded border border-border bg-input text-sm text-text-muted">
+                  <span className="material-symbols-outlined animate-spin text-sm">progress_activity</span>
+                  {tsProgress || "Connecting..."}
+                </div>
+                {tsAuthUrl && (
+                  <Button
+                    size="sm"
+                    icon="open_in_new"
+                    onClick={() => window.open(tsAuthUrl, "tailscale_auth", "width=600,height=700,noopener,noreferrer")}
+                  >
+                    {tsAuthLabel || "Open"}
+                  </Button>
+                )}
+                <button
+                  onClick={() => { setTsLoading(false); setTsConnecting(false); setTsProgress(""); clearUserAuth(); }}
+                  className="p-2 hover:bg-red-500/10 rounded text-red-500 transition-colors shrink-0"
+                  title="Stop"
+                >
+                  <span className="material-symbols-outlined text-[18px]">power_settings_new</span>
+                </button>
+              </>
+            ) : tsStatus?.type === "error" ? (
+              <>
+                <div className="flex-1 flex items-center gap-2 px-3 py-1.5 rounded border border-red-300 dark:border-red-800 bg-red-500/5 text-sm text-red-600 dark:text-red-400">
+                  <span className="material-symbols-outlined text-sm">error</span>
+                  {tsStatus.message}
+                </div>
+                <Button size="sm" icon="vpn_lock" onClick={handleOpenTsModal}>Enable</Button>
+              </>
+            ) : (
+              <Button
+                size="sm"
+                icon="vpn_lock"
+                onClick={() => {
+                  if (isLoginUnsafe) {
+                    setTsStatus({ type: "error", message: `Security required: ${unsafeReason}` });
+                    return;
+                  }
+                  handleOpenTsModal();
+                }}
+                className="bg-linear-to-r from-indigo-500 to-purple-500 hover:from-indigo-600 hover:to-purple-600 text-white!"
+              >
+                Enable
+              </Button>
+            )}
+          </div>
+        </div>
+
+        {/* Pre-enable security gate banner */}
+        {isLoginUnsafe && !tunnelEnabled && !tsEnabled && (
+          <div className="mt-4">
+            <SecurityWarning
+              message={unsafeReason}
+              action={{ label: "Open settings", href: "/dashboard/profile" }}
+            />
+          </div>
+        )}
+
+        {/* Security warnings when tunnel or tailscale is active */}
+        {(tunnelEnabled || tsEnabled) && (
+          <div className="mt-4 flex flex-col gap-2">
+            {!requireApiKey && (
+              <SecurityWarning
+                message="Require API key is disabled — your endpoint is publicly accessible without authentication."
+                action={{ label: "Enable", href: "#require-api-key" }}
+              />
+            )}
+            {(!requireLogin || !hasPassword) && (
+              <SecurityWarning
+                message={
+                  !requireLogin
+                    ? "Require login is disabled — anyone can access your dashboard via tunnel."
+                    : "Dashboard uses the default password — change it in Profile settings."
+                }
+                action={{
+                  label: !requireLogin ? "Enable" : "Change password",
+                  href: "/dashboard/profile",
+                }}
+              />
+            )}
+          </div>
+        )}
+
+        {/* Tunnel dashboard access option */}
+        {(tunnelEnabled || tsEnabled) && (
+          <div className="mt-4 pt-4 border-t border-border flex items-center gap-3">
+            <Toggle
+              checked={tunnelDashboardAccess}
+              onChange={() => handleTunnelDashboardAccess(!tunnelDashboardAccess)}
+            />
+            <div className="flex items-center gap-1.5">
+              <p className="font-medium text-sm">Allow dashboard access via tunnel</p>
+              <Tooltip text="When enabled, the dashboard can be accessed through your tunnel or Tailscale URL (login still required). When disabled, dashboard access via tunnel/Tailscale is completely blocked." />
+            </div>
+          </div>
+        )}
+      </Card>
+
+      {/* API Keys */}
+      <Card id="require-api-key">
+        <div className="flex items-center justify-between mb-4">
+          <h2 className="text-lg font-semibold flex items-center gap-2">
+            <span className="material-symbols-outlined text-primary">vpn_key</span>
+            API Keys
+          </h2>
+          <Button icon="add" onClick={() => setShowAddModal(true)}>
+            Create Key
+          </Button>
+        </div>
+
+        <div className="flex items-center justify-between pb-4 mb-4 border-b border-border">
+          <div>
+            <p className="font-medium">Require API key</p>
+            <p className="text-sm text-text-muted">
+              Requests without a valid key will be rejected
+            </p>
+          </div>
+          <Toggle
+            checked={requireApiKey}
+            onChange={() => handleRequireApiKey(!requireApiKey)}
+          />
+        </div>
+
+        {isRemoteHost && !requireApiKey && (
+          <div className="mb-4 -mt-2">
+            <SecurityWarning message="Endpoint is exposed without an API key." />
+          </div>
+        )}
+
+        {keys.length === 0 ? (
+          <div className="text-center py-12">
+            <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-primary/10 text-primary mb-4">
+              <span className="material-symbols-outlined text-[32px]">vpn_key</span>
+            </div>
+            <p className="text-text-main font-medium mb-1">No API keys yet</p>
+            <p className="text-sm text-text-muted mb-4">Create your first API key to get started</p>
+            <Button icon="add" onClick={() => setShowAddModal(true)}>
+              Create Key
+            </Button>
+          </div>
+        ) : (
+          <div className="flex flex-col">
+            {keys.map((key) => (
+              <div
+                key={key.id}
+                className={`group flex items-center justify-between py-3 border-b border-black/[0.03] dark:border-white/[0.03] last:border-b-0 ${key.isActive === false ? "opacity-60" : ""}`}
+              >
+                <div className="flex-1 min-w-0">
+                  <p className="text-sm font-medium">{key.name}</p>
+                  <div className="flex items-center gap-2 mt-1">
+                    <code className="text-xs text-text-muted font-mono">
+                      {visibleKeys.has(key.id) ? key.key : maskKey(key.key)}
+                    </code>
+                    <button
+                      onClick={() => toggleKeyVisibility(key.id)}
+                      className="p-1 hover:bg-black/5 dark:hover:bg-white/5 rounded text-text-muted hover:text-primary opacity-100 sm:opacity-0 sm:group-hover:opacity-100 transition-all"
+                      title={visibleKeys.has(key.id) ? "Hide key" : "Show key"}
+                    >
+                      <span className="material-symbols-outlined text-[14px]">
+                        {visibleKeys.has(key.id) ? "visibility_off" : "visibility"}
+                      </span>
+                    </button>
+                    <button
+                      onClick={() => copy(key.key, key.id)}
+                      className="p-1 hover:bg-black/5 dark:hover:bg-white/5 rounded text-text-muted hover:text-primary opacity-100 sm:opacity-0 sm:group-hover:opacity-100 transition-all"
+                    >
+                      <span className="material-symbols-outlined text-[14px]">
+                        {copied === key.id ? "check" : "content_copy"}
+                      </span>
+                    </button>
+                  </div>
+                  <p className="text-xs text-text-muted mt-1">
+                    Created {new Date(key.createdAt).toLocaleDateString()}
+                  </p>
+                  {key.isActive === false && (
+                    <p className="text-xs text-orange-500 mt-1">Paused</p>
+                  )}
+                </div>
+                <div className="flex items-center gap-2">
+                  <Toggle
+                    size="sm"
+                    checked={key.isActive ?? true}
+                    onChange={(checked) => {
+                      if (key.isActive && !checked) {
+                        setConfirmState({
+                          title: "Pause API Key",
+                          message: `Pause API key "${key.name}"?\n\nThis key will stop working immediately but can be resumed later.`,
+                          onConfirm: async () => {
+                            setConfirmState(null);
+                            handleToggleKey(key.id, checked);
+                          }
+                        });
+                      } else {
+                        handleToggleKey(key.id, checked);
+                      }
+                    }}
+                    title={key.isActive ? "Pause key" : "Resume key"}
+                  />
+                  <button
+                    onClick={() => handleDeleteKey(key.id)}
+                    className="p-2 hover:bg-red-500/10 rounded text-red-500 opacity-100 sm:opacity-0 sm:group-hover:opacity-100 transition-all"
+                  >
+                    <span className="material-symbols-outlined text-[18px]">delete</span>
+                  </button>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </Card>
+
+      {/* Add Key Modal */}
+      <Modal
+        isOpen={showAddModal}
+        title="Create API Key"
+        onClose={() => {
+          setShowAddModal(false);
+          setNewKeyName("");
+        }}
+      >
+        <div className="flex flex-col gap-4">
+          <Input
+            label="Key Name"
+            value={newKeyName}
+            onChange={(e) => setNewKeyName(e.target.value)}
+            placeholder="Production Key"
+          />
+          <div className="flex gap-2">
+            <Button onClick={handleCreateKey} fullWidth disabled={!newKeyName.trim()}>
+              Create
+            </Button>
+            <Button
+              onClick={() => {
+                setShowAddModal(false);
+                setNewKeyName("");
+              }}
+              variant="ghost"
+              fullWidth
+            >
+              Cancel
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      {/* Created Key Modal */}
+      <Modal
+        isOpen={!!createdKey}
+        title="API Key Created"
+        onClose={() => setCreatedKey(null)}
+      >
+        <div className="flex flex-col gap-4">
+          <div className="bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg p-4">
+            <p className="text-sm text-yellow-800 dark:text-yellow-200 mb-2 font-medium">
+              Save this key now!
+            </p>
+            <p className="text-sm text-yellow-700 dark:text-yellow-300">
+              This is the only time you will see this key. Store it securely.
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Input
+              value={createdKey || ""}
+              readOnly
+              className="flex-1 font-mono text-sm"
+            />
+            <Button
+              variant="secondary"
+              icon={copied === "created_key" ? "check" : "content_copy"}
+              onClick={() => copy(createdKey, "created_key")}
+            >
+              {copied === "created_key" ? "Copied!" : "Copy"}
+            </Button>
+          </div>
+          <Button onClick={() => setCreatedKey(null)} fullWidth>
+            Done
+          </Button>
+        </div>
+      </Modal>
+
+      {/* Enable Tunnel Modal */}
+      <Modal
+        isOpen={showEnableTunnelModal}
+        title="Enable Tunnel"
+        onClose={() => setShowEnableTunnelModal(false)}
+      >
+        <div className="flex flex-col gap-4">
+          <div className="bg-surface-2 border border-border-subtle rounded-lg p-4">
+            <div className="flex items-start gap-3">
+              <span className="material-symbols-outlined text-primary">cloud_upload</span>
+              <div>
+                <p className="text-sm text-text-main font-medium mb-1">
+                  Cloudflare Tunnel
+                </p>
+                <p className="text-sm text-text-muted">
+                  Expose your local 9Router to the internet. No port forwarding, no static IP needed. Share endpoint URL with your team or use it in Cursor, Cline, and other AI tools from anywhere.
+                </p>
+              </div>
+            </div>
+          </div>
+
+          <div className="grid grid-cols-2 gap-3">
+            {TUNNEL_BENEFITS.map((benefit) => (
+              <div key={benefit.title} className="flex flex-col items-center text-center p-3 rounded-lg bg-sidebar/50">
+                <span className="material-symbols-outlined text-xl text-primary mb-1">{benefit.icon}</span>
+                <p className="text-xs font-semibold">{benefit.title}</p>
+                <p className="text-xs text-text-muted">{benefit.desc}</p>
+              </div>
+            ))}
+          </div>
+
+          <p className="text-xs text-text-muted">
+            Requires outbound port 7844 (TCP/UDP). Connection may take 10-30s.
+          </p>
+
+          <div className="flex gap-2">
+            <Button onClick={handleEnableTunnel} fullWidth>
+              Start Tunnel
+            </Button>
+            <Button onClick={() => setShowEnableTunnelModal(false)} variant="ghost" fullWidth>Cancel</Button>
+          </div>
+        </div>
+      </Modal>
+
+      {/* Disable Cloudflare Tunnel Modal */}
+      <Modal
+        isOpen={showDisableTunnelModal}
+        title="Disable Tunnel"
+        onClose={() => !tunnelLoading && setShowDisableTunnelModal(false)}
+      >
+        <div className="flex flex-col gap-4">
+          <p className="text-sm text-text-muted">The Cloudflare tunnel will be disconnected. Remote access via tunnel URL will stop working.</p>
+          <div className="flex gap-2">
+            <Button onClick={handleDisableTunnel} fullWidth disabled={tunnelLoading} variant="danger">
+              {tunnelLoading ? "Disabling..." : "Disable"}
+            </Button>
+            <Button onClick={() => setShowDisableTunnelModal(false)} variant="ghost" fullWidth disabled={tunnelLoading}>Cancel</Button>
+          </div>
+        </div>
+      </Modal>
+
+      {/* Tailscale Modal */}
+      <Modal
+        isOpen={showTsModal}
+        title="Tailscale Funnel"
+        onClose={() => { if (!tsInstalling) { setShowTsModal(false); setTsSudoPassword(""); setTsStatus(null); } }}
+      >
+        <div className="flex flex-col gap-4">
+          {/* Checking state */}
+          {tsInstalled === null && (
+            <p className="text-sm text-text-muted flex items-center gap-2">
+              <span className="material-symbols-outlined animate-spin text-sm">progress_activity</span>
+              Checking...
+            </p>
+          )}
+
+          {/* Not installed */}
+          {tsInstalled === false && !tsInstalling && (
+            <div className="flex flex-col gap-3">
+              <p className="text-sm text-text-muted">Tailscale is not installed. Install it to enable Funnel.</p>
+              <div className="flex gap-2">
+                <Button onClick={handleInstallTailscale} fullWidth>
+                  Install Tailscale
+                </Button>
+                <Button onClick={() => setShowTsModal(false)} variant="ghost" fullWidth>Cancel</Button>
+              </div>
+            </div>
+          )}
+
+          {/* Installing with progress log */}
+          {tsInstalling && (
+            <div className="flex flex-col gap-2">
+              <div className="flex items-center gap-2 text-sm text-text-muted">
+                <span className="material-symbols-outlined animate-spin text-sm">progress_activity</span>
+                Installing Tailscale...
+              </div>
+              {tsInstallLog.length > 0 && (
+                <div ref={tsLogRef} className="bg-black/5 dark:bg-white/5 rounded p-2 max-h-40 overflow-y-auto font-mono text-xs text-text-muted">
+                  {tsInstallLog.map((line, i) => (
+                    <div key={i}>{line}</div>
+                  ))}
+                </div>
+              )}
+            </div>
+          )}
+
+          {/* Installed: show Connect button */}
+          {tsInstalled === true && !tsInstalling && (
+            <div className="flex flex-col gap-3">
+              <div className="flex items-center gap-2 text-sm text-green-600 dark:text-green-400">
+                <span className="material-symbols-outlined text-[16px]">check_circle</span>
+                Tailscale installed
+              </div>
+              <div className="flex gap-2">
+                <Button
+                  onClick={() => handleConnectTailscale()}
+                  fullWidth
+                >
+                  Connect
+                </Button>
+                <Button onClick={() => setShowTsModal(false)} variant="ghost" fullWidth>Cancel</Button>
+              </div>
+            </div>
+          )}
+
+          {tsStatus && <StatusAlert status={tsStatus} />}
+        </div>
+      </Modal>
+
+      {/* Disable Tailscale Modal */}
+      <Modal
+        isOpen={showDisableTsModal}
+        title="Disable Tailscale"
+        onClose={() => !tsLoading && setShowDisableTsModal(false)}
+      >
+        <div className="flex flex-col gap-4">
+          <p className="text-sm text-text-muted">Tailscale Funnel will be stopped. Remote access via Tailscale URL will stop working.</p>
+          <div className="flex gap-2">
+            <Button onClick={handleDisableTailscale} fullWidth disabled={tsLoading} variant="danger">
+              {tsLoading ? "Disabling..." : "Disable"}
+            </Button>
+            <Button onClick={() => setShowDisableTsModal(false)} variant="ghost" fullWidth disabled={tsLoading}>Cancel</Button>
+          </div>
+        </div>
+      </Modal>
+
+      {/* Confirm Modal */}
+      <ConfirmModal
+        isOpen={!!confirmState}
+        onClose={() => setConfirmState(null)}
+        onConfirm={confirmState?.onConfirm}
+        title={confirmState?.title || "Confirm"}
+        message={confirmState?.message}
+        variant="danger"
+      />
+    </div>
+  );
+}
+
+
+APIPageClient.propTypes = {
+  machineId: PropTypes.string.isRequired,
+};
diff --git a/src/app/(dashboard)/dashboard/endpoint/components/EndpointRow.js b/src/app/(dashboard)/dashboard/endpoint/components/EndpointRow.js
new file mode 100644
index 0000000..29d3d65
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/endpoint/components/EndpointRow.js
@@ -0,0 +1,22 @@
+"use client";
+
+import { Input } from "@/shared/components";
+
+/** Reusable endpoint row component */
+export default function EndpointRow({ label, url, copyId, copied, onCopy, badge, actions }) {
+  return (
+    <div className="flex items-center gap-2">
+      <span className={`text-xs font-mono px-1.5 py-0.5 rounded shrink-0 min-w-[88px] text-center ${
+          (badge === "CF" || badge === "TS") ? "bg-primary/10 text-primary" : "bg-surface-2 text-text-muted"
+        }`}>{label}</span>
+      <Input value={url} readOnly className="flex-1 font-mono text-sm" />
+      <button
+        onClick={() => onCopy(url, copyId)}
+        className="p-2 hover:bg-black/5 dark:hover:bg-white/5 rounded text-text-muted hover:text-primary transition-colors shrink-0"
+      >
+        <span className="material-symbols-outlined text-[18px]">{copied === copyId ? "check" : "content_copy"}</span>
+      </button>
+      {actions}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/endpoint/components/SecurityWarning.js b/src/app/(dashboard)/dashboard/endpoint/components/SecurityWarning.js
new file mode 100644
index 0000000..8756503
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/endpoint/components/SecurityWarning.js
@@ -0,0 +1,23 @@
+"use client";
+
+/** Security warning banner with optional action link */
+export default function SecurityWarning({ message, action }) {
+  return (
+    <div className="flex items-center gap-2 px-3 py-2 rounded-lg bg-amber-500/10 border border-amber-500/20 text-amber-700 dark:text-amber-400">
+      <span className="material-symbols-outlined text-[16px] shrink-0 mt-0.5">warning</span>
+      <p className="text-xs flex-1">{message}</p>
+      {action && (
+        <a
+          href={action.href}
+          className="text-xs font-medium underline shrink-0 hover:opacity-80"
+          onClick={action.href.startsWith("#") ? (e) => {
+            e.preventDefault();
+            document.getElementById(action.href.slice(1))?.scrollIntoView({ behavior: "smooth" });
+          } : undefined}
+        >
+          {action.label}
+        </a>
+      )}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/endpoint/components/StatusAlert.js b/src/app/(dashboard)/dashboard/endpoint/components/StatusAlert.js
new file mode 100644
index 0000000..c0609ab
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/endpoint/components/StatusAlert.js
@@ -0,0 +1,23 @@
+"use client";
+
+/** Reusable status alert */
+export default function StatusAlert({ status, className = "" }) {
+  const renderMessage = (msg) => {
+    const parts = msg.split(/(https?:\/\/[^\s]+)/g);
+    return parts.map((part, i) =>
+      /^https?:\/\//.test(part)
+        ? <a key={i} href={part} target="_blank" rel="noreferrer" className="underline font-medium">{part}</a>
+        : part
+    );
+  };
+
+  return (
+    <div className={`p-2 rounded text-sm ${className} ${status.type === "success" ? "bg-green-500/10 text-green-600 dark:text-green-400" :
+        status.type === "warning" ? "bg-yellow-500/10 text-yellow-600 dark:text-yellow-400" :
+        status.type === "info" ? "bg-blue-500/10 text-blue-600 dark:text-blue-400" :
+          "bg-red-500/10 text-red-600 dark:text-red-400"
+      }`}>
+      {renderMessage(status.message)}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/endpoint/components/Tooltip.js b/src/app/(dashboard)/dashboard/endpoint/components/Tooltip.js
new file mode 100644
index 0000000..c9726ea
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/endpoint/components/Tooltip.js
@@ -0,0 +1,13 @@
+"use client";
+
+/** Inline tooltip, Claude Code CLI style */
+export default function Tooltip({ text }) {
+  return (
+    <span className="relative group inline-flex items-center">
+      <span className="material-symbols-outlined text-[14px] text-text-muted cursor-help">help</span>
+      <span className="pointer-events-none absolute left-5 top-1/2 -translate-y-1/2 z-50 w-64 rounded bg-gray-900 dark:bg-gray-800 text-white text-xs px-2.5 py-1.5 opacity-0 group-hover:opacity-100 transition-opacity shadow-lg">
+        {text}
+      </span>
+    </span>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/endpoint/endpointConstants.js b/src/app/(dashboard)/dashboard/endpoint/endpointConstants.js
new file mode 100644
index 0000000..ac10b76
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/endpoint/endpointConstants.js
@@ -0,0 +1,32 @@
+export const WENYAN_LOCALES = ["zh-CN", "zh-TW"];
+
+export const TUNNEL_BENEFITS = [
+  { icon: "public", title: "Access Anywhere", desc: "Use your API from any network" },
+  { icon: "group", title: "Share Endpoint", desc: "Share URL with team members" },
+  { icon: "code", title: "Use in Cursor/Cline", desc: "Connect AI tools remotely" },
+  { icon: "lock", title: "Encrypted", desc: "End-to-end TLS via Cloudflare" },
+];
+
+export const TUNNEL_PING_INTERVAL_MS = 2000;
+export const TUNNEL_PING_MAX_MS = 300000;
+export const STATUS_POLL_FAST_MS = 5000;
+export const STATUS_POLL_SLOW_MS = 30000;
+export const REACHABLE_MISS_THRESHOLD = 5;
+export const CLIENT_PING_FAST_MS = 10000;
+export const CLIENT_PING_SLOW_MS = 60000;
+export const CLIENT_PING_TIMEOUT_MS = 5000;
+
+export const CAVEMAN_LEVELS = [
+  { id: "lite", label: "Lite", desc: "Drop filler, keep grammar" },
+  { id: "full", label: "Full", desc: "Drop articles, fragments OK" },
+  { id: "ultra", label: "Ultra", desc: "Telegraphic, max compression" },
+  { id: "wenyan-lite", label: "文 Lite", desc: "Classical Chinese, light compression", wenyan: true },
+  { id: "wenyan", label: "文 Full", desc: "Maximum 文言文, 80-90% reduction", wenyan: true },
+  { id: "wenyan-ultra", label: "文 Ultra", desc: "Extreme classical compression", wenyan: true },
+];
+
+export const PONYTAIL_LEVELS = [
+  { id: "lite", label: "Lite", desc: "Build asked, name lazier option" },
+  { id: "full", label: "Full", desc: "Ladder enforced: stdlib/native first" },
+  { id: "ultra", label: "Ultra", desc: "YAGNI extremist, deletion first" },
+];
diff --git a/src/app/(dashboard)/dashboard/endpoint/endpointPing.js b/src/app/(dashboard)/dashboard/endpoint/endpointPing.js
new file mode 100644
index 0000000..5c522cd
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/endpoint/endpointPing.js
@@ -0,0 +1,29 @@
+import { CLIENT_PING_TIMEOUT_MS } from "./endpointConstants";
+
+// Browser-side health probe: must reach origin (not just CF/TS edge).
+// cors mode → res.ok=false for 5xx (e.g. Cloudflare 530 when origin dead).
+// /api/health route sets Access-Control-Allow-Origin: * → CORS works through tunnel.
+export async function clientPingUrl(url) {
+  if (!url) return false;
+  try {
+    const res = await fetch(`${url}/api/health`, {
+      mode: "cors",
+      cache: "no-store",
+      signal: AbortSignal.timeout(CLIENT_PING_TIMEOUT_MS),
+    });
+    return res.ok;
+  } catch { return false; }
+}
+
+// Race multiple URLs: resolve true as soon as any one passes ping.
+export async function clientPingAny(...urls) {
+  const checks = urls.filter(Boolean).map(clientPingUrl);
+  if (!checks.length) return false;
+  return new Promise((resolve) => {
+    let pending = checks.length;
+    checks.forEach((p) => p.then((ok) => {
+      if (ok) resolve(true);
+      else if (--pending === 0) resolve(false);
+    }));
+  });
+}
diff --git a/src/app/(dashboard)/dashboard/endpoint/page.js b/src/app/(dashboard)/dashboard/endpoint/page.js
new file mode 100644
index 0000000..96a3e31
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/endpoint/page.js
@@ -0,0 +1,7 @@
+import { getMachineId } from "@/shared/utils/machine";
+import EndpointPageClient from "./EndpointPageClient";
+
+export default async function EndpointPage() {
+  const machineId = await getMachineId();
+  return <EndpointPageClient machineId={machineId} />;
+}
diff --git a/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/EmbeddingExampleCard.js b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/EmbeddingExampleCard.js
new file mode 100644
index 0000000..5580d75
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/EmbeddingExampleCard.js
@@ -0,0 +1,254 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card } from "@/shared/components";
+import { getProviderAlias, isCustomEmbeddingProvider } from "@/shared/constants/providers";
+import { getModelsByProviderId, getModelKind } from "@/shared/constants/models";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import { Row } from "./exampleShared";
+
+const DEFAULT_RESPONSE_EXAMPLE = `{
+  "object": "list",
+  "data": [{
+    "object": "embedding",
+    "index": 0,
+    "embedding": [0.002301, -0.019212, 0.004815, -0.031249, ...]
+  }],
+  "model": "...",
+  "usage": { "prompt_tokens": 9, "total_tokens": 9 }
+}`;
+
+export function EmbeddingExampleCard({ providerId, customAlias }) {
+  const isCustom = isCustomEmbeddingProvider(providerId);
+  const providerAlias = isCustom ? (customAlias || providerId) : getProviderAlias(providerId);
+  const embeddingModels = isCustom ? [] : getModelsByProviderId(providerId).filter((m) => getModelKind(m) === "embedding");
+
+  const [selectedModel, setSelectedModel] = useState(embeddingModels[0]?.id ?? "");
+  const [input, setInput] = useState("The quick brown fox jumps over the lazy dog");
+  const [dimensions, setDimensions] = useState("");
+  const [apiKey, setApiKey] = useState("");
+  const [useTunnel, setUseTunnel] = useState(false);
+  const [localEndpoint, setLocalEndpoint] = useState("");
+  const [tunnelEndpoint, setTunnelEndpoint] = useState("");
+  const [result, setResult] = useState(null);
+  const [running, setRunning] = useState(false);
+  const [error, setError] = useState("");
+  const { copied: copiedCurl, copy: copyCurl } = useCopyToClipboard();
+  const { copied: copiedRes, copy: copyRes } = useCopyToClipboard();
+
+  useEffect(() => {
+    setLocalEndpoint(window.location.origin);
+    fetch("/api/keys")
+      .then((r) => r.json())
+      .then((d) => { setApiKey((d.keys || []).find((k) => k.isActive !== false)?.key || ""); })
+      .catch(() => {});
+    fetch("/api/tunnel/status")
+      .then((r) => r.json())
+      .then((d) => { if (d.publicUrl) setTunnelEndpoint(d.publicUrl); })
+      .catch(() => {});
+  }, []);
+
+  const endpoint = useTunnel ? tunnelEndpoint : localEndpoint;
+  const modelFull = selectedModel ? `${providerAlias}/${selectedModel}` : "";
+
+  // Build request body — include dimensions only if user provided a positive number
+  const buildBody = () => {
+    const body = { model: modelFull, input: input.trim() };
+    const dim = Number(dimensions);
+    if (dimensions && Number.isFinite(dim) && dim > 0) body.dimensions = dim;
+    return body;
+  };
+
+  const curlSnippet = `curl -X POST ${endpoint}/v1/embeddings \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer ${apiKey || "YOUR_KEY"}" \\
+  -d '${JSON.stringify(buildBody())}'`;
+
+  const handleRun = async () => {
+    if (!input.trim() || !modelFull) return;
+    setRunning(true);
+    setError("");
+    setResult(null);
+    const start = Date.now();
+    try {
+      const headers = { "Content-Type": "application/json" };
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+      const res = await fetch("/api/v1/embeddings", {
+        method: "POST",
+        headers,
+        body: JSON.stringify(buildBody()),
+      });
+      const latencyMs = Date.now() - start;
+      const data = await res.json();
+      if (!res.ok) { setError(data?.error?.message || data?.error || `HTTP ${res.status}`); return; }
+      setResult({ data, latencyMs });
+    } catch (e) {
+      setError(e.message || "Network error");
+    } finally {
+      setRunning(false);
+    }
+  };
+
+  // Compact embedding array: first 4 values + count
+  const formatResultJson = (data) => {
+    if (!data) return DEFAULT_RESPONSE_EXAMPLE;
+    const clone = JSON.parse(JSON.stringify(data));
+    (clone.data || []).forEach((item) => {
+      if (Array.isArray(item.embedding) && item.embedding.length > 4) {
+        item.embedding = [...item.embedding.slice(0, 4).map((v) => parseFloat(v.toFixed(6))), `... (${item.embedding.length} dims)`];
+      }
+    });
+    return JSON.stringify(clone, null, 2);
+  };
+
+  const resultJson = result ? JSON.stringify(result.data, null, 2) : "";
+
+  return (
+    <Card>
+      <h2 className="text-lg font-semibold mb-4">Example</h2>
+
+      <div className="flex flex-col gap-2.5">
+        {/* Model — text input for custom node, dropdown otherwise */}
+        <Row label="Model">
+          {isCustom ? (
+            <input
+              value={selectedModel}
+              onChange={(e) => setSelectedModel(e.target.value)}
+              placeholder="e.g. voyage-3, embed-english-v3.0, text-embedding-3-small"
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary font-mono"
+            />
+          ) : (
+            <select
+              value={selectedModel}
+              onChange={(e) => setSelectedModel(e.target.value)}
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            >
+              {embeddingModels.map((m) => (
+                <option key={m.id} value={m.id}>{m.name || m.id}</option>
+              ))}
+            </select>
+          )}
+        </Row>
+
+        {/* Endpoint */}
+        <Row label="Endpoint">
+          <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+            <input
+              value={endpoint}
+              onChange={(e) => useTunnel ? setTunnelEndpoint(e.target.value) : setLocalEndpoint(e.target.value)}
+              className="w-full min-w-0 flex-1 px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary font-mono"
+              placeholder="http://localhost:3000"
+            />
+            {/* Tunnel toggle — only show if tunnel URL is available */}
+            {tunnelEndpoint && (
+              <button
+                onClick={() => setUseTunnel((v) => !v)}
+                title={useTunnel ? "Using tunnel" : "Using local"}
+                className={`flex items-center gap-1 text-xs px-2 py-1.5 rounded-lg border shrink-0 transition-colors ${
+                  useTunnel ? "border-primary/40 bg-primary/10 text-primary" : "border-border text-text-muted hover:text-primary"
+                }`}
+              >
+                <span className="material-symbols-outlined text-[14px]">wifi_tethering</span>
+                Tunnel
+              </button>
+            )}
+          </div>
+        </Row>
+
+        {/* API Key */}
+        <Row label="API Key">
+          <input
+            type="password"
+            value={apiKey}
+            onChange={(e) => setApiKey(e.target.value)}
+            placeholder="sk-..."
+            className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary font-mono"
+          />
+        </Row>
+
+        {/* Input */}
+        <Row label="Input">
+          <div className="relative">
+            <input
+              value={input}
+              onChange={(e) => setInput(e.target.value)}
+              className="w-full px-3 py-1.5 pr-7 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            />
+            {input && (
+              <button
+                type="button"
+                onClick={() => setInput("")}
+                className="absolute right-2 top-1/2 -translate-y-1/2 text-text-muted hover:text-primary transition-colors"
+              >
+                <span className="material-symbols-outlined text-[14px]">close</span>
+              </button>
+            )}
+          </div>
+        </Row>
+
+        {/* Dimensions (optional) — truncate embedding vector length */}
+        <Row label="Dimensions">
+          <input
+            type="number"
+            min="1"
+            value={dimensions}
+            onChange={(e) => setDimensions(e.target.value)}
+            placeholder="optional, e.g. 512, 1024 (leave empty for default)"
+            className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+          />
+        </Row>
+
+        {/* Curl + Run */}
+        <div className="mt-1">
+          <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between mb-1.5">
+            <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">Request</span>
+            <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+              <button
+                onClick={() => copyCurl(curlSnippet)}
+                className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors"
+              >
+                <span className="material-symbols-outlined text-[14px]">{copiedCurl ? "check" : "content_copy"}</span>
+                {copiedCurl ? "Copied" : "Copy"}
+              </button>
+              <button
+                onClick={handleRun}
+                disabled={running || !input.trim() || !modelFull}
+                className="flex w-full sm:w-auto items-center justify-center gap-1.5 px-3 py-1 rounded-lg bg-primary text-white text-xs font-medium hover:bg-primary/90 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+              >
+                <span className="material-symbols-outlined text-[14px]" style={running ? { animation: "spin 1s linear infinite" } : undefined}>
+                  play_arrow
+                </span>
+                {running ? "Running..." : "Run"}
+              </button>
+            </div>
+          </div>
+          <pre className="bg-sidebar rounded-lg px-3 py-2.5 text-xs font-mono text-text-main overflow-x-auto whitespace-pre-wrap break-all">{curlSnippet}</pre>
+        </div>
+
+        {/* Error */}
+        {error && <p className="text-xs text-red-500 break-words">{error}</p>}
+
+        {/* Response — default example or real result */}
+        <div>
+          <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between mb-1.5">
+            <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">
+              Response {result && <span className="font-normal normal-case">&#9889; {result.latencyMs}ms</span>}
+            </span>
+            {result && (
+              <button
+                onClick={() => copyRes(resultJson)}
+                className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors"
+              >
+                <span className="material-symbols-outlined text-[14px]">{copiedRes ? "check" : "content_copy"}</span>
+                {copiedRes ? "Copied" : "Copy"}
+              </button>
+            )}
+          </div>
+          <pre className="bg-sidebar rounded-lg px-3 py-2.5 text-xs font-mono text-text-main overflow-x-auto whitespace-pre-wrap break-all opacity-70">
+            {formatResultJson(result?.data)}
+          </pre>
+        </div>
+      </div>
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/GenericExampleCard.js b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/GenericExampleCard.js
new file mode 100644
index 0000000..815528d
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/GenericExampleCard.js
@@ -0,0 +1,539 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card } from "@/shared/components";
+import { MEDIA_PROVIDER_KINDS, getProviderAlias, resolveProviderId } from "@/shared/constants/providers";
+import { getModelsByProviderId, getModelKind } from "@/shared/constants/models";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import { Row, KIND_EXAMPLE_CONFIG } from "./exampleShared";
+
+const CLOUDFLARE_TEST_IMAGE_URL = "https://pub-1fb693cb11cc46b2b2f656f51e015a2c.r2.dev/dog.png";
+const CLOUDFLARE_TEST_MASK_URL = "https://pub-1fb693cb11cc46b2b2f656f51e015a2c.r2.dev/dog-mask.png";
+
+function getImageEditDefaults(providerId, modelId) {
+  if (providerId !== "cloudflare-ai") return {};
+  if (modelId === "@cf/runwayml/stable-diffusion-v1-5-img2img") {
+    return { image: CLOUDFLARE_TEST_IMAGE_URL };
+  }
+  if (modelId === "@cf/runwayml/stable-diffusion-v1-5-inpainting") {
+    return { image: CLOUDFLARE_TEST_IMAGE_URL, mask_image: CLOUDFLARE_TEST_MASK_URL };
+  }
+  return {};
+}
+
+function toImagePreviewSrc(value) {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  if (!trimmed) return "";
+  if (/^(data:image\/|https?:\/\/)/i.test(trimmed)) return trimmed;
+  return `data:image/png;base64,${trimmed}`;
+}
+
+export function GenericExampleCard({ providerId, kind }) {
+  const providerAlias = getProviderAlias(providerId);
+  const resolvedId = resolveProviderId(providerAlias);
+  const safeProviderAlias = resolvedId === providerId ? providerAlias : providerId;
+  const kindConfig = MEDIA_PROVIDER_KINDS.find((k) => k.id === kind);
+  const exConfig = KIND_EXAMPLE_CONFIG[kind];
+  const safeExConfig = exConfig || {};
+
+  // Get models for this kind (e.g., type="image")
+  const kindModels = getModelsByProviderId(providerId).filter((m) => getModelKind(m) === kind);
+  // Kinds that need a model identifier in the request (image/video/music)
+  const KIND_NEEDS_MODEL = new Set(["image", "video", "music", "imageToText"]);
+  const needsModel = KIND_NEEDS_MODEL.has(kind);
+  const allowManualModel = needsModel && kindModels.length === 0;
+  const [selectedModel, setSelectedModel] = useState(kindModels[0]?.id ?? "");
+  const selectedModelObj = kindModels.find((m) => m.id === selectedModel);
+  const supportsEdit = !!selectedModelObj?.capabilities?.includes("edit");
+  const supportsMask = !!selectedModelObj?.capabilities?.includes("mask");
+
+  const [input, setInput] = useState(safeExConfig.defaultInput || "");
+  const [refImage, setRefImage] = useState("");
+  const [maskImage, setMaskImage] = useState("");
+  const [extraValues, setExtraValues] = useState(() =>
+    (safeExConfig.extraFields || []).reduce((acc, f) => { acc[f.key] = f.default ?? ""; return acc; }, {})
+  );
+  const [apiKey, setApiKey] = useState("");
+  const [useTunnel, setUseTunnel] = useState(false);
+  const [localEndpoint, setLocalEndpoint] = useState("");
+  const [tunnelEndpoint, setTunnelEndpoint] = useState("");
+  const [result, setResult] = useState(null);
+  const [progress, setProgress] = useState(null); // { stage, bytesReceived }
+  const [partialImage, setPartialImage] = useState(null);
+  const [imageOutputFormat, setImageOutputFormat] = useState("json"); // json | binary
+  const [binaryImageUrl, setBinaryImageUrl] = useState("");
+  const [running, setRunning] = useState(false);
+  const [error, setError] = useState("");
+  const [connections, setConnections] = useState([]);
+  const [pinnedConnectionId, setPinnedConnectionId] = useState("");
+  const { copied: copiedCurl, copy: copyCurl } = useCopyToClipboard();
+  const { copied: copiedRes, copy: copyRes } = useCopyToClipboard();
+
+  useEffect(() => {
+    setLocalEndpoint(window.location.origin);
+    fetch("/api/keys")
+      .then((r) => r.json())
+      .then((d) => { setApiKey((d.keys || []).find((k) => k.isActive !== false)?.key || ""); })
+      .catch(() => {});
+    fetch("/api/tunnel/status")
+      .then((r) => r.json())
+      .then((d) => { if (d.publicUrl) setTunnelEndpoint(d.publicUrl); })
+      .catch(() => {});
+    // Load active connections of this provider for pinning
+    fetch("/api/providers/client")
+      .then((r) => r.json())
+      .then((d) => {
+        const conns = (d.connections || []).filter((c) => c.provider === providerId && c.isActive !== false);
+        setConnections(conns);
+      })
+      .catch(() => {});
+  }, [providerId]);
+
+  // Safe to early-return now that all hooks are declared
+  if (!kindConfig || !exConfig) return null;
+
+  const endpoint = useTunnel ? tunnelEndpoint : localEndpoint;
+  const apiPath = kindConfig.endpoint.path;
+  // webSearch/webFetch: use safeProviderAlias only. Other kinds: append model when present.
+  const modelFull = !needsModel
+    ? safeProviderAlias
+    : (selectedModel ? `${safeProviderAlias}/${selectedModel}` : (allowManualModel ? "" : safeProviderAlias));
+  const imageEditDefaults = getImageEditDefaults(providerId, selectedModel);
+  const effectiveRefImage = refImage.trim() || imageEditDefaults.image || "";
+  const effectiveMaskImage = maskImage.trim() || imageEditDefaults.mask_image || "";
+  const refImagePreviewSrc = toImagePreviewSrc(effectiveRefImage);
+  const maskImagePreviewSrc = toImagePreviewSrc(effectiveMaskImage);
+
+  // Build request body with optional extra fields (only non-empty values)
+  const extraBodyFromFields = Object.entries(extraValues).reduce((acc, [k, v]) => {
+    if (v === "" || v === null || v === undefined) return acc;
+    if (typeof v === "number" && Number.isNaN(v)) return acc;
+    acc[k] = v;
+    return acc;
+  }, {});
+  const requestBody = {
+    model: modelFull,
+    [exConfig.bodyKey]: input,
+    ...exConfig.extraBody,
+    ...extraBodyFromFields,
+    ...(supportsEdit && effectiveRefImage ? { image: effectiveRefImage } : {}),
+    ...(supportsMask && effectiveMaskImage ? { mask_image: effectiveMaskImage } : {}),
+  };
+
+  // Streaming supported for codex image (Plus/Pro accounts) — disabled when binary output requested
+  const wantBinary = kind === "image" && imageOutputFormat === "binary";
+  const useStreaming = kind === "image" && providerId === "codex" && !wantBinary;
+  const apiPathWithQuery = `${apiPath}${wantBinary ? "?response_format=binary" : ""}`;
+  const headersPreview = `-H "Content-Type: application/json" \\\n  -H "Authorization: Bearer ${apiKey || "YOUR_KEY"}"${pinnedConnectionId ? ` \\\n  -H "x-connection-id: ${pinnedConnectionId}"` : ""}${useStreaming ? ` \\\n  -H "Accept: text/event-stream"` : ""}`;
+  const curlSnippet = `curl -X ${kindConfig.endpoint.method} ${endpoint}${apiPathWithQuery} \\
+  ${headersPreview.replace(/\\\n  /g, "\\\n  ")} \\
+  -d '${JSON.stringify(requestBody)}'${wantBinary ? " \\\n  --output image.png" : ""}`;
+
+  const handleRun = async () => {
+    if (!input.trim() || !modelFull) return;
+    setRunning(true);
+    setError("");
+    setResult(null);
+    setProgress(null);
+    setPartialImage(null);
+    if (binaryImageUrl) { try { URL.revokeObjectURL(binaryImageUrl); } catch {} setBinaryImageUrl(""); }
+    const start = Date.now();
+    try {
+      const headers = { "Content-Type": "application/json" };
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+      if (pinnedConnectionId) headers["x-connection-id"] = pinnedConnectionId;
+      if (useStreaming) headers["Accept"] = "text/event-stream";
+      const body = { ...requestBody, model: modelFull };
+      const res = await fetch(`/api${apiPathWithQuery}`, {
+        method: kindConfig.endpoint.method,
+        headers,
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        setError(data?.error?.message || data?.error || `HTTP ${res.status}`);
+        return;
+      }
+      const ctype = res.headers.get("content-type") || "";
+      // Binary image response — convert to blob URL
+      if (ctype.startsWith("image/")) {
+        const blob = await res.blob();
+        const objUrl = URL.createObjectURL(blob);
+        setBinaryImageUrl(objUrl);
+        setResult({ data: { binary: true, mime: ctype, size: blob.size }, latencyMs: Date.now() - start });
+        return;
+      }
+      const isSse = ctype.includes("text/event-stream");
+      if (isSse && res.body) {
+        // Parse SSE: progress / partial_image / done / error
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        let finalData = null;
+        let streamErr = null;
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buf += decoder.decode(value, { stream: true });
+          let sep;
+          while ((sep = buf.indexOf("\n\n")) !== -1) {
+            const block = buf.slice(0, sep);
+            buf = buf.slice(sep + 2);
+            let evt = null, dataStr = "";
+            for (const line of block.split("\n")) {
+              if (line.startsWith("event:")) evt = line.slice(6).trim();
+              else if (line.startsWith("data:")) dataStr += line.slice(5).trim();
+            }
+            if (!evt) continue;
+            try {
+              const payload = dataStr ? JSON.parse(dataStr) : {};
+              if (evt === "progress") setProgress(payload);
+              else if (evt === "partial_image") setPartialImage(payload);
+              else if (evt === "done") finalData = payload;
+              else if (evt === "error") streamErr = payload?.message || "Stream error";
+            } catch {}
+          }
+        }
+        const latencyMs = Date.now() - start;
+        if (streamErr) { setError(streamErr); return; }
+        if (finalData) setResult({ data: finalData, latencyMs });
+      } else {
+        const data = await res.json();
+        const latencyMs = Date.now() - start;
+        setResult({ data, latencyMs });
+      }
+    } catch (e) {
+      setError(e.message || "Network error");
+    } finally {
+      setRunning(false);
+    }
+  };
+
+  // Mask large b64_json strings in JSON view to keep it readable
+  const maskB64 = (obj) => {
+    if (!obj || typeof obj !== "object") return obj;
+    if (Array.isArray(obj)) return obj.map(maskB64);
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+      out[k] = (k === "b64_json" && typeof v === "string" && v.length > 100)
+        ? `<${v.length} chars base64>`
+        : maskB64(v);
+    }
+    return out;
+  };
+  const resultJson = result ? JSON.stringify(maskB64(result.data), null, 2) : "";
+
+  return (
+    <Card>
+      <h2 className="text-lg font-semibold mb-4">Example</h2>
+      <div className="flex flex-col gap-2.5">
+        {/* Model selector — dropdown if presets exist, else manual input for media kinds */}
+        {kindModels.length > 0 ? (
+          <Row label="Model">
+            <select
+              value={selectedModel}
+              onChange={(e) => setSelectedModel(e.target.value)}
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            >
+              {kindModels.map((m) => (
+                <option key={m.id} value={m.id}>{m.name || m.id}</option>
+              ))}
+            </select>
+          </Row>
+        ) : allowManualModel ? (
+          <Row label="Model">
+            <input
+              value={selectedModel}
+              onChange={(e) => setSelectedModel(e.target.value)}
+              placeholder="Enter model id (provider-specific)"
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary font-mono"
+            />
+          </Row>
+        ) : null}
+
+        {/* Endpoint */}
+        <Row label="Endpoint">
+          <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+            <span className="w-full min-w-0 flex-1 px-3 py-1.5 text-sm font-mono text-text-main bg-sidebar rounded-lg truncate">
+              {endpoint}{apiPath}
+            </span>
+            {tunnelEndpoint && (
+              <button
+                onClick={() => setUseTunnel((v) => !v)}
+                title={useTunnel ? "Using tunnel" : "Using local"}
+                className={`flex items-center gap-1 text-xs px-2 py-1.5 rounded-lg border shrink-0 transition-colors ${
+                  useTunnel ? "border-primary/40 bg-primary/10 text-primary" : "border-border text-text-muted hover:text-primary"
+                }`}
+              >
+                <span className="material-symbols-outlined text-[14px]">wifi_tethering</span>
+                Tunnel
+              </button>
+            )}
+          </div>
+        </Row>
+
+        {/* API Key */}
+        <Row label="API Key">
+          <span className="px-3 py-1.5 text-sm font-mono text-text-main bg-sidebar rounded-lg truncate block">
+            {apiKey ? `${apiKey.slice(0, 8)}${"\u2022".repeat(Math.min(20, apiKey.length - 8))}` : <span className="text-text-muted italic">No key configured</span>}
+          </span>
+        </Row>
+
+        {/* Connection picker - only show when 2+ connections (or any with email) */}
+        {connections.length > 0 && (
+          <Row label="Connection">
+            <select
+              value={pinnedConnectionId}
+              onChange={(e) => setPinnedConnectionId(e.target.value)}
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            >
+              <option value="">Auto (by priority)</option>
+              {connections.map((c) => {
+                const plan = c.providerSpecificData?.chatgptPlanType;
+                const label = c.email || c.name || c.id.slice(0, 8);
+                return (
+                  <option key={c.id} value={c.id}>
+                    {label}{plan ? ` [${plan}]` : ""}
+                  </option>
+                );
+              })}
+            </select>
+          </Row>
+        )}
+
+        {/* Input */}
+        <Row label={exConfig.inputLabel}>
+          <div className="relative">
+            <input
+              value={input}
+              onChange={(e) => setInput(e.target.value)}
+              placeholder={exConfig.inputPlaceholder}
+              className="w-full px-3 py-1.5 pr-7 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            />
+            {input && (
+              <button
+                type="button"
+                onClick={() => setInput("")}
+                className="absolute right-2 top-1/2 -translate-y-1/2 text-text-muted hover:text-primary transition-colors"
+              >
+                <span className="material-symbols-outlined text-[14px]">close</span>
+              </button>
+            )}
+          </div>
+        </Row>
+
+        {/* Reference image (only for edit-capable image models) */}
+        {supportsEdit && (
+          <Row label="Ref Image (URL)">
+            <div className="flex flex-col gap-2">
+              <div className="relative">
+                <input
+                  value={refImage}
+                  onChange={(e) => setRefImage(e.target.value)}
+                  placeholder={imageEditDefaults.image || "https://example.com/source.png"}
+                  className="w-full px-3 py-1.5 pr-7 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+                />
+                {refImage && (
+                  <button
+                    type="button"
+                    onClick={() => setRefImage("")}
+                    className="absolute right-2 top-1/2 -translate-y-1/2 text-text-muted hover:text-primary transition-colors"
+                  >
+                    <span className="material-symbols-outlined text-[14px]">close</span>
+                  </button>
+                )}
+              </div>
+              {refImagePreviewSrc && (
+                <img
+                  src={refImagePreviewSrc}
+                  alt="Reference"
+                  className="max-h-40 rounded-lg border border-border object-contain bg-sidebar"
+                  onError={(e) => { e.currentTarget.style.display = "none"; }}
+                  onLoad={(e) => { e.currentTarget.style.display = "block"; }}
+                />
+              )}
+            </div>
+          </Row>
+        )}
+
+        {supportsMask && (
+          <Row label="Mask (URL)">
+            <div className="flex flex-col gap-2">
+              <div className="relative">
+                <input
+                  value={maskImage}
+                  onChange={(e) => setMaskImage(e.target.value)}
+                  placeholder={imageEditDefaults.mask_image || "https://example.com/mask.png"}
+                  className="w-full px-3 py-1.5 pr-7 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+                />
+                {maskImage && (
+                  <button
+                    type="button"
+                    onClick={() => setMaskImage("")}
+                    className="absolute right-2 top-1/2 -translate-y-1/2 text-text-muted hover:text-primary transition-colors"
+                  >
+                    <span className="material-symbols-outlined text-[14px]">close</span>
+                  </button>
+                )}
+              </div>
+              {maskImagePreviewSrc && (
+                <img
+                  src={maskImagePreviewSrc}
+                  alt="Mask"
+                  className="max-h-40 rounded-lg border border-border object-contain bg-sidebar"
+                  onError={(e) => { e.currentTarget.style.display = "none"; }}
+                  onLoad={(e) => { e.currentTarget.style.display = "block"; }}
+                />
+              )}
+            </div>
+          </Row>
+        )}
+
+        {/* Extra fields — for kinds without model concept (webSearch/webFetch), show all; otherwise filter by model.params */}
+        {(exConfig.extraFields || [])
+          .filter((f) => kindModels.length === 0 || (Array.isArray(selectedModelObj?.params) && selectedModelObj.params.includes(f.key)))
+          .map((f) => (
+          <Row key={f.key} label={f.label}>
+            {f.type === "select" ? (
+              <select
+                value={extraValues[f.key] ?? ""}
+                onChange={(e) => setExtraValues((s) => ({ ...s, [f.key]: e.target.value }))}
+                className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+              >
+                {(f.options || []).map((opt) => (
+                  <option key={opt} value={opt}>{opt === "" ? "(default)" : opt}</option>
+                ))}
+              </select>
+            ) : f.type === "text" ? (
+              <input
+                type="text"
+                value={extraValues[f.key] ?? ""}
+                placeholder={f.placeholder}
+                onChange={(e) => setExtraValues((s) => ({ ...s, [f.key]: e.target.value }))}
+                className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+              />
+            ) : (
+              <input
+                type="number"
+                value={extraValues[f.key] ?? ""}
+                min={f.min}
+                max={f.max}
+                onChange={(e) => setExtraValues((s) => ({ ...s, [f.key]: e.target.value === "" ? "" : Number(e.target.value) }))}
+                className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+              />
+            )}
+          </Row>
+        ))}
+
+        {/* Output Format toggle (image only) — last */}
+        {kind === "image" && (
+          <Row label="Output Format">
+            <select
+              value={imageOutputFormat}
+              onChange={(e) => setImageOutputFormat(e.target.value)}
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            >
+              <option value="json">JSON (Base64)</option>
+              <option value="binary">Binary File</option>
+            </select>
+          </Row>
+        )}
+
+        {/* Curl + Run */}
+        <div className="mt-1">
+          <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between mb-1.5">
+            <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">Request</span>
+            <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+              <button
+                onClick={() => copyCurl(curlSnippet)}
+                className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors"
+              >
+                <span className="material-symbols-outlined text-[14px]">{copiedCurl ? "check" : "content_copy"}</span>
+                {copiedCurl ? "Copied" : "Copy"}
+              </button>
+            <button
+              onClick={handleRun}
+              disabled={running || !input.trim() || !modelFull}
+              className="flex w-full sm:w-auto items-center justify-center gap-1.5 px-3 py-1 rounded-lg bg-primary text-white text-xs font-medium hover:bg-primary/90 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+                <span className="material-symbols-outlined text-[14px]" style={running ? { animation: "spin 1s linear infinite" } : undefined}>
+                  play_arrow
+                </span>
+                {running ? "Running..." : "Run"}
+              </button>
+            </div>
+          </div>
+          <pre className="bg-sidebar rounded-lg px-3 py-2.5 text-xs font-mono text-text-main overflow-x-auto whitespace-pre-wrap break-all">{curlSnippet}</pre>
+        </div>
+
+        {/* Streaming progress */}
+        {(running || progress) && useStreaming && (
+          <div className="flex flex-col gap-2 px-3 py-2 rounded-lg bg-sidebar border border-border sm:flex-row sm:items-center sm:gap-3">
+            <span className="material-symbols-outlined text-[16px] text-primary" style={running ? { animation: "spin 1s linear infinite" } : undefined}>
+              {running ? "progress_activity" : "check_circle"}
+            </span>
+            <span className="text-xs text-text-muted">
+              {progress?.stage || "starting"}
+              {!running && progress?.bytesReceived ? ` · ${(progress.bytesReceived / 1024).toFixed(1)} KB` : ""}
+            </span>
+          </div>
+        )}
+
+        {/* Partial image preview (codex stream) */}
+        {partialImage?.b64_json && !result && (
+          <div>
+            <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">Partial preview</span>
+            <img
+              src={`data:image/png;base64,${partialImage.b64_json}`}
+              alt="Partial"
+              className="max-w-full rounded-lg border border-border mt-1.5 opacity-80"
+            />
+          </div>
+        )}
+
+        {/* Error */}
+        {error && <p className="text-xs text-red-500 break-words">{error}</p>}
+
+        {/* Response */}
+        <div>
+          <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between mb-1.5">
+            <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">
+              Response {result && <span className="font-normal normal-case">&#9889; {result.latencyMs}ms</span>}
+            </span>
+            {result && (
+              <button
+                onClick={() => copyRes(resultJson)}
+                className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors"
+              >
+                <span className="material-symbols-outlined text-[14px]">{copiedRes ? "check" : "content_copy"}</span>
+                {copiedRes ? "Copied" : "Copy"}
+              </button>
+            )}
+          </div>
+          <pre className="bg-sidebar rounded-lg px-3 py-2.5 text-xs font-mono text-text-main overflow-x-auto whitespace-pre-wrap break-all opacity-70">
+            {result ? resultJson : exConfig.defaultResponse}
+          </pre>
+          {kind === "image" && (binaryImageUrl || result?.data?.data?.[0]) && (
+            <div className="mt-2">
+              <div className="flex items-center justify-end mb-1.5">
+                <a
+                  href={binaryImageUrl || (result?.data?.data?.[0]?.b64_json ? `data:image/png;base64,${result.data.data[0].b64_json}` : result?.data?.data?.[0]?.url || "")}
+                  download="image.png"
+                  className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors"
+                >
+                  <span className="material-symbols-outlined text-[14px]">download</span>
+                  Download
+                </a>
+              </div>
+              <img
+                src={binaryImageUrl || (result?.data?.data?.[0]?.b64_json ? `data:image/png;base64,${result.data.data[0].b64_json}` : result?.data?.data?.[0]?.url)}
+                alt="Generated"
+                className="max-w-full rounded-lg border border-border"
+              />
+            </div>
+          )}
+        </div>
+      </div>
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/SttExampleCard.js b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/SttExampleCard.js
new file mode 100644
index 0000000..18f2a4f
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/SttExampleCard.js
@@ -0,0 +1,290 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card } from "@/shared/components";
+import { getProviderAlias } from "@/shared/constants/providers";
+import { getModelKind } from "@/shared/constants/models";
+import { getModelsByProviderId } from "@/shared/constants/models";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import { Row } from "./exampleShared";
+
+export function SttExampleCard({ providerId }) {
+  const providerAlias = getProviderAlias(providerId);
+  const builtinSttModels = getModelsByProviderId(providerId).filter((m) => getModelKind(m) === "stt");
+  const [customSttModels, setCustomSttModels] = useState([]);
+  const sttModels = [...builtinSttModels, ...customSttModels];
+
+  const [selectedModel, setSelectedModel] = useState(builtinSttModels[0]?.id ?? "");
+  const selectedModelObj = sttModels.find((m) => m.id === selectedModel);
+  const allowedParams = Array.isArray(selectedModelObj?.params) ? selectedModelObj.params : [];
+
+  const [audioFile, setAudioFile] = useState(null);
+  const [language, setLanguage] = useState("");
+  const [prompt, setPrompt] = useState("");
+  const [responseFormat, setResponseFormat] = useState("json");
+  const [temperature, setTemperature] = useState("");
+  const [apiKey, setApiKey] = useState("");
+  const [useTunnel, setUseTunnel] = useState(false);
+  const [localEndpoint, setLocalEndpoint] = useState("");
+  const [tunnelEndpoint, setTunnelEndpoint] = useState("");
+  const [result, setResult] = useState(null);
+  const [latency, setLatency] = useState(null);
+  const [running, setRunning] = useState(false);
+  const [error, setError] = useState("");
+  const { copied: copiedCurl, copy: copyCurl } = useCopyToClipboard();
+  const { copied: copiedRes, copy: copyRes } = useCopyToClipboard();
+
+  useEffect(() => {
+    setLocalEndpoint(window.location.origin);
+    fetch("/api/keys")
+      .then((r) => r.json())
+      .then((d) => { setApiKey((d.keys || []).find((k) => k.isActive !== false)?.key || ""); })
+      .catch(() => {});
+    fetch("/api/tunnel/status")
+      .then((r) => r.json())
+      .then((d) => { if (d.publicUrl) setTunnelEndpoint(d.publicUrl); })
+      .catch(() => {});
+    const loadCustom = () => {
+      fetch("/api/models/custom", { cache: "no-store" })
+        .then((r) => r.json())
+        .then((d) => {
+          const list = (d.models || []).filter((m) => getModelKind(m) === "stt" && m.providerAlias === providerAlias);
+          setCustomSttModels(list);
+        })
+        .catch(() => {});
+    };
+    loadCustom();
+    window.addEventListener("focus", loadCustom);
+    window.addEventListener("customModelChanged", loadCustom);
+    return () => {
+      window.removeEventListener("focus", loadCustom);
+      window.removeEventListener("customModelChanged", loadCustom);
+    };
+  }, [providerAlias]);
+
+  const endpoint = useTunnel ? tunnelEndpoint : localEndpoint;
+  const modelFull = selectedModel ? `${providerAlias}/${selectedModel}` : "";
+
+  const curlSnippet = `curl -X POST ${endpoint}/v1/audio/transcriptions \\
+  -H "Authorization: Bearer ${apiKey || "YOUR_KEY"}" \\
+  -F "file=@${audioFile?.name || "audio.mp3"}" \\
+  -F "model=${modelFull}"${allowedParams.includes("language") && language ? ` \\\n  -F "language=${language}"` : ""}${allowedParams.includes("response_format") ? ` \\\n  -F "response_format=${responseFormat}"` : ""}${allowedParams.includes("temperature") && temperature ? ` \\\n  -F "temperature=${temperature}"` : ""}${allowedParams.includes("prompt") && prompt ? ` \\\n  -F "prompt=${prompt}"` : ""}`;
+
+  const handleRun = async () => {
+    if (!audioFile || !modelFull) return;
+    setRunning(true);
+    setError("");
+    setResult(null);
+    const start = Date.now();
+    try {
+      const fd = new FormData();
+      fd.append("file", audioFile);
+      fd.append("model", modelFull);
+      if (allowedParams.includes("language") && language) fd.append("language", language);
+      if (allowedParams.includes("response_format")) fd.append("response_format", responseFormat);
+      if (allowedParams.includes("temperature") && temperature) fd.append("temperature", temperature);
+      if (allowedParams.includes("prompt") && prompt) fd.append("prompt", prompt);
+
+      const headers = {};
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+      const res = await fetch("/api/v1/audio/transcriptions", { method: "POST", headers, body: fd });
+      setLatency(Date.now() - start);
+      const ct = res.headers.get("content-type") || "";
+      const data = ct.includes("application/json") ? await res.json() : await res.text();
+      if (!res.ok) {
+        setError(data?.error?.message || data?.error || data || `HTTP ${res.status}`);
+        return;
+      }
+      setResult(data);
+    } catch (e) {
+      setError(e.message || "Network error");
+    } finally {
+      setRunning(false);
+    }
+  };
+
+  const resultStr = typeof result === "string" ? result : (result ? JSON.stringify(result, null, 2) : `{\n  "text": "Hello world..."\n}`);
+
+  return (
+    <Card>
+      <h2 className="text-lg font-semibold mb-4">Example</h2>
+      <div className="flex flex-col gap-2.5">
+        {/* Model */}
+        {sttModels.length > 0 ? (
+          <Row label="Model">
+            <select
+              value={selectedModel}
+              onChange={(e) => setSelectedModel(e.target.value)}
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            >
+              {sttModels.map((m) => (
+                <option key={m.id} value={m.id}>{m.name || m.id}</option>
+              ))}
+            </select>
+          </Row>
+        ) : (
+          <Row label="Model">
+            <input
+              value={selectedModel}
+              onChange={(e) => setSelectedModel(e.target.value)}
+              placeholder="Enter model id"
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary font-mono"
+            />
+          </Row>
+        )}
+
+        {/* Endpoint */}
+        <Row label="Endpoint">
+          <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+            <span className="w-full min-w-0 flex-1 px-3 py-1.5 text-sm font-mono text-text-main bg-sidebar rounded-lg truncate">
+              {endpoint}/v1/audio/transcriptions
+            </span>
+            {tunnelEndpoint && (
+              <button
+                onClick={() => setUseTunnel((v) => !v)}
+                title={useTunnel ? "Using tunnel" : "Using local"}
+                className={`flex items-center gap-1 text-xs px-2 py-1.5 rounded-lg border shrink-0 transition-colors ${
+                  useTunnel ? "border-primary/40 bg-primary/10 text-primary" : "border-border text-text-muted hover:text-primary"
+                }`}
+              >
+                <span className="material-symbols-outlined text-[14px]">wifi_tethering</span>
+                Tunnel
+              </button>
+            )}
+          </div>
+        </Row>
+
+        {/* API Key */}
+        <Row label="API Key">
+          <span className="px-3 py-1.5 text-sm font-mono text-text-main bg-sidebar rounded-lg truncate block">
+            {apiKey ? `${apiKey.slice(0, 8)}${"\u2022".repeat(Math.min(20, apiKey.length - 8))}` : <span className="text-text-muted italic">No key configured</span>}
+          </span>
+        </Row>
+
+        {/* Audio file */}
+        <Row label="Audio File">
+          <div className="flex flex-col gap-2">
+            <input
+              type="file"
+              accept="audio/*,video/mp4,.m4a,.mp3,.wav,.ogg,.flac,.webm,.opus"
+              onChange={(e) => setAudioFile(e.target.files?.[0] || null)}
+              className="w-full text-xs text-text-muted file:mr-2 file:py-1 file:px-2.5 file:rounded-lg file:border file:border-border file:bg-background file:text-text-main hover:file:bg-sidebar file:cursor-pointer"
+            />
+            {audioFile && (
+              <span className="text-xs text-text-muted font-mono">
+                {audioFile.name} · {(audioFile.size / 1024).toFixed(1)} KB
+              </span>
+            )}
+          </div>
+        </Row>
+
+        {/* Language (if model supports) */}
+        {allowedParams.includes("language") && (
+          <Row label="Language">
+            <input
+              value={language}
+              onChange={(e) => setLanguage(e.target.value)}
+              placeholder="e.g. en, vi, ja (auto-detect if empty)"
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary font-mono"
+            />
+          </Row>
+        )}
+
+        {/* Prompt (if model supports) */}
+        {allowedParams.includes("prompt") && (
+          <Row label="Prompt">
+            <input
+              value={prompt}
+              onChange={(e) => setPrompt(e.target.value)}
+              placeholder="optional context to improve accuracy"
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            />
+          </Row>
+        )}
+
+        {/* Temperature (if model supports) */}
+        {allowedParams.includes("temperature") && (
+          <Row label="Temperature">
+            <input
+              type="number"
+              step="0.1"
+              min="0"
+              max="1"
+              value={temperature}
+              onChange={(e) => setTemperature(e.target.value)}
+              placeholder="0 - 1 (default 0)"
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            />
+          </Row>
+        )}
+
+        {/* Response format (if model supports) */}
+        {allowedParams.includes("response_format") && (
+          <Row label="Response Format">
+            <select
+              value={responseFormat}
+              onChange={(e) => setResponseFormat(e.target.value)}
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            >
+              <option value="json">json</option>
+              <option value="text">text</option>
+              <option value="srt">srt</option>
+              <option value="verbose_json">verbose_json</option>
+              <option value="vtt">vtt</option>
+            </select>
+          </Row>
+        )}
+
+        {/* Curl + Run */}
+        <div className="mt-1">
+          <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between mb-1.5">
+            <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">Request</span>
+            <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+              <button
+                onClick={() => copyCurl(curlSnippet)}
+                className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors"
+              >
+                <span className="material-symbols-outlined text-[14px]">{copiedCurl ? "check" : "content_copy"}</span>
+                {copiedCurl ? "Copied" : "Copy"}
+              </button>
+              <button
+                onClick={handleRun}
+                disabled={running || !audioFile || !modelFull}
+                className="flex w-full sm:w-auto items-center justify-center gap-1.5 px-3 py-1 rounded-lg bg-primary text-white text-xs font-medium hover:bg-primary/90 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+              >
+                <span className="material-symbols-outlined text-[14px]" style={running ? { animation: "spin 1s linear infinite" } : undefined}>
+                  play_arrow
+                </span>
+                {running ? "Transcribing..." : "Run"}
+              </button>
+            </div>
+          </div>
+          <pre className="bg-sidebar rounded-lg px-3 py-2.5 text-xs font-mono text-text-main overflow-x-auto whitespace-pre-wrap break-all">{curlSnippet}</pre>
+        </div>
+
+        {error && <p className="text-xs text-red-500 break-words">{error}</p>}
+
+        {/* Response */}
+        <div>
+          <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between mb-1.5">
+            <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">
+              Response {result && latency && <span className="font-normal normal-case">&#9889; {latency}ms</span>}
+            </span>
+            {result && (
+              <button
+                onClick={() => copyRes(resultStr)}
+                className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors"
+              >
+                <span className="material-symbols-outlined text-[14px]">{copiedRes ? "check" : "content_copy"}</span>
+                {copiedRes ? "Copied" : "Copy"}
+              </button>
+            )}
+          </div>
+          <pre className="bg-sidebar rounded-lg px-3 py-2.5 text-xs font-mono text-text-main overflow-x-auto whitespace-pre-wrap break-all opacity-70">
+            {resultStr}
+          </pre>
+        </div>
+      </div>
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/TtsExampleCard.js b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/TtsExampleCard.js
new file mode 100644
index 0000000..e019190
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/TtsExampleCard.js
@@ -0,0 +1,566 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card } from "@/shared/components";
+import { AI_PROVIDERS, getProviderAlias } from "@/shared/constants/providers";
+import { getModelsByProviderId, getModelKind } from "@/shared/constants/models";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import { TTS_PROVIDER_CONFIG } from "@/shared/constants/ttsProviders";
+import { getTtsVoicesForModel } from "open-sse/config/ttsModels.js";
+import { GOOGLE_TTS_LANGUAGES } from "open-sse/config/googleTtsLanguages.js";
+import { Row } from "./exampleShared";
+
+const DEFAULT_TTS_RESPONSE_EXAMPLE = `// Audio will appear here after running.
+// Example JSON response (response_format=json):
+{
+  "format": "mp3",
+  "audio": "//NExAANaAIIAUAAANNNNNNNN..." // base64 encoded MP3
+}`;
+
+export function TtsExampleCard({ providerId }) {
+  const providerAlias = getProviderAlias(providerId);
+  const config = TTS_PROVIDER_CONFIG[providerId] || TTS_PROVIDER_CONFIG["edge-tts"];
+
+  // Voice state
+  const [selectedVoice, setSelectedVoice]     = useState(config.defaultVoiceId || "");
+  const [selectedVoiceName, setSelectedVoiceName] = useState("");
+  const [voiceId, setVoiceId]               = useState(config.defaultVoiceId || ""); // editable voice id (elevenlabs/config providers)
+  // Voices shown below Voice row after language selected
+  const [countryVoices, setCountryVoices]     = useState([]);
+  const [selectedLang, setSelectedLang]       = useState("");
+  const [selectedModel, setSelectedModel]     = useState(() => {
+    const cfgModels = AI_PROVIDERS[providerId]?.ttsConfig?.models;
+    if (cfgModels?.length) return cfgModels[0].id;
+    if (config.hasModelSelector && config.modelKey) {
+      const models = getModelsByProviderId(config.modelKey);
+      return models?.[0]?.id || "";
+    }
+    return "";
+  });
+
+  // Form state
+  const [input, setInput]               = useState("Hello, this is a text to speech test.");
+  const [apiKey, setApiKey]             = useState("");
+  const [useTunnel, setUseTunnel]       = useState(false);
+  const [localEndpoint, setLocalEndpoint]   = useState("");
+  const [tunnelEndpoint, setTunnelEndpoint] = useState("");
+  const [responseFormat, setResponseFormat] = useState("mp3"); // mp3 | json
+  const [audioUrl, setAudioUrl]         = useState("");
+  const [jsonResponse, setJsonResponse] = useState(null); // Store JSON response
+  const [running, setRunning]           = useState(false);
+  const [error, setError]               = useState("");
+  const [latency, setLatency]           = useState(null);
+  const { copied: copiedCurl, copy: copyCurl } = useCopyToClipboard();
+
+  // Country picker modal state
+  const [modalOpen, setModalOpen]           = useState(false);
+  const [languages, setLanguages]           = useState([]);
+  const [modalLoading, setModalLoading]     = useState(false);
+  const [modalSearch, setModalSearch]       = useState("");
+  const [modalError, setModalError]         = useState("");
+  const [byLang, setByLang]                 = useState({});
+  // Language hint (e.g. Gemini): controls the spoken language without affecting voice selection
+  const [languageHint, setLanguageHint]     = useState("");
+
+  useEffect(() => {
+    setLocalEndpoint(window.location.origin);
+    fetch("/api/keys")
+      .then((r) => r.json())
+      .then((d) => { setApiKey((d.keys || []).find((k) => k.isActive !== false)?.key || ""); })
+      .catch(() => {});
+    fetch("/api/tunnel/status")
+      .then((r) => r.json())
+      .then((d) => { if (d.publicUrl) setTunnelEndpoint(d.publicUrl); })
+      .catch(() => {});
+
+    // Pre-select default voice based on provider config
+    if (config.voiceSource === "hardcoded") {
+      const defaultModel = config.hasModelSelector && config.modelKey
+        ? (getModelsByProviderId(config.modelKey)?.[0]?.id || "")
+        : "";
+      // Use per-model voices if available, else flat list
+      const voices = (config.voicesPerModel && defaultModel)
+        ? (getTtsVoicesForModel(providerId, defaultModel) || [])
+        : getModelsByProviderId(config.voiceKey || providerId).filter((m) => getModelKind(m) === "tts");
+      if (voices.length) {
+        if (config.hasBrowseButton) {
+          // Google TTS: pre-select "en" (English) as default, show as single voice chip
+          const defaultVoice = voices.find((v) => v.id === "en") || voices[0];
+          setSelectedLang(defaultVoice.id);
+          setSelectedVoice(defaultVoice.id);
+          setSelectedVoiceName(defaultVoice.name);
+          setCountryVoices([{ id: defaultVoice.id, name: defaultVoice.name }]);
+        } else {
+          // OpenAI/OpenRouter: set voice chips directly (no language picker)
+          setCountryVoices(voices);
+          setSelectedVoice(voices[0].id);
+          setSelectedVoiceName(voices[0].name || voices[0].id);
+        }
+      }
+    }
+    // api-language (edge-tts, local-device, elevenlabs): NO default load, wait for user to pick language
+    // config (nvidia, hyperbolic, deepgram, huggingface, cartesia, playht, coqui, tortoise, inworld, qwen):
+    // use ttsConfig.models for model selector; voice is empty by default (backend uses provider default)
+  }, [providerId]);
+
+  // Update voices when model changes (voicesPerModel providers)
+  useEffect(() => {
+    if (!config.voicesPerModel || !selectedModel) return;
+    const voices = getTtsVoicesForModel(providerId, selectedModel) || [];
+    setCountryVoices(voices);
+    if (voices.length) {
+      setSelectedVoice(voices[0].id);
+      setSelectedVoiceName(voices[0].name || voices[0].id);
+    }
+  }, [selectedModel]);
+
+  // Open modal — load language list
+  const openModal = async () => {
+    setModalOpen(true);
+    setModalSearch("");
+    setModalError("");
+    if (languages.length) return; // already loaded
+    setModalLoading(true);
+    try {
+      if (config.voiceSource === "hardcoded") {
+        // Build languages/byLang from static providerModels data
+        const voiceKey = config.voiceKey || providerId;
+        const voices = getModelsByProviderId(voiceKey).filter((m) => getModelKind(m) === "tts");
+        const byLangMap = {};
+        for (const v of voices) {
+          if (!byLangMap[v.id]) byLangMap[v.id] = { code: v.id, name: v.name, voices: [{ id: v.id, name: v.name }] };
+        }
+        setByLang(byLangMap);
+        setLanguages(Object.values(byLangMap).sort((a, b) => a.name.localeCompare(b.name)));
+      } else {
+        // Use provider-specific apiEndpoint if available, else default to edge-tts voices API
+        const url = config.apiEndpoint
+          ? config.apiEndpoint
+          : `/api/media-providers/tts/voices?provider=${providerId === "local-device" ? "local-device" : "edge-tts"}`;
+        const r = await fetch(url);
+        const d = await r.json();
+        if (d.error) { setModalError(d.error); return; }
+        setLanguages(d.languages || []);
+        setByLang(d.byLang || {});
+      }
+    } catch (e) {
+      setModalError(e.message);
+    } finally {
+      setModalLoading(false);
+    }
+  };
+
+  // Click language → close modal → show voices below
+  const handlePickLanguage = (lang) => {
+    setModalOpen(false);
+    setSelectedLang(lang.code);
+    const voices = byLang[lang.code]?.voices || [];
+    setCountryVoices(voices);
+    // Auto-select first voice
+    if (voices.length) {
+      setSelectedVoice(voices[0].id);
+      setSelectedVoiceName(voices[0].name);
+      if (config.hasVoiceIdInput) setVoiceId(voices[0].id);
+    }
+  };
+
+  const filteredLanguages = modalSearch
+    ? languages.filter((c) =>
+        c.name.toLowerCase().includes(modalSearch.toLowerCase()) ||
+        c.code.toLowerCase().includes(modalSearch.toLowerCase())
+      )
+    : languages;
+
+  const endpoint = useTunnel ? tunnelEndpoint : localEndpoint;
+  // For ElevenLabs/config-driven: prefer manual voiceId (if any), else fall back to selectedVoice
+  const activeVoiceId = config.hasVoiceIdInput ? (voiceId || selectedVoice) : selectedVoice;
+  const modelFull = (() => {
+    if (config.hasModelSelector && selectedModel && activeVoiceId) return `${providerAlias}/${selectedModel}/${activeVoiceId}`;
+    if (config.hasModelSelector && selectedModel) return `${providerAlias}/${selectedModel}`;
+    if (activeVoiceId) return `${providerAlias}/${activeVoiceId}`;
+    return "";
+  })();
+
+  const ttsBody = (() => {
+    const b = { model: modelFull, input };
+    if (config.hasLanguageHint && languageHint) b.language = languageHint;
+    return b;
+  })();
+  const curlSnippet = `curl -X POST ${endpoint}/v1/audio/speech${responseFormat === "json" ? "?response_format=json" : ""} \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer ${apiKey || "YOUR_KEY"}" \\
+  -d '${JSON.stringify(ttsBody)}' \\
+  ${responseFormat === "json" ? "" : "--output speech.mp3"}`;
+
+  const handleRun = async () => {
+    if (!input.trim() || !modelFull) return;
+    setRunning(true);
+    setError("");
+    setAudioUrl("");
+    setJsonResponse(null);
+    const start = Date.now();
+    try {
+      const headers = { "Content-Type": "application/json" };
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+      const url = `/api/v1/audio/speech${responseFormat === "json" ? "?response_format=json" : ""}`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ ...ttsBody, input: input.trim() }),
+      });
+      setLatency(Date.now() - start);
+      if (!res.ok) {
+        const d = await res.json().catch(() => ({}));
+        setError(d?.error?.message || d?.error || `HTTP ${res.status}`);
+        return;
+      }
+      
+      if (responseFormat === "json") {
+        const data = await res.json();
+        setJsonResponse(data); // Store full JSON response
+        const audioBlob = await fetch(`data:audio/mp3;base64,${data.audio}`).then(r => r.blob());
+        setAudioUrl(URL.createObjectURL(audioBlob));
+      } else {
+        const blob = await res.blob();
+        setAudioUrl(URL.createObjectURL(blob));
+      }
+    } catch (e) {
+      setError(e.message || "Network error");
+    } finally {
+      setRunning(false);
+    }
+  };
+
+  return (
+    <>
+      <Card>
+        <h2 className="text-lg font-semibold mb-4">Example</h2>
+
+        <div className="flex flex-col gap-2.5">
+          {/* Endpoint + API Key as read-only text */}
+          <Row label="Endpoint">
+            <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+              <span className="w-full min-w-0 flex-1 px-3 py-1.5 text-sm font-mono text-text-main bg-sidebar rounded-lg truncate">
+                {endpoint}/v1/audio/speech
+              </span>
+              {tunnelEndpoint && (
+                <button
+                  onClick={() => setUseTunnel((v) => !v)}
+                  title={useTunnel ? "Using tunnel" : "Using local"}
+                  className={`flex items-center gap-1 text-xs px-2 py-1.5 rounded-lg border shrink-0 transition-colors ${
+                    useTunnel ? "border-primary/40 bg-primary/10 text-primary" : "border-border text-text-muted hover:text-primary"
+                  }`}
+                >
+                  <span className="material-symbols-outlined text-[14px]">wifi_tethering</span>
+                  Tunnel
+                </button>
+              )}
+            </div>
+          </Row>
+          <Row label="API Key">
+            <span className="px-3 py-1.5 text-sm font-mono text-text-main bg-sidebar rounded-lg truncate block">
+              {apiKey ? `${apiKey.slice(0, 8)}${"•".repeat(Math.min(20, apiKey.length - 8))}` : <span className="text-text-muted italic">No key configured</span>}
+            </span>
+          </Row>
+
+          {/* Model selector — prefer PROVIDER_MODELS[kind=tts], else providerModels via modelKey */}
+          {config.hasModelSelector && (config.modelKey || getModelsByProviderId(providerId).some(m => getModelKind(m) === "tts")) && (
+            <Row label="Model">
+              <select
+                value={selectedModel}
+                onChange={(e) => setSelectedModel(e.target.value)}
+                className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+              >
+                {(() => {
+                  const ttsModels = getModelsByProviderId(providerId).filter(m => getModelKind(m) === "tts");
+                  return (ttsModels.length ? ttsModels : getModelsByProviderId(config.modelKey) || []).map((m) => (
+                    <option key={m.id} value={m.id}>{m.name || m.id}</option>
+                  ));
+                })()}
+              </select>
+            </Row>
+          )}
+
+          {/* Language hint dropdown (Gemini) — sends body.language to guide pronunciation */}
+          {config.hasLanguageHint && (
+            <Row label="Language">
+              <select
+                value={languageHint}
+                onChange={(e) => setLanguageHint(e.target.value)}
+                className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+              >
+                <option value="">Auto-detect</option>
+                {GOOGLE_TTS_LANGUAGES.map((l) => (
+                  <option key={l.id} value={l.name}>{l.name}</option>
+                ))}
+              </select>
+            </Row>
+          )}
+
+          {/* Language row + Browse button (edge-tts, local-device, elevenlabs) */}
+          {config.hasBrowseButton && (
+            <Row label="Language">
+              <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+                <button
+                  onClick={openModal}
+                  className="w-full min-w-0 flex-1 px-3 py-1.5 text-sm border border-border rounded-lg bg-background font-mono truncate text-left hover:border-primary/40 transition-colors"
+                >
+                  {selectedLang
+                    ? <span className="text-text-main">{languages.find((l) => l.code === selectedLang)?.name || selectedLang}</span>
+                    : <span className="text-text-muted">No language selected</span>}
+                </button>
+                <button
+                  onClick={openModal}
+                  className="flex w-full items-center justify-center gap-1 text-xs px-2.5 py-1.5 rounded-lg border border-border text-text-muted hover:text-primary hover:border-primary/40 transition-colors sm:w-auto sm:shrink-0"
+                >
+                  <span className="material-symbols-outlined text-[14px]">language</span>
+                  Select language
+                </button>
+              </div>
+            </Row>
+          )}
+
+          {/* Voice chips — shown after language picked (edge-tts, local-device) or always (OpenAI/ElevenLabs) */}
+          {countryVoices.length > 0 && (
+            <Row label="Voice">
+              <div className="flex flex-wrap gap-1.5">
+                {countryVoices.map((v) => (
+                  <button
+                    key={v.id}
+                    onClick={() => {
+                      setSelectedVoice(v.id);
+                      setSelectedVoiceName(v.name);
+                      if (config.hasVoiceIdInput) setVoiceId(v.id);
+                    }}
+                    className={`px-2.5 py-1 rounded-full text-xs border transition-colors ${
+                      selectedVoice === v.id
+                        ? "bg-primary/15 border-primary/40 text-primary font-medium"
+                        : "border-border text-text-muted hover:text-primary hover:border-primary/40"
+                    }`}
+                  >
+                    {v.name}{v.gender ? ` · ${v.gender[0].toUpperCase()}` : ""}
+                    {v.free_users_allowed === true && (
+                      <span className="ml-1.5 px-1 py-0.5 text-[9px] font-semibold rounded bg-green-500/15 text-green-600 border border-green-500/20">Free</span>
+                    )}
+                    {v.free_users_allowed === false && (
+                      <span className="ml-1.5 px-1 py-0.5 text-[9px] font-semibold rounded bg-amber-500/15 text-amber-600 border border-amber-500/20">Paid</span>
+                    )}
+                  </button>
+                ))}
+              </div>
+            </Row>
+          )}
+
+          {/* Voice ID input (ElevenLabs) — manual entry or auto-fill from chip */}
+          {config.hasVoiceIdInput && (
+            <Row label="Voice ID">
+              <div className="flex flex-col gap-1">
+                <div className="relative">
+                  <input
+                    value={voiceId}
+                    onChange={(e) => {
+                      setVoiceId(e.target.value);
+                      setSelectedVoice(e.target.value);
+                    }}
+                    placeholder="e.g. CwhRBWXzGAHq8TQ4Fs17"
+                    className="w-full px-3 py-1.5 pr-7 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary font-mono"
+                  />
+                  {voiceId && (
+                    <button
+                      type="button"
+                      onClick={() => { setVoiceId(""); setSelectedVoice(""); }}
+                      className="absolute right-2 top-1/2 -translate-y-1/2 text-text-muted hover:text-primary transition-colors"
+                    >
+                      <span className="material-symbols-outlined text-[14px]">close</span>
+                    </button>
+                  )}
+                </div>
+              </div>
+            </Row>
+          )}
+
+          {/* Google TTS: Language dropdown */}
+          {config.hasLanguageDropdown && (
+            <Row label="Language">
+              <select
+                value={selectedVoice}
+                onChange={(e) => {
+                  const m = getModelsByProviderId(providerId).filter((m) => getModelKind(m) === "tts").find((m) => m.id === e.target.value);
+                  setSelectedVoice(e.target.value);
+                  setSelectedVoiceName(m?.name || e.target.value);
+                }}
+                className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+              >
+                {getModelsByProviderId(providerId).filter((m) => getModelKind(m) === "tts").map((m) => (
+                  <option key={m.id} value={m.id}>{m.name || m.id}</option>
+                ))}
+              </select>
+            </Row>
+          )}
+
+          {/* Input */}
+          <Row label="Input">
+            <div className="relative">
+              <input
+                value={input}
+                onChange={(e) => setInput(e.target.value)}
+                className="w-full px-3 py-1.5 pr-7 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+              />
+              {input && (
+                <button
+                  type="button"
+                  onClick={() => setInput("")}
+                  className="absolute right-2 top-1/2 -translate-y-1/2 text-text-muted hover:text-primary transition-colors"
+                >
+                  <span className="material-symbols-outlined text-[14px]">close</span>
+                </button>
+              )}
+            </div>
+          </Row>
+
+          {/* Output Format */}
+          <Row label="Output Format">
+            <select
+              value={responseFormat}
+              onChange={(e) => setResponseFormat(e.target.value)}
+              className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            >
+              <option value="mp3">MP3 (Binary)</option>
+              <option value="json">JSON (Base64)</option>
+            </select>
+          </Row>
+
+          {/* Curl + Run */}
+          <div className="mt-1">
+            <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between mb-1.5">
+              <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">Request</span>
+              <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+                <button
+                  onClick={() => copyCurl(curlSnippet)}
+                  className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors"
+                >
+                  <span className="material-symbols-outlined text-[14px]">{copiedCurl ? "check" : "content_copy"}</span>
+                  {copiedCurl ? "Copied" : "Copy"}
+                </button>
+                <button
+                  onClick={handleRun}
+                  disabled={running || !input.trim() || !modelFull}
+                  className="flex w-full sm:w-auto items-center justify-center gap-1.5 px-3 py-1 rounded-lg bg-primary text-white text-xs font-medium hover:bg-primary/90 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                >
+                  <span className="material-symbols-outlined text-[14px]" style={running ? { animation: "spin 1s linear infinite" } : undefined}>
+                    play_arrow
+                  </span>
+                  {running ? "Generating..." : "Run"}
+                </button>
+              </div>
+            </div>
+            <pre className="bg-sidebar rounded-lg px-3 py-2.5 text-xs font-mono text-text-main overflow-x-auto whitespace-pre-wrap break-all">{curlSnippet}</pre>
+          </div>
+
+          {error && <p className="text-xs text-red-500 break-words">{error}</p>}
+
+          {/* Audio player */}
+          {audioUrl ? (
+            <div>
+              <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between mb-1.5">
+                <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">
+                  Response {latency && <span className="font-normal normal-case">&#9889; {latency}ms</span>}
+                </span>
+                <a href={audioUrl} download="speech.mp3" className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors">
+                  <span className="material-symbols-outlined text-[14px]">download</span>
+                  Download
+                </a>
+              </div>
+              <audio controls src={audioUrl} className="w-full" />
+              
+              {/* JSON Response (if format is json) */}
+              {jsonResponse && (
+                <div className="mt-3">
+                  <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between mb-1.5">
+                    <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">JSON Response</span>
+                  </div>
+                  <pre className="bg-sidebar rounded-lg px-3 py-2.5 text-xs font-mono text-text-main overflow-x-auto whitespace-pre-wrap break-all">
+                    {JSON.stringify({
+                      format: jsonResponse.format,
+                      audio: jsonResponse.audio ? `${jsonResponse.audio.substring(0, 100)}...` : ""
+                    }, null, 2)}
+                  </pre>
+                </div>
+              )}
+            </div>
+          ) : (
+            <div>
+            <span className="text-xs font-semibold text-text-muted uppercase tracking-wider">Response</span>
+            <pre className="mt-1.5 bg-sidebar rounded-lg px-3 py-2.5 text-xs font-mono text-text-main overflow-x-auto whitespace-pre-wrap break-all opacity-50">{DEFAULT_TTS_RESPONSE_EXAMPLE}</pre>
+          </div>
+          )}
+        </div>
+      </Card>
+
+      {/* Country Picker Modal */}
+      {modalOpen && (
+        <div
+          className="fixed inset-0 z-50 flex items-end justify-center sm:items-center"
+          style={{ backgroundColor: "rgba(0,0,0,0.6)", backdropFilter: "blur(2px)" }}
+          onClick={() => setModalOpen(false)}
+        >
+          <div
+            className="border border-border rounded-xl shadow-2xl w-full max-w-md mx-4 flex flex-col max-h-[80vh]"
+            style={{ backgroundColor: "var(--color-bg)", isolation: "isolate" }}
+            onClick={(e) => e.stopPropagation()}
+          >
+            {/* Header */}
+            <div className="flex items-center justify-between px-4 py-3 border-b border-border shrink-0 rounded-t-xl">
+              <h3 className="text-sm font-semibold">Select Language</h3>
+              <button onClick={() => setModalOpen(false)} className="text-text-muted hover:text-primary transition-colors">
+                <span className="material-symbols-outlined text-[20px]">close</span>
+              </button>
+            </div>
+
+            {/* Search */}
+            <div className="px-4 py-2.5 border-b border-border shrink-0">
+              <input
+                autoFocus
+                value={modalSearch}
+                onChange={(e) => setModalSearch(e.target.value)}
+                placeholder="Search language..."
+                className="w-full px-3 py-1.5 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+              />
+            </div>
+
+            {/* Language list */}
+            <div className="overflow-y-auto flex-1 p-2">
+              {modalError && <p className="text-xs text-red-500 px-2 py-1">{modalError}</p>}
+              {modalLoading ? (
+                <p className="text-xs text-text-muted px-2 py-3">Loading...</p>
+              ) : (
+                <div className="flex flex-col gap-0.5">
+                  {filteredLanguages.map((c) => (
+                    <button
+                      key={c.code}
+                      onClick={() => handlePickLanguage(c)}
+                      className={`flex items-center justify-between w-full px-3 py-2 rounded-lg text-left hover:bg-sidebar transition-colors ${
+                        selectedLang === c.code ? "bg-primary/10 text-primary" : ""
+                      }`}
+                    >
+                      <span className="text-sm">{c.name}</span>
+                      <div className="flex items-center gap-2 shrink-0">
+                        <span className="text-xs text-text-muted">{c.voices.length} voices</span>
+                        {selectedLang === c.code && (
+                          <span className="material-symbols-outlined text-[16px] text-primary">check</span>
+                        )}
+                      </div>
+                    </button>
+                  ))}
+                  {filteredLanguages.length === 0 && (
+                    <p className="text-xs text-text-muted px-2 py-3">No languages found.</p>
+                  )}
+                </div>
+              )}
+            </div>
+          </div>
+        </div>
+      )}
+    </>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/exampleShared.js b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/exampleShared.js
new file mode 100644
index 0000000..2fb4cb5
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/components/exampleShared.js
@@ -0,0 +1,76 @@
+"use client";
+
+export function Row({ label, children }) {
+  return (
+    <div className="flex min-w-0 flex-col gap-1.5 sm:flex-row sm:items-center sm:gap-3">
+      <span className="w-full text-xs font-medium text-text-muted sm:w-20 sm:shrink-0">{label}</span>
+      <div className="w-full min-w-0 flex-1">{children}</div>
+    </div>
+  );
+}
+
+export const KIND_EXAMPLE_CONFIG = {
+  webSearch: {
+    inputLabel: "Query",
+    inputPlaceholder: "What is the latest news about AI?",
+    defaultInput: "What is the latest news about AI?",
+    bodyKey: "query",
+    defaultResponse: `{\n  "results": [\n    { "title": "...", "url": "...", "snippet": "..." }\n  ]\n}`,
+    extraFields: [
+      { key: "search_type", label: "Type", type: "select", default: "web", options: ["web", "news"] },
+      { key: "max_results", label: "Max results", type: "number", default: 5, min: 1, max: 100 },
+      { key: "country", label: "Country", type: "text", default: "" },
+      { key: "language", label: "Language", type: "text", default: "" },
+    ],
+  },
+  webFetch: {
+    inputLabel: "URL",
+    inputPlaceholder: "https://example.com",
+    defaultInput: "https://example.com",
+    bodyKey: "url",
+    defaultResponse: `{\n  "content": "...",\n  "title": "...",\n  "url": "..."\n}`,
+    extraFields: [
+      { key: "format", label: "Format", type: "select", default: "markdown", options: ["markdown", "text", "html"] },
+      { key: "max_characters", label: "Max chars", type: "number", default: 0, min: 0 },
+    ],
+  },
+  image: {
+    inputLabel: "Prompt",
+    inputPlaceholder: "A cute cat wearing a hat",
+    defaultInput: "A cute cat wearing a hat",
+    bodyKey: "prompt",
+    defaultResponse: `{\n  "data": [\n    { "url": "...", "b64_json": "..." }\n  ]\n}`,
+    extraFields: [
+      { key: "n", label: "n", type: "number", default: 1, min: 1, max: 4 },
+      { key: "size", label: "Size", type: "select", default: "auto", options: ["auto", "1024x1024", "1024x1536", "1536x1024", "1024x1792", "1792x1024"] },
+      { key: "quality", label: "Quality", type: "select", default: "auto", options: ["auto", "low", "medium", "high", "standard", "hd"] },
+      { key: "background", label: "Background", type: "select", default: "auto", options: ["auto", "transparent", "opaque"] },
+      { key: "style", label: "Style", type: "select", default: "", options: ["", "vivid", "natural"] },
+      { key: "response_format", label: "Format", type: "select", default: "", options: ["", "url", "b64_json"] },
+      { key: "image_detail", label: "Image Detail", type: "select", default: "high", options: ["auto", "low", "high", "original"] },
+      { key: "output_format", label: "Codec", type: "select", default: "png", options: ["png", "jpeg", "webp"] },
+    ],
+  },
+  imageToText: {
+    inputLabel: "Image URL",
+    inputPlaceholder: "https://example.com/image.png",
+    defaultInput: "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg",
+    bodyKey: "url",
+    extraBody: { prompt: "Describe this image in detail" },
+    defaultResponse: `{\n  "text": "A cat sitting on a windowsill...",\n  "model": "..."\n}`,
+  },
+  video: {
+    inputLabel: "Prompt",
+    inputPlaceholder: "A serene lake at sunset",
+    defaultInput: "A serene lake at sunset",
+    bodyKey: "prompt",
+    defaultResponse: `{\n  "data": [\n    { "url": "..." }\n  ]\n}`,
+  },
+  music: {
+    inputLabel: "Prompt",
+    inputPlaceholder: "A calm piano melody",
+    defaultInput: "A calm piano melody",
+    bodyKey: "prompt",
+    defaultResponse: `{\n  "data": [\n    { "url": "...", "format": "mp3" }\n  ]\n}`,
+  },
+};
diff --git a/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/page.js b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/page.js
new file mode 100644
index 0000000..c331267
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/media-providers/[kind]/[id]/page.js
@@ -0,0 +1,210 @@
+"use client";
+
+import { useParams, notFound, useRouter } from "next/navigation";
+import Link from "next/link";
+import { useState, useEffect } from "react";
+import { Card, Badge, Button, AddCustomEmbeddingModal, NoAuthProxyCard, ProviderInfoCard } from "@/shared/components";
+import ProviderIcon from "@/shared/components/ProviderIcon";
+import { MEDIA_PROVIDER_KINDS, AI_PROVIDERS, isCustomEmbeddingProvider } from "@/shared/constants/providers";
+import ConnectionsCard from "@/app/(dashboard)/dashboard/providers/components/ConnectionsCard";
+import ModelsCard from "@/app/(dashboard)/dashboard/providers/components/ModelsCard";
+import { KIND_EXAMPLE_CONFIG } from "./components/exampleShared";
+import { EmbeddingExampleCard } from "./components/EmbeddingExampleCard";
+import { TtsExampleCard } from "./components/TtsExampleCard";
+import { GenericExampleCard } from "./components/GenericExampleCard";
+import { SttExampleCard } from "./components/SttExampleCard";
+
+// MediaProviderDetailPage
+export default function MediaProviderDetailPage() {
+  const { kind, id } = useParams();
+  const router = useRouter();
+  const kindConfig = MEDIA_PROVIDER_KINDS.find((k) => k.id === kind);
+  const isCustom = isCustomEmbeddingProvider(id) && kind === "embedding";
+
+  const handleDeleteCustom = async () => {
+    if (!confirm("Delete this Custom Embedding node?")) return;
+    try {
+      const res = await fetch(`/api/provider-nodes/${id}`, { method: "DELETE" });
+      if (res.ok) router.push(`/dashboard/media-providers/${kind}`);
+    } catch (error) {
+      console.log("Error deleting custom embedding node:", error);
+    }
+  };
+
+  const [customNode, setCustomNode] = useState(null);
+  const [customLoading, setCustomLoading] = useState(isCustom);
+  const [showEditModal, setShowEditModal] = useState(false);
+
+  // Fetch custom node info from API for custom embedding nodes
+  useEffect(() => {
+    if (!isCustom) return;
+    let cancelled = false;
+    fetch("/api/provider-nodes", { cache: "no-store" })
+      .then((r) => r.json())
+      .then((d) => {
+        if (cancelled) return;
+        setCustomNode((d.nodes || []).find((n) => n.id === id) || null);
+        setCustomLoading(false);
+      })
+      .catch(() => { if (!cancelled) setCustomLoading(false); });
+    return () => { cancelled = true; };
+  }, [id, isCustom]);
+
+  if (!kindConfig) return notFound();
+
+  const builtInProvider = AI_PROVIDERS[id];
+
+  // For custom embedding nodes, build a synthetic provider object
+  const provider = isCustom
+    ? (customNode ? { id, name: customNode.name || "Custom Embedding", color: "#6366F1", textIcon: "CE" } : null)
+    : builtInProvider;
+
+  if (!isCustom && !builtInProvider) return notFound();
+  if (isCustom && !customLoading && !customNode) return notFound();
+  if (isCustom && customLoading) {
+    return <div className="text-text-muted text-sm py-12 text-center">Loading...</div>;
+  }
+
+  const kinds = isCustom ? ["embedding"] : (provider.serviceKinds ?? ["llm"]);
+  if (!isCustom && !kinds.includes(kind)) return notFound();
+
+  return (
+    <div className="flex flex-col gap-8">
+      {/* Back */}
+      <div>
+        <Link
+          href={`/dashboard/media-providers/${kind}`}
+          className="inline-flex items-center gap-1 text-sm text-text-muted hover:text-primary transition-colors mb-4"
+        >
+          <span className="material-symbols-outlined text-lg">arrow_back</span>
+          {kindConfig.label}
+        </Link>
+
+        {/* Header */}
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:gap-4">
+          <div className="size-12 rounded-lg flex items-center justify-center shrink-0" style={{ backgroundColor: `${provider.color}15` }}>
+            <ProviderIcon
+              src={`/providers/${provider.id}.png`}
+              alt={provider.name}
+              size={48}
+              className="object-contain rounded-lg max-w-[48px] max-h-[48px]"
+              fallbackText={provider.textIcon || provider.id.slice(0, 2).toUpperCase()}
+              fallbackColor={provider.color}
+            />
+          </div>
+          <div className="flex-1">
+            <div className="flex flex-wrap items-center gap-2 sm:gap-3">
+              <h1 className="text-3xl font-semibold tracking-tight">{provider.name}</h1>
+              {!isCustom && provider.notice?.apiKeyUrl && (
+                <a
+                  href={provider.notice.apiKeyUrl}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-xs text-primary hover:underline inline-flex items-center gap-1"
+                >
+                  <span className="material-symbols-outlined text-sm">open_in_new</span>
+                  Get API Key
+                </a>
+              )}
+            </div>
+            <div className="flex items-center gap-1.5 mt-1 flex-wrap">
+              {isCustom && <Badge variant="default" size="sm">Custom · {customNode?.prefix}</Badge>}
+              {kinds.map((k) => (
+                <Badge key={k} variant={k === kind ? "primary" : "default"} size="sm">
+                  {k.toUpperCase()}
+                </Badge>
+              ))}
+            </div>
+          </div>
+          {isCustom && (
+            <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+              <Button size="sm" variant="secondary" icon="edit" onClick={() => setShowEditModal(true)}>
+                Edit
+              </Button>
+              <Button size="sm" variant="secondary" icon="delete" onClick={handleDeleteCustom}>
+                Delete
+              </Button>
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Kind-specific notice (e.g. codex/image requires Plus) */}
+      {!isCustom && provider.kindNotice?.[kind] && (
+        <div className="flex items-start gap-3 px-4 py-3 rounded-lg bg-amber-500/10 border border-amber-500/30 text-amber-700 dark:text-amber-400">
+          <span className="material-symbols-outlined text-[20px] mt-0.5">warning</span>
+          <p className="text-sm">{provider.kindNotice[kind]}</p>
+        </div>
+      )}
+
+      {/* Provider notice text (only when there's actual text content) */}
+      {!isCustom && provider.notice?.text && !provider.deprecated && (
+        <div className="flex flex-col gap-2 rounded-lg border border-blue-500/30 bg-blue-500/10 px-3 py-2 sm:flex-row sm:items-center">
+          <span className="material-symbols-outlined text-[16px] text-blue-500 shrink-0">info</span>
+          <p className="min-w-0 flex-1 text-xs leading-relaxed text-blue-600 dark:text-blue-400">{provider.notice.text}</p>
+          {provider.notice.apiKeyUrl && (
+            <a
+              href={provider.notice.apiKeyUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex justify-center rounded bg-blue-500 px-2 py-1 text-xs font-medium text-white transition-colors hover:bg-blue-600 sm:py-0.5"
+            >
+              Get API Key →
+            </a>
+          )}
+        </div>
+      )}
+
+      {/* Connections */}
+      {!isCustom && provider.noAuth ? (
+        <NoAuthProxyCard providerId={id} />
+      ) : (
+        <ConnectionsCard providerId={id} isOAuth={false} />
+      )}
+
+      {/* Models - hidden for tts/webSearch/webFetch (provider IS the model); custom uses prefix as alias */}
+      {kind !== "tts" && kind !== "webSearch" && kind !== "webFetch" && (
+        <ModelsCard
+          providerId={id}
+          kindFilter={kind}
+          providerAliasOverride={isCustom ? customNode?.prefix : undefined}
+        />
+      )}
+
+      {/* Provider Info — config-driven, supports searchConfig, fetchConfig, ttsConfig, embeddingConfig, searchViaChat */}
+      {!isCustom && (provider.searchConfig || provider.fetchConfig || provider.ttsConfig || provider.sttConfig || provider.embeddingConfig || provider.searchViaChat) && (
+        <ProviderInfoCard
+          config={
+            kind === "webFetch" ? provider.fetchConfig
+              : kind === "tts" ? provider.ttsConfig
+              : kind === "stt" ? provider.sttConfig
+              : kind === "embedding" ? provider.embeddingConfig
+              : provider.searchConfig || { mode: "chat-completions", defaultModel: provider.searchViaChat?.defaultModel, pricingUrl: provider.searchViaChat?.pricingUrl, freeTier: provider.searchViaChat?.freeTier }
+          }
+          provider={provider}
+          title={`${kindConfig.label} Config`}
+        />
+      )}
+
+      {/* Example — per kind */}
+      {kind === "embedding" && (
+        <EmbeddingExampleCard providerId={id} customAlias={customNode?.prefix} />
+      )}
+      {kind === "tts" && <TtsExampleCard providerId={id} />}
+      {kind === "stt" && !isCustom && <SttExampleCard providerId={id} />}
+      {!isCustom && KIND_EXAMPLE_CONFIG[kind] && <GenericExampleCard providerId={id} kind={kind} />}
+
+      {isCustom && (
+        <AddCustomEmbeddingModal
+          isOpen={showEditModal}
+          node={customNode}
+          onClose={() => setShowEditModal(false)}
+          onSaved={(updated) => {
+            setCustomNode(updated);
+            setShowEditModal(false);
+          }}
+        />
+      )}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/media-providers/[kind]/page.js b/src/app/(dashboard)/dashboard/media-providers/[kind]/page.js
new file mode 100644
index 0000000..e7d0cf2
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/media-providers/[kind]/page.js
@@ -0,0 +1,289 @@
+"use client";
+
+import { useParams, notFound, useRouter } from "next/navigation";
+import Link from "next/link";
+import { useEffect, useState } from "react";
+import { Card, Badge, Button, Toggle, AddCustomEmbeddingModal } from "@/shared/components";
+import ProviderIcon from "@/shared/components/ProviderIcon";
+import { MEDIA_PROVIDER_KINDS, AI_PROVIDERS, getProvidersByKind } from "@/shared/constants/providers";
+
+// Kinds that support combos (currently disabled for image/tts — temporarily hidden).
+// webSearch/webFetch handled by /web page.
+const COMBO_KINDS = new Set([]);
+const COMBO_BASE_NAMES = { image: "image-combo", tts: "tts-combo" };
+
+function getEffectiveStatus(conn) {
+  const isCooldown = Object.entries(conn).some(
+    ([k, v]) => k.startsWith("modelLock_") && v && new Date(v).getTime() > Date.now()
+  );
+  return conn.testStatus === "unavailable" && !isCooldown ? "active" : conn.testStatus;
+}
+
+function MediaProviderCard({ provider, kind, connections, isCustom, onToggle }) {
+  const providerInfo = AI_PROVIDERS[provider.id];
+  const isNoAuth = !!providerInfo?.noAuth;
+
+  const providerConns = connections.filter((c) => c.provider === provider.id);
+  const connected = providerConns.filter((c) => { const s = getEffectiveStatus(c); return s === "active" || s === "success"; }).length;
+  const error = providerConns.filter((c) => { const s = getEffectiveStatus(c); return s === "error" || s === "expired" || s === "unavailable"; }).length;
+  const total = providerConns.length;
+  const allDisabled = total > 0 && providerConns.every((c) => c.isActive === false);
+
+  const handleToggleClick = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    if (onToggle) onToggle(provider.id, allDisabled);
+  };
+
+  const renderStatus = () => {
+    if (isNoAuth) return <Badge variant="success" size="sm">Ready</Badge>;
+    if (allDisabled) return <Badge variant="default" size="sm">Disabled</Badge>;
+    if (total === 0) return <span className="text-xs text-text-muted">No connections</span>;
+    return (
+      <>
+        {connected > 0 && <Badge variant="success" size="sm" dot>{connected} Connected</Badge>}
+        {error > 0 && <Badge variant="error" size="sm" dot>{error} Error</Badge>}
+        {connected === 0 && error === 0 && <Badge variant="default" size="sm">{total} Added</Badge>}
+      </>
+    );
+  };
+
+  return (
+    <Link href={`/dashboard/media-providers/${kind}/${provider.id}`} className="group">
+      <Card
+        padding="xs"
+        className={`h-full hover:bg-black/[0.01] dark:hover:bg-white/[0.01] transition-colors cursor-pointer ${allDisabled ? "opacity-50" : ""}`}
+      >
+        <div className="flex min-w-0 items-center justify-between gap-3">
+          <div className="flex min-w-0 items-center gap-3">
+            <div
+              className="size-8 rounded-lg flex items-center justify-center shrink-0"
+              style={{ backgroundColor: `${provider.color?.length > 7 ? provider.color : (provider.color ?? "#888") + "15"}` }}
+            >
+              <ProviderIcon
+                src={`/providers/${provider.id}.png`}
+                alt={provider.name}
+                size={30}
+                className="object-contain rounded-lg max-w-[30px] max-h-[30px]"
+                fallbackText={provider.textIcon || provider.id.slice(0, 2).toUpperCase()}
+                fallbackColor={provider.color}
+              />
+            </div>
+            <div className="min-w-0">
+              <h3 className="font-semibold text-sm">{provider.name}</h3>
+              <div className="flex items-center gap-2 mt-0.5 flex-wrap">
+                {isCustom && <Badge variant="default" size="sm">Custom</Badge>}
+                {renderStatus()}
+              </div>
+            </div>
+          </div>
+          {total > 0 && (
+            <div
+              className="shrink-0 opacity-100 transition-opacity sm:opacity-0 sm:group-hover:opacity-100"
+              onClick={handleToggleClick}
+            >
+              <Toggle
+                size="sm"
+                checked={!allDisabled}
+                onChange={() => {}}
+                title={allDisabled ? "Enable provider" : "Disable provider"}
+              />
+            </div>
+          )}
+        </div>
+      </Card>
+    </Link>
+  );
+}
+
+function ComboList({ combos }) {
+  if (combos.length === 0) return null;
+  return (
+    <div className="flex flex-col gap-2">
+      {combos.map((combo) => (
+        <Link key={combo.id} href={`/dashboard/media-providers/combo/${combo.id}`}>
+          <Card padding="xs" className="hover:bg-black/[0.02] dark:hover:bg-white/[0.02] transition-colors cursor-pointer">
+            <div className="flex min-w-0 items-center gap-3">
+              <span className="material-symbols-outlined text-primary text-[18px]">layers</span>
+              <code className="text-sm font-mono font-medium flex-1 truncate">{combo.name}</code>
+              <div className="flex flex-wrap items-center gap-1 sm:shrink-0">
+                {combo.models.slice(0, 6).map((entry, i) => {
+                  const pid = typeof entry === "string" ? entry.split("/")[0] : "";
+                  const p = AI_PROVIDERS[pid];
+                  return (
+                    <div key={`${entry}-${i}`} title={p?.name || entry} className="size-5 rounded flex items-center justify-center" style={{ backgroundColor: `${(p?.color ?? "#888")}15` }}>
+                      <ProviderIcon
+                        src={`/providers/${pid}.png`}
+                        alt={p?.name || pid}
+                        size={18}
+                        className="object-contain rounded max-w-[18px] max-h-[18px]"
+                        fallbackText={p?.textIcon || pid.slice(0, 2).toUpperCase()}
+                        fallbackColor={p?.color}
+                      />
+                    </div>
+                  );
+                })}
+                {combo.models.length > 6 && (
+                  <span className="text-[10px] text-text-muted ml-1">+{combo.models.length - 6}</span>
+                )}
+              </div>
+              <span className="text-[11px] text-text-muted shrink-0">{combo.models.length}</span>
+              <span className="material-symbols-outlined text-text-muted text-[16px]">chevron_right</span>
+            </div>
+          </Card>
+        </Link>
+      ))}
+    </div>
+  );
+}
+
+export default function MediaProviderKindPage() {
+  const { kind } = useParams();
+  const router = useRouter();
+  const [connections, setConnections] = useState([]);
+  const [customNodes, setCustomNodes] = useState([]);
+  const [combos, setCombos] = useState([]);
+  const [showAddCustomEmbedding, setShowAddCustomEmbedding] = useState(false);
+
+  // webSearch/webFetch listing pages are merged into /web
+  useEffect(() => {
+    if (kind === "webSearch" || kind === "webFetch") {
+      router.replace("/dashboard/media-providers/web");
+    }
+  }, [kind, router]);
+
+  const kindConfig = MEDIA_PROVIDER_KINDS.find((k) => k.id === kind);
+  const isEmbedding = kind === "embedding";
+  const supportsCombo = COMBO_KINDS.has(kind);
+
+  useEffect(() => {
+    if (!kindConfig) return;
+    fetch("/api/providers", { cache: "no-store" })
+      .then((r) => r.json())
+      .then((d) => setConnections(d.connections || []))
+      .catch(() => {});
+    if (isEmbedding) {
+      fetch("/api/provider-nodes", { cache: "no-store" })
+        .then((r) => r.json())
+        .then((d) => setCustomNodes((d.nodes || []).filter((n) => n.type === "custom-embedding")))
+        .catch(() => {});
+    }
+    if (supportsCombo) {
+      fetch("/api/combos", { cache: "no-store" })
+        .then((r) => r.json())
+        .then((d) => setCombos(d.combos || []))
+        .catch(() => {});
+    }
+  }, [isEmbedding, supportsCombo, kindConfig]);
+
+  if (!kindConfig) return notFound();
+
+  const providers = getProvidersByKind(kind);
+  const kindCombos = combos.filter((c) => c.kind === kind);
+
+  // Map custom nodes to MediaProviderCard shape
+  const customProviders = customNodes.map((n) => ({
+    id: n.id,
+    name: n.name || "Custom Embedding",
+    color: "#6366F1",
+    textIcon: "CE",
+  }));
+
+  const allProviders = [...providers, ...customProviders];
+
+  const handleToggleProvider = async (providerId, newActive) => {
+    const providerConns = connections.filter((c) => c.provider === providerId);
+    setConnections((prev) =>
+      prev.map((c) => (c.provider === providerId ? { ...c, isActive: newActive } : c))
+    );
+    await Promise.allSettled(
+      providerConns.map((c) =>
+        fetch(`/api/providers/${c.id}`, {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ isActive: newActive }),
+        })
+      )
+    );
+  };
+
+  const handleCreateCombo = async () => {
+    const base = COMBO_BASE_NAMES[kind] || `${kind}-combo`;
+    let name = base;
+    let i = 1;
+    const existing = new Set(combos.map((c) => c.name));
+    while (existing.has(name)) { name = `${base}-${i++}`; }
+    const res = await fetch("/api/combos", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name, models: [], kind }),
+    });
+    if (res.ok) {
+      const created = await res.json();
+      router.push(`/dashboard/media-providers/combo/${created.id}`);
+    } else {
+      const err = await res.json();
+      alert(err.error || "Failed to create combo");
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-6">
+      {(isEmbedding || supportsCombo) && (
+        <div className="flex items-center justify-end gap-2">
+          {supportsCombo && (
+            <Button size="sm" icon="add" onClick={handleCreateCombo}>Create Combo</Button>
+          )}
+          {isEmbedding && (
+            <Button size="sm" icon="add" onClick={() => setShowAddCustomEmbedding(true)}>
+              Add Custom Embedding
+            </Button>
+          )}
+        </div>
+      )}
+
+      {supportsCombo && kindCombos.length > 0 && (
+        <ComboList combos={kindCombos} />
+      )}
+
+      {allProviders.length === 0 ? (
+        <div className="text-center py-12 border border-dashed border-border rounded-xl text-text-muted text-sm">
+          No providers support <strong>{kindConfig.label}</strong> yet.
+        </div>
+      ) : (
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
+          {providers.map((provider) => (
+            <MediaProviderCard
+              key={provider.id}
+              provider={provider}
+              kind={kind}
+              connections={connections}
+              onToggle={handleToggleProvider}
+            />
+          ))}
+          {customProviders.map((provider) => (
+            <MediaProviderCard
+              key={provider.id}
+              provider={provider}
+              kind={kind}
+              connections={connections}
+              isCustom
+              onToggle={handleToggleProvider}
+            />
+          ))}
+        </div>
+      )}
+
+      {isEmbedding && (
+        <AddCustomEmbeddingModal
+          isOpen={showAddCustomEmbedding}
+          onClose={() => setShowAddCustomEmbedding(false)}
+          onCreated={(node) => {
+            setCustomNodes((prev) => [...prev, node]);
+            setShowAddCustomEmbedding(false);
+          }}
+        />
+      )}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/media-providers/combo/[id]/page.js b/src/app/(dashboard)/dashboard/media-providers/combo/[id]/page.js
new file mode 100644
index 0000000..45c1546
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/media-providers/combo/[id]/page.js
@@ -0,0 +1,410 @@
+"use client";
+
+import { useParams, notFound, useRouter } from "next/navigation";
+import { useEffect, useState } from "react";
+import Link from "next/link";
+import { Card, Button, Input, Toggle, ModelSelectModal } from "@/shared/components";
+import ProviderIcon from "@/shared/components/ProviderIcon";
+import { AI_PROVIDERS, MEDIA_PROVIDER_KINDS } from "@/shared/constants/providers";
+
+// Parse "providerId/model" or just "providerId" → { providerId, model }
+function parseModelEntry(entry) {
+  if (typeof entry !== "string") return { providerId: "", model: "" };
+  const idx = entry.indexOf("/");
+  if (idx < 0) return { providerId: entry, model: "" };
+  return { providerId: entry.slice(0, idx), model: entry.slice(idx + 1) };
+}
+
+const VALID_NAME_REGEX = /^[a-zA-Z0-9_.\-]+$/;
+
+const KIND_LABELS = {
+  webSearch: "Web Search",
+  webFetch: "Web Fetch",
+  image: "Text to Image",
+  tts: "Text To Speech",
+};
+
+const EXAMPLE_PATHS = {
+  webSearch: "/v1/search",
+  webFetch: "/v1/web/fetch",
+  image: "/v1/images/generations",
+  tts: "/v1/audio/speech",
+};
+
+const EXAMPLE_BODIES = {
+  webSearch: (n) => ({ model: n, query: "What is the latest news about AI?", search_type: "web", max_results: 5 }),
+  webFetch: (n) => ({ model: n, url: "https://example.com", format: "markdown" }),
+  image: (n) => ({ model: n, prompt: "A cute cat playing piano", n: 1, size: "1024x1024" }),
+  tts: (n) => ({ model: n, input: "Hello, this is a test.", voice: "alloy" }),
+};
+
+// Map combo.kind → listing route to go back to
+function getListingHref(kind) {
+  if (kind === "webSearch" || kind === "webFetch") return "/dashboard/media-providers/web";
+  return `/dashboard/media-providers/${kind}`;
+}
+
+export default function ComboDetailPage() {
+  const { id } = useParams();
+  const router = useRouter();
+  const [combo, setCombo] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [name, setName] = useState("");
+  const [nameError, setNameError] = useState("");
+  const [providers, setProviders] = useState([]);
+  const [roundRobin, setRoundRobin] = useState(false);
+  const [showPicker, setShowPicker] = useState(false);
+  const [logs, setLogs] = useState([]);
+  const [testing, setTesting] = useState(false);
+  const [testResult, setTestResult] = useState(null);
+  const [testError, setTestError] = useState("");
+  const [apiKey, setApiKey] = useState("");
+  const [connections, setConnections] = useState([]);
+  const [modelAliases, setModelAliases] = useState({});
+
+  const fetchAll = async () => {
+    try {
+      const [comboRes, settingsRes, logsRes, keysRes, connsRes, aliasesRes] = await Promise.all([
+        fetch(`/api/combos/${id}`, { cache: "no-store" }),
+        fetch("/api/settings", { cache: "no-store" }),
+        fetch("/api/usage/logs", { cache: "no-store" }),
+        fetch("/api/keys", { cache: "no-store" }),
+        fetch("/api/providers", { cache: "no-store" }),
+        fetch("/api/models/alias", { cache: "no-store" }),
+      ]);
+      if (aliasesRes.ok) setModelAliases((await aliasesRes.json()).aliases || {});
+      if (keysRes.ok) {
+        const k = await keysRes.json();
+        setApiKey((k.keys || []).find((x) => x.isActive !== false)?.key || "");
+      }
+      if (connsRes.ok) setConnections((await connsRes.json()).connections || []);
+      if (!comboRes.ok) { setCombo(null); setLoading(false); return; }
+      const c = await comboRes.json();
+      setCombo(c);
+      setName(c.name);
+      setProviders(c.models || []);
+      const s = settingsRes.ok ? await settingsRes.json() : {};
+      setRoundRobin(s.comboStrategies?.[c.name]?.fallbackStrategy === "round-robin");
+      const allLogs = logsRes.ok ? await logsRes.json() : [];
+      setLogs(allLogs.filter((l) => typeof l === "string" && l.includes(c.name)).slice(0, 50));
+    } catch { /* noop */ }
+    setLoading(false);
+  };
+
+  // eslint-disable-next-line react-hooks/set-state-in-effect
+  useEffect(() => { fetchAll(); }, [id]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const validateName = (v) => {
+    if (!v.trim()) { setNameError("Name is required"); return false; }
+    if (!VALID_NAME_REGEX.test(v)) { setNameError("Only letters, numbers, -, _ and ."); return false; }
+    setNameError("");
+    return true;
+  };
+
+  const saveCombo = async (patch) => {
+    const res = await fetch(`/api/combos/${id}`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(patch),
+    });
+    if (!res.ok) { const err = await res.json(); alert(err.error || "Failed to save"); return false; }
+    return true;
+  };
+
+  const handleSaveName = async () => {
+    if (!validateName(name)) return;
+    if (name === combo.name) return;
+    const ok = await saveCombo({ name });
+    if (ok) await fetchAll();
+  };
+
+  const handleAddModel = async (model) => {
+    const value = model?.value || model;
+    if (!value || providers.includes(value)) return;
+    const next = [...providers, value];
+    setProviders(next);
+    await saveCombo({ models: next });
+  };
+
+  const handleDeselectModel = async (model) => {
+    const value = model?.value || model;
+    if (!value || !providers.includes(value)) return;
+    const next = providers.filter((p) => p !== value);
+    setProviders(next);
+    await saveCombo({ models: next });
+  };
+
+  const handleRemoveProvider = async (idx) => {
+    const next = providers.filter((_, i) => i !== idx);
+    setProviders(next);
+    await saveCombo({ models: next });
+  };
+
+  const handleMove = async (idx, dir) => {
+    const next = [...providers];
+    const swap = idx + dir;
+    if (swap < 0 || swap >= next.length) return;
+    [next[idx], next[swap]] = [next[swap], next[idx]];
+    setProviders(next);
+    await saveCombo({ models: next });
+  };
+
+  const handleToggleRoundRobin = async (enabled) => {
+    setRoundRobin(enabled);
+    const settingsRes = await fetch("/api/settings", { cache: "no-store" });
+    const s = settingsRes.ok ? await settingsRes.json() : {};
+    const updated = { ...(s.comboStrategies || {}) };
+    if (enabled) updated[combo.name] = { fallbackStrategy: "round-robin" };
+    else delete updated[combo.name];
+    await fetch("/api/settings", {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ comboStrategies: updated }),
+    });
+  };
+
+  const handleDelete = async () => {
+    if (!confirm(`Delete combo "${combo.name}"?`)) return;
+    const res = await fetch(`/api/combos/${id}`, { method: "DELETE" });
+    if (res.ok) router.push(getListingHref(combo.kind));
+  };
+
+  const handleTest = async () => {
+    setTesting(true);
+    setTestResult(null);
+    setTestError("");
+    if (testResult?.audioUrl) { try { URL.revokeObjectURL(testResult.audioUrl); } catch {} }
+    if (testResult?.imageUrl?.startsWith("blob:")) { try { URL.revokeObjectURL(testResult.imageUrl); } catch {} }
+    const start = Date.now();
+    try {
+      const path = EXAMPLE_PATHS[combo.kind];
+      const body = EXAMPLE_BODIES[combo.kind](combo.name);
+      const headers = { "Content-Type": "application/json" };
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+      const res = await fetch(`/api${path}`, { method: "POST", headers, body: JSON.stringify(body) });
+      const latencyMs = Date.now() - start;
+      if (!res.ok) {
+        const d = await res.json().catch(() => ({}));
+        setTestError(d?.error?.message || d?.error || `HTTP ${res.status}`);
+        setTestResult({ json: JSON.stringify(d, null, 2), latencyMs });
+        return;
+      }
+      const ctype = res.headers.get("content-type") || "";
+      // Binary image
+      if (ctype.startsWith("image/")) {
+        const blob = await res.blob();
+        setTestResult({ imageUrl: URL.createObjectURL(blob), latencyMs });
+        return;
+      }
+      // Binary audio
+      if (ctype.startsWith("audio/") || ctype === "application/octet-stream") {
+        const blob = await res.blob();
+        setTestResult({ audioUrl: URL.createObjectURL(blob), latencyMs });
+        return;
+      }
+      // JSON — could be image (data[0].b64_json/url) or generic
+      const data = await res.json();
+      const first = data?.data?.[0];
+      const imageUrl = first?.b64_json
+        ? `data:image/png;base64,${first.b64_json}`
+        : (first?.url || "");
+      setTestResult({ json: JSON.stringify(maskB64(data), null, 2), imageUrl, latencyMs });
+    } catch (e) {
+      setTestError(e.message || "Network error");
+    }
+    setTesting(false);
+  };
+
+  // Mask large b64_json strings to keep JSON view readable
+  function maskB64(obj) {
+    if (!obj || typeof obj !== "object") return obj;
+    if (Array.isArray(obj)) return obj.map(maskB64);
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+      out[k] = (k === "b64_json" && typeof v === "string" && v.length > 100)
+        ? `<${v.length} chars base64>`
+        : maskB64(v);
+    }
+    return out;
+  }
+
+  if (loading) return <div className="text-text-muted text-sm">Loading...</div>;
+  if (!combo) return notFound();
+
+  const kindLabel = KIND_LABELS[combo.kind] || MEDIA_PROVIDER_KINDS.find((k) => k.id === combo.kind)?.label || "Combo";
+  const examplePath = EXAMPLE_PATHS[combo.kind];
+  const exampleBody = combo.kind && EXAMPLE_BODIES[combo.kind] ? EXAMPLE_BODIES[combo.kind](combo.name) : null;
+  const curlExample = examplePath
+    ? `curl -X POST http://localhost:20128${examplePath} \\\n  -H "Content-Type: application/json" \\\n  -H "Authorization: Bearer ${apiKey || "YOUR_KEY"}" \\\n  -d '${JSON.stringify(exampleBody)}'`
+    : "";
+  const backHref = getListingHref(combo.kind);
+
+  return (
+    <div className="flex flex-col gap-6">
+      {/* Header */}
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+        <div className="flex items-center gap-3 min-w-0">
+          <Link href={backHref} className="text-text-muted hover:text-primary">
+            <span className="material-symbols-outlined">arrow_back</span>
+          </Link>
+          <div className="size-10 rounded-lg bg-primary/10 flex items-center justify-center">
+            <span className="material-symbols-outlined text-primary">layers</span>
+          </div>
+          <div className="min-w-0">
+            <p className="text-xs text-text-muted">{kindLabel} Combo</p>
+            <code className="text-lg font-semibold font-mono">{combo.name}</code>
+          </div>
+        </div>
+        <Button variant="outline" icon="delete" onClick={handleDelete} className="text-red-500 border-red-200 hover:bg-red-50">
+          Delete
+        </Button>
+      </div>
+
+      {/* Settings Card */}
+      <Card>
+        <h2 className="text-lg font-semibold mb-3">Settings</h2>
+        <div className="flex flex-col gap-4">
+          <div>
+            <Input label="Combo Name" value={name} onChange={(e) => { setName(e.target.value); validateName(e.target.value); }} onBlur={handleSaveName} error={nameError} />
+            <p className="text-[10px] text-text-muted mt-0.5">Only letters, numbers, -, _ and .</p>
+          </div>
+          <div className="flex items-center justify-between">
+            <div>
+              <p className="text-sm font-medium">Round Robin</p>
+              <p className="text-xs text-text-muted">Rotate providers across requests instead of strict fallback order.</p>
+            </div>
+            <Toggle checked={roundRobin} onChange={handleToggleRoundRobin} />
+          </div>
+        </div>
+      </Card>
+
+      {/* Providers Card */}
+      <Card>
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between mb-3">
+          <div>
+            <h2 className="text-lg font-semibold">Providers</h2>
+            <p className="text-xs text-text-muted">Tried in order (top-down) or rotated when round-robin is on.</p>
+          </div>
+          <Button size="sm" icon="add" onClick={() => setShowPicker(true)}>Add Provider</Button>
+        </div>
+        {providers.length === 0 ? (
+          <div className="text-center py-6 border border-dashed border-border rounded-lg text-text-muted text-sm">
+            No providers yet.
+          </div>
+        ) : (
+          <div className="flex flex-col gap-2">
+            {providers.map((entry, idx) => {
+              const { providerId, model } = parseModelEntry(entry);
+              const p = AI_PROVIDERS[providerId];
+              return (
+                <div key={`${entry}-${idx}`} className="flex items-center gap-3 p-2 rounded-lg bg-black/[0.02] dark:bg-white/[0.02]">
+                  <span className="text-xs text-text-muted w-5 text-center">{idx + 1}</span>
+                  <ProviderIcon
+                    src={`/providers/${providerId}.png`}
+                    alt={p?.name || providerId}
+                    size={24}
+                    className="object-contain rounded shrink-0"
+                    fallbackText={p?.textIcon || providerId.slice(0, 2).toUpperCase()}
+                    fallbackColor={p?.color}
+                  />
+                  <div className="min-w-0 flex-1">
+                    <div className="text-sm font-medium truncate">{p?.name || providerId}</div>
+                    {model && <code className="text-[10px] text-text-muted font-mono truncate block">{model}</code>}
+                  </div>
+                  <div className="flex items-center gap-0.5">
+                    <button onClick={() => handleMove(idx, -1)} disabled={idx === 0} className={`p-1 rounded ${idx === 0 ? "text-text-muted/20" : "text-text-muted hover:text-primary hover:bg-black/5"}`} title="Move up">
+                      <span className="material-symbols-outlined text-[16px]">arrow_upward</span>
+                    </button>
+                    <button onClick={() => handleMove(idx, 1)} disabled={idx === providers.length - 1} className={`p-1 rounded ${idx === providers.length - 1 ? "text-text-muted/20" : "text-text-muted hover:text-primary hover:bg-black/5"}`} title="Move down">
+                      <span className="material-symbols-outlined text-[16px]">arrow_downward</span>
+                    </button>
+                    <button onClick={() => handleRemoveProvider(idx)} className="p-1 rounded text-text-muted hover:text-red-500 hover:bg-red-500/10" title="Remove">
+                      <span className="material-symbols-outlined text-[16px]">close</span>
+                    </button>
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </Card>
+
+      {/* Test Example Card */}
+      {combo.kind && examplePath && (
+        <Card>
+          <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between mb-3">
+            <h2 className="text-lg font-semibold">Test Example</h2>
+            <Button size="sm" icon="play_arrow" onClick={handleTest} disabled={testing || providers.length === 0}>
+              {testing ? "Running..." : "Run"}
+            </Button>
+          </div>
+          <pre className="text-xs font-mono bg-black/[0.03] dark:bg-white/[0.03] p-3 rounded-lg overflow-x-auto whitespace-pre-wrap break-all">
+            {curlExample}
+          </pre>
+          {testError && (
+            <p className="mt-3 text-xs text-red-500 break-words">{testError}</p>
+          )}
+          {testResult && (
+            <div className="mt-3 flex flex-col gap-3">
+              {testResult.latencyMs != null && (
+                <span className="text-[11px] text-text-muted">⚡ {testResult.latencyMs}ms</span>
+              )}
+              {testResult.imageUrl && (
+                <div>
+                  <div className="flex items-center justify-end mb-1.5">
+                    <a href={testResult.imageUrl} download="image.png" className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors">
+                      <span className="material-symbols-outlined text-[14px]">download</span>
+                      Download
+                    </a>
+                  </div>
+                  <img src={testResult.imageUrl} alt="Generated" className="max-w-full rounded-lg border border-border" />
+                </div>
+              )}
+              {testResult.audioUrl && (
+                <div>
+                  <div className="flex items-center justify-end mb-1.5">
+                    <a href={testResult.audioUrl} download="speech.mp3" className="inline-flex items-center gap-1 text-xs text-text-muted hover:text-primary transition-colors">
+                      <span className="material-symbols-outlined text-[14px]">download</span>
+                      Download
+                    </a>
+                  </div>
+                  <audio controls src={testResult.audioUrl} className="w-full" />
+                </div>
+              )}
+              {testResult.json && (
+                <pre className="text-xs font-mono bg-black/[0.03] dark:bg-white/[0.03] p-3 rounded-lg overflow-auto max-h-[300px] whitespace-pre-wrap break-all">
+                  {testResult.json}
+                </pre>
+              )}
+            </div>
+          )}
+        </Card>
+      )}
+
+      {/* Usage Logs Card */}
+      <Card>
+        <h2 className="text-lg font-semibold mb-3">Usage Logs</h2>
+        {logs.length === 0 ? (
+          <p className="text-xs text-text-muted italic">No usage yet.</p>
+        ) : (
+          <pre className="text-[11px] font-mono bg-black/[0.03] dark:bg-white/[0.03] p-3 rounded-lg overflow-auto max-h-[400px] whitespace-pre-wrap">
+            {logs.join("\n")}
+          </pre>
+        )}
+      </Card>
+
+      <ModelSelectModal
+        isOpen={showPicker}
+        onClose={() => setShowPicker(false)}
+        onSelect={handleAddModel}
+        onDeselect={handleDeselectModel}
+        activeProviders={connections}
+        modelAliases={modelAliases}
+        title={`Add ${kindLabel} Model`}
+        kindFilter={combo.kind}
+        addedModelValues={providers}
+        closeOnSelect={false}
+      />
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/media-providers/web/page.js b/src/app/(dashboard)/dashboard/media-providers/web/page.js
new file mode 100644
index 0000000..755126d
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/media-providers/web/page.js
@@ -0,0 +1,209 @@
+"use client";
+
+import Link from "next/link";
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { Card, Badge, Button } from "@/shared/components";
+import ProviderIcon from "@/shared/components/ProviderIcon";
+import { AI_PROVIDERS, getProvidersByKind } from "@/shared/constants/providers";
+
+function getEffectiveStatus(conn) {
+  const isCooldown = Object.entries(conn).some(
+    ([k, v]) => k.startsWith("modelLock_") && v && new Date(v).getTime() > Date.now()
+  );
+  return conn.testStatus === "unavailable" && !isCooldown ? "active" : conn.testStatus;
+}
+
+function ProviderCard({ provider, kind, connections }) {
+  const providerInfo = AI_PROVIDERS[provider.id];
+  const isNoAuth = !!providerInfo?.noAuth;
+  const providerConns = connections.filter((c) => c.provider === provider.id);
+  const connected = providerConns.filter((c) => { const s = getEffectiveStatus(c); return s === "active" || s === "success"; }).length;
+  const error = providerConns.filter((c) => { const s = getEffectiveStatus(c); return s === "error" || s === "expired" || s === "unavailable"; }).length;
+  const total = providerConns.length;
+  const allDisabled = total > 0 && providerConns.every((c) => c.isActive === false);
+
+  const renderStatus = () => {
+    if (isNoAuth) return <Badge variant="success" size="sm">Ready</Badge>;
+    if (allDisabled) return <Badge variant="default" size="sm">Disabled</Badge>;
+    if (total === 0) return <span className="text-xs text-text-muted">No connections</span>;
+    return (
+      <>
+        {connected > 0 && <Badge variant="success" size="sm" dot>{connected} Connected</Badge>}
+        {error > 0 && <Badge variant="error" size="sm" dot>{error} Error</Badge>}
+        {connected === 0 && error === 0 && <Badge variant="default" size="sm">{total} Added</Badge>}
+      </>
+    );
+  };
+
+  return (
+    <Link href={`/dashboard/media-providers/${kind}/${provider.id}`} className="group">
+      <Card padding="xs" className={`h-full hover:bg-black/[0.01] dark:hover:bg-white/[0.01] transition-colors cursor-pointer ${allDisabled ? "opacity-50" : ""}`}>
+        <div className="flex min-w-0 items-center gap-3">
+          <div
+            className="size-8 rounded-lg flex items-center justify-center shrink-0"
+            style={{ backgroundColor: `${provider.color?.length > 7 ? provider.color : (provider.color ?? "#888") + "15"}` }}
+          >
+            <ProviderIcon
+              src={`/providers/${provider.id}.png`}
+              alt={provider.name}
+              size={30}
+              className="object-contain rounded-lg max-w-[30px] max-h-[30px]"
+              fallbackText={provider.textIcon || provider.id.slice(0, 2).toUpperCase()}
+              fallbackColor={provider.color}
+            />
+          </div>
+          <div>
+            <h3 className="font-semibold text-sm">{provider.name}</h3>
+            <div className="flex items-center gap-2 mt-0.5 flex-wrap">{renderStatus()}</div>
+          </div>
+        </div>
+      </Card>
+    </Link>
+  );
+}
+
+function ComboList({ combos }) {
+  if (combos.length === 0) {
+    return <p className="text-xs text-text-muted italic">No combos yet.</p>;
+  }
+  return (
+    <div className="flex flex-col gap-2">
+      {combos.map((combo) => (
+        <Link key={combo.id} href={`/dashboard/media-providers/combo/${combo.id}`}>
+          <Card padding="xs" className="hover:bg-black/[0.02] dark:hover:bg-white/[0.02] transition-colors cursor-pointer">
+            <div className="flex min-w-0 items-center gap-3">
+              <span className="material-symbols-outlined text-primary text-[18px]">layers</span>
+              <code className="text-sm font-mono font-medium flex-1 truncate">{combo.name}</code>
+              {/* Provider icons preview */}
+              <div className="flex flex-wrap items-center gap-1 sm:shrink-0">
+                {combo.models.slice(0, 6).map((entry, i) => {
+                  const pid = typeof entry === "string" ? entry.split("/")[0] : "";
+                  const p = AI_PROVIDERS[pid];
+                  return (
+                    <div key={`${entry}-${i}`} title={p?.name || entry} className="size-5 rounded flex items-center justify-center" style={{ backgroundColor: `${(p?.color ?? "#888")}15` }}>
+                      <ProviderIcon
+                        src={`/providers/${pid}.png`}
+                        alt={p?.name || pid}
+                        size={18}
+                        className="object-contain rounded max-w-[18px] max-h-[18px]"
+                        fallbackText={p?.textIcon || pid.slice(0, 2).toUpperCase()}
+                        fallbackColor={p?.color}
+                      />
+                    </div>
+                  );
+                })}
+                {combo.models.length > 6 && (
+                  <span className="text-[10px] text-text-muted ml-1">+{combo.models.length - 6}</span>
+                )}
+              </div>
+              <span className="text-[11px] text-text-muted shrink-0">{combo.models.length}</span>
+              <span className="material-symbols-outlined text-text-muted text-[16px]">chevron_right</span>
+            </div>
+          </Card>
+        </Link>
+      ))}
+    </div>
+  );
+}
+
+function Section({ title, icon, kind, providers, connections, combos, onCreateCombo }) {
+  return (
+    <div>
+      {/* Header — title left, Create Combo right */}
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between mb-3">
+        <div className="flex flex-wrap items-center gap-2">
+          <span className="material-symbols-outlined text-primary">{icon}</span>
+          <h2 className="text-base font-semibold">{title}</h2>
+          <span className="text-xs text-text-muted">({providers.length} providers · {combos.length} combos)</span>
+        </div>
+        <Button size="sm" icon="add" onClick={onCreateCombo}>Create Combo</Button>
+      </div>
+
+      {/* Combos — top */}
+      {combos.length > 0 && (
+        <div className="mb-4">
+          <ComboList combos={combos} />
+        </div>
+      )}
+
+      {/* Providers grid — bottom */}
+      {providers.length === 0 ? (
+        <div className="text-center py-8 border border-dashed border-border rounded-xl text-text-muted text-sm">
+          No providers.
+        </div>
+      ) : (
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
+          {providers.map((p) => (
+            <ProviderCard key={p.id} provider={p} kind={kind} connections={connections} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function WebProvidersPage() {
+  const router = useRouter();
+  const [connections, setConnections] = useState([]);
+  const [combos, setCombos] = useState([]);
+
+  const fetchAll = async () => {
+    try {
+      const [connsRes, combosRes] = await Promise.all([
+        fetch("/api/providers", { cache: "no-store" }),
+        fetch("/api/combos", { cache: "no-store" }),
+      ]);
+      if (connsRes.ok) setConnections((await connsRes.json()).connections || []);
+      if (combosRes.ok) setCombos((await combosRes.json()).combos || []);
+    } catch { /* noop */ }
+  };
+
+  // eslint-disable-next-line react-hooks/set-state-in-effect
+  useEffect(() => { fetchAll(); }, []);
+
+  const searchProviders = getProvidersByKind("webSearch");
+  const fetchProviders = getProvidersByKind("webFetch");
+  const searchCombos = combos.filter((c) => c.kind === "webSearch");
+  const fetchCombos = combos.filter((c) => c.kind === "webFetch");
+
+  const handleCreateCombo = async (kind) => {
+    // Generate unique default name
+    const base = kind === "webSearch" ? "search-combo" : "fetch-combo";
+    let name = base;
+    let i = 1;
+    const existing = new Set(combos.map((c) => c.name));
+    while (existing.has(name)) { name = `${base}-${i++}`; }
+    const res = await fetch("/api/combos", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name, models: [], kind }),
+    });
+    if (res.ok) {
+      const created = await res.json();
+      router.push(`/dashboard/media-providers/combo/${created.id}`);
+    } else {
+      const err = await res.json();
+      alert(err.error || "Failed to create combo");
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-8">
+      <Section
+        title="Web Search" icon="search" kind="webSearch"
+        providers={searchProviders} connections={connections} combos={searchCombos}
+        onCreateCombo={() => handleCreateCombo("webSearch")}
+      />
+
+      {/* Divider between sections */}
+      <div className="border-t border-border" />
+
+      <Section
+        title="Web Fetch" icon="travel_explore" kind="webFetch"
+        providers={fetchProviders} connections={connections} combos={fetchCombos}
+        onCreateCombo={() => handleCreateCombo("webFetch")}
+      />
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/mitm/MitmPageClient.js b/src/app/(dashboard)/dashboard/mitm/MitmPageClient.js
new file mode 100644
index 0000000..2b0169b
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/mitm/MitmPageClient.js
@@ -0,0 +1,117 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { MITM_TOOLS } from "@/shared/constants/cliTools";
+import { getModelsByProviderId } from "@/shared/constants/models";
+import { isOpenAICompatibleProvider, isAnthropicCompatibleProvider } from "@/shared/constants/providers";
+import { MitmServerCard, MitmToolCard } from "@/app/(dashboard)/dashboard/cli-tools/components";
+
+export default function MitmPageClient() {
+  const [connections, setConnections] = useState([]);
+  const [apiKeys, setApiKeys] = useState([]);
+  const [modelAliases, setModelAliases] = useState({});
+  const [cloudEnabled, setCloudEnabled] = useState(false);
+  const [expandedTool, setExpandedTool] = useState(null);
+  const [mitmStatus, setMitmStatus] = useState({ running: false, certExists: false, dnsStatus: {}, hasCachedPassword: false });
+
+  useEffect(() => {
+    fetchConnections();
+    fetchApiKeys();
+    fetchAliases();
+    fetchCloudSettings();
+  }, []);
+
+  const fetchConnections = async () => {
+    try {
+      const res = await fetch("/api/providers");
+      if (res.ok) {
+        const data = await res.json();
+        setConnections(data.connections || []);
+      }
+    } catch { /* ignore */ }
+  };
+
+  const fetchApiKeys = async () => {
+    try {
+      const res = await fetch("/api/keys");
+      if (res.ok) {
+        const data = await res.json();
+        setApiKeys(data.keys || []);
+      }
+    } catch { /* ignore */ }
+  };
+
+  const fetchAliases = async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      if (res.ok) {
+        const data = await res.json();
+        setModelAliases(data.aliases || {});
+      }
+    } catch { /* ignore */ }
+  };
+
+  const fetchCloudSettings = async () => {
+    try {
+      const res = await fetch("/api/settings");
+      if (res.ok) {
+        const data = await res.json();
+        setCloudEnabled(data.cloudEnabled || false);
+      }
+    } catch { /* ignore */ }
+  };
+
+  const getActiveProviders = () => connections.filter(c => c.isActive !== false);
+
+  const hasActiveProviders = () => {
+    const active = getActiveProviders();
+    return active.some(conn =>
+      getModelsByProviderId(conn.provider).length > 0 ||
+      isOpenAICompatibleProvider(conn.provider) ||
+      isAnthropicCompatibleProvider(conn.provider)
+    );
+  };
+
+  const mitmTools = Object.entries(MITM_TOOLS);
+
+  return (
+    <div className="flex w-full flex-col gap-6">
+      <div className="flex items-start gap-2 px-3 py-2 rounded-lg bg-yellow-500/10 border border-yellow-500/30">
+        <span className="material-symbols-outlined text-[16px] text-yellow-500 mt-0.5 shrink-0">warning</span>
+        <p className="text-xs text-red-600 dark:text-yellow-400 leading-relaxed">
+          ⚠️ MITM intercepts HTTPS traffic of IDE tools (Antigravity, GitHub Copilot, Kiro) via local CA to redirect requests to your providers. May violate ToS → account ban. Use at your own risk.
+        </p>
+      </div>
+
+      {/* MITM Server Card */}
+      <MitmServerCard
+        apiKeys={apiKeys}
+        cloudEnabled={cloudEnabled}
+        onStatusChange={setMitmStatus}
+      />
+
+      {/* Tool Cards */}
+      <div className="grid gap-3 sm:gap-4">
+        {mitmTools.map(([toolId, tool]) => (
+          <MitmToolCard
+            key={toolId}
+            tool={tool}
+            isExpanded={expandedTool === toolId}
+            onToggle={() => setExpandedTool(expandedTool === toolId ? null : toolId)}
+            serverRunning={mitmStatus.running}
+            dnsActive={mitmStatus.dnsStatus?.[toolId] || false}
+            hasCachedPassword={mitmStatus.hasCachedPassword || false}
+            needsSudoPassword={mitmStatus.needsSudoPassword !== false}
+            isWin={mitmStatus.isWin === true}
+            apiKeys={apiKeys}
+            activeProviders={getActiveProviders()}
+            hasActiveProviders={hasActiveProviders()}
+            modelAliases={modelAliases}
+            cloudEnabled={cloudEnabled}
+            onDnsChange={(data) => setMitmStatus(prev => ({ ...prev, dnsStatus: data.dnsStatus ?? prev.dnsStatus }))}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/mitm/page.js b/src/app/(dashboard)/dashboard/mitm/page.js
new file mode 100644
index 0000000..03d5f39
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/mitm/page.js
@@ -0,0 +1,5 @@
+import MitmPageClient from "./MitmPageClient";
+
+export default function MitmPage() {
+  return <MitmPageClient />;
+}
diff --git a/src/app/(dashboard)/dashboard/page.js b/src/app/(dashboard)/dashboard/page.js
new file mode 100644
index 0000000..6a94a1f
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/page.js
@@ -0,0 +1,7 @@
+import { getMachineId } from "@/shared/utils/machine";
+import EndpointPageClient from "./endpoint/EndpointPageClient";
+
+export default async function DashboardPage() {
+  const machineId = await getMachineId();
+  return <EndpointPageClient machineId={machineId} />;
+}
diff --git a/src/app/(dashboard)/dashboard/profile/page.js b/src/app/(dashboard)/dashboard/profile/page.js
new file mode 100644
index 0000000..4df8cbe
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/profile/page.js
@@ -0,0 +1,1182 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { Card, Button, Toggle, Input } from "@/shared/components";
+import Modal, { ConfirmModal } from "@/shared/components/Modal";
+import LanguageSwitcher from "@/shared/components/LanguageSwitcher";
+import { useTheme } from "@/shared/hooks/useTheme";
+import { cn } from "@/shared/utils/cn";
+import { APP_CONFIG } from "@/shared/constants/config";
+import { LOCALE_COOKIE, normalizeLocale } from "@/i18n/config";
+import { LOCALE_FLAGS } from "@/shared/constants/locales";
+
+function getLocaleFromCookie() {
+  if (typeof document === "undefined") return "en";
+  const cookie = document.cookie
+    .split(";")
+    .find((c) => c.trim().startsWith(`${LOCALE_COOKIE}=`));
+  const value = cookie ? decodeURIComponent(cookie.split("=")[1]) : "en";
+  return normalizeLocale(value);
+}
+
+export default function ProfilePage() {
+  const { theme, setTheme, isDark } = useTheme();
+  const [locale, setLocale] = useState("en");
+  const [langOpen, setLangOpen] = useState(false);
+  const [shutdownOpen, setShutdownOpen] = useState(false);
+  const [isShuttingDown, setIsShuttingDown] = useState(false);
+  const [settings, setSettings] = useState({ fallbackStrategy: "fill-first" });
+  const [loading, setLoading] = useState(true);
+  const [passwords, setPasswords] = useState({ current: "", new: "", confirm: "" });
+  const [passStatus, setPassStatus] = useState({ type: "", message: "" });
+  const [passLoading, setPassLoading] = useState(false);
+  const [dbLoading, setDbLoading] = useState(false);
+  const [dbStatus, setDbStatus] = useState({ type: "", message: "" });
+  const [dbAuth, setDbAuth] = useState({ open: false, mode: "", password: "" });
+  const pendingImportRef = useRef(null);
+  const [oidcForm, setOidcForm] = useState({
+    authMode: "password",
+    oidcIssuerUrl: "",
+    oidcClientId: "",
+    oidcScopes: "openid profile email",
+    oidcLoginLabel: "Sign in with OIDC",
+  });
+  const [oidcClientSecret, setOidcClientSecret] = useState("");
+  const [oidcStatus, setOidcStatus] = useState({ type: "", message: "" });
+  const [oidcLoading, setOidcLoading] = useState(false);
+  const [oidcTestLoading, setOidcTestLoading] = useState(false);
+  const [oidcTestStatus, setOidcTestStatus] = useState({ type: "", message: "" });
+  const [oidcRedirectUri, setOidcRedirectUri] = useState("/api/auth/oidc/callback");
+  const [oidcExpanded, setOidcExpanded] = useState(false);
+  const importFileRef = useRef(null);
+  const [proxyForm, setProxyForm] = useState({
+    outboundProxyEnabled: false,
+    outboundProxyUrl: "",
+    outboundNoProxy: "",
+  });
+  const [proxyStatus, setProxyStatus] = useState({ type: "", message: "" });
+  const [proxyLoading, setProxyLoading] = useState(false);
+  const [proxyTestLoading, setProxyTestLoading] = useState(false);
+
+  useEffect(() => {
+    setLocale(getLocaleFromCookie());
+  }, [langOpen]);
+
+  useEffect(() => {
+    fetch("/api/settings")
+      .then((res) => res.json())
+      .then((data) => {
+        setSettings(data);
+        setOidcForm({
+          authMode: data?.authMode || "password",
+          oidcIssuerUrl: data?.oidcIssuerUrl || "",
+          oidcClientId: data?.oidcClientId || "",
+          oidcScopes: data?.oidcScopes || "openid profile email",
+          oidcLoginLabel: data?.oidcLoginLabel || "Sign in with OIDC",
+        });
+        setOidcClientSecret("");
+        if (data?.authMode === "oidc" || data?.authMode === "both") setOidcExpanded(true);
+        setProxyForm({
+          outboundProxyEnabled: data?.outboundProxyEnabled === true,
+          outboundProxyUrl: data?.outboundProxyUrl || "",
+          outboundNoProxy: data?.outboundNoProxy || "",
+        });
+        setLoading(false);
+      })
+      .catch((err) => {
+        console.error("Failed to fetch settings:", err);
+        setLoading(false);
+      });
+  }, []);
+
+  useEffect(() => {
+    if (typeof window !== "undefined") {
+      setOidcRedirectUri(`${window.location.origin}/api/auth/oidc/callback`);
+    }
+  }, []);
+
+  const updateOutboundProxy = async (e) => {
+    e.preventDefault();
+    if (settings.outboundProxyEnabled !== true) return;
+    setProxyLoading(true);
+    setProxyStatus({ type: "", message: "" });
+
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          outboundProxyUrl: proxyForm.outboundProxyUrl,
+          outboundNoProxy: proxyForm.outboundNoProxy,
+        }),
+      });
+
+      const data = await res.json();
+      if (res.ok) {
+        setSettings((prev) => ({ ...prev, ...data }));
+        setProxyStatus({ type: "success", message: "Proxy settings applied" });
+      } else {
+        setProxyStatus({ type: "error", message: data.error || "Failed to update proxy settings" });
+      }
+    } catch (err) {
+      setProxyStatus({ type: "error", message: "An error occurred" });
+    } finally {
+      setProxyLoading(false);
+    }
+  };
+
+  const testOutboundProxy = async () => {
+    if (settings.outboundProxyEnabled !== true) return;
+
+    const proxyUrl = (proxyForm.outboundProxyUrl || "").trim();
+    if (!proxyUrl) {
+      setProxyStatus({ type: "error", message: "Please enter a Proxy URL to test" });
+      return;
+    }
+
+    setProxyTestLoading(true);
+    setProxyStatus({ type: "", message: "" });
+
+    try {
+      const res = await fetch("/api/settings/proxy-test", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ proxyUrl }),
+      });
+
+      const data = await res.json();
+      if (res.ok && data?.ok) {
+        setProxyStatus({
+          type: "success",
+          message: `Proxy test OK (${data.status}) in ${data.elapsedMs}ms`,
+        });
+      } else {
+        setProxyStatus({
+          type: "error",
+          message: data?.error || "Proxy test failed",
+        });
+      }
+    } catch (err) {
+      setProxyStatus({ type: "error", message: "An error occurred" });
+    } finally {
+      setProxyTestLoading(false);
+    }
+  };
+
+  const updateOutboundProxyEnabled = async (outboundProxyEnabled) => {
+    setProxyLoading(true);
+    setProxyStatus({ type: "", message: "" });
+
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ outboundProxyEnabled }),
+      });
+
+      const data = await res.json();
+      if (res.ok) {
+        setSettings((prev) => ({ ...prev, ...data }));
+        setProxyForm((prev) => ({ ...prev, outboundProxyEnabled: data?.outboundProxyEnabled === true }));
+        setProxyStatus({
+          type: "success",
+          message: outboundProxyEnabled ? "Proxy enabled" : "Proxy disabled",
+        });
+      } else {
+        setProxyStatus({ type: "error", message: data.error || "Failed to update proxy settings" });
+      }
+    } catch (err) {
+      setProxyStatus({ type: "error", message: "An error occurred" });
+    } finally {
+      setProxyLoading(false);
+    }
+  };
+
+  const handlePasswordChange = async (e) => {
+    e.preventDefault();
+    if (passwords.new !== passwords.confirm) {
+      setPassStatus({ type: "error", message: "Passwords do not match" });
+      return;
+    }
+
+    setPassLoading(true);
+    setPassStatus({ type: "", message: "" });
+
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          currentPassword: passwords.current,
+          newPassword: passwords.new,
+        }),
+      });
+
+      const data = await res.json();
+
+      if (res.ok) {
+        setPassStatus({ type: "success", message: "Password updated successfully" });
+        setPasswords({ current: "", new: "", confirm: "" });
+      } else {
+        setPassStatus({ type: "error", message: data.error || "Failed to update password" });
+      }
+    } catch (err) {
+      setPassStatus({ type: "error", message: "An error occurred" });
+    } finally {
+      setPassLoading(false);
+    }
+  };
+
+  const updateFallbackStrategy = async (strategy) => {
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ fallbackStrategy: strategy }),
+      });
+      if (res.ok) {
+        setSettings(prev => ({ ...prev, fallbackStrategy: strategy }));
+      }
+    } catch (err) {
+      console.error("Failed to update settings:", err);
+    }
+  };
+
+  const updateComboStrategy = async (strategy) => {
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ comboStrategy: strategy }),
+      });
+      if (res.ok) {
+        setSettings(prev => ({ ...prev, comboStrategy: strategy }));
+      }
+    } catch (err) {
+      console.error("Failed to update combo strategy:", err);
+    }
+  };
+
+  const updateStickyLimit = async (limit) => {
+    const numLimit = parseInt(limit);
+    if (isNaN(numLimit) || numLimit < 1) return;
+
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ stickyRoundRobinLimit: numLimit }),
+      });
+      if (res.ok) {
+        setSettings(prev => ({ ...prev, stickyRoundRobinLimit: numLimit }));
+      }
+    } catch (err) {
+      console.error("Failed to update sticky limit:", err);
+    }
+  };
+
+  const updateComboStickyLimit = async (limit) => {
+    const numLimit = parseInt(limit);
+    if (isNaN(numLimit) || numLimit < 1) return;
+
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ comboStickyRoundRobinLimit: numLimit }),
+      });
+      if (res.ok) {
+        setSettings(prev => ({ ...prev, comboStickyRoundRobinLimit: numLimit }));
+      }
+    } catch (err) {
+      console.error("Failed to update combo sticky limit:", err);
+    }
+  };
+
+  const updateRequireLogin = async (requireLogin) => {
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ requireLogin }),
+      });
+      if (res.ok) {
+        setSettings(prev => ({ ...prev, requireLogin }));
+      }
+    } catch (err) {
+      console.error("Failed to update require login:", err);
+    }
+  };
+
+  const updateOidcForm = (field, value) => {
+    setOidcForm((prev) => ({ ...prev, [field]: value }));
+  };
+
+  const saveOidcSettings = async (authMode = oidcForm.authMode || "password") => {
+    const issuerUrl = oidcForm.oidcIssuerUrl.trim();
+    const clientId = oidcForm.oidcClientId.trim();
+    const scopes = oidcForm.oidcScopes.trim();
+    const loginLabel = oidcForm.oidcLoginLabel.trim();
+    const secret = oidcClientSecret.trim();
+
+    if (authMode !== "password" && (!issuerUrl || !clientId || !secret) && !settings.oidcConfigured) {
+      setOidcStatus({ type: "error", message: "Issuer URL, client ID, and client secret are required to enable OIDC." });
+      return;
+    }
+
+    setOidcLoading(true);
+    setOidcStatus({ type: "", message: "" });
+    setOidcTestStatus({ type: "", message: "" });
+
+    try {
+      const payload = {
+        authMode,
+        oidcIssuerUrl: issuerUrl,
+        oidcClientId: clientId,
+        oidcScopes: scopes || "openid profile email",
+        oidcLoginLabel: loginLabel || "Sign in with OIDC",
+      };
+      if (secret) {
+        payload.oidcClientSecret = secret;
+      }
+
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+
+      const data = await res.json();
+      if (res.ok) {
+        setSettings((prev) => ({ ...prev, ...data }));
+        setOidcForm({
+          authMode: data?.authMode || authMode,
+          oidcIssuerUrl: data?.oidcIssuerUrl || issuerUrl,
+          oidcClientId: data?.oidcClientId || clientId,
+          oidcScopes: data?.oidcScopes || scopes || "openid profile email",
+          oidcLoginLabel: data?.oidcLoginLabel || loginLabel || "Sign in with OIDC",
+        });
+        setOidcClientSecret("");
+        setOidcStatus({
+          type: "success",
+          message:
+            authMode === "oidc"
+              ? "OIDC login enabled"
+              : authMode === "both"
+                ? "Password and OIDC login enabled"
+                : "OIDC settings saved",
+        });
+      } else {
+        setOidcStatus({ type: "error", message: data.error || "Failed to save OIDC settings" });
+      }
+    } catch (err) {
+      setOidcStatus({ type: "error", message: "An error occurred" });
+    } finally {
+      setOidcLoading(false);
+    }
+  };
+
+  const testOidcConnection = async () => {
+    const issuerUrl = oidcForm.oidcIssuerUrl.trim();
+    const clientId = oidcForm.oidcClientId.trim();
+    const scopes = oidcForm.oidcScopes.trim();
+    const secret = oidcClientSecret.trim();
+
+    if (!issuerUrl || !clientId) {
+      setOidcTestStatus({ type: "error", message: "Issuer URL and client ID are required to test the connection." });
+      return;
+    }
+
+    setOidcTestLoading(true);
+    setOidcStatus({ type: "", message: "" });
+    setOidcTestStatus({ type: "", message: "" });
+
+    try {
+      const saveRes = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          authMode: oidcForm.authMode || settings.authMode || "password",
+          oidcIssuerUrl: issuerUrl,
+          oidcClientId: clientId,
+          oidcScopes: scopes || "openid profile email",
+          oidcLoginLabel: oidcForm.oidcLoginLabel.trim() || "Sign in with OIDC",
+          ...(secret ? { oidcClientSecret: secret } : {}),
+        }),
+      });
+
+      const saved = await saveRes.json().catch(() => ({}));
+      if (!saveRes.ok) {
+        setOidcTestStatus({
+          type: "error",
+          message: saved.error || "Failed to save OIDC settings before testing",
+        });
+        return;
+      }
+
+      const res = await fetch("/api/auth/oidc/test", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          issuerUrl: saved.oidcIssuerUrl || issuerUrl,
+          clientId: saved.oidcClientId || clientId,
+          scopes: saved.oidcScopes || scopes || "openid profile email",
+        }),
+      });
+
+      const data = await res.json().catch(() => ({}));
+      if (res.ok && data?.ok) {
+        const statusMessage = data.clientSecretTested
+          ? data.clientSecretValid === true
+            ? `Connection OK. Discovery loaded from ${data.issuerUrl}. Client secret validated too.`
+            : `Connection OK. Discovery loaded from ${data.issuerUrl}. Client secret was not checked.`
+          : `Connection OK. Discovery loaded from ${data.issuerUrl}.`;
+        setOidcTestStatus({
+          type: "success",
+          message: statusMessage,
+        });
+      } else {
+        setOidcTestStatus({ type: "error", message: data.error || "OIDC connection test failed" });
+      }
+    } catch (err) {
+      setOidcTestStatus({ type: "error", message: "An error occurred" });
+    } finally {
+      setOidcTestLoading(false);
+    }
+  };
+
+  const updateObservabilityEnabled = async (enabled) => {
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ enableObservability: enabled }),
+      });
+      if (res.ok) {
+        setSettings(prev => ({ ...prev, enableObservability: enabled }));
+      }
+    } catch (err) {
+      console.error("Failed to update enableObservability:", err);
+    }
+  };
+
+  const reloadSettings = async () => {
+    try {
+      const res = await fetch("/api/settings");
+      if (!res.ok) return;
+      const data = await res.json();
+      setSettings(data);
+    } catch (err) {
+      console.error("Failed to reload settings:", err);
+    }
+  };
+
+  const handleExportDatabase = async (password) => {
+    setDbLoading(true);
+    setDbStatus({ type: "", message: "" });
+    try {
+      const res = await fetch("/api/settings/database", {
+        headers: { "x-9r-password": password },
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        throw new Error(data.error || "Failed to export database");
+      }
+
+      const payload = await res.json();
+      const content = JSON.stringify(payload, null, 2);
+      const blob = new Blob([content], { type: "application/json" });
+      const url = URL.createObjectURL(blob);
+      const anchor = document.createElement("a");
+      const stamp = new Date().toISOString().replace(/[.:]/g, "-");
+      anchor.href = url;
+      anchor.download = `9router-backup-${stamp}.json`;
+      document.body.appendChild(anchor);
+      anchor.click();
+      document.body.removeChild(anchor);
+      URL.revokeObjectURL(url);
+
+      setDbStatus({ type: "success", message: "Database backup downloaded" });
+    } catch (err) {
+      setDbStatus({ type: "error", message: err.message || "Failed to export database" });
+    } finally {
+      setDbLoading(false);
+    }
+  };
+
+  const handleImportDatabase = (event) => {
+    const file = event.target.files?.[0];
+    if (importFileRef.current) importFileRef.current.value = "";
+    if (!file) return;
+    pendingImportRef.current = file;
+    setDbStatus({ type: "", message: "" });
+    setDbAuth({ open: true, mode: "import", password: "" });
+  };
+
+  const runImportDatabase = async (password) => {
+    const file = pendingImportRef.current;
+    if (!file) return;
+    setDbLoading(true);
+    try {
+      const raw = await file.text();
+      const payload = JSON.parse(raw);
+
+      const res = await fetch("/api/settings/database", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ ...payload, password }),
+      });
+
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        throw new Error(data.error || "Failed to import database");
+      }
+
+      await reloadSettings();
+      setDbStatus({ type: "success", message: "Database imported successfully" });
+    } catch (err) {
+      setDbStatus({ type: "error", message: err.message || "Invalid backup file" });
+    } finally {
+      pendingImportRef.current = null;
+      setDbLoading(false);
+    }
+  };
+
+  // Confirm password modal, then run export or import.
+  const handleDbAuthConfirm = async () => {
+    const { mode, password } = dbAuth;
+    setDbAuth({ open: false, mode: "", password: "" });
+    if (mode === "export") await handleExportDatabase(password);
+    else if (mode === "import") await runImportDatabase(password);
+  };
+
+  const observabilityEnabled = settings.enableObservability === true;
+
+  const handleShutdown = async () => {
+    setIsShuttingDown(true);
+    try {
+      await fetch("/api/version/shutdown", { method: "POST" });
+    } catch (e) {
+      // Expected to fail as server shuts down; ignore error
+    }
+    setIsShuttingDown(false);
+    setShutdownOpen(false);
+  };
+
+  const handleLogout = async () => {
+    try {
+      const res = await fetch("/api/auth/logout", { method: "POST" });
+      if (res.ok) {
+        window.location.assign("/login");
+      }
+    } catch (err) {
+      console.error("Failed to logout:", err);
+    }
+  };
+
+  return (
+    <div className="max-w-2xl mx-auto px-4 sm:px-0">
+      <div className="flex flex-col gap-6">
+        {/* Local Mode Info */}
+        <Card>
+          <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4 mb-4">
+            <div className="flex items-center gap-3 sm:gap-4">
+              <div className="size-10 sm:size-12 rounded-lg bg-green-500/10 text-green-500 flex items-center justify-center shrink-0">
+                <span className="material-symbols-outlined text-xl sm:text-2xl">computer</span>
+              </div>
+              <div>
+                <h2 className="text-lg sm:text-xl font-semibold">Local Mode</h2>
+                <p className="text-sm text-text-muted">Running on your machine</p>
+              </div>
+            </div>
+            <div className="inline-flex p-1 rounded-lg bg-black/5 dark:bg-white/5 w-full sm:w-auto">
+              {["light", "dark", "system"].map((option) => (
+                <button
+                  key={option}
+                  type="button"
+                  onClick={() => setTheme(option)}
+                  className={cn(
+                    "flex items-center justify-center gap-1 sm:gap-1.5 px-2 sm:px-3 py-1.5 rounded-md font-medium transition-all flex-1 sm:flex-initial",
+                    theme === option
+                      ? "bg-white dark:bg-white/10 text-text-main shadow-sm"
+                      : "text-text-muted hover:text-text-main"
+                  )}
+                >
+                  <span className="material-symbols-outlined text-[18px]">
+                    {option === "light" ? "light_mode" : option === "dark" ? "dark_mode" : "contrast"}
+                  </span>
+                  <span className="capitalize text-xs sm:text-sm">{option}</span>
+                </button>
+              ))}
+            </div>
+          </div>
+          <div className="flex flex-col gap-3 pt-4 border-t border-border">
+            <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between p-3 rounded-lg bg-bg border border-border gap-2">
+              <div>
+                <p className="font-medium text-sm sm:text-base">Database Location</p>
+                <p className="text-xs sm:text-sm text-text-muted font-mono break-all">~/.9router/db/data.sqlite</p>
+              </div>
+            </div>
+            <div className="flex flex-col sm:flex-row gap-2">
+              <Button
+                variant="secondary"
+                icon="download"
+                onClick={() => setDbAuth({ open: true, mode: "export", password: "" })}
+                loading={dbLoading}
+                className="w-full sm:w-auto"
+              >
+                Download Backup
+              </Button>
+              <Button
+                variant="outline"
+                icon="upload"
+                onClick={() => importFileRef.current?.click()}
+                disabled={dbLoading}
+                className="w-full sm:w-auto"
+              >
+                Import Backup
+              </Button>
+              <input
+                ref={importFileRef}
+                type="file"
+                accept="application/json,.json"
+                className="hidden"
+                onChange={handleImportDatabase}
+              />
+            </div>
+            {dbStatus.message && (
+              <p className={`text-sm ${dbStatus.type === "error" ? "text-red-500" : "text-green-600 dark:text-green-400"}`}>
+                {dbStatus.message}
+              </p>
+            )}
+          </div>
+        </Card>
+
+        {/* Language */}
+        <Card>
+          <div className="flex items-center gap-3 mb-4">
+            <div className="size-10 rounded-lg bg-blue-500/10 text-blue-500 flex items-center justify-center shrink-0">
+              <span className="material-symbols-outlined text-[20px]">language</span>
+            </div>
+            <h3 className="text-base sm:text-lg font-semibold">Language</h3>
+          </div>
+          <button
+            onClick={() => setLangOpen(true)}
+            className="flex items-center justify-between w-full p-3 rounded-lg bg-bg border border-border hover:border-primary/50 transition-colors"
+            data-i18n-skip="true"
+          >
+            <span className="text-sm text-text-muted">Display language</span>
+            <span className="text-2xl">{LOCALE_FLAGS[locale] || "🌐"}</span>
+          </button>
+        </Card>
+
+        {/* Security */}
+        <Card>
+          <div className="flex items-center gap-3 mb-4">
+            <div className="p-2 rounded-lg bg-primary/10 text-primary shrink-0">
+              <span className="material-symbols-outlined text-[20px]">shield</span>
+            </div>
+            <h3 className="text-base sm:text-lg font-semibold">Security</h3>
+          </div>
+          <div className="flex flex-col gap-4">
+            <div className="flex items-start sm:items-center justify-between gap-4">
+              <div className="flex-1 min-w-0">
+                <p className="font-medium text-sm sm:text-base">Require login</p>
+                <p className="text-xs sm:text-sm text-text-muted">
+                  When ON, dashboard requires password. When OFF, access without login.
+                </p>
+              </div>
+              <Toggle
+                checked={settings.requireLogin === true}
+                onChange={() => updateRequireLogin(!settings.requireLogin)}
+                disabled={loading}
+              />
+            </div>
+            {settings.requireLogin === true && (
+              <form onSubmit={handlePasswordChange} className="flex flex-col gap-4 pt-4 border-t border-border/50">
+                {settings.hasPassword && (
+                  <div className="flex flex-col gap-2">
+                    <label className="text-xs sm:text-sm font-medium">Current Password</label>
+                    <Input
+                      type="password"
+                      placeholder="Enter current password"
+                      value={passwords.current}
+                      onChange={(e) => setPasswords({ ...passwords, current: e.target.value })}
+                      required
+                    />
+                  </div>
+                )}
+                {/* {!settings.hasPassword && (
+                  <div className="p-3 rounded-lg bg-blue-500/10 border border-blue-500/20">
+                    <p className="text-sm text-blue-600 dark:text-blue-400">
+                      Setting password for the first time. Leave current password empty or use default: <code className="bg-blue-500/20 px-1 rounded">123456</code>
+                    </p>
+                  </div>
+                )} */}
+                <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+                  <div className="flex flex-col gap-2">
+                    <label className="text-xs sm:text-sm font-medium">New Password</label>
+                    <Input
+                      type="password"
+                      placeholder="Enter new password"
+                      value={passwords.new}
+                      onChange={(e) => setPasswords({ ...passwords, new: e.target.value })}
+                      required
+                    />
+                  </div>
+                  <div className="flex flex-col gap-2">
+                    <label className="text-xs sm:text-sm font-medium">Confirm New Password</label>
+                    <Input
+                      type="password"
+                      placeholder="Confirm new password"
+                      value={passwords.confirm}
+                      onChange={(e) => setPasswords({ ...passwords, confirm: e.target.value })}
+                      required
+                    />
+                  </div>
+                </div>
+
+                {passStatus.message && (
+                  <p className={`text-xs sm:text-sm ${passStatus.type === "error" ? "text-red-500" : "text-green-500"}`}>
+                    {passStatus.message}
+                  </p>
+                )}
+
+                <div className="pt-2">
+                  <Button type="submit" variant="primary" loading={passLoading} className="w-full sm:w-auto">
+                    {settings.hasPassword ? "Update Password" : "Set Password"}
+                  </Button>
+                </div>
+              </form>
+            )}
+          </div>
+        </Card>
+
+        {/* OIDC */}
+        <Card>
+          <button
+            type="button"
+            onClick={() => setOidcExpanded((v) => !v)}
+            className="w-full flex items-center gap-3 text-left"
+          >
+            <div className="p-2 rounded-lg bg-indigo-500/10 text-indigo-500 shrink-0">
+              <span className="material-symbols-outlined text-[20px]">lock_open</span>
+            </div>
+            <div className="flex-1 min-w-0">
+              <h3 className="text-base sm:text-lg font-semibold">OIDC Dashboard Login</h3>
+              <p className="text-xs text-text-muted">
+                {settings.authMode === "oidc" ? "OIDC active" : settings.authMode === "both" ? "Password + OIDC active" : "Optional SSO via Authentik/Keycloak/Google"}
+              </p>
+            </div>
+            <span className="material-symbols-outlined text-text-muted shrink-0">
+              {oidcExpanded ? "expand_less" : "expand_more"}
+            </span>
+          </button>
+          {oidcExpanded && (
+          <div className="flex flex-col gap-4 mt-4">
+            <p className="text-xs sm:text-sm text-text-muted">
+              Use Authentik or any OIDC provider to sign in to the dashboard. You can enable password-only, OIDC-only, or both for the dashboard; model API access still uses API keys.
+            </p>
+
+            <div className="flex flex-col gap-2">
+              <label className="font-medium text-sm sm:text-base">Auth Mode</label>
+              <div className="grid grid-cols-1 sm:grid-cols-3 gap-2">
+                {[
+                  {
+                    value: "password",
+                    title: "Password only",
+                    desc: "Keep the legacy password login.",
+                  },
+                  {
+                    value: "oidc",
+                    title: "OIDC only",
+                    desc: "Require OIDC for dashboard access.",
+                  },
+                  {
+                    value: "both",
+                    title: "Both",
+                    desc: "Allow either password or OIDC.",
+                  },
+                ].map((option) => {
+                  const active = oidcForm.authMode === option.value;
+                  return (
+                    <button
+                      key={option.value}
+                      type="button"
+                      onClick={() => updateOidcForm("authMode", option.value)}
+                      className={cn(
+                        "text-left rounded-lg border p-3 transition-colors",
+                        active
+                          ? "border-primary bg-primary/5"
+                          : "border-border bg-bg hover:bg-black/5 dark:hover:bg-white/5"
+                      )}
+                      disabled={loading || oidcLoading}
+                    >
+                      <p className="font-medium text-sm sm:text-base">{option.title}</p>
+                      <p className="text-xs sm:text-sm text-text-muted mt-1">{option.desc}</p>
+                    </button>
+                  );
+                })}
+              </div>
+            </div>
+
+            <div className="grid grid-cols-1 gap-4">
+              <div className="flex flex-col gap-2">
+                <label className="font-medium text-sm sm:text-base">Issuer URL</label>
+                <Input
+                  placeholder="https://auth.example.com/application/o/9router/"
+                  value={oidcForm.oidcIssuerUrl}
+                  onChange={(e) => updateOidcForm("oidcIssuerUrl", e.target.value)}
+                  disabled={loading || oidcLoading}
+                />
+              </div>
+
+              <div className="flex flex-col gap-2">
+                <label className="font-medium text-sm sm:text-base">Client ID</label>
+                <Input
+                  placeholder="9router-dashboard"
+                  value={oidcForm.oidcClientId}
+                  onChange={(e) => updateOidcForm("oidcClientId", e.target.value)}
+                  disabled={loading || oidcLoading}
+                />
+              </div>
+
+              <div className="flex flex-col gap-2">
+                <label className="font-medium text-sm sm:text-base">Client Secret</label>
+                <Input
+                  type="password"
+                  placeholder="Leave blank to keep existing secret"
+                  value={oidcClientSecret}
+                  onChange={(e) => setOidcClientSecret(e.target.value)}
+                  disabled={loading || oidcLoading}
+                />
+                <p className="text-xs sm:text-sm text-text-muted">This value is write-only after saving.</p>
+              </div>
+
+              <div className="flex flex-col gap-2">
+                <label className="font-medium text-sm sm:text-base">Scopes</label>
+                <Input
+                  placeholder="openid profile email"
+                  value={oidcForm.oidcScopes}
+                  onChange={(e) => updateOidcForm("oidcScopes", e.target.value)}
+                  disabled={loading || oidcLoading}
+                />
+              </div>
+
+              <div className="flex flex-col gap-2">
+                <label className="font-medium text-sm sm:text-base">Login Button Label</label>
+                <Input
+                  placeholder="Sign in with OIDC"
+                  value={oidcForm.oidcLoginLabel}
+                  onChange={(e) => updateOidcForm("oidcLoginLabel", e.target.value)}
+                  disabled={loading || oidcLoading}
+                />
+              </div>
+            </div>
+
+            <div className="rounded-lg border border-border bg-bg p-3 text-xs sm:text-sm text-text-muted">
+              <p className="font-medium text-text-main mb-1">Redirect URI</p>
+              <code className="block break-all font-mono">{oidcRedirectUri}</code>
+            </div>
+
+            <div className="flex flex-col sm:flex-row gap-2 pt-2 border-t border-border/50">
+              <Button type="button" variant="primary" loading={oidcLoading} onClick={() => saveOidcSettings()} className="w-full sm:w-auto">
+                Save auth mode
+              </Button>
+              <Button type="button" variant="outline" loading={oidcTestLoading} onClick={testOidcConnection} className="w-full sm:w-auto">
+                Test connection
+              </Button>
+            </div>
+
+            {oidcTestStatus.message && (
+              <p className={`text-xs sm:text-sm ${oidcTestStatus.type === "error" ? "text-red-500" : "text-green-500"}`}>
+                {oidcTestStatus.message}
+              </p>
+            )}
+
+            {oidcStatus.message && (
+              <p className={`text-xs sm:text-sm ${oidcStatus.type === "error" ? "text-red-500" : "text-green-500"}`}>
+                {oidcStatus.message}
+              </p>
+            )}
+
+            {settings.authMode === "oidc" && (
+              <p className="text-xs sm:text-sm text-amber-600 dark:text-amber-400">
+                OIDC login is currently active. Password login is disabled until you switch back.
+              </p>
+            )}
+
+            {settings.authMode === "both" && (
+              <p className="text-xs sm:text-sm text-amber-600 dark:text-amber-400">
+                Password and OIDC login are both active.
+              </p>
+            )}
+          </div>
+          )}
+        </Card>
+
+        {/* Routing Preferences */}
+        <Card>
+          <div className="flex items-center gap-3 mb-4">
+            <div className="p-2 rounded-lg bg-blue-500/10 text-blue-500 shrink-0">
+              <span className="material-symbols-outlined text-[20px]">route</span>
+            </div>
+            <h3 className="text-base sm:text-lg font-semibold">Routing Strategy</h3>
+          </div>
+          <div className="flex flex-col gap-4">
+            <div className="flex items-start sm:items-center justify-between gap-4">
+              <div className="flex-1 min-w-0">
+                <p className="font-medium text-sm sm:text-base">Round Robin</p>
+                <p className="text-xs sm:text-sm text-text-muted">
+                  Cycle through accounts to distribute load
+                </p>
+              </div>
+              <Toggle
+                checked={settings.fallbackStrategy === "round-robin"}
+                onChange={() => updateFallbackStrategy(settings.fallbackStrategy === "round-robin" ? "fill-first" : "round-robin")}
+                disabled={loading}
+              />
+            </div>
+
+            {/* Sticky Round Robin Limit */}
+            {settings.fallbackStrategy === "round-robin" && (
+              <div className="flex items-start sm:items-center justify-between gap-4 pt-2 border-t border-border/50">
+                <div className="flex-1 min-w-0">
+                  <p className="font-medium text-sm sm:text-base">Sticky Limit</p>
+                  <p className="text-xs sm:text-sm text-text-muted">
+                    Calls per account before switching
+                  </p>
+                </div>
+                <Input
+                  type="number"
+                  min="1"
+                  max="10"
+                  value={settings.stickyRoundRobinLimit || 3}
+                  onChange={(e) => updateStickyLimit(e.target.value)}
+                  disabled={loading}
+                  className="w-16 sm:w-20 text-center shrink-0"
+                />
+              </div>
+            )}
+
+            {/* Combo Round Robin */}
+            <div className="flex items-start sm:items-center justify-between gap-4 pt-4 border-t border-border/50">
+              <div className="flex-1 min-w-0">
+                <p className="font-medium text-sm sm:text-base">Combo Round Robin</p>
+                <p className="text-xs sm:text-sm text-text-muted">
+                  Cycle through providers in combos instead of always starting with first
+                </p>
+              </div>
+              <Toggle
+                checked={settings.comboStrategy === "round-robin"}
+                onChange={() => updateComboStrategy(settings.comboStrategy === "round-robin" ? "fallback" : "round-robin")}
+                disabled={loading}
+              />
+            </div>
+
+            {/* Combo Sticky Round Robin Limit */}
+            {settings.comboStrategy === "round-robin" && (
+              <div className="flex items-center justify-between pt-2 border-t border-border/50">
+                <div>
+                  <p className="font-medium">Combo Sticky Limit</p>
+                  <p className="text-sm text-text-muted">
+                    Calls per combo model before switching
+                  </p>
+                </div>
+                <Input
+                  type="number"
+                  min="1"
+                  max="100"
+                  value={settings.comboStickyRoundRobinLimit || 1}
+                  onChange={(e) => updateComboStickyLimit(e.target.value)}
+                  disabled={loading}
+                  className="w-20 text-center"
+                />
+              </div>
+            )}
+
+            <p className="text-xs text-text-muted italic pt-2 border-t border-border/50">
+              {settings.fallbackStrategy === "round-robin"
+                ? `Currently distributing requests across all available accounts with ${settings.stickyRoundRobinLimit || 3} calls per account.`
+                : "Currently using accounts in priority order (Fill First)."}
+              {settings.comboStrategy === "round-robin"
+                ? ` Combos rotate after ${settings.comboStickyRoundRobinLimit || 1} call${(settings.comboStickyRoundRobinLimit || 1) === 1 ? "" : "s"} per model.`
+                : " Combos always start with their first model."}
+            </p>
+          </div>
+        </Card>
+
+        {/* Network */}
+        <Card>
+          <div className="flex items-center gap-3 mb-4">
+            <div className="p-2 rounded-lg bg-purple-500/10 text-purple-500 shrink-0">
+              <span className="material-symbols-outlined text-[20px]">wifi</span>
+            </div>
+            <h3 className="text-base sm:text-lg font-semibold">Network</h3>
+          </div>
+
+          <div className="flex flex-col gap-4">
+            <div className="flex items-start sm:items-center justify-between gap-4">
+              <div className="flex-1 min-w-0">
+                <p className="font-medium text-sm sm:text-base">Outbound Proxy</p>
+                <p className="text-xs sm:text-sm text-text-muted">Enable proxy for OAuth + provider outbound requests.</p>
+              </div>
+              <Toggle
+                checked={settings.outboundProxyEnabled === true}
+                onChange={() => updateOutboundProxyEnabled(!(settings.outboundProxyEnabled === true))}
+                disabled={loading || proxyLoading}
+              />
+            </div>
+
+            {settings.outboundProxyEnabled === true && (
+              <form onSubmit={updateOutboundProxy} className="flex flex-col gap-4 pt-2 border-t border-border/50">
+                <div className="flex flex-col gap-2">
+                  <label className="font-medium text-sm sm:text-base">Proxy URL</label>
+                  <Input
+                    placeholder="http://127.0.0.1:7897"
+                    value={proxyForm.outboundProxyUrl}
+                    onChange={(e) => setProxyForm((prev) => ({ ...prev, outboundProxyUrl: e.target.value }))}
+                    disabled={loading || proxyLoading}
+                  />
+                  <p className="text-xs sm:text-sm text-text-muted">Leave empty to inherit existing env proxy (if any).</p>
+                </div>
+
+                <div className="flex flex-col gap-2 pt-2 border-t border-border/50">
+                  <label className="font-medium text-sm sm:text-base">No Proxy</label>
+                  <Input
+                    placeholder="localhost,127.0.0.1"
+                    value={proxyForm.outboundNoProxy}
+                    onChange={(e) => setProxyForm((prev) => ({ ...prev, outboundNoProxy: e.target.value }))}
+                    disabled={loading || proxyLoading}
+                  />
+                  <p className="text-xs sm:text-sm text-text-muted">Comma-separated hostnames/domains to bypass the proxy.</p>
+                </div>
+
+                <div className="pt-2 border-t border-border/50 flex flex-col sm:flex-row items-stretch sm:items-center gap-2">
+                  <Button
+                    type="button"
+                    variant="secondary"
+                    loading={proxyTestLoading}
+                    disabled={loading || proxyLoading}
+                    onClick={testOutboundProxy}
+                    className="w-full sm:w-auto"
+                  >
+                    Test proxy URL
+                  </Button>
+                  <Button type="submit" variant="primary" loading={proxyLoading} className="w-full sm:w-auto">
+                    Apply
+                  </Button>
+                </div>
+              </form>
+            )}
+
+            {proxyStatus.message && (
+              <p className={`text-xs sm:text-sm ${proxyStatus.type === "error" ? "text-red-500" : "text-green-500"} pt-2 border-t border-border/50`}>
+                {proxyStatus.message}
+              </p>
+            )}
+          </div>
+        </Card>
+
+        {/* Observability Settings */}
+        <Card>
+          <div className="flex items-center gap-3 mb-4">
+            <div className="p-2 rounded-lg bg-orange-500/10 text-orange-500 shrink-0">
+              <span className="material-symbols-outlined text-[20px]">monitoring</span>
+            </div>
+            <h3 className="text-base sm:text-lg font-semibold">Observability</h3>
+          </div>
+          <div className="flex items-start sm:items-center justify-between gap-4">
+            <div className="flex-1 min-w-0">
+              <p className="font-medium text-sm sm:text-base">Enable Observability</p>
+              <p className="text-xs sm:text-sm text-text-muted">
+                Record request details for inspection in the logs view
+              </p>
+            </div>
+            <Toggle
+              checked={observabilityEnabled}
+              onChange={updateObservabilityEnabled}
+              disabled={loading}
+            />
+          </div>
+        </Card>
+
+        {/* Account actions */}
+        <div className="flex flex-col sm:flex-row gap-2">
+          <Button
+            variant="outline"
+            fullWidth
+            icon="power_settings_new"
+            onClick={() => setShutdownOpen(true)}
+            className="text-red-500 border-red-200 hover:bg-red-50 hover:border-red-300"
+          >
+            Shutdown
+          </Button>
+          <Button
+            variant="outline"
+            fullWidth
+            icon="logout"
+            onClick={handleLogout}
+          >
+            Logout
+          </Button>
+        </div>
+
+        {/* App Info */}
+        <div className="text-center text-xs sm:text-sm text-text-muted py-4">
+          <p>{APP_CONFIG.name} v{APP_CONFIG.version}</p>
+          <p className="mt-1">Local Mode - All data stored on your machine</p>
+        </div>
+      </div>
+
+      <LanguageSwitcher
+        hideTrigger
+        isOpen={langOpen}
+        onClose={(next) => {
+          setLangOpen(false);
+          setLocale(next);
+        }}
+      />
+      <ConfirmModal
+        isOpen={shutdownOpen}
+        onClose={() => setShutdownOpen(false)}
+        onConfirm={handleShutdown}
+        title="Close Proxy"
+        message="Are you sure you want to close the proxy server?"
+        confirmText="Close"
+        cancelText="Cancel"
+        variant="danger"
+        loading={isShuttingDown}
+      />
+
+      <Modal
+        isOpen={dbAuth.open}
+        onClose={() => setDbAuth({ open: false, mode: "", password: "" })}
+        title="Confirm Password"
+        size="sm"
+        footer={
+          <>
+            <Button variant="ghost" onClick={() => setDbAuth({ open: false, mode: "", password: "" })} disabled={dbLoading}>
+              Cancel
+            </Button>
+            <Button variant="primary" onClick={handleDbAuthConfirm} loading={dbLoading} disabled={!dbAuth.password}>
+              Confirm
+            </Button>
+          </>
+        }
+      >
+        <p className="text-text-muted mb-3 text-sm">
+          Enter your current password to {dbAuth.mode === "export" ? "export" : "import"} the database.
+        </p>
+        <Input
+          type="password"
+          value={dbAuth.password}
+          onChange={(e) => setDbAuth((s) => ({ ...s, password: e.target.value }))}
+          onKeyDown={(e) => { if (e.key === "Enter" && dbAuth.password) handleDbAuthConfirm(); }}
+          placeholder="Current password"
+          autoFocus
+        />
+      </Modal>
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/AddApiKeyModal.js b/src/app/(dashboard)/dashboard/providers/[id]/AddApiKeyModal.js
new file mode 100644
index 0000000..0a27204
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/[id]/AddApiKeyModal.js
@@ -0,0 +1,415 @@
+"use client";
+
+import { useState } from "react";
+import PropTypes from "prop-types";
+import { Button, Badge, Input, Modal, Select } from "@/shared/components";
+import { AI_PROVIDERS } from "@/shared/constants/providers";
+
+const BULK_PLACEHOLDER = `name1|sk-key1\nname2|sk-key2\nsk-key-only-auto-named`;
+
+export default function AddApiKeyModal({ isOpen, provider, providerName, isCompatible, isAnthropic, authType, authHint, website, proxyPools, error, onSave, onBulkDone, onClose }) {
+  const NONE_PROXY_POOL_VALUE = "__none__";
+  const isOllamaLocal = provider === "ollama-local";
+  const isCookie = authType === "cookie";
+  const isXaiApiKey = provider === "xai" && !isCookie;
+  const credentialLabel = isCookie ? "Cookie Value" : "API Key";
+  const credentialPlaceholder = isCookie
+    ? (provider === "grok-web" ? "sso=xxxxx... or just the raw value" : "eyJhbGciOi...")
+    : (isXaiApiKey ? "xai-..." : "");
+
+  const isAzure = provider === "azure";
+  const isCloudflareAi = provider === "cloudflare-ai";
+  const providerRegions = AI_PROVIDERS?.[provider]?.regions || null;
+  const defaultRegion = AI_PROVIDERS?.[provider]?.defaultRegion || providerRegions?.[0]?.id || "";
+
+  const [formData, setFormData] = useState({
+    name: "",
+    apiKey: "",
+    defaultModel: "",
+    priority: 1,
+    proxyPoolId: NONE_PROXY_POOL_VALUE,
+    ollamaHostUrl: "",
+  });
+  const [azureData, setAzureData] = useState({
+    azureEndpoint: "",
+    apiVersion: "2024-10-01-preview",
+    deployment: "",
+    organization: "",
+  });
+  const [cloudflareData, setCloudflareData] = useState({ accountId: "" });
+  const [region, setRegion] = useState(defaultRegion);
+  const [validating, setValidating] = useState(false);
+  const [validationResult, setValidationResult] = useState(null);
+  const [saving, setSaving] = useState(false);
+  const bulkPlaceholder = isCloudflareAi
+    ? `name1|sk-key1|acc123456\nname2|sk-key2|def789012\nsk-key-only-auto-named`
+    : BULK_PLACEHOLDER;
+
+  const [mode, setMode] = useState("single"); // "single" | "bulk"
+  const [bulkText, setBulkText] = useState("");
+  const [bulkResult, setBulkResult] = useState(null); // { success, failed }
+
+  const buildProviderSpecificData = () => {
+    if (isOllamaLocal && formData.ollamaHostUrl.trim()) {
+      return { baseUrl: formData.ollamaHostUrl.trim() };
+    }
+    if (isAzure) {
+      return {
+        azureEndpoint: azureData.azureEndpoint,
+        apiVersion: azureData.apiVersion,
+        deployment: azureData.deployment,
+        organization: azureData.organization,
+      };
+    }
+    if (isCloudflareAi) {
+      return { accountId: cloudflareData.accountId };
+    }
+    if (providerRegions && region) {
+      return { region };
+    }
+    return undefined;
+  };
+
+  const handleValidate = async () => {
+    setValidating(true);
+    try {
+      const res = await fetch("/api/providers/validate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ provider, apiKey: formData.apiKey, providerSpecificData: buildProviderSpecificData() }),
+      });
+      const data = await res.json();
+      setValidationResult(data.valid ? "success" : "failed");
+    } catch {
+      setValidationResult("failed");
+    } finally {
+      setValidating(false);
+    }
+  };
+
+  const handleSubmit = async () => {
+    if (!provider) return;
+    if (!isOllamaLocal && !formData.apiKey) return;
+    if (!isOllamaLocal) {
+      // Non-ollama providers require a name
+      if (!formData.name) return;
+    }
+    if (isCompatible && !formData.defaultModel.trim()) return;
+
+    setSaving(true);
+    try {
+      let isValid = false;
+      try {
+        setValidating(true);
+        setValidationResult(null);
+        const res = await fetch("/api/providers/validate", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ provider, apiKey: formData.apiKey, providerSpecificData: buildProviderSpecificData() }),
+        });
+        const data = await res.json();
+        isValid = !!data.valid;
+        setValidationResult(isValid ? "success" : "failed");
+      } catch {
+        setValidationResult("failed");
+      } finally {
+        setValidating(false);
+      }
+
+      await onSave({
+        name: formData.name || (isOllamaLocal ? "Ollama Local" : ""),
+        apiKey: formData.apiKey,
+        defaultModel: isCompatible ? formData.defaultModel.trim() : undefined,
+        priority: formData.priority,
+        proxyPoolId: formData.proxyPoolId === NONE_PROXY_POOL_VALUE ? null : formData.proxyPoolId,
+        testStatus: isValid ? "active" : "unknown",
+        providerSpecificData: buildProviderSpecificData()
+      });
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleBulkSubmit = async () => {
+    const lines = bulkText.split("\n").map(l => l.trim()).filter(Boolean);
+    if (!lines.length) return;
+    setSaving(true);
+    setBulkResult(null);
+    let success = 0;
+    let failed = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const parts = lines[i].split("|");
+      const baseName = parts.length >= 2 ? parts[0].trim() : "Key";
+      const name = `${baseName} ${i + 1}`;
+
+      let apiKey;
+      let providerSpecificData;
+      if (isCloudflareAi && parts.length >= 3) {
+        // Format: name|apiKey|accountId
+        apiKey = parts.slice(1, -1).join("|").trim();
+        providerSpecificData = { accountId: parts[parts.length - 1].trim() };
+      } else {
+        apiKey = parts.length >= 2 ? parts.slice(1).join("|").trim() : parts[0].trim();
+      }
+
+      try {
+        const res = await fetch("/api/providers", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            provider,
+            apiKey,
+            name,
+            priority: 1,
+            testStatus: "unknown",
+            ...(providerSpecificData ? { providerSpecificData } : {}),
+          }),
+        });
+        if (res.ok) success++;
+        else failed++;
+      } catch {
+        failed++;
+      }
+    }
+    setSaving(false);
+    setBulkResult({ success, failed });
+    if (success > 0 && onBulkDone) onBulkDone();
+  };
+
+  if (!provider) return null;
+
+  return (
+    <Modal isOpen={isOpen} title={`Add ${providerName || provider} ${credentialLabel}`} onClose={onClose}>
+      <div className="flex flex-col gap-4">
+        {/* Mode switcher */}
+        <div className="flex gap-2">
+          <Button size="sm" variant={mode === "single" ? "primary" : "ghost"} onClick={() => { setMode("single"); setBulkResult(null); }}>Single</Button>
+          <Button size="sm" variant={mode === "bulk" ? "primary" : "ghost"} onClick={() => { setMode("bulk"); setBulkResult(null); }}>Bulk Add</Button>
+        </div>
+
+        {mode === "bulk" && (
+          <div className="flex flex-col gap-3">
+            <p className="text-xs text-text-muted">
+              {isCloudflareAi
+                ? <>One key per line. Format: <code>name|apiKey|accountId</code> or just <code>apiKey</code> (auto-named by index).</>
+                : <>One key per line. Format: <code>name|apiKey</code> or just <code>apiKey</code> (auto-named by index).</>
+              }
+            </p>
+            <textarea
+              className="w-full rounded border border-accent/30 bg-sidebar p-2 text-sm font-mono resize-y min-h-[140px] focus:outline-none focus:ring-1 focus:ring-primary"
+              placeholder={bulkPlaceholder}
+              value={bulkText}
+              onChange={(e) => setBulkText(e.target.value)}
+            />
+            {bulkResult && (
+              <div className={`text-sm font-medium ${bulkResult.failed > 0 ? "text-yellow-400" : "text-green-400"}`}>
+                ✓ {bulkResult.success} added{bulkResult.failed > 0 ? `, ✗ ${bulkResult.failed} failed` : ""}
+              </div>
+            )}
+            <div className="flex gap-2">
+              <Button onClick={handleBulkSubmit} fullWidth disabled={saving || !bulkText.trim()}>
+                {saving ? "Adding..." : "Add All Keys"}
+              </Button>
+              <Button onClick={onClose} variant="ghost" fullWidth>Cancel</Button>
+            </div>
+          </div>
+        )}
+
+        {mode === "single" && (<>
+        <Input
+          label="Name"
+          value={formData.name}
+          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+          placeholder={isOllamaLocal ? "Ollama Local" : "Production Key"}
+        />
+        {isOllamaLocal && (
+          <div className="flex gap-2">
+            <Input
+              label="Ollama Host URL"
+              value={formData.ollamaHostUrl}
+              onChange={(e) => setFormData({ ...formData, ollamaHostUrl: e.target.value })}
+              placeholder="http://localhost:11434"
+              className="flex-1"
+            />
+            <div className="pt-6">
+              <Button onClick={handleValidate} disabled={validating || saving} variant="secondary">
+                {validating ? "Checking..." : "Check"}
+              </Button>
+            </div>
+          </div>
+        )}
+        {!isOllamaLocal && (
+          <div className="flex gap-2">
+            <Input
+              label={credentialLabel}
+              type={isCookie ? "text" : "password"}
+              value={formData.apiKey}
+              onChange={(e) => setFormData({ ...formData, apiKey: e.target.value })}
+              placeholder={credentialPlaceholder}
+              className="flex-1"
+            />
+            <div className="pt-6">
+              <Button onClick={handleValidate} disabled={!formData.apiKey || validating || saving} variant="secondary">
+                {validating ? "Checking..." : "Check"}
+              </Button>
+            </div>
+          </div>
+        )}
+        {isXaiApiKey && (
+          <p className="text-xs text-text-muted">
+            Use a direct xAI API key from console.x.ai. This is separate from Grok Build OAuth.
+          </p>
+        )}
+        {isCookie && authHint && (
+          <p className="text-xs text-text-muted">
+            {authHint}
+            {website && (
+              <>
+                {" "}
+                <a href={website} target="_blank" rel="noopener noreferrer" className="text-primary underline">
+                  Open {website.replace(/^https?:\/\//, "")}
+                </a>
+              </>
+            )}
+          </p>
+        )}
+        {providerRegions && (
+          <Select
+            label="Region"
+            value={region}
+            onChange={(e) => setRegion(e.target.value)}
+            options={providerRegions.map((r) => ({ value: r.id, label: r.label }))}
+          />
+        )}
+        {isCompatible && (
+          <Input
+            label="Default Model"
+            value={formData.defaultModel}
+            onChange={(e) => setFormData({ ...formData, defaultModel: e.target.value })}
+            placeholder={isAnthropic ? "claude-3-5-sonnet-latest" : "gpt-4o-mini"}
+          />
+        )}
+        {isOllamaLocal && (
+          <p className="text-xs text-text-muted">
+            Leave blank to use <code>http://localhost:11434</code>. For remote Ollama, enter the full host URL (e.g. <code>http://192.168.1.10:11434</code>).
+          </p>
+        )}
+        {validationResult && (
+          <Badge variant={validationResult === "success" ? "success" : "error"}>
+            {validationResult === "success" ? "Valid" : "Invalid"}
+          </Badge>
+        )}
+        {error && (
+          <p className="text-xs text-red-500 break-words">{error}</p>
+        )}
+        {isCompatible && (
+          <p className="text-xs text-text-muted">
+            Enter the model ID exactly as your compatible endpoint expects it. This model will be saved as the connection default.
+          </p>
+        )}
+        {isCloudflareAi && (
+          <div className="bg-sidebar/50 p-4 rounded-lg border border-accent/20">
+            <h3 className="font-semibold mb-3 text-sm">Cloudflare Workers AI</h3>
+            <Input
+              label="Account ID"
+              value={cloudflareData.accountId}
+              onChange={(e) => setCloudflareData({ ...cloudflareData, accountId: e.target.value })}
+              placeholder="abc123def456..."
+            />
+            <p className="text-xs text-text-muted mt-2">
+              Find your Account ID in the right sidebar of <a href="https://dash.cloudflare.com" target="_blank" rel="noopener noreferrer" className="text-primary underline">dash.cloudflare.com</a>
+            </p>
+          </div>
+        )}
+        {isAzure && (
+          <div className="bg-sidebar/50 p-4 rounded-lg border border-accent/20">
+            <h3 className="font-semibold mb-3 text-sm">Azure OpenAI Configuration</h3>
+            <div className="flex flex-col gap-3">
+              <Input
+                label="Azure Endpoint"
+                value={azureData.azureEndpoint}
+                onChange={(e) => setAzureData({ ...azureData, azureEndpoint: e.target.value })}
+                placeholder="https://your-resource.openai.azure.com"
+              />
+              <Input
+                label="Deployment Name"
+                value={azureData.deployment}
+                onChange={(e) => setAzureData({ ...azureData, deployment: e.target.value })}
+                placeholder="gpt-4"
+              />
+              <Input
+                label="API Version"
+                value={azureData.apiVersion}
+                onChange={(e) => setAzureData({ ...azureData, apiVersion: e.target.value })}
+                placeholder="2024-10-01-preview"
+              />
+              <Input
+                label="Organization"
+                value={azureData.organization}
+                onChange={(e) => setAzureData({ ...azureData, organization: e.target.value })}
+                placeholder="Organization ID"
+              />
+            </div>
+          </div>
+        )}
+
+        <Input
+          label="Priority"
+          type="number"
+          value={formData.priority}
+          onChange={(e) => setFormData({ ...formData, priority: Number.parseInt(e.target.value) || 1 })}
+        />
+
+        <Select
+          label="Proxy Pool"
+          value={formData.proxyPoolId}
+          onChange={(e) => setFormData({ ...formData, proxyPoolId: e.target.value })}
+          options={[
+            { value: NONE_PROXY_POOL_VALUE, label: "None" },
+            ...(proxyPools || []).map((pool) => ({ value: pool.id, label: pool.name })),
+          ]}
+          placeholder="None"
+        />
+
+        {(proxyPools || []).length === 0 && (
+          <p className="text-xs text-text-muted">
+            No active proxy pools available. Create one in Proxy Pools page first.
+          </p>
+        )}
+
+        <p className="text-xs text-text-muted">
+          Legacy manual proxy fields are still accepted by API for backward compatibility.
+        </p>
+
+        <div className="flex gap-2">
+          <Button onClick={handleSubmit} fullWidth disabled={saving || (!isOllamaLocal && (!formData.name || !formData.apiKey)) || (isCompatible && !formData.defaultModel.trim()) || (isAzure && (!azureData.azureEndpoint || !azureData.deployment || !azureData.organization)) || (isCloudflareAi && !cloudflareData.accountId)}>
+            {saving ? "Saving..." : "Save"}
+          </Button>
+          <Button onClick={onClose} variant="ghost" fullWidth>
+            Cancel
+          </Button>
+        </div>
+        </>)}
+      </div>
+    </Modal>
+  );
+}
+
+AddApiKeyModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  provider: PropTypes.string,
+  providerName: PropTypes.string,
+  isCompatible: PropTypes.bool,
+  isAnthropic: PropTypes.bool,
+  authType: PropTypes.string,
+  authHint: PropTypes.string,
+  website: PropTypes.string,
+  proxyPools: PropTypes.arrayOf(PropTypes.shape({
+    id: PropTypes.string,
+    name: PropTypes.string,
+  })),
+  error: PropTypes.string,
+  onSave: PropTypes.func.isRequired,
+  onBulkDone: PropTypes.func,
+  onClose: PropTypes.func.isRequired,
+};
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/AddCustomModelModal.js b/src/app/(dashboard)/dashboard/providers/[id]/AddCustomModelModal.js
new file mode 100644
index 0000000..d0bf165
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/[id]/AddCustomModelModal.js
@@ -0,0 +1,125 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import PropTypes from "prop-types";
+import { Button, Modal } from "@/shared/components";
+
+export default function AddCustomModelModal({ isOpen, providerAlias, providerDisplayAlias, onSave, onClose }) {
+  const [modelId, setModelId] = useState("");
+  const [testStatus, setTestStatus] = useState(null); // null | "testing" | "ok" | "error"
+  const [testError, setTestError] = useState("");
+  const [saving, setSaving] = useState(false);
+
+  // Reset state when modal opens
+  useEffect(() => {
+    if (isOpen) { setModelId(""); setTestStatus(null); setTestError(""); }
+  }, [isOpen]);
+
+  // Strip provider's own alias prefix (e.g. "cc/model" -> "model" for cc provider)
+  const stripAlias = (id) => {
+    const prefix = `${providerAlias}/`;
+    return id.startsWith(prefix) ? id.slice(prefix.length) : id;
+  };
+
+  const handleTest = async () => {
+    const cleanId = stripAlias(modelId.trim());
+    if (!cleanId) return;
+    setTestStatus("testing");
+    setTestError("");
+    try {
+      const res = await fetch("/api/models/test", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: `${providerAlias}/${cleanId}` }),
+      });
+      const data = await res.json();
+      setTestStatus(data.ok ? "ok" : "error");
+      setTestError(data.error || "");
+    } catch (err) {
+      setTestStatus("error");
+      setTestError(err.message);
+    }
+  };
+
+  const handleSave = async () => {
+    const cleanId = stripAlias(modelId.trim());
+    if (!cleanId || saving) return;
+    setSaving(true);
+    try {
+      await onSave(cleanId);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleKeyDown = (e) => {
+    if (e.key === "Enter") handleTest();
+  };
+
+  return (
+    <Modal isOpen={isOpen} onClose={onClose} title="Add Custom Model">
+      <div className="flex flex-col gap-4">
+        <div>
+          <label className="text-sm font-medium mb-1.5 block">Model ID</label>
+          <div className="flex gap-2">
+            <input
+              type="text"
+              value={modelId}
+              onChange={(e) => { setModelId(e.target.value); setTestStatus(null); setTestError(""); }}
+              onKeyDown={handleKeyDown}
+              placeholder="e.g. claude-opus-4-5"
+              className="flex-1 px-3 py-2 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+              autoFocus
+            />
+            <Button
+              variant="secondary"
+              icon="science"
+              loading={testStatus === "testing"}
+              onClick={handleTest}
+              disabled={!modelId.trim() || testStatus === "testing"}
+            >
+              {testStatus === "testing" ? "Testing..." : "Test"}
+            </Button>
+          </div>
+          <p className="text-xs text-text-muted mt-1">
+            Sent to provider as: <code className="font-mono bg-sidebar px-1 rounded">{stripAlias(modelId.trim()) || "model-id"}</code>
+          </p>
+        </div>
+
+        {/* Test result */}
+        {testStatus === "ok" && (
+          <div className="flex items-center gap-2 text-sm text-green-600">
+            <span className="material-symbols-outlined text-base">check_circle</span>
+            Model is reachable
+          </div>
+        )}
+        {testStatus === "error" && (
+          <div className="flex items-start gap-2 text-sm text-red-500">
+            <span className="material-symbols-outlined text-base shrink-0">cancel</span>
+            <span>{testError || "Model not reachable"}</span>
+          </div>
+        )}
+
+        <div className="flex gap-2 pt-1">
+          <Button onClick={onClose} variant="ghost" fullWidth size="sm">Cancel</Button>
+          <Button
+            onClick={handleSave}
+            fullWidth
+            size="sm"
+            disabled={!modelId.trim() || saving}
+          >
+            {saving ? "Adding..." : "Add Model"}
+          </Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+AddCustomModelModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  providerAlias: PropTypes.string.isRequired,
+  providerDisplayAlias: PropTypes.string.isRequired,
+  onSave: PropTypes.func.isRequired,
+  onClose: PropTypes.func.isRequired,
+};
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/BulkImportCodexModal.js b/src/app/(dashboard)/dashboard/providers/[id]/BulkImportCodexModal.js
new file mode 100644
index 0000000..d18abef
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/[id]/BulkImportCodexModal.js
@@ -0,0 +1,150 @@
+"use client";
+
+import { useState } from "react";
+import PropTypes from "prop-types";
+import { Button, Modal } from "@/shared/components";
+import { translate } from "@/i18n/runtime";
+
+const PLACEHOLDER = `[
+  {
+    "accessToken": "eyJhbGc...",
+    "refreshToken": "rt_...",
+    "idToken": "eyJhbGc...",
+    "email": "user@example.com"
+  }
+]`;
+
+function normalizeToArray(parsed) {
+  if (Array.isArray(parsed)) return parsed;
+  if (parsed && typeof parsed === "object") {
+    if (Array.isArray(parsed.accounts)) return parsed.accounts;
+    return [parsed];
+  }
+  return null;
+}
+
+export default function BulkImportCodexModal({ isOpen, onClose, onSuccess }) {
+  const [jsonText, setJsonText] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [parseError, setParseError] = useState("");
+  const [result, setResult] = useState(null);
+
+  const handleClose = () => {
+    if (submitting) return;
+    setJsonText("");
+    setParseError("");
+    setResult(null);
+    onClose();
+  };
+
+  const handleSubmit = async () => {
+    setParseError("");
+    setResult(null);
+
+    const trimmed = jsonText.trim();
+    if (!trimmed) return;
+
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (err) {
+      setParseError(`${translate("Invalid JSON")}: ${err.message}`);
+      return;
+    }
+
+    const accounts = normalizeToArray(parsed);
+    if (!accounts || accounts.length === 0) {
+      setParseError(translate("No accounts found in input"));
+      return;
+    }
+
+    setSubmitting(true);
+    try {
+      const res = await fetch("/api/oauth/codex/bulk-import", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ accounts }),
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        setParseError(data?.error || `Request failed: ${res.status}`);
+        return;
+      }
+      setResult(data);
+      if (data.success > 0 && typeof onSuccess === "function") {
+        onSuccess();
+      }
+    } catch (err) {
+      setParseError(err.message || translate("Request failed"));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const failedItems = result?.results?.filter((r) => !r.ok) || [];
+
+  return (
+    <Modal isOpen={isOpen} title={translate("Bulk Add Codex Accounts")} onClose={handleClose}>
+      <div className="flex flex-col gap-4">
+        <p className="text-xs text-text-muted">
+          {translate(
+            "Paste an array of codex account JSON objects. Each must include accessToken (and ideally refreshToken, idToken)."
+          )}
+        </p>
+
+        <textarea
+          className="w-full rounded border border-accent/30 bg-sidebar p-2 text-sm font-mono resize-y min-h-[240px] focus:outline-none focus:ring-1 focus:ring-primary"
+          placeholder={PLACEHOLDER}
+          value={jsonText}
+          onChange={(e) => setJsonText(e.target.value)}
+          disabled={submitting}
+        />
+
+        {parseError && (
+          <p className="text-xs text-red-500 break-words">{parseError}</p>
+        )}
+
+        {result && (
+          <div className="flex flex-col gap-2">
+            <div
+              className={`text-sm font-medium ${
+                result.failed > 0 ? "text-yellow-400" : "text-green-400"
+              }`}
+            >
+              ✓ {result.success} {translate("added")}
+              {result.failed > 0 ? `, ✗ ${result.failed} ${translate("failed")}` : ""}
+            </div>
+            {failedItems.length > 0 && (
+              <ul className="rounded border border-accent/20 bg-sidebar/50 p-2 text-xs font-mono max-h-40 overflow-y-auto">
+                {failedItems.map((item) => (
+                  <li key={item.index} className="text-red-400">
+                    [{item.index}] {item.error}
+                  </li>
+                ))}
+              </ul>
+            )}
+          </div>
+        )}
+
+        <div className="flex gap-2">
+          <Button
+            onClick={handleSubmit}
+            fullWidth
+            disabled={submitting || !jsonText.trim()}
+          >
+            {submitting ? translate("Importing...") : translate("Import All")}
+          </Button>
+          <Button onClick={handleClose} variant="ghost" fullWidth disabled={submitting}>
+            {translate("Close")}
+          </Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+BulkImportCodexModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  onClose: PropTypes.func.isRequired,
+  onSuccess: PropTypes.func,
+};
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/CompatibleModelsSection.js b/src/app/(dashboard)/dashboard/providers/[id]/CompatibleModelsSection.js
new file mode 100644
index 0000000..bfc12a1
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/[id]/CompatibleModelsSection.js
@@ -0,0 +1,232 @@
+"use client";
+
+import { useState } from "react";
+import PropTypes from "prop-types";
+import { Button } from "@/shared/components";
+import { getProviderCustomModelRows } from "@/shared/utils/providerCustomModels";
+function CompatibleModelRow({ modelId, fullModel, copied, onCopy, onDeleteAlias, onTest, testStatus, isTesting }) {
+  const borderColor = testStatus === "ok"
+    ? "border-green-500/40"
+    : testStatus === "error"
+    ? "border-red-500/40"
+    : "border-border";
+
+  const iconColor = testStatus === "ok"
+    ? "#22c55e"
+    : testStatus === "error"
+    ? "#ef4444"
+    : undefined;
+
+  return (
+    <div className={`flex items-center gap-3 p-3 rounded-lg border ${borderColor} hover:bg-sidebar/50`}>
+      <span
+        className="material-symbols-outlined text-base text-text-muted"
+        style={iconColor ? { color: iconColor } : undefined}
+      >
+        {testStatus === "ok" ? "check_circle" : testStatus === "error" ? "cancel" : "smart_toy"}
+      </span>
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium truncate">{modelId}</p>
+        <div className="flex items-center gap-1 mt-1">
+          <code className="text-xs text-text-muted font-mono bg-sidebar px-1.5 py-0.5 rounded">{fullModel}</code>
+          <div className="relative group/btn">
+            <button
+              onClick={() => onCopy(fullModel, `model-${modelId}`)}
+              className="p-0.5 hover:bg-sidebar rounded text-text-muted hover:text-primary"
+            >
+              <span className="material-symbols-outlined text-sm">
+                {copied === `model-${modelId}` ? "check" : "content_copy"}
+              </span>
+            </button>
+            <span className="pointer-events-none absolute top-5 left-1/2 -translate-x-1/2 text-[10px] text-text-muted whitespace-nowrap opacity-0 group-hover/btn:opacity-100 transition-opacity">
+              {copied === `model-${modelId}` ? "Copied!" : "Copy"}
+            </span>
+          </div>
+          {onTest && (
+            <div className="relative group/btn">
+              <button
+                onClick={onTest}
+                disabled={isTesting}
+                className="p-0.5 hover:bg-sidebar rounded text-text-muted hover:text-primary transition-colors"
+              >
+                <span className="material-symbols-outlined text-sm" style={isTesting ? { animation: "spin 1s linear infinite" } : undefined}>
+                  {isTesting ? "progress_activity" : "science"}
+                </span>
+              </button>
+              <span className="pointer-events-none absolute top-5 left-1/2 -translate-x-1/2 text-[10px] text-text-muted whitespace-nowrap opacity-0 group-hover/btn:opacity-100 transition-opacity">
+                {isTesting ? "Testing..." : "Test"}
+              </span>
+            </div>
+          )}
+        </div>
+      </div>
+      <button
+        onClick={onDeleteAlias}
+        className="p-1 hover:bg-red-50 rounded text-red-500"
+        title="Remove model"
+      >
+        <span className="material-symbols-outlined text-sm">delete</span>
+      </button>
+    </div>
+  );
+}
+
+export default function CompatibleModelsSection({ providerStorageAlias, providerDisplayAlias, modelAliases, customModels, copied, onCopy, onDeleteAlias, onAddCustomModel, onDeleteCustomModel, connections, isAnthropic }) {
+  const [newModel, setNewModel] = useState("");
+  const [adding, setAdding] = useState(false);
+  const [importing, setImporting] = useState(false);
+  const [testingModelId, setTestingModelId] = useState(null);
+  const [modelTestResults, setModelTestResults] = useState({});
+
+  const handleTestModel = async (modelId) => {
+    if (testingModelId) return;
+    setTestingModelId(modelId);
+    try {
+      const res = await fetch("/api/models/test", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: `${providerStorageAlias}/${modelId}` }),
+      });
+      const data = await res.json();
+      setModelTestResults((prev) => ({ ...prev, [modelId]: data.ok ? "ok" : "error" }));
+    } catch {
+      setModelTestResults((prev) => ({ ...prev, [modelId]: "error" }));
+    } finally {
+      setTestingModelId(null);
+    }
+  };
+
+  const allModels = getProviderCustomModelRows({
+    customModels,
+    modelAliases,
+    providerAlias: providerStorageAlias,
+    type: "llm",
+  });
+
+  const handleAdd = async () => {
+    if (!newModel.trim() || adding) return;
+    const modelId = newModel.trim();
+    if (allModels.some((model) => model.id === modelId)) {
+      alert("Model already exists for this provider.");
+      return;
+    }
+
+    setAdding(true);
+    try {
+      await onAddCustomModel(modelId);
+      setNewModel("");
+    } catch (error) {
+      console.log("Error adding model:", error);
+    } finally {
+      setAdding(false);
+    }
+  };
+
+  const handleImport = async () => {
+    if (importing) return;
+    const activeConnection = connections.find((conn) => conn.isActive !== false);
+    if (!activeConnection) return;
+
+    setImporting(true);
+    try {
+      const res = await fetch(`/api/providers/${activeConnection.id}/models`);
+      const data = await res.json();
+      if (!res.ok) {
+        alert(data.error || "Failed to import models");
+        return;
+      }
+      const models = data.models || [];
+      if (models.length === 0) {
+        alert("No models returned from /models.");
+        return;
+      }
+      let importedCount = 0;
+      for (const model of models) {
+        const modelId = model.id || model.name || model.model;
+        if (!modelId) continue;
+        if (allModels.some((entry) => entry.id === modelId)) continue;
+        await onAddCustomModel(modelId);
+        importedCount += 1;
+      }
+      if (importedCount === 0) {
+        alert("No new models were added.");
+      }
+    } catch (error) {
+      console.log("Error importing models:", error);
+    } finally {
+      setImporting(false);
+    }
+  };
+
+  const canImport = connections.some((conn) => conn.isActive !== false);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <p className="text-sm text-text-muted">
+        Add {isAnthropic ? "Anthropic" : "OpenAI"}-compatible models manually or import them from the /models endpoint.
+      </p>
+
+      <div className="flex items-end gap-2 flex-wrap">
+        <div className="flex-1 min-w-[240px]">
+          <label htmlFor="new-compatible-model-input" className="text-xs text-text-muted mb-1 block">Model ID</label>
+          <input
+            id="new-compatible-model-input"
+            type="text"
+            value={newModel}
+            onChange={(e) => setNewModel(e.target.value)}
+            onKeyDown={(e) => e.key === "Enter" && handleAdd()}
+            placeholder={isAnthropic ? "claude-3-opus-20240229" : "gpt-4o"}
+            className="w-full px-3 py-2 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+          />
+        </div>
+        <Button size="sm" icon="add" onClick={handleAdd} disabled={!newModel.trim() || adding}>
+          {adding ? "Adding..." : "Add"}
+        </Button>
+        <Button size="sm" variant="secondary" icon="download" onClick={handleImport} disabled={!canImport || importing}>
+          {importing ? "Importing..." : "Import from /models"}
+        </Button>
+      </div>
+
+      {!canImport && (
+        <p className="text-xs text-text-muted">
+          Add a connection to enable importing models.
+        </p>
+      )}
+
+      {allModels.length > 0 && (
+        <div className="flex flex-col gap-3">
+          {allModels.map(({ id, alias, source }) => (
+            <CompatibleModelRow
+              key={`${source}-${providerStorageAlias}/${id}`}
+              modelId={id}
+              fullModel={`${providerDisplayAlias}/${id}`}
+              copied={copied}
+              onCopy={onCopy}
+              onDeleteAlias={() => source === "custom" ? onDeleteCustomModel(id) : onDeleteAlias(alias)}
+              onTest={connections.length > 0 ? () => handleTestModel(id) : undefined}
+              testStatus={modelTestResults[id]}
+              isTesting={testingModelId === id}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+CompatibleModelsSection.propTypes = {
+  providerStorageAlias: PropTypes.string.isRequired,
+  providerDisplayAlias: PropTypes.string.isRequired,
+  modelAliases: PropTypes.object.isRequired,
+  customModels: PropTypes.arrayOf(PropTypes.object),
+  copied: PropTypes.string,
+  onCopy: PropTypes.func.isRequired,
+  onDeleteAlias: PropTypes.func.isRequired,
+  onAddCustomModel: PropTypes.func.isRequired,
+  onDeleteCustomModel: PropTypes.func.isRequired,
+  connections: PropTypes.arrayOf(PropTypes.shape({
+    id: PropTypes.string,
+    isActive: PropTypes.bool,
+  })).isRequired,
+  isAnthropic: PropTypes.bool,
+};
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/ConnectionRow.js b/src/app/(dashboard)/dashboard/providers/[id]/ConnectionRow.js
new file mode 100644
index 0000000..0b5bea1
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/[id]/ConnectionRow.js
@@ -0,0 +1,318 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { getStatusVariant as getConnectionStatusVariant } from "@/shared/utils/connectionStatus";
+import PropTypes from "prop-types";
+import { Badge, Toggle, Tooltip } from "@/shared/components";
+import CooldownTimer from "./CooldownTimer";
+
+export default function ConnectionRow({ connection, proxyPools, isOAuth, isFirst, isLast, onMoveUp, onMoveDown, onToggleActive, onUpdateProxy, onEdit, onDelete, oneByOneStatus = null, autoPing = null }) {
+  const [showProxyDropdown, setShowProxyDropdown] = useState(false);
+  const [updatingProxy, setUpdatingProxy] = useState(false);
+  const proxyDropdownRef = useRef(null);
+
+  const proxyPoolMap = new Map((proxyPools || []).map((pool) => [pool.id, pool]));
+  const boundProxyPoolId = connection.providerSpecificData?.proxyPoolId || null;
+  const boundProxyPool = boundProxyPoolId ? proxyPoolMap.get(boundProxyPoolId) : null;
+  const hasLegacyProxy = connection.providerSpecificData?.connectionProxyEnabled === true && !!connection.providerSpecificData?.connectionProxyUrl;
+  const hasAnyProxy = !!boundProxyPoolId || hasLegacyProxy;
+  const proxyDisplayText = boundProxyPool
+    ? `Pool: ${boundProxyPool.name}`
+    : boundProxyPoolId
+      ? `Pool: ${boundProxyPoolId} (inactive/missing)`
+      : hasLegacyProxy
+        ? `Legacy: ${connection.providerSpecificData?.connectionProxyUrl}`
+        : "";
+  const autoPingTooltip = autoPing?.provider === "codex"
+    ? "Auto-starts the next 5h Codex window after reset by sending a tiny gpt-5.5 request. Consumes a small amount of quota."
+    : "When your 5h quota runs out, auto-sends a request the moment it resets so a new window starts right away.";
+
+  let maskedProxyUrl = "";
+  if (boundProxyPool?.proxyUrl || connection.providerSpecificData?.connectionProxyUrl) {
+    const rawProxyUrl = boundProxyPool?.proxyUrl || connection.providerSpecificData?.connectionProxyUrl;
+    try {
+      const parsed = new URL(rawProxyUrl);
+      maskedProxyUrl = `${parsed.protocol}//${parsed.hostname}${parsed.port ? `:${parsed.port}` : ""}`;
+    } catch {
+      maskedProxyUrl = rawProxyUrl;
+    }
+  }
+
+  const noProxyText = boundProxyPool?.noProxy || connection.providerSpecificData?.connectionNoProxy || "";
+
+  let proxyBadgeVariant = "default";
+  if (boundProxyPool?.isActive === true) {
+    proxyBadgeVariant = "success";
+  } else if (boundProxyPoolId || hasLegacyProxy) {
+    proxyBadgeVariant = "error";
+  }
+
+  // Close dropdown when clicking outside
+  useEffect(() => {
+    if (!showProxyDropdown) return;
+    const handler = (e) => {
+      if (proxyDropdownRef.current && !proxyDropdownRef.current.contains(e.target)) {
+        setShowProxyDropdown(false);
+      }
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [showProxyDropdown]);
+
+  const handleSelectProxy = async (poolId) => {
+    setUpdatingProxy(true);
+    try {
+      await onUpdateProxy(poolId === "__none__" ? null : poolId);
+    } finally {
+      setUpdatingProxy(false);
+      setShowProxyDropdown(false);
+    }
+  };
+
+  const rowAuthType = connection.authType || (isOAuth ? "oauth" : "apikey");
+  const isOAuthConnection = rowAuthType === "oauth";
+  const isCookieConnection = rowAuthType === "cookie";
+  const authIcon = isCookieConnection ? "cookie" : isOAuthConnection ? "lock" : "key";
+  const authLabel = isOAuthConnection ? "OAuth" : isCookieConnection ? "Cookie" : "API Key";
+  const displayName = connection.name?.trim()
+    || connection.email?.trim()
+    || connection.displayName?.trim()
+    || (isOAuthConnection ? "OAuth Account" : isCookieConnection ? "Cookie Account" : "API Key");
+  const secondaryDisplayName = connection.name?.trim() && connection.email?.trim() && connection.name.trim() !== connection.email.trim()
+    ? connection.email.trim()
+    : connection.name?.trim() && connection.displayName?.trim() && connection.name.trim() !== connection.displayName.trim()
+      ? connection.displayName.trim()
+      : null;
+
+  // Use useState + useEffect for impure Date.now() to avoid calling during render
+  const [isCooldown, setIsCooldown] = useState(false);
+
+  // Get earliest model lock timestamp (useEffect handles the Date.now() comparison)
+  const modelLockUntil = Object.entries(connection)
+    .filter(([k]) => k.startsWith("modelLock_"))
+    .map(([, v]) => v)
+    .filter(v => !!v)
+    .sort()[0] || null;
+
+  useEffect(() => {
+    const checkCooldown = () => {
+      const until = Object.entries(connection)
+        .filter(([k]) => k.startsWith("modelLock_"))
+        .map(([, v]) => v)
+        .filter(v => v && new Date(v).getTime() > Date.now())
+        .sort()[0] || null;
+      setIsCooldown(!!until);
+    };
+
+    checkCooldown();
+    const interval = modelLockUntil ? setInterval(checkCooldown, 1000) : null;
+    return () => {
+      if (interval) clearInterval(interval);
+    };
+  }, [modelLockUntil]);
+
+  // Determine effective status (override unavailable if cooldown expired)
+  const effectiveStatus = (connection.testStatus === "unavailable" && !isCooldown)
+    ? "active"  // Cooldown expired u2192 treat as active
+    : connection.testStatus;
+
+  const getStatusVariant = () => getConnectionStatusVariant(connection.isActive, effectiveStatus);
+
+  const getOneByOneVariant = () => {
+    if (!oneByOneStatus) return "default";
+    if (oneByOneStatus.state === "success") return "success";
+    if (oneByOneStatus.state === "failed") return "error";
+    if (oneByOneStatus.state === "testing") return "primary";
+    return "default";
+  };
+
+  const getOneByOneLabel = () => {
+    if (!oneByOneStatus) return null;
+    if (oneByOneStatus.state === "queued") return "queued";
+    if (oneByOneStatus.state === "testing") return "testing";
+    if (oneByOneStatus.state === "success") return "success";
+    if (oneByOneStatus.state === "failed") return oneByOneStatus.error ? `failed: ${oneByOneStatus.error}` : "failed";
+    return null;
+  };
+
+  return (
+    <div className={`group flex min-w-0 flex-col gap-3 rounded-lg p-2 transition-colors hover:bg-black/[0.02] dark:hover:bg-white/[0.02] sm:flex-row sm:items-center sm:justify-between ${connection.isActive === false ? "opacity-60" : ""}`}>
+      <div className="flex min-w-0 flex-1 items-start gap-2 sm:items-center sm:gap-3">
+        {/* Priority arrows */}
+        <div className="flex shrink-0 flex-col">
+          <button
+            onClick={onMoveUp}
+            disabled={isFirst}
+            className={`p-0.5 rounded ${isFirst ? "text-text-muted/30 cursor-not-allowed" : "hover:bg-sidebar text-text-muted hover:text-primary"}`}
+          >
+            <span className="material-symbols-outlined text-sm">keyboard_arrow_up</span>
+          </button>
+          <button
+            onClick={onMoveDown}
+            disabled={isLast}
+            className={`p-0.5 rounded ${isLast ? "text-text-muted/30 cursor-not-allowed" : "hover:bg-sidebar text-text-muted hover:text-primary"}`}
+          >
+            <span className="material-symbols-outlined text-sm">keyboard_arrow_down</span>
+          </button>
+        </div>
+        <span className="material-symbols-outlined shrink-0 text-base text-text-muted">
+          {authIcon}
+        </span>
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-medium truncate">{displayName}</p>
+          {secondaryDisplayName && (
+            <p className="text-xs text-text-muted truncate">{secondaryDisplayName}</p>
+          )}
+          <div className="mt-1 flex min-w-0 flex-wrap items-center gap-1.5 sm:gap-2">
+            <Badge variant={getStatusVariant()} size="sm" dot>
+              {connection.isActive === false ? "disabled" : (effectiveStatus || "Unknown")}
+            </Badge>
+            <Badge variant="default" size="sm">
+              {authLabel}
+            </Badge>
+            {hasAnyProxy && (
+              <Badge variant={proxyBadgeVariant} size="sm">
+                Proxy
+              </Badge>
+            )}
+            {isCooldown && connection.isActive !== false && <CooldownTimer until={modelLockUntil} />}
+            {connection.lastError && connection.isActive !== false && (
+              <span className="max-w-full truncate text-xs text-red-500 sm:max-w-[300px]" title={connection.lastError}>
+                {connection.lastError}
+              </span>
+            )}
+            <span className="text-xs text-text-muted">#{connection.priority}</span>
+            {connection.globalPriority && (
+              <span className="text-xs text-text-muted">Auto: {connection.globalPriority}</span>
+            )}
+            {getOneByOneLabel() && (
+              <Badge variant={getOneByOneVariant()} size="sm">
+                {getOneByOneLabel()}
+              </Badge>
+            )}
+          </div>
+          {hasAnyProxy && (
+            <div className="mt-1 flex items-center gap-2 flex-wrap">
+              <span className="max-w-full truncate text-[11px] text-text-muted sm:max-w-[420px]" title={proxyDisplayText}>
+                {proxyDisplayText}
+              </span>
+              {maskedProxyUrl && (
+                <code className="max-w-full truncate rounded bg-black/5 px-1 py-0.5 font-mono text-[10px] text-text-muted dark:bg-white/5 sm:max-w-[260px]">
+                  {maskedProxyUrl}
+                </code>
+              )}
+              {noProxyText && (
+                <span className="max-w-full truncate text-[11px] text-text-muted sm:max-w-[320px]" title={noProxyText}>
+                  no_proxy: {noProxyText}
+                </span>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+      <div className="flex w-full items-center justify-between gap-2 sm:w-auto sm:justify-end">
+        <div className="grid flex-1 grid-cols-3 gap-1 sm:flex sm:flex-none">
+          {/* Proxy button with inline dropdown */}
+          {(proxyPools || []).length > 0 && (
+            <div className="relative" ref={proxyDropdownRef}>
+              <button
+                onClick={() => setShowProxyDropdown((v) => !v)}
+                className={`flex w-full flex-col items-center rounded px-2 py-1 transition-colors hover:bg-black/5 dark:hover:bg-white/5 ${hasAnyProxy ? "text-primary" : "text-text-muted hover:text-primary"}`}
+                disabled={updatingProxy}
+              >
+                <span className="material-symbols-outlined text-[18px]">
+                  {updatingProxy ? "progress_activity" : "lan"}
+                </span>
+                <span className="text-[10px] leading-tight">Proxy</span>
+              </button>
+              {showProxyDropdown && (
+                <div className="absolute right-0 top-full z-50 mt-1 max-w-[78vw] min-w-[160px] rounded-lg border border-border bg-bg py-1 shadow-lg">
+                  <button
+                    onClick={() => handleSelectProxy("__none__")}
+                    className={`w-full text-left px-3 py-1.5 text-sm hover:bg-black/5 dark:hover:bg-white/5 ${!boundProxyPoolId ? "text-primary font-medium" : "text-text-main"}`}
+                  >
+                    None
+                  </button>
+                  {(proxyPools || []).map((pool) => (
+                    <button
+                      key={pool.id}
+                      onClick={() => handleSelectProxy(pool.id)}
+                      className={`w-full text-left px-3 py-1.5 text-sm hover:bg-black/5 dark:hover:bg-white/5 ${boundProxyPoolId === pool.id ? "text-primary font-medium" : "text-text-main"}`}
+                    >
+                      {pool.name}
+                    </button>
+                  ))}
+                </div>
+              )}
+            </div>
+          )}
+          {autoPing && (
+            <Tooltip text={autoPingTooltip}>
+              <button
+                onClick={() => autoPing.onToggle(!autoPing.on)}
+                className={`flex w-full flex-col items-center rounded px-2 py-1 transition-colors hover:bg-black/5 dark:hover:bg-white/5 ${autoPing.on ? "text-primary" : "text-text-muted hover:text-primary"}`}
+              >
+                <span className="material-symbols-outlined text-[18px]">bolt</span>
+                <span className="text-[10px] leading-tight">Auto-ping</span>
+              </button>
+            </Tooltip>
+          )}
+          <button onClick={onEdit} className="flex flex-col items-center rounded px-2 py-1 text-text-muted hover:bg-black/5 hover:text-primary dark:hover:bg-white/5">
+            <span className="material-symbols-outlined text-[18px]">edit</span>
+            <span className="text-[10px] leading-tight">Edit</span>
+          </button>
+          <button onClick={onDelete} className="flex flex-col items-center rounded px-2 py-1 text-red-500 hover:bg-red-500/10">
+            <span className="material-symbols-outlined text-[18px]">delete</span>
+            <span className="text-[10px] leading-tight">Delete</span>
+          </button>
+        </div>
+        <Toggle
+          size="sm"
+          checked={connection.isActive ?? true}
+          onChange={onToggleActive}
+          title={(connection.isActive ?? true) ? "Disable connection" : "Enable connection"}
+        />
+      </div>
+    </div>
+  );
+}
+
+ConnectionRow.propTypes = {
+  connection: PropTypes.shape({
+    id: PropTypes.string,
+    name: PropTypes.string,
+    email: PropTypes.string,
+    displayName: PropTypes.string,
+    modelLockUntil: PropTypes.string,
+    testStatus: PropTypes.string,
+    isActive: PropTypes.bool,
+    lastError: PropTypes.string,
+    priority: PropTypes.number,
+    globalPriority: PropTypes.number,
+  }).isRequired,
+  proxyPools: PropTypes.arrayOf(PropTypes.shape({
+    id: PropTypes.string,
+    name: PropTypes.string,
+    proxyUrl: PropTypes.string,
+    noProxy: PropTypes.string,
+    isActive: PropTypes.bool,
+  })),
+  isOAuth: PropTypes.bool.isRequired,
+  isFirst: PropTypes.bool.isRequired,
+  isLast: PropTypes.bool.isRequired,
+  onMoveUp: PropTypes.func.isRequired,
+  onMoveDown: PropTypes.func.isRequired,
+  onToggleActive: PropTypes.func.isRequired,
+  onUpdateProxy: PropTypes.func,
+  onEdit: PropTypes.func.isRequired,
+  onDelete: PropTypes.func.isRequired,
+  oneByOneStatus: PropTypes.shape({
+    state: PropTypes.string,
+    error: PropTypes.string,
+  }),
+  autoPing: PropTypes.shape({
+    on: PropTypes.bool,
+    onToggle: PropTypes.func,
+    provider: PropTypes.string,
+  }),
+};
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/CooldownTimer.js b/src/app/(dashboard)/dashboard/providers/[id]/CooldownTimer.js
new file mode 100644
index 0000000..50e99da
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/[id]/CooldownTimer.js
@@ -0,0 +1,42 @@
+import { useState, useEffect } from "react";
+import PropTypes from "prop-types";
+
+export default function CooldownTimer({ until }) {
+  const [remaining, setRemaining] = useState("");
+
+  useEffect(() => {
+    const updateRemaining = () => {
+      const diff = new Date(until).getTime() - Date.now();
+      if (diff <= 0) {
+        setRemaining("");
+        return;
+      }
+      const secs = Math.floor(diff / 1000);
+      if (secs < 60) {
+        setRemaining(`${secs}s`);
+      } else if (secs < 3600) {
+        setRemaining(`${Math.floor(secs / 60)}m ${secs % 60}s`);
+      } else {
+        const hrs = Math.floor(secs / 3600);
+        const mins = Math.floor((secs % 3600) / 60);
+        setRemaining(`${hrs}h ${mins}m`);
+      }
+    };
+
+    updateRemaining();
+    const interval = setInterval(updateRemaining, 1000);
+    return () => clearInterval(interval);
+  }, [until]);
+
+  if (!remaining) return null;
+
+  return (
+    <span className="text-xs text-orange-500 font-mono">
+      ⏱ {remaining}
+    </span>
+  );
+}
+
+CooldownTimer.propTypes = {
+  until: PropTypes.string.isRequired,
+};
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/EditCompatibleNodeModal.js b/src/app/(dashboard)/dashboard/providers/[id]/EditCompatibleNodeModal.js
new file mode 100644
index 0000000..d6d33de
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/[id]/EditCompatibleNodeModal.js
@@ -0,0 +1,161 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import PropTypes from "prop-types";
+import { Button, Badge, Input, Modal, Select } from "@/shared/components";
+
+export default function EditCompatibleNodeModal({ isOpen, node, onSave, onClose, isAnthropic }) {
+  const [formData, setFormData] = useState({
+    name: "",
+    prefix: "",
+    apiType: "chat",
+    baseUrl: "https://api.openai.com/v1",
+  });
+  const [saving, setSaving] = useState(false);
+  const [checkKey, setCheckKey] = useState("");
+  const [checkModelId, setCheckModelId] = useState("");
+  const [validating, setValidating] = useState(false);
+  const [validationResult, setValidationResult] = useState(null);
+
+  useEffect(() => {
+    if (node) {
+      setFormData({
+        name: node.name || "",
+        prefix: node.prefix || "",
+        apiType: node.apiType || "chat",
+        baseUrl: node.baseUrl || (isAnthropic ? "https://api.anthropic.com/v1" : "https://api.openai.com/v1"),
+      });
+    }
+  }, [node, isAnthropic]);
+
+  const apiTypeOptions = [
+    { value: "chat", label: "Chat Completions" },
+    { value: "responses", label: "Responses API" },
+  ];
+
+  const handleSubmit = async () => {
+    if (!formData.name.trim() || !formData.prefix.trim() || !formData.baseUrl.trim()) return;
+    setSaving(true);
+    try {
+      const payload = {
+        name: formData.name,
+        prefix: formData.prefix,
+        baseUrl: formData.baseUrl,
+      };
+      if (!isAnthropic) {
+        payload.apiType = formData.apiType;
+      }
+      await onSave(payload);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleValidate = async () => {
+    setValidating(true);
+    try {
+      const res = await fetch("/api/provider-nodes/validate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: formData.baseUrl,
+          apiKey: checkKey,
+          type: isAnthropic ? "anthropic-compatible" : "openai-compatible",
+          modelId: checkModelId.trim() || undefined
+        }),
+      });
+      const data = await res.json();
+      setValidationResult(data.valid ? "success" : "failed");
+    } catch {
+      setValidationResult("failed");
+    } finally {
+      setValidating(false);
+    }
+  };
+
+  if (!node) return null;
+
+  return (
+    <Modal isOpen={isOpen} title={`Edit ${isAnthropic ? "Anthropic" : "OpenAI"} Compatible`} onClose={onClose}>
+      <div className="flex flex-col gap-4">
+        <Input
+          label="Name"
+          value={formData.name}
+          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+          placeholder={`${isAnthropic ? "Anthropic" : "OpenAI"} Compatible (Prod)`}
+          hint="Required. A friendly label for this node."
+        />
+        <Input
+          label="Prefix"
+          value={formData.prefix}
+          onChange={(e) => setFormData({ ...formData, prefix: e.target.value })}
+          placeholder={isAnthropic ? "ac-prod" : "oc-prod"}
+          hint="Required. Used as the provider prefix for model IDs."
+        />
+        {!isAnthropic && (
+          <Select
+            label="API Type"
+            options={apiTypeOptions}
+            value={formData.apiType}
+            onChange={(e) => setFormData({ ...formData, apiType: e.target.value })}
+          />
+        )}
+        <Input
+          label="Base URL"
+          value={formData.baseUrl}
+          onChange={(e) => setFormData({ ...formData, baseUrl: e.target.value })}
+          placeholder={isAnthropic ? "https://api.anthropic.com/v1" : "https://api.openai.com/v1"}
+          hint={`Use the base URL (ending in /v1) for your ${isAnthropic ? "Anthropic" : "OpenAI"}-compatible API.`}
+        />
+        <div className="flex gap-2">
+          <Input
+            label="API Key (for Check)"
+            type="password"
+            value={checkKey}
+            onChange={(e) => setCheckKey(e.target.value)}
+            className="flex-1"
+          />
+          <div className="pt-6">
+            <Button onClick={handleValidate} disabled={!checkKey || validating || !formData.baseUrl.trim()} variant="secondary">
+              {validating ? "Checking..." : "Check"}
+            </Button>
+          </div>
+        </div>
+        <Input
+          label="Model ID (optional)"
+          value={checkModelId}
+          onChange={(e) => setCheckModelId(e.target.value)}
+          placeholder="e.g. my-model-id"
+          hint="If provider lacks /models endpoint, enter a model ID to validate via chat/completions instead."
+        />
+        {validationResult && (
+          <Badge variant={validationResult === "success" ? "success" : "error"}>
+            {validationResult === "success" ? "Valid" : "Invalid"}
+          </Badge>
+        )}
+        <div className="flex gap-2">
+          <Button onClick={handleSubmit} fullWidth disabled={!formData.name.trim() || !formData.prefix.trim() || !formData.baseUrl.trim() || saving}>
+            {saving ? "Saving..." : "Save"}
+          </Button>
+          <Button onClick={onClose} variant="ghost" fullWidth>
+            Cancel
+          </Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+EditCompatibleNodeModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  node: PropTypes.shape({
+    id: PropTypes.string,
+    name: PropTypes.string,
+    prefix: PropTypes.string,
+    apiType: PropTypes.string,
+    baseUrl: PropTypes.string,
+  }),
+  onSave: PropTypes.func.isRequired,
+  onClose: PropTypes.func.isRequired,
+  isAnthropic: PropTypes.bool,
+};
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/ModelRow.js b/src/app/(dashboard)/dashboard/providers/[id]/ModelRow.js
new file mode 100644
index 0000000..b011f58
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/[id]/ModelRow.js
@@ -0,0 +1,102 @@
+import PropTypes from "prop-types";
+import { CapacityBadges } from "@/shared/components";
+
+export default function ModelRow({ model, fullModel, alias, copied, onCopy, testStatus, isCustom, isFree, onDeleteAlias, onTest, isTesting, onDisable, caps, thinkingSuffix }) {
+  const displayModel = thinkingSuffix ? `${fullModel}(${thinkingSuffix})` : fullModel;
+  const borderColor = testStatus === "ok"
+    ? "border-green-500/40"
+    : testStatus === "error"
+    ? "border-red-500/40"
+    : "border-border";
+
+  const iconColor = testStatus === "ok"
+    ? "#22c55e"
+    : testStatus === "error"
+    ? "#ef4444"
+    : undefined;
+
+  return (
+    <div className={`group min-w-0 max-w-full rounded-lg border px-3 py-2 ${borderColor} hover:bg-sidebar/50`}>
+      <div className="flex min-w-0 items-start gap-2 sm:items-center">
+        <span
+          className="material-symbols-outlined shrink-0 text-base"
+          style={iconColor ? { color: iconColor } : undefined}
+        >
+          {testStatus === "ok" ? "check_circle" : testStatus === "error" ? "cancel" : "smart_toy"}
+        </span>
+        <div className="flex min-w-0 flex-1 flex-col gap-1">
+          <code className="max-w-[72vw] truncate rounded bg-sidebar px-1.5 py-0.5 font-mono text-xs text-text-muted sm:max-w-[360px]">{displayModel}</code>
+          <span className="flex min-w-0 items-center text-[9px] gap-1 pl-1">
+            {model.name && <span className="truncate text-[9px] italic text-text-muted/70">{model.name}</span>}
+            <CapacityBadges caps={caps} colorOverride="text-text-muted/70" size={12} />
+          </span>
+        </div>
+        {onTest && (
+          <div className="relative shrink-0 group/btn">
+            <button
+              onClick={onTest}
+              disabled={isTesting}
+              className={`rounded p-0.5 text-text-muted transition-opacity hover:bg-sidebar hover:text-primary ${isTesting ? "opacity-100" : "opacity-100 sm:opacity-0 sm:group-hover:opacity-100"}`}
+            >
+              <span className="material-symbols-outlined text-sm" style={isTesting ? { animation: "spin 1s linear infinite" } : undefined}>
+                {isTesting ? "progress_activity" : "science"}
+              </span>
+            </button>
+            <span className="pointer-events-none absolute mt-1 top-5 left-1/2 -translate-x-1/2 text-[10px] text-text-muted whitespace-nowrap opacity-0 group-hover/btn:opacity-100 transition-opacity">
+              {isTesting ? "Testing..." : "Test"}
+            </span>
+          </div>
+        )}
+        <div className="relative shrink-0 group/btn">
+          <button
+            onClick={() => onCopy(displayModel, `model-${model.id}`)}
+            className="rounded p-0.5 text-text-muted hover:bg-sidebar hover:text-primary"
+          >
+            <span className="material-symbols-outlined text-sm">
+              {copied === `model-${model.id}` ? "check" : "content_copy"}
+            </span>
+          </button>
+          <span className="pointer-events-none absolute mt-1 top-5 left-1/2 -translate-x-1/2 text-[10px] text-text-muted whitespace-nowrap opacity-0 group-hover/btn:opacity-100 transition-opacity">
+            {copied === `model-${model.id}` ? "Copied!" : "Copy"}
+          </span>
+        </div>
+        {isCustom ? (
+          <button
+            onClick={onDeleteAlias}
+            className="ml-auto rounded p-0.5 text-text-muted opacity-100 transition-opacity hover:bg-red-500/10 hover:text-red-500 sm:opacity-0 sm:group-hover:opacity-100"
+            title="Remove custom model"
+          >
+            <span className="material-symbols-outlined text-sm">close</span>
+          </button>
+        ) : onDisable ? (
+          <button
+            onClick={onDisable}
+            className="ml-auto rounded p-0.5 text-text-muted opacity-100 transition-opacity hover:bg-red-500/10 hover:text-red-500 sm:opacity-0 sm:group-hover:opacity-100"
+            title="Disable this model"
+          >
+            <span className="material-symbols-outlined text-sm">close</span>
+          </button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+ModelRow.propTypes = {
+  model: PropTypes.shape({
+    id: PropTypes.string.isRequired,
+  }).isRequired,
+  fullModel: PropTypes.string.isRequired,
+  alias: PropTypes.string,
+  copied: PropTypes.string,
+  onCopy: PropTypes.func.isRequired,
+  testStatus: PropTypes.oneOf(["ok", "error"]),
+  isCustom: PropTypes.bool,
+  isFree: PropTypes.bool,
+  onDeleteAlias: PropTypes.func,
+  onTest: PropTypes.func,
+  isTesting: PropTypes.bool,
+  onDisable: PropTypes.func,
+  caps: PropTypes.object,
+  thinkingSuffix: PropTypes.string,
+};
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/PassthroughModelsSection.js b/src/app/(dashboard)/dashboard/providers/[id]/PassthroughModelsSection.js
new file mode 100644
index 0000000..606db9e
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/[id]/PassthroughModelsSection.js
@@ -0,0 +1,174 @@
+"use client";
+
+import { useState } from "react";
+import PropTypes from "prop-types";
+import { Button } from "@/shared/components";
+import { getProviderCustomModelRows } from "@/shared/utils/providerCustomModels";
+
+function PassthroughModelRow({ modelId, fullModel, copied, onCopy, onDeleteAlias, onTest, testStatus, isTesting }) {
+  const borderColor = testStatus === "ok"
+    ? "border-green-500/40"
+    : testStatus === "error"
+    ? "border-red-500/40"
+    : "border-border";
+
+  const iconColor = testStatus === "ok"
+    ? "#22c55e"
+    : testStatus === "error"
+    ? "#ef4444"
+    : undefined;
+
+  return (
+    <div className={`flex items-center gap-3 p-3 rounded-lg border ${borderColor} hover:bg-sidebar/50`}>
+      <span
+        className="material-symbols-outlined text-base text-text-muted"
+        style={iconColor ? { color: iconColor } : undefined}
+      >
+        {testStatus === "ok" ? "check_circle" : testStatus === "error" ? "cancel" : "smart_toy"}
+      </span>
+
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium truncate">{modelId}</p>
+
+        <div className="flex items-center gap-1 mt-1">
+        <code className="text-xs text-text-muted font-mono bg-sidebar px-1.5 py-0.5 rounded">{fullModel}</code>
+          <div className="relative group/btn">
+            <button
+              onClick={() => onCopy(fullModel, `model-${modelId}`)}
+              className="p-0.5 hover:bg-sidebar rounded text-text-muted hover:text-primary"
+            >
+              <span className="material-symbols-outlined text-sm">
+                {copied === `model-${modelId}` ? "check" : "content_copy"}
+              </span>
+            </button>
+            <span className="pointer-events-none absolute top-5 left-1/2 -translate-x-1/2 text-[10px] text-text-muted whitespace-nowrap opacity-0 group-hover/btn:opacity-100 transition-opacity">
+              {copied === `model-${modelId}` ? "Copied!" : "Copy"}
+            </span>
+          </div>
+          {onTest && (
+            <div className="relative group/btn">
+              <button
+                onClick={onTest}
+                disabled={isTesting}
+                className="p-0.5 hover:bg-sidebar rounded text-text-muted hover:text-primary transition-colors"
+              >
+                <span className="material-symbols-outlined text-sm" style={isTesting ? { animation: "spin 1s linear infinite" } : undefined}>
+                  {isTesting ? "progress_activity" : "science"}
+                </span>
+              </button>
+              <span className="pointer-events-none absolute top-5 left-1/2 -translate-x-1/2 text-[10px] text-text-muted whitespace-nowrap opacity-0 group-hover/btn:opacity-100 transition-opacity">
+                {isTesting ? "Testing..." : "Test"}
+              </span>
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Delete button */}
+      <button
+        onClick={onDeleteAlias}
+        className="p-1 hover:bg-red-50 rounded text-red-500"
+        title="Remove model"
+      >
+        <span className="material-symbols-outlined text-sm">delete</span>
+      </button>
+    </div>
+  );
+}
+
+PassthroughModelRow.propTypes = {
+  modelId: PropTypes.string.isRequired,
+  fullModel: PropTypes.string.isRequired,
+  copied: PropTypes.string,
+  onCopy: PropTypes.func.isRequired,
+  onDeleteAlias: PropTypes.func.isRequired,
+  onTest: PropTypes.func,
+  testStatus: PropTypes.oneOf(["ok", "error"]),
+  isTesting: PropTypes.bool,
+};
+
+export default function PassthroughModelsSection({ providerAlias, modelAliases, customModels, copied, onCopy, onDeleteAlias, onAddCustomModel, onDeleteCustomModel }) {
+  const [newModel, setNewModel] = useState("");
+  const [adding, setAdding] = useState(false);
+
+  const allModels = getProviderCustomModelRows({
+    customModels,
+    modelAliases,
+    providerAlias,
+    type: "llm",
+  });
+
+  const handleAdd = async () => {
+    if (!newModel.trim() || adding) return;
+    const modelId = newModel.trim();
+
+    if (allModels.some((model) => model.id === modelId)) {
+      alert("Model already exists for this provider.");
+      return;
+    }
+
+    setAdding(true);
+    try {
+      await onAddCustomModel(modelId);
+      setNewModel("");
+    } catch (error) {
+      console.log("Error adding model:", error);
+    } finally {
+      setAdding(false);
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <p className="text-sm text-text-muted">
+        OpenRouter supports any model. Add models and create aliases for quick access.
+      </p>
+
+      {/* Add new model */}
+      <div className="flex items-end gap-2">
+        <div className="flex-1">
+          <label htmlFor="new-model-input" className="text-xs text-text-muted mb-1 block">Model ID (from OpenRouter)</label>
+          <input
+            id="new-model-input"
+            type="text"
+            value={newModel}
+            onChange={(e) => setNewModel(e.target.value)}
+            onKeyDown={(e) => e.key === "Enter" && handleAdd()}
+            placeholder="anthropic/claude-3-opus"
+            className="w-full px-3 py-2 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+          />
+        </div>
+        <Button size="sm" icon="add" onClick={handleAdd} disabled={!newModel.trim() || adding}>
+          {adding ? "Adding..." : "Add"}
+        </Button>
+      </div>
+
+      {/* Models list */}
+      {allModels.length > 0 && (
+        <div className="flex flex-col gap-3">
+          {allModels.map(({ id, fullModel, alias, source }) => (
+            <PassthroughModelRow
+              key={`${source}-${fullModel}`}
+              modelId={id}
+              fullModel={fullModel}
+              copied={copied}
+              onCopy={onCopy}
+              onDeleteAlias={() => source === "custom" ? onDeleteCustomModel(id) : onDeleteAlias(alias)}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+PassthroughModelsSection.propTypes = {
+  providerAlias: PropTypes.string.isRequired,
+  modelAliases: PropTypes.object.isRequired,
+  customModels: PropTypes.arrayOf(PropTypes.object),
+  copied: PropTypes.string,
+  onCopy: PropTypes.func.isRequired,
+  onDeleteAlias: PropTypes.func.isRequired,
+  onAddCustomModel: PropTypes.func.isRequired,
+  onDeleteCustomModel: PropTypes.func.isRequired,
+};
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/page.js b/src/app/(dashboard)/dashboard/providers/[id]/page.js
new file mode 100644
index 0000000..845eed8
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/[id]/page.js
@@ -0,0 +1,1760 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { useParams, useRouter } from "next/navigation";
+import Link from "next/link";
+import Image from "next/image";
+import { Card, Button, Badge, Input, Modal, CardSkeleton, OAuthModal, KiroOAuthWrapper, CursorAuthModal, IFlowCookieModal, GitLabAuthModal, Toggle, Select, EditConnectionModal, NoAuthProxyCard, ConfirmModal } from "@/shared/components";
+import { OAUTH_PROVIDERS, APIKEY_PROVIDERS, FREE_PROVIDERS, FREE_TIER_PROVIDERS, WEB_COOKIE_PROVIDERS, getProviderAlias, isOpenAICompatibleProvider, isAnthropicCompatibleProvider, AI_PROVIDERS } from "@/shared/constants/providers";
+import { getModelsByProviderId, getModelKind } from "@/shared/constants/models";
+import { getThinkingLevels } from "open-sse/providers/thinkingLevels.js";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import { useModelCaps } from "@/shared/hooks/useModelCaps";
+import { translate } from "@/i18n/runtime";
+import { fetchSuggestedModels } from "@/shared/utils/providerModelsFetcher";
+import { getProviderCustomModelRows } from "@/shared/utils/providerCustomModels";
+import ModelRow from "./ModelRow";
+import PassthroughModelsSection from "./PassthroughModelsSection";
+import CompatibleModelsSection from "./CompatibleModelsSection";
+import ConnectionRow from "./ConnectionRow";
+import AddApiKeyModal from "./AddApiKeyModal";
+import EditCompatibleNodeModal from "./EditCompatibleNodeModal";
+import AddCustomModelModal from "./AddCustomModelModal";
+import BulkImportCodexModal from "./BulkImportCodexModal";
+
+const ONE_BY_ONE_DELAY_MS = 1000;
+
+const AUTO_PING_SETTINGS_KEYS = {
+  claude: "claudeAutoPing",
+  codex: "codexAutoPing",
+};
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export default function ProviderDetailPage() {
+  const params = useParams();
+  const router = useRouter();
+  const providerId = params.id;
+  const { getCaps } = useModelCaps();
+  const [connections, setConnections] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [providerNode, setProviderNode] = useState(null);
+  const [proxyPools, setProxyPools] = useState([]);
+  const [showOAuthModal, setShowOAuthModal] = useState(false);
+  const [showIFlowCookieModal, setShowIFlowCookieModal] = useState(false);
+  const [showAddApiKeyModal, setShowAddApiKeyModal] = useState(false);
+  const [addConnectionError, setAddConnectionError] = useState("");
+  const [showBulkImportCodex, setShowBulkImportCodex] = useState(false);
+  const [showEditModal, setShowEditModal] = useState(false);
+  const [showEditNodeModal, setShowEditNodeModal] = useState(false);
+  const [showBulkProxyModal, setShowBulkProxyModal] = useState(false);
+  const [selectedConnection, setSelectedConnection] = useState(null);
+  const [modelAliases, setModelAliases] = useState({});
+  const [customModels, setCustomModels] = useState([]);
+  const [headerImgError, setHeaderImgError] = useState(false);
+  const [modelTestResults, setModelTestResults] = useState({});
+  const [modelsTestError, setModelsTestError] = useState("");
+  const [testingModelIds, setTestingModelIds] = useState(() => new Set());
+  const [showAddCustomModel, setShowAddCustomModel] = useState(false);
+  const [selectedConnectionIds, setSelectedConnectionIds] = useState([]);
+  const [bulkProxyPoolId, setBulkProxyPoolId] = useState("__none__");
+  const [bulkUpdatingProxy, setBulkUpdatingProxy] = useState(false);
+  const [providerStrategy, setProviderStrategy] = useState(null);
+  const [providerStickyLimit, setProviderStickyLimit] = useState("");
+  const [thinkingMode, setThinkingMode] = useState("auto");
+  const [autoPing, setAutoPing] = useState({ enabled: false, connections: {} });
+  const [suggestedModels, setSuggestedModels] = useState([]);
+  const [kiloFreeModels, setKiloFreeModels] = useState([]);
+  const [disabledModelIds, setDisabledModelIds] = useState([]);
+  const [confirmState, setConfirmState] = useState(null);
+  const [showAgRiskModal, setShowAgRiskModal] = useState(false);
+  const [oneByOneRunning, setOneByOneRunning] = useState(false);
+  const [oneByOneStopping, setOneByOneStopping] = useState(false);
+  const [oneByOneCurrentConnectionId, setOneByOneCurrentConnectionId] = useState(null);
+  const [oneByOneResults, setOneByOneResults] = useState({});
+  const [oneByOneSummary, setOneByOneSummary] = useState(null);
+  const stopOneByOneRef = useRef(false);
+  const [importingQoderModels, setImportingQoderModels] = useState(false);
+  const { copied, copy } = useCopyToClipboard();
+
+  const AG_RISK_STORAGE_KEY = "ag_risk_confirmed";
+
+  const openOAuthConnection = () => {
+    setShowOAuthModal(true);
+  };
+
+  const triggerOAuthConnection = () => {
+    if (providerId === "antigravity" && typeof window !== "undefined") {
+      const confirmed = window.localStorage.getItem(AG_RISK_STORAGE_KEY) === "true";
+      if (!confirmed) {
+        setShowAgRiskModal(true);
+        return;
+      }
+    }
+    if (isOAuth) {
+      openOAuthConnection();
+      return;
+    }
+    setAddConnectionError("");
+    setShowAddApiKeyModal(true);
+  };
+
+  const triggerApiKeyConnection = () => {
+    setAddConnectionError("");
+    setShowAddApiKeyModal(true);
+  };
+
+  const triggerAddConnection = () => {
+    if (isOAuth) {
+      triggerOAuthConnection();
+      return;
+    }
+    triggerApiKeyConnection();
+  };
+
+  const handleAgRiskConfirm = () => {
+    if (typeof window !== "undefined") {
+      window.localStorage.setItem(AG_RISK_STORAGE_KEY, "true");
+    }
+    setShowAgRiskModal(false);
+    if (isOAuth) {
+      openOAuthConnection();
+      return;
+    }
+    triggerApiKeyConnection();
+  };
+
+  const providerInfo = providerNode
+    ? {
+        id: providerNode.id,
+        name: providerNode.name || (providerNode.type === "anthropic-compatible" ? "Anthropic Compatible" : "OpenAI Compatible"),
+        color: providerNode.type === "anthropic-compatible" ? "#D97757" : "#10A37F",
+        textIcon: providerNode.type === "anthropic-compatible" ? "AC" : "OC",
+        apiType: providerNode.apiType,
+        baseUrl: providerNode.baseUrl,
+        type: providerNode.type,
+      }
+    : (OAUTH_PROVIDERS[providerId] || APIKEY_PROVIDERS[providerId] || FREE_PROVIDERS[providerId] || FREE_TIER_PROVIDERS[providerId] || WEB_COOKIE_PROVIDERS[providerId]);
+  const authModes = providerInfo?.authModes || [];
+  const isOAuth = !!OAUTH_PROVIDERS[providerId] || !!FREE_PROVIDERS[providerId] || authModes.includes("oauth");
+  const supportsApiKeyAuth = !!APIKEY_PROVIDERS[providerId] || authModes.includes("apikey");
+  const isFreeNoAuth = !!FREE_PROVIDERS[providerId]?.noAuth;
+  const models = getModelsByProviderId(providerId);
+  const providerAlias = getProviderAlias(providerId);
+  
+  const isOpenAICompatible = isOpenAICompatibleProvider(providerId);
+  const isAnthropicCompatible = isAnthropicCompatibleProvider(providerId);
+  const isCompatible = isOpenAICompatible || isAnthropicCompatible;
+  const hasDualAuthModes = !isCompatible && isOAuth && supportsApiKeyAuth;
+  const oauthConnectionLabel =
+    providerId === "xai" ? "Grok Build OAuth"
+    : providerId === "grok-cli" ? "Grok CLI Device Login"
+    : "OAuth";
+  const apiKeyConnectionLabel = providerId === "xai" ? "xAI API Key" : "API Key";
+  // Resolve suffix "(level)" for a model when a thinking level is picked and the model supports it.
+  const resolveThinkingSuffix = (modelId) => {
+    if (!thinkingMode || thinkingMode === "auto") return null;
+    const levels = getThinkingLevels(providerId, modelId);
+    return levels && levels.includes(thinkingMode) ? thinkingMode : null;
+  };
+  const providerStorageAlias = isCompatible ? providerId : providerAlias;
+  // Union of levels across this provider's reasoning models — drives the level picker options.
+  // Include custom models too (e.g. manually added gpt-5.6-sol → max).
+  const providerThinkingLevels = (() => {
+    const set = new Set();
+    const seen = new Set();
+    const addLevels = (modelId) => {
+      if (!modelId || seen.has(modelId)) return;
+      seen.add(modelId);
+      const lv = getThinkingLevels(providerId, modelId);
+      if (lv) lv.forEach((l) => { if (l !== "none") set.add(l); });
+    };
+    for (const m of models) addLevels(m.id);
+    for (const m of kiloFreeModels) addLevels(m.id);
+    for (const entry of customModels) {
+      if (entry.providerAlias !== providerStorageAlias) continue;
+      if ((entry.kind || entry.type || "llm") !== "llm") continue;
+      addLevels(entry.id);
+    }
+    return set.size ? ["auto", ...[...set]] : null;
+  })();
+  const providerDisplayAlias = isCompatible
+    ? (providerNode?.prefix || providerId)
+    : providerAlias;
+
+  const fetchDisabledModels = useCallback(async () => {
+    try {
+      const res = await fetch(`/api/models/disabled?providerAlias=${encodeURIComponent(providerStorageAlias)}`, { cache: "no-store" });
+      const data = await res.json();
+      if (res.ok) setDisabledModelIds(data.ids || []);
+    } catch (error) {
+      console.log("Error fetching disabled models:", error);
+    }
+  }, [providerStorageAlias]);
+
+  const handleDisableModel = async (modelId) => {
+    try {
+      const res = await fetch("/api/models/disabled", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ providerAlias: providerStorageAlias, ids: [modelId] }),
+      });
+      if (res.ok) await fetchDisabledModels();
+    } catch (error) {
+      console.log("Error disabling model:", error);
+    }
+  };
+
+  const handleEnableModel = async (modelId) => {
+    try {
+      const res = await fetch(`/api/models/disabled?providerAlias=${encodeURIComponent(providerStorageAlias)}&id=${encodeURIComponent(modelId)}`, { method: "DELETE" });
+      if (res.ok) await fetchDisabledModels();
+    } catch (error) {
+      console.log("Error enabling model:", error);
+    }
+  };
+
+  const handleDisableAll = async (ids) => {
+    if (!ids.length) return;
+    setConfirmState({
+      title: "Disable All Models",
+      message: `Disable all ${ids.length} model(s)?`,
+      onConfirm: async () => {
+        setConfirmState(null);
+        try {
+          const res = await fetch("/api/models/disabled", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ providerAlias: providerStorageAlias, ids }),
+          });
+          if (res.ok) await fetchDisabledModels();
+        } catch (error) {
+          console.log("Error disabling all models:", error);
+        }
+      }
+    });
+  };
+
+  const handleEnableAll = async () => {
+    try {
+      const res = await fetch(`/api/models/disabled?providerAlias=${encodeURIComponent(providerStorageAlias)}`, { method: "DELETE" });
+      if (res.ok) await fetchDisabledModels();
+    } catch (error) {
+      console.log("Error enabling all models:", error);
+    }
+  };
+
+  // Define callbacks BEFORE the useEffect that uses them
+  const fetchAliases = useCallback(async () => {
+    try {
+      const res = await fetch("/api/models/alias");
+      const data = await res.json();
+      if (res.ok) {
+        setModelAliases(data.aliases || {});
+      }
+    } catch (error) {
+      console.log("Error fetching aliases:", error);
+    }
+  }, []);
+
+  const fetchCustomModels = useCallback(async () => {
+    try {
+      const res = await fetch("/api/models/custom", { cache: "no-store" });
+      const data = await res.json();
+      if (res.ok) {
+        setCustomModels(data.models || []);
+      }
+    } catch (error) {
+      console.log("Error fetching custom models:", error);
+    }
+  }, []);
+
+  // Fetch free models from Kilo API for kilocode provider
+  useEffect(() => {
+    if (providerId !== "kilocode") return;
+    fetch("/api/providers/kilo/free-models")
+      .then((res) => res.json())
+      .then((data) => { if (data.models?.length) setKiloFreeModels(data.models); })
+      .catch(() => {});
+  }, [providerId]);
+
+  const fetchConnections = useCallback(async () => {
+    try {
+      const [connectionsRes, nodesRes, proxyPoolsRes, settingsRes] = await Promise.all([
+        fetch("/api/providers", { cache: "no-store" }),
+        fetch("/api/provider-nodes", { cache: "no-store" }),
+        fetch("/api/proxy-pools?isActive=true", { cache: "no-store" }),
+        fetch("/api/settings", { cache: "no-store" }),
+      ]);
+      const connectionsData = await connectionsRes.json();
+      const nodesData = await nodesRes.json();
+      const proxyPoolsData = await proxyPoolsRes.json();
+      const settingsData = settingsRes.ok ? await settingsRes.json() : {};
+      if (connectionsRes.ok) {
+        const filtered = (connectionsData.connections || []).filter(c => c.provider === providerId);
+        setConnections(filtered);
+      }
+      if (proxyPoolsRes.ok) {
+        setProxyPools(proxyPoolsData.proxyPools || []);
+      }
+      // Load per-provider strategy override
+      const override = (settingsData.providerStrategies || {})[providerId] || {};
+      setProviderStrategy(override.fallbackStrategy || null);
+      setProviderStickyLimit(override.stickyRoundRobinLimit != null ? String(override.stickyRoundRobinLimit) : "1");
+      // Load per-provider thinking config
+      const thinkingCfg = (settingsData.providerThinking || {})[providerId] || {};
+      setThinkingMode(thinkingCfg.mode || "auto");
+      const autoPingSettingsKey = AUTO_PING_SETTINGS_KEYS[providerId];
+      const apCfg = autoPingSettingsKey ? settingsData[autoPingSettingsKey] || {} : {};
+      setAutoPing({ enabled: apCfg.enabled === true, connections: apCfg.connections || {} });
+      if (nodesRes.ok) {
+        let node = (nodesData.nodes || []).find((entry) => entry.id === providerId) || null;
+
+        // Newly created compatible nodes can be briefly unavailable on one worker.
+        // Retry a few times before showing "Provider not found".
+        if (!node && isCompatible) {
+          for (let attempt = 0; attempt < 3; attempt += 1) {
+            await new Promise((resolve) => setTimeout(resolve, 150));
+            const retryRes = await fetch("/api/provider-nodes", { cache: "no-store" });
+            if (!retryRes.ok) continue;
+            const retryData = await retryRes.json();
+            node = (retryData.nodes || []).find((entry) => entry.id === providerId) || null;
+            if (node) break;
+          }
+        }
+
+        setProviderNode(node);
+      }
+    } catch (error) {
+      console.log("Error fetching connections:", error);
+    } finally {
+      setLoading(false);
+    }
+  }, [providerId, isCompatible]);
+
+  const handleUpdateNode = async (formData) => {
+    try {
+      const res = await fetch(`/api/provider-nodes/${providerId}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(formData),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setProviderNode(data.node);
+        await fetchConnections();
+        setShowEditNodeModal(false);
+      }
+    } catch (error) {
+      console.log("Error updating provider node:", error);
+    }
+  };
+
+  const saveProviderStrategy = async (strategy, stickyLimit) => {
+    try {
+      const settingsRes = await fetch("/api/settings", { cache: "no-store" });
+      const settingsData = settingsRes.ok ? await settingsRes.json() : {};
+      const current = settingsData.providerStrategies || {};
+
+      // Build override: null strategy means remove override, use global
+      const override = {};
+      if (strategy) override.fallbackStrategy = strategy;
+      if (strategy === "round-robin" && stickyLimit !== "") {
+        override.stickyRoundRobinLimit = Number(stickyLimit) || 3;
+      }
+
+      const updated = { ...current };
+      if (Object.keys(override).length === 0) {
+        delete updated[providerId];
+      } else {
+        updated[providerId] = override;
+      }
+
+      await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ providerStrategies: updated }),
+      });
+    } catch (error) {
+      console.log("Error saving provider strategy:", error);
+    }
+  };
+
+  const handleRoundRobinToggle = (enabled) => {
+    const strategy = enabled ? "round-robin" : null;
+    const sticky = enabled ? (providerStickyLimit || "1") : providerStickyLimit;
+    if (enabled && !providerStickyLimit) setProviderStickyLimit("1");
+    setProviderStrategy(strategy);
+    saveProviderStrategy(strategy, sticky);
+  };
+
+  const handleStickyLimitChange = (value) => {
+    setProviderStickyLimit(value);
+    saveProviderStrategy("round-robin", value);
+  };
+
+  const saveThinkingConfig = async (mode) => {
+    try {
+      const settingsRes = await fetch("/api/settings", { cache: "no-store" });
+      const settingsData = settingsRes.ok ? await settingsRes.json() : {};
+      const current = settingsData.providerThinking || {};
+      const updated = { ...current };
+      if (!mode || mode === "auto") {
+        delete updated[providerId];
+      } else {
+        updated[providerId] = { mode };
+      }
+      await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ providerThinking: updated }),
+      });
+    } catch (error) {
+      console.log("Error saving thinking config:", error);
+    }
+  };
+
+  const handleThinkingModeChange = (mode) => {
+    setThinkingMode(mode);
+    saveThinkingConfig(mode);
+  };
+
+  const saveAutoPing = async (next) => {
+    const autoPingSettingsKey = AUTO_PING_SETTINGS_KEYS[providerId];
+    if (!autoPingSettingsKey) return;
+
+    setAutoPing(next);
+    try {
+      await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ [autoPingSettingsKey]: next }),
+      });
+    } catch (error) {
+      console.log("Error saving auto-ping config:", error);
+    }
+  };
+
+  const handleAutoPingConnection = (connectionId, on) => {
+    saveAutoPing({ ...autoPing, connections: { ...autoPing.connections, [connectionId]: on } });
+  };
+
+  useEffect(() => {
+    fetchConnections();
+    fetchAliases();
+    fetchCustomModels();
+    fetchDisabledModels();
+  }, [fetchConnections, fetchAliases, fetchCustomModels, fetchDisabledModels]);
+
+  // Fetch suggested models from provider's public API (if configured)
+  useEffect(() => {
+    const fetcher = (OAUTH_PROVIDERS[providerId] || APIKEY_PROVIDERS[providerId] || FREE_PROVIDERS[providerId] || FREE_TIER_PROVIDERS[providerId])?.modelsFetcher;
+    if (!fetcher) return;
+    fetchSuggestedModels(fetcher).then(setSuggestedModels);
+  }, [providerId]);
+
+  const handleSetAlias = async (modelId, alias, providerAliasOverride = providerAlias) => {
+    const fullModel = `${providerAliasOverride}/${modelId}`;
+    try {
+      const res = await fetch("/api/models/alias", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: fullModel, alias }),
+      });
+      if (res.ok) {
+        await fetchAliases();
+      } else {
+        const data = await res.json();
+        alert(data.error || "Failed to set alias");
+      }
+    } catch (error) {
+      console.log("Error setting alias:", error);
+    }
+  };
+
+  const handleDeleteAlias = async (alias) => {
+    try {
+      const res = await fetch(`/api/models/alias?alias=${encodeURIComponent(alias)}`, {
+        method: "DELETE",
+      });
+      if (res.ok) {
+        await fetchAliases();
+      }
+    } catch (error) {
+      console.log("Error deleting alias:", error);
+    }
+  };
+
+  const handleAddCustomModel = async (modelId, type = "llm", providerAliasOverride = providerStorageAlias) => {
+    try {
+      const res = await fetch("/api/models/custom", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ providerAlias: providerAliasOverride, id: modelId, type }),
+      });
+      if (res.ok) {
+        await fetchCustomModels();
+        if (typeof window !== "undefined") window.dispatchEvent(new CustomEvent("customModelChanged"));
+      } else {
+        const data = await res.json();
+        alert(data.error || "Failed to add custom model");
+      }
+    } catch (error) {
+      console.log("Error adding custom model:", error);
+    }
+  };
+
+  const handleDeleteCustomModel = async (modelId, type = "llm", providerAliasOverride = providerStorageAlias) => {
+    try {
+      const params = new URLSearchParams({ providerAlias: providerAliasOverride, id: modelId, type });
+      const res = await fetch(`/api/models/custom?${params}`, { method: "DELETE" });
+      if (res.ok) {
+        await fetchCustomModels();
+        if (typeof window !== "undefined") window.dispatchEvent(new CustomEvent("customModelChanged"));
+      }
+    } catch (error) {
+      console.log("Error deleting custom model:", error);
+    }
+  };
+
+  // Fetch Qoder model list and automatically add to available models
+  const handleImportQoderModels = async () => {
+    if (importingQoderModels) return;
+    const activeConnection = connections.find((conn) => conn.isActive !== false);
+    if (!activeConnection) {
+      alert(translate("Please add an active Qoder connection first"));
+      return;
+    }
+
+    setImportingQoderModels(true);
+    try {
+      const res = await fetch(`/api/providers/${activeConnection.id}/models`);
+      const data = await res.json();
+      if (!res.ok) {
+        alert(data.error || translate("Failed to fetch models"));
+        return;
+      }
+      const models = data.models || [];
+      if (models.length === 0) {
+        alert(translate("No models returned"));
+        return;
+      }
+
+      let importedCount = 0;
+      for (const model of models) {
+        const modelId = model.id || model.name;
+        if (!modelId) continue;
+        
+        // Qoder model ID format may be "qoder/auto" or "auto", need to remove prefix
+        const cleanModelId = modelId.replace(/^qoder\//, "");
+        const alreadyExists = customModels.some(
+          (entry) => entry.providerAlias === providerStorageAlias && entry.id === cleanModelId && (entry.kind || entry.type || "llm") === "llm"
+        ) || Object.values(modelAliases).includes(`${providerStorageAlias}/${cleanModelId}`);
+        if (alreadyExists) {
+          continue;
+        }
+
+        await handleAddCustomModel(cleanModelId, "llm", providerStorageAlias);
+        importedCount += 1;
+      }
+      
+      if (importedCount === 0) {
+        alert(translate("All models already exist, no new models added"));
+      } else {
+        alert(translate("Successfully added") + ` ${importedCount} ` + translate("models"));
+      }
+    } catch (error) {
+      console.log("Error importing Qoder models:", error);
+      alert(translate("Error fetching models") + ": " + error.message);
+    } finally {
+      setImportingQoderModels(false);
+    }
+  };
+
+  const handleRunOneByOneTest = async () => {
+    if (oneByOneRunning || connections.length === 0) return;
+
+    const queuedState = Object.fromEntries(
+      connections.map((connection) => [connection.id, { state: "queued", error: null }]),
+    );
+
+    stopOneByOneRef.current = false;
+    setOneByOneRunning(true);
+    setOneByOneStopping(false);
+    setOneByOneCurrentConnectionId(null);
+    setOneByOneResults(queuedState);
+    setOneByOneSummary({ total: connections.length, completed: 0, passed: 0, failed: 0, stopped: false });
+
+    let passed = 0;
+    let failed = 0;
+
+    try {
+      for (let index = 0; index < connections.length; index += 1) {
+        if (stopOneByOneRef.current) {
+          setOneByOneSummary({
+            total: connections.length,
+            completed: index,
+            passed,
+            failed,
+            stopped: true,
+          });
+          break;
+        }
+
+        const connection = connections[index];
+        setOneByOneCurrentConnectionId(connection.id);
+        setOneByOneResults((prev) => ({
+          ...prev,
+          [connection.id]: { state: "testing", error: null },
+        }));
+
+        try {
+          const res = await fetch(`/api/providers/${connection.id}/test`, { method: "POST" });
+          const data = await res.json();
+          const valid = !!data.valid;
+
+          if (valid) {
+            passed += 1;
+          } else {
+            failed += 1;
+          }
+
+          setOneByOneResults((prev) => ({
+            ...prev,
+            [connection.id]: {
+              state: valid ? "success" : "failed",
+              error: valid ? null : (data.error || null),
+            },
+          }));
+        } catch (error) {
+          failed += 1;
+          setOneByOneResults((prev) => ({
+            ...prev,
+            [connection.id]: {
+              state: "failed",
+              error: error.message || "Test failed",
+            },
+          }));
+        }
+
+        setOneByOneSummary({
+          total: connections.length,
+          completed: index + 1,
+          passed,
+          failed,
+          stopped: false,
+        });
+
+        if (index < connections.length - 1) {
+          await sleep(ONE_BY_ONE_DELAY_MS);
+        }
+      }
+    } finally {
+      setOneByOneCurrentConnectionId(null);
+      setOneByOneRunning(false);
+      setOneByOneStopping(false);
+      stopOneByOneRef.current = false;
+    }
+  };
+
+  const handleStopOneByOneTest = () => {
+    if (!oneByOneRunning) return;
+    stopOneByOneRef.current = true;
+    setOneByOneStopping(true);
+  };
+
+  const handleDelete = async (id) => {
+    setConfirmState({
+      title: "Delete Connection",
+      message: "Delete this connection?",
+      onConfirm: async () => {
+        setConfirmState(null);
+        try {
+          const res = await fetch(`/api/providers/${id}`, { method: "DELETE" });
+          if (res.ok) {
+            setConnections(prev => prev.filter(c => c.id !== id));
+          }
+        } catch (error) {
+          console.log("Error deleting connection:", error);
+        }
+      }
+    });
+  };
+
+  const handleBulkDelete = () => {
+    const count = selectedConnectionIds.length;
+    if (count === 0) return;
+    setConfirmState({
+      title: `Delete ${count} Connection${count > 1 ? "s" : ""}`,
+      message: `Delete ${count} connection${count > 1 ? "s" : ""}? This cannot be undone.`,
+      onConfirm: async () => {
+        setConfirmState(null);
+        let failed = 0;
+        const idsToDelete = [...selectedConnectionIds];
+        for (const id of idsToDelete) {
+          try {
+            const res = await fetch(`/api/providers/${id}`, { method: "DELETE" });
+            if (!res.ok) failed += 1;
+          } catch (error) {
+            console.log("Error deleting connection:", error);
+            failed += 1;
+          }
+        }
+        setConnections(prev => prev.filter(c => !idsToDelete.includes(c.id)));
+        setSelectedConnectionIds([]);
+        if (failed > 0) alert(`Deleted ${idsToDelete.length - failed} connection(s), ${failed} failed.`);
+      }
+    });
+  };
+
+  const handleOAuthSuccess = () => {
+    fetchConnections();
+    setShowOAuthModal(false);
+  };
+
+  const handleIFlowCookieSuccess = () => {
+    fetchConnections();
+    setShowIFlowCookieModal(false);
+  };
+
+  const handleSaveApiKey = async (formData) => {
+    setAddConnectionError("");
+    try {
+      const res = await fetch("/api/providers", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ provider: providerId, ...formData }),
+      });
+
+      let data = null;
+      try {
+        data = await res.json();
+      } catch {
+        data = null;
+      }
+
+      if (res.ok) {
+        await fetchConnections();
+        setShowAddApiKeyModal(false);
+        return;
+      }
+
+      setAddConnectionError(data?.error || "Failed to save connection");
+    } catch (error) {
+      console.log("Error saving connection:", error);
+      setAddConnectionError("Failed to save connection");
+    }
+  };
+
+  const handleUpdateConnection = async (formData) => {
+    try {
+      const res = await fetch(`/api/providers/${selectedConnection.id}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(formData),
+      });
+      if (res.ok) {
+        await fetchConnections();
+        setShowEditModal(false);
+      }
+    } catch (error) {
+      console.log("Error updating connection:", error);
+    }
+  };
+
+  const handleUpdateConnectionStatus = async (id, isActive) => {
+    try {
+      const res = await fetch(`/api/providers/${id}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ isActive }),
+      });
+      if (res.ok) {
+        setConnections(prev => prev.map(c => c.id === id ? { ...c, isActive } : c));
+      }
+    } catch (error) {
+      console.log("Error updating connection status:", error);
+    }
+  };
+
+  const handleSwapPriority = async (index1, index2) => {
+    // Optimistic update state
+    const newConnections = [...connections];
+    [newConnections[index1], newConnections[index2]] = [newConnections[index2], newConnections[index1]];
+    setConnections(newConnections);
+
+    try {
+      await Promise.all([
+        fetch(`/api/providers/${newConnections[index1].id}`, {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ priority: index1 }),
+        }),
+        fetch(`/api/providers/${newConnections[index2].id}`, {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ priority: index2 }),
+        }),
+      ]);
+    } catch (error) {
+      console.log("Error swapping priority:", error);
+      await fetchConnections();
+    }
+  };
+
+  const selectedConnections = connections.filter((conn) => selectedConnectionIds.includes(conn.id));
+  const allSelected = connections.length > 0 && selectedConnectionIds.length === connections.length;
+
+  const toggleSelectConnection = (connectionId) => {
+    setSelectedConnectionIds((prev) => (
+      prev.includes(connectionId)
+        ? prev.filter((id) => id !== connectionId)
+        : [...prev, connectionId]
+    ));
+  };
+
+  const toggleSelectAllConnections = () => {
+    if (allSelected) {
+      setSelectedConnectionIds([]);
+      return;
+    }
+    setSelectedConnectionIds(connections.map((conn) => conn.id));
+  };
+
+  const clearSelection = () => {
+    setSelectedConnectionIds([]);
+    setBulkProxyPoolId("__none__");
+  };
+
+  useEffect(() => {
+    setSelectedConnectionIds((prev) => prev.filter((id) => connections.some((conn) => conn.id === id)));
+  }, [connections]);
+
+  const selectedProxySummary = (() => {
+    if (selectedConnections.length === 0) return "";
+    const poolIds = new Set(selectedConnections.map((conn) => conn.providerSpecificData?.proxyPoolId || "__none__"));
+    if (poolIds.size === 1) {
+      const onlyId = [...poolIds][0];
+      if (onlyId === "__none__") return "All selected currently unbound";
+      const pool = proxyPools.find((p) => p.id === onlyId);
+      return `All selected currently bound to ${pool?.name || onlyId}`;
+    }
+    return "Selected connections have mixed proxy bindings";
+  })();
+
+  const openBulkProxyModal = () => {
+    if (selectedConnections.length === 0) return;
+    const uniquePoolIds = [...new Set(selectedConnections.map((conn) => conn.providerSpecificData?.proxyPoolId || "__none__"))];
+    setBulkProxyPoolId(uniquePoolIds.length === 1 ? uniquePoolIds[0] : "__none__");
+    setShowBulkProxyModal(true);
+  };
+
+  const closeBulkProxyModal = () => {
+    if (bulkUpdatingProxy) return;
+    setShowBulkProxyModal(false);
+  };
+
+  const applyProxyAssignments = async (assignments) => {
+    setBulkUpdatingProxy(true);
+    try {
+      let failed = 0;
+      for (const { connectionId, proxyPoolId } of assignments) {
+        try {
+          const res = await fetch(`/api/providers/${connectionId}`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ proxyPoolId }),
+          });
+          if (!res.ok) failed += 1;
+        } catch (e) {
+          console.log("Error applying proxy for", connectionId, e);
+          failed += 1;
+        }
+      }
+      if (failed > 0) alert(`Updated with ${failed} failed request(s).`);
+      await fetchConnections();
+      setShowBulkProxyModal(false);
+    } finally {
+      setBulkUpdatingProxy(false);
+    }
+  };
+
+  const handleApplySinglePool = (proxyPoolId) => {
+    const targets = connections.map((c) => ({ connectionId: c.id, proxyPoolId }));
+    return applyProxyAssignments(targets);
+  };
+
+  const handleApplyOneToOne = () => {
+    const activePools = proxyPools.filter((p) => p.isActive === true);
+    if (activePools.length === 0) {
+      alert("No active proxy pools available.");
+      return;
+    }
+    const targets = connections.map((c, i) => ({
+      connectionId: c.id,
+      proxyPoolId: activePools[i % activePools.length].id,
+    }));
+    return applyProxyAssignments(targets);
+  };
+
+
+  const isSelected = (connectionId) => selectedConnectionIds.includes(connectionId);
+
+  const connectionsList = (
+    <div className="flex min-w-0 flex-col divide-y divide-black/[0.03] dark:divide-white/[0.03]">
+      {connections
+        .map((conn, index) => (
+          <div key={conn.id} className="flex min-w-0 items-stretch">
+            <div className="flex shrink-0 items-center pl-1 sm:pl-2">
+              <input
+                type="checkbox"
+                checked={isSelected(conn.id)}
+                onChange={() => toggleSelectConnection(conn.id)}
+                className="h-4 w-4 rounded border-gray-300 text-primary focus:ring-primary"
+              />
+            </div>
+            <div className="flex-1 min-w-0">
+              <ConnectionRow
+                connection={conn}
+                proxyPools={proxyPools}
+                isOAuth={isOAuth}
+                isFirst={index === 0}
+                isLast={index === connections.length - 1}
+                onMoveUp={() => handleSwapPriority(index, index - 1)}
+                onMoveDown={() => handleSwapPriority(index, index + 1)}
+                onToggleActive={(isActive) => handleUpdateConnectionStatus(conn.id, isActive)}
+                autoPing={AUTO_PING_SETTINGS_KEYS[providerId] && conn.authType === "oauth" ? {
+                  on: autoPing.connections[conn.id] === true,
+                  onToggle: (on) => handleAutoPingConnection(conn.id, on),
+                  provider: providerId,
+                } : null}
+                onUpdateProxy={async (proxyPoolId) => {
+                  try {
+                    const res = await fetch(`/api/providers/${conn.id}`, {
+                      method: "PUT",
+                      headers: { "Content-Type": "application/json" },
+                      body: JSON.stringify({ proxyPoolId: proxyPoolId || null }),
+                    });
+                    if (res.ok) {
+                      setConnections(prev => prev.map(c =>
+                        c.id === conn.id
+                          ? { ...c, providerSpecificData: { ...c.providerSpecificData, proxyPoolId: proxyPoolId || null } }
+                          : c
+                      ));
+                    }
+                  } catch (error) {
+                    console.log("Error updating proxy:", error);
+                  }
+                }}
+                onEdit={() => {
+                  setSelectedConnection(conn);
+                  setShowEditModal(true);
+                }}
+                onDelete={() => handleDelete(conn.id)}
+                oneByOneStatus={oneByOneResults[conn.id] || null}
+              />
+            </div>
+          </div>
+        ))}
+    </div>
+  );
+
+  const activePools = proxyPools.filter((p) => p.isActive === true);
+
+  const bulkActionModal = (
+    <Modal
+      isOpen={showBulkProxyModal}
+      onClose={closeBulkProxyModal}
+      title={`Apply Proxy (${connections.length} connections)`}
+    >
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-col">
+          <button
+            onClick={handleApplyOneToOne}
+            disabled={bulkUpdatingProxy || activePools.length === 0}
+            className="flex items-center gap-2 rounded-lg px-3 py-2 text-left transition-colors hover:bg-black/[0.04] dark:hover:bg-white/[0.04] disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            <span className="material-symbols-outlined text-text-muted text-[18px]">sync_alt</span>
+            <span className="text-sm text-text-main">One-to-one (rotate)</span>
+          </button>
+          <button
+            onClick={() => handleApplySinglePool(null)}
+            disabled={bulkUpdatingProxy}
+            className="flex items-center gap-2 rounded-lg px-3 py-2 text-left transition-colors hover:bg-black/[0.04] dark:hover:bg-white/[0.04] disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            <span className="material-symbols-outlined text-text-muted text-[18px]">link_off</span>
+            <span className="text-sm text-text-main">None (unbind all)</span>
+          </button>
+          {proxyPools.map((pool) => (
+            <button
+              key={pool.id}
+              onClick={() => handleApplySinglePool(pool.id)}
+              disabled={bulkUpdatingProxy || pool.isActive !== true}
+              className="flex items-center gap-2 rounded-lg px-3 py-2 text-left transition-colors hover:bg-black/[0.04] dark:hover:bg-white/[0.04] disabled:cursor-not-allowed disabled:opacity-50"
+            >
+              <span className="material-symbols-outlined text-text-muted text-[18px]">lan</span>
+              <span className="truncate text-sm text-text-main">{pool.name}</span>
+              {pool.isActive !== true && (
+                <span className="text-[10px] text-text-muted">(inactive)</span>
+              )}
+            </button>
+          ))}
+        </div>
+
+        {bulkUpdatingProxy && <p className="text-xs text-text-muted">Applying...</p>}
+
+        <Button onClick={closeBulkProxyModal} variant="ghost" fullWidth disabled={bulkUpdatingProxy}>
+          Cancel
+        </Button>
+      </div>
+    </Modal>
+  );
+
+  const handleTestModel = async (modelId) => {
+    if (testingModelIds.has(modelId)) return;
+    setTestingModelIds((prev) => new Set(prev).add(modelId));
+    try {
+      const res = await fetch("/api/models/test", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: `${providerStorageAlias}/${modelId}` }),
+      });
+      const data = await res.json();
+      setModelTestResults((prev) => ({ ...prev, [modelId]: data.ok ? "ok" : "error" }));
+      setModelsTestError(data.ok ? "" : (data.error || "Model not reachable"));
+    } catch {
+      setModelTestResults((prev) => ({ ...prev, [modelId]: "error" }));
+      setModelsTestError("Network error");
+    } finally {
+      setTestingModelIds((prev) => { const n = new Set(prev); n.delete(modelId); return n; });
+    }
+  };
+
+  const renderModelsSection = () => {
+    if (isCompatible) {
+      return (
+        <CompatibleModelsSection
+          providerStorageAlias={providerStorageAlias}
+          providerDisplayAlias={providerDisplayAlias}
+          modelAliases={modelAliases}
+          customModels={customModels}
+          copied={copied}
+          onCopy={copy}
+          onSetAlias={handleSetAlias}
+          onDeleteAlias={handleDeleteAlias}
+          onAddCustomModel={(modelId) => handleAddCustomModel(modelId, "llm", providerStorageAlias)}
+          onDeleteCustomModel={(modelId) => handleDeleteCustomModel(modelId, "llm", providerStorageAlias)}
+          connections={connections}
+          isAnthropic={isAnthropicCompatible}
+        />
+      );
+    }
+    // Combine hardcoded models with Kilo free models (deduplicated)
+    // Exclude non-llm models (embedding, tts, etc.) — they have dedicated pages under media-providers
+    const allModels = [
+      ...models,
+      ...kiloFreeModels.filter((fm) => !models.some((m) => m.id === fm.id)),
+    ].filter((m) => { const k = getModelKind(m); return !k || k === "llm"; });
+    const disabledSet = new Set(disabledModelIds);
+    const displayModels = allModels.filter((m) => !disabledSet.has(m.id));
+    const disabledDisplayModels = allModels.filter((m) => disabledSet.has(m.id));
+    const customModelRows = getProviderCustomModelRows({
+      customModels,
+      modelAliases,
+      providerAlias: providerStorageAlias,
+      builtInModels: models,
+      type: "llm",
+    });
+
+    return (
+      <div className="flex flex-wrap gap-3">
+        {/* Custom models first */}
+        {customModelRows.map((model) => (
+          <ModelRow
+            key={`${model.source}-${model.fullModel}`}
+            model={{ id: model.id, name: model.name }}
+            fullModel={`${providerDisplayAlias}/${model.id}`}
+            alias={model.alias}
+            copied={copied}
+            onCopy={copy}
+            onSetAlias={() => {}}
+            onDeleteAlias={() => {
+              if (model.source === "custom") {
+                handleDeleteCustomModel(model.id, "llm", providerStorageAlias);
+              } else {
+                handleDeleteAlias(model.alias);
+              }
+            }}
+            testStatus={modelTestResults[model.id]}
+            onTest={connections.length > 0 || isFreeNoAuth ? () => handleTestModel(model.id) : undefined}
+            isTesting={testingModelIds.has(model.id)}
+            isCustom
+            isFree={false}
+            caps={getCaps(`${providerId}/${model.id}`)}
+            thinkingSuffix={resolveThinkingSuffix(model.id)}
+          />
+        ))}
+
+        {displayModels.map((model) => {
+          const fullModel = `${providerStorageAlias}/${model.id}`;
+          const oldFormatModel = `${providerId}/${model.id}`;
+          const existingAlias = Object.entries(modelAliases).find(
+            ([, m]) => m === fullModel || m === oldFormatModel
+          )?.[0];
+          return (
+            <ModelRow
+              key={model.id}
+              model={model}
+              fullModel={`${providerDisplayAlias}/${model.id}`}
+              alias={existingAlias}
+              copied={copied}
+              onCopy={copy}
+              onSetAlias={(alias) => handleSetAlias(model.id, alias, providerStorageAlias)}
+              onDeleteAlias={() => handleDeleteAlias(existingAlias)}
+              testStatus={modelTestResults[model.id]}
+              onTest={connections.length > 0 || isFreeNoAuth ? () => handleTestModel(model.id) : undefined}
+              isTesting={testingModelIds.has(model.id)}
+              isFree={model.isFree}
+              onDisable={() => handleDisableModel(model.id)}
+              caps={getCaps(`${providerId}/${model.id}`)}
+              thinkingSuffix={resolveThinkingSuffix(model.id)}
+            />
+          );
+        })}
+
+        {/* Add model button — inline, same style as model chips */}
+        <button
+          onClick={() => setShowAddCustomModel(true)}
+          className="flex w-full items-center justify-center gap-1.5 rounded-lg border border-dashed border-primary/40 px-3 py-2 text-xs text-primary transition-colors hover:border-primary hover:bg-primary/5 sm:w-auto"
+        >
+          <span className="material-symbols-outlined text-sm">add</span>
+          Add Model
+        </button>
+
+        {/* Import Qoder models button — only show for qoder provider */}
+        {providerId === "qoder" && connections.some((conn) => conn.isActive !== false) && (
+          <button
+            onClick={handleImportQoderModels}
+            disabled={importingQoderModels}
+            className="flex w-full items-center justify-center gap-1.5 rounded-lg border border-dashed border-blue-500/40 px-3 py-2 text-xs text-blue-600 dark:text-blue-400 transition-colors hover:border-blue-500 hover:bg-blue-500/5 sm:w-auto disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            <span className="material-symbols-outlined text-sm" style={importingQoderModels ? { animation: "spin 1s linear infinite" } : undefined}>
+              {importingQoderModels ? "progress_activity" : "download"}
+            </span>
+            {importingQoderModels ? translate("Fetching...") : translate("Fetch Qoder Models")}
+          </button>
+        )}
+
+        {/* Suggested models from provider API — show only models not yet added */}
+        {suggestedModels.length > 0 && (() => {
+          const addedFullModels = new Set([
+            ...Object.values(modelAliases),
+            ...customModelRows.map((model) => model.fullModel),
+          ]);
+          const hardcodedIds = new Set(models.map((m) => m.id));
+          const notAdded = suggestedModels.filter(
+            (m) => !addedFullModels.has(`${providerStorageAlias}/${m.id}`) && !hardcodedIds.has(m.id)
+          );
+          if (notAdded.length === 0) return null;
+          return (
+            <div className="w-full mt-2">
+              <p className="text-xs text-text-muted mb-2">Suggested free models (≥200k context):</p>
+              <div className="flex flex-wrap gap-2">
+                {notAdded.map((m) => (
+                  <button
+                    key={m.id}
+                    onClick={async () => {
+                      await handleAddCustomModel(m.id, "llm", providerStorageAlias);
+                    }}
+                    className="flex items-center gap-1 px-2.5 py-1.5 rounded-lg border border-black/10 dark:border-white/10 text-xs text-text-muted hover:text-primary hover:border-primary/40 hover:bg-primary/5 transition-colors"
+                    title={`${m.name} · ${(m.contextLength / 1000).toFixed(0)}k ctx`}
+                  >
+                    <span className="material-symbols-outlined text-[13px]">add</span>
+                    {m.id.split("/").pop()}
+                  </button>
+                ))}
+              </div>
+            </div>
+          );
+        })()}
+
+        {/* Disabled models — restorable */}
+        {disabledDisplayModels.length > 0 && (
+          <div className="w-full mt-2">
+            <p className="text-xs text-text-muted mb-2">Disabled models ({disabledDisplayModels.length}):</p>
+            <div className="flex flex-wrap gap-2">
+              {disabledDisplayModels.map((m) => (
+                <button
+                  key={m.id}
+                  onClick={() => handleEnableModel(m.id)}
+                  className="flex items-center gap-1 px-2.5 py-1.5 rounded-lg border border-dashed border-black/10 dark:border-white/10 text-xs text-text-muted hover:text-primary hover:border-primary/40 hover:bg-primary/5 transition-colors"
+                  title="Restore model"
+                >
+                  <span className="material-symbols-outlined text-[13px]">add</span>
+                  {m.id}
+                </button>
+              ))}
+            </div>
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  if (loading) {
+    return (
+      <div className="flex flex-col gap-8">
+        <CardSkeleton />
+        <CardSkeleton />
+      </div>
+    );
+}
+
+  if (!providerInfo) {
+    return (
+      <div className="text-center py-20">
+        <p className="text-text-muted">Provider not found</p>
+        <Link href="/dashboard/providers" className="text-primary mt-4 inline-block">
+          Back to Providers
+        </Link>
+      </div>
+    );
+  }
+
+  // Determine icon path: OpenAI Compatible providers use specialized icons
+  const getHeaderIconPath = () => {
+    if (isOpenAICompatible && providerInfo.apiType) {
+      return providerInfo.apiType === "responses" ? "/providers/oai-r.png" : "/providers/oai-cc.png";
+    }
+    if (isAnthropicCompatible) {
+      return "/providers/anthropic-m.png";
+    }
+    return `/providers/${providerInfo.id}.png`;
+  };
+
+  return (
+    <div className="flex min-w-0 flex-col gap-6 px-1 sm:gap-8 sm:px-0">
+      {/* Header */}
+      <div className="min-w-0">
+        <Link
+          href="/dashboard/providers"
+          className="inline-flex items-center gap-1 text-sm text-text-muted hover:text-primary transition-colors mb-4"
+        >
+          <span className="material-symbols-outlined text-lg">arrow_back</span>
+          Back to Providers
+        </Link>
+        <div className="flex min-w-0 items-center gap-3 sm:gap-4">
+          <div
+            className="flex size-12 shrink-0 items-center justify-center rounded-lg"
+            style={{ backgroundColor: `${providerInfo.color}15` }}
+          >
+            {headerImgError ? (
+              <span className="text-sm font-bold" style={{ color: providerInfo.color }}>
+                {providerInfo.textIcon || providerInfo.id.slice(0, 2).toUpperCase()}
+              </span>
+            ) : (
+              <Image
+                src={getHeaderIconPath()}
+                alt={providerInfo.name}
+                width={48}
+                height={48}
+                className="max-h-12 max-w-12 rounded-lg object-contain"
+                sizes="48px"
+                onError={() => setHeaderImgError(true)}
+              />
+            )}
+          </div>
+          <div className="min-w-0">
+            <div className="flex items-center gap-3 flex-wrap">
+              <h1 className="truncate text-2xl font-semibold tracking-tight sm:text-3xl">{providerInfo.name}</h1>
+              {(providerInfo.notice?.apiKeyUrl || providerInfo.notice?.signupUrl || providerInfo.website) && (
+                <a
+                  href={providerInfo.notice?.apiKeyUrl || providerInfo.notice?.signupUrl || providerInfo.website}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-xs text-primary hover:underline inline-flex items-center gap-1"
+                >
+                  <span className="material-symbols-outlined text-sm">open_in_new</span>
+                  {providerInfo.notice?.apiKeyUrl ? "Get API Key" : "Sign up / Learn more"}
+                </a>
+              )}
+            </div>
+            <p className="text-text-muted">
+              {connections.length} connection{connections.length === 1 ? "" : "s"}
+            </p>
+          </div>
+        </div>
+      </div>
+
+      {providerInfo.deprecated && (
+        <div className="flex items-center gap-2 px-3 py-2 rounded-lg bg-yellow-500/10 border border-yellow-500/30">
+          <span className="material-symbols-outlined text-[16px] text-yellow-500 mt-0.5 shrink-0">warning</span>
+          <p className="text-xs text-red-600 dark:text-yellow-400 leading-relaxed">{providerInfo.deprecationNotice}</p>
+        </div>
+      )}
+
+      {providerInfo.notice?.text && !providerInfo.deprecated && (
+        <div className="flex flex-col gap-2 rounded-lg border border-blue-500/30 bg-blue-500/10 px-3 py-2 sm:flex-row sm:items-center">
+          <span className="material-symbols-outlined text-[16px] text-blue-500 shrink-0">info</span>
+          <p className="min-w-0 flex-1 text-xs leading-relaxed text-blue-600 dark:text-blue-400">{providerInfo.notice.text}</p>
+          {providerInfo.notice.apiKeyUrl && (
+            <a
+              href={providerInfo.notice.apiKeyUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex justify-center rounded bg-blue-500 px-2 py-1 text-xs font-medium text-white transition-colors hover:bg-blue-600 sm:py-0.5"
+            >
+              Get API Key →
+            </a>
+          )}
+        </div>
+      )}
+
+      {isCompatible && providerNode && (
+        <Card>
+          <div className="mb-4 flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+            <div className="min-w-0">
+              <h2 className="text-lg font-semibold">{isAnthropicCompatible ? "Anthropic Compatible Details" : "OpenAI Compatible Details"}</h2>
+              <p className="break-all text-sm text-text-muted">
+                {isAnthropicCompatible ? "Messages API" : (providerNode.apiType === "responses" ? "Responses API" : "Chat Completions")} · {(providerNode.baseUrl || "").replace(/\/$/, "")}/
+                {isAnthropicCompatible ? "messages" : (providerNode.apiType === "responses" ? "responses" : "chat/completions")}
+              </p>
+            </div>
+            <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+              <Button
+                size="sm"
+                icon="add"
+                onClick={() => {
+                  setAddConnectionError("");
+                  setShowAddApiKeyModal(true);
+                }}
+                className="w-full sm:w-auto"
+              >
+                Add API Key
+              </Button>
+              <Button
+                size="sm"
+                variant="secondary"
+                icon="edit"
+                onClick={() => setShowEditNodeModal(true)}
+                className="w-full sm:w-auto"
+              >
+                Edit
+              </Button>
+              <Button
+                size="sm"
+                variant="secondary"
+                icon="delete"
+                onClick={async () => {
+                  setConfirmState({
+                    title: "Delete Compatible Node",
+                    message: `Delete this ${isAnthropicCompatible ? "Anthropic" : "OpenAI"} Compatible node?`,
+                    onConfirm: async () => {
+                      setConfirmState(null);
+                      try {
+                        const res = await fetch(`/api/provider-nodes/${providerId}`, { method: "DELETE" });
+                        if (res.ok) {
+                          router.push("/dashboard/providers");
+                        }
+                      } catch (error) {
+                        console.log("Error deleting provider node:", error);
+                      }
+                    }
+                  });
+                }}
+                className="w-full sm:w-auto"
+              >
+                Delete
+              </Button>
+            </div>
+          </div>
+        </Card>
+      )}
+
+      {/* Connections */}
+      {isFreeNoAuth ? (
+        <NoAuthProxyCard providerId={providerId} />
+      ) : (
+        <Card>
+          <div className="mb-4 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+            <h2 className="text-lg font-semibold">Connections</h2>
+            <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:gap-4">
+              {connections.length > 0 && proxyPools.length > 0 && (
+                <Button
+                  size="sm"
+                  variant="secondary"
+                  icon="lan"
+                  onClick={() => setShowBulkProxyModal(true)}
+                >
+                  Apply Proxy
+                </Button>
+              )}
+              {connections.length > 0 && (
+                <>
+                  {selectedConnectionIds.length > 0 && (
+                    <Button
+                      size="sm"
+                      variant="danger"
+                      icon="delete"
+                      onClick={handleBulkDelete}
+                    >
+                      Delete Selected ({selectedConnectionIds.length})
+                    </Button>
+                  )}
+                  <Button
+                    size="sm"
+                    variant="secondary"
+                    icon="sync"
+                    onClick={handleRunOneByOneTest}
+                    disabled={oneByOneRunning}
+                  >
+                    {oneByOneRunning ? "Testing Connection One-by-One..." : "Test Connection One-by-One"}
+                  </Button>
+                  {oneByOneRunning && (
+                    <Button
+                      size="sm"
+                      variant="ghost"
+                      icon="stop"
+                      onClick={handleStopOneByOneTest}
+                      disabled={oneByOneStopping}
+                    >
+                      {oneByOneStopping ? "Stopping..." : "Stop"}
+                    </Button>
+                  )}
+                </>
+              )}
+              {/* Round Robin toggle */}
+              <div className="flex flex-wrap items-center gap-2">
+                <span className="text-xs text-text-muted font-medium">Round Robin</span>
+                <Toggle
+                  checked={providerStrategy === "round-robin"}
+                  onChange={handleRoundRobinToggle}
+                />
+                {providerStrategy === "round-robin" && (
+                  <div className="flex items-center gap-1.5">
+                    <span className="text-xs text-text-muted">Sticky:</span>
+                    <input
+                      type="number"
+                      min={1}
+                      value={providerStickyLimit}
+                      onChange={(e) => handleStickyLimitChange(e.target.value)}
+                      placeholder="1"
+                      className="w-14 px-2 py-1 text-xs border border-border rounded-md bg-background focus:outline-none focus:border-primary"
+                    />
+                  </div>
+                )}
+              </div>
+            </div>
+          </div>
+
+          {connections.length === 0 ? (
+            <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+              <div className="flex items-center gap-3">
+                <div className="inline-flex items-center justify-center w-9 h-9 rounded-full bg-primary/10 text-primary shrink-0">
+                  <span className="material-symbols-outlined text-[18px]">{isOAuth ? "lock" : "key"}</span>
+                </div>
+                <div className="min-w-0">
+                  <p className="text-sm text-text-muted">No connections yet</p>
+                  {hasDualAuthModes && (
+                    <p className="text-xs text-text-muted">
+                      Choose {oauthConnectionLabel} or {apiKeyConnectionLabel}.
+                    </p>
+                  )}
+                </div>
+              </div>
+              <div className="flex gap-2">
+                {hasDualAuthModes ? (
+                  <>
+                    <Button size="sm" icon="lock" variant="secondary" onClick={triggerOAuthConnection}>
+                      {oauthConnectionLabel}
+                    </Button>
+                    <Button size="sm" icon="key" onClick={triggerApiKeyConnection}>
+                      {apiKeyConnectionLabel}
+                    </Button>
+                  </>
+                ) : (
+                  <>
+                    {!isCompatible && providerId === "iflow" && (
+                      <Button size="sm" icon="cookie" variant="secondary" onClick={() => setShowIFlowCookieModal(true)}>
+                        Cookie
+                      </Button>
+                    )}
+                    {providerId === "codex" && (
+                      <Button size="sm" icon="playlist_add" variant="secondary" onClick={() => setShowBulkImportCodex(true)}>
+                        {translate("Bulk Add")}
+                      </Button>
+                    )}
+                    <Button
+                      size="sm"
+                      icon="add"
+                      onClick={triggerAddConnection}
+                    >
+                      {isCompatible ? "Add API Key" : (providerId === "iflow" ? "OAuth" : "Add Connection")}
+                    </Button>
+                  </>
+                )}
+              </div>
+            </div>
+          ) : (
+            <>
+              {oneByOneSummary && (
+                <div className="mb-4 rounded-lg border border-black/10 bg-black/[0.02] px-3 py-2 text-xs text-text-muted dark:border-white/10 dark:bg-white/[0.03]">
+                  <div className="flex flex-wrap items-center gap-3">
+                    <span>Total: {oneByOneSummary.total}</span>
+                    <span>Completed: {oneByOneSummary.completed}</span>
+                    <span>Passed: {oneByOneSummary.passed}</span>
+                    <span>Failed: {oneByOneSummary.failed}</span>
+                    {oneByOneSummary.stopped && (
+                      <span className="text-amber-600 dark:text-amber-400">Stopped</span>
+                    )}
+                    {oneByOneRunning && oneByOneCurrentConnectionId && (
+                      <span>Running: {connections.find((conn) => conn.id === oneByOneCurrentConnectionId)?.name || oneByOneCurrentConnectionId}</span>
+                    )}
+                  </div>
+                </div>
+              )}
+              {connections.length > 0 && (
+                <div className="mb-3 flex items-center gap-2 border-b border-black/[0.03] pb-2 dark:border-white/[0.03]">
+                  <label className="flex cursor-pointer items-center gap-1.5 text-xs text-text-muted hover:text-primary">
+                    <input
+                      type="checkbox"
+                      checked={allSelected}
+                      onChange={toggleSelectAllConnections}
+                      className="h-3.5 w-3.5 rounded border-gray-300 text-primary focus:ring-primary"
+                    />
+                    Select All
+                  </label>
+                </div>
+              )}
+              {connectionsList}
+              {!isCompatible && (
+                <div className="mt-4 grid grid-cols-1 gap-2 sm:flex">
+                  {providerId === "iflow" && (
+                    <Button
+                      size="sm"
+                      icon="cookie"
+                      variant="secondary"
+                      onClick={() => setShowIFlowCookieModal(true)}
+                      title="Add connection using browser cookie"
+                      className="w-full sm:w-auto"
+                    >
+                      Cookie
+                    </Button>
+                  )}
+                  {providerId === "codex" && (
+                    <Button
+                      size="sm"
+                      icon="playlist_add"
+                      variant="secondary"
+                      onClick={() => setShowBulkImportCodex(true)}
+                      title={translate("Bulk import codex accounts from JSON")}
+                      className="w-full sm:w-auto"
+                    >
+                      {translate("Bulk Add")}
+                    </Button>
+                  )}
+                  {hasDualAuthModes ? (
+                    <>
+                      <Button
+                        size="sm"
+                        icon="lock"
+                        variant="secondary"
+                        onClick={triggerOAuthConnection}
+                        className="w-full sm:w-auto"
+                      >
+                        {oauthConnectionLabel}
+                      </Button>
+                      <Button
+                        size="sm"
+                        icon="key"
+                        onClick={triggerApiKeyConnection}
+                        className="w-full sm:w-auto"
+                      >
+                        {apiKeyConnectionLabel}
+                      </Button>
+                    </>
+                  ) : (
+                    <Button
+                      size="sm"
+                      icon="add"
+                      onClick={triggerAddConnection}
+                      className="w-full sm:w-auto"
+                    >
+                      Add
+                    </Button>
+                  )}
+                </div>
+              )}
+            </>
+          )}
+        </Card>
+      )}
+
+      {/* Models */}
+      <Card>
+        <div className="mb-4 flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+          <div className="flex items-center gap-3">
+            <h2 className="text-lg font-semibold">
+              {"Available Models"}
+            </h2>
+            {providerThinkingLevels && (
+              <select
+                value={thinkingMode}
+                onChange={(e) => handleThinkingModeChange(e.target.value)}
+                title="Appends (level) suffix to copied model names"
+                className="rounded-md border border-border bg-background px-2 py-1 text-xs focus:border-primary focus:outline-none"
+              >
+                {providerThinkingLevels.map((opt) => (
+                  <option key={opt} value={opt}>{`Thinking: ${opt.charAt(0).toUpperCase() + opt.slice(1)}`}</option>
+                ))}
+              </select>
+            )}
+          </div>
+          {!isCompatible && (() => {
+            const allIds = [
+              ...models,
+              ...kiloFreeModels.filter((fm) => !models.some((m) => m.id === fm.id)),
+            ].filter((m) => { const k = getModelKind(m); return !k || k === "llm"; }).map((m) => m.id);
+            const activeIds = allIds.filter((id) => !disabledModelIds.includes(id));
+            return (
+              <div className="flex gap-2">
+                {disabledModelIds.length > 0 && (
+                  <Button size="sm" variant="secondary" icon="restart_alt" onClick={handleEnableAll}>
+                    Active All
+                  </Button>
+                )}
+                {activeIds.length > 0 && (
+                  <Button size="sm" variant="secondary" icon="block" onClick={() => handleDisableAll(activeIds)}>
+                    Disable All
+                  </Button>
+                )}
+              </div>
+            );
+          })()}
+        </div>
+        {!!modelsTestError && (
+          <p className="text-xs text-red-500 mb-3 break-words">{modelsTestError}</p>
+        )}
+        {renderModelsSection()}
+      </Card>
+
+      {bulkActionModal}
+
+      {/* Modals */}
+      {providerId === "kiro" ? (
+        <KiroOAuthWrapper
+          isOpen={showOAuthModal}
+          providerInfo={providerInfo}
+          onSuccess={handleOAuthSuccess}
+          onClose={() => setShowOAuthModal(false)}
+        />
+      ) : providerId === "cursor" ? (
+        <CursorAuthModal
+          isOpen={showOAuthModal}
+          onSuccess={handleOAuthSuccess}
+          onClose={() => setShowOAuthModal(false)}
+        />
+      ) : providerId === "gitlab" ? (
+        <GitLabAuthModal
+          isOpen={showOAuthModal}
+          providerInfo={providerInfo}
+          onSuccess={handleOAuthSuccess}
+          onClose={() => setShowOAuthModal(false)}
+        />
+      ) : (
+        <OAuthModal
+          isOpen={showOAuthModal}
+          provider={providerId}
+          providerInfo={providerInfo}
+          onSuccess={handleOAuthSuccess}
+          onClose={() => setShowOAuthModal(false)}
+        />
+      )}
+      {providerId === "iflow" && (
+        <IFlowCookieModal
+          isOpen={showIFlowCookieModal}
+          onSuccess={handleIFlowCookieSuccess}
+          onClose={() => setShowIFlowCookieModal(false)}
+        />
+      )}
+      <AddApiKeyModal
+        isOpen={showAddApiKeyModal}
+        provider={providerId}
+        providerName={providerInfo.name}
+        isCompatible={isCompatible}
+        isAnthropic={isAnthropicCompatible}
+        authType={providerInfo?.authType}
+        authHint={providerInfo?.authHint}
+        website={providerInfo?.website}
+        proxyPools={proxyPools}
+        error={addConnectionError}
+        onSave={handleSaveApiKey}
+        onBulkDone={fetchConnections}
+        onClose={() => {
+          setAddConnectionError("");
+          setShowAddApiKeyModal(false);
+        }}
+      />
+      <EditConnectionModal
+        isOpen={showEditModal}
+        connection={selectedConnection}
+        proxyPools={proxyPools}
+        onSave={handleUpdateConnection}
+        onClose={() => setShowEditModal(false)}
+      />
+      {isCompatible && (
+        <EditCompatibleNodeModal
+          isOpen={showEditNodeModal}
+          node={providerNode}
+          onSave={handleUpdateNode}
+          onClose={() => setShowEditNodeModal(false)}
+          isAnthropic={isAnthropicCompatible}
+        />
+      )}
+      {!isCompatible && (
+        <AddCustomModelModal
+          isOpen={showAddCustomModel}
+          providerAlias={providerStorageAlias}
+          providerDisplayAlias={providerDisplayAlias}
+          onSave={async (modelId) => {
+            await handleAddCustomModel(modelId, "llm", providerStorageAlias);
+            setShowAddCustomModel(false);
+          }}
+          onClose={() => setShowAddCustomModel(false)}
+        />
+      )}
+
+      {providerId === "codex" && (
+        <BulkImportCodexModal
+          isOpen={showBulkImportCodex}
+          onClose={() => setShowBulkImportCodex(false)}
+          onSuccess={fetchConnections}
+        />
+      )}
+
+      {/* AG Risk Confirmation Modal */}
+      <ConfirmModal
+        isOpen={showAgRiskModal}
+        onClose={() => setShowAgRiskModal(false)}
+        onConfirm={handleAgRiskConfirm}
+        title="Risk Notice"
+        message={providerInfo?.deprecationNotice}
+        confirmText="I Understand, Continue"
+        cancelText="Cancel"
+        variant="danger"
+      />
+
+      {/* Confirm Modal */}
+      <ConfirmModal
+        isOpen={!!confirmState}
+        onClose={() => setConfirmState(null)}
+        onConfirm={confirmState?.onConfirm}
+        title={confirmState?.title || "Confirm"}
+        message={confirmState?.message}
+        variant="danger"
+      />
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/providers/components/AddCompatibleModal.js b/src/app/(dashboard)/dashboard/providers/components/AddCompatibleModal.js
new file mode 100644
index 0000000..d0951d7
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/components/AddCompatibleModal.js
@@ -0,0 +1,221 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import PropTypes from "prop-types";
+import { Badge, Button, Input, Modal, Select } from "@/shared/components";
+
+const VARIANT_CONFIG = {
+  openai: {
+    title: "Add OpenAI Compatible",
+    type: "openai-compatible",
+    defaultBaseUrl: "https://api.openai.com/v1",
+    namePlaceholder: "OpenAI Compatible (Prod)",
+    prefixPlaceholder: "oc-prod",
+    baseUrlHint: "Use the base URL (ending in /v1) for your OpenAI-compatible API.",
+    modelIdPlaceholder: "e.g. gpt-4, claude-3-opus",
+    errorLabel: "OpenAI Compatible",
+    hasApiType: true,
+  },
+  anthropic: {
+    title: "Add Anthropic Compatible",
+    type: "anthropic-compatible",
+    defaultBaseUrl: "https://api.anthropic.com/v1",
+    namePlaceholder: "Anthropic Compatible (Prod)",
+    prefixPlaceholder: "ac-prod",
+    baseUrlHint: "Use the base URL (ending in /v1) for your Anthropic-compatible API. The system will append /messages.",
+    modelIdPlaceholder: "e.g. claude-3-opus",
+    errorLabel: "Anthropic Compatible",
+    hasApiType: false,
+  },
+};
+
+const API_TYPE_OPTIONS = [
+  { value: "chat", label: "Chat Completions" },
+  { value: "responses", label: "Responses API" },
+];
+
+function AddCompatibleModal({ variant, isOpen, onClose, onCreated }) {
+  const config = VARIANT_CONFIG[variant];
+  const initialFormData = () => ({
+    name: "",
+    prefix: "",
+    ...(config.hasApiType ? { apiType: "chat" } : {}),
+    baseUrl: config.defaultBaseUrl,
+  });
+
+  const [formData, setFormData] = useState(initialFormData);
+  const [submitting, setSubmitting] = useState(false);
+  const [checkKey, setCheckKey] = useState("");
+  const [checkModelId, setCheckModelId] = useState("");
+  const [validating, setValidating] = useState(false);
+  const [validationResult, setValidationResult] = useState(null);
+
+  // openai: reset baseUrl when apiType changes; anthropic: reset checks when opened
+  useEffect(() => {
+    if (config.hasApiType) {
+      setFormData((prev) => ({ ...prev, baseUrl: config.defaultBaseUrl }));
+    } else if (isOpen) {
+      setValidationResult(null);
+      setCheckKey("");
+      setCheckModelId("");
+    }
+  }, [config.hasApiType ? formData.apiType : isOpen]);
+
+  const handleSubmit = async () => {
+    if (!formData.name.trim() || !formData.prefix.trim() || !formData.baseUrl.trim()) return;
+    setSubmitting(true);
+    try {
+      const res = await fetch("/api/provider-nodes", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          name: formData.name,
+          prefix: formData.prefix,
+          ...(config.hasApiType ? { apiType: formData.apiType } : {}),
+          baseUrl: formData.baseUrl,
+          type: config.type,
+        }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        onCreated(data.node);
+        setFormData(initialFormData());
+        setCheckKey("");
+        setValidationResult(null);
+      }
+    } catch (error) {
+      console.log(`Error creating ${config.errorLabel} node:`, error);
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleValidate = async () => {
+    setValidating(true);
+    try {
+      const res = await fetch("/api/provider-nodes/validate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: formData.baseUrl,
+          apiKey: checkKey,
+          type: config.type,
+          modelId: checkModelId.trim() || undefined,
+        }),
+      });
+      const data = await res.json();
+      setValidationResult(data);
+    } catch {
+      setValidationResult({ valid: false, error: "Network error" });
+    } finally {
+      setValidating(false);
+    }
+  };
+
+  const renderValidationResult = () => {
+    if (!validationResult) return null;
+    const { valid, error, method } = validationResult;
+    if (valid) {
+      return (
+        <>
+          <Badge variant="success">Valid</Badge>
+          {method === "chat" && (
+            <span className="text-sm text-text-muted">(via inference test)</span>
+          )}
+        </>
+      );
+    }
+    return (
+      <div className="flex flex-col gap-1">
+        <Badge variant="error">Invalid</Badge>
+        {error && <span className="text-sm text-red-500">{error}</span>}
+      </div>
+    );
+  };
+
+  return (
+    <Modal isOpen={isOpen} title={config.title} onClose={onClose}>
+      <div className="flex flex-col gap-4">
+        <Input
+          label="Name"
+          value={formData.name}
+          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+          placeholder={config.namePlaceholder}
+          hint="Required. A friendly label for this node."
+        />
+        <Input
+          label="Prefix"
+          value={formData.prefix}
+          onChange={(e) => setFormData({ ...formData, prefix: e.target.value })}
+          placeholder={config.prefixPlaceholder}
+          hint="Required. Used as the provider prefix for model IDs."
+        />
+        {config.hasApiType && (
+          <Select
+            label="API Type"
+            options={API_TYPE_OPTIONS}
+            value={formData.apiType}
+            onChange={(e) => setFormData({ ...formData, apiType: e.target.value })}
+          />
+        )}
+        <Input
+          label="Base URL"
+          value={formData.baseUrl}
+          onChange={(e) => setFormData({ ...formData, baseUrl: e.target.value })}
+          placeholder={config.defaultBaseUrl}
+          hint={config.baseUrlHint}
+        />
+        <Input
+          label="API Key (for Check)"
+          type="password"
+          value={checkKey}
+          onChange={(e) => setCheckKey(e.target.value)}
+        />
+        <Input
+          label="Model ID (optional)"
+          value={checkModelId}
+          onChange={(e) => setCheckModelId(e.target.value)}
+          placeholder={config.modelIdPlaceholder}
+          hint="If provider lacks /models endpoint, enter a model ID to validate via chat/completions instead."
+        />
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center">
+          <Button
+            onClick={handleValidate}
+            disabled={!checkKey || validating || !formData.baseUrl.trim()}
+            variant="secondary"
+            className="w-full sm:w-auto"
+          >
+            {validating ? "Checking..." : "Check"}
+          </Button>
+          {renderValidationResult()}
+        </div>
+        <div className="flex flex-col gap-2 sm:flex-row">
+          <Button
+            onClick={handleSubmit}
+            fullWidth
+            disabled={
+              !formData.name.trim() ||
+              !formData.prefix.trim() ||
+              !formData.baseUrl.trim() ||
+              submitting
+            }
+          >
+            {submitting ? "Creating..." : "Create"}
+          </Button>
+          <Button onClick={onClose} variant="ghost" fullWidth>
+            Cancel
+          </Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+AddCompatibleModal.propTypes = {
+  variant: PropTypes.oneOf(["openai", "anthropic"]).isRequired,
+  isOpen: PropTypes.bool.isRequired,
+  onClose: PropTypes.func.isRequired,
+  onCreated: PropTypes.func.isRequired,
+};
+
+export default AddCompatibleModal;
diff --git a/src/app/(dashboard)/dashboard/providers/components/ConnectionsCard.js b/src/app/(dashboard)/dashboard/providers/components/ConnectionsCard.js
new file mode 100644
index 0000000..6b178bd
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/components/ConnectionsCard.js
@@ -0,0 +1,493 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { getStatusVariant as getConnectionStatusVariant } from "@/shared/utils/connectionStatus";
+import PropTypes from "prop-types";
+import { Card, Badge, Button, Modal, Select, Toggle, EditConnectionModal, ConfirmModal } from "@/shared/components";
+
+// ── CooldownTimer ──────────────────────────────────────────────
+function CooldownTimer({ until }) {
+  const [remaining, setRemaining] = useState("");
+
+  useEffect(() => {
+    const update = () => {
+      const diff = new Date(until).getTime() - Date.now();
+      if (diff <= 0) { setRemaining(""); return; }
+      const s = Math.floor(diff / 1000);
+      if (s < 60) setRemaining(`${s}s`);
+      else if (s < 3600) setRemaining(`${Math.floor(s / 60)}m ${s % 60}s`);
+      else setRemaining(`${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`);
+    };
+    update();
+    const t = setInterval(update, 1000);
+    return () => clearInterval(t);
+  }, [until]);
+
+  if (!remaining) return null;
+  return <span className="text-xs text-orange-500 font-mono">⏱ {remaining}</span>;
+}
+
+CooldownTimer.propTypes = { until: PropTypes.string.isRequired };
+
+// ── ConnectionRow ──────────────────────────────────────────────
+function ConnectionRow({ connection, proxyPools, isOAuth, isFirst, isLast, onMoveUp, onMoveDown, onToggleActive, onUpdateProxy, onEdit, onDelete }) {
+  const [showProxyDropdown, setShowProxyDropdown] = useState(false);
+  const [updatingProxy, setUpdatingProxy] = useState(false);
+  const [isCooldown, setIsCooldown] = useState(false);
+  const proxyDropdownRef = useRef(null);
+
+  const proxyPoolMap = new Map((proxyPools || []).map((p) => [p.id, p]));
+  const boundProxyPoolId = connection.providerSpecificData?.proxyPoolId || null;
+  const boundProxyPool = boundProxyPoolId ? proxyPoolMap.get(boundProxyPoolId) : null;
+  const hasLegacyProxy = connection.providerSpecificData?.connectionProxyEnabled === true && !!connection.providerSpecificData?.connectionProxyUrl;
+  const hasAnyProxy = !!boundProxyPoolId || hasLegacyProxy;
+
+  const proxyDisplayText = boundProxyPool
+    ? `Pool: ${boundProxyPool.name}`
+    : boundProxyPoolId ? `Pool: ${boundProxyPoolId} (inactive/missing)`
+    : hasLegacyProxy ? `Legacy: ${connection.providerSpecificData?.connectionProxyUrl}` : "";
+
+  let maskedProxyUrl = "";
+  const rawProxyUrl = boundProxyPool?.proxyUrl || connection.providerSpecificData?.connectionProxyUrl;
+  if (rawProxyUrl) {
+    try {
+      const p = new URL(rawProxyUrl);
+      maskedProxyUrl = `${p.protocol}//${p.hostname}${p.port ? `:${p.port}` : ""}`;
+    } catch { maskedProxyUrl = rawProxyUrl; }
+  }
+
+  const noProxyText = boundProxyPool?.noProxy || connection.providerSpecificData?.connectionNoProxy || "";
+  const proxyBadgeVariant = boundProxyPool?.isActive === true ? "success" : (boundProxyPoolId || hasLegacyProxy) ? "error" : "default";
+
+  const modelLockUntil = Object.entries(connection)
+    .filter(([k]) => k.startsWith("modelLock_"))
+    .map(([, v]) => v).filter(Boolean).sort()[0] || null;
+
+  useEffect(() => {
+    const check = () => {
+      const until = Object.entries(connection)
+        .filter(([k]) => k.startsWith("modelLock_"))
+        .map(([, v]) => v).filter(v => v && new Date(v).getTime() > Date.now()).sort()[0] || null;
+      setIsCooldown(!!until);
+    };
+    check();
+    const t = modelLockUntil ? setInterval(check, 1000) : null;
+    return () => { if (t) clearInterval(t); };
+  }, [modelLockUntil]);
+
+  useEffect(() => {
+    if (!showProxyDropdown) return;
+    const handler = (e) => {
+      if (proxyDropdownRef.current && !proxyDropdownRef.current.contains(e.target))
+        setShowProxyDropdown(false);
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [showProxyDropdown]);
+
+  const effectiveStatus = connection.testStatus === "unavailable" && !isCooldown ? "active" : connection.testStatus;
+
+  const getStatusVariant = () => getConnectionStatusVariant(connection.isActive, effectiveStatus);
+
+  const displayName = isOAuth
+    ? connection.name || connection.email || connection.displayName || "OAuth Account"
+    : connection.name;
+
+  const handleSelectProxy = async (poolId) => {
+    setUpdatingProxy(true);
+    try { await onUpdateProxy(poolId === "__none__" ? null : poolId); }
+    finally { setUpdatingProxy(false); setShowProxyDropdown(false); }
+  };
+
+  return (
+    <div className={`group flex flex-col gap-3 p-2 rounded-lg sm:flex-row sm:items-center sm:justify-between hover:bg-black/[0.02] dark:hover:bg-white/[0.02] transition-colors ${connection.isActive === false ? "opacity-60" : ""}`}>
+      <div className="flex w-full min-w-0 flex-1 items-start gap-3 sm:items-center">
+        <div className="flex flex-col">
+          <button onClick={onMoveUp} disabled={isFirst} className={`p-0.5 rounded ${isFirst ? "text-text-muted/30 cursor-not-allowed" : "hover:bg-sidebar text-text-muted hover:text-primary"}`}>
+            <span className="material-symbols-outlined text-sm">keyboard_arrow_up</span>
+          </button>
+          <button onClick={onMoveDown} disabled={isLast} className={`p-0.5 rounded ${isLast ? "text-text-muted/30 cursor-not-allowed" : "hover:bg-sidebar text-text-muted hover:text-primary"}`}>
+            <span className="material-symbols-outlined text-sm">keyboard_arrow_down</span>
+          </button>
+        </div>
+        <span className="material-symbols-outlined text-base text-text-muted">{isOAuth ? "lock" : "key"}</span>
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-medium truncate">{displayName}</p>
+          <div className="flex flex-wrap items-center gap-2 mt-1">
+            <Badge variant={getStatusVariant()} size="sm" dot>
+              {connection.isActive === false ? "disabled" : (effectiveStatus || "Unknown")}
+            </Badge>
+            {hasAnyProxy && <Badge variant={proxyBadgeVariant} size="sm">Proxy</Badge>}
+            {isCooldown && connection.isActive !== false && <CooldownTimer until={modelLockUntil} />}
+            {connection.lastError && connection.isActive !== false && (
+              <span className="text-xs text-red-500 truncate max-w-[300px]" title={connection.lastError}>{connection.lastError}</span>
+            )}
+            <span className="text-xs text-text-muted">#{connection.priority}</span>
+          </div>
+          {hasAnyProxy && (
+            <div className="mt-1 flex flex-wrap items-center gap-2">
+              <span className="text-[11px] text-text-muted truncate max-w-[420px]" title={proxyDisplayText}>{proxyDisplayText}</span>
+              {maskedProxyUrl && <code className="text-[10px] font-mono bg-black/5 dark:bg-white/5 px-1 py-0.5 rounded text-text-muted">{maskedProxyUrl}</code>}
+              {noProxyText && <span className="text-[11px] text-text-muted truncate max-w-[320px]" title={noProxyText}>no_proxy: {noProxyText}</span>}
+            </div>
+          )}
+        </div>
+      </div>
+      <div className="flex w-full flex-wrap items-center justify-between gap-2 sm:w-auto sm:justify-end">
+        <div className="flex flex-wrap gap-1">
+          {(proxyPools || []).length > 0 && (
+            <div className="relative" ref={proxyDropdownRef}>
+              <button
+                onClick={() => setShowProxyDropdown((v) => !v)}
+                className={`flex flex-col items-center px-2 py-1 rounded hover:bg-black/5 dark:hover:bg-white/5 transition-colors ${hasAnyProxy ? "text-primary" : "text-text-muted hover:text-primary"}`}
+                disabled={updatingProxy}
+              >
+                <span className="material-symbols-outlined text-[18px]">{updatingProxy ? "progress_activity" : "lan"}</span>
+                <span className="text-[10px] leading-tight">Proxy</span>
+              </button>
+              {showProxyDropdown && (
+                <div className="absolute right-0 top-full mt-1 z-50 bg-bg border border-border rounded-lg shadow-lg py-1 min-w-[160px]">
+                  <button onClick={() => handleSelectProxy("__none__")} className={`w-full text-left px-3 py-1.5 text-sm hover:bg-black/5 dark:hover:bg-white/5 ${!boundProxyPoolId ? "text-primary font-medium" : "text-text-main"}`}>None</button>
+                  {(proxyPools || []).map((pool) => (
+                    <button key={pool.id} onClick={() => handleSelectProxy(pool.id)} className={`w-full text-left px-3 py-1.5 text-sm hover:bg-black/5 dark:hover:bg-white/5 ${boundProxyPoolId === pool.id ? "text-primary font-medium" : "text-text-main"}`}>{pool.name}</button>
+                  ))}
+                </div>
+              )}
+            </div>
+          )}
+          <button onClick={onEdit} className="flex flex-col items-center px-2 py-1 rounded hover:bg-black/5 dark:hover:bg-white/5 text-text-muted hover:text-primary">
+            <span className="material-symbols-outlined text-[18px]">edit</span>
+            <span className="text-[10px] leading-tight">Edit</span>
+          </button>
+          <button onClick={onDelete} className="flex flex-col items-center px-2 py-1 rounded hover:bg-red-500/10 text-red-500">
+            <span className="material-symbols-outlined text-[18px]">delete</span>
+            <span className="text-[10px] leading-tight">Delete</span>
+          </button>
+        </div>
+        <Toggle size="sm" checked={connection.isActive ?? true} onChange={onToggleActive} title={(connection.isActive ?? true) ? "Disable" : "Enable"} />
+      </div>
+    </div>
+  );
+}
+
+ConnectionRow.propTypes = {
+  connection: PropTypes.shape({
+    id: PropTypes.string,
+    name: PropTypes.string,
+    email: PropTypes.string,
+    displayName: PropTypes.string,
+    testStatus: PropTypes.string,
+    isActive: PropTypes.bool,
+    lastError: PropTypes.string,
+    priority: PropTypes.number,
+  }).isRequired,
+  proxyPools: PropTypes.array,
+  isOAuth: PropTypes.bool.isRequired,
+  isFirst: PropTypes.bool.isRequired,
+  isLast: PropTypes.bool.isRequired,
+  onMoveUp: PropTypes.func.isRequired,
+  onMoveDown: PropTypes.func.isRequired,
+  onToggleActive: PropTypes.func.isRequired,
+  onUpdateProxy: PropTypes.func,
+  onEdit: PropTypes.func.isRequired,
+  onDelete: PropTypes.func.isRequired,
+};
+
+// ── AddApiKeyModal ─────────────────────────────────────────────
+function AddApiKeyModal({ isOpen, provider, providerName, proxyPools, onSave, onClose }) {
+  const NONE = "__none__";
+  const [formData, setFormData] = useState({ name: "", apiKey: "", priority: 1, proxyPoolId: NONE });
+  const [validating, setValidating] = useState(false);
+  const [validationResult, setValidationResult] = useState(null);
+  const [saving, setSaving] = useState(false);
+
+  const handleValidate = async () => {
+    setValidating(true);
+    try {
+      const res = await fetch("/api/providers/validate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ provider, apiKey: formData.apiKey }),
+      });
+      const data = await res.json();
+      setValidationResult(data.valid ? "success" : "failed");
+    } catch { setValidationResult("failed"); }
+    finally { setValidating(false); }
+  };
+
+  const handleSubmit = async () => {
+    if (!provider || !formData.apiKey) return;
+    setSaving(true);
+    try {
+      let isValid = false;
+      try {
+        setValidating(true); setValidationResult(null);
+        const res = await fetch("/api/providers/validate", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ provider, apiKey: formData.apiKey }),
+        });
+        const data = await res.json();
+        isValid = !!data.valid;
+        setValidationResult(isValid ? "success" : "failed");
+      } catch { setValidationResult("failed"); }
+      finally { setValidating(false); }
+      await onSave({
+        name: formData.name,
+        apiKey: formData.apiKey,
+        priority: formData.priority,
+        proxyPoolId: formData.proxyPoolId === NONE ? null : formData.proxyPoolId,
+        testStatus: isValid ? "active" : "unknown",
+      });
+    } finally { setSaving(false); }
+  };
+
+  if (!provider) return null;
+
+  return (
+    <Modal isOpen={isOpen} title={`Add ${providerName || provider} API Key`} onClose={onClose}>
+      <div className="flex flex-col gap-4">
+        <div>
+          <label className="text-xs text-text-muted mb-1 block">Name</label>
+          <input className="w-full px-3 py-2 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary" value={formData.name} onChange={(e) => setFormData({ ...formData, name: e.target.value })} placeholder="Production Key" />
+        </div>
+        <div className="flex gap-2">
+          <div className="flex-1">
+            <label className="text-xs text-text-muted mb-1 block">API Key</label>
+            <input type="password" className="w-full px-3 py-2 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary" value={formData.apiKey} onChange={(e) => setFormData({ ...formData, apiKey: e.target.value })} />
+          </div>
+          <div className="pt-6">
+            <Button onClick={handleValidate} disabled={!formData.apiKey || validating || saving} variant="secondary">
+              {validating ? "Checking..." : "Check"}
+            </Button>
+          </div>
+        </div>
+        {validationResult && (
+          <Badge variant={validationResult === "success" ? "success" : "error"}>
+            {validationResult === "success" ? "Valid" : "Invalid"}
+          </Badge>
+        )}
+        <div>
+          <label className="text-xs text-text-muted mb-1 block">Priority</label>
+          <input type="number" className="w-full px-3 py-2 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary" value={formData.priority} onChange={(e) => setFormData({ ...formData, priority: Number.parseInt(e.target.value) || 1 })} />
+        </div>
+        <Select label="Proxy Pool" value={formData.proxyPoolId} onChange={(e) => setFormData({ ...formData, proxyPoolId: e.target.value })}
+          options={[{ value: NONE, label: "None" }, ...(proxyPools || []).map((p) => ({ value: p.id, label: p.name }))]} />
+        <div className="flex gap-2">
+          <Button onClick={handleSubmit} fullWidth disabled={!formData.name || !formData.apiKey || saving}>
+            {saving ? "Saving..." : "Save"}
+          </Button>
+          <Button onClick={onClose} variant="ghost" fullWidth>Cancel</Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+AddApiKeyModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  provider: PropTypes.string,
+  providerName: PropTypes.string,
+  proxyPools: PropTypes.array,
+  onSave: PropTypes.func.isRequired,
+  onClose: PropTypes.func.isRequired,
+};
+
+// ── ConnectionsCard ────────────────────────────────────────────
+// Self-contained card: fetches, displays and manages all connections for a provider.
+export default function ConnectionsCard({ providerId, isOAuth }) {
+  const [connections, setConnections] = useState([]);
+  const [proxyPools, setProxyPools] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [showAddModal, setShowAddModal] = useState(false);
+  const [showEditModal, setShowEditModal] = useState(false);
+  const [selectedConnection, setSelectedConnection] = useState(null);
+  const [providerStrategy, setProviderStrategy] = useState(null);
+  const [providerStickyLimit, setProviderStickyLimit] = useState("1");
+  const [confirmState, setConfirmState] = useState(null);
+
+  const fetch_ = useCallback(async () => {
+    try {
+      const [connRes, proxyRes, settingsRes] = await Promise.all([
+        fetch("/api/providers", { cache: "no-store" }),
+        fetch("/api/proxy-pools?isActive=true", { cache: "no-store" }),
+        fetch("/api/settings", { cache: "no-store" }),
+      ]);
+      const connData = await connRes.json();
+      const proxyData = await proxyRes.json();
+      const settingsData = settingsRes.ok ? await settingsRes.json() : {};
+      if (connRes.ok) setConnections((connData.connections || []).filter((c) => c.provider === providerId));
+      if (proxyRes.ok) setProxyPools(proxyData.proxyPools || []);
+      const override = (settingsData.providerStrategies || {})[providerId] || {};
+      setProviderStrategy(override.fallbackStrategy || null);
+      setProviderStickyLimit(override.stickyRoundRobinLimit != null ? String(override.stickyRoundRobinLimit) : "1");
+    } catch (e) { console.log("ConnectionsCard fetch error:", e); }
+    finally { setLoading(false); }
+  }, [providerId]);
+
+  useEffect(() => { fetch_(); }, [fetch_]);
+
+  const saveStrategy = async (strategy, stickyLimit) => {
+    try {
+      const res = await fetch("/api/settings", { cache: "no-store" });
+      const data = res.ok ? await res.json() : {};
+      const current = data.providerStrategies || {};
+      const override = {};
+      if (strategy) override.fallbackStrategy = strategy;
+      if (strategy === "round-robin" && stickyLimit !== "") override.stickyRoundRobinLimit = Number(stickyLimit) || 3;
+      const updated = { ...current };
+      if (Object.keys(override).length === 0) delete updated[providerId];
+      else updated[providerId] = override;
+      await fetch("/api/settings", { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ providerStrategies: updated }) });
+    } catch (e) { console.log("saveStrategy error:", e); }
+  };
+
+  const handleSwapPriority = async (i1, i2) => {
+    const next = [...connections];
+    [next[i1], next[i2]] = [next[i2], next[i1]];
+    setConnections(next);
+    try {
+      await Promise.all([
+        fetch(`/api/providers/${next[i1].id}`, { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ priority: i1 }) }),
+        fetch(`/api/providers/${next[i2].id}`, { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ priority: i2 }) }),
+      ]);
+    } catch { await fetch_(); }
+  };
+
+  const handleDelete = async (id) => {
+    setConfirmState({
+      title: "Delete Connection",
+      message: "Delete this connection?",
+      onConfirm: async () => {
+        setConfirmState(null);
+        try {
+          const res = await fetch(`/api/providers/${id}`, { method: "DELETE" });
+          if (res.ok) setConnections((prev) => prev.filter((c) => c.id !== id));
+        } catch (e) { console.log("delete error:", e); }
+      }
+    });
+  };
+
+  const handleToggleActive = async (id, isActive) => {
+    try {
+      const res = await fetch(`/api/providers/${id}`, { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ isActive }) });
+      if (res.ok) setConnections((prev) => prev.map((c) => c.id === id ? { ...c, isActive } : c));
+    } catch (e) { console.log("toggle error:", e); }
+  };
+
+  const handleUpdateProxy = async (connId, proxyPoolId) => {
+    try {
+      const res = await fetch(`/api/providers/${connId}`, { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ proxyPoolId: proxyPoolId || null }) });
+      if (res.ok) setConnections((prev) => prev.map((c) => c.id === connId ? { ...c, providerSpecificData: { ...c.providerSpecificData, proxyPoolId: proxyPoolId || null } } : c));
+    } catch (e) { console.log("proxy error:", e); }
+  };
+
+  const handleSaveApiKey = async (formData) => {
+    try {
+      const res = await fetch("/api/providers", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ provider: providerId, ...formData }) });
+      if (res.ok) { await fetch_(); setShowAddModal(false); }
+    } catch (e) { console.log("save apikey error:", e); }
+  };
+
+  const handleUpdateConnection = async (formData) => {
+    try {
+      const res = await fetch(`/api/providers/${selectedConnection.id}`, { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify(formData) });
+      if (res.ok) { await fetch_(); setShowEditModal(false); }
+    } catch (e) { console.log("update connection error:", e); }
+  };
+
+  if (loading) return <Card><div className="h-20 animate-pulse bg-black/5 rounded-lg" /></Card>;
+
+  return (
+    <>
+      <Card>
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between mb-4">
+          <h2 className="text-lg font-semibold">Connections</h2>
+          <div className="flex flex-wrap items-center gap-2">
+            <span className="text-xs text-text-muted font-medium">Round Robin</span>
+            <Toggle
+              checked={providerStrategy === "round-robin"}
+              onChange={(enabled) => {
+                const strategy = enabled ? "round-robin" : null;
+                setProviderStrategy(strategy);
+                if (enabled && !providerStickyLimit) setProviderStickyLimit("1");
+                saveStrategy(strategy, enabled ? (providerStickyLimit || "1") : providerStickyLimit);
+              }}
+            />
+            {providerStrategy === "round-robin" && (
+              <div className="flex flex-wrap items-center gap-1.5">
+                <span className="text-xs text-text-muted">Sticky:</span>
+                <input
+                  type="number" min={1} value={providerStickyLimit}
+                  onChange={(e) => { setProviderStickyLimit(e.target.value); saveStrategy("round-robin", e.target.value); }}
+                  className="w-16 px-2 py-1 text-xs border border-border rounded-md bg-background focus:outline-none focus:border-primary"
+                />
+              </div>
+            )}
+          </div>
+        </div>
+
+        {connections.length === 0 ? (
+          <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+            <p className="text-sm text-text-muted">No connections yet</p>
+            <Button size="sm" icon="add" onClick={() => setShowAddModal(true)}>Add Connection</Button>
+          </div>
+        ) : (
+          <>
+            <div className="flex flex-col divide-y divide-black/[0.03] dark:divide-white/[0.03]">
+              {connections.map((conn, idx) => (
+                <ConnectionRow
+                  key={conn.id}
+                  connection={conn}
+                  proxyPools={proxyPools}
+                  isOAuth={isOAuth}
+                  isFirst={idx === 0}
+                  isLast={idx === connections.length - 1}
+                  onMoveUp={() => handleSwapPriority(idx, idx - 1)}
+                  onMoveDown={() => handleSwapPriority(idx, idx + 1)}
+                  onToggleActive={(isActive) => handleToggleActive(conn.id, isActive)}
+                  onUpdateProxy={(poolId) => handleUpdateProxy(conn.id, poolId)}
+                  onEdit={() => { setSelectedConnection(conn); setShowEditModal(true); }}
+                  onDelete={() => handleDelete(conn.id)}
+                />
+              ))}
+            </div>
+            <div className="mt-4 flex justify-stretch sm:justify-start">
+              <Button size="sm" icon="add" onClick={() => setShowAddModal(true)}>Add</Button>
+            </div>
+          </>
+        )}
+      </Card>
+
+      <AddApiKeyModal
+        isOpen={showAddModal}
+        provider={providerId}
+        proxyPools={proxyPools}
+        onSave={handleSaveApiKey}
+        onClose={() => setShowAddModal(false)}
+      />
+      <EditConnectionModal
+        isOpen={showEditModal}
+        connection={selectedConnection}
+        proxyPools={proxyPools}
+        onSave={handleUpdateConnection}
+        onClose={() => setShowEditModal(false)}
+      />
+
+      {/* Confirm Modal */}
+      <ConfirmModal
+        isOpen={!!confirmState}
+        onClose={() => setConfirmState(null)}
+        onConfirm={confirmState?.onConfirm}
+        title={confirmState?.title || "Confirm"}
+        message={confirmState?.message}
+        variant="danger"
+      />
+    </>
+  );
+}
+
+ConnectionsCard.propTypes = {
+  providerId: PropTypes.string.isRequired,
+  isOAuth: PropTypes.bool,
+};
diff --git a/src/app/(dashboard)/dashboard/providers/components/ModelAvailabilityBadge.js b/src/app/(dashboard)/dashboard/providers/components/ModelAvailabilityBadge.js
new file mode 100644
index 0000000..9150bef
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/components/ModelAvailabilityBadge.js
@@ -0,0 +1,185 @@
+"use client";
+
+/**
+ * ModelAvailabilityBadge — compact inline status indicator
+ *
+ * Shows green when all models are operational, or amber/red when there are
+ * issues, with a hover popover for details and cooldown clearing.
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { Button } from "@/shared/components";
+import { useNotificationStore } from "@/store/notificationStore";
+
+const STATUS_CONFIG = {
+  available: { icon: "check_circle", color: "#22c55e", label: "Available" },
+  cooldown: { icon: "schedule", color: "#f59e0b", label: "Cooldown" },
+  unavailable: { icon: "error", color: "#ef4444", label: "Unavailable" },
+  unknown: { icon: "help", color: "#6b7280", label: "Unknown" },
+};
+
+export default function ModelAvailabilityBadge() {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [expanded, setExpanded] = useState(false);
+  const [clearing, setClearing] = useState(null);
+  const ref = useRef(null);
+  const notify = useNotificationStore();
+
+  const fetchStatus = useCallback(async () => {
+    try {
+      const res = await fetch("/api/models/availability");
+      if (res.ok) {
+        const json = await res.json();
+        setData(json);
+      }
+    } catch {
+      // silent fail — will retry
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    fetchStatus();
+    const interval = setInterval(fetchStatus, 30000);
+    return () => clearInterval(interval);
+  }, [fetchStatus]);
+
+  // Close popover on outside click
+  useEffect(() => {
+    const handleClick = (e) => {
+      if (ref.current && !ref.current.contains(e.target)) setExpanded(false);
+    };
+    if (expanded) document.addEventListener("mousedown", handleClick);
+    return () => document.removeEventListener("mousedown", handleClick);
+  }, [expanded]);
+
+  const handleClearCooldown = async (provider, model) => {
+    setClearing(`${provider}:${model}`);
+    try {
+      const res = await fetch("/api/models/availability", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ action: "clearCooldown", provider, model }),
+      });
+      if (res.ok) {
+        notify.success(`Cooldown cleared for ${model}`);
+        await fetchStatus();
+      } else {
+        notify.error("Failed to clear cooldown");
+      }
+    } catch {
+      notify.error("Failed to clear cooldown");
+    } finally {
+      setClearing(null);
+    }
+  };
+
+  if (loading) return null;
+
+  const models = data?.models || [];
+  const unavailableCount = data?.unavailableCount || models.filter((m) => m.status !== "available").length;
+  const isHealthy = unavailableCount === 0;
+
+  // Group unhealthy models by provider
+  const byProvider = {};
+  models.forEach((m) => {
+    if (m.status === "available") return;
+    const key = m.provider || "unknown";
+    if (!byProvider[key]) byProvider[key] = [];
+    byProvider[key].push(m);
+  });
+
+  return (
+    <div className="relative" ref={ref}>
+      {/* <button
+        onClick={() => setExpanded(!expanded)}
+        className={`inline-flex items-center gap-1.5 px-3 py-1.5 rounded-lg text-xs font-medium border transition-all ${
+          isHealthy
+            ? "bg-emerald-500/10 border-emerald-500/20 text-emerald-500 hover:bg-emerald-500/15"
+            : "bg-amber-500/10 border-amber-500/20 text-amber-500 hover:bg-amber-500/15"
+        }`}
+      >
+        <span className="material-symbols-outlined text-[14px]">
+          {isHealthy ? "verified" : "warning"}
+        </span>
+        {isHealthy
+          ? "All models operational"
+          : `${unavailableCount} model${unavailableCount !== 1 ? "s" : ""} with issues`}
+      </button> */}
+
+      {expanded && (
+        <div className="absolute top-full right-0 mt-2 w-80 bg-surface border border-border rounded-xl shadow-2xl z-50 overflow-hidden">
+          <div className="flex items-center justify-between px-4 py-3 border-b border-border bg-bg">
+            <div className="flex items-center gap-2">
+              <span
+                className="material-symbols-outlined text-[16px]"
+                style={{ color: isHealthy ? "#22c55e" : "#f59e0b" }}
+              >
+                {isHealthy ? "verified" : "warning"}
+              </span>
+              <span className="text-sm font-semibold text-text-main">Model Status</span>
+            </div>
+            <button
+              onClick={fetchStatus}
+              className="p-1 rounded-lg hover:bg-surface text-text-muted hover:text-text-main transition-colors"
+              title="Refresh"
+            >
+              <span className="material-symbols-outlined text-[14px]">refresh</span>
+            </button>
+          </div>
+
+          <div className="px-4 py-3 max-h-60 overflow-y-auto">
+            {isHealthy ? (
+              <p className="text-sm text-text-muted text-center py-2">
+                All models are responding normally.
+              </p>
+            ) : (
+              <div className="flex flex-col gap-2.5">
+                {Object.entries(byProvider).map(([provider, provModels]) => (
+                  <div key={provider}>
+                    <p className="text-xs font-semibold text-text-main mb-1.5 capitalize">{provider}</p>
+                    <div className="flex flex-col gap-1">
+                      {provModels.map((m) => {
+                        const status = STATUS_CONFIG[m.status] || STATUS_CONFIG.unknown;
+                        const isClearing = clearing === `${m.provider}:${m.model}`;
+                        return (
+                          <div
+                            key={`${m.provider}-${m.model}`}
+                            className="flex items-center justify-between px-2.5 py-1.5 rounded-lg bg-surface/30"
+                          >
+                            <div className="flex items-center gap-1.5 min-w-0">
+                              <span
+                                className="material-symbols-outlined text-[14px] shrink-0"
+                                style={{ color: status.color }}
+                              >
+                                {status.icon}
+                              </span>
+                              <span className="font-mono text-xs text-text-main truncate">{m.model}</span>
+                            </div>
+                            {m.status === "cooldown" && (
+                              <Button
+                                size="sm"
+                                variant="ghost"
+                                onClick={() => handleClearCooldown(m.provider, m.model)}
+                                disabled={isClearing}
+                                className="text-[10px] px-1.5! py-0.5! ml-2"
+                              >
+                                {isClearing ? "..." : "Clear"}
+                              </Button>
+                            )}
+                          </div>
+                        );
+                      })}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/providers/components/ModelsCard.js b/src/app/(dashboard)/dashboard/providers/components/ModelsCard.js
new file mode 100644
index 0000000..a6d9533
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/components/ModelsCard.js
@@ -0,0 +1,294 @@
+"use client";
+
+import { useState, useCallback, useEffect } from "react";
+import PropTypes from "prop-types";
+import { Card, Button, Modal } from "@/shared/components";
+import { getModelsByProviderId, getModelKind } from "@/shared/constants/models";
+import { getProviderAlias } from "@/shared/constants/providers";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+
+// ── ModelRow ───────────────────────────────────────────────────
+export function ModelRow({ model, fullModel, copied, onCopy, testStatus, isCustom, isFree, onDeleteAlias, onTest, isTesting }) {
+  const borderColor = testStatus === "ok" ? "border-green-500/40" : testStatus === "error" ? "border-red-500/40" : "border-border";
+  const iconColor = testStatus === "ok" ? "#22c55e" : testStatus === "error" ? "#ef4444" : undefined;
+
+  return (
+    <div className={`group px-3 py-2 rounded-lg border ${borderColor} hover:bg-sidebar/50`}>
+      <div className="flex items-center gap-2">
+        <span className="material-symbols-outlined text-base" style={iconColor ? { color: iconColor } : undefined}>
+          {testStatus === "ok" ? "check_circle" : testStatus === "error" ? "cancel" : "smart_toy"}
+        </span>
+        <div className="flex flex-col gap-1">
+          <code className="text-xs text-text-muted font-mono bg-sidebar px-1.5 py-0.5 rounded">{fullModel}</code>
+          {model.name && <span className="text-[9px] text-text-muted/70 italic pl-1">{model.name}</span>}
+        </div>
+        {onTest && (
+          <div className="relative group/btn">
+            <button onClick={onTest} disabled={isTesting} className={`p-0.5 hover:bg-sidebar rounded text-text-muted hover:text-primary transition-opacity ${isTesting ? "opacity-100" : "opacity-0 group-hover:opacity-100"}`}>
+              <span className="material-symbols-outlined text-sm" style={isTesting ? { animation: "spin 1s linear infinite" } : undefined}>
+                {isTesting ? "progress_activity" : "science"}
+              </span>
+            </button>
+            <span className="pointer-events-none absolute mt-1 top-5 left-1/2 -translate-x-1/2 text-[10px] text-text-muted whitespace-nowrap opacity-0 group-hover/btn:opacity-100 transition-opacity">
+              {isTesting ? "Testing..." : "Test"}
+            </span>
+          </div>
+        )}
+        <div className="relative group/btn">
+          <button onClick={() => onCopy(fullModel, `model-${model.id}`)} className="p-0.5 hover:bg-sidebar rounded text-text-muted hover:text-primary">
+            <span className="material-symbols-outlined text-sm">{copied === `model-${model.id}` ? "check" : "content_copy"}</span>
+          </button>
+          <span className="pointer-events-none absolute mt-1 top-5 left-1/2 -translate-x-1/2 text-[10px] text-text-muted whitespace-nowrap opacity-0 group-hover/btn:opacity-100 transition-opacity">
+            {copied === `model-${model.id}` ? "Copied!" : "Copy"}
+          </span>
+        </div>
+        {isFree && <span className="text-[10px] font-bold text-green-500 bg-green-500/10 px-1.5 py-0.5 rounded">FREE</span>}
+        {isCustom && (
+          <button onClick={onDeleteAlias} className="p-0.5 hover:bg-red-500/10 rounded text-text-muted hover:text-red-500 opacity-0 group-hover:opacity-100 transition-opacity ml-auto" title="Remove custom model">
+            <span className="material-symbols-outlined text-sm">close</span>
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+ModelRow.propTypes = {
+  model: PropTypes.shape({ id: PropTypes.string.isRequired }).isRequired,
+  fullModel: PropTypes.string.isRequired,
+  copied: PropTypes.string,
+  onCopy: PropTypes.func.isRequired,
+  testStatus: PropTypes.oneOf(["ok", "error"]),
+  isCustom: PropTypes.bool,
+  isFree: PropTypes.bool,
+  onDeleteAlias: PropTypes.func,
+  onTest: PropTypes.func,
+  isTesting: PropTypes.bool,
+};
+
+// ── AddCustomModelModal ────────────────────────────────────────
+function AddCustomModelModal({ isOpen, onSave, onClose }) {
+  const [modelId, setModelId] = useState("");
+
+  const handleSave = () => {
+    if (!modelId.trim()) return;
+    onSave(modelId.trim());
+    setModelId("");
+  };
+
+  return (
+    <Modal isOpen={isOpen} title="Add Custom Model" onClose={onClose}>
+      <div className="flex flex-col gap-4">
+        <div>
+          <label className="text-xs text-text-muted mb-1 block">Model ID</label>
+          <input
+            className="w-full px-3 py-2 text-sm border border-border rounded-lg bg-background focus:outline-none focus:border-primary"
+            value={modelId}
+            onChange={(e) => setModelId(e.target.value)}
+            onKeyDown={(e) => e.key === "Enter" && handleSave()}
+            placeholder="e.g. tts-1-hd"
+            autoFocus
+          />
+        </div>
+        <div className="flex gap-2">
+          <Button onClick={handleSave} fullWidth disabled={!modelId.trim()}>Add</Button>
+          <Button onClick={onClose} variant="ghost" fullWidth>Cancel</Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+AddCustomModelModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  onSave: PropTypes.func.isRequired,
+  onClose: PropTypes.func.isRequired,
+};
+
+// ── ModelsCard ─────────────────────────────────────────────────
+// Self-contained card: shows models for a provider, filtered by optional `kindFilter`.
+// kindFilter: if provided, only shows models with matching type/kinds field.
+export default function ModelsCard({ providerId, kindFilter, providerAliasOverride }) {
+  const { copied, copy } = useCopyToClipboard();
+  const [modelAliases, setModelAliases] = useState({});
+  const [customModels, setCustomModels] = useState([]);
+  const [modelTestResults, setModelTestResults] = useState({});
+  const [testingModelId, setTestingModelId] = useState(null);
+  const [testError, setTestError] = useState("");
+  const [showAddCustomModel, setShowAddCustomModel] = useState(false);
+  const [connections, setConnections] = useState([]);
+
+  const providerAlias = providerAliasOverride || getProviderAlias(providerId);
+  const effectiveType = kindFilter || "llm";
+
+  const fetchData = useCallback(async () => {
+    try {
+      const [aliasRes, connRes, customRes] = await Promise.all([
+        fetch("/api/models/alias"),
+        fetch("/api/providers", { cache: "no-store" }),
+        fetch("/api/models/custom", { cache: "no-store" }),
+      ]);
+      const aliasData = await aliasRes.json();
+      const connData = await connRes.json();
+      const customData = await customRes.json();
+      if (aliasRes.ok) setModelAliases(aliasData.aliases || {});
+      if (connRes.ok) setConnections((connData.connections || []).filter((c) => c.provider === providerId));
+      if (customRes.ok) setCustomModels(customData.models || []);
+    } catch (e) { console.log("ModelsCard fetch error:", e); }
+  }, [providerId]);
+
+  useEffect(() => { fetchData(); }, [fetchData]);
+
+  const handleSetAlias = async (modelId, alias) => {
+    const fullModel = `${providerAlias}/${modelId}`;
+    try {
+      const res = await fetch("/api/models/alias", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: fullModel, alias }),
+      });
+      if (res.ok) await fetchData();
+    } catch (e) { console.log("set alias error:", e); }
+  };
+
+  const handleDeleteAlias = async (alias) => {
+    try {
+      const res = await fetch(`/api/models/alias?alias=${encodeURIComponent(alias)}`, { method: "DELETE" });
+      if (res.ok) await fetchData();
+    } catch (e) { console.log("delete alias error:", e); }
+  };
+
+  const handleAddCustomModel = async (modelId) => {
+    try {
+      const res = await fetch("/api/models/custom", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ providerAlias, id: modelId, type: effectiveType }),
+      });
+      if (res.ok) {
+        await fetchData();
+        window.dispatchEvent(new CustomEvent("customModelChanged"));
+      }
+    } catch (e) { console.log("add custom model error:", e); }
+  };
+
+  const handleDeleteCustomModel = async (modelId) => {
+    try {
+      const params = new URLSearchParams({ providerAlias, id: modelId, type: effectiveType });
+      const res = await fetch(`/api/models/custom?${params}`, { method: "DELETE" });
+      if (res.ok) {
+        await fetchData();
+        window.dispatchEvent(new CustomEvent("customModelChanged"));
+      }
+    } catch (e) { console.log("delete custom model error:", e); }
+  };
+
+  const handleTestModel = async (modelId) => {
+    if (testingModelId) return;
+    setTestingModelId(modelId);
+    try {
+      const res = await fetch("/api/models/test", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: `${providerAlias}/${modelId}`, kind: kindFilter }),
+      });
+      const data = await res.json();
+      setModelTestResults((prev) => ({ ...prev, [modelId]: data.ok ? "ok" : "error" }));
+      setTestError(data.ok ? "" : (data.error || "Model not reachable"));
+    } catch {
+      setModelTestResults((prev) => ({ ...prev, [modelId]: "error" }));
+      setTestError("Network error");
+    } finally { setTestingModelId(null); }
+  };
+
+  // Built-in models — filter by kindFilter if provided
+  const allBuiltIn = getModelsByProviderId(providerId);
+  const builtInModels = kindFilter
+    ? allBuiltIn.filter((m) => {
+        if (m.kinds) return m.kinds.includes(kindFilter);
+        return getModelKind(m, "llm") === kindFilter;
+      })
+    : allBuiltIn;
+
+  // Custom models for this provider + kind, dedupe vs built-in
+  const myCustomModels = customModels.filter(
+    (m) => m.providerAlias === providerAlias
+      && getModelKind(m, "llm") === effectiveType
+      && !builtInModels.some((b) => b.id === m.id)
+  );
+
+  const displayModels = builtInModels;
+
+  return (
+    <>
+      <Card>
+        <div className="flex items-center justify-between mb-4">
+          <h2 className="text-lg font-semibold">Models{kindFilter ? ` — ${kindFilter.toUpperCase()}` : ""}</h2>
+        </div>
+        {testError && <p className="text-xs text-red-500 mb-3 break-words">{testError}</p>}
+
+        <div className="flex flex-wrap gap-3">
+          {displayModels.map((model) => {
+            const fullModel = `${providerAlias}/${model.id}`;
+            const existingAlias = Object.entries(modelAliases).find(([, m]) => m === fullModel)?.[0];
+            return (
+              <ModelRow
+                key={model.id}
+                model={model}
+                fullModel={`${providerAlias}/${model.id}`}
+                alias={existingAlias}
+                copied={copied}
+                onCopy={copy}
+                onSetAlias={(alias) => handleSetAlias(model.id, alias)}
+                onDeleteAlias={() => handleDeleteAlias(existingAlias)}
+                testStatus={modelTestResults[model.id]}
+                onTest={connections.length > 0 ? () => handleTestModel(model.id) : undefined}
+                isTesting={testingModelId === model.id}
+                isFree={model.isFree}
+              />
+            );
+          })}
+
+          {myCustomModels.map((model) => (
+            <ModelRow
+              key={`${model.id}-${model.type}`}
+              model={{ id: model.id, name: model.name }}
+              fullModel={`${providerAlias}/${model.id}`}
+              copied={copied}
+              onCopy={copy}
+              onSetAlias={() => {}}
+              onDeleteAlias={() => handleDeleteCustomModel(model.id)}
+              testStatus={modelTestResults[model.id]}
+              onTest={connections.length > 0 ? () => handleTestModel(model.id) : undefined}
+              isTesting={testingModelId === model.id}
+              isCustom
+            />
+          ))}
+
+          <button
+            onClick={() => setShowAddCustomModel(true)}
+            className="flex items-center gap-1.5 px-3 py-2 rounded-lg border border-dashed border-black/15 dark:border-white/15 text-xs text-text-muted hover:text-primary hover:border-primary/40 transition-colors"
+          >
+            <span className="material-symbols-outlined text-sm">add</span>
+            Add Model
+          </button>
+        </div>
+      </Card>
+
+      <AddCustomModelModal
+        isOpen={showAddCustomModel}
+        onSave={async (modelId) => {
+          await handleAddCustomModel(modelId);
+          setShowAddCustomModel(false);
+        }}
+        onClose={() => setShowAddCustomModel(false)}
+      />
+    </>
+  );
+}
+
+ModelsCard.propTypes = {
+  providerId: PropTypes.string.isRequired,
+  kindFilter: PropTypes.string, // e.g. "tts", "embedding" — filters models shown
+  providerAliasOverride: PropTypes.string, // override alias (e.g. for custom-embedding nodes using prefix)
+};
diff --git a/src/app/(dashboard)/dashboard/providers/new/page.js b/src/app/(dashboard)/dashboard/providers/new/page.js
new file mode 100644
index 0000000..57d0a7f
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/new/page.js
@@ -0,0 +1,220 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import Link from "next/link";
+import { Card, Button, Input, Select, Toggle } from "@/shared/components";
+import { AI_PROVIDERS, AUTH_METHODS } from "@/shared/constants/config";
+
+const providerOptions = Object.values(AI_PROVIDERS).map((p) => ({
+  value: p.id,
+  label: p.name,
+}));
+
+const authMethodOptions = Object.values(AUTH_METHODS).map((m) => ({
+  value: m.id,
+  label: m.name,
+}));
+
+export default function NewProviderPage() {
+  const router = useRouter();
+  const [loading, setLoading] = useState(false);
+  const [formData, setFormData] = useState({
+    provider: "",
+    authMethod: "api_key",
+    apiKey: "",
+    displayName: "",
+    isActive: true,
+  });
+  const [errors, setErrors] = useState({});
+
+  const handleChange = (field, value) => {
+    setFormData((prev) => ({ ...prev, [field]: value }));
+    if (errors[field]) {
+      setErrors((prev) => ({ ...prev, [field]: null }));
+    }
+  };
+
+  const validate = () => {
+    const newErrors = {};
+    if (!formData.provider) newErrors.provider = "Please select a provider";
+    if (formData.authMethod === "api_key" && !formData.apiKey) {
+      newErrors.apiKey = "API Key is required";
+    }
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  };
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    if (!validate()) return;
+
+    setLoading(true);
+    try {
+      const response = await fetch("/api/providers", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(formData),
+      });
+
+      if (response.ok) {
+        router.push("/dashboard/providers");
+      } else {
+        const data = await response.json();
+        setErrors({ submit: data.error || "Failed to create provider" });
+      }
+    } catch (error) {
+      setErrors({ submit: "An error occurred. Please try again." });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const selectedProvider = AI_PROVIDERS[formData.provider];
+
+  return (
+    <div className="max-w-2xl mx-auto">
+      {/* Header */}
+      <div className="mb-8">
+        <Link
+          href="/dashboard/providers"
+          className="inline-flex items-center gap-1 text-sm text-text-muted hover:text-primary transition-colors mb-4"
+        >
+          <span className="material-symbols-outlined text-lg">arrow_back</span>
+          Back to Providers
+        </Link>
+        <h1 className="text-3xl font-semibold tracking-tight">Add New Provider</h1>
+        <p className="text-text-muted mt-2">
+          Configure a new AI provider to use with your applications.
+        </p>
+      </div>
+
+      {/* Form */}
+      <Card>
+        <form onSubmit={handleSubmit} className="flex flex-col gap-6">
+          {/* Provider Selection */}
+          <Select
+            label="Provider"
+            options={providerOptions}
+            value={formData.provider}
+            onChange={(e) => handleChange("provider", e.target.value)}
+            placeholder="Select a provider"
+            error={errors.provider}
+            required
+          />
+
+          {/* Provider Info */}
+          {selectedProvider && (
+            <Card.Section className="flex items-center gap-3">
+              <div
+                className="size-10 rounded-lg flex items-center justify-center bg-bg border border-border"
+              >
+                <span
+                  className="material-symbols-outlined text-xl"
+                  style={{ color: selectedProvider.color }}
+                >
+                  {selectedProvider.icon}
+                </span>
+              </div>
+              <div>
+                <p className="font-medium">{selectedProvider.name}</p>
+                <p className="text-sm text-text-muted">
+                  Selected provider
+                </p>
+              </div>
+            </Card.Section>
+          )}
+
+          {/* Auth Method */}
+          <div className="flex flex-col gap-3">
+            <label className="text-sm font-medium">
+              Authentication Method <span className="text-red-500">*</span>
+            </label>
+            <div className="flex gap-3">
+              {authMethodOptions.map((method) => (
+                <button
+                  key={method.value}
+                  type="button"
+                  onClick={() => handleChange("authMethod", method.value)}
+                  className={`flex-1 flex items-center justify-center gap-2 p-4 rounded-lg border transition-all ${
+                    formData.authMethod === method.value
+                      ? "border-primary bg-primary/5 text-primary"
+                      : "border-border hover:border-primary/50"
+                  }`}
+                >
+                  <span className="material-symbols-outlined">
+                    {method.value === "api_key" ? "key" : "lock"}
+                  </span>
+                  <span className="font-medium">{method.label}</span>
+                </button>
+              ))}
+            </div>
+          </div>
+
+          {/* API Key Input */}
+          {formData.authMethod === "api_key" && (
+            <Input
+              label="API Key"
+              type="password"
+              placeholder="Enter your API key"
+              value={formData.apiKey}
+              onChange={(e) => handleChange("apiKey", e.target.value)}
+              error={errors.apiKey}
+              hint="Your API key will be encrypted and stored securely."
+              required
+            />
+          )}
+
+          {/* OAuth2 Button */}
+          {formData.authMethod === "oauth2" && (
+            <Card.Section>
+              <p className="text-sm text-text-muted mb-4">
+                Connect your account using OAuth2 authentication.
+              </p>
+              <Button type="button" variant="secondary" icon="link">
+                Connect with OAuth2
+              </Button>
+            </Card.Section>
+          )}
+
+          {/* Display Name */}
+          <Input
+            label="Display Name"
+            placeholder="e.g., Production API, Dev Environment"
+            value={formData.displayName}
+            onChange={(e) => handleChange("displayName", e.target.value)}
+            hint="Optional. A friendly name to identify this configuration."
+          />
+
+          {/* Active Toggle */}
+          <Toggle
+            checked={formData.isActive}
+            onChange={(checked) => handleChange("isActive", checked)}
+            label="Active"
+            description="Enable this provider for use in your applications"
+          />
+
+          {/* Error Message */}
+          {errors.submit && (
+            <div className="p-4 rounded-lg bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 text-red-600 dark:text-red-400 text-sm">
+              {errors.submit}
+            </div>
+          )}
+
+          {/* Actions */}
+          <div className="flex gap-3 pt-4 border-t border-border">
+            <Link href="/dashboard/providers" className="flex-1">
+              <Button type="button" variant="ghost" fullWidth>
+                Cancel
+              </Button>
+            </Link>
+            <Button type="submit" loading={loading} fullWidth className="flex-1">
+              Create Provider
+            </Button>
+          </div>
+        </form>
+      </Card>
+    </div>
+  );
+}
+
diff --git a/src/app/(dashboard)/dashboard/providers/page.js b/src/app/(dashboard)/dashboard/providers/page.js
new file mode 100644
index 0000000..dd134f3
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/providers/page.js
@@ -0,0 +1,966 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import PropTypes from "prop-types";
+import {
+  Card,
+  CardSkeleton,
+  Badge,
+  Button,
+  Toggle,
+} from "@/shared/components";
+import ProviderIcon from "@/shared/components/ProviderIcon";
+import { OAUTH_PROVIDERS, APIKEY_PROVIDERS } from "@/shared/constants/config";
+import {
+  FREE_PROVIDERS,
+  FREE_TIER_PROVIDERS,
+  WEB_COOKIE_PROVIDERS,
+  OPENAI_COMPATIBLE_PREFIX,
+  ANTHROPIC_COMPATIBLE_PREFIX,
+} from "@/shared/constants/providers";
+import Link from "next/link";
+import { getErrorCode, getRelativeTime } from "@/shared/utils";
+import { useNotificationStore } from "@/store/notificationStore";
+import { useHeaderSearchStore } from "@/store/headerSearchStore";
+import ModelAvailabilityBadge from "./components/ModelAvailabilityBadge";
+import AddCompatibleModal from "./components/AddCompatibleModal";
+
+function getStatusDisplay(connected, error, errorCode) {
+  const parts = [];
+  if (connected > 0) {
+    parts.push(
+      <Badge key="connected" variant="success" size="sm" dot>
+        {connected} Connected
+      </Badge>,
+    );
+  }
+  if (error > 0) {
+    const errText = errorCode
+      ? `${error} Error (${errorCode})`
+      : `${error} Error`;
+    parts.push(
+      <Badge key="error" variant="error" size="sm" dot>
+        {errText}
+      </Badge>,
+    );
+  }
+  if (parts.length === 0) {
+    return <span className="text-text-muted">No connections</span>;
+  }
+  return parts;
+}
+
+function getConnectionErrorTag(connection) {
+  if (!connection) return null;
+
+  const explicitType = connection.lastErrorType;
+  if (explicitType === "runtime_error") return "RUNTIME";
+  if (
+    explicitType === "upstream_auth_error" ||
+    explicitType === "auth_missing" ||
+    explicitType === "token_refresh_failed" ||
+    explicitType === "token_expired"
+  )
+    return "AUTH";
+  if (explicitType === "upstream_rate_limited") return "429";
+  if (explicitType === "upstream_unavailable") return "5XX";
+  if (explicitType === "network_error") return "NET";
+
+  const numericCode = Number(connection.errorCode);
+  if (Number.isFinite(numericCode) && numericCode >= 400)
+    return String(numericCode);
+
+  const fromMessage = getErrorCode(connection.lastError);
+  if (fromMessage === "401" || fromMessage === "403") return "AUTH";
+  if (fromMessage && fromMessage !== "ERR") return fromMessage;
+
+  const msg = (connection.lastError || "").toLowerCase();
+  if (
+    msg.includes("runtime") ||
+    msg.includes("not runnable") ||
+    msg.includes("not installed")
+  )
+    return "RUNTIME";
+  if (
+    msg.includes("invalid api key") ||
+    msg.includes("token invalid") ||
+    msg.includes("revoked") ||
+    msg.includes("unauthorized")
+  )
+    return "AUTH";
+
+  return "ERR";
+}
+
+const APIKEY_INITIAL_VISIBLE = 20;
+
+export default function ProvidersPage() {
+  const [connections, setConnections] = useState([]);
+  const [providerNodes, setProviderNodes] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [showAllApikey, setShowAllApikey] = useState(false);
+  const [showAddCompatibleModal, setShowAddCompatibleModal] = useState(false);
+  const [showAddAnthropicCompatibleModal, setShowAddAnthropicCompatibleModal] =
+    useState(false);
+  const [testingMode, setTestingMode] = useState(null);
+  const [testResults, setTestResults] = useState(null);
+  const notify = useNotificationStore();
+  const searchQuery = useHeaderSearchStore((s) => s.query);
+  const registerSearch = useHeaderSearchStore((s) => s.register);
+  const unregisterSearch = useHeaderSearchStore((s) => s.unregister);
+
+  useEffect(() => {
+    registerSearch("Search providers...");
+    return () => unregisterSearch();
+  }, [registerSearch, unregisterSearch]);
+
+  const matchSearch = (name) =>
+    !searchQuery.trim() ||
+    name.toLowerCase().includes(searchQuery.trim().toLowerCase());
+
+  const sortByPriority = (entries, authType) =>
+    [...entries].sort(([ka, a], [kb, b]) => {
+      const pa = a.priority ?? 999;
+      const pb = b.priority ?? 999;
+      if (pa !== pb) return pa - pb;
+      const sa = getProviderStats(ka, authType);
+      const sb = getProviderStats(kb, authType);
+      const ca = sa.connected > 0 ? 1 : 0;
+      const cb = sb.connected > 0 ? 1 : 0;
+      if (ca !== cb) return cb - ca;
+      return (a.name || "").localeCompare(b.name || "");
+    });
+
+  const sortItemsByPriority = (items, authType) =>
+    [...items].sort((a, b) => {
+      const pa = a.priority ?? 999;
+      const pb = b.priority ?? 999;
+      if (pa !== pb) return pa - pb;
+      const sa = getProviderStats(a.id, authType);
+      const sb = getProviderStats(b.id, authType);
+      const ca = sa.connected > 0 ? 1 : 0;
+      const cb = sb.connected > 0 ? 1 : 0;
+      if (ca !== cb) return cb - ca;
+      return (a.name || "").localeCompare(b.name || "");
+    });
+
+  useEffect(() => {
+    const fetchData = async () => {
+      try {
+        const [connectionsRes, nodesRes] = await Promise.all([
+          fetch("/api/providers"),
+          fetch("/api/provider-nodes"),
+        ]);
+        const connectionsData = await connectionsRes.json();
+        const nodesData = await nodesRes.json();
+        if (connectionsRes.ok)
+          setConnections(connectionsData.connections || []);
+        if (nodesRes.ok) setProviderNodes(nodesData.nodes || []);
+      } catch (error) {
+        console.log("Error fetching data:", error);
+      } finally {
+        setLoading(false);
+      }
+    };
+    fetchData();
+  }, []);
+
+  const getProviderStats = (providerId, authType) => {
+    const authTypes = Array.isArray(authType) ? authType : [authType];
+    const providerConnections = connections.filter(
+      (c) => c.provider === providerId && authTypes.includes(c.authType),
+    );
+
+    const getEffectiveStatus = (conn) => {
+      const isCooldown = Object.entries(conn).some(
+        ([k, v]) =>
+          k.startsWith("modelLock_") && v && new Date(v).getTime() > Date.now(),
+      );
+      return conn.testStatus === "unavailable" && !isCooldown
+        ? "active"
+        : conn.testStatus;
+    };
+
+    const connected = providerConnections.filter((c) => {
+      const status = getEffectiveStatus(c);
+      return status === "active" || status === "success";
+    }).length;
+
+    const errorConns = providerConnections.filter((c) => {
+      const status = getEffectiveStatus(c);
+      return (
+        status === "error" || status === "expired" || status === "unavailable"
+      );
+    });
+
+    const error = errorConns.length;
+    const total = providerConnections.length;
+    const allDisabled =
+      total > 0 && providerConnections.every((c) => c.isActive === false);
+
+    const latestError = errorConns.sort(
+      (a, b) => new Date(b.lastErrorAt || 0) - new Date(a.lastErrorAt || 0),
+    )[0];
+    const errorCode = latestError ? getConnectionErrorTag(latestError) : null;
+    const errorTime = latestError?.lastErrorAt
+      ? getRelativeTime(latestError.lastErrorAt)
+      : null;
+
+    return { connected, error, total, errorCode, errorTime, allDisabled };
+  };
+
+  // Toggle all connections for a provider on/off. authType may be a single
+  // string or an array (kiro counts oauth + api_key/apikey together).
+  const handleToggleProvider = async (providerId, authType, newActive) => {
+    const authTypes = Array.isArray(authType) ? authType : [authType];
+    const matches = (c) =>
+      c.provider === providerId && authTypes.includes(c.authType);
+    const providerConns = connections.filter(matches);
+    setConnections((prev) =>
+      prev.map((c) => (matches(c) ? { ...c, isActive: newActive } : c)),
+    );
+    await Promise.allSettled(
+      providerConns.map((c) =>
+        fetch(`/api/providers/${c.id}`, {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ isActive: newActive }),
+        }),
+      ),
+    );
+  };
+
+  const handleBatchTest = async (mode, providerId = null) => {
+    if (testingMode) return;
+    setTestingMode(mode === "provider" ? providerId : mode);
+    setTestResults(null);
+    try {
+      const res = await fetch("/api/providers/test-batch", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ mode, providerId }),
+      });
+      const data = await res.json();
+      setTestResults(data);
+      if (data.summary) {
+        const { passed, failed, total } = data.summary;
+        if (failed === 0) notify.success(`All ${total} tests passed`);
+        else notify.warning(`${passed}/${total} passed, ${failed} failed`);
+      }
+    } catch (error) {
+      setTestResults({ error: "Test request failed" });
+      notify.error("Provider test failed");
+    } finally {
+      setTestingMode(null);
+    }
+  };
+
+  const compatibleProviders = providerNodes
+    .filter((node) => node.type === "openai-compatible")
+    .map((node) => ({
+      id: node.id,
+      name: node.name || "OpenAI Compatible",
+      color: "#10A37F",
+      textIcon: "OC",
+      apiType: node.apiType,
+    }))
+    .filter((p) => matchSearch(p.name));
+
+  const anthropicCompatibleProviders = providerNodes
+    .filter((node) => node.type === "anthropic-compatible")
+    .map((node) => ({
+      id: node.id,
+      name: node.name || "Anthropic Compatible",
+      color: "#D97757",
+      textIcon: "AC",
+    }))
+    .filter((p) => matchSearch(p.name));
+
+  const oauthEntries = sortByPriority(
+    Object.entries(OAUTH_PROVIDERS).filter(([, info]) => !info.hidden && matchSearch(info.name)),
+    "oauth",
+  );
+  const freeEntries = Object.entries(FREE_PROVIDERS)
+    .filter(([, info]) => !info.hidden && matchSearch(info.name))
+    .sort(([, a], [, b]) => (b.noAuth ? 1 : 0) - (a.noAuth ? 1 : 0));
+  const freeTierEntries = sortByPriority(
+    Object.entries(FREE_TIER_PROVIDERS).filter(
+      ([, info]) =>
+        !info.hidden &&
+        matchSearch(info.name) &&
+        (info.serviceKinds ?? ["llm"]).includes("llm"),
+    ),
+    "freeTier",
+  ).sort(([, a], [, b]) => (b.noAuth ? 1 : 0) - (a.noAuth ? 1 : 0));
+  // API Key: connected providers first, then alphabetical by name
+  const apikeyEntries = Object.entries(APIKEY_PROVIDERS)
+    .filter(
+      ([, info]) =>
+        !info.hidden &&
+        (info.serviceKinds ?? ["llm"]).includes("llm") &&
+        matchSearch(info.name),
+    )
+    .sort(([ka, a], [kb, b]) => {
+      const ca = getProviderStats(ka, "apikey").total > 0 ? 0 : 1;
+      const cb = getProviderStats(kb, "apikey").total > 0 ? 0 : 1;
+      if (ca !== cb) return ca - cb;
+      return (a.name || "").localeCompare(b.name || "");
+    });
+  const isApikeySearching = !!searchQuery.trim();
+  const visibleApikeyEntries =
+    isApikeySearching || showAllApikey
+      ? apikeyEntries
+      : apikeyEntries.slice(0, APIKEY_INITIAL_VISIBLE);
+  const hiddenApikeyCount = apikeyEntries.length - APIKEY_INITIAL_VISIBLE;
+
+  if (loading) {
+    return (
+      <div className="flex flex-col gap-8">
+        <CardSkeleton />
+        <CardSkeleton />
+      </div>
+    );
+  }
+
+  const hasAnyResult =
+    oauthEntries.length > 0 ||
+    freeEntries.length > 0 ||
+    freeTierEntries.length > 0 ||
+    apikeyEntries.length > 0 ||
+    compatibleProviders.length > 0 ||
+    anthropicCompatibleProviders.length > 0;
+
+  return (
+    <div className="flex min-w-0 flex-col gap-6 px-1 sm:px-0">
+      {!hasAnyResult && (
+        <div className="text-center py-8 border border-dashed border-border rounded-xl">
+          <span className="material-symbols-outlined text-[32px] text-text-muted mb-2">
+            search_off
+          </span>
+          <p className="text-text-muted text-sm">No providers match your search</p>
+        </div>
+      )}
+
+      {/* Custom Providers (OpenAI/Anthropic Compatible) — dynamic */}
+      <div className="flex flex-col gap-4">
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <h2 className="text-lg sm:text-xl font-semibold flex items-center gap-2 leading-tight">
+            Custom Providers (OpenAI/Anthropic Compatible){" "}
+          </h2>
+          <div className="grid grid-cols-1 gap-2 sm:flex sm:w-auto">
+            <Button
+              size="sm"
+              icon="add"
+              onClick={() => setShowAddAnthropicCompatibleModal(true)}
+              className="w-full sm:w-auto"
+            >
+              Add Anthropic Compatible
+            </Button>
+            <Button
+              size="sm"
+              variant="secondary"
+              icon="add"
+              onClick={() => setShowAddCompatibleModal(true)}
+              className="w-full !bg-white !text-black hover:!bg-gray-100 sm:w-auto"
+            >
+              Add OpenAI Compatible
+            </Button>
+          </div>
+        </div>
+        {compatibleProviders.length === 0 &&
+        anthropicCompatibleProviders.length === 0 ? (
+          <div className="flex items-center justify-center gap-2 py-2 border border-dashed border-border rounded-xl text-text-muted text-sm">
+            <span className="material-symbols-outlined text-[18px]">extension</span>
+            <span>No custom providers — use buttons above to add OpenAI/Anthropic compatible endpoints</span>
+          </div>
+        ) : (
+          <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 sm:gap-4 lg:grid-cols-3 xl:grid-cols-4">
+            {[...compatibleProviders, ...anthropicCompatibleProviders].map(
+              (info) => (
+                <ApiKeyProviderCard
+                  key={info.id}
+                  providerId={info.id}
+                  provider={info}
+                  stats={getProviderStats(info.id, "apikey")}
+                  authType="compatible"
+                  onToggle={(active) =>
+                    handleToggleProvider(info.id, "apikey", active)
+                  }
+                />
+              ),
+            )}
+          </div>
+        )}
+      </div>
+
+      {/* OAuth Providers */}
+      {oauthEntries.length > 0 && (
+      <div className="flex flex-col gap-4">
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <h2 className="text-lg sm:text-xl font-semibold flex items-center gap-2 leading-tight">
+            OAuth Providers
+          </h2>
+          <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
+            <ModelAvailabilityBadge />
+            <button
+              onClick={() => handleBatchTest("oauth")}
+              disabled={!!testingMode}
+              className={`flex w-full items-center justify-center gap-1.5 rounded-lg border px-3 py-2 text-xs font-medium transition-colors sm:w-auto sm:py-1.5 ${
+                testingMode === "oauth"
+                  ? "bg-primary/20 border-primary/40 text-primary animate-pulse"
+                  : "bg-bg border-border text-text-muted hover:text-text-main hover:border-primary/40"
+              }`}
+              title="Test all OAuth connections"
+              aria-label="Test all OAuth connections"
+            >
+              <span
+                className={`material-symbols-outlined text-[14px]${testingMode === "oauth" ? " animate-spin" : ""}`}
+              >
+                play_arrow
+              </span>
+              {testingMode === "oauth" ? "Testing..." : "Test All"}
+            </button>
+          </div>
+        </div>
+        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 sm:gap-4 lg:grid-cols-3 xl:grid-cols-4">
+          {oauthEntries.map(([key, info]) => (
+            <ProviderCard
+              key={key}
+              providerId={key}
+              provider={info}
+              stats={getProviderStats(key, "oauth")}
+              authType="oauth"
+              onToggle={(active) => handleToggleProvider(key, "oauth", active)}
+            />
+          ))}
+        </div>
+      </div>
+      )}
+
+      {/* Free Tier Providers */}
+      {(freeEntries.length > 0 || freeTierEntries.length > 0) && (
+      <div className="flex flex-col gap-4">
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <h2 className="text-lg sm:text-xl font-semibold flex items-center gap-2 leading-tight">
+            Free Tier Providers
+          </h2>
+          <button
+            onClick={() => handleBatchTest("free")}
+            disabled={!!testingMode}
+            className={`flex w-full items-center justify-center gap-1.5 rounded-lg border px-3 py-2 text-xs font-medium transition-colors sm:w-auto sm:py-1.5 ${
+              testingMode === "free"
+                ? "bg-primary/20 border-primary/40 text-primary animate-pulse"
+                : "bg-bg border-border text-text-muted hover:text-text-main hover:border-primary/40"
+            }`}
+            title="Test all Free connections"
+            aria-label="Test all Free provider connections"
+          >
+            <span
+              className={`material-symbols-outlined text-[14px]${testingMode === "free" ? " animate-spin" : ""}`}
+            >
+              play_arrow
+            </span>
+            {testingMode === "free" ? "Testing..." : "Test All"}
+          </button>
+        </div>
+        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 sm:gap-4 lg:grid-cols-3 xl:grid-cols-4">
+          {freeEntries.map(([key, info]) => {
+            // Kiro accepts both OAuth and api-key connections; count/toggle both
+            // so the card total matches the provider detail page (#kiro-apikey).
+            // Kiro's headless api-key flow persists authType "api_key" (underscore),
+            // while generic apikey providers use "apikey" — include both spellings.
+            const freeAuthTypes =
+              key === "kiro" ? ["oauth", "apikey", "api_key"] : "oauth";
+            return (
+              <ProviderCard
+                key={key}
+                providerId={key}
+                provider={info}
+                stats={getProviderStats(key, freeAuthTypes)}
+                authType="free"
+                onToggle={(active) =>
+                  handleToggleProvider(key, freeAuthTypes, active)
+                }
+              />
+            );
+          })}
+          {freeTierEntries.map(([key, info]) => (
+            <ApiKeyProviderCard
+              key={key}
+              providerId={key}
+              provider={info}
+              stats={getProviderStats(key, "apikey")}
+              authType="apikey"
+              onToggle={(active) => handleToggleProvider(key, "apikey", active)}
+            />
+          ))}
+        </div>
+      </div>
+      )}
+
+      {/* API Key Providers — fixed list */}
+      {apikeyEntries.length > 0 && (
+      <div className="flex flex-col gap-4">
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <h2 className="text-lg sm:text-xl font-semibold flex items-center gap-2 leading-tight">
+            API Key Providers{" "}
+          </h2>
+          <button
+            onClick={() => handleBatchTest("apikey")}
+            disabled={!!testingMode}
+            className={`flex w-full items-center justify-center gap-1.5 rounded-lg border px-3 py-2 text-xs font-medium transition-colors sm:w-auto sm:py-1.5 ${
+              testingMode === "apikey"
+                ? "bg-primary/20 border-primary/40 text-primary animate-pulse"
+                : "bg-bg border-border text-text-muted hover:text-text-main hover:border-primary/40"
+            }`}
+            title="Test all API Key connections"
+            aria-label="Test all API Key connections"
+          >
+            <span
+              className={`material-symbols-outlined text-[14px]${testingMode === "apikey" ? " animate-spin" : ""}`}
+            >
+              play_arrow
+            </span>
+            {testingMode === "apikey" ? "Testing..." : "Test All"}
+          </button>
+        </div>
+        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 sm:gap-4 lg:grid-cols-3 xl:grid-cols-4">
+          {visibleApikeyEntries.map(([key, info]) => (
+            <ApiKeyProviderCard
+              key={key}
+              providerId={key}
+              provider={info}
+              stats={getProviderStats(key, "apikey")}
+              authType="apikey"
+              onToggle={(active) => handleToggleProvider(key, "apikey", active)}
+            />
+          ))}
+        </div>
+        {!isApikeySearching && !showAllApikey && hiddenApikeyCount > 0 && (
+          <button
+            onClick={() => setShowAllApikey(true)}
+            className="flex w-full items-center justify-center gap-1.5 rounded-lg border border-dashed border-primary/40 px-3 py-2.5 text-sm font-medium text-primary transition-colors hover:border-primary hover:bg-primary/5"
+          >
+            <span className="material-symbols-outlined text-[16px]">expand_more</span>
+            Show all {apikeyEntries.length} providers
+          </button>
+        )}
+      </div>
+      )}
+
+      {/* Web Cookie Providers — use browser subscription cookie instead of API key */}
+      {/* <div className="flex flex-col gap-4">
+        <div className="flex items-center justify-between">
+          <h2 className="text-xl font-semibold flex items-center gap-2">
+            Web Cookie Providers{" "}
+          </h2>
+        </div>
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
+          {Object.entries(WEB_COOKIE_PROVIDERS).map(([key, info]) => (
+            <ApiKeyProviderCard
+              key={key}
+              providerId={key}
+              provider={info}
+              stats={getProviderStats(key, "apikey")}
+              authType="apikey"
+              onToggle={(active) => handleToggleProvider(key, "apikey", active)}
+            />
+          ))}
+        </div>
+      </div> */}
+
+      <AddCompatibleModal
+        variant="openai"
+        isOpen={showAddCompatibleModal}
+        onClose={() => setShowAddCompatibleModal(false)}
+        onCreated={(node) => {
+          setProviderNodes((prev) => [...prev, node]);
+          setShowAddCompatibleModal(false);
+        }}
+      />
+      <AddCompatibleModal
+        variant="anthropic"
+        isOpen={showAddAnthropicCompatibleModal}
+        onClose={() => setShowAddAnthropicCompatibleModal(false)}
+        onCreated={(node) => {
+          setProviderNodes((prev) => [...prev, node]);
+          setShowAddAnthropicCompatibleModal(false);
+        }}
+      />
+
+      {/* Test Results Modal */}
+      {testResults && (
+        <div
+          className="fixed inset-0 z-50 flex items-start justify-center px-3 pt-[6vh] sm:pt-[10vh]"
+          onClick={() => setTestResults(null)}
+        >
+          <div className="absolute inset-0 bg-black/60 backdrop-blur-sm" />
+          <div
+            className="relative bg-surface border border-border rounded-xl w-full max-w-[600px] max-h-[86vh] sm:max-h-[80vh] overflow-y-auto shadow-2xl"
+            onClick={(e) => e.stopPropagation()}
+          >
+            <div className="sticky top-0 z-10 flex items-center justify-between px-5 py-3 border-b border-border bg-surface/95 backdrop-blur-sm rounded-t-xl">
+              <h3 className="font-semibold">Test Results</h3>
+              <button
+                onClick={() => setTestResults(null)}
+                className="p-1 rounded-lg hover:bg-bg text-text-muted hover:text-text-main transition-colors"
+                aria-label="Close test results"
+              >
+                <span className="material-symbols-outlined text-lg">close</span>
+              </button>
+            </div>
+            <div className="p-5">
+              <ProviderTestResultsView results={testResults} />
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function ProviderCard({ providerId, provider, stats, authType, onToggle }) {
+  const { connected, error, errorCode, errorTime, allDisabled } = stats;
+  const isNoAuth = !!provider.noAuth;
+
+  const dotColors = {
+    free: "bg-green-500",
+    oauth: "bg-blue-500",
+    apikey: "bg-amber-500",
+    compatible: "bg-orange-500",
+  };
+  const dotLabels = {
+    free: "Free",
+    oauth: "OAuth",
+    apikey: "API Key",
+    compatible: "Compatible",
+  };
+
+  return (
+    <Link href={`/dashboard/providers/${providerId}`} className="group min-w-0">
+      <Card
+        padding="xs"
+        className={`h-full hover:bg-black/[0.01] dark:hover:bg-white/[0.01] transition-colors cursor-pointer ${allDisabled ? "opacity-50" : ""}`}
+      >
+        <div className="flex min-w-0 items-center justify-between gap-3">
+          <div className="flex min-w-0 items-center gap-3">
+            <div
+              className="size-8 shrink-0 rounded-lg flex items-center justify-center"
+              style={{
+                backgroundColor: `${provider.color?.length > 7 ? provider.color : provider.color + "15"}`,
+              }}
+            >
+              <ProviderIcon
+                src={`/providers/${provider.id}.png`}
+                alt={provider.name}
+                size={30}
+                className="object-contain rounded-lg max-w-[32px] max-h-[32px]"
+                fallbackText={
+                  provider.textIcon || provider.id.slice(0, 2).toUpperCase()
+                }
+                fallbackColor={provider.color}
+              />
+            </div>
+            <div className="min-w-0">
+              <h3 className="truncate font-semibold">{provider.name}</h3>
+              <div className="flex min-w-0 items-center gap-1.5 text-xs flex-wrap">
+                {allDisabled ? (
+                  <Badge variant="default" size="sm">
+                    <span className="flex items-center gap-1">
+                      <span className="material-symbols-outlined text-[12px]">
+                        pause_circle
+                      </span>
+                      Disabled
+                    </span>
+                  </Badge>
+                ) : isNoAuth ? (
+                  <Badge variant="success" size="sm" dot>Ready</Badge>
+                ) : (
+                  <>
+                    {getStatusDisplay(connected, error, errorCode)}
+                    {errorTime && (
+                      <span className="text-text-muted">{errorTime}</span>
+                    )}
+                  </>
+                )}
+              </div>
+            </div>
+          </div>
+          <div className="flex shrink-0 items-center gap-2">
+            {stats.total > 0 && (
+              <div
+                className="opacity-100 transition-opacity sm:opacity-0 sm:group-hover:opacity-100"
+                onClick={(e) => {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  onToggle(!allDisabled ? false : true);
+                }}
+              >
+                <Toggle
+                  size="sm"
+                  checked={!allDisabled}
+                  onChange={() => {}}
+                  title={allDisabled ? "Enable provider" : "Disable provider"}
+                />
+              </div>
+            )}
+          </div>
+        </div>
+      </Card>
+    </Link>
+  );
+}
+
+ProviderCard.propTypes = {
+  providerId: PropTypes.string.isRequired,
+  provider: PropTypes.shape({
+    id: PropTypes.string.isRequired,
+    name: PropTypes.string.isRequired,
+    color: PropTypes.string,
+    textIcon: PropTypes.string,
+  }).isRequired,
+  stats: PropTypes.shape({
+    connected: PropTypes.number,
+    error: PropTypes.number,
+    errorCode: PropTypes.string,
+    errorTime: PropTypes.string,
+  }).isRequired,
+  authType: PropTypes.string,
+  onToggle: PropTypes.func,
+};
+
+function ApiKeyProviderCard({
+  providerId,
+  provider,
+  stats,
+  authType,
+  onToggle,
+}) {
+  const { connected, error, errorCode, errorTime, allDisabled } = stats;
+  const isCompatible = providerId.startsWith(OPENAI_COMPATIBLE_PREFIX);
+  const isAnthropicCompatible = providerId.startsWith(
+    ANTHROPIC_COMPATIBLE_PREFIX,
+  );
+
+  const dotColors = {
+    free: "bg-green-500",
+    oauth: "bg-blue-500",
+    apikey: "bg-amber-500",
+    compatible: "bg-orange-500",
+  };
+  const dotLabels = {
+    free: "Free",
+    oauth: "OAuth",
+    apikey: "API Key",
+    compatible: "Compatible",
+  };
+
+  const getIconPath = () => {
+    if (isCompatible)
+      return provider.apiType === "responses"
+        ? "/providers/oai-r.png"
+        : "/providers/oai-cc.png";
+    if (isAnthropicCompatible) return "/providers/anthropic-m.png";
+    return `/providers/${provider.id}.png`;
+  };
+
+  return (
+    <Link href={`/dashboard/providers/${providerId}`} className="group min-w-0">
+      <Card
+        padding="xs"
+        className={`h-full hover:bg-black/[0.01] dark:hover:bg-white/[0.01] transition-colors cursor-pointer ${allDisabled ? "opacity-50" : ""}`}
+      >
+        <div className="flex min-w-0 items-center justify-between gap-3">
+          <div className="flex min-w-0 items-center gap-3">
+            <div
+              className="size-8 shrink-0 rounded-lg flex items-center justify-center"
+              style={{
+                backgroundColor: `${provider.color?.length > 7 ? provider.color : provider.color + "15"}`,
+              }}
+            >
+              <ProviderIcon
+                src={getIconPath()}
+                alt={provider.name}
+                size={30}
+                className="object-contain rounded-lg max-w-[30px] max-h-[30px]"
+                fallbackText={
+                  provider.textIcon || provider.id.slice(0, 2).toUpperCase()
+                }
+                fallbackColor={provider.color}
+              />
+            </div>
+            <div className="min-w-0">
+              <h3 className="truncate font-semibold">{provider.name}</h3>
+              <div className="flex min-w-0 items-center gap-1.5 text-xs flex-wrap">
+                {allDisabled ? (
+                  <Badge variant="default" size="sm">
+                    <span className="flex items-center gap-1">
+                      <span className="material-symbols-outlined text-[12px]">
+                        pause_circle
+                      </span>
+                      Disabled
+                    </span>
+                  </Badge>
+                ) : (
+                  <>
+                    {getStatusDisplay(connected, error, errorCode)}
+                    {isCompatible && (
+                      <Badge variant="default" size="sm">
+                        {provider.apiType === "responses"
+                          ? "Responses"
+                          : "Chat"}
+                      </Badge>
+                    )}
+                    {isAnthropicCompatible && (
+                      <Badge variant="default" size="sm">
+                        Messages
+                      </Badge>
+                    )}
+                    {errorTime && (
+                      <span className="text-text-muted">{errorTime}</span>
+                    )}
+                  </>
+                )}
+              </div>
+            </div>
+          </div>
+          <div className="flex shrink-0 items-center gap-2">
+            {stats.total > 0 && (
+              <div
+                className="opacity-100 transition-opacity sm:opacity-0 sm:group-hover:opacity-100"
+                onClick={(e) => {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  onToggle(!allDisabled ? false : true);
+                }}
+              >
+                <Toggle
+                  size="sm"
+                  checked={!allDisabled}
+                  onChange={() => {}}
+                  title={allDisabled ? "Enable provider" : "Disable provider"}
+                />
+              </div>
+            )}
+          </div>
+        </div>
+      </Card>
+    </Link>
+  );
+}
+
+ApiKeyProviderCard.propTypes = {
+  providerId: PropTypes.string.isRequired,
+  provider: PropTypes.shape({
+    id: PropTypes.string.isRequired,
+    name: PropTypes.string.isRequired,
+    color: PropTypes.string,
+    textIcon: PropTypes.string,
+    apiType: PropTypes.string,
+  }).isRequired,
+  stats: PropTypes.shape({
+    connected: PropTypes.number,
+    error: PropTypes.number,
+    errorCode: PropTypes.string,
+    errorTime: PropTypes.string,
+  }).isRequired,
+  authType: PropTypes.string,
+  onToggle: PropTypes.func,
+};
+
+function ProviderTestResultsView({ results }) {
+  if (results.error && !results.results) {
+    return (
+      <div className="text-center py-6">
+        <span className="material-symbols-outlined text-red-500 text-[32px] mb-2 block">
+          error
+        </span>
+        <p className="text-sm text-red-400">{results.error}</p>
+      </div>
+    );
+  }
+
+  const { summary, mode } = results;
+  const items = results.results || [];
+  const modeLabel =
+    {
+      oauth: "OAuth",
+      free: "Free",
+      apikey: "API Key",
+      provider: "Provider",
+      all: "All",
+    }[mode] || mode;
+
+  return (
+    <div className="flex min-w-0 flex-col gap-3">
+      {summary && (
+        <div className="flex flex-wrap items-center gap-2 text-xs mb-1 sm:gap-3">
+          <span className="text-text-muted">{modeLabel} Test</span>
+          <span className="px-2 py-0.5 rounded bg-emerald-500/15 text-emerald-400 font-medium">
+            {summary.passed} passed
+          </span>
+          {summary.failed > 0 && (
+            <span className="px-2 py-0.5 rounded bg-red-500/15 text-red-400 font-medium">
+              {summary.failed} failed
+            </span>
+          )}
+          <span className="text-text-muted sm:ml-auto">
+            {summary.total} tested
+          </span>
+        </div>
+      )}
+      {items.map((r, i) => (
+        <div
+          key={r.connectionId || i}
+          className="flex min-w-0 flex-wrap items-center gap-2 rounded-lg bg-black/[0.03] px-3 py-2 text-xs dark:bg-white/[0.03] sm:flex-nowrap"
+        >
+          <span
+            className={`material-symbols-outlined text-[16px] ${r.valid ? "text-emerald-500" : "text-red-500"}`}
+          >
+            {r.valid ? "check_circle" : "error"}
+          </span>
+          <div className="min-w-0 flex-[1_1_160px]">
+            <span className="block truncate font-medium sm:inline">
+              {r.connectionName}
+            </span>
+            <span className="block truncate text-text-muted sm:ml-1.5 sm:inline">
+              ({r.provider})
+            </span>
+          </div>
+          {r.latencyMs !== undefined && (
+            <span className="shrink-0 text-text-muted font-mono tabular-nums">
+              {r.latencyMs}ms
+            </span>
+          )}
+          <span
+            className={`shrink-0 text-[10px] uppercase font-bold px-1.5 py-0.5 rounded ${
+              r.valid
+                ? "bg-emerald-500/15 text-emerald-400"
+                : "bg-red-500/15 text-red-400"
+            }`}
+          >
+            {r.valid ? "OK" : r.diagnosis?.type || "ERROR"}
+          </span>
+        </div>
+      ))}
+      {items.length === 0 && (
+        <div className="text-center py-4 text-text-muted text-sm">
+          No active connections found for this group.
+        </div>
+      )}
+    </div>
+  );
+}
+
+ProviderTestResultsView.propTypes = {
+  results: PropTypes.shape({
+    mode: PropTypes.string,
+    results: PropTypes.array,
+    summary: PropTypes.shape({
+      total: PropTypes.number,
+      passed: PropTypes.number,
+      failed: PropTypes.number,
+    }),
+    error: PropTypes.string,
+  }).isRequired,
+};
diff --git a/src/app/(dashboard)/dashboard/proxy-pools/page.js b/src/app/(dashboard)/dashboard/proxy-pools/page.js
new file mode 100644
index 0000000..8edf791
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/proxy-pools/page.js
@@ -0,0 +1,1063 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState, useRef } from "react";
+import { Badge, Button, Card, CardSkeleton, Input, Modal, Toggle, ConfirmModal } from "@/shared/components";
+import { useNotificationStore } from "@/store/notificationStore";
+
+function getStatusVariant(status) {
+  if (status === "active") return "success";
+  if (status === "error") return "error";
+  return "default";
+}
+
+function formatDateTime(value) {
+  if (!value) return "Never";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return "Never";
+  return date.toLocaleString();
+}
+
+function normalizeFormData(data = {}) {
+  return {
+    name: data.name || "",
+    proxyUrl: data.proxyUrl || "",
+    noProxy: data.noProxy || "",
+    isActive: data.isActive !== false,
+    strictProxy: data.strictProxy === true,
+  };
+}
+
+export default function ProxyPoolsPage() {
+  const [proxyPools, setProxyPools] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [showFormModal, setShowFormModal] = useState(false);
+  const [showBatchImportModal, setShowBatchImportModal] = useState(false);
+  const [showVercelModal, setShowVercelModal] = useState(false);
+  const [showCloudflareModal, setShowCloudflareModal] = useState(false);
+  const [showDenoModal, setShowDenoModal] = useState(false);
+  const [showRelayMenu, setShowRelayMenu] = useState(false);
+  const [editingProxyPool, setEditingProxyPool] = useState(null);
+  const [formData, setFormData] = useState(normalizeFormData());
+  const [batchImportText, setBatchImportText] = useState("");
+  const [vercelForm, setVercelForm] = useState({ vercelToken: "", projectName: "vercel-relay" });
+  const [cloudflareForm, setCloudflareForm] = useState({ accountId: "", apiToken: "", projectName: "cloudflare-relay" });
+  const [denoForm, setDenoForm] = useState({ denoToken: "", orgDomain: "", projectName: "" });
+  const [saving, setSaving] = useState(false);
+  const [importing, setImporting] = useState(false);
+  const [deploying, setDeploying] = useState(false);
+  const [testingId, setTestingId] = useState(null);
+  const [selectedIds, setSelectedIds] = useState([]);
+  const [healthChecking, setHealthChecking] = useState(false);
+  const [healthProgress, setHealthProgress] = useState({ current: 0, total: 0 });
+  const [bulkBusy, setBulkBusy] = useState(false);
+  const [confirmState, setConfirmState] = useState(null);
+  const relayMenuRef = useRef(null);
+  const notify = useNotificationStore();
+
+  useEffect(() => {
+    const handleClickOutside = (e) => {
+      if (relayMenuRef.current && !relayMenuRef.current.contains(e.target)) {
+        setShowRelayMenu(false);
+      }
+    };
+    if (showRelayMenu) {
+      document.addEventListener("mousedown", handleClickOutside);
+    }
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, [showRelayMenu]);
+
+  const fetchProxyPools = useCallback(async () => {
+    try {
+      const res = await fetch("/api/proxy-pools?includeUsage=true", { cache: "no-store" });
+      const data = await res.json();
+      if (res.ok) {
+        setProxyPools(data.proxyPools || []);
+      }
+    } catch (error) {
+      console.log("Error fetching proxy pools:", error);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    fetchProxyPools();
+  }, [fetchProxyPools]);
+
+  const resetForm = () => {
+    setEditingProxyPool(null);
+    setFormData(normalizeFormData());
+  };
+
+  const openCreateModal = () => {
+    resetForm();
+    setShowFormModal(true);
+  };
+
+  const openEditModal = (proxyPool) => {
+    setEditingProxyPool(proxyPool);
+    setFormData(normalizeFormData(proxyPool));
+    setShowFormModal(true);
+  };
+
+  const closeFormModal = () => {
+    setShowFormModal(false);
+    resetForm();
+  };
+
+  const handleSave = async () => {
+    const payload = {
+      name: formData.name.trim(),
+      proxyUrl: formData.proxyUrl.trim(),
+      noProxy: formData.noProxy.trim(),
+      isActive: formData.isActive === true,
+      strictProxy: formData.strictProxy === true,
+    };
+
+    if (!payload.name || !payload.proxyUrl) return;
+
+    setSaving(true);
+    try {
+      const isEdit = !!editingProxyPool;
+      const res = await fetch(isEdit ? `/api/proxy-pools/${editingProxyPool.id}` : "/api/proxy-pools", {
+        method: isEdit ? "PUT" : "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+
+      if (res.ok) {
+        await fetchProxyPools();
+        closeFormModal();
+        notify.success(editingProxyPool ? "Proxy pool updated" : "Proxy pool created");
+      } else {
+        const data = await res.json();
+        notify.error(data.error || "Failed to save proxy pool");
+      }
+    } catch (error) {
+      console.log("Error saving proxy pool:", error);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleDelete = async (proxyPool) => {
+    setConfirmState({
+      title: "Delete Proxy Pool",
+      message: `Delete proxy pool "${proxyPool.name}"?`,
+      onConfirm: async () => {
+        setConfirmState(null);
+        try {
+          const res = await fetch(`/api/proxy-pools/${proxyPool.id}`, { method: "DELETE" });
+          if (res.ok) {
+            setProxyPools((prev) => prev.filter((item) => item.id !== proxyPool.id));
+            notify.success("Proxy pool deleted");
+            return;
+          }
+
+          const data = await res.json();
+          if (res.status === 409) {
+            notify.warning(`Cannot delete: ${data.boundConnectionCount || 0} connection(s) are still using this pool.`);
+          } else {
+            notify.error(data.error || "Failed to delete proxy pool");
+          }
+        } catch (error) {
+          console.log("Error deleting proxy pool:", error);
+          notify.error("Failed to delete proxy pool");
+        }
+      }
+    });
+  };
+
+  const handleTest = async (proxyPoolId) => {
+    setTestingId(proxyPoolId);
+    try {
+      const res = await fetch(`/api/proxy-pools/${proxyPoolId}/test`, { method: "POST" });
+      const data = await res.json();
+
+      if (!res.ok) {
+        notify.error(data.error || "Failed to test proxy");
+        return;
+      }
+
+      await fetchProxyPools();
+      notify.success(data.ok ? "Proxy test passed" : "Proxy test failed");
+    } catch (error) {
+      console.log("Error testing proxy pool:", error);
+      notify.error("Failed to test proxy");
+    } finally {
+      setTestingId(null);
+    }
+  };
+
+  const handleToggleActive = async (pool) => {
+    const next = !pool.isActive;
+    setProxyPools((prev) => prev.map((p) => p.id === pool.id ? { ...p, isActive: next } : p));
+    try {
+      const res = await fetch(`/api/proxy-pools/${pool.id}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ isActive: next }),
+      });
+      if (!res.ok) {
+        setProxyPools((prev) => prev.map((p) => p.id === pool.id ? { ...p, isActive: pool.isActive } : p));
+        notify.error("Failed to update active state");
+      }
+    } catch (error) {
+      console.log("Error toggling active:", error);
+      setProxyPools((prev) => prev.map((p) => p.id === pool.id ? { ...p, isActive: pool.isActive } : p));
+    }
+  };
+
+  const allSelected = proxyPools.length > 0 && selectedIds.length === proxyPools.length;
+  const toggleSelect = (id) => setSelectedIds((prev) => prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id]);
+  const toggleSelectAll = () => setSelectedIds(allSelected ? [] : proxyPools.map((p) => p.id));
+  const clearSelection = () => setSelectedIds([]);
+
+  const bulkSetActive = async (isActive) => {
+    const targets = selectedIds.length > 0 ? selectedIds : proxyPools.map((p) => p.id);
+    if (targets.length === 0) return;
+    setBulkBusy(true);
+    try {
+      let ok = 0; let failed = 0;
+      for (const id of targets) {
+        try {
+          const res = await fetch(`/api/proxy-pools/${id}`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ isActive }),
+          });
+          if (res.ok) ok += 1; else failed += 1;
+        } catch { failed += 1; }
+      }
+      await fetchProxyPools();
+      notify.success(`${isActive ? "Activated" : "Deactivated"} ${ok}${failed ? `, failed ${failed}` : ""}`);
+    } finally {
+      setBulkBusy(false);
+    }
+  };
+
+  const bulkDelete = async () => {
+    if (selectedIds.length === 0) return;
+    setConfirmState({
+      title: "Delete Proxy Pools",
+      message: `Delete ${selectedIds.length} proxy pool(s)?`,
+      onConfirm: async () => {
+        setConfirmState(null);
+        setBulkBusy(true);
+        try {
+          let ok = 0; let blocked = 0; let failed = 0;
+          for (const id of selectedIds) {
+            try {
+              const res = await fetch(`/api/proxy-pools/${id}`, { method: "DELETE" });
+              if (res.ok) ok += 1;
+              else if (res.status === 409) blocked += 1;
+              else failed += 1;
+            } catch { failed += 1; }
+          }
+          await fetchProxyPools();
+          clearSelection();
+          notify.success(`Deleted ${ok}${blocked ? `, ${blocked} bound` : ""}${failed ? `, ${failed} failed` : ""}`);
+        } finally {
+          setBulkBusy(false);
+        }
+      }
+    });
+  };
+
+  const handleHealthCheck = async () => {
+    const targets = selectedIds.length > 0
+      ? proxyPools.filter((p) => selectedIds.includes(p.id))
+      : proxyPools;
+    if (targets.length === 0) return;
+    setHealthChecking(true);
+    setHealthProgress({ current: 0, total: targets.length });
+    let alive = 0; const deadIds = [];
+    let done = 0;
+    const CONCURRENCY = 10;
+    const queue = [...targets];
+
+    const worker = async () => {
+      while (queue.length > 0) {
+        const pool = queue.shift();
+        if (!pool) break;
+        try {
+          const res = await fetch(`/api/proxy-pools/${pool.id}/test`, { method: "POST" });
+          const data = await res.json();
+          if (res.ok && data.ok) alive += 1; else deadIds.push(pool.id);
+        } catch {
+          deadIds.push(pool.id);
+        } finally {
+          done += 1;
+          setHealthProgress({ current: done, total: targets.length });
+        }
+      }
+    };
+
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, targets.length) }, worker));
+    await fetchProxyPools();
+    setHealthChecking(false);
+    setHealthProgress({ current: 0, total: 0 });
+
+    if (deadIds.length > 0) {
+      setConfirmState({
+        title: "Disable Dead Proxies",
+        message: `Alive: ${alive}, Dead: ${deadIds.length}.\n\nDisable ${deadIds.length} dead proxies?`,
+        onConfirm: async () => {
+          setConfirmState(null);
+          setBulkBusy(true);
+          try {
+            for (const id of deadIds) {
+              try {
+                await fetch(`/api/proxy-pools/${id}`, {
+                  method: "PUT",
+                  headers: { "Content-Type": "application/json" },
+                  body: JSON.stringify({ isActive: false }),
+                });
+              } catch {}
+            }
+            await fetchProxyPools();
+            notify.success(`Disabled ${deadIds.length} dead proxies`);
+          } finally {
+            setBulkBusy(false);
+          }
+        }
+      });
+    } else {
+      notify.success(`Health check done. Alive: ${alive}, Dead: ${deadIds.length}`);
+    }
+  };
+
+  // Cleanup selectedIds when pools change
+  useEffect(() => {
+    setSelectedIds((prev) => prev.filter((id) => proxyPools.some((p) => p.id === id)));
+  }, [proxyPools]);
+
+  const openBatchImportModal = () => {
+    setBatchImportText("");
+    setShowBatchImportModal(true);
+  };
+
+  const closeBatchImportModal = () => {
+    if (importing) return;
+    setShowBatchImportModal(false);
+  };
+
+  const openVercelModal = () => {
+    setVercelForm({ vercelToken: "", projectName: "vercel-relay" });
+    setShowVercelModal(true);
+  };
+
+  const closeVercelModal = () => {
+    if (deploying) return;
+    setShowVercelModal(false);
+  };
+
+  const openCloudflareModal = () => {
+    setCloudflareForm({ accountId: "", apiToken: "", projectName: "cloudflare-relay" });
+    setShowCloudflareModal(true);
+  };
+
+  const closeCloudflareModal = () => {
+    if (deploying) return;
+    setShowCloudflareModal(false);
+  };
+
+  const openDenoModal = () => {
+    setDenoForm({ denoToken: "", orgDomain: "", projectName: "" });
+    setShowDenoModal(true);
+  };
+
+  const closeDenoModal = () => {
+    if (deploying) return;
+    setShowDenoModal(false);
+  };
+
+  const handleVercelDeploy = async () => {
+    if (!vercelForm.vercelToken.trim()) return;
+    setDeploying(true);
+    try {
+      const res = await fetch("/api/proxy-pools/vercel-deploy", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(vercelForm),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        await fetchProxyPools();
+        closeVercelModal();
+        notify.success(`Deployed: ${data.deployUrl}`);
+      } else {
+        notify.error(data.error || "Deploy failed");
+      }
+    } catch (error) {
+      console.log("Error deploying Vercel relay:", error);
+      notify.error("Deploy failed");
+    } finally {
+      setDeploying(false);
+    }
+  };
+
+  const handleCloudflareDeploy = async () => {
+    if (!cloudflareForm.accountId.trim() || !cloudflareForm.apiToken.trim()) return;
+    setDeploying(true);
+    try {
+      const res = await fetch("/api/proxy-pools/cloudflare-deploy", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(cloudflareForm),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        await fetchProxyPools();
+        closeCloudflareModal();
+        notify.success(`Deployed: ${data.deployUrl}`);
+      } else {
+        notify.error(data.error || "Deploy failed");
+      }
+    } catch (error) {
+      console.log("Error deploying Cloudflare relay:", error);
+      notify.error("Deploy failed");
+    } finally {
+      setDeploying(false);
+    }
+  };
+
+  const handleDenoDeploy = async () => {
+    if (!denoForm.denoToken.trim()) return;
+    setDeploying(true);
+    try {
+      const res = await fetch("/api/proxy-pools/deno-deploy", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(denoForm),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        await fetchProxyPools();
+        closeDenoModal();
+        notify.success(`Deployed: ${data.deployUrl}`);
+      } else {
+        notify.error(data.error || "Deploy failed");
+      }
+    } catch (error) {
+      console.log("Error deploying Deno relay:", error);
+      notify.error("Deploy failed");
+    } finally {
+      setDeploying(false);
+    }
+  };
+
+  const parseProxyLine = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return null;
+
+    if (trimmed.includes("://")) {
+      const parsed = new URL(trimmed);
+      const hostLabel = parsed.port ? `${parsed.hostname}:${parsed.port}` : parsed.hostname;
+      return {
+        proxyUrl: parsed.toString(),
+        name: `Imported ${hostLabel}`,
+      };
+    }
+
+    const parts = trimmed.split(":");
+    if (parts.length === 4) {
+      const [host, port, username, password] = parts;
+      if (!host || !port || !username || !password) {
+        throw new Error("Invalid host:port:user:pass format");
+      }
+
+      const proxyUrl = `http://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${host}:${port}`;
+      const parsed = new URL(proxyUrl);
+      return {
+        proxyUrl: parsed.toString(),
+        name: `Imported ${host}:${port}`,
+      };
+    }
+
+    throw new Error("Unsupported format");
+  };
+
+  const handleBatchImport = async () => {
+    const lines = batchImportText
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean);
+
+    if (lines.length === 0) {
+      notify.warning("Please paste at least one proxy line.");
+      return;
+    }
+
+    const parsedEntries = [];
+    const invalidLines = [];
+
+    lines.forEach((line, index) => {
+      try {
+        const parsed = parseProxyLine(line);
+        if (parsed) {
+          parsedEntries.push({
+            ...parsed,
+            lineNumber: index + 1,
+          });
+        }
+      } catch (error) {
+        invalidLines.push(`Line ${index + 1}: ${error.message}`);
+      }
+    });
+
+    if (invalidLines.length > 0) {
+      notify.error(`Invalid proxy format:\n${invalidLines.join("\n")}`);
+      return;
+    }
+
+    setImporting(true);
+    try {
+      const existingKeys = new Set(
+        proxyPools.map((pool) => `${(pool.proxyUrl || "").trim()}|||${(pool.noProxy || "").trim()}`)
+      );
+
+      let created = 0;
+      let skipped = 0;
+      let failed = 0;
+
+      for (const entry of parsedEntries) {
+        const dedupeKey = `${entry.proxyUrl}|||`;
+        if (existingKeys.has(dedupeKey)) {
+          skipped += 1;
+          continue;
+        }
+
+        const res = await fetch("/api/proxy-pools", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            name: entry.name,
+            proxyUrl: entry.proxyUrl,
+            noProxy: "",
+            isActive: true,
+          }),
+        });
+
+        if (res.ok) {
+          created += 1;
+          existingKeys.add(dedupeKey);
+        } else {
+          failed += 1;
+        }
+      }
+
+      await fetchProxyPools();
+      setShowBatchImportModal(false);
+      notify.success(`Batch import completed: Created ${created}, Skipped ${skipped}, Failed ${failed}`);
+    } catch (error) {
+      console.log("Error batch importing proxies:", error);
+      notify.error("Batch import failed");
+    } finally {
+      setImporting(false);
+    }
+  };
+
+  const activeCount = useMemo(
+    () => proxyPools.filter((pool) => pool.isActive === true).length,
+    [proxyPools]
+  );
+
+  if (loading) {
+    return (
+      <div className="mx-auto flex w-full max-w-5xl flex-col gap-4 px-1 sm:gap-6 sm:px-0">
+        <CardSkeleton />
+        <CardSkeleton />
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto flex w-full max-w-5xl flex-col gap-4 px-1 sm:gap-6 sm:px-0">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+        <div className="min-w-0">
+          <h1 className="text-xl font-semibold sm:text-2xl">Proxy Pools</h1>
+        </div>
+
+        <div className="grid grid-cols-1 gap-2 sm:flex sm:items-center">
+          <div className="relative" ref={relayMenuRef}>
+            <Button
+              size="sm"
+              variant="secondary"
+              icon="rocket_launch"
+              onClick={() => setShowRelayMenu(!showRelayMenu)}
+            >
+              Deploy Relay
+              <span className="material-symbols-outlined ml-1 text-[18px]">
+                {showRelayMenu ? "expand_less" : "expand_more"}
+              </span>
+            </Button>
+
+            {showRelayMenu && (
+              <div className="absolute left-0 top-full z-50 mt-1 w-48 rounded-xl border border-black/10 bg-white p-1 shadow-xl dark:border-white/10 dark:bg-zinc-900 sm:left-auto sm:right-0">
+                <button
+                  onClick={() => {
+                    openCloudflareModal();
+                    setShowRelayMenu(false);
+                  }}
+                  className="flex w-full items-center gap-2 rounded-lg px-3 py-2 text-sm text-text-main transition-colors hover:bg-black/5 dark:hover:bg-white/5"
+                >
+                  <span className="material-symbols-outlined text-[20px] text-orange-500">cloud</span>
+                  Cloudflare Relay
+                </button>
+                <button
+                  onClick={() => {
+                    openVercelModal();
+                    setShowRelayMenu(false);
+                  }}
+                  className="flex w-full items-center gap-2 rounded-lg px-3 py-2 text-sm text-text-main transition-colors hover:bg-black/5 dark:hover:bg-white/5"
+                >
+                  <span className="material-symbols-outlined text-[20px] text-blue-500">cloud_upload</span>
+                  Vercel Relay
+                </button>
+                <button
+                  onClick={() => {
+                    openDenoModal();
+                    setShowRelayMenu(false);
+                  }}
+                  className="flex w-full items-center gap-2 rounded-lg px-3 py-2 text-sm text-text-main transition-colors hover:bg-black/5 dark:hover:bg-white/5"
+                >
+                  <span className="material-symbols-outlined text-[20px] text-green-500">terminal</span>
+                  Deno Relay
+                </button>
+              </div>
+            )}
+          </div>
+
+          <Button size="sm" variant="secondary" icon="upload" onClick={openBatchImportModal}>
+            Batch Import
+          </Button>
+          <Button size="sm" icon="add" onClick={openCreateModal}>Add Proxy Pool</Button>
+        </div>
+      </div>
+
+      <Card>
+        <div className="mb-4 flex flex-wrap items-center gap-2">
+          {proxyPools.length > 0 && (
+            <label className="flex items-center gap-1.5 text-xs text-text-muted cursor-pointer">
+              <input
+                type="checkbox"
+                checked={allSelected}
+                onChange={toggleSelectAll}
+                className="size-4 rounded border-black/20 dark:border-white/20"
+              />
+              {allSelected ? "Unselect all" : "Select all"}
+            </label>
+          )}
+          <Badge variant="default">Total: {proxyPools.length}</Badge>
+          <Badge variant="success">Active: {activeCount}</Badge>
+        </div>
+
+        {(selectedIds.length > 0 || healthChecking) && (
+          <div className="mb-4 flex flex-wrap items-center gap-2 rounded-lg border border-primary/30 bg-primary/5 px-3 py-2">
+            <span className="material-symbols-outlined text-[18px] text-primary">checklist</span>
+            <span className="text-xs font-medium text-primary">
+              {selectedIds.length > 0 ? `${selectedIds.length} selected` : "All pools"}
+            </span>
+            <div className="ml-auto flex flex-wrap items-center gap-2">
+              <Button
+                size="sm"
+                icon={healthChecking ? "progress_activity" : "health_and_safety"}
+                onClick={handleHealthCheck}
+                disabled={healthChecking || bulkBusy || proxyPools.length === 0}
+              >
+                {healthChecking ? `Checking ${healthProgress.current}/${healthProgress.total}` : "Health Check"}
+              </Button>
+              {selectedIds.length > 0 && (
+                <>
+                  <Button size="sm" variant="secondary" icon="toggle_on" onClick={() => bulkSetActive(true)} disabled={bulkBusy || healthChecking}>
+                    Activate
+                  </Button>
+                  <Button size="sm" variant="secondary" icon="toggle_off" onClick={() => bulkSetActive(false)} disabled={bulkBusy || healthChecking}>
+                    Deactivate
+                  </Button>
+                  <Button size="sm" variant="secondary" icon="delete" onClick={bulkDelete} disabled={bulkBusy || healthChecking}>
+                    Delete
+                  </Button>
+                  <Button size="sm" variant="ghost" onClick={clearSelection} disabled={bulkBusy || healthChecking}>
+                    Clear
+                  </Button>
+                </>
+              )}
+            </div>
+          </div>
+        )}
+
+        {proxyPools.length === 0 ? (
+          <div className="text-center py-10">
+            <p className="text-text-main font-medium mb-1">No proxy pool entries yet</p>
+            <p className="text-sm text-text-muted mb-4">
+              Create a proxy pool entry, then assign it to connections.
+            </p>
+            <Button icon="add" onClick={openCreateModal}>Add Proxy Pool</Button>
+          </div>
+        ) : (
+          <div className="flex flex-col divide-y divide-black/[0.04] dark:divide-white/[0.05]">
+            {proxyPools.map((pool) => (
+              <div key={pool.id} className="flex flex-col gap-3 py-3 sm:flex-row sm:items-center sm:justify-between">
+                <div className="flex items-start gap-3 min-w-0 flex-1">
+                  <input
+                    type="checkbox"
+                    checked={selectedIds.includes(pool.id)}
+                    onChange={() => toggleSelect(pool.id)}
+                    className="mt-1 size-4 shrink-0 rounded border-black/20 dark:border-white/20"
+                  />
+                  <div className="min-w-0 flex-1">
+                  <div className="flex items-center gap-2 flex-wrap">
+                    <p className="min-w-0 max-w-full truncate text-sm font-medium sm:max-w-[18rem]">{pool.name}</p>
+                    <Badge variant={getStatusVariant(pool.testStatus)} size="sm" dot>
+                      {pool.testStatus || "unknown"}
+                    </Badge>
+                    <Badge variant={pool.isActive ? "success" : "default"} size="sm">
+                      {pool.isActive ? "active" : "inactive"}
+                    </Badge>
+                    {pool.type === "vercel" && (
+                      <Badge variant="default" size="sm">vercel relay</Badge>
+                    )}
+                    {pool.type === "cloudflare" && (
+                      <Badge variant="default" size="sm">cloudflare relay</Badge>
+                    )}
+                    <Badge variant="default" size="sm">
+                      {pool.boundConnectionCount || 0} bound
+                    </Badge>
+                  </div>
+                  <p className="text-xs text-text-muted truncate mt-1">{pool.proxyUrl}</p>
+                  {pool.noProxy ? (
+                    <p className="text-xs text-text-muted truncate">No proxy: {pool.noProxy}</p>
+                  ) : null}
+                  <p className="text-[11px] text-text-muted mt-1">
+                    Last tested: {formatDateTime(pool.lastTestedAt)}
+                    {pool.lastError ? ` · ${pool.lastError}` : ""}
+                  </p>
+                  </div>
+                </div>
+
+                <div className="flex items-center justify-end gap-1">
+                  <Toggle
+                    size="sm"
+                    checked={pool.isActive === true}
+                    onChange={() => handleToggleActive(pool)}
+                    title={pool.isActive ? "Disable" : "Enable"}
+                  />
+                  <button
+                    onClick={() => handleTest(pool.id)}
+                    className="p-2 rounded hover:bg-black/5 dark:hover:bg-white/5 text-text-muted hover:text-primary"
+                    title="Test proxy"
+                    disabled={testingId === pool.id}
+                  >
+                    <span
+                      className="material-symbols-outlined text-[18px]"
+                      style={testingId === pool.id ? { animation: "spin 1s linear infinite" } : undefined}
+                    >
+                      {testingId === pool.id ? "progress_activity" : "science"}
+                    </span>
+                  </button>
+                  <button
+                    onClick={() => openEditModal(pool)}
+                    className="p-2 rounded hover:bg-black/5 dark:hover:bg-white/5 text-text-muted hover:text-primary"
+                    title="Edit"
+                  >
+                    <span className="material-symbols-outlined text-[18px]">edit</span>
+                  </button>
+                  <button
+                    onClick={() => handleDelete(pool)}
+                    className="p-2 rounded hover:bg-red-500/10 text-red-500"
+                    title="Delete"
+                  >
+                    <span className="material-symbols-outlined text-[18px]">delete</span>
+                  </button>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </Card>
+
+      <Modal
+        isOpen={showBatchImportModal}
+        title="Batch Import Proxies"
+        onClose={closeBatchImportModal}
+      >
+        <div className="flex flex-col gap-4">
+          <div>
+            <label className="text-sm font-medium text-text-main mb-1 block">Paste Proxy List (One per line)</label>
+            <textarea
+              value={batchImportText}
+              onChange={(e) => setBatchImportText(e.target.value)}
+              placeholder={"http://user:pass@127.0.0.1:7897\n127.0.0.1:7897:user:pass"}
+              className="w-full min-h-[180px] py-2 px-3 text-sm text-text-main bg-white dark:bg-white/5 border border-black/10 dark:border-white/10 rounded-md focus:ring-1 focus:ring-primary/30 focus:border-primary/50 focus:outline-none transition-all"
+            />
+            <p className="text-xs text-text-muted mt-1">
+              Supported formats: protocol://user:pass@host:port, host:port:user:pass
+            </p>
+          </div>
+
+          <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+            <Button fullWidth onClick={handleBatchImport} disabled={!batchImportText.trim() || importing}>
+              {importing ? "Importing..." : "Import"}
+            </Button>
+            <Button fullWidth variant="ghost" onClick={closeBatchImportModal} disabled={importing}>
+              Cancel
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      <Modal
+        isOpen={showVercelModal}
+        title="Deploy Vercel Relay"
+        onClose={closeVercelModal}
+      >
+        <div className="flex flex-col gap-4">
+          <div className="rounded-lg bg-blue-500/5 border border-blue-500/10 p-3 flex flex-col gap-1.5">
+            <p className="text-sm text-text-main font-medium">What is Vercel Relay?</p>
+            <p className="text-xs text-text-muted">
+              Deploys an edge relay function to Vercel. All AI provider requests will be forwarded through Vercel&apos;s edge network, masking your real IP from providers.
+            </p>
+            <ul className="text-xs text-text-muted list-disc pl-4 space-y-0.5">
+              <li>Your IP is replaced by Vercel&apos;s dynamic edge IPs (hundreds of IPs across 20+ global regions)</li>
+              <li>Vercel serves millions of apps — providers can&apos;t block Vercel IPs without affecting legitimate traffic</li>
+              <li>Free tier: 100GB bandwidth/month, 500K edge invocations</li>
+              <li>Deploy multiple relays on different accounts for more IP diversity</li>
+            </ul>
+          </div>
+          <Input
+            label="Vercel API Token"
+            value={vercelForm.vercelToken}
+            onChange={(e) => setVercelForm((prev) => ({ ...prev, vercelToken: e.target.value }))}
+            placeholder="your-vercel-api-token"
+            hint={<>Token is used once for deployment and not stored. <a href="https://vercel.com/account/tokens" target="_blank" rel="noopener noreferrer" className="text-primary hover:underline">Get token →</a></>}
+            type="password"
+          />
+          <Input
+            label="Project Name"
+            value={vercelForm.projectName}
+            onChange={(e) => setVercelForm((prev) => ({ ...prev, projectName: e.target.value }))}
+            placeholder="my-relay"
+            hint="Unique name for your Vercel project. Leave empty for auto-generated name."
+          />
+          <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+            <Button
+              fullWidth
+              onClick={handleVercelDeploy}
+              disabled={!vercelForm.vercelToken.trim() || deploying}
+            >
+              {deploying ? "Deploying... (may take ~1 min)" : "Deploy"}
+            </Button>
+            <Button fullWidth variant="ghost" onClick={closeVercelModal} disabled={deploying}>
+              Cancel
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      <Modal
+        isOpen={showCloudflareModal}
+        title="Deploy Cloudflare Relay"
+        onClose={closeCloudflareModal}
+      >
+        <div className="flex flex-col gap-4">
+          <div className="rounded-lg bg-orange-500/5 border border-orange-500/10 p-3 flex flex-col gap-1.5">
+            <p className="text-sm text-text-main font-medium">What is Cloudflare Relay?</p>
+            <p className="text-xs text-text-muted">
+              Deploys a Cloudflare Worker as a proxy relay. All AI provider requests will be forwarded through Cloudflare&apos;s global edge network.
+            </p>
+            <ul className="text-xs text-text-muted list-disc pl-4 space-y-0.5">
+              <li>High performance global routing and IP masking via Cloudflare Workers</li>
+              <li>Free tier: 100,000 requests per day</li>
+              <li>Requires Cloudflare Account ID and a Workers API Token (Edit Workers permission)</li>
+            </ul>
+            <div className="mt-2 pt-2 border-t border-orange-500/10 text-xs text-text-muted">
+              <p className="font-medium text-text-main mb-1">How to generate your API Token:</p>
+              <ol className="list-decimal pl-4 space-y-0.5">
+                <li>Go to <b>My Profile</b> → <b>API Tokens</b> → <b>Create Token</b></li>
+                <li>Scroll down to <b>Custom Token</b> and click <b>Get started</b></li>
+                <li>Under <b>Permissions</b>: Account | Workers Scripts | Edit</li>
+                <li>Under <b>Account Resources</b>: Include | Account | <i>Your Account Name</i></li>
+                <li>Click <b>Continue to summary</b> → <b>Create Token</b></li>
+              </ol>
+            </div>
+          </div>
+          <Input
+            label="Account ID"
+            value={cloudflareForm.accountId}
+            onChange={(e) => setCloudflareForm((prev) => ({ ...prev, accountId: e.target.value }))}
+            placeholder="your-cloudflare-account-id"
+            hint={<>Found on the right side of the Cloudflare dashboard overview page.</>}
+          />
+          <Input
+            label="API Token"
+            value={cloudflareForm.apiToken}
+            onChange={(e) => setCloudflareForm((prev) => ({ ...prev, apiToken: e.target.value }))}
+            placeholder="your-cloudflare-api-token"
+            hint={<>Requires "Workers Scripts: Edit" permission. <a href="https://dash.cloudflare.com/profile/api-tokens" target="_blank" rel="noopener noreferrer" className="text-primary hover:underline">Get token →</a></>}
+            type="password"
+          />
+          <Input
+            label="Worker Name"
+            value={cloudflareForm.projectName}
+            onChange={(e) => setCloudflareForm((prev) => ({ ...prev, projectName: e.target.value }))}
+            placeholder="my-relay"
+            hint="Unique name for your Cloudflare Worker. Leave empty for auto-generated name."
+          />
+          <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+            <Button
+              fullWidth
+              onClick={handleCloudflareDeploy}
+              disabled={!cloudflareForm.accountId.trim() || !cloudflareForm.apiToken.trim() || deploying}
+            >
+              {deploying ? "Deploying..." : "Deploy Worker"}
+            </Button>
+            <Button fullWidth variant="ghost" onClick={closeCloudflareModal} disabled={deploying}>
+              Cancel
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      <Modal
+        isOpen={showDenoModal}
+        title="Deploy Deno Relay"
+        onClose={closeDenoModal}
+      >
+        <div className="flex flex-col gap-4">
+          <div className="rounded-lg bg-black/5 dark:bg-white/5 border border-black/10 dark:border-white/10 p-3 flex flex-col gap-1.5">
+            <p className="text-sm text-text-main font-medium">What is Deno Relay?</p>
+            <p className="text-xs text-text-muted">
+              Deploys a relay worker to Deno Deploy&apos;s global edge network. All AI provider requests are forwarded through Deno&apos;s edge, masking your real IP.
+            </p>
+            <ul className="text-xs text-text-muted list-disc pl-4 space-y-0.5">
+              <li>Deno Deploy v2 runs on a high-performance global edge network</li>
+              <li>Free tier: 1M requests & 100GiB outbound traffic per month</li>
+              <li>No per-request CPU time limits (unlike Vercel/Cloudflare)</li>
+              <li>Support up to 20 active apps & 50 custom domains</li>
+              <li>Deploy multiple relays for maximum IP diversity</li>
+            </ul>
+            <div className="mt-2 pt-2 border-t border-black/10 dark:border-white/10 text-xs text-text-muted">
+              <p className="font-medium text-text-main mb-1">How to generate API token:</p>
+              <ol className="list-decimal pl-4 space-y-0.5">
+                <li>Go to <b>console.deno.com</b></li>
+                <li>Select your <b>Organization</b> → <b>Settings</b> → <b>Organization Tokens</b></li>
+                <li>Create a <b>Organization Token</b> (prefix <b>ddo_</b>)</li>
+              </ol>
+            </div>
+          </div>
+          <Input
+            label="Deno Deploy API Token"
+            value={denoForm.denoToken}
+            onChange={(e) => setDenoForm((prev) => ({ ...prev, denoToken: e.target.value }))}
+            placeholder="ddo_xxxxxxxxxxxxxxxx"
+            hint={<>Token is used once for deployment, not stored. Found in Organization Settings.</>}
+            type="password"
+          />
+          <Input
+            label="Organization Domain"
+            value={denoForm.orgDomain}
+            onChange={(e) => setDenoForm((prev) => ({ ...prev, orgDomain: e.target.value }))}
+            placeholder="your-org.deno.net"
+            hint="Organization's default domain. Your relay URL will be in the format: https://my-relay.your-org.deno.net"
+          />
+          <Input
+            label="App Name"
+            value={denoForm.projectName}
+            onChange={(e) => setDenoForm((prev) => ({ ...prev, projectName: e.target.value }))}
+            placeholder="deno-relay"
+            hint="Unique app name. Leave empty for auto-generated name."
+          />
+          <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+            <Button
+              fullWidth
+              onClick={handleDenoDeploy}
+              disabled={!denoForm.denoToken.trim() || !denoForm.orgDomain.trim() || deploying}
+            >
+              {deploying ? "Deploying..." : "Deploy Relay"}
+            </Button>
+            <Button fullWidth variant="ghost" onClick={closeDenoModal} disabled={deploying}>
+              Cancel
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      <Modal
+        isOpen={showFormModal}
+        title={editingProxyPool ? "Edit Proxy Pool" : "Add Proxy Pool"}
+        onClose={closeFormModal}
+      >
+        <div className="flex flex-col gap-4">
+          <Input
+            label="Name"
+            value={formData.name}
+            onChange={(e) => setFormData((prev) => ({ ...prev, name: e.target.value }))}
+            placeholder="Office Proxy"
+          />
+          <Input
+            label="Proxy URL"
+            value={formData.proxyUrl}
+            onChange={(e) => setFormData((prev) => ({ ...prev, proxyUrl: e.target.value }))}
+            placeholder="http://127.0.0.1:7897"
+          />
+          <Input
+            label="No Proxy"
+            value={formData.noProxy}
+            onChange={(e) => setFormData((prev) => ({ ...prev, noProxy: e.target.value }))}
+            placeholder="localhost,127.0.0.1,.internal"
+            hint="Comma-separated hosts/domains to bypass proxy"
+          />
+
+          <div className="flex flex-col gap-3 rounded-lg border border-border/50 p-3 sm:flex-row sm:items-center sm:justify-between">
+            <div>
+              <p className="font-medium text-sm">Active</p>
+              <p className="text-xs text-text-muted">Inactive pools are ignored by runtime resolution.</p>
+            </div>
+            <Toggle
+              checked={formData.isActive === true}
+              onChange={() => setFormData((prev) => ({ ...prev, isActive: !prev.isActive }))}
+              disabled={saving}
+            />
+          </div>
+
+          <div className="flex flex-col gap-3 rounded-lg border border-border/50 p-3 sm:flex-row sm:items-center sm:justify-between">
+            <div>
+              <p className="font-medium text-sm">Strict Proxy</p>
+              <p className="text-xs text-text-muted">Fail request if proxy is unreachable instead of falling back to direct.</p>
+            </div>
+            <Toggle
+              checked={formData.strictProxy === true}
+              onChange={() => setFormData((prev) => ({ ...prev, strictProxy: !prev.strictProxy }))}
+              disabled={saving}
+            />
+          </div>
+
+          <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+            <Button
+              fullWidth
+              onClick={handleSave}
+              disabled={!formData.name.trim() || !formData.proxyUrl.trim() || saving}
+            >
+              {saving ? "Saving..." : "Save"}
+            </Button>
+            <Button fullWidth variant="ghost" onClick={closeFormModal} disabled={saving}>
+              Cancel
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      {/* Confirm Modal */}
+      <ConfirmModal
+        isOpen={!!confirmState}
+        onClose={() => setConfirmState(null)}
+        onConfirm={confirmState?.onConfirm}
+        title={confirmState?.title || "Confirm"}
+        message={confirmState?.message}
+        variant="danger"
+      />
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/pxpipe/PxpipeClient.js b/src/app/(dashboard)/dashboard/pxpipe/PxpipeClient.js
new file mode 100644
index 0000000..b3a4247
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/pxpipe/PxpipeClient.js
@@ -0,0 +1,283 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import {
+  AreaChart,
+  Area,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  ResponsiveContainer,
+} from "recharts";
+import { Card, Button } from "@/shared/components";
+
+const fmtTokens = (n) => {
+  if (n >= 1000000) return `${(n / 1000000).toFixed(2)}M`;
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}K`;
+  return String(n || 0);
+};
+
+const fmtUptime = (ms) => {
+  if (!ms || ms <= 0) return "—";
+  const m = Math.floor(ms / 60000);
+  const h = Math.floor(m / 60);
+  return h > 0 ? `${h}h${String(m % 60).padStart(2, "0")}m` : `${m}m`;
+};
+
+const WINDOW_TABS = [
+  { id: "today", label: "Today" },
+  { id: "yesterday", label: "Yesterday" },
+  { id: "last7d", label: "7 days" },
+  { id: "last30d", label: "30 days" },
+  { id: "all", label: "All time" },
+];
+
+const REASON_LABELS = {
+  applied: "Prompt exceeded threshold",
+  below_threshold: "Below size threshold",
+  not_profitable: "Compression not profitable",
+  below_min_chars: "Below minimum chars",
+  below_min_tokens: "Below minimum tokens",
+  unsupported_model: "Model not in allowlist",
+  unsupported_format: "Non-Claude request format",
+  timeout: "Compression timed out",
+  transform_error: "Transform error",
+  passthrough: "Passthrough",
+  disabled: "Disabled",
+  not_installed: "Not installed",
+};
+
+function SummaryCard({ label, value, sub, tone }) {
+  return (
+    <Card className="p-4">
+      <p className="text-xs text-text-muted uppercase tracking-wide">{label}</p>
+      <p className={`text-xl font-semibold mt-1 ${tone || ""}`}>{value}</p>
+      {sub && <p className="text-xs text-text-muted mt-0.5">{sub}</p>}
+    </Card>
+  );
+}
+
+export default function PxpipeClient() {
+  const [status, setStatus] = useState(null);
+  const [health, setHealth] = useState(null);
+  const [stats, setStats] = useState(null);
+  const [logs, setLogs] = useState(null);
+  const [windowId, setWindowId] = useState("last7d");
+  const [loading, setLoading] = useState(true);
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    try {
+      const [statusRes, statsRes, logsRes] = await Promise.all([
+        fetch("/api/pxpipe/status", { headers: { "Cache-Control": "no-store" } }),
+        fetch("/api/pxpipe/stats"),
+        fetch("/api/pxpipe/logs?limit=50"),
+      ]);
+      setStatus(await statusRes.json());
+      setStats(await statsRes.json());
+      setLogs(await logsRes.json());
+      const healthRes = await fetch("/api/pxpipe/health", { method: "POST" });
+      setHealth(await healthRes.json());
+    } catch {
+      /* sections render placeholders */
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+
+  const w = stats?.windows?.[windowId];
+  const statusLabel = !status
+    ? "—"
+    : !status.installed
+      ? "Not installed"
+      : health?.healthy
+        ? "Healthy"
+        : status.running
+          ? "Running"
+          : "Stopped";
+
+  return (
+    <div className="space-y-6 p-6">
+      <div className="flex items-center justify-between flex-wrap gap-3">
+        <h2 className="text-lg font-semibold flex items-center gap-2">
+          <span className="material-symbols-outlined text-primary">image</span>
+          PXPIPE Dashboard
+        </h2>
+        <div className="flex items-center gap-2">
+          <a href="/dashboard/token-saver" className="text-xs text-primary underline hover:opacity-80">
+            Token Saver settings
+          </a>
+          <Button size="sm" variant="ghost" onClick={refresh} disabled={loading}>
+            {loading ? "Refreshing…" : "Refresh"}
+          </Button>
+        </div>
+      </div>
+
+      <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-6 gap-3">
+        <SummaryCard
+          label="Status"
+          value={statusLabel}
+          tone={health?.healthy ? "text-success" : status?.installed ? "text-warning" : "text-text-muted"}
+          sub={status?.enabled ? "Enabled in pipeline" : "Disabled in pipeline"}
+        />
+        <SummaryCard label="Version" value={status?.version ? `v${status.version}` : "—"} sub="pxpipe-proxy" />
+        <SummaryCard label="Uptime" value={fmtUptime(status?.uptimeMs)} sub="module loaded" />
+        <SummaryCard label="Requests" value={w ? w.requests.toLocaleString() : "—"} />
+        <SummaryCard label="Compressed" value={w ? w.compressed.toLocaleString() : "—"} tone="text-success" />
+        <SummaryCard label="Bypassed" value={w ? w.bypassed.toLocaleString() : "—"} />
+      </div>
+
+      <Card className="p-4">
+        <div className="flex items-center justify-between flex-wrap gap-3 mb-4">
+          <h3 className="font-medium">Token savings (estimated)</h3>
+          <div className="flex items-center gap-1 rounded-lg border border-border bg-bg-subtle p-1">
+            {WINDOW_TABS.map((tab) => (
+              <button
+                key={tab.id}
+                onClick={() => setWindowId(tab.id)}
+                className={`px-3 py-1 rounded-md text-xs font-medium transition-colors ${
+                  windowId === tab.id
+                    ? "bg-primary text-white shadow-sm"
+                    : "text-text-muted hover:text-text hover:bg-bg-hover"
+                }`}
+              >
+                {tab.label}
+              </button>
+            ))}
+          </div>
+        </div>
+        <div className="grid grid-cols-2 md:grid-cols-4 gap-4 text-center">
+          <div>
+            <p className="text-xs text-text-muted">Original tokens</p>
+            <p className="text-lg font-semibold">{w ? fmtTokens(w.tokensBeforeEst) : "—"}</p>
+          </div>
+          <div>
+            <p className="text-xs text-text-muted">After PXPIPE</p>
+            <p className="text-lg font-semibold">{w ? fmtTokens(w.tokensAfterEst) : "—"}</p>
+          </div>
+          <div>
+            <p className="text-xs text-text-muted">Saved</p>
+            <p className="text-lg font-semibold text-success">{w ? fmtTokens(w.tokensSavedEst) : "—"}</p>
+          </div>
+          <div>
+            <p className="text-xs text-text-muted">Reduction</p>
+            <p className="text-lg font-semibold text-success">{w ? `${w.savedPct}%` : "—"}</p>
+          </div>
+        </div>
+        <p className="text-xs text-text-muted mt-3">
+          Estimates from body size before/after imaging; billed usage per request
+          (recorded on the Usage page) remains the ground truth. Images generated:{" "}
+          {w ? w.imagesGenerated.toLocaleString() : "—"} · avg compression time:{" "}
+          {w ? `${w.avgCompressionMs}ms` : "—"} · errors: {w ? w.errors : "—"}
+        </p>
+      </Card>
+
+      <Card className="p-4">
+        <h3 className="font-medium mb-3">Tokens saved — last 30 days</h3>
+        {stats?.timeline?.some((d) => d.tokensSavedEst > 0) ? (
+          <ResponsiveContainer width="100%" height={220}>
+            <AreaChart data={stats.timeline} margin={{ top: 4, right: 8, left: 0, bottom: 0 }}>
+              <defs>
+                <linearGradient id="gradPxpipe" x1="0" y1="0" x2="0" y2="1">
+                  <stop offset="5%" stopColor="#10b981" stopOpacity={0.25} />
+                  <stop offset="95%" stopColor="#10b981" stopOpacity={0} />
+                </linearGradient>
+              </defs>
+              <CartesianGrid strokeDasharray="3 3" strokeOpacity={0.2} />
+              <XAxis dataKey="date" tick={{ fontSize: 11 }} tickFormatter={(d) => d.slice(5)} />
+              <YAxis tick={{ fontSize: 11 }} tickFormatter={fmtTokens} width={48} />
+              <Tooltip formatter={(v) => [fmtTokens(v), "Tokens saved"]} labelFormatter={(d) => d} />
+              <Area type="monotone" dataKey="tokensSavedEst" stroke="#10b981" fill="url(#gradPxpipe)" strokeWidth={2} />
+            </AreaChart>
+          </ResponsiveContainer>
+        ) : (
+          <div className="h-32 flex items-center justify-center text-text-muted text-sm">
+            No savings recorded yet — enable PXPIPE in the Token Saver and route a large Claude-format request.
+          </div>
+        )}
+      </Card>
+
+      <Card className="p-4">
+        <h3 className="font-medium mb-3">History</h3>
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="text-left text-xs text-text-muted border-b border-border">
+                <th className="py-2 pr-3">Time</th>
+                <th className="py-2 pr-3">Model</th>
+                <th className="py-2 pr-3 text-right">Original</th>
+                <th className="py-2 pr-3 text-right">Compressed</th>
+                <th className="py-2 pr-3 text-right">Saved</th>
+                <th className="py-2 pr-3 text-right">%</th>
+                <th className="py-2 pr-3 text-right">Duration</th>
+                <th className="py-2">Status</th>
+              </tr>
+            </thead>
+            <tbody>
+              {(stats?.recent || []).slice(0, 50).map((ev, i) => (
+                <tr key={`${ev.ts}-${i}`} className="border-b border-border/50">
+                  <td className="py-1.5 pr-3 whitespace-nowrap text-text-muted">
+                    {new Date(ev.ts).toLocaleString()}
+                  </td>
+                  <td className="py-1.5 pr-3 font-mono text-xs">{ev.provider ? `${ev.provider}/${ev.model}` : ev.model || "—"}</td>
+                  <td className="py-1.5 pr-3 text-right font-mono text-xs">
+                    {ev.applied ? fmtTokens(ev.tokensBeforeEst) : "—"}
+                  </td>
+                  <td className="py-1.5 pr-3 text-right font-mono text-xs">
+                    {ev.applied ? fmtTokens(ev.tokensAfterEst) : "—"}
+                  </td>
+                  <td className="py-1.5 pr-3 text-right font-mono text-xs text-success">
+                    {ev.applied ? fmtTokens(ev.tokensSavedEst) : "—"}
+                  </td>
+                  <td className="py-1.5 pr-3 text-right font-mono text-xs">
+                    {ev.applied ? `${ev.savedPct}%` : "—"}
+                  </td>
+                  <td className="py-1.5 pr-3 text-right font-mono text-xs">
+                    {ev.durationMs != null ? `${ev.durationMs}ms` : "—"}
+                  </td>
+                  <td className="py-1.5">
+                    <span
+                      className={`text-xs px-2 py-0.5 rounded ${
+                        ev.applied
+                          ? "bg-success/15 text-success"
+                          : ev.reason === "transform_error" || ev.reason === "timeout"
+                            ? "bg-danger/15 text-danger"
+                            : "bg-warning/15 text-warning"
+                      }`}
+                      title={ev.detail || ""}
+                    >
+                      {ev.applied ? "Compressed" : REASON_LABELS[ev.reason] || ev.reason}
+                    </span>
+                  </td>
+                </tr>
+              ))}
+              {(!stats?.recent || stats.recent.length === 0) && (
+                <tr>
+                  <td colSpan={8} className="py-6 text-center text-text-muted text-sm">
+                    No PXPIPE activity yet
+                  </td>
+                </tr>
+              )}
+            </tbody>
+          </table>
+        </div>
+      </Card>
+
+      <Card className="p-4" id="logs">
+        <h3 className="font-medium mb-3">PXPIPE Logs</h3>
+        {logs?.installLog ? (
+          <pre className="rounded bg-black/5 dark:bg-white/5 p-3 text-xs font-mono overflow-x-auto max-h-64 overflow-y-auto whitespace-pre-wrap">
+            {logs.installLog}
+          </pre>
+        ) : (
+          <p className="text-sm text-text-muted">No install log yet.</p>
+        )}
+      </Card>
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/pxpipe/page.js b/src/app/(dashboard)/dashboard/pxpipe/page.js
new file mode 100644
index 0000000..e53a44a
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/pxpipe/page.js
@@ -0,0 +1,5 @@
+import PxpipeClient from "./PxpipeClient";
+
+export default function PxpipePage() {
+  return <PxpipeClient />;
+}
diff --git a/src/app/(dashboard)/dashboard/quota/page.js b/src/app/(dashboard)/dashboard/quota/page.js
new file mode 100644
index 0000000..ee5e7e7
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/quota/page.js
@@ -0,0 +1,11 @@
+import { Suspense } from "react";
+import { CardSkeleton } from "@/shared/components/Loading";
+import ProviderLimits from "../usage/components/ProviderLimits";
+
+export default function QuotaPage() {
+  return (
+    <Suspense fallback={<CardSkeleton />}>
+      <ProviderLimits />
+    </Suspense>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/skills/page.js b/src/app/(dashboard)/dashboard/skills/page.js
new file mode 100644
index 0000000..de3c67d
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/skills/page.js
@@ -0,0 +1,112 @@
+"use client";
+
+import { Card, Badge } from "@/shared/components";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import {
+  SKILLS,
+  SKILLS_REPO_URL,
+  getSkillRawUrl,
+  getSkillBlobUrl,
+} from "@/shared/constants/skills";
+
+function CopyButton({ value, label = "Copy link" }) {
+  const { copied, copy } = useCopyToClipboard(2000);
+  return (
+    <button
+      onClick={() => copy(value)}
+      className="px-2 py-1 rounded-md bg-primary text-white text-[11px] font-medium hover:bg-primary/90 transition-colors cursor-pointer shrink-0 inline-flex items-center gap-1"
+      title={value}
+    >
+      <span className="material-symbols-outlined text-[12px]">
+        {copied ? "check" : "content_copy"}
+      </span>
+      {copied ? "Copied!" : label}
+    </button>
+  );
+}
+
+function SkillRow({ skill }) {
+  const url = getSkillRawUrl(skill.id);
+  return (
+    <div
+      className={`flex items-start gap-3 p-4 rounded-[14px] border shadow-[var(--shadow-soft)] transition-colors ${
+        skill.isEntry
+          ? "border-brand-500/40 bg-brand-500/5"
+          : "border-border-subtle bg-surface hover:bg-surface-2"
+      }`}
+    >
+      <div
+        className={`size-9 rounded-lg flex items-center justify-center shrink-0 ${
+          skill.isEntry ? "bg-primary text-white" : "bg-primary/10 text-primary"
+        }`}
+      >
+        <span className="material-symbols-outlined text-[18px]">{skill.icon}</span>
+      </div>
+
+      <div className="min-w-0 flex-1">
+        <div className="flex items-center gap-2 flex-wrap">
+          <h3 className="font-semibold text-sm text-text-main">{skill.name}</h3>
+          {skill.isEntry && (
+            <Badge variant="primary" size="sm">START HERE</Badge>
+          )}
+          {skill.endpoint && (
+            <Badge variant="default" size="sm">
+              <code className="text-[10px]">{skill.endpoint}</code>
+            </Badge>
+          )}
+        </div>
+        <p className="text-xs text-text-muted mt-0.5">{skill.description}</p>
+        <a
+          href={getSkillBlobUrl(skill.id)}
+          target="_blank"
+          rel="noreferrer"
+          className="text-[11px] text-text-muted hover:text-primary mt-1 inline-flex items-center gap-1 break-all"
+        >
+          {url}
+          <span className="material-symbols-outlined text-[12px]">open_in_new</span>
+        </a>
+      </div>
+
+      <CopyButton value={url} />
+    </div>
+  );
+}
+
+export default function SkillsPage() {
+  return (
+    <div className="max-w-4xl mx-auto space-y-6">
+      <Card padding="md">
+        <div className="text-xs text-text-muted mb-2">Paste this to your AI:</div>
+        <div className="px-3 py-2 rounded bg-surface-2 font-mono text-[12px] text-text-main">
+          Read this skill and use it: {getSkillRawUrl("9router")}
+        </div>
+      </Card>
+
+      <div className="space-y-2">
+        {SKILLS.map((skill) => (
+          <SkillRow key={skill.id} skill={skill} />
+        ))}
+      </div>
+
+      <Card padding="md">
+        <div className="flex items-center justify-between gap-3 flex-wrap">
+          <div>
+            <h2 className="text-sm font-semibold text-text-main">More on GitHub</h2>
+            <p className="text-xs text-text-muted mt-0.5">
+              Browse source, README, and examples.
+            </p>
+          </div>
+          <a
+            href={`${SKILLS_REPO_URL}/tree/master/skills`}
+            target="_blank"
+            rel="noreferrer"
+            className="text-sm text-primary hover:underline inline-flex items-center gap-1"
+          >
+            <span className="material-symbols-outlined text-[16px]">open_in_new</span>
+            View on GitHub
+          </a>
+        </div>
+      </Card>
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/token-saver/TokenSaverClient.js b/src/app/(dashboard)/dashboard/token-saver/TokenSaverClient.js
new file mode 100644
index 0000000..4e641f3
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/token-saver/TokenSaverClient.js
@@ -0,0 +1,1015 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { Card, Button, Input, Modal, Toggle, ConfirmModal } from "@/shared/components";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import { getCurrentLocale, onLocaleChange } from "@/i18n/runtime";
+import {
+  WENYAN_LOCALES,
+  CAVEMAN_LEVELS,
+  PONYTAIL_LEVELS,
+} from "../endpoint/endpointConstants";
+
+export default function TokenSaverClient() {
+  const [rtkEnabled, setRtkEnabledState] = useState(true);
+  const [headroomEnabled, setHeadroomEnabled] = useState(false);
+  const [headroomUrl, setHeadroomUrl] = useState("http://localhost:8787");
+  const [headroomStatus, setHeadroomStatus] = useState({
+    installed: false,
+    running: false,
+    python: null,
+    loading: true,
+  });
+  const [showHeadroomInstallModal, setShowHeadroomInstallModal] =
+    useState(false);
+  const [headroomActionLoading, setHeadroomActionLoading] = useState(false);
+  const [headroomActionError, setHeadroomActionError] = useState("");
+  const [headroomExtras, setHeadroomExtras] = useState({
+    version: null,
+    extras: { code: false, ml: false },
+    available: ["code", "ml"],
+    loading: false,
+  });
+  const [pendingExtras, setPendingExtras] = useState([]);
+  const [extrasActionLoading, setExtrasActionLoading] = useState(false);
+  const [extrasActionError, setExtrasActionError] = useState("");
+  const [removingExtra, setRemovingExtra] = useState(null);
+  const [installLog, setInstallLog] = useState("");
+  const [extrasConfirm, setExtrasConfirm] = useState(null);
+  const [codeAware, setCodeAware] = useState(false);
+  const [kompress, setKompress] = useState(true);
+  const [restartingProxy, setRestartingProxy] = useState(false);
+  const logPollRef = useRef(null);
+  const [cavemanEnabled, setCavemanEnabled] = useState(false);
+  const [cavemanLevel, setCavemanLevel] = useState("full");
+  const [ponytailEnabled, setPonytailEnabled] = useState(false);
+  const [ponytailLevel, setPonytailLevel] = useState("full");
+  const [pxpipeEnabled, setPxpipeEnabled] = useState(false);
+  const [pxpipeMinChars, setPxpipeMinChars] = useState(25000);
+  const [pxpipeStatus, setPxpipeStatus] = useState({
+    installed: false,
+    installing: false,
+    running: false,
+    version: null,
+    loading: true,
+  });
+  const [pxpipeHealth, setPxpipeHealth] = useState(null);
+  const [showPxpipeModal, setShowPxpipeModal] = useState(false);
+  const [pxpipeActionLoading, setPxpipeActionLoading] = useState(false);
+  const [pxpipeActionError, setPxpipeActionError] = useState("");
+  const [locale, setLocale] = useState("en");
+
+  const { copied, copy } = useCopyToClipboard();
+
+  useEffect(() => {
+    setLocale(getCurrentLocale());
+    return onLocaleChange(() => setLocale(getCurrentLocale()));
+  }, []);
+
+  const isWenyanLocale = WENYAN_LOCALES.includes(locale);
+  const visibleCavemanLevels = isWenyanLocale
+    ? CAVEMAN_LEVELS
+    : CAVEMAN_LEVELS.filter((lvl) => !lvl.wenyan);
+
+  useEffect(() => {
+    const current = CAVEMAN_LEVELS.find((lvl) => lvl.id === cavemanLevel);
+    if (current?.wenyan && !isWenyanLocale) {
+      setCavemanLevel("ultra");
+      patchSetting({ cavemanLevel: "ultra" });
+    }
+  }, [isWenyanLocale, cavemanLevel]);
+
+  const patchSetting = async (patch) => {
+    try {
+      await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(patch),
+      });
+    } catch (error) {
+      console.log("Error updating setting:", error);
+    }
+  };
+
+  const handleRtkEnabled = async (value) => {
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ rtkEnabled: value }),
+      });
+      if (res.ok) setRtkEnabledState(value);
+    } catch (error) {
+      console.log("Error updating rtkEnabled:", error);
+    }
+  };
+
+  const handleCavemanEnabled = (value) => {
+    setCavemanEnabled(value);
+    patchSetting({ cavemanEnabled: value });
+  };
+
+  const handleHeadroomEnabled = (value) => {
+    const nextUrl = headroomUrl.trim() || "http://localhost:8787";
+    setHeadroomUrl(nextUrl);
+    setHeadroomEnabled(value);
+    patchSetting({ headroomEnabled: value, headroomUrl: nextUrl });
+  };
+
+  const handleHeadroomUrlBlur = async () => {
+    const next = headroomUrl.trim() || "http://localhost:8787";
+    setHeadroomUrl(next);
+    await patchSetting({ headroomUrl: next });
+    refreshHeadroomStatus();
+  };
+
+  const refreshHeadroomStatus = useCallback(async () => {
+    setHeadroomStatus((s) => ({ ...s, loading: true }));
+    try {
+      const res = await fetch("/api/headroom/status", {
+        headers: { "Cache-Control": "no-store" },
+      });
+      const data = await res.json();
+      setHeadroomStatus({ ...data, loading: false });
+      if (!data?.installed) {
+        setHeadroomExtras({
+          version: null,
+          extras: { code: false, ml: false },
+          available: ["code", "ml"],
+          loading: false,
+        });
+        setPendingExtras([]);
+        return;
+      }
+      try {
+        const er = await fetch("/api/headroom/extras", {
+          headers: { "Cache-Control": "no-store" },
+        });
+        if (!er.ok) throw new Error("extras status failed");
+        const ed = await er.json();
+        setHeadroomExtras((s) => ({
+          ...s,
+          version: ed.version ?? null,
+          extras: ed.extras || { code: false, ml: false },
+          available: ed.available || ["code", "ml"],
+          loading: false,
+        }));
+        setPendingExtras([]);
+      } catch {
+        setHeadroomExtras({
+          version: null,
+          extras: { code: false, ml: false },
+          available: ["code", "ml"],
+          loading: false,
+        });
+        setPendingExtras([]);
+      }
+    } catch {
+      setHeadroomStatus({
+        installed: false,
+        running: false,
+        python: null,
+        loading: false,
+      });
+      setHeadroomExtras({
+        version: null,
+        extras: { code: false, ml: false },
+        available: ["code", "ml"],
+        loading: false,
+      });
+      setPendingExtras([]);
+    }
+  }, []);
+
+  const handleHeadroomStart = useCallback(async () => {
+    setHeadroomActionError("");
+    setHeadroomActionLoading(true);
+    try {
+      const res = await fetch("/api/headroom/start", { method: "POST" });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(data.error || "Failed to start proxy");
+      await refreshHeadroomStatus();
+    } catch (e) {
+      setHeadroomActionError(e.message);
+    } finally {
+      setHeadroomActionLoading(false);
+    }
+  }, [refreshHeadroomStatus]);
+
+  const handleHeadroomStop = useCallback(async () => {
+    setHeadroomActionLoading(true);
+    try {
+      await fetch("/api/headroom/stop", { method: "POST" });
+      await refreshHeadroomStatus();
+    } finally {
+      setHeadroomActionLoading(false);
+    }
+  }, [refreshHeadroomStatus]);
+
+  const togglePendingExtra = (extra) => {
+    setPendingExtras((cur) =>
+      cur.includes(extra) ? cur.filter((e) => e !== extra) : [...cur, extra]
+    );
+  };
+
+  // Poll the install log tail while a pip install/uninstall is running.
+  const startLogPolling = useCallback(() => {
+    setInstallLog("");
+    if (logPollRef.current) clearInterval(logPollRef.current);
+    const tick = async () => {
+      try {
+        const r = await fetch("/api/headroom/extras?log=1", {
+          headers: { "Cache-Control": "no-store" },
+        });
+        const d = await r.json().catch(() => ({}));
+        if (typeof d.log === "string") setInstallLog(d.log);
+      } catch { /* ignore transient poll errors */ }
+    };
+    tick();
+    logPollRef.current = setInterval(tick, 1500);
+  }, []);
+
+  const stopLogPolling = useCallback(() => {
+    if (logPollRef.current) {
+      clearInterval(logPollRef.current);
+      logPollRef.current = null;
+    }
+  }, []);
+
+  useEffect(() => () => stopLogPolling(), [stopLogPolling]);
+
+  const installExtrasConfirmed = useCallback(async () => {
+    if (pendingExtras.length === 0) return;
+    setExtrasActionLoading(true);
+    setExtrasActionError("");
+    startLogPolling();
+    try {
+      const res = await fetch("/api/headroom/extras", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ extras: pendingExtras }),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(data.error || "Install failed");
+      setHeadroomExtras((s) => ({
+        ...s,
+        version: data.version ?? s.version,
+        extras: data.extras || s.extras,
+      }));
+      setPendingExtras([]);
+    } catch (e) {
+      setExtrasActionError(e.message);
+    } finally {
+      stopLogPolling();
+      setExtrasActionLoading(false);
+    }
+  }, [pendingExtras, startLogPolling, stopLogPolling]);
+
+  const removeExtraConfirmed = useCallback(async (extra) => {
+    setRemovingExtra(extra);
+    setExtrasActionError("");
+    startLogPolling();
+    try {
+      const res = await fetch("/api/headroom/extras", {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ extras: [extra] }),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(data.error || "Remove failed");
+      setHeadroomExtras((s) => ({
+        ...s,
+        version: data.version ?? s.version,
+        extras: data.extras || s.extras,
+      }));
+    } catch (e) {
+      setExtrasActionError(e.message);
+    } finally {
+      stopLogPolling();
+      setRemovingExtra(null);
+    }
+  }, [startLogPolling, stopLogPolling]);
+
+  const handleInstallExtras = useCallback(() => {
+    if (pendingExtras.length === 0) return;
+    // Warn about the heavy ~1GB torch download before installing [ml].
+    if (pendingExtras.includes("ml")) {
+      setExtrasConfirm({
+        title: "Install [ml]",
+        message: "[ml] downloads ~1 GB (torch + huggingface-hub). Continue?",
+        confirmText: "Install",
+        variant: "primary",
+        onConfirm: installExtrasConfirmed,
+      });
+      return;
+    }
+    installExtrasConfirmed();
+  }, [pendingExtras, installExtrasConfirmed]);
+
+  const handleRemoveExtra = useCallback((extra) => {
+    setExtrasConfirm({
+      title: `Remove [${extra}]`,
+      message: `Remove [${extra}] and its packages?`,
+      confirmText: "Remove",
+      variant: "danger",
+      onConfirm: () => removeExtraConfirmed(extra),
+    });
+  }, [removeExtraConfirmed]);
+
+  // Toggle an extra's active state (persist setting), then restart the proxy so
+  // the new --code-aware / --disable-kompress flags take effect.
+  const toggleExtraActive = useCallback(async (extra, value) => {
+    setExtrasActionError("");
+    if (extra === "code") setCodeAware(value);
+    if (extra === "ml") setKompress(value);
+    const key = extra === "code" ? "headroomCodeAware" : "headroomKompress";
+    await patchSetting({ [key]: value });
+    if (!headroomStatus.running) return;
+    setRestartingProxy(true);
+    try {
+      const res = await fetch("/api/headroom/restart", { method: "POST" });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(data.error || "Restart failed");
+      await refreshHeadroomStatus();
+    } catch (e) {
+      setExtrasActionError(e.message);
+    } finally {
+      setRestartingProxy(false);
+    }
+  }, [headroomStatus.running, refreshHeadroomStatus]);
+
+  const handleCavemanLevel = (level) => {
+    setCavemanLevel(level);
+    patchSetting({ cavemanLevel: level });
+  };
+
+  const handlePonytailEnabled = (value) => {
+    setPonytailEnabled(value);
+    patchSetting({ ponytailEnabled: value });
+  };
+
+  const handlePonytailLevel = (level) => {
+    setPonytailLevel(level);
+    patchSetting({ ponytailLevel: level });
+  };
+
+  const refreshPxpipeStatus = useCallback(async () => {
+    setPxpipeStatus((s) => ({ ...s, loading: true }));
+    try {
+      const res = await fetch("/api/pxpipe/status", {
+        headers: { "Cache-Control": "no-store" },
+      });
+      const data = await res.json();
+      setPxpipeStatus({ ...data, loading: false });
+      if (typeof data.minChars === "number") setPxpipeMinChars(data.minChars);
+    } catch {
+      setPxpipeStatus({ installed: false, installing: false, running: false, version: null, loading: false });
+    }
+  }, []);
+
+  const runPxpipeHealth = useCallback(async () => {
+    try {
+      const res = await fetch("/api/pxpipe/health", { method: "POST" });
+      setPxpipeHealth(await res.json());
+    } catch (e) {
+      setPxpipeHealth({ healthy: false, checks: [], error: e.message });
+    }
+  }, []);
+
+  const pxpipeAction = useCallback(
+    async (endpoint) => {
+      setPxpipeActionError("");
+      setPxpipeActionLoading(true);
+      try {
+        const res = await fetch(`/api/pxpipe/${endpoint}`, { method: "POST" });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) throw new Error(data.error || `PXPIPE ${endpoint} failed`);
+        await refreshPxpipeStatus();
+        await runPxpipeHealth();
+      } catch (e) {
+        setPxpipeActionError(e.message);
+      } finally {
+        setPxpipeActionLoading(false);
+      }
+    },
+    [refreshPxpipeStatus, runPxpipeHealth]
+  );
+
+  const handlePxpipeEnabled = (value) => {
+    setPxpipeEnabled(value);
+    patchSetting({ pxpipeEnabled: value });
+  };
+
+  const handlePxpipeMinCharsBlur = () => {
+    const next = Math.max(0, Number(pxpipeMinChars) || 25000);
+    setPxpipeMinChars(next);
+    patchSetting({ pxpipeMinChars: next });
+  };
+
+  useEffect(() => {
+    const loadSettings = async () => {
+      try {
+        const res = await fetch("/api/settings");
+        if (res.ok) {
+          const data = await res.json();
+          setRtkEnabledState(data.rtkEnabled !== false);
+          setHeadroomEnabled(!!data.headroomEnabled);
+          setHeadroomUrl(data.headroomUrl || "http://localhost:8787");
+          setCodeAware(data.headroomCodeAware === true);
+          setKompress(data.headroomKompress !== false);
+          setCavemanEnabled(!!data.cavemanEnabled);
+          setCavemanLevel(data.cavemanLevel || "full");
+          setPonytailEnabled(!!data.ponytailEnabled);
+          setPonytailLevel(data.ponytailLevel || "full");
+          setPxpipeEnabled(!!data.pxpipeEnabled);
+          if (typeof data.pxpipeMinChars === "number") setPxpipeMinChars(data.pxpipeMinChars);
+          refreshHeadroomStatus();
+          // PRD: run the PXPIPE health check automatically when the page opens
+          refreshPxpipeStatus().then(runPxpipeHealth);
+        }
+      } catch {}
+    };
+    loadSettings();
+  }, [refreshHeadroomStatus, refreshPxpipeStatus, runPxpipeHealth]);
+
+  const headroomRunning = !!headroomStatus.running;
+  const headroomStatusLabel = headroomStatus.loading
+    ? "Checking…"
+    : headroomRunning
+      ? "Running"
+      : headroomStatus.localUrl !== false && !headroomStatus.installed
+        ? "Not installed"
+        : headroomStatus.localUrl !== false
+          ? "Stopped"
+          : "External";
+  const headroomLocalUrl = headroomStatus.localUrl !== false;
+  const headroomCanStart = !!headroomStatus.canStart;
+  const headroomManaged =
+    headroomLocalUrl && !!headroomStatus.managedPid;
+
+  const pxpipeHealthy = pxpipeHealth?.healthy === true;
+  const pxpipeStatusLabel = pxpipeStatus.loading
+    ? "Checking…"
+    : pxpipeStatus.installing
+      ? "Installing…"
+      : !pxpipeStatus.installed
+        ? "Not installed"
+        : pxpipeHealthy
+          ? "Healthy"
+          : pxpipeStatus.running
+            ? "Running"
+            : "Stopped";
+  const pxpipeChipClass =
+    pxpipeHealthy || pxpipeStatus.running
+      ? "bg-success/15 text-success"
+      : "bg-warning/15 text-warning";
+
+  return (
+    <div className="space-y-6 p-6">
+      <Card id="rtk">
+        <div className="flex items-center justify-between mb-2">
+          <h2 className="text-lg font-semibold flex items-center gap-2">
+            <span className="material-symbols-outlined text-primary">
+              bolt
+            </span>
+            Token Saver
+          </h2>
+        </div>
+        <div className="flex items-center justify-between pt-2 pb-4 border-b border-border gap-4">
+          <div className="min-w-0 flex-1">
+            <p className="font-medium">
+              Compress tool output{" "}
+              <a
+                href="https://github.com/rtk-ai/rtk"
+                target="_blank"
+                rel="noreferrer"
+                className="text-xs font-normal text-primary underline hover:opacity-80"
+              >
+                (RTK)
+              </a>
+            </p>
+            <p className="text-sm text-text-muted">
+              git/grep/ls/tree/logs → 60-90% fewer input tokens
+            </p>
+          </div>
+          <Toggle
+            checked={rtkEnabled}
+            onChange={() => handleRtkEnabled(!rtkEnabled)}
+          />
+        </div>
+        <div className="flex items-center justify-between py-4 gap-4 flex-wrap">
+          <div className="min-w-0 flex-1">
+            <div className="flex items-center gap-3 flex-wrap">
+              <p className="font-medium">
+                Compress context{" "}
+                <a
+                  href="https://github.com/chopratejas/headroom"
+                  target="_blank"
+                  rel="noreferrer"
+                  className="text-xs font-normal text-primary underline hover:opacity-80"
+                >
+                  (Headroom)
+                </a>
+              </p>
+              <span
+                className={`text-xs px-2 py-0.5 rounded ${headroomRunning ? "bg-success/15 text-success" : "bg-warning/15 text-warning"}`}
+              >
+                {headroomStatusLabel}
+              </span>
+              <button
+                type="button"
+                onClick={() => setShowHeadroomInstallModal(true)}
+                className="text-xs text-primary underline hover:opacity-80"
+              >
+                {headroomRunning ? "Manage" : "Setup"}
+              </button>
+            </div>
+            <p className="text-sm text-text-muted mt-1">
+              Compress prompts via /v1/compress before routing to the model
+            </p>
+          </div>
+          <Toggle
+            checked={headroomEnabled && headroomRunning}
+            disabled={!headroomRunning}
+            onChange={() => handleHeadroomEnabled(!headroomEnabled)}
+          />
+        </div>
+        {headroomStatus.installed && (
+          <div className="mb-3 ml-1 pl-3 pb-4 border-l-2 border-border">
+            <div className="flex items-center gap-2 flex-wrap">
+              <span className="text-xs text-text-muted">
+                Compression extras
+                {headroomExtras.version ? ` · v${headroomExtras.version}` : ""}:
+              </span>
+              {headroomExtras.available.map((extra) => {
+                const installed = !!headroomExtras.extras[extra];
+                const pending = pendingExtras.includes(extra);
+                const extraTitle =
+                  extra === "code"
+                    ? "tree-sitter AST compression for code responses"
+                    : "Kompress-v2 HF model for prose/agentic traces (~+1GB)";
+
+                if (installed) {
+                  const active = extra === "code" ? codeAware : kompress;
+                  return (
+                    <div
+                      key={extra}
+                      className="flex items-center gap-1.5 text-xs px-2 py-1 rounded border border-success/40 bg-success/5 text-text"
+                      title={extraTitle}
+                    >
+                      <Toggle
+                        size="sm"
+                        checked={active}
+                        disabled={restartingProxy}
+                        onChange={() => toggleExtraActive(extra, !active)}
+                      />
+                      <span className="font-medium">[{extra}]</span>
+                      <button
+                        type="button"
+                        onClick={() => handleRemoveExtra(extra)}
+                        disabled={removingExtra === extra}
+                        className="ml-1 text-error underline hover:opacity-80 disabled:opacity-50"
+                        title={`Uninstall [${extra}]`}
+                      >
+                        {removingExtra === extra ? "Uninstalling…" : "Uninstall"}
+                      </button>
+                    </div>
+                  );
+                }
+
+                return (
+                  <label
+                    key={extra}
+                    className={`flex items-center gap-1.5 text-xs px-2 py-1 rounded border cursor-pointer transition-colors ${
+                      pending
+                        ? "border-primary bg-primary/10 text-primary"
+                        : "border-border text-text-muted hover:bg-surface-2"
+                    }`}
+                    title={extraTitle}
+                  >
+                    <input
+                      type="checkbox"
+                      className="w-3 h-3"
+                      checked={pending}
+                      onChange={() => togglePendingExtra(extra)}
+                    />
+                    <span className="font-medium">[{extra}]</span>
+                    <span className="opacity-70">not installed</span>
+                  </label>
+                );
+              })}
+              {pendingExtras.length > 0 && (
+                <button
+                  onClick={handleInstallExtras}
+                  disabled={extrasActionLoading}
+                  className="text-xs px-2.5 py-1 rounded bg-primary text-white hover:opacity-90 disabled:opacity-50"
+                >
+                  {extrasActionLoading
+                    ? "Installing…"
+                    : `Install [proxy,${pendingExtras.join(",")}]`}
+                </button>
+              )}
+            </div>
+            {extrasActionError && (
+              <p className="text-xs text-error mt-1">{extrasActionError}</p>
+            )}
+            {restartingProxy && (
+              <p className="text-xs text-text-muted mt-1">Restarting proxy…</p>
+            )}
+            {(extrasActionLoading || removingExtra) && installLog && (
+              <pre className="mt-2 max-h-32 overflow-auto rounded bg-surface-2 p-2 text-[10px] leading-tight text-text-muted whitespace-pre-wrap">
+                {installLog}
+              </pre>
+            )}
+            <p className="text-xs text-text-muted mt-1">
+              Installing adds the package; use <code>on</code>/<code>off</code>{" "}
+              to activate it (restarts the proxy). Default install is{" "}
+              <code>[proxy]</code> only (SmartCrusher for JSON). Adding{" "}
+              <code>[code]</code> enables AST compression
+              (Python/JS/TS/Go/Rust/Java/C/C++/Perl). Adding <code>[ml]</code>{" "}
+              enables the Kompress-v2 HF model for prose/agentic traces but
+              adds ~1 GB (torch + huggingface-hub).
+            </p>
+          </div>
+        )}
+        <div className="flex items-center justify-between pt-4 border-t border-border gap-4 flex-wrap">
+          <div className="min-w-0 flex-1">
+            <p className="font-medium">
+              Compress LLM output{" "}
+              <a
+                href="https://github.com/JuliusBrussee/caveman"
+                target="_blank"
+                rel="noreferrer"
+                className="text-xs font-normal text-primary underline hover:opacity-80"
+              >
+                (Caveman)
+              </a>
+            </p>
+            <p className="text-sm text-text-muted">
+              Terse-style system prompt → ~65% fewer output tokens (up to 87%)
+            </p>
+          </div>
+          <div className="flex items-center gap-3 shrink-0">
+            {cavemanEnabled && (
+              <div className="flex flex-col items-end gap-1">
+                <div className="flex items-center gap-1.5">
+                  {visibleCavemanLevels.map((lvl) => (
+                    <button
+                      key={lvl.id}
+                      onClick={() => handleCavemanLevel(lvl.id)}
+                      className={`px-3 py-1.5 rounded text-xs font-medium border transition-colors ${
+                        cavemanLevel === lvl.id
+                          ? "bg-primary text-white border-primary"
+                          : "bg-transparent border-border text-text-muted hover:bg-surface-2"
+                      }`}
+                      title={lvl.desc}
+                    >
+                      {lvl.label}
+                    </button>
+                  ))}
+                </div>
+                <p className="text-xs text-primary">
+                  {
+                    CAVEMAN_LEVELS.find((lvl) => lvl.id === cavemanLevel)
+                      ?.desc
+                  }
+                </p>
+              </div>
+            )}
+            <Toggle
+              checked={cavemanEnabled}
+              onChange={() => handleCavemanEnabled(!cavemanEnabled)}
+            />
+          </div>
+        </div>
+        <div className="flex items-center justify-between pt-4 mt-4 border-t border-border gap-4 flex-wrap">
+          <div className="min-w-0 flex-1">
+            <p className="font-medium">
+              Lazy senior dev{" "}
+              <a
+                href="https://github.com/DietrichGebert/ponytail"
+                target="_blank"
+                rel="noreferrer"
+                className="text-xs font-normal text-primary underline hover:opacity-80"
+              >
+                (Ponytail)
+              </a>
+            </p>
+            <p className="text-sm text-text-muted">
+              Bias the model toward minimal code: YAGNI, reuse stdlib,
+              deletion over addition
+            </p>
+          </div>
+          <div className="flex items-center gap-3 shrink-0">
+            {ponytailEnabled && (
+              <div className="flex flex-col items-end gap-1">
+                <div className="flex items-center gap-1.5">
+                  {PONYTAIL_LEVELS.map((lvl) => (
+                    <button
+                      key={lvl.id}
+                      onClick={() => handlePonytailLevel(lvl.id)}
+                      className={`px-3 py-1.5 rounded text-xs font-medium border transition-colors ${
+                        ponytailLevel === lvl.id
+                          ? "bg-primary text-white border-primary"
+                          : "bg-transparent border-border text-text-muted hover:bg-surface-2"
+                      }`}
+                      title={lvl.desc}
+                    >
+                      {lvl.label}
+                    </button>
+                  ))}
+                </div>
+                <p className="text-xs text-primary">
+                  {
+                    PONYTAIL_LEVELS.find((lvl) => lvl.id === ponytailLevel)
+                      ?.desc
+                  }
+                </p>
+              </div>
+            )}
+            <Toggle
+              checked={ponytailEnabled}
+              onChange={() => handlePonytailEnabled(!ponytailEnabled)}
+            />
+          </div>
+        </div>
+        {/* PXPIPE hidden from UI — experimental, not exposed to users yet */}
+        {false && (
+        <div className="flex items-center justify-between pt-4 mt-4 border-t border-border gap-4 flex-wrap">
+          <div className="min-w-0 flex-1">
+            <div className="flex items-center gap-3 flex-wrap">
+              <p className="font-medium">
+                Compress prompts as images{" "}
+                <a
+                  href="https://github.com/teamchong/pxpipe"
+                  target="_blank"
+                  rel="noreferrer"
+                  className="text-xs font-normal text-primary underline hover:opacity-80"
+                >
+                  (PXPIPE)
+                </a>
+              </p>
+              <span className={`text-xs px-2 py-0.5 rounded ${pxpipeChipClass}`}>
+                {pxpipeStatusLabel}
+              </span>
+              <button
+                type="button"
+                onClick={() => setShowPxpipeModal(true)}
+                className="text-xs text-primary underline hover:opacity-80"
+              >
+                {pxpipeStatus.installed ? "Manage" : "Setup"}
+              </button>
+              <a
+                href="/dashboard/pxpipe"
+                className="text-xs text-primary underline hover:opacity-80"
+              >
+                Dashboard
+              </a>
+            </div>
+            <p className="text-sm text-text-muted mt-1">
+              Transforms large textual context into optimized images before
+              sending to the LLM. Ideal for huge prompts, tool outputs and long
+              conversations.
+            </p>
+          </div>
+          <Toggle
+            checked={pxpipeEnabled}
+            disabled={!pxpipeStatus.installed}
+            onChange={() => handlePxpipeEnabled(!pxpipeEnabled)}
+          />
+        </div>
+        )}
+      </Card>
+
+      <Modal
+        isOpen={showHeadroomInstallModal}
+        title={headroomRunning ? "Headroom" : "Setup Headroom"}
+        onClose={() => setShowHeadroomInstallModal(false)}
+      >
+        <div className="flex flex-col gap-4">
+          <div className="flex items-center justify-between text-sm">
+            <span>Status</span>
+            <span
+              className={headroomRunning ? "text-success" : "text-warning"}
+            >
+              {headroomStatusLabel}
+            </span>
+          </div>
+          {headroomRunning && (
+            <a
+              href="/api/headroom/proxy/dashboard"
+              target="_blank"
+              rel="noreferrer"
+              className="w-full rounded border border-border px-4 py-2 text-center text-sm hover:bg-surface-2"
+            >
+              Open Headroom Dashboard
+            </a>
+          )}
+          <div className="flex flex-col gap-1">
+            <p className="text-sm font-medium">Proxy URL</p>
+            <Input
+              value={headroomUrl}
+              onChange={(e) => setHeadroomUrl(e.target.value)}
+              onBlur={handleHeadroomUrlBlur}
+              placeholder="http://localhost:8787"
+              className="font-mono text-sm"
+            />
+            <p className="text-xs text-text-muted">
+              Use a local proxy for Start/Stop, or an external Docker sidecar
+              like http://headroom:8787.
+            </p>
+          </div>
+          {headroomManaged ? (
+            <Button
+              onClick={handleHeadroomStop}
+              variant="ghost"
+              fullWidth
+              disabled={headroomActionLoading}
+            >
+              {headroomActionLoading ? "Stopping…" : "Stop Headroom"}
+            </Button>
+          ) : headroomRunning ? (
+            <p className="text-sm text-success">
+              Headroom proxy is reachable. You can enable the token saver.
+            </p>
+          ) : headroomCanStart ? (
+            <Button
+              onClick={handleHeadroomStart}
+              fullWidth
+              disabled={headroomActionLoading}
+            >
+              {headroomActionLoading ? "Starting…" : "Start Headroom"}
+            </Button>
+          ) : !headroomLocalUrl ? (
+            <p className="text-sm text-warning">
+              Start Headroom separately at the configured URL, then recheck.
+            </p>
+          ) : !headroomStatus.python ? (
+            <p className="text-sm text-warning">
+              Python ≥ 3.10 required for local managed mode. Install Python
+              first, or use an external proxy URL.
+            </p>
+          ) : (
+            <div className="flex flex-col gap-1">
+              <p className="text-sm font-medium">Install then click Start:</p>
+              <div className="flex items-center gap-2">
+                <pre className="flex-1 rounded bg-black/5 dark:bg-white/5 p-2 text-xs font-mono overflow-x-auto">
+                  {`pip install "headroom-ai[proxy]"`}
+                </pre>
+                <Button
+                  size="sm"
+                  variant="ghost"
+                  onClick={() =>
+                    copy(`pip install "headroom-ai[proxy]"`)
+                  }
+                >
+                  {copied ? "Copied" : "Copy"}
+                </Button>
+              </div>
+            </div>
+          )}
+          {headroomActionError && (
+            <p className="text-sm text-warning">{headroomActionError}</p>
+          )}
+          <div className="flex gap-2">
+            <Button
+              onClick={() => refreshHeadroomStatus()}
+              variant="ghost"
+              fullWidth
+            >
+              Recheck
+            </Button>
+            <Button
+              onClick={() => setShowHeadroomInstallModal(false)}
+              fullWidth
+            >
+              Done
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      <Modal
+        isOpen={false}
+        title={pxpipeStatus.installed ? "PXPIPE" : "Setup PXPIPE"}
+        onClose={() => setShowPxpipeModal(false)}
+      >
+        <div className="flex flex-col gap-4">
+          <p className="text-sm text-text-muted">
+            Compress prompts using multimodal encoding. Runs in-process — no
+            extra server or environment variables required.
+          </p>
+          <div className="flex items-center justify-between text-sm">
+            <span>Status</span>
+            <span className={pxpipeHealthy || pxpipeStatus.running ? "text-success" : "text-warning"}>
+              {pxpipeStatusLabel}
+              {pxpipeStatus.version ? ` · v${pxpipeStatus.version}` : ""}
+            </span>
+          </div>
+          {pxpipeHealth?.checks?.length > 0 && (
+            <div className="flex flex-col gap-1 rounded border border-border p-3">
+              <p className="text-sm font-medium mb-1">Health check</p>
+              {pxpipeHealth.checks.map((check) => (
+                <div key={check.id} className="flex items-center justify-between text-xs">
+                  <span className={check.ok ? "text-success" : "text-warning"}>
+                    {check.ok ? "●" : "○"} {check.label}
+                  </span>
+                  {check.detail && (
+                    <span className="text-text-muted font-mono truncate max-w-[50%]">{check.detail}</span>
+                  )}
+                </div>
+              ))}
+              {pxpipeHealth.error && (
+                <p className="text-xs text-warning mt-1">{pxpipeHealth.error}</p>
+              )}
+            </div>
+          )}
+          {!pxpipeStatus.installed ? (
+            <div className="flex flex-col gap-2">
+              <p className="text-sm text-warning">PXPIPE is not installed.</p>
+              <Button
+                onClick={() => pxpipeAction("install")}
+                fullWidth
+                disabled={pxpipeActionLoading || pxpipeStatus.installing}
+              >
+                {pxpipeActionLoading || pxpipeStatus.installing ? "Installing…" : "Install"}
+              </Button>
+              <p className="text-xs text-text-muted">
+                Installs the npm package <code className="font-mono">pxpipe-proxy</code> into
+                the 9Router data directory. May take a few minutes.
+              </p>
+            </div>
+          ) : (
+            <div className="grid grid-cols-2 gap-2">
+              {pxpipeStatus.running ? (
+                <>
+                  <Button onClick={() => pxpipeAction("restart")} variant="ghost" disabled={pxpipeActionLoading}>
+                    Restart
+                  </Button>
+                  <Button onClick={() => pxpipeAction("stop")} variant="ghost" disabled={pxpipeActionLoading}>
+                    Stop
+                  </Button>
+                </>
+              ) : (
+                <Button onClick={() => pxpipeAction("start")} disabled={pxpipeActionLoading}>
+                  {pxpipeActionLoading ? "Starting…" : "Start"}
+                </Button>
+              )}
+              <Button onClick={() => pxpipeAction("install")} variant="ghost" disabled={pxpipeActionLoading}>
+                Repair
+              </Button>
+              <a
+                href="/dashboard/pxpipe#logs"
+                className="col-span-2 rounded border border-border px-4 py-2 text-center text-sm hover:bg-surface-2"
+              >
+                Open Logs
+              </a>
+            </div>
+          )}
+          <div className="flex flex-col gap-1">
+            <p className="text-sm font-medium">Minimum prompt size (chars)</p>
+            <Input
+              value={String(pxpipeMinChars)}
+              onChange={(e) => setPxpipeMinChars(e.target.value)}
+              onBlur={handlePxpipeMinCharsBlur}
+              placeholder="25000"
+              className="font-mono text-sm"
+            />
+            <p className="text-xs text-text-muted">
+              Requests smaller than this bypass PXPIPE and are sent as-is.
+            </p>
+          </div>
+          {pxpipeActionError && (
+            <p className="text-sm text-warning">{pxpipeActionError}</p>
+          )}
+          <div className="flex gap-2">
+            <Button
+              onClick={() => refreshPxpipeStatus().then(runPxpipeHealth)}
+              variant="ghost"
+              fullWidth
+            >
+              Recheck
+            </Button>
+            <Button onClick={() => setShowPxpipeModal(false)} fullWidth>
+              Done
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      <ConfirmModal
+        isOpen={!!extrasConfirm}
+        onClose={() => setExtrasConfirm(null)}
+        onConfirm={() => {
+          const fn = extrasConfirm?.onConfirm;
+          setExtrasConfirm(null);
+          fn?.();
+        }}
+        title={extrasConfirm?.title}
+        message={extrasConfirm?.message}
+        confirmText={extrasConfirm?.confirmText}
+        variant={extrasConfirm?.variant}
+      />
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/token-saver/page.js b/src/app/(dashboard)/dashboard/token-saver/page.js
new file mode 100644
index 0000000..765b51f
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/token-saver/page.js
@@ -0,0 +1,5 @@
+import TokenSaverClient from "./TokenSaverClient";
+
+export default function TokenSaverPage() {
+  return <TokenSaverClient />;
+}
diff --git a/src/app/(dashboard)/dashboard/translator/page.js b/src/app/(dashboard)/dashboard/translator/page.js
new file mode 100644
index 0000000..df6b743
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/translator/page.js
@@ -0,0 +1,303 @@
+"use client";
+
+import { useState } from "react";
+import { Card, Button } from "@/shared/components";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import dynamic from "next/dynamic";
+
+const Editor = dynamic(() => import("@monaco-editor/react"), { ssr: false });
+
+// 7 steps matching requestLogger files exactly
+const STEPS = [
+  { id: 1, label: "Client Request",         file: "1_req_client.json",  lang: "json", desc: "Raw request from client" },
+  { id: 2, label: "Source Body",            file: "2_req_source.json",  lang: "json", desc: "After initial conversion" },
+  { id: 3, label: "OpenAI Intermediate",    file: "3_req_openai.json",  lang: "json", desc: "source → openai" },
+  { id: 4, label: "Target Request",         file: "4_req_target.json",  lang: "json", desc: "openai → target + URL + headers" },
+  { id: 5, label: "Provider Response",      file: "5_res_provider.txt", lang: "text", desc: "Raw SSE from provider" },
+  { id: 6, label: "OpenAI Response",        file: "6_res_openai.txt",   lang: "text", desc: "target → openai (response)" },
+  { id: 7, label: "Client Response",        file: "7_res_client.txt",   lang: "text", desc: "Final response to client" },
+];
+
+const EDITOR_OPTIONS = {
+  minimap: { enabled: false },
+  fontSize: 12,
+  lineNumbers: "on",
+  scrollBeyondLastLine: false,
+  wordWrap: "on",
+  automaticLayout: true,
+};
+
+export default function TranslatorPage() {
+  const [contents, setContents] = useState({});
+  const [expanded, setExpanded] = useState({ 1: true });
+  const [loading, setLoading] = useState({});
+  // Detected from step 1: { provider, model, sourceFormat, targetFormat }
+  const [meta, setMeta] = useState(null);
+
+  const setLoad = (key, val) => setLoading(prev => ({ ...prev, [key]: val }));
+  const setContent = (id, val) => setContents(prev => ({ ...prev, [id]: val }));
+  const toggle = (id) => setExpanded(prev => ({ ...prev, [id]: !prev[id] }));
+
+  const openNext = (nextId) => setExpanded(prev => {
+    const next = {};
+    STEPS.forEach(s => { next[s.id] = false; });
+    next[nextId] = true;
+    return next;
+  });
+
+  // Load file from logs/translator/
+  const handleLoad = async (stepId) => {
+    const step = STEPS.find(s => s.id === stepId);
+    setLoad(`load-${stepId}`, true);
+    try {
+      const res = await fetch(`/api/translator/load?file=${step.file}`);
+      const data = await res.json();
+      if (data.success) {
+        setContent(stepId, data.content);
+        if (stepId === 1) await detectMeta(data.content);
+      } else {
+        alert(data.error || "File not found");
+      }
+    } catch (e) {
+      alert(e.message);
+    }
+    setLoad(`load-${stepId}`, false);
+  };
+
+  // Step 1: detect provider/format from model field
+  const detectMeta = async (rawContent) => {
+    try {
+      const body = typeof rawContent === "string" ? JSON.parse(rawContent) : rawContent;
+      const res = await fetch("/api/translator/translate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ step: 1, body })
+      });
+      const data = await res.json();
+      if (data.success) setMeta(data.result);
+    } catch { /* ignore */ }
+  };
+
+  const save = (file, content) => fetch("/api/translator/save", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ file, content })
+  }).catch(() => {});
+
+  // Step 1 → Step 3: source → OpenAI intermediate
+  const handleToOpenAI = async () => {
+    setLoad("toOpenAI", true);
+    try {
+      const raw = contents[1];
+      const body = JSON.parse(raw);
+      // Save input: 1_req_client.json + 2_req_source.json (body only)
+      save("1_req_client.json", raw);
+      save("2_req_source.json", JSON.stringify({ timestamp: new Date().toISOString(), headers: {}, body: body.body || body }, null, 2));
+
+      const res = await fetch("/api/translator/translate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ step: 2, body })
+      });
+      const data = await res.json();
+      if (!data.success) { alert(data.error); return; }
+      const str = JSON.stringify(data.result.body, null, 2);
+      setContent(3, str);
+      openNext(3);
+    } catch (e) { alert(e.message); }
+    setLoad("toOpenAI", false);
+  };
+
+  // Step 3 → Step 4: OpenAI → target + build URL/headers
+  const handleToTarget = async () => {
+    setLoad("toTarget", true);
+    try {
+      const raw = contents[3];
+      const openaiBody = JSON.parse(raw);
+      // Save input: 3_req_openai.json
+      save("3_req_openai.json", raw);
+
+      const res = await fetch("/api/translator/translate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ step: 3, body: { ...openaiBody, provider: meta?.provider, model: meta?.model } })
+      });
+      const data = await res.json();
+      if (!data.success) { alert(data.error); return; }
+      // Embed provider + model so Send works even without meta
+      const step4Content = { ...data.result, provider: meta?.provider, model: meta?.model };
+      setContent(4, JSON.stringify(step4Content, null, 2));
+      openNext(4);
+    } catch (e) { alert(e.message); }
+    setLoad("toTarget", false);
+  };
+
+  // Step 4 → Step 5: send to provider via executor
+  const handleSend = async () => {
+    setLoad("send", true);
+    try {
+      const raw = contents[4];
+      const step4 = JSON.parse(raw);
+      // Save input: 4_req_target.json
+      save("4_req_target.json", raw);
+
+      // Read provider/model from step4 content (embedded during build), fallback to meta
+      const provider = step4.provider || meta?.provider;
+      const model = step4.model || meta?.model;
+
+      if (!provider || !model) {
+        alert("Missing provider or model. Please run step 1 first to detect them.");
+        return;
+      }
+
+      const res = await fetch("/api/translator/send", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ provider, model, body: step4.body || step4 })
+      });
+
+      if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+        alert(err.error || "Send failed");
+        return;
+      }
+
+      // Accumulate streaming response
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let full = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        full += decoder.decode(value, { stream: true });
+      }
+
+      setContent(5, full);
+      openNext(5);
+
+      // Save to logs/translator/5_res_provider.txt
+      await fetch("/api/translator/save", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ file: "5_res_provider.txt", content: full })
+      });
+    } catch (e) {
+      alert(e.message);
+    } finally {
+      setLoad("send", false);
+    }
+  };
+
+  const { copy } = useCopyToClipboard();
+
+  const handleCopy = async (id) => {
+    if (!contents[id]) return;
+    copy(contents[id], `translator-step-${id}`);
+  };
+
+  const handleFormat = (id) => {
+    try {
+      const obj = JSON.parse(contents[id]);
+      setContent(id, JSON.stringify(obj, null, 2));
+    } catch { /* not JSON, skip */ }
+  };
+
+  // Render action button per step
+  const getAction = (stepId) => {
+    if (stepId === 1) return <Button size="sm" icon="arrow_forward" loading={loading["toOpenAI"]} onClick={handleToOpenAI}>→ OpenAI</Button>;
+    if (stepId === 3) return <Button size="sm" icon="arrow_forward" loading={loading["toTarget"]} onClick={handleToTarget}>→ Target</Button>;
+    if (stepId === 4) return <Button size="sm" icon="send" loading={loading["send"]} onClick={handleSend}>Send</Button>;
+    return null;
+  };
+
+  return (
+    <div className="p-8 space-y-3">
+      {/* Header */}
+      <div className="flex items-center justify-between mb-2">
+        <div>
+          <h1 className="text-2xl font-bold text-text-main">Translator Debug</h1>
+          <p className="text-sm text-text-muted mt-1">Replay request flow — matches log files</p>
+        </div>
+        {meta && (
+          <div className="flex items-center gap-2 flex-wrap justify-end">
+            <MetaBadge label="src" value={meta.sourceFormat} color="blue" />
+            <span className="material-symbols-outlined text-text-muted text-[14px]">arrow_forward</span>
+            <MetaBadge label="dst" value={meta.targetFormat} color="orange" />
+            <MetaBadge label="provider" value={meta.provider} color="green" />
+            <MetaBadge label="model" value={meta.model} color="purple" />
+          </div>
+        )}
+      </div>
+
+      {STEPS.map((step) => {
+        const action = getAction(step.id);
+        const isExpanded = !!expanded[step.id];
+        const content = contents[step.id] || "";
+
+        return (
+          <Card key={step.id}>
+            <div className="p-4 space-y-3">
+              {/* Step header */}
+              <div className="flex items-center justify-between">
+                <button onClick={() => toggle(step.id)} className="flex items-center gap-2 flex-1 text-left group">
+                  <span className="material-symbols-outlined text-[20px] text-text-muted group-hover:text-primary transition-colors">
+                    {isExpanded ? "expand_more" : "chevron_right"}
+                  </span>
+                  <span className="text-xs font-mono text-text-muted/60 w-4">{step.id}</span>
+                  <h3 className="text-sm font-semibold text-text-main">{step.label}</h3>
+                  <span className="text-xs text-text-muted/60 font-mono">{step.file}</span>
+                  {content && <span className="text-xs text-green-500">({content.length} chars)</span>}
+                </button>
+                {!isExpanded && (
+                  <div className="flex gap-1 shrink-0">
+                    <Button size="sm" variant="ghost" icon="folder_open" loading={loading[`load-${step.id}`]} onClick={() => handleLoad(step.id)} />
+                    {action}
+                  </div>
+                )}
+              </div>
+
+              {/* Expanded content */}
+              {isExpanded && (
+                <>
+                  <div className="border border-border rounded-lg overflow-hidden">
+                    <Editor
+                      height="400px"
+                      defaultLanguage={step.lang === "text" ? "plaintext" : "json"}
+                      value={content}
+                      onChange={(v) => {
+                        setContent(step.id, v || "");
+                        if (step.id === 1) detectMeta(v || "");
+                      }}
+                      theme="vs-dark"
+                      options={EDITOR_OPTIONS}
+                    />
+                  </div>
+                  <div className="flex gap-2 flex-wrap">
+                    <Button size="sm" variant="outline" icon="folder_open" loading={loading[`load-${step.id}`]} onClick={() => handleLoad(step.id)}>Load</Button>
+                    <Button size="sm" variant="outline" icon="data_object" onClick={() => handleFormat(step.id)}>Format</Button>
+                    <Button size="sm" variant="outline" icon="content_copy" onClick={() => handleCopy(step.id)}>Copy</Button>
+                    {action}
+                  </div>
+                </>
+              )}
+            </div>
+          </Card>
+        );
+      })}
+    </div>
+  );
+}
+
+function MetaBadge({ label, value, color }) {
+  const colors = {
+    blue: "bg-blue-500/10 text-blue-500",
+    orange: "bg-orange-500/10 text-orange-500",
+    green: "bg-green-500/10 text-green-500",
+    purple: "bg-purple-500/10 text-purple-500",
+  };
+  return (
+    <span className={`inline-flex items-center gap-1 px-2 py-0.5 rounded text-xs font-mono ${colors[color]}`}>
+      <span className="text-text-muted/70 font-sans text-[10px]">{label}:</span>{value}
+    </span>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/usage/components/OverviewCards.js b/src/app/(dashboard)/dashboard/usage/components/OverviewCards.js
new file mode 100644
index 0000000..22020ff
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/components/OverviewCards.js
@@ -0,0 +1,39 @@
+"use client";
+
+import PropTypes from "prop-types";
+import Card from "@/shared/components/Card";
+
+const fmt = (n) => new Intl.NumberFormat().format(n || 0);
+const fmtCost = (n) => `$${(n || 0).toFixed(2)}`;
+
+export default function OverviewCards({ stats }) {
+  return (
+    <div className="grid min-w-0 grid-cols-1 gap-3 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-5 sm:gap-4">
+      <Card className="flex min-w-0 flex-col gap-1 px-4 py-3">
+        <span className="text-text-muted text-sm uppercase font-semibold">Total Requests</span>
+        <span className="truncate text-2xl font-bold">{fmt(stats.totalRequests)}</span>
+      </Card>
+      <Card className="flex min-w-0 flex-col gap-1 px-4 py-3">
+        <span className="text-text-muted text-sm uppercase font-semibold">Total Input Tokens</span>
+        <span className="truncate text-2xl font-bold text-primary">{fmt(stats.totalPromptTokens)}</span>
+      </Card>
+      <Card className="flex min-w-0 flex-col gap-1 px-4 py-3">
+        <span className="text-text-muted text-sm uppercase font-semibold">Cached Tokens</span>
+        <span className="truncate text-2xl font-bold text-info">{fmt(stats.totalCachedTokens)}</span>
+      </Card>
+      <Card className="flex min-w-0 flex-col gap-1 px-4 py-3">
+        <span className="text-text-muted text-sm uppercase font-semibold">Output Tokens</span>
+        <span className="truncate text-2xl font-bold text-success">{fmt(stats.totalCompletionTokens)}</span>
+      </Card>
+      <Card className="flex min-w-0 flex-col gap-1 px-4 py-3">
+        <span className="text-text-muted text-sm uppercase font-semibold">Est. Cost</span>
+        <span className="truncate text-2xl font-bold text-warning">~{fmtCost(stats.totalCost)}</span>
+        <span className="text-[10px] text-text-muted">Estimated, not actual billing</span>
+      </Card>
+    </div>
+  );
+}
+
+OverviewCards.propTypes = {
+  stats: PropTypes.object.isRequired,
+};
diff --git a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/ProviderLimitCard.js b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/ProviderLimitCard.js
new file mode 100644
index 0000000..541cc9f
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/ProviderLimitCard.js
@@ -0,0 +1,186 @@
+"use client";
+
+import { useState } from "react";
+import Card from "@/shared/components/Card";
+import ProviderIcon from "@/shared/components/ProviderIcon";
+import Badge from "@/shared/components/Badge";
+import QuotaProgressBar from "./QuotaProgressBar";
+import { calculatePercentage } from "./utils";
+
+const planVariants = {
+  free: "default",
+  pro: "primary",
+  ultra: "success",
+  enterprise: "info",
+};
+
+export default function ProviderLimitCard({
+  provider,
+  name,
+  plan,
+  quotas = [],
+  message = null,
+  loading = false,
+  error = null,
+  onRefresh,
+}) {
+  const [refreshing, setRefreshing] = useState(false);
+
+  const handleRefresh = async () => {
+    if (!onRefresh || refreshing) return;
+
+    setRefreshing(true);
+    try {
+      await onRefresh();
+    } finally {
+      setRefreshing(false);
+    }
+  };
+
+  // Get provider info from config
+  const getProviderColor = () => {
+    const colors = {
+      github: "#000000",
+      antigravity: "#4285F4",
+      codex: "#10A37F",
+      kiro: "#FF9900",
+      qoder: "#EC4899",
+      claude: "#D97757",
+    };
+    return colors[provider?.toLowerCase()] || "#6B7280";
+  };
+
+  const providerColor = getProviderColor();
+  const planVariant = planVariants[plan?.toLowerCase()] || "default";
+
+  return (
+    <Card padding="md" className="flex flex-col gap-4">
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          {/* Provider Logo */}
+          <div
+            className="size-10 rounded-lg flex items-center justify-center p-1.5"
+            style={{ backgroundColor: `${providerColor}15` }}
+          >
+            <ProviderIcon
+              src={`/providers/${provider}.png`}
+              alt={provider || "Provider"}
+              size={40}
+              className="object-contain rounded-lg"
+              fallbackText={provider?.slice(0, 2).toUpperCase() || "PR"}
+              fallbackColor={providerColor}
+            />
+          </div>
+
+          <div>
+            <h3 className="font-semibold text-text-primary">
+              {name || provider}
+            </h3>
+            {plan && (
+              <Badge
+                variant={planVariants[plan?.toLowerCase()] || "default"}
+                size="xs"
+              >
+                {plan}
+              </Badge>
+            )}
+          </div>
+        </div>
+
+        {/* Refresh Button */}
+        <button
+          onClick={handleRefresh}
+          disabled={refreshing || loading}
+          className="p-2 rounded-lg hover:bg-black/5 dark:hover:bg-white/5 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+          title="Refresh quota"
+        >
+          <span
+            className={`material-symbols-outlined text-[20px] text-text-muted ${
+              refreshing || loading ? "animate-spin" : ""
+            }`}
+          >
+            refresh
+          </span>
+        </button>
+      </div>
+
+      {/* Loading State */}
+      {loading && (
+        <div className="space-y-4">
+          <div className="space-y-2">
+            <div className="h-4 bg-black/5 dark:bg-white/5 rounded animate-pulse" />
+            <div className="h-2 bg-black/5 dark:bg-white/5 rounded animate-pulse" />
+          </div>
+          <div className="space-y-2">
+            <div className="h-4 bg-black/5 dark:bg-white/5 rounded animate-pulse" />
+            <div className="h-2 bg-black/5 dark:bg-white/5 rounded animate-pulse" />
+          </div>
+        </div>
+      )}
+
+      {/* Error State */}
+      {!loading && error && (
+        <div className="p-4 rounded-lg bg-red-500/10 border border-red-500/20">
+          <div className="flex items-start gap-2">
+            <span className="material-symbols-outlined text-red-500 text-[20px]">
+              error
+            </span>
+            <p className="text-sm text-red-600 dark:text-red-400">{error}</p>
+          </div>
+        </div>
+      )}
+
+      {/* Info Message (for providers without API) */}
+      {!loading && !error && message && (
+        <div className="p-4 rounded-lg bg-blue-500/10 border border-blue-500/20">
+          <div className="flex items-start gap-2">
+            <span className="material-symbols-outlined text-blue-500 text-[20px]">
+              info
+            </span>
+            <p className="text-sm text-blue-600 dark:text-blue-400">
+              {message}
+            </p>
+          </div>
+        </div>
+      )}
+
+      {/* Quota Progress Bars */}
+      {!loading && !error && !message && quotas?.length > 0 && (
+        <div className="space-y-4">
+          {quotas.map((quota, index) => {
+            // For Antigravity, use remainingPercentage if available, otherwise calculate
+            const percentage =
+              quota.remainingPercentage !== undefined
+                ? Math.round(((quota.total - quota.used) / quota.total) * 100)
+                : calculatePercentage(quota.used, quota.total);
+            const unlimited = quota.total === 0 || quota.total === null;
+
+            return (
+              <QuotaProgressBar
+                key={`${quota.name}-${index}`}
+                label={quota.name}
+                used={quota.used}
+                total={quota.total}
+                percentage={percentage}
+                unlimited={unlimited}
+                resetTime={quota.resetAt}
+                recurring={quota.recurring !== false}
+              />
+            );
+          })}
+        </div>
+      )}
+
+      {/* Empty State */}
+      {!loading && !error && !message && quotas?.length === 0 && (
+        <div className="text-center py-8 text-text-muted">
+          <span className="material-symbols-outlined text-[48px] opacity-20">
+            data_usage
+          </span>
+          <p className="text-sm mt-2">No quota data available</p>
+        </div>
+      )}
+    </Card>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaProgressBar.js b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaProgressBar.js
new file mode 100644
index 0000000..1a13acd
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaProgressBar.js
@@ -0,0 +1,132 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+import { formatResetTime } from "./utils";
+
+// Calculate color based on remaining percentage
+const getColorClasses = (remainingPercentage) => {
+  if (remainingPercentage > 70) {
+    return {
+      text: "text-green-500",
+      bg: "bg-green-500",
+      bgLight: "bg-green-500/10",
+      emoji: "🟢"
+    };
+  }
+  
+  if (remainingPercentage >= 30) {
+    return {
+      text: "text-yellow-500",
+      bg: "bg-yellow-500",
+      bgLight: "bg-yellow-500/10",
+      emoji: "🟡"
+    };
+  }
+  
+  // 0-29% including 0% (out of quota) - show red
+  return {
+    text: "text-red-500",
+    bg: "bg-red-500",
+    bgLight: "bg-red-500/10",
+    emoji: "🔴"
+  };
+};
+
+// Format reset time display
+const formatResetTimeDisplay = (resetTime) => {
+  if (!resetTime) return null;
+  
+  try {
+    const resetDate = new Date(resetTime);
+    const now = new Date();
+    const isToday = resetDate.toDateString() === now.toDateString();
+    const isTomorrow = resetDate.toDateString() === new Date(now.getTime() + 86400000).toDateString();
+    
+    const timeStr = resetDate.toLocaleTimeString(undefined, {
+      hour: "2-digit",
+      minute: "2-digit",
+      hour12: true,
+    });
+    
+    if (isToday) return `Today, ${timeStr}`;
+    if (isTomorrow) return `Tomorrow, ${timeStr}`;
+    
+    return resetDate.toLocaleString(undefined, {
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+      hour12: true,
+    });
+  } catch {
+    return null;
+  }
+};
+
+export default function QuotaProgressBar({
+  percentage = 0,
+  label = "",
+  used = 0,
+  total = 0,
+  unlimited = false,
+  resetTime = null,
+  recurring = true,
+}) {
+  const colors = getColorClasses(percentage);
+  const countdown = formatResetTime(resetTime);
+  const resetDisplay = formatResetTimeDisplay(resetTime);
+
+  // recurring defaults true. One-shot packs (e.g. CodeBuddy CN bonus packs)
+  // set recurring:false: resetTime is a hard expiry, so word it as "expires".
+  const resetWord = recurring ? "Reset" : "Expires";
+
+  // percentage is already remaining percentage (from ProviderLimitCard)
+  const remaining = percentage;
+  
+  return (
+    <div className="space-y-2">
+      {/* Label and percentage */}
+      <div className="flex items-center justify-between text-sm">
+        <span className="font-semibold text-text-primary">
+          {label}
+        </span>
+        <div className="flex items-center gap-1.5">
+          <span className="text-xs">{colors.emoji}</span>
+          <span className={cn("font-medium", colors.text)}>
+            {remaining}%
+          </span>
+        </div>
+      </div>
+
+      {/* Progress bar */}
+      {!unlimited && (
+        <div className={cn("h-2 rounded-full overflow-hidden", colors.bgLight)}>
+          <div
+            className={cn("h-full transition-all duration-300", colors.bg)}
+            style={{ width: `${Math.min(remaining, 100)}%` }}
+          />
+        </div>
+      )}
+
+      {/* Usage details and countdown */}
+      <div className="flex items-center justify-between text-xs text-text-muted">
+        <span>
+          {used.toLocaleString()} / {total.toLocaleString()} requests
+        </span>
+        {countdown !== "-" && (
+          <div className="flex items-center gap-1">
+            <span>•</span>
+            <span className="font-medium">{resetWord} in {countdown}</span>
+          </div>
+        )}
+      </div>
+
+      {/* Reset time display */}
+      {resetDisplay && (
+        <div className="text-xs text-text-muted/70">
+          {resetWord} at {resetDisplay}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaTable.js b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaTable.js
new file mode 100644
index 0000000..8f2a1bc
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaTable.js
@@ -0,0 +1,264 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { formatResetTime, getRemainingPercentage } from "./utils";
+
+const PAGE_SIZE = 10;
+
+/**
+ * Format reset time display (Today, 12:00 PM)
+ */
+function formatResetTimeDisplay(resetTime) {
+  if (!resetTime) return null;
+
+  try {
+    const date = new Date(resetTime);
+    const now = new Date();
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const tomorrow = new Date(today);
+    tomorrow.setDate(tomorrow.getDate() + 1);
+
+    let dayStr = "";
+    if (date >= today && date < tomorrow) {
+      dayStr = "Today";
+    } else if (date >= tomorrow && date < new Date(tomorrow.getTime() + 24 * 60 * 60 * 1000)) {
+      dayStr = "Tomorrow";
+    } else {
+      dayStr = date.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+    }
+
+    const timeStr = date.toLocaleTimeString("en-US", {
+      hour: "numeric",
+      minute: "2-digit",
+      hour12: true,
+    });
+
+    return `${dayStr}, ${timeStr}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get color classes based on remaining percentage
+ */
+function getColorClasses(remainingPercentage) {
+  if (remainingPercentage > 70) {
+    return {
+      text: "text-green-600 dark:text-green-400",
+      bg: "bg-green-500",
+      bgLight: "bg-green-500/10",
+      emoji: "🟢",
+    };
+  }
+
+  if (remainingPercentage >= 30) {
+    return {
+      text: "text-yellow-600 dark:text-yellow-400",
+      bg: "bg-yellow-500",
+      bgLight: "bg-yellow-500/10",
+      emoji: "🟡",
+    };
+  }
+
+  return {
+    text: "text-red-600 dark:text-red-400",
+    bg: "bg-red-500",
+    bgLight: "bg-red-500/10",
+    emoji: "🔴",
+  };
+}
+
+function sortQuotas(quotas, sortMode) {
+  if (sortMode === "remaining-asc") {
+    return [...quotas].sort((a, b) => a.remaining - b.remaining || a.name.localeCompare(b.name));
+  }
+
+  if (sortMode === "remaining-desc") {
+    return [...quotas].sort((a, b) => b.remaining - a.remaining || a.name.localeCompare(b.name));
+  }
+
+  return quotas;
+}
+
+/**
+ * Quota Table Component - Table-based display for quota data
+ */
+export default function QuotaTable({
+  quotas = [],
+  compact = false,
+  sortMode = "default",
+  showSortLabel = false,
+}) {
+  const [page, setPage] = useState(1);
+
+  const normalizedQuotas = useMemo(
+    () => quotas.map((quota, index) => ({
+      ...quota,
+      index,
+      remaining: getRemainingPercentage(quota),
+    })),
+    [quotas],
+  );
+
+  const sortedQuotas = useMemo(
+    () => sortQuotas(normalizedQuotas, sortMode),
+    [normalizedQuotas, sortMode],
+  );
+
+  const totalPages = Math.max(1, Math.ceil(sortedQuotas.length / PAGE_SIZE));
+
+  useEffect(() => {
+    setPage(1);
+  }, [sortMode, quotas]);
+
+  useEffect(() => {
+    setPage((currentPage) => Math.min(currentPage, totalPages));
+  }, [totalPages]);
+
+  if (!quotas || quotas.length === 0) {
+    return null;
+  }
+
+  const currentPageRows = sortedQuotas.slice(
+    (page - 1) * PAGE_SIZE,
+    page * PAGE_SIZE,
+  );
+  const pageStart = sortedQuotas.length === 0 ? 0 : (page - 1) * PAGE_SIZE + 1;
+  const pageEnd = Math.min(page * PAGE_SIZE, sortedQuotas.length);
+
+  const cellPad = compact ? "py-1 px-1.5" : "py-2 px-3";
+  const nameText = compact ? "text-[11px]" : "text-sm";
+  const resetPrimary = compact ? "text-[11px]" : "text-sm";
+  const resetSecondary = compact ? "text-[10px] leading-tight" : "text-xs";
+  const sortLabel = "Sorted by account remaining";
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center justify-between gap-2">
+        <div className="text-[10px] text-text-muted">
+          {sortedQuotas.length} quota{sortedQuotas.length > 1 ? "s" : ""}
+        </div>
+        {showSortLabel && (
+          <div className="rounded-md border border-black/10 bg-black/[0.02] px-2 py-1 text-[10px] text-text-muted dark:border-white/10 dark:bg-white/[0.03]">
+            {sortLabel}
+          </div>
+        )}
+      </div>
+
+      <div className="overflow-x-auto">
+        <table className="w-full table-fixed text-left">
+          <tbody>
+            {currentPageRows.map((quota) => {
+              const colors = getColorClasses(quota.remaining);
+              const countdown = formatResetTime(quota.resetAt);
+              const resetDisplay = formatResetTimeDisplay(quota.resetAt);
+              // recurring defaults true: a missing flag means the quota
+              // refreshes at resetAt. Bonus/one-shot packs set recurring:false
+              // and their resetAt is a hard expiry, so word it as "expires".
+              const recurring = quota.recurring !== false;
+              const countdownLabel = recurring ? `in ${countdown}` : `expires in ${countdown}`;
+
+              return (
+                <tr
+                  key={`${quota.name}-${quota.index}`}
+                  className="border-b border-black/5 dark:border-white/5 hover:bg-black/[0.02] dark:hover:bg-white/[0.02] transition-colors"
+                >
+                  <td className={`${cellPad} w-[30%]`}>
+                    <div className="flex items-center gap-1.5 min-w-0">
+                      <span className="text-[10px] shrink-0">{colors.emoji}</span>
+                      <span className={`${nameText} font-medium text-text-primary truncate`}>
+                        {quota.name}
+                      </span>
+                    </div>
+                  </td>
+
+                  <td className={`${cellPad} w-[45%]`}>
+                    <div className={compact ? "space-y-1" : "space-y-1.5"}>
+                      <div className={`${compact ? "h-1" : "h-1.5"} rounded-full overflow-hidden border ${colors.bgLight} ${
+                        quota.remaining === 0 ? "border-black/10 dark:border-white/10" : "border-transparent"
+                      }`}>
+                        <div
+                          className={`h-full transition-all duration-300 ${colors.bg}`}
+                          style={{ width: `${Math.min(quota.remaining, 100)}%` }}
+                        />
+                      </div>
+
+                      <div className={`flex items-center justify-between ${compact ? "text-[10px]" : "text-xs"}`}>
+                        <span className="text-text-muted">
+                          {quota.used.toLocaleString()} / {quota.total > 0 ? quota.total.toLocaleString() : "∞"}
+                        </span>
+                        <span className={`font-medium ${colors.text}`}>
+                          {quota.remaining}%
+                        </span>
+                      </div>
+                    </div>
+                  </td>
+
+                  <td className={`${cellPad} w-[25%]`}>
+                    {countdown !== "-" || resetDisplay ? (
+                      compact ? (
+                        <div
+                          className={`${resetPrimary} text-text-primary font-medium truncate`}
+                          title={resetDisplay || ""}
+                        >
+                          {countdown !== "-" ? countdownLabel : resetDisplay}
+                        </div>
+                      ) : (
+                        <div className="space-y-0.5">
+                          {countdown !== "-" && (
+                            <div className={`${resetPrimary} text-text-primary font-medium`}>
+                              {countdownLabel}
+                            </div>
+                          )}
+                          {resetDisplay && (
+                            <div className={`${resetSecondary} text-text-muted`}>
+                              {resetDisplay}
+                            </div>
+                          )}
+                        </div>
+                      )
+                    ) : (
+                      <div className={`${resetPrimary} text-text-muted italic`}>N/A</div>
+                    )}
+                  </td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+
+      {totalPages > 1 && (
+        <div className="rounded-md border border-black/10 bg-black/[0.02] px-2 py-1.5 dark:border-white/10 dark:bg-white/[0.03]">
+          <div className="flex items-center justify-between gap-2 text-[10px] text-text-muted">
+            <span>
+              Showing {pageStart}-{pageEnd} of {sortedQuotas.length}
+            </span>
+            <span>
+              Page {page} / {totalPages}
+            </span>
+          </div>
+          <div className="mt-1.5 flex items-center justify-end gap-1">
+            <button
+              type="button"
+              onClick={() => setPage((currentPage) => Math.max(1, currentPage - 1))}
+              disabled={page === 1}
+              className="flex h-6 items-center rounded-md border border-black/10 px-2 text-[10px] text-text-primary transition-colors hover:bg-black/5 disabled:cursor-not-allowed disabled:opacity-40 dark:border-white/10 dark:hover:bg-white/5"
+            >
+              Prev
+            </button>
+            <button
+              type="button"
+              onClick={() => setPage((currentPage) => Math.min(totalPages, currentPage + 1))}
+              disabled={page === totalPages}
+              className="flex h-6 items-center rounded-md border border-black/10 px-2 text-[10px] text-text-primary transition-colors hover:bg-black/5 disabled:cursor-not-allowed disabled:opacity-40 dark:border-white/10 dark:hover:bg-white/5"
+            >
+              Next
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.js b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.js
new file mode 100644
index 0000000..95300c9
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.js
@@ -0,0 +1,1438 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef, useMemo } from "react";
+import ProviderIcon from "@/shared/components/ProviderIcon";
+import QuotaTable from "./QuotaTable";
+import Toggle from "@/shared/components/Toggle";
+import Tooltip from "@/shared/components/Tooltip";
+import {
+  parseQuotaData,
+  calculatePercentage,
+  getConnectionLabel,
+  getConnectionQuotaRemaining,
+  sortVisibleConnections,
+  buildLoadingState,
+  filterQuotaStateByConnections,
+  getConnectionsEmptyMessage,
+  getPageSizeLabel,
+  getConnectionsPaginationSummary,
+  getSafePagination,
+  getSafeTotals,
+  shouldResetPage,
+  getPaginationPageValue,
+  getProviderOptions,
+  reconcileConnectionsPage,
+  getQuotaCache,
+  setQuotaCache,
+  QUOTA_CACHE_KEY,
+  REFRESH_INTERVAL_MS,
+  CLAUDE_REFRESH_INTERVAL_MS,
+  DEPLETED_QUOTA_THRESHOLD,
+  AUTO_REFRESH_STORAGE_KEY,
+  CONNECTIONS_PAGE_SIZE,
+  ACCOUNT_PAGE_SIZE_OPTIONS,
+  ACCOUNT_PAGE_SIZE_MAX,
+  ACCOUNT_FILTER_OPTIONS,
+  QUOTA_SORT_OPTIONS,
+} from "./utils";
+import Card from "@/shared/components/Card";
+import { ConfirmModal, EditConnectionModal } from "@/shared/components";
+import { USAGE_SUPPORTED_PROVIDERS } from "@/shared/constants/providers";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+
+// Maps the stored providerSpecificData.authMethod to a human label for Kiro.
+// Values come from the Kiro connect flows: builder-id/idc (device code),
+// google/github (social), imported (refresh-token paste), api_key (headless).
+const KIRO_METHOD_LABELS = {
+  "builder-id": "AWS Builder ID",
+  idc: "IAM Identity Center",
+  google: "Google",
+  github: "GitHub",
+  imported: "Imported Token",
+  api_key: "API Key",
+};
+
+const AUTO_PING_SETTINGS_KEYS = {
+  claude: "claudeAutoPing",
+  codex: "codexAutoPing",
+};
+
+const AUTO_PING_TOOLTIPS = {
+  claude: "When your 5h quota runs out, auto-sends a request the moment it resets so a new window starts right away.",
+  codex: "Auto-starts the next 5h Codex window after reset by sending a tiny gpt-5.5 request. Consumes a small amount of quota.",
+};
+
+function kiroMethodLabel(conn) {
+  const m = conn.providerSpecificData?.authMethod;
+  if (m && KIRO_METHOD_LABELS[m]) return KIRO_METHOD_LABELS[m];
+  return conn.authType === "api_key" ? "API Key" : "OAuth";
+}
+
+function getConnectionSecondaryLabel(connection) {
+  if (connection.name?.trim() && connection.email?.trim() && connection.name.trim() !== connection.email.trim()) {
+    return connection.email.trim();
+  }
+
+  if (connection.name?.trim() && connection.displayName?.trim() && connection.name.trim() !== connection.displayName.trim()) {
+    return connection.displayName.trim();
+  }
+
+  return null;
+}
+
+// Region is stored for builder-id/idc/api_key flows; social and imported flows
+// omit it, so fall back to the region segment of the profileArn
+// (arn:aws:codewhisperer:<region>:...).
+function kiroRegion(conn) {
+  const r = conn.providerSpecificData?.region;
+  if (r) return r;
+  const arn = conn.providerSpecificData?.profileArn;
+  const seg = typeof arn === "string" ? arn.split(":")[3] : "";
+  return seg || "";
+}
+
+function getCodexResetCreditCount(quota) {
+  const value = quota?.raw?.resetCredits?.availableCount;
+  const count = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(count) ? Math.max(0, count) : 0;
+}
+
+function formatCreditDate(value) {
+  if (!value) return "N/A";
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime())) return "N/A";
+  return date.toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  });
+}
+
+function formatTimeRemaining(value) {
+  if (!value) return "N/A";
+  const diffMs = new Date(value).getTime() - Date.now();
+  if (!Number.isFinite(diffMs)) return "N/A";
+  if (diffMs <= 0) return "Expired";
+  const totalHours = Math.ceil(diffMs / (60 * 60 * 1000));
+  const days = Math.floor(totalHours / 24);
+  const hours = totalHours % 24;
+  return days > 0 ? `${days}d ${hours}h` : `${hours}h`;
+}
+
+export default function ProviderLimits() {
+  const { copied, copy } = useCopyToClipboard();
+  const [connections, setConnections] = useState([]);
+  const [quotaData, setQuotaData] = useState({});
+  const [loading, setLoading] = useState({});
+  const [errors, setErrors] = useState({});
+  const [autoRefresh, setAutoRefresh] = useState(true);
+  const [autoPingMaps, setAutoPingMaps] = useState({ claude: {}, codex: {} });
+  const [lastUpdated, setLastUpdated] = useState(null);
+  const [hasHydratedAutoRefresh, setHasHydratedAutoRefresh] = useState(false);
+  const [refreshingAll, setRefreshingAll] = useState(false);
+  const [countdown, setCountdown] = useState(60);
+  const [connectionsLoading, setConnectionsLoading] = useState(true);
+  const [deletingId, setDeletingId] = useState(null);
+  const [togglingId, setTogglingId] = useState(null);
+  const [resettingLimitId, setResettingLimitId] = useState(null);
+  const [resetConfirmState, setResetConfirmState] = useState(null);
+  const [resetCreditsState, setResetCreditsState] = useState(null);
+  const [showEditModal, setShowEditModal] = useState(false);
+  const [selectedConnection, setSelectedConnection] = useState(null);
+  const [proxyPools, setProxyPools] = useState([]);
+  const [providerFilter, setProviderFilter] = useState("all");
+  const [providerOptions, setProviderOptions] = useState([]);
+  const [accountFilter, setAccountFilter] = useState("all");
+  const [quotaSortMode, setQuotaSortMode] = useState("default");
+  const [expiringFirst, setExpiringFirst] = useState(false);
+  const [providerMenuOpen, setProviderMenuOpen] = useState(false);
+  const [bulkToggling, setBulkToggling] = useState(false);
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(CONNECTIONS_PAGE_SIZE);
+  const [customPageSizeInput, setCustomPageSizeInput] = useState(
+    String(CONNECTIONS_PAGE_SIZE),
+  );
+  const [pagination, setPagination] = useState({
+    page: 1,
+    pageSize: CONNECTIONS_PAGE_SIZE,
+    total: 0,
+    totalPages: 1,
+  });
+  const [totals, setTotals] = useState({
+    eligibleConnections: 0,
+    providerFilteredConnections: 0,
+  });
+
+  const intervalRef = useRef(null);
+  const countdownRef = useRef(null);
+  const tickCountRef = useRef(0);
+
+  const fetchConnections = useCallback(
+    async (targetPage = page) => {
+      try {
+        const params = new URLSearchParams({
+          page: String(targetPage),
+          pageSize: String(pageSize),
+          accountStatus: accountFilter,
+          sort: "priority",
+        });
+
+        if (providerFilter !== "all") {
+          params.set("provider", providerFilter);
+        }
+
+        const response = await fetch(
+          `/api/providers/client?${params.toString()}`,
+        );
+        if (!response.ok) throw new Error("Failed to fetch connections");
+
+        const data = await response.json();
+        const connectionList = data.connections || [];
+        const nextPagination = getSafePagination(data.pagination, pageSize);
+        const nextTotals = getSafeTotals(data.totals, connectionList.length);
+
+        setConnections(connectionList);
+        setProviderOptions(getProviderOptions(data.providerOptions));
+        setPagination(nextPagination);
+        setTotals(nextTotals);
+        setPage(getPaginationPageValue(data.pagination, targetPage));
+        return connectionList;
+      } catch (error) {
+        console.error("Error fetching connections:", error);
+        setConnections([]);
+        setProviderOptions([]);
+        setPagination({ page: 1, pageSize, total: 0, totalPages: 1 });
+        setTotals({ eligibleConnections: 0, providerFilteredConnections: 0 });
+        return [];
+      }
+    },
+    [accountFilter, expiringFirst, page, pageSize, providerFilter],
+  );
+
+  // Fetch quota for a specific connection
+  const fetchQuota = useCallback(async (connectionId, provider) => {
+    setLoading((prev) => ({ ...prev, [connectionId]: true }));
+    setErrors((prev) => ({ ...prev, [connectionId]: null }));
+
+    try {
+      console.log(
+        `[ProviderLimits] Fetching quota for ${provider} (${connectionId})`,
+      );
+      const response = await fetch(`/api/usage/${connectionId}`);
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        const errorMsg = errorData.error || response.statusText;
+
+        // Handle different error types gracefully
+        if (response.status === 404) {
+          // Connection not found - skip silently
+          console.warn(
+            `[ProviderLimits] Connection not found for ${provider}, skipping`,
+          );
+          return;
+        }
+
+        if (response.status === 401) {
+          // Auth error - show message instead of throwing
+          console.warn(
+            `[ProviderLimits] Auth error for ${provider}:`,
+            errorMsg,
+          );
+          const quotaEntry = {
+            quotas: [],
+            message: errorMsg,
+          };
+          setQuotaData((prev) => ({
+            ...prev,
+            [connectionId]: quotaEntry,
+          }));
+          setQuotaCache(connectionId, quotaEntry);
+          return;
+        }
+
+        throw new Error(`HTTP ${response.status}: ${errorMsg}`);
+      }
+
+      const data = await response.json();
+      console.log(`[ProviderLimits] Got quota for ${provider}:`, data);
+
+      // Parse quota data using provider-specific parser
+      const parsedQuotas = parseQuotaData(provider, data);
+
+      const quotaEntry = {
+        quotas: parsedQuotas,
+        plan: data.plan || null,
+        message: data.message || null,
+        raw: data,
+      };
+
+      setQuotaData((prev) => ({
+        ...prev,
+        [connectionId]: quotaEntry,
+      }));
+      setQuotaCache(connectionId, quotaEntry);
+    } catch (error) {
+      console.error(
+        `[ProviderLimits] Error fetching quota for ${provider} (${connectionId}):`,
+        error,
+      );
+      setErrors((prev) => ({
+        ...prev,
+        [connectionId]: error.message || "Failed to fetch quota",
+      }));
+    } finally {
+      setLoading((prev) => ({ ...prev, [connectionId]: false }));
+    }
+  }, []);
+
+  // Refresh quota for a specific provider
+  const refreshProvider = useCallback(
+    async (connectionId, provider) => {
+      await fetchQuota(connectionId, provider);
+      setLastUpdated(new Date());
+    },
+    [fetchQuota],
+  );
+
+  const handleResetCodexLimit = useCallback(
+    async (connectionId, provider) => {
+      if (provider !== "codex" || resettingLimitId) return;
+
+      setResettingLimitId(connectionId);
+      setErrors((prev) => ({ ...prev, [connectionId]: null }));
+
+      try {
+        const response = await fetch(`/api/usage/${connectionId}/codex-reset-credits`, { method: "POST" });
+        const result = await response.json().catch(() => ({}));
+
+        if (!response.ok) {
+          throw new Error(result.message || result.error || result.code || "Failed to reset Codex limit");
+        }
+
+        await fetchQuota(connectionId, provider);
+        setLastUpdated(new Date());
+      } catch (error) {
+        setErrors((prev) => ({ ...prev, [connectionId]: error.message || "Failed to reset Codex limit" }));
+      } finally {
+        setResettingLimitId(null);
+      }
+    },
+    [fetchQuota, resettingLimitId],
+  );
+
+  const handleViewCodexResetCredits = useCallback(async (connection) => {
+    setResetCreditsState({ connection, loading: true, error: null, data: null });
+    try {
+      const response = await fetch(`/api/usage/${connection.id}/codex-reset-credits`, { cache: "no-store" });
+      const result = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        throw new Error(result.error || result.message || "Failed to load Codex reset credits");
+      }
+      const credits = Array.isArray(result.credits) ? [...result.credits] : [];
+      credits.sort((a, b) => {
+        const aTime = a.expiresAt ? new Date(a.expiresAt).getTime() : Number.POSITIVE_INFINITY;
+        const bTime = b.expiresAt ? new Date(b.expiresAt).getTime() : Number.POSITIVE_INFINITY;
+        return aTime - bTime;
+      });
+      setResetCreditsState({ connection, loading: false, error: null, data: { ...result, credits } });
+    } catch (error) {
+      setResetCreditsState({ connection, loading: false, error: error.message || "Failed to load Codex reset credits", data: null });
+    }
+  }, []);
+
+  const handleDeleteConnection = useCallback(
+    async (id) => {
+      if (!confirm("Delete this connection?")) return;
+      setDeletingId(id);
+      try {
+        const res = await fetch(`/api/providers/${id}`, { method: "DELETE" });
+        if (res.ok) {
+          setQuotaData((prev) => {
+            const next = { ...prev };
+            delete next[id];
+            return next;
+          });
+          setLoading((prev) => {
+            const next = { ...prev };
+            delete next[id];
+            return next;
+          });
+          setErrors((prev) => {
+            const next = { ...prev };
+            delete next[id];
+            return next;
+          });
+
+          if (typeof window !== "undefined") {
+            try {
+              const cache = getQuotaCache();
+              if (cache[id]) {
+                delete cache[id];
+                window.localStorage.setItem(
+                  QUOTA_CACHE_KEY,
+                  JSON.stringify(cache),
+                );
+              }
+            } catch (e) {
+              console.error("Error deleting cache entry:", e);
+            }
+          }
+
+          await reconcileConnectionsPage(fetchConnections, page);
+        }
+      } catch (error) {
+        console.error("Error deleting connection:", error);
+      } finally {
+        setDeletingId(null);
+      }
+    },
+    [fetchConnections, page],
+  );
+
+  const handleToggleConnectionActive = useCallback(
+    async (id, isActive) => {
+      setTogglingId(id);
+      try {
+        const res = await fetch(`/api/providers/${id}`, {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ isActive }),
+        });
+        if (res.ok) {
+          setQuotaData((prev) => {
+            const next = { ...prev };
+            return next;
+          });
+          await reconcileConnectionsPage(fetchConnections, page);
+        }
+      } catch (error) {
+        console.error("Error updating connection status:", error);
+      } finally {
+        setTogglingId(null);
+      }
+    },
+    [fetchConnections, page],
+  );
+
+  const handleUpdateConnection = useCallback(
+    async (formData) => {
+      if (!selectedConnection?.id) return;
+      const connectionId = selectedConnection.id;
+      const provider = selectedConnection.provider;
+      try {
+        const res = await fetch(`/api/providers/${connectionId}`, {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(formData),
+        });
+        if (res.ok) {
+          await fetchConnections();
+          setShowEditModal(false);
+          setSelectedConnection(null);
+          if (USAGE_SUPPORTED_PROVIDERS.includes(provider)) {
+            await fetchQuota(connectionId, provider);
+          }
+        }
+      } catch (error) {
+        console.error("Error saving connection:", error);
+      }
+    },
+    [selectedConnection, fetchConnections, fetchQuota],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch("/api/proxy-pools?isActive=true", { cache: "no-store" })
+      .then((res) => res.json())
+      .then((data) => {
+        if (!cancelled && data?.proxyPools) {
+          setProxyPools(data.proxyPools);
+        }
+      })
+      .catch(() => {});
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const refreshAll = useCallback(async (force = false) => {
+    if (refreshingAll) return;
+
+    setRefreshingAll(true);
+    setCountdown(60);
+
+    // Throttle Claude: poll its quota every Nth auto-tick (manual force bypasses)
+    const tick = (tickCountRef.current += 1);
+    const claudeEvery = Math.round(CLAUDE_REFRESH_INTERVAL_MS / REFRESH_INTERVAL_MS);
+    const shouldFetch = (conn) =>
+      force || conn.provider !== "claude" || tick % claudeEvery === 0;
+
+    try {
+      const visibleConnections = await fetchConnections(page);
+
+      setLoading(buildLoadingState(visibleConnections));
+      setErrors((prev) =>
+        filterQuotaStateByConnections(prev, visibleConnections),
+      );
+      setQuotaData((prev) =>
+        filterQuotaStateByConnections(prev, visibleConnections),
+      );
+
+      await Promise.all(
+        visibleConnections
+          .filter(shouldFetch)
+          .map((conn) => fetchQuota(conn.id, conn.provider)),
+      );
+
+      setLastUpdated(new Date());
+    } catch (error) {
+      console.error("Error refreshing all providers:", error);
+    } finally {
+      setRefreshingAll(false);
+    }
+  }, [refreshingAll, fetchConnections, fetchQuota, page]);
+
+  useEffect(() => {
+    const initializeData = async () => {
+      setConnectionsLoading(true);
+      const visibleConnections = await fetchConnections(page);
+      setConnectionsLoading(false);
+
+      // Always fetch fresh quota on mount, no cache display
+      setLoading(buildLoadingState(visibleConnections));
+      setErrors((prev) =>
+        filterQuotaStateByConnections(prev, visibleConnections),
+      );
+      setQuotaData((prev) =>
+        filterQuotaStateByConnections(prev, visibleConnections),
+      );
+
+      await Promise.all(
+        visibleConnections.map((conn) => fetchQuota(conn.id, conn.provider)),
+      );
+      setLastUpdated(new Date());
+    };
+
+    initializeData();
+  }, [fetchConnections, fetchQuota, page]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const stored = window.localStorage.getItem(AUTO_REFRESH_STORAGE_KEY);
+    setAutoRefresh(stored === null ? true : stored === "true");
+    setHasHydratedAutoRefresh(true);
+  }, []);
+
+  // Persist auto-refresh preference
+  useEffect(() => {
+    if (typeof window === "undefined" || !hasHydratedAutoRefresh) return;
+    window.localStorage.setItem(AUTO_REFRESH_STORAGE_KEY, String(autoRefresh));
+  }, [autoRefresh, hasHydratedAutoRefresh]);
+
+  // Load auto-ping per-connection maps
+  useEffect(() => {
+    fetch("/api/settings", { cache: "no-store" })
+      .then((r) => (r.ok ? r.json() : {}))
+      .then((s) => setAutoPingMaps({
+        claude: s?.claudeAutoPing?.connections || {},
+        codex: s?.codexAutoPing?.connections || {},
+      }))
+      .catch(() => {});
+  }, []);
+
+  const toggleAutoPing = useCallback(async (connectionId, provider, on) => {
+    const settingsKey = AUTO_PING_SETTINGS_KEYS[provider];
+    if (!settingsKey) return;
+
+    const previous = autoPingMaps;
+    const nextProviderMap = { ...(autoPingMaps[provider] || {}), [connectionId]: on };
+    const nextMaps = { ...autoPingMaps, [provider]: nextProviderMap };
+    setAutoPingMaps(nextMaps);
+    try {
+      const r = await fetch("/api/settings", { cache: "no-store" });
+      const s = r.ok ? await r.json() : {};
+      const cfg = { ...(s[settingsKey] || {}), connections: nextProviderMap };
+      await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ [settingsKey]: cfg }),
+      });
+    } catch {
+      setAutoPingMaps(previous);
+    }
+  }, [autoPingMaps]);
+
+  // Auto-refresh interval
+  useEffect(() => {
+    if (!hasHydratedAutoRefresh || !autoRefresh) {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+      if (countdownRef.current) {
+        clearInterval(countdownRef.current);
+        countdownRef.current = null;
+      }
+      return;
+    }
+
+    // Main refresh interval
+    intervalRef.current = setInterval(() => {
+      refreshAll();
+    }, REFRESH_INTERVAL_MS);
+
+    // Countdown interval
+    countdownRef.current = setInterval(() => {
+      setCountdown((prev) => {
+        if (prev <= 1) return 60;
+        return prev - 1;
+      });
+    }, 1000);
+
+    return () => {
+      if (intervalRef.current) clearInterval(intervalRef.current);
+      if (countdownRef.current) clearInterval(countdownRef.current);
+    };
+  }, [autoRefresh, refreshAll, hasHydratedAutoRefresh]);
+
+  // Pause auto-refresh when tab is hidden (Page Visibility API)
+  useEffect(() => {
+    const handleVisibilityChange = () => {
+      if (document.hidden) {
+        if (intervalRef.current) {
+          clearInterval(intervalRef.current);
+          intervalRef.current = null;
+        }
+        if (countdownRef.current) {
+          clearInterval(countdownRef.current);
+          countdownRef.current = null;
+        }
+      } else if (autoRefresh && hasHydratedAutoRefresh) {
+        // Resume auto-refresh when tab becomes visible
+        intervalRef.current = setInterval(() => refreshAll(), REFRESH_INTERVAL_MS);
+        countdownRef.current = setInterval(() => {
+          setCountdown((prev) => (prev <= 1 ? 60 : prev - 1));
+        }, 1000);
+      }
+    };
+
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [autoRefresh, refreshAll, hasHydratedAutoRefresh]);
+
+  const sortedConnections = useMemo(
+    () =>
+      sortVisibleConnections(
+        connections,
+        quotaData,
+        expiringFirst,
+        providerFilter,
+        quotaSortMode,
+      ),
+    [connections, quotaData, expiringFirst, providerFilter, quotaSortMode],
+  );
+
+  // Connection is depleted when any quota entry hit the threshold
+  const isConnectionDepleted = (conn) => {
+    const quotas = quotaData[conn.id]?.quotas;
+    if (!quotas?.length) return false;
+    return quotas.some((q) => {
+      if (!q.total || q.total <= 0) return false;
+      return calculatePercentage(q.used, q.total) <= DEPLETED_QUOTA_THRESHOLD;
+    });
+  };
+
+  const bulkSetActive = useCallback(
+    async (targetIds, isActive) => {
+      if (!targetIds.length || bulkToggling) return;
+      setBulkToggling(true);
+      try {
+        await Promise.all(
+          targetIds.map((id) =>
+            fetch(`/api/providers/${id}`, {
+              method: "PUT",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ isActive }),
+            }),
+          ),
+        );
+        await reconcileConnectionsPage(fetchConnections, page);
+      } catch (error) {
+        console.error("Error bulk toggling connections:", error);
+      } finally {
+        setBulkToggling(false);
+      }
+    },
+    [bulkToggling, fetchConnections, page],
+  );
+
+  const handleDisableDepleted = () => {
+    const ids = sortedConnections
+      .filter((c) => (c.isActive ?? true) && isConnectionDepleted(c))
+      .map((c) => c.id);
+    bulkSetActive(ids, false);
+  };
+
+  const handleEnableAvailable = () => {
+    const ids = sortedConnections
+      .filter((c) => !(c.isActive ?? true) && !isConnectionDepleted(c))
+      .map((c) => c.id);
+    bulkSetActive(ids, true);
+  };
+
+  const selectedProviderLabel =
+    providerFilter === "all" ? "All providers" : providerFilter;
+  const hasEligibleConnections = totals.eligibleConnections > 0;
+  const hasVisibleConnections = sortedConnections.length > 0;
+  const emptyState = getConnectionsEmptyMessage(
+    totals,
+    providerFilter,
+    accountFilter,
+  );
+  const connectionsPageSummary = getConnectionsPaginationSummary(pagination);
+  const isCustomPageSize = !ACCOUNT_PAGE_SIZE_OPTIONS.includes(pageSize);
+  const pageSizeLabel = getPageSizeLabel(pageSize, isCustomPageSize);
+
+  if (!connectionsLoading && !hasEligibleConnections) {
+    return (
+      <Card padding="lg">
+        <div className="text-center py-12">
+          <span className="material-symbols-outlined text-[64px] text-text-muted opacity-20">
+            cloud_off
+          </span>
+          <h3 className="mt-4 text-lg font-semibold text-text-primary">
+            No Providers Connected
+          </h3>
+          <p className="mt-2 text-sm text-text-muted max-w-md mx-auto">
+            Connect to providers with OAuth to track your API quota limits and
+            usage.
+          </p>
+        </div>
+      </Card>
+    );
+  }
+
+  if (!connectionsLoading && !hasVisibleConnections) {
+    return (
+      <Card padding="lg">
+        <div className="text-center py-12">
+          <span className="material-symbols-outlined text-[64px] text-text-muted opacity-20">
+            {emptyState.icon}
+          </span>
+          <h3 className="mt-4 text-lg font-semibold text-text-primary">
+            {emptyState.title}
+          </h3>
+          <p className="mt-2 text-sm text-text-muted max-w-md mx-auto">
+            {emptyState.description}
+          </p>
+        </div>
+      </Card>
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      {/* Header Controls */}
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-end">
+        <div className="flex flex-wrap items-center gap-1.5">
+          <div className="relative">
+            <button
+              type="button"
+              onClick={() => setProviderMenuOpen((prev) => !prev)}
+              className="flex h-8 items-center justify-between gap-1 rounded-lg border border-black/10 bg-black/[0.02] px-2 text-xs text-text-primary transition-colors hover:bg-black/5 dark:border-white/10 dark:bg-white/[0.03] dark:hover:bg-white/10"
+              aria-haspopup="menu"
+              aria-expanded={providerMenuOpen}
+              title="Filter quota providers"
+            >
+              <span className="flex min-w-0 items-center gap-1.5">
+                {providerFilter === "all" ? (
+                  <span className="material-symbols-outlined text-[14px] text-text-muted">
+                    apps
+                  </span>
+                ) : (
+                  <ProviderIcon
+                    src={`/providers/${providerFilter}.png`}
+                    alt={providerFilter}
+                    size={18}
+                    className="size-[18px] rounded object-contain"
+                    fallbackText={providerFilter.slice(0, 2).toUpperCase()}
+                  />
+                )}
+                <span className="truncate capitalize hidden lg:inline">
+                  {selectedProviderLabel}
+                </span>
+              </span>
+              <span className="material-symbols-outlined text-[14px] text-text-muted">
+                expand_more
+              </span>
+            </button>
+
+            {providerMenuOpen && (
+              <>
+                <button
+                  type="button"
+                  className="fixed inset-0 z-30 bg-transparent"
+                  aria-label="Close provider filter"
+                  onClick={() => setProviderMenuOpen(false)}
+                />
+                <div className="absolute left-0 z-40 mt-2 w-64 overflow-hidden rounded-2xl border border-black/10 bg-surface/95 p-1.5 shadow-xl shadow-black/10 backdrop-blur dark:border-white/10 dark:bg-surface/95 sm:w-72">
+                  <button
+                    type="button"
+                    onClick={() => {
+                      if (shouldResetPage(providerFilter, "all")) {
+                        setPage(1);
+                      }
+                      setProviderFilter("all");
+                      setProviderMenuOpen(false);
+                    }}
+                    className={`flex w-full items-center gap-3 rounded-xl px-3 py-2.5 text-left text-sm transition-colors ${providerFilter === "all" ? "bg-primary/10 text-primary" : "text-text-primary hover:bg-black/5 dark:hover:bg-white/10"}`}
+                  >
+                    <span className="material-symbols-outlined text-[22px]">
+                      apps
+                    </span>
+                    <span className="font-medium">All providers</span>
+                    {providerFilter === "all" && (
+                      <span className="material-symbols-outlined ml-auto text-[20px]">
+                        check
+                      </span>
+                    )}
+                  </button>
+                  <div className="my-1 h-px bg-black/10 dark:bg-white/10" />
+                  <div className="max-h-72 overflow-y-auto pr-1">
+                    {providerOptions.map((provider) => (
+                      <button
+                        key={provider}
+                        type="button"
+                        onClick={() => {
+                          if (shouldResetPage(providerFilter, provider)) {
+                            setPage(1);
+                          }
+                          setProviderFilter(provider);
+                          setProviderMenuOpen(false);
+                        }}
+                        className={`flex w-full items-center gap-3 rounded-xl px-3 py-2.5 text-left text-sm transition-colors ${providerFilter === provider ? "bg-primary/10 text-primary" : "text-text-primary hover:bg-black/5 dark:hover:bg-white/10"}`}
+                      >
+                        <ProviderIcon
+                          src={`/providers/${provider}.png`}
+                          alt={provider}
+                          size={24}
+                          className="size-6 rounded-md object-contain"
+                          fallbackText={provider.slice(0, 2).toUpperCase()}
+                        />
+                        <span className="font-medium capitalize">
+                          {provider}
+                        </span>
+                        {providerFilter === provider && (
+                          <span className="material-symbols-outlined ml-auto text-[20px]">
+                            check
+                          </span>
+                        )}
+                      </button>
+                    ))}
+                  </div>
+                </div>
+              </>
+            )}
+          </div>
+          <select
+            value={accountFilter}
+            onChange={(event) => {
+              const nextValue = event.target.value;
+              if (shouldResetPage(accountFilter, nextValue)) {
+                setPage(1);
+              }
+              setAccountFilter(nextValue);
+            }}
+            className="h-8 rounded-lg border border-black/10 bg-black/[0.02] px-2 text-xs text-text-primary outline-none transition-colors hover:bg-black/5 dark:border-white/10 dark:bg-white/[0.03] dark:hover:bg-white/10"
+            aria-label="Filter accounts by status"
+          >
+            {ACCOUNT_FILTER_OPTIONS.map((option) => (
+              <option key={option.value} value={option.value}>
+                {option.label}
+              </option>
+            ))}
+          </select>
+
+          {providerFilter === "codex" && (
+            <select
+              value={quotaSortMode}
+              onChange={(event) => setQuotaSortMode(event.target.value)}
+              className="h-8 rounded-lg border border-black/10 bg-black/[0.02] px-2 text-xs text-text-primary outline-none transition-colors hover:bg-black/5 dark:border-white/10 dark:bg-white/[0.03] dark:hover:bg-white/10"
+              aria-label="Sort Codex quotas by remaining"
+            >
+              {QUOTA_SORT_OPTIONS.map((option) => (
+                <option key={option.value} value={option.value}>
+                  {option.label}
+                </option>
+              ))}
+            </select>
+          )}
+
+          <button
+            type="button"
+            onClick={() => setExpiringFirst((prev) => !prev)}
+            aria-pressed={expiringFirst}
+            className={`flex h-8 shrink-0 items-center gap-1 rounded-lg border px-2 text-xs transition-colors ${expiringFirst ? "border-amber-500/40 bg-amber-500/10 text-amber-500" : "border-black/10 text-text-primary hover:bg-black/5 dark:border-white/10 dark:hover:bg-white/5"}`}
+            title="Sort accounts by earliest quota reset time"
+          >
+            <span className="material-symbols-outlined text-[14px]">
+              hourglass_top
+            </span>
+            <span className="hidden sm:inline">Expiring first</span>
+          </button>
+
+          {/* Bulk: disable depleted */}
+          <button
+            type="button"
+            onClick={handleDisableDepleted}
+            disabled={bulkToggling}
+            className="flex h-8 shrink-0 items-center gap-1 rounded-lg border border-red-500/30 px-2 text-xs text-red-500 transition-colors hover:bg-red-500/10 disabled:opacity-50"
+            title="Disable connections with depleted quota on the current page"
+          >
+            <span className="material-symbols-outlined text-[14px]">block</span>
+            <span className="hidden sm:inline">Turn off Empty</span>
+          </button>
+
+          {/* Bulk: enable available */}
+          <button
+            type="button"
+            onClick={handleEnableAvailable}
+            disabled={bulkToggling}
+            className="flex h-8 shrink-0 items-center gap-1 rounded-lg border border-emerald-500/30 px-2 text-xs text-emerald-500 transition-colors hover:bg-emerald-500/10 disabled:opacity-50"
+            title="Enable connections that still have quota on the current page"
+          >
+            <span className="material-symbols-outlined text-[14px]">
+              check_circle
+            </span>
+            <span className="hidden sm:inline">Turn on Available</span>
+          </button>
+
+          {/* Auto-refresh toggle */}
+          <button
+            onClick={() => setAutoRefresh((prev) => !prev)}
+            className="flex h-8 shrink-0 items-center gap-1 rounded-lg border border-black/10 px-2 text-xs transition-colors hover:bg-black/5 dark:border-white/10 dark:hover:bg-white/5"
+            title={autoRefresh ? "Disable auto-refresh" : "Enable auto-refresh"}
+          >
+            <span
+              className={`material-symbols-outlined text-[14px] ${
+                autoRefresh ? "text-primary" : "text-text-muted"
+              }`}
+            >
+              {autoRefresh ? "toggle_on" : "toggle_off"}
+            </span>
+            <span className="hidden text-text-primary sm:inline">
+              Auto-refresh
+            </span>
+            {autoRefresh && (
+              <span className="text-[10px] text-text-muted tabular-nums">
+                ({countdown}s)
+              </span>
+            )}
+          </button>
+
+
+          {/* Refresh all button */}
+          <button
+            type="button"
+            onClick={() => refreshAll(true)}
+            disabled={refreshingAll}
+            className="flex h-8 shrink-0 items-center gap-1 rounded-lg border border-black/10 px-2 text-xs text-text-primary transition-colors hover:bg-black/5 dark:border-white/10 dark:hover:bg-white/5 disabled:opacity-50"
+            title="Refresh all"
+          >
+            <span
+              className={`material-symbols-outlined text-[14px] ${refreshingAll ? "animate-spin" : ""}`}
+            >
+              refresh
+            </span>
+          </button>
+        </div>
+      </div>
+
+      {/* Provider cards: 2 columns, compact */}
+      {expiringFirst && (
+        <div className="rounded-xl border border-amber-500/20 bg-amber-500/10 px-3 py-2 text-xs text-amber-700 dark:text-amber-300">
+          Expiring-first currently reorders accounts inside the current page.
+          Cross-page ordering still follows backend pagination.
+        </div>
+      )}
+
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-3">
+        {sortedConnections.map((conn) => {
+          const quota = quotaData[conn.id];
+          const isLoading = loading[conn.id];
+          const error = errors[conn.id];
+
+          // Use table layout for all providers
+          const isInactive = conn.isActive === false;
+          const isCodex = conn.provider === "codex";
+          const resetCreditCount = getCodexResetCreditCount(quota);
+          const isResettingLimit = resettingLimitId === conn.id;
+          const rowBusy = deletingId === conn.id || togglingId === conn.id || isResettingLimit;
+
+          return (
+            <Card
+              key={conn.id}
+              padding="none"
+              className={`min-w-0 ${isInactive ? "opacity-60" : ""}`}
+            >
+              <div className="px-3 py-2 border-b border-black/10 dark:border-white/10">
+                <div className="flex items-center justify-between gap-2">
+                  <div className="flex items-center gap-2 min-w-0">
+                    <div className="w-8 h-8 shrink-0 rounded-md flex items-center justify-center overflow-hidden">
+                      <ProviderIcon
+                        src={`/providers/${conn.provider}.png`}
+                        alt={conn.provider}
+                        size={32}
+                        className="object-contain"
+                        fallbackText={
+                          conn.provider?.slice(0, 2).toUpperCase() || "PR"
+                        }
+                      />
+                    </div>
+                    <div className="min-w-0">
+                      <h3 className="text-sm font-semibold text-text-primary capitalize truncate">
+                        {conn.provider}
+                      </h3>
+                      {getConnectionLabel(conn) ? (
+                        <p className="text-xs text-text-muted truncate">
+                          {getConnectionLabel(conn)}
+                        </p>
+                      ) : null}
+                      {getConnectionSecondaryLabel(conn) ? (
+                        <p className="text-[11px] text-text-muted/80 truncate">
+                          {getConnectionSecondaryLabel(conn)}
+                        </p>
+                      ) : null}
+                      {conn.provider === "kiro" && (
+                        <div className="mt-1 flex flex-wrap items-center gap-1">
+                          <span className="rounded-full bg-brand-500/10 px-2 py-0.5 text-[10px] font-semibold text-brand-600 dark:text-brand-300">
+                            {kiroMethodLabel(conn)}
+                          </span>
+                          {kiroRegion(conn) && (
+                            <span className="rounded-full bg-blue-500/10 px-2 py-0.5 text-[10px] font-semibold text-blue-600 dark:text-blue-400">
+                              {kiroRegion(conn)}
+                            </span>
+                          )}
+                          <span
+                            className={`rounded-full px-2 py-0.5 text-[10px] font-semibold ${
+                              isInactive
+                                ? "bg-surface-2 text-text-muted"
+                                : conn.testStatus === "active" || conn.testStatus === "success"
+                                  ? "bg-green-500/10 text-green-600 dark:text-green-400"
+                                  : conn.testStatus === "error" || conn.testStatus === "expired" || conn.testStatus === "unavailable"
+                                    ? "bg-red-500/10 text-red-600 dark:text-red-400"
+                                    : "bg-surface-2 text-text-muted"
+                            }`}
+                          >
+                            {isInactive ? "disabled" : conn.testStatus || "unknown"}
+                          </span>
+                          {conn.providerSpecificData?.profileArn && (
+                            <button
+                              type="button"
+                              onClick={() => copy(conn.providerSpecificData.profileArn, conn.id)}
+                              title={conn.providerSpecificData.profileArn}
+                              className="inline-flex max-w-full items-center gap-1 rounded-full border border-border-subtle px-2 py-0.5 text-[10px] text-text-muted transition-colors hover:text-primary"
+                            >
+                              <span className="material-symbols-outlined text-[12px]">
+                                {copied === conn.id ? "check" : "content_copy"}
+                              </span>
+                              <code className="truncate font-mono">
+                                {conn.providerSpecificData.profileArn}
+                              </code>
+                            </button>
+                          )}
+                        </div>
+                      )}
+                    </div>
+                  </div>
+
+                  <div className="flex items-center gap-1 shrink-0">
+                    {isCodex && (
+                      <>
+                        <Tooltip
+                          text={
+                            resetCreditCount > 0
+                              ? `Use one Codex reset credit. Available: ${resetCreditCount}`
+                              : "No Codex reset credits available"
+                          }
+                        >
+                          <button
+                            type="button"
+                            onClick={() => setResetConfirmState({ connection: conn, resetCreditCount })}
+                            disabled={resetCreditCount <= 0 || isLoading || rowBusy}
+                            aria-label={
+                              resetCreditCount > 0
+                                ? `Use one Codex reset credit. ${resetCreditCount} available.`
+                                : "No Codex reset credits available"
+                            }
+                            className={`flex h-8 min-w-10 items-center justify-center gap-1 rounded-lg border px-2 text-[11px] font-medium tabular-nums transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary/60 disabled:cursor-not-allowed disabled:opacity-60 ${
+                              resetCreditCount > 0
+                                ? "border-primary/30 bg-primary/5 text-primary hover:bg-primary/10"
+                                : "border-black/10 bg-black/[0.02] text-text-muted dark:border-white/10 dark:bg-white/[0.03]"
+                            }`}
+                          >
+                            <span className={`material-symbols-outlined text-[15px] ${isResettingLimit ? "animate-spin" : ""}`}>
+                              {isResettingLimit ? "progress_activity" : "restart_alt"}
+                            </span>
+                            <span>{resetCreditCount}</span>
+                          </button>
+                        </Tooltip>
+                        <Tooltip text="View Codex reset credit expiry">
+                          <button
+                            type="button"
+                            onClick={() => handleViewCodexResetCredits(conn)}
+                            disabled={isLoading || rowBusy}
+                            aria-label="View Codex reset credit expiry"
+                            className="flex h-8 w-8 items-center justify-center rounded-lg border border-black/10 text-text-muted transition-colors hover:bg-black/5 hover:text-primary disabled:cursor-not-allowed disabled:opacity-50 dark:border-white/10 dark:hover:bg-white/5"
+                          >
+                            <span className="material-symbols-outlined text-[17px]">schedule</span>
+                          </button>
+                        </Tooltip>
+                      </>
+                    )}
+                    {AUTO_PING_SETTINGS_KEYS[conn.provider] && conn.authType === "oauth" && (
+                      <Tooltip text={AUTO_PING_TOOLTIPS[conn.provider]}>
+                        <button
+                          type="button"
+                          onClick={() => toggleAutoPing(conn.id, conn.provider, !(autoPingMaps[conn.provider]?.[conn.id] === true))}
+                          aria-label="Toggle auto-ping"
+                          className={`flex h-8 w-8 items-center justify-center rounded-lg transition-colors hover:bg-black/5 dark:hover:bg-white/5 ${autoPingMaps[conn.provider]?.[conn.id] === true ? "text-primary" : "text-text-muted"}`}
+                        >
+                          <span className="material-symbols-outlined text-[18px]">bolt</span>
+                        </button>
+                      </Tooltip>
+                    )}
+                    <Tooltip text="Refresh quota">
+                      <button
+                        type="button"
+                        onClick={() => refreshProvider(conn.id, conn.provider)}
+                        disabled={isLoading || rowBusy}
+                        aria-label="Refresh quota"
+                        className="flex h-8 w-8 items-center justify-center rounded-lg hover:bg-black/5 dark:hover:bg-white/5 transition-colors disabled:opacity-50"
+                      >
+                        <span
+                          className={`material-symbols-outlined text-[18px] text-text-muted ${isLoading ? "animate-spin" : ""}`}
+                        >
+                          refresh
+                        </span>
+                      </button>
+                    </Tooltip>
+                    <Tooltip text="Edit connection">
+                      <button
+                        type="button"
+                        onClick={() => {
+                          setSelectedConnection(conn);
+                          setShowEditModal(true);
+                        }}
+                        disabled={rowBusy}
+                        aria-label="Edit connection"
+                        className="flex h-8 w-8 items-center justify-center rounded-lg hover:bg-black/5 dark:hover:bg-white/5 text-text-muted hover:text-primary transition-colors disabled:opacity-50"
+                      >
+                        <span className="material-symbols-outlined text-[18px]">
+                          edit
+                        </span>
+                      </button>
+                    </Tooltip>
+                    <Tooltip text="Delete connection">
+                      <button
+                        type="button"
+                        onClick={() => handleDeleteConnection(conn.id)}
+                        disabled={rowBusy}
+                        aria-label="Delete connection"
+                        className="flex h-8 w-8 items-center justify-center rounded-lg hover:bg-red-500/10 text-red-500 transition-colors disabled:opacity-50"
+                      >
+                        <span
+                          className={`material-symbols-outlined text-[18px] ${deletingId === conn.id ? "animate-pulse" : ""}`}
+                        >
+                          delete
+                        </span>
+                      </button>
+                    </Tooltip>
+                    <div
+                      className="inline-flex items-center pl-0.5"
+                      title={
+                        (conn.isActive ?? true)
+                          ? "Disable connection"
+                          : "Enable connection"
+                      }
+                    >
+                      <Toggle
+                        size="sm"
+                        checked={conn.isActive ?? true}
+                        disabled={rowBusy}
+                        onChange={(nextActive) =>
+                          handleToggleConnectionActive(conn.id, nextActive)
+                        }
+                      />
+                    </div>
+                  </div>
+                </div>
+              </div>
+
+              <div className="px-2 py-1.5">
+                {isLoading ? (
+                  <div className="text-center py-5 text-text-muted">
+                    <span className="material-symbols-outlined text-[28px] animate-spin">
+                      progress_activity
+                    </span>
+                  </div>
+                ) : error ? (
+                  <div className="text-center py-5">
+                    <span className="material-symbols-outlined text-[28px] text-red-500">
+                      error
+                    </span>
+                    <p className="mt-1.5 text-xs text-text-muted">{error}</p>
+                  </div>
+                ) : quota?.message ? (
+                  <div className="text-center py-5">
+                    <p className="text-xs text-text-muted">{quota.message}</p>
+                  </div>
+                ) : (
+                  <QuotaTable
+                    quotas={quota?.quotas}
+                    compact
+                    sortMode="default"
+                    showSortLabel={
+                      conn.provider === "codex" && quotaSortMode !== "default"
+                    }
+                  />
+                )}
+              </div>
+            </Card>
+          );
+        })}
+      </div>
+
+      <div className="rounded-xl border border-black/10 bg-black/[0.02] px-3 py-2 dark:border-white/10 dark:bg-white/[0.03]">
+          <div className="flex flex-wrap items-center justify-between gap-2">
+            <span className="text-xs text-text-muted">{connectionsPageSummary}</span>
+            <div className="flex flex-wrap items-center gap-2">
+              <select
+                value={isCustomPageSize ? "custom" : String(pageSize)}
+                onChange={(event) => {
+                  const nextValue = event.target.value;
+                  if (nextValue === "custom") return;
+                  const nextPageSize = Number.parseInt(nextValue, 10);
+                  if (Number.isFinite(nextPageSize)) {
+                    setPage(1);
+                    setPageSize(nextPageSize);
+                    setCustomPageSizeInput(String(nextPageSize));
+                  }
+                }}
+                className="h-8 rounded-lg border border-black/10 bg-black/[0.02] px-2 text-xs text-text-primary outline-none transition-colors hover:bg-black/5 dark:border-white/10 dark:bg-white/[0.03] dark:hover:bg-white/10"
+                aria-label="Accounts per page"
+              >
+                {ACCOUNT_PAGE_SIZE_OPTIONS.map((option) => (
+                  <option key={option} value={String(option)}>
+                    {option} / page
+                  </option>
+                ))}
+                <option value="custom">Custom</option>
+              </select>
+              <input
+                type="number"
+                min="1"
+                max={String(ACCOUNT_PAGE_SIZE_MAX)}
+                inputMode="numeric"
+                value={customPageSizeInput}
+                onChange={(event) => setCustomPageSizeInput(event.target.value)}
+                onBlur={() => {
+                  const parsedValue = Number.parseInt(customPageSizeInput, 10);
+                  if (!Number.isFinite(parsedValue)) {
+                    setCustomPageSizeInput(String(pageSize));
+                    return;
+                  }
+                  const nextPageSize = Math.min(ACCOUNT_PAGE_SIZE_MAX, Math.max(1, parsedValue));
+                  setPage(1);
+                  setPageSize(nextPageSize);
+                  setCustomPageSizeInput(String(nextPageSize));
+                }}
+                onKeyDown={(event) => {
+                  if (event.key !== "Enter") return;
+                  const parsedValue = Number.parseInt(customPageSizeInput, 10);
+                  if (!Number.isFinite(parsedValue)) {
+                    setCustomPageSizeInput(String(pageSize));
+                    return;
+                  }
+                  const nextPageSize = Math.min(ACCOUNT_PAGE_SIZE_MAX, Math.max(1, parsedValue));
+                  setPage(1);
+                  setPageSize(nextPageSize);
+                  setCustomPageSizeInput(String(nextPageSize));
+                }}
+                className="h-8 w-20 rounded-lg border border-black/10 bg-black/[0.02] px-2 text-xs text-text-primary outline-none transition-colors hover:bg-black/5 dark:border-white/10 dark:bg-white/[0.03] dark:hover:bg-white/10"
+                aria-label="Custom accounts per page"
+                placeholder="Custom"
+              />
+              <span className="text-xs text-text-muted">Page {pagination.page} / {pagination.totalPages}</span>
+            </div>
+            <div className="flex items-center gap-1.5">
+              <button
+                type="button"
+                onClick={() => setPage(1)}
+                disabled={
+                  pagination.page <= 1 || connectionsLoading || refreshingAll
+                }
+                className="flex h-8 items-center rounded-lg border border-black/10 px-3 text-xs text-text-primary transition-colors hover:bg-black/5 disabled:cursor-not-allowed disabled:opacity-40 dark:border-white/10 dark:hover:bg-white/5"
+              >
+                First Page
+              </button>
+              <button
+                type="button"
+                onClick={() =>
+                  setPage((currentPage) => Math.max(1, currentPage - 1))
+                }
+                disabled={
+                  pagination.page <= 1 || connectionsLoading || refreshingAll
+                }
+                className="flex h-8 w-8 items-center justify-center rounded-lg border border-black/10 text-text-primary transition-colors hover:bg-black/5 disabled:cursor-not-allowed disabled:opacity-40 dark:border-white/10 dark:hover:bg-white/5"
+                aria-label="Previous accounts page"
+              >
+                <span className="material-symbols-outlined text-[16px]">
+                  chevron_left
+                </span>
+              </button>
+              <button
+                type="button"
+                onClick={() =>
+                  setPage((currentPage) =>
+                    Math.min(pagination.totalPages, currentPage + 1),
+                  )
+                }
+                disabled={
+                  pagination.page >= pagination.totalPages ||
+                  connectionsLoading ||
+                  refreshingAll
+                }
+                className="flex h-8 w-8 items-center justify-center rounded-lg border border-black/10 text-text-primary transition-colors hover:bg-black/5 disabled:cursor-not-allowed disabled:opacity-40 dark:border-white/10 dark:hover:bg-white/5"
+                aria-label="Next accounts page"
+              >
+                <span className="material-symbols-outlined text-[16px]">
+                  chevron_right
+                </span>
+              </button>
+              <button
+                type="button"
+                onClick={() => setPage(pagination.totalPages)}
+                disabled={
+                  pagination.page >= pagination.totalPages ||
+                  connectionsLoading ||
+                  refreshingAll
+                }
+                className="flex h-8 items-center rounded-lg border border-black/10 px-3 text-xs text-text-primary transition-colors hover:bg-black/5 disabled:cursor-not-allowed disabled:opacity-40 dark:border-white/10 dark:hover:bg-white/5"
+              >
+                Last Page
+              </button>
+            </div>
+          </div>
+        </div>
+
+      <ConfirmModal
+        isOpen={Boolean(resetConfirmState)}
+        onClose={() => {
+          if (!resettingLimitId) setResetConfirmState(null);
+        }}
+        onConfirm={async () => {
+          const connection = resetConfirmState?.connection;
+          if (!connection) return;
+          await handleResetCodexLimit(connection.id, connection.provider);
+          setResetConfirmState(null);
+        }}
+        title="Reset Codex limit?"
+        message={`Use 1 Codex reset credit for ${getConnectionLabel(resetConfirmState?.connection || {}) || "this account"}. This cannot be undone. Remaining credits: ${resetConfirmState?.resetCreditCount ?? 0}.`}
+        confirmText="Reset limit"
+        cancelText="Cancel"
+        variant="danger"
+        loading={Boolean(resettingLimitId)}
+      />
+
+      {resetCreditsState && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 px-4 backdrop-blur-sm">
+          <div className="w-full max-w-2xl overflow-hidden rounded-2xl border border-black/15 bg-white shadow-2xl ring-1 ring-black/10 dark:border-white/15 dark:bg-neutral-950 dark:ring-white/10">
+            <div className="flex items-start justify-between gap-3 border-b border-black/10 bg-black/[0.03] px-4 py-3 dark:border-white/10 dark:bg-white/[0.04]">
+              <div className="min-w-0">
+                <h3 className="text-base font-semibold text-text-primary">Codex Reset Credit Expiry</h3>
+                <p className="mt-0.5 truncate text-xs text-text-muted">
+                  {getConnectionLabel(resetCreditsState.connection) || "Codex account"}
+                </p>
+              </div>
+              <button
+                type="button"
+                onClick={() => setResetCreditsState(null)}
+                className="flex h-8 w-8 items-center justify-center rounded-lg text-text-muted transition-colors hover:bg-black/5 hover:text-text-primary dark:hover:bg-white/5"
+                aria-label="Close reset credit expiry modal"
+              >
+                <span className="material-symbols-outlined text-[18px]">close</span>
+              </button>
+            </div>
+
+            <div className="max-h-[70vh] overflow-auto bg-white p-4 dark:bg-neutral-950">
+              {resetCreditsState.loading ? (
+                <div className="flex items-center justify-center gap-2 py-10 text-sm text-text-muted">
+                  <span className="material-symbols-outlined animate-spin text-[20px]">progress_activity</span>
+                  Loading reset credits...
+                </div>
+              ) : resetCreditsState.error ? (
+                <div className="rounded-xl border border-red-500/20 bg-red-500/10 px-3 py-2 text-sm text-red-600 dark:text-red-300">
+                  {resetCreditsState.error}
+                </div>
+              ) : resetCreditsState.data?.credits?.length ? (
+                <div className="space-y-3">
+                  <div className="flex items-center justify-between rounded-xl border border-black/10 bg-black/[0.02] px-3 py-2 text-xs text-text-muted dark:border-white/10 dark:bg-white/[0.03]">
+                    <span>{resetCreditsState.data.credits.length} reset credit{resetCreditsState.data.credits.length === 1 ? "" : "s"}</span>
+                    <span>{resetCreditsState.data.availableCount ?? 0} available</span>
+                  </div>
+                  <div className="overflow-x-auto rounded-xl border border-black/10 dark:border-white/10">
+                    <table className="w-full min-w-[560px] text-left text-sm">
+                      <thead className="bg-black/[0.03] text-xs uppercase tracking-wide text-text-muted dark:bg-white/[0.04]">
+                        <tr>
+                          <th className="px-3 py-2 font-medium">Status</th>
+                          <th className="px-3 py-2 font-medium">Granted At</th>
+                          <th className="px-3 py-2 font-medium">Expires At</th>
+                          <th className="px-3 py-2 font-medium">Remaining</th>
+                        </tr>
+                      </thead>
+                      <tbody>
+                        {resetCreditsState.data.credits.map((credit, index) => (
+                          <tr key={`${credit.status}-${credit.expiresAt || index}`} className="border-t border-black/5 dark:border-white/5">
+                            <td className="px-3 py-2">
+                              <span className="rounded-full bg-primary/10 px-2 py-0.5 text-xs font-medium text-primary">
+                                {credit.status || "unknown"}
+                              </span>
+                            </td>
+                            <td className="px-3 py-2 text-text-muted">{formatCreditDate(credit.grantedAt)}</td>
+                            <td className="px-3 py-2 text-text-primary">{formatCreditDate(credit.expiresAt)}</td>
+                            <td className="px-3 py-2 font-medium text-text-primary">{formatTimeRemaining(credit.expiresAt)}</td>
+                          </tr>
+                        ))}
+                      </tbody>
+                    </table>
+                  </div>
+                </div>
+              ) : (
+                <div className="rounded-xl border border-black/10 bg-black/[0.02] px-3 py-8 text-center text-sm text-text-muted dark:border-white/10 dark:bg-white/[0.03]">
+                  No reset credit details returned for this account.
+                </div>
+              )}
+            </div>
+          </div>
+        </div>
+      )}
+
+      <EditConnectionModal
+        isOpen={showEditModal}
+        connection={selectedConnection}
+        proxyPools={proxyPools}
+        onSave={handleUpdateConnection}
+        onClose={() => {
+          setShowEditModal(false);
+          setSelectedConnection(null);
+        }}
+      />
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.js b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.js
new file mode 100644
index 0000000..06cc323
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.js
@@ -0,0 +1,505 @@
+import { getModelsByProviderId } from "open-sse/config/providerModels.js";
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+export const QUOTA_CACHE_KEY = "quotaCacheData";
+export const REFRESH_INTERVAL_MS = 60000;
+// Claude usage/quota endpoint rate-limits; poll it less often than other providers
+export const CLAUDE_REFRESH_INTERVAL_MS = 180000;
+export const DEPLETED_QUOTA_THRESHOLD = 5;
+export const AUTO_REFRESH_STORAGE_KEY = "quotaAutoRefresh";
+export const CONNECTIONS_PAGE_SIZE = 20;
+export const ACCOUNT_PAGE_SIZE_OPTIONS = [10, 20, 50, 100];
+export const ACCOUNT_PAGE_SIZE_MAX = 500;
+export const ACCOUNT_FILTER_OPTIONS = [
+  { value: "all", label: "All accounts" },
+  { value: "active", label: "Active" },
+  { value: "inactive", label: "Turned off" },
+];
+export const QUOTA_SORT_OPTIONS = [
+  { value: "default", label: "Default quota order" },
+  { value: "remaining-asc", label: "% quota: low to high" },
+  { value: "remaining-desc", label: "% quota: high to low" },
+];
+
+// ─── Pure helpers ─────────────────────────────────────────────────────────────
+export function getConnectionLabel(connection) {
+  return connection.name?.trim()
+    || connection.email?.trim()
+    || connection.displayName?.trim()
+    || null;
+}
+
+export function getConnectionQuotaRemaining(connection, quotaData) {
+  const quota = quotaData[connection.id]?.quotas?.[0];
+  if (!quota) return Number.POSITIVE_INFINITY;
+  if (typeof quota.remaining === "number") return quota.remaining;
+  return Number.POSITIVE_INFINITY;
+}
+
+export function sortVisibleConnections(
+  connections,
+  quotaData,
+  expiringFirst,
+  providerFilter,
+  quotaSortMode,
+) {
+  if (providerFilter === "codex" && quotaSortMode !== "default") {
+    return [...connections].sort((a, b) => {
+      const remainingA = getConnectionQuotaRemaining(a, quotaData);
+      const remainingB = getConnectionQuotaRemaining(b, quotaData);
+      const remainingDiff =
+        quotaSortMode === "remaining-asc"
+          ? remainingA - remainingB
+          : remainingB - remainingA;
+      if (remainingDiff !== 0) return remainingDiff;
+      return (getConnectionLabel(a) || "").localeCompare(
+        getConnectionLabel(b) || "",
+      );
+    });
+  }
+
+  if (!expiringFirst) return connections;
+
+  const getEarliestResetTime = (connection) => {
+    const resetTimes = (quotaData[connection.id]?.quotas || [])
+      .map((quota) =>
+        quota.resetAt
+          ? new Date(quota.resetAt).getTime()
+          : Number.POSITIVE_INFINITY,
+      )
+      .filter((time) => Number.isFinite(time));
+    return resetTimes.length > 0
+      ? Math.min(...resetTimes)
+      : Number.POSITIVE_INFINITY;
+  };
+
+  return [...connections].sort((a, b) => {
+    const expiryDiff = getEarliestResetTime(a) - getEarliestResetTime(b);
+    if (expiryDiff !== 0) return expiryDiff;
+    return (
+      (a.provider || "").localeCompare(b.provider || "") ||
+      (getConnectionLabel(a) || "").localeCompare(getConnectionLabel(b) || "")
+    );
+  });
+}
+
+export function buildLoadingState(connections) {
+  const nextLoadingState = {};
+  connections.forEach((connection) => {
+    nextLoadingState[connection.id] = true;
+  });
+  return nextLoadingState;
+}
+
+export function filterQuotaStateByConnections(state, connections) {
+  const visibleIds = new Set(connections.map((connection) => connection.id));
+  return Object.fromEntries(
+    Object.entries(state).filter(([id]) => visibleIds.has(id)),
+  );
+}
+
+export function getConnectionsPageRange(pagination) {
+  if (!pagination.total) {
+    return { start: 0, end: 0 };
+  }
+  const start = (pagination.page - 1) * pagination.pageSize + 1;
+  const end = Math.min(pagination.page * pagination.pageSize, pagination.total);
+  return { start, end };
+}
+
+export function getConnectionsEmptyMessage(totals, providerFilter, accountFilter) {
+  if (!totals.eligibleConnections) {
+    return {
+      icon: "cloud_off",
+      title: "No Providers Connected",
+      description:
+        "Connect to providers with OAuth to track your API quota limits and usage.",
+    };
+  }
+  if (!totals.providerFilteredConnections) {
+    return {
+      icon: "filter_alt_off",
+      title: "No Accounts Match Current Filters",
+      description:
+        providerFilter === "all"
+          ? "Try changing the account status filter to see more quota trackers."
+          : `No ${accountFilter === "inactive" ? "turned off" : accountFilter === "active" ? "active" : "matching"} accounts found for ${providerFilter}.`,
+    };
+  }
+  return {
+    icon: "filter_alt_off",
+    title: "No Accounts On This Page",
+    description:
+      "Try moving to another page or refreshing the current filters.",
+  };
+}
+
+export function sortRequestFromExpiringFirst(expiringFirst) {
+  return expiringFirst ? "expiring" : "priority";
+}
+
+export function getPageSizeLabel(pageSize, isCustomPageSize) {
+  return isCustomPageSize ? `Custom: ${pageSize} / page` : `${pageSize} / page`;
+}
+
+export function getConnectionsPaginationSummary(pagination) {
+  const { start, end } = getConnectionsPageRange(pagination);
+  return `Showing ${start}-${end} of ${pagination.total}`;
+}
+
+export function getSafePagination(pagination, fallbackPageSize) {
+  return (
+    pagination || {
+      page: 1,
+      pageSize: fallbackPageSize,
+      total: 0,
+      totalPages: 1,
+    }
+  );
+}
+
+export function getSafeTotals(totals, fallbackTotal = 0) {
+  return (
+    totals || {
+      eligibleConnections: fallbackTotal,
+      providerFilteredConnections: fallbackTotal,
+    }
+  );
+}
+
+export function shouldResetPage(previousValue, nextValue) {
+  return previousValue !== nextValue;
+}
+
+export function getPaginationPageValue(dataPagination, fallbackPage) {
+  return dataPagination?.page || fallbackPage;
+}
+
+export function getProviderOptions(dataProviderOptions) {
+  return dataProviderOptions || [];
+}
+
+export async function reconcileConnectionsPage(fetchConnections, targetPage) {
+  return await fetchConnections(targetPage);
+}
+
+export function getQuotaCache() {
+  if (typeof window === "undefined") return {};
+  try {
+    const cached = window.localStorage.getItem(QUOTA_CACHE_KEY);
+    return cached ? JSON.parse(cached) : {};
+  } catch (error) {
+    console.error("Error reading quota cache:", error);
+    return {};
+  }
+}
+
+export function setQuotaCache(connectionId, quotaEntry) {
+  if (typeof window === "undefined") return;
+  try {
+    const cache = getQuotaCache();
+    cache[connectionId] = {
+      ...quotaEntry,
+      cachedAt: new Date().toISOString(),
+    };
+    window.localStorage.setItem(QUOTA_CACHE_KEY, JSON.stringify(cache));
+  } catch (error) {
+    console.error("Error writing quota cache:", error);
+  }
+}
+
+/**
+ * Format ISO date string to countdown format (inspired by vscode-antigravity-cockpit)
+ * @param {string|Date} date - ISO date string or Date object
+ * @returns {string} Formatted countdown (e.g., "2d 5h 30m", "4h 40m", "15m") or "-"
+ */
+export function formatResetTime(date) {
+  if (!date) return "-";
+
+  try {
+    const resetDate = typeof date === "string" ? new Date(date) : date;
+    const now = new Date();
+    const diffMs = resetDate - now;
+
+    if (diffMs <= 0) return "-";
+
+    const totalMinutes = Math.ceil(diffMs / (1000 * 60));
+    
+    // < 60 minutes: show only minutes
+    if (totalMinutes < 60) {
+      return `${totalMinutes}m`;
+    }
+    
+    const totalHours = Math.floor(totalMinutes / 60);
+    const remainingMinutes = totalMinutes % 60;
+    
+    // < 24 hours: show hours and minutes
+    if (totalHours < 24) {
+      return `${totalHours}h ${remainingMinutes}m`;
+    }
+    
+    // >= 24 hours: show days, hours, and minutes
+    const days = Math.floor(totalHours / 24);
+    const remainingHours = totalHours % 24;
+    return `${days}d ${remainingHours}h ${remainingMinutes}m`;
+  } catch (error) {
+    return "-";
+  }
+}
+
+/**
+ * Get Tailwind color class based on percentage
+ * @param {number} percentage - Remaining percentage (0-100)
+ * @returns {string} Color name: "green" | "yellow" | "red"
+ */
+export function getStatusColor(percentage) {
+  if (percentage > 70) return "green";
+  if (percentage >= 30) return "yellow";
+  return "red"; // 0-29% including 0% (out of quota) - show red
+}
+
+/**
+ * Get status emoji based on percentage
+ * @param {number} percentage - Remaining percentage (0-100)
+ * @returns {string} Emoji: "🟢" | "🟡" | "🔴"
+ */
+export function getStatusEmoji(percentage) {
+  if (percentage > 70) return "🟢";
+  if (percentage >= 30) return "🟡";
+  return "🔴"; // 0-29% including 0% (out of quota) - show red
+}
+
+/**
+ * Calculate remaining percentage
+ * @param {number} used - Used amount
+ * @param {number} total - Total amount
+ * @returns {number} Remaining percentage (0-100)
+ */
+export function calculatePercentage(used, total) {
+  if (!total || total === 0) return 0;
+  if (!used || used < 0) return 100;
+  if (used >= total) return 0;
+
+  return Math.round(((total - used) / total) * 100);
+}
+
+/**
+ * Get remaining percentage from a normalized quota row
+ * @param {Object} quota - Normalized quota object
+ * @returns {number} Remaining percentage (0-100)
+ */
+export function getRemainingPercentage(quota) {
+  if (quota?.remaining !== undefined) {
+    return Math.max(0, Math.round(quota.remaining));
+  }
+
+  if (quota?.remainingPercentage !== undefined) {
+    return Math.round(quota.remainingPercentage);
+  }
+
+  return calculatePercentage(quota?.used, quota?.total);
+}
+
+/**
+ * Parse provider-specific quota structures into normalized array
+ * @param {string} provider - Provider name (github, antigravity, codex, kiro, claude)
+ * @param {Object} data - Raw quota data from provider
+ * @returns {Array<Object>} Normalized quota objects with { name, used, total, resetAt }
+ */
+export function parseQuotaData(provider, data) {
+  if (!data || typeof data !== "object") return [];
+
+  const normalizedQuotas = [];
+
+  try {
+    switch (provider.toLowerCase()) {
+      case "github":
+        if (data.quotas) {
+          Object.entries(data.quotas).forEach(([name, quota]) => {
+            normalizedQuotas.push({
+              name,
+              used: quota.used || 0,
+              total: quota.total || 0,
+              resetAt: quota.resetAt || null,
+            });
+          });
+        }
+        break;
+
+      case "antigravity":
+        if (data.quotas) {
+          Object.entries(data.quotas).forEach(([modelKey, quota]) => {
+            normalizedQuotas.push({
+              name: quota.displayName || modelKey,
+              modelKey: modelKey, // Keep modelKey for sorting
+              used: quota.used || 0,
+              total: quota.total || 0,
+              resetAt: quota.resetAt || null,
+              remainingPercentage: quota.remainingPercentage,
+            });
+          });
+        }
+        break;
+
+      case "codex":
+        if (data.quotas) {
+          Object.entries(data.quotas).forEach(([quotaType, quota]) => {
+            normalizedQuotas.push({
+              name: quotaType,
+              used: quota.used || 0,
+              total: quota.total || 0,
+              remaining: quota.remaining,
+              resetAt: quota.resetAt || null,
+            });
+          });
+        }
+        break;
+
+      case "kiro":
+        if (data.quotas) {
+          Object.entries(data.quotas).forEach(([quotaType, quota]) => {
+            normalizedQuotas.push({
+              name: quotaType,
+              used: quota.used || 0,
+              total: quota.total || 0,
+              resetAt: quota.resetAt || null,
+            });
+          });
+        }
+        break;
+
+      case "qoder":
+        // Qoder ships a `user` quota and (optionally) an `organization`
+        // quota, both with same shape: {total, used, remaining, unit, resetAt}.
+        // Skip an organization bucket when its total is 0 — most personal
+        // Qoder accounts won't have one and rendering "0/0" is misleading.
+        // Don't forward Qoder's `remaining` field: it's an absolute credit
+        // count, but getRemainingPercentage / QuotaTable interpret
+        // `remaining` as a 0-100 percentage and would render 348 credits
+        // as "348%". The percentage is computed from used/total instead.
+        if (data.quotas) {
+          Object.entries(data.quotas).forEach(([quotaType, quota]) => {
+            if (quotaType === "organization" && (!quota || (Number(quota.total) || 0) === 0)) {
+              return;
+            }
+            normalizedQuotas.push({
+              name: quotaType === "user" ? "Personal" : quotaType === "organization" ? "Organization" : quotaType,
+              used: quota.used || 0,
+              total: quota.total || 0,
+              unit: quota.unit,
+              resetAt: quota.resetAt || null,
+            });
+          });
+        }
+        break;
+
+      case "claude":
+        if (data.message) {
+          // Handle error message case
+          normalizedQuotas.push({
+            name: "error",
+            used: 0,
+            total: 0,
+            resetAt: null,
+            message: data.message,
+          });
+        } else if (data.quotas) {
+          Object.entries(data.quotas).forEach(([name, quota]) => {
+            normalizedQuotas.push({
+              name,
+              used: quota.used || 0,
+              total: quota.total || 0,
+              resetAt: quota.resetAt || null,
+            });
+          });
+        }
+        break;
+
+      case "vercel-ai-gateway":
+        // Vercel returns currency credit balance, not request quotas.
+        // The 'Remaining (USD)' row needs explicit remainingPercentage because
+        // its used/total values would otherwise compute the wrong direction
+        // (e.g. used=95.5 / total=100 → 4% instead of 96%).
+        if (data.quotas) {
+          Object.entries(data.quotas).forEach(([name, quota]) => {
+            normalizedQuotas.push({
+              name,
+              used: quota.used || 0,
+              total: quota.total || 0,
+              resetAt: quota.resetAt || null,
+              remainingPercentage: quota.remainingPercentage,
+            });
+          });
+        }
+        break;
+
+      case "codebuddy-cn":
+        // CodeBuddy CN mixes recurring refill packs ("Monthly"/"Weekly"/...)
+        // with one-shot bonus packs ("Bonus Pack N"). Forward `recurring`
+        // so the UI can show "Expires in" for bonus packs (whose resetAt is
+        // a hard expiry, not a refresh) instead of "Reset in".
+        if (data.quotas) {
+          Object.entries(data.quotas).forEach(([name, quota]) => {
+            normalizedQuotas.push({
+              name,
+              used: quota.used || 0,
+              total: quota.total || 0,
+              resetAt: quota.resetAt || null,
+              recurring: quota.recurring !== false,
+            });
+          });
+        }
+        break;
+
+      case "grok-cli":
+        // Grok Build credits (on-demand window + prepaid balance).
+        // Do NOT forward absolute `remaining` — getRemainingPercentage treats
+        // it as a 0–100 percentage (same as Qoder). Use remainingPercentage.
+        if (data.quotas) {
+          Object.entries(data.quotas).forEach(([name, quota]) => {
+            normalizedQuotas.push({
+              name,
+              used: quota.used || 0,
+              total: quota.total || 0,
+              resetAt: quota.resetAt || null,
+              remainingPercentage: quota.remainingPercentage,
+            });
+          });
+        }
+        break;
+
+      default:
+        // Generic fallback for unknown providers
+        if (data.quotas) {
+          Object.entries(data.quotas).forEach(([name, quota]) => {
+            normalizedQuotas.push({
+              name,
+              used: quota.used || 0,
+              total: quota.total || 0,
+              resetAt: quota.resetAt || null,
+            });
+          });
+        }
+    }
+  } catch (error) {
+    console.error(`Error parsing quota data for ${provider}:`, error);
+    return [];
+  }
+
+  // Sort quotas according to PROVIDER_MODELS order
+  const modelOrder = getModelsByProviderId(provider);
+  if (modelOrder.length > 0) {
+    const orderMap = new Map(modelOrder.map((m, i) => [m.id, i]));
+    
+    normalizedQuotas.sort((a, b) => {
+      // Use modelKey for antigravity, otherwise use name
+      const keyA = a.modelKey || a.name;
+      const keyB = b.modelKey || b.name;
+      const orderA = orderMap.get(keyA) ?? 999;
+      const orderB = orderMap.get(keyB) ?? 999;
+      return orderA - orderB;
+    });
+  }
+
+  return normalizedQuotas;
+}
diff --git a/src/app/(dashboard)/dashboard/usage/components/ProviderTopology.js b/src/app/(dashboard)/dashboard/usage/components/ProviderTopology.js
new file mode 100644
index 0000000..3827a0f
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/components/ProviderTopology.js
@@ -0,0 +1,327 @@
+"use client";
+
+import { useMemo, useState, useEffect, useCallback, useRef } from "react";
+import PropTypes from "prop-types";
+import {
+  ReactFlow,
+  Handle,
+  Position,
+  Controls,
+} from "@xyflow/react";
+import "@xyflow/react/dist/style.css";
+import { AI_PROVIDERS } from "@/shared/constants/providers";
+
+// Force-stop FE animation if a provider stays active longer than this
+const FE_ACTIVE_TIMEOUT_MS = 60000;
+const FE_ACTIVE_TICK_MS = 1000;
+
+function getProviderConfig(providerId) {
+  return AI_PROVIDERS[providerId] || { color: "#6b7280", name: providerId };
+}
+
+// Use local provider images from /public/providers/
+function getProviderImageUrl(providerId) {
+  return `/providers/${providerId}.png`;
+}
+
+// Custom provider node - rectangle with image + name
+function ProviderNode({ data }) {
+  const { label, color, imageUrl, textIcon, active } = data;
+  const [imgError, setImgError] = useState(false);
+  return (
+    <div
+      className="flex items-center gap-2.5 px-4 py-2.5 rounded-lg border-2 transition-all duration-300 bg-bg"
+      style={{
+        borderColor: active ? color : "var(--color-border)",
+        boxShadow: active ? `0 0 16px ${color}40` : "none",
+        minWidth: "150px",
+      }}
+    >
+      <Handle type="target" position={Position.Top} id="top" className="!bg-transparent !border-0 !w-0 !h-0" />
+      <Handle type="target" position={Position.Bottom} id="bottom" className="!bg-transparent !border-0 !w-0 !h-0" />
+      <Handle type="target" position={Position.Left} id="left" className="!bg-transparent !border-0 !w-0 !h-0" />
+      <Handle type="target" position={Position.Right} id="right" className="!bg-transparent !border-0 !w-0 !h-0" />
+
+      {/* Provider icon */}
+      <div
+        className="w-8 h-8 rounded-md flex items-center justify-center shrink-0"
+        style={{ backgroundColor: `${color}15` }}
+      >
+        {!imgError ? (
+          <img src={imageUrl} alt={label} className="w-6 h-6 rounded-sm object-contain" onError={() => setImgError(true)} />
+        ) : (
+          <span className="text-sm font-bold" style={{ color }}>{textIcon}</span>
+        )}
+      </div>
+
+      {/* Provider name */}
+      <span
+        className="text-base font-medium truncate"
+        style={{ color: active ? color : "var(--color-text)" }}
+      >
+        {label}
+      </span>
+
+      {/* Active indicator */}
+      {active && (
+        <span className="relative flex h-2 w-2 shrink-0">
+          <span className="animate-ping absolute inline-flex h-full w-full rounded-full opacity-75" style={{ backgroundColor: color }} />
+          <span className="relative inline-flex rounded-full h-2 w-2" style={{ backgroundColor: color }} />
+        </span>
+      )}
+    </div>
+  );
+}
+
+ProviderNode.propTypes = {
+  data: PropTypes.object.isRequired,
+};
+
+// Center 9Router node
+function RouterNode({ data }) {
+  return (
+    <div className="flex items-center justify-center px-5 py-3 rounded-xl border-2 border-primary bg-primary/5 shadow-md min-w-[130px]">
+      <Handle type="source" position={Position.Top} id="top" className="!bg-transparent !border-0 !w-0 !h-0" />
+      <Handle type="source" position={Position.Bottom} id="bottom" className="!bg-transparent !border-0 !w-0 !h-0" />
+      <Handle type="source" position={Position.Left} id="left" className="!bg-transparent !border-0 !w-0 !h-0" />
+      <Handle type="source" position={Position.Right} id="right" className="!bg-transparent !border-0 !w-0 !h-0" />
+
+      <img src="/favicon.svg" alt="9Router" className="w-6 h-6 mr-2" />
+      <span className="text-sm font-bold text-primary">9Router</span>
+      {data.activeCount > 0 && (
+        <span className="ml-2 px-1.5 py-0.5 rounded-full bg-primary text-white text-xs font-bold">
+          {data.activeCount}
+        </span>
+      )}
+    </div>
+  );
+}
+
+RouterNode.propTypes = {
+  data: PropTypes.object.isRequired,
+};
+
+const nodeTypes = { provider: ProviderNode, router: RouterNode };
+
+// Place N nodes evenly along an ellipse around the router center.
+function buildLayout(providers, activeSet, lastSet, errorSet) {
+  const nodeW = 180;
+  const nodeH = 30;
+  const routerW = 120;
+  const routerH = 44;
+  const nodeGap = 24;
+
+  const count = providers.length;
+
+  // Compute rx so arc spacing between nodes >= nodeW + nodeGap
+  const minRx = ((nodeW + nodeGap) * count) / (2 * Math.PI);
+  const rx = Math.max(320, minRx);
+  const ry = Math.max(200, rx * 0.55); // ellipse ratio ~0.55
+  if (count === 0) {
+    return {
+      nodes: [{ id: "router", type: "router", position: { x: 0, y: 0 }, data: { activeCount: 0 }, draggable: false }],
+      edges: [],
+    };
+  }
+
+  const nodes = [];
+  const edges = [];
+
+  nodes.push({
+    id: "router",
+    type: "router",
+    position: { x: -routerW / 2, y: -routerH / 2 },
+    data: { activeCount: activeSet.size },
+    draggable: false,
+  });
+
+  const edgeStyle = (active, last, error, color) => {
+    if (error) return { stroke: "#ef4444", strokeWidth: 2.5, opacity: 0.9 };
+    if (active) return { stroke: "#22c55e", strokeWidth: 2.5, opacity: 0.9 };
+    if (last) return { stroke: "#f59e0b", strokeWidth: 2, opacity: 0.7 };
+    return { stroke: "var(--color-border)", strokeWidth: 1, opacity: 0.3 };
+  };
+
+  providers.forEach((p, i) => {
+    const config = getProviderConfig(p.provider);
+    const active = activeSet.has(p.provider?.toLowerCase());
+    const last = !active && lastSet.has(p.provider?.toLowerCase());
+    const error = !active && errorSet.has(p.provider?.toLowerCase());
+    const nodeId = `provider-${p.provider}`;
+    const data = {
+      label: (config.name !== p.provider ? config.name : null) || p.nodeName || p.name || p.provider,
+      color: config.color || "#6b7280",
+      imageUrl: getProviderImageUrl(p.provider),
+      textIcon: config.textIcon || (p.provider || "?").slice(0, 2).toUpperCase(),
+      active,
+    };
+
+    // Distribute evenly starting from top (−π/2), clockwise
+    const angle = -Math.PI / 2 + (2 * Math.PI * i) / count;
+    const cx = rx * Math.cos(angle);
+    const cy = ry * Math.sin(angle);
+
+    // Pick router handle closest to the node direction
+    let sourceHandle, targetHandle;
+    if (Math.abs(angle + Math.PI / 2) < Math.PI / 4 || Math.abs(angle - 3 * Math.PI / 2) < Math.PI / 4) {
+      sourceHandle = "top"; targetHandle = "bottom";
+    } else if (Math.abs(angle - Math.PI / 2) < Math.PI / 4) {
+      sourceHandle = "bottom"; targetHandle = "top";
+    } else if (cx > 0) {
+      sourceHandle = "right"; targetHandle = "left";
+    } else {
+      sourceHandle = "left"; targetHandle = "right";
+    }
+
+    nodes.push({
+      id: nodeId,
+      type: "provider",
+      position: { x: cx - nodeW / 2, y: cy - nodeH / 2 },
+      data,
+      draggable: false,
+    });
+
+    edges.push({
+      id: `e-${nodeId}`,
+      source: "router",
+      sourceHandle,
+      target: nodeId,
+      targetHandle,
+      animated: active,
+      style: edgeStyle(active, last, error, config.color),
+    });
+  });
+
+  return { nodes, edges };
+}
+
+export default function ProviderTopology({ providers = [], activeRequests = [], lastProvider = "", errorProvider = "" }) {
+  // Serialize to stable string keys so useMemo only re-runs when values actually change
+  const activeKey = useMemo(
+    () => activeRequests.map((r) => r.provider?.toLowerCase()).filter(Boolean).sort().join(","),
+    [activeRequests]
+  );
+  const lastKey = lastProvider?.toLowerCase() || "";
+  const errorKey = errorProvider?.toLowerCase() || "";
+
+  const rawActiveSet = useMemo(() => new Set(activeKey ? activeKey.split(",") : []), [activeKey]);
+  const lastSet = useMemo(() => new Set(lastKey ? [lastKey] : []), [lastKey]);
+  const errorSet = useMemo(() => new Set(errorKey ? [errorKey] : []), [errorKey]);
+
+  // Track firstSeen per active provider; drop provider if running too long (BE stuck)
+  const firstSeenRef = useRef({});
+  const [tick, setTick] = useState(0);
+
+  useEffect(() => {
+    const seen = firstSeenRef.current;
+    const now = Date.now();
+    for (const p of rawActiveSet) {
+      if (!seen[p]) seen[p] = now;
+    }
+    for (const p of Object.keys(seen)) {
+      if (!rawActiveSet.has(p)) delete seen[p];
+    }
+  }, [rawActiveSet]);
+
+  useEffect(() => {
+    if (rawActiveSet.size === 0) return;
+    const id = setInterval(() => setTick((t) => t + 1), FE_ACTIVE_TICK_MS);
+    return () => clearInterval(id);
+  }, [rawActiveSet]);
+
+  const activeSet = useMemo(() => {
+    const now = Date.now();
+    const filtered = new Set();
+    for (const p of rawActiveSet) {
+      const ts = firstSeenRef.current[p];
+      if (!ts || now - ts < FE_ACTIVE_TIMEOUT_MS) filtered.add(p);
+    }
+    return filtered;
+  }, [rawActiveSet, tick]);
+
+  const { nodes, edges } = useMemo(
+    () => buildLayout(providers, activeSet, lastSet, errorSet),
+    [providers, activeSet, lastKey, errorKey]
+  );
+
+  // Stable key — only remount when provider list changes
+  const providersKey = useMemo(
+    () => providers.map((p) => p.provider).sort().join(","),
+    [providers]
+  );
+
+  const rfInstance = useRef(null);
+  const containerRef = useRef(null);
+  const fitOpts = { padding: 0.2, duration: 200 };
+  const onInit = useCallback((instance) => {
+    rfInstance.current = instance;
+    setTimeout(() => instance.fitView(fitOpts), 50);
+  }, []);
+
+  // Re-fit on container resize
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const ro = new ResizeObserver(() => {
+      if (rfInstance.current) rfInstance.current.fitView(fitOpts);
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  // Re-fit when node count/layout changes
+  useEffect(() => {
+    if (rfInstance.current) {
+      const id = setTimeout(() => rfInstance.current.fitView(fitOpts), 50);
+      return () => clearTimeout(id);
+    }
+  }, [nodes.length]);
+
+  return (
+    <div ref={containerRef} className="h-[320px] w-full min-w-0 rounded-lg border border-border bg-bg-subtle/30 sm:h-[480px]">
+      {providers.length === 0 ? (
+        <div className="h-full flex items-center justify-center text-text-muted text-sm">
+          No providers connected
+        </div>
+      ) : (
+        <ReactFlow
+          key={providersKey}
+          nodes={nodes}
+          edges={edges}
+          nodeTypes={nodeTypes}
+          fitView
+          fitViewOptions={fitOpts}
+          minZoom={0.1}
+          maxZoom={2}
+          onInit={onInit}
+          proOptions={{ hideAttribution: true }}
+          panOnDrag
+          zoomOnScroll
+          zoomOnPinch
+          zoomOnDoubleClick
+          preventScrolling={false}
+          nodesDraggable={false}
+          nodesConnectable={false}
+          elementsSelectable={false}
+        >
+          <Controls showInteractive={false} className="react-flow-controls-custom" />
+        </ReactFlow>
+      )}
+    </div>
+  );
+}
+
+ProviderTopology.propTypes = {
+  providers: PropTypes.arrayOf(PropTypes.shape({
+    id: PropTypes.string,
+    provider: PropTypes.string,
+    name: PropTypes.string,
+  })),
+  activeRequests: PropTypes.arrayOf(PropTypes.shape({
+    provider: PropTypes.string,
+    model: PropTypes.string,
+    account: PropTypes.string,
+  })),
+  lastProvider: PropTypes.string,
+  errorProvider: PropTypes.string,
+};
diff --git a/src/app/(dashboard)/dashboard/usage/components/RequestDetailsTab.js b/src/app/(dashboard)/dashboard/usage/components/RequestDetailsTab.js
new file mode 100644
index 0000000..af8eb73
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/components/RequestDetailsTab.js
@@ -0,0 +1,510 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import Card from "@/shared/components/Card";
+import Button from "@/shared/components/Button";
+import Drawer from "@/shared/components/Drawer";
+import Pagination from "@/shared/components/Pagination";
+import { cn } from "@/shared/utils/cn";
+import { AI_PROVIDERS, getProviderByAlias } from "@/shared/constants/providers";
+
+let providerNameCache = null;
+let providerNodesCache = null;
+
+async function fetchProviderNames() {
+  if (providerNameCache && providerNodesCache) {
+    return { providerNameCache, providerNodesCache };
+  }
+
+  const nodesRes = await fetch("/api/provider-nodes");
+  const nodesData = await nodesRes.json();
+  const nodes = nodesData.nodes || [];
+  providerNodesCache = {};
+
+  for (const node of nodes) {
+    providerNodesCache[node.id] = node.name;
+  }
+
+  providerNameCache = {
+    ...AI_PROVIDERS,
+    ...providerNodesCache
+  };
+
+  return { providerNameCache, providerNodesCache };
+}
+
+function getProviderName(providerId, cache) {
+  if (!providerId) return providerId;
+  if (!cache) return providerId;
+
+  const cached = cache[providerId];
+
+  if (typeof cached === 'string') {
+    return cached;
+  }
+
+  if (cached?.name) {
+    return cached.name;
+  }
+
+  const providerConfig = getProviderByAlias(providerId) || AI_PROVIDERS[providerId];
+  return providerConfig?.name || providerId;
+}
+
+function CollapsibleSection({ title, children, defaultOpen = false, icon = null }) {
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+  
+  return (
+    <div className="border border-black/5 dark:border-white/5 rounded-lg overflow-hidden">
+      <button 
+        type="button"
+        onClick={() => setIsOpen(!isOpen)}
+        className="w-full flex items-center justify-between p-3 bg-black/[0.02] dark:bg-white/[0.02] hover:bg-black/[0.04] dark:hover:bg-white/[0.04] transition-colors"
+      >
+        <div className="flex items-center gap-2">
+          {icon && <span className="material-symbols-outlined text-[18px] text-text-muted">{icon}</span>}
+          <span className="font-semibold text-sm text-text-main">{title}</span>
+        </div>
+        <span className={cn(
+          "material-symbols-outlined text-[20px] text-text-muted transition-transform duration-200",
+          isOpen ? "rotate-90" : ""
+        )}>
+          chevron_right
+        </span>
+      </button>
+      
+      {isOpen && (
+        <div className="p-4 border-t border-black/5 dark:border-white/5">
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function getCachedTokens(tokens) {
+  return tokens?.cached_tokens || tokens?.cache_read_input_tokens || 0;
+}
+
+function getCacheCreationTokens(tokens) {
+  return tokens?.cache_creation_input_tokens || 0;
+}
+
+function getInputTokens(tokens) {
+  const prompt = tokens?.prompt_tokens || tokens?.input_tokens || 0;
+  // Canonical storage keeps prompt cache-inclusive. Legacy Claude rows may have
+  // stored prompt cache-exclusive; fall back to cache when it's larger so old
+  // rows don't under-report input.
+  const cache = getCachedTokens(tokens);
+  return prompt < cache ? cache : prompt;
+}
+
+export default function RequestDetailsTab() {
+  const [details, setDetails] = useState([]);
+  const [pagination, setPagination] = useState({
+    page: 1,
+    pageSize: 20,
+    totalItems: 0,
+    totalPages: 0
+  });
+  const [loading, setLoading] = useState(false);
+  const [selectedDetail, setSelectedDetail] = useState(null);
+  const [isDrawerOpen, setIsDrawerOpen] = useState(false);
+  const [providers, setProviders] = useState([]);
+  const [providerNameCache, setProviderNameCache] = useState(null);
+  const [filters, setFilters] = useState({
+    provider: "",
+    startDate: "",
+    endDate: ""
+  });
+
+  const fetchProviders = useCallback(async () => {
+    try {
+      const res = await fetch("/api/usage/providers");
+      const data = await res.json();
+      setProviders(data.providers || []);
+
+      const cache = await fetchProviderNames();
+      setProviderNameCache(cache.providerNameCache);
+    } catch (error) {
+      console.error("Failed to fetch providers:", error);
+    }
+  }, []);
+
+  const fetchDetails = useCallback(async () => {
+    setLoading(true);
+    try {
+      const params = new URLSearchParams({
+        page: pagination.page.toString(),
+        pageSize: pagination.pageSize.toString()
+      });
+      if (filters.provider) params.append("provider", filters.provider);
+      if (filters.startDate) params.append("startDate", filters.startDate);
+      if (filters.endDate) params.append("endDate", filters.endDate);
+
+      const res = await fetch(`/api/usage/request-details?${params}`);
+      const data = await res.json();
+
+      setDetails(data.details || []);
+      setPagination(prev => ({ ...prev, ...data.pagination }));
+    } catch (error) {
+      console.error("Failed to fetch request details:", error);
+    } finally {
+      setLoading(false);
+    }
+  }, [pagination.page, pagination.pageSize, filters]);
+
+  useEffect(() => {
+    fetchProviders();
+  }, [fetchProviders]);
+
+  useEffect(() => {
+    fetchDetails();
+  }, [fetchDetails]);
+
+  const handleViewDetail = (detail) => {
+    setSelectedDetail(detail);
+    setIsDrawerOpen(true);
+  };
+
+  const handlePageChange = (newPage) => {
+    setPagination(prev => ({ ...prev, page: newPage }));
+  };
+
+  const handlePageSizeChange = (newPageSize) => {
+    setPagination(prev => ({ ...prev, pageSize: newPageSize, page: 1 }));
+  };
+
+  const handleClearFilters = () => {
+    setFilters({ provider: "", startDate: "", endDate: "" });
+  };
+
+  return (
+    <div className="flex min-w-0 flex-col gap-6">
+      <Card padding="md">
+        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
+          <div className="flex min-w-0 flex-col gap-2">
+            <label htmlFor="provider-filter" className="text-sm font-medium text-text-main">Provider</label>
+            <select
+              id="provider-filter"
+              value={filters.provider}
+              onChange={(e) => setFilters({ ...filters, provider: e.target.value })}
+              className={cn(
+                "h-9 px-3 rounded-lg border border-black/10 dark:border-white/10 bg-surface",
+                "text-sm text-text-main focus:outline-none focus:ring-2 focus:ring-primary/20",
+                "w-full min-w-0 cursor-pointer"
+              )}
+              style={{ colorScheme: 'auto' }}
+            >
+              <option value="">All Providers</option>
+              {providers.map((provider) => (
+                <option key={provider.id} value={provider.id}>
+                  {provider.name}
+                </option>
+              ))}
+            </select>
+          </div>
+          
+          <div className="flex min-w-0 flex-col gap-2">
+            <label htmlFor="start-date-filter" className="text-sm font-medium text-text-main">Start Date</label>
+            <input
+              id="start-date-filter"
+              type="datetime-local"
+              value={filters.startDate}
+              onChange={(e) => setFilters({ ...filters, startDate: e.target.value })}
+              className={cn(
+                "h-9 px-3 rounded-lg border border-black/10 dark:border-white/10 bg-surface",
+                "w-full min-w-0 text-sm text-text-main focus:outline-none focus:ring-2 focus:ring-primary/20"
+              )}
+            />
+          </div>
+
+          <div className="flex min-w-0 flex-col gap-2">
+            <label htmlFor="end-date-filter" className="text-sm font-medium text-text-main">End Date</label>
+            <input
+              id="end-date-filter"
+              type="datetime-local"
+              value={filters.endDate}
+              onChange={(e) => setFilters({ ...filters, endDate: e.target.value })}
+              className={cn(
+                "h-9 px-3 rounded-lg border border-black/10 dark:border-white/10 bg-surface",
+                "w-full min-w-0 text-sm text-text-main focus:outline-none focus:ring-2 focus:ring-primary/20"
+              )}
+            />
+          </div>
+          
+          <div className="flex min-w-0 flex-col gap-2 sm:col-span-2 lg:col-span-1">
+            <span className="hidden text-sm font-medium text-text-main opacity-0 lg:block" aria-hidden="true">Clear</span>
+            <Button 
+              variant="ghost" 
+              onClick={handleClearFilters}
+              disabled={!filters.provider && !filters.startDate && !filters.endDate}
+              className="w-full"
+            >
+              Clear Filters
+            </Button>
+          </div>
+        </div>
+      </Card>
+
+      <Card padding="none">
+        <div className="overflow-x-auto">
+          <table className="w-full min-w-[880px]">
+            <thead>
+              <tr className="border-b border-black/5 dark:border-white/5">
+                <th className="text-left p-4 text-sm font-semibold text-text-main">Timestamp</th>
+                <th className="text-left p-4 text-sm font-semibold text-text-main">Model</th>
+                <th className="text-left p-4 text-sm font-semibold text-text-main">Provider</th>
+                <th className="text-right p-4 text-sm font-semibold text-text-main">Input Tokens</th>
+                <th className="text-right p-4 text-sm font-semibold text-text-main">Cached</th>
+                <th className="text-right p-4 text-sm font-semibold text-text-main">Cache Creation</th>
+                <th className="text-right p-4 text-sm font-semibold text-text-main">Output Tokens</th>
+                <th className="text-left p-4 text-sm font-semibold text-text-main">Latency</th>
+                <th className="text-center p-4 text-sm font-semibold text-text-main">Action</th>
+              </tr>
+            </thead>
+            <tbody>
+              {loading ? (
+                <tr>
+                  <td colSpan="7" className="p-8 text-center text-text-muted">
+                    <div className="flex items-center justify-center gap-2">
+                      <span className="material-symbols-outlined animate-spin text-[20px]">progress_activity</span>
+                      Loading...
+                    </div>
+                  </td>
+                </tr>
+              ) : details.length === 0 ? (
+                <tr>
+                  <td colSpan="7" className="p-8 text-center text-text-muted">
+                    No request details found
+                  </td>
+                </tr>
+              ) : (
+                details.map((detail, index) => (
+                  <tr
+                    key={`${detail.id}-${index}`}
+                    className="border-b border-black/5 dark:border-white/5 last:border-b-0 hover:bg-black/[0.02] dark:hover:bg-white/[0.02] transition-colors"
+                  >
+                    <td className="whitespace-nowrap p-4 text-sm text-text-main">
+                      {new Date(detail.timestamp).toLocaleString()}
+                    </td>
+                    <td className="max-w-[260px] truncate p-4 font-mono text-sm text-text-main">
+                      {detail.model}
+                    </td>
+                    <td className="max-w-[180px] truncate p-4 text-sm text-text-main">
+                       <span className="font-medium">
+                         {getProviderName(detail.provider, providerNameCache)}
+                       </span>
+                     </td>
+                    <td className="p-4 text-sm text-text-main text-right font-mono">
+                      {getInputTokens(detail.tokens).toLocaleString()}
+                    </td>
+                    <td className="p-4 text-sm text-text-main text-right font-mono">
+                      {getCachedTokens(detail.tokens) > 0 ? getCachedTokens(detail.tokens).toLocaleString() : "—"}
+                    </td>
+                    <td className="p-4 text-sm text-text-main text-right font-mono">
+                      {getCacheCreationTokens(detail.tokens) > 0 ? getCacheCreationTokens(detail.tokens).toLocaleString() : "—"}
+                    </td>
+                    <td className="p-4 text-sm text-text-main text-right font-mono">
+                      {detail.tokens?.completion_tokens?.toLocaleString() || 0}
+                    </td>
+                    <td className="p-4 text-sm text-text-muted">
+                      <div className="flex flex-col gap-0.5">
+                        <div>TTFT: <span className="font-mono">{detail.latency?.ttft || 0}ms</span></div>
+                        <div>Total: <span className="font-mono">{detail.latency?.total || 0}ms</span></div>
+                      </div>
+                    </td>
+                    <td className="p-4 text-center">
+                      <Button
+                        variant="outline"
+                        size="sm"
+                        onClick={() => handleViewDetail(detail)}
+                      >
+                        Detail
+                      </Button>
+                    </td>
+                  </tr>
+                ))
+              )}
+            </tbody>
+          </table>
+        </div>
+
+        {!loading && details.length > 0 && (
+          <div className="border-t border-black/5 dark:border-white/5">
+            <Pagination
+              currentPage={pagination.page}
+              pageSize={pagination.pageSize}
+              totalItems={pagination.totalItems}
+              onPageChange={handlePageChange}
+              onPageSizeChange={handlePageSizeChange}
+            />
+          </div>
+        )}
+      </Card>
+
+      <Drawer
+        isOpen={isDrawerOpen}
+        onClose={() => setIsDrawerOpen(false)}
+        title="Request Details"
+        width="lg"
+      >
+        {selectedDetail && (
+          <div className="space-y-6">
+            <div className="grid min-w-0 grid-cols-1 gap-4 text-sm sm:grid-cols-2">
+              <div>
+                <span className="text-text-muted">ID:</span>{" "}
+                <span className="break-all font-mono text-text-main">{selectedDetail.id}</span>
+              </div>
+              <div>
+                <span className="text-text-muted">Timestamp:</span>{" "}
+                <span className="text-text-main">{new Date(selectedDetail.timestamp).toLocaleString()}</span>
+              </div>
+              <div>
+                 <span className="text-text-muted">Provider:</span>{" "}
+                 <span className="text-text-main font-medium">{getProviderName(selectedDetail.provider, providerNameCache)}</span>
+               </div>
+              <div>
+                <span className="text-text-muted">Model:</span>{" "}
+                <span className="text-text-main font-mono">{selectedDetail.model}</span>
+              </div>
+              <div>
+                <span className="text-text-muted">Status:</span>{" "}
+                <span className={cn(
+                  "font-medium",
+                  selectedDetail.status === "success" ? "text-green-600" : "text-red-600"
+                )}>
+                  {selectedDetail.status}
+                </span>
+              </div>
+              <div>
+                <span className="text-text-muted">Latency:</span>{" "}
+                <span className="text-text-main font-mono">
+                  TTFT {selectedDetail.latency?.ttft || 0}ms / Total {selectedDetail.latency?.total || 0}ms
+                </span>
+              </div>
+              <div>
+                <span className="text-text-muted">Input Tokens:</span>{" "}
+                <span className="text-text-main font-mono">
+                  {getInputTokens(selectedDetail.tokens).toLocaleString()}
+                </span>
+              </div>
+              {getCachedTokens(selectedDetail.tokens) > 0 && (
+                <div>
+                  <span className="text-text-muted">Cached Tokens:</span>{" "}
+                  <span className="text-text-main font-mono">
+                    {getCachedTokens(selectedDetail.tokens).toLocaleString()}
+                  </span>
+                </div>
+              )}
+              {getCacheCreationTokens(selectedDetail.tokens) > 0 && (
+                <div>
+                  <span className="text-text-muted">Cache Creation:</span>{" "}
+                  <span className="text-text-main font-mono">
+                    {getCacheCreationTokens(selectedDetail.tokens).toLocaleString()}
+                  </span>
+                </div>
+              )}
+              <div>
+                <span className="text-text-muted">Output Tokens:</span>{" "}
+                <span className="text-text-main font-mono">
+                  {selectedDetail.tokens?.completion_tokens?.toLocaleString() || 0}
+                </span>
+              </div>
+            </div>
+
+            {selectedDetail.pxpipe && (
+              <div className="rounded-lg border border-black/5 dark:border-white/5 p-4">
+                <div className="flex items-center gap-2 mb-2">
+                  <span className="material-symbols-outlined text-[18px] text-text-muted">image</span>
+                  <span className="font-semibold text-sm text-text-main">PXPIPE</span>
+                  <span className={cn(
+                    "text-xs px-2 py-0.5 rounded",
+                    selectedDetail.pxpipe.applied
+                      ? "bg-green-500/15 text-green-600"
+                      : "bg-amber-500/15 text-amber-600"
+                  )}>
+                    {selectedDetail.pxpipe.applied ? "Activated" : "Skipped"}
+                  </span>
+                </div>
+                {selectedDetail.pxpipe.applied ? (
+                  <div className="grid grid-cols-2 gap-2 text-sm sm:grid-cols-4">
+                    <div>
+                      <span className="text-text-muted block text-xs">Original (est.)</span>
+                      <span className="font-mono">{(selectedDetail.pxpipe.tokensBeforeEst || 0).toLocaleString()} tokens</span>
+                    </div>
+                    <div>
+                      <span className="text-text-muted block text-xs">Compressed (est.)</span>
+                      <span className="font-mono">{(selectedDetail.pxpipe.tokensAfterEst || 0).toLocaleString()} tokens</span>
+                    </div>
+                    <div>
+                      <span className="text-text-muted block text-xs">Saved</span>
+                      <span className="font-mono text-green-600">{selectedDetail.pxpipe.savedPct || 0}%</span>
+                    </div>
+                    <div>
+                      <span className="text-text-muted block text-xs">Images</span>
+                      <span className="font-mono">{selectedDetail.pxpipe.imageCount || 0} ({selectedDetail.pxpipe.durationMs || 0}ms)</span>
+                    </div>
+                  </div>
+                ) : (
+                  <p className="text-sm text-text-muted">
+                    Reason: <span className="font-mono">{selectedDetail.pxpipe.reason}</span>
+                    {selectedDetail.pxpipe.detail ? ` — ${selectedDetail.pxpipe.detail}` : ""}
+                  </p>
+                )}
+              </div>
+            )}
+
+            <div className="space-y-4">
+              <CollapsibleSection title="1. Client Request (Input)" defaultOpen={true} icon="input">
+                <pre className="max-h-[300px] max-w-full overflow-auto rounded-lg border border-black/5 bg-black/5 p-3 font-mono text-xs text-text-main dark:border-white/5 dark:bg-white/5 sm:p-4">
+                  {JSON.stringify(selectedDetail.request, null, 2)}
+                </pre>
+              </CollapsibleSection>
+
+              {selectedDetail.providerRequest && (
+                <CollapsibleSection title="2. Provider Request (Translated)" icon="translate">
+                  <pre className="max-h-[300px] max-w-full overflow-auto rounded-lg border border-black/5 bg-black/5 p-3 font-mono text-xs text-text-main dark:border-white/5 dark:bg-white/5 sm:p-4">
+                    {JSON.stringify(selectedDetail.providerRequest, null, 2)}
+                  </pre>
+                </CollapsibleSection>
+              )}
+
+              {selectedDetail.providerResponse && (
+                <CollapsibleSection title="3. Provider Response (Raw)" icon="data_object">
+                  <pre className="max-h-[300px] max-w-full overflow-auto rounded-lg border border-black/5 bg-black/5 p-3 font-mono text-xs text-text-main dark:border-white/5 dark:bg-white/5 sm:p-4">
+                    {typeof selectedDetail.providerResponse === 'object'
+                      ? JSON.stringify(selectedDetail.providerResponse, null, 2)
+                      : selectedDetail.providerResponse
+                    }
+                  </pre>
+                </CollapsibleSection>
+              )}
+              
+              <CollapsibleSection title="4. Client Response (Final)" defaultOpen={true} icon="output">
+                {selectedDetail.response?.thinking && (
+                  <div className="mb-4">
+                    <h4 className="font-semibold text-text-main mb-2 flex items-center gap-2 text-xs uppercase tracking-wide opacity-70">
+                      <span className="material-symbols-outlined text-[16px]">psychology</span>
+                      Thinking Process
+                    </h4>
+                    <pre className="max-h-[200px] max-w-full overflow-auto rounded-lg border border-amber-200 bg-amber-50 p-3 font-mono text-xs text-amber-900 dark:border-amber-800 dark:bg-amber-950/30 dark:text-amber-100 sm:p-4">
+                      {selectedDetail.response.thinking}
+                    </pre>
+                  </div>
+                )}
+                
+                <h4 className="font-semibold text-text-main mb-2 text-xs uppercase tracking-wide opacity-70">
+                  Content
+                </h4>
+                <pre className="max-h-[300px] max-w-full overflow-auto rounded-lg border border-black/5 bg-black/5 p-3 font-mono text-xs text-text-main dark:border-white/5 dark:bg-white/5 sm:p-4">
+                  {selectedDetail.response?.content || "[No content]"}
+                </pre>
+              </CollapsibleSection>
+            </div>
+          </div>
+        )}
+      </Drawer>
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/dashboard/usage/components/UsageChart.js b/src/app/(dashboard)/dashboard/usage/components/UsageChart.js
new file mode 100644
index 0000000..14a19c4
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/components/UsageChart.js
@@ -0,0 +1,141 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import PropTypes from "prop-types";
+import {
+  AreaChart,
+  Area,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  ResponsiveContainer,
+  Legend,
+} from "recharts";
+import Card from "@/shared/components/Card";
+
+const fmtTokens = (n) => {
+  if (n >= 1000000) return `${(n / 1000000).toFixed(1)}M`;
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}K`;
+  return String(n || 0);
+};
+
+const fmtCost = (n) => `$${(n || 0).toFixed(4)}`;
+
+export default function UsageChart({ period = "7d" }) {
+  const [data, setData] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [viewMode, setViewMode] = useState("tokens");
+
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    try {
+      const res = await fetch(`/api/usage/chart?period=${period}`);
+      if (res.ok) {
+        const json = await res.json();
+        setData(json);
+      }
+    } catch (e) {
+      console.error("Failed to fetch chart data:", e);
+    } finally {
+      setLoading(false);
+    }
+  }, [period]);
+
+  useEffect(() => {
+    fetchData();
+  }, [fetchData]);
+
+  const hasData = data.some((d) => d.tokens > 0 || d.cost > 0);
+
+  return (
+    <Card className="flex min-w-0 flex-col gap-3 p-3 sm:p-4">
+      <div className="grid w-full grid-cols-2 items-center gap-1 rounded-lg border border-border bg-bg-subtle p-1 sm:w-auto sm:self-start">
+        <button
+          onClick={() => setViewMode("tokens")}
+          className={`px-3 py-1 rounded-md text-sm font-medium transition-colors ${viewMode === "tokens" ? "bg-primary text-white shadow-sm" : "text-text-muted hover:text-text hover:bg-bg-hover"}`}
+        >
+          Tokens
+        </button>
+        <button
+          onClick={() => setViewMode("cost")}
+          className={`px-3 py-1 rounded-md text-sm font-medium transition-colors ${viewMode === "cost" ? "bg-primary text-white shadow-sm" : "text-text-muted hover:text-text hover:bg-bg-hover"}`}
+        >
+          Cost
+        </button>
+      </div>
+
+      {loading ? (
+        <div className="h-48 flex items-center justify-center text-text-muted text-sm">Loading...</div>
+      ) : !hasData ? (
+        <div className="h-48 flex items-center justify-center text-text-muted text-sm">No data for this period</div>
+      ) : (
+        <ResponsiveContainer width="100%" height={220}>
+          <AreaChart data={data} margin={{ top: 4, right: 8, left: 0, bottom: 0 }}>
+            <defs>
+              <linearGradient id="gradTokens" x1="0" y1="0" x2="0" y2="1">
+                <stop offset="5%" stopColor="#6366f1" stopOpacity={0.25} />
+                <stop offset="95%" stopColor="#6366f1" stopOpacity={0} />
+              </linearGradient>
+              <linearGradient id="gradCost" x1="0" y1="0" x2="0" y2="1">
+                <stop offset="5%" stopColor="#f59e0b" stopOpacity={0.25} />
+                <stop offset="95%" stopColor="#f59e0b" stopOpacity={0} />
+              </linearGradient>
+            </defs>
+            <CartesianGrid strokeDasharray="3 3" strokeOpacity={0.1} />
+            <XAxis
+              dataKey="label"
+              tick={{ fontSize: 10, fill: "currentColor", fillOpacity: 0.5 }}
+              tickLine={false}
+              axisLine={false}
+              interval="preserveStartEnd"
+            />
+            <YAxis
+              tick={{ fontSize: 10, fill: "currentColor", fillOpacity: 0.5 }}
+              tickLine={false}
+              axisLine={false}
+              tickFormatter={viewMode === "tokens" ? fmtTokens : fmtCost}
+              width={50}
+            />
+            <Tooltip
+              contentStyle={{
+                backgroundColor: "var(--color-bg)",
+                border: "1px solid var(--color-border)",
+                borderRadius: "8px",
+                fontSize: "12px",
+              }}
+              formatter={(value, name) =>
+                name === "tokens" ? [fmtTokens(value), "Tokens"] : [fmtCost(value), "Cost"]
+              }
+            />
+            {viewMode === "tokens" ? (
+              <Area
+                type="monotone"
+                dataKey="tokens"
+                stroke="#6366f1"
+                strokeWidth={2}
+                fill="url(#gradTokens)"
+                dot={false}
+                activeDot={{ r: 4 }}
+              />
+            ) : (
+              <Area
+                type="monotone"
+                dataKey="cost"
+                stroke="#f59e0b"
+                strokeWidth={2}
+                fill="url(#gradCost)"
+                dot={false}
+                activeDot={{ r: 4 }}
+              />
+            )}
+          </AreaChart>
+        </ResponsiveContainer>
+      )}
+    </Card>
+  );
+}
+
+UsageChart.propTypes = {
+  period: PropTypes.string,
+};
diff --git a/src/app/(dashboard)/dashboard/usage/components/UsageTable.js b/src/app/(dashboard)/dashboard/usage/components/UsageTable.js
new file mode 100644
index 0000000..9da3c3e
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/components/UsageTable.js
@@ -0,0 +1,255 @@
+"use client";
+
+import { useState, useEffect, useCallback, useMemo, Fragment } from "react";
+import PropTypes from "prop-types";
+import Card from "@/shared/components/Card";
+import Badge from "@/shared/components/Badge";
+
+const fmt = (n) => new Intl.NumberFormat().format(n || 0);
+const fmtCost = (n) => `$${(n || 0).toFixed(2)}`;
+
+function fmtTime(iso) {
+  if (!iso) return "Never";
+  const diffMins = Math.floor((Date.now() - new Date(iso)) / 60000);
+  if (diffMins < 1) return "Just now";
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffMins < 1440) return `${Math.floor(diffMins / 60)}h ago`;
+  return new Date(iso).toLocaleDateString();
+}
+
+function SortIcon({ field, currentSort, currentOrder }) {
+  if (currentSort !== field) return <span className="ml-1 opacity-20">↕</span>;
+  return <span className="ml-1">{currentOrder === "asc" ? "↑" : "↓"}</span>;
+}
+
+SortIcon.propTypes = {
+  field: PropTypes.string.isRequired,
+  currentSort: PropTypes.string.isRequired,
+  currentOrder: PropTypes.string.isRequired,
+};
+
+/**
+ * Render 3 token or cost cells based on viewMode
+ */
+function ValueCells({ item, viewMode, isSummary = false }) {
+  if (viewMode === "tokens") {
+    return (
+      <>
+        <td className="px-6 py-3 text-right text-text-muted">
+          {isSummary && item.promptTokens === undefined ? "—" : fmt(item.promptTokens)}
+        </td>
+        <td className="px-6 py-3 text-right text-text-muted">
+          {item.cachedTokens ? fmt(item.cachedTokens) : "—"}
+        </td>
+        <td className="px-6 py-3 text-right text-text-muted">
+          {isSummary && item.completionTokens === undefined ? "—" : fmt(item.completionTokens)}
+        </td>
+        <td className="px-6 py-3 text-right font-medium">
+          {fmt(item.totalTokens)}
+        </td>
+      </>
+    );
+  }
+  return (
+    <>
+      <td className="px-6 py-3 text-right text-text-muted">
+        {isSummary && item.inputCost === undefined ? "—" : fmtCost(item.inputCost)}
+      </td>
+      <td className="px-6 py-3 text-right text-text-muted">
+        {item.cachedCost ? fmtCost(item.cachedCost) : "—"}
+      </td>
+      <td className="px-6 py-3 text-right text-text-muted">
+        {isSummary && item.outputCost === undefined ? "—" : fmtCost(item.outputCost)}
+      </td>
+      <td className="px-6 py-3 text-right font-medium text-warning">
+        {fmtCost(item.totalCost || item.cost)}
+      </td>
+    </>
+  );
+}
+
+ValueCells.propTypes = {
+  item: PropTypes.object.isRequired,
+  viewMode: PropTypes.string.isRequired,
+  isSummary: PropTypes.bool,
+};
+
+/**
+ * Reusable sortable usage table with expandable group rows.
+ *
+ * @param {object} props
+ * @param {string} props.title - Table title
+ * @param {Array} props.columns - Column definitions [{field, label}]
+ * @param {Array} props.groupedData - Grouped data from groupDataByKey
+ * @param {string} props.tableType - Table type key for sort URL params
+ * @param {string} props.sortBy - Current sort field
+ * @param {string} props.sortOrder - Current sort order
+ * @param {function} props.onToggleSort - Sort toggle handler
+ * @param {string} props.viewMode - "tokens" or "costs"
+ * @param {string} props.storageKey - localStorage key for expanded state
+ * @param {function} props.renderGroupLabel - Render group summary first cell content
+ * @param {function} props.renderDetailCells - Render detail row custom cells (before value cells)
+ * @param {function} props.renderSummaryCells - Render summary row cells after group label (placeholder cols)
+ * @param {string} props.emptyMessage - Empty state message
+ */
+export default function UsageTable({
+  title,
+  columns,
+  groupedData,
+  tableType,
+  sortBy,
+  sortOrder,
+  onToggleSort,
+  viewMode,
+  storageKey,
+  renderDetailCells,
+  renderSummaryCells,
+  emptyMessage,
+}) {
+  const [expanded, setExpanded] = useState(new Set());
+
+  // Load expanded state from localStorage
+  useEffect(() => {
+    try {
+      const saved = localStorage.getItem(storageKey);
+      if (saved) setExpanded(new Set(JSON.parse(saved)));
+    } catch (e) {
+      console.error(`Failed to load ${storageKey}:`, e);
+    }
+  }, [storageKey]);
+
+  // Save expanded state to localStorage
+  useEffect(() => {
+    try {
+      localStorage.setItem(storageKey, JSON.stringify([...expanded]));
+    } catch (e) {
+      console.error(`Failed to save ${storageKey}:`, e);
+    }
+  }, [expanded, storageKey]);
+
+  const toggleGroup = useCallback((groupKey) => {
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      next.has(groupKey) ? next.delete(groupKey) : next.add(groupKey);
+      return next;
+    });
+  }, []);
+
+  const valueColumns = useMemo(() => {
+    if (viewMode === "tokens") {
+      return [
+        { field: "promptTokens", label: "Input Tokens" },
+        { field: "cachedTokens", label: "Cached" },
+        { field: "completionTokens", label: "Output Tokens" },
+        { field: "totalTokens", label: "Total Tokens" },
+      ];
+    }
+    return [
+      { field: "promptTokens", label: "Input Cost" },
+      { field: "cachedCost", label: "Cached Cost" },
+      { field: "completionTokens", label: "Output Cost" },
+      { field: "cost", label: "Total Cost" },
+    ];
+  }, [viewMode]);
+
+  const totalColSpan = columns.length + valueColumns.length;
+
+  return (
+    <Card className="overflow-hidden">
+      <div className="p-4 border-b border-border bg-bg-subtle/50">
+        <h3 className="font-semibold">{title}</h3>
+      </div>
+      <div className="overflow-x-auto">
+        <table className="w-full text-sm text-left">
+          <thead className="bg-bg-subtle/30 text-text-muted uppercase text-xs">
+            <tr>
+              {columns.map((col) => (
+                <th
+                  key={col.field}
+                  className={`px-6 py-3 cursor-pointer hover:bg-bg-subtle/50 ${col.align === "right" ? "text-right" : ""}`}
+                  onClick={() => onToggleSort(tableType, col.field)}
+                >
+                  {col.label}{" "}
+                  <SortIcon field={col.field} currentSort={sortBy} currentOrder={sortOrder} />
+                </th>
+              ))}
+              {valueColumns.map((col) => (
+                <th
+                  key={col.field}
+                  className="px-6 py-3 text-right cursor-pointer hover:bg-bg-subtle/50"
+                  onClick={() => onToggleSort(tableType, col.field)}
+                >
+                  {col.label}{" "}
+                  <SortIcon field={col.field} currentSort={sortBy} currentOrder={sortOrder} />
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody className="divide-y divide-border">
+            {groupedData.map((group) => (
+              <Fragment key={group.groupKey}>
+                {/* Group summary row */}
+                <tr
+                  className="group-summary cursor-pointer hover:bg-bg-subtle/50 transition-colors"
+                  onClick={() => toggleGroup(group.groupKey)}
+                >
+                  <td className="px-6 py-3">
+                    <div className="flex items-center gap-2">
+                      <span className={`material-symbols-outlined text-[18px] text-text-muted transition-transform ${expanded.has(group.groupKey) ? "rotate-90" : ""}`}>
+                        chevron_right
+                      </span>
+                      <span className={`font-medium transition-colors ${group.summary.pending > 0 ? "text-primary" : ""}`}>
+                        {group.groupKey}
+                      </span>
+                    </div>
+                  </td>
+                  {renderSummaryCells(group)}
+                  <ValueCells item={group.summary} viewMode={viewMode} isSummary />
+                </tr>
+                {/* Detail rows */}
+                {expanded.has(group.groupKey) && group.items.map((item) => (
+                  <tr
+                    key={`detail-${item.key}`}
+                    className="group-detail hover:bg-bg-subtle/20 transition-colors"
+                  >
+                    {renderDetailCells(item)}
+                    <ValueCells item={item} viewMode={viewMode} />
+                  </tr>
+                ))}
+              </Fragment>
+            ))}
+            {groupedData.length === 0 && (
+              <tr>
+                <td colSpan={totalColSpan} className="px-6 py-8 text-center text-text-muted">
+                  {emptyMessage}
+                </td>
+              </tr>
+            )}
+          </tbody>
+        </table>
+      </div>
+    </Card>
+  );
+}
+
+UsageTable.propTypes = {
+  title: PropTypes.string.isRequired,
+  columns: PropTypes.arrayOf(PropTypes.shape({
+    field: PropTypes.string.isRequired,
+    label: PropTypes.string.isRequired,
+    align: PropTypes.string,
+  })).isRequired,
+  groupedData: PropTypes.array.isRequired,
+  tableType: PropTypes.string.isRequired,
+  sortBy: PropTypes.string.isRequired,
+  sortOrder: PropTypes.string.isRequired,
+  onToggleSort: PropTypes.func.isRequired,
+  viewMode: PropTypes.string.isRequired,
+  storageKey: PropTypes.string.isRequired,
+  renderDetailCells: PropTypes.func.isRequired,
+  renderSummaryCells: PropTypes.func.isRequired,
+  emptyMessage: PropTypes.string.isRequired,
+};
+
+// Re-export utilities for use in UsageStats orchestrator
+export { fmt, fmtCost, fmtTime };
diff --git a/src/app/(dashboard)/dashboard/usage/page.js b/src/app/(dashboard)/dashboard/usage/page.js
new file mode 100644
index 0000000..075b211
--- /dev/null
+++ b/src/app/(dashboard)/dashboard/usage/page.js
@@ -0,0 +1,75 @@
+"use client";
+
+import { Suspense, useState } from "react";
+import { useSearchParams, useRouter } from "next/navigation";
+import { UsageStats, RequestLogger, CardSkeleton, SegmentedControl } from "@/shared/components";
+import RequestDetailsTab from "./components/RequestDetailsTab";
+
+const PERIODS = [
+  { value: "today", label: "Today" },
+  { value: "24h", label: "24h" },
+  { value: "7d", label: "7D" },
+  { value: "30d", label: "30D" },
+  { value: "60d", label: "60D" },
+];
+
+export default function UsagePage() {
+  return (
+    <Suspense fallback={<CardSkeleton />}>
+      <UsageContent />
+    </Suspense>
+  );
+}
+
+function UsageContent() {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+
+  const [period, setPeriod] = useState("today");
+
+  const tabFromUrl = searchParams.get("tab");
+  const activeTab = tabFromUrl && ["overview", "logs", "details"].includes(tabFromUrl)
+    ? tabFromUrl
+    : "overview";
+
+  const handleTabChange = (value) => {
+    if (value === activeTab) return;
+    const params = new URLSearchParams(searchParams);
+    params.set("tab", value);
+    router.push(`/dashboard/usage?${params.toString()}`, { scroll: false });
+  };
+
+  return (
+    <div className="flex min-w-0 flex-col gap-6 px-1 sm:px-0">
+      {/* Tabs + period selector on same row */}
+      <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+        <SegmentedControl
+          options={[
+            { value: "overview", label: "Overview" },
+            { value: "details", label: "Details" },
+          ]}
+          value={activeTab}
+          onChange={handleTabChange}
+          className="w-full sm:w-auto"
+        />
+        {activeTab === "overview" && (
+          <SegmentedControl
+            options={PERIODS}
+            value={period}
+            onChange={setPeriod}
+            size="sm"
+            className="w-full sm:w-auto"
+          />
+        )}
+      </div>
+
+      {activeTab === "overview" && (
+        <Suspense fallback={<CardSkeleton />}>
+          <UsageStats period={period} setPeriod={setPeriod} hidePeriodSelector />
+        </Suspense>
+      )}
+      {activeTab === "logs" && <RequestLogger />}
+      {activeTab === "details" && <RequestDetailsTab />}
+    </div>
+  );
+}
diff --git a/src/app/(dashboard)/layout.js b/src/app/(dashboard)/layout.js
new file mode 100644
index 0000000..5ef563e
--- /dev/null
+++ b/src/app/(dashboard)/layout.js
@@ -0,0 +1,6 @@
+import { DashboardLayout } from "@/shared/components";
+
+export default function DashboardRootLayout({ children }) {
+  return <DashboardLayout>{children}</DashboardLayout>;
+}
+
diff --git a/src/app/api/auth/login/route.js b/src/app/api/auth/login/route.js
new file mode 100644
index 0000000..cbd3c6a
--- /dev/null
+++ b/src/app/api/auth/login/route.js
@@ -0,0 +1,83 @@
+import { NextResponse } from "next/server";
+import { getSettings } from "@/lib/localDb";
+import bcrypt from "bcryptjs";
+import { cookies } from "next/headers";
+import { setDashboardAuthCookie } from "@/lib/auth/dashboardSession";
+import { isOidcConfigured } from "@/lib/auth/oidc";
+import { checkLock, recordFail, recordSuccess, getClientIp } from "@/lib/auth/loginLimiter";
+import { isLocalRequest } from "@/dashboardGuard";
+
+const RESET_HINT = "Forgot password? Reset to default via 9Router CLI → Settings → Reset Password to Default.";
+const NO_STORE_HEADERS = { "Cache-Control": "no-store" };
+
+function isTunnelRequest(request, settings) {
+  const host = (request.headers.get("host") || "").split(":")[0].toLowerCase();
+  const tunnelHost = settings.tunnelUrl ? new URL(settings.tunnelUrl).hostname.toLowerCase() : "";
+  const tailscaleHost = settings.tailscaleUrl ? new URL(settings.tailscaleUrl).hostname.toLowerCase() : "";
+  return (tunnelHost && host === tunnelHost) || (tailscaleHost && host === tailscaleHost);
+}
+
+export async function POST(request) {
+  try {
+    const ip = getClientIp(request);
+    const lock = checkLock(ip);
+    if (lock.locked) {
+      return NextResponse.json(
+        { error: `Too many failed attempts. Try again in ${lock.retryAfter}s. ${RESET_HINT}`, retryAfter: lock.retryAfter, resetHint: RESET_HINT },
+        { status: 429, headers: { "Retry-After": String(lock.retryAfter) } }
+      );
+    }
+
+    const { password } = await request.json();
+    const settings = await getSettings();
+
+    // Block login via tunnel/tailscale if dashboard access is disabled
+    if (isTunnelRequest(request, settings) && settings.tunnelDashboardAccess !== true) {
+      return NextResponse.json({ error: "Dashboard access via tunnel is disabled" }, { status: 403 });
+    }
+
+    // Default password is '123456' if not set
+    const storedHash = settings.password;
+
+    if (settings.authMode === "oidc" && isOidcConfigured(settings)) {
+      return NextResponse.json({ error: "Password login is disabled. Use OIDC sign in." }, { status: 403 });
+    }
+
+    let isValid = false;
+    if (storedHash) {
+      isValid = await bcrypt.compare(password, storedHash);
+    } else {
+      // Use env var or default
+      const initialPassword = process.env.INITIAL_PASSWORD || "123456";
+      isValid = password === initialPassword;
+    }
+
+    if (isValid) {
+      recordSuccess(ip);
+      const cookieStore = await cookies();
+      await setDashboardAuthCookie(cookieStore, request);
+
+      // Default password still in use on a remote client → force a password
+      // change before the dashboard is exposed remotely (keeps local UX intact).
+      const mustChangePassword =
+        !storedHash && !process.env.INITIAL_PASSWORD && !isLocalRequest(request);
+
+      return NextResponse.json({ success: true, mustChangePassword }, { headers: NO_STORE_HEADERS });
+    }
+
+    const { remainingBeforeLock } = recordFail(ip);
+    const postLock = checkLock(ip);
+    if (postLock.locked) {
+      return NextResponse.json(
+        { error: `Too many failed attempts. Try again in ${postLock.retryAfter}s. ${RESET_HINT}`, retryAfter: postLock.retryAfter, resetHint: RESET_HINT },
+        { status: 429, headers: { "Retry-After": String(postLock.retryAfter) } }
+      );
+    }
+    return NextResponse.json(
+      { error: `Invalid password. ${remainingBeforeLock} attempt(s) left before lockout.`, remainingBeforeLock },
+      { status: 401 }
+    );
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/auth/logout/route.js b/src/app/api/auth/logout/route.js
new file mode 100644
index 0000000..2b0fa5c
--- /dev/null
+++ b/src/app/api/auth/logout/route.js
@@ -0,0 +1,12 @@
+import { NextResponse } from "next/server";
+import { cookies } from "next/headers";
+import { clearDashboardAuthCookie } from "@/lib/auth/dashboardSession";
+
+export async function POST() {
+  const cookieStore = await cookies();
+  clearDashboardAuthCookie(cookieStore);
+  cookieStore.delete("oidc_state");
+  cookieStore.delete("oidc_nonce");
+  cookieStore.delete("oidc_code_verifier");
+  return NextResponse.json({ success: true }, { headers: { "Cache-Control": "no-store" } });
+}
diff --git a/src/app/api/auth/oidc/callback/route.js b/src/app/api/auth/oidc/callback/route.js
new file mode 100644
index 0000000..2e6a253
--- /dev/null
+++ b/src/app/api/auth/oidc/callback/route.js
@@ -0,0 +1,87 @@
+import { NextResponse } from "next/server";
+import { cookies } from "next/headers";
+import {
+  exchangeOidcCode,
+  fetchOidcDiscovery,
+  getOidcRuntimeConfig,
+  getPublicOrigin,
+  pickOidcDisplayName,
+  pickOidcEmail,
+  verifyOidcIdToken,
+} from "@/lib/auth/oidc";
+import { setDashboardAuthCookie } from "@/lib/auth/dashboardSession";
+
+function clearOidcCookies(cookieStore) {
+  cookieStore.delete("oidc_state");
+  cookieStore.delete("oidc_nonce");
+  cookieStore.delete("oidc_code_verifier");
+}
+
+export async function GET(request) {
+  const url = new URL(request.url);
+  const error = url.searchParams.get("error");
+  if (error) {
+    return NextResponse.redirect(new URL(`/login?error=${encodeURIComponent(error)}`, getPublicOrigin(request)));
+  }
+
+  const code = url.searchParams.get("code");
+  const state = url.searchParams.get("state");
+  if (!code || !state) {
+    return NextResponse.redirect(new URL("/login?error=oidc_missing_code", getPublicOrigin(request)));
+  }
+
+  const cookieStore = await cookies();
+  const storedState = cookieStore.get("oidc_state")?.value;
+  const storedNonce = cookieStore.get("oidc_nonce")?.value;
+  const codeVerifier = cookieStore.get("oidc_code_verifier")?.value;
+
+  if (!storedState || !storedNonce || !codeVerifier || storedState !== state) {
+    clearOidcCookies(cookieStore);
+    return NextResponse.redirect(new URL("/login?error=oidc_invalid_state", getPublicOrigin(request)));
+  }
+
+  try {
+    const config = await getOidcRuntimeConfig();
+    if (!config) {
+      clearOidcCookies(cookieStore);
+      return NextResponse.redirect(new URL("/login?error=oidc_not_configured", getPublicOrigin(request)));
+    }
+
+    const discovery = await fetchOidcDiscovery(config.issuerUrl);
+    const discoveredIssuer = discovery.issuer || config.issuerUrl;
+    const redirectUri = `${getPublicOrigin(request)}/api/auth/oidc/callback`;
+    const tokenData = await exchangeOidcCode({
+      tokenEndpoint: discovery.token_endpoint,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      code,
+      redirectUri,
+      codeVerifier,
+    });
+
+    if (!tokenData.id_token) {
+      throw new Error("OIDC provider did not return an id_token");
+    }
+
+    const payload = await verifyOidcIdToken({
+      idToken: tokenData.id_token,
+      issuer: discoveredIssuer,
+      audience: config.clientId,
+      jwksUri: discovery.jwks_uri,
+      nonce: storedNonce,
+    });
+
+    clearOidcCookies(cookieStore);
+    await setDashboardAuthCookie(cookieStore, request, {
+      oidc: true,
+      oidcSub: payload.sub || null,
+      oidcEmail: pickOidcEmail(payload) || null,
+      oidcName: pickOidcDisplayName(payload),
+    });
+
+    return NextResponse.redirect(new URL("/dashboard", getPublicOrigin(request)));
+  } catch (error) {
+    clearOidcCookies(cookieStore);
+    return NextResponse.redirect(new URL(`/login?error=${encodeURIComponent(error.message || "oidc_callback_failed")}`, getPublicOrigin(request)));
+  }
+}
diff --git a/src/app/api/auth/oidc/start/route.js b/src/app/api/auth/oidc/start/route.js
new file mode 100644
index 0000000..d4ae5e5
--- /dev/null
+++ b/src/app/api/auth/oidc/start/route.js
@@ -0,0 +1,52 @@
+import { NextResponse } from "next/server";
+import { cookies } from "next/headers";
+import {
+  buildOidcAuthorizationUrl,
+  createOidcNonce,
+  createOidcState,
+  createPkcePair,
+  fetchOidcDiscovery,
+  getOidcRuntimeConfig,
+  getPublicOrigin,
+} from "@/lib/auth/oidc";
+import { shouldUseSecureCookie } from "@/lib/auth/dashboardSession";
+
+export async function GET(request) {
+  try {
+    const config = await getOidcRuntimeConfig();
+    if (!config) {
+      return NextResponse.redirect(new URL("/login?error=oidc_not_configured", getPublicOrigin(request)));
+    }
+
+    const discovery = await fetchOidcDiscovery(config.issuerUrl);
+    const state = createOidcState();
+    const nonce = createOidcNonce();
+    const { verifier, challenge } = createPkcePair();
+    const redirectUri = `${getPublicOrigin(request)}/api/auth/oidc/callback`;
+    const authUrl = buildOidcAuthorizationUrl({
+      authorizationEndpoint: discovery.authorization_endpoint,
+      clientId: config.clientId,
+      redirectUri,
+      scopes: config.scopes,
+      state,
+      nonce,
+      codeChallenge: challenge,
+    });
+
+    const cookieStore = await cookies();
+    const baseOptions = {
+      httpOnly: true,
+      secure: shouldUseSecureCookie(request),
+      sameSite: "lax",
+      path: "/",
+      maxAge: 10 * 60,
+    };
+    cookieStore.set("oidc_state", state, baseOptions);
+    cookieStore.set("oidc_nonce", nonce, baseOptions);
+    cookieStore.set("oidc_code_verifier", verifier, baseOptions);
+
+    return NextResponse.redirect(authUrl);
+  } catch (error) {
+    return NextResponse.redirect(new URL(`/login?error=${encodeURIComponent(error.message || "oidc_start_failed")}`, getPublicOrigin(request)));
+  }
+}
diff --git a/src/app/api/auth/oidc/test/route.js b/src/app/api/auth/oidc/test/route.js
new file mode 100644
index 0000000..85f0aaf
--- /dev/null
+++ b/src/app/api/auth/oidc/test/route.js
@@ -0,0 +1,84 @@
+import { NextResponse } from "next/server";
+import { cookies } from "next/headers";
+import { getSettings } from "@/lib/localDb";
+import { fetchOidcDiscovery, getPublicOrigin, probeOidcClientSecret } from "@/lib/auth/oidc";
+import { verifyDashboardAuthToken } from "@/lib/auth/dashboardSession";
+
+async function canAccessTestRoute() {
+  const settings = await getSettings();
+  if (settings.requireLogin === false) return true;
+
+  const cookieStore = await cookies();
+  const token = cookieStore.get("auth_token")?.value;
+  return await verifyDashboardAuthToken(token);
+}
+
+export async function POST(request) {
+  try {
+    if (!(await canAccessTestRoute())) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    const body = await request.json().catch(() => ({}));
+    const settings = await getSettings();
+
+    const issuerUrl = String(body.issuerUrl || settings.oidcIssuerUrl || "").trim();
+    const clientId = String(body.clientId || settings.oidcClientId || "").trim();
+    const scopes = String(body.scopes || settings.oidcScopes || "openid profile email").trim() || "openid profile email";
+    const clientSecret = String(
+      Object.prototype.hasOwnProperty.call(body, "clientSecret")
+        ? body.clientSecret
+        : settings.oidcClientSecret || ""
+    ).trim();
+
+    if (!issuerUrl) {
+      return NextResponse.json({ error: "Issuer URL is required" }, { status: 400 });
+    }
+    if (!clientId) {
+      return NextResponse.json({ error: "Client ID is required" }, { status: 400 });
+    }
+
+    const discovery = await fetchOidcDiscovery(issuerUrl);
+    const redirectUri = `${getPublicOrigin(request)}/api/auth/oidc/callback`;
+    const secretProbe = await probeOidcClientSecret({
+      tokenEndpoint: discovery.token_endpoint,
+      clientId,
+      clientSecret,
+      redirectUri,
+    });
+
+    if (secretProbe.tested && secretProbe.valid === false) {
+      return NextResponse.json({
+        ok: false,
+        discoveryOk: true,
+        clientSecretTested: true,
+        clientSecretValid: false,
+        issuerUrl,
+        clientId,
+        scopes,
+        redirectUri,
+        authorizationEndpoint: discovery.authorization_endpoint || "",
+        tokenEndpoint: discovery.token_endpoint || "",
+        jwksUri: discovery.jwks_uri || "",
+        error: `Discovery loaded, but the client secret is not valid: ${secretProbe.message}`,
+      });
+    }
+
+    return NextResponse.json({
+      ok: true,
+      discoveryOk: true,
+      clientSecretTested: secretProbe.tested,
+      clientSecretValid: secretProbe.valid,
+      issuerUrl,
+      clientId,
+      scopes,
+      redirectUri,
+      authorizationEndpoint: discovery.authorization_endpoint || "",
+      tokenEndpoint: discovery.token_endpoint || "",
+      jwksUri: discovery.jwks_uri || "",
+      message: secretProbe.message,
+    });
+  } catch (error) {
+    return NextResponse.json({ error: error.message || "OIDC test failed" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/auth/reset-password/route.js b/src/app/api/auth/reset-password/route.js
new file mode 100644
index 0000000..49e6d72
--- /dev/null
+++ b/src/app/api/auth/reset-password/route.js
@@ -0,0 +1,13 @@
+import { NextResponse } from "next/server";
+import { updateSettings } from "@/lib/localDb";
+
+// Reset dashboard password to default by clearing the stored hash.
+// Local-only (enforced by dashboardGuard). Never returns the default literal.
+export async function POST() {
+  try {
+    await updateSettings({ password: null });
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/auth/status/route.js b/src/app/api/auth/status/route.js
new file mode 100644
index 0000000..32cc503
--- /dev/null
+++ b/src/app/api/auth/status/route.js
@@ -0,0 +1,45 @@
+import { NextResponse } from "next/server";
+import { cookies } from "next/headers";
+import { getSettings } from "@/lib/localDb";
+import { isOidcConfigured } from "@/lib/auth/oidc";
+import { getDashboardAuthSession } from "@/lib/auth/dashboardSession";
+
+export async function GET() {
+  try {
+    const settings = await getSettings();
+    const cookieStore = await cookies();
+    const session = await getDashboardAuthSession(cookieStore.get("auth_token")?.value);
+    const requireLogin = settings.requireLogin !== false;
+    const authMode = settings.authMode || "password";
+    const oidcName = String(session?.oidcName || "").trim();
+    const oidcEmail = String(session?.oidcEmail || "").trim();
+    const displayName = oidcName || oidcEmail || (session?.oidc ? "OIDC user" : "Password user");
+    const loginMethod = session?.oidc ? "OIDC" : "Password";
+
+    return NextResponse.json({
+      requireLogin,
+      authMode,
+      oidcConfigured: isOidcConfigured(settings),
+      oidcLoginLabel: (settings.oidcLoginLabel || "Sign in with OIDC").trim() || "Sign in with OIDC",
+      hasPassword: !!settings.password,
+      displayName,
+      loginMethod,
+      oidcName: oidcName || null,
+      oidcEmail: oidcEmail || null,
+      oidcLogin: !!session?.oidc,
+    });
+  } catch {
+    return NextResponse.json({
+      requireLogin: true,
+      authMode: "password",
+      oidcConfigured: false,
+      oidcLoginLabel: "Sign in with OIDC",
+      hasPassword: false,
+      displayName: "Password user",
+      loginMethod: "Password",
+      oidcName: null,
+      oidcEmail: null,
+      oidcLogin: false,
+    });
+  }
+}
diff --git a/src/app/api/cli-tools/all-statuses/route.js b/src/app/api/cli-tools/all-statuses/route.js
new file mode 100644
index 0000000..4d5174f
--- /dev/null
+++ b/src/app/api/cli-tools/all-statuses/route.js
@@ -0,0 +1,46 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { GET as claudeGet } from "../claude-settings/route";
+import { GET as codexGet } from "../codex-settings/route";
+import { GET as opencodeGet } from "../opencode-settings/route";
+import { GET as droidGet } from "../droid-settings/route";
+import { GET as openclawGet } from "../openclaw-settings/route";
+import { GET as hermesGet } from "../hermes-settings/route";
+import { GET as coworkGet } from "../cowork-settings/route";
+import { GET as copilotGet } from "../copilot-settings/route";
+import { GET as clineGet } from "../cline-settings/route";
+import { GET as kiloGet } from "../kilo-settings/route";
+import { GET as deepseekTuiGet } from "../deepseek-tui-settings/route";
+import { GET as jcodeGet } from "../jcode-settings/route";
+
+const STATUS_GETTERS = {
+  claude: claudeGet,
+  codex: codexGet,
+  opencode: opencodeGet,
+  droid: droidGet,
+  openclaw: openclawGet,
+  hermes: hermesGet,
+  cowork: coworkGet,
+  copilot: copilotGet,
+  cline: clineGet,
+  kilo: kiloGet,
+  "deepseek-tui": deepseekTuiGet,
+  jcode: jcodeGet,
+};
+
+// Batch endpoint: gather all CLI tool statuses in one round-trip
+export async function GET() {
+  const entries = await Promise.all(
+    Object.entries(STATUS_GETTERS).map(async ([toolId, getter]) => {
+      try {
+        const res = await getter();
+        const data = await res.json();
+        return [toolId, data];
+      } catch {
+        return [toolId, null];
+      }
+    })
+  );
+  return NextResponse.json(Object.fromEntries(entries));
+}
diff --git a/src/app/api/cli-tools/antigravity-mitm/alias/route.js b/src/app/api/cli-tools/antigravity-mitm/alias/route.js
new file mode 100644
index 0000000..3814a34
--- /dev/null
+++ b/src/app/api/cli-tools/antigravity-mitm/alias/route.js
@@ -0,0 +1,53 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { getMitmAlias, setMitmAliasAll } from "@/models";
+import { getMitmStatus } from "@/mitm/manager";
+import { writeAliasForTool } from "@/lib/mitmAliasCache";
+
+// GET - Get MITM aliases for a tool
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const toolName = searchParams.get("tool");
+    const aliases = await getMitmAlias(toolName || undefined);
+    return NextResponse.json({ aliases });
+  } catch (error) {
+    console.log("Error fetching MITM aliases:", error.message);
+    return NextResponse.json({ error: "Failed to fetch aliases" }, { status: 500 });
+  }
+}
+
+// PUT - Save MITM aliases for a specific tool
+export async function PUT(request) {
+  try {
+    const { tool, mappings } = await request.json();
+
+    if (!tool || !mappings || typeof mappings !== "object") {
+      return NextResponse.json({ error: "tool and mappings required" }, { status: 400 });
+    }
+
+    // Check if DNS is enabled for this tool
+    const status = await getMitmStatus();
+    if (!status.dnsStatus || !status.dnsStatus[tool]) {
+      return NextResponse.json(
+        { error: `DNS must be enabled for ${tool} before editing model mappings` },
+        { status: 403 }
+      );
+    }
+
+    const filtered = {};
+    for (const [alias, model] of Object.entries(mappings)) {
+      if (model && model.trim()) {
+        filtered[alias] = model.trim();
+      }
+    }
+
+    await setMitmAliasAll(tool, filtered);
+    writeAliasForTool(tool, filtered);
+    return NextResponse.json({ success: true, aliases: filtered });
+  } catch (error) {
+    console.log("Error saving MITM aliases:", error.message);
+    return NextResponse.json({ error: "Failed to save aliases" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/antigravity-mitm/route.js b/src/app/api/cli-tools/antigravity-mitm/route.js
new file mode 100644
index 0000000..7d50571
--- /dev/null
+++ b/src/app/api/cli-tools/antigravity-mitm/route.js
@@ -0,0 +1,202 @@
+import { NextResponse } from "next/server";
+import {
+  getMitmStatus,
+  startServer,
+  stopServer,
+  enableToolDNS,
+  disableToolDNS,
+  trustCert,
+  getCachedPassword,
+  setCachedPassword,
+  loadEncryptedPassword,
+  isSudoPasswordRequired,
+  initDbHooks,
+} from "@/mitm/manager";
+import { getSettings, updateSettings } from "@/lib/localDb";
+
+initDbHooks(getSettings, updateSettings);
+
+const DEFAULT_MITM_ROUTER_BASE = "http://localhost:20128";
+
+function normalizeMitmRouterBaseUrlInput(input) {
+  if (input == null || String(input).trim() === "") {
+    return DEFAULT_MITM_ROUTER_BASE;
+  }
+  const t = String(input).trim().replace(/\/+$/, "");
+  let u;
+  try {
+    u = new URL(t);
+  } catch {
+    throw new Error("Invalid MITM router URL");
+  }
+  if (u.protocol !== "http:" && u.protocol !== "https:") {
+    throw new Error("MITM router URL must use http or https");
+  }
+  return t;
+}
+
+const isWin = process.platform === "win32";
+
+function getPassword(provided) {
+  return provided || getCachedPassword() || null;
+}
+
+function requiresSudoPassword(pwd) {
+  return !isWin && !pwd && isSudoPasswordRequired();
+}
+
+function checkIsAdmin() {
+  if (isWin) {
+    try {
+      require("child_process").execSync("net session >nul 2>&1", { windowsHide: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return typeof process.getuid === "function" && process.getuid() === 0;
+}
+
+function checkPrivilege(pwd) {
+  if (checkIsAdmin()) return true;
+  if (isWin) return false;
+  if (!isSudoPasswordRequired()) return true;
+  return !!pwd;
+}
+
+// GET - Full MITM status (server + per-tool DNS)
+export async function GET() {
+  try {
+    const status = await getMitmStatus();
+    const settings = await getSettings();
+    const hasCachedPassword = !!getCachedPassword() || !!(await loadEncryptedPassword());
+    return NextResponse.json({
+      running: status.running,
+      pid: status.pid || null,
+      certExists: status.certExists || false,
+      certTrusted: status.certTrusted || false,
+      dnsStatus: status.dnsStatus || {},
+      hasCachedPassword,
+      isWin,
+      needsSudoPassword: !isWin && !hasCachedPassword && isSudoPasswordRequired(),
+      isAdmin: checkIsAdmin(),
+      mitmRouterBaseUrl:
+        (settings.mitmRouterBaseUrl && String(settings.mitmRouterBaseUrl).trim()) ||
+        DEFAULT_MITM_ROUTER_BASE,
+    });
+  } catch (error) {
+    console.log("Error getting MITM status:", error.message);
+    return NextResponse.json({ error: "Failed to get MITM status" }, { status: 500 });
+  }
+}
+
+// POST - Start MITM server (cert + server, no DNS)
+export async function POST(request) {
+  try {
+    const { apiKey, sudoPassword, mitmRouterBaseUrl, forceKillPort443 } = await request.json();
+    const pwd = getPassword(sudoPassword) || await loadEncryptedPassword() || "";
+
+    if (!apiKey || requiresSudoPassword(pwd)) {
+      return NextResponse.json(
+        { error: !apiKey ? "Missing apiKey" : "Missing sudoPassword" },
+        { status: 400 }
+      );
+    }
+
+    if (!checkPrivilege(pwd)) {
+      return NextResponse.json(
+        { error: isWin ? "Administrator required — restart 9Router as Administrator" : "Root or sudo password required to start MITM" },
+        { status: 403 }
+      );
+    }
+
+    if (mitmRouterBaseUrl !== undefined && mitmRouterBaseUrl !== null) {
+      try {
+        const normalized = normalizeMitmRouterBaseUrlInput(mitmRouterBaseUrl);
+        await updateSettings({ mitmRouterBaseUrl: normalized });
+      } catch (e) {
+        return NextResponse.json(
+          { error: e.message || "Invalid MITM router URL" },
+          { status: 400 },
+        );
+      }
+    }
+
+    const result = await startServer(apiKey, pwd, !!forceKillPort443);
+    if (!isWin) setCachedPassword(pwd);
+
+    return NextResponse.json({ success: true, running: result.running, pid: result.pid });
+  } catch (error) {
+    console.log("Error starting MITM server:", error.message);
+    if (error.code === "PORT_443_BUSY") {
+      return NextResponse.json(
+        { error: error.message, code: "PORT_443_BUSY", portOwner: error.portOwner },
+        { status: 409 }
+      );
+    }
+    return NextResponse.json({ error: error.message || "Failed to start MITM server" }, { status: 500 });
+  }
+}
+
+// DELETE - Stop MITM server (removes all DNS first, then kills server)
+export async function DELETE(request) {
+  try {
+    const body = await request.json().catch(() => ({}));
+    const { sudoPassword } = body;
+    const pwd = getPassword(sudoPassword) || await loadEncryptedPassword() || "";
+
+    if (requiresSudoPassword(pwd)) {
+      return NextResponse.json({ error: "Missing sudoPassword" }, { status: 400 });
+    }
+
+    await stopServer(pwd);
+    if (!isWin && sudoPassword) setCachedPassword(sudoPassword);
+
+    return NextResponse.json({ success: true, running: false });
+  } catch (error) {
+    console.log("Error stopping MITM server:", error.message);
+    return NextResponse.json({ error: error.message || "Failed to stop MITM server" }, { status: 500 });
+  }
+}
+
+// PATCH - Toggle DNS for a specific tool (enable/disable)
+export async function PATCH(request) {
+  try {
+    const { tool, action, sudoPassword } = await request.json();
+    const pwd = getPassword(sudoPassword) || await loadEncryptedPassword() || "";
+
+    if (!tool || !action) {
+      return NextResponse.json({ error: "tool and action required" }, { status: 400 });
+    }
+    if (requiresSudoPassword(pwd)) {
+      return NextResponse.json({ error: "Missing sudoPassword" }, { status: 400 });
+    }
+    if (!checkPrivilege(pwd)) {
+      return NextResponse.json(
+        { error: isWin ? "Administrator required — restart 9Router as Administrator" : "Root or sudo password required to modify DNS" },
+        { status: 403 }
+      );
+    }
+
+    if (action === "enable") {
+      await enableToolDNS(tool, pwd);
+    } else if (action === "disable") {
+      await disableToolDNS(tool, pwd);
+    } else if (action === "trust-cert") {
+      await trustCert(pwd);
+      if (!isWin && sudoPassword) setCachedPassword(sudoPassword);
+      const status = await getMitmStatus();
+      return NextResponse.json({ success: true, certTrusted: status.certTrusted });
+    } else {
+      return NextResponse.json({ error: "action must be enable, disable, or trust-cert" }, { status: 400 });
+    }
+
+    if (!isWin && sudoPassword) setCachedPassword(sudoPassword);
+
+    const status = await getMitmStatus();
+    return NextResponse.json({ success: true, dnsStatus: status.dnsStatus });
+  } catch (error) {
+    console.log("Error toggling DNS:", error.message);
+    return NextResponse.json({ error: error.message || "Failed to toggle DNS" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/claude-settings/route.js b/src/app/api/cli-tools/claude-settings/route.js
new file mode 100644
index 0000000..bb5fa06
--- /dev/null
+++ b/src/app/api/cli-tools/claude-settings/route.js
@@ -0,0 +1,203 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+const execAsync = promisify(exec);
+
+// Get claude settings path based on OS
+const getClaudeSettingsPath = () => {
+  const homeDir = os.homedir();
+  return path.join(homeDir, ".claude", "settings.json");
+};
+
+
+// Check if claude CLI is installed (via which/where or config file exists)
+const checkClaudeInstalled = async () => {
+  try {
+    const isWindows = os.platform() === "win32";
+    const command = isWindows ? "where claude" : "which claude";
+    const env = isWindows
+      ? { ...process.env, PATH: `${process.env.APPDATA}\\npm;${process.env.PATH}` }
+      : process.env;
+    await execAsync(command, { windowsHide: true, env });
+    return true;
+  } catch {
+    try {
+      await fs.access(getClaudeSettingsPath());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// Read current settings
+const readSettings = async () => {
+  try {
+    const settingsPath = getClaudeSettingsPath();
+    const content = await fs.readFile(settingsPath, "utf-8");
+    // Tolerate JSONC (trailing commas) and treat unparseable files as "no config"
+    // rather than throwing a 500 that the UI misreads as "tool not installed".
+    const stripped = content.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch (error) {
+    return null;
+  }
+};
+
+// GET - Check claude CLI and read current settings
+export async function GET() {
+  try {
+    const isInstalled = await checkClaudeInstalled();
+    
+    if (!isInstalled) {
+      return NextResponse.json({
+        installed: false,
+        settings: null,
+        message: "Claude CLI is not installed",
+      });
+    }
+
+    const settings = await readSettings();
+    const has9Router = !!(settings?.env?.ANTHROPIC_BASE_URL);
+
+    return NextResponse.json({
+      installed: true,
+      settings: settings,
+      has9Router: has9Router,
+      settingsPath: getClaudeSettingsPath(),
+    });
+  } catch (error) {
+    console.log("Error checking claude settings:", error);
+    return NextResponse.json(
+      { error: "Failed to check claude settings" },
+      { status: 500 }
+    );
+  }
+}
+
+// POST - Backup old fields and write new settings
+export async function POST(request) {
+  try {
+    const { env } = await request.json();
+    
+    if (!env || typeof env !== "object") {
+      return NextResponse.json(
+        { error: "Invalid env object" },
+        { status: 400 }
+      );
+    }
+
+    const settingsPath = getClaudeSettingsPath();
+    const claudeDir = path.dirname(settingsPath);
+
+    // Ensure .claude directory exists
+    await fs.mkdir(claudeDir, { recursive: true });
+
+    // Read current settings
+    let currentSettings = {};
+    try {
+      const content = await fs.readFile(settingsPath, "utf-8");
+      currentSettings = JSON.parse(content);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+
+    // Normalize ANTHROPIC_BASE_URL to ensure /v1 suffix
+    if (env.ANTHROPIC_BASE_URL) {
+      env.ANTHROPIC_BASE_URL = env.ANTHROPIC_BASE_URL.endsWith("/v1") 
+        ? env.ANTHROPIC_BASE_URL 
+        : `${env.ANTHROPIC_BASE_URL}/v1`;
+    }
+
+    // Merge new env with existing settings
+    const newSettings = {
+      ...currentSettings,
+      hasCompletedOnboarding: true,
+      env: {
+        ...(currentSettings.env || {}),
+        ...env,
+      },
+    };
+
+    // Write new settings
+    await fs.writeFile(settingsPath, JSON.stringify(newSettings, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "Settings updated successfully",
+    });
+  } catch (error) {
+    console.log("Error updating claude settings:", error);
+    return NextResponse.json(
+      { error: "Failed to update claude settings" },
+      { status: 500 }
+    );
+  }
+}
+
+// Fields to remove when resetting
+const RESET_ENV_KEYS = [
+  "ANTHROPIC_BASE_URL",
+  "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_DEFAULT_OPUS_MODEL",
+  "ANTHROPIC_DEFAULT_SONNET_MODEL",
+  "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+  "API_TIMEOUT_MS",
+];
+
+// DELETE - Reset settings (remove env fields)
+export async function DELETE() {
+  try {
+    const settingsPath = getClaudeSettingsPath();
+
+    // Read current settings
+    let currentSettings = {};
+    try {
+      const content = await fs.readFile(settingsPath, "utf-8");
+      currentSettings = JSON.parse(content);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return NextResponse.json({
+          success: true,
+          message: "No settings file to reset",
+        });
+      }
+      throw error;
+    }
+
+    // Remove specified env fields
+    if (currentSettings.env) {
+      RESET_ENV_KEYS.forEach((key) => {
+        delete currentSettings.env[key];
+      });
+      
+      // Clean up empty env object
+      if (Object.keys(currentSettings.env).length === 0) {
+        delete currentSettings.env;
+      }
+    }
+
+    // Write updated settings
+    await fs.writeFile(settingsPath, JSON.stringify(currentSettings, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "Settings reset successfully",
+    });
+  } catch (error) {
+    console.log("Error resetting claude settings:", error);
+    return NextResponse.json(
+      { error: "Failed to reset claude settings" },
+      { status: 500 }
+    );
+  }
+}
+
diff --git a/src/app/api/cli-tools/cline-settings/route.js b/src/app/api/cli-tools/cline-settings/route.js
new file mode 100644
index 0000000..ecbccbd
--- /dev/null
+++ b/src/app/api/cli-tools/cline-settings/route.js
@@ -0,0 +1,135 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+const execAsync = promisify(exec);
+
+const getDataDir = () => path.join(os.homedir(), ".cline", "data");
+const getGlobalStatePath = () => path.join(getDataDir(), "globalState.json");
+const getSecretsPath = () => path.join(getDataDir(), "secrets.json");
+
+const checkInstalled = async () => {
+  try {
+    const isWindows = os.platform() === "win32";
+    const command = isWindows ? "where cline" : "which cline";
+    const env = isWindows
+      ? { ...process.env, PATH: `${process.env.APPDATA}\\npm;${process.env.PATH}` }
+      : process.env;
+    await execAsync(command, { windowsHide: true, env });
+    return true;
+  } catch {
+    try {
+      await fs.access(getGlobalStatePath());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+const readJson = async (filePath) => {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    // Tolerate JSONC (trailing commas) and treat unparseable files as "no config"
+    // rather than throwing a 500 that the UI misreads as "tool not installed".
+    const stripped = content.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch (error) {
+    return null;
+  }
+};
+
+const has9RouterConfig = (globalState) => {
+  if (!globalState) return false;
+  const isOpenAi =
+    globalState.actModeApiProvider === "openai" || globalState.planModeApiProvider === "openai";
+  const baseUrl = globalState.openAiBaseUrl || "";
+  return isOpenAi && (baseUrl.includes("localhost") || baseUrl.includes("127.0.0.1") || baseUrl.includes("9router"));
+};
+
+export async function GET() {
+  try {
+    const installed = await checkInstalled();
+    if (!installed) {
+      return NextResponse.json({ installed: false, settings: null, message: "Cline CLI is not installed" });
+    }
+    const globalState = await readJson(getGlobalStatePath());
+    return NextResponse.json({
+      installed: true,
+      settings: {
+        actModeApiProvider: globalState?.actModeApiProvider,
+        planModeApiProvider: globalState?.planModeApiProvider,
+        openAiBaseUrl: globalState?.openAiBaseUrl,
+        openAiModelId: globalState?.openAiModelId,
+      },
+      has9Router: has9RouterConfig(globalState),
+      globalStatePath: getGlobalStatePath(),
+    });
+  } catch (error) {
+    console.log("Error checking cline settings:", error);
+    return NextResponse.json({ error: "Failed to check cline settings" }, { status: 500 });
+  }
+}
+
+export async function POST(request) {
+  try {
+    const { baseUrl, apiKey, model } = await request.json();
+    if (!baseUrl || !apiKey || !model) {
+      return NextResponse.json({ error: "baseUrl, apiKey and model are required" }, { status: 400 });
+    }
+
+    await fs.mkdir(getDataDir(), { recursive: true });
+
+    // Cline expects base WITHOUT /v1
+    const normalizedBaseUrl = baseUrl.endsWith("/v1") ? baseUrl.slice(0, -3) : baseUrl;
+
+    const globalState = (await readJson(getGlobalStatePath())) || {};
+    globalState.actModeApiProvider = "openai";
+    globalState.planModeApiProvider = "openai";
+    globalState.openAiBaseUrl = normalizedBaseUrl;
+    globalState.openAiModelId = model;
+    globalState.planModeOpenAiModelId = model;
+    await fs.writeFile(getGlobalStatePath(), JSON.stringify(globalState, null, 2));
+
+    const secrets = (await readJson(getSecretsPath())) || {};
+    secrets.openAiApiKey = apiKey;
+    await fs.writeFile(getSecretsPath(), JSON.stringify(secrets, null, 2));
+
+    return NextResponse.json({ success: true, message: "Cline settings applied successfully!", globalStatePath: getGlobalStatePath() });
+  } catch (error) {
+    console.log("Error updating cline settings:", error);
+    return NextResponse.json({ error: "Failed to update cline settings" }, { status: 500 });
+  }
+}
+
+export async function DELETE() {
+  try {
+    const globalState = await readJson(getGlobalStatePath());
+    if (!globalState) {
+      return NextResponse.json({ success: true, message: "No settings file to reset" });
+    }
+
+    if (globalState.actModeApiProvider === "openai") {
+      delete globalState.openAiBaseUrl;
+      delete globalState.openAiModelId;
+      delete globalState.planModeOpenAiModelId;
+      globalState.actModeApiProvider = "cline";
+      globalState.planModeApiProvider = "cline";
+    }
+    await fs.writeFile(getGlobalStatePath(), JSON.stringify(globalState, null, 2));
+
+    const secrets = (await readJson(getSecretsPath())) || {};
+    delete secrets.openAiApiKey;
+    await fs.writeFile(getSecretsPath(), JSON.stringify(secrets, null, 2));
+
+    return NextResponse.json({ success: true, message: "9Router settings removed from Cline" });
+  } catch (error) {
+    console.log("Error resetting cline settings:", error);
+    return NextResponse.json({ error: "Failed to reset cline settings" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/codex-settings/route.js b/src/app/api/cli-tools/codex-settings/route.js
new file mode 100644
index 0000000..ff20c57
--- /dev/null
+++ b/src/app/api/cli-tools/codex-settings/route.js
@@ -0,0 +1,238 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { parseTOML, stringifyTOML } from "confbox";
+
+const execAsync = promisify(exec);
+
+const getCodexDir = () => path.join(os.homedir(), ".codex");
+const getCodexConfigPath = () => path.join(getCodexDir(), "config.toml");
+const getCodexAuthPath = () => path.join(getCodexDir(), "auth.json");
+
+// Flatten confbox-parsed TOML into a writable object, preserving nested tables
+const parsedToWritable = (obj) => obj ?? {};
+
+// Set a nested key from a flat dotted path, creating intermediate objects as needed
+const setNestedSection = (obj, dottedKey, value) => {
+  const keys = dottedKey.split(".");
+  let cur = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (cur[keys[i]] == null || typeof cur[keys[i]] !== "object") {
+      cur[keys[i]] = {};
+    }
+    cur = cur[keys[i]];
+  }
+  cur[keys[keys.length - 1]] = value;
+};
+
+// Delete a nested key from a flat dotted path
+const deleteNestedSection = (obj, dottedKey) => {
+  const keys = dottedKey.split(".");
+  let cur = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    cur = cur?.[keys[i]];
+    if (cur == null) return;
+  }
+  delete cur[keys[keys.length - 1]];
+};
+
+// Check if codex CLI is installed (via which/where or config file exists)
+const checkCodexInstalled = async () => {
+  try {
+    const isWindows = os.platform() === "win32";
+    const command = isWindows ? "where codex" : "which codex";
+    const env = isWindows
+      ? { ...process.env, PATH: `${process.env.APPDATA}\\npm;${process.env.PATH}` }
+      : process.env;
+    await execAsync(command, { windowsHide: true, env });
+    return true;
+  } catch {
+    try {
+      await fs.access(getCodexConfigPath());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// Read current config.toml
+const readConfig = async () => {
+  try {
+    const configPath = getCodexConfigPath();
+    const content = await fs.readFile(configPath, "utf-8");
+    return content;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+};
+
+// Check if config has 9Router settings
+const has9RouterConfig = (config) => {
+  if (!config) return false;
+  return config.includes("model_provider = \"9router\"") || config.includes("[model_providers.9router]");
+};
+
+// GET - Check codex CLI and read current settings
+export async function GET() {
+  try {
+    const isInstalled = await checkCodexInstalled();
+    
+    if (!isInstalled) {
+      return NextResponse.json({
+        installed: false,
+        config: null,
+        message: "Codex CLI is not installed",
+      });
+    }
+
+    const config = await readConfig();
+
+    return NextResponse.json({
+      installed: true,
+      config,
+      has9Router: has9RouterConfig(config),
+      configPath: getCodexConfigPath(),
+    });
+  } catch (error) {
+    console.log("Error checking codex settings:", error);
+    return NextResponse.json({ error: "Failed to check codex settings" }, { status: 500 });
+  }
+}
+
+// POST - Update 9Router settings (merge with existing config)
+export async function POST(request) {
+  try {
+    const { baseUrl, apiKey, model, subagentModel } = await request.json();
+    
+    if (!baseUrl || !apiKey || !model) {
+      return NextResponse.json({ error: "baseUrl, apiKey and model are required" }, { status: 400 });
+    }
+
+    const codexDir = getCodexDir();
+    const configPath = getCodexConfigPath();
+
+    // Ensure directory exists
+    await fs.mkdir(codexDir, { recursive: true });
+
+    // Read and parse existing config
+    let parsed = {};
+    try {
+      const existingConfig = await fs.readFile(configPath, "utf-8");
+      parsed = parsedToWritable(parseTOML(existingConfig));
+    } catch { /* No existing config */ }
+
+    // Update only 9Router related fields (api_key goes to auth.json, not config.toml)
+    parsed.model = model;
+    parsed.model_provider = "9router";
+
+    // Update or create 9router provider section (no api_key - Codex reads from auth.json)
+    // Ensure /v1 suffix is added only once
+    const normalizedBaseUrl = baseUrl.endsWith("/v1") ? baseUrl : `${baseUrl}/v1`;
+    setNestedSection(parsed, "model_providers.9router", {
+      name: "9Router",
+      base_url: normalizedBaseUrl,
+      wire_api: "responses",
+    });
+
+    // Add subagent configuration
+    const effectiveSubagentModel = subagentModel || model;
+    setNestedSection(parsed, "agents.subagent", {
+      model: effectiveSubagentModel,
+    });
+
+    // Write merged config
+    const configContent = stringifyTOML(parsed);
+    await fs.writeFile(configPath, configContent);
+
+    // Update auth.json with OPENAI_API_KEY (Codex reads this first)
+    const authPath = getCodexAuthPath();
+    let authData = {};
+    try {
+      const existingAuth = await fs.readFile(authPath, "utf-8");
+      authData = JSON.parse(existingAuth);
+    } catch { /* No existing auth */ }
+    
+    // Force apikey mode (keep existing tokens untouched for ChatGPT login reuse)
+    authData.OPENAI_API_KEY = apiKey;
+    authData.auth_mode = "apikey";
+    await fs.writeFile(authPath, JSON.stringify(authData, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "Codex settings applied successfully!",
+      configPath,
+    });
+  } catch (error) {
+    console.log("Error updating codex settings:", error);
+    return NextResponse.json({ error: "Failed to update codex settings" }, { status: 500 });
+  }
+}
+
+// DELETE - Remove 9Router settings only (keep other settings)
+export async function DELETE() {
+  try {
+    const configPath = getCodexConfigPath();
+
+    // Read and parse existing config
+    let parsed = {};
+    try {
+      const existingConfig = await fs.readFile(configPath, "utf-8");
+      parsed = parsedToWritable(parseTOML(existingConfig));
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return NextResponse.json({
+          success: true,
+          message: "No config file to reset",
+        });
+      }
+      throw error;
+    }
+
+    // Remove 9Router related root fields only if they point to 9router
+    if (parsed.model_provider === "9router") {
+      delete parsed.model;
+      delete parsed.model_provider;
+    }
+
+    // Remove 9router provider section
+    deleteNestedSection(parsed, "model_providers.9router");
+
+    // Remove subagent configuration
+    deleteNestedSection(parsed, "agents.subagent");
+
+    // Write updated config
+    const configContent = stringifyTOML(parsed);
+    await fs.writeFile(configPath, configContent);
+
+    // Remove OPENAI_API_KEY from auth.json
+    const authPath = getCodexAuthPath();
+    try {
+      const existingAuth = await fs.readFile(authPath, "utf-8");
+      const authData = JSON.parse(existingAuth);
+      delete authData.OPENAI_API_KEY;
+      delete authData.auth_mode;
+
+      // Write back or delete if empty
+      if (Object.keys(authData).length === 0) {
+        await fs.unlink(authPath);
+      } else {
+        await fs.writeFile(authPath, JSON.stringify(authData, null, 2));
+      }
+    } catch { /* No auth file */ }
+
+    return NextResponse.json({
+      success: true,
+      message: "9Router settings removed successfully",
+    });
+  } catch (error) {
+    console.log("Error resetting codex settings:", error);
+    return NextResponse.json({ error: "Failed to reset codex settings" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/copilot-settings/route.js b/src/app/api/cli-tools/copilot-settings/route.js
new file mode 100644
index 0000000..3c0bd66
--- /dev/null
+++ b/src/app/api/cli-tools/copilot-settings/route.js
@@ -0,0 +1,150 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+// Resolve chatLanguageModels.json path per OS
+const getConfigPath = () => {
+  const home = os.homedir();
+  const platform = os.platform();
+  if (platform === "win32") {
+    return path.join(process.env.APPDATA || home, "Code", "User", "chatLanguageModels.json");
+  }
+  if (platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "Code", "User", "chatLanguageModels.json");
+  }
+  return path.join(home, ".config", "Code", "User", "chatLanguageModels.json");
+};
+
+const readConfig = async () => {
+  try {
+    const content = await fs.readFile(getConfigPath(), "utf-8");
+    // Tolerate JSONC (trailing commas) and treat unparseable files as "no config"
+    // rather than throwing a 500 that the UI misreads as "tool not installed".
+    const stripped = content.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch (error) {
+    return null;
+  }
+};
+
+const has9RouterConfig = (config) => {
+  if (!Array.isArray(config)) return false;
+  return config.some((entry) => entry.name === "9Router");
+};
+
+const get9RouterEntry = (config) => {
+  if (!Array.isArray(config)) return null;
+  return config.find((entry) => entry.name === "9Router") || null;
+};
+
+// GET - Read current copilot config
+export async function GET() {
+  try {
+    const config = await readConfig();
+    const entry = get9RouterEntry(config);
+
+    return NextResponse.json({
+      installed: true,
+      config,
+      has9Router: has9RouterConfig(config),
+      configPath: getConfigPath(),
+      currentModel: entry?.models?.[0]?.id || null,
+      currentUrl: entry?.models?.[0]?.url || null,
+    });
+  } catch (error) {
+    console.log("Error checking copilot settings:", error);
+    return NextResponse.json({ error: "Failed to check copilot settings" }, { status: 500 });
+  }
+}
+
+// POST - Apply 9Router config to chatLanguageModels.json
+export async function POST(request) {
+  try {
+    const { baseUrl, apiKey, models } = await request.json();
+
+    if (!baseUrl || !models?.length) {
+      return NextResponse.json({ error: "baseUrl and models are required" }, { status: 400 });
+    }
+
+    const configPath = getConfigPath();
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+
+    // Read existing config array
+    let config = [];
+    try {
+      const existing = await fs.readFile(configPath, "utf-8");
+      const parsed = JSON.parse(existing);
+      config = Array.isArray(parsed) ? parsed : [];
+    } catch { /* No existing config */ }
+
+    const endpointUrl = `${baseUrl}/chat/completions#models.ai.azure.com`;
+    const keyToUse = apiKey || "sk_9router";
+
+    const newEntry = {
+      name: "9Router",
+      vendor: "azure",
+      apiKey: keyToUse,
+      models: models.map((id) => ({
+        id,
+        name: id,
+        url: endpointUrl,
+        toolCalling: true,
+        vision: false,
+        maxInputTokens: 128000,
+        maxOutputTokens: 16000,
+      })),
+    };
+
+    // Replace existing 9Router entry or append
+    const idx = config.findIndex((e) => e.name === "9Router");
+    if (idx >= 0) {
+      config[idx] = newEntry;
+    } else {
+      config.push(newEntry);
+    }
+
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "Copilot settings applied! Reload VS Code to take effect.",
+      configPath,
+    });
+  } catch (error) {
+    console.log("Error updating copilot settings:", error);
+    return NextResponse.json({ error: "Failed to update copilot settings" }, { status: 500 });
+  }
+}
+
+// DELETE - Remove 9Router entry from chatLanguageModels.json
+export async function DELETE() {
+  try {
+    const configPath = getConfigPath();
+
+    let config = [];
+    try {
+      const existing = await fs.readFile(configPath, "utf-8");
+      const parsed = JSON.parse(existing);
+      config = Array.isArray(parsed) ? parsed : [];
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return NextResponse.json({ success: true, message: "No config file to reset" });
+      }
+      throw error;
+    }
+
+    config = config.filter((e) => e.name !== "9Router");
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "9Router removed from Copilot config",
+    });
+  } catch (error) {
+    console.log("Error resetting copilot settings:", error);
+    return NextResponse.json({ error: "Failed to reset copilot settings" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/cowork-mcp-registry/route.js b/src/app/api/cli-tools/cowork-mcp-registry/route.js
new file mode 100644
index 0000000..62275f8
--- /dev/null
+++ b/src/app/api/cli-tools/cowork-mcp-registry/route.js
@@ -0,0 +1,77 @@
+"use server";
+
+import { NextResponse } from "next/server";
+
+const REGISTRY_URL = "https://api.anthropic.com/mcp-registry/v0/servers";
+const VISIBILITY = "commercial,gsuite,gsuite-google";
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const G_KEY = "__9routerCoworkMcpRegistryCache";
+
+function gcache() {
+  if (!globalThis[G_KEY]) globalThis[G_KEY] = { ts: 0, data: null };
+  return globalThis[G_KEY];
+}
+
+// Filter out claude.ai-mediated servers (broken in 3p) and tenant-required entries.
+function isDirectConnect(url) {
+  if (!url || typeof url !== "string") return false;
+  if (/^https?:\/\/[^/]*\bmcp\.claude\.com\b/i.test(url)) return false;
+  if (/^https?:\/\/api\.anthropic\.com\/mcp\b/i.test(url)) return false;
+  if (/[<{]/.test(url)) return false;
+  return /^https:\/\//i.test(url);
+}
+
+async function fetchAll() {
+  const out = [];
+  let cursor = "";
+  for (let i = 0; i < 20; i++) {
+    const url = `${REGISTRY_URL}?limit=500&visibility=${VISIBILITY}${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`;
+    const r = await fetch(url, { headers: { accept: "application/json" } });
+    if (!r.ok) break;
+    const j = await r.json();
+    for (const item of j.servers || []) {
+      const s = item.server || {};
+      const meta = item._meta?.["com.anthropic.api/mcp-registry"] || {};
+      const remote = (s.remotes || [])[0];
+      if (!remote?.url || !isDirectConnect(remote.url)) continue;
+      if (meta.requiredFields?.length) continue;
+      const transport = remote.type === "sse" ? "sse" : "http";
+      const toolNames = Array.isArray(meta.toolNames) ? meta.toolNames : [];
+      out.push({
+        name: s.name,
+        slug: meta.slug || s.name,
+        title: s.title || meta.displayName || s.name,
+        description: s.description || meta.oneLiner || "",
+        url: remote.url,
+        transport,
+        oauth: !meta.isAuthless,
+        toolNames,
+        toolCount: toolNames.length,
+        iconUrl: meta.iconUrl || null,
+      });
+    }
+    cursor = j.metadata?.nextCursor;
+    if (!cursor) break;
+  }
+  // Dedupe by url
+  const seen = new Set();
+  return out.filter((s) => (seen.has(s.url) ? false : (seen.add(s.url), true)));
+}
+
+export async function GET(request) {
+  const { searchParams } = new URL(request.url);
+  const force = searchParams.get("refresh") === "1";
+  const cache = gcache();
+  if (!force && cache.data && Date.now() - cache.ts < CACHE_TTL_MS) {
+    return NextResponse.json({ cached: true, ...cache.data });
+  }
+  try {
+    const servers = await fetchAll();
+    const data = { servers, total: servers.length };
+    cache.ts = Date.now();
+    cache.data = data;
+    return NextResponse.json({ cached: false, ...data });
+  } catch (e) {
+    return NextResponse.json({ error: e.message, servers: [], total: 0 }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/cowork-mcp-tools/route.js b/src/app/api/cli-tools/cowork-mcp-tools/route.js
new file mode 100644
index 0000000..5cc3d3a
--- /dev/null
+++ b/src/app/api/cli-tools/cowork-mcp-tools/route.js
@@ -0,0 +1,95 @@
+"use server";
+
+import { NextResponse } from "next/server";
+
+const TIMEOUT_MS = 8000;
+
+// Probe MCP server: initialize + tools/list. No auth header — works for authless servers.
+// OAuth servers return 401, signal client to skip tool listing.
+async function probeMcp(url) {
+  const headers = {
+    "Content-Type": "application/json",
+    "Accept": "application/json, text/event-stream",
+    "MCP-Protocol-Version": "2025-06-18",
+  };
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  try {
+    // Step 1: initialize
+    const initRes = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        jsonrpc: "2.0", id: 1, method: "initialize",
+        params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "9router", version: "1" } },
+      }),
+      signal: ac.signal,
+    });
+    if (initRes.status === 401 || initRes.status === 403) {
+      return { requiresAuth: true, tools: [] };
+    }
+    if (!initRes.ok) {
+      return { error: `init ${initRes.status}`, tools: [] };
+    }
+    const sessionId = initRes.headers.get("mcp-session-id") || "";
+    await initRes.text().catch(() => {});
+
+    const listHeaders = { ...headers };
+    if (sessionId) listHeaders["mcp-session-id"] = sessionId;
+
+    // Step 2: notifications/initialized (required by spec before tools/list)
+    await fetch(url, {
+      method: "POST",
+      headers: listHeaders,
+      body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }),
+      signal: ac.signal,
+    }).catch(() => {});
+
+    // Step 3: tools/list
+    const listRes = await fetch(url, {
+      method: "POST",
+      headers: listHeaders,
+      body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" }),
+      signal: ac.signal,
+    });
+    if (listRes.status === 401 || listRes.status === 403) {
+      return { requiresAuth: true, tools: [] };
+    }
+    const ct = listRes.headers.get("content-type") || "";
+    let parsed;
+    if (ct.includes("text/event-stream")) {
+      // Parse SSE: each "data: {...}" line is a JSON-RPC message
+      const text = await listRes.text();
+      const dataLines = text.split("\n").filter((l) => l.startsWith("data:"));
+      for (const line of dataLines) {
+        try {
+          const obj = JSON.parse(line.replace(/^data:\s*/, ""));
+          if (obj?.id === 2 && obj.result) { parsed = obj; break; }
+        } catch { /* skip */ }
+      }
+    } else {
+      parsed = await listRes.json().catch(() => null);
+    }
+    const tools = parsed?.result?.tools || [];
+    return {
+      tools: tools.map((t) => ({ name: t.name, description: t.description || "" })),
+    };
+  } catch (e) {
+    return { error: e.name === "AbortError" ? "timeout" : e.message, tools: [] };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function POST(request) {
+  try {
+    const { url } = await request.json();
+    if (!url || typeof url !== "string") {
+      return NextResponse.json({ error: "url required" }, { status: 400 });
+    }
+    const result = await probeMcp(url);
+    return NextResponse.json(result);
+  } catch (e) {
+    return NextResponse.json({ error: e.message, tools: [] }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/cowork-settings/route.js b/src/app/api/cli-tools/cowork-settings/route.js
new file mode 100644
index 0000000..d30b667
--- /dev/null
+++ b/src/app/api/cli-tools/cowork-settings/route.js
@@ -0,0 +1,387 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
+import { DEFAULT_PLUGINS, LOCAL_STDIO_PLUGINS, buildManagedMcpServers } from "@/shared/constants/coworkPlugins";
+import { UPDATER_CONFIG } from "@/shared/constants/config";
+import { getConsistentMachineId } from "@/shared/utils/machineId";
+
+const APP_PORT = UPDATER_CONFIG.appPort;
+const CLI_TOKEN_HEADER = "x-9r-cli-token";
+const CLI_TOKEN_SALT = "9r-cli-auth";
+const LOCAL_MCP_PREFIX = `http://localhost:${APP_PORT}/api/mcp/`;
+
+let cachedCliToken = null;
+const getCliToken = async () => {
+  if (!cachedCliToken) cachedCliToken = await getConsistentMachineId(CLI_TOKEN_SALT);
+  return cachedCliToken;
+};
+
+// Inject CLI token header into entries pointing at our local /api/mcp/ bridge.
+const injectAuthHeaders = async (entries) => {
+  const token = await getCliToken();
+  for (const e of entries) {
+    if (typeof e?.url === "string" && e.url.startsWith(LOCAL_MCP_PREFIX)) {
+      e.headers = { ...(e.headers || {}), [CLI_TOKEN_HEADER]: token };
+    }
+  }
+  return entries;
+};
+
+const PROVIDER = "gateway";
+
+// Hardcoded relax-security profile applied on every Apply.
+const SECURITY_RELAX = {
+  coworkEgressAllowedHosts: ["*"],
+  disabledBuiltinTools: [],
+  isLocalDevMcpEnabled: true,
+  isDesktopExtensionEnabled: true,
+  isDesktopExtensionDirectoryEnabled: true,
+  isDesktopExtensionSignatureRequired: false,
+  isClaudeCodeForDesktopEnabled: true,
+  disableEssentialTelemetry: true,
+  disableNonessentialTelemetry: true,
+  disableNonessentialServices: true,
+};
+
+// Tools auto-allow per server via toolPolicy["*"] = "allow" semantics.
+// 3p schema requires explicit tool names; we mark "*" via operonSkipMcpApprovals instead.
+
+const getCandidateRoots = () => {
+  if (os.platform() === "darwin") {
+    const base = path.join(os.homedir(), "Library", "Application Support");
+    return [path.join(base, "Claude-3p"), path.join(base, "Claude")];
+  }
+  if (os.platform() === "win32") {
+    const localApp = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+    const roaming = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    return [
+      path.join(localApp, "Claude-3p"),
+      path.join(roaming, "Claude-3p"),
+      path.join(localApp, "Claude"),
+      path.join(roaming, "Claude"),
+    ];
+  }
+  return [
+    path.join(os.homedir(), ".config", "Claude-3p"),
+    path.join(os.homedir(), ".config", "Claude"),
+  ];
+};
+
+const getAppInstallPaths = () => {
+  if (os.platform() === "darwin") {
+    return ["/Applications/Claude.app", path.join(os.homedir(), "Applications", "Claude.app")];
+  }
+  if (os.platform() === "win32") {
+    const localApp = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+    const programFiles = process.env["ProgramFiles"] || "C:\\Program Files";
+    return [
+      path.join(localApp, "AnthropicClaude"),
+      path.join(programFiles, "Claude"),
+      path.join(programFiles, "AnthropicClaude"),
+    ];
+  }
+  return [];
+};
+
+const resolveAppRootForRead = async () => {
+  const candidates = getCandidateRoots();
+  for (const dir of candidates) {
+    try {
+      await fs.access(path.join(dir, "configLibrary"));
+      return dir;
+    } catch { /* try next */ }
+  }
+  return candidates[0];
+};
+
+const getWriteRoot = () => getCandidateRoots()[0];
+const getConfigDir = async () => path.join(await resolveAppRootForRead(), "configLibrary");
+const getWriteConfigDir = () => path.join(getWriteRoot(), "configLibrary");
+const getMetaPath = async () => path.join(await getConfigDir(), "_meta.json");
+const getWriteMetaPath = () => path.join(getWriteConfigDir(), "_meta.json");
+
+const get1pRoot = () => {
+  if (os.platform() === "darwin") return path.join(os.homedir(), "Library", "Application Support", "Claude");
+  if (os.platform() === "win32") {
+    const roaming = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(roaming, "Claude");
+  }
+  return path.join(os.homedir(), ".config", "Claude");
+};
+
+const get1pConfigPath = () => path.join(get1pRoot(), "claude_desktop_config.json");
+
+const read1pConfig = async () => {
+  try {
+    const content = await fs.readFile(get1pConfigPath(), "utf-8");
+    // Tolerate JSONC (trailing commas) and treat unparseable files as empty config
+    // rather than throwing a 500 that the UI misreads as "tool not installed".
+    const stripped = content.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped) || {};
+  } catch (error) {
+    return {};
+  }
+};
+
+const write1pConfig = async (cfg) => {
+  await fs.mkdir(get1pRoot(), { recursive: true });
+  await fs.writeFile(get1pConfigPath(), JSON.stringify(cfg, null, 2));
+};
+
+const bootstrapDeploymentMode = async () => {
+  const cfg = await read1pConfig();
+  if (cfg.deploymentMode === "3p") return false;
+  cfg.deploymentMode = "3p";
+  await write1pConfig(cfg);
+  return true;
+};
+
+// Remove any legacy stdio entries previously written into 1p claude_desktop_config.json.
+const cleanup1pLegacy = async () => {
+  const cfg = await read1pConfig();
+  if (!cfg.mcpServers || typeof cfg.mcpServers !== "object") return;
+  const managedNames = new Set(LOCAL_STDIO_PLUGINS.map((p) => p.name));
+  for (const k of Object.keys(cfg.mcpServers)) {
+    if (managedNames.has(k)) delete cfg.mcpServers[k];
+  }
+  if (Object.keys(cfg.mcpServers).length === 0) delete cfg.mcpServers;
+  await write1pConfig(cfg);
+};
+
+// Build SSE bridge entries pointing at this app's inline /api/mcp/{name} endpoint.
+const buildLocalBridgeEntries = (localPluginNames) => {
+  const names = Array.isArray(localPluginNames) ? localPluginNames : [];
+  const out = [];
+  for (const n of names) {
+    const def = LOCAL_STDIO_PLUGINS.find((p) => p.name === n);
+    if (!def) continue;
+    const entry = {
+      name: def.name,
+      url: `http://localhost:${APP_PORT}/api/mcp/${def.name}/sse`,
+      transport: "sse",
+    };
+    if (Array.isArray(def.toolNames) && def.toolNames.length > 0) {
+      const prefix = `${def.name}-`;
+      const policy = {};
+      for (const t of def.toolNames) {
+        policy[t] = "allow";
+        policy[`${prefix}${t}`] = "allow";
+      }
+      entry.toolPolicy = policy;
+    }
+    out.push(entry);
+  }
+  return out;
+};
+
+// Build entries for user-defined custom MCP plugins (URL or stdio command).
+const buildCustomEntries = (customPlugins) => {
+  if (!Array.isArray(customPlugins)) return [];
+  const out = [];
+  for (const p of customPlugins) {
+    if (!p?.name || !p?.url) continue;
+    out.push({ name: p.name, url: p.url, transport: p.transport || "sse", custom: true });
+  }
+  return out;
+};
+
+const checkInstalled = async () => {
+  for (const dir of [...getCandidateRoots(), ...getAppInstallPaths()]) {
+    try { await fs.access(dir); return true; } catch { /* try next */ }
+  }
+  return false;
+};
+
+const readJson = async (filePath) => {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    // Tolerate JSONC (trailing commas) and treat unparseable files as "no config"
+    // rather than throwing a 500 that the UI misreads as "tool not installed".
+    const stripped = content.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch (error) {
+    return null;
+  }
+};
+
+const ensureMeta = async () => {
+  const writeMetaPath = getWriteMetaPath();
+  let meta = await readJson(writeMetaPath);
+  if (!meta || !meta.appliedId) {
+    const existingRead = await readJson(await getMetaPath());
+    if (existingRead?.appliedId) {
+      meta = existingRead;
+    } else {
+      const newId = crypto.randomUUID();
+      meta = { appliedId: newId, entries: [{ id: newId, name: "Default" }] };
+    }
+    await fs.mkdir(getWriteConfigDir(), { recursive: true });
+    await fs.writeFile(writeMetaPath, JSON.stringify(meta, null, 2));
+  }
+  return meta;
+};
+
+// Auto-skip approvals for every managed server (no per-tool prompts).
+async function writeSkipApprovals(managedServers) {
+  const cfgPath = path.join(getWriteRoot(), "config.json");
+  let cfg = {};
+  try { cfg = JSON.parse(await fs.readFile(cfgPath, "utf-8")) || {}; }
+  catch (e) { if (e.code !== "ENOENT") return { error: e.code }; }
+  const skip = {};
+  for (const srv of managedServers) {
+    if (srv?.name) skip[srv.name] = true;
+  }
+  cfg.operonSkipMcpApprovals = skip;
+  await fs.mkdir(getWriteRoot(), { recursive: true });
+  await fs.writeFile(cfgPath, JSON.stringify(cfg, null, 2));
+  return { written: Object.keys(skip).length };
+}
+
+export async function GET() {
+  try {
+    const installed = await checkInstalled();
+    if (!installed) {
+      return NextResponse.json({ installed: false, config: null, message: "Claude Desktop (Cowork mode) not detected" });
+    }
+    const meta = await readJson(await getMetaPath());
+    const appliedId = meta?.appliedId || null;
+    const configDir = await getConfigDir();
+    const configPath = appliedId ? path.join(configDir, `${appliedId}.json`) : null;
+    const config = configPath ? await readJson(configPath) : null;
+
+    const baseUrl = config?.inferenceGatewayBaseUrl || null;
+    const models = Array.isArray(config?.inferenceModels)
+      ? config.inferenceModels.map((m) => (typeof m === "string" ? m : m?.name)).filter(Boolean)
+      : [];
+    const managedMcp = Array.isArray(config?.managedMcpServers) ? config.managedMcpServers : [];
+    const has9Router = !!(config?.inferenceProvider === PROVIDER && baseUrl);
+
+    // Active local plugins = managedMcp entries whose URL points at our inline bridge.
+    const stdioNames = new Set(LOCAL_STDIO_PLUGINS.map((p) => p.name));
+    const activeLocalNames = managedMcp
+      .filter((m) => stdioNames.has(m.name) && typeof m.url === "string" && m.url.includes("/api/mcp/"))
+      .map((m) => m.name);
+
+    // Custom plugins = bridge entries not in preset LOCAL_STDIO_PLUGINS (custom:true or unknown name).
+    const activeCustomPlugins = managedMcp
+      .filter((m) => m.custom || (!stdioNames.has(m.name) && typeof m.url === "string" && m.url.includes("/api/mcp/")))
+      .map((m) => ({ name: m.name, url: m.url, transport: m.transport, custom: true }));
+
+    return NextResponse.json({
+      installed: true,
+      config,
+      has9Router,
+      configPath,
+      cowork: {
+        appliedId,
+        baseUrl,
+        models,
+        provider: config?.inferenceProvider || null,
+        plugins: managedMcp.filter((m) => !m.custom && !(stdioNames.has(m.name) && typeof m.url === "string" && m.url.includes("/api/mcp/"))).map((m) => {
+          // Strip "{name}-" prefix and dedupe so re-applies don't multiply entries.
+          const keys = m.toolPolicy ? Object.keys(m.toolPolicy) : [];
+          const prefix = `${m.name}-`;
+          const bare = new Set();
+          for (const k of keys) {
+            let t = k;
+            while (t.startsWith(prefix)) t = t.slice(prefix.length);
+            bare.add(t);
+          }
+          // If plugin matches a default, prefer default toolNames (curated/correct).
+          const def = DEFAULT_PLUGINS.find((d) => d.name === m.name);
+          const toolNames = def && Array.isArray(def.toolNames) ? def.toolNames : Array.from(bare);
+          return { name: m.name, url: m.url, transport: m.transport, oauth: !!m.oauth, toolNames };
+        }),
+        localPlugins: activeLocalNames,
+        customPlugins: activeCustomPlugins,
+      },
+      defaultPlugins: DEFAULT_PLUGINS,
+      localStdioPlugins: LOCAL_STDIO_PLUGINS,
+    });
+  } catch (error) {
+    console.log("Error reading cowork settings:", error);
+    return NextResponse.json({ error: "Failed to read cowork settings" }, { status: 500 });
+  }
+}
+
+export async function POST(request) {
+  try {
+    const { baseUrl, apiKey, models, plugins, localPlugins, customPlugins } = await request.json();
+
+    if (!baseUrl || !apiKey) {
+      return NextResponse.json({ error: "baseUrl and apiKey are required" }, { status: 400 });
+    }
+    const modelsArray = Array.isArray(models) ? models.filter((m) => typeof m === "string" && m.trim()) : [];
+    if (modelsArray.length === 0) {
+      return NextResponse.json({ error: "At least one model is required" }, { status: 400 });
+    }
+
+    // Respect empty array (user toggled all off); fallback to defaults only when undefined.
+    const pluginsArray = Array.isArray(plugins) ? plugins : DEFAULT_PLUGINS;
+    const localPluginNames = Array.isArray(localPlugins) ? localPlugins : [];
+    // Only URL-based custom plugins allowed (no stdio command spawning).
+    const customPluginsArray = (Array.isArray(customPlugins) ? customPlugins : []).filter((p) => p?.url);
+
+    const bridgeEntries = await injectAuthHeaders(buildLocalBridgeEntries(localPluginNames));
+    const customEntries = await injectAuthHeaders(buildCustomEntries(customPluginsArray));
+    const managedMcpServers = [...buildManagedMcpServers(pluginsArray), ...bridgeEntries, ...customEntries];
+
+    const bootstrapped = await bootstrapDeploymentMode();
+    const meta = await ensureMeta();
+    const configPath = path.join(getWriteConfigDir(), `${meta.appliedId}.json`);
+
+    const newConfig = {
+      ...SECURITY_RELAX,
+      inferenceProvider: PROVIDER,
+      inferenceGatewayBaseUrl: baseUrl,
+      inferenceGatewayApiKey: apiKey,
+      inferenceModels: modelsArray.map((name) => ({ name })),
+    };
+    if (managedMcpServers.length > 0) newConfig.managedMcpServers = managedMcpServers;
+
+    await fs.writeFile(configPath, JSON.stringify(newConfig, null, 2));
+
+    let skipResult = null;
+    try { skipResult = await writeSkipApprovals(managedMcpServers); } catch (e) { skipResult = { error: e.message }; }
+
+    // Best-effort cleanup of legacy 1p mcpServers entries written by earlier versions.
+    let localMcpResult = { applied: localPluginNames, via: "3p-sse-bridge" };
+    try { await cleanup1pLegacy(); } catch { /* ignore */ }
+
+    return NextResponse.json({
+      success: true,
+      bootstrapped,
+      message: bootstrapped
+        ? "Cowork enabled (3p mode set). Quit & reopen Claude Desktop."
+        : "Cowork settings applied. Quit & reopen Claude Desktop.",
+      configPath,
+      skipApprovals: skipResult,
+      localMcp: localMcpResult,
+    });
+  } catch (error) {
+    console.log("Error applying cowork settings:", error);
+    return NextResponse.json({ error: "Failed to apply cowork settings" }, { status: 500 });
+  }
+}
+
+export async function DELETE() {
+  try {
+    const meta = await readJson(await getMetaPath());
+    if (!meta?.appliedId) {
+      return NextResponse.json({ success: true, message: "No active config to reset" });
+    }
+    const configPath = path.join(await getConfigDir(), `${meta.appliedId}.json`);
+    try { await fs.writeFile(configPath, JSON.stringify({}, null, 2)); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+    try { await writeSkipApprovals([]); } catch { /* ignore */ }
+    try { await cleanup1pLegacy(); } catch { /* ignore */ }
+    return NextResponse.json({ success: true, message: "Cowork config reset" });
+  } catch (error) {
+    console.log("Error resetting cowork settings:", error);
+    return NextResponse.json({ error: "Failed to reset cowork settings" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/deepseek-tui-settings/route.js b/src/app/api/cli-tools/deepseek-tui-settings/route.js
new file mode 100644
index 0000000..0edf74d
--- /dev/null
+++ b/src/app/api/cli-tools/deepseek-tui-settings/route.js
@@ -0,0 +1,164 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+const execAsync = promisify(exec);
+
+const PROVIDER_NAME = "9router";
+
+const getDeepSeekDir = () => path.join(os.homedir(), ".deepseek");
+const getDeepSeekConfigPath = () => path.join(getDeepSeekDir(), "config.toml");
+
+// Simple TOML parser for key = "value" and [section] patterns
+const parseToml = (content) => {
+    const result = {};
+    let currentSection = result;
+
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip empty lines and comments
+        if (!trimmed || trimmed.startsWith("#")) continue;
+
+        // Section header: [section] or [section.subsection]
+        const sectionMatch = trimmed.match(/^\[([^\]]+)\]$/);
+        if (sectionMatch) {
+            const sectionName = sectionMatch[1];
+            if (!result[sectionName]) result[sectionName] = {};
+            currentSection = result[sectionName];
+            continue;
+        }
+
+        // Key = "value" or key = value
+        const keyValueMatch = trimmed.match(/^(\w+)\s*=\s*"([^"]*)"$/);
+        if (keyValueMatch) {
+            currentSection[keyValueMatch[1]] = keyValueMatch[2];
+            continue;
+        }
+
+        // Key = value (unquoted)
+        const unquotedMatch = trimmed.match(/^(\w+)\s*=\s*(.+)$/);
+        if (unquotedMatch) {
+            currentSection[unquotedMatch[1]] = unquotedMatch[2].trim();
+        }
+    }
+
+    return result;
+};
+
+// Build TOML config for 9Router (openai provider mode)
+const build9RouterConfig = (baseUrl, apiKey, model) => {
+    const normalizedBaseUrl = baseUrl.endsWith("/v1") ? baseUrl : `${baseUrl}/v1`;
+    return `provider = "openai"
+
+[providers.openai]
+base_url = "${normalizedBaseUrl}"
+api_key = "${apiKey}"
+model = "${model}"
+`;
+};
+
+// Default DeepSeek config (reset state)
+const DEFAULT_CONFIG = `provider = "deepseek"
+`;
+
+const checkDeepSeekInstalled = async () => {
+    try {
+        const isWindows = os.platform() === "win32";
+        const command = isWindows ? "where deepseek" : "which deepseek";
+        await execAsync(command, { windowsHide: true });
+        return true;
+    } catch {
+        try {
+            await fs.access(getDeepSeekConfigPath());
+            return true;
+        } catch {
+            return false;
+        }
+    }
+};
+
+const readConfigToml = async () => {
+    try {
+        return await fs.readFile(getDeepSeekConfigPath(), "utf-8");
+    } catch (error) {
+        if (error.code === "ENOENT") return "";
+        throw error;
+    }
+};
+
+// Detect 9Router by checking if provider is "openai" and base_url points to localhost/127.0.0.1
+const has9RouterConfig = (config) => {
+    if (!config) return false;
+    const provider = config.provider;
+    if (provider !== "openai") return false;
+    const openaiSection = config["providers.openai"];
+    if (!openaiSection?.base_url) return false;
+    return /localhost|127\.0\.0\.1|0\.0\.0\.0/.test(openaiSection.base_url);
+};
+
+export async function GET() {
+    try {
+        const installed = await checkDeepSeekInstalled();
+        if (!installed) {
+            return NextResponse.json({ installed: false, settings: null, message: "DeepSeek TUI is not installed" });
+        }
+        const toml = await readConfigToml();
+        const config = parseToml(toml);
+        return NextResponse.json({
+            installed: true,
+            settings: config,
+            has9Router: has9RouterConfig(config),
+            configPath: getDeepSeekConfigPath(),
+        });
+    } catch (error) {
+        console.log("Error checking deepseek-tui settings:", error);
+        return NextResponse.json({ error: "Failed to check deepseek-tui settings" }, { status: 500 });
+    }
+}
+
+export async function POST(request) {
+    try {
+        const { baseUrl, apiKey, model } = await request.json();
+        if (!baseUrl || !model) {
+            return NextResponse.json({ error: "baseUrl and model are required" }, { status: 400 });
+        }
+
+        const dir = getDeepSeekDir();
+        await fs.mkdir(dir, { recursive: true });
+
+        const newConfig = build9RouterConfig(baseUrl, apiKey || "sk_9router", model);
+        await fs.writeFile(getDeepSeekConfigPath(), newConfig);
+
+        return NextResponse.json({
+            success: true,
+            message: "DeepSeek TUI settings applied successfully!",
+            configPath: getDeepSeekConfigPath(),
+        });
+    } catch (error) {
+        console.log("Error updating deepseek-tui settings:", error);
+        return NextResponse.json({ error: "Failed to update deepseek-tui settings" }, { status: 500 });
+    }
+}
+
+export async function DELETE() {
+    try {
+        const configPath = getDeepSeekConfigPath();
+        try {
+            await fs.access(configPath);
+        } catch {
+            return NextResponse.json({ success: true, message: "No config file to reset" });
+        }
+
+        await fs.writeFile(configPath, DEFAULT_CONFIG);
+        return NextResponse.json({ success: true, message: `${PROVIDER_NAME} config reset to DeepSeek defaults` });
+    } catch (error) {
+        console.log("Error resetting deepseek-tui settings:", error);
+        return NextResponse.json({ error: "Failed to reset deepseek-tui settings" }, { status: 500 });
+    }
+}
\ No newline at end of file
diff --git a/src/app/api/cli-tools/droid-settings/route.js b/src/app/api/cli-tools/droid-settings/route.js
new file mode 100644
index 0000000..a416257
--- /dev/null
+++ b/src/app/api/cli-tools/droid-settings/route.js
@@ -0,0 +1,215 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+const execAsync = promisify(exec);
+
+const getDroidDir = () => path.join(os.homedir(), ".factory");
+const getDroidSettingsPath = () => path.join(getDroidDir(), "settings.json");
+
+// Check if droid CLI is installed (via which/where or config file exists)
+const checkDroidInstalled = async () => {
+  try {
+    const isWindows = os.platform() === "win32";
+    const command = isWindows ? "where droid" : "which droid";
+    const env = isWindows
+      ? { ...process.env, PATH: `${process.env.APPDATA}\\npm;${process.env.PATH}` }
+      : process.env;
+    await execAsync(command, { windowsHide: true, env });
+    return true;
+  } catch {
+    try {
+      await fs.access(getDroidSettingsPath());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// Read current settings.json
+const readSettings = async () => {
+  try {
+    const settingsPath = getDroidSettingsPath();
+    const content = await fs.readFile(settingsPath, "utf-8");
+    // Tolerate JSONC (trailing commas) and treat unparseable files as "no config"
+    // rather than throwing a 500 that the UI misreads as "tool not installed".
+    const stripped = content.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch (error) {
+    return null;
+  }
+};
+
+// Check if settings has 9Router customModels
+const has9RouterConfig = (settings) => {
+  if (!settings || !settings.customModels) return false;
+  return settings.customModels.some(m => m.id?.startsWith("custom:9Router"));
+};
+
+// GET - Check droid CLI and read current settings
+export async function GET() {
+  try {
+    const isInstalled = await checkDroidInstalled();
+    
+    if (!isInstalled) {
+      return NextResponse.json({
+        installed: false,
+        settings: null,
+        message: "Factory Droid CLI is not installed",
+      });
+    }
+
+    const settings = await readSettings();
+
+    return NextResponse.json({
+      installed: true,
+      settings,
+      has9Router: has9RouterConfig(settings),
+      settingsPath: getDroidSettingsPath(),
+    });
+  } catch (error) {
+    console.log("Error checking droid settings:", error);
+    return NextResponse.json({ error: "Failed to check droid settings" }, { status: 500 });
+  }
+}
+
+// POST - Update 9Router customModels (merge with existing settings)
+// Accepts either `model` (string, legacy single-model) or `models` (array of strings, multi-model)
+// Also accepts `activeModel` to set which model is active/primary
+export async function POST(request) {
+  try {
+    const { baseUrl, apiKey, model, models, activeModel } = await request.json();
+    
+    // Accept either `models` (array) or `model` (string, legacy)
+    const modelsArray = Array.isArray(models) ? models.slice() : (typeof model === "string" ? [model] : []);
+    
+    if (!baseUrl || modelsArray.length === 0) {
+      return NextResponse.json({ error: "baseUrl and at least one model are required" }, { status: 400 });
+    }
+
+    const droidDir = getDroidDir();
+    const settingsPath = getDroidSettingsPath();
+
+    // Ensure directory exists
+    await fs.mkdir(droidDir, { recursive: true });
+
+    // Read existing settings or create new
+    let settings = {};
+    try {
+      const existingSettings = await fs.readFile(settingsPath, "utf-8");
+      settings = JSON.parse(existingSettings);
+    } catch { /* No existing settings */ }
+
+    // Ensure customModels array exists
+    if (!settings.customModels) {
+      settings.customModels = [];
+    }
+
+    // Remove all existing 9Router configs
+    settings.customModels = settings.customModels.filter(m => !m.id?.startsWith("custom:9Router"));
+
+    // Normalize baseUrl to ensure /v1 suffix
+    const normalizedBaseUrl = baseUrl.endsWith("/v1") ? baseUrl : `${baseUrl}/v1`;
+    const keyToUse = apiKey || "your_api_key";
+
+    // Determine active model: prefer explicit activeModel, else first of modelsArray
+    // If activeModel is explicitly empty string, no model will be set as default
+    let defaultIndex = 0;
+    if (typeof activeModel === "string") {
+      if (activeModel === "") {
+        defaultIndex = -1; // signal: don't set a default
+      } else {
+        const idx = modelsArray.indexOf(activeModel);
+        defaultIndex = idx >= 0 ? idx : 0;
+      }
+    }
+
+    // Add entries for all requested models
+    // The first one (index 0) will be the default if defaultIndex >= 0
+    for (let i = 0; i < modelsArray.length; i++) {
+      const m = modelsArray[i];
+      if (!m || typeof m !== "string") continue;
+      settings.customModels.push({
+        model: m,
+        id: `custom:9Router-${i}`,
+        index: i,
+        baseUrl: normalizedBaseUrl,
+        apiKey: keyToUse,
+        displayName: m,
+        maxOutputTokens: 131072,
+        noImageSupport: false,
+        provider: "openai",
+      });
+    }
+
+    // Set default model if applicable
+    if (defaultIndex >= 0 && settings.customModels[defaultIndex]) {
+      // Reorder so the default comes first
+      const [defaultEntry] = settings.customModels.splice(defaultIndex, 1);
+      settings.customModels.unshift({ ...defaultEntry, index: 0 });
+      // Re-index the rest
+      settings.customModels.forEach((m, i) => { m.index = i; });
+    }
+
+    // Write settings
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "Factory Droid settings applied successfully!",
+      settingsPath,
+    });
+  } catch (error) {
+    console.log("Error updating droid settings:", error);
+    return NextResponse.json({ error: "Failed to update droid settings" }, { status: 500 });
+  }
+}
+
+// DELETE - Remove 9Router customModels only (keep other settings)
+export async function DELETE() {
+  try {
+    const settingsPath = getDroidSettingsPath();
+
+    // Read existing settings
+    let settings = {};
+    try {
+      const existingSettings = await fs.readFile(settingsPath, "utf-8");
+      settings = JSON.parse(existingSettings);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return NextResponse.json({
+          success: true,
+          message: "No settings file to reset",
+        });
+      }
+      throw error;
+    }
+
+    // Remove 9Router customModels
+    if (settings.customModels) {
+      settings.customModels = settings.customModels.filter(m => !m.id?.startsWith("custom:9Router"));
+      
+      // Remove customModels array if empty
+      if (settings.customModels.length === 0) {
+        delete settings.customModels;
+      }
+    }
+
+    // Write updated settings
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "9Router settings removed successfully",
+    });
+  } catch (error) {
+    console.log("Error resetting droid settings:", error);
+    return NextResponse.json({ error: "Failed to reset droid settings" }, { status: 500 });
+  }
+}
\ No newline at end of file
diff --git a/src/app/api/cli-tools/hermes-settings/route.js b/src/app/api/cli-tools/hermes-settings/route.js
new file mode 100644
index 0000000..104c4f1
--- /dev/null
+++ b/src/app/api/cli-tools/hermes-settings/route.js
@@ -0,0 +1,175 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+const execAsync = promisify(exec);
+
+const PROVIDER_NAME = "9router";
+const API_KEY_ENV = "OPENAI_API_KEY";
+
+const getHermesDir = () => path.join(os.homedir(), ".hermes");
+const getHermesConfigPath = () => path.join(getHermesDir(), "config.yaml");
+const getHermesEnvPath = () => path.join(getHermesDir(), ".env");
+
+// Match top-level "model:" block (until next non-indented, non-empty line)
+const MODEL_BLOCK_RE = /^model:[ \t]*\r?\n((?:[ \t]+.*\r?\n?|[ \t]*\r?\n)*)/m;
+
+const buildModelBlock = (model, baseUrl) =>
+  `model:\n  default: "${model}"\n  provider: "custom"\n  base_url: "${baseUrl}"\n`;
+
+// Parse current model block back to fields (best-effort, simple key:value)
+const parseModelBlock = (yaml) => {
+  const match = yaml.match(MODEL_BLOCK_RE);
+  if (!match) return null;
+  const body = match[1] || "";
+  const get = (key) => {
+    const m = body.match(new RegExp(`^[ \\t]+${key}:[ \\t]*["']?([^"'\\r\\n]+)["']?`, "m"));
+    return m ? m[1].trim() : null;
+  };
+  return {
+    default: get("default"),
+    provider: get("provider"),
+    base_url: get("base_url"),
+  };
+};
+
+const upsertModelBlock = (yaml, newBlock) => {
+  if (MODEL_BLOCK_RE.test(yaml)) return yaml.replace(MODEL_BLOCK_RE, newBlock);
+  return yaml.length > 0 ? `${newBlock}\n${yaml}` : newBlock;
+};
+
+const removeModelBlock = (yaml) => yaml.replace(MODEL_BLOCK_RE, "").replace(/^\n+/, "");
+
+// .env helpers — upsert/remove single KEY=VALUE line
+const upsertEnvVar = (envText, key, value) => {
+  const re = new RegExp(`^${key}=.*$`, "m");
+  const line = `${key}=${value}`;
+  if (re.test(envText)) return envText.replace(re, line);
+  return envText.length > 0 && !envText.endsWith("\n") ? `${envText}\n${line}\n` : `${envText}${line}\n`;
+};
+
+const removeEnvVar = (envText, key) => {
+  const re = new RegExp(`^${key}=.*\\r?\\n?`, "m");
+  return envText.replace(re, "");
+};
+
+const checkHermesInstalled = async () => {
+  try {
+    const isWindows = os.platform() === "win32";
+    const command = isWindows ? "where hermes" : "which hermes";
+    await execAsync(command, { windowsHide: true });
+    return true;
+  } catch {
+    try {
+      await fs.access(getHermesConfigPath());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+const readConfigYaml = async () => {
+  try {
+    return await fs.readFile(getHermesConfigPath(), "utf-8");
+  } catch (error) {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  }
+};
+
+const readEnvFile = async () => {
+  try {
+    return await fs.readFile(getHermesEnvPath(), "utf-8");
+  } catch (error) {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  }
+};
+
+// Detect 9router by base_url containing localhost/127.0.0.1 or matching tunnel URL
+const has9RouterConfig = (modelCfg) => {
+  if (!modelCfg?.base_url) return false;
+  return modelCfg.provider === "custom" && /localhost|127\.0\.0\.1|0\.0\.0\.0/.test(modelCfg.base_url);
+};
+
+export async function GET() {
+  try {
+    const installed = await checkHermesInstalled();
+    if (!installed) {
+      return NextResponse.json({ installed: false, settings: null, message: "Hermes Agent is not installed" });
+    }
+    const yaml = await readConfigYaml();
+    const model = parseModelBlock(yaml);
+    return NextResponse.json({
+      installed: true,
+      settings: { model },
+      has9Router: has9RouterConfig(model),
+      configPath: getHermesConfigPath(),
+    });
+  } catch (error) {
+    console.log("Error checking hermes settings:", error);
+    return NextResponse.json({ error: "Failed to check hermes settings" }, { status: 500 });
+  }
+}
+
+export async function POST(request) {
+  try {
+    const { baseUrl, apiKey, model } = await request.json();
+    if (!baseUrl || !model) {
+      return NextResponse.json({ error: "baseUrl and model are required" }, { status: 400 });
+    }
+
+    const dir = getHermesDir();
+    await fs.mkdir(dir, { recursive: true });
+
+    const normalizedBaseUrl = baseUrl.endsWith("/v1") ? baseUrl : `${baseUrl}/v1`;
+
+    // Update config.yaml — replace/insert model: block, keep everything else
+    const existingYaml = await readConfigYaml();
+    const newYaml = upsertModelBlock(existingYaml, buildModelBlock(model, normalizedBaseUrl));
+    await fs.writeFile(getHermesConfigPath(), newYaml);
+
+    // Update .env — upsert OPENAI_API_KEY only when caller provides one
+    if (apiKey) {
+      const existingEnv = await readEnvFile();
+      const newEnv = upsertEnvVar(existingEnv, API_KEY_ENV, apiKey);
+      await fs.writeFile(getHermesEnvPath(), newEnv);
+    }
+
+    return NextResponse.json({
+      success: true,
+      message: "Hermes settings applied successfully!",
+      configPath: getHermesConfigPath(),
+    });
+  } catch (error) {
+    console.log("Error updating hermes settings:", error);
+    return NextResponse.json({ error: "Failed to update hermes settings" }, { status: 500 });
+  }
+}
+
+export async function DELETE() {
+  try {
+    const configPath = getHermesConfigPath();
+    let yaml = "";
+    try {
+      yaml = await fs.readFile(configPath, "utf-8");
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return NextResponse.json({ success: true, message: "No config file to reset" });
+      }
+      throw error;
+    }
+    const newYaml = removeModelBlock(yaml);
+    await fs.writeFile(configPath, newYaml);
+    return NextResponse.json({ success: true, message: `${PROVIDER_NAME} model block removed` });
+  } catch (error) {
+    console.log("Error resetting hermes settings:", error);
+    return NextResponse.json({ error: "Failed to reset hermes settings" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/jcode-settings/route.js b/src/app/api/cli-tools/jcode-settings/route.js
new file mode 100644
index 0000000..9e05a16
--- /dev/null
+++ b/src/app/api/cli-tools/jcode-settings/route.js
@@ -0,0 +1,216 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { exec } from "child_process";
+import { promisify } from "util";
+import { parseTOML, stringifyTOML } from "confbox";
+
+const execAsync = promisify(exec);
+
+const getJcodeConfigDir = () => path.join(os.homedir(), ".jcode");
+const getConfigPath = () => path.join(getJcodeConfigDir(), "config.toml");
+
+const getProviderEnvPath = () => {
+  const configDir = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(configDir, "jcode", "provider-9router.env");
+};
+
+const checkJcodeInstalled = async () => {
+  try {
+    const isWindows = os.platform() === "win32";
+    const command = isWindows ? "where jcode" : "which jcode";
+    await execAsync(command, { windowsHide: true });
+    return true;
+  } catch {
+    try {
+      await fs.access(getJcodeConfigDir());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+const readConfig = async () => {
+  try {
+    const configPath = getConfigPath();
+    const content = await fs.readFile(configPath, "utf-8");
+    return parseTOML(content);
+  } catch (error) {
+    return { providers: {} };
+  }
+};
+
+const has9RouterConfig = (config) => {
+  if (!config || !config.providers) return false;
+
+  const providers = config.providers;
+
+  if (providers["9router"]) return true;
+
+  for (const [name, provider] of Object.entries(providers)) {
+    if (provider.base_url && provider.base_url.includes("localhost:20128")) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+const writeConfig = async (config) => {
+  const configPath = getConfigPath();
+  const content = stringifyTOML(config);
+  await fs.writeFile(configPath, content, "utf-8");
+};
+
+const readProviderEnv = async () => {
+  try {
+    const envPath = getProviderEnvPath();
+    const content = await fs.readFile(envPath, "utf-8");
+    const env = {};
+
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+
+      const eqIndex = trimmed.indexOf("=");
+      if (eqIndex > 0) {
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+          value = value.slice(1, -1);
+        }
+
+        env[key] = value;
+      }
+    }
+
+    return env;
+  } catch {
+    return {};
+  }
+};
+
+const writeProviderEnv = async (env) => {
+  const envPath = getProviderEnvPath();
+  let content = "# jcode provider environment variables\n";
+
+  for (const [key, value] of Object.entries(env)) {
+    content += `${key}="${value}"\n`;
+  }
+
+  await fs.writeFile(envPath, content, "utf-8");
+};
+
+export async function GET() {
+  const isInstalled = await checkJcodeInstalled();
+
+  if (!isInstalled) {
+    return NextResponse.json({
+      installed: false,
+      message: "jcode not installed. Install via: curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash",
+    });
+  }
+
+  const config = await readConfig();
+  const has9Router = has9RouterConfig(config);
+
+  return NextResponse.json({
+    installed: true,
+    config,
+    has9Router,
+    configPath: getConfigPath(),
+  });
+}
+
+export async function POST(request) {
+  try {
+    const { baseUrl, apiKey, models } = await request.json();
+
+    if (!baseUrl || !apiKey) {
+      return NextResponse.json(
+        { error: "baseUrl and apiKey are required" },
+        { status: 400 }
+      );
+    }
+
+    const normalizedBaseUrl = baseUrl.endsWith("/v1")
+      ? baseUrl
+      : `${baseUrl}/v1`;
+
+    let config = await readConfig();
+
+    if (!config.providers) {
+      config.providers = {};
+    }
+
+    config.providers["9router"] = {
+      type: "openai-compatible",
+      base_url: normalizedBaseUrl,
+      auth: "bearer",
+      api_key_env: "JCODE_9ROUTER_API_KEY",
+      env_file: "provider-9router.env",
+      default_model: models && models.length > 0 ? models[0] : "cc/claude-opus-4-7",
+      requires_api_key: true,
+    };
+
+    const configDir = getJcodeConfigDir();
+    await fs.mkdir(configDir, { recursive: true });
+
+    await writeConfig(config);
+
+    const xdgConfigDir = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+    const jcodeConfigDir = path.join(xdgConfigDir, "jcode");
+    await fs.mkdir(jcodeConfigDir, { recursive: true });
+
+    const env = await readProviderEnv();
+    env.JCODE_9ROUTER_API_KEY = apiKey;
+    await writeProviderEnv(env);
+
+    return NextResponse.json({
+      success: true,
+      message: "jcode configured successfully. Use: jcode --provider-profile 9router",
+      configPath: getConfigPath(),
+    });
+  } catch (error) {
+    console.error("Error configuring jcode:", error);
+    return NextResponse.json(
+      { error: error.message },
+      { status: 500 }
+    );
+  }
+}
+
+export async function DELETE() {
+  try {
+    const config = await readConfig();
+
+    if (!config.providers) {
+      return NextResponse.json({ success: true, message: "No configuration to remove" });
+    }
+
+    delete config.providers["9router"];
+
+    await writeConfig(config);
+
+    const env = await readProviderEnv();
+    delete env.JCODE_9ROUTER_API_KEY;
+    await writeProviderEnv(env);
+
+    return NextResponse.json({
+      success: true,
+      message: "9router configuration removed from jcode",
+    });
+  } catch (error) {
+    console.error("Error removing jcode configuration:", error);
+    return NextResponse.json(
+      { error: error.message },
+      { status: 500 }
+    );
+  }
+}
diff --git a/src/app/api/cli-tools/kilo-settings/route.js b/src/app/api/cli-tools/kilo-settings/route.js
new file mode 100644
index 0000000..9c5993f
--- /dev/null
+++ b/src/app/api/cli-tools/kilo-settings/route.js
@@ -0,0 +1,133 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+const execAsync = promisify(exec);
+
+const getDataDir = () => path.join(os.homedir(), ".local", "share", "kilo");
+const getAuthPath = () => path.join(getDataDir(), "auth.json");
+const getVscodeSettingsPath = () => path.join(os.homedir(), ".config", "Code", "User", "settings.json");
+
+const checkInstalled = async () => {
+  try {
+    const isWindows = os.platform() === "win32";
+    const command = isWindows ? "where kilo" : "which kilo";
+    const env = isWindows
+      ? { ...process.env, PATH: `${process.env.APPDATA}\\npm;${process.env.PATH}` }
+      : process.env;
+    await execAsync(command, { windowsHide: true, env });
+    return true;
+  } catch {
+    try {
+      await fs.access(getAuthPath());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+const readJson = async (filePath) => {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    // Tolerate JSONC (trailing commas) and treat unparseable files as "no config"
+    // rather than throwing a 500 that the UI misreads as "tool not installed".
+    const stripped = content.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch (error) {
+    return null;
+  }
+};
+
+const has9RouterConfig = (auth) => {
+  if (!auth) return false;
+  const entry = auth["openai-compatible"] || auth["9router"];
+  if (!entry) return false;
+  const baseUrl = entry.baseUrl || entry.baseURL || "";
+  return baseUrl.includes("localhost") || baseUrl.includes("127.0.0.1") || baseUrl.includes("9router");
+};
+
+export async function GET() {
+  try {
+    const installed = await checkInstalled();
+    if (!installed) {
+      return NextResponse.json({ installed: false, settings: null, message: "Kilo Code CLI is not installed" });
+    }
+    const auth = await readJson(getAuthPath());
+    return NextResponse.json({
+      installed: true,
+      settings: { auth: auth ? Object.keys(auth) : [] },
+      has9Router: has9RouterConfig(auth),
+      authPath: getAuthPath(),
+    });
+  } catch (error) {
+    console.log("Error checking kilo settings:", error);
+    return NextResponse.json({ error: "Failed to check kilo settings" }, { status: 500 });
+  }
+}
+
+export async function POST(request) {
+  try {
+    const { baseUrl, apiKey, model } = await request.json();
+    if (!baseUrl || !apiKey || !model) {
+      return NextResponse.json({ error: "baseUrl, apiKey and model are required" }, { status: 400 });
+    }
+
+    await fs.mkdir(getDataDir(), { recursive: true });
+
+    const normalizedBaseUrl = baseUrl.endsWith("/v1") ? baseUrl : `${baseUrl}/v1`;
+
+    const auth = (await readJson(getAuthPath())) || {};
+    auth["openai-compatible"] = {
+      type: "api-key",
+      apiKey,
+      baseUrl: normalizedBaseUrl,
+      model,
+    };
+    await fs.writeFile(getAuthPath(), JSON.stringify(auth, null, 2));
+
+    // Best-effort: update VS Code extension settings
+    try {
+      const vscode = (await readJson(getVscodeSettingsPath())) || {};
+      vscode["kilocode.customProvider"] = { name: "9Router", baseURL: normalizedBaseUrl, apiKey };
+      vscode["kilocode.defaultModel"] = model;
+      await fs.writeFile(getVscodeSettingsPath(), JSON.stringify(vscode, null, 2));
+    } catch { /* VS Code settings not writable */ }
+
+    return NextResponse.json({ success: true, message: "Kilo Code settings applied successfully!", authPath: getAuthPath() });
+  } catch (error) {
+    console.log("Error updating kilo settings:", error);
+    return NextResponse.json({ error: "Failed to update kilo settings" }, { status: 500 });
+  }
+}
+
+export async function DELETE() {
+  try {
+    const auth = await readJson(getAuthPath());
+    if (!auth) {
+      return NextResponse.json({ success: true, message: "No settings file to reset" });
+    }
+    delete auth["openai-compatible"];
+    delete auth["9router"];
+    await fs.writeFile(getAuthPath(), JSON.stringify(auth, null, 2));
+
+    try {
+      const vscode = await readJson(getVscodeSettingsPath());
+      if (vscode) {
+        delete vscode["kilocode.customProvider"];
+        delete vscode["kilocode.defaultModel"];
+        await fs.writeFile(getVscodeSettingsPath(), JSON.stringify(vscode, null, 2));
+      }
+    } catch { /* ignore */ }
+
+    return NextResponse.json({ success: true, message: "9Router settings removed from Kilo Code" });
+  } catch (error) {
+    console.log("Error resetting kilo settings:", error);
+    return NextResponse.json({ error: "Failed to reset kilo settings" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/openclaw-settings/route.js b/src/app/api/cli-tools/openclaw-settings/route.js
new file mode 100644
index 0000000..2047a25
--- /dev/null
+++ b/src/app/api/cli-tools/openclaw-settings/route.js
@@ -0,0 +1,294 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+const execAsync = promisify(exec);
+
+// OpenClaw 2026.5.x writes agents[].model as either a plain string
+// (legacy) or as an object `{ primary, fallbacks }`. Normalize to the
+// string id so downstream consumers can call `.startsWith()` safely.
+const resolveAgentModel = (m) => {
+  if (typeof m === "string") return m;
+  if (m && typeof m === "object") return m.primary ?? "";
+  return "";
+};
+
+const getOpenClawDir = () => path.join(os.homedir(), ".openclaw");
+const getOpenClawSettingsPath = () => path.join(getOpenClawDir(), "openclaw.json");
+
+// Check if openclaw CLI is installed (via which/where or config file exists)
+const checkOpenClawInstalled = async () => {
+  try {
+    const isWindows = os.platform() === "win32";
+    const command = isWindows ? "where openclaw" : "which openclaw";
+    // On Windows, inject %APPDATA%\npm into PATH so npm global packages are found
+    const env = isWindows
+      ? { ...process.env, PATH: `${process.env.APPDATA}\\npm;${process.env.PATH}` }
+      : process.env;
+    await execAsync(command, { windowsHide: true, env });
+    return true;
+  } catch {
+    try {
+      await fs.access(getOpenClawSettingsPath());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// Read current settings.json
+const readSettings = async () => {
+  try {
+    const settingsPath = getOpenClawSettingsPath();
+    const content = await fs.readFile(settingsPath, "utf-8");
+    // Tolerate JSONC (trailing commas) and treat unparseable files as "no config"
+    // rather than throwing a 500 that the UI misreads as "tool not installed".
+    const stripped = content.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch (error) {
+    return null;
+  }
+};
+
+// Check if settings has 9Router config
+const has9RouterConfig = (settings) => {
+  if (!settings || !settings.models || !settings.models.providers) return false;
+  return !!settings.models.providers["9router"];
+};
+
+// Read per-agent models.json and return current model id (without "9router/" prefix)
+const readAgentModel = async (agentDir) => {
+  try {
+    const modelsPath = path.join(agentDir, "models.json");
+    const content = await fs.readFile(modelsPath, "utf-8");
+    const data = JSON.parse(content);
+    const models = data?.providers?.["9router"]?.models;
+    return models?.[0]?.id || null;
+  } catch {
+    return null;
+  }
+};
+
+// GET - Check openclaw CLI and read current settings
+export async function GET() {
+  try {
+    const isInstalled = await checkOpenClawInstalled();
+    
+    if (!isInstalled) {
+      return NextResponse.json({
+        installed: false,
+        settings: null,
+        message: "Open Claw CLI is not installed",
+      });
+    }
+
+    const settings = await readSettings();
+
+    // Enrich agents list with current per-agent model from models.json.
+    // Coerce agent.model to its string id when OpenClaw stores it as
+    // `{ primary, fallbacks }` so downstream `.startsWith()` calls work.
+    const agentList = settings?.agents?.list || [];
+    const enrichedAgents = await Promise.all(
+      agentList.map(async (agent) => {
+        const agentModel = agent.agentDir ? await readAgentModel(agent.agentDir) : null;
+        return { ...agent, model: resolveAgentModel(agent.model), currentModel: agentModel };
+      })
+    );
+
+    return NextResponse.json({
+      installed: true,
+      settings,
+      agents: enrichedAgents,
+      has9Router: has9RouterConfig(settings),
+      settingsPath: getOpenClawSettingsPath(),
+    });
+  } catch (error) {
+    console.log("Error checking openclaw settings:", error);
+    return NextResponse.json({ error: "Failed to check openclaw settings" }, { status: 500 });
+  }
+}
+
+// Write per-agent models.json
+const writeAgentModels = async (agentDir, model, baseUrl, apiKey) => {
+  await fs.mkdir(agentDir, { recursive: true });
+  const modelsPath = path.join(agentDir, "models.json");
+  let existing = {};
+  try {
+    const content = await fs.readFile(modelsPath, "utf-8");
+    existing = JSON.parse(content);
+  } catch { /* No existing */ }
+
+  if (!existing.providers) existing.providers = {};
+  existing.providers["9router"] = {
+    baseUrl,
+    apiKey: apiKey || "your_api_key",
+    api: "openai-completions",
+    models: [{ id: model, name: model.split("/").pop() || model }],
+  };
+  await fs.writeFile(modelsPath, JSON.stringify(existing, null, 2));
+};
+
+// POST - Update 9Router settings (merge with existing settings)
+export async function POST(request) {
+  try {
+    // agentModels: { [agentId]: modelId } for per-agent override
+    const { baseUrl, apiKey, model, agentModels = {} } = await request.json();
+    
+    if (!baseUrl || !model) {
+      return NextResponse.json({ error: "baseUrl and model are required" }, { status: 400 });
+    }
+
+    const openclawDir = getOpenClawDir();
+    const settingsPath = getOpenClawSettingsPath();
+
+    await fs.mkdir(openclawDir, { recursive: true });
+
+    let settings = {};
+    try {
+      const existingSettings = await fs.readFile(settingsPath, "utf-8");
+      settings = JSON.parse(existingSettings);
+    } catch { /* No existing settings */ }
+
+    if (!settings.agents) settings.agents = {};
+    if (!settings.agents.defaults) settings.agents.defaults = {};
+    if (!settings.agents.defaults.model) settings.agents.defaults.model = {};
+    if (!settings.agents.defaults.models) settings.agents.defaults.models = {};
+    if (!settings.models) settings.models = {};
+    if (!settings.models.providers) settings.models.providers = {};
+
+    const normalizedBaseUrl = baseUrl.endsWith("/v1") ? baseUrl : `${baseUrl}/v1`;
+    const fullModelId = `9router/${model}`;
+
+    // Remove all old 9router/* entries from agents.defaults.models
+    Object.keys(settings.agents.defaults.models)
+      .filter((k) => k.startsWith("9router/"))
+      .forEach((k) => { delete settings.agents.defaults.models[k]; });
+
+    // Update default model
+    settings.agents.defaults.model.primary = fullModelId;
+
+    // Collect all unique models (default + per-agent)
+    const allModelIds = new Set([model]);
+    Object.values(agentModels).forEach((m) => { if (m) allModelIds.add(m); });
+
+    // Add fresh 9router models to allowlist
+    allModelIds.forEach((m) => {
+      settings.agents.defaults.models[`9router/${m}`] = {};
+    });
+
+    // Remove old 9router model from each agent in agents.list. The
+    // model field may be a plain string or `{ primary, fallbacks }`.
+    if (settings.agents.list) {
+      settings.agents.list = settings.agents.list.map((agent) => {
+        if (resolveAgentModel(agent.model).startsWith("9router/")) {
+          const { model: _, ...rest } = agent;
+          return rest;
+        }
+        return agent;
+      });
+    }
+
+    // Update models.providers.9router with all models
+    settings.models.providers["9router"] = {
+      baseUrl: normalizedBaseUrl,
+      apiKey: apiKey || "your_api_key",
+      api: "openai-completions",
+      models: [...allModelIds].map((m) => ({ id: m, name: m.split("/").pop() || m })),
+    };
+
+    // Set per-agent model in agents.list and write models.json
+    if (settings.agents.list) {
+      settings.agents.list = settings.agents.list.map((agent) => {
+        const agentModel = agentModels[agent.id];
+        if (agentModel) return { ...agent, model: `9router/${agentModel}` };
+        return agent;
+      });
+
+      // Write per-agent models.json for agents with agentDir
+      await Promise.all(
+        settings.agents.list.map(async (agent) => {
+          if (!agent.agentDir) return;
+          const agentModel = agentModels[agent.id];
+          const modelToWrite = agentModel || model; // fallback to default
+          await writeAgentModels(agent.agentDir, modelToWrite, normalizedBaseUrl, apiKey);
+        })
+      );
+    }
+
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "Open Claw settings applied successfully!",
+      settingsPath,
+    });
+  } catch (error) {
+    console.log("Error updating openclaw settings:", error);
+    return NextResponse.json({ error: "Failed to update openclaw settings" }, { status: 500 });
+  }
+}
+
+// DELETE - Remove 9Router settings only (keep other settings)
+export async function DELETE() {
+  try {
+    const settingsPath = getOpenClawSettingsPath();
+
+    // Read existing settings
+    let settings = {};
+    try {
+      const existingSettings = await fs.readFile(settingsPath, "utf-8");
+      settings = JSON.parse(existingSettings);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return NextResponse.json({
+          success: true,
+          message: "No settings file to reset",
+        });
+      }
+      throw error;
+    }
+
+    // Remove 9Router from models.providers
+    if (settings.models && settings.models.providers) {
+      delete settings.models.providers["9router"];
+      
+      // Remove providers object if empty
+      if (Object.keys(settings.models.providers).length === 0) {
+        delete settings.models.providers;
+      }
+    }
+
+    // Remove 9router models from agents.defaults.models allowlist
+    if (settings.agents?.defaults?.models) {
+      const keysToRemove = Object.keys(settings.agents.defaults.models).filter((k) => k.startsWith("9router/"));
+      for (const key of keysToRemove) {
+        delete settings.agents.defaults.models[key];
+      }
+      if (Object.keys(settings.agents.defaults.models).length === 0) {
+        delete settings.agents.defaults.models;
+      }
+    }
+
+    // Reset agents.defaults.model.primary if it uses 9router
+    if (settings.agents?.defaults?.model?.primary?.startsWith("9router/")) {
+      delete settings.agents.defaults.model.primary;
+    }
+
+    // Write updated settings
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "9Router settings removed successfully",
+    });
+  } catch (error) {
+    console.log("Error resetting openclaw settings:", error);
+    return NextResponse.json({ error: "Failed to reset openclaw settings" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/cli-tools/opencode-settings/route.js b/src/app/api/cli-tools/opencode-settings/route.js
new file mode 100644
index 0000000..03819c6
--- /dev/null
+++ b/src/app/api/cli-tools/opencode-settings/route.js
@@ -0,0 +1,265 @@
+"use server";
+
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+const execAsync = promisify(exec);
+
+const getConfigDir = () => path.join(os.homedir(), ".config", "opencode");
+const getConfigPath = () => path.join(getConfigDir(), "opencode.json");
+
+// Check if opencode CLI is installed (via which/where or config file exists)
+const checkOpenCodeInstalled = async () => {
+  try {
+    const isWindows = os.platform() === "win32";
+    const command = isWindows ? "where opencode" : "which opencode";
+    const env = isWindows
+      ? { ...process.env, PATH: `${process.env.APPDATA}\\npm;${process.env.PATH}` }
+      : process.env;
+    await execAsync(command, { windowsHide: true, env });
+    return true;
+  } catch {
+    try {
+      await fs.access(getConfigPath());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+const readConfig = async () => {
+  try {
+    const content = await fs.readFile(getConfigPath(), "utf-8");
+    // opencode config files may use JSONC format (trailing commas, comments).
+    // Strip trailing commas before parsing to avoid SyntaxError on valid JSONC.
+    const stripped = content.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    // If the config file exists but is unparseable (corrupted, exotic JSONC),
+    // treat it as "no config" rather than throwing a 500 that the UI
+    // misinterprets as "opencode not installed".
+    return null;
+  }
+};
+
+const has9RouterConfig = (config) => {
+  if (!config?.provider) return false;
+  return !!config.provider["9router"];
+};
+
+// GET - Check opencode CLI and read current settings
+export async function GET() {
+  try {
+    const isInstalled = await checkOpenCodeInstalled();
+
+    if (!isInstalled) {
+      return NextResponse.json({
+        installed: false,
+        config: null,
+        message: "OpenCode CLI is not installed",
+      });
+    }
+
+    const config = await readConfig();
+    const providerConfig = config?.provider?.["9router"];
+    const modelMap = providerConfig?.models || {};
+
+    return NextResponse.json({
+      installed: true,
+      config,
+      has9Router: has9RouterConfig(config),
+      configPath: getConfigPath(),
+        opencode: {
+          models: Object.keys(modelMap),
+          activeModel: config?.model?.startsWith("9router/") ? config.model.replace(/^9router\//, "") : null,
+          baseURL: providerConfig?.options?.baseURL || null,
+        },
+    });
+  } catch (error) {
+    console.log("Error checking opencode settings:", error);
+    return NextResponse.json({ error: "Failed to check opencode settings" }, { status: 500 });
+  }
+}
+
+// POST - Apply 9Router as openai-compatible provider (multi-model support)
+export async function POST(request) {
+  try {
+    const { baseUrl, apiKey, model, models, activeModel, subagentModel } = await request.json();
+
+    // Accept either `model` (string, legacy) or `models` (array of strings)
+    const modelsArray = Array.isArray(models) ? models.slice() : (typeof model === "string" ? [model] : []);
+
+    if (!baseUrl || modelsArray.length === 0) {
+      return NextResponse.json({ error: "baseUrl and at least one model are required" }, { status: 400 });
+    }
+
+    const configDir = getConfigDir();
+    const configPath = getConfigPath();
+
+    await fs.mkdir(configDir, { recursive: true });
+
+    // Read existing config or start fresh
+    let config = {};
+    try {
+      const existing = await fs.readFile(configPath, "utf-8");
+      config = JSON.parse(existing);
+    } catch { /* No existing config */ }
+
+    const normalizedBaseUrl = baseUrl.endsWith("/v1") ? baseUrl : `${baseUrl}/v1`;
+    const keyToUse = apiKey || "sk_9router";
+    const effectiveSubagentModel = subagentModel || modelsArray[0];
+
+    // Ensure provider object
+    if (!config.provider) config.provider = {};
+
+    // Preserve any existing 9router provider entry and its models
+    const existingProvider = config.provider["9router"] || { npm: "@ai-sdk/openai-compatible", options: {}, models: {} };
+
+    // Merge options (overwrite baseURL/apiKey)
+    existingProvider.options = {
+      ...existingProvider.options,
+      baseURL: normalizedBaseUrl,
+      apiKey: keyToUse,
+    };
+
+    // Ensure models map exists
+    existingProvider.models = existingProvider.models || {};
+
+    // Add or update entries for all requested models
+    for (const m of modelsArray) {
+      if (!m || typeof m !== "string") continue;
+      existingProvider.models[m] = { name: m, modalities: { input: ["text", "image"], output: ["text"] } };
+    }
+
+    // Save merged provider back
+    config.provider["9router"] = existingProvider;
+
+    // Set the active model: prefer explicit activeModel, else first of modelsArray
+    // If activeModel is explicitly empty string, clear the model
+    if (activeModel === "") {
+      config.model = "";
+    } else {
+      const finalActive = activeModel || modelsArray[0];
+      if (finalActive) {
+        config.model = `9router/${finalActive}`;
+      }
+    }
+
+    // Add subagent configuration
+    if (!config.agent) config.agent = {};
+    config.agent.explorer = {
+      description: "Fast explorer subagent for codebase exploration",
+      mode: "subagent",
+      model: `9router/${effectiveSubagentModel}`,
+    };
+
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "OpenCode settings applied successfully!",
+      configPath,
+    });
+  } catch (error) {
+    console.log("Error applying opencode settings:", error);
+    return NextResponse.json({ error: "Failed to apply settings" }, { status: 500 });
+  }
+}
+
+// PATCH - Update specific settings (e.g., clear active model)
+export async function PATCH(request) {
+  try {
+    const { clearActiveModel } = await request.json();
+    const configPath = getConfigPath();
+
+    let config = {};
+    try {
+      const existing = await fs.readFile(configPath, "utf-8");
+      config = JSON.parse(existing);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return NextResponse.json({ success: true, message: "No config file found" });
+      }
+      throw error;
+    }
+
+    if (clearActiveModel === true) {
+      // Clear active model but keep models in the list
+      if (config.model?.startsWith("9router/")) {
+        config.model = "";
+      }
+    }
+
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: "Settings updated",
+    });
+  } catch (error) {
+    console.log("Error patching opencode settings:", error);
+    return NextResponse.json({ error: "Failed to patch settings" }, { status: 500 });
+  }
+}
+
+// DELETE - Remove 9Router provider or specific models from config
+export async function DELETE(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const modelToRemove = searchParams.get("model");
+    const configPath = getConfigPath();
+
+    let config = {};
+    try {
+      const existing = await fs.readFile(configPath, "utf-8");
+      config = JSON.parse(existing);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return NextResponse.json({ success: true, message: "No config file to reset" });
+      }
+      throw error;
+    }
+
+    // If specific model provided, remove just that model
+    if (modelToRemove && config.provider?.["9router"]?.models) {
+      delete config.provider["9router"].models[modelToRemove];
+      
+      // If no models left, remove the provider
+      if (Object.keys(config.provider["9router"].models).length === 0) {
+        delete config.provider["9router"];
+        if (config.model?.startsWith("9router/")) delete config.model;
+      } else if (config.model === `9router/${modelToRemove}`) {
+        // If removed model was active, switch to first remaining model
+        const remainingModels = Object.keys(config.provider["9router"].models);
+        config.model = `9router/${remainingModels[0]}`;
+      }
+    } else {
+      // No specific model - remove entire 9router provider
+      if (config.provider) delete config.provider["9router"];
+      if (config.model?.startsWith("9router/")) delete config.model;
+    }
+
+    // Remove subagent configuration
+    if (config.agent?.explorer?.model?.startsWith("9router/")) {
+      delete config.agent.explorer;
+      // Clean up empty agent object
+      if (Object.keys(config.agent).length === 0) delete config.agent;
+    }
+
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+
+    return NextResponse.json({
+      success: true,
+      message: modelToRemove ? `Model "${modelToRemove}" removed` : "9Router settings removed from OpenCode",
+    });
+  } catch (error) {
+    console.log("Error resetting opencode settings:", error);
+    return NextResponse.json({ error: "Failed to reset opencode settings" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/combos/[id]/route.js b/src/app/api/combos/[id]/route.js
new file mode 100644
index 0000000..d641da7
--- /dev/null
+++ b/src/app/api/combos/[id]/route.js
@@ -0,0 +1,81 @@
+import { NextResponse } from "next/server";
+import { getComboById, updateCombo, deleteCombo, getComboByName } from "@/lib/localDb";
+import { resetComboRotation } from "open-sse/services/combo.js";
+
+// Validate combo name: only a-z, A-Z, 0-9, -, _
+const VALID_NAME_REGEX = /^[a-zA-Z0-9_.\-]+$/;
+
+// GET /api/combos/[id] - Get combo by ID
+export async function GET(request, { params }) {
+  try {
+    const { id } = await params;
+    const combo = await getComboById(id);
+    
+    if (!combo) {
+      return NextResponse.json({ error: "Combo not found" }, { status: 404 });
+    }
+    
+    return NextResponse.json(combo);
+  } catch (error) {
+    console.log("Error fetching combo:", error);
+    return NextResponse.json({ error: "Failed to fetch combo" }, { status: 500 });
+  }
+}
+
+// PUT /api/combos/[id] - Update combo
+export async function PUT(request, { params }) {
+  try {
+    const { id } = await params;
+    const body = await request.json();
+    
+    // Validate name format if provided
+    if (body.name) {
+      if (!VALID_NAME_REGEX.test(body.name)) {
+        return NextResponse.json({ error: "Name can only contain letters, numbers, -, _ and ." }, { status: 400 });
+      }
+      
+      // Check if name already exists (exclude current combo)
+      const existing = await getComboByName(body.name);
+      if (existing && existing.id !== id) {
+        return NextResponse.json({ error: "Combo name already exists" }, { status: 400 });
+      }
+    }
+    
+    // Capture previous name to invalidate rotation state on rename
+    const prev = await getComboById(id);
+    const combo = await updateCombo(id, body);
+    
+    if (!combo) {
+      return NextResponse.json({ error: "Combo not found" }, { status: 404 });
+    }
+
+    // Invalidate rotation state (models/strategy/name may have changed)
+    if (prev?.name) resetComboRotation(prev.name);
+    if (combo.name && combo.name !== prev?.name) resetComboRotation(combo.name);
+
+    return NextResponse.json(combo);
+  } catch (error) {
+    console.log("Error updating combo:", error);
+    return NextResponse.json({ error: "Failed to update combo" }, { status: 500 });
+  }
+}
+
+// DELETE /api/combos/[id] - Delete combo
+export async function DELETE(request, { params }) {
+  try {
+    const { id } = await params;
+    const prev = await getComboById(id);
+    const success = await deleteCombo(id);
+    
+    if (!success) {
+      return NextResponse.json({ error: "Combo not found" }, { status: 404 });
+    }
+
+    if (prev?.name) resetComboRotation(prev.name);
+    
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.log("Error deleting combo:", error);
+    return NextResponse.json({ error: "Failed to delete combo" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/combos/route.js b/src/app/api/combos/route.js
new file mode 100644
index 0000000..db9f02d
--- /dev/null
+++ b/src/app/api/combos/route.js
@@ -0,0 +1,48 @@
+import { NextResponse } from "next/server";
+import { getCombos, createCombo, getComboByName } from "@/lib/localDb";
+
+export const dynamic = "force-dynamic";
+
+// Validate combo name: only a-z, A-Z, 0-9, -, _
+const VALID_NAME_REGEX = /^[a-zA-Z0-9_.\-]+$/;
+
+// GET /api/combos - Get all combos
+export async function GET() {
+  try {
+    const combos = await getCombos();
+    return NextResponse.json({ combos });
+  } catch (error) {
+    console.log("Error fetching combos:", error);
+    return NextResponse.json({ error: "Failed to fetch combos" }, { status: 500 });
+  }
+}
+
+// POST /api/combos - Create new combo
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const { name, models, kind } = body;
+
+    if (!name) {
+      return NextResponse.json({ error: "Name is required" }, { status: 400 });
+    }
+
+    // Validate name format
+    if (!VALID_NAME_REGEX.test(name)) {
+      return NextResponse.json({ error: "Name can only contain letters, numbers, -, _ and ." }, { status: 400 });
+    }
+
+    // Check if name already exists
+    const existing = await getComboByName(name);
+    if (existing) {
+      return NextResponse.json({ error: "Combo name already exists" }, { status: 400 });
+    }
+
+    const combo = await createCombo({ name, models: models || [], kind: kind || null });
+
+    return NextResponse.json(combo, { status: 201 });
+  } catch (error) {
+    console.log("Error creating combo:", error);
+    return NextResponse.json({ error: "Failed to create combo" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/headroom/extras/route.js b/src/app/api/headroom/extras/route.js
new file mode 100644
index 0000000..3dffaa5
--- /dev/null
+++ b/src/app/api/headroom/extras/route.js
@@ -0,0 +1,46 @@
+import { NextResponse } from "next/server";
+import { findPython310, getInstalledHeadroomExtras, HEADROOM_COMPRESSION_EXTRAS } from "@/lib/headroom/detect";
+import { installHeadroomExtras, uninstallHeadroomExtras, getInstallLogTail } from "@/lib/headroom/process";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(req) {
+  try {
+    // `?log=1` returns the live install/uninstall log tail for progress polling.
+    if (new URL(req.url).searchParams.get("log") === "1") {
+      return NextResponse.json({ log: getInstallLogTail() });
+    }
+    const python = findPython310();
+    const status = getInstalledHeadroomExtras(python);
+    return NextResponse.json({
+      available: HEADROOM_COMPRESSION_EXTRAS,
+      ...status,
+    });
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
+
+export async function POST(req) {
+  try {
+    const body = await req.json().catch(() => ({}));
+    const requested = Array.isArray(body?.extras) ? body.extras : [];
+    const result = await installHeadroomExtras(requested);
+    return NextResponse.json(result);
+  } catch (error) {
+    const status = error.code === "NOT_INSTALLED" || error.code === "NO_PYTHON" ? 400 : 500;
+    return NextResponse.json({ error: error.message, code: error.code || null }, { status });
+  }
+}
+
+export async function DELETE(req) {
+  try {
+    const body = await req.json().catch(() => ({}));
+    const requested = Array.isArray(body?.extras) ? body.extras : [];
+    const result = await uninstallHeadroomExtras(requested);
+    return NextResponse.json(result);
+  } catch (error) {
+    const status = error.code === "NO_PYTHON" || error.code === "INVALID_EXTRAS" ? 400 : 500;
+    return NextResponse.json({ error: error.message, code: error.code || null }, { status });
+  }
+}
diff --git a/src/app/api/headroom/proxy/[...path]/route.js b/src/app/api/headroom/proxy/[...path]/route.js
new file mode 100644
index 0000000..dee647d
--- /dev/null
+++ b/src/app/api/headroom/proxy/[...path]/route.js
@@ -0,0 +1,104 @@
+import { NextResponse } from "next/server";
+import { getSettings } from "@/lib/localDb";
+import { DEFAULT_HEADROOM_URL } from "@/lib/headroom/detect";
+
+export const dynamic = "force-dynamic";
+
+const HOP_BY_HOP_HEADERS = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+const DASHBOARD_PREFIX = "/api/headroom/proxy";
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+
+async function getTargetBase() {
+  const settings = await getSettings();
+  const url = settings.headroomUrl || DEFAULT_HEADROOM_URL;
+  const target = new URL(url);
+  if (!["http:", "https:"].includes(target.protocol)) {
+    throw new Error("Headroom URL must use http or https");
+  }
+  return target;
+}
+
+function buildTargetUrl(base, path, search) {
+  const target = new URL(base);
+  target.pathname = `/${path.join("/")}`;
+  target.search = search;
+  return target;
+}
+
+function forwardedHeaders(request, target) {
+  const headers = new Headers(request.headers);
+  for (const header of headers.keys()) {
+    if (HOP_BY_HOP_HEADERS.has(header.toLowerCase())) headers.delete(header);
+  }
+  headers.delete("host");
+  // Never leak viewer credentials to a non-loopback Headroom host
+  if (!LOOPBACK_HOSTS.has(target.hostname.replace(/^\[|\]$/g, "").toLowerCase())) {
+    headers.delete("cookie");
+    headers.delete("authorization");
+  }
+  return headers;
+}
+
+function rewriteDashboardHtml(html) {
+  return html.replace(
+    /fetch\('(?=\/(?:stats|health|stats-history|transformations\/feed))/g,
+    `fetch('${DASHBOARD_PREFIX}`,
+  );
+}
+
+async function proxy(request, { params }) {
+  try {
+    const base = await getTargetBase();
+    const { search } = new URL(request.url);
+    const path = (await params).path || [];
+    const target = buildTargetUrl(base, path, search);
+    const method = request.method;
+    const hasBody = !["GET", "HEAD"].includes(method);
+
+    const response = await fetch(target, {
+      method,
+      headers: forwardedHeaders(request, target),
+      body: hasBody ? request.body : undefined,
+      duplex: hasBody ? "half" : undefined,
+      redirect: "manual",
+    });
+
+    const headers = new Headers(response.headers);
+    for (const header of headers.keys()) {
+      if (HOP_BY_HOP_HEADERS.has(header.toLowerCase())) headers.delete(header);
+    }
+
+    if (path.join("/") === "dashboard") {
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("text/html")) {
+        headers.delete("content-length");
+        return new NextResponse(rewriteDashboardHtml(await response.text()), {
+          status: response.status,
+          headers,
+        });
+      }
+    }
+
+    return new NextResponse(response.body, { status: response.status, headers });
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
+
+export const GET = proxy;
+export const POST = proxy;
+export const PUT = proxy;
+export const PATCH = proxy;
+export const DELETE = proxy;
+export const HEAD = proxy;
+export const OPTIONS = proxy;
diff --git a/src/app/api/headroom/restart/route.js b/src/app/api/headroom/restart/route.js
new file mode 100644
index 0000000..7d98e80
--- /dev/null
+++ b/src/app/api/headroom/restart/route.js
@@ -0,0 +1,35 @@
+import { NextResponse } from "next/server";
+import { getSettings } from "@/lib/localDb";
+import { restartHeadroomProxy } from "@/lib/headroom/process";
+import { DEFAULT_HEADROOM_URL, isLoopbackHeadroomUrl } from "@/lib/headroom/detect";
+
+export const dynamic = "force-dynamic";
+
+function parsePortFromUrl(url) {
+  try {
+    const u = new URL(url);
+    const p = parseInt(u.port, 10);
+    if (p > 0 && p < 65536) return p;
+  } catch { /* ignore, fall through to default */ }
+  return null;
+}
+
+export async function POST() {
+  try {
+    const settings = await getSettings();
+    const url = settings.headroomUrl || DEFAULT_HEADROOM_URL;
+    if (!isLoopbackHeadroomUrl(url)) {
+      return NextResponse.json({ error: "External Headroom proxies must be started outside 9Router", code: "EXTERNAL_PROXY" }, { status: 400 });
+    }
+    const port = parsePortFromUrl(url) || 8787;
+    const result = await restartHeadroomProxy({
+      port,
+      codeAware: settings.headroomCodeAware === true,
+      kompress: settings.headroomKompress !== false,
+    });
+    return NextResponse.json({ success: true, ...result });
+  } catch (error) {
+    const status = error.code === "NOT_INSTALLED" ? 400 : 500;
+    return NextResponse.json({ error: error.message, code: error.code || null }, { status });
+  }
+}
diff --git a/src/app/api/headroom/start/route.js b/src/app/api/headroom/start/route.js
new file mode 100644
index 0000000..9be6d88
--- /dev/null
+++ b/src/app/api/headroom/start/route.js
@@ -0,0 +1,35 @@
+import { NextResponse } from "next/server";
+import { getSettings } from "@/lib/localDb";
+import { startHeadroomProxy } from "@/lib/headroom/process";
+import { DEFAULT_HEADROOM_URL, isLoopbackHeadroomUrl } from "@/lib/headroom/detect";
+
+export const dynamic = "force-dynamic";
+
+function parsePortFromUrl(url) {
+  try {
+    const u = new URL(url);
+    const p = parseInt(u.port, 10);
+    if (p > 0 && p < 65536) return p;
+  } catch { /* ignore, fall through to default */ }
+  return null;
+}
+
+export async function POST() {
+  try {
+    const settings = await getSettings();
+    const url = settings.headroomUrl || DEFAULT_HEADROOM_URL;
+    if (!isLoopbackHeadroomUrl(url)) {
+      return NextResponse.json({ error: "External Headroom proxies must be started outside 9Router", code: "EXTERNAL_PROXY" }, { status: 400 });
+    }
+    const port = parsePortFromUrl(url) || 8787;
+    const result = await startHeadroomProxy({
+      port,
+      codeAware: settings.headroomCodeAware === true,
+      kompress: settings.headroomKompress !== false,
+    });
+    return NextResponse.json({ success: true, ...result });
+  } catch (error) {
+    const status = error.code === "NOT_INSTALLED" ? 400 : 500;
+    return NextResponse.json({ error: error.message, code: error.code || null }, { status });
+  }
+}
diff --git a/src/app/api/headroom/status/route.js b/src/app/api/headroom/status/route.js
new file mode 100644
index 0000000..582147c
--- /dev/null
+++ b/src/app/api/headroom/status/route.js
@@ -0,0 +1,18 @@
+import { NextResponse } from "next/server";
+import { getSettings } from "@/lib/localDb";
+import { DEFAULT_HEADROOM_URL, getHeadroomStatus } from "@/lib/headroom/detect";
+import { getManagedPid } from "@/lib/headroom/process";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  try {
+    const settings = await getSettings();
+    const url = settings.headroomUrl || DEFAULT_HEADROOM_URL;
+    const status = await getHeadroomStatus(url);
+    const managedPid = getManagedPid();
+    return NextResponse.json({ ...status, url, managedPid });
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/headroom/stop/route.js b/src/app/api/headroom/stop/route.js
new file mode 100644
index 0000000..122251e
--- /dev/null
+++ b/src/app/api/headroom/stop/route.js
@@ -0,0 +1,14 @@
+import { NextResponse } from "next/server";
+import { stopHeadroomProxy } from "@/lib/headroom/process";
+
+export const dynamic = "force-dynamic";
+
+export async function POST() {
+  try {
+    const result = stopHeadroomProxy();
+    const status = result.stopped ? 200 : 409;
+    return NextResponse.json({ ...result }, { status });
+  } catch (error) {
+    return NextResponse.json({ error: error.message, code: error.code || null }, { status: 500 });
+  }
+}
diff --git a/src/app/api/health/route.js b/src/app/api/health/route.js
new file mode 100644
index 0000000..5021b7d
--- /dev/null
+++ b/src/app/api/health/route.js
@@ -0,0 +1,15 @@
+import { NextResponse } from "next/server";
+
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "*",
+};
+
+export async function GET() {
+  return NextResponse.json({ ok: true }, { headers: CORS_HEADERS });
+}
+
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 204, headers: CORS_HEADERS });
+}
diff --git a/src/app/api/init/route.js b/src/app/api/init/route.js
new file mode 100644
index 0000000..2e2b13f
--- /dev/null
+++ b/src/app/api/init/route.js
@@ -0,0 +1,4 @@
+// This API route is called automatically to initialize app
+export async function GET() {
+  return new Response("Initialized", { status: 200 });
+}
diff --git a/src/app/api/keys/[id]/route.js b/src/app/api/keys/[id]/route.js
new file mode 100644
index 0000000..1d22596
--- /dev/null
+++ b/src/app/api/keys/[id]/route.js
@@ -0,0 +1,58 @@
+import { NextResponse } from "next/server";
+import { deleteApiKey, getApiKeyById, updateApiKey } from "@/lib/localDb";
+
+// GET /api/keys/[id] - Get single key
+export async function GET(request, { params }) {
+  try {
+    const { id } = await params;
+    const key = await getApiKeyById(id);
+    if (!key) {
+      return NextResponse.json({ error: "Key not found" }, { status: 404 });
+    }
+    return NextResponse.json({ key });
+  } catch (error) {
+    console.log("Error fetching key:", error);
+    return NextResponse.json({ error: "Failed to fetch key" }, { status: 500 });
+  }
+}
+
+// PUT /api/keys/[id] - Update key
+export async function PUT(request, { params }) {
+  try {
+    const { id } = await params;
+    const body = await request.json();
+    const { isActive } = body;
+
+    const existing = await getApiKeyById(id);
+    if (!existing) {
+      return NextResponse.json({ error: "Key not found" }, { status: 404 });
+    }
+
+    const updateData = {};
+    if (isActive !== undefined) updateData.isActive = isActive;
+
+    const updated = await updateApiKey(id, updateData);
+
+    return NextResponse.json({ key: updated });
+  } catch (error) {
+    console.log("Error updating key:", error);
+    return NextResponse.json({ error: "Failed to update key" }, { status: 500 });
+  }
+}
+
+// DELETE /api/keys/[id] - Delete API key
+export async function DELETE(request, { params }) {
+  try {
+    const { id } = await params;
+
+    const deleted = await deleteApiKey(id);
+    if (!deleted) {
+      return NextResponse.json({ error: "Key not found" }, { status: 404 });
+    }
+
+    return NextResponse.json({ message: "Key deleted successfully" });
+  } catch (error) {
+    console.log("Error deleting key:", error);
+    return NextResponse.json({ error: "Failed to delete key" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/keys/route.js b/src/app/api/keys/route.js
new file mode 100644
index 0000000..ab0470a
--- /dev/null
+++ b/src/app/api/keys/route.js
@@ -0,0 +1,42 @@
+import { NextResponse } from "next/server";
+import { getApiKeys, createApiKey } from "@/lib/localDb";
+import { getConsistentMachineId } from "@/shared/utils/machineId";
+
+export const dynamic = "force-dynamic";
+
+// GET /api/keys - List API keys
+export async function GET() {
+  try {
+    const keys = await getApiKeys();
+    return NextResponse.json({ keys });
+  } catch (error) {
+    console.log("Error fetching keys:", error);
+    return NextResponse.json({ error: "Failed to fetch keys" }, { status: 500 });
+  }
+}
+
+// POST /api/keys - Create new API key
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const { name } = body;
+
+    if (!name) {
+      return NextResponse.json({ error: "Name is required" }, { status: 400 });
+    }
+
+    // Always get machineId from server
+    const machineId = await getConsistentMachineId();
+    const apiKey = await createApiKey(name, machineId);
+
+    return NextResponse.json({
+      key: apiKey.key,
+      name: apiKey.name,
+      id: apiKey.id,
+      machineId: apiKey.machineId,
+    }, { status: 201 });
+  } catch (error) {
+    console.log("Error creating key:", error);
+    return NextResponse.json({ error: "Failed to create key" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/locale/route.js b/src/app/api/locale/route.js
new file mode 100644
index 0000000..767e425
--- /dev/null
+++ b/src/app/api/locale/route.js
@@ -0,0 +1,30 @@
+import { cookies } from "next/headers";
+import { NextResponse } from "next/server";
+import { LOCALE_COOKIE, normalizeLocale, isSupportedLocale } from "@/i18n/config";
+
+export async function POST(request) {
+  try {
+    const { locale } = await request.json();
+    
+    if (!locale || !isSupportedLocale(locale)) {
+      return NextResponse.json(
+        { error: "Invalid locale" },
+        { status: 400 }
+      );
+    }
+
+    const normalized = normalizeLocale(locale);
+    const cookieStore = await cookies();
+    cookieStore.set(LOCALE_COOKIE, normalized, {
+      path: "/",
+      maxAge: 60 * 60 * 24 * 365, // 1 year
+    });
+
+    return NextResponse.json({ success: true, locale: normalized });
+  } catch (error) {
+    return NextResponse.json(
+      { error: "Failed to set locale" },
+      { status: 500 }
+    );
+  }
+}
diff --git a/src/app/api/mcp/[plugin]/message/route.js b/src/app/api/mcp/[plugin]/message/route.js
new file mode 100644
index 0000000..86df051
--- /dev/null
+++ b/src/app/api/mcp/[plugin]/message/route.js
@@ -0,0 +1,19 @@
+import { NextResponse } from "next/server";
+import { sendToChild, findPlugin } from "@/lib/mcp/stdioSseBridge";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function POST(request, { params }) {
+  const { plugin } = await params;
+  if (!findPlugin(plugin)) {
+    return NextResponse.json({ error: `Unknown plugin: ${plugin}` }, { status: 404 });
+  }
+  try {
+    const body = await request.json();
+    sendToChild(plugin, body);
+    return new Response(null, { status: 202 });
+  } catch (e) {
+    return NextResponse.json({ error: e.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/mcp/[plugin]/sse/route.js b/src/app/api/mcp/[plugin]/sse/route.js
new file mode 100644
index 0000000..8f9d67d
--- /dev/null
+++ b/src/app/api/mcp/[plugin]/sse/route.js
@@ -0,0 +1,35 @@
+import { registerSession, unregisterSession, findPlugin } from "@/lib/mcp/stdioSseBridge";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function GET(request, { params }) {
+  const { plugin } = await params;
+  if (!findPlugin(plugin)) {
+    return new Response(`Unknown plugin: ${plugin}`, { status: 404 });
+  }
+
+  const encoder = new TextEncoder();
+  let sid;
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const send = (chunk) => controller.enqueue(encoder.encode(chunk));
+      sid = registerSession(plugin, send);
+      // MCP SSE handshake: tell client where to POST messages.
+      send(`event: endpoint\ndata: /api/mcp/${plugin}/message?sessionId=${sid}\n\n`);
+    },
+    cancel() {
+      if (sid) unregisterSession(plugin, sid);
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no",
+    },
+  });
+}
diff --git a/src/app/api/media-providers/tts/deepgram/voices/route.js b/src/app/api/media-providers/tts/deepgram/voices/route.js
new file mode 100644
index 0000000..57d0c5f
--- /dev/null
+++ b/src/app/api/media-providers/tts/deepgram/voices/route.js
@@ -0,0 +1,65 @@
+import { NextResponse } from "next/server";
+import { getProviderConnections } from "@/lib/localDb";
+
+const langNames = new Intl.DisplayNames(["en"], { type: "language" });
+
+/**
+ * GET /api/media-providers/tts/deepgram/voices[?lang=en]
+ * Returns { languages, byLang } grouped by language code (same shape as edge-tts/elevenlabs/inworld)
+ * Each Deepgram voice = one model (canonical_name like "aura-2-thalia-en")
+ */
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const langFilter = searchParams.get("lang");
+
+    const connections = await getProviderConnections({ provider: "deepgram", isActive: true });
+    const apiKey = connections[0]?.apiKey;
+    if (!apiKey) return NextResponse.json({ error: "No Deepgram connection found" }, { status: 400 });
+
+    const res = await fetch("https://api.deepgram.com/v1/models", {
+      headers: { "Authorization": `Token ${apiKey}` },
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      return NextResponse.json({ error: `Deepgram API ${res.status}: ${text || "Failed"}` }, { status: 502 });
+    }
+    const data = await res.json();
+    const ttsModels = data.tts || [];
+
+    const byLang = {};
+    for (const m of ttsModels) {
+      // Deepgram returns `languages: ["en"]` or sometimes language inferred from canonical_name suffix
+      const langs = Array.isArray(m.languages) && m.languages.length
+        ? m.languages
+        : [m.canonical_name?.split("-").pop() || "en"];
+      for (const code of langs) {
+        if (!byLang[code]) {
+          byLang[code] = {
+            code,
+            name: (() => { try { return langNames.of(code); } catch { return code; } })(),
+            voices: [],
+          };
+        }
+        const voiceId = m.canonical_name || m.name;
+        if (!byLang[code].voices.find((x) => x.id === voiceId)) {
+          byLang[code].voices.push({
+            id: voiceId,
+            name: m.name || voiceId,
+            gender: m.metadata?.tags?.find((t) => t === "masculine" || t === "feminine") || "",
+            lang: code,
+          });
+        }
+      }
+    }
+
+    const languages = Object.values(byLang).sort((a, b) => a.name.localeCompare(b.name));
+
+    if (langFilter) {
+      return NextResponse.json({ voices: byLang[langFilter]?.voices || [] });
+    }
+    return NextResponse.json({ languages, byLang });
+  } catch (err) {
+    return NextResponse.json({ error: err.message || "Failed to fetch voices" }, { status: 502 });
+  }
+}
diff --git a/src/app/api/media-providers/tts/elevenlabs/voices/route.js b/src/app/api/media-providers/tts/elevenlabs/voices/route.js
new file mode 100644
index 0000000..39638d2
--- /dev/null
+++ b/src/app/api/media-providers/tts/elevenlabs/voices/route.js
@@ -0,0 +1,71 @@
+import { NextResponse } from "next/server";
+import { getProviderConnections } from "@/lib/localDb";
+import { fetchElevenLabsVoices } from "open-sse/handlers/ttsCore.js";
+
+const langNames = new Intl.DisplayNames(["en"], { type: "language" });
+
+/**
+ * GET /api/media-providers/tts/elevenlabs/voices[?lang=en]
+ * Returns { languages, byLang } grouped by language - same format as edge-tts
+ * Uses direct DB read (no mutex) to avoid blocking on concurrent TTS requests
+ */
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const langFilter = searchParams.get("lang");
+
+    // Direct DB read - bypass auth mutex used for TTS inference
+    const connections = await getProviderConnections({ provider: "elevenlabs", isActive: true });
+    const apiKey = connections[0]?.apiKey;
+    if (!apiKey) {
+      return NextResponse.json({ error: "No ElevenLabs connection found" }, { status: 400 });
+    }
+
+    const voices = await fetchElevenLabsVoices(apiKey);
+
+    // Group by all supported languages (verified_languages + labels.language)
+    const byLang = {};
+    const addToLang = (code, voice) => {
+      if (!byLang[code]) {
+        byLang[code] = {
+          code,
+          name: (() => { try { return langNames.of(code); } catch { return code; } })(),
+          voices: [],
+        };
+      }
+      // Avoid duplicate voice in same lang
+      if (!byLang[code].voices.find((v) => v.id === voice.voice_id)) {
+        byLang[code].voices.push({
+          id: voice.voice_id,
+          name: voice.name,
+          gender: voice.labels?.gender || "",
+          lang: code,
+          // premade voices are free; professional library voices added to account may require paid plan
+          free_users_allowed: voice.category === "premade" || voice.is_owner === true
+        });
+      }
+    };
+    for (const v of voices) {
+      // Add to primary language
+      const primaryLang = v.labels?.language || "en";
+      addToLang(primaryLang, v);
+      // Add to all verified languages
+      for (const vl of v.verified_languages || []) {
+        if (vl.language && vl.language !== primaryLang) {
+          addToLang(vl.language, v);
+        }
+      }
+    }
+
+    const languages = Object.values(byLang).sort((a, b) => a.name.localeCompare(b.name));
+
+    // If lang filter requested, return only that group's voices
+    if (langFilter) {
+      return NextResponse.json({ voices: byLang[langFilter]?.voices || [] });
+    }
+
+    return NextResponse.json({ languages, byLang });
+  } catch (err) {
+    return NextResponse.json({ error: err.message || "Failed to fetch voices" }, { status: 502 });
+  }
+}
diff --git a/src/app/api/media-providers/tts/inworld/voices/route.js b/src/app/api/media-providers/tts/inworld/voices/route.js
new file mode 100644
index 0000000..fb904e5
--- /dev/null
+++ b/src/app/api/media-providers/tts/inworld/voices/route.js
@@ -0,0 +1,61 @@
+import { NextResponse } from "next/server";
+import { getProviderConnections } from "@/lib/localDb";
+
+const langNames = new Intl.DisplayNames(["en"], { type: "language" });
+
+/**
+ * GET /api/media-providers/tts/inworld/voices[?lang=en]
+ * Returns { languages, byLang } grouped by language code (same shape as edge-tts/elevenlabs)
+ */
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const langFilter = searchParams.get("lang");
+
+    const connections = await getProviderConnections({ provider: "inworld", isActive: true });
+    const apiKey = connections[0]?.apiKey;
+    if (!apiKey) return NextResponse.json({ error: "No Inworld connection found" }, { status: 400 });
+
+    const res = await fetch("https://api.inworld.ai/tts/v1/voices", {
+      headers: { "Authorization": `Basic ${apiKey}` },
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      return NextResponse.json({ error: `Inworld API ${res.status}: ${text || "Failed"}` }, { status: 502 });
+    }
+    const data = await res.json();
+    const voices = data.voices || [];
+
+    const byLang = {};
+    for (const v of voices) {
+      // Each voice has `languages: ["en", "es", ...]`
+      const langs = Array.isArray(v.languages) && v.languages.length ? v.languages : ["en"];
+      for (const code of langs) {
+        if (!byLang[code]) {
+          byLang[code] = {
+            code,
+            name: (() => { try { return langNames.of(code); } catch { return code; } })(),
+            voices: [],
+          };
+        }
+        if (!byLang[code].voices.find((x) => x.id === v.voiceId)) {
+          byLang[code].voices.push({
+            id: v.voiceId,
+            name: v.displayName || v.voiceId,
+            gender: v.gender || "",
+            lang: code,
+          });
+        }
+      }
+    }
+
+    const languages = Object.values(byLang).sort((a, b) => a.name.localeCompare(b.name));
+
+    if (langFilter) {
+      return NextResponse.json({ voices: byLang[langFilter]?.voices || [] });
+    }
+    return NextResponse.json({ languages, byLang });
+  } catch (err) {
+    return NextResponse.json({ error: err.message || "Failed to fetch voices" }, { status: 502 });
+  }
+}
diff --git a/src/app/api/media-providers/tts/minimax/voices/route.js b/src/app/api/media-providers/tts/minimax/voices/route.js
new file mode 100644
index 0000000..955efce
--- /dev/null
+++ b/src/app/api/media-providers/tts/minimax/voices/route.js
@@ -0,0 +1,113 @@
+import { NextResponse } from "next/server";
+import { getProviderConnections } from "@/lib/localDb";
+
+const MINIMAX_VOICE_ENDPOINTS = {
+  minimax: "https://api.minimax.io/v1/get_voice",
+  "minimax-cn": "https://api.minimaxi.com/v1/get_voice",
+};
+
+const VOICE_GROUPS = [
+  { key: "system_voice", label: "System" },
+  { key: "voice_cloning", label: "Cloned" },
+  { key: "voice_generation", label: "Generated" },
+  { key: "music_generation", label: "Music" },
+];
+
+function inferLanguage(voiceId) {
+  const value = typeof voiceId === "string" ? voiceId.trim() : "";
+  if (!value.includes("_")) return "Custom";
+  return value.split("_")[0] || "Custom";
+}
+
+function addVoice(byLang, code, voice) {
+  if (!byLang[code]) byLang[code] = { code, name: code, voices: [] };
+  if (byLang[code].voices.some((v) => v.id === voice.id)) return;
+  byLang[code].voices.push(voice);
+}
+
+function normalizeMiniMaxVoices(data) {
+  const byLang = {};
+
+  for (const group of VOICE_GROUPS) {
+    const voices = Array.isArray(data?.[group.key]) ? data[group.key] : [];
+    for (const item of voices) {
+      const voiceId = item?.voice_id || item?.voiceId;
+      if (!voiceId) continue;
+
+      const voiceName = item?.voice_name || item?.voiceName || voiceId;
+      const lang = group.key === "system_voice" ? inferLanguage(voiceId) : "Custom";
+      addVoice(byLang, lang, {
+        id: voiceId,
+        name: group.key === "system_voice" ? voiceName : `${voiceName} · ${group.label}`,
+        lang,
+        category: group.key,
+      });
+    }
+  }
+
+  const languages = Object.values(byLang).sort((a, b) => {
+    if (a.code === "Custom") return 1;
+    if (b.code === "Custom") return -1;
+    return a.name.localeCompare(b.name);
+  });
+
+  for (const lang of languages) {
+    lang.voices.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  return { languages, byLang };
+}
+
+/**
+ * GET /api/media-providers/tts/minimax/voices[?provider=minimax|minimax-cn&voice_type=all]
+ * Returns { languages, byLang } grouped for the shared TTS voice picker.
+ */
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const provider = searchParams.get("provider") === "minimax-cn" ? "minimax-cn" : "minimax";
+    const voiceType = searchParams.get("voice_type") || "all";
+    const langFilter = searchParams.get("lang");
+
+    const connections = await getProviderConnections({ provider, isActive: true });
+    const apiKey = connections[0]?.apiKey;
+    if (!apiKey) {
+      return NextResponse.json({ error: `No ${provider} connection found` }, { status: 400 });
+    }
+
+    const res = await fetch(MINIMAX_VOICE_ENDPOINTS[provider], {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ voice_type: voiceType }),
+    });
+
+    const rawText = await res.text();
+    let data = {};
+    if (rawText) {
+      try { data = JSON.parse(rawText); } catch { data = {}; }
+    }
+
+    const baseResp = data.base_resp || data.baseResp || {};
+    const statusCode = Number(baseResp.status_code ?? baseResp.statusCode ?? 0);
+    const statusMessage = baseResp.status_msg || baseResp.statusMsg || data.message || "";
+
+    if (!res.ok) {
+      return NextResponse.json({ error: `MiniMax API ${res.status}: ${statusMessage || rawText || "Failed"}` }, { status: 502 });
+    }
+    if (statusCode !== 0) {
+      return NextResponse.json({ error: statusMessage || "MiniMax voice API error" }, { status: 502 });
+    }
+
+    const normalized = normalizeMiniMaxVoices(data);
+    if (langFilter) {
+      return NextResponse.json({ voices: normalized.byLang[langFilter]?.voices || [] });
+    }
+
+    return NextResponse.json(normalized);
+  } catch (err) {
+    return NextResponse.json({ error: err.message || "Failed to fetch MiniMax voices" }, { status: 502 });
+  }
+}
diff --git a/src/app/api/media-providers/tts/voices/route.js b/src/app/api/media-providers/tts/voices/route.js
new file mode 100644
index 0000000..6bac4f8
--- /dev/null
+++ b/src/app/api/media-providers/tts/voices/route.js
@@ -0,0 +1,99 @@
+import { VOICE_FETCHERS } from "open-sse/handlers/ttsCore.js";
+import { NextResponse } from "next/server";
+
+// Map locale code → country name
+const LOCALE_NAMES = new Intl.DisplayNames(["en"], { type: "region" });
+const LANG_NAMES   = new Intl.DisplayNames(["en"], { type: "language" });
+
+function countryName(code) {
+  try { return LOCALE_NAMES.of(code); } catch { return code; }
+}
+function langName(code) {
+  try { return LANG_NAMES.of(code); } catch { return code; }
+}
+
+/**
+ * GET /api/media-providers/tts/voices
+ * Query:
+ *   ?provider=edge-tts | local-device | elevenlabs  (default: edge-tts)
+ *   ?lang=en     (optional filter by lang code)
+ *   ?apiKey=xxx  (required for elevenlabs)
+ */
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const provider   = searchParams.get("provider") || "edge-tts";
+    const langFilter = searchParams.get("lang");
+    const apiKey     = searchParams.get("apiKey");
+
+    const fetcher = VOICE_FETCHERS[provider];
+    if (!fetcher) {
+      return NextResponse.json({ error: `Provider '${provider}' does not support voice listing` }, { status: 400 });
+    }
+
+    // ElevenLabs requires API key
+    const raw = provider === "elevenlabs" ? await fetcher(apiKey) : await fetcher();
+    const useElevenShape = provider === "elevenlabs" || provider === "gemini";
+    let voices;
+
+    if (provider === "local-device") {
+      voices = raw.map((v) => ({
+        id:      v.id,
+        name:    v.name,
+        locale:  v.locale.replace("_", "-"),
+        lang:    v.lang,
+        country: v.country,
+        countryName: countryName(v.country),
+        langName:    langName(v.lang),
+        gender:  v.gender,
+      }));
+    } else if (useElevenShape) {
+      voices = raw.map((v) => ({
+        id:      v.voice_id,
+        name:    v.name,
+        locale:  v.labels?.language || "en",
+        lang:    (v.labels?.language || "en").split("-")[0],
+        country: "",
+        countryName: "",
+        langName:    langName((v.labels?.language || "en").split("-")[0]),
+        gender:  v.labels?.gender || "",
+        category: v.category,
+      }));
+    } else {
+      // edge-tts (default)
+      voices = raw.map((v) => {
+        const [lang, country] = v.Locale.split("-");
+        return {
+          id:      v.ShortName,
+          name:    (v.FriendlyName || v.ShortName)
+            .replace("Microsoft ", "")
+            .replace(/ Online \(Natural\) - /g, " ("),
+          locale:  v.Locale,
+          lang,
+          country: country || "",
+          countryName: countryName(country || lang),
+          langName:    langName(lang),
+          gender:  v.Gender,
+        };
+      });
+    }
+
+    // Apply filter
+    if (langFilter) voices = voices.filter((v) => v.lang === langFilter);
+
+    // Group by language
+    const byLang = {};
+    for (const v of voices) {
+      const key = v.lang;
+      if (!byLang[key]) byLang[key] = { code: key, name: v.langName, voices: [] };
+      byLang[key].voices.push(v);
+    }
+
+    // Sorted language list
+    const languages = Object.values(byLang).sort((a, b) => a.name.localeCompare(b.name));
+
+    return NextResponse.json({ voices, languages, byLang });
+  } catch (err) {
+    return NextResponse.json({ error: err.message || "Failed to fetch voices" }, { status: 502 });
+  }
+}
diff --git a/src/app/api/models/alias/route.js b/src/app/api/models/alias/route.js
new file mode 100644
index 0000000..980ea6d
--- /dev/null
+++ b/src/app/api/models/alias/route.js
@@ -0,0 +1,53 @@
+import { NextResponse } from "next/server";
+import { getModelAliases, setModelAlias, deleteModelAlias } from "@/models";
+
+export const dynamic = "force-dynamic";
+
+// GET /api/models/alias - Get all aliases
+export async function GET() {
+  try {
+    const aliases = await getModelAliases();
+    return NextResponse.json({ aliases });
+  } catch (error) {
+    console.log("Error fetching aliases:", error);
+    return NextResponse.json({ error: "Failed to fetch aliases" }, { status: 500 });
+  }
+}
+
+// PUT /api/models/alias - Set model alias
+export async function PUT(request) {
+  try {
+    const body = await request.json();
+    const { model, alias } = body;
+
+    if (!model || !alias) {
+      return NextResponse.json({ error: "Model and alias required" }, { status: 400 });
+    }
+
+    await setModelAlias(alias, model);
+
+    return NextResponse.json({ success: true, model, alias });
+  } catch (error) {
+    console.log("Error updating alias:", error);
+    return NextResponse.json({ error: "Failed to update alias" }, { status: 500 });
+  }
+}
+
+// DELETE /api/models/alias?alias=xxx - Delete alias
+export async function DELETE(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const alias = searchParams.get("alias");
+
+    if (!alias) {
+      return NextResponse.json({ error: "Alias required" }, { status: 400 });
+    }
+
+    await deleteModelAlias(alias);
+
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.log("Error deleting alias:", error);
+    return NextResponse.json({ error: "Failed to delete alias" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/models/availability/route.js b/src/app/api/models/availability/route.js
new file mode 100644
index 0000000..cceacda
--- /dev/null
+++ b/src/app/api/models/availability/route.js
@@ -0,0 +1,103 @@
+import { NextResponse } from "next/server";
+import {
+  getProviderConnections,
+  updateProviderConnection,
+} from "@/lib/localDb";
+
+const MODEL_LOCK_PREFIX = "modelLock_";
+
+function getActiveModelLocks(connection) {
+  const now = Date.now();
+  return Object.entries(connection)
+    .filter(([key, value]) => key.startsWith(MODEL_LOCK_PREFIX) && value)
+    .map(([key, value]) => ({
+      key,
+      model: key.slice(MODEL_LOCK_PREFIX.length) || "__all",
+      until: value,
+      active: new Date(value).getTime() > now,
+    }))
+    .filter((lock) => lock.active);
+}
+
+export async function GET() {
+  try {
+    const connections = await getProviderConnections();
+    const models = [];
+
+    for (const connection of connections) {
+      const locks = getActiveModelLocks(connection);
+      for (const lock of locks) {
+        models.push({
+          provider: connection.provider,
+          model: lock.model,
+          status: "cooldown",
+          until: lock.until,
+          connectionId: connection.id,
+          connectionName: connection.name || connection.email || connection.id,
+          lastError: connection.lastError || null,
+        });
+      }
+
+      if (locks.length === 0 && connection.testStatus === "unavailable") {
+        models.push({
+          provider: connection.provider,
+          model: "__all",
+          status: "unavailable",
+          connectionId: connection.id,
+          connectionName: connection.name || connection.email || connection.id,
+          lastError: connection.lastError || null,
+        });
+      }
+    }
+
+    return NextResponse.json({
+      models,
+      unavailableCount: models.length,
+    });
+  } catch (error) {
+    console.error("[API] Failed to get model availability:", error);
+    return NextResponse.json(
+      { error: "Failed to fetch model availability" },
+      { status: 500 },
+    );
+  }
+}
+
+export async function POST(request) {
+  try {
+    const { action, provider, model } = await request.json();
+
+    if (action !== "clearCooldown" || !provider || !model) {
+      return NextResponse.json({ error: "Invalid request" }, { status: 400 });
+    }
+
+    const connections = await getProviderConnections({ provider });
+    const lockKey = `${MODEL_LOCK_PREFIX}${model}`;
+
+    await Promise.all(
+      connections
+        .filter((connection) => connection[lockKey])
+        .map((connection) =>
+          updateProviderConnection(connection.id, {
+            [lockKey]: null,
+            ...(connection.testStatus === "unavailable"
+              ? {
+                  testStatus: "active",
+                  lastError: null,
+                  lastErrorAt: null,
+                  backoffLevel: 0,
+                }
+              : {}),
+          }),
+        ),
+    );
+
+    return NextResponse.json({ ok: true });
+  } catch (error) {
+    console.error("[API] Failed to clear model cooldown:", error);
+    return NextResponse.json(
+      { error: "Failed to clear cooldown" },
+      { status: 500 },
+    );
+  }
+}
diff --git a/src/app/api/models/custom/route.js b/src/app/api/models/custom/route.js
new file mode 100644
index 0000000..76e14c9
--- /dev/null
+++ b/src/app/api/models/custom/route.js
@@ -0,0 +1,48 @@
+import { NextResponse } from "next/server";
+import { getCustomModels, addCustomModel, deleteCustomModel } from "@/models";
+
+export const dynamic = "force-dynamic";
+
+// GET /api/models/custom - List all custom models
+export async function GET() {
+  try {
+    const models = await getCustomModels();
+    return NextResponse.json({ models });
+  } catch (error) {
+    console.log("Error fetching custom models:", error);
+    return NextResponse.json({ error: "Failed to fetch custom models" }, { status: 500 });
+  }
+}
+
+// POST /api/models/custom - Add custom model
+export async function POST(request) {
+  try {
+    const { providerAlias, id, type, name } = await request.json();
+    if (!providerAlias || !id) {
+      return NextResponse.json({ error: "providerAlias and id required" }, { status: 400 });
+    }
+    const added = await addCustomModel({ providerAlias, id, type: type || "llm", name });
+    return NextResponse.json({ success: true, added });
+  } catch (error) {
+    console.log("Error adding custom model:", error);
+    return NextResponse.json({ error: "Failed to add custom model" }, { status: 500 });
+  }
+}
+
+// DELETE /api/models/custom?providerAlias=xxx&id=yyy&type=zzz
+export async function DELETE(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const providerAlias = searchParams.get("providerAlias");
+    const id = searchParams.get("id");
+    const type = searchParams.get("type") || "llm";
+    if (!providerAlias || !id) {
+      return NextResponse.json({ error: "providerAlias and id required" }, { status: 400 });
+    }
+    await deleteCustomModel({ providerAlias, id, type });
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.log("Error deleting custom model:", error);
+    return NextResponse.json({ error: "Failed to delete custom model" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/models/disabled/route.js b/src/app/api/models/disabled/route.js
new file mode 100644
index 0000000..e9d3e31
--- /dev/null
+++ b/src/app/api/models/disabled/route.js
@@ -0,0 +1,50 @@
+import { NextResponse } from "next/server";
+import { getDisabledModels, disableModels, enableModels } from "@/lib/disabledModelsDb";
+
+export const dynamic = "force-dynamic";
+
+// GET /api/models/disabled?providerAlias=xxx
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const providerAlias = searchParams.get("providerAlias");
+    const all = await getDisabledModels();
+    if (providerAlias) return NextResponse.json({ ids: all[providerAlias] || [] });
+    return NextResponse.json({ disabled: all });
+  } catch (error) {
+    console.log("Error fetching disabled models:", error);
+    return NextResponse.json({ error: "Failed to fetch disabled models" }, { status: 500 });
+  }
+}
+
+// POST /api/models/disabled  body: { providerAlias, ids: [...] }
+export async function POST(request) {
+  try {
+    const { providerAlias, ids } = await request.json();
+    if (!providerAlias || !Array.isArray(ids)) {
+      return NextResponse.json({ error: "providerAlias and ids[] required" }, { status: 400 });
+    }
+    await disableModels(providerAlias, ids);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.log("Error disabling models:", error);
+    return NextResponse.json({ error: "Failed to disable models" }, { status: 500 });
+  }
+}
+
+// DELETE /api/models/disabled?providerAlias=xxx[&id=yyy]
+export async function DELETE(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const providerAlias = searchParams.get("providerAlias");
+    const id = searchParams.get("id");
+    if (!providerAlias) {
+      return NextResponse.json({ error: "providerAlias required" }, { status: 400 });
+    }
+    await enableModels(providerAlias, id ? [id] : []);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.log("Error enabling models:", error);
+    return NextResponse.json({ error: "Failed to enable models" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/models/route.js b/src/app/api/models/route.js
new file mode 100644
index 0000000..a4e833a
--- /dev/null
+++ b/src/app/api/models/route.js
@@ -0,0 +1,67 @@
+import { NextResponse } from "next/server";
+import { getModelAliases, setModelAlias } from "@/models";
+import { getDisabledModels } from "@/lib/disabledModelsDb";
+import { AI_MODELS } from "@/shared/constants/config";
+import { getProviderAlias } from "@/shared/constants/providers";
+import { getCapabilitiesForModel } from "open-sse/providers/capabilities.js";
+
+// GET /api/models - Get models with aliases
+export async function GET() {
+  try {
+    const modelAliases = await getModelAliases();
+    const disabled = await getDisabledModels();
+
+    const models = AI_MODELS
+      .filter((m) => {
+        const alias = getProviderAlias(m.provider) || m.provider;
+        const list = disabled[alias] || disabled[m.provider] || [];
+        return !list.includes(m.model);
+      })
+      .map((m) => {
+        const fullModel = `${m.provider}/${m.model}`;
+        const c = getCapabilitiesForModel(m.provider, m.model);
+        return {
+          ...m,
+          fullModel,
+          alias: modelAliases[fullModel] || m.model,
+          caps: { vision: c.vision, search: c.search, reasoning: c.reasoning },
+        };
+      });
+
+    return NextResponse.json({ models });
+  } catch (error) {
+    console.log("Error fetching models:", error);
+    return NextResponse.json({ error: "Failed to fetch models" }, { status: 500 });
+  }
+}
+
+// PUT /api/models - Update model alias
+export async function PUT(request) {
+  try {
+    const body = await request.json();
+    const { model, alias } = body;
+
+    if (!model || !alias) {
+      return NextResponse.json({ error: "Model and alias required" }, { status: 400 });
+    }
+
+    const modelAliases = await getModelAliases();
+
+    // Check if alias already exists for different model
+    const existingModel = Object.entries(modelAliases).find(
+      ([key, val]) => val === alias && key !== model
+    );
+
+    if (existingModel) {
+      return NextResponse.json({ error: "Alias already in use" }, { status: 400 });
+    }
+
+    // Update alias
+    await setModelAlias(model, alias);
+
+    return NextResponse.json({ success: true, model, alias });
+  } catch (error) {
+    console.log("Error updating alias:", error);
+    return NextResponse.json({ error: "Failed to update alias" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/models/test/ping.js b/src/app/api/models/test/ping.js
new file mode 100644
index 0000000..f7ea92a
--- /dev/null
+++ b/src/app/api/models/test/ping.js
@@ -0,0 +1,193 @@
+import { getApiKeys } from "@/lib/localDb";
+import { UPDATER_CONFIG } from "@/shared/constants/config";
+import { getConsistentMachineId } from "@/shared/utils/machineId";
+
+const CLI_TOKEN_SALT = "9r-cli-auth";
+
+function createSilentWavFile() {
+  const sampleRate = 16000;
+  const channels = 1;
+  const bitsPerSample = 16;
+  const durationMs = 250;
+  const sampleCount = Math.max(1, Math.floor((sampleRate * durationMs) / 1000));
+  const dataSize = sampleCount * channels * (bitsPerSample / 8);
+  const buffer = new ArrayBuffer(44 + dataSize);
+  const view = new DataView(buffer);
+
+  const writeAscii = (offset, value) => {
+    for (let i = 0; i < value.length; i += 1) {
+      view.setUint8(offset + i, value.charCodeAt(i));
+    }
+  };
+
+  writeAscii(0, "RIFF");
+  view.setUint32(4, 36 + dataSize, true);
+  writeAscii(8, "WAVE");
+  writeAscii(12, "fmt ");
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, channels, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * channels * (bitsPerSample / 8), true);
+  view.setUint16(32, channels * (bitsPerSample / 8), true);
+  view.setUint16(34, bitsPerSample, true);
+  writeAscii(36, "data");
+  view.setUint32(40, dataSize, true);
+
+  return new Blob([buffer], { type: "audio/wav" });
+}
+
+async function getInternalHeaders() {
+  let apiKey = null;
+  try {
+    const keys = await getApiKeys();
+    apiKey = keys.find((k) => k.isActive !== false)?.key || null;
+  } catch {}
+
+  const headers = { "Content-Type": "application/json" };
+  if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+  headers["x-9r-cli-token"] = await getConsistentMachineId(CLI_TOKEN_SALT);
+  return headers;
+}
+
+export async function pingModelByKind(model, kind, baseUrl = `http://127.0.0.1:${process.env.PORT || UPDATER_CONFIG.appPort}`) {
+  const headers = await getInternalHeaders();
+  const start = Date.now();
+
+  if (kind === "embedding") {
+    const res = await fetch(`${baseUrl}/api/v1/embeddings`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ model, input: "test" }),
+      signal: AbortSignal.timeout(15000),
+    });
+    const latencyMs = Date.now() - start;
+    const rawText = await res.text().catch(() => "");
+    let parsed = null;
+    try { parsed = rawText ? JSON.parse(rawText) : null; } catch {}
+
+    if (!res.ok) {
+      const detail = parsed?.error?.message || parsed?.error || rawText;
+      return { ok: false, latencyMs, error: `HTTP ${res.status}${detail ? `: ${String(detail).slice(0, 240)}` : ""}`, status: res.status };
+    }
+    const hasEmbedding = Array.isArray(parsed?.data) && parsed.data.length > 0 && Array.isArray(parsed.data[0]?.embedding);
+    if (!hasEmbedding) {
+      return { ok: false, latencyMs, status: res.status, error: "Provider returned no embedding data" };
+    }
+    return { ok: true, latencyMs, error: null, status: res.status };
+  }
+
+  if (kind === "image") {
+    const res = await fetch(`${baseUrl}/api/v1/images/generations`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ model, prompt: "test" }),
+      signal: AbortSignal.timeout(15000),
+    });
+    const latencyMs = Date.now() - start;
+    const rawText = await res.text().catch(() => "");
+    let parsed = null;
+    try { parsed = rawText ? JSON.parse(rawText) : null; } catch {}
+
+    if (!res.ok) {
+      const detail = parsed?.error?.message || parsed?.msg || parsed?.message || parsed?.error || rawText;
+      return { ok: false, latencyMs, error: `HTTP ${res.status}${detail ? `: ${String(detail).slice(0, 240)}` : ""}`, status: res.status };
+    }
+
+    const hasImages = Array.isArray(parsed?.data) && parsed.data.length > 0;
+    if (!hasImages) {
+      return { ok: false, latencyMs, status: res.status, error: "Provider returned no image data for this model" };
+    }
+    return { ok: true, latencyMs, error: null, status: res.status };
+  }
+
+  if (kind === "stt") {
+    const form = new FormData();
+    const sampleAudio = createSilentWavFile();
+    form.append("file", sampleAudio, "test.wav");
+    form.append("model", model);
+
+    const res = await fetch(`${baseUrl}/api/v1/audio/transcriptions`, {
+      method: "POST",
+      headers: Object.fromEntries(Object.entries(headers).filter(([key]) => key.toLowerCase() !== "content-type")),
+      body: form,
+      signal: AbortSignal.timeout(15000),
+    });
+    const latencyMs = Date.now() - start;
+    const rawText = await res.text().catch(() => "");
+    let parsed = null;
+    try { parsed = rawText ? JSON.parse(rawText) : null; } catch {}
+
+    if (!res.ok) {
+      const detail = parsed?.error?.message || parsed?.msg || parsed?.message || parsed?.error || rawText;
+      return { ok: false, latencyMs, error: `HTTP ${res.status}${detail ? `: ${String(detail).slice(0, 240)}` : ""}`, status: res.status };
+    }
+
+    const text = typeof parsed?.text === "string" ? parsed.text : "";
+    if (!text.trim()) {
+      return { ok: false, latencyMs, status: res.status, error: "Provider returned no transcription text for this model" };
+    }
+    return { ok: true, latencyMs, error: null, status: res.status };
+  }
+
+  const res = await fetch(`${baseUrl}/api/v1/chat/completions`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      model,
+      // Claude-on-Copilot returns empty choices at max_tokens:1 (budget is spent
+      // before a content token emits), so a 1-token probe yields a false negative.
+      max_tokens: 16,
+      stream: false,
+      messages: [{ role: "user", content: "hi" }],
+    }),
+    signal: AbortSignal.timeout(15000),
+  });
+  const latencyMs = Date.now() - start;
+
+  const rawText = await res.text().catch(() => "");
+  let parsed = null;
+  try { parsed = rawText ? JSON.parse(rawText) : null; } catch {}
+
+  if (!res.ok) {
+    const detail = parsed?.error?.message || parsed?.msg || parsed?.message || parsed?.error || rawText;
+    return { ok: false, latencyMs, error: `HTTP ${res.status}${detail ? `: ${String(detail).slice(0, 240)}` : ""}`, status: res.status };
+  }
+
+  const providerStatus = parsed?.status;
+  const providerMsg = parsed?.msg || parsed?.message;
+  const hasProviderErrorStatus = providerStatus !== undefined
+    && providerStatus !== null
+    && String(providerStatus) !== "200"
+    && String(providerStatus) !== "0";
+  if (hasProviderErrorStatus && providerMsg) {
+    return {
+      ok: false,
+      latencyMs,
+      status: res.status,
+      error: `Provider status ${providerStatus}: ${String(providerMsg).slice(0, 240)}`,
+    };
+  }
+
+  if (parsed?.error) {
+    const providerError = parsed?.error?.message || parsed?.error || "Provider returned an error";
+    return {
+      ok: false,
+      latencyMs,
+      status: res.status,
+      error: String(providerError).slice(0, 240),
+    };
+  }
+
+  const hasChoices = Array.isArray(parsed?.choices) && parsed.choices.length > 0;
+  if (!hasChoices) {
+    return {
+      ok: false,
+      latencyMs,
+      status: res.status,
+      error: "Provider returned no completion choices for this model",
+    };
+  }
+
+  return { ok: true, latencyMs, error: null, status: res.status };
+}
diff --git a/src/app/api/models/test/route.js b/src/app/api/models/test/route.js
new file mode 100644
index 0000000..0b35c9f
--- /dev/null
+++ b/src/app/api/models/test/route.js
@@ -0,0 +1,14 @@
+import { NextResponse } from "next/server";
+import { pingModelByKind } from "./ping";
+
+// POST /api/models/test - Ping a single model via internal completions or embeddings
+export async function POST(request) {
+  try {
+    const { model, kind } = await request.json();
+    if (!model) return NextResponse.json({ error: "Model required" }, { status: 400 });
+    const result = await pingModelByKind(model, kind || "llm");
+    return NextResponse.json(result);
+  } catch (err) {
+    return NextResponse.json({ ok: false, error: err.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/oauth/[provider]/[action]/route.js b/src/app/api/oauth/[provider]/[action]/route.js
new file mode 100644
index 0000000..57bff27
--- /dev/null
+++ b/src/app/api/oauth/[provider]/[action]/route.js
@@ -0,0 +1,351 @@
+import { NextResponse } from "next/server";
+import { 
+  getProvider, 
+  generateAuthData, 
+  exchangeTokens, 
+  requestDeviceCode, 
+  pollForToken 
+} from "@/lib/oauth/providers";
+import { createProviderConnection } from "@/models";
+import {
+  startCodexProxy,
+  stopCodexProxy,
+  registerCodexSession,
+  getCodexSessionStatus,
+  clearCodexSession,
+  startXaiProxy,
+  stopXaiProxy,
+  registerXaiSession,
+  getXaiSessionStatus,
+  clearXaiSession,
+} from "@/lib/oauth/utils/server";
+
+async function completeXaiManualCode(code, state) {
+  const session = state ? getXaiSessionStatus(state) : null;
+  if (!session) {
+    throw new Error("xAI OAuth session not found; restart the login flow and paste the code again");
+  }
+  if (!code) throw new Error("Missing xAI authorization code");
+
+  try {
+    const tokenData = await exchangeTokens(
+      "xai",
+      code,
+      session.redirectUri,
+      session.codeVerifier,
+      state
+    );
+    const connection = await createProviderConnection({
+      provider: "xai",
+      authType: "oauth",
+      ...tokenData,
+      expiresAt: tokenData.expiresIn
+        ? new Date(Date.now() + tokenData.expiresIn * 1000).toISOString()
+        : null,
+      testStatus: "active",
+    });
+    clearXaiSession(state);
+    stopXaiProxy();
+    return {
+      id: connection.id,
+      provider: connection.provider,
+      email: connection.email,
+      displayName: connection.displayName,
+    };
+  } catch (err) {
+    clearXaiSession(state);
+    stopXaiProxy();
+    throw err;
+  }
+}
+
+/**
+ * Dynamic OAuth API Route
+ * Handles: authorize, exchange, device-code, poll
+ */
+
+// GET /api/oauth/[provider]/authorize - Generate auth URL
+// GET /api/oauth/[provider]/device-code - Request device code (for device_code flow)
+export async function GET(request, { params }) {
+  try {
+    const { provider, action } = await params;
+    const { searchParams } = new URL(request.url);
+
+    if (action === "authorize") {
+      const redirectUri = searchParams.get("redirect_uri") || "http://localhost:8080/callback";
+      // Collect provider-specific meta params (e.g. gitlab passes baseUrl, clientId, clientSecret)
+      const reservedParams = new Set(["redirect_uri"]);
+      const meta = {};
+      searchParams.forEach((value, key) => { if (!reservedParams.has(key)) meta[key] = value; });
+      const authData = await generateAuthData(provider, redirectUri, Object.keys(meta).length ? meta : undefined);
+      return NextResponse.json(authData);
+    }
+
+    if (action === "start-proxy") {
+      if (!["codex", "xai"].includes(provider)) {
+        return NextResponse.json({ error: "Proxy only supported for codex/xai" }, { status: 400 });
+      }
+      const appPort = searchParams.get("app_port");
+      if (!appPort) {
+        return NextResponse.json({ error: "Missing app_port" }, { status: 400 });
+      }
+      const state = searchParams.get("state");
+      const codeVerifier = searchParams.get("code_verifier");
+      const redirectUri = searchParams.get("redirect_uri");
+      const result = provider === "xai"
+        ? await startXaiProxy(Number(appPort))
+        : await startCodexProxy(Number(appPort));
+      let serverSide = false;
+      if (result.success && state && codeVerifier && redirectUri) {
+        serverSide = provider === "xai"
+          ? registerXaiSession({ state, codeVerifier, redirectUri })
+          : registerCodexSession({ state, codeVerifier, redirectUri });
+      }
+      return NextResponse.json({ ...result, serverSide });
+    }
+
+    if (action === "poll-status") {
+      if (!["codex", "xai"].includes(provider)) {
+        return NextResponse.json({ error: "Poll only supported for codex/xai" }, { status: 400 });
+      }
+      const state = searchParams.get("state");
+      if (!state) {
+        return NextResponse.json({ error: "Missing state" }, { status: 400 });
+      }
+      const session = provider === "xai" ? getXaiSessionStatus(state) : getCodexSessionStatus(state);
+      if (!session) return NextResponse.json({ status: "unknown" });
+      if (session.status === "done" || session.status === "error") {
+        const payload = { ...session };
+        if (provider === "xai") clearXaiSession(state);
+        else clearCodexSession(state);
+        return NextResponse.json(payload);
+      }
+      return NextResponse.json({ status: session.status });
+    }
+
+    if (action === "stop-proxy") {
+      if (!["codex", "xai"].includes(provider)) {
+        return NextResponse.json({ error: "Proxy only supported for codex/xai" }, { status: 400 });
+      }
+      if (provider === "xai") stopXaiProxy();
+      else stopCodexProxy();
+      return NextResponse.json({ success: true });
+    }
+
+    if (action === "device-code") {
+      const providerData = getProvider(provider);
+      if (providerData.flowType !== "device_code") {
+        return NextResponse.json({ error: "Provider does not support device code flow" }, { status: 400 });
+      }
+
+      const authData = await generateAuthData(provider, null);
+      const startUrl = searchParams.get("start_url");
+      const region = searchParams.get("region");
+      const authMethod = searchParams.get("auth_method");
+      const deviceOptions = provider === "kiro"
+        ? {
+            ...(startUrl ? { startUrl } : {}),
+            ...(region ? { region } : {}),
+            ...(authMethod ? { authMethod } : {}),
+          }
+        : undefined;
+      
+      // Providers that don't use PKCE for device code (Grok CLI HAR: plain device_code, no challenge)
+      const noPkceDeviceProviders = [
+        "github",
+        "kiro",
+        "kimi-coding",
+        "kilocode",
+        "codebuddy-cn",
+        "qoder",
+        "grok-cli",
+      ];
+      let deviceData;
+      if (noPkceDeviceProviders.includes(provider)) {
+        deviceData = await requestDeviceCode(provider, undefined, deviceOptions);
+      } else {
+        // Qwen and other PKCE providers
+        deviceData = await requestDeviceCode(provider, authData.codeChallenge, deviceOptions);
+      }
+
+      return NextResponse.json({
+        ...deviceData,
+        // Prefer the verifier the provider's requestDeviceCode generated for
+        // itself (qoder rolls its own PKCE pair); fall back to the generic one.
+        codeVerifier: deviceData.codeVerifier || authData.codeVerifier,
+      });
+    }
+
+    return NextResponse.json({ error: "Unknown action" }, { status: 400 });
+  } catch (error) {
+    console.log("OAuth GET error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
+
+// POST /api/oauth/[provider]/exchange - Exchange code for tokens and save
+// POST /api/oauth/[provider]/poll - Poll for token (device_code flow)
+export async function POST(request, { params }) {
+  try {
+    const { provider, action } = await params;
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      return NextResponse.json({ error: "Invalid or empty request body" }, { status: 400 });
+    }
+
+    if (action === "exchange") {
+      const { code, redirectUri, codeVerifier, state, meta } = body;
+
+      // Detect if "code" is actually a raw JWT access token (starts with eyJ)
+      if (code && code.startsWith("eyJ") && code.includes(".")) {
+        const { extractCodexAccountInfo } = await import("@/lib/oauth/providers");
+        const info = extractCodexAccountInfo(code);
+
+        // Also decode JWT directly for ChatGPT website tokens which use
+        // top-level account_id/plan_type instead of nested openai auth claims
+        let directPayload = {};
+        try {
+          const b64 = code.split(".")[1].replace(/-/g, "+").replace(/_/g, "/");
+          const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+          directPayload = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+        } catch {}
+
+        const accountId = info.chatgptAccountId || directPayload.account_id;
+        const planType = info.chatgptPlanType || directPayload.plan_type;
+        const email = info.email || directPayload.email;
+
+        const providerSpecificData = { authMethod: "access_token" };
+        if (accountId) providerSpecificData.chatgptAccountId = accountId;
+        if (planType) providerSpecificData.chatgptPlanType = planType;
+
+        const connection = await createProviderConnection({
+          provider,
+          authType: "access_token",
+          accessToken: code,
+          email: email || null,
+          providerSpecificData,
+          testStatus: "active",
+        });
+
+        return NextResponse.json({
+          success: true,
+          connection: {
+            id: connection.id,
+            provider: connection.provider,
+            email: connection.email,
+            displayName: connection.displayName,
+          }
+        });
+      }
+
+      // Cline and ClinePass use authorization_code without PKCE. Kimchi returns a browser token.
+      const noPkceExchangeProviders = ["cline", "clinepass", "kimchi"];
+      if (!code || !redirectUri || (!codeVerifier && !noPkceExchangeProviders.includes(provider))) {
+        return NextResponse.json({ error: "Missing required fields" }, { status: 400 });
+      }
+
+      // Exchange code for tokens (meta carries provider-specific params, e.g. gitlab clientId/baseUrl)
+      const tokenData = await exchangeTokens(provider, code, redirectUri, codeVerifier, state, meta);
+
+      // Save to database
+      const connection = await createProviderConnection({
+        provider,
+        authType: "oauth",
+        ...tokenData,
+        expiresAt: tokenData.expiresIn 
+          ? new Date(Date.now() + tokenData.expiresIn * 1000).toISOString() 
+          : null,
+        testStatus: "active",
+      });
+
+      return NextResponse.json({ 
+        success: true, 
+        connection: {
+          id: connection.id,
+          provider: connection.provider,
+          email: connection.email,
+          displayName: connection.displayName,
+        }
+      });
+    }
+
+    if (action === "poll") {
+      const { deviceCode, codeVerifier, extraData } = body;
+
+      if (!deviceCode) {
+        return NextResponse.json({ error: "Missing device code" }, { status: 400 });
+      }
+
+      // Providers that don't use PKCE for device code
+      const noPkceProviders = ["github", "kimi-coding", "kilocode", "codebuddy-cn"];
+      let result;
+      if (noPkceProviders.includes(provider)) {
+        result = await pollForToken(provider, deviceCode);
+      } else if (provider === "kiro") {
+        // Kiro needs extraData (clientId, clientSecret) from device code response
+        result = await pollForToken(provider, deviceCode, null, extraData);
+      } else if (provider === "qoder") {
+        // Qoder needs both the PKCE verifier (codeVerifier) and the machineId
+        // captured at device-code time (extraData._qoderMachineId) so
+        // mapTokens can persist it for COSY signing.
+        if (!codeVerifier) {
+          return NextResponse.json({ error: "Missing code verifier" }, { status: 400 });
+        }
+        result = await pollForToken(provider, deviceCode, codeVerifier, extraData);
+      } else {
+        // Qwen and other PKCE providers
+        if (!codeVerifier) {
+          return NextResponse.json({ error: "Missing code verifier" }, { status: 400 });
+        }
+        result = await pollForToken(provider, deviceCode, codeVerifier);
+      }
+
+      if (result.success) {
+        // Save to database
+        const connection = await createProviderConnection({
+          provider,
+          authType: "oauth",
+          ...result.tokens,
+          expiresAt: result.tokens.expiresIn 
+            ? new Date(Date.now() + result.tokens.expiresIn * 1000).toISOString() 
+            : null,
+          testStatus: "active",
+        });
+
+        return NextResponse.json({ 
+          success: true, 
+          connection: {
+            id: connection.id,
+            provider: connection.provider,
+          }
+        });
+      }
+
+      // Still pending or error - don't create connection for pending states
+      const isPending = result.pending || result.error === "authorization_pending" || result.error === "slow_down";
+      
+      return NextResponse.json({
+        success: false,
+        error: result.error,
+        errorDescription: result.errorDescription,
+        pending: isPending,
+      });
+    }
+
+    if (action === "manual-code") {
+      if (provider !== "xai") {
+        return NextResponse.json({ error: "Manual code only supported for xai" }, { status: 400 });
+      }
+      const { code, state } = body;
+      const connection = await completeXaiManualCode(String(code || "").trim(), String(state || "").trim());
+      return NextResponse.json({ success: true, connection });
+    }
+
+    return NextResponse.json({ error: "Unknown action" }, { status: 400 });
+  } catch (error) {
+    console.log("OAuth POST error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/oauth/codex/bulk-import/route.js b/src/app/api/oauth/codex/bulk-import/route.js
new file mode 100644
index 0000000..42d5341
--- /dev/null
+++ b/src/app/api/oauth/codex/bulk-import/route.js
@@ -0,0 +1,121 @@
+import { NextResponse } from "next/server";
+import { createProviderConnection } from "@/models";
+import { extractCodexAccountInfo } from "@/lib/oauth/providers";
+
+/**
+ * POST /api/oauth/codex/bulk-import
+ * Bulk import multiple codex (OAuth) account JSON objects in one call.
+ *
+ * Body accepts any of:
+ *   - Array:    [{...}, {...}]
+ *   - Single:   {...}
+ *   - Wrapped:  { accounts: [{...}, ...] }
+ *
+ * Each item must contain at least `accessToken`. Missing email / chatgpt
+ * account info is best-effort backfilled from the JWT (idToken or accessToken).
+ *
+ * Tokens are NEVER echoed back in the response.
+ */
+export async function POST(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch (err) {
+    return NextResponse.json(
+      { error: `Invalid JSON body: ${err.message}` },
+      { status: 400 }
+    );
+  }
+
+  // Normalize to array
+  let accounts;
+  if (Array.isArray(body)) {
+    accounts = body;
+  } else if (body && typeof body === "object" && Array.isArray(body.accounts)) {
+    accounts = body.accounts;
+  } else if (body && typeof body === "object") {
+    accounts = [body];
+  } else {
+    accounts = null;
+  }
+
+  if (!Array.isArray(accounts) || accounts.length === 0) {
+    return NextResponse.json(
+      { error: "No accounts provided" },
+      { status: 400 }
+    );
+  }
+
+  const results = [];
+  let success = 0;
+  let failed = 0;
+
+  // SERIAL loop — createProviderConnection reads max(priority) and reorders
+  // inside a transaction. Parallel calls would race on priority assignment.
+  for (let i = 0; i < accounts.length; i++) {
+    const raw = accounts[i];
+    try {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("Item is not an object");
+      }
+
+      // Strip server-controlled fields
+      const {
+        id: _id,
+        provider: _provider,
+        authType: _authType,
+        createdAt: _createdAt,
+        updatedAt: _updatedAt,
+        ...item
+      } = raw;
+
+      if (!item.accessToken || typeof item.accessToken !== "string") {
+        throw new Error("Missing accessToken");
+      }
+
+      // Backfill missing identity fields from JWT claims
+      const psd = item.providerSpecificData || {};
+      const needsEmail = !item.email;
+      const needsAccountId = !psd.chatgptAccountId;
+      const needsPlanType = !psd.chatgptPlanType;
+
+      if (needsEmail || needsAccountId || needsPlanType) {
+        const info = extractCodexAccountInfo(item.idToken || item.accessToken) || {};
+        if (needsEmail && info.email) item.email = info.email;
+        if (needsAccountId && info.chatgptAccountId) {
+          psd.chatgptAccountId = info.chatgptAccountId;
+        }
+        if (needsPlanType && info.chatgptPlanType) {
+          psd.chatgptPlanType = info.chatgptPlanType;
+        }
+      }
+      if (Object.keys(psd).length > 0) {
+        item.providerSpecificData = psd;
+      }
+
+      // Compute expiresAt from expiresIn if absent
+      if (!item.expiresAt && typeof item.expiresIn === "number" && item.expiresIn > 0) {
+        item.expiresAt = new Date(Date.now() + item.expiresIn * 1000).toISOString();
+      }
+
+      // Defaults aligned with OAuth-completed flow
+      if (item.testStatus === undefined) item.testStatus = "active";
+      if (item.isActive === undefined) item.isActive = true;
+      if (!item.lastRefreshAt) item.lastRefreshAt = new Date().toISOString();
+
+      const created = await createProviderConnection({
+        provider: "codex",
+        authType: "oauth",
+        ...item,
+      });
+
+      results.push({ index: i, ok: true, id: created.id });
+      success++;
+    } catch (e) {
+      results.push({ index: i, ok: false, error: e.message || "Unknown error" });
+      failed++;
+    }
+  }
+
+  return NextResponse.json({ success, failed, results });
+}
diff --git a/src/app/api/oauth/codex/import-token/route.js b/src/app/api/oauth/codex/import-token/route.js
new file mode 100644
index 0000000..73e80d5
--- /dev/null
+++ b/src/app/api/oauth/codex/import-token/route.js
@@ -0,0 +1,96 @@
+import { NextResponse } from "next/server";
+import { createProviderConnection } from "@/models";
+import { extractCodexAccountInfo } from "@/lib/oauth/providers";
+
+/**
+ * POST /api/oauth/codex/import-token
+ * Import a ChatGPT access token (created from chatgpt.com settings)
+ * as a provider connection, bypassing OAuth refresh flow.
+ *
+ * Body: { accessToken: string, name?: string }
+ */
+export async function POST(request) {
+  try {
+    const { accessToken, name } = await request.json();
+
+    if (!accessToken || typeof accessToken !== "string") {
+      return NextResponse.json(
+        { error: "Access token is required" },
+        { status: 400 }
+      );
+    }
+
+    const token = accessToken.trim();
+
+    // Extract account info from the JWT (email, workspace, plan)
+    let email = null;
+    let providerSpecificData = { authMethod: "access_token" };
+
+    // Try decoding as JWT to extract email + workspace
+    try {
+      const parts = token.split(".");
+      if (parts.length === 3) {
+        const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const missingPadding = (4 - (base64.length % 4)) % 4;
+        const padded = base64 + "=".repeat(missingPadding);
+        const payload = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+
+        // Extract from OpenAI JWT structure
+        const auth = payload["https://api.openai.com/auth"] || {};
+        const profile = payload["https://api.openai.com/profile"] || {};
+        email = profile.email || payload.email || payload.preferred_username || null;
+
+        if (auth.chatgpt_account_id) {
+          providerSpecificData.chatgptAccountId = auth.chatgpt_account_id;
+        }
+        if (auth.chatgpt_plan_type) {
+          providerSpecificData.chatgptPlanType = auth.chatgpt_plan_type;
+        }
+
+        // Store expiry info from JWT if available
+        if (payload.exp) {
+          providerSpecificData.jwtExp = payload.exp;
+        }
+      }
+    } catch {
+      // Not a JWT or malformed — still allow import as raw token
+    }
+
+    // Also try extractCodexAccountInfo via id_token-style extraction
+    // (the access token itself may contain the same claims)
+    if (!email) {
+      const info = extractCodexAccountInfo(token);
+      if (info.email) email = info.email;
+      if (info.chatgptAccountId) providerSpecificData.chatgptAccountId = info.chatgptAccountId;
+      if (info.chatgptPlanType) providerSpecificData.chatgptPlanType = info.chatgptPlanType;
+    }
+
+    const connectionName = name || email || "ChatGPT Access Token";
+
+    // Save to database as access_token authType (no refresh token)
+    const connection = await createProviderConnection({
+      provider: "codex",
+      authType: "access_token",
+      accessToken: token,
+      name: connectionName,
+      email: email,
+      providerSpecificData,
+      testStatus: "active",
+    });
+
+    return NextResponse.json({
+      success: true,
+      connection: {
+        id: connection.id,
+        provider: connection.provider,
+        email: connection.email,
+        name: connection.name,
+        workspace: providerSpecificData.chatgptAccountId || null,
+        plan: providerSpecificData.chatgptPlanType || null,
+      },
+    });
+  } catch (error) {
+    console.log("Codex access token import error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/oauth/cursor/auto-import/route.js b/src/app/api/oauth/cursor/auto-import/route.js
new file mode 100644
index 0000000..5f84fa9
--- /dev/null
+++ b/src/app/api/oauth/cursor/auto-import/route.js
@@ -0,0 +1,258 @@
+import { NextResponse } from "next/server";
+import { access, constants } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+
+const ACCESS_TOKEN_KEYS = ["cursorAuth/accessToken", "cursorAuth/token"];
+const MACHINE_ID_KEYS = [
+  "storage.serviceMachineId",
+  "storage.machineId",
+  "telemetry.machineId",
+];
+
+/** Get candidate db paths by platform */
+function getCandidatePaths(platform) {
+  const home = homedir();
+
+  if (platform === "darwin") {
+    return [
+      join(
+        home,
+        "Library/Application Support/Cursor/User/globalStorage/state.vscdb",
+      ),
+      join(
+        home,
+        "Library/Application Support/Cursor - Insiders/User/globalStorage/state.vscdb",
+      ),
+    ];
+  }
+
+  if (platform === "win32") {
+    const appData = process.env.APPDATA || join(home, "AppData", "Roaming");
+    const localAppData =
+      process.env.LOCALAPPDATA || join(home, "AppData", "Local");
+    return [
+      join(appData, "Cursor", "User", "globalStorage", "state.vscdb"),
+      join(
+        appData,
+        "Cursor - Insiders",
+        "User",
+        "globalStorage",
+        "state.vscdb",
+      ),
+      join(localAppData, "Cursor", "User", "globalStorage", "state.vscdb"),
+      join(
+        localAppData,
+        "Programs",
+        "Cursor",
+        "User",
+        "globalStorage",
+        "state.vscdb",
+      ),
+    ];
+  }
+
+  return [
+    join(home, ".config/Cursor/User/globalStorage/state.vscdb"),
+    join(home, ".config/cursor/User/globalStorage/state.vscdb"),
+  ];
+}
+
+const normalize = (value) => {
+  if (typeof value !== "string") return value;
+  try {
+    const parsed = JSON.parse(value);
+    return typeof parsed === "string" ? parsed : value;
+  } catch {
+    return value;
+  }
+};
+
+/**
+ * Extract tokens via better-sqlite3 (bundled dependency).
+ * This is the preferred strategy — no external CLI required.
+ */
+function extractTokensViaBetterSqlite(dbPath) {
+  // Dynamic require so the route stays importable even if native bindings fail
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const Database = require("better-sqlite3");
+  const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+
+  const query = (key) => {
+    const row = db.prepare("SELECT value FROM itemTable WHERE key=? LIMIT 1").get(key);
+    return row?.value || null;
+  };
+
+  const normalize = (value) => {
+    if (typeof value !== "string") return value;
+    try {
+      const parsed = JSON.parse(value);
+      return typeof parsed === "string" ? parsed : value;
+    } catch {
+      return value;
+    }
+  };
+
+  let accessToken = null;
+  for (const key of ACCESS_TOKEN_KEYS) {
+    const raw = query(key);
+    if (raw) { accessToken = normalize(raw); break; }
+  }
+
+  let machineId = null;
+  for (const key of MACHINE_ID_KEYS) {
+    const raw = query(key);
+    if (raw) { machineId = normalize(raw); break; }
+  }
+
+  db.close();
+  return { accessToken, machineId };
+}
+
+/**
+ * Extract tokens via sqlite3 CLI.
+ * Fallback when better-sqlite3 native bindings are unavailable.
+ */
+async function extractTokensViaCLI(dbPath) {
+  const normalize = (raw) => {
+    const value = raw.trim();
+    try {
+      const parsed = JSON.parse(value);
+      return typeof parsed === "string" ? parsed : value;
+    } catch {
+      return value;
+    }
+  };
+
+  const query = async (sql) => {
+    const { stdout } = await execFileAsync("sqlite3", [dbPath, sql], {
+      timeout: 10000,
+    });
+    return stdout.trim();
+  };
+
+  // Try each key in priority order
+  let accessToken = null;
+  for (const key of ACCESS_TOKEN_KEYS) {
+    try {
+      const raw = await query(
+        `SELECT value FROM itemTable WHERE key='${key}' LIMIT 1`,
+      );
+      if (raw) {
+        accessToken = normalize(raw);
+        break;
+      }
+    } catch {
+      /* try next */
+    }
+  }
+
+  let machineId = null;
+  for (const key of MACHINE_ID_KEYS) {
+    try {
+      const raw = await query(
+        `SELECT value FROM itemTable WHERE key='${key}' LIMIT 1`,
+      );
+      if (raw) {
+        machineId = normalize(raw);
+        break;
+      }
+    } catch {
+      /* try next */
+    }
+  }
+
+  return { accessToken, machineId };
+}
+
+/**
+ * GET /api/oauth/cursor/auto-import
+ * Auto-detect and extract Cursor tokens from local SQLite database.
+ * Strategy: better-sqlite3 → sqlite3 CLI → manual fallback
+ */
+export async function GET() {
+  try {
+    const platform = process.platform;
+    const candidates = getCandidatePaths(platform);
+
+    let dbPath = null;
+    for (const candidate of candidates) {
+      try {
+        await access(candidate, constants.R_OK);
+        dbPath = candidate;
+        break;
+      } catch {
+        // Try next candidate
+      }
+    }
+
+    if (!dbPath) {
+      return NextResponse.json({
+        found: false,
+        error: `Cursor database not found. Checked locations:\n${candidates.join("\n")}\n\nMake sure Cursor IDE is installed and opened at least once.`,
+      });
+    }
+
+    // On Linux, verify Cursor is actually installed (not just leftover config)
+    if (platform === "linux") {
+      let cursorInstalled = false;
+      try {
+        await execFileAsync("which", ["cursor"], { timeout: 5000 });
+        cursorInstalled = true;
+      } catch {
+        try {
+          const desktopFile = join(homedir(), ".local/share/applications/cursor.desktop");
+          await access(desktopFile, constants.R_OK);
+          cursorInstalled = true;
+        } catch { /* not found */ }
+      }
+      if (!cursorInstalled) {
+        return NextResponse.json({
+          found: false,
+          error: "Cursor config files found but Cursor IDE does not appear to be installed. Skipping auto-import.",
+        });
+      }
+    }
+
+    // Strategy 1: better-sqlite3 (bundled — no external tools required)
+    try {
+      const tokens = extractTokensViaBetterSqlite(dbPath);
+      if (tokens.accessToken && tokens.machineId) {
+        return NextResponse.json({
+          found: true,
+          accessToken: tokens.accessToken,
+          machineId: tokens.machineId,
+        });
+      }
+    } catch {
+      // Native bindings unavailable — try CLI fallback
+    }
+
+    // Strategy 2: sqlite3 CLI
+    try {
+      const tokens = await extractTokensViaCLI(dbPath);
+      if (tokens.accessToken && tokens.machineId) {
+        return NextResponse.json({
+          found: true,
+          accessToken: tokens.accessToken,
+          machineId: tokens.machineId,
+        });
+      }
+    } catch {
+      // sqlite3 CLI not available either
+    }
+
+    // Strategy 3: ask user to paste manually
+    return NextResponse.json({ found: false, windowsManual: true, dbPath });
+  } catch (error) {
+    console.log("Cursor auto-import error:", error);
+    return NextResponse.json(
+      { found: false, error: error.message },
+      { status: 500 },
+    );
+  }
+}
diff --git a/src/app/api/oauth/cursor/import/route.js b/src/app/api/oauth/cursor/import/route.js
new file mode 100644
index 0000000..a1695e9
--- /dev/null
+++ b/src/app/api/oauth/cursor/import/route.js
@@ -0,0 +1,100 @@
+import { NextResponse } from "next/server";
+import { CursorService } from "@/lib/oauth/services/cursor";
+import { createProviderConnection } from "@/models";
+
+/**
+ * POST /api/oauth/cursor/import
+ * Import and validate access token from Cursor IDE's local SQLite database
+ *
+ * Request body:
+ * - accessToken: string - Access token from cursorAuth/accessToken
+ * - machineId: string - Machine ID from storage.serviceMachineId
+ */
+export async function POST(request) {
+  try {
+    const { accessToken, machineId } = await request.json();
+
+    if (!accessToken || typeof accessToken !== "string") {
+      return NextResponse.json(
+        { error: "Access token is required" },
+        { status: 400 }
+      );
+    }
+
+    if (!machineId || typeof machineId !== "string") {
+      return NextResponse.json(
+        { error: "Machine ID is required" },
+        { status: 400 }
+      );
+    }
+
+    const cursorService = new CursorService();
+
+    // Validate token by making API call
+    const tokenData = await cursorService.validateImportToken(
+      accessToken.trim(),
+      machineId.trim()
+    );
+
+    // Try to extract user info from token
+    const userInfo = cursorService.extractUserInfo(tokenData.accessToken);
+
+    // Save to database
+    const connection = await createProviderConnection({
+      provider: "cursor",
+      authType: "oauth",
+      accessToken: tokenData.accessToken,
+      refreshToken: null, // Cursor doesn't have public refresh endpoint
+      expiresAt: new Date(Date.now() + tokenData.expiresIn * 1000).toISOString(),
+      email: userInfo?.email || null,
+      providerSpecificData: {
+        machineId: tokenData.machineId,
+        authMethod: "imported",
+        provider: "Imported",
+        userId: userInfo?.userId,
+      },
+      testStatus: "active",
+    });
+
+    return NextResponse.json({
+      success: true,
+      connection: {
+        id: connection.id,
+        provider: connection.provider,
+        email: connection.email,
+      },
+    });
+  } catch (error) {
+    console.log("Cursor import token error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
+
+/**
+ * GET /api/oauth/cursor/import
+ * Get instructions for importing Cursor token
+ */
+export async function GET() {
+  const cursorService = new CursorService();
+  const instructions = cursorService.getTokenStorageInstructions();
+
+  return NextResponse.json({
+    provider: "cursor",
+    method: "import_token",
+    instructions,
+    requiredFields: [
+      {
+        name: "accessToken",
+        label: "Access Token",
+        description: "From cursorAuth/accessToken in state.vscdb",
+        type: "textarea",
+      },
+      {
+        name: "machineId",
+        label: "Machine ID",
+        description: "From storage.serviceMachineId in state.vscdb",
+        type: "text",
+      },
+    ],
+  });
+}
diff --git a/src/app/api/oauth/gitlab/pat/route.js b/src/app/api/oauth/gitlab/pat/route.js
new file mode 100644
index 0000000..286ddc2
--- /dev/null
+++ b/src/app/api/oauth/gitlab/pat/route.js
@@ -0,0 +1,62 @@
+import { NextResponse } from "next/server";
+import { createProviderConnection } from "@/models";
+
+const GITLAB_DEFAULT_BASE = "https://gitlab.com";
+
+/**
+ * POST /api/oauth/gitlab/pat
+ * Authenticate GitLab Duo with a Personal Access Token (PAT)
+ */
+export async function POST(request) {
+  try {
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      return NextResponse.json({ error: "Invalid request body" }, { status: 400 });
+    }
+
+    const { token, baseUrl } = body;
+    if (!token?.trim()) {
+      return NextResponse.json({ error: "Personal Access Token is required" }, { status: 400 });
+    }
+
+    const base = (baseUrl?.trim() || GITLAB_DEFAULT_BASE).replace(/\/$/, "");
+
+    // Verify token by fetching current user
+    const userRes = await fetch(`${base}/api/v4/user`, {
+      headers: { "Private-Token": token.trim(), Accept: "application/json" },
+    });
+
+    if (!userRes.ok) {
+      const err = await userRes.text();
+      return NextResponse.json({ error: `GitLab token verification failed: ${err}` }, { status: 401 });
+    }
+
+    const user = await userRes.json();
+    const email = user.email || user.public_email || "";
+
+    await createProviderConnection({
+      provider: "gitlab",
+      authType: "oauth",
+      accessToken: token.trim(),
+      refreshToken: null,
+      expiresAt: null,
+      email,
+      displayName: user.name || user.username || email,
+      testStatus: "active",
+      providerSpecificData: {
+        username: user.username || "",
+        email,
+        name: user.name || "",
+        baseUrl: base,
+        authKind: "personal_access_token",
+      },
+    });
+
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.error("GitLab PAT auth error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/oauth/iflow/cookie/route.js b/src/app/api/oauth/iflow/cookie/route.js
new file mode 100644
index 0000000..fe0ea97
--- /dev/null
+++ b/src/app/api/oauth/iflow/cookie/route.js
@@ -0,0 +1,137 @@
+import { NextResponse } from "next/server";
+import { createProviderConnection } from "@/models";
+
+/**
+ * iFlow Cookie-Based Authentication
+ * POST /api/oauth/iflow/cookie
+ * Body: { cookie: "BXAuth=xxx; ..." }
+ */
+export async function POST(request) {
+  try {
+    const { cookie } = await request.json();
+
+    if (!cookie || typeof cookie !== "string") {
+      return NextResponse.json({ error: "Cookie is required" }, { status: 400 });
+    }
+
+    // Normalize cookie
+    const trimmed = cookie.trim();
+    if (!trimmed.includes("BXAuth=")) {
+      return NextResponse.json({ error: "Cookie must contain BXAuth field" }, { status: 400 });
+    }
+
+    let normalizedCookie = trimmed;
+    if (!normalizedCookie.endsWith(";")) {
+      normalizedCookie += ";";
+    }
+
+    // Step 1: GET API key info to get the name
+    const getResponse = await fetch("https://platform.iflow.cn/api/openapi/apikey", {
+      method: "GET",
+      headers: {
+        "Cookie": normalizedCookie,
+        "Accept": "application/json, text/plain, */*",
+        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+        "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+        "Accept-Encoding": "gzip, deflate, br",
+        "Connection": "keep-alive",
+        "Sec-Fetch-Dest": "empty",
+        "Sec-Fetch-Mode": "cors",
+        "Sec-Fetch-Site": "same-origin",
+      },
+    });
+
+    if (!getResponse.ok) {
+      const errorText = await getResponse.text();
+      return NextResponse.json(
+        { error: `Failed to fetch API key info: ${errorText}` },
+        { status: getResponse.status }
+      );
+    }
+
+    const getResult = await getResponse.json();
+    if (!getResult.success) {
+      return NextResponse.json(
+        { error: `API key fetch failed: ${getResult.message}` },
+        { status: 400 }
+      );
+    }
+
+    const keyData = getResult.data;
+    if (!keyData.name) {
+      return NextResponse.json({ error: "Missing name in API key info" }, { status: 400 });
+    }
+
+    // Step 2: POST to refresh API key
+    const postResponse = await fetch("https://platform.iflow.cn/api/openapi/apikey", {
+      method: "POST",
+      headers: {
+        "Cookie": normalizedCookie,
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/plain, */*",
+        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+        "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+        "Accept-Encoding": "gzip, deflate, br",
+        "Connection": "keep-alive",
+        "Origin": "https://platform.iflow.cn",
+        "Referer": "https://platform.iflow.cn/",
+      },
+      body: JSON.stringify({ name: keyData.name }),
+    });
+
+    if (!postResponse.ok) {
+      const errorText = await postResponse.text();
+      return NextResponse.json(
+        { error: `Failed to refresh API key: ${errorText}` },
+        { status: postResponse.status }
+      );
+    }
+
+    const postResult = await postResponse.json();
+    if (!postResult.success) {
+      return NextResponse.json(
+        { error: `API key refresh failed: ${postResult.message}` },
+        { status: 400 }
+      );
+    }
+
+    const refreshedKey = postResult.data;
+    if (!refreshedKey.apiKey) {
+      return NextResponse.json({ error: "Missing API key in response" }, { status: 400 });
+    }
+
+    // Extract only BXAuth from cookie
+    const bxAuthMatch = normalizedCookie.match(/BXAuth=([^;]+)/);
+    const bxAuth = bxAuthMatch ? bxAuthMatch[1] : "";
+    const cookieToSave = bxAuth ? `BXAuth=${bxAuth};` : "";
+
+    // Save to database
+    const connection = await createProviderConnection({
+      provider: "iflow",
+      authType: "cookie",
+      name: refreshedKey.name || keyData.name,
+      email: refreshedKey.name || keyData.name,
+      apiKey: refreshedKey.apiKey,
+      providerSpecificData: {
+        cookie: cookieToSave,
+        expireTime: refreshedKey.expireTime,
+      },
+      testStatus: "active",
+      isActive: true,
+    });
+
+    return NextResponse.json({
+      success: true,
+      connection: {
+        id: connection.id,
+        provider: connection.provider,
+        email: connection.email,
+        apiKey: refreshedKey.apiKey.substring(0, 10) + "...", // masked
+        expireTime: refreshedKey.expireTime,
+      },
+    });
+  } catch (error) {
+    console.error("iFlow cookie auth error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/oauth/kiro/api-key/route.js b/src/app/api/oauth/kiro/api-key/route.js
new file mode 100644
index 0000000..139df9b
--- /dev/null
+++ b/src/app/api/oauth/kiro/api-key/route.js
@@ -0,0 +1,67 @@
+import { NextResponse } from "next/server";
+import { KiroService } from "@/lib/oauth/services/kiro";
+import { createProviderConnection } from "@/models";
+
+/**
+ * POST /api/oauth/kiro/api-key
+ * Import a Kiro API key (headless auth). The key is a long-lived bearer
+ * credential — there is no refresh token. It is validated by listing
+ * CodeWhisperer profiles, then stored with authMethod="api_key".
+ */
+export async function POST(request) {
+  try {
+    const { apiKey, region } = await request.json();
+
+    if (!apiKey || typeof apiKey !== "string" || !apiKey.trim()) {
+      return NextResponse.json(
+        { error: "API key is required" },
+        { status: 400 }
+      );
+    }
+
+    const kiroService = new KiroService();
+
+    // Validate the key and resolve its profileArn via ListAvailableProfiles
+    const credential = await kiroService.validateApiKey(
+      apiKey,
+      region || "us-east-1"
+    );
+
+    // Extract email from JWT if the key happens to be a JWT (optional display)
+    const email = kiroService.extractEmailFromJWT(credential.accessToken);
+
+    // API keys never expire on a fixed schedule; persist a long horizon so the
+    // proactive refresh path (which requires a refreshToken anyway) is skipped.
+    const connection = await createProviderConnection({
+      provider: "kiro",
+      authType: "api_key",
+      accessToken: credential.accessToken,
+      refreshToken: null,
+      expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(),
+      email: email || null,
+      providerSpecificData: {
+        profileArn: credential.profileArn,
+        region: credential.region,
+        authMethod: "api_key",
+        provider: "API Key",
+      },
+      testStatus: "active",
+    });
+
+    return NextResponse.json({
+      success: true,
+      connection: {
+        id: connection.id,
+        provider: connection.provider,
+        email: connection.email,
+      },
+    });
+  } catch (error) {
+    console.log("Kiro API key import error:", error);
+    // Do not reflect upstream response body to the client (SSRF hardening)
+    return NextResponse.json(
+      { error: "API key validation failed" },
+      { status: 500 }
+    );
+  }
+}
diff --git a/src/app/api/oauth/kiro/auto-import/route.js b/src/app/api/oauth/kiro/auto-import/route.js
new file mode 100644
index 0000000..0d28ea6
--- /dev/null
+++ b/src/app/api/oauth/kiro/auto-import/route.js
@@ -0,0 +1,132 @@
+import { NextResponse } from "next/server";
+import { readFile, readdir } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+
+/**
+ * GET /api/oauth/kiro/auto-import
+ * Auto-detect and extract Kiro refresh token from AWS SSO cache.
+ * For IDC (organization) tokens, also resolves clientId/clientSecret from the
+ * linked client registration file so token refresh works.
+ */
+export async function GET() {
+  try {
+    const cachePath = join(homedir(), ".aws/sso/cache");
+
+    let files;
+    try {
+      files = await readdir(cachePath);
+    } catch (error) {
+      return NextResponse.json({
+        found: false,
+        error: "AWS SSO cache not found. Please login to Kiro IDE first.",
+      });
+    }
+
+    let refreshToken = null;
+    let foundFile = null;
+    let tokenData = null;
+
+    // First try kiro-auth-token.json
+    const kiroTokenFile = "kiro-auth-token.json";
+    if (files.includes(kiroTokenFile)) {
+      try {
+        const content = await readFile(join(cachePath, kiroTokenFile), "utf-8");
+        const data = JSON.parse(content);
+        if (data.refreshToken && data.refreshToken.startsWith("aorAAAAAG")) {
+          refreshToken = data.refreshToken;
+          foundFile = kiroTokenFile;
+          tokenData = data;
+        }
+      } catch (error) {
+        // Continue to search other files
+      }
+    }
+
+    // If not found, search all .json files
+    if (!refreshToken) {
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        try {
+          const content = await readFile(join(cachePath, file), "utf-8");
+          const data = JSON.parse(content);
+          if (data.refreshToken && data.refreshToken.startsWith("aorAAAAAG")) {
+            refreshToken = data.refreshToken;
+            foundFile = file;
+            tokenData = data;
+            break;
+          }
+        } catch (error) {
+          continue;
+        }
+      }
+    }
+
+    if (!refreshToken) {
+      return NextResponse.json({
+        found: false,
+        error: "Kiro token not found in AWS SSO cache. Please login to Kiro IDE first.",
+      });
+    }
+
+    // For IDC/organization tokens, resolve clientId and clientSecret from
+    // the linked client registration file (referenced by clientIdHash).
+    let clientId = null;
+    let clientSecret = null;
+    const region = tokenData?.region || null;
+    const authMethod = tokenData?.authMethod || null;
+
+    if (tokenData?.clientIdHash) {
+      const clientFile = `${tokenData.clientIdHash}.json`;
+      try {
+        const clientContent = await readFile(join(cachePath, clientFile), "utf-8");
+        const clientData = JSON.parse(clientContent);
+        if (clientData.clientId && clientData.clientSecret) {
+          clientId = clientData.clientId;
+          clientSecret = clientData.clientSecret;
+        }
+      } catch (error) {
+        // Client registration file not found - continue without it
+      }
+    }
+
+    // Read profileArn from Kiro IDE's profile.json.
+    // Important: the runtime gateway requires us-east-1 in the ARN regardless
+    // of the IDC region, so we normalize the region in the ARN to us-east-1.
+    let profileArn = null;
+    const kiroProfilePaths = [
+      join(process.env.APPDATA || join(homedir(), "AppData", "Roaming"), "Kiro", "User", "globalStorage", "kiro.kiroagent", "profile.json"),
+      join(homedir(), ".config", "Kiro", "User", "globalStorage", "kiro.kiroagent", "profile.json"),
+    ];
+    for (const profilePath of kiroProfilePaths) {
+      try {
+        const profileContent = await readFile(profilePath, "utf-8");
+        const profileData = JSON.parse(profileContent);
+        if (profileData.arn) {
+          // Normalize region to us-east-1 for the runtime gateway
+          profileArn = profileData.arn.replace(/arn:aws:codewhisperer:[^:]+:/, "arn:aws:codewhisperer:us-east-1:");
+          break;
+        }
+      } catch (error) {
+        continue;
+      }
+    }
+
+    return NextResponse.json({
+      found: true,
+      refreshToken,
+      source: foundFile,
+      clientId,
+      clientSecret,
+      region,
+      authMethod,
+      profileArn,
+    });
+  } catch (error) {
+    console.log("Kiro auto-import error:", error);
+    return NextResponse.json(
+      { found: false, error: error.message },
+      { status: 500 }
+    );
+  }
+}
diff --git a/src/app/api/oauth/kiro/import-cli-proxy/route.js b/src/app/api/oauth/kiro/import-cli-proxy/route.js
new file mode 100644
index 0000000..d71d6a7
--- /dev/null
+++ b/src/app/api/oauth/kiro/import-cli-proxy/route.js
@@ -0,0 +1,40 @@
+import { NextResponse } from "next/server";
+import { createProviderConnection } from "@/models";
+import { normalizeKiroExternalIdpAuth } from "@/lib/oauth/kiroExternalIdp";
+
+/**
+ * POST /api/oauth/kiro/import-cli-proxy
+ * Import Kiro CLIProxyAPI auth JSON for Microsoft external_idp accounts.
+ */
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const rawAuth = body?.cliProxyAuth ?? body?.auth ?? body?.json ?? body;
+    const tokenData = normalizeKiroExternalIdpAuth(rawAuth);
+
+    const connection = await createProviderConnection({
+      provider: "kiro",
+      authType: "oauth",
+      accessToken: tokenData.accessToken,
+      refreshToken: tokenData.refreshToken,
+      expiresAt: tokenData.expiresAt,
+      email: tokenData.email || null,
+      providerSpecificData: tokenData.providerSpecificData,
+      testStatus: "active",
+    });
+
+    return NextResponse.json({
+      success: true,
+      connection: {
+        id: connection.id,
+        provider: connection.provider,
+        email: connection.email,
+      },
+    });
+  } catch (error) {
+    return NextResponse.json(
+      { error: error?.message || "CLIProxyAPI import failed" },
+      { status: 400 }
+    );
+  }
+}
diff --git a/src/app/api/oauth/kiro/import/route.js b/src/app/api/oauth/kiro/import/route.js
new file mode 100644
index 0000000..4638341
--- /dev/null
+++ b/src/app/api/oauth/kiro/import/route.js
@@ -0,0 +1,66 @@
+import { NextResponse } from "next/server";
+import { KiroService } from "@/lib/oauth/services/kiro";
+import { createProviderConnection } from "@/models";
+
+/**
+ * POST /api/oauth/kiro/import
+ * Import and validate refresh token from Kiro IDE.
+ * For IDC (organization) tokens, accepts clientId/clientSecret/region so the
+ * token can be refreshed via the regional AWS OIDC endpoint.
+ */
+export async function POST(request) {
+  try {
+    const { refreshToken, clientId, clientSecret, region, authMethod, profileArn } = await request.json();
+
+    if (!refreshToken || typeof refreshToken !== "string") {
+      return NextResponse.json(
+        { error: "Refresh token is required" },
+        { status: 400 }
+      );
+    }
+
+    const kiroService = new KiroService();
+    const isIdc = !!(clientId && clientSecret);
+
+    // For IDC tokens, refresh via the regional OIDC endpoint with client credentials.
+    // For social/builder-id tokens, use the standard social refresh endpoint.
+    const providerSpecificData = isIdc
+      ? { clientId, clientSecret, region: region || "us-east-1", authMethod: "idc" }
+      : {};
+
+    const tokenData = await kiroService.refreshToken(refreshToken.trim(), providerSpecificData);
+
+    const email = kiroService.extractEmailFromJWT(tokenData.accessToken);
+    const resolvedAuthMethod = isIdc ? "idc" : "imported";
+    const providerLabel = isIdc ? "Enterprise" : "Imported";
+    const resolvedProfileArn = profileArn || tokenData.profileArn || null;
+
+    const connection = await createProviderConnection({
+      provider: "kiro",
+      authType: "oauth",
+      accessToken: tokenData.accessToken,
+      refreshToken: tokenData.refreshToken || refreshToken.trim(),
+      expiresAt: new Date(Date.now() + (tokenData.expiresIn || 3600) * 1000).toISOString(),
+      email: email || null,
+      providerSpecificData: {
+        profileArn: resolvedProfileArn,
+        authMethod: resolvedAuthMethod,
+        provider: providerLabel,
+        ...(isIdc ? { clientId, clientSecret, region: region || "us-east-1" } : {}),
+      },
+      testStatus: "active",
+    });
+
+    return NextResponse.json({
+      success: true,
+      connection: {
+        id: connection.id,
+        provider: connection.provider,
+        email: connection.email,
+      },
+    });
+  } catch (error) {
+    console.log("Kiro import token error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/oauth/kiro/social-authorize/route.js b/src/app/api/oauth/kiro/social-authorize/route.js
new file mode 100644
index 0000000..e5e1281
--- /dev/null
+++ b/src/app/api/oauth/kiro/social-authorize/route.js
@@ -0,0 +1,43 @@
+import { NextResponse } from "next/server";
+import { generatePKCE } from "@/lib/oauth/utils/pkce";
+import { KiroService } from "@/lib/oauth/services/kiro";
+
+/**
+ * GET /api/oauth/kiro/social-authorize
+ * Generate Google/GitHub social login URL for manual callback flow
+ * Uses kiro:// custom protocol as required by AWS Cognito
+ */
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const provider = searchParams.get("provider"); // "google" or "github"
+
+    if (!provider || !["google", "github"].includes(provider)) {
+      return NextResponse.json(
+        { error: "Invalid provider. Use 'google' or 'github'" },
+        { status: 400 }
+      );
+    }
+
+    // Generate PKCE for social auth
+    const { codeVerifier, codeChallenge, state } = generatePKCE();
+
+    const kiroService = new KiroService();
+    const authUrl = kiroService.buildSocialLoginUrl(
+      provider,
+      codeChallenge,
+      state
+    );
+
+    return NextResponse.json({
+      authUrl,
+      state,
+      codeVerifier,
+      codeChallenge,
+      provider,
+    });
+  } catch (error) {
+    console.log("Kiro social authorize error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/oauth/kiro/social-exchange/route.js b/src/app/api/oauth/kiro/social-exchange/route.js
new file mode 100644
index 0000000..a99f276
--- /dev/null
+++ b/src/app/api/oauth/kiro/social-exchange/route.js
@@ -0,0 +1,67 @@
+import { NextResponse } from "next/server";
+import { KiroService } from "@/lib/oauth/services/kiro";
+import { createProviderConnection } from "@/models";
+
+/**
+ * POST /api/oauth/kiro/social-exchange
+ * Exchange authorization code for tokens (Google/GitHub social login)
+ * Callback URL will be in format: kiro://kiro.kiroAgent/authenticate-success?code=XXX&state=YYY
+ */
+export async function POST(request) {
+  try {
+    const { code, codeVerifier, provider } = await request.json();
+
+    if (!code || !codeVerifier) {
+      return NextResponse.json(
+        { error: "Missing required fields" },
+        { status: 400 }
+      );
+    }
+
+    if (!provider || !["google", "github"].includes(provider)) {
+      return NextResponse.json(
+        { error: "Invalid provider" },
+        { status: 400 }
+      );
+    }
+
+    const kiroService = new KiroService();
+
+    // Exchange code for tokens (redirect_uri handled internally)
+    const tokenData = await kiroService.exchangeSocialCode(
+      code,
+      codeVerifier
+    );
+
+    // Extract email from JWT if available
+    const email = kiroService.extractEmailFromJWT(tokenData.accessToken);
+
+    // Save to database
+    const connection = await createProviderConnection({
+      provider: "kiro",
+      authType: "oauth",
+      accessToken: tokenData.accessToken,
+      refreshToken: tokenData.refreshToken,
+      expiresAt: new Date(Date.now() + tokenData.expiresIn * 1000).toISOString(),
+      email: email || null,
+      providerSpecificData: {
+        profileArn: tokenData.profileArn,
+        authMethod: provider, // "google" or "github"
+        provider: provider.charAt(0).toUpperCase() + provider.slice(1),
+      },
+      testStatus: "active",
+    });
+
+    return NextResponse.json({
+      success: true,
+      connection: {
+        id: connection.id,
+        provider: connection.provider,
+        email: connection.email,
+      },
+    });
+  } catch (error) {
+    console.log("Kiro social exchange error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/pricing/route.js b/src/app/api/pricing/route.js
new file mode 100644
index 0000000..18a8584
--- /dev/null
+++ b/src/app/api/pricing/route.js
@@ -0,0 +1,134 @@
+import { NextResponse } from "next/server";
+import { getPricing, updatePricing, resetPricing, resetAllPricing } from "@/lib/localDb.js";
+import { getDefaultPricing } from "open-sse/providers/pricing.js";
+
+/**
+ * GET /api/pricing
+ * Get current pricing configuration (merged user + defaults)
+ */
+export async function GET() {
+  try {
+    const pricing = await getPricing();
+    return NextResponse.json(pricing);
+  } catch (error) {
+    console.error("Error fetching pricing:", error);
+    return NextResponse.json(
+      { error: "Failed to fetch pricing" },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * PATCH /api/pricing
+ * Update pricing configuration
+ * Body: { provider: { model: { input: number, output: number, cached: number, ... } } }
+ */
+export async function PATCH(request) {
+  try {
+    const body = await request.json();
+
+    // Validate body structure
+    if (typeof body !== "object" || body === null) {
+      return NextResponse.json(
+        { error: "Invalid pricing data format" },
+        { status: 400 }
+      );
+    }
+
+    // Validate pricing structure
+    for (const [provider, models] of Object.entries(body)) {
+      if (typeof models !== "object" || models === null) {
+        return NextResponse.json(
+          { error: `Invalid pricing for provider: ${provider}` },
+          { status: 400 }
+        );
+      }
+
+      for (const [model, pricing] of Object.entries(models)) {
+        if (typeof pricing !== "object" || pricing === null) {
+          return NextResponse.json(
+            { error: `Invalid pricing for model: ${provider}/${model}` },
+            { status: 400 }
+          );
+        }
+
+        // Validate pricing fields
+        const validFields = ["input", "output", "cached", "reasoning", "cache_creation"];
+        for (const [key, value] of Object.entries(pricing)) {
+          if (!validFields.includes(key)) {
+            return NextResponse.json(
+              { error: `Invalid pricing field: ${key} for ${provider}/${model}` },
+              { status: 400 }
+            );
+          }
+          if (typeof value !== "number" || isNaN(value) || value < 0) {
+            return NextResponse.json(
+              { error: `Invalid pricing value for ${key} in ${provider}/${model}: must be non-negative number` },
+              { status: 400 }
+            );
+          }
+        }
+      }
+    }
+
+    const updatedPricing = await updatePricing(body);
+    return NextResponse.json(updatedPricing);
+  } catch (error) {
+    console.error("Error updating pricing:", error);
+    return NextResponse.json(
+      { error: "Failed to update pricing" },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * DELETE /api/pricing
+ * Reset pricing to defaults
+ * Query params: ?provider=xxx&model=yyy (optional)
+ */
+export async function DELETE(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const provider = searchParams.get("provider");
+    const model = searchParams.get("model");
+
+    if (provider && model) {
+      // Reset specific model
+      await resetPricing(provider, model);
+    } else if (provider) {
+      // Reset entire provider
+      await resetPricing(provider);
+    } else {
+      // Reset all pricing
+      await resetAllPricing();
+    }
+
+    const pricing = await getPricing();
+    return NextResponse.json(pricing);
+  } catch (error) {
+    console.error("Error resetting pricing:", error);
+    return NextResponse.json(
+      { error: "Failed to reset pricing" },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * GET /api/pricing/defaults
+ * Get default pricing configuration
+ */
+export async function GET_DEFAULTS() {
+  try {
+    const defaultPricing = getDefaultPricing();
+    return NextResponse.json(defaultPricing);
+  } catch (error) {
+    console.error("Error fetching default pricing:", error);
+    return NextResponse.json(
+      { error: "Failed to fetch default pricing" },
+      { status: 500 }
+    );
+  }
+}
\ No newline at end of file
diff --git a/src/app/api/provider-nodes/[id]/route.js b/src/app/api/provider-nodes/[id]/route.js
new file mode 100644
index 0000000..a758d0a
--- /dev/null
+++ b/src/app/api/provider-nodes/[id]/route.js
@@ -0,0 +1,101 @@
+import { NextResponse } from "next/server";
+import { deleteProviderConnectionsByProvider, deleteProviderNode, getProviderConnections, getProviderNodeById, updateProviderConnection, updateProviderNode } from "@/models";
+
+// PUT /api/provider-nodes/[id] - Update provider node
+export async function PUT(request, { params }) {
+  try {
+    const { id } = await params;
+    const body = await request.json();
+    const { name, prefix, apiType, baseUrl } = body;
+    const node = await getProviderNodeById(id);
+
+    if (!node) {
+      return NextResponse.json({ error: "Provider node not found" }, { status: 404 });
+    }
+
+    if (!name?.trim()) {
+      return NextResponse.json({ error: "Name is required" }, { status: 400 });
+    }
+
+    if (!prefix?.trim()) {
+      return NextResponse.json({ error: "Prefix is required" }, { status: 400 });
+    }
+
+    // Only validate apiType for OpenAI Compatible nodes
+    if (node.type === "openai-compatible" && (!apiType || !["chat", "responses"].includes(apiType))) {
+      return NextResponse.json({ error: "Invalid OpenAI compatible API type" }, { status: 400 });
+    }
+
+    if (!baseUrl?.trim()) {
+      return NextResponse.json({ error: "Base URL is required" }, { status: 400 });
+    }
+
+    let sanitizedBaseUrl = baseUrl.trim();
+    
+    // Sanitize Base URL for Anthropic Compatible
+    if (node.type === "anthropic-compatible") {
+      sanitizedBaseUrl = sanitizedBaseUrl.replace(/\/$/, "");
+      if (sanitizedBaseUrl.endsWith("/messages")) {
+        sanitizedBaseUrl = sanitizedBaseUrl.slice(0, -9); // remove /messages
+      }
+    }
+
+    // Sanitize Base URL for Custom Embedding (strip trailing slash and /embeddings)
+    if (node.type === "custom-embedding") {
+      sanitizedBaseUrl = sanitizedBaseUrl.replace(/\/$/, "");
+      if (sanitizedBaseUrl.endsWith("/embeddings")) {
+        sanitizedBaseUrl = sanitizedBaseUrl.slice(0, -"/embeddings".length);
+      }
+    }
+
+    const updates = {
+      name: name.trim(),
+      prefix: prefix.trim(),
+      baseUrl: sanitizedBaseUrl,
+    };
+
+    if (node.type === "openai-compatible") {
+      updates.apiType = apiType;
+    }
+
+    const updated = await updateProviderNode(id, updates);
+
+    const connections = await getProviderConnections({ provider: id });
+    await Promise.all(connections.map((connection) => (
+      updateProviderConnection(connection.id, {
+        providerSpecificData: {
+          ...(connection.providerSpecificData || {}),
+          prefix: prefix.trim(),
+          apiType: node.type === "openai-compatible" ? apiType : undefined,
+          baseUrl: sanitizedBaseUrl,
+          nodeName: updated.name,
+        }
+      })
+    )));
+
+    return NextResponse.json({ node: updated });
+  } catch (error) {
+    console.log("Error updating provider node:", error);
+    return NextResponse.json({ error: "Failed to update provider node" }, { status: 500 });
+  }
+}
+
+// DELETE /api/provider-nodes/[id] - Delete provider node and its connections
+export async function DELETE(request, { params }) {
+  try {
+    const { id } = await params;
+    const node = await getProviderNodeById(id);
+
+    if (!node) {
+      return NextResponse.json({ error: "Provider node not found" }, { status: 404 });
+    }
+
+    await deleteProviderConnectionsByProvider(id);
+    await deleteProviderNode(id);
+
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.log("Error deleting provider node:", error);
+    return NextResponse.json({ error: "Failed to delete provider node" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/provider-nodes/route.js b/src/app/api/provider-nodes/route.js
new file mode 100644
index 0000000..92c8919
--- /dev/null
+++ b/src/app/api/provider-nodes/route.js
@@ -0,0 +1,104 @@
+import { NextResponse } from "next/server";
+import { createProviderNode, getProviderNodes } from "@/models";
+import { OPENAI_COMPATIBLE_PREFIX, ANTHROPIC_COMPATIBLE_PREFIX, CUSTOM_EMBEDDING_PREFIX } from "@/shared/constants/providers";
+import { generateId } from "@/shared/utils";
+
+export const dynamic = "force-dynamic";
+
+const OPENAI_COMPATIBLE_DEFAULTS = {
+  baseUrl: "https://api.openai.com/v1",
+};
+
+const ANTHROPIC_COMPATIBLE_DEFAULTS = {
+  baseUrl: "https://api.anthropic.com/v1",
+};
+
+const CUSTOM_EMBEDDING_DEFAULTS = {
+  baseUrl: "https://api.openai.com/v1",
+};
+
+// GET /api/provider-nodes - List all provider nodes
+export async function GET() {
+  try {
+    const nodes = await getProviderNodes();
+    return NextResponse.json({ nodes });
+  } catch (error) {
+    console.log("Error fetching provider nodes:", error);
+    return NextResponse.json({ error: "Failed to fetch provider nodes" }, { status: 500 });
+  }
+}
+
+// POST /api/provider-nodes - Create provider node
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const { name, prefix, apiType, baseUrl, type } = body;
+
+    if (!name?.trim()) {
+      return NextResponse.json({ error: "Name is required" }, { status: 400 });
+    }
+
+    if (!prefix?.trim()) {
+      return NextResponse.json({ error: "Prefix is required" }, { status: 400 });
+    }
+
+    // Determine type
+    const nodeType = type || "openai-compatible";
+
+    if (nodeType === "openai-compatible") {
+      if (!apiType || !["chat", "responses"].includes(apiType)) {
+        return NextResponse.json({ error: "Invalid OpenAI compatible API type" }, { status: 400 });
+      }
+
+      const node = await createProviderNode({
+        id: `${OPENAI_COMPATIBLE_PREFIX}${apiType}-${generateId()}`,
+        type: "openai-compatible",
+        prefix: prefix.trim(),
+        apiType,
+        baseUrl: (baseUrl || OPENAI_COMPATIBLE_DEFAULTS.baseUrl).trim(),
+        name: name.trim(),
+      });
+      return NextResponse.json({ node }, { status: 201 });
+    }
+
+    if (nodeType === "custom-embedding") {
+      // Strip trailing slash and /embeddings if user pasted full endpoint
+      let sanitizedBaseUrl = (baseUrl || CUSTOM_EMBEDDING_DEFAULTS.baseUrl).trim().replace(/\/$/, "");
+      if (sanitizedBaseUrl.endsWith("/embeddings")) {
+        sanitizedBaseUrl = sanitizedBaseUrl.slice(0, -"/embeddings".length);
+      }
+
+      const node = await createProviderNode({
+        id: `${CUSTOM_EMBEDDING_PREFIX}${generateId()}`,
+        type: "custom-embedding",
+        prefix: prefix.trim(),
+        baseUrl: sanitizedBaseUrl,
+        name: name.trim(),
+      });
+      return NextResponse.json({ node }, { status: 201 });
+    }
+
+    if (nodeType === "anthropic-compatible") {
+      // Sanitize Base URL: remove trailing slash, and remove trailing /messages if user added it
+      // This prevents double-appending /messages at runtime
+      let sanitizedBaseUrl = (baseUrl || ANTHROPIC_COMPATIBLE_DEFAULTS.baseUrl).trim().replace(/\/$/, "");
+      if (sanitizedBaseUrl.endsWith("/messages")) {
+        sanitizedBaseUrl = sanitizedBaseUrl.slice(0, -9); // remove /messages
+      }
+
+      const node = await createProviderNode({
+        id: `${ANTHROPIC_COMPATIBLE_PREFIX}${generateId()}`,
+        type: "anthropic-compatible",
+        prefix: prefix.trim(),
+        baseUrl: sanitizedBaseUrl,
+        name: name.trim(),
+      });
+      return NextResponse.json({ node }, { status: 201 });
+    }
+
+    return NextResponse.json({ error: "Invalid provider node type" }, { status: 400 });
+  } catch (error) {
+    console.log("Error creating provider node:", error);
+    return NextResponse.json({ error: "Failed to create provider node" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/provider-nodes/validate/route.js b/src/app/api/provider-nodes/validate/route.js
new file mode 100644
index 0000000..4148ab4
--- /dev/null
+++ b/src/app/api/provider-nodes/validate/route.js
@@ -0,0 +1,212 @@
+import { NextResponse } from "next/server";
+import { assertPublicUrl } from "@/shared/utils/ssrfGuard.js";
+import { isLocalRequest } from "@/dashboardGuard";
+
+// Fetch with timeout wrapper
+const fetchWithTimeout = (url, options, timeout = 10000) => {
+  return Promise.race([
+    fetch(url, options),
+    new Promise((_, reject) => 
+      setTimeout(() => reject(new Error("Request timeout")), timeout)
+    )
+  ]);
+};
+
+// Validate URL format
+const isValidUrl = (url) => {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// Parse error details for user-friendly messages
+const getErrorMessage = (error) => {
+  if (error.cause?.code === "ECONNREFUSED") return "Connection refused - provider node offline or unreachable";
+  if (error.cause?.code === "ENOTFOUND") return "DNS lookup failed - invalid domain or network issue";
+  if (error.cause?.code === "ETIMEDOUT") return "Connection timeout - provider node too slow";
+  if (error.message.includes("timeout")) return "Request timeout (>10s) - provider node not responding";
+  if (error.cause?.code === "CERT_HAS_EXPIRED") return "SSL certificate expired";
+  if (error.cause?.code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE") return "SSL certificate verification failed";
+  if (error.cause?.code) return `Network error: ${error.cause.code}`;
+  return "Network connection failed - check URL and network connectivity";
+};
+
+// Get status-specific error message for /models endpoint
+const getModelsErrorMessage = (status) => {
+  if (status === 401 || status === 403) return "API key unauthorized";
+  if (status === 404) return "/models endpoint not found - try chat validation with model ID";
+  if (status >= 500) return "Server error - try again later";
+  return `Unexpected response (${status})`;
+};
+
+// Get status-specific error message for /chat/completions endpoint
+const getChatErrorMessage = (status) => {
+  if (status === 401 || status === 403) return "API key unauthorized";
+  if (status === 400) return "Invalid model or bad request";
+  if (status === 404) return "Chat endpoint not found";
+  if (status >= 500) return "Server error - try again later";
+  return `Chat request failed (${status})`;
+};
+
+// POST /api/provider-nodes/validate - Validate API key against base URL
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const { baseUrl, apiKey, type, modelId } = body;
+
+    if (!baseUrl || !apiKey) {
+      return NextResponse.json({ error: "Base URL and API key required" }, { status: 400 });
+    }
+
+    // Validate URL format
+    if (!isValidUrl(baseUrl)) {
+      return NextResponse.json({ error: "Invalid URL format" }, { status: 400 });
+    }
+
+    // SSRF guard for remote callers; local host keeps self-hosted nodes (e.g. ollama-local)
+    if (!isLocalRequest(request)) {
+      try {
+        assertPublicUrl(baseUrl);
+      } catch {
+        return NextResponse.json({ error: "URL not allowed" }, { status: 400 });
+      }
+    }
+
+    // Custom Embedding Validation - test POST /embeddings directly
+    if (type === "custom-embedding") {
+      const normalizedBase = baseUrl.trim().replace(/\/$/, "");
+      if (!modelId?.trim()) {
+        return NextResponse.json({ valid: false, error: "Model ID required for embedding validation" });
+      }
+      const embedRes = await fetchWithTimeout(`${normalizedBase}/embeddings`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ model: modelId.trim(), input: "ping" })
+      });
+      if (embedRes.ok) {
+        const data = await embedRes.json().catch(() => null);
+        const dims = Array.isArray(data?.data?.[0]?.embedding) ? data.data[0].embedding.length : null;
+        return NextResponse.json({ valid: true, method: "embeddings", dimensions: dims });
+      }
+      if (embedRes.status === 401 || embedRes.status === 403) {
+        return NextResponse.json({ valid: false, error: "API key unauthorized" });
+      }
+      const errBody = await embedRes.text().catch(() => "");
+      return NextResponse.json({
+        valid: false,
+        error: `Embeddings request failed (${embedRes.status})${errBody ? `: ${errBody.slice(0, 200)}` : ""}`,
+        method: "embeddings"
+      });
+    }
+
+    // Anthropic Compatible Validation
+    if (type === "anthropic-compatible") {
+      let normalizedBase = baseUrl.trim().replace(/\/$/, "");
+      if (normalizedBase.endsWith("/messages")) {
+        normalizedBase = normalizedBase.slice(0, -9);
+      }
+
+      const modelsUrl = `${normalizedBase}/models`;
+      const res = await fetchWithTimeout(modelsUrl, {
+        method: "GET",
+        headers: {
+          "x-api-key": apiKey,
+          "anthropic-version": "2023-06-01",
+          "Authorization": `Bearer ${apiKey}`
+        }
+      });
+
+      if (res.ok) return NextResponse.json({ valid: true });
+
+      // Auth errors - no point trying chat fallback
+      if (res.status === 401 || res.status === 403) {
+        return NextResponse.json({ valid: false, error: "API key unauthorized" });
+      }
+
+      // Fallback: try chat/completions if modelId provided
+      if (modelId) {
+        const chatRes = await fetchWithTimeout(`${normalizedBase}/chat/completions`, {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            "x-api-key": apiKey,
+            "anthropic-version": "2023-06-01"
+          },
+          body: JSON.stringify({
+            model: modelId,
+            messages: [{ role: "user", content: "ping" }],
+            max_tokens: 1
+          })
+        });
+        if (chatRes.ok) {
+          return NextResponse.json({ valid: true, method: "chat" });
+        }
+        return NextResponse.json({
+          valid: false,
+          error: getChatErrorMessage(chatRes.status),
+          method: "chat"
+        });
+      }
+
+      return NextResponse.json({ valid: false, error: getModelsErrorMessage(res.status) });
+    }
+
+    // OpenAI Compatible Validation (Default)
+    const modelsUrl = `${baseUrl.replace(/\/$/, "")}/models`;
+    const res = await fetchWithTimeout(modelsUrl, {
+      headers: { "Authorization": `Bearer ${apiKey}` },
+    });
+
+    if (res.ok) return NextResponse.json({ valid: true });
+
+    // Auth errors - no point trying chat fallback
+    if (res.status === 401 || res.status === 403) {
+      return NextResponse.json({ valid: false, error: "API key unauthorized" });
+    }
+
+    // Fallback: try chat/completions if modelId provided
+    if (modelId) {
+      const chatRes = await fetchWithTimeout(`${baseUrl.replace(/\/$/, "")}/chat/completions`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          model: modelId,
+          messages: [{ role: "user", content: "ping" }],
+          max_tokens: 1
+        })
+      });
+      if (chatRes.ok) {
+        return NextResponse.json({ valid: true, method: "chat" });
+      }
+      return NextResponse.json({
+        valid: false,
+        error: getChatErrorMessage(chatRes.status),
+        method: "chat"
+      });
+    }
+
+    return NextResponse.json({ valid: false, error: getModelsErrorMessage(res.status) });
+  } catch (error) {
+    const errorMessage = getErrorMessage(error);
+    console.error("Error validating provider node:", {
+      message: error.message,
+      cause: error.cause,
+      code: error.cause?.code,
+      userMessage: errorMessage
+    });
+    return NextResponse.json({ 
+      valid: false,
+      error: errorMessage 
+    }, { status: 500 });
+  }
+}
diff --git a/src/app/api/providers/[id]/models/route.js b/src/app/api/providers/[id]/models/route.js
new file mode 100644
index 0000000..52f0291
--- /dev/null
+++ b/src/app/api/providers/[id]/models/route.js
@@ -0,0 +1,552 @@
+import { NextResponse } from "next/server";
+import { getProviderConnectionById } from "@/models";
+import { isOpenAICompatibleProvider, isAnthropicCompatibleProvider } from "@/shared/constants/providers";
+import { GEMINI_CONFIG } from "@/lib/oauth/constants/oauth";
+import { refreshGoogleToken, updateProviderCredentials } from "@/sse/services/tokenRefresh";
+import { resolveOllamaLocalHost } from "open-sse/config/providers.js";
+import { getModelsByProviderId } from "open-sse/config/providerModels.js";
+import { resolveKiroModels } from "open-sse/services/kiroModels.js";
+import { resolveKimchiModels } from "open-sse/services/kimchiModels.js";
+import { resolveQoderModels } from "open-sse/services/qoderModels.js";
+
+const GEMINI_CLI_MODELS_URL = "https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels";
+
+const parseOpenAIStyleModels = (data) => {
+  if (Array.isArray(data)) return data;
+  return data?.data || data?.models || data?.results || [];
+};
+
+const parseGeminiCliModels = (data) => {
+  if (Array.isArray(data?.models)) {
+    return data.models
+      .map((item) => {
+        const id = item?.id || item?.model || item?.name;
+        if (!id) return null;
+        return { id, name: item?.displayName || item?.name || id };
+      })
+      .filter(Boolean);
+  }
+
+  if (data?.models && typeof data.models === "object") {
+    return Object.entries(data.models)
+      .filter(([, info]) => !info?.isInternal)
+      .map(([id, info]) => ({
+        id,
+        name: info?.displayName || info?.name || id,
+      }));
+  }
+
+  return [];
+};
+
+const appendCodexReviewModels = (models) => models.flatMap((model) => {
+  const id = model?.id || model?.slug || model?.model || model?.name;
+  if (!id) return [];
+  const name = model?.display_name || model?.displayName || model?.name || id;
+  const normalized = { ...model, id, name };
+  const isChatModel = (model?.type || "llm") !== "image" && !id.toLowerCase().includes("embed");
+  if (!isChatModel || id.endsWith("-review")) return [normalized];
+  return [
+    normalized,
+    {
+      ...normalized,
+      id: `${id}-review`,
+      name: `${name} Review`,
+      upstreamModelId: id,
+      quotaFamily: "review",
+    },
+  ];
+});
+
+const parseCodexModels = (data) => appendCodexReviewModels(parseOpenAIStyleModels(data));
+
+const createOpenAIModelsConfig = (url) => ({
+  url,
+  method: "GET",
+  headers: { "Content-Type": "application/json" },
+  authHeader: "Authorization",
+  authPrefix: "Bearer ",
+  parseResponse: parseOpenAIStyleModels
+});
+
+const resolveQwenModelsUrl = (connection) => {
+  const fallback = "https://portal.qwen.ai/v1/models";
+  const raw = connection?.providerSpecificData?.resourceUrl;
+  if (!raw || typeof raw !== "string") return fallback;
+  const value = raw.trim();
+  if (!value) return fallback;
+  if (value.startsWith("http://") || value.startsWith("https://")) {
+    return `${value.replace(/\/$/, "")}/models`;
+  }
+  return `https://${value.replace(/\/$/, "")}/v1/models`;
+};
+
+const getStaticProviderModels = (providerId) =>
+  getModelsByProviderId(providerId).map((model) => ({
+    ...model,
+    id: model.id,
+    name: model.name || model.id,
+  }));
+
+// Generic custom resolver for OAuth providers that need refresh-on-401 + token persist.
+// Receives a `fetchFn(token)` and returns parsed models or throws.
+const buildOAuthResolver = ({ refreshFn, fetchFn, parseFn, errorLabel }) => async (connection) => {
+  const { accessToken, refreshToken } = connection;
+  if (!accessToken) {
+    return { error: "No valid token found", status: 401 };
+  }
+  let warning;
+  try {
+    let response = await fetchFn(accessToken, connection);
+    if (!response.ok && (response.status === 401 || response.status === 403) && refreshToken) {
+      const refreshed = await refreshFn(connection);
+      if (refreshed?.accessToken) {
+        await updateProviderCredentials(connection.id, {
+          accessToken: refreshed.accessToken,
+          refreshToken: refreshed.refreshToken || refreshToken,
+          expiresIn: refreshed.expiresIn,
+        });
+        connection.accessToken = refreshed.accessToken;
+        if (refreshed.refreshToken) connection.refreshToken = refreshed.refreshToken;
+        response = await fetchFn(refreshed.accessToken, connection);
+      }
+    }
+    if (response.ok) {
+      const data = await response.json();
+      const models = parseFn(data);
+      if (models.length > 0) return { models };
+    } else {
+      const errorText = await response.text();
+      warning = `${errorLabel}: ${response.status} ${errorText}`;
+      console.log(`${errorLabel} (falling back to static):`, errorText);
+    }
+  } catch (error) {
+    warning = `${errorLabel}: ${error.message}`;
+    console.log(`${errorLabel} (falling back to static):`, error.message);
+  }
+  return { models: [], warning };
+};
+
+// Provider models endpoints configuration
+const PROVIDER_MODELS_CONFIG = {
+  claude: {
+    url: "https://api.anthropic.com/v1/models",
+    method: "GET",
+    headers: {
+      "Anthropic-Version": "2023-06-01",
+      "Content-Type": "application/json"
+    },
+    authHeader: "x-api-key",
+    parseResponse: (data) => data.data || []
+  },
+  gemini: {
+    url: "https://generativelanguage.googleapis.com/v1beta/models",
+    method: "GET",
+    headers: { "Content-Type": "application/json" },
+    authQuery: "key", // Use query param for API key
+    parseResponse: (data) => data.models || []
+  },
+  qwen: {
+    url: "https://portal.qwen.ai/v1/models",
+    method: "GET",
+    headers: { "Content-Type": "application/json" },
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    parseResponse: (data) => data.data || []
+  },
+  codex: {
+    url: "https://chatgpt.com/backend-api/codex/models?client_version=1.0.0",
+    method: "GET",
+    headers: { "Content-Type": "application/json", "Accept": "application/json" },
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    parseResponse: parseCodexModels
+  },
+  antigravity: {
+    url: "https://daily-cloudcode-pa.sandbox.googleapis.com/v1internal:models",
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    body: {},
+    parseResponse: (data) => data.models || []
+  },
+  github: {
+    url: "https://api.githubcopilot.com/models",
+    method: "GET",
+    headers: {
+      "Content-Type": "application/json",
+      "Copilot-Integration-Id": "vscode-chat",
+      "editor-version": "vscode/1.107.1",
+      "editor-plugin-version": "copilot-chat/0.26.7",
+      "user-agent": "GitHubCopilotChat/0.26.7"
+    },
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    parseResponse: (data) => {
+      if (!data?.data) return [];
+      // Filter out embeddings, non-chat models, and disabled models
+      return data.data
+        .filter(m => m.capabilities?.type === "chat")
+        .filter(m => m.policy?.state !== "disabled") // Only return explicitly enabled models
+        .map(m => ({
+          id: m.id,
+          name: m.name || m.id,
+          version: m.version,
+          capabilities: m.capabilities,
+          isDefault: m.model_picker_enabled === true
+        }));
+    }
+  },
+  openai: createOpenAIModelsConfig("https://api.openai.com/v1/models"),
+  openrouter: createOpenAIModelsConfig("https://openrouter.ai/api/v1/models"),
+  anthropic: {
+    url: "https://api.anthropic.com/v1/models",
+    method: "GET",
+    headers: {
+      "Anthropic-Version": "2023-06-01",
+      "Content-Type": "application/json"
+    },
+    authHeader: "x-api-key",
+    parseResponse: (data) => data.data || []
+  },
+
+  alicode: {
+    url: "https://coding.dashscope.aliyuncs.com/v1/models",
+    method: "GET",
+    headers: { "Content-Type": "application/json" },
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    parseResponse: (data) => data.data || []
+  },
+  "alicode-intl": {
+    url: "https://coding-intl.dashscope.aliyuncs.com/v1/models",
+    method: "GET",
+    headers: { "Content-Type": "application/json" },
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    parseResponse: (data) => data.data || []
+  },
+  "volcengine-ark": createOpenAIModelsConfig("https://ark.cn-beijing.volces.com/api/coding/v3/models"),
+  byteplus: createOpenAIModelsConfig("https://ark.ap-southeast.bytepluses.com/api/coding/v3/models"),
+
+  // OpenAI-compatible API key providers
+  deepseek: createOpenAIModelsConfig("https://api.deepseek.com/models"),
+  groq: createOpenAIModelsConfig("https://api.groq.com/openai/v1/models"),
+  xai: createOpenAIModelsConfig("https://api.x.ai/v1/models"),
+  mistral: createOpenAIModelsConfig("https://api.mistral.ai/v1/models"),
+  perplexity: createOpenAIModelsConfig("https://api.perplexity.ai/v1/models"),
+  "perplexity-agent": createOpenAIModelsConfig("https://api.perplexity.ai/v1/models"),
+  together: createOpenAIModelsConfig("https://api.together.xyz/v1/models"),
+  fireworks: createOpenAIModelsConfig("https://api.fireworks.ai/inference/v1/models"),
+  cerebras: createOpenAIModelsConfig("https://api.cerebras.ai/v1/models"),
+  cohere: createOpenAIModelsConfig("https://api.cohere.ai/v1/models"),
+  nebius: createOpenAIModelsConfig("https://api.studio.nebius.ai/v1/models"),
+  siliconflow: createOpenAIModelsConfig("https://api.siliconflow.com/v1/models"),
+  hyperbolic: createOpenAIModelsConfig("https://api.hyperbolic.xyz/v1/models"),
+  ollama: createOpenAIModelsConfig("https://ollama.com/api/tags"),
+  // ollama-local: url resolved dynamically below via providerSpecificData.baseUrl
+  nanobanana: createOpenAIModelsConfig("https://api.nanobananaapi.ai/v1/models"),
+  chutes: createOpenAIModelsConfig("https://llm.chutes.ai/v1/models"),
+  nvidia: createOpenAIModelsConfig("https://integrate.api.nvidia.com/v1/models"),
+  assemblyai: createOpenAIModelsConfig("https://api.assemblyai.com/v1/models"),
+  "vercel-ai-gateway": createOpenAIModelsConfig("https://ai-gateway.vercel.sh/v1/models"),
+  kimchi: {
+    customResolver: async (connection) => {
+      const result = await resolveKimchiModels({
+        accessToken: connection.accessToken,
+        apiKey: connection.apiKey,
+        providerSpecificData: connection.providerSpecificData || {},
+      }, { forceRefresh: true, log: console });
+      if (result?.models?.length) {
+        return { models: result.models };
+      }
+      return {
+        models: getStaticProviderModels("kimchi"),
+        warning: "Kimchi returned no live models; falling back to static catalog.",
+      };
+    }
+  },
+
+  // Custom resolvers (non-OpenAI-shaped APIs / token-refresh flows)
+  kiro: {
+    customResolver: async (connection) => {
+      const credentials = {
+        accessToken: connection.accessToken,
+        refreshToken: connection.refreshToken,
+        providerSpecificData: connection.providerSpecificData || {}
+      };
+      let warning;
+      try {
+        const result = await resolveKiroModels(credentials, {
+          log: console,
+          onCredentialsRefreshed: async (refreshed) => {
+            if (refreshed?.accessToken) {
+              await updateProviderCredentials(connection.id, {
+                accessToken: refreshed.accessToken,
+                refreshToken: refreshed.refreshToken || connection.refreshToken,
+                expiresIn: refreshed.expiresIn,
+              });
+              connection.accessToken = refreshed.accessToken;
+              if (refreshed.refreshToken) connection.refreshToken = refreshed.refreshToken;
+            }
+          }
+        });
+        if (result?.models?.length) {
+          return {
+            models: result.models.map((m) => ({
+              id: m.id,
+              name: m.name,
+              upstreamModelId: m.upstreamModelId,
+              contextLength: m.contextLength,
+              rateMultiplier: m.rateMultiplier,
+              capabilities: m.capabilities,
+              description: m.description
+            }))
+          };
+        }
+        warning = "Kiro returned no models; falling back to static catalog.";
+      } catch (error) {
+        warning = `Failed to fetch Kiro models: ${error.message}`;
+        console.log("Failed to fetch Kiro models dynamically, falling back to static:", error.message);
+      }
+      return { models: [], warning };
+    }
+  },
+  qoder: {
+    customResolver: async (connection) => {
+      const credentials = {
+        accessToken: connection.accessToken,
+        refreshToken: connection.refreshToken,
+        email: connection.email,
+        displayName: connection.displayName,
+        providerSpecificData: connection.providerSpecificData || {},
+      };
+      let warning;
+      try {
+        const result = await resolveQoderModels(credentials, { forceRefresh: true });
+        if (result?.models?.length) {
+          return {
+            models: result.models.map((m) => ({
+              // Use the canonical "qoder/<key>" id so the dashboard
+              // surfaces the same identifier the chat router expects.
+              id: `qoder/${m.id}`,
+              name: m.name,
+              contextLength: m.contextLength,
+              isVL: m.isVL,
+              isReasoning: m.isReasoning,
+              maxOutputTokens: m.maxOutputTokens,
+              description: m.description,
+            })),
+          };
+        }
+        warning = "Qoder returned no models; falling back to static catalog.";
+      } catch (error) {
+        warning = `Failed to fetch Qoder models: ${error.message}`;
+        console.log("Failed to fetch Qoder models dynamically, falling back to static:", error.message);
+      }
+      return { models: [], warning };
+    },
+  },
+  "gemini-cli": {
+    customResolver: buildOAuthResolver({
+      refreshFn: (conn) => refreshGoogleToken(conn.refreshToken, GEMINI_CONFIG.clientId, GEMINI_CONFIG.clientSecret),
+      fetchFn: (token, conn) => {
+        const projectId = conn.projectId || conn.providerSpecificData?.projectId;
+        const body = projectId ? { project: projectId } : {};
+        return fetch(GEMINI_CLI_MODELS_URL, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${token}`,
+            "User-Agent": "google-api-nodejs-client/9.15.1",
+            "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1"
+          },
+          body: JSON.stringify(body)
+        });
+      },
+      parseFn: parseGeminiCliModels,
+      errorLabel: "Failed to fetch Gemini CLI models"
+    })
+  },
+  "ollama-local": {
+    customResolver: async (connection) => {
+      const url = `${resolveOllamaLocalHost(connection)}/api/tags`;
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { "Content-Type": "application/json" }
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.log("Error fetching models from ollama-local:", errorText);
+        return { error: `Failed to fetch models: ${response.status}`, status: response.status };
+      }
+      const data = await response.json();
+      return { models: parseOpenAIStyleModels(data) };
+    }
+  }
+};
+
+/**
+ * GET /api/providers/[id]/models - Get models list from provider
+ */
+export async function GET(request, { params }) {
+  try {
+    const { id } = await params;
+    const connection = await getProviderConnectionById(id);
+
+    if (!connection) {
+      return NextResponse.json({ error: "Connection not found" }, { status: 404 });
+    }
+
+    if (isOpenAICompatibleProvider(connection.provider)) {
+      const baseUrl = connection.providerSpecificData?.baseUrl;
+      if (!baseUrl) {
+        return NextResponse.json({ error: "No base URL configured for OpenAI compatible provider" }, { status: 400 });
+      }
+      const url = `${baseUrl.replace(/\/$/, "")}/models`;
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${connection.apiKey}`,
+        },
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.log(`Error fetching models from ${connection.provider}:`, errorText);
+        return NextResponse.json(
+          { error: `Failed to fetch models: ${response.status}` },
+          { status: response.status }
+        );
+      }
+
+      const data = await response.json();
+      const models = data.data || data.models || [];
+
+      return NextResponse.json({
+        provider: connection.provider,
+        connectionId: connection.id,
+        models
+      });
+    }
+
+    if (isAnthropicCompatibleProvider(connection.provider)) {
+      let baseUrl = connection.providerSpecificData?.baseUrl;
+      if (!baseUrl) {
+        return NextResponse.json({ error: "No base URL configured for Anthropic compatible provider" }, { status: 400 });
+      }
+
+      baseUrl = baseUrl.replace(/\/$/, "");
+      if (baseUrl.endsWith("/messages")) {
+        baseUrl = baseUrl.slice(0, -9);
+      }
+
+      const url = `${baseUrl}/models`;
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": connection.apiKey,
+          "anthropic-version": "2023-06-01",
+          "Authorization": `Bearer ${connection.apiKey}`
+        },
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.log(`Error fetching models from ${connection.provider}:`, errorText);
+        return NextResponse.json(
+          { error: `Failed to fetch models: ${response.status}` },
+          { status: response.status }
+        );
+      }
+
+      const data = await response.json();
+      const models = data.data || data.models || [];
+
+      return NextResponse.json({
+        provider: connection.provider,
+        connectionId: connection.id,
+        models
+      });
+    }
+
+    const config = PROVIDER_MODELS_CONFIG[connection.provider];
+    if (!config) {
+      return NextResponse.json(
+        { error: `Provider ${connection.provider} does not support models listing` },
+        { status: 400 }
+      );
+    }
+
+    // Config-driven custom resolver path (OAuth refresh, non-OpenAI shape, etc.)
+    if (typeof config.customResolver === "function") {
+      const result = await config.customResolver(connection);
+      if (result.error) {
+        return NextResponse.json({ error: result.error }, { status: result.status || 500 });
+      }
+      return NextResponse.json({
+        provider: connection.provider,
+        connectionId: connection.id,
+        models: result.models,
+        ...(result.warning ? { warning: result.warning } : {})
+      });
+    }
+
+    // Get auth token
+    const token = connection.providerSpecificData?.copilotToken || connection.accessToken || connection.apiKey;
+    if (!token) {
+      return NextResponse.json({ error: "No valid token found" }, { status: 401 });
+    }
+
+    // Build request URL
+    let url = config.url;
+    if (connection.provider === "qwen") {
+      url = resolveQwenModelsUrl(connection);
+    }
+    if (config.authQuery) {
+      url += `?${config.authQuery}=${token}`;
+    }
+
+    // Build headers
+    const headers = { ...config.headers };
+    if (config.authHeader && !config.authQuery) {
+      headers[config.authHeader] = (config.authPrefix || "") + token;
+    }
+
+    // Make request
+    const fetchOptions = {
+      method: config.method,
+      headers
+    };
+
+    if (config.body && config.method === "POST") {
+      fetchOptions.body = JSON.stringify(config.body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      console.log(`Error fetching models from ${connection.provider}:`, errorText);
+      return NextResponse.json(
+        { error: `Failed to fetch models: ${response.status}` },
+        { status: response.status }
+      );
+    }
+
+    const data = await response.json();
+    const models = config.parseResponse(data);
+
+    return NextResponse.json({
+      provider: connection.provider,
+      connectionId: connection.id,
+      models
+    });
+  } catch (error) {
+    console.log("Error fetching provider models:", error);
+    return NextResponse.json({ error: "Failed to fetch models" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/providers/[id]/route.js b/src/app/api/providers/[id]/route.js
new file mode 100644
index 0000000..6ab5179
--- /dev/null
+++ b/src/app/api/providers/[id]/route.js
@@ -0,0 +1,189 @@
+import { NextResponse } from "next/server";
+import {
+  getProviderConnectionById,
+  getProxyPoolById,
+  updateProviderConnection,
+  deleteProviderConnection,
+} from "@/models";
+
+function normalizeProxyConfig(body = {}) {
+  const hasAnyProxyField =
+    Object.prototype.hasOwnProperty.call(body, "connectionProxyEnabled") ||
+    Object.prototype.hasOwnProperty.call(body, "connectionProxyUrl") ||
+    Object.prototype.hasOwnProperty.call(body, "connectionNoProxy");
+
+  if (!hasAnyProxyField) return { hasAnyProxyField: false };
+
+  const enabled = body?.connectionProxyEnabled === true;
+  const url = typeof body?.connectionProxyUrl === "string" ? body.connectionProxyUrl.trim() : "";
+  const noProxy = typeof body?.connectionNoProxy === "string" ? body.connectionNoProxy.trim() : "";
+
+  if (enabled && !url) {
+    return {
+      hasAnyProxyField: true,
+      error: "Connection proxy URL is required when connection proxy is enabled",
+    };
+  }
+
+  return {
+    hasAnyProxyField: true,
+    connectionProxyEnabled: enabled,
+    connectionProxyUrl: url,
+    connectionNoProxy: noProxy,
+  };
+}
+
+async function normalizeProxyPoolUpdate(proxyPoolIdInput) {
+  if (proxyPoolIdInput === undefined) {
+    return { hasProxyPoolField: false, proxyPoolId: null };
+  }
+
+  if (proxyPoolIdInput === null || proxyPoolIdInput === "" || proxyPoolIdInput === "__none__") {
+    return { hasProxyPoolField: true, proxyPoolId: null };
+  }
+
+  const proxyPoolId = String(proxyPoolIdInput).trim();
+  if (!proxyPoolId) {
+    return { hasProxyPoolField: true, proxyPoolId: null };
+  }
+
+  const proxyPool = await getProxyPoolById(proxyPoolId);
+  if (!proxyPool) {
+    return { hasProxyPoolField: true, error: "Proxy pool not found" };
+  }
+
+  return { hasProxyPoolField: true, proxyPoolId };
+}
+
+function shouldMergeProviderSpecificData(existing, incoming, hasLegacyProxy, hasProxyPoolField) {
+  return existing !== undefined || incoming !== undefined || hasLegacyProxy || hasProxyPoolField;
+}
+
+// GET /api/providers/[id] - Get single connection
+export async function GET(request, { params }) {
+  try {
+    const { id } = await params;
+    const connection = await getProviderConnectionById(id);
+
+    if (!connection) {
+      return NextResponse.json({ error: "Connection not found" }, { status: 404 });
+    }
+
+    // Hide sensitive fields
+    const result = { ...connection };
+    delete result.apiKey;
+    delete result.accessToken;
+    delete result.refreshToken;
+    delete result.idToken;
+
+    return NextResponse.json({ connection: result });
+  } catch (error) {
+    console.log("Error fetching connection:", error);
+    return NextResponse.json({ error: "Failed to fetch connection" }, { status: 500 });
+  }
+}
+
+// PUT /api/providers/[id] - Update connection
+export async function PUT(request, { params }) {
+  try {
+    const { id } = await params;
+    const body = await request.json();
+    const {
+      name,
+      priority,
+      globalPriority,
+      defaultModel,
+      isActive,
+      apiKey,
+      testStatus,
+      lastError,
+      lastErrorAt,
+      providerSpecificData
+    } = body;
+
+    const existing = await getProviderConnectionById(id);
+    if (!existing) {
+      return NextResponse.json({ error: "Connection not found" }, { status: 404 });
+    }
+
+    const proxyConfig = normalizeProxyConfig(body);
+    if (proxyConfig.error) {
+      return NextResponse.json({ error: proxyConfig.error }, { status: 400 });
+    }
+
+    const proxyPoolResult = await normalizeProxyPoolUpdate(body.proxyPoolId);
+    if (proxyPoolResult.error) {
+      return NextResponse.json({ error: proxyPoolResult.error }, { status: 400 });
+    }
+
+    const updateData = {};
+    if (name !== undefined) updateData.name = name;
+    if (priority !== undefined) updateData.priority = priority;
+    if (globalPriority !== undefined) updateData.globalPriority = globalPriority;
+    if (defaultModel !== undefined) updateData.defaultModel = defaultModel;
+    if (isActive !== undefined) updateData.isActive = isActive;
+    if (apiKey && existing.authType === "apikey") updateData.apiKey = apiKey;
+    if (testStatus !== undefined) updateData.testStatus = testStatus;
+    if (lastError !== undefined) updateData.lastError = lastError;
+    if (lastErrorAt !== undefined) updateData.lastErrorAt = lastErrorAt;
+
+    if (
+      shouldMergeProviderSpecificData(
+        existing.providerSpecificData,
+        providerSpecificData,
+        proxyConfig.hasAnyProxyField,
+        proxyPoolResult.hasProxyPoolField
+      )
+    ) {
+      updateData.providerSpecificData = {
+        ...(existing.providerSpecificData || {}),
+        ...(providerSpecificData || {}),
+      };
+
+      if (proxyConfig.hasAnyProxyField) {
+        updateData.providerSpecificData.connectionProxyEnabled = proxyConfig.connectionProxyEnabled;
+        updateData.providerSpecificData.connectionProxyUrl = proxyConfig.connectionProxyUrl;
+        updateData.providerSpecificData.connectionNoProxy = proxyConfig.connectionNoProxy;
+      }
+
+      if (proxyPoolResult.hasProxyPoolField) {
+        if (proxyPoolResult.proxyPoolId === null) {
+          delete updateData.providerSpecificData.proxyPoolId;
+        } else {
+          updateData.providerSpecificData.proxyPoolId = proxyPoolResult.proxyPoolId;
+        }
+      }
+    }
+
+    const updated = await updateProviderConnection(id, updateData);
+
+    // Hide sensitive fields
+    const result = { ...updated };
+    delete result.apiKey;
+    delete result.accessToken;
+    delete result.refreshToken;
+    delete result.idToken;
+
+    return NextResponse.json({ connection: result });
+  } catch (error) {
+    console.log("Error updating connection:", error);
+    return NextResponse.json({ error: "Failed to update connection" }, { status: 500 });
+  }
+}
+
+// DELETE /api/providers/[id] - Delete connection
+export async function DELETE(request, { params }) {
+  try {
+    const { id } = await params;
+
+    const deleted = await deleteProviderConnection(id);
+    if (!deleted) {
+      return NextResponse.json({ error: "Connection not found" }, { status: 404 });
+    }
+
+    return NextResponse.json({ message: "Connection deleted successfully" });
+  } catch (error) {
+    console.log("Error deleting connection:", error);
+    return NextResponse.json({ error: "Failed to delete connection" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/providers/[id]/test-models/route.js b/src/app/api/providers/[id]/test-models/route.js
new file mode 100644
index 0000000..8494639
--- /dev/null
+++ b/src/app/api/providers/[id]/test-models/route.js
@@ -0,0 +1,66 @@
+import { NextResponse } from "next/server";
+import { getProviderConnectionById } from "@/lib/localDb";
+import { getProviderModels, PROVIDER_ID_TO_ALIAS } from "open-sse/config/providerModels.js";
+import { isOpenAICompatibleProvider, isAnthropicCompatibleProvider } from "@/shared/constants/providers";
+import { UPDATER_CONFIG } from "@/shared/constants/config";
+import { pingModelByKind } from "@/app/api/models/test/ping";
+
+/**
+ * POST /api/providers/[id]/test-models
+ * id = connectionId — used only to resolve provider + model list.
+ * Actual requests go through the internal endpoint that matches each model kind.
+ */
+export async function POST(request, { params }) {
+  try {
+    const { id } = await params;
+    const connection = await getProviderConnectionById(id);
+    if (!connection) {
+      return NextResponse.json({ error: "Connection not found" }, { status: 404 });
+    }
+
+    const providerId = connection.provider;
+    const isCompatible = isOpenAICompatibleProvider(providerId) || isAnthropicCompatibleProvider(providerId);
+    const alias = PROVIDER_ID_TO_ALIAS[providerId] || providerId;
+
+    let models = getProviderModels(alias);
+
+    const baseUrl = `http://127.0.0.1:${process.env.PORT || UPDATER_CONFIG.appPort}`;
+
+    // Compatible providers: fetch live model list
+    if (isCompatible && models.length === 0) {
+      try {
+        const modelsRes = await fetch(`${baseUrl}/api/providers/${id}/models`);
+        if (modelsRes.ok) {
+          const data = await modelsRes.json();
+          models = (data.models || []).map((m) => ({ id: m.id || m.name, name: m.name || m.id }));
+        }
+      } catch { /* fallback to empty */ }
+    }
+
+    if (models.length === 0) {
+      return NextResponse.json({ error: "No models configured for this provider" }, { status: 400 });
+    }
+
+    // Warm up with first model to trigger token refresh (if needed) before parallel calls.
+    // This prevents race condition where multiple requests concurrently refresh the same token.
+    const [first, ...rest] = models;
+    const firstKind = first.kind || first.type || "llm";
+    const firstResult = await pingModelByKind(`${alias}/${first.id}`, firstKind, baseUrl);
+    const results = [{ modelId: first.id, name: first.name || first.id, ...firstResult }];
+
+    if (rest.length > 0) {
+      const restResults = await Promise.all(
+        rest.map(async (model) => {
+          const result = await pingModelByKind(`${alias}/${model.id}`, model.kind || model.type || "llm", baseUrl);
+          return { modelId: model.id, name: model.name || model.id, ...result };
+        })
+      );
+      results.push(...restResults);
+    }
+
+    return NextResponse.json({ provider: providerId, connectionId: id, results });
+  } catch (error) {
+    console.log("Error testing models:", error);
+    return NextResponse.json({ error: "Test failed" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/providers/[id]/test/route.js b/src/app/api/providers/[id]/test/route.js
new file mode 100644
index 0000000..0fa641a
--- /dev/null
+++ b/src/app/api/providers/[id]/test/route.js
@@ -0,0 +1,23 @@
+import { NextResponse } from "next/server";
+import { testSingleConnection } from "./testUtils.js";
+
+// POST /api/providers/[id]/test - Test connection
+export async function POST(request, { params }) {
+  try {
+    const { id } = await params;
+    const result = await testSingleConnection(id);
+
+    if (result.error === "Connection not found") {
+      return NextResponse.json({ error: "Connection not found" }, { status: 404 });
+    }
+
+    return NextResponse.json({
+      valid: result.valid,
+      error: result.error,
+      refreshed: result.refreshed || false,
+    });
+  } catch (error) {
+    console.log("Error testing connection:", error);
+    return NextResponse.json({ error: "Test failed" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/providers/[id]/test/testUtils.js b/src/app/api/providers/[id]/test/testUtils.js
new file mode 100644
index 0000000..a05e6f4
--- /dev/null
+++ b/src/app/api/providers/[id]/test/testUtils.js
@@ -0,0 +1,861 @@
+import { getProviderConnectionById, updateProviderConnection } from "@/lib/localDb";
+import { resolveConnectionProxyConfig } from "@/lib/network/connectionProxy";
+import { testProxyUrl } from "@/lib/network/proxyTest";
+import { isOpenAICompatibleProvider, isAnthropicCompatibleProvider } from "@/shared/constants/providers";
+import { getDefaultModel } from "open-sse/config/providerModels.js";
+import { resolveOllamaLocalHost, PROVIDERS } from "open-sse/config/providers.js";
+import {
+  refreshProviderCredentials,
+  shouldRefreshCredentials,
+} from "open-sse/services/oauthCredentialManager.js";
+import {
+  GEMINI_CONFIG,
+  ANTIGRAVITY_CONFIG,
+  KIRO_CONFIG,
+  QWEN_CONFIG,
+  CLAUDE_CONFIG,
+  CLINE_CONFIG,
+  KILOCODE_CONFIG,
+  KIMCHI_CONFIG,
+} from "@/lib/oauth/constants/oauth";
+import { buildClineHeaders } from "@/shared/utils/clineAuth";
+
+// OAuth provider test endpoints
+const OAUTH_TEST_CONFIG = {
+  claude: { checkExpiry: true, refreshable: true },
+  codex: {
+    url: "https://chatgpt.com/backend-api/codex/responses",
+    method: "POST",
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    extraHeaders: { "Content-Type": "application/json", "originator": "codex_cli_rs", "User-Agent": "codex_cli_rs/0.136.0" },
+    // Minimal invalid body — triggers fast 400 without consuming quota
+    body: JSON.stringify({ model: "gpt-5.3-codex", input: [], stream: false, store: false }),
+    // 400 (bad request) means auth succeeded; only 401/403 means token is bad
+    acceptStatuses: [400],
+    refreshable: true,
+  },
+  "gemini-cli": {
+    url: "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+    method: "GET",
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    refreshable: true,
+  },
+  antigravity: {
+    url: "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+    method: "GET",
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    refreshable: true,
+  },
+  github: {
+    url: "https://api.github.com/user",
+    method: "GET",
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    extraHeaders: { "User-Agent": "9Router", "Accept": "application/vnd.github+json" },
+  },
+  iflow: {
+    // iFlow getUserInfo requires accessToken as query param, not header
+    buildUrl: (token) => `https://iflow.cn/api/oauth/getUserInfo?accessToken=${encodeURIComponent(token)}`,
+    method: "GET",
+    noAuth: true,
+  },
+  qwen: { checkExpiry: true, refreshable: true },
+  kiro: { checkExpiry: true, refreshable: true },
+  qoder: {
+    // Test by hitting Qoder's userinfo endpoint with the device token.
+    // refreshable: false because the device-flow refresh endpoint returns
+    // 403 for our flow (users re-login when expired). No checkExpiry —
+    // we want the actual URL probe to run so revoked tokens surface.
+    url: "https://openapi.qoder.sh/api/v1/userinfo",
+    method: "GET",
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    refreshable: false,
+  },
+  "kimi-coding": { checkExpiry: true, refreshable: false },
+  cursor: { tokenExists: true },
+  kilocode: {
+    url: `${KILOCODE_CONFIG.apiBaseUrl}/api/profile`,
+    method: "GET",
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+  },
+  cline: { refreshable: true },
+  gitlab: {
+    // Test by hitting the GitLab user API — requires api or read_user scope
+    url: "https://gitlab.com/api/v4/user",
+    method: "GET",
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+  },
+  "codebuddy-cn": { tokenExists: true },
+  kimchi: {
+    url: KIMCHI_CONFIG.validationUrl || "https://api.cast.ai/v1/llm/openai/supported-providers",
+    method: "GET",
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    extraHeaders: {
+      Accept: "application/json",
+      "User-Agent": "kimchi/0.1.40",
+    },
+    refreshable: false,
+  },
+  // Grok CLI / Grok Build — probe /v1/user (no inference quota). Headers mirror official CLI.
+  "grok-cli": {
+    url: PROVIDERS["grok-cli"]?.userUrl || "https://cli-chat-proxy.grok.com/v1/user",
+    method: "GET",
+    authHeader: "Authorization",
+    authPrefix: "Bearer ",
+    extraHeaders: {
+      Accept: "application/json",
+      ...(PROVIDERS["grok-cli"]?.headers || {
+        "User-Agent": "grok-pager/0.2.93 grok-shell/0.2.93 (linux; x86_64)",
+        "x-xai-token-auth": "xai-grok-cli",
+        "x-grok-client-identifier": "grok-pager",
+        "x-grok-client-version": "0.2.93",
+      }),
+    },
+    refreshable: true,
+    // Subscription spending-limit is not an auth failure — token is fine, credits aren't.
+    // Accept 402 so the connection stays "active" with a warning (same idea as Codex 400).
+    acceptStatuses: [402],
+    softFailMessage: {
+      402: "Connected, but Grok Build credits are exhausted (spending limit). Add credits or upgrade SuperGrok.",
+    },
+  },
+};
+
+/**
+ * Classify an OAuth probe response as success / soft-success / hard-fail.
+ * Soft success (e.g. 402 spending-limit on Grok CLI) means auth works but the
+ * account cannot spend — keep connection active and surface a warning.
+ * Exported for unit tests.
+ */
+export function classifyOAuthProbeResult(res, config, bodyText = "") {
+  if (!res) return { valid: false, error: "No response", soft: false };
+  const status = res.status;
+  const accepted = res.ok || (config?.acceptStatuses && config.acceptStatuses.includes(status));
+  if (!accepted) {
+    if (status === 401) return { valid: false, error: "Token invalid or revoked", soft: false };
+    if (status === 403) return { valid: false, error: "Access denied", soft: false };
+    return { valid: false, error: `API returned ${status}`, soft: false };
+  }
+
+  // Soft success only when the provider configured an explicit message for this
+  // status (e.g. Grok CLI 402 spending-limit). Codex-style acceptStatuses:[400]
+  // stays silent success — 400 there only proves auth, not a user-facing warning.
+  if (!res.ok && config?.acceptStatuses?.includes(status)) {
+    const softMap = config.softFailMessage || {};
+    if (softMap[status]) {
+      return { valid: true, error: softMap[status], soft: true };
+    }
+    return { valid: true, error: null, soft: false };
+  }
+
+  return { valid: true, error: null, soft: false };
+}
+
+async function probeClineAccessToken(accessToken) {
+  const res = await fetch("https://api.cline.bot/api/v1/users/me", {
+    method: "GET",
+    headers: buildClineHeaders(accessToken, {
+      Accept: "application/json",
+    }),
+  });
+
+  return res;
+}
+
+const CLOUD_CODE_ASSIST_TEST_URL = "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist";
+const CLOUD_CODE_ASSIST_TEST_BODY = JSON.stringify({
+  metadata: {
+    ideType: "IDE_UNSPECIFIED",
+    platform: "PLATFORM_UNSPECIFIED",
+    pluginType: "GEMINI",
+  },
+});
+
+function parseProviderErrorMessage(bodyText, fallback) {
+  if (!bodyText) return fallback;
+  try {
+    const parsed = JSON.parse(bodyText);
+    const message = parsed?.error?.message || parsed?.message || parsed?.error;
+    if (typeof message === "string" && message.trim()) return message.trim();
+    if (message) return JSON.stringify(message);
+  } catch {
+    // fall through
+  }
+  return bodyText.trim() || fallback;
+}
+
+async function probeCloudCodeAssistAccess(connection, accessToken, effectiveProxy = null) {
+  const userAgent = connection.provider === "antigravity"
+    ? "google-api-nodejs-client/9.15.1 vscode-antigravity/1.107.0"
+    : "google-api-nodejs-client/9.15.1 gemini-cli/0.34.0";
+
+  const res = await fetchWithConnectionProxy(CLOUD_CODE_ASSIST_TEST_URL, {
+    method: "POST",
+    headers: {
+      "Authorization": `Bearer ${accessToken}`,
+      "Content-Type": "application/json",
+      "User-Agent": userAgent,
+    },
+    body: CLOUD_CODE_ASSIST_TEST_BODY,
+  }, effectiveProxy);
+
+  if (res.ok) return { valid: true, error: null };
+
+  const bodyText = await res.text().catch(() => "");
+  return {
+    valid: false,
+    error: parseProviderErrorMessage(bodyText, `API returned ${res.status}`),
+    status: res.status,
+  };
+}
+
+async function refreshOAuthToken(connection) {
+  const provider = connection.provider;
+  const refreshToken = connection.refreshToken;
+  if (!refreshToken) return null;
+
+  try {
+    if (provider === "gemini-cli" || provider === "antigravity") {
+      const config = provider === "gemini-cli" ? GEMINI_CONFIG : ANTIGRAVITY_CONFIG;
+      const response = await fetch("https://oauth2.googleapis.com/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          client_id: config.clientId,
+          client_secret: config.clientSecret,
+          grant_type: "refresh_token",
+          refresh_token: refreshToken,
+        }),
+      });
+      if (!response.ok) return null;
+      const data = await response.json();
+      return { accessToken: data.access_token, expiresIn: data.expires_in, refreshToken: data.refresh_token || refreshToken };
+    }
+
+    if (provider === "codex" || provider === "grok-cli" || provider === "xai") {
+      return await refreshProviderCredentials(provider, connection, console);
+    }
+
+    if (provider === "claude") {
+      const response = await fetch(CLAUDE_CONFIG.tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "Accept": "application/json" },
+        body: JSON.stringify({
+          grant_type: "refresh_token",
+          refresh_token: refreshToken,
+          client_id: CLAUDE_CONFIG.clientId,
+        }),
+      });
+      if (!response.ok) return null;
+      const data = await response.json();
+      return { accessToken: data.access_token, expiresIn: data.expires_in, refreshToken: data.refresh_token || refreshToken };
+    }
+
+    if (provider === "kiro") {
+      const psd = connection.providerSpecificData || {};
+      const clientId = psd.clientId || connection.clientId;
+      const clientSecret = psd.clientSecret || connection.clientSecret;
+      const region = psd.region || connection.region;
+      if (clientId && clientSecret) {
+        const endpoint = `https://oidc.${region || "us-east-1"}.amazonaws.com/token`;
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ clientId, clientSecret, refreshToken, grantType: "refresh_token" }),
+        });
+        if (!response.ok) return null;
+        const data = await response.json();
+        return { accessToken: data.accessToken, expiresIn: data.expiresIn || 3600, refreshToken: data.refreshToken || refreshToken };
+      }
+      const response = await fetch(KIRO_CONFIG.socialRefreshUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "User-Agent": "kiro-cli/1.0.0" },
+        body: JSON.stringify({ refreshToken }),
+      });
+      if (!response.ok) return null;
+      const data = await response.json();
+      return { accessToken: data.accessToken, expiresIn: data.expiresIn || 3600, refreshToken: data.refreshToken || refreshToken };
+    }
+
+    if (provider === "qwen") {
+      const response = await fetch(QWEN_CONFIG.tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json" },
+        body: new URLSearchParams({
+          grant_type: "refresh_token",
+          refresh_token: refreshToken,
+          client_id: QWEN_CONFIG.clientId,
+        }),
+      });
+      if (!response.ok) return null;
+      const data = await response.json();
+      return { accessToken: data.access_token, expiresIn: data.expires_in, refreshToken: data.refresh_token || refreshToken };
+    }
+
+    if (provider === "cline") {
+      const response = await fetch(CLINE_CONFIG.refreshUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({
+          refreshToken,
+          grantType: "refresh_token",
+          clientType: "extension",
+        }),
+      });
+      if (!response.ok) return null;
+      const payload = await response.json();
+      const data = payload?.data || payload;
+      const expiresIn = data?.expiresAt
+        ? Math.max(1, Math.floor((new Date(data.expiresAt).getTime() - Date.now()) / 1000))
+        : 3600;
+      return {
+        accessToken: data?.accessToken,
+        expiresIn,
+        refreshToken: data?.refreshToken || refreshToken,
+      };
+    }
+
+    return null;
+  } catch (err) {
+    console.log(`Error refreshing ${provider} token:`, err.message);
+    return null;
+  }
+}
+
+function isTokenExpired(connection) {
+  return shouldRefreshCredentials(connection.provider, connection);
+}
+
+async function testOAuthConnection(connection, effectiveProxy = null) {
+  const config = OAUTH_TEST_CONFIG[connection.provider];
+  if (!config) return { valid: false, error: "Provider test not supported", refreshed: false };
+  if (!connection.accessToken) return { valid: false, error: "No access token", refreshed: false };
+
+  // Cursor uses protobuf API - can only verify token exists, not test endpoint
+  if (config.tokenExists) {
+    return { valid: true, error: null, refreshed: false, newTokens: null };
+  }
+
+  let accessToken = connection.accessToken;
+  let refreshed = false;
+  let newTokens = null;
+
+  const tokenExpired = isTokenExpired(connection);
+  if (config.refreshable && tokenExpired && connection.refreshToken) {
+    const tokens = await refreshOAuthToken(connection);
+    if (tokens) {
+      accessToken = tokens.accessToken;
+      refreshed = true;
+      newTokens = tokens;
+    } else {
+      return { valid: false, error: "Token expired and refresh failed", refreshed: false };
+    }
+  }
+
+  if (config.checkExpiry) {
+    if (refreshed) return { valid: true, error: null, refreshed, newTokens };
+    if (tokenExpired) return { valid: false, error: "Token expired", refreshed: false };
+    return { valid: true, error: null, refreshed: false, newTokens: null };
+  }
+
+  if (connection.provider === "gemini-cli" || connection.provider === "antigravity") {
+    const initial = await probeCloudCodeAssistAccess(connection, accessToken, effectiveProxy);
+    if (initial.valid) return { valid: true, error: null, refreshed, newTokens };
+
+    if (initial.status === 401 && config.refreshable && !refreshed && connection.refreshToken) {
+      const tokens = await refreshOAuthToken(connection);
+      if (tokens?.accessToken) {
+        const retry = await probeCloudCodeAssistAccess(connection, tokens.accessToken, effectiveProxy);
+        if (retry.valid) return { valid: true, error: null, refreshed: true, newTokens: tokens };
+        return { valid: false, error: retry.error, refreshed: true, newTokens: tokens };
+      }
+      return { valid: false, error: "Token invalid or revoked", refreshed: false };
+    }
+
+    return { valid: false, error: initial.error, refreshed };
+  }
+
+  if (connection.provider === "cline") {
+    const tryProbe = async (token) => {
+      const res = await probeClineAccessToken(token);
+      if (res.ok) return { valid: true, error: null, refreshed, newTokens };
+      if (res.status === 401) return { valid: false, error: "Token invalid or revoked", refreshed };
+      if (res.status === 403) return { valid: false, error: "Access denied", refreshed };
+      return { valid: false, error: `API returned ${res.status}`, refreshed };
+    };
+
+    const initial = await tryProbe(accessToken);
+    if (initial.valid || initial.error !== "Token invalid or revoked" || !connection.refreshToken) {
+      return initial;
+    }
+
+    const tokens = await refreshOAuthToken(connection);
+    if (!tokens?.accessToken) {
+      return { valid: false, error: "Token invalid or revoked", refreshed: false };
+    }
+
+    refreshed = true;
+    newTokens = tokens;
+    accessToken = tokens.accessToken;
+    return await tryProbe(accessToken);
+  }
+
+  try {
+    const testUrl = config.buildUrl ? config.buildUrl(accessToken) : config.url;
+    const headers = config.noAuth
+      ? { ...config.extraHeaders }
+      : { [config.authHeader]: `${config.authPrefix}${accessToken}`, ...config.extraHeaders };
+    const fetchOpts = { method: config.method, headers };
+    if (config.body) fetchOpts.body = config.body;
+    const res = await fetchWithConnectionProxy(testUrl, fetchOpts, effectiveProxy);
+    const bodyText = !res.ok ? await res.text().catch(() => "") : "";
+
+    const classified = classifyOAuthProbeResult(res, config, bodyText);
+    if (classified.valid) {
+      return {
+        valid: true,
+        // soft success surfaces warning text without marking connection error
+        error: classified.soft ? classified.error : null,
+        warning: classified.soft ? classified.error : null,
+        refreshed,
+        newTokens,
+      };
+    }
+
+    if (res.status === 401 && config.refreshable && !refreshed && connection.refreshToken) {
+      const tokens = await refreshOAuthToken(connection);
+      if (tokens) {
+        const retryUrl = config.buildUrl ? config.buildUrl(tokens.accessToken) : testUrl;
+        const retryHeaders = config.noAuth
+          ? { ...config.extraHeaders }
+          : { [config.authHeader]: `${config.authPrefix}${tokens.accessToken}`, ...config.extraHeaders };
+        const retryOpts = { method: config.method, headers: retryHeaders };
+        if (config.body) retryOpts.body = config.body;
+        const retryRes = await fetchWithConnectionProxy(retryUrl, retryOpts, effectiveProxy);
+        const retryBody = !retryRes.ok ? await retryRes.text().catch(() => "") : "";
+        const retryClassified = classifyOAuthProbeResult(retryRes, config, retryBody);
+        if (retryClassified.valid) {
+          return {
+            valid: true,
+            error: retryClassified.soft ? retryClassified.error : null,
+            warning: retryClassified.soft ? retryClassified.error : null,
+            refreshed: true,
+            newTokens: tokens,
+          };
+        }
+      }
+      return { valid: false, error: "Token invalid or revoked", refreshed: false };
+    }
+
+    return { valid: false, error: classified.error, refreshed };
+  } catch (err) {
+    return { valid: false, error: err.message, refreshed };
+  }
+}
+
+async function fetchWithConnectionProxy(url, options = {}, effectiveProxy = null) {
+  // Vercel relay: forward via relay URL
+  if (effectiveProxy?.vercelRelayUrl) {
+    const { proxyAwareFetch } = await import("open-sse/utils/proxyFetch.js");
+    return proxyAwareFetch(url, options, {
+      vercelRelayUrl: effectiveProxy.vercelRelayUrl,
+    });
+  }
+
+  if (!effectiveProxy?.connectionProxyEnabled || !effectiveProxy?.connectionProxyUrl) {
+    return fetch(url, options);
+  }
+
+  const { proxyAwareFetch } = await import("open-sse/utils/proxyFetch.js");
+  return proxyAwareFetch(url, options, {
+    connectionProxyEnabled: true,
+    connectionProxyUrl: effectiveProxy.connectionProxyUrl,
+    connectionNoProxy: effectiveProxy.connectionNoProxy || "",
+  });
+}
+
+async function testApiKeyConnection(connection, effectiveProxy = null) {
+  if (isOpenAICompatibleProvider(connection.provider)) {
+    const modelsBase = connection.providerSpecificData?.baseUrl;
+    if (!modelsBase) return { valid: false, error: "Missing base URL" };
+    try {
+      const res = await fetchWithConnectionProxy(`${modelsBase.replace(/\/$/, "")}/models`, {
+        headers: { "Authorization": `Bearer ${connection.apiKey}` },
+      }, effectiveProxy);
+      return { valid: res.ok, error: res.ok ? null : "Invalid API key or base URL" };
+    } catch (err) {
+      return { valid: false, error: err.message };
+    }
+  }
+
+  if (isAnthropicCompatibleProvider(connection.provider)) {
+    let modelsBase = connection.providerSpecificData?.baseUrl;
+    if (!modelsBase) return { valid: false, error: "Missing base URL" };
+    try {
+      modelsBase = modelsBase.replace(/\/$/, "");
+      if (modelsBase.endsWith("/messages")) modelsBase = modelsBase.slice(0, -9);
+      const messagesUrl = `${modelsBase}/v1/messages`;
+      const model = connection.defaultModel || "claude-3-haiku-20240307";
+      const res = await fetchWithConnectionProxy(messagesUrl, {
+        method: "POST",
+        headers: {
+          "x-api-key": connection.apiKey,
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json",
+          "Authorization": `Bearer ${connection.apiKey}`,
+        },
+        body: JSON.stringify({
+          model,
+          max_tokens: 1,
+          messages: [{ role: "user", content: "test" }],
+        }),
+      }, effectiveProxy);
+      // 400/529 still confirms key accepted; only 401/403 = bad key
+      const valid = res.status !== 401 && res.status !== 403;
+      return { valid, error: valid ? null : "Invalid API key or base URL" };
+    } catch (err) {
+      return { valid: false, error: err.message };
+    }
+  }
+
+  try {
+    switch (connection.provider) {
+      case "cloudflare-ai": {
+        const psd = connection.providerSpecificData || {};
+        const accountId = psd.accountId;
+        if (!accountId) return { valid: false, error: "Missing Account ID" };
+        const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1/chat/completions`;
+        const res = await fetchWithConnectionProxy(url, {
+          method: "POST",
+          headers: { "Authorization": `Bearer ${connection.apiKey}`, "Content-Type": "application/json" },
+          body: JSON.stringify({ model: getDefaultModel("cloudflare-ai"), messages: [{ role: "user", content: "test" }], max_tokens: 1 }),
+        }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403 && res.status !== 404;
+        return { valid, error: valid ? null : "Invalid API token or Account ID" };
+      }
+      case "azure": {
+        const psd = connection.providerSpecificData || {};
+        const endpoint = (psd.azureEndpoint || "").replace(/\/$/, "");
+        const deployment = psd.deployment || "gpt-4";
+        const apiVersion = psd.apiVersion || "2024-10-01-preview";
+        const url = `${endpoint}/openai/deployments/${deployment}/chat/completions?api-version=${apiVersion}`;
+        const headers = { "api-key": connection.apiKey, "Content-Type": "application/json" };
+        if (psd.organization) headers["OpenAI-Organization"] = psd.organization;
+        const res = await fetchWithConnectionProxy(url, {
+          method: "POST", headers,
+          body: JSON.stringify({ messages: [{ role: "user", content: "test" }], max_completion_tokens: 1 }),
+        }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403;
+        return { valid, error: valid ? null : "Invalid API key or Azure configuration" };
+      }
+      case "openai": {
+        const res = await fetchWithConnectionProxy("https://api.openai.com/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "vercel-ai-gateway": {
+        const res = await fetchWithConnectionProxy("https://ai-gateway.vercel.sh/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "anthropic": {
+        const res = await fetchWithConnectionProxy("https://api.anthropic.com/v1/messages", {
+          method: "POST",
+          headers: { "x-api-key": connection.apiKey, "anthropic-version": "2023-06-01", "content-type": "application/json" },
+          body: JSON.stringify({ model: "claude-3-haiku-20240307", max_tokens: 1, messages: [{ role: "user", content: "test" }] }),
+        }, effectiveProxy);
+        const valid = res.status !== 401;
+        return { valid, error: valid ? null : "Invalid API key" };
+      }
+      case "gemini": {
+        const res = await fetchWithConnectionProxy(`https://generativelanguage.googleapis.com/v1/models?key=${connection.apiKey}`, {}, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "openrouter": {
+        const res = await fetchWithConnectionProxy("https://openrouter.ai/api/v1/auth/key", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "glm": {
+        const res = await fetchWithConnectionProxy("https://api.z.ai/api/anthropic/v1/messages", {
+          method: "POST",
+          headers: { "x-api-key": connection.apiKey, "anthropic-version": "2023-06-01", "content-type": "application/json" },
+          body: JSON.stringify({ model: "glm-4.7", max_tokens: 1, messages: [{ role: "user", content: "test" }] }),
+        }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403;
+        return { valid, error: valid ? null : "Invalid API key" };
+      }
+      case "glm-cn": {
+        const res = await fetchWithConnectionProxy("https://open.bigmodel.cn/api/coding/paas/v4/chat/completions", {
+          method: "POST",
+          headers: { "Authorization": `Bearer ${connection.apiKey}`, "content-type": "application/json" },
+          body: JSON.stringify({ model: "glm-4.7", max_tokens: 1, messages: [{ role: "user", content: "test" }] }),
+        }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403;
+        return { valid, error: valid ? null : "Invalid API key" };
+      }
+      case "minimax":
+      case "minimax-cn": {
+        const endpoints = { minimax: "https://api.minimax.io/anthropic/v1/messages", "minimax-cn": "https://api.minimaxi.com/anthropic/v1/messages" };
+        const res = await fetchWithConnectionProxy(endpoints[connection.provider], {
+          method: "POST",
+          headers: { "x-api-key": connection.apiKey, "anthropic-version": "2023-06-01", "content-type": "application/json" },
+          body: JSON.stringify({ model: "minimax-m2", max_tokens: 1, messages: [{ role: "user", content: "test" }] }),
+        }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403;
+        return { valid, error: valid ? null : "Invalid API key" };
+      }
+      case "kimi": {
+        const res = await fetchWithConnectionProxy("https://api.kimi.com/coding/v1/messages", {
+          method: "POST",
+          headers: { "x-api-key": connection.apiKey, "anthropic-version": "2023-06-01", "content-type": "application/json" },
+          body: JSON.stringify({ model: "kimi-latest", max_tokens: 1, messages: [{ role: "user", content: "test" }] }),
+        }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403;
+        return { valid, error: valid ? null : "Invalid API key" };
+      }
+      case "alicode":
+      case "alicode-intl": {
+        // Aliyun Coding Plan uses OpenAI-compatible API
+        const aliBaseUrl = connection.provider === "alicode-intl"
+          ? "https://coding-intl.dashscope.aliyuncs.com/v1/chat/completions"
+          : "https://coding.dashscope.aliyuncs.com/v1/chat/completions";
+        const res = await fetchWithConnectionProxy(aliBaseUrl, {
+          method: "POST",
+          headers: { "Authorization": `Bearer ${connection.apiKey}`, "content-type": "application/json" },
+          body: JSON.stringify({ model: getDefaultModel(connection.provider), max_tokens: 1, messages: [{ role: "user", content: "test" }] }),
+        }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403;
+        return { valid, error: valid ? null : "Invalid API key" };
+      }
+      case "volcengine-ark":
+      case "byteplus": {
+        const res = await fetchWithConnectionProxy(PROVIDERS[connection.provider]?.baseUrl, {
+          method: "POST",
+          headers: { "Authorization": `Bearer ${connection.apiKey}`, "content-type": "application/json" },
+          body: JSON.stringify({ model: getDefaultModel(connection.provider), max_tokens: 1, messages: [{ role: "user", content: "test" }] }),
+        }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403;
+        return { valid, error: valid ? null : "Invalid API key" };
+      }
+      case "deepseek": {
+        const res = await fetchWithConnectionProxy("https://api.deepseek.com/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "groq": {
+        const res = await fetchWithConnectionProxy("https://api.groq.com/openai/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "mistral": {
+        const res = await fetchWithConnectionProxy("https://api.mistral.ai/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "xai": {
+        const res = await fetchWithConnectionProxy("https://api.x.ai/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "nvidia": {
+        const res = await fetchWithConnectionProxy("https://integrate.api.nvidia.com/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "perplexity": {
+        const res = await fetchWithConnectionProxy("https://api.perplexity.ai/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "together": {
+        const res = await fetchWithConnectionProxy("https://api.together.xyz/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "fireworks": {
+        const res = await fetchWithConnectionProxy("https://api.fireworks.ai/inference/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "cerebras": {
+        const res = await fetchWithConnectionProxy("https://api.cerebras.ai/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "cohere": {
+        const res = await fetchWithConnectionProxy("https://api.cohere.ai/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "nebius": {
+        const res = await fetchWithConnectionProxy("https://api.studio.nebius.ai/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "siliconflow": {
+        const res = await fetchWithConnectionProxy("https://api.siliconflow.com/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "hyperbolic": {
+        const res = await fetchWithConnectionProxy("https://api.hyperbolic.xyz/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "ollama": {
+        const res = await fetch("https://ollama.com/api/tags", { headers: { Authorization: `Bearer ${connection.apiKey}` } });
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "ollama-local": {
+        const host = resolveOllamaLocalHost(connection);
+        const res = await fetch(`${host}/api/tags`);
+        return { valid: res.ok, error: res.ok ? null : `Ollama not reachable at ${host}` };
+      }
+      case "deepgram": {
+        const res = await fetchWithConnectionProxy("https://api.deepgram.com/v1/projects", { headers: { Authorization: `Token ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "assemblyai": {
+        const res = await fetchWithConnectionProxy("https://api.assemblyai.com/v1/account", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "nanobanana": {
+        const res = await fetchWithConnectionProxy("https://api.nanobananaapi.ai/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "fal-ai": {
+        const res = await fetchWithConnectionProxy("https://api.fal.ai/v1/models?limit=1", { headers: { Authorization: `Key ${connection.apiKey}` } }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403;
+        return { valid, error: valid ? null : "Invalid API key" };
+      }
+      case "chutes": {
+        const res = await fetchWithConnectionProxy("https://llm.chutes.ai/v1/models", { headers: { Authorization: `Bearer ${connection.apiKey}` } }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "grok-web": {
+        const token = connection.apiKey.startsWith("sso=") ? connection.apiKey.slice(4) : connection.apiKey;
+        const randomHex = (n) => Array.from(crypto.getRandomValues(new Uint8Array(n)), (b) => b.toString(16).padStart(2, "0")).join("");
+        const statsigId = Buffer.from("e:TypeError: Cannot read properties of null (reading 'children')").toString("base64");
+        const res = await fetchWithConnectionProxy("https://grok.com/rest/app-chat/conversations/new", {
+          method: "POST",
+          headers: {
+            Accept: "*/*", "Content-Type": "application/json",
+            Cookie: `sso=${token}`, Origin: "https://grok.com", Referer: "https://grok.com/",
+            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
+            "x-statsig-id": statsigId, "x-xai-request-id": crypto.randomUUID(),
+            traceparent: `00-${randomHex(16)}-${randomHex(8)}-00`,
+          },
+          body: JSON.stringify({ temporary: true, modelName: "grok-4", message: "ping", fileAttachments: [], imageAttachments: [], disableSearch: false, enableImageGeneration: false, sendFinalMetadata: true }),
+        }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403;
+        return { valid, error: valid ? null : "Invalid SSO cookie" };
+      }
+      case "perplexity-web": {
+        let sessionToken = connection.apiKey;
+        if (sessionToken.startsWith("__Secure-next-auth.session-token=")) sessionToken = sessionToken.slice("__Secure-next-auth.session-token=".length);
+        const res = await fetchWithConnectionProxy("https://www.perplexity.ai/api/auth/session", {
+          method: "GET",
+          headers: {
+            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
+            Cookie: `__Secure-next-auth.session-token=${sessionToken}`,
+          },
+        }, effectiveProxy);
+        if (!res.ok) return { valid: false, error: "Invalid session cookie" };
+        const data = await res.json().catch(() => null);
+        const valid = !!(data && data.user);
+        return { valid, error: valid ? null : "Session expired — re-paste cookie" };
+      }
+      case "opencode-go": {
+        const res = await fetchWithConnectionProxy("https://opencode.ai/zen/go/v1/chat/completions", {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Authorization: `Bearer ${connection.apiKey}` },
+          body: JSON.stringify({ model: getDefaultModel("opencode-go"), messages: [{ role: "user", content: "ping" }], max_tokens: 1, stream: false }),
+        }, effectiveProxy);
+        const valid = res.status !== 401 && res.status !== 403;
+        return { valid, error: valid ? null : "Invalid API key" };
+      }
+      case "xiaomi-mimo":
+      case "xiaomi-tokenplan": {
+        const baseUrls = { "xiaomi-mimo": "https://api.xiaomimimo.com/v1", "xiaomi-tokenplan": "https://token-plan-sgp.xiaomimimo.com/v1" };
+        const res = await fetchWithConnectionProxy(`${baseUrls[connection.provider]}/models`, {
+          headers: { Authorization: `Bearer ${connection.apiKey}` },
+        }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      case "blackbox": {
+        const baseUrl = PROVIDERS["blackbox"]?.baseUrl?.replace(/\/chat\/completions$/, "") || "https://api.blackbox.ai/v1";
+        const res = await fetchWithConnectionProxy(`${baseUrl}/models`, {
+          headers: { Authorization: `Bearer ${connection.apiKey}` },
+        }, effectiveProxy);
+        return { valid: res.ok, error: res.ok ? null : "Invalid API key" };
+      }
+      default:
+        return { valid: false, error: "Provider test not supported" };
+    }
+  } catch (err) {
+    return { valid: false, error: err.message };
+  }
+}
+
+/**
+ * Test a single connection by ID, update DB, and return result.
+ */
+export async function testSingleConnection(id) {
+  const connection = await getProviderConnectionById(id);
+  if (!connection) return { valid: false, error: "Connection not found", latencyMs: 0, testedAt: new Date().toISOString() };
+
+  const effectiveProxy = await resolveConnectionProxyConfig(connection.providerSpecificData || {});
+
+  if (effectiveProxy.connectionProxyEnabled && effectiveProxy.connectionProxyUrl && !effectiveProxy.vercelRelayUrl) {
+    const proxyResult = await testProxyUrl({ proxyUrl: effectiveProxy.connectionProxyUrl });
+    if (!proxyResult.ok) {
+      const proxyError = proxyResult.error || `Proxy test failed with status ${proxyResult.status}`;
+      await updateProviderConnection(id, {
+        testStatus: "error",
+        lastError: proxyError,
+        lastErrorAt: new Date().toISOString(),
+      });
+      return { valid: false, error: proxyError, latencyMs: 0, testedAt: new Date().toISOString() };
+    }
+  }
+
+  const start = Date.now();
+  let result;
+
+  if (connection.authType === "apikey" || connection.authType === "cookie") {
+    result = await testApiKeyConnection(connection, effectiveProxy);
+  } else {
+    result = await testOAuthConnection(connection, effectiveProxy);
+  }
+
+  const latencyMs = Date.now() - start;
+
+  // Soft success (e.g. Grok CLI 402 spending-limit): credentials are good, account is
+  // out of credits. Keep testStatus active; surface the message as lastError so the
+  // dashboard can show a warning without marking the connection broken.
+  const softWarning = result.valid && (result.warning || result.error);
+  const updateData = {
+    testStatus: result.valid ? "active" : "error",
+    lastError: result.valid ? (softWarning || null) : result.error,
+    lastErrorAt: result.valid
+      ? softWarning
+        ? new Date().toISOString()
+        : null
+      : new Date().toISOString(),
+  };
+
+  if (result.refreshed && result.newTokens) {
+    if (result.newTokens.accessToken) updateData.accessToken = result.newTokens.accessToken;
+    if (result.newTokens.refreshToken) updateData.refreshToken = result.newTokens.refreshToken;
+    if (result.newTokens.idToken) updateData.idToken = result.newTokens.idToken;
+    if (result.newTokens.lastRefreshAt) updateData.lastRefreshAt = result.newTokens.lastRefreshAt;
+    if (result.newTokens.expiresIn) updateData.expiresIn = result.newTokens.expiresIn;
+    if (result.newTokens.expiresIn) {
+      updateData.expiresAt = new Date(Date.now() + result.newTokens.expiresIn * 1000).toISOString();
+    } else if (result.newTokens.expiresAt) {
+      updateData.expiresAt = result.newTokens.expiresAt;
+    }
+    if (result.newTokens.providerSpecificData) {
+      updateData.providerSpecificData = {
+        ...(connection.providerSpecificData || {}),
+        ...result.newTokens.providerSpecificData,
+      };
+    }
+  }
+
+  await updateProviderConnection(id, updateData);
+
+  return { valid: result.valid, error: result.error, refreshed: !!result.refreshed, latencyMs, testedAt: new Date().toISOString() };
+}
diff --git a/src/app/api/providers/client/route.js b/src/app/api/providers/client/route.js
new file mode 100644
index 0000000..be5342c
--- /dev/null
+++ b/src/app/api/providers/client/route.js
@@ -0,0 +1,127 @@
+import { NextResponse } from "next/server";
+import { getProviderConnections } from "@/lib/localDb";
+import { backfillCodexEmails } from "@/lib/oauth/providers";
+import { USAGE_APIKEY_PROVIDERS, USAGE_SUPPORTED_PROVIDERS } from "@/shared/constants/providers";
+
+const SAFE_FIELDS = [
+  "id", "provider", "authType", "name", "email", "displayName",
+  "priority", "globalPriority", "isActive", "defaultModel",
+  "testStatus", "lastError", "lastErrorAt", "errorCode",
+  "expiresAt", "lastUsedAt", "consecutiveUseCount",
+  "createdAt", "updatedAt",
+];
+
+const SAFE_PSD_FIELDS = [
+  "baseUrl", "azureEndpoint", "deployment", "apiVersion", "accountId",
+  "region", "projectId", "resourceUrl", "proxyPoolId",
+  "connectionProxyEnabled", "connectionProxyUrl", "connectionNoProxy",
+  "githubLogin", "githubName", "githubEmail", "githubUserId",
+  "username", "firstName", "lastName", "authMethod", "authKind",
+  "profileArn",
+];
+
+const DEFAULT_PAGE_SIZE = 20;
+const MAX_PAGE_SIZE = 500;
+
+function maskName(name) {
+  if (typeof name !== "string" || name.length <= 16) return name;
+  if (/[a-zA-Z0-9_-]{32,}/.test(name)) return `${name.slice(0, 8)}***`;
+  return name;
+}
+
+function sanitize(c) {
+  const safe = {};
+  for (const f of SAFE_FIELDS) if (c[f] !== undefined) safe[f] = c[f];
+  if (safe.name) safe.name = maskName(safe.name);
+  if (c.providerSpecificData) {
+    const psd = {};
+    for (const f of SAFE_PSD_FIELDS) {
+      if (c.providerSpecificData[f] !== undefined) psd[f] = c.providerSpecificData[f];
+    }
+    safe.providerSpecificData = psd;
+  }
+  return safe;
+}
+
+function isUsageEligible(connection) {
+  return USAGE_SUPPORTED_PROVIDERS.includes(connection.provider) && (
+    connection.authType === "oauth" || USAGE_APIKEY_PROVIDERS.includes(connection.provider)
+  );
+}
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function sortConnections(connections, sort) {
+  const list = [...connections];
+
+  if (sort === "provider") {
+    return list.sort((a, b) => {
+      const orderA = USAGE_SUPPORTED_PROVIDERS.indexOf(a.provider);
+      const orderB = USAGE_SUPPORTED_PROVIDERS.indexOf(b.provider);
+      if (orderA !== orderB) return orderA - orderB;
+      return a.provider.localeCompare(b.provider);
+    });
+  }
+
+  return list.sort((a, b) => {
+    const priorityA = a.priority ?? Number.MAX_SAFE_INTEGER;
+    const priorityB = b.priority ?? Number.MAX_SAFE_INTEGER;
+    if (priorityA !== priorityB) return priorityA - priorityB;
+    return (a.provider || "").localeCompare(b.provider || "");
+  });
+}
+
+export async function GET(request) {
+  try {
+    await backfillCodexEmails();
+
+    const { searchParams } = new URL(request.url);
+    const provider = searchParams.get("provider") || "all";
+    const accountStatus = searchParams.get("accountStatus") || "all";
+    const sort = searchParams.get("sort") || "priority";
+    const page = parsePositiveInt(searchParams.get("page"), 1);
+    const pageSize = Math.min(parsePositiveInt(searchParams.get("pageSize"), DEFAULT_PAGE_SIZE), MAX_PAGE_SIZE);
+
+    const allConnections = await getProviderConnections();
+    const eligibleConnections = allConnections.filter(isUsageEligible);
+    const providerOptions = Array.from(new Set(eligibleConnections.map((conn) => conn.provider))).sort();
+
+    const providerFilteredConnections = eligibleConnections.filter((conn) => (
+      provider === "all" || conn.provider === provider
+    ));
+
+    const accountFilteredConnections = providerFilteredConnections.filter((conn) => {
+      if (accountStatus === "active") return conn.isActive ?? true;
+      if (accountStatus === "inactive") return !(conn.isActive ?? true);
+      return true;
+    });
+
+    const sortedConnections = sortConnections(accountFilteredConnections, sort);
+    const total = sortedConnections.length;
+    const totalPages = Math.max(1, Math.ceil(total / pageSize));
+    const currentPage = Math.min(page, totalPages);
+    const offset = (currentPage - 1) * pageSize;
+    const pageConnections = sortedConnections.slice(offset, offset + pageSize).map(sanitize);
+
+    return NextResponse.json({
+      connections: pageConnections,
+      providerOptions,
+      pagination: {
+        page: currentPage,
+        pageSize,
+        total,
+        totalPages,
+      },
+      totals: {
+        eligibleConnections: eligibleConnections.length,
+        providerFilteredConnections: providerFilteredConnections.length,
+      },
+    });
+  } catch (error) {
+    console.log("Error fetching providers for client:", error);
+    return NextResponse.json({ error: "Failed to fetch providers" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/providers/kilo/free-models/route.js b/src/app/api/providers/kilo/free-models/route.js
new file mode 100644
index 0000000..784b459
--- /dev/null
+++ b/src/app/api/providers/kilo/free-models/route.js
@@ -0,0 +1,55 @@
+import { NextResponse } from "next/server";
+
+const KILO_MODELS_URL = "https://api.kilo.ai/api/gateway/models";
+
+// In-memory cache with TTL
+let cachedModels = null;
+let cacheTimestamp = 0;
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+export async function GET() {
+  const now = Date.now();
+
+  // Return cached result if still valid
+  if (cachedModels && now - cacheTimestamp < CACHE_TTL_MS) {
+    return NextResponse.json({ models: cachedModels, cached: true });
+  }
+
+  try {
+    const res = await fetch(KILO_MODELS_URL, {
+      headers: { "Accept": "application/json" },
+      signal: AbortSignal.timeout(10000),
+    });
+
+    if (!res.ok) {
+      throw new Error(`Kilo API returned ${res.status}`);
+    }
+
+    const json = await res.json();
+    const allModels = json.data || [];
+
+    const freeModels = allModels
+      .filter((m) => m.isFree === true)
+      .map((m) => ({
+        id: m.id,
+        name: m.name,
+        isFree: true,
+        context_length: m.context_length || 0,
+      }));
+
+    cachedModels = freeModels;
+    cacheTimestamp = now;
+
+    return NextResponse.json({ models: freeModels, cached: false });
+  } catch (error) {
+    // Return cached data if available, even if expired
+    if (cachedModels) {
+      return NextResponse.json({ models: cachedModels, cached: true, warning: error.message });
+    }
+
+    return NextResponse.json(
+      { models: [], error: `Failed to fetch Kilo models: ${error.message}` },
+      { status: 502 }
+    );
+  }
+}
diff --git a/src/app/api/providers/route.js b/src/app/api/providers/route.js
new file mode 100644
index 0000000..5885472
--- /dev/null
+++ b/src/app/api/providers/route.js
@@ -0,0 +1,197 @@
+import { NextResponse } from "next/server";
+import {
+  getProviderConnections,
+  createProviderConnection,
+  getProviderNodeById,
+  getProviderNodes,
+  getProxyPoolById,
+} from "@/models";
+import { APIKEY_PROVIDERS } from "@/shared/constants/config";
+import { AI_PROVIDERS, FREE_TIER_PROVIDERS, WEB_COOKIE_PROVIDERS, isOpenAICompatibleProvider, isAnthropicCompatibleProvider, isCustomEmbeddingProvider } from "@/shared/constants/providers";
+import { normalizeProviderId, normalizeProviderSpecificData } from "@/lib/providerNormalization";
+
+export const dynamic = "force-dynamic";
+
+function normalizeProxyConfig(body = {}) {
+  const enabled = body?.connectionProxyEnabled === true;
+  const url = typeof body?.connectionProxyUrl === "string" ? body.connectionProxyUrl.trim() : "";
+  const noProxy = typeof body?.connectionNoProxy === "string" ? body.connectionNoProxy.trim() : "";
+
+  if (enabled && !url) {
+    return { error: "Connection proxy URL is required when connection proxy is enabled" };
+  }
+
+  return {
+    connectionProxyEnabled: enabled,
+    connectionProxyUrl: url,
+    connectionNoProxy: noProxy,
+  };
+}
+
+async function normalizeProxyPoolId(proxyPoolId) {
+  if (proxyPoolId === undefined || proxyPoolId === null || proxyPoolId === "" || proxyPoolId === "__none__") {
+    return { proxyPoolId: null };
+  }
+
+  const normalizedId = String(proxyPoolId).trim();
+  if (!normalizedId) {
+    return { proxyPoolId: null };
+  }
+
+  const proxyPool = await getProxyPoolById(normalizedId);
+  if (!proxyPool) {
+    return { error: "Proxy pool not found" };
+  }
+
+  return { proxyPoolId: normalizedId };
+}
+
+// GET /api/providers - List all connections
+export async function GET() {
+  try {
+    const connections = await getProviderConnections();
+
+    // Build nodeNameMap for compatible providers (id → name)
+    let nodeNameMap = {};
+    try {
+      const nodes = await getProviderNodes();
+      for (const node of nodes) {
+        if (node.id && node.name) nodeNameMap[node.id] = node.name;
+      }
+    } catch { }
+
+    // Hide sensitive fields, enrich name for compatible providers
+    const safeConnections = connections.map(c => {
+      const isCompatible = isOpenAICompatibleProvider(c.provider) || isAnthropicCompatibleProvider(c.provider);
+      const name = isCompatible
+        ? (c.name || nodeNameMap[c.provider] || c.providerSpecificData?.nodeName || c.provider)
+        : c.name;
+      return {
+        ...c,
+        name,
+        apiKey: undefined,
+        accessToken: undefined,
+        refreshToken: undefined,
+        idToken: undefined,
+      };
+    });
+
+    return NextResponse.json({ connections: safeConnections });
+  } catch (error) {
+    console.log("Error fetching providers:", error);
+    return NextResponse.json({ error: "Failed to fetch providers" }, { status: 500 });
+  }
+}
+
+// POST /api/providers - Create new connection (API Key only, OAuth via separate flow)
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const provider = normalizeProviderId(body.provider);
+    const { apiKey, name, displayName, priority, globalPriority, defaultModel, testStatus } = body;
+    const proxyConfig = normalizeProxyConfig(body);
+    if (proxyConfig.error) {
+      return NextResponse.json({ error: proxyConfig.error }, { status: 400 });
+    }
+
+    const proxyPoolResult = await normalizeProxyPoolId(body.proxyPoolId);
+    if (proxyPoolResult.error) {
+      return NextResponse.json({ error: proxyPoolResult.error }, { status: 400 });
+    }
+    const proxyPoolId = proxyPoolResult.proxyPoolId;
+
+    // Validation
+    const isWebCookieProvider = !!WEB_COOKIE_PROVIDERS[provider];
+    // Dual-auth providers (e.g. codebuddy-cn, xai) live under category "oauth" but also
+    // accept an API key via authModes — they aren't in APIKEY_PROVIDERS, so allow them here.
+    const supportsApiKeyMode = !!AI_PROVIDERS[provider]?.authModes?.includes("apikey");
+    const isValidProvider = APIKEY_PROVIDERS[provider] ||
+      FREE_TIER_PROVIDERS[provider] ||
+      supportsApiKeyMode ||
+      isWebCookieProvider ||
+      isOpenAICompatibleProvider(provider) ||
+      isAnthropicCompatibleProvider(provider) ||
+      isCustomEmbeddingProvider(provider);
+
+    if (!provider || !isValidProvider) {
+      return NextResponse.json({ error: "Invalid provider" }, { status: 400 });
+    }
+    if (!apiKey && provider !== "ollama-local") {
+      return NextResponse.json({ error: `${isWebCookieProvider ? "Cookie value" : "API Key"} is required` }, { status: 400 });
+    }
+    const connectionName = name || displayName || AI_PROVIDERS[provider]?.name;
+    if (!connectionName) {
+      return NextResponse.json({ error: "Name is required" }, { status: 400 });
+    }
+
+    let providerSpecificData = normalizeProviderSpecificData(provider, body, body.providerSpecificData);
+
+    // Compatible LLM nodes support multiple API-key connections (key pool); runtime
+    // rotates/fails over via getProviderCredentials. Embedding nodes stay single-connection.
+    if (isOpenAICompatibleProvider(provider)) {
+      const node = await getProviderNodeById(provider);
+      if (!node) {
+        return NextResponse.json({ error: "OpenAI Compatible node not found" }, { status: 404 });
+      }
+      providerSpecificData = {
+        prefix: node.prefix,
+        apiType: node.apiType,
+        baseUrl: node.baseUrl,
+        nodeName: node.name,
+      };
+    } else if (isAnthropicCompatibleProvider(provider)) {
+      const node = await getProviderNodeById(provider);
+      if (!node) {
+        return NextResponse.json({ error: "Anthropic Compatible node not found" }, { status: 404 });
+      }
+      providerSpecificData = {
+        prefix: node.prefix,
+        baseUrl: node.baseUrl,
+        nodeName: node.name,
+      };
+    } else if (isCustomEmbeddingProvider(provider)) {
+      const node = await getProviderNodeById(provider);
+      if (!node) {
+        return NextResponse.json({ error: "Custom Embedding node not found" }, { status: 404 });
+      }
+      providerSpecificData = {
+        prefix: node.prefix,
+        baseUrl: node.baseUrl,
+        nodeName: node.name,
+      };
+    }
+
+    const mergedProviderSpecificData = {
+      ...(providerSpecificData || {}),
+      connectionProxyEnabled: proxyConfig.connectionProxyEnabled,
+      connectionProxyUrl: proxyConfig.connectionProxyUrl,
+      connectionNoProxy: proxyConfig.connectionNoProxy,
+    };
+
+    if (proxyPoolId !== null) {
+      mergedProviderSpecificData.proxyPoolId = proxyPoolId;
+    }
+
+    const newConnection = await createProviderConnection({
+      provider,
+      authType: isWebCookieProvider ? "cookie" : "apikey",
+      name: connectionName,
+      apiKey: apiKey || "",
+      priority: priority || 1,
+      globalPriority: globalPriority || null,
+      defaultModel: defaultModel || null,
+      providerSpecificData: mergedProviderSpecificData,
+      isActive: true,
+      testStatus: testStatus || "unknown",
+    });
+
+    // Hide sensitive fields
+    const result = { ...newConnection };
+    delete result.apiKey;
+
+    return NextResponse.json({ connection: result }, { status: 201 });
+  } catch (error) {
+    console.log("Error creating provider:", error);
+    return NextResponse.json({ error: "Failed to create provider" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/providers/suggested-models/filters.js b/src/app/api/providers/suggested-models/filters.js
new file mode 100644
index 0000000..8299f46
--- /dev/null
+++ b/src/app/api/providers/suggested-models/filters.js
@@ -0,0 +1,26 @@
+// Free OpenCode models that don't use the "-free" id suffix
+const KNOWN_FREE_OPENCODE_MODELS = ["big-pickle"];
+
+export const FILTERS = {
+  "openrouter-free": (models) =>
+    models
+      .filter(
+        (m) =>
+          m.pricing?.prompt === "0" &&
+          m.pricing?.completion === "0" &&
+          m.context_length >= 200000
+      )
+      .map((m) => ({ id: m.id, name: m.name, contextLength: m.context_length }))
+      .sort((a, b) => b.contextLength - a.contextLength),
+
+  "opencode-free": (models) =>
+    models
+      .filter((m) => m.id?.endsWith("-free") || KNOWN_FREE_OPENCODE_MODELS.includes(m.id))
+      .map((m) => ({ id: m.id, name: m.id })),
+
+  // models.dev returns a large catalog; keep only mimo models
+  "mimo-free": (models) =>
+    (Array.isArray(models) ? models : [])
+      .filter((m) => m.id?.startsWith("mimo") || m.name?.toLowerCase().includes("mimo"))
+      .map((m) => ({ id: m.id, name: m.name || m.id })),
+};
diff --git a/src/app/api/providers/suggested-models/route.js b/src/app/api/providers/suggested-models/route.js
new file mode 100644
index 0000000..c14f70c
--- /dev/null
+++ b/src/app/api/providers/suggested-models/route.js
@@ -0,0 +1,32 @@
+import { NextResponse } from "next/server";
+import { FILTERS } from "./filters.js";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(request) {
+  const { searchParams } = new URL(request.url);
+  const url = searchParams.get("url");
+  const type = searchParams.get("type");
+
+  if (!url || !type) {
+    return NextResponse.json({ error: "Missing url or type" }, { status: 400 });
+  }
+
+  const filter = FILTERS[type];
+  if (!filter) {
+    return NextResponse.json({ error: "Unknown filter type" }, { status: 400 });
+  }
+
+  try {
+    const res = await fetch(url);
+    if (!res.ok) {
+      return NextResponse.json({ data: [] });
+    }
+    const json = await res.json();
+    const raw = json.data ?? json.models ?? json;
+    const data = filter(Array.isArray(raw) ? raw : []);
+    return NextResponse.json({ data });
+  } catch {
+    return NextResponse.json({ data: [] });
+  }
+}
diff --git a/src/app/api/providers/test-batch/route.js b/src/app/api/providers/test-batch/route.js
new file mode 100644
index 0000000..da020cc
--- /dev/null
+++ b/src/app/api/providers/test-batch/route.js
@@ -0,0 +1,131 @@
+import { NextResponse } from "next/server";
+import { getProviderConnections } from "@/models";
+import {
+  FREE_PROVIDERS,
+  OAUTH_PROVIDERS,
+  APIKEY_PROVIDERS,
+  OPENAI_COMPATIBLE_PREFIX,
+  ANTHROPIC_COMPATIBLE_PREFIX,
+} from "@/shared/constants/providers";
+import { testSingleConnection } from "../[id]/test/testUtils.js";
+
+function getAuthGroup(providerId, connection = null) {
+  // Prioritize authType from connection if available
+  if (connection?.authType) {
+    if (connection.authType === "oauth") {
+      // Check if it's a free provider
+      if (FREE_PROVIDERS[providerId]) return "free";
+      return "oauth";
+    }
+    return connection.authType;
+  }
+  
+  // Fallback to constants
+  if (FREE_PROVIDERS[providerId]) return "free";
+  if (OAUTH_PROVIDERS[providerId]) return "oauth";
+  if (APIKEY_PROVIDERS[providerId]) return "apikey";
+  if (
+    typeof providerId === "string" &&
+    (providerId.startsWith(OPENAI_COMPATIBLE_PREFIX) || providerId.startsWith(ANTHROPIC_COMPATIBLE_PREFIX))
+  )
+    return "compatible";
+  return "apikey";
+}
+
+function isCompatibleProvider(providerId) {
+  return (
+    typeof providerId === "string" &&
+    (providerId.startsWith(OPENAI_COMPATIBLE_PREFIX) || providerId.startsWith(ANTHROPIC_COMPATIBLE_PREFIX))
+  );
+}
+
+// POST /api/providers/test-batch - Test multiple connections by group
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const { mode, providerId } = body;
+
+    if (!mode) {
+      return NextResponse.json({ error: "mode is required" }, { status: 400 });
+    }
+
+    const allConnections = await getProviderConnections({ isActive: true });
+
+    let connectionsToTest = [];
+    if (mode === "provider" && providerId) {
+      connectionsToTest = allConnections.filter((c) => c.provider === providerId);
+    } else if (mode === "oauth") {
+      connectionsToTest = allConnections.filter((c) => getAuthGroup(c.provider, c) === "oauth");
+    } else if (mode === "free") {
+      connectionsToTest = allConnections.filter((c) => getAuthGroup(c.provider, c) === "free");
+    } else if (mode === "apikey") {
+      connectionsToTest = allConnections.filter((c) => getAuthGroup(c.provider, c) === "apikey");
+    } else if (mode === "compatible") {
+      connectionsToTest = allConnections.filter((c) => isCompatibleProvider(c.provider));
+    } else if (mode === "all") {
+      connectionsToTest = allConnections;
+    } else {
+      return NextResponse.json(
+        { error: "Invalid mode. Use: provider, oauth, free, apikey, compatible, all" },
+        { status: 400 }
+      );
+    }
+
+    if (connectionsToTest.length === 0) {
+      return NextResponse.json({
+        mode,
+        providerId: providerId || null,
+        results: [],
+        summary: { total: 0, passed: 0, failed: 0 },
+        testedAt: new Date().toISOString(),
+      });
+    }
+
+    const results = [];
+    for (const conn of connectionsToTest) {
+      try {
+        const data = await testSingleConnection(conn.id);
+        results.push({
+          provider: conn.provider,
+          connectionId: conn.id,
+          connectionName: conn.name || conn.email || conn.provider,
+          authType: conn.authType || getAuthGroup(conn.provider, conn),
+          valid: data.valid,
+          latencyMs: data.latencyMs || 0,
+          error: data.error || null,
+          diagnosis: data.diagnosis || null,
+          statusCode: data.statusCode || null,
+          testedAt: data.testedAt || new Date().toISOString(),
+        });
+      } catch (error) {
+        results.push({
+          provider: conn.provider,
+          connectionId: conn.id,
+          connectionName: conn.name || conn.email || conn.provider,
+          authType: conn.authType || getAuthGroup(conn.provider, conn),
+          valid: false,
+          latencyMs: 0,
+          error: error.message,
+          diagnosis: { type: "network_error", source: "local", code: null, message: error.message },
+          statusCode: null,
+          testedAt: new Date().toISOString(),
+        });
+      }
+    }
+
+    return NextResponse.json({
+      mode,
+      providerId: providerId || null,
+      results,
+      testedAt: new Date().toISOString(),
+      summary: {
+        total: results.length,
+        passed: results.filter((r) => r.valid).length,
+        failed: results.filter((r) => !r.valid).length,
+      },
+    });
+  } catch (error) {
+    console.log("Error in batch test:", error);
+    return NextResponse.json({ error: "Batch test failed" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/providers/validate/route.js b/src/app/api/providers/validate/route.js
new file mode 100644
index 0000000..d568409
--- /dev/null
+++ b/src/app/api/providers/validate/route.js
@@ -0,0 +1,634 @@
+import { NextResponse } from "next/server";
+import { getProviderNodeById } from "@/models";
+import { isOpenAICompatibleProvider, isAnthropicCompatibleProvider, isCustomEmbeddingProvider, AI_PROVIDERS } from "@/shared/constants/providers";
+import { getDefaultModel } from "open-sse/config/providerModels.js";
+import { resolveOllamaLocalHost, resolveXiaomiTokenplanBaseUrl, PROVIDERS } from "open-sse/config/providers.js";
+import { openaiToCommandCodeRequest } from "open-sse/translator/request/openai-to-commandcode.js";
+import { normalizeProviderId } from "@/lib/providerNormalization";
+
+// Probe a webSearch/webFetch provider using its searchConfig/fetchConfig.
+// Returns true if API key is accepted (status !== 401 && !== 403).
+async function probeWebProvider(provider, apiKey) {
+  const p = AI_PROVIDERS[provider];
+  if (!p) return null;
+  // Skip if provider has dual-purpose (LLM + search), let LLM validate handle it
+  const kinds = p.serviceKinds || ["llm"];
+  const isWebOnly = kinds.every((k) => k === "webSearch" || k === "webFetch");
+  if (!isWebOnly) return null;
+  const cfg = p.searchConfig || p.fetchConfig;
+  if (!cfg) return null;
+  if (cfg.authType === "none") return true; // no-auth (e.g. searxng)
+
+  let url = cfg.baseUrl;
+  const headers = { "Content-Type": "application/json" };
+  let body;
+
+  // Apply auth based on authHeader
+  switch (cfg.authHeader) {
+    case "bearer":              headers["Authorization"] = `Bearer ${apiKey}`; break;
+    case "x-api-key":           headers["x-api-key"] = apiKey; break;
+    case "x-subscription-token":headers["x-subscription-token"] = apiKey; break;
+    case "key":                 url += `?key=${encodeURIComponent(apiKey)}&q=ping&cx=test`; break; // google-pse
+    case "api_key":             url += `?api_key=${encodeURIComponent(apiKey)}&q=ping&engine=google`; break; // searchapi
+  }
+
+  // Minimal body for POST endpoints; GET sends nothing
+  if (cfg.method === "POST") {
+    body = JSON.stringify({ query: "ping", q: "ping", url: "https://example.com" });
+  }
+
+  const res = await fetch(url, { method: cfg.method, headers, body, signal: AbortSignal.timeout(8000) });
+  return res.status !== 401 && res.status !== 403;
+}
+
+// Probe a media provider (tts/embedding/stt/image/video) using *Config.
+// Returns true if API key is accepted; null to skip (let default handler decide).
+async function probeMediaProvider(provider, apiKey) {
+  const p = AI_PROVIDERS[provider];
+  if (!p) return null;
+  const MEDIA_KINDS = new Set(["tts", "embedding", "stt", "image", "video", "music", "imageToText"]);
+  const kinds = p.serviceKinds || ["llm"];
+  const isMediaOnly = kinds.every((k) => MEDIA_KINDS.has(k));
+  if (!isMediaOnly) return null;
+  const cfg = p.ttsConfig || p.sttConfig || p.embeddingConfig || p.imageConfig || p.videoConfig || p.musicConfig;
+  // No probe config → best-effort accept (validate at usage time)
+  if (!cfg) return true;
+  if (p.noAuth || cfg.authType === "none") return true;
+  // Skip auth schemes that need provider-specific data
+  if (cfg.authHeader === "playht" || cfg.authHeader === "aws-sigv4") return true;
+
+  const headers = { "Content-Type": "application/json", ...(cfg.extraHeaders || {}) };
+
+  switch (cfg.authHeader) {
+    case "bearer":     headers["Authorization"] = `Bearer ${apiKey}`; break;
+    case "key":        headers["Authorization"] = `Key ${apiKey}`; break;
+    case "x-api-key":  headers["x-api-key"] = apiKey; break;
+    case "x-key":      headers["x-key"] = apiKey; break;
+    case "xi-api-key": headers["xi-api-key"] = apiKey; break;
+    case "token":      headers["Authorization"] = `Token ${apiKey}`; break;
+    case "basic":      headers["Authorization"] = `Basic ${apiKey}`; break;
+    default: return null;
+  }
+
+  const method = cfg.method || "POST";
+  const res = await fetch(cfg.baseUrl, {
+    method,
+    headers,
+    body: method === "GET" ? undefined : JSON.stringify({ input: "ping", text: "ping", prompt: "ping", model: getDefaultModel(provider) || "test" }),
+    signal: AbortSignal.timeout(8000),
+  });
+  return res.status !== 401 && res.status !== 403;
+}
+
+// POST /api/providers/validate - Validate API key with provider
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const provider = normalizeProviderId(body.provider);
+    const { apiKey, providerSpecificData } = body;
+
+    const isNoAuth = AI_PROVIDERS[provider]?.noAuth === true;
+    if (!provider || (!apiKey && provider !== "ollama-local" && !isNoAuth)) {
+      return NextResponse.json({ error: "Provider and API key required" }, { status: 400 });
+    }
+
+    let isValid = false;
+    let error = null;
+
+    // Validate with each provider
+    try {
+      if (isOpenAICompatibleProvider(provider)) {
+        const node = await getProviderNodeById(provider);
+        if (!node) {
+          return NextResponse.json({ error: "OpenAI Compatible node not found" }, { status: 404 });
+        }
+        const modelsUrl = `${node.baseUrl?.replace(/\/$/, "")}/models`;
+        const res = await fetch(modelsUrl, {
+          headers: { "Authorization": `Bearer ${apiKey}` },
+        });
+        isValid = res.ok;
+        return NextResponse.json({
+          valid: isValid,
+          error: isValid ? null : "Invalid API key",
+        });
+      }
+
+      // Custom Embedding nodes: probe /models (most embedding APIs are OpenAI-compatible)
+      if (isCustomEmbeddingProvider(provider)) {
+        const node = await getProviderNodeById(provider);
+        if (!node) {
+          return NextResponse.json({ error: "Custom Embedding node not found" }, { status: 404 });
+        }
+        const baseUrl = node.baseUrl?.replace(/\/$/, "");
+        const modelsRes = await fetch(`${baseUrl}/models`, {
+          headers: { "Authorization": `Bearer ${apiKey}` },
+        });
+        if (modelsRes.ok) {
+          return NextResponse.json({ valid: true });
+        }
+        // Auth errors are definitive
+        if (modelsRes.status === 401 || modelsRes.status === 403) {
+          return NextResponse.json({ valid: false, error: "Invalid API key" });
+        }
+        // Fallback: probe /embeddings with a common test model — many providers lack /models
+        const embedRes = await fetch(`${baseUrl}/embeddings`, {
+          method: "POST",
+          headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" },
+          body: JSON.stringify({ model: "test", input: "ping" }),
+        });
+        // 401/403 = bad key; anything else (including 400 "model not found") means key works
+        isValid = embedRes.status !== 401 && embedRes.status !== 403;
+        return NextResponse.json({
+          valid: isValid,
+          error: isValid ? null : "Invalid API key",
+        });
+      }
+
+      if (isAnthropicCompatibleProvider(provider)) {
+        const node = await getProviderNodeById(provider);
+        if (!node) {
+          return NextResponse.json({ error: "Anthropic Compatible node not found" }, { status: 404 });
+        }
+
+        let normalizedBase = node.baseUrl?.trim().replace(/\/$/, "") || "";
+        if (normalizedBase.endsWith("/messages")) {
+          normalizedBase = normalizedBase.slice(0, -9); // remove /messages
+        }
+
+        const messagesUrl = `${normalizedBase}/v1/messages`;
+        const model = node.defaultModel || "claude-3-haiku-20240307";
+
+        const res = await fetch(messagesUrl, {
+          method: "POST",
+          headers: {
+            "x-api-key": apiKey,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+            "Authorization": `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            model,
+            max_tokens: 1,
+            messages: [{ role: "user", content: "test" }],
+          }),
+        });
+
+        // 400/529 still confirms key accepted; only 401/403 = bad key
+        isValid = res.status !== 401 && res.status !== 403;
+        return NextResponse.json({
+          valid: isValid,
+          error: isValid ? null : "Invalid API key",
+        });
+      }
+
+      if (provider === "cloudflare-ai") {
+        const { providerSpecificData } = body;
+        const accountId = providerSpecificData?.accountId;
+        if (!accountId) {
+          return NextResponse.json({ valid: false, error: "Missing Account ID" });
+        }
+        const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1/chat/completions`;
+        const cfRes = await fetch(url, {
+          method: "POST",
+          headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" },
+          body: JSON.stringify({
+            model: getDefaultModel("cloudflare-ai"),
+            messages: [{ role: "user", content: "test" }],
+            max_tokens: 1,
+          }),
+        });
+        isValid = cfRes.status !== 401 && cfRes.status !== 403 && cfRes.status !== 404;
+        return NextResponse.json({
+          valid: isValid,
+          error: isValid ? null : "Invalid API token or Account ID",
+        });
+      }
+
+      if (provider === "azure") {
+        const { providerSpecificData } = body;
+        const endpoint = (providerSpecificData?.azureEndpoint || "").replace(/\/$/, "");
+        const deployment = providerSpecificData?.deployment || "gpt-4";
+        const apiVersion = providerSpecificData?.apiVersion || "2024-10-01-preview";
+        const organization = providerSpecificData?.organization;
+
+        const url = `${endpoint}/openai/deployments/${deployment}/chat/completions?api-version=${apiVersion}`;
+        const headers = {
+          "api-key": apiKey,
+          "Content-Type": "application/json",
+        };
+        if (organization) headers["OpenAI-Organization"] = organization;
+
+        const azureRes = await fetch(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            messages: [{ role: "user", content: "test" }],
+            max_tokens: 1,
+          }),
+        });
+        isValid = azureRes.status !== 401 && azureRes.status !== 403;
+        return NextResponse.json({
+          valid: isValid,
+          error: isValid ? null : "Invalid API key or Azure configuration",
+        });
+      }
+
+      // Generic probe for webSearch/webFetch providers (config-driven)
+      const webResult = await probeWebProvider(provider, apiKey);
+      if (webResult !== null) {
+        return NextResponse.json({
+          valid: webResult,
+          error: webResult ? null : "Invalid API key",
+        });
+      }
+
+      // Generic probe for tts/embedding providers (config-driven)
+      const mediaResult = await probeMediaProvider(provider, apiKey);
+      if (mediaResult !== null) {
+        return NextResponse.json({
+          valid: mediaResult,
+          error: mediaResult ? null : "Invalid API key",
+        });
+      }
+
+      switch (provider) {
+        case "openai":
+          const openaiRes = await fetch("https://api.openai.com/v1/models", {
+            headers: { "Authorization": `Bearer ${apiKey}` },
+          });
+          isValid = openaiRes.ok;
+          break;
+
+        case "vercel-ai-gateway":
+          const vercelAiGatewayRes = await fetch("https://ai-gateway.vercel.sh/v1/models", {
+            headers: { "Authorization": `Bearer ${apiKey}` },
+          });
+          isValid = vercelAiGatewayRes.ok;
+          break;
+
+        case "anthropic":
+          const anthropicRes = await fetch("https://api.anthropic.com/v1/messages", {
+            method: "POST",
+            headers: {
+              "x-api-key": apiKey,
+              "anthropic-version": "2023-06-01",
+              "content-type": "application/json",
+            },
+            body: JSON.stringify({
+              model: "claude-3-haiku-20240307",
+              max_tokens: 1,
+              messages: [{ role: "user", content: "test" }],
+            }),
+          });
+          isValid = anthropicRes.status !== 401;
+          break;
+
+        case "gemini":
+          const geminiRes = await fetch(`https://generativelanguage.googleapis.com/v1/models?key=${apiKey}`);
+          isValid = geminiRes.ok;
+          break;
+
+        case "openrouter":
+          const openrouterRes = await fetch("https://openrouter.ai/api/v1/models", {
+            headers: { "Authorization": `Bearer ${apiKey}` },
+          });
+          isValid = openrouterRes.ok;
+          break;
+
+        case "glm":
+        case "glm-cn":
+        case "kimi":
+        case "minimax":
+        case "minimax-cn":
+        case "alicode-intl":
+        case "alicode":
+        case "agentrouter": {
+          // Use baseUrl from PROVIDERS (DRY); separate openai-format vs claude-format flow
+          const cfg = PROVIDERS[provider];
+          const isOpenAiFormat = provider === "glm-cn" || provider === "alicode" || provider === "alicode-intl";
+
+          if (isOpenAiFormat) {
+            const testModel = getDefaultModel(provider);
+            const res = await fetch(cfg.baseUrl, {
+              method: "POST",
+              headers: { "Authorization": `Bearer ${apiKey}`, "content-type": "application/json" },
+              body: JSON.stringify({ model: testModel, max_tokens: 1, messages: [{ role: "user", content: "test" }] }),
+            });
+            isValid = res.status !== 401 && res.status !== 403;
+          } else {
+            const testModel = getDefaultModel(provider) || "claude-sonnet-4-20250514";
+            const res = await fetch(cfg.baseUrl, {
+              method: "POST",
+              headers: {
+                "x-api-key": apiKey,
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+                ...(cfg.headers || {}),
+              },
+              body: JSON.stringify({ model: testModel, max_tokens: 1, messages: [{ role: "user", content: "test" }] }),
+            });
+            // 400 = model resolution error but auth passed (e.g. agentrouter "no available channel")
+            isValid = res.status !== 401 && res.status !== 403;
+          }
+          break;
+        }
+        case "volcengine-ark":
+        case "byteplus": {
+          const res = await fetch(PROVIDERS[provider]?.baseUrl, {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${apiKey}`,
+              "content-type": "application/json",
+            },
+            body: JSON.stringify({
+              model: getDefaultModel(provider),
+              max_tokens: 1,
+              messages: [{ role: "user", content: "test" }],
+            }),
+          });
+          isValid = res.status !== 401 && res.status !== 403;
+          break;
+        }
+
+        case "deepseek":
+        case "groq":
+        case "xai":
+        case "mistral":
+        case "perplexity":
+        case "together":
+        case "fireworks":
+        case "cerebras":
+        case "cohere":
+        case "nebius":
+        case "siliconflow":
+        case "hyperbolic":
+        case "ollama":
+        case "ollama-local":
+        case "assemblyai":
+        case "nanobanana":
+        case "chutes":
+        case "xiaomi-mimo":
+        case "xiaomi-tokenplan":
+        case "nvidia": {
+          const endpoints = {
+            ...Object.fromEntries(
+              Object.entries(PROVIDERS).filter(([, t]) => t.validateUrl).map(([id, t]) => [id, t.validateUrl])
+            ),
+            // dynamic URLs (depend on providerSpecificData) — kept inline
+            "ollama-local": `${resolveOllamaLocalHost({ providerSpecificData })}/api/tags`,
+            "xiaomi-tokenplan": `${resolveXiaomiTokenplanBaseUrl({ providerSpecificData })}/models`,
+          };
+          const headers = {};
+          if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+          const res = await fetch(endpoints[provider], { headers, signal: AbortSignal.timeout(8000) });
+          // xai returns 400 for bad key, 403 for valid-but-no-credit. Other providers use 401.
+          if (provider === "xai") {
+            isValid = res.status === 200 || res.status === 403;
+          } else if (provider === "xiaomi-tokenplan") {
+            // /models returns 403 for valid keys lacking list permission; only 401 means invalid
+            isValid = res.status !== 401;
+          } else {
+            isValid = res.ok;
+          }
+          break;
+        }
+
+        case "opencode-go": {
+          const res = await fetch("https://opencode.ai/zen/go/v1/chat/completions", {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
+            body: JSON.stringify({
+              model: getDefaultModel("opencode-go"),
+              messages: [{ role: "user", content: "ping" }],
+              max_tokens: 1,
+              stream: false,
+            }),
+          });
+          isValid = res.status !== 401 && res.status !== 403;
+          break;
+        }
+
+        case "commandcode": {
+          const cfg = PROVIDERS.commandcode;
+          const model = getDefaultModel("commandcode");
+          const payload = openaiToCommandCodeRequest(model, {
+            messages: [{ role: "user", content: "ping" }],
+            max_tokens: 1,
+            stream: false,
+          }, false);
+          const res = await fetch(cfg.baseUrl, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              ...(cfg.headers || {}),
+              "x-session-id": crypto.randomUUID(),
+              "Authorization": `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify(payload),
+          });
+          isValid = res.status !== 401 && res.status !== 403;
+          break;
+        }
+
+        case "deepgram": {
+          const res = await fetch("https://api.deepgram.com/v1/projects", {
+            headers: { "Authorization": `Token ${apiKey}` },
+          });
+          isValid = res.ok;
+          break;
+        }
+
+        case "blackbox": {
+          const res = await fetch("https://api.blackbox.ai/chat/completions", {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${apiKey}`,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+              model: "gpt-4o",
+              messages: [{ role: "user", content: "test" }],
+              max_tokens: 10,
+            }),
+          });
+          // Returns 401 for invalid key, 200 for valid, 400 for malformed
+          isValid = res.status === 200 || res.status === 400;
+          break;
+        }
+
+        case "vertex": {
+          // Raw key: probe global endpoint (always 404 for unknown model, never 401)
+          // SA JSON: attempt token mint via JWT assertion
+          const saJson = (() => { try { const p = JSON.parse(apiKey); return p.type === "service_account" ? p : null; } catch { return null; } })();
+          if (saJson) {
+            // Validate SA JSON has required fields
+            isValid = !!(saJson.client_email && saJson.private_key && saJson.project_id);
+          } else {
+            // Raw key: probe Vertex — 404 means key is valid (model just doesn't exist), 401 means invalid key
+            const probeRes = await fetch(
+              `https://aiplatform.googleapis.com/v1/publishers/google/models/__probe__:generateContent?key=${apiKey}`,
+              { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" }
+            );
+            isValid = probeRes.status !== 401 && probeRes.status !== 403;
+          }
+          break;
+        }
+
+        case "vertex-partner": {
+          const saJson = (() => { try { const p = JSON.parse(apiKey); return p.type === "service_account" ? p : null; } catch { return null; } })();
+          if (saJson) {
+            isValid = !!(saJson.client_email && saJson.private_key && saJson.project_id);
+          } else {
+            const probeRes = await fetch(
+              `https://aiplatform.googleapis.com/v1/publishers/google/models/__probe__:generateContent?key=${apiKey}`,
+              { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" }
+            );
+            isValid = probeRes.status !== 401 && probeRes.status !== 403;
+          }
+          break;
+        }
+
+        case "grok-web": {
+          const token = apiKey.startsWith("sso=") ? apiKey.slice(4) : apiKey;
+          // Cloudflare-bypass: send POST with same browser fingerprint headers as GrokWebExecutor
+          const randomHex = (n) => {
+            const a = new Uint8Array(n);
+            crypto.getRandomValues(a);
+            return Array.from(a, (b) => b.toString(16).padStart(2, "0")).join("");
+          };
+          const statsigId = Buffer.from("e:TypeError: Cannot read properties of null (reading 'children')").toString("base64");
+          const traceId = randomHex(16);
+          const spanId = randomHex(8);
+          const res = await fetch("https://grok.com/rest/app-chat/conversations/new", {
+            method: "POST",
+            headers: {
+              Accept: "*/*",
+              "Accept-Encoding": "gzip, deflate, br, zstd",
+              "Accept-Language": "en-US,en;q=0.9",
+              "Cache-Control": "no-cache",
+              "Content-Type": "application/json",
+              Cookie: `sso=${token}`,
+              Origin: "https://grok.com",
+              Pragma: "no-cache",
+              Referer: "https://grok.com/",
+              "Sec-Ch-Ua": '"Google Chrome";v="136", "Chromium";v="136", "Not(A:Brand";v="24"',
+              "Sec-Ch-Ua-Mobile": "?0",
+              "Sec-Ch-Ua-Platform": '"macOS"',
+              "Sec-Fetch-Dest": "empty",
+              "Sec-Fetch-Mode": "cors",
+              "Sec-Fetch-Site": "same-origin",
+              "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
+              "x-statsig-id": statsigId,
+              "x-xai-request-id": crypto.randomUUID(),
+              traceparent: `00-${traceId}-${spanId}-00`,
+            },
+            body: JSON.stringify({
+              temporary: true, modelName: "grok-4", modelMode: "MODEL_MODE_GROK_4", message: "ping",
+              fileAttachments: [], imageAttachments: [],
+              disableSearch: false, enableImageGeneration: false, returnImageBytes: false,
+              returnRawGrokInXaiRequest: false, enableImageStreaming: false, imageGenerationCount: 0,
+              forceConcise: false, toolOverrides: {}, enableSideBySide: true, sendFinalMetadata: true,
+              isReasoning: false, disableTextFollowUps: true, disableMemory: true,
+              forceSideBySide: false, isAsyncChat: false, disableSelfHarmShortCircuit: false,
+            }),
+          });
+          // Cookie valid = any non-401/403 response (200, 400, 429 all mean cookie accepted)
+          if (res.status === 401 || res.status === 403) {
+            isValid = false;
+            error = "Invalid SSO cookie — re-paste from grok.com DevTools → Cookies → sso";
+          } else {
+            isValid = true;
+          }
+          break;
+        }
+
+        case "perplexity-web": {
+          let sessionToken = apiKey;
+          if (sessionToken.startsWith("__Secure-next-auth.session-token=")) {
+            sessionToken = sessionToken.slice("__Secure-next-auth.session-token=".length);
+          }
+          const tz = typeof Intl !== "undefined" ? Intl.DateTimeFormat().resolvedOptions().timeZone : "UTC";
+          const res = await fetch("https://www.perplexity.ai/rest/sse/perplexity_ask", {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Accept: "text/event-stream",
+              Origin: "https://www.perplexity.ai",
+              Referer: "https://www.perplexity.ai/",
+              "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
+              "X-App-ApiClient": "default",
+              "X-App-ApiVersion": "2.18",
+              Cookie: `__Secure-next-auth.session-token=${sessionToken}`,
+            },
+            body: JSON.stringify({
+              query_str: "ping",
+              params: {
+                query_str: "ping", search_focus: "internet", mode: "concise", model_preference: "pplx_pro",
+                sources: ["web"], attachments: [],
+                frontend_uuid: crypto.randomUUID(), frontend_context_uuid: crypto.randomUUID(),
+                version: "2.18", language: "en-US", timezone: tz,
+                search_recency_filter: null, is_incognito: true, use_schematized_api: true, last_backend_uuid: null,
+              },
+            }),
+          });
+          if (res.status === 401 || res.status === 403) {
+            isValid = false;
+            error = "Invalid session cookie — re-paste __Secure-next-auth.session-token from perplexity.ai";
+          } else {
+            isValid = true;
+          }
+          break;
+        }
+
+        default: {
+          // Generic probe for OpenAI-compatible providers (config-driven from PROVIDERS)
+          const cfg = PROVIDERS[provider];
+          if (!cfg || cfg.format !== "openai" || !cfg.baseUrl) {
+            return NextResponse.json({ error: "Provider validation not supported" }, { status: 400 });
+          }
+          if (cfg.noAuth) {
+            isValid = true;
+            break;
+          }
+          // Build auth headers based on cfg.authHeader (default: bearer)
+          const headers = { "Content-Type": "application/json", ...(cfg.headers || {}) };
+          if (cfg.authHeader === "x-api-key") headers["X-API-Key"] = apiKey;
+          else headers["Authorization"] = `Bearer ${apiKey}`;
+          // Try /models first (fast GET), fallback to chat probe on ambiguous response
+          const modelsUrl = cfg.baseUrl.replace(/\/chat\/completions$/, "/models").replace(/\/chatbot$/, "/models");
+          let probeOk = null;
+          try {
+            const probeRes = await fetch(modelsUrl, { headers, signal: AbortSignal.timeout(8000) });
+            if (probeRes.status === 401 || probeRes.status === 403) probeOk = false;
+            else if (probeRes.ok) probeOk = true;
+          } catch { /* fallback to chat */ }
+          if (probeOk !== null) {
+            isValid = probeOk;
+            break;
+          }
+          // Fallback: minimal chat probe
+          const defaultModel = getDefaultModel(provider) || "test";
+          const chatRes = await fetch(cfg.baseUrl, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ model: defaultModel, messages: [{ role: "user", content: "ping" }], max_tokens: 1 }),
+            signal: AbortSignal.timeout(10000),
+          });
+          isValid = chatRes.status !== 401 && chatRes.status !== 403;
+          break;
+        }
+      }
+    } catch (err) {
+      error = err.message;
+      isValid = false;
+    }
+
+    return NextResponse.json({
+      valid: isValid,
+      error: isValid ? null : (error || "Invalid API key"),
+    });
+  } catch (error) {
+    console.log("Error validating API key:", error);
+    return NextResponse.json({ error: "Validation failed" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/proxy-pools/[id]/route.js b/src/app/api/proxy-pools/[id]/route.js
new file mode 100644
index 0000000..dcfd1fe
--- /dev/null
+++ b/src/app/api/proxy-pools/[id]/route.js
@@ -0,0 +1,123 @@
+import { NextResponse } from "next/server";
+import {
+  deleteProxyPool,
+  getProviderConnections,
+  getProxyPoolById,
+  updateProxyPool,
+} from "@/models";
+
+function normalizeProxyPoolUpdate(body = {}) {
+  const updates = {};
+
+  if (Object.prototype.hasOwnProperty.call(body, "name")) {
+    const name = typeof body?.name === "string" ? body.name.trim() : "";
+    if (!name) {
+      return { error: "Name is required" };
+    }
+    updates.name = name;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(body, "proxyUrl")) {
+    const proxyUrl = typeof body?.proxyUrl === "string" ? body.proxyUrl.trim() : "";
+    if (!proxyUrl) {
+      return { error: "Proxy URL is required" };
+    }
+    updates.proxyUrl = proxyUrl;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(body, "noProxy")) {
+    updates.noProxy = typeof body?.noProxy === "string" ? body.noProxy.trim() : "";
+  }
+
+  if (Object.prototype.hasOwnProperty.call(body, "isActive")) {
+    updates.isActive = body?.isActive === true;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(body, "strictProxy")) {
+    updates.strictProxy = body?.strictProxy === true;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(body, "type")) {
+    const validTypes = ["http", "vercel", "cloudflare"];
+    updates.type = validTypes.includes(body?.type) ? body.type : "http";
+  }
+
+  return { updates };
+}
+
+function countBoundConnections(connections = [], proxyPoolId) {
+  return connections.filter((connection) => connection?.providerSpecificData?.proxyPoolId === proxyPoolId).length;
+}
+
+// GET /api/proxy-pools/[id] - Get proxy pool
+export async function GET(request, { params }) {
+  try {
+    const { id } = await params;
+    const proxyPool = await getProxyPoolById(id);
+
+    if (!proxyPool) {
+      return NextResponse.json({ error: "Proxy pool not found" }, { status: 404 });
+    }
+
+    return NextResponse.json({ proxyPool });
+  } catch (error) {
+    console.log("Error fetching proxy pool:", error);
+    return NextResponse.json({ error: "Failed to fetch proxy pool" }, { status: 500 });
+  }
+}
+
+// PUT /api/proxy-pools/[id] - Update proxy pool
+export async function PUT(request, { params }) {
+  try {
+    const { id } = await params;
+    const existing = await getProxyPoolById(id);
+
+    if (!existing) {
+      return NextResponse.json({ error: "Proxy pool not found" }, { status: 404 });
+    }
+
+    const body = await request.json();
+    const normalized = normalizeProxyPoolUpdate(body);
+
+    if (normalized.error) {
+      return NextResponse.json({ error: normalized.error }, { status: 400 });
+    }
+
+    const updated = await updateProxyPool(id, normalized.updates);
+    return NextResponse.json({ proxyPool: updated });
+  } catch (error) {
+    console.log("Error updating proxy pool:", error);
+    return NextResponse.json({ error: "Failed to update proxy pool" }, { status: 500 });
+  }
+}
+
+// DELETE /api/proxy-pools/[id] - Delete proxy pool
+export async function DELETE(request, { params }) {
+  try {
+    const { id } = await params;
+    const existing = await getProxyPoolById(id);
+
+    if (!existing) {
+      return NextResponse.json({ error: "Proxy pool not found" }, { status: 404 });
+    }
+
+    const connections = await getProviderConnections();
+    const boundConnectionCount = countBoundConnections(connections, id);
+
+    if (boundConnectionCount > 0) {
+      return NextResponse.json(
+        {
+          error: "Proxy pool is currently in use",
+          boundConnectionCount,
+        },
+        { status: 409 }
+      );
+    }
+
+    await deleteProxyPool(id);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.log("Error deleting proxy pool:", error);
+    return NextResponse.json({ error: "Failed to delete proxy pool" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/proxy-pools/[id]/test/route.js b/src/app/api/proxy-pools/[id]/test/route.js
new file mode 100644
index 0000000..57bd00e
--- /dev/null
+++ b/src/app/api/proxy-pools/[id]/test/route.js
@@ -0,0 +1,70 @@
+import { NextResponse } from "next/server";
+import { getProxyPoolById, updateProxyPool } from "@/models";
+import { testProxyUrl } from "@/lib/network/proxyTest";
+import { fetch as undiciFetch } from "undici";
+
+async function testVercelRelay(relayUrl, timeoutMs = 10000) {
+  const controller = new AbortController();
+  const startedAt = Date.now();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await undiciFetch(relayUrl, {
+      method: "GET",
+      headers: {
+        "x-relay-target": "https://httpbin.org",
+        "x-relay-path": "/get",
+      },
+      signal: controller.signal,
+    });
+    return {
+      ok: res.ok,
+      status: res.status,
+      statusText: res.statusText,
+      elapsedMs: Date.now() - startedAt,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      status: 500,
+      error: err?.name === "AbortError" ? "Relay test timed out" : (err?.message || String(err)),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// POST /api/proxy-pools/[id]/test - Test proxy pool entry
+export async function POST(request, { params }) {
+  try {
+    const { id } = await params;
+    const proxyPool = await getProxyPoolById(id);
+
+    if (!proxyPool) {
+      return NextResponse.json({ error: "Proxy pool not found" }, { status: 404 });
+    }
+
+    const result = proxyPool.type === "vercel" || proxyPool.type === "cloudflare" || proxyPool.type === "deno"
+      ? await testVercelRelay(proxyPool.proxyUrl)
+      : await testProxyUrl({ proxyUrl: proxyPool.proxyUrl });
+    const now = new Date().toISOString();
+
+    await updateProxyPool(id, {
+      testStatus: result.ok ? "active" : "error",
+      lastTestedAt: now,
+      lastError: result.ok ? null : (result.error || `Proxy test failed with status ${result.status}`),
+      isActive: result.ok,
+    });
+
+    return NextResponse.json({
+      ok: result.ok,
+      status: result.status,
+      statusText: result.statusText || null,
+      error: result.error || null,
+      elapsedMs: result.elapsedMs || 0,
+      testedAt: now,
+    });
+  } catch (error) {
+    console.log("Error testing proxy pool:", error);
+    return NextResponse.json({ error: "Failed to test proxy pool" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/proxy-pools/cloudflare-deploy/route.js b/src/app/api/proxy-pools/cloudflare-deploy/route.js
new file mode 100644
index 0000000..814c1fb
--- /dev/null
+++ b/src/app/api/proxy-pools/cloudflare-deploy/route.js
@@ -0,0 +1,145 @@
+import { NextResponse } from "next/server";
+import { createProxyPool } from "@/models";
+
+// Relay worker source code deployed to Cloudflare
+const RELAY_WORKER_CODE = `
+export default {
+  async fetch(request, env, ctx) {
+    const target = request.headers.get("x-relay-target");
+    const relayPath = request.headers.get("x-relay-path") || "/";
+    
+    if (!target) {
+      return new Response(JSON.stringify({ error: "Missing x-relay-target header" }), {
+        status: 400,
+        headers: { "content-type": "application/json" },
+      });
+    }
+
+    const targetUrl = target.replace(/\\/$/, "") + relayPath;
+    const newRequestInit = {
+      method: request.method,
+      headers: new Headers(request.headers),
+    };
+
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      newRequestInit.body = request.body;
+      newRequestInit.duplex = "half";
+    }
+
+    newRequestInit.headers.delete("x-relay-target");
+    newRequestInit.headers.delete("x-relay-path");
+    newRequestInit.headers.delete("host");
+
+    try {
+      const response = await fetch(targetUrl, newRequestInit);
+      return new Response(response.body, {
+        status: response.status,
+        headers: response.headers,
+      });
+    } catch (error) {
+      return new Response(JSON.stringify({ error: error.message }), {
+        status: 502,
+        headers: { "content-type": "application/json" },
+      });
+    }
+  },
+};
+`;
+
+// POST /api/proxy-pools/cloudflare-deploy
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const accountId = body.accountId?.trim();
+    const apiToken = body.apiToken?.trim();
+    const projectName = body.projectName?.trim() || `relay-${Date.now().toString(36)}`;
+
+    if (!accountId || !apiToken) {
+      return NextResponse.json({ error: "Cloudflare Account ID and API Token are required" }, { status: 400 });
+    }
+
+    // 1. Upload Worker Script
+    const workerScriptUrl = `https://api.cloudflare.com/client/v4/accounts/${accountId}/workers/scripts/${projectName}`;
+    
+    // Cloudflare requires multipart/form-data for worker script upload
+    const formData = new FormData();
+    formData.append("index.js", new Blob([RELAY_WORKER_CODE], { type: "application/javascript+module" }), "index.js");
+    formData.append("metadata", new Blob([JSON.stringify({
+      main_module: "index.js",
+      compatibility_date: "2024-03-20",
+      observability: { enabled: true }
+    })], { type: "application/json" }), "metadata.json");
+
+    const uploadRes = await fetch(workerScriptUrl, {
+      method: "PUT",
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+      },
+      body: formData,
+    });
+
+    if (!uploadRes.ok) {
+      const err = await uploadRes.json().catch(() => ({}));
+      console.error("Cloudflare upload error:", err);
+      return NextResponse.json(
+        { error: err.errors?.[0]?.message || "Failed to upload Worker to Cloudflare" },
+        { status: uploadRes.status }
+      );
+    }
+
+    // 2. Enable workers.dev subdomain for the script
+    const enableSubdomainRes = await fetch(`${workerScriptUrl}/subdomain`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ enabled: true }),
+    });
+
+    if (!enableSubdomainRes.ok) {
+      const err = await enableSubdomainRes.json().catch(() => ({}));
+      console.error("Cloudflare subdomain enable error:", err);
+      // We don't fail completely here, just continue
+    }
+
+    // 3. Get the workers.dev subdomain for the account to construct the final URL
+    let deployUrl = "";
+    const subdomainRes = await fetch(`https://api.cloudflare.com/client/v4/accounts/${accountId}/workers/subdomain`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+        "Content-Type": "application/json",
+      },
+    });
+
+    if (subdomainRes.ok) {
+      const subdomainData = await subdomainRes.json();
+      if (subdomainData.result && subdomainData.result.subdomain) {
+        deployUrl = `https://${projectName}.${subdomainData.result.subdomain}.workers.dev`;
+      }
+    }
+
+    if (!deployUrl) {
+       return NextResponse.json(
+        { error: "Worker deployed but failed to retrieve workers.dev subdomain. Make sure you have setup a workers.dev subdomain in Cloudflare Dashboard." },
+        { status: 400 }
+      );
+    }
+
+    // Create proxy pool entry with type cloudflare
+    const proxyPool = await createProxyPool({
+      name: projectName,
+      proxyUrl: deployUrl,
+      type: "cloudflare",
+      noProxy: "",
+      isActive: true,
+      strictProxy: false,
+    });
+
+    return NextResponse.json({ proxyPool, deployUrl }, { status: 201 });
+  } catch (error) {
+    console.log("Error deploying Cloudflare relay:", error);
+    return NextResponse.json({ error: error.message || "Deploy failed" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/proxy-pools/deno-deploy/route.js b/src/app/api/proxy-pools/deno-deploy/route.js
new file mode 100644
index 0000000..d777d68
--- /dev/null
+++ b/src/app/api/proxy-pools/deno-deploy/route.js
@@ -0,0 +1,175 @@
+import { NextResponse } from "next/server";
+import { createProxyPool } from "@/models";
+
+const DENO_V2_API = "https://api.deno.com/v2";
+
+const DENO_RELAY_CODE = `Deno.serve(async (request) => {
+  const target = request.headers.get("x-relay-target");
+  const relayPath = request.headers.get("x-relay-path") || "/";
+
+  if (!target) {
+    return new Response(JSON.stringify({ error: "Missing x-relay-target header" }), {
+      status: 400,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  const targetUrl = target.replace(/\\/$/, "") + relayPath;
+  const newHeaders = new Headers(request.headers);
+  newHeaders.delete("x-relay-target");
+  newHeaders.delete("x-relay-path");
+  newHeaders.delete("host");
+
+  const init = {
+    method: request.method,
+    headers: newHeaders,
+  };
+
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    init.body = request.body;
+    init.duplex = "half";
+  }
+
+  try {
+    const response = await fetch(targetUrl, init);
+    return new Response(response.body, {
+      status: response.status,
+      headers: response.headers,
+    });
+  } catch (error) {
+    return new Response(JSON.stringify({ error: error.message }), {
+      status: 502,
+      headers: { "content-type": "application/json" },
+    });
+  }
+});`;
+
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const denoToken = body.denoToken?.trim();
+    const orgDomain = body.orgDomain?.trim();
+    const projectName = body.projectName?.trim() || `relay-${Date.now().toString(36)}`;
+
+    if (!orgDomain) {
+      return NextResponse.json({ error: "Organization domain is required" }, { status: 400 });
+    }
+
+    if (!denoToken) {
+      return NextResponse.json({ error: "Deno Deploy API token is required" }, { status: 400 });
+    }
+
+    const headers = {
+      Authorization: `Bearer ${denoToken}`,
+      "Content-Type": "application/json",
+    };
+
+    const createAppRes = await fetch(`${DENO_V2_API}/apps`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        slug: projectName,
+        labels: { "custom.kind": "9router-relay" },
+        config: {
+          install: "deno install",
+          runtime: {
+            type: "dynamic",
+            entrypoint: "main.ts",
+          },
+        },
+      }),
+    });
+
+    if (!createAppRes.ok) {
+      const text = await createAppRes.text().catch(() => "");
+      if (createAppRes.status === 409) {
+        return NextResponse.json(
+          { error: `App "${projectName}" already exists. Choose a different name.` },
+          { status: 409 }
+        );
+      }
+      return NextResponse.json(
+        { error: `Failed to create app (${createAppRes.status}): ${text}` },
+        { status: createAppRes.status }
+      );
+    }
+
+    const app = await createAppRes.json();
+
+    const deployRes = await fetch(`${DENO_V2_API}/apps/${app.id}/deploy`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        assets: {
+          "main.ts": {
+            kind: "file",
+            content: DENO_RELAY_CODE,
+            encoding: "utf-8",
+          },
+        },
+      }),
+    });
+
+    if (!deployRes.ok) {
+      const text = await deployRes.text().catch(() => "");
+      console.error("Deno Deploy error:", deployRes.status, text);
+      await fetch(`${DENO_V2_API}/apps/${app.id}`, {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${denoToken}` },
+      }).catch(() => {});
+      return NextResponse.json(
+        { error: `Deploy failed (${deployRes.status}): ${text}` },
+        { status: deployRes.status }
+      );
+    }
+
+    const revision = await deployRes.json();
+    const revisionId = revision.id;
+
+    let status = revision.status;
+    let attempts = 0;
+    const maxAttempts = 30; // 30 * 2s = 60s max
+    while (status === "queued" || status === "building") {
+      if (attempts >= maxAttempts) {
+        throw new Error("Deploy timed out after 60 seconds");
+      }
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      const statusRes = await fetch(`${DENO_V2_API}/revisions/${revisionId}`, {
+        headers: { Authorization: `Bearer ${denoToken}` },
+      });
+      if (!statusRes.ok) break;
+      const statusData = await statusRes.json();
+      status = statusData.status;
+      attempts++;
+    }
+
+    if (status !== "succeeded") {
+      await fetch(`${DENO_V2_API}/apps/${app.id}`, {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${denoToken}` },
+      }).catch(() => {});
+      return NextResponse.json(
+        { error: `Deploy failed with status: ${status}` },
+        { status: 500 }
+      );
+    }
+
+    const orgSlug = orgDomain.split(".")[0];
+    const deployUrl = `https://${projectName}.${orgSlug}.deno.net`;
+    console.log("Deno deployUrl:", deployUrl);
+
+    const proxyPool = await createProxyPool({
+      name: projectName,
+      proxyUrl: deployUrl,
+      type: "deno",
+      noProxy: "",
+      isActive: true,
+      strictProxy: false,
+    });
+
+    return NextResponse.json({ proxyPool, deployUrl }, { status: 201 });
+  } catch (error) {
+    console.log("Error deploying Deno Deploy relay:", error);
+    return NextResponse.json({ error: error.message || "Deploy failed" }, { status: 500 });
+  }
+}
\ No newline at end of file
diff --git a/src/app/api/proxy-pools/route.js b/src/app/api/proxy-pools/route.js
new file mode 100644
index 0000000..3dcfa06
--- /dev/null
+++ b/src/app/api/proxy-pools/route.js
@@ -0,0 +1,93 @@
+import { NextResponse } from "next/server";
+import { createProxyPool, getProviderConnections, getProxyPools } from "@/models";
+
+function toBoolean(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return undefined;
+}
+
+const VALID_PROXY_TYPES = ["http", "vercel", "cloudflare", "deno"];
+
+function normalizeProxyPoolInput(body = {}) {
+  const name = typeof body?.name === "string" ? body.name.trim() : "";
+  const proxyUrl = typeof body?.proxyUrl === "string" ? body.proxyUrl.trim() : "";
+  const noProxy = typeof body?.noProxy === "string" ? body.noProxy.trim() : "";
+  const isActive = body?.isActive === undefined ? true : body.isActive === true;
+  const strictProxy = body?.strictProxy === true;
+  const type = VALID_PROXY_TYPES.includes(body?.type) ? body.type : "http";
+
+  if (!name) {
+    return { error: "Name is required" };
+  }
+
+  if (!proxyUrl) {
+    return { error: "Proxy URL is required" };
+  }
+
+  return { name, proxyUrl, noProxy, isActive, strictProxy, type };
+}
+
+function buildUsageMap(connections = []) {
+  const usageMap = new Map();
+
+  for (const connection of connections) {
+    const proxyPoolId = connection?.providerSpecificData?.proxyPoolId;
+    if (!proxyPoolId) continue;
+
+    usageMap.set(proxyPoolId, (usageMap.get(proxyPoolId) || 0) + 1);
+  }
+
+  return usageMap;
+}
+
+// GET /api/proxy-pools - List proxy pools
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const isActive = toBoolean(searchParams.get("isActive"));
+    const includeUsage = searchParams.get("includeUsage") === "true";
+
+    const filter = {};
+    if (isActive !== undefined) {
+      filter.isActive = isActive;
+    }
+
+    const proxyPools = await getProxyPools(filter);
+
+    if (!includeUsage) {
+      return NextResponse.json({ proxyPools });
+    }
+
+    const connections = await getProviderConnections();
+    const usageMap = buildUsageMap(connections);
+
+    const enrichedProxyPools = proxyPools.map((pool) => ({
+      ...pool,
+      boundConnectionCount: usageMap.get(pool.id) || 0,
+    }));
+
+    return NextResponse.json({ proxyPools: enrichedProxyPools });
+  } catch (error) {
+    console.log("Error fetching proxy pools:", error);
+    return NextResponse.json({ error: "Failed to fetch proxy pools" }, { status: 500 });
+  }
+}
+
+// POST /api/proxy-pools - Create proxy pool
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const normalized = normalizeProxyPoolInput(body);
+
+    if (normalized.error) {
+      return NextResponse.json({ error: normalized.error }, { status: 400 });
+    }
+
+    const proxyPool = await createProxyPool(normalized);
+    return NextResponse.json({ proxyPool }, { status: 201 });
+  } catch (error) {
+    console.log("Error creating proxy pool:", error);
+    return NextResponse.json({ error: "Failed to create proxy pool" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/proxy-pools/vercel-deploy/route.js b/src/app/api/proxy-pools/vercel-deploy/route.js
new file mode 100644
index 0000000..e87390f
--- /dev/null
+++ b/src/app/api/proxy-pools/vercel-deploy/route.js
@@ -0,0 +1,142 @@
+import { NextResponse } from "next/server";
+import { createProxyPool } from "@/models";
+
+const VERCEL_API = "https://api.vercel.com";
+
+// Relay function source code deployed to Vercel
+// Forwards requests to target URL specified in x-relay-target header
+const RELAY_FUNCTION_CODE = `
+export const config = { runtime: "edge" };
+
+export default async function handler(req) {
+  const target = req.headers.get("x-relay-target");
+  const relayPath = req.headers.get("x-relay-path") || "/";
+  if (!target) {
+    return new Response(JSON.stringify({ error: "Missing x-relay-target header" }), {
+      status: 400,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  const targetUrl = target.replace(/\\/$/, "") + relayPath;
+
+  const headers = new Headers(req.headers);
+  headers.delete("x-relay-target");
+  headers.delete("x-relay-path");
+  headers.delete("host");
+
+  const response = await fetch(targetUrl, {
+    method: req.method,
+    headers,
+    body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined,
+    duplex: "half",
+  });
+
+  return new Response(response.body, {
+    status: response.status,
+    headers: response.headers,
+  });
+}
+`;
+
+async function pollDeployment(deploymentId, token, maxMs = 120000) {
+  const start = Date.now();
+  while (Date.now() - start < maxMs) {
+    const res = await fetch(`${VERCEL_API}/v13/deployments/${deploymentId}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const data = await res.json();
+    if (data.readyState === "READY") return data;
+    if (data.readyState === "ERROR" || data.readyState === "CANCELED") {
+      throw new Error(`Deployment failed: ${data.readyState}`);
+    }
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+  throw new Error("Deployment timed out");
+}
+
+// POST /api/proxy-pools/vercel-deploy
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const vercelToken = body.vercelToken;
+    const projectName = body.projectName?.trim() || `relay-${Date.now().toString(36)}`;
+
+    if (!vercelToken) {
+      return NextResponse.json({ error: "Vercel API token is required" }, { status: 400 });
+    }
+
+    // Deploy relay function to Vercel
+    const deployRes = await fetch(`${VERCEL_API}/v13/deployments`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${vercelToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        name: projectName,
+        files: [
+          {
+            file: "api/relay.js",
+            data: RELAY_FUNCTION_CODE,
+          },
+          {
+            file: "package.json",
+            data: JSON.stringify({ name: projectName, version: "1.0.0" }),
+          },
+          {
+            file: "vercel.json",
+            data: JSON.stringify({
+              rewrites: [{ source: "/(.*)", destination: "/api/relay" }],
+            }),
+          },
+        ],
+        projectSettings: {
+          framework: null,
+        },
+        target: "production",
+      }),
+    });
+
+    if (!deployRes.ok) {
+      const err = await deployRes.json().catch(() => ({}));
+      return NextResponse.json(
+        { error: err.error?.message || "Failed to create Vercel deployment" },
+        { status: deployRes.status }
+      );
+    }
+
+    const deployment = await deployRes.json();
+    const deploymentId = deployment.id || deployment.uid;
+
+    // Disable deployment protection (Vercel Authentication)
+    const projectId = deployment.projectId || projectName;
+    await fetch(`${VERCEL_API}/v9/projects/${projectId}`, {
+      method: "PATCH",
+      headers: {
+        Authorization: `Bearer ${vercelToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ ssoProtection: null }),
+    });
+
+    // Poll until deployment is ready
+    const ready = await pollDeployment(deploymentId, vercelToken);
+    const deployUrl = `https://${ready.url}`;
+
+    // Create proxy pool entry with type vercel
+    const proxyPool = await createProxyPool({
+      name: projectName,
+      proxyUrl: deployUrl,
+      type: "vercel",
+      noProxy: "",
+      isActive: true,
+      strictProxy: false,
+    });
+
+    return NextResponse.json({ proxyPool, deployUrl }, { status: 201 });
+  } catch (error) {
+    console.log("Error deploying Vercel relay:", error);
+    return NextResponse.json({ error: error.message || "Deploy failed" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/pxpipe/health/route.js b/src/app/api/pxpipe/health/route.js
new file mode 100644
index 0000000..f974342
--- /dev/null
+++ b/src/app/api/pxpipe/health/route.js
@@ -0,0 +1,16 @@
+import { NextResponse } from "next/server";
+import { runHealthCheck } from "@/lib/pxpipe/service.js";
+
+export const dynamic = "force-dynamic";
+
+export async function POST() {
+  try {
+    const result = await runHealthCheck();
+    return NextResponse.json(result);
+  } catch (error) {
+    return NextResponse.json({ healthy: false, checks: [], error: error.message }, { status: 500 });
+  }
+}
+
+// GET mirrors POST so the card can probe on page load without a mutation call.
+export const GET = POST;
diff --git a/src/app/api/pxpipe/install/route.js b/src/app/api/pxpipe/install/route.js
new file mode 100644
index 0000000..c5eedcc
--- /dev/null
+++ b/src/app/api/pxpipe/install/route.js
@@ -0,0 +1,20 @@
+import { NextResponse } from "next/server";
+import { installPxpipe } from "@/lib/pxpipe/install.js";
+import { unloadPxpipe } from "@/lib/pxpipe/loader.js";
+import { runHealthCheck } from "@/lib/pxpipe/service.js";
+
+export const dynamic = "force-dynamic";
+// npm install can legitimately take minutes on a cold cache.
+export const maxDuration = 300;
+
+// Install (or repair — same operation, reinstalls @latest) then re-run the health check.
+export async function POST() {
+  try {
+    const info = await installPxpipe();
+    unloadPxpipe(); // drop any previously-loaded version so health loads the fresh one
+    const health = await runHealthCheck();
+    return NextResponse.json({ ...info, health });
+  } catch (error) {
+    return NextResponse.json({ error: error.message, code: error.code || null }, { status: 500 });
+  }
+}
diff --git a/src/app/api/pxpipe/logs/route.js b/src/app/api/pxpipe/logs/route.js
new file mode 100644
index 0000000..051db38
--- /dev/null
+++ b/src/app/api/pxpipe/logs/route.js
@@ -0,0 +1,18 @@
+import { NextResponse } from "next/server";
+import { getInstallLogTail } from "@/lib/pxpipe/install.js";
+import { readPxpipeEvents } from "@/lib/pxpipe/events.js";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const limit = Math.min(Number(searchParams.get("limit")) || 100, 500);
+    return NextResponse.json({
+      installLog: getInstallLogTail(),
+      events: readPxpipeEvents({ limit }).reverse(),
+    });
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/pxpipe/restart/route.js b/src/app/api/pxpipe/restart/route.js
new file mode 100644
index 0000000..1aaab39
--- /dev/null
+++ b/src/app/api/pxpipe/restart/route.js
@@ -0,0 +1,16 @@
+import { NextResponse } from "next/server";
+import { unloadPxpipe, loadPxpipe } from "@/lib/pxpipe/loader.js";
+import { getPxpipeStatus } from "@/lib/pxpipe/service.js";
+
+export const dynamic = "force-dynamic";
+
+// Reload the in-process module (picks up an upgraded install without a server restart).
+export async function POST() {
+  try {
+    unloadPxpipe();
+    await loadPxpipe();
+    return NextResponse.json(getPxpipeStatus());
+  } catch (error) {
+    return NextResponse.json({ error: error.message, code: error.code || null }, { status: 500 });
+  }
+}
diff --git a/src/app/api/pxpipe/start/route.js b/src/app/api/pxpipe/start/route.js
new file mode 100644
index 0000000..5dad8b2
--- /dev/null
+++ b/src/app/api/pxpipe/start/route.js
@@ -0,0 +1,26 @@
+import { NextResponse } from "next/server";
+import { getSettings } from "@/lib/localDb";
+import { getInstallInfo, installPxpipe } from "@/lib/pxpipe/install.js";
+import { loadPxpipe } from "@/lib/pxpipe/loader.js";
+import { getPxpipeStatus } from "@/lib/pxpipe/service.js";
+
+export const dynamic = "force-dynamic";
+export const maxDuration = 300;
+
+// "Start" in library mode = warm the in-process transform module.
+// Auto-installs first when the package is missing and pxpipeAutoInstall is on.
+export async function POST() {
+  try {
+    if (!getInstallInfo().installed) {
+      const settings = await getSettings();
+      if (!settings.pxpipeAutoInstall) {
+        return NextResponse.json({ error: "PXPIPE is not installed", code: "NOT_INSTALLED" }, { status: 409 });
+      }
+      await installPxpipe();
+    }
+    await loadPxpipe();
+    return NextResponse.json(getPxpipeStatus());
+  } catch (error) {
+    return NextResponse.json({ error: error.message, code: error.code || null }, { status: 500 });
+  }
+}
diff --git a/src/app/api/pxpipe/stats/route.js b/src/app/api/pxpipe/stats/route.js
new file mode 100644
index 0000000..c5860b6
--- /dev/null
+++ b/src/app/api/pxpipe/stats/route.js
@@ -0,0 +1,14 @@
+import { NextResponse } from "next/server";
+import { getPxpipeStats } from "@/lib/pxpipe/events.js";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const recentLimit = Math.min(Number(searchParams.get("limit")) || 100, 500);
+    return NextResponse.json(getPxpipeStats({ recentLimit }));
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/pxpipe/status/route.js b/src/app/api/pxpipe/status/route.js
new file mode 100644
index 0000000..663c839
--- /dev/null
+++ b/src/app/api/pxpipe/status/route.js
@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { getSettings } from "@/lib/localDb";
+import { getPxpipeStatus } from "@/lib/pxpipe/service.js";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  try {
+    const settings = await getSettings();
+    const status = getPxpipeStatus();
+    return NextResponse.json({
+      ...status,
+      enabled: !!settings.pxpipeEnabled,
+      autoInstall: !!settings.pxpipeAutoInstall,
+      minChars: settings.pxpipeMinChars,
+      timeoutMs: settings.pxpipeTimeoutMs,
+    });
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/pxpipe/stop/route.js b/src/app/api/pxpipe/stop/route.js
new file mode 100644
index 0000000..cc675c5
--- /dev/null
+++ b/src/app/api/pxpipe/stop/route.js
@@ -0,0 +1,16 @@
+import { NextResponse } from "next/server";
+import { unloadPxpipe } from "@/lib/pxpipe/loader.js";
+import { getPxpipeStatus } from "@/lib/pxpipe/service.js";
+
+export const dynamic = "force-dynamic";
+
+// "Stop" in library mode = drop the in-process module; requests fail open to
+// uncompressed passthrough until it is started again.
+export async function POST() {
+  try {
+    const wasLoaded = unloadPxpipe();
+    return NextResponse.json({ stopped: wasLoaded, ...getPxpipeStatus() });
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/settings/database/route.js b/src/app/api/settings/database/route.js
new file mode 100644
index 0000000..a20e27b
--- /dev/null
+++ b/src/app/api/settings/database/route.js
@@ -0,0 +1,51 @@
+import { NextResponse } from "next/server";
+import { exportDb, getSettings, importDb } from "@/lib/localDb";
+import { applyOutboundProxyEnv } from "@/lib/network/outboundProxy";
+import { verifyDashboardPassword } from "@/lib/auth/dashboardSession";
+
+const CLI_TOKEN_HEADER = "x-9r-cli-token";
+const PASSWORD_HEADER = "x-9r-password";
+
+// CLI token requests are already trusted (local machine); skip password re-auth.
+function isCliRequest(request) {
+  return Boolean(request.headers.get(CLI_TOKEN_HEADER));
+}
+
+export async function GET(request) {
+  try {
+    if (!isCliRequest(request) && !(await verifyDashboardPassword(request.headers.get(PASSWORD_HEADER)))) {
+      return NextResponse.json({ error: "Invalid password" }, { status: 401 });
+    }
+    const payload = await exportDb();
+    return NextResponse.json(payload);
+  } catch (error) {
+    console.log("Error exporting database:", error);
+    return NextResponse.json({ error: "Failed to export database" }, { status: 500 });
+  }
+}
+
+export async function POST(request) {
+  try {
+    const { password, ...payload } = await request.json();
+    if (!isCliRequest(request) && !(await verifyDashboardPassword(password))) {
+      return NextResponse.json({ error: "Invalid password" }, { status: 401 });
+    }
+    await importDb(payload);
+
+    // Ensure proxy settings take effect immediately after a DB import.
+    try {
+      const settings = await getSettings();
+      applyOutboundProxyEnv(settings);
+    } catch (err) {
+      console.warn("[Settings][DatabaseImport] Failed to re-apply outbound proxy env:", err);
+    }
+
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.log("Error importing database:", error);
+    return NextResponse.json(
+      { error: error?.message || "Failed to import database" },
+      { status: 400 }
+    );
+  }
+}
diff --git a/src/app/api/settings/proxy-test/route.js b/src/app/api/settings/proxy-test/route.js
new file mode 100644
index 0000000..8d390d2
--- /dev/null
+++ b/src/app/api/settings/proxy-test/route.js
@@ -0,0 +1,23 @@
+import { NextResponse } from "next/server";
+import { testProxyUrl } from "@/lib/network/proxyTest";
+
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const result = await testProxyUrl({
+      proxyUrl: body?.proxyUrl,
+      testUrl: body?.testUrl,
+      timeoutMs: body?.timeoutMs,
+    });
+
+    if (result?.ok) {
+      return NextResponse.json(result);
+    }
+
+    const status = typeof result?.status === "number" ? result.status : 500;
+    return NextResponse.json({ ok: false, error: result?.error || "Proxy test failed" }, { status });
+  } catch (err) {
+    const message = err?.name === "AbortError" ? "Proxy test timed out" : (err?.message || String(err));
+    return NextResponse.json({ ok: false, error: message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/settings/require-login/route.js b/src/app/api/settings/require-login/route.js
new file mode 100644
index 0000000..6622721
--- /dev/null
+++ b/src/app/api/settings/require-login/route.js
@@ -0,0 +1,15 @@
+import { NextResponse } from "next/server";
+import { getSettings } from "@/lib/localDb";
+
+export async function GET() {
+  try {
+    const settings = await getSettings();
+    const requireLogin = settings.requireLogin !== false;
+    const tunnelDashboardAccess = settings.tunnelDashboardAccess !== false;
+    const tunnelUrl = settings.tunnelUrl || "";
+    const tailscaleUrl = settings.tailscaleUrl || "";
+    return NextResponse.json({ requireLogin, tunnelDashboardAccess, tunnelUrl, tailscaleUrl });
+  } catch (error) {
+    return NextResponse.json({ requireLogin: true }, { status: 200 });
+  }
+}
diff --git a/src/app/api/settings/route.js b/src/app/api/settings/route.js
new file mode 100644
index 0000000..ccbaee3
--- /dev/null
+++ b/src/app/api/settings/route.js
@@ -0,0 +1,117 @@
+import { NextResponse } from "next/server";
+import { getSettings, updateSettings } from "@/lib/localDb";
+import { applyOutboundProxyEnv } from "@/lib/network/outboundProxy";
+import { resetComboRotation } from "open-sse/services/combo.js";
+import { runQuotaAutoPingTick } from "@/shared/services/quotaAutoPing";
+import bcrypt from "bcryptjs";
+
+export const dynamic = "force-dynamic";
+export const revalidate = 0;
+
+const SETTINGS_RESPONSE_HEADERS = {
+  "Cache-Control": "no-store"
+};
+
+// Secrets must never be mass-assigned from request body (CWE-915)
+const PROTECTED_SETTING_KEYS = ["password", "mitmSudoEncrypted"];
+
+export async function GET() {
+  try {
+    const settings = await getSettings();
+    const { password, oidcClientSecret, ...safeSettings } = settings;
+    safeSettings.oidcConfigured = !!(safeSettings.oidcIssuerUrl && safeSettings.oidcClientId && oidcClientSecret);
+    
+    const enableRequestLogs = process.env.ENABLE_REQUEST_LOGS === "true";
+    const enableTranslator = process.env.ENABLE_TRANSLATOR === "true";
+    
+    return NextResponse.json({ 
+      ...safeSettings, 
+      enableRequestLogs,
+      enableTranslator,
+      hasPassword: !!password
+    }, { headers: SETTINGS_RESPONSE_HEADERS });
+  } catch (error) {
+    console.log("Error getting settings:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
+
+export async function PATCH(request) {
+  try {
+    const body = await request.json();
+
+    // Strip protected secrets before any internal handling sets them
+    for (const key of PROTECTED_SETTING_KEYS) delete body[key];
+
+    // If updating password, hash it
+    if (body.newPassword) {
+      const settings = await getSettings();
+      const currentHash = settings.password;
+
+      // Verify current password if it exists
+      if (currentHash) {
+        if (!body.currentPassword) {
+          return NextResponse.json({ error: "Current password required" }, { status: 400 });
+        }
+        const isValid = await bcrypt.compare(body.currentPassword, currentHash);
+        if (!isValid) {
+          return NextResponse.json({ error: "Invalid current password" }, { status: 401 });
+        }
+      } else {
+        // First time setting password, no current password needed
+        // Allow empty currentPassword or default "123456"
+        if (body.currentPassword && body.currentPassword !== "123456") {
+           return NextResponse.json({ error: "Invalid current password" }, { status: 401 });
+        }
+      }
+
+      const salt = await bcrypt.genSalt(10);
+      body.password = await bcrypt.hash(body.newPassword, salt);
+      delete body.newPassword;
+      delete body.currentPassword;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(body, "oidcClientSecret")) {
+      if (!body.oidcClientSecret || !String(body.oidcClientSecret).trim()) {
+        delete body.oidcClientSecret;
+      }
+    }
+
+    const settings = await updateSettings(body);
+
+    // Apply outbound proxy settings immediately (no restart required)
+    if (
+      Object.prototype.hasOwnProperty.call(body, "outboundProxyEnabled") ||
+      Object.prototype.hasOwnProperty.call(body, "outboundProxyUrl") ||
+      Object.prototype.hasOwnProperty.call(body, "outboundNoProxy")
+    ) {
+      applyOutboundProxyEnv(settings);
+    }
+
+    // Invalidate combo rotation state when strategy settings change
+    if (
+      Object.prototype.hasOwnProperty.call(body, "comboStrategy") ||
+      Object.prototype.hasOwnProperty.call(body, "comboStickyRoundRobinLimit") ||
+      Object.prototype.hasOwnProperty.call(body, "comboStrategies")
+    ) {
+      resetComboRotation();
+    }
+
+    if (
+      Object.prototype.hasOwnProperty.call(body, "claudeAutoPing") ||
+      Object.prototype.hasOwnProperty.call(body, "codexAutoPing")
+    ) {
+      // Run once immediately after opt-in changes so users don't wait for the next scheduler tick.
+      runQuotaAutoPingTick().catch((error) => {
+        console.warn("[AutoPing] settings-triggered tick failed:", error.message);
+      });
+    }
+
+    const { password, oidcClientSecret, ...safeSettings } = settings;
+    safeSettings.oidcConfigured = !!(safeSettings.oidcIssuerUrl && safeSettings.oidcClientId && oidcClientSecret);
+    return NextResponse.json(safeSettings, { headers: SETTINGS_RESPONSE_HEADERS });
+  } catch (error) {
+    console.log("Error updating settings:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/shutdown/route.js b/src/app/api/shutdown/route.js
new file mode 100644
index 0000000..bf7ff10
--- /dev/null
+++ b/src/app/api/shutdown/route.js
@@ -0,0 +1,24 @@
+import { NextResponse } from "next/server";
+import { headers } from "next/headers";
+
+export async function POST() {
+  if (process.env.NODE_ENV === "production") {
+    return NextResponse.json({ success: false, message: "Not allowed in production" }, { status: 403 });
+  }
+
+  const secret = process.env.SHUTDOWN_SECRET;
+  const authorization = headers().get("authorization");
+
+  if (!secret || authorization !== `Bearer ${secret}`) {
+    return NextResponse.json({ success: false, message: "Unauthorized" }, { status: 401 });
+  }
+
+  const response = NextResponse.json({ success: true, message: "Shutting down..." });
+
+  setTimeout(() => {
+    process.exit(0);
+  }, 500);
+
+  return response;
+}
+
diff --git a/src/app/api/tags/route.js b/src/app/api/tags/route.js
new file mode 100644
index 0000000..53bfb2e
--- /dev/null
+++ b/src/app/api/tags/route.js
@@ -0,0 +1,18 @@
+import { ollamaModels } from "open-sse/config/ollamaModels.js";
+
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "*"
+};
+
+export async function OPTIONS() {
+  return new Response(null, { headers: CORS_HEADERS });
+}
+
+export async function GET() {
+  return new Response(JSON.stringify(ollamaModels), {
+    headers: { "Content-Type": "application/json", ...CORS_HEADERS }
+  });
+}
+
diff --git a/src/app/api/translator/console-logs/route.js b/src/app/api/translator/console-logs/route.js
new file mode 100644
index 0000000..43d3e59
--- /dev/null
+++ b/src/app/api/translator/console-logs/route.js
@@ -0,0 +1,24 @@
+import { NextResponse } from "next/server";
+import { clearConsoleLogs, getConsoleLogs, initConsoleLogCapture } from "@/lib/consoleLogBuffer";
+
+initConsoleLogCapture();
+
+export async function GET() {
+  try {
+    const logs = getConsoleLogs();
+    return NextResponse.json({ success: true, logs });
+  } catch (error) {
+    console.error("Error getting console logs:", error);
+    return NextResponse.json({ success: false, error: error.message }, { status: 500 });
+  }
+}
+
+export async function DELETE() {
+  try {
+    clearConsoleLogs();
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.error("Error clearing console logs:", error);
+    return NextResponse.json({ success: false, error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/translator/console-logs/stream/route.js b/src/app/api/translator/console-logs/stream/route.js
new file mode 100644
index 0000000..5eb3ae3
--- /dev/null
+++ b/src/app/api/translator/console-logs/stream/route.js
@@ -0,0 +1,90 @@
+import { getConsoleLogs, getConsoleEmitter, initConsoleLogCapture } from "@/lib/consoleLogBuffer";
+
+export const dynamic = "force-dynamic";
+
+initConsoleLogCapture();
+
+export async function GET(request) {
+  const encoder = new TextEncoder();
+  const emitter = getConsoleEmitter();
+  const state = { closed: false, send: null, sendLines: null, sendClear: null, keepalive: null };
+
+  // Idempotent: safe to call from request.signal abort, cancel(), or enqueue failure.
+  const cleanup = () => {
+    if (state.closed) return;
+    state.closed = true;
+    if (state.send) emitter.off("line", state.send);
+    if (state.sendLines) emitter.off("lines", state.sendLines);
+    if (state.sendClear) emitter.off("clear", state.sendClear);
+    if (state.keepalive) clearInterval(state.keepalive);
+  };
+
+  // request.signal fires reliably on client disconnect; ReadableStream.cancel()
+  // is not always invoked in Next.js, which caused listeners to accumulate.
+  request.signal.addEventListener("abort", cleanup, { once: true });
+
+  const stream = new ReadableStream({
+    start(controller) {
+      // Send all buffered logs immediately on connect
+      const buffered = getConsoleLogs();
+      if (buffered.length > 0) {
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: "init", logs: buffered })}\n\n`));
+      }
+
+      // Push new lines as they arrive
+      state.send = (line) => {
+        if (state.closed) return;
+        try {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: "line", line })}\n\n`));
+        } catch {
+          cleanup();
+        }
+      };
+
+      state.sendLines = (lines) => {
+        if (state.closed || !Array.isArray(lines) || lines.length === 0) return;
+        try {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: "lines", lines })}\n\n`));
+        } catch {
+          cleanup();
+        }
+      };
+
+      // Notify client when cleared
+      state.sendClear = () => {
+        if (state.closed) return;
+        try {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: "clear" })}\n\n`));
+        } catch {
+          cleanup();
+        }
+      };
+
+      emitter.on("line", state.send);
+      emitter.on("lines", state.sendLines);
+      emitter.on("clear", state.sendClear);
+
+      // Keepalive ping every 25s
+      state.keepalive = setInterval(() => {
+        if (state.closed) { clearInterval(state.keepalive); return; }
+        try {
+          controller.enqueue(encoder.encode(": ping\n\n"));
+        } catch {
+          cleanup();
+        }
+      }, 25000);
+    },
+
+    cancel() {
+      cleanup();
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      "Connection": "keep-alive",
+    },
+  });
+}
diff --git a/src/app/api/translator/load/route.js b/src/app/api/translator/load/route.js
new file mode 100644
index 0000000..aa88b83
--- /dev/null
+++ b/src/app/api/translator/load/route.js
@@ -0,0 +1,45 @@
+import { NextResponse } from "next/server";
+import fs from "fs";
+import path from "path";
+
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const file = searchParams.get("file");
+
+    if (!file) {
+      return NextResponse.json({ success: false, error: "File parameter required" }, { status: 400 });
+    }
+
+    // Security: only allow specific filenames
+    const allowedFiles = [
+      "1_req_client.json",
+      "2_req_source.json",
+      "3_req_openai.json",
+      "4_req_target.json",
+      "5_res_provider.txt",
+      "6_res_openai.txt",
+      "7_res_client.txt",
+      "7_res_client.json",
+    ];
+
+    if (!allowedFiles.includes(file)) {
+      return NextResponse.json({ success: false, error: "Invalid file name" }, { status: 400 });
+    }
+
+    const logsDir = path.join(process.cwd(), "logs", "translator");
+    const filePath = path.join(logsDir, file);
+
+    // Check if file exists
+    if (!fs.existsSync(filePath)) {
+      return NextResponse.json({ success: false, error: "File not found" }, { status: 404 });
+    }
+
+    const content = fs.readFileSync(filePath, "utf-8");
+
+    return NextResponse.json({ success: true, content });
+  } catch (error) {
+    console.error("Error loading file:", error);
+    return NextResponse.json({ success: false, error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/translator/save/route.js b/src/app/api/translator/save/route.js
new file mode 100644
index 0000000..eb940f4
--- /dev/null
+++ b/src/app/api/translator/save/route.js
@@ -0,0 +1,44 @@
+import { NextResponse } from "next/server";
+import fs from "fs";
+import path from "path";
+
+export async function POST(request) {
+  try {
+    const { file, content } = await request.json();
+
+    if (!file || content === undefined) {
+      return NextResponse.json({ success: false, error: "File and content required" }, { status: 400 });
+    }
+
+    // Security: only allow specific filenames
+    const allowedFiles = [
+      "1_req_client.json",
+      "2_req_source.json",
+      "3_req_openai.json",
+      "4_req_target.json",
+      "5_res_provider.txt",
+      "6_res_openai.txt",
+      "7_res_client.txt",
+      "7_res_client.json",
+    ];
+
+    if (!allowedFiles.includes(file)) {
+      return NextResponse.json({ success: false, error: "Invalid file name" }, { status: 400 });
+    }
+
+    const logsDir = path.join(process.cwd(), "logs", "translator");
+    
+    // Create directory if not exists
+    if (!fs.existsSync(logsDir)) {
+      fs.mkdirSync(logsDir, { recursive: true });
+    }
+
+    const filePath = path.join(logsDir, file);
+    fs.writeFileSync(filePath, content, "utf-8");
+
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.error("Error saving file:", error);
+    return NextResponse.json({ success: false, error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/translator/send/route.js b/src/app/api/translator/send/route.js
new file mode 100644
index 0000000..0e752ef
--- /dev/null
+++ b/src/app/api/translator/send/route.js
@@ -0,0 +1,94 @@
+import { getProviderConnections, updateProviderConnection } from "@/lib/localDb.js";
+import { getExecutor } from "open-sse/index.js";
+
+async function persistRefreshedCredentials(connection, newCredentials) {
+  const updateData = {};
+
+  if (newCredentials.accessToken) updateData.accessToken = newCredentials.accessToken;
+  if (newCredentials.refreshToken) updateData.refreshToken = newCredentials.refreshToken;
+  if (newCredentials.idToken) updateData.idToken = newCredentials.idToken;
+  if (newCredentials.lastRefreshAt) updateData.lastRefreshAt = newCredentials.lastRefreshAt;
+  if (newCredentials.expiresIn) {
+    updateData.expiresIn = newCredentials.expiresIn;
+    updateData.expiresAt = new Date(Date.now() + newCredentials.expiresIn * 1000).toISOString();
+  } else if (newCredentials.expiresAt) {
+    updateData.expiresAt = newCredentials.expiresAt;
+  }
+
+  const providerSpecificUpdates = {
+    ...(newCredentials.providerSpecificData || {}),
+    ...(newCredentials.copilotToken ? { copilotToken: newCredentials.copilotToken } : {}),
+    ...(newCredentials.copilotTokenExpiresAt ? { copilotTokenExpiresAt: newCredentials.copilotTokenExpiresAt } : {}),
+  };
+  if (Object.keys(providerSpecificUpdates).length > 0) {
+    updateData.providerSpecificData = {
+      ...(connection.providerSpecificData || {}),
+      ...providerSpecificUpdates,
+    };
+  }
+
+  if (Object.keys(updateData).length > 0) {
+    await updateProviderConnection(connection.id, updateData);
+  }
+}
+
+export async function POST(request) {
+  try {
+    const { provider, model, body } = await request.json();
+
+    if (!provider || !model || !body) {
+      return Response.json({ success: false, error: "provider, model, and body required" }, { status: 400 });
+    }
+
+    const connections = await getProviderConnections({ provider });
+    const connection = connections.find(c => c.isActive !== false);
+    if (!connection) {
+      return Response.json({ success: false, error: `No active connection for provider: ${provider}` }, { status: 400 });
+    }
+
+    const credentials = {
+      apiKey: connection.apiKey,
+      accessToken: connection.accessToken,
+      refreshToken: connection.refreshToken,
+      idToken: connection.idToken,
+      lastRefreshAt: connection.lastRefreshAt,
+      connectionId: connection.id,
+      copilotToken: connection.providerSpecificData?.copilotToken,
+      copilotTokenExpiresAt: connection.providerSpecificData?.copilotTokenExpiresAt,
+      projectId: connection.projectId,
+      providerSpecificData: connection.providerSpecificData
+    };
+
+    const executor = getExecutor(provider);
+    const stream = body.stream !== false;
+
+    let { response } = await executor.execute({ model, body, stream, credentials });
+
+    // Auto-refresh token on 401/403 and retry (same as chatCore.js)
+    if (response.status === 401 || response.status === 403) {
+      const newCredentials = await executor.refreshCredentials(credentials, console);
+      if (newCredentials?.accessToken || newCredentials?.copilotToken) {
+        Object.assign(credentials, newCredentials);
+        await persistRefreshedCredentials(connection, newCredentials);
+        ({ response } = await executor.execute({ model, body, stream, credentials }));
+      }
+    }
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      console.error(`[Translator] Provider error ${response.status}:`, errorText.slice(0, 500));
+      return Response.json({ success: false, error: `Provider error: ${response.status}`, details: errorText }, { status: response.status });
+    }
+
+    return new Response(response.body, {
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive"
+      }
+    });
+  } catch (error) {
+    console.error("[Translator] Send error:", error);
+    return Response.json({ success: false, error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/translator/translate/route.js b/src/app/api/translator/translate/route.js
new file mode 100644
index 0000000..c0f3c12
--- /dev/null
+++ b/src/app/api/translator/translate/route.js
@@ -0,0 +1,90 @@
+import { NextResponse } from "next/server";
+import { detectFormat, getTargetFormat } from "open-sse/services/provider.js";
+import { translateRequest } from "open-sse/translator/index.js";
+import { FORMATS } from "open-sse/translator/formats.js";
+import { getModelInfo } from "@/sse/services/model.js";
+import { getProviderConnections } from "@/lib/localDb.js";
+import { getExecutor } from "open-sse/executors/index.js";
+
+export async function POST(request) {
+  try {
+    const { step, body } = await request.json();
+
+    if (!step || !body) {
+      return NextResponse.json({ success: false, error: "Step and body required" }, { status: 400 });
+    }
+
+    switch (step) {
+      case 1: {
+        // Detect provider + formats from 1_req_client.json
+        const clientBody = body.body || body;
+        const { provider, model } = await getModelInfo(clientBody.model);
+        const sourceFormat = detectFormat(clientBody);
+        const targetFormat = getTargetFormat(provider);
+        return NextResponse.json({ success: true, result: { provider, model, sourceFormat, targetFormat } });
+      }
+
+      case 2: {
+        // source → OpenAI intermediate (mirrors 3_req_openai.json)
+        // Translate source→openai only (half of the pipeline)
+        const clientBody = body.body || body;
+        const { provider, model } = await getModelInfo(clientBody.model);
+        const sourceFormat = detectFormat(clientBody);
+        const stream = clientBody.stream !== false;
+
+        // translateRequest(source, OPENAI) = only the first half
+        const result = translateRequest(sourceFormat, FORMATS.OPENAI, model, clientBody, stream, null, provider);
+        delete result._toolNameMap;
+
+        return NextResponse.json({ success: true, result: { body: result } });
+      }
+
+      case 3: {
+        // OpenAI intermediate → target + build URL/headers (mirrors 4_req_target.json)
+        const openaiBody = body.body || body;
+        const provider = body.provider;
+        const model = body.model;
+
+        if (!provider || !model) {
+          return NextResponse.json({ success: false, error: "provider and model required" }, { status: 400 });
+        }
+
+        const targetFormat = getTargetFormat(provider);
+        const stream = openaiBody.stream !== false;
+
+        // translateRequest(OPENAI, target) = second half of pipeline
+        const translated = translateRequest(FORMATS.OPENAI, targetFormat, model, openaiBody, stream, null, provider);
+        delete translated._toolNameMap;
+
+        // Build URL + headers via executor (same as chatCore → executor.execute)
+        const connections = await getProviderConnections({ provider });
+        const connection = connections.find(c => c.isActive !== false);
+        if (!connection) {
+          return NextResponse.json({ success: false, error: `No active connection for provider: ${provider}` }, { status: 400 });
+        }
+
+        const credentials = {
+          apiKey: connection.apiKey,
+          accessToken: connection.accessToken,
+          refreshToken: connection.refreshToken,
+          copilotToken: connection.copilotToken,
+          projectId: connection.projectId,
+          providerSpecificData: connection.providerSpecificData
+        };
+
+        const executor = getExecutor(provider);
+        const url = executor.buildUrl(model, stream, 0, credentials);
+        const headers = executor.buildHeaders(credentials, stream);
+        const finalBody = executor.transformRequest(model, translated, stream, credentials);
+
+        return NextResponse.json({ success: true, result: { url, headers, body: finalBody } });
+      }
+
+      default:
+        return NextResponse.json({ success: false, error: "Invalid step (1-3)" }, { status: 400 });
+    }
+  } catch (error) {
+    console.error("Error in translator:", error);
+    return NextResponse.json({ success: false, error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/tunnel/disable/route.js b/src/app/api/tunnel/disable/route.js
new file mode 100644
index 0000000..2d49e03
--- /dev/null
+++ b/src/app/api/tunnel/disable/route.js
@@ -0,0 +1,12 @@
+import { NextResponse } from "next/server";
+import { disableTunnel } from "@/lib/tunnel";
+
+export async function POST() {
+  try {
+    const result = await disableTunnel();
+    return NextResponse.json(result);
+  } catch (error) {
+    console.error("Tunnel disable error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/tunnel/enable/route.js b/src/app/api/tunnel/enable/route.js
new file mode 100644
index 0000000..910ad61
--- /dev/null
+++ b/src/app/api/tunnel/enable/route.js
@@ -0,0 +1,16 @@
+import { NextResponse } from "next/server";
+import { enableTunnel } from "@/lib/tunnel";
+
+const DNS_WARMUP_DELAY_MS = 8000;
+
+export async function POST() {
+  try {
+    const result = await enableTunnel();
+    // Wait for DNS warmup to propagate at Cloudflare edge after tunnel registered
+    await new Promise((r) => setTimeout(r, DNS_WARMUP_DELAY_MS));
+    return NextResponse.json(result);
+  } catch (error) {
+    console.error("Tunnel enable error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/tunnel/status/route.js b/src/app/api/tunnel/status/route.js
new file mode 100644
index 0000000..8b8f805
--- /dev/null
+++ b/src/app/api/tunnel/status/route.js
@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+import { getTunnelStatus, getTailscaleStatus, getDownloadStatus } from "@/lib/tunnel";
+
+const STATUS_CACHE_TTL_MS = 3000; // coalesce rapid polls; underlying probes already cache 10s
+
+// Survive hot reload; one cache per process. Only tunnel/tailscale probes are cached —
+// download progress stays live so the enable/download UI updates smoothly.
+const statusCache = (global.__tunnelStatusCache ??= { value: null, fetchedAt: 0 });
+
+export async function GET() {
+  try {
+    let probes = statusCache.value;
+    if (!probes || Date.now() - statusCache.fetchedAt >= STATUS_CACHE_TTL_MS) {
+      const [tunnel, tailscale] = await Promise.all([getTunnelStatus(), getTailscaleStatus()]);
+      probes = { tunnel, tailscale };
+      statusCache.value = probes;
+      statusCache.fetchedAt = Date.now();
+    }
+    const download = getDownloadStatus();
+    return NextResponse.json({ ...probes, download });
+  } catch (error) {
+    console.error("Tunnel status error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/tunnel/tailscale-check/route.js b/src/app/api/tunnel/tailscale-check/route.js
new file mode 100644
index 0000000..f1a830a
--- /dev/null
+++ b/src/app/api/tunnel/tailscale-check/route.js
@@ -0,0 +1,54 @@
+import os from "os";
+import { exec } from "child_process";
+import { promisify } from "util";
+import { NextResponse } from "next/server";
+import { isTailscaleInstalled, isTailscaleLoggedIn, isSystemDaemonRunning, getTailscaleBin, TAILSCALE_SOCKET } from "@/lib/tunnel";
+import { getCachedPassword, loadEncryptedPassword } from "@/mitm/manager";
+
+const execAsync = promisify(exec);
+const EXTENDED_PATH = `/usr/local/bin:/opt/homebrew/bin:/usr/sbin:/usr/bin:/bin:/snap/bin:${process.env.PATH || ""}`;
+const PROBE_TIMEOUT_MS = 1500;
+
+async function hasBrew() {
+  try {
+    await execAsync("which brew", { windowsHide: true, env: { ...process.env, PATH: EXTENDED_PATH }, timeout: PROBE_TIMEOUT_MS });
+    return true;
+  } catch { return false; }
+}
+
+async function isCustomDaemonRunning() {
+  const bin = getTailscaleBin();
+  if (!bin) return false;
+  try {
+    await execAsync(`"${bin}" --socket ${TAILSCALE_SOCKET} status --json`, {
+      windowsHide: true,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+      timeout: PROBE_TIMEOUT_MS
+    });
+    return true;
+  } catch {
+    try {
+      await execAsync("pgrep -x tailscaled", { windowsHide: true, timeout: PROBE_TIMEOUT_MS });
+      return true;
+    } catch { return false; }
+  }
+}
+
+export async function GET() {
+  try {
+    const installed = isTailscaleInstalled();
+    const platform = os.platform();
+    // Run independent probes in parallel — none blocks the event loop
+    const [brewAvailable, customDaemonRunning, systemDaemonRunning] = await Promise.all([
+      platform === "darwin" ? hasBrew() : Promise.resolve(false),
+      installed ? isCustomDaemonRunning() : Promise.resolve(false),
+      installed ? Promise.resolve(isSystemDaemonRunning()) : Promise.resolve(false),
+    ]);
+    const daemonRunning = customDaemonRunning || systemDaemonRunning;
+    const loggedIn = daemonRunning ? isTailscaleLoggedIn() : false;
+    const hasCachedPassword = !!(getCachedPassword() || await loadEncryptedPassword());
+    return NextResponse.json({ installed, loggedIn, platform, brewAvailable, daemonRunning, customDaemonRunning, systemDaemonRunning, hasCachedPassword });
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/tunnel/tailscale-disable/route.js b/src/app/api/tunnel/tailscale-disable/route.js
new file mode 100644
index 0000000..1a0dca0
--- /dev/null
+++ b/src/app/api/tunnel/tailscale-disable/route.js
@@ -0,0 +1,12 @@
+import { NextResponse } from "next/server";
+import { disableTailscale } from "@/lib/tunnel";
+
+export async function POST() {
+  try {
+    const result = await disableTailscale();
+    return NextResponse.json(result);
+  } catch (error) {
+    console.error("Tailscale disable error:", error);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/tunnel/tailscale-enable/route.js b/src/app/api/tunnel/tailscale-enable/route.js
new file mode 100644
index 0000000..61b7bda
--- /dev/null
+++ b/src/app/api/tunnel/tailscale-enable/route.js
@@ -0,0 +1,12 @@
+import { NextResponse } from "next/server";
+import { enableTailscale } from "@/lib/tunnel";
+
+export async function POST() {
+  try {
+    const result = await enableTailscale();
+    return NextResponse.json(result);
+  } catch (error) {
+    console.error("Tailscale enable error:", error.message);
+    return NextResponse.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/tunnel/tailscale-install/route.js b/src/app/api/tunnel/tailscale-install/route.js
new file mode 100644
index 0000000..f53c5ee
--- /dev/null
+++ b/src/app/api/tunnel/tailscale-install/route.js
@@ -0,0 +1,72 @@
+"use server";
+
+import os from "os";
+import { execSync } from "child_process";
+import { installTailscale, loadState, generateShortId } from "@/lib/tunnel";
+import { getCachedPassword, loadEncryptedPassword, initDbHooks } from "@/mitm/manager";
+import { getSettings, updateSettings } from "@/lib/localDb";
+
+initDbHooks(getSettings, updateSettings);
+
+const EXTENDED_PATH = `/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:${process.env.PATH || ""}`;
+
+function hasBrew() {
+  try { execSync("which brew", { stdio: "ignore", windowsHide: true, env: { ...process.env, PATH: EXTENDED_PATH } }); return true; } catch { return false; }
+}
+
+export async function POST(request) {
+  const body = await request.json().catch(() => ({}));
+  const platform = os.platform();
+  const isWindows = platform === "win32";
+  const isBrew = platform === "darwin" && hasBrew();
+  const needsPassword = !isWindows && !isBrew;
+
+  const sudoPassword = body.sudoPassword || getCachedPassword() || await loadEncryptedPassword() || "";
+
+  if (needsPassword && !sudoPassword.trim()) {
+    return new Response(JSON.stringify({ error: "Sudo password is required" }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  const shortId = loadState()?.shortId || generateShortId();
+
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    async start(controller) {
+      let closed = false;
+      const send = (event, data) => {
+        if (closed) return;
+        try {
+          controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+        } catch {
+          closed = true;
+        }
+      };
+
+      try {
+        const result = await installTailscale(sudoPassword, shortId, (msg) => {
+          send("progress", { message: msg });
+        });
+        send("done", { success: true, authUrl: result?.authUrl || null });
+      } catch (error) {
+        console.error("Tailscale install error:", error);
+        const msg = error.message?.includes("incorrect password") || error.message?.includes("Sorry")
+          ? "Wrong sudo password"
+          : error.message;
+        send("error", { error: msg });
+      } finally {
+        if (!closed) { try { controller.close(); } catch {} }
+      }
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      "Connection": "keep-alive",
+    },
+  });
+}
diff --git a/src/app/api/usage/[connectionId]/codex-reset-credits/route.js b/src/app/api/usage/[connectionId]/codex-reset-credits/route.js
new file mode 100644
index 0000000..0fb4626
--- /dev/null
+++ b/src/app/api/usage/[connectionId]/codex-reset-credits/route.js
@@ -0,0 +1,156 @@
+// Ensure proxyFetch is loaded to patch globalThis.fetch
+import "open-sse/index.js";
+
+import { getProviderConnectionById } from "@/lib/localDb";
+import { consumeCodexRateLimitResetCredit, getCodexRateLimitResetCredits } from "open-sse/services/usage.js";
+import { resolveConnectionProxyConfig } from "@/lib/network/connectionProxy";
+import { refreshAndUpdateCredentials } from "../route.js";
+
+const AUTH_EXPIRED_PATTERNS = ["expired", "authentication", "unauthorized", "401", "re-authorize"];
+
+function isAuthExpiredResult(result) {
+  const values = [result?.message, result?.code, result?.raw?.detail, result?.raw?.error]
+    .filter(Boolean)
+    .map((value) => String(value).toLowerCase());
+  return values.some((value) => AUTH_EXPIRED_PATTERNS.some((pattern) => value.includes(pattern)));
+}
+
+function isAuthExpiredError(error) {
+  return isAuthExpiredResult({ message: error?.message });
+}
+
+function getResponseForConsumeResult(result, redeemRequestId) {
+  if (result.ok) {
+    return Response.json({
+      code: result.code,
+      reset: true,
+      windows_reset: result.windowsReset,
+      redeemRequestId,
+      credit: result.raw?.credit || null,
+    });
+  }
+
+  if (result.noCredit) {
+    return Response.json({
+      code: "no_credit",
+      reset: false,
+      windows_reset: result.windowsReset,
+      message: "No Codex reset credits available.",
+    }, { status: 409 });
+  }
+
+  return Response.json({
+    code: result.code || "unknown_response",
+    reset: false,
+    windows_reset: result.windowsReset,
+    message: result.message || "Codex reset credit consume returned an unexpected response.",
+  }, { status: result.status >= 400 && result.status < 500 ? result.status : 502 });
+}
+
+async function getCodexConnection(connectionId) {
+  const connection = await getProviderConnectionById(connectionId);
+  if (!connection) {
+    return { response: Response.json({ error: "Connection not found" }, { status: 404 }) };
+  }
+
+  if (connection.provider !== "codex") {
+    return { response: Response.json({ error: "Codex reset credits are only available for Codex connections." }, { status: 400 }) };
+  }
+
+  const isOAuth = connection.authType === "oauth";
+  const isAccessToken = connection.authType === "access_token";
+  if (!isOAuth && !isAccessToken) {
+    return { response: Response.json({ error: "Codex reset credits require an OAuth or access-token connection." }, { status: 400 }) };
+  }
+
+  const proxyConfig = await resolveConnectionProxyConfig(connection.providerSpecificData);
+  const proxyOptions = {
+    connectionProxyEnabled: proxyConfig.connectionProxyEnabled === true,
+    connectionProxyUrl: proxyConfig.connectionProxyUrl || "",
+    connectionNoProxy: proxyConfig.connectionNoProxy || "",
+    vercelRelayUrl: proxyConfig.vercelRelayUrl || "",
+    strictProxy: false,
+  };
+
+  return { connection, isOAuth, proxyOptions };
+}
+
+async function refreshCodexConnection(connection, proxyOptions) {
+  try {
+    const result = await refreshAndUpdateCredentials(connection, false, proxyOptions);
+    return { connection: result.connection };
+  } catch (refreshError) {
+    console.error("[Codex Reset Credits API] Credential refresh failed:", refreshError);
+    return { response: Response.json({ error: `Credential refresh failed: ${refreshError.message}` }, { status: 401 }) };
+  }
+}
+
+export async function GET(_request, { params }) {
+  let connection;
+  try {
+    const { connectionId } = await params;
+    const resolved = await getCodexConnection(connectionId);
+    if (resolved.response) return resolved.response;
+    ({ connection } = resolved);
+    const { isOAuth, proxyOptions } = resolved;
+
+    if (isOAuth) {
+      const refreshed = await refreshCodexConnection(connection, proxyOptions);
+      if (refreshed.response) return refreshed.response;
+      connection = refreshed.connection;
+    }
+
+    let result;
+    try {
+      result = await getCodexRateLimitResetCredits(connection.accessToken, proxyOptions, connection.providerSpecificData);
+    } catch (fetchError) {
+      if (!isOAuth || !connection.refreshToken || !isAuthExpiredError(fetchError)) throw fetchError;
+      const retryResult = await refreshAndUpdateCredentials(connection, true, proxyOptions);
+      connection = retryResult.connection;
+      result = await getCodexRateLimitResetCredits(connection.accessToken, proxyOptions, connection.providerSpecificData);
+    }
+
+    return Response.json(result);
+  } catch (error) {
+    const provider = connection?.provider ?? "unknown";
+    console.warn(`[Codex Reset Credits] ${provider}: ${error.message}`);
+    return Response.json({ error: error.message }, { status: 500 });
+  }
+}
+
+export async function POST(request, { params }) {
+  let connection;
+  try {
+    const { connectionId } = await params;
+    const resolved = await getCodexConnection(connectionId);
+    if (resolved.response) return resolved.response;
+    ({ connection } = resolved);
+    const { isOAuth, proxyOptions } = resolved;
+
+    if (isOAuth) {
+      const refreshed = await refreshCodexConnection(connection, proxyOptions);
+      if (refreshed.response) return refreshed.response;
+      connection = refreshed.connection;
+    }
+
+    // Server-generated redeem id prevents client-controlled replay
+    const redeemRequestId = crypto.randomUUID();
+    let consumeResult = await consumeCodexRateLimitResetCredit(connection.accessToken, redeemRequestId, proxyOptions);
+
+    if (isOAuth && isAuthExpiredResult(consumeResult) && connection.refreshToken) {
+      try {
+        const retryResult = await refreshAndUpdateCredentials(connection, true, proxyOptions);
+        connection = retryResult.connection;
+        consumeResult = await consumeCodexRateLimitResetCredit(connection.accessToken, redeemRequestId, proxyOptions);
+      } catch (retryError) {
+        console.warn(`[Codex Reset Credits] force refresh failed: ${retryError.message}`);
+      }
+    }
+
+    return getResponseForConsumeResult(consumeResult, redeemRequestId);
+  } catch (error) {
+    const provider = connection?.provider ?? "unknown";
+    console.warn(`[Codex Reset Credits] ${provider}: ${error.message}`);
+    return Response.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/usage/[connectionId]/route.js b/src/app/api/usage/[connectionId]/route.js
new file mode 100644
index 0000000..8ccdc01
--- /dev/null
+++ b/src/app/api/usage/[connectionId]/route.js
@@ -0,0 +1,191 @@
+// Ensure proxyFetch is loaded to patch globalThis.fetch
+import "open-sse/index.js";
+
+import { getProviderConnectionById, updateProviderConnection } from "@/lib/localDb";
+import { getUsageForProvider } from "open-sse/services/usage.js";
+import { getExecutor } from "open-sse/executors/index.js";
+import { resolveConnectionProxyConfig } from "@/lib/network/connectionProxy";
+import { USAGE_APIKEY_PROVIDERS } from "@/shared/constants/providers";
+
+// Detect auth-expired messages returned by usage providers instead of throwing
+const AUTH_EXPIRED_PATTERNS = ["expired", "authentication", "unauthorized", "401", "re-authorize"];
+function isAuthExpiredMessage(usage) {
+  if (!usage?.message) return false;
+  const msg = usage.message.toLowerCase();
+  return AUTH_EXPIRED_PATTERNS.some((p) => msg.includes(p));
+}
+
+/**
+ * Refresh credentials using executor and update database
+ * @param {boolean} force - Skip needsRefresh check and always attempt refresh
+ * @returns Promise<{ connection, refreshed: boolean }>
+ */
+export async function refreshAndUpdateCredentials(connection, force = false, proxyOptions = null) {
+  const executor = getExecutor(connection.provider);
+
+  // Build credentials object from connection
+  const credentials = {
+    accessToken: connection.accessToken,
+    refreshToken: connection.refreshToken,
+    idToken: connection.idToken,
+    expiresAt: connection.expiresAt || connection.tokenExpiresAt,
+    lastRefreshAt: connection.lastRefreshAt,
+    connectionId: connection.id,
+    providerSpecificData: connection.providerSpecificData,
+    // For GitHub
+    copilotToken: connection.providerSpecificData?.copilotToken,
+    copilotTokenExpiresAt: connection.providerSpecificData?.copilotTokenExpiresAt,
+  };
+
+  // Check if refresh is needed (skip when force=true)
+  const needsRefresh = force || executor.needsRefresh(credentials);
+
+  if (!needsRefresh) {
+    return { connection, refreshed: false };
+  }
+
+  // Use executor's refreshCredentials method (with optional proxy)
+  const refreshResult = await executor.refreshCredentials(credentials, console, proxyOptions);
+
+  if (!refreshResult) {
+    // Refresh failed but we still have an accessToken — try with existing token
+    if (connection.accessToken) {
+      return { connection, refreshed: false };
+    }
+    throw new Error("Failed to refresh credentials. Please re-authorize the connection.");
+  }
+
+  // Build update object
+  const now = new Date().toISOString();
+  const updateData = {
+    updatedAt: now,
+  };
+
+  // Update accessToken if present
+  if (refreshResult.accessToken) {
+    updateData.accessToken = refreshResult.accessToken;
+  }
+
+  // Update refreshToken if present
+  if (refreshResult.refreshToken) {
+    updateData.refreshToken = refreshResult.refreshToken;
+  }
+
+  if (refreshResult.idToken) {
+    updateData.idToken = refreshResult.idToken;
+  }
+
+  if (refreshResult.lastRefreshAt) {
+    updateData.lastRefreshAt = refreshResult.lastRefreshAt;
+  }
+
+  // Update token expiry
+  if (refreshResult.expiresIn) {
+    updateData.expiresAt = new Date(Date.now() + refreshResult.expiresIn * 1000).toISOString();
+    updateData.expiresIn = refreshResult.expiresIn;
+  } else if (refreshResult.expiresAt) {
+    updateData.expiresAt = refreshResult.expiresAt;
+  }
+
+  // Handle provider-specific data (copilotToken for GitHub, etc.)
+  const providerSpecificUpdates = {
+    ...(refreshResult.providerSpecificData || {}),
+    ...(refreshResult.copilotToken ? { copilotToken: refreshResult.copilotToken } : {}),
+    ...(refreshResult.copilotTokenExpiresAt ? { copilotTokenExpiresAt: refreshResult.copilotTokenExpiresAt } : {}),
+  };
+  if (Object.keys(providerSpecificUpdates).length > 0) {
+    updateData.providerSpecificData = {
+      ...(connection.providerSpecificData || {}),
+      ...providerSpecificUpdates,
+    };
+  }
+
+  // Update database
+  await updateProviderConnection(connection.id, updateData);
+
+  // Return updated connection
+  const updatedConnection = {
+    ...connection,
+    ...updateData,
+    providerSpecificData: updateData.providerSpecificData || connection.providerSpecificData,
+  };
+
+  return {
+    connection: updatedConnection,
+    refreshed: true,
+  };
+}
+
+/**
+ * GET /api/usage/[connectionId] - Get usage data for a specific connection
+ */
+export async function GET(request, { params }) {
+  let connection;
+  try {
+    const { connectionId } = await params;
+
+
+    // Get connection from database
+    connection = await getProviderConnectionById(connectionId);
+    if (!connection) {
+      return Response.json({ error: "Connection not found" }, { status: 404 });
+    }
+
+    // Allow OAuth connections, plus whitelisted apikey providers (glm/minimax/kiro/...)
+    // Kiro's headless api-key flow persists authType "api_key" (underscore) while
+    // generic apikey providers persist "apikey" — accept both spellings here.
+    const isOAuth = connection.authType === "oauth";
+    const isApikeyAuth =
+      connection.authType === "apikey" || connection.authType === "api_key";
+    const isApikeyEligible =
+      isApikeyAuth && USAGE_APIKEY_PROVIDERS.includes(connection.provider);
+
+    if (!isOAuth && !isApikeyEligible) {
+      return Response.json({ message: "Usage not available for this connection" });
+    }
+
+    // Resolve connection proxy config; force strictProxy=false so quota/refresh fall back to direct on failure
+    const proxyConfig = await resolveConnectionProxyConfig(connection.providerSpecificData);
+    const proxyOptions = {
+      connectionProxyEnabled: proxyConfig.connectionProxyEnabled === true,
+      connectionProxyUrl: proxyConfig.connectionProxyUrl || "",
+      connectionNoProxy: proxyConfig.connectionNoProxy || "",
+      vercelRelayUrl: proxyConfig.vercelRelayUrl || "",
+      strictProxy: false,
+    };
+
+    // Refresh credentials only for OAuth connections (apikey has no token refresh)
+    if (isOAuth) {
+      try {
+        const result = await refreshAndUpdateCredentials(connection, false, proxyOptions);
+        connection = result.connection;
+      } catch (refreshError) {
+        console.error("[Usage API] Credential refresh failed:", refreshError);
+        return Response.json({
+          error: `Credential refresh failed: ${refreshError.message}`
+        }, { status: 401 });
+      }
+    }
+
+    // Fetch usage from provider API
+    let usage = await getUsageForProvider(connection, proxyOptions);
+
+    // If provider returned an auth-expired message instead of throwing,
+    // force-refresh token and retry once (OAuth only)
+    if (isOAuth && isAuthExpiredMessage(usage) && connection.refreshToken) {
+      try {
+        const retryResult = await refreshAndUpdateCredentials(connection, true, proxyOptions);
+        connection = retryResult.connection;
+        usage = await getUsageForProvider(connection, proxyOptions);
+      } catch (retryError) {
+        console.warn(`[Usage] ${connection.provider}: force refresh failed: ${retryError.message}`);
+      }
+    }
+
+    return Response.json(usage);
+  } catch (error) {
+    const provider = connection?.provider ?? "unknown";
+    console.warn(`[Usage] ${provider}: ${error.message}`);
+    return Response.json({ error: error.message }, { status: 500 });
+  }
+}
diff --git a/src/app/api/usage/chart/route.js b/src/app/api/usage/chart/route.js
new file mode 100644
index 0000000..063cedd
--- /dev/null
+++ b/src/app/api/usage/chart/route.js
@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { getChartData } from "@/lib/usageDb";
+
+const VALID_PERIODS = new Set(["today", "24h", "7d", "30d", "60d"]);
+
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const period = searchParams.get("period") || "7d";
+
+    if (!VALID_PERIODS.has(period)) {
+      return NextResponse.json({ error: "Invalid period" }, { status: 400 });
+    }
+
+    const data = await getChartData(period);
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error("[API] Failed to get chart data:", error);
+    return NextResponse.json({ error: "Failed to fetch chart data" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/usage/history/route.js b/src/app/api/usage/history/route.js
new file mode 100644
index 0000000..16a5d40
--- /dev/null
+++ b/src/app/api/usage/history/route.js
@@ -0,0 +1,12 @@
+import { NextResponse } from "next/server";
+import { getUsageStats } from "@/lib/usageDb";
+
+export async function GET() {
+  try {
+    const stats = await getUsageStats();
+    return NextResponse.json(stats);
+  } catch (error) {
+    console.error("Error fetching usage stats:", error);
+    return NextResponse.json({ error: "Failed to fetch usage stats" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/usage/logs/route.js b/src/app/api/usage/logs/route.js
new file mode 100644
index 0000000..b5b875e
--- /dev/null
+++ b/src/app/api/usage/logs/route.js
@@ -0,0 +1,12 @@
+import { NextResponse } from "next/server";
+import { getRecentLogs } from "@/lib/usageDb";
+
+export async function GET() {
+  try {
+    const logs = await getRecentLogs(200);
+    return NextResponse.json(logs);
+  } catch (error) {
+    console.error("Error fetching logs:", error);
+    return NextResponse.json({ error: "Failed to fetch logs" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/usage/providers/route.js b/src/app/api/usage/providers/route.js
new file mode 100644
index 0000000..8523b8b
--- /dev/null
+++ b/src/app/api/usage/providers/route.js
@@ -0,0 +1,41 @@
+import { NextResponse } from "next/server";
+import { getDistinctProviders } from "@/lib/requestDetailsDb";
+import { getProviderNodes } from "@/lib/localDb";
+import { AI_PROVIDERS, getProviderByAlias } from "@/shared/constants/providers";
+
+/**
+ * GET /api/usage/providers
+ * Returns list of unique providers from request details
+ */
+export async function GET() {
+  try {
+    // Query DISTINCT provider column directly — avoids parsing every row's
+    // full JSON blob (can be hundreds of MB), which previously caused OOM.
+    const providerIds = await getDistinctProviders();
+
+    const providerNodes = await getProviderNodes();
+    const nodeMap = {};
+    for (const node of providerNodes) {
+      nodeMap[node.id] = node.name;
+    }
+
+    const providers = providerIds.map(providerId => {
+      let name = providerId;
+      if (nodeMap[providerId]) {
+        name = nodeMap[providerId];
+      } else {
+        const providerConfig = getProviderByAlias(providerId) || AI_PROVIDERS[providerId];
+        if (providerConfig?.name) name = providerConfig.name;
+      }
+      return { id: providerId, name };
+    });
+
+    return NextResponse.json({ providers });
+  } catch (error) {
+    console.error("[API] Failed to get providers:", error);
+    return NextResponse.json(
+      { error: "Failed to fetch providers" },
+      { status: 500 }
+    );
+  }
+}
diff --git a/src/app/api/usage/request-details/route.js b/src/app/api/usage/request-details/route.js
new file mode 100644
index 0000000..9b15449
--- /dev/null
+++ b/src/app/api/usage/request-details/route.js
@@ -0,0 +1,59 @@
+import { NextResponse } from "next/server";
+import { getRequestDetails } from "@/lib/usageDb";
+
+/**
+ * GET /api/usage/request-details
+ * Query parameters: page, pageSize (1-100), provider, model, connectionId, status, startDate, endDate
+ */
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    
+    const pageRaw = parseInt(searchParams.get("page"));
+    const page = Number.isNaN(pageRaw) ? 1 : pageRaw;
+    const pageSizeRaw = parseInt(searchParams.get("pageSize"));
+    const pageSize = Number.isNaN(pageSizeRaw) ? 20 : pageSizeRaw;
+    const provider = searchParams.get("provider");
+    const model = searchParams.get("model");
+    const connectionId = searchParams.get("connectionId");
+    const status = searchParams.get("status");
+    const startDate = searchParams.get("startDate");
+    const endDate = searchParams.get("endDate");
+    
+    if (page < 1) {
+      return NextResponse.json(
+        { error: "Page must be >= 1" },
+        { status: 400 }
+      );
+    }
+    
+    if (pageSize < 1 || pageSize > 100) {
+      return NextResponse.json(
+        { error: "PageSize must be between 1 and 100" },
+        { status: 400 }
+      );
+    }
+    
+    const filter = {
+      page,
+      pageSize
+    };
+    
+    if (provider) filter.provider = provider;
+    if (model) filter.model = model;
+    if (connectionId) filter.connectionId = connectionId;
+    if (status) filter.status = status;
+    if (startDate) filter.startDate = startDate;
+    if (endDate) filter.endDate = endDate;
+    
+    const result = await getRequestDetails(filter);
+    
+    return NextResponse.json(result);
+  } catch (error) {
+    console.error("[API] Failed to get request details:", error);
+    return NextResponse.json(
+      { error: "Failed to fetch request details" },
+      { status: 500 }
+    );
+  }
+}
diff --git a/src/app/api/usage/request-logs/route.js b/src/app/api/usage/request-logs/route.js
new file mode 100644
index 0000000..0ae5e96
--- /dev/null
+++ b/src/app/api/usage/request-logs/route.js
@@ -0,0 +1,13 @@
+import { NextResponse } from "next/server";
+import { getRecentLogs } from "@/lib/usageDb";
+
+export async function GET() {
+  try {
+    const logs = await getRecentLogs(200);
+    return NextResponse.json(logs);
+  } catch (error) {
+    console.error("[API ERROR] /api/usage/logs failed:", error);
+    console.error("[API ERROR] Stack:", error?.stack);
+    return NextResponse.json({ error: "Failed to fetch logs" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/usage/stats/route.js b/src/app/api/usage/stats/route.js
new file mode 100644
index 0000000..27e5109
--- /dev/null
+++ b/src/app/api/usage/stats/route.js
@@ -0,0 +1,23 @@
+import { NextResponse } from "next/server";
+import { getUsageStats } from "@/lib/usageDb";
+
+const VALID_PERIODS = new Set(["today", "24h", "7d", "30d", "60d", "all"]);
+
+export const dynamic = "force-dynamic";
+
+export async function GET(request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const period = searchParams.get("period") || "7d";
+
+    if (!VALID_PERIODS.has(period)) {
+      return NextResponse.json({ error: "Invalid period" }, { status: 400 });
+    }
+
+    const stats = await getUsageStats(period);
+    return NextResponse.json(stats);
+  } catch (error) {
+    console.error("[API] Failed to get usage stats:", error);
+    return NextResponse.json({ error: "Failed to fetch usage stats" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/usage/stream/route.js b/src/app/api/usage/stream/route.js
new file mode 100644
index 0000000..57782dd
--- /dev/null
+++ b/src/app/api/usage/stream/route.js
@@ -0,0 +1,79 @@
+import { getUsageStats, statsEmitter, getActiveRequests } from "@/lib/usageDb";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  const encoder = new TextEncoder();
+  const state = { closed: false, keepalive: null, send: null, sendPending: null, cachedStats: null };
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      // Full stats refresh (heavy) + immediate lightweight push
+      state.send = async () => {
+        if (state.closed) return;
+        try {
+          // Push lightweight update immediately so UI reflects changes fast
+          if (state.cachedStats) {
+            const { activeRequests, recentRequests, errorProvider } = await getActiveRequests();
+            const quickStats = { ...state.cachedStats, activeRequests, recentRequests, errorProvider };
+            controller.enqueue(encoder.encode(`data: ${JSON.stringify(quickStats)}\n\n`));
+          }
+          // Then do full recalc and update cache
+          const stats = await getUsageStats();
+          state.cachedStats = stats;
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(stats)}\n\n`));
+        } catch {
+          state.closed = true;
+          statsEmitter.off("update", state.send);
+          statsEmitter.off("pending", state.sendPending);
+          clearInterval(state.keepalive);
+        }
+      };
+
+      // Lightweight push: only refresh activeRequests + recentRequests on pending changes
+      state.sendPending = async () => {
+        if (state.closed || !state.cachedStats) return;
+        try {
+          const { activeRequests, recentRequests, errorProvider } = await getActiveRequests();
+          const stats = { ...state.cachedStats, activeRequests, recentRequests, errorProvider };
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(stats)}\n\n`));
+        } catch {
+          state.closed = true;
+          statsEmitter.off("update", state.send);
+          statsEmitter.off("pending", state.sendPending);
+          clearInterval(state.keepalive);
+        }
+      };
+
+      await state.send();
+
+      statsEmitter.on("update", state.send);
+      statsEmitter.on("pending", state.sendPending);
+
+      state.keepalive = setInterval(() => {
+        if (state.closed) { clearInterval(state.keepalive); return; }
+        try {
+          controller.enqueue(encoder.encode(": ping\n\n"));
+        } catch {
+          state.closed = true;
+          clearInterval(state.keepalive);
+        }
+      }, 25000);
+    },
+
+    cancel() {
+      state.closed = true;
+      statsEmitter.off("update", state.send);
+      statsEmitter.off("pending", state.sendPending);
+      clearInterval(state.keepalive);
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    },
+  });
+}
diff --git a/src/app/api/v1/api/chat/route.js b/src/app/api/v1/api/chat/route.js
new file mode 100644
index 0000000..746d7ed
--- /dev/null
+++ b/src/app/api/v1/api/chat/route.js
@@ -0,0 +1,37 @@
+import { handleChat } from "@/sse/handlers/chat.js";
+import { initTranslators } from "open-sse/translator/index.js";
+import { transformToOllama } from "open-sse/utils/ollamaTransform.js";
+
+let initialized = false;
+
+async function ensureInitialized() {
+  if (!initialized) {
+    await initTranslators();
+    initialized = true;
+  }
+}
+
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*"
+    }
+  });
+}
+
+export async function POST(request) {
+  await ensureInitialized();
+  
+  const clonedReq = request.clone();
+  let modelName = "llama3.2";
+  try {
+    const body = await clonedReq.json();
+    modelName = body.model || "llama3.2";
+  } catch {}
+
+  const response = await handleChat(request);
+  return transformToOllama(response, modelName);
+}
+
diff --git a/src/app/api/v1/audio/speech/route.js b/src/app/api/v1/audio/speech/route.js
new file mode 100644
index 0000000..98355d5
--- /dev/null
+++ b/src/app/api/v1/audio/speech/route.js
@@ -0,0 +1,16 @@
+import { handleTts } from "@/sse/handlers/tts.js";
+
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*",
+    },
+  });
+}
+
+/** POST /v1/audio/speech - OpenAI-compatible TTS endpoint */
+export async function POST(request) {
+  return await handleTts(request);
+}
diff --git a/src/app/api/v1/audio/transcriptions/route.js b/src/app/api/v1/audio/transcriptions/route.js
new file mode 100644
index 0000000..caf4847
--- /dev/null
+++ b/src/app/api/v1/audio/transcriptions/route.js
@@ -0,0 +1,19 @@
+import { handleStt } from "@/sse/handlers/stt.js";
+
+// Allow large audio uploads — 5min for processing large files
+export const maxDuration = 300;
+
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*",
+    },
+  });
+}
+
+/** POST /v1/audio/transcriptions - OpenAI Whisper compatible STT */
+export async function POST(request) {
+  return await handleStt(request);
+}
diff --git a/src/app/api/v1/audio/voices/route.js b/src/app/api/v1/audio/voices/route.js
new file mode 100644
index 0000000..69d37bd
--- /dev/null
+++ b/src/app/api/v1/audio/voices/route.js
@@ -0,0 +1,68 @@
+import { AI_PROVIDERS } from "@/shared/constants/providers";
+
+// Provider → internal voices API. Edge/local-device share the generic endpoint.
+const PROVIDER_API = {
+  elevenlabs: (origin) => `${origin}/api/media-providers/tts/elevenlabs/voices`,
+  deepgram: (origin) => `${origin}/api/media-providers/tts/deepgram/voices`,
+  inworld: (origin) => `${origin}/api/media-providers/tts/inworld/voices`,
+  "edge-tts": (origin) => `${origin}/api/media-providers/tts/voices?provider=edge-tts`,
+  "local-device": (origin) => `${origin}/api/media-providers/tts/voices?provider=local-device`,
+};
+
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET, OPTIONS" },
+  });
+}
+
+// GET /v1/audio/voices?provider={p}[&lang=xx]
+// Returns OpenAI-style list with each voice's full model id ready for /v1/audio/speech
+export async function GET(request) {
+  try {
+    const { searchParams, origin } = new URL(request.url);
+    const provider = searchParams.get("provider");
+    const lang = searchParams.get("lang");
+
+    if (!provider || !PROVIDER_API[provider]) {
+      return Response.json(
+        { error: { message: `provider must be one of: ${Object.keys(PROVIDER_API).join(", ")}`, type: "invalid_request_error" } },
+        { status: 400, headers: { "Access-Control-Allow-Origin": "*" } },
+      );
+    }
+
+    const baseUrl = PROVIDER_API[provider](origin);
+    const url = lang ? `${baseUrl}${baseUrl.includes("?") ? "&" : "?"}lang=${encodeURIComponent(lang)}` : baseUrl;
+    const res = await fetch(url, { cache: "no-store" });
+    const data = await res.json();
+    if (!res.ok || data.error) {
+      return Response.json(
+        { error: { message: data.error || `Upstream ${res.status}`, type: "server_error" } },
+        { status: res.status, headers: { "Access-Control-Allow-Origin": "*" } },
+      );
+    }
+
+    // Internal API shape: { voices } when lang filter, else { byLang, languages }
+    const rawVoices = lang
+      ? (data.voices || [])
+      : Object.values(data.byLang || {}).flatMap((l) => l.voices || []);
+
+    // Use provider alias for /v1/audio/speech model param (matches skill convention e.g. el/, dg/, edge-tts/)
+    const alias = AI_PROVIDERS[provider]?.alias || provider;
+    const data_out = rawVoices.map((v) => ({
+      id: v.id,
+      name: v.name,
+      lang: v.lang || "",
+      gender: v.gender || "",
+      model: `${alias}/${v.id}`,
+    }));
+
+    return Response.json({ object: "list", data: data_out }, {
+      headers: { "Access-Control-Allow-Origin": "*" },
+    });
+  } catch (err) {
+    return Response.json(
+      { error: { message: err.message || "Failed", type: "server_error" } },
+      { status: 502, headers: { "Access-Control-Allow-Origin": "*" } },
+    );
+  }
+}
diff --git a/src/app/api/v1/chat/completions/route.js b/src/app/api/v1/chat/completions/route.js
new file mode 100644
index 0000000..ddb5512
--- /dev/null
+++ b/src/app/api/v1/chat/completions/route.js
@@ -0,0 +1,35 @@
+import { handleChat } from "@/sse/handlers/chat.js";
+import { initTranslators } from "open-sse/translator/index.js";
+
+let initialized = false;
+
+/**
+ * Initialize translators once
+ */
+async function ensureInitialized() {
+  if (!initialized) {
+    await initTranslators();
+    initialized = true;
+  }
+}
+
+/**
+ * Handle CORS preflight
+ */
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*"
+    }
+  });
+}
+
+export async function POST(request) {  
+  // Fallback to local handling
+  await ensureInitialized();
+  
+  return await handleChat(request);
+}
+
diff --git a/src/app/api/v1/embeddings/route.js b/src/app/api/v1/embeddings/route.js
new file mode 100644
index 0000000..9ae873d
--- /dev/null
+++ b/src/app/api/v1/embeddings/route.js
@@ -0,0 +1,21 @@
+import { handleEmbeddings } from "@/sse/handlers/embeddings.js";
+
+/**
+ * Handle CORS preflight
+ */
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*"
+    }
+  });
+}
+
+/**
+ * POST /v1/embeddings - OpenAI-compatible embeddings endpoint
+ */
+export async function POST(request) {
+  return await handleEmbeddings(request);
+}
diff --git a/src/app/api/v1/images/generations/route.js b/src/app/api/v1/images/generations/route.js
new file mode 100644
index 0000000..302a718
--- /dev/null
+++ b/src/app/api/v1/images/generations/route.js
@@ -0,0 +1,16 @@
+import { handleImageGeneration } from "@/sse/handlers/imageGeneration.js";
+
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*",
+    },
+  });
+}
+
+/** POST /v1/images/generations - OpenAI-compatible image generation endpoint */
+export async function POST(request) {
+  return await handleImageGeneration(request);
+}
diff --git a/src/app/api/v1/messages/count_tokens/route.js b/src/app/api/v1/messages/count_tokens/route.js
new file mode 100644
index 0000000..2e08cd0
--- /dev/null
+++ b/src/app/api/v1/messages/count_tokens/route.js
@@ -0,0 +1,94 @@
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "POST, OPTIONS",
+  "Access-Control-Allow-Headers": "*"
+};
+
+/**
+ * Handle CORS preflight
+ */
+export async function OPTIONS() {
+  return new Response(null, { headers: CORS_HEADERS });
+}
+
+function countValueChars(value) {
+  if (value == null) return 0;
+  if (typeof value === "string") return value.length;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value).length;
+  }
+  if (Array.isArray(value)) {
+    return value.reduce((total, item) => total + countValueChars(item), 0);
+  }
+  if (typeof value === "object") {
+    return Object.entries(value).reduce((total, [key, item]) => {
+      return total + key.length + countValueChars(item);
+    }, 0);
+  }
+  return 0;
+}
+
+function countContentBlockChars(block) {
+  if (block == null) return 0;
+  if (typeof block === "string") return block.length;
+  if (typeof block !== "object") return countValueChars(block);
+
+  switch (block.type) {
+    case "text":
+      return countValueChars(block.text);
+    case "tool_use":
+      return countValueChars(block.name) + countValueChars(block.input);
+    case "tool_result":
+      return countValueChars(block.content);
+    case "thinking":
+      return countValueChars(block.thinking);
+    default:
+      return countValueChars(block);
+  }
+}
+
+function countMessageChars(message) {
+  if (!message || typeof message !== "object") return 0;
+  const content = message.content;
+
+  if (typeof content === "string") return content.length;
+  if (Array.isArray(content)) {
+    return content.reduce((total, block) => total + countContentBlockChars(block), 0);
+  }
+  return countValueChars(content);
+}
+
+export function estimateAnthropicInputTokens(body = {}) {
+  const messages = Array.isArray(body.messages) ? body.messages : [];
+  let totalChars = countValueChars(body.system) + countValueChars(body.tools);
+
+  for (const msg of messages) {
+    totalChars += countMessageChars(msg);
+  }
+
+  return Math.ceil(totalChars / 4);
+}
+
+/**
+ * POST /v1/messages/count_tokens - Mock token count response
+ */
+export async function POST(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return new Response(JSON.stringify({ error: "Invalid JSON body" }), {
+      status: 400,
+      headers: { "Content-Type": "application/json", ...CORS_HEADERS }
+    });
+  }
+
+  const inputTokens = estimateAnthropicInputTokens(body);
+
+  return new Response(JSON.stringify({
+    input_tokens: inputTokens
+  }), {
+    headers: { "Content-Type": "application/json", ...CORS_HEADERS }
+  });
+}
+
diff --git a/src/app/api/v1/messages/route.js b/src/app/api/v1/messages/route.js
new file mode 100644
index 0000000..0f20478
--- /dev/null
+++ b/src/app/api/v1/messages/route.js
@@ -0,0 +1,36 @@
+import { handleChat } from "@/sse/handlers/chat.js";
+import { initTranslators } from "open-sse/translator/index.js";
+
+let initialized = false;
+
+/**
+ * Initialize translators once
+ */
+async function ensureInitialized() {
+  if (!initialized) {
+    await initTranslators();
+    initialized = true;
+  }
+}
+
+/**
+ * Handle CORS preflight
+ */
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*"
+    }
+  });
+}
+
+/**
+ * POST /v1/messages - Claude format (auto convert via handleChat)
+ */
+export async function POST(request) {
+  await ensureInitialized();
+  return await handleChat(request);
+}
+
diff --git a/src/app/api/v1/models/[kind]/route.js b/src/app/api/v1/models/[kind]/route.js
new file mode 100644
index 0000000..b0f715b
--- /dev/null
+++ b/src/app/api/v1/models/[kind]/route.js
@@ -0,0 +1,55 @@
+import { buildModelsList } from "../route.js";
+
+// URL slug → service kind(s). `web` covers both webSearch and webFetch.
+const KIND_SLUG_MAP = {
+  "image": ["image"],
+  "tts": ["tts"],
+  "stt": ["stt"],
+  "embedding": ["embedding"],
+  "image-to-text": ["imageToText"],
+  "web": ["webSearch", "webFetch"],
+};
+
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, OPTIONS",
+      "Access-Control-Allow-Headers": "*",
+    },
+  });
+}
+
+/**
+ * GET /v1/models/{kind} - OpenAI-compatible models list filtered by capability.
+ * Supported kinds: image, tts, stt, embedding, image-to-text, web.
+ */
+export async function GET(_request, { params }) {
+  try {
+    const { kind } = await params;
+    const kindFilter = KIND_SLUG_MAP[kind];
+
+    if (!kindFilter) {
+      return Response.json(
+        {
+          error: {
+            message: `Unknown model kind: ${kind}. Supported: ${Object.keys(KIND_SLUG_MAP).join(", ")}`,
+            type: "invalid_request_error",
+          },
+        },
+        { status: 404, headers: { "Access-Control-Allow-Origin": "*" } }
+      );
+    }
+
+    const data = await buildModelsList(kindFilter);
+    return Response.json({ object: "list", data }, {
+      headers: { "Access-Control-Allow-Origin": "*" },
+    });
+  } catch (error) {
+    console.log("Error fetching models by kind:", error);
+    return Response.json(
+      { error: { message: error.message, type: "server_error" } },
+      { status: 500 }
+    );
+  }
+}
diff --git a/src/app/api/v1/models/info/route.js b/src/app/api/v1/models/info/route.js
new file mode 100644
index 0000000..551c122
--- /dev/null
+++ b/src/app/api/v1/models/info/route.js
@@ -0,0 +1,104 @@
+import { PROVIDER_MODELS } from "open-sse/config/providerModels.js";
+import { AI_PROVIDERS, ALIAS_TO_ID } from "@/shared/constants/providers";
+import { getModelKind } from "@/shared/constants/models";
+
+const KIND_ENDPOINT = {
+  llm: "/v1/chat/completions",
+  image: "/v1/images/generations",
+  tts: "/v1/audio/speech",
+  stt: "/v1/audio/transcriptions",
+  embedding: "/v1/embeddings",
+  imageToText: "/v1/chat/completions",
+  webSearch: "/v1/search",
+  webFetch: "/v1/fetch",
+};
+
+const TTS_VOICES_API = new Set(["elevenlabs", "edge-tts", "deepgram", "inworld", "local-device"]);
+
+function buildInfo({ alias, providerId, model, kind, providerInfo }) {
+  const out = {
+    id: `${alias}/${model.id}`,
+    name: model.name || model.id,
+    kind,
+    owned_by: alias,
+    endpoint: KIND_ENDPOINT[kind] || null,
+  };
+  if (model.params) out.params = model.params;
+  if (model.capabilities) out.capabilities = model.capabilities;
+  if (model.options) out.options = model.options;
+  if (model.dimensions) out.dimensions = model.dimensions;
+  if (model.contextWindow) out.contextWindow = model.contextWindow;
+  if (kind === "tts" && TTS_VOICES_API.has(providerId)) {
+    out.voicesUrl = `/v1/audio/voices?provider=${providerId}`;
+  }
+  if (kind === "webSearch" && providerInfo?.searchConfig) {
+    const cfg = providerInfo.searchConfig;
+    if (cfg.searchTypes) out.searchTypes = cfg.searchTypes;
+    if (cfg.maxMaxResults) out.maxResults = cfg.maxMaxResults;
+    if (cfg.requiredOptions) out.required = cfg.requiredOptions;
+  }
+  return out;
+}
+
+// id format: "{alias}/{modelId}" - alias may also be providerId
+// requestedKind: optional, disambiguates duplicate ids across kinds (e.g. gemini-2.5-pro llm vs stt)
+function lookup(fullId, requestedKind) {
+  if (!fullId || !fullId.includes("/")) return null;
+  const slash = fullId.indexOf("/");
+  const alias = fullId.slice(0, slash);
+  const modelId = fullId.slice(slash + 1);
+  const providerId = ALIAS_TO_ID[alias] || alias;
+  const providerInfo = AI_PROVIDERS[providerId];
+
+  // PROVIDER_MODELS lookup (by alias key, fallback to providerId)
+  const list = PROVIDER_MODELS[alias] || PROVIDER_MODELS[providerId] || [];
+  const m = requestedKind
+    ? list.find((x) => x.id === modelId && getModelKind(x, "llm") === requestedKind)
+    : list.find((x) => x.id === modelId);
+  if (m) {
+    const kind = getModelKind(m, "llm");
+    return buildInfo({ alias, providerId, model: m, kind, providerInfo });
+  }
+
+  // Web search/fetch — virtual model id "search" / "fetch"
+  if (modelId === "search" && providerInfo?.searchConfig) {
+    return buildInfo({
+      alias, providerId, kind: "webSearch", providerInfo,
+      model: { id: "search", name: `${providerInfo.name} Search`, params: ["query", "max_results", "country", "language", "time_range", "domain_filter", "search_type"] },
+    });
+  }
+  if (modelId === "fetch" && providerInfo?.fetchConfig) {
+    return buildInfo({
+      alias, providerId, kind: "webFetch", providerInfo,
+      model: { id: "fetch", name: `${providerInfo.name} Fetch`, params: ["url", "format", "max_characters"] },
+    });
+  }
+  return null;
+}
+
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET, OPTIONS" },
+  });
+}
+
+// GET /v1/models/info?id={alias}/{modelId} — metadata for a single model
+export async function GET(request) {
+  const { searchParams } = new URL(request.url);
+  const id = searchParams.get("id");
+  const kind = searchParams.get("kind");
+  if (!id) {
+    return Response.json(
+      { error: { message: "Missing required query param: id (e.g. ?id=openai/dall-e-3)", type: "invalid_request_error" } },
+      { status: 400, headers: { "Access-Control-Allow-Origin": "*" } },
+    );
+  }
+  const info = lookup(id, kind);
+  if (!info) {
+    return Response.json(
+      { error: { message: `Model not found: ${id}`, type: "not_found" } },
+      { status: 404, headers: { "Access-Control-Allow-Origin": "*" } },
+    );
+  }
+  return Response.json(info, { headers: { "Access-Control-Allow-Origin": "*" } });
+}
diff --git a/src/app/api/v1/models/route.js b/src/app/api/v1/models/route.js
new file mode 100644
index 0000000..3264730
--- /dev/null
+++ b/src/app/api/v1/models/route.js
@@ -0,0 +1,491 @@
+import { PROVIDER_MODELS, PROVIDER_ID_TO_ALIAS, getModelKind } from "@/shared/constants/models";
+import {
+  AI_PROVIDERS,
+  getProviderAlias,
+  isAnthropicCompatibleProvider,
+  isOpenAICompatibleProvider,
+} from "@/shared/constants/providers";
+import { getProviderConnections, getCombos, getCustomModels, getModelAliases } from "@/lib/localDb";
+import { getDisabledModels } from "@/lib/disabledModelsDb";
+import { resolveKiroModels } from "open-sse/services/kiroModels.js";
+import { resolveKimchiModels } from "open-sse/services/kimchiModels.js";
+import { resolveQoderModels } from "open-sse/services/qoderModels.js";
+import { resolveCopilotModels } from "open-sse/services/copilotModels.js";
+import { resolveClinepassModels } from "open-sse/services/clinepassModels.js";
+import { updateProviderCredentials } from "@/sse/services/tokenRefresh";
+import { capabilitiesFromServiceKind } from "open-sse/providers/capabilities.js";
+
+// Per-provider live model resolvers. Each receives a connection record and
+// returns { models: [{ id, name? }, ...] } | null on failure.
+// Adding a provider here makes /v1/models prefer the live catalog for it.
+const LIVE_MODEL_RESOLVERS = {
+  kiro: async (conn) => {
+    const result = await resolveKiroModels({
+      accessToken: conn.accessToken,
+      refreshToken: conn.refreshToken,
+      providerSpecificData: conn.providerSpecificData || {}
+    }, { log: console });
+    return result?.models?.length ? { models: result.models } : null;
+  },
+  qoder: async (conn) => {
+    const result = await resolveQoderModels({
+      accessToken: conn.accessToken,
+      refreshToken: conn.refreshToken,
+      email: conn.email,
+      displayName: conn.displayName,
+      providerSpecificData: conn.providerSpecificData || {}
+    });
+    if (!result?.models?.length) return null;
+    return {
+      models: result.models.map((m) => ({ id: m.id, name: m.name })),
+    };
+  },
+  kimchi: async (conn) => {
+    const result = await resolveKimchiModels({
+      accessToken: conn.accessToken,
+      apiKey: conn.apiKey,
+      providerSpecificData: conn.providerSpecificData || {}
+    }, { log: console });
+    return result?.models?.length ? { models: result.models } : null;
+  },
+  github: async (conn) => {
+    const result = await resolveCopilotModels({
+      accessToken: conn.accessToken,
+      refreshToken: conn.refreshToken,
+      providerSpecificData: conn.providerSpecificData || {}
+    }, {
+      log: console,
+      onCredentialsRefreshed: async (refreshed) => {
+        await updateProviderCredentials(conn.id, {
+          copilotToken: refreshed.copilotToken,
+          copilotTokenExpiresAt: refreshed.copilotTokenExpiresAt,
+          existingProviderSpecificData: conn.providerSpecificData || {},
+        });
+      },
+    });
+    return result?.models?.length ? { models: result.models } : null;
+  },
+  clinepass: async (conn) => {
+    const result = await resolveClinepassModels({
+      accessToken: conn.accessToken,
+      apiKey: conn.apiKey,
+    });
+    return result?.models?.length ? { models: result.models } : null;
+  }
+};
+
+const parseOpenAIStyleModels = (data) => {
+  if (Array.isArray(data)) return data;
+  return data?.data || data?.models || data?.results || [];
+};
+
+// Matches provider IDs that are upstream/cross-instance connections (contain a UUID suffix)
+const UPSTREAM_CONNECTION_RE = /[-_][0-9a-f]{8,}$/i;
+
+// LLM kind sentinel — combos/models with no explicit kind default to LLM
+const LLM_KIND = "llm";
+
+// Map per-model `type` field (in PROVIDER_MODELS) to service kind.
+// Models without `type` are treated as LLM.
+const MODEL_TYPE_TO_KIND = {
+  image: "image",
+  tts: "tts",
+  embedding: "embedding",
+  stt: "stt",
+  imageToText: "imageToText",
+};
+
+function modelKind(model) {
+  const k = model?.kind || model?.type;
+  if (!k) return LLM_KIND;
+  return MODEL_TYPE_TO_KIND[k] || LLM_KIND;
+}
+
+// For dynamic/unknown model IDs (compatible providers, alias map, custom models)
+// fall back to provider-level kind matching when per-model type is unavailable.
+function inferKindFromUnknownModelId(modelId) {
+  const lower = String(modelId).toLowerCase();
+  if (/embed/.test(lower)) return "embedding";
+  if (/tts|speech|audio|voice/.test(lower)) return "tts";
+  if (/image|imagen|dall-?e|flux|sdxl|sd-|stable-diffusion/.test(lower)) return "image";
+  return LLM_KIND;
+}
+
+async function fetchCompatibleModelIds(connection) {
+  if (!connection?.apiKey) return [];
+
+  const baseUrl = typeof connection?.providerSpecificData?.baseUrl === "string"
+    ? connection.providerSpecificData.baseUrl.trim().replace(/\/$/, "")
+    : "";
+
+  if (!baseUrl) return [];
+
+  let url = `${baseUrl}/models`;
+  const headers = {
+    "Content-Type": "application/json",
+  };
+
+  if (isOpenAICompatibleProvider(connection.provider)) {
+    headers.Authorization = `Bearer ${connection.apiKey}`;
+  } else if (isAnthropicCompatibleProvider(connection.provider)) {
+    if (url.endsWith("/messages/models")) {
+      url = url.slice(0, -9);
+    } else if (url.endsWith("/messages")) {
+      url = `${url.slice(0, -9)}/models`;
+    }
+    headers["x-api-key"] = connection.apiKey;
+    headers["anthropic-version"] = "2023-06-01";
+    headers.Authorization = `Bearer ${connection.apiKey}`;
+  } else {
+    return [];
+  }
+
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
+    const response = await fetch(url, {
+      method: "GET",
+      headers,
+      cache: "no-store",
+      signal: controller.signal,
+    });
+    clearTimeout(timeoutId);
+
+    if (!response.ok) return [];
+
+    const data = await response.json();
+    const rawModels = parseOpenAIStyleModels(data);
+
+    return Array.from(
+      new Set(
+        rawModels
+          .map((model) => model?.id || model?.name || model?.model)
+          .filter((modelId) => typeof modelId === "string" && modelId.trim() !== "")
+      )
+    );
+  } catch {
+    return [];
+  }
+}
+
+// Provider matches kindFilter when its serviceKinds intersect the requested kinds.
+// LLM is the default kind for providers missing serviceKinds.
+function providerMatchesKinds(providerId, kindFilter) {
+  const provider = AI_PROVIDERS[providerId];
+  const kinds = Array.isArray(provider?.serviceKinds) && provider.serviceKinds.length > 0
+    ? provider.serviceKinds
+    : [LLM_KIND];
+  return kindFilter.some((k) => kinds.includes(k));
+}
+
+// Combo matches kindFilter when its `kind` field is in the list.
+// Combos with no kind are treated as LLM.
+function comboMatchesKinds(combo, kindFilter) {
+  const kind = combo?.kind || LLM_KIND;
+  return kindFilter.includes(kind);
+}
+
+/**
+ * Build OpenAI-format models list filtered by service kinds.
+ * @param {string[]} kindFilter - List of service kinds to include (e.g. ["llm"], ["webSearch","webFetch"]).
+ */
+export async function buildModelsList(kindFilter) {
+  let connections = [];
+  try {
+    connections = await getProviderConnections();
+    connections = connections.filter(c => c.isActive !== false);
+  } catch (e) {
+    console.log("Could not fetch providers, returning all models");
+  }
+
+  let combos = [];
+  try {
+    combos = await getCombos();
+  } catch (e) {
+    console.log("Could not fetch combos");
+  }
+
+  let customModels = [];
+  try {
+    customModels = await getCustomModels();
+  } catch (e) {
+    console.log("Could not fetch custom models");
+  }
+
+  let modelAliases = {};
+  try {
+    modelAliases = await getModelAliases();
+  } catch (e) {
+    console.log("Could not fetch model aliases");
+  }
+
+  let disabledByAlias = {};
+  try {
+    disabledByAlias = await getDisabledModels();
+  } catch (e) {
+    console.log("Could not fetch disabled models");
+  }
+  const isDisabled = (alias, modelId) => Array.isArray(disabledByAlias[alias]) && disabledByAlias[alias].includes(modelId);
+
+  const activeConnectionByProvider = new Map();
+  for (const conn of connections) {
+    if (!activeConnectionByProvider.has(conn.provider)) {
+      activeConnectionByProvider.set(conn.provider, conn);
+    }
+  }
+
+  const models = [];
+
+  // Combos first (filtered by kind). Web combos expose `kind` so AI knows search vs fetch.
+  for (const combo of combos) {
+    if (!comboMatchesKinds(combo, kindFilter)) continue;
+    const entry = {
+      id: combo.name,
+      object: "model",
+      owned_by: "combo",
+    };
+    if (combo.kind === "webSearch" || combo.kind === "webFetch") {
+      entry.kind = combo.kind;
+    }
+    models.push(entry);
+  }
+
+  if (connections.length === 0) {
+    // DB unavailable -> return static models, filtered by per-model kind
+    const aliasToProviderId = Object.fromEntries(
+      Object.entries(PROVIDER_ID_TO_ALIAS).map(([id, alias]) => [alias, id])
+    );
+    for (const [alias, providerModels] of Object.entries(PROVIDER_MODELS)) {
+      const providerId = aliasToProviderId[alias] || alias;
+      if (!providerMatchesKinds(providerId, kindFilter)) continue;
+      for (const model of providerModels) {
+        if (!kindFilter.includes(modelKind(model))) continue;
+        if (isDisabled(alias, model.id)) continue;
+        models.push({
+          id: `${alias}/${model.id}`,
+          object: "model",
+          owned_by: alias,
+        });
+      }
+    }
+
+    for (const customModel of customModels) {
+      if (!customModel?.id || (customModel.type && customModel.type !== "llm")) continue;
+      // Custom models without active connection are LLM-only by current schema
+      if (!kindFilter.includes(LLM_KIND)) continue;
+      const providerAlias = customModel.providerAlias;
+      if (!providerAlias) continue;
+
+      const modelId = String(customModel.id).trim();
+      if (!modelId) continue;
+
+      models.push({
+        id: `${providerAlias}/${modelId}`,
+        object: "model",
+        owned_by: providerAlias,
+      });
+    }
+  } else {
+    for (const [providerId, conn] of activeConnectionByProvider.entries()) {
+      if (!providerMatchesKinds(providerId, kindFilter)) continue;
+
+      const staticAlias = PROVIDER_ID_TO_ALIAS[providerId] || providerId;
+      const outputAlias = (
+        conn?.providerSpecificData?.prefix
+        || getProviderAlias(providerId)
+        || staticAlias
+      ).trim();
+      const providerModels = PROVIDER_MODELS[staticAlias] || [];
+      const enabledModels = conn?.providerSpecificData?.enabledModels;
+      const hasExplicitEnabledModels =
+        Array.isArray(enabledModels) && enabledModels.length > 0;
+      const isCompatibleProvider =
+        isOpenAICompatibleProvider(providerId) || isAnthropicCompatibleProvider(providerId);
+
+      // Build kind lookup for static models so we can filter even when only IDs are exposed
+      const staticModelKindById = new Map(
+        providerModels.map((m) => [m.id, modelKind(m)])
+      );
+      let liveModelKindById = new Map();
+      let liveCapabilitiesById = new Map();
+
+      let rawModelIds = hasExplicitEnabledModels
+        ? Array.from(
+            new Set(
+              enabledModels.filter(
+                (modelId) => typeof modelId === "string" && modelId.trim() !== "",
+              ),
+            ),
+          )
+        : providerModels.map((model) => model.id);
+
+      if (isCompatibleProvider && rawModelIds.length === 0 && !UPSTREAM_CONNECTION_RE.test(providerId)) {
+        rawModelIds = await fetchCompatibleModelIds(conn);
+      }
+
+      // Config-driven live catalog override (e.g. Kiro returns dynamic
+      // -thinking/-agentic variants per account). On failure, fall back to
+      // whatever rawModelIds already holds.
+      const liveResolver = LIVE_MODEL_RESOLVERS[providerId];
+      if (liveResolver && !hasExplicitEnabledModels) {
+        try {
+          const live = await liveResolver(conn);
+          if (live?.models?.length) {
+            rawModelIds = live.models.map((m) => m.id);
+            liveModelKindById = new Map(
+              live.models
+                .filter((m) => m?.id)
+                .map((m) => [m.id, modelKind(m)])
+            );
+            liveCapabilitiesById = new Map(
+              live.models
+                .filter((m) => m?.id && m.capabilities)
+                .map((m) => [m.id, m.capabilities])
+            );
+          }
+        } catch (err) {
+          console.log(`Live model fetch failed for ${providerId}: ${err?.message || err}`);
+        }
+      }
+
+      const modelIds = rawModelIds
+        .map((modelId) => {
+          if (modelId.startsWith(`${outputAlias}/`)) {
+            return modelId.slice(outputAlias.length + 1);
+          }
+          if (modelId.startsWith(`${staticAlias}/`)) {
+            return modelId.slice(staticAlias.length + 1);
+          }
+          if (modelId.startsWith(`${providerId}/`)) {
+            return modelId.slice(providerId.length + 1);
+          }
+          return modelId;
+        })
+        .filter((modelId) => typeof modelId === "string" && modelId.trim() !== "");
+
+      const customModelKindById = new Map();
+      const customModelIds = customModels
+        .filter((m) => {
+          if (!m?.id) return false;
+          const kind = getModelKind(m) || LLM_KIND;
+          // imageToText custom models are vision-capable chat models: expose them
+          // both in the default LLM list and in /v1/models/image-to-text.
+          if (!kindFilter.includes(kind) && !(kind === "imageToText" && kindFilter.includes(LLM_KIND))) return false;
+          const alias = m.providerAlias;
+          return alias === staticAlias || alias === outputAlias || alias === providerId;
+        })
+        .map((m) => {
+          const modelId = String(m.id).trim();
+          if (modelId) customModelKindById.set(modelId, getModelKind(m) || LLM_KIND);
+          return modelId;
+        })
+        .filter((modelId) => modelId !== "");
+
+      const aliasModelIds = Object.values(modelAliases || {})
+        .filter((fullModel) => {
+          if (typeof fullModel !== "string" || !fullModel.includes("/")) return false;
+          return (
+            fullModel.startsWith(`${outputAlias}/`) ||
+            fullModel.startsWith(`${staticAlias}/`) ||
+            fullModel.startsWith(`${providerId}/`)
+          );
+        })
+        .map((fullModel) => {
+          if (fullModel.startsWith(`${outputAlias}/`)) {
+            return fullModel.slice(outputAlias.length + 1);
+          }
+          if (fullModel.startsWith(`${staticAlias}/`)) {
+            return fullModel.slice(staticAlias.length + 1);
+          }
+          if (fullModel.startsWith(`${providerId}/`)) {
+            return fullModel.slice(providerId.length + 1);
+          }
+          return fullModel;
+        })
+        .filter((modelId) => typeof modelId === "string" && modelId.trim() !== "");
+
+      const mergedModelIds = Array.from(new Set([...modelIds, ...customModelIds, ...aliasModelIds]));
+
+      for (const modelId of mergedModelIds) {
+        // Resolve kind: prefer custom/live metadata, then static, then ID heuristics.
+        const customKind = customModelKindById.get(modelId);
+        const liveKind = liveModelKindById.get(modelId);
+        const kind = customKind || liveKind || staticModelKindById.get(modelId) || inferKindFromUnknownModelId(modelId);
+        // imageToText custom models stay in the LLM list (vision-capable chat models)
+        const allowAsLlm = kind === "imageToText" && kindFilter.includes(LLM_KIND);
+        if (!kindFilter.includes(kind) && !allowAsLlm) continue;
+        if (isDisabled(outputAlias, modelId) || isDisabled(staticAlias, modelId)) continue;
+
+        const model = {
+          id: `${outputAlias}/${modelId}`,
+          object: "model",
+          owned_by: outputAlias,
+        };
+        const caps = liveCapabilitiesById.get(modelId) || capabilitiesFromServiceKind(customKind || liveKind);
+        if (caps) model.capabilities = caps;
+        models.push(model);
+      }
+
+      // Web search/fetch — provider IS the model, expose as {alias}/search and/or {alias}/fetch with explicit kind
+      const providerInfo = AI_PROVIDERS[providerId];
+      if (kindFilter.includes("webSearch") && providerInfo?.searchConfig) {
+        models.push({
+          id: `${outputAlias}/search`,
+          object: "model",
+          kind: "webSearch",
+          owned_by: outputAlias,
+        });
+      }
+      if (kindFilter.includes("webFetch") && providerInfo?.fetchConfig) {
+        models.push({
+          id: `${outputAlias}/fetch`,
+          object: "model",
+          kind: "webFetch",
+          owned_by: outputAlias,
+        });
+      }
+    }
+  }
+
+  const dedupedModels = [];
+  const seenModelIds = new Set();
+  for (const model of models) {
+    if (!model?.id || seenModelIds.has(model.id)) continue;
+    seenModelIds.add(model.id);
+    dedupedModels.push(model);
+  }
+
+  return dedupedModels;
+}
+
+/**
+ * Handle CORS preflight
+ */
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, OPTIONS",
+      "Access-Control-Allow-Headers": "*",
+    },
+  });
+}
+
+/**
+ * GET /v1/models - OpenAI compatible models list (LLM/chat models only by default).
+ * For other capabilities use /v1/models/{kind} (image, tts, stt, embedding, image-to-text, web).
+ */
+export async function GET() {
+  try {
+    const data = await buildModelsList([LLM_KIND]);
+    return Response.json({ object: "list", data }, {
+      headers: { "Access-Control-Allow-Origin": "*" },
+    });
+  } catch (error) {
+    console.log("Error fetching models:", error);
+    return Response.json(
+      { error: { message: error.message, type: "server_error" } },
+      { status: 500 }
+    );
+  }
+}
diff --git a/src/app/api/v1/responses/compact/route.js b/src/app/api/v1/responses/compact/route.js
new file mode 100644
index 0000000..7016c07
--- /dev/null
+++ b/src/app/api/v1/responses/compact/route.js
@@ -0,0 +1,37 @@
+import { handleChat } from "@/sse/handlers/chat.js";
+import { initTranslators } from "open-sse/translator/index.js";
+
+let initialized = false;
+
+async function ensureInitialized() {
+  if (!initialized) {
+    await initTranslators();
+    initialized = true;
+  }
+}
+
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*"
+    }
+  });
+}
+
+/**
+ * POST /v1/responses/compact - Compact conversation context
+ * Reuses the same handleChat pipeline, signals compact via body._compact
+ */
+export async function POST(request) {
+  await ensureInitialized();
+  const body = await request.json();
+  body._compact = true;
+  const newRequest = new Request(request.url, {
+    method: "POST",
+    headers: request.headers,
+    body: JSON.stringify(body)
+  });
+  return await handleChat(newRequest);
+}
diff --git a/src/app/api/v1/responses/route.js b/src/app/api/v1/responses/route.js
new file mode 100644
index 0000000..dbc38b5
--- /dev/null
+++ b/src/app/api/v1/responses/route.js
@@ -0,0 +1,30 @@
+import { handleChat } from "@/sse/handlers/chat.js";
+import { initTranslators } from "open-sse/translator/index.js";
+
+let initialized = false;
+
+async function ensureInitialized() {
+  if (!initialized) {
+    await initTranslators();
+    initialized = true;
+  }
+}
+
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*"
+    }
+  });
+}
+
+/**
+ * POST /v1/responses - OpenAI Responses API format
+ * Now handled by translator pattern (openai-responses format auto-detected)
+ */
+export async function POST(request) {
+  await ensureInitialized();
+  return await handleChat(request);
+}
diff --git a/src/app/api/v1/route.js b/src/app/api/v1/route.js
new file mode 100644
index 0000000..7f44b6d
--- /dev/null
+++ b/src/app/api/v1/route.js
@@ -0,0 +1 @@
+export { GET, OPTIONS } from "./models/route";
diff --git a/src/app/api/v1/search/route.js b/src/app/api/v1/search/route.js
new file mode 100644
index 0000000..279b46a
--- /dev/null
+++ b/src/app/api/v1/search/route.js
@@ -0,0 +1,21 @@
+import { handleSearch } from "@/sse/handlers/search.js";
+
+/**
+ * Handle CORS preflight
+ */
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*"
+    }
+  });
+}
+
+/**
+ * POST /v1/search - Web search endpoint
+ */
+export async function POST(request) {
+  return await handleSearch(request);
+}
diff --git a/src/app/api/v1/web/fetch/route.js b/src/app/api/v1/web/fetch/route.js
new file mode 100644
index 0000000..332600e
--- /dev/null
+++ b/src/app/api/v1/web/fetch/route.js
@@ -0,0 +1,21 @@
+import { handleFetch } from "@/sse/handlers/fetch.js";
+
+/**
+ * Handle CORS preflight
+ */
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*"
+    }
+  });
+}
+
+/**
+ * POST /v1/web/fetch - Web URL fetch/extract endpoint
+ */
+export async function POST(request) {
+  return await handleFetch(request);
+}
diff --git a/src/app/api/v1beta/models/[...path]/route.js b/src/app/api/v1beta/models/[...path]/route.js
new file mode 100644
index 0000000..1284631
--- /dev/null
+++ b/src/app/api/v1beta/models/[...path]/route.js
@@ -0,0 +1,585 @@
+import { handleChat } from "@/sse/handlers/chat.js";
+import {
+  clearAccountError,
+  getProviderCredentials,
+  isValidApiKey,
+  markAccountUnavailable,
+} from "@/sse/services/auth.js";
+import { getSettings } from "@/lib/localDb";
+import { PROVIDER_MODELS } from "@/shared/constants/models";
+import { GEMINI_NATIVE_TTS_FETCH_TIMEOUT_MS } from "open-sse/config/runtimeConfig.js";
+import { initTranslators } from "open-sse/translator/index.js";
+
+let initialized = false;
+const GEMINI_NATIVE_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models";
+// Gemini model id charset (matches sanitizeGeminiFunctionName); blocks path traversal in upstream URL.
+const GEMINI_NATIVE_MODEL_PATTERN = /^[a-zA-Z0-9_.:-]+$/;
+
+/**
+ * Initialize translators once
+ */
+async function ensureInitialized() {
+  if (!initialized) {
+    await initTranslators();
+    initialized = true;
+  }
+}
+
+/**
+ * Handle CORS preflight
+ */
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "*"
+    }
+  });
+}
+
+/**
+ * POST /v1beta/models/{model}:generateContent        — non-streaming
+ * POST /v1beta/models/{model}:streamGenerateContent  — streaming (SSE)
+ *
+ * Streaming intent is determined by the URL action suffix (canonical Gemini API
+ * convention), NOT by a body field. generationConfig.stream is not a real
+ * Gemini API field and Gemini CLI never sets it.
+ *
+ * The @google/genai SDK always uses :streamGenerateContent?alt=sse for chat.
+ * The upstream handleChat returns OpenAI SSE format; we transform it to
+ * Gemini SSE format on the fly via transformOpenAISSEToGeminiSSE().
+ */
+export async function POST(request, { params }) {
+  await ensureInitialized();
+
+  try {
+    const { path } = await params;
+    // path = ["provider", "model:action"] or ["model:action"]
+
+    let model;
+    let action; // ":generateContent" | ":streamGenerateContent"
+
+    if (path.length >= 2) {
+      // Format: /v1beta/models/provider/model:generateContent
+      const provider = path[0];
+      const modelAction = path[1];
+      action = modelAction.includes(":streamGenerateContent")
+        ? ":streamGenerateContent"
+        : ":generateContent";
+      const modelName = modelAction
+        .replace(":streamGenerateContent", "")
+        .replace(":generateContent", "");
+      model = provider + "/" + modelName;
+    } else {
+      // Format: /v1beta/models/model:generateContent
+      const modelAction = path[0];
+      action = modelAction.includes(":streamGenerateContent")
+        ? ":streamGenerateContent"
+        : ":generateContent";
+      model = modelAction
+        .replace(":streamGenerateContent", "")
+        .replace(":generateContent", "");
+    }
+
+    const body = await request.json();
+
+    if (isGeminiNativeTtsRequest(model, body)) {
+      return await forwardGeminiNativeRequest(request, body, model, action);
+    }
+
+    // Streaming is determined by URL action suffix:
+    //   :streamGenerateContent => stream: true  (SSE)
+    //   :generateContent       => stream: false (plain JSON)
+    const stream = action === ":streamGenerateContent";
+
+    // Convert Gemini request format to OpenAI/internal format
+    const convertedBody = convertGeminiToInternal(body, model, stream);
+
+    // Create new request with converted body
+    const newRequest = new Request(request.url, {
+      method: "POST",
+      headers: request.headers,
+      body: JSON.stringify(convertedBody),
+    });
+
+    const response = await handleChat(newRequest);
+
+    if (stream) {
+      // Transform OpenAI SSE => Gemini SSE on the fly.
+      // The @google/genai SDK always uses :streamGenerateContent?alt=sse and
+      // expects Gemini SSE chunks (no [DONE] sentinel — stream just closes).
+      return transformOpenAISSEToGeminiSSE(response, model);
+    } else {
+      // Convert OpenAI JSON response => Gemini GenerateContentResponse
+      return await convertOpenAIResponseToGemini(response, model);
+    }
+  } catch (error) {
+    console.log("Error handling Gemini request:", error);
+    return Response.json(
+      { error: { message: error.message, code: 500 } },
+      { status: 500 }
+    );
+  }
+}
+
+function extractGeminiClientApiKey(request) {
+  const authHeader = request.headers.get("Authorization");
+  if (authHeader?.startsWith("Bearer ")) return authHeader.slice(7);
+
+  const googleApiKey = request.headers.get("x-goog-api-key");
+  if (googleApiKey) return googleApiKey;
+
+  const url = new URL(request.url);
+  return url.searchParams.get("key");
+}
+
+function normalizeGeminiNativeModel(model) {
+  return String(model || "")
+    .replace(/^models\//, "")
+    .replace(/^gemini\//, "");
+}
+
+function getGeminiTtsModelIds() {
+  return new Set([
+    ...(PROVIDER_MODELS.gemini || [])
+      .filter((model) => (model.kind || model.type) === "tts")
+      .map((model) => model.id),
+    ...(PROVIDER_MODELS["gemini-tts-models"] || []).map((model) => model.id),
+  ]);
+}
+
+function hasAudioResponseModality(body) {
+  const modalities = body?.generationConfig?.responseModalities;
+  return Array.isArray(modalities)
+    && modalities.some((modality) => String(modality).toUpperCase() === "AUDIO");
+}
+
+function isGeminiNativeTtsRequest(model, body) {
+  const rawModel = String(model || "");
+  if (rawModel.includes("/") && !rawModel.startsWith("gemini/") && !rawModel.startsWith("models/")) {
+    return false;
+  }
+
+  const modelId = normalizeGeminiNativeModel(model);
+  return hasAudioResponseModality(body) || getGeminiTtsModelIds().has(modelId);
+}
+
+function buildGeminiNativeUrl(requestUrl, model, action) {
+  const sourceUrl = new URL(requestUrl);
+  const upstreamUrl = new URL(`${GEMINI_NATIVE_BASE_URL}/${normalizeGeminiNativeModel(model)}${action}`);
+
+  for (const [key, value] of sourceUrl.searchParams.entries()) {
+    if (key === "key") continue;
+    upstreamUrl.searchParams.append(key, value);
+  }
+
+  return upstreamUrl.toString();
+}
+
+async function validateGeminiNativeClientKey(request) {
+  const settings = await getSettings();
+  if (!settings.requireApiKey) return null;
+
+  const apiKey = extractGeminiClientApiKey(request);
+  if (!apiKey) {
+    return Response.json({ error: { message: "Missing API key" } }, { status: 401 });
+  }
+
+  const valid = await isValidApiKey(apiKey);
+  if (!valid) {
+    return Response.json({ error: { message: "Invalid API key" } }, { status: 401 });
+  }
+
+  return null;
+}
+
+function buildGeminiNativeAuthHeaders(credentials) {
+  if (credentials?.apiKey) return { "x-goog-api-key": credentials.apiKey };
+  if (credentials?.accessToken) return { Authorization: `Bearer ${credentials.accessToken}` };
+  return null;
+}
+
+function corsHeadersFrom(response) {
+  const headers = new Headers(response.headers);
+  // Node fetch may expose a decoded body while preserving upstream compression
+  // headers. Forwarding those headers makes clients decompress plain bytes again.
+  headers.delete("content-encoding");
+  headers.delete("content-length");
+  headers.delete("transfer-encoding");
+  headers.set("Access-Control-Allow-Origin", "*");
+  return headers;
+}
+
+function getSafeGeminiConnectionLabel(credentials) {
+  const connectionId = String(credentials?.connectionId || "unknown");
+  const shortId = connectionId.slice(0, 8);
+  const connectionName = String(credentials?.connectionName || "");
+  if (!connectionName || connectionName.includes("@")) return shortId;
+  return `${connectionName}:${shortId}`;
+}
+
+function getGeminiNativeErrorCode(error) {
+  return error?.cause?.code || error?.code || error?.cause?.name || error?.name || "UNKNOWN";
+}
+
+function isGeminiNativeTimeoutError(error, timedOut) {
+  if (timedOut) return true;
+  const code = getGeminiNativeErrorCode(error);
+  return code === "UND_ERR_HEADERS_TIMEOUT" || code === "HeadersTimeoutError";
+}
+
+function getSafeGeminiNativeErrorText(error) {
+  const message = error?.message || String(error);
+  const code = getGeminiNativeErrorCode(error);
+  return `${message} (${code})`;
+}
+
+async function forwardGeminiNativeRequest(request, body, model, action) {
+  const authError = await validateGeminiNativeClientKey(request);
+  if (authError) return authError;
+
+  const modelId = normalizeGeminiNativeModel(model);
+  if (!GEMINI_NATIVE_MODEL_PATTERN.test(modelId)) {
+    return Response.json({ error: { message: "Invalid model" } }, { status: 400 });
+  }
+  const excludeConnectionIds = new Set();
+  const bodyText = JSON.stringify(body);
+  let lastError = null;
+  let lastStatus = null;
+
+  while (true) {
+    const credentials = await getProviderCredentials("gemini", excludeConnectionIds, modelId);
+    if (!credentials || credentials.allRateLimited) {
+      console.log(`[GEMINI_NATIVE] exhausted model=${modelId} status=${lastStatus || Number(credentials?.lastErrorCode) || 503} error=${lastError || credentials?.lastError || "No active credentials for provider: gemini"}`);
+      return Response.json(
+        { error: { message: lastError || credentials?.lastError || "No active credentials for provider: gemini" } },
+        { status: lastStatus || Number(credentials?.lastErrorCode) || 503 }
+      );
+    }
+
+    const authHeaders = buildGeminiNativeAuthHeaders(credentials);
+    if (!authHeaders) {
+      return Response.json(
+        { error: { message: "No Gemini API key configured" } },
+        { status: 404 }
+      );
+    }
+
+    const safeConnection = getSafeGeminiConnectionLabel(credentials);
+    const startedAt = Date.now();
+    const upstreamUrl = buildGeminiNativeUrl(request.url, modelId, action);
+    const attemptController = new AbortController();
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      attemptController.abort();
+    }, GEMINI_NATIVE_TTS_FETCH_TIMEOUT_MS);
+    const abortAttempt = () => attemptController.abort();
+
+    if (request.signal?.aborted) {
+      console.log(`[GEMINI_NATIVE] client aborted model=${modelId} ms=0 conn=${safeConnection}`);
+      return Response.json({ error: { message: "Client closed request" } }, { status: 499 });
+    }
+
+    request.signal?.addEventListener("abort", abortAttempt, { once: true });
+    console.log(`[GEMINI_NATIVE] start model=${modelId} action=${action} conn=${safeConnection} body=${Buffer.byteLength(bodyText)}B timeout=${GEMINI_NATIVE_TTS_FETCH_TIMEOUT_MS}`);
+
+    let upstreamResponse;
+    try {
+      upstreamResponse = await fetch(upstreamUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": request.headers.get("Content-Type") || "application/json",
+          ...authHeaders,
+        },
+        body: bodyText,
+        signal: attemptController.signal,
+      });
+    } catch (error) {
+      const durationMs = Date.now() - startedAt;
+      if (request.signal?.aborted && !timedOut) {
+        console.log(`[GEMINI_NATIVE] client aborted model=${modelId} ms=${durationMs} conn=${safeConnection}`);
+        return Response.json({ error: { message: "Client closed request" } }, { status: 499 });
+      }
+
+      const status = isGeminiNativeTimeoutError(error, timedOut) ? 504 : 502;
+      const errorText = getSafeGeminiNativeErrorText(error);
+      console.log(`[GEMINI_NATIVE] fetch failed model=${modelId} status=${status} ms=${durationMs} conn=${safeConnection} error=${errorText}`);
+
+      const { shouldFallback } = await markAccountUnavailable(
+        credentials.connectionId,
+        status,
+        errorText,
+        "gemini",
+        modelId
+      );
+
+      if (shouldFallback) {
+        excludeConnectionIds.add(credentials.connectionId);
+        lastError = errorText;
+        lastStatus = status;
+        console.log(`[GEMINI_NATIVE] fallback model=${modelId} status=${status} conn=${safeConnection} exclude=${excludeConnectionIds.size}`);
+        continue;
+      }
+
+      return Response.json({ error: { message: errorText } }, { status });
+    } finally {
+      clearTimeout(timeout);
+      request.signal?.removeEventListener("abort", abortAttempt);
+    }
+
+    console.log(`[GEMINI_NATIVE] upstream model=${modelId} status=${upstreamResponse.status} ms=${Date.now() - startedAt} conn=${safeConnection} ct=${upstreamResponse.headers.get("content-type") || "?"} cl=${upstreamResponse.headers.get("content-length") || "?"}`);
+
+    if (upstreamResponse.ok) {
+      await clearAccountError(credentials.connectionId, credentials, modelId);
+      return new Response(upstreamResponse.body, {
+        status: upstreamResponse.status,
+        statusText: upstreamResponse.statusText,
+        headers: corsHeadersFrom(upstreamResponse),
+      });
+    }
+
+    const errorText = await upstreamResponse.text();
+    const { shouldFallback } = await markAccountUnavailable(
+      credentials.connectionId,
+      upstreamResponse.status,
+      errorText,
+      "gemini",
+      modelId
+    );
+
+    if (shouldFallback) {
+      excludeConnectionIds.add(credentials.connectionId);
+      lastError = errorText;
+      lastStatus = upstreamResponse.status;
+      continue;
+    }
+
+    return new Response(errorText, {
+      status: upstreamResponse.status,
+      statusText: upstreamResponse.statusText,
+      headers: corsHeadersFrom(upstreamResponse),
+    });
+  }
+}
+
+/**
+ * Convert Gemini request format to OpenAI/internal format.
+ *
+ * @param {object} geminiBody  - parsed Gemini request body
+ * @param {string} model       - resolved model string (e.g. "gemini-pro-high")
+ * @param {boolean} stream     - whether to stream (from URL action)
+ */
+function convertGeminiToInternal(geminiBody, model, stream) {
+  const messages = [];
+
+  // Convert system instruction
+  if (geminiBody.systemInstruction) {
+    const systemText = geminiBody.systemInstruction.parts
+      ?.map(p => p.text)
+      .join("\n") || "";
+    if (systemText) {
+      messages.push({ role: "system", content: systemText });
+    }
+  }
+
+  // Convert contents to messages
+  if (geminiBody.contents) {
+    for (const content of geminiBody.contents) {
+      const role = content.role === "model" ? "assistant" : "user";
+      const text = content.parts?.map(p => p.text).join("\n") || "";
+      messages.push({ role, content: text });
+    }
+  }
+
+  return {
+    model,
+    messages,
+    stream,
+    max_tokens: geminiBody.generationConfig?.maxOutputTokens,
+    temperature: geminiBody.generationConfig?.temperature,
+    top_p: geminiBody.generationConfig?.topP,
+  };
+}
+
+/** Map OpenAI finish_reason => Gemini finishReason */
+const FINISH_REASON_MAP = {
+  stop: "STOP",
+  length: "MAX_TOKENS",
+  tool_calls: "STOP",
+  content_filter: "SAFETY",
+};
+
+/**
+ * Transform an OpenAI SSE stream into a Gemini SSE stream.
+ *
+ * OpenAI SSE format (what handleChat returns):
+ *   data: {"choices":[{"delta":{"content":"Hi"},"finish_reason":null}]}
+ *   data: {"choices":[{"delta":{},"finish_reason":"stop"}],"usage":{...}}
+ *   data: [DONE]
+ *
+ * Gemini SSE format (what @google/genai SDK expects):
+ *   data: {"candidates":[{"content":{"role":"model","parts":[{"text":"Hi"}]},"index":0}]}
+ *   data: {"candidates":[{"content":{"role":"model","parts":[{"text":""}]},"finishReason":"STOP","index":0}],"usageMetadata":{...}}
+ *   (stream closes — no [DONE])
+ */
+function transformOpenAISSEToGeminiSSE(upstreamResponse, model) {
+  if (!upstreamResponse.ok || !upstreamResponse.body) {
+    return upstreamResponse;
+  }
+
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+
+  const transformStream = new TransformStream({
+    transform(chunk, controller) {
+      const text = decoder.decode(chunk, { stream: true });
+      const lines = text.split("\n");
+
+      for (const line of lines) {
+        if (!line.startsWith("data:")) continue;
+
+        const data = line.slice(5).trim();
+
+        // Drop empty lines and the OpenAI [DONE] sentinel.
+        // Gemini SSE ends by stream close, no sentinel needed.
+        if (!data || data === "[DONE]") continue;
+
+        let parsed;
+        try {
+          parsed = JSON.parse(data);
+        } catch {
+          continue;
+        }
+
+        const choice = parsed.choices?.[0];
+        if (!choice) continue;
+
+        const delta = choice.delta || {};
+
+        const parts = [];
+        if (delta.reasoning_content) {
+          parts.push({ text: delta.reasoning_content, thought: true });
+        }
+        if (delta.content) {
+          parts.push({ text: delta.content });
+        }
+
+        // Skip pure role-only deltas with no content and no finish signal
+        if (parts.length === 0 && !choice.finish_reason) continue;
+
+        const candidate = {
+          content: {
+            role: "model",
+            parts: parts.length > 0 ? parts : [{ text: "" }],
+          },
+          index: 0,
+        };
+
+        if (choice.finish_reason) {
+          candidate.finishReason = FINISH_REASON_MAP[choice.finish_reason] || "STOP";
+        }
+
+        const geminiChunk = { candidates: [candidate] };
+
+        // Attach usage + modelVersion on the final chunk (when finish_reason is set)
+        if (choice.finish_reason && parsed.usage) {
+          geminiChunk.usageMetadata = {
+            promptTokenCount: parsed.usage.prompt_tokens || 0,
+            candidatesTokenCount: parsed.usage.completion_tokens || 0,
+            totalTokenCount: parsed.usage.total_tokens || 0,
+          };
+          const reasoningTokens =
+            parsed.usage.completion_tokens_details?.reasoning_tokens;
+          if (reasoningTokens) {
+            geminiChunk.usageMetadata.thoughtsTokenCount = reasoningTokens;
+          }
+          geminiChunk.modelVersion = parsed.model || model;
+        }
+
+        controller.enqueue(
+          encoder.encode("data: " + JSON.stringify(geminiChunk) + "\r\n\r\n")
+        );
+      }
+    },
+    // No flush() needed: Gemini SSE ends by stream close, not a sentinel
+  });
+
+  return new Response(upstreamResponse.body.pipeThrough(transformStream), {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      "Access-Control-Allow-Origin": "*",
+    },
+  });
+}
+
+/**
+ * Convert an OpenAI chat.completion JSON response into a Gemini
+ * GenerateContentResponse so that Gemini CLI can parse it.
+ */
+async function convertOpenAIResponseToGemini(response, model) {
+  if (!response.ok) return response;
+
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return response;
+  }
+
+  if (body.candidates) return Response.json(body, {
+    headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" }
+  });
+
+  if (body.error) return Response.json(body, {
+    status: response.status,
+    headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" }
+  });
+
+  const choice = body.choices?.[0];
+  if (!choice) {
+    return Response.json(body, {
+      headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" }
+    });
+  }
+
+  const { message, finish_reason } = choice;
+
+  const parts = [];
+  if (message.reasoning_content) {
+    parts.push({ text: message.reasoning_content, thought: true });
+  }
+  parts.push({ text: message.content || "" });
+
+  const finishReason = FINISH_REASON_MAP[finish_reason] || "STOP";
+
+  const geminiResponse = {
+    candidates: [
+      {
+        content: { role: "model", parts },
+        finishReason,
+        index: 0,
+      },
+    ],
+    modelVersion: body.model || model,
+  };
+
+  if (body.usage) {
+    geminiResponse.usageMetadata = {
+      promptTokenCount: body.usage.prompt_tokens || 0,
+      candidatesTokenCount: body.usage.completion_tokens || 0,
+      totalTokenCount: body.usage.total_tokens || 0,
+    };
+    const reasoningTokens = body.usage.completion_tokens_details?.reasoning_tokens;
+    if (reasoningTokens) {
+      geminiResponse.usageMetadata.thoughtsTokenCount = reasoningTokens;
+    }
+  }
+
+  return Response.json(geminiResponse, {
+    headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" }
+  });
+}
diff --git a/src/app/api/v1beta/models/route.js b/src/app/api/v1beta/models/route.js
new file mode 100644
index 0000000..b5b47a9
--- /dev/null
+++ b/src/app/api/v1beta/models/route.js
@@ -0,0 +1,62 @@
+import { PROVIDER_MODELS } from "@/shared/constants/models";
+
+/**
+ * Handle CORS preflight
+ */
+export async function OPTIONS() {
+  return new Response(null, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, OPTIONS",
+      "Access-Control-Allow-Headers": "*"
+    }
+  });
+}
+
+/**
+ * GET /v1beta/models - Gemini compatible models list
+ * Returns models in Gemini API format
+ */
+export async function GET() {
+  try {
+    const models = [];
+    const seen = new Set();
+
+    function addModel({ name, displayName, description, methods = ["generateContent"] }) {
+      if (seen.has(name)) return;
+      seen.add(name);
+      models.push({
+        name,
+        displayName,
+        description,
+        supportedGenerationMethods: methods,
+        inputTokenLimit: 128000,
+        outputTokenLimit: 8192,
+      });
+    }
+    
+    for (const [provider, providerModels] of Object.entries(PROVIDER_MODELS)) {
+      for (const model of providerModels) {
+        addModel({
+          name: `models/${provider}/${model.id}`,
+          displayName: model.name || model.id,
+          description: `${provider} model: ${model.name || model.id}`,
+        });
+
+        if (provider === "gemini") {
+          addModel({
+            name: `models/${model.id}`,
+            displayName: model.name || model.id,
+            description: `Gemini model: ${model.name || model.id}`,
+            methods: ["generateContent", "streamGenerateContent"],
+          });
+        }
+      }
+    }
+
+    return Response.json({ models });
+  } catch (error) {
+    console.log("Error fetching models:", error);
+    return Response.json({ error: { message: error.message } }, { status: 500 });
+  }
+}
diff --git a/src/app/api/version/route.js b/src/app/api/version/route.js
new file mode 100644
index 0000000..5635f9a
--- /dev/null
+++ b/src/app/api/version/route.js
@@ -0,0 +1,61 @@
+import https from "https";
+import pkg from "../../../../package.json" with { type: "json" };
+
+const NPM_PACKAGE_NAME = "9router";
+const VERSION_CACHE_TTL_MS = 3600000; // cache npm latest lookup for 1h
+
+// Survive hot reload; one cache per process
+const versionCache = (global.__npmVersionCache ??= { value: null, fetchedAt: 0 });
+
+// Fetch latest version from npm registry
+function fetchLatestVersion() {
+  return new Promise((resolve) => {
+    const req = https.get(
+      `https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`,
+      { timeout: 4000 },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          try {
+            resolve(JSON.parse(data).version || null);
+          } catch {
+            resolve(null);
+          }
+        });
+      }
+    );
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+  });
+}
+
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return 1;
+    if (pa[i] < pb[i]) return -1;
+  }
+  return 0;
+}
+
+async function getLatestVersionCached() {
+  if (versionCache.value && Date.now() - versionCache.fetchedAt < VERSION_CACHE_TTL_MS) {
+    return versionCache.value;
+  }
+  const latest = await fetchLatestVersion();
+  if (latest) {
+    versionCache.value = latest;
+    versionCache.fetchedAt = Date.now();
+  }
+  return latest;
+}
+
+export async function GET() {
+  const latestVersion = await getLatestVersionCached();
+  const currentVersion = pkg.version;
+  const hasUpdate = latestVersion ? compareVersions(latestVersion, currentVersion) > 0 : false;
+
+  return Response.json({ currentVersion, latestVersion, hasUpdate });
+}
diff --git a/src/app/api/version/shutdown/route.js b/src/app/api/version/shutdown/route.js
new file mode 100644
index 0000000..bb1cd9d
--- /dev/null
+++ b/src/app/api/version/shutdown/route.js
@@ -0,0 +1,15 @@
+import { NextResponse } from "next/server";
+import { killAppProcesses } from "@/lib/appUpdater";
+
+// Shutdown app to release file locks for manual update
+export async function POST() {
+  try {
+    await killAppProcesses();
+  } catch { /* best effort */ }
+
+  const response = NextResponse.json({ success: true, message: "Shutting down for manual update..." });
+
+  setTimeout(() => process.exit(0), 500);
+
+  return response;
+}
diff --git a/src/app/api/version/update/route.js b/src/app/api/version/update/route.js
new file mode 100644
index 0000000..e35de79
--- /dev/null
+++ b/src/app/api/version/update/route.js
@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { killAppProcesses, spawnUpdaterAndExit } from "@/lib/appUpdater";
+
+export async function POST() {
+  if (process.env.NODE_ENV !== "production") {
+    return NextResponse.json(
+      { success: false, message: "Update is only available in production build (9router CLI)" },
+      { status: 403 }
+    );
+  }
+
+  try {
+    // Kill sibling processes (cloudflared, MITM, stray next-server) to release file locks on Windows
+    await killAppProcesses();
+  } catch { /* best effort */ }
+
+  // Schedule detached updater then exit current server process
+  spawnUpdaterAndExit();
+
+  return NextResponse.json({ success: true, message: "Updater started. This app will exit shortly." });
+}
diff --git a/src/app/callback/page.js b/src/app/callback/page.js
new file mode 100644
index 0000000..df7bbbc
--- /dev/null
+++ b/src/app/callback/page.js
@@ -0,0 +1,150 @@
+"use client";
+
+import { Suspense, useEffect, useState } from "react";
+import { useSearchParams } from "next/navigation";
+
+/**
+ * OAuth Callback Page Content
+ */
+function CallbackContent() {
+  const searchParams = useSearchParams();
+  const [status, setStatus] = useState("processing");
+
+  useEffect(() => {
+    const code = searchParams.get("code");
+    const token = searchParams.get("token");
+    const state = searchParams.get("state");
+    const error = searchParams.get("error");
+    const errorDescription = searchParams.get("error_description");
+
+    const callbackData = {
+      code,
+      token,
+      state,
+      error,
+      errorDescription,
+      fullUrl: window.location.href,
+    };
+
+    let relayed = false;
+
+    // Trusted origins that may receive this callback. The OAuth code/state
+    // must only be relayed to the dashboard window we expect to be the opener
+    // (same origin) or the Codex helper that listens on a fixed loopback port.
+    // Any other origin is treated as hostile (drive-by attacker that opened
+    // the popup against the well-known redirect_uri to phish the code).
+    const expectedOrigins = [
+      window.location.origin, // Same origin (for most providers)
+      "http://localhost:1455", // Codex specific port
+    ];
+
+    // Method 1: postMessage to opener (popup mode)
+    // Send once per expected origin. The browser delivers the message only
+    // when the opener's origin matches the targetOrigin we pass — using "*"
+    // here would leak the code/state to any opener (e.g. an attacker page
+    // that opened this URL in a popup), so iterate over the allowlist.
+    if (window.opener) {
+      for (const origin of expectedOrigins) {
+        try {
+          window.opener.postMessage({ type: "oauth_callback", data: callbackData }, origin);
+          relayed = true;
+        } catch (e) {
+          console.log("postMessage failed:", e);
+        }
+      }
+    }
+
+    // Method 2: BroadcastChannel (same origin tabs)
+    try {
+      const channel = new BroadcastChannel("oauth_callback");
+      channel.postMessage(callbackData);
+      channel.close();
+      relayed = true;
+    } catch (e) {
+      console.log("BroadcastChannel failed:", e);
+    }
+
+    // Method 3: localStorage event (fallback)
+    try {
+      localStorage.setItem("oauth_callback", JSON.stringify({ ...callbackData, timestamp: Date.now() }));
+      relayed = true;
+    } catch (e) {
+      console.log("localStorage failed:", e);
+    }
+
+    if (!(code || token || error)) {
+      setTimeout(() => setStatus("manual"), 0);
+      return;
+    }
+
+    setStatus("success");
+    setTimeout(() => {
+      window.close();
+      setTimeout(() => setStatus("done"), 500);
+    }, 1500);
+  }, [searchParams]);
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-bg">
+      <div className="text-center p-8 max-w-md">
+        {status === "processing" && (
+          <>
+            <div className="size-16 mx-auto mb-4 rounded-full bg-primary/10 flex items-center justify-center">
+              <span className="material-symbols-outlined text-3xl text-primary animate-spin">progress_activity</span>
+            </div>
+            <h1 className="text-xl font-semibold mb-2">Processing...</h1>
+            <p className="text-text-muted">Please wait while we complete the authorization.</p>
+          </>
+        )}
+
+        {(status === "success" || status === "done") && (
+          <>
+            <div className="size-16 mx-auto mb-4 rounded-full bg-green-100 dark:bg-green-900/30 flex items-center justify-center">
+              <span className="material-symbols-outlined text-3xl text-green-600">check_circle</span>
+            </div>
+            <h1 className="text-xl font-semibold mb-2">Authorization Successful!</h1>
+            <p className="text-text-muted">
+              {status === "success" ? "This window will close automatically..." : "You can close this tab now."}
+            </p>
+          </>
+        )}
+
+        {status === "manual" && (
+          <>
+            <div className="size-16 mx-auto mb-4 rounded-full bg-yellow-100 dark:bg-yellow-900/30 flex items-center justify-center">
+              <span className="material-symbols-outlined text-3xl text-yellow-600">info</span>
+            </div>
+            <h1 className="text-xl font-semibold mb-2">Copy This URL</h1>
+            <p className="text-text-muted mb-4">
+              Please copy the URL from the address bar and paste it in the application.
+            </p>
+            <div className="bg-surface border border-border rounded-lg p-3 text-left">
+              <code className="text-xs break-all">{typeof window !== "undefined" ? window.location.href : ""}</code>
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * OAuth Callback Page
+ * Receives callback from OAuth providers and sends data back via multiple methods
+ */
+export default function CallbackPage() {
+  return (
+    <Suspense fallback={
+      <div className="min-h-screen flex items-center justify-center bg-bg">
+        <div className="text-center p-8">
+          <div className="size-16 mx-auto mb-4 rounded-full bg-primary/10 flex items-center justify-center">
+            <span className="material-symbols-outlined text-3xl text-primary animate-spin">progress_activity</span>
+          </div>
+          <p className="text-text-muted">Loading...</p>
+        </div>
+      </div>
+    }>
+      <CallbackContent />
+    </Suspense>
+  );
+}
diff --git a/src/app/dashboard/settings/pricing/page.js b/src/app/dashboard/settings/pricing/page.js
new file mode 100644
index 0000000..0c98c51
--- /dev/null
+++ b/src/app/dashboard/settings/pricing/page.js
@@ -0,0 +1,173 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { useRouter } from "next/navigation";
+import Card from "@/shared/components/Card";
+import PricingModal from "@/shared/components/PricingModal";
+
+export default function PricingSettingsPage() {
+  const router = useRouter();
+  const [showModal, setShowModal] = useState(false);
+  const [currentPricing, setCurrentPricing] = useState(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    loadPricing();
+  }, []);
+
+  const loadPricing = async () => {
+    setLoading(true);
+    try {
+      const response = await fetch("/api/pricing");
+      if (response.ok) {
+        const data = await response.json();
+        setCurrentPricing(data);
+      }
+    } catch (error) {
+      console.error("Failed to load pricing:", error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handlePricingUpdated = () => {
+    loadPricing();
+  };
+
+  // Count total models with pricing
+  const getModelCount = () => {
+    if (!currentPricing) return 0;
+    let count = 0;
+    for (const provider in currentPricing) {
+      count += Object.keys(currentPricing[provider]).length;
+    }
+    return count;
+  };
+
+  // Get providers list
+  const getProviders = () => {
+    if (!currentPricing) return [];
+    return Object.keys(currentPricing).sort();
+  };
+
+  return (
+    <div className="max-w-6xl mx-auto p-6 space-y-6">
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="text-3xl font-bold">Pricing Settings</h1>
+          <p className="text-text-muted mt-1">
+            Configure pricing rates for cost tracking and calculations
+          </p>
+        </div>
+        <button
+          onClick={() => setShowModal(true)}
+          className="px-4 py-2 bg-primary text-white rounded hover:bg-primary/90 transition-colors"
+        >
+          Edit Pricing
+        </button>
+      </div>
+
+      {/* Quick Stats */}
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+        <Card className="p-4">
+          <div className="text-text-muted text-sm uppercase font-semibold">
+            Total Models
+          </div>
+          <div className="text-2xl font-bold mt-1">
+            {loading ? "..." : getModelCount()}
+          </div>
+        </Card>
+        <Card className="p-4">
+          <div className="text-text-muted text-sm uppercase font-semibold">
+            Providers
+          </div>
+          <div className="text-2xl font-bold mt-1">
+            {loading ? "..." : getProviders().length}
+          </div>
+        </Card>
+        <Card className="p-4">
+          <div className="text-text-muted text-sm uppercase font-semibold">
+            Status
+          </div>
+          <div className="text-2xl font-bold mt-1 text-success">
+            {loading ? "..." : "Active"}
+          </div>
+        </Card>
+      </div>
+
+      {/* Info Section */}
+      <Card className="p-6">
+        <h2 className="text-xl font-semibold mb-4">How Pricing Works</h2>
+        <div className="space-y-3 text-sm text-text-muted">
+          <p>
+            <strong>Cost Calculation:</strong> Costs are calculated based on token usage and pricing rates.
+            Each request&apos;s cost is determined by: (input_tokens × input_rate) + (output_tokens × output_rate) + (cached_tokens × cached_rate)
+          </p>
+          <p>
+            <strong>Pricing Format:</strong> All rates are in <strong>dollars per million tokens</strong> ($/1M tokens).
+            Example: An input rate of 2.50 means $2.50 per 1,000,000 input tokens.
+          </p>
+          <p>
+            <strong>Token Types:</strong>
+          </p>
+          <ul className="list-disc list-inside ml-4 space-y-1">
+            <li><strong>Input:</strong> Standard prompt tokens</li>
+            <li><strong>Output:</strong> Completion/response tokens</li>
+            <li><strong>Cached:</strong> Cached input tokens (typically 50% of input rate)</li>
+            <li><strong>Reasoning:</strong> Special reasoning/thinking tokens (fallback to output rate)</li>
+            <li><strong>Cache Creation:</strong> Tokens used to create cache entries (fallback to input rate)</li>
+          </ul>
+          <p>
+            <strong>Custom Pricing:</strong> You can override default pricing for specific models.
+            Reset to defaults anytime to restore standard rates.
+          </p>
+        </div>
+      </Card>
+
+      {/* Current Pricing Preview */}
+      <Card className="p-6">
+        <div className="flex items-center justify-between mb-4">
+          <h2 className="text-xl font-semibold">Current Pricing Overview</h2>
+          <button
+            onClick={() => setShowModal(true)}
+            className="text-primary hover:underline text-sm"
+          >
+            View Full Details
+          </button>
+        </div>
+
+        {loading ? (
+          <div className="text-center py-4 text-text-muted">Loading pricing data...</div>
+        ) : currentPricing ? (
+          <div className="space-y-3">
+            {Object.keys(currentPricing).slice(0, 5).map(provider => (
+              <div key={provider} className="text-sm">
+                <span className="font-semibold">{provider.toUpperCase()}:</span>{" "}
+                <span className="text-text-muted">
+                  {Object.keys(currentPricing[provider]).length} models
+                </span>
+              </div>
+            ))}
+            {Object.keys(currentPricing).length > 5 && (
+              <div className="text-sm text-text-muted">
+                + {Object.keys(currentPricing).length - 5} more providers
+              </div>
+            )}
+          </div>
+        ) : (
+          <div className="text-text-muted">No pricing data available</div>
+        )}
+      </Card>
+
+      {/* Pricing Modal */}
+      {showModal && (
+        <PricingModal
+          isOpen={showModal}
+          onClose={() => setShowModal(false)}
+          onSave={handlePricingUpdated}
+        />
+      )}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/app/favicon.ico b/src/app/favicon.ico
new file mode 100644
index 0000000..718d6fe
Binary files /dev/null and b/src/app/favicon.ico differ
diff --git a/src/app/globals.css b/src/app/globals.css
new file mode 100644
index 0000000..fdc219b
--- /dev/null
+++ b/src/app/globals.css
@@ -0,0 +1,511 @@
+/* source() sets scan base to src/ for both webpack + Turbopack; auto-detection still skips binaries + gitignore */
+@import "tailwindcss" source("../../");
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* Hide icon ligature text until font is ready */
+.material-symbols-outlined { visibility: hidden; }
+.fonts-loaded .material-symbols-outlined { visibility: visible; }
+
+/* ============================================================
+   9Router palette — adopted from 9remote_private/web
+   Brand orange (dark) / soft coral (light), neutral warm bases
+   ============================================================ */
+:root {
+  /* Brand scale (light) - centered on #E56A4A */
+  --color-brand-50: #fdf1ed;
+  --color-brand-100: #fadccf;
+  --color-brand-200: #f4b59c;
+  --color-brand-300: #ee8d6a;
+  --color-brand-400: #ea7855;
+  --color-brand-500: #E56A4A;
+  --color-brand-600: #cc5236;
+  --color-brand-700: #a64027;
+  --color-brand-800: #7a2f1d;
+  --color-brand-900: #4d1e12;
+
+  /* Primary (legacy alias for backward compat with existing components) */
+  --color-primary: var(--color-brand-500);
+  --color-primary-hover: var(--color-brand-600);
+
+  /* Surfaces & backgrounds (light) */
+  --color-bg: #FDFAF6;
+  --color-bg-alt: #F7F3EE;
+  --color-surface: #ffffff;
+  --color-surface-2: #f4f4f5;
+  --color-surface-3: #e7e7e9;
+  --color-sidebar: rgba(244, 241, 236, 0.85);
+
+  /* Borders */
+  --color-border: #e5e7eb;
+  --color-border-subtle: #f1f1f3;
+
+  /* Text */
+  --color-text: #0a0a0a;
+  --color-text-main: #0a0a0a;
+  --color-text-muted: #6B7280;
+  --color-text-subtle: #9CA3AF;
+
+  /* Status */
+  --color-danger: #cf222e;
+  --color-success: #10B981;
+  --color-warning: #F59E0B;
+  --color-info: #3B82F6;
+
+  /* Radius */
+  --radius-brand: 10px;
+  --radius-brand-lg: 14px;
+
+  /* Shadows */
+  --shadow-soft: 0 1px 2px 0 rgba(0,0,0,0.04);
+  --shadow-warm: 0 2px 12px -2px rgba(229, 106, 74, 0.18);
+  --shadow-elevated: 0 12px 28px -4px rgba(60, 50, 45, 0.06);
+  --shadow-elev:
+    inset 0 1px 0 0 rgba(255,255,255,0.8),
+    0 1px 2px rgba(15,23,42,0.04),
+    0 12px 36px -8px rgba(15,23,42,0.10);
+  --shadow-focus: 0 0 0 3px rgba(229,106,74,0.18);
+
+  color-scheme: light;
+}
+
+.dark {
+  /* Brand scale (dark) - centered on #E56A4A, same as light for consistency */
+  --color-brand-50: #fdf1ed;
+  --color-brand-100: #fadccf;
+  --color-brand-200: #f4b59c;
+  --color-brand-300: #ee8d6a;
+  --color-brand-400: #ea7855;
+  --color-brand-500: #E56A4A;
+  --color-brand-600: #cc5236;
+  --color-brand-700: #a64027;
+  --color-brand-800: #7a2f1d;
+  --color-brand-900: #4d1e12;
+
+  --color-primary: #E56A4A;
+  --color-primary-hover: #cc5236;
+
+  /* Surfaces (dark - Claude-like neutral warm) */
+  --color-bg: #1a1a1a;
+  --color-bg-alt: #1F1F1E;
+  --color-surface: #262626;
+  --color-surface-2: #303030;
+  --color-surface-3: #3a3a3a;
+  --color-sidebar: rgba(30, 30, 30, 0.85);
+
+  --color-border: #333333;
+  --color-border-subtle: #2a2a2a;
+
+  --color-text: #ededed;
+  --color-text-main: #ededed;
+  --color-text-muted: #9ca3af;
+  --color-text-subtle: #6b7280;
+
+  --color-danger: #ef4444;
+  --color-success: #22c55e;
+  --color-warning: #fbbf24;
+  --color-info: #60a5fa;
+
+  --shadow-soft: 0 1px 2px 0 rgba(0,0,0,0.3);
+  --shadow-warm: 0 2px 12px -2px rgba(229, 106, 74, 0.25);
+  --shadow-elevated: 0 12px 28px -4px rgba(0, 0, 0, 0.45);
+  --shadow-elev:
+    inset 0 1px 0 0 rgba(255,255,255,0.06),
+    0 1px 2px rgba(0,0,0,0.4),
+    0 16px 48px -8px rgba(0,0,0,0.55);
+  --shadow-focus: 0 0 0 3px rgba(229, 106, 74, 0.18);
+
+  color-scheme: dark;
+}
+
+/* ============================================================
+   Fix native select dropdowns in dark mode
+   ============================================================ */
+select {
+  color-scheme: light;
+}
+
+.dark select {
+  color-scheme: dark;
+}
+
+.dark select option {
+  background-color: var(--color-surface);
+  color: var(--color-text-main);
+}
+
+@theme inline {
+  /* Brand scale */
+  --color-brand-50: var(--color-brand-50);
+  --color-brand-100: var(--color-brand-100);
+  --color-brand-200: var(--color-brand-200);
+  --color-brand-300: var(--color-brand-300);
+  --color-brand-400: var(--color-brand-400);
+  --color-brand-500: var(--color-brand-500);
+  --color-brand-600: var(--color-brand-600);
+  --color-brand-700: var(--color-brand-700);
+  --color-brand-800: var(--color-brand-800);
+  --color-brand-900: var(--color-brand-900);
+
+  /* Primary aliases */
+  --color-primary: var(--color-primary);
+  --color-primary-hover: var(--color-primary-hover);
+
+  /* Semantic */
+  --color-bg: var(--color-bg);
+  --color-bg-alt: var(--color-bg-alt);
+  --color-surface: var(--color-surface);
+  --color-surface-2: var(--color-surface-2);
+  --color-surface-3: var(--color-surface-3);
+  --color-sidebar: var(--color-sidebar);
+  --color-border: var(--color-border);
+  --color-border-subtle: var(--color-border-subtle);
+  --color-text: var(--color-text);
+  --color-text-main: var(--color-text-main);
+  --color-text-muted: var(--color-text-muted);
+  --color-text-subtle: var(--color-text-subtle);
+  --color-accent: var(--color-brand-500);
+  --color-danger: var(--color-danger);
+  --color-success: var(--color-success);
+  --color-warning: var(--color-warning);
+  --color-info: var(--color-info);
+
+  /* Static fallbacks (explicit per-mode usage if needed) */
+  --color-bg-light: #FCFBF9;
+  --color-bg-dark: #1a1a1a;
+  --color-surface-light: #ffffff;
+  --color-surface-dark: #262626;
+  --color-sidebar-light: #F4F1EC;
+  --color-sidebar-dark: #1F1F1E;
+  --color-border-light: #e5e7eb;
+  --color-border-dark: #333333;
+  --color-text-main-light: #0a0a0a;
+  --color-text-main-dark: #ededed;
+  --color-text-muted-light: #6B7280;
+  --color-text-muted-dark: #9ca3af;
+
+  /* Radius */
+  --radius-brand: var(--radius-brand);
+  --radius-brand-lg: var(--radius-brand-lg);
+
+  /* Shadows */
+  --shadow-soft: var(--shadow-soft);
+  --shadow-warm: var(--shadow-warm);
+  --shadow-elevated: var(--shadow-elevated);
+  --shadow-elev: var(--shadow-elev);
+  --shadow-focus: var(--shadow-focus);
+
+  /* Font - Inter primary, Apple system fallback */
+  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'SF Pro Display', system-ui, sans-serif;
+}
+
+/* Base */
+body {
+  background-color: var(--color-bg);
+  color: var(--color-text-main);
+  font-family: var(--font-sans);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Selection - brand-tinted */
+::selection {
+  background-color: rgba(229, 106, 74, 0.25);
+  color: var(--color-primary);
+}
+.dark ::selection {
+  background-color: rgba(229, 106, 74, 0.3);
+  color: var(--color-brand-300);
+}
+
+/* iOS keyboard accent */
+input, textarea {
+  accent-color: var(--color-primary);
+}
+
+/* Scrollbar (custom-scrollbar utility kept for compat) */
+.custom-scrollbar::-webkit-scrollbar {
+  width: 6px;
+}
+.custom-scrollbar::-webkit-scrollbar-track {
+  background: transparent;
+}
+.custom-scrollbar::-webkit-scrollbar-thumb {
+  background-color: rgba(156, 163, 175, 0.3);
+  border-radius: 20px;
+}
+.custom-scrollbar::-webkit-scrollbar-thumb:hover {
+  background-color: var(--color-primary);
+}
+
+/* Thin horizontal scrollbar - brand colored */
+.scroll-thin-x {
+  scrollbar-width: thin;
+  scrollbar-color: rgba(229, 106, 74, 0.55) transparent;
+}
+.dark .scroll-thin-x {
+  scrollbar-color: rgba(229, 106, 74, 0.55) transparent;
+}
+.scroll-thin-x::-webkit-scrollbar { height: 3px; }
+.scroll-thin-x::-webkit-scrollbar-track { background: transparent; }
+.scroll-thin-x::-webkit-scrollbar-thumb {
+  background: rgba(229, 106, 74, 0.55);
+  border-radius: 3px;
+}
+.dark .scroll-thin-x::-webkit-scrollbar-thumb {
+  background: rgba(229, 106, 74, 0.55);
+}
+
+/* Reusable elevated card */
+.card-soft {
+  background-color: var(--color-surface);
+  box-shadow: var(--shadow-soft);
+  border-radius: var(--radius-brand-lg);
+}
+.card-elev {
+  background-color: var(--color-surface);
+  box-shadow: var(--shadow-elev);
+  border-radius: var(--radius-brand-lg);
+}
+
+/* Hero gradient (compat) */
+.bg-hero-gradient {
+  background: linear-gradient(180deg, var(--color-bg-alt) 0%, var(--color-bg) 100%);
+}
+
+/* macOS Vibrancy */
+.bg-vibrancy {
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+  background: rgba(255, 255, 255, 0.72);
+}
+.dark .bg-vibrancy {
+  background: rgba(38, 38, 38, 0.72);
+}
+
+/* macOS Traffic Lights */
+.traffic-lights {
+  display: flex;
+  gap: 8px;
+}
+.traffic-light {
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+}
+.traffic-light.red { background: #FF5F56; }
+.traffic-light.yellow { background: #FFBD2E; }
+.traffic-light.green { background: #27C93F; }
+
+/* Material Symbols */
+.material-symbols-outlined {
+  font-family: 'Material Symbols Outlined', sans-serif;
+  font-weight: normal;
+  font-style: normal;
+  font-size: 24px;
+  line-height: 1;
+  letter-spacing: normal;
+  text-transform: none;
+  display: inline-block;
+  white-space: nowrap;
+  word-wrap: normal;
+  direction: ltr;
+  font-feature-settings: 'liga';
+  -webkit-font-feature-settings: 'liga';
+  -webkit-font-smoothing: antialiased;
+  font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24;
+}
+.material-symbols-outlined.fill-1 {
+  font-variation-settings: 'FILL' 1, 'wght' 400, 'GRAD' 0, 'opsz' 24;
+}
+
+/* Disable text selection on buttons */
+button {
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+/* Tailwind v4 dropped default button cursor — restore globally */
+button:not(:disabled),
+[role="button"]:not([aria-disabled="true"]),
+label[for],
+summary,
+select {
+  cursor: pointer;
+}
+
+button:disabled,
+[role="button"][aria-disabled="true"] {
+  cursor: not-allowed;
+}
+
+/* ============================================================
+   Animations
+   ============================================================ */
+@keyframes spin {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+.animate-spin { animation: spin 1s linear infinite; }
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.5; }
+}
+.animate-pulse { animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite; }
+
+@keyframes border-glow {
+  0%, 100% {
+    box-shadow: 0 0 5px rgba(229, 106, 74, 0.3), 0 0 10px rgba(229, 106, 74, 0.2);
+    border-color: rgba(229, 106, 74, 0.5);
+  }
+  50% {
+    box-shadow: 0 0 10px rgba(229, 106, 74, 0.5), 0 0 20px rgba(229, 106, 74, 0.3);
+    border-color: rgba(229, 106, 74, 0.8);
+  }
+}
+.animate-border-glow { animation: border-glow 2s ease-in-out infinite; }
+
+@keyframes slideInFromRight {
+  from { transform: translateX(100%); opacity: 0; }
+  to { transform: translateX(0); opacity: 1; }
+}
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+@keyframes slideInFromTop {
+  from { transform: translateY(-10px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+.slide-in-right { animation: slideInFromRight 0.25s cubic-bezier(0.22, 1, 0.36, 1) forwards; }
+.fade-in { animation: fadeIn 0.2s ease-out forwards; }
+.slide-in-top { animation: slideInFromTop 0.18s cubic-bezier(0.22, 1, 0.36, 1) forwards; }
+
+@keyframes pulseGlow {
+  0%, 100% { opacity: 0.4; transform: scale(1); }
+  50% { opacity: 0.7; transform: scale(1.05); }
+}
+.animate-pulse-glow { animation: pulseGlow 3s ease-in-out infinite; }
+
+/* CTA shimmer + glow pulse */
+@keyframes ctaShimmer {
+  0% { transform: translateX(-120%) skewX(-20deg); }
+  100% { transform: translateX(220%) skewX(-20deg); }
+}
+@keyframes ctaGlowPulse {
+  0%, 100% { box-shadow: 0 8px 24px -8px rgba(229, 106, 74, 0.45), 0 0 0 0 rgba(229, 106, 74, 0.5); }
+  50% { box-shadow: 0 12px 32px -8px rgba(229, 106, 74, 0.6), 0 0 0 8px rgba(229, 106, 74, 0); }
+}
+.btn-cta {
+  position: relative;
+  overflow: hidden;
+  isolation: isolate;
+  animation: ctaGlowPulse 2.4s ease-in-out infinite;
+}
+.btn-cta::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 50%;
+  height: 100%;
+  background: linear-gradient(90deg, transparent, rgba(255,255,255,0.35), transparent);
+  animation: ctaShimmer 2.8s ease-in-out infinite;
+  pointer-events: none;
+  z-index: 1;
+}
+.btn-cta > * { position: relative; z-index: 2; }
+
+/* Dot Grid Background Pattern */
+.dot-grid-bg {
+  background-color: var(--color-bg);
+  background-image:
+    radial-gradient(circle at 15% 20%, rgba(229, 106, 74, 0.10) 0%, transparent 40%),
+    radial-gradient(circle at 85% 80%, rgba(229, 106, 74, 0.06) 0%, transparent 40%);
+}
+.dark .dot-grid-bg {
+  background-image:
+    radial-gradient(circle at 15% 20%, rgba(229, 106, 74, 0.18) 0%, transparent 40%),
+    radial-gradient(circle at 85% 80%, rgba(229, 106, 74, 0.10) 0%, transparent 40%);
+}
+
+/* Landing-style faint grid overlay (use absolute pos inside relative parent) */
+.landing-grid {
+  background-image:
+    linear-gradient(to right, var(--color-accent) 1px, transparent 1px),
+    linear-gradient(to bottom, var(--color-accent) 1px, transparent 1px);
+  background-size: 40px 40px;
+  opacity: 0.08;
+}
+.dark .landing-grid {
+  opacity: 0.04;
+}
+
+/* React Flow controls: match app theme */
+.react-flow-controls-custom {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 10px;
+  box-shadow: var(--shadow-soft);
+  overflow: hidden;
+}
+
+.react-flow-controls-custom button {
+  background: var(--color-surface);
+  color: var(--color-text-main);
+  border: 0;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.react-flow-controls-custom button:last-child {
+  border-bottom: 0;
+}
+
+.react-flow-controls-custom button:hover {
+  background: var(--color-bg-alt);
+}
+
+/* Changelog markdown body */
+.changelog-body h1 {
+  font-size: 1.4rem;
+  font-weight: 700;
+  margin: 1.5rem 0 0.75rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--color-border);
+}
+.changelog-body h1:first-child { margin-top: 0; }
+.changelog-body h2 {
+  font-size: 1.05rem;
+  font-weight: 600;
+  margin: 1rem 0 0.5rem;
+  color: var(--color-primary);
+}
+.changelog-body h3 {
+  font-size: 0.95rem;
+  font-weight: 600;
+  margin: 0.75rem 0 0.4rem;
+}
+.changelog-body ul {
+  list-style: disc;
+  padding-left: 1.5rem;
+  margin: 0.5rem 0;
+}
+.changelog-body li { margin: 0.25rem 0; line-height: 1.6; }
+.changelog-body p { margin: 0.5rem 0; line-height: 1.6; }
+.changelog-body code {
+  background: var(--color-bg-alt);
+  padding: 0.1rem 0.35rem;
+  border-radius: 4px;
+  font-size: 0.875em;
+  font-family: ui-monospace, monospace;
+}
+.changelog-body a {
+  color: var(--color-primary);
+  text-decoration: underline;
+}
+.changelog-body hr {
+  border: none;
+  border-top: 1px solid var(--color-border);
+  margin: 1.5rem 0;
+}
diff --git a/src/app/landing/components/AnimatedBackground.js b/src/app/landing/components/AnimatedBackground.js
new file mode 100644
index 0000000..9251aaf
--- /dev/null
+++ b/src/app/landing/components/AnimatedBackground.js
@@ -0,0 +1,57 @@
+"use client";
+
+export default function AnimatedBackground() {
+  return (
+    <>
+      {/* Animated Background */}
+      <div className="fixed inset-0 -z-10 overflow-hidden pointer-events-none">
+        {/* Grid pattern */}
+        <div 
+          className="absolute inset-0 opacity-[0.08]" 
+          style={{
+            backgroundImage: `linear-gradient(to right, #f97815 1px, transparent 1px), linear-gradient(to bottom, #f97815 1px, transparent 1px)`,
+            backgroundSize: '50px 50px'
+          }}
+        />
+        
+        {/* Animated gradient orbs */}
+        <div className="absolute -top-20 left-1/4 w-[600px] h-[600px] bg-[#f97815]/20 rounded-full blur-[120px] animate-blob" />
+        <div className="absolute top-1/3 -right-20 w-[500px] h-[500px] bg-purple-500/15 rounded-full blur-[120px] animate-blob-delayed-1" />
+        <div className="absolute -bottom-20 left-1/2 w-[550px] h-[550px] bg-blue-500/12 rounded-full blur-[120px] animate-blob-delayed-2" />
+        
+        {/* Vignette effect */}
+        <div 
+          className="absolute inset-0" 
+          style={{
+            background: 'radial-gradient(circle at center, transparent 0%, rgba(24, 20, 17, 0.4) 100%)'
+          }}
+        />
+      </div>
+
+      {/* CSS Animations */}
+      <style jsx global>{`
+        @keyframes blob {
+          0%, 100% { 
+            transform: translate(0, 0) scale(1);
+          }
+          33% { 
+            transform: translate(30px, -50px) scale(1.1);
+          }
+          66% { 
+            transform: translate(-20px, 20px) scale(0.9);
+          }
+        }
+        .animate-blob {
+          animation: blob 20s ease-in-out infinite;
+        }
+        .animate-blob-delayed-1 {
+          animation: blob 22s ease-in-out 2s infinite;
+        }
+        .animate-blob-delayed-2 {
+          animation: blob 25s ease-in-out 4s infinite;
+        }
+      `}</style>
+    </>
+  );
+}
+
diff --git a/src/app/landing/components/Features.js b/src/app/landing/components/Features.js
new file mode 100644
index 0000000..37c29ab
--- /dev/null
+++ b/src/app/landing/components/Features.js
@@ -0,0 +1,133 @@
+"use client";
+
+const FEATURES = [
+  { 
+    icon: "link", 
+    title: "Unified Endpoint", 
+    desc: "Access all providers via a single standard API URL.", 
+    colors: {
+      border: "hover:border-blue-500/50",
+      bg: "hover:bg-blue-500/5",
+      iconBg: "bg-blue-500/10",
+      iconText: "text-blue-500",
+      titleHover: "group-hover:text-blue-400"
+    }
+  },
+  { 
+    icon: "bolt", 
+    title: "Easy Setup", 
+    desc: "Get up and running in minutes with npx command.", 
+    colors: {
+      border: "hover:border-orange-500/50",
+      bg: "hover:bg-orange-500/5",
+      iconBg: "bg-orange-500/10",
+      iconText: "text-orange-500",
+      titleHover: "group-hover:text-orange-400"
+    }
+  },
+  { 
+    icon: "shield_with_heart", 
+    title: "Model Fallback", 
+    desc: "Automatically switch providers on failure or high latency.", 
+    colors: {
+      border: "hover:border-rose-500/50",
+      bg: "hover:bg-rose-500/5",
+      iconBg: "bg-rose-500/10",
+      iconText: "text-rose-500",
+      titleHover: "group-hover:text-rose-400"
+    }
+  },
+  { 
+    icon: "monitoring", 
+    title: "Usage Tracking", 
+    desc: "Detailed analytics and cost monitoring across all models.", 
+    colors: {
+      border: "hover:border-purple-500/50",
+      bg: "hover:bg-purple-500/5",
+      iconBg: "bg-purple-500/10",
+      iconText: "text-purple-500",
+      titleHover: "group-hover:text-purple-400"
+    }
+  },
+  { 
+    icon: "key", 
+    title: "OAuth & API Keys", 
+    desc: "Securely manage credentials in one vault.", 
+    colors: {
+      border: "hover:border-amber-500/50",
+      bg: "hover:bg-amber-500/5",
+      iconBg: "bg-amber-500/10",
+      iconText: "text-amber-500",
+      titleHover: "group-hover:text-amber-400"
+    }
+  },
+  { 
+    icon: "cloud_sync", 
+    title: "Cloud Sync", 
+    desc: "Sync your configurations across devices instantly.", 
+    colors: {
+      border: "hover:border-sky-500/50",
+      bg: "hover:bg-sky-500/5",
+      iconBg: "bg-sky-500/10",
+      iconText: "text-sky-500",
+      titleHover: "group-hover:text-sky-400"
+    }
+  },
+  { 
+    icon: "terminal", 
+    title: "CLI Support", 
+    desc: "Works with Claude Code, Codex, Cline, Cursor, and more.", 
+    colors: {
+      border: "hover:border-emerald-500/50",
+      bg: "hover:bg-emerald-500/5",
+      iconBg: "bg-emerald-500/10",
+      iconText: "text-emerald-500",
+      titleHover: "group-hover:text-emerald-400"
+    }
+  },
+  { 
+    icon: "dashboard", 
+    title: "Dashboard", 
+    desc: "Visual dashboard for real-time traffic analysis.", 
+    colors: {
+      border: "hover:border-fuchsia-500/50",
+      bg: "hover:bg-fuchsia-500/5",
+      iconBg: "bg-fuchsia-500/10",
+      iconText: "text-fuchsia-500",
+      titleHover: "group-hover:text-fuchsia-400"
+    }
+  },
+];
+
+export default function Features() {
+  return (
+    <section className="py-24 px-6" id="features">
+      <div className="max-w-7xl mx-auto">
+        <div className="mb-16">
+          <h2 className="text-3xl md:text-4xl font-bold mb-4">Powerful Features</h2>
+          <p className="text-gray-400 max-w-xl text-lg">
+            Everything you need to manage your AI infrastructure in one place, built for scale.
+          </p>
+        </div>
+        
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+          {FEATURES.map((feature) => (
+            <div 
+              key={feature.title}
+              className={`p-6 rounded-xl bg-[#23180f] border border-[#3a2f27] ${feature.colors.border} ${feature.colors.bg} transition-all duration-300 group`}
+            >
+              <div className={`w-10 h-10 rounded-lg ${feature.colors.iconBg} flex items-center justify-center mb-4 ${feature.colors.iconText} group-hover:scale-110 transition-transform duration-300`}>
+                <span className="material-symbols-outlined">{feature.icon}</span>
+              </div>
+              <h3 className={`text-lg font-bold mb-2 ${feature.colors.titleHover} transition-colors`}>
+                {feature.title}
+              </h3>
+              <p className="text-sm text-gray-400 leading-relaxed">{feature.desc}</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
+
diff --git a/src/app/landing/components/FlowAnimation.js b/src/app/landing/components/FlowAnimation.js
new file mode 100644
index 0000000..4209cc0
--- /dev/null
+++ b/src/app/landing/components/FlowAnimation.js
@@ -0,0 +1,175 @@
+"use client";
+import { useEffect, useState } from "react";
+import ProviderIcon from "@/shared/components/ProviderIcon";
+
+const CLI_TOOLS = [
+  { id: "claude", name: "Claude Code", image: "/providers/claude.png" },
+  { id: "codex", name: "OpenAI Codex", image: "/providers/codex.png" },
+  { id: "cline", name: "Cline", image: "/providers/cline.png" },
+  { id: "cursor", name: "Cursor", image: "/providers/cursor.png" },
+];
+
+const PROVIDERS = [
+  {
+    id: "openai",
+    name: "OpenAI",
+    color: "bg-emerald-500",
+    textColor: "text-white",
+  },
+  {
+    id: "anthropic",
+    name: "Anthropic",
+    color: "bg-orange-400",
+    textColor: "text-white",
+  },
+  {
+    id: "gemini",
+    name: "Gemini",
+    color: "bg-blue-500",
+    textColor: "text-white",
+  },
+  {
+    id: "github",
+    name: "GitHub Copilot",
+    color: "bg-gray-700",
+    textColor: "text-white",
+  },
+];
+
+export default function FlowAnimation() {
+  const [activeFlow, setActiveFlow] = useState(0);
+
+  useEffect(() => {
+    const interval = setInterval(() => {
+      setActiveFlow((prev) => (prev + 1) % PROVIDERS.length);
+    }, 2000);
+    return () => clearInterval(interval);
+  }, []);
+
+  return (
+    <div className="mt-16 w-full max-w-4xl relative h-[360px] hidden md:flex items-center justify-center animate-[float_6s_ease-in-out_infinite]">
+      {/* 9Router Hub - Center */}
+      <div className="relative z-20 w-32 h-32 rounded-full bg-[#23180f] border-2 border-[#f97815] shadow-[0_0_40px_rgba(249,120,21,0.3)] flex flex-col items-center justify-center gap-1 group cursor-pointer hover:scale-105 transition-transform duration-500">
+        <span className="material-symbols-outlined text-4xl text-[#f97815]">
+          hub
+        </span>
+        <span className="text-xs font-bold text-white tracking-widest uppercase">
+          9Router
+        </span>
+        <div className="absolute inset-0 rounded-full border border-[#f97815]/30 animate-ping opacity-20"></div>
+      </div>
+
+      {/* CLI Tools - Left side */}
+      <div className="absolute left-0 top-1/2 -translate-y-1/2 flex flex-col gap-7">
+        {CLI_TOOLS.map((tool) => (
+          <div
+            key={tool.id}
+            className="flex items-center gap-3 opacity-70 hover:opacity-100 transition-opacity group"
+          >
+            <div className="w-16 h-16 rounded-2xl bg-[#23180f] border border-[#3a2f27] flex items-center justify-center overflow-hidden p-2 hover:border-[#f97815]/50 transition-all hover:scale-105">
+              <ProviderIcon
+                src={tool.image}
+                alt={tool.name}
+                size={48}
+                className="object-contain rounded-xl max-w-[48px] max-h-[48px]"
+                fallbackText={tool.name.slice(0, 2).toUpperCase()}
+              />
+            </div>
+          </div>
+        ))}
+      </div>
+
+      {/* SVG Lines from CLI to 9Router */}
+      <svg
+        className="absolute inset-0 w-full h-full z-10 pointer-events-none stroke-yellow-700"
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path
+          className="animate-[dash_2s_linear_infinite]"
+          d="M 60 50 C 250 70, 250 180, 360 180"
+          fill="none"
+          strokeDasharray="5,5"
+          strokeWidth="2"
+        ></path>
+        <path
+          className="animate-[dash_2s_linear_infinite]"
+          d="M 60 140 C 250 140, 250 180, 360 180"
+          fill="none"
+          strokeDasharray="5,5"
+          strokeWidth="2"
+        ></path>
+        <path
+          className="animate-[dash_2s_linear_infinite]"
+          d="M 60 210 C 250 210, 250 180, 360 180"
+          fill="none"
+          strokeDasharray="5,5"
+          strokeWidth="2"
+        ></path>
+        <path
+          className="animate-[dash_2s_linear_infinite]"
+          d="M 60 300 C 250 280, 250 180, 360 180"
+          fill="none"
+          strokeDasharray="5,5"
+          strokeWidth="2"
+        ></path>
+      </svg>
+
+      {/* SVG Lines from 9Router to Providers */}
+      <svg
+        className="absolute inset-0 w-full h-full z-10 pointer-events-none"
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path
+          d="M 440 180 C 550 180, 550 50, 740 50"
+          fill="none"
+          stroke={activeFlow === 0 ? "#f97815" : "rgb(75, 85, 99)"}
+          strokeWidth={activeFlow === 0 ? "3" : "2"}
+          className={activeFlow === 0 ? "animate-pulse" : ""}
+        ></path>
+        <path
+          d="M 440 180 C 550 180, 550 130, 740 130"
+          fill="none"
+          stroke={activeFlow === 1 ? "#f97815" : "rgb(75, 85, 99)"}
+          strokeWidth={activeFlow === 1 ? "3" : "2"}
+          className={activeFlow === 1 ? "animate-pulse" : ""}
+        ></path>
+        <path
+          d="M 440 180 C 550 180, 550 230, 740 230"
+          fill="none"
+          stroke={activeFlow === 2 ? "#f97815" : "rgb(75, 85, 99)"}
+          strokeWidth={activeFlow === 2 ? "3" : "2"}
+          className={activeFlow === 2 ? "animate-pulse" : ""}
+        ></path>
+        <path
+          d="M 440 180 C 550 180, 550 310, 740 310"
+          fill="none"
+          stroke={activeFlow === 3 ? "#f97815" : "rgb(75, 85, 99)"}
+          strokeWidth={activeFlow === 3 ? "3" : "2"}
+          className={activeFlow === 3 ? "animate-pulse" : ""}
+        ></path>
+      </svg>
+
+      {/* AI Providers - Right side */}
+      <div className="absolute right-0 top-0 bottom-0 flex flex-col justify-between py-6">
+        {PROVIDERS.map((provider, idx) => (
+          <div
+            key={provider.id}
+            className={`px-4 py-2 rounded-lg ${provider.color} ${provider.textColor} flex items-center justify-center font-bold text-xs shadow-lg hover:scale-110 transition-all cursor-help min-w-[140px] ${
+              activeFlow === idx ? "ring-4 ring-[#f97815]/50 scale-110" : ""
+            }`}
+            title={provider.name}
+          >
+            {provider.name}
+          </div>
+        ))}
+      </div>
+
+      {/* Mobile fallback */}
+      <div className="md:hidden mt-8 w-full p-4 rounded-lg bg-[#23180f] border border-[#3a2f27]">
+        <p className="text-sm text-center text-gray-400">
+          Interactive diagram visible on desktop
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/src/app/landing/components/Footer.js b/src/app/landing/components/Footer.js
new file mode 100644
index 0000000..91209a5
--- /dev/null
+++ b/src/app/landing/components/Footer.js
@@ -0,0 +1,61 @@
+"use client";
+
+export default function Footer() {
+  return (
+    <footer className="border-t border-[#3a2f27] bg-[#120f0d] pt-16 pb-8 px-6">
+      <div className="max-w-7xl mx-auto">
+        <div className="grid grid-cols-2 md:grid-cols-4 lg:grid-cols-5 gap-8 mb-16">
+          {/* Brand */}
+          <div className="col-span-2 lg:col-span-2">
+            <div className="flex items-center gap-3 mb-6">
+              <div className="size-6 rounded bg-[#f97815] flex items-center justify-center text-white">
+                <span className="material-symbols-outlined text-[16px]">hub</span>
+              </div>
+              <h3 className="text-white text-lg font-bold">9Router</h3>
+            </div>
+            <p className="text-gray-500 text-sm max-w-xs mb-6">
+              The unified endpoint for AI generation. Connect, route, and manage your AI providers with ease.
+            </p>
+            <div className="flex gap-4">
+              <a className="text-gray-400 hover:text-white transition-colors" href="https://github.com/decolua/9router" target="_blank" rel="noopener noreferrer">
+                <span className="material-symbols-outlined">code</span>
+              </a>
+            </div>
+          </div>
+          
+          {/* Product */}
+          <div className="flex flex-col gap-4">
+            <h4 className="font-bold text-white">Product</h4>
+            <a className="text-gray-400 hover:text-[#f97815] text-sm transition-colors" href="#features">Features</a>
+            <a className="text-gray-400 hover:text-[#f97815] text-sm transition-colors" href="/dashboard">Dashboard</a>
+            <a className="text-gray-400 hover:text-[#f97815] text-sm transition-colors" href="https://github.com/decolua/9router" target="_blank" rel="noopener noreferrer">Changelog</a>
+          </div>
+          
+          {/* Resources */}
+          <div className="flex flex-col gap-4">
+            <h4 className="font-bold text-white">Resources</h4>
+            <a className="text-gray-400 hover:text-[#f97815] text-sm transition-colors" href="https://github.com/decolua/9router#readme" target="_blank" rel="noopener noreferrer">Documentation</a>
+            <a className="text-gray-400 hover:text-[#f97815] text-sm transition-colors" href="https://github.com/decolua/9router" target="_blank" rel="noopener noreferrer">GitHub</a>
+            <a className="text-gray-400 hover:text-[#f97815] text-sm transition-colors" href="https://www.npmjs.com/package/9router" target="_blank" rel="noopener noreferrer">NPM</a>
+          </div>
+          
+          {/* Legal */}
+          <div className="flex flex-col gap-4">
+            <h4 className="font-bold text-white">Legal</h4>
+            <a className="text-gray-400 hover:text-[#f97815] text-sm transition-colors" href="https://github.com/decolua/9router/blob/main/LICENSE" target="_blank" rel="noopener noreferrer">MIT License</a>
+          </div>
+        </div>
+        
+        {/* Bottom */}
+        <div className="border-t border-[#3a2f27] pt-8 flex flex-col md:flex-row justify-between items-center gap-4">
+          <p className="text-gray-600 text-sm">© 2025 9Router. All rights reserved.</p>
+          <div className="flex gap-6">
+            <a className="text-gray-600 hover:text-white text-sm transition-colors" href="https://github.com/decolua/9router" target="_blank" rel="noopener noreferrer">GitHub</a>
+            <a className="text-gray-600 hover:text-white text-sm transition-colors" href="https://www.npmjs.com/package/9router" target="_blank" rel="noopener noreferrer">NPM</a>
+          </div>
+        </div>
+      </div>
+    </footer>
+  );
+}
+
diff --git a/src/app/landing/components/GetStarted.js b/src/app/landing/components/GetStarted.js
new file mode 100644
index 0000000..564213a
--- /dev/null
+++ b/src/app/landing/components/GetStarted.js
@@ -0,0 +1,97 @@
+"use client";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+
+export default function GetStarted() {
+  const { copied, copy } = useCopyToClipboard();
+
+  const handleCopy = (text) => {
+    copy(text, "landing");
+  };
+
+  return (
+    <section className="py-24 px-6 bg-[#120f0d]">
+      <div className="max-w-7xl mx-auto">
+        <div className="flex flex-col lg:flex-row gap-16 items-start">
+          {/* Left: Steps */}
+          <div className="flex-1">
+            <h2 className="text-3xl md:text-4xl font-bold mb-6">Get Started in 30 Seconds</h2>
+            <p className="text-gray-400 text-lg mb-8">
+              Install 9Router, configure your providers via web dashboard, and start routing AI requests.
+            </p>
+            
+            <div className="flex flex-col gap-6">
+              <div className="flex gap-4">
+                <div className="flex-none w-8 h-8 rounded-full bg-[#f97815]/20 text-[#f97815] flex items-center justify-center font-bold">1</div>
+                <div>
+                  <h4 className="font-bold text-lg">Install 9Router</h4>
+                  <p className="text-sm text-gray-500 mt-1">Run npx command to start the server instantly</p>
+                </div>
+              </div>
+              
+              <div className="flex gap-4">
+                <div className="flex-none w-8 h-8 rounded-full bg-[#f97815]/20 text-[#f97815] flex items-center justify-center font-bold">2</div>
+                <div>
+                  <h4 className="font-bold text-lg">Open Dashboard</h4>
+                  <p className="text-sm text-gray-500 mt-1">Configure providers and API keys via web interface</p>
+                </div>
+              </div>
+              
+              <div className="flex gap-4">
+                <div className="flex-none w-8 h-8 rounded-full bg-[#f97815]/20 text-[#f97815] flex items-center justify-center font-bold">3</div>
+                <div>
+                  <h4 className="font-bold text-lg">Route Requests</h4>
+                  <p className="text-sm text-gray-500 mt-1">Point your CLI tools to http://localhost:20128</p>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          {/* Right: Code block */}
+          <div className="flex-1 w-full">
+            <div className="rounded-xl overflow-hidden bg-[#1e1e1e] border border-[#3a2f27] shadow-2xl">
+              {/* Terminal header */}
+              <div className="flex items-center gap-2 px-4 py-3 bg-[#252526] border-b border-gray-700">
+                <div className="w-3 h-3 rounded-full bg-red-500"></div>
+                <div className="w-3 h-3 rounded-full bg-yellow-500"></div>
+                <div className="w-3 h-3 rounded-full bg-green-500"></div>
+                <div className="ml-2 text-xs text-gray-500 font-mono">terminal</div>
+              </div>
+              
+              {/* Terminal content */}
+              <div className="p-6 font-mono text-sm leading-relaxed overflow-x-auto">
+                <div 
+                  className="flex items-center gap-2 mb-4 group cursor-pointer"
+                  onClick={() => handleCopy("npx 9router")}
+                >
+                  <span className="text-green-400">$</span>
+                  <span className="text-white">npx 9router</span>
+                  <span className="ml-auto text-gray-500 text-xs opacity-0 group-hover:opacity-100">
+                    {copied === "landing" ? "✓ Copied" : "Copy"}
+                  </span>
+                </div>
+                
+                <div className="text-gray-400 mb-6">
+                  <span className="text-[#f97815]">&gt;</span> Starting 9Router...<br/>
+                  <span className="text-[#f97815]">&gt;</span> Server running on <span className="text-blue-400">http://localhost:20128</span><br/>
+                  <span className="text-[#f97815]">&gt;</span> Dashboard: <span className="text-blue-400">http://localhost:20128/dashboard</span><br/>
+                  <span className="text-green-400">&gt;</span> Ready to route! ✓
+                </div>
+                
+                <div className="text-xs text-gray-500 mb-2 border-t border-gray-700 pt-4">
+                  📝 Configure providers in dashboard or use environment variables
+                </div>
+                
+                <div className="text-gray-400 text-xs">
+                  <span className="text-purple-400">Data Location:</span><br/>
+                  <span className="text-gray-500">  macOS/Linux:</span> ~/.9router/db/data.sqlite<br/>
+                  <span className="text-gray-500">  Windows:</span> %APPDATA%/9router/db/data.sqlite
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
+
diff --git a/src/app/landing/components/HeroSection.js b/src/app/landing/components/HeroSection.js
new file mode 100644
index 0000000..cb69116
--- /dev/null
+++ b/src/app/landing/components/HeroSection.js
@@ -0,0 +1,47 @@
+"use client";
+
+export default function HeroSection() {
+  return (
+    <section className="relative pt-32 pb-20 px-6 min-h-[90vh] flex flex-col items-center justify-center overflow-hidden">
+      {/* Glow effect */}
+      <div className="absolute top-0 left-1/2 -translate-x-1/2 w-[1000px] h-[500px] bg-[#f97815]/10 rounded-full blur-[120px] pointer-events-none"></div>
+      
+      <div className="relative z-10 max-w-4xl w-full text-center flex flex-col items-center gap-8">
+        {/* Version badge */}
+        <div className="inline-flex items-center gap-2 rounded-full border border-[#3a2f27] bg-[#23180f]/50 px-3 py-1 text-xs font-medium text-[#f97815]">
+          <span className="flex h-2 w-2 rounded-full bg-[#f97815] animate-pulse"></span>
+          v1.0 is now live
+        </div>
+
+        {/* Main heading */}
+        <h1 className="text-5xl md:text-7xl font-black leading-[1.1] tracking-tight">
+          One Endpoint for <br/>
+          <span className="text-[#f97815]">All AI Providers</span>
+        </h1>
+
+        {/* Description */}
+        <p className="text-lg md:text-xl text-gray-400 max-w-2xl mx-auto font-light">
+          AI endpoint proxy with web dashboard - A JavaScript port of CLIProxyAPI. Works seamlessly with Claude Code, OpenAI Codex, Cline, RooCode, and other CLI tools.
+        </p>
+
+        {/* CTA Buttons */}
+        <div className="flex flex-wrap items-center justify-center gap-4 w-full">
+          <button className="h-12 px-8 rounded-lg bg-[#f97815] hover:bg-[#e0650a] text-[#181411] text-base font-bold transition-all shadow-[0_0_15px_rgba(249,120,21,0.4)] flex items-center gap-2">
+            <span className="material-symbols-outlined">rocket_launch</span>
+            Get Started
+          </button>
+          <a 
+            href="https://github.com/decolua/9router" 
+            target="_blank" 
+            rel="noopener noreferrer"
+            className="h-12 px-8 rounded-lg border border-[#3a2f27] bg-[#23180f] hover:bg-[#3a2f27] text-white text-base font-bold transition-all flex items-center gap-2"
+          >
+            <span className="material-symbols-outlined">code</span>
+            View on GitHub
+          </a>
+        </div>
+      </div>
+    </section>
+  );
+}
+
diff --git a/src/app/landing/components/HowItWorks.js b/src/app/landing/components/HowItWorks.js
new file mode 100644
index 0000000..c9b2b7a
--- /dev/null
+++ b/src/app/landing/components/HowItWorks.js
@@ -0,0 +1,66 @@
+"use client";
+
+export default function HowItWorks() {
+  return (
+    <section className="py-24 border-y border-[#3a2f27] bg-[#23180f]/30" id="how-it-works">
+      <div className="max-w-7xl mx-auto px-6">
+        <div className="mb-16">
+          <h2 className="text-3xl md:text-4xl font-bold mb-4">How 9Router Works</h2>
+          <p className="text-gray-400 max-w-xl text-lg">
+            Data flows seamlessly from your application through our intelligent routing layer to the best provider for the job.
+          </p>
+        </div>
+        
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-8 relative">
+          {/* Connection line */}
+          <div className="hidden md:block absolute top-12 left-[16%] right-[16%] h-[2px] bg-linear-to-r from-gray-700 via-[#f97815] to-gray-700 -z-10"></div>
+          
+          {/* Step 1: CLI & SDKs */}
+          <div className="flex flex-col gap-6 relative group">
+            <div className="w-24 h-24 rounded-2xl bg-[#181411] border border-[#3a2f27] flex items-center justify-center shadow-xl group-hover:border-gray-500 transition-colors z-10 mx-auto md:mx-0">
+              <span className="material-symbols-outlined text-4xl text-gray-300">terminal</span>
+            </div>
+            <div>
+              <h3 className="text-xl font-bold mb-2">1. CLI &amp; SDKs</h3>
+              <p className="text-sm text-gray-400">
+                Your requests start from your favorite tools or our unified SDK. Just change the base URL.
+              </p>
+            </div>
+          </div>
+
+          {/* Step 2: 9Router Hub */}
+          <div className="flex flex-col gap-6 relative group md:items-center md:text-center">
+            <div className="w-24 h-24 rounded-2xl bg-[#181411] border-2 border-[#f97815] flex items-center justify-center shadow-[0_0_30px_rgba(249,120,21,0.2)] z-10 mx-auto">
+              <span className="material-symbols-outlined text-4xl text-[#f97815] animate-pulse">hub</span>
+            </div>
+            <div>
+              <h3 className="text-xl font-bold mb-2 text-[#f97815]">2. 9Router Hub</h3>
+              <p className="text-sm text-gray-400">
+                Our engine analyzes the prompt, checks provider health, and routes for lowest latency or cost.
+              </p>
+            </div>
+          </div>
+
+          {/* Step 3: AI Providers */}
+          <div className="flex flex-col gap-6 relative group md:items-end md:text-right">
+            <div className="w-24 h-24 rounded-2xl bg-[#181411] border border-[#3a2f27] flex items-center justify-center shadow-xl group-hover:border-gray-500 transition-colors z-10 mx-auto md:mx-0">
+              <div className="grid grid-cols-2 gap-2">
+                <div className="w-6 h-6 rounded bg-white/10"></div>
+                <div className="w-6 h-6 rounded bg-white/10"></div>
+                <div className="w-6 h-6 rounded bg-white/10"></div>
+                <div className="w-6 h-6 rounded bg-white/10"></div>
+              </div>
+            </div>
+            <div>
+              <h3 className="text-xl font-bold mb-2">3. AI Providers</h3>
+              <p className="text-sm text-gray-400">
+                The request is fulfilled by OpenAI, Anthropic, Gemini, or others instantly.
+              </p>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
+
diff --git a/src/app/landing/components/Navigation.js b/src/app/landing/components/Navigation.js
new file mode 100644
index 0000000..ba552d6
--- /dev/null
+++ b/src/app/landing/components/Navigation.js
@@ -0,0 +1,72 @@
+"use client";
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+
+export default function Navigation() {
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+  const router = useRouter();
+
+  return (
+    <nav className="fixed top-0 z-50 w-full bg-[#181411]/80 backdrop-blur-md border-b border-[#3a2f27]">
+      <div className="max-w-7xl mx-auto px-6 h-16 flex items-center justify-between">
+        {/* Logo */}
+        <button
+          type="button"
+          className="flex items-center gap-3 cursor-pointer bg-transparent border-none p-0"
+          onClick={() => router.push("/")}
+          aria-label="Navigate to home"
+        >
+          <div className="size-8 rounded bg-linear-to-br from-[#f97815] to-orange-700 flex items-center justify-center text-white">
+            <span className="material-symbols-outlined text-[20px]">hub</span>
+          </div>
+          <h2 className="text-white text-xl font-bold tracking-tight">9Router</h2>
+        </button>
+
+        {/* Desktop menu */}
+        <div className="hidden md:flex items-center gap-8">
+          <a className="text-gray-300 hover:text-white text-sm font-medium transition-colors" href="#features">Features</a>
+          <a className="text-gray-300 hover:text-white text-sm font-medium transition-colors" href="#how-it-works">How it Works</a>
+          <a className="text-gray-300 hover:text-white text-sm font-medium transition-colors" href="https://github.com/decolua/9router#readme" target="_blank" rel="noopener noreferrer">Docs</a>
+          <a className="text-gray-300 hover:text-white text-sm font-medium transition-colors flex items-center gap-1" href="https://github.com/decolua/9router" target="_blank" rel="noopener noreferrer">
+            GitHub <span className="material-symbols-outlined text-[14px]">open_in_new</span>
+          </a>
+        </div>
+
+        {/* CTA + Mobile menu */}
+        <div className="flex items-center gap-4">
+          <button 
+            onClick={() => router.push("/dashboard")}
+            className="hidden sm:flex h-9 items-center justify-center rounded-lg px-4 bg-[#f97815] hover:bg-[#e0650a] transition-all text-[#181411] text-sm font-bold shadow-[0_0_15px_rgba(249,120,21,0.4)] hover:shadow-[0_0_20px_rgba(249,120,21,0.6)]"
+          >
+            Get Started
+          </button>
+          <button 
+            className="md:hidden text-white"
+            onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
+          >
+            <span className="material-symbols-outlined">{mobileMenuOpen ? "close" : "menu"}</span>
+          </button>
+        </div>
+      </div>
+
+      {/* Mobile menu dropdown */}
+      {mobileMenuOpen && (
+        <div className="md:hidden border-t border-[#3a2f27] bg-[#181411]/95 backdrop-blur-md">
+          <div className="flex flex-col gap-4 p-6">
+            <a className="text-gray-300 hover:text-white text-sm font-medium transition-colors" href="#features" onClick={() => setMobileMenuOpen(false)}>Features</a>
+            <a className="text-gray-300 hover:text-white text-sm font-medium transition-colors" href="#how-it-works" onClick={() => setMobileMenuOpen(false)}>How it Works</a>
+            <a className="text-gray-300 hover:text-white text-sm font-medium transition-colors" href="https://github.com/decolua/9router#readme" target="_blank" rel="noopener noreferrer">Docs</a>
+            <a className="text-gray-300 hover:text-white text-sm font-medium transition-colors" href="https://github.com/decolua/9router" target="_blank" rel="noopener noreferrer">GitHub</a>
+            <button 
+              onClick={() => router.push("/dashboard")}
+              className="h-9 rounded-lg bg-[#f97815] hover:bg-[#e0650a] text-[#181411] text-sm font-bold"
+            >
+              Get Started
+            </button>
+          </div>
+        </div>
+      )}
+    </nav>
+  );
+}
+
diff --git a/src/app/landing/page.js b/src/app/landing/page.js
new file mode 100644
index 0000000..78b0905
--- /dev/null
+++ b/src/app/landing/page.js
@@ -0,0 +1,106 @@
+"use client";
+import { useRouter } from "next/navigation";
+import Navigation from "./components/Navigation";
+import HeroSection from "./components/HeroSection";
+import FlowAnimation from "./components/FlowAnimation";
+import HowItWorks from "./components/HowItWorks";
+import Features from "./components/Features";
+import GetStarted from "./components/GetStarted";
+import Footer from "./components/Footer";
+
+export default function LandingPage() {
+  const router = useRouter();
+  return (
+    <div className="relative text-white font-sans overflow-x-hidden antialiased selection:bg-[#f97815] selection:text-white">
+      {/* Animated Background */}
+      <div className="fixed inset-0 z-0 overflow-hidden pointer-events-none bg-[#181411]">
+        {/* Grid pattern */}
+        <div className="absolute inset-0 opacity-[0.06]" style={{
+          backgroundImage: `linear-gradient(to right, #f97815 1px, transparent 1px), linear-gradient(to bottom, #f97815 1px, transparent 1px)`,
+          backgroundSize: '50px 50px'
+        }}></div>
+        
+        {/* Animated gradient orbs */}
+        <div className="absolute top-0 left-1/4 w-[700px] h-[700px] bg-[#f97815]/12 rounded-full blur-[130px] animate-blob"></div>
+        <div className="absolute top-1/3 right-1/4 w-[600px] h-[600px] bg-purple-500/10 rounded-full blur-[130px] animate-blob" style={{ animationDelay: '2s', animationDuration: '22s' }}></div>
+        <div className="absolute bottom-0 left-1/2 w-[650px] h-[650px] bg-blue-500/8 rounded-full blur-[130px] animate-blob" style={{ animationDelay: '4s', animationDuration: '25s' }}></div>
+        
+        {/* Vignette effect */}
+        <div className="absolute inset-0" style={{
+          background: 'radial-gradient(circle at center, transparent 0%, rgba(24, 20, 17, 0.4) 100%)'
+        }}></div>
+      </div>
+
+      <div className="relative z-10">
+        <Navigation />
+        
+        <main>
+          {/* Hero with Flow Animation */}
+          <div className="relative">
+          <HeroSection />
+          <div className="flex justify-center pb-20">
+            <FlowAnimation />
+          </div>
+        </div>
+        
+        <GetStarted />
+        <HowItWorks />
+        <Features />
+        
+        {/* CTA Section */}
+        <section className="py-32 px-6 relative overflow-hidden">
+          <div className="absolute inset-0 bg-linear-to-t from-[#f97815]/5 to-transparent pointer-events-none"></div>
+          <div className="max-w-4xl mx-auto text-center relative z-10">
+            <h2 className="text-4xl md:text-5xl font-black mb-6">Ready to Simplify Your AI Infrastructure?</h2>
+            <p className="text-xl text-gray-400 mb-10 max-w-2xl mx-auto">
+              Join developers who are streamlining their AI integrations with 9Router. Open source and free to start.
+            </p>
+            <div className="flex flex-col sm:flex-row items-center justify-center gap-4">
+              <button 
+                onClick={() => router.push("/dashboard")}
+                className="w-full sm:w-auto h-14 px-10 rounded-lg bg-[#f97815] hover:bg-[#e0650a] text-[#181411] text-lg font-bold transition-all shadow-[0_0_20px_rgba(249,120,21,0.5)]"
+              >
+                Start Free
+              </button>
+              <button 
+                onClick={() => window.open("https://github.com/decolua/9router#readme", "_blank")}
+                className="w-full sm:w-auto h-14 px-10 rounded-lg border border-[#3a2f27] hover:bg-[#23180f] text-white text-lg font-bold transition-all"
+              >
+                Read Documentation
+              </button>
+            </div>
+          </div>
+        </section>
+        </main>
+        
+        <Footer />
+      </div>
+      
+      {/* Global styles for keyframes */}
+      <style jsx global>{`
+        @keyframes float {
+          0%, 100% { transform: translateY(0); }
+          50% { transform: translateY(-10px); }
+        }
+        @keyframes dash {
+          to { stroke-dashoffset: -20; }
+        }
+        @keyframes blob {
+          0%, 100% { 
+            transform: translate(0, 0) scale(1);
+          }
+          33% { 
+            transform: translate(30px, -50px) scale(1.1);
+          }
+          66% { 
+            transform: translate(-20px, 20px) scale(0.9);
+          }
+        }
+        .animate-blob {
+          animation: blob 20s ease-in-out infinite;
+        }
+      `}</style>
+    </div>
+  );
+}
+
diff --git a/src/app/layout.js b/src/app/layout.js
new file mode 100644
index 0000000..5ea6c11
--- /dev/null
+++ b/src/app/layout.js
@@ -0,0 +1,51 @@
+import { Inter } from "next/font/google";
+import { GoogleAnalytics } from "@next/third-parties/google";
+import "material-symbols/outlined.css";
+import "./globals.css";
+import { ThemeProvider } from "@/shared/components/ThemeProvider";
+import "@/lib/network/initOutboundProxy"; // Auto-initialize outbound proxy env
+import "@/shared/services/bootstrap"; // Auto-run initializeApp (watchdog, auto-resume tunnel)
+import { initConsoleLogCapture } from "@/lib/consoleLogBuffer";
+import { RuntimeI18nProvider } from "@/i18n/RuntimeI18nProvider";
+
+// Hook console immediately at module load time (server-side only, runs once)
+initConsoleLogCapture();
+
+const inter = Inter({
+  subsets: ["latin"],
+  variable: "--font-inter",
+});
+
+export const metadata = {
+  title: "9Router - AI Infrastructure Management",
+  description: "One endpoint for all your AI providers. Manage keys, monitor usage, and scale effortlessly.",
+  icons: {
+    icon: "/favicon.svg",
+  },
+};
+
+export const viewport = {
+  themeColor: "#0a0a0a",
+};
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `if(document.fonts&&document.fonts.ready){document.fonts.ready.then(function(){document.documentElement.classList.add('fonts-loaded')})}else{document.documentElement.classList.add('fonts-loaded')}`,
+          }}
+        />
+      </head>
+      <body className={`${inter.variable} font-sans antialiased`}>
+        <ThemeProvider>
+          <RuntimeI18nProvider>
+            {children}
+          </RuntimeI18nProvider>
+        </ThemeProvider>
+        <GoogleAnalytics gaId={"G-LC959F603F"} />
+      </body>
+    </html>
+  );
+}
diff --git a/src/app/login/page.js b/src/app/login/page.js
new file mode 100644
index 0000000..8e50a19
--- /dev/null
+++ b/src/app/login/page.js
@@ -0,0 +1,247 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Card, Button, Input } from "@/shared/components";
+
+export default function LoginPage() {
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState("");
+  const [resetHint, setResetHint] = useState("");
+  const [retryAfter, setRetryAfter] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [hasPassword, setHasPassword] = useState(null);
+  const [authMode, setAuthMode] = useState("password");
+  const [oidcConfigured, setOidcConfigured] = useState(false);
+  const [oidcLoginLabel, setOidcLoginLabel] = useState("Sign in with OIDC");
+  const [mustChange, setMustChange] = useState(false);
+  const [newPassword, setNewPassword] = useState("");
+
+  // Countdown for rate-limit
+  useEffect(() => {
+    if (retryAfter <= 0) return;
+    const id = setInterval(() => setRetryAfter((s) => (s > 0 ? s - 1 : 0)), 1000);
+    return () => clearInterval(id);
+  }, [retryAfter]);
+
+  useEffect(() => {
+    async function checkAuth() {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 5000);
+      const baseUrl = typeof window !== "undefined" ? window.location.origin : "";
+
+      try {
+        const res = await fetch(`${baseUrl}/api/auth/status`, {
+          signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+
+        if (res.ok) {
+          const data = await res.json();
+          if (data.requireLogin === false) {
+            window.location.assign("/dashboard");
+            return;
+          }
+          setHasPassword(!!data.hasPassword);
+          setAuthMode(data.authMode || "password");
+          setOidcConfigured(data.oidcConfigured === true);
+          setOidcLoginLabel(data.oidcLoginLabel || "Sign in with OIDC");
+        } else {
+          // Safe fallback on non-OK response to avoid infinite loading state.
+          setHasPassword(true);
+        }
+      } catch (err) {
+        clearTimeout(timeoutId);
+        setHasPassword(true);
+      }
+    }
+    checkAuth();
+  }, []);
+
+  const handleLogin = async (e) => {
+    e.preventDefault();
+    setLoading(true);
+    setError("");
+    setResetHint("");
+
+    try {
+      const res = await fetch("/api/auth/login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ password }),
+      });
+
+      if (res.ok) {
+        const data = await res.json();
+        if (data.mustChangePassword) {
+          setMustChange(true);
+          return;
+        }
+        window.location.assign("/dashboard");
+      } else {
+        const data = await res.json();
+        setError(data.error || "Invalid password");
+        if (data.resetHint) setResetHint(data.resetHint);
+        if (data.retryAfter) setRetryAfter(Number(data.retryAfter));
+      }
+    } catch (err) {
+      setError("An error occurred. Please try again.");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // Force a new password before entering the dashboard (default + remote).
+  const handleSetNewPassword = async (e) => {
+    e.preventDefault();
+    setLoading(true);
+    setError("");
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ currentPassword: password, newPassword }),
+      });
+      if (res.ok) {
+        window.location.assign("/dashboard");
+      } else {
+        const data = await res.json();
+        setError(data.error || "Failed to set password");
+      }
+    } catch (err) {
+      setError("An error occurred. Please try again.");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleOidcLogin = () => {
+    window.location.href = "/api/auth/oidc/start";
+  };
+
+  const oidcAvailable = oidcConfigured && ["oidc", "both"].includes(authMode);
+  const passwordAvailable = authMode !== "oidc" || !oidcConfigured;
+
+  // Show loading state while checking password
+  if (hasPassword === null) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-bg p-4">
+        <div className="text-center">
+          <div className="inline-block animate-spin rounded-full h-8 w-8 border-b-2 border-primary"></div>
+          <p className="text-text-muted mt-4">Loading...</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-bg p-4 relative overflow-hidden">
+      {/* Faint grid background */}
+      <div className="landing-grid absolute inset-0 pointer-events-none" aria-hidden="true" />
+      <div className="relative z-10 w-full max-w-md">
+        <div className="text-center mb-8">
+          <h1 className="text-3xl font-bold text-primary mb-2">9Router</h1>
+          <p className="text-text-muted">
+            {authMode === "oidc" && oidcConfigured
+              ? "Sign in with your OIDC provider to access the dashboard"
+              : "Enter your password to access the dashboard"}
+          </p>
+        </div>
+
+        <Card>
+          {mustChange ? (
+            <form onSubmit={handleSetNewPassword} className="flex flex-col gap-4">
+              <p className="text-sm text-amber-600 dark:text-amber-400 text-center">
+                Set a new password before accessing the dashboard remotely.
+              </p>
+              <div className="flex flex-col gap-2">
+                <label className="text-sm font-medium">New password</label>
+                <Input
+                  type="password"
+                  placeholder="Enter new password"
+                  value={newPassword}
+                  onChange={(e) => setNewPassword(e.target.value)}
+                  required
+                  autoFocus
+                />
+                {error && <p className="text-xs text-red-500">{error}</p>}
+              </div>
+              <Button type="submit" variant="primary" className="w-full" loading={loading} disabled={!newPassword}>
+                Set password
+              </Button>
+            </form>
+          ) : (
+          <div className="flex flex-col gap-4">
+            {oidcAvailable && (
+              <Button type="button" variant="primary" className="w-full" onClick={handleOidcLogin}>
+                {oidcLoginLabel}
+              </Button>
+            )}
+
+            {oidcAvailable && passwordAvailable && <div className="h-px bg-border/60" />}
+
+            {passwordAvailable ? (
+              <form onSubmit={handleLogin} className="flex flex-col gap-4">
+                {((authMode === "oidc" && !oidcConfigured) || (authMode === "both" && !oidcConfigured)) && (
+                  <p className="text-xs text-amber-600 dark:text-amber-400 text-center">
+                    OIDC login is enabled, but the issuer/client fields are not configured yet. Password login is still available for recovery.
+                  </p>
+                )}
+
+                {authMode === "both" && oidcConfigured && (
+                  <p className="text-xs text-text-muted text-center">
+                    Password and OIDC login are both enabled.
+                  </p>
+                )}
+
+                <div className="flex flex-col gap-2">
+                  <label className="text-sm font-medium">Password</label>
+                  <Input
+                    type="password"
+                    placeholder="Enter password"
+                    value={password}
+                    onChange={(e) => setPassword(e.target.value)}
+                    required
+                    autoFocus={!oidcAvailable}
+                  />
+                  {error && <p className="text-xs text-red-500">{error}</p>}
+                  {retryAfter > 0 && (
+                    <p className="text-xs text-amber-600 dark:text-amber-400">
+                      Locked. Retry in <span className="font-mono">{retryAfter}s</span>.
+                    </p>
+                  )}
+                  {resetHint && (
+                    <p className="text-xs text-text-muted">
+                      Forgot password? Open <code className="bg-sidebar px-1 rounded">9router</code> CLI on the host → <b>Settings</b> → <b>Reset Password to Default</b>.
+                    </p>
+                  )}
+                </div>
+
+                <Button
+                  type="submit"
+                  variant="primary"
+                  className="w-full"
+                  loading={loading}
+                  disabled={retryAfter > 0}
+                >
+                  {retryAfter > 0 ? `Wait ${retryAfter}s` : "Login"}
+                </Button>
+
+                <p className="text-xs text-center text-text-muted mt-2">
+                  Default password is <code className="bg-sidebar px-1 rounded">123456</code>
+                </p>
+                {hasPassword === false && (
+                  <p className="text-xs text-center text-amber-600 dark:text-amber-400">
+                    Security risk: no password set. You will be asked to set one when logging in remotely.
+                  </p>
+                )}
+              </form>
+            ) : (
+              error && <p className="text-xs text-red-500">{error}</p>
+            )}
+          </div>
+          )}
+        </Card>
+      </div>
+    </div>
+  );
+}
diff --git a/src/app/manifest.js b/src/app/manifest.js
new file mode 100644
index 0000000..6ad46da
--- /dev/null
+++ b/src/app/manifest.js
@@ -0,0 +1,30 @@
+export default function manifest() {
+  return {
+    name: '9Router - AI Infrastructure Management',
+    short_name: '9Router',
+    description: 'One endpoint for all your AI providers. Manage keys, monitor usage, and scale effortlessly.',
+    start_url: '/',
+    display: 'standalone',
+    background_color: '#0a0a0a',
+    theme_color: '#0a0a0a',
+    orientation: 'portrait-primary',
+    icons: [
+      {
+        src: '/icons/icon-192.svg',
+        sizes: '192x192',
+        type: 'image/svg+xml',
+      },
+      {
+        src: '/icons/icon-512.svg',
+        sizes: '512x512',
+        type: 'image/svg+xml',
+      },
+      {
+        src: '/icons/icon-512.svg',
+        sizes: '512x512',
+        type: 'image/svg+xml',
+        purpose: 'maskable',
+      },
+    ],
+  }
+}
diff --git a/src/app/page.js b/src/app/page.js
new file mode 100644
index 0000000..9654779
--- /dev/null
+++ b/src/app/page.js
@@ -0,0 +1,5 @@
+import { redirect } from "next/navigation";
+
+export default function InitPage() {
+  redirect('/dashboard');
+}
diff --git a/src/dashboardGuard.js b/src/dashboardGuard.js
new file mode 100644
index 0000000..3f90c4f
--- /dev/null
+++ b/src/dashboardGuard.js
@@ -0,0 +1,260 @@
+import { NextResponse } from "next/server";
+import { getSettings, validateApiKey } from "@/lib/localDb";
+import { getConsistentMachineId } from "@/shared/utils/machineId";
+import { verifyDashboardAuthToken } from "@/lib/auth/dashboardSession";
+
+const CLI_TOKEN_HEADER = "x-9r-cli-token";
+const CLI_TOKEN_SALT = "9r-cli-auth";
+
+let cachedCliToken = null;
+async function getCliToken() {
+  if (!cachedCliToken) cachedCliToken = await getConsistentMachineId(CLI_TOKEN_SALT);
+  return cachedCliToken;
+}
+
+async function hasValidCliToken(request) {
+  const token = request.headers.get(CLI_TOKEN_HEADER);
+  if (!token) return false;
+  return token === await getCliToken();
+}
+
+// Public API paths — no auth required (LLM API has its own key auth inside handler).
+const PUBLIC_API_PATHS = [
+  "/api/health",
+  "/api/init",
+  "/api/locale",
+  "/api/auth/login",
+  "/api/auth/logout",
+  "/api/auth/status",
+  "/api/auth/oidc",
+  "/api/version",
+  "/api/settings/require-login",
+];
+
+// Public top-level prefixes (LLM API endpoints with their own API key auth).
+const PUBLIC_PREFIXES = ["/v1", "/v1beta", "/api/v1", "/api/v1beta", "/codex"];
+
+// Always require JWT token regardless of requireLogin setting
+const ALWAYS_PROTECTED = [
+  "/api/shutdown",
+  "/api/settings/database",
+  "/api/version/shutdown",
+  "/api/version/update",
+  "/api/oauth/cursor/auto-import",
+  "/api/oauth/kiro/auto-import",
+];
+
+// Require auth, but allow through if requireLogin is disabled
+const PROTECTED_API_PATHS = [
+  "/api/settings",
+  "/api/keys",
+  "/api/providers",
+  "/api/provider-nodes",
+  "/api/proxy-pools",
+  "/api/combos",
+  "/api/models",
+  "/api/usage",
+  "/api/oauth",
+  "/api/cloud",
+  "/api/media-providers",
+  "/api/pricing",
+  "/api/tags",
+  "/api/cli-tools",
+  "/api/mcp",
+  "/api/translator",
+  "/api/tunnel",
+];
+
+// Routes that spawn child processes or read host secrets — restrict to localhost.
+const LOCAL_ONLY_PATHS = [
+  "/api/cli-tools/cowork-settings",
+  "/api/cli-tools/antigravity-mitm",
+  "/api/mcp/",
+  "/api/tunnel/tailscale-install",
+  "/api/tunnel/tailscale-enable",
+  "/api/tunnel/tailscale-disable",
+  "/api/tunnel/tailscale-check",
+  "/api/tunnel/enable",
+  "/api/tunnel/disable",
+  "/api/oauth/cursor/auto-import",
+  "/api/oauth/kiro/auto-import",
+  "/api/auth/reset-password",
+  "/api/headroom/start",
+  "/api/headroom/stop",
+  "/api/headroom/proxy",
+];
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+
+function isLoopbackHostname(h) {
+  if (!h) return false;
+  const name = h.split(":")[0].replace(/^\[|\]$/g, "").toLowerCase();
+  return LOOPBACK_HOSTS.has(name);
+}
+
+export function isLocalRequest(request) {
+  // Stamped by custom-server.js when forwarding headers exist: request came through
+  // a reverse proxy, so the loopback socket is the proxy hop, not the end-user.
+  if (request.headers.get("x-9r-via-proxy")) return false;
+  // Trusted peer IP from TCP socket (custom-server.js); unspoofable. Primary anchor for "local".
+  const realIp = request.headers.get("x-9r-real-ip");
+  if (realIp) {
+    if (!isLoopbackHostname(realIp)) return false;
+  } else if (!isLoopbackHostname(request.headers.get("host"))) {
+    // Fallback for bare server.js (dev) without custom-server: legacy Host-based check.
+    return false;
+  }
+  const origin = request.headers.get("origin");
+  if (origin) {
+    try {
+      if (!isLoopbackHostname(new URL(origin).hostname)) return false;
+    } catch { return false; }
+  }
+  return true;
+}
+
+function isPublicLlmApi(pathname) {
+  return PUBLIC_PREFIXES.some((p) => pathname === p || pathname.startsWith(`${p}/`));
+}
+
+function extractApiKey(request) {
+  const authHeader = request.headers.get("Authorization");
+  if (authHeader?.startsWith("Bearer ")) return authHeader.slice(7);
+  const apiKeyHeader = request.headers.get("x-api-key");
+  if (apiKeyHeader) return apiKeyHeader;
+  const googleApiKeyHeader = request.headers.get("x-goog-api-key");
+  if (googleApiKeyHeader) return googleApiKeyHeader;
+  return request.nextUrl.searchParams?.get("key") || null;
+}
+
+async function hasValidApiKey(request) {
+  const apiKey = extractApiKey(request);
+  if (!apiKey) return false;
+  return await validateApiKey(apiKey);
+}
+
+async function canAccessPublicLlmApi(request) {
+  if (isLocalRequest(request)) return true;
+  if (await hasValidCliToken(request)) return true;
+  return await hasValidApiKey(request);
+}
+
+async function canAccessLocalOnlyRoute(request) {
+  if (await hasValidCliToken(request)) return true;
+  // Browser on host: loopback Host + Origin (blocks tunnel/CSRF) + auth (JWT or requireLogin=false)
+  if (isLocalRequest(request) && await isAuthenticated(request)) return true;
+  return false;
+}
+
+async function hasValidToken(request) {
+  const token = request.cookies.get("auth_token")?.value;
+  return await verifyDashboardAuthToken(token);
+}
+
+// Read settings directly from DB to avoid self-fetch deadlock in proxy
+async function loadSettings() {
+  try {
+    return await getSettings();
+  } catch {
+    return null;
+  }
+}
+
+async function isAuthenticated(request) {
+  if (await hasValidToken(request)) return true;
+  const settings = await loadSettings();
+  if (settings && settings.requireLogin === false) return true;
+  return false;
+}
+
+function isPublicApi(pathname) {
+  if (isPublicLlmApi(pathname)) return true;
+  return PUBLIC_API_PATHS.some((p) => pathname === p || pathname.startsWith(`${p}/`));
+}
+
+export const __test__ = {
+  isLocalRequest,
+  isPublicLlmApi,
+  extractApiKey,
+  canAccessPublicLlmApi,
+  canAccessLocalOnlyRoute,
+};
+
+export async function proxy(request) {
+  const { pathname } = request.nextUrl;
+
+  // Local-only gate for spawn-capable / host-secret routes.
+  if (LOCAL_ONLY_PATHS.some((p) => pathname.startsWith(p))) {
+    if (!(await canAccessLocalOnlyRoute(request))) {
+      return NextResponse.json({ error: "Local only: CLI token required" }, { status: 403 });
+    }
+  }
+
+  // Always protected - require valid JWT or local CLI token (machineId-based)
+  if (ALWAYS_PROTECTED.some((p) => pathname.startsWith(p))) {
+    if (await hasValidCliToken(request) || await hasValidToken(request))
+      return NextResponse.next();
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  if (isPublicLlmApi(pathname)) {
+    if (await canAccessPublicLlmApi(request)) return NextResponse.next();
+    return NextResponse.json({ error: "API key required for remote API access" }, { status: 401 });
+  }
+
+  // Deny-by-default for /api/* — public allow-list bypasses, everything else requires auth.
+  if (pathname.startsWith("/api/")) {
+    if (isPublicApi(pathname)) return NextResponse.next();
+    if (await hasValidCliToken(request) || await isAuthenticated(request))
+      return NextResponse.next();
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  // Protect all dashboard routes
+  if (pathname.startsWith("/dashboard")) {
+    let requireLogin = true;
+    let tunnelDashboardAccess = true;
+
+    try {
+      const settings = await loadSettings();
+      if (settings) {
+        requireLogin = settings.requireLogin !== false;
+        tunnelDashboardAccess = settings.tunnelDashboardAccess === true;
+
+        // Block tunnel/tailscale access if disabled (redirect to login)
+        if (!tunnelDashboardAccess) {
+          const host = (request.headers.get("host") || "").split(":")[0].toLowerCase();
+          const tunnelHost = settings.tunnelUrl ? new URL(settings.tunnelUrl).hostname.toLowerCase() : "";
+          const tailscaleHost = settings.tailscaleUrl ? new URL(settings.tailscaleUrl).hostname.toLowerCase() : "";
+          if ((tunnelHost && host === tunnelHost) || (tailscaleHost && host === tailscaleHost)) {
+            return NextResponse.redirect(new URL("/login", request.url));
+          }
+        }
+      }
+    } catch {
+      // On error, keep defaults (require login, block tunnel)
+    }
+
+    // If login not required, allow through
+    if (!requireLogin) return NextResponse.next();
+
+    // Verify JWT token
+    const token = request.cookies.get("auth_token")?.value;
+    if (token) {
+      if (await verifyDashboardAuthToken(token)) {
+        return NextResponse.next();
+      } else {
+        return NextResponse.redirect(new URL("/login", request.url));
+      }
+    }
+
+    return NextResponse.redirect(new URL("/login", request.url));
+  }
+
+  // Redirect / to /dashboard if logged in, or /dashboard if it's the root
+  if (pathname === "/") {
+    return NextResponse.redirect(new URL("/dashboard", request.url));
+  }
+
+  return NextResponse.next();
+}
diff --git a/src/i18n/RuntimeI18nProvider.js b/src/i18n/RuntimeI18nProvider.js
new file mode 100644
index 0000000..58ae47a
--- /dev/null
+++ b/src/i18n/RuntimeI18nProvider.js
@@ -0,0 +1,27 @@
+"use client";
+
+import { useEffect } from "react";
+import { usePathname } from "next/navigation";
+import { initRuntimeI18n, reloadTranslations } from "./runtime";
+
+export function RuntimeI18nProvider({ children }) {
+  const pathname = usePathname();
+
+  useEffect(() => {
+    initRuntimeI18n();
+  }, []);
+
+  // Re-process DOM when route changes
+  useEffect(() => {
+    if (pathname) {
+      // Double RAF to ensure React has committed changes to DOM
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          reloadTranslations();
+        });
+      });
+    }
+  }, [pathname]);
+
+  return <>{children}</>;
+}
diff --git a/src/i18n/config.js b/src/i18n/config.js
new file mode 100644
index 0000000..ef6d41c
--- /dev/null
+++ b/src/i18n/config.js
@@ -0,0 +1,185 @@
+export const LOCALES = [
+  "en",
+  "vi",
+  "zh-CN",
+  "zh-TW",
+  "ja",
+  "pt-BR",
+  "pt-PT",
+  "ko",
+  "es",
+  "de",
+  "fr",
+  "he",
+  "ar",
+  "ru",
+  "pl",
+  "cs",
+  "nl",
+  "tr",
+  "uk",
+  "tl",
+  "id",
+  "th",
+  "hi",
+  "bn",
+  "ur",
+  "ro",
+  "sv",
+  "it",
+  "el",
+  "hu",
+  "fi",
+  "da",
+  "no",
+  "fa",
+];
+export const DEFAULT_LOCALE = "en";
+export const LOCALE_COOKIE = "locale";
+
+export const LOCALE_NAMES = {
+  en: "English",
+  vi: "Tiếng Việt",
+  "zh-CN": "简体中文",
+  "zh-TW": "繁體中文",
+  ja: "日本語",
+  "pt-BR": "Português (Brasil)",
+  "pt-PT": "Português (Portugal)",
+  ko: "한국어",
+  es: "Español",
+  de: "Deutsch",
+  fr: "Français",
+  he: "עברית",
+  ar: "العربية",
+  ru: "Русский",
+  pl: "Polski",
+  cs: "Čeština",
+  nl: "Nederlands",
+  tr: "Türkçe",
+  uk: "Українська",
+  tl: "Tagalog",
+  id: "Indonesia",
+  th: "ไทย",
+  hi: "हिन्दी",
+  bn: "বাংলা",
+  ur: "اردو",
+  ro: "Română",
+  sv: "Svenska",
+  it: "Italiano",
+  el: "Ελληνικά",
+  hu: "Magyar",
+  fi: "Suomi",
+  da: "Dansk",
+  no: "Norsk",
+  fa: "فارسی",
+};
+
+export function normalizeLocale(locale) {
+  if (locale === "zh" || locale === "zh-CN") {
+    return "zh-CN";
+  }
+  if (locale === "en") {
+    return "en";
+  }
+  if (locale === "vi") {
+    return "vi";
+  }
+  if (locale === "zh-TW") {
+    return "zh-TW";
+  }
+  if (locale === "ja") {
+    return "ja";
+  }
+  if (locale === "pt-BR") {
+    return "pt-BR";
+  }
+  if (locale === "pt-PT") {
+    return "pt-PT";
+  }
+  if (locale === "ko") {
+    return "ko";
+  }
+  if (locale === "es") {
+    return "es";
+  }
+  if (locale === "de") {
+    return "de";
+  }
+  if (locale === "fr") {
+    return "fr";
+  }
+  if (locale === "he") {
+    return "he";
+  }
+  if (locale === "ar") {
+    return "ar";
+  }
+  if (locale === "ru") {
+    return "ru";
+  }
+  if (locale === "pl") {
+    return "pl";
+  }
+  if (locale === "cs") {
+    return "cs";
+  }
+  if (locale === "nl") {
+    return "nl";
+  }
+  if (locale === "tr") {
+    return "tr";
+  }
+  if (locale === "uk") {
+    return "uk";
+  }
+  if (locale === "tl") {
+    return "tl";
+  }
+  if (locale === "id") {
+    return "id";
+  }
+  if (locale === "th") {
+    return "th";
+  }
+  if (locale === "hi") {
+    return "hi";
+  }
+  if (locale === "bn") {
+    return "bn";
+  }
+  if (locale === "ur") {
+    return "ur";
+  }
+  if (locale === "ro") {
+    return "ro";
+  }
+  if (locale === "sv") {
+    return "sv";
+  }
+  if (locale === "it") {
+    return "it";
+  }
+  if (locale === "el") {
+    return "el";
+  }
+  if (locale === "hu") {
+    return "hu";
+  }
+  if (locale === "fi") {
+    return "fi";
+  }
+  if (locale === "da") {
+    return "da";
+  }
+  if (locale === "no") {
+    return "no";
+  }
+  if (locale === "fa") {
+    return "fa";
+  }
+  return DEFAULT_LOCALE;
+}
+
+export function isSupportedLocale(locale) {
+  return LOCALES.includes(locale);
+}
diff --git a/src/i18n/runtime.js b/src/i18n/runtime.js
new file mode 100644
index 0000000..fef9332
--- /dev/null
+++ b/src/i18n/runtime.js
@@ -0,0 +1,162 @@
+"use client";
+
+import { DEFAULT_LOCALE, LOCALE_COOKIE, normalizeLocale } from "./config";
+
+let translationMap = {};
+let currentLocale = DEFAULT_LOCALE;
+let reloadCallbacks = [];
+
+// Read locale from cookie
+function getLocaleFromCookie() {
+  if (typeof document === "undefined") return DEFAULT_LOCALE;
+  const cookie = document.cookie
+    .split(";")
+    .find((c) => c.trim().startsWith(`${LOCALE_COOKIE}=`));
+  const value = cookie ? decodeURIComponent(cookie.split("=")[1]) : DEFAULT_LOCALE;
+  return normalizeLocale(value);
+}
+
+// Load translation map
+async function loadTranslations(locale) {
+  if (locale === "en") {
+    translationMap = {};
+    return;
+  }
+  
+  try {
+    const response = await fetch(`/i18n/literals/${locale}.json`);
+    translationMap = await response.json();
+  } catch (err) {
+    console.error("Failed to load translations:", err);
+    translationMap = {};
+  }
+}
+
+// Translate text - exported for use in components
+export function translate(text) {
+  if (!text || typeof text !== "string") return text;
+  const trimmed = text.trim();
+  if (!trimmed) return text;
+  if (currentLocale === "en") return text;
+  return translationMap[trimmed] || text;
+}
+
+// Get current locale - exported for use in components
+export function getCurrentLocale() {
+  return currentLocale;
+}
+
+// Register callback for locale changes
+export function onLocaleChange(callback) {
+  reloadCallbacks.push(callback);
+  return () => {
+    reloadCallbacks = reloadCallbacks.filter(cb => cb !== callback);
+  };
+}
+
+// Process text node
+function processTextNode(node) {
+  if (!node.nodeValue || !node.nodeValue.trim()) return;
+  
+  // Skip if parent is script, style, code, or structural elements
+  const parent = node.parentElement;
+  if (!parent) return;
+  
+  // Skip if parent or any ancestor has data-i18n-skip attribute
+  let element = parent;
+  while (element) {
+    if (element.hasAttribute && element.hasAttribute('data-i18n-skip')) {
+      return;
+    }
+    element = element.parentElement;
+  }
+  
+  const tagName = parent.tagName?.toLowerCase();
+  
+  // Skip elements that don't allow text nodes
+  const skipTags = [
+    "script", "style", "code", "pre",
+    "colgroup", "table", "thead", "tbody", "tfoot", "tr",
+    "select", "datalist", "optgroup"
+  ];
+  
+  if (skipTags.includes(tagName)) return;
+  
+  // Store original text if not already stored
+  if (!node._originalText) {
+    node._originalText = node.nodeValue;
+  }
+  
+  // Use original text for translation
+  const original = node._originalText;
+  const translated = translate(original);
+  
+  // Only update if different to avoid unnecessary DOM mutations
+  if (translated !== node.nodeValue) {
+    node.nodeValue = translated;
+  }
+}
+
+// Process all text nodes in element
+function processElement(element) {
+  if (!element) return;
+  
+  const walker = document.createTreeWalker(
+    element,
+    NodeFilter.SHOW_TEXT,
+    null,
+    false
+  );
+  
+  let node;
+  const nodesToProcess = [];
+  
+  // Collect all nodes first to avoid live collection issues
+  while ((node = walker.nextNode())) {
+    nodesToProcess.push(node);
+  }
+  
+  // Process collected nodes
+  nodesToProcess.forEach(processTextNode);
+}
+
+// Initialize runtime i18n
+export async function initRuntimeI18n() {
+  if (typeof window === "undefined") return;
+  
+  currentLocale = getLocaleFromCookie();
+  await loadTranslations(currentLocale);
+  
+  // Process existing DOM
+  processElement(document.body);
+  
+  // Watch for new nodes
+  const observer = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      mutation.addedNodes.forEach((node) => {
+        if (node.nodeType === Node.ELEMENT_NODE) {
+          processElement(node);
+        } else if (node.nodeType === Node.TEXT_NODE) {
+          processTextNode(node);
+        }
+      });
+    });
+  });
+  
+  observer.observe(document.body, {
+    childList: true,
+    subtree: true,
+  });
+}
+
+// Reload translations when locale changes
+export async function reloadTranslations() {
+  currentLocale = getLocaleFromCookie();
+  await loadTranslations(currentLocale);
+  
+  // Notify all registered callbacks
+  reloadCallbacks.forEach(callback => callback());
+  
+  // Re-process entire DOM (will use stored original text)
+  processElement(document.body);
+}
diff --git a/src/lib/appUpdater.js b/src/lib/appUpdater.js
new file mode 100644
index 0000000..e1e270c
--- /dev/null
+++ b/src/lib/appUpdater.js
@@ -0,0 +1,200 @@
+import { spawn, execSync } from "child_process";
+import path from "path";
+import fs from "fs";
+import os from "os";
+import { UPDATER_CONFIG } from "@/shared/constants/config";
+
+const KILL_TIMEOUT_MS = 5000;
+const PROCESS_WAIT_MS = 1500;
+
+// Kill MITM server by PID file (MITM may run as admin/sudo)
+function killMitmByPidFile() {
+  try {
+    const mitmPidFile = path.join(
+      process.platform === "win32"
+        ? path.join(process.env.APPDATA || "", "9router")
+        : path.join(os.homedir(), ".9router"),
+      "mitm",
+      ".mitm.pid"
+    );
+    if (!fs.existsSync(mitmPidFile)) return;
+    const pid = parseInt(fs.readFileSync(mitmPidFile, "utf8").trim(), 10);
+    if (!pid) return;
+
+    if (process.platform === "win32") {
+      // taskkill first (works if same user); fallback to PowerShell Stop-Process which can kill admin process if our token allows
+      try { execSync(`taskkill /F /T /PID ${pid}`, { stdio: "ignore", windowsHide: true, timeout: 3000 }); } catch {
+        try { execSync(`powershell -NonInteractive -WindowStyle Hidden -Command "Stop-Process -Id ${pid} -Force"`, { stdio: "ignore", windowsHide: true, timeout: 3000 }); } catch { /* best effort */ }
+      }
+    } else {
+      try {
+        execSync(`sudo -n kill -9 ${pid} 2>/dev/null`, { stdio: "ignore", timeout: 3000 });
+      } catch {
+        try { process.kill(pid, "SIGKILL"); } catch { /* best effort */ }
+      }
+    }
+    try { fs.unlinkSync(mitmPidFile); } catch { /* best effort */ }
+  } catch { /* best effort */ }
+}
+
+// Collect PIDs of all 9router-related processes (excluding current)
+function collectAppPids() {
+  const pids = [];
+  const platform = process.platform;
+
+  if (platform === "win32") {
+    try {
+      const psCmd = `powershell -NonInteractive -WindowStyle Hidden -Command "Get-WmiObject Win32_Process -Filter 'Name=\\"node.exe\\"' | Select-Object ProcessId,CommandLine | ConvertTo-Csv -NoTypeInformation"`;
+      const output = execSync(psCmd, { encoding: "utf8", windowsHide: true, timeout: KILL_TIMEOUT_MS });
+      const lines = output.split("\n").slice(1).filter(l => l.trim());
+      lines.forEach(line => {
+        const lower = line.toLowerCase();
+        // Match anything running from 9router install dir or wrapper cli.js
+        const isAppProcess = lower.includes("9router") ||
+          lower.includes("next-server") ||
+          lower.includes("\\bin\\app\\") ||
+          lower.includes("/bin/app/") ||
+          lower.includes("cli.js");
+        if (isAppProcess) {
+          const match = line.match(/^"(\d+)"/);
+          if (match && match[1] && match[1] !== process.pid.toString()) pids.push(match[1]);
+        }
+      });
+    } catch { /* no processes */ }
+
+    // Kill cloudflared + tray binaries (hold app dir lock)
+    for (const procName of ["cloudflared", "tray_windows_release"]) {
+      try {
+        const cmd = `powershell -NonInteractive -WindowStyle Hidden -Command "Get-Process ${procName} -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Id"`;
+        const out = execSync(cmd, { encoding: "utf8", windowsHide: true, timeout: KILL_TIMEOUT_MS });
+        out.split("\n").forEach(l => {
+          const pid = l.trim();
+          if (pid && !isNaN(pid)) pids.push(pid);
+        });
+      } catch { /* not running */ }
+    }
+  } else {
+    try {
+      const output = execSync("ps aux 2>/dev/null", { encoding: "utf8", timeout: KILL_TIMEOUT_MS });
+      output.split("\n").forEach(line => {
+        const isAppProcess = line.includes("9router") ||
+          line.includes("next-server") ||
+          line.includes("cloudflared") ||
+          line.includes("/bin/app/") ||
+          line.includes("tray_darwin") ||
+          line.includes("tray_linux");
+        if (isAppProcess) {
+          const parts = line.trim().split(/\s+/);
+          const pid = parts[1];
+          if (pid && !isNaN(pid) && pid !== process.pid.toString()) pids.push(pid);
+        }
+      });
+    } catch { /* no processes */ }
+  }
+
+  return pids;
+}
+
+// Copy updater.js into DATA_DIR so npm -g can overwrite node_modules safely
+function getDataDir() {
+  if (process.env.DATA_DIR) return process.env.DATA_DIR;
+  if (process.platform === "win32") {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "9router");
+  }
+  return path.join(os.homedir(), ".9router");
+}
+
+function resolveBundledUpdaterPath() {
+  if (process.env.UPDATER_SCRIPT_PATH && fs.existsSync(process.env.UPDATER_SCRIPT_PATH)) {
+    return process.env.UPDATER_SCRIPT_PATH;
+  }
+  // Production standalone: cwd is binAppDir (see bin/cli.js)
+  // Dev: cwd is app/
+  const fromCwd = path.join(process.cwd(), "src", "lib", "updater", "updater.js");
+  if (fs.existsSync(fromCwd)) return fromCwd;
+  const fromParent = path.join(process.cwd(), "..", "src", "lib", "updater", "updater.js");
+  if (fs.existsSync(fromParent)) return fromParent;
+  return fromCwd;
+}
+
+function ensureRuntimeUpdater(bundledPath) {
+  try {
+    if (!bundledPath || !fs.existsSync(bundledPath)) return bundledPath;
+    const runtimeDir = path.join(getDataDir(), "runtime", "updater");
+    const runtimePath = path.join(runtimeDir, "updater.js");
+    if (fs.existsSync(runtimePath)) {
+      try {
+        if (fs.statSync(bundledPath).size === fs.statSync(runtimePath).size) return runtimePath;
+      } catch { /* recopy */ }
+    }
+    fs.mkdirSync(runtimeDir, { recursive: true });
+    fs.copyFileSync(bundledPath, runtimePath);
+    return runtimePath;
+  } catch {
+    return bundledPath;
+  }
+}
+
+// Kill all app-related processes to release file locks (esp. on Windows)
+export async function killAppProcesses() {
+  killMitmByPidFile();
+  const pids = collectAppPids();
+  const platform = process.platform;
+
+  pids.forEach(pid => {
+    try {
+      if (platform === "win32") {
+        execSync(`taskkill /F /PID ${pid} 2>nul`, { stdio: "ignore", shell: true, windowsHide: true, timeout: 3000 });
+      } else {
+        execSync(`kill -9 ${pid} 2>/dev/null`, { stdio: "ignore", timeout: 3000 });
+      }
+    } catch { /* already dead */ }
+  });
+
+  if (pids.length > 0) {
+    await new Promise(r => setTimeout(r, PROCESS_WAIT_MS));
+  }
+}
+
+// Resolve npx/9router binary to relaunch after update (cross-platform)
+function resolveRelaunchCommand() {
+  const isWin = process.platform === "win32";
+  // Prefer `npx 9router` — works regardless of global bin path changes after npm i -g
+  const npx = isWin ? "npx.cmd" : "npx";
+  return { cmd: npx, args: [UPDATER_CONFIG.npmPackageName] };
+}
+
+// Spawn detached headless updater (Node process) then exit current server
+export function spawnUpdaterAndExit(packageName = UPDATER_CONFIG.npmPackageName) {
+  const updaterPath = ensureRuntimeUpdater(resolveBundledUpdaterPath());
+  const isTray = process.env.TRAY_MODE === "1";
+  const relaunch = resolveRelaunchCommand();
+  // Relaunch matching original env: tray stays tray, foreground stays foreground
+  const relaunchArgs = isTray
+    ? [...relaunch.args, "--tray", "--skip-update"]
+    : [...relaunch.args, "--skip-update"];
+
+  spawn(process.execPath, [updaterPath], {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env: {
+      ...process.env,
+      UPDATER_PKG_NAME: packageName,
+      UPDATER_PORT: String(UPDATER_CONFIG.statusPort),
+      UPDATER_TAIL_LINES: String(UPDATER_CONFIG.statusLogTailLines),
+      UPDATER_RETRIES: String(UPDATER_CONFIG.installRetries),
+      UPDATER_RETRY_DELAY_MS: String(UPDATER_CONFIG.installRetryDelayMs),
+      UPDATER_LINGER_MS: String(UPDATER_CONFIG.lingerAfterDoneMs),
+      UPDATER_WAIT_MIN_MS: String(UPDATER_CONFIG.waitForExitMinMs),
+      UPDATER_WAIT_MAX_MS: String(UPDATER_CONFIG.waitForExitMaxMs),
+      UPDATER_WAIT_CHECK_MS: String(UPDATER_CONFIG.waitForExitCheckMs),
+      UPDATER_APP_PORT: String(UPDATER_CONFIG.appPort),
+      UPDATER_RELAUNCH: "1",
+      UPDATER_RELAUNCH_CMD: relaunch.cmd,
+      UPDATER_RELAUNCH_ARGS: JSON.stringify(relaunchArgs),
+    },
+  }).unref();
+
+  setTimeout(() => process.exit(0), UPDATER_CONFIG.exitDelayMs);
+}
diff --git a/src/lib/auth/dashboardSession.js b/src/lib/auth/dashboardSession.js
new file mode 100644
index 0000000..b4c65aa
--- /dev/null
+++ b/src/lib/auth/dashboardSession.js
@@ -0,0 +1,82 @@
+import { SignJWT, jwtVerify } from "jose";
+import bcrypt from "bcryptjs";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { DATA_DIR } from "@/lib/dataDir";
+import { getSettings } from "@/lib/localDb";
+
+const DEFAULT_PASSWORD = "123456";
+
+function loadJwtSecret() {
+  if (process.env.JWT_SECRET) return process.env.JWT_SECRET;
+  const file = path.join(DATA_DIR, "jwt-secret");
+  try {
+    return fs.readFileSync(file, "utf8").trim();
+  } catch {}
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  const generated = crypto.randomBytes(32).toString("hex");
+  fs.writeFileSync(file, generated, { mode: 0o600 });
+  return generated;
+}
+
+const SECRET = new TextEncoder().encode(loadJwtSecret());
+
+export function shouldUseSecureCookie(request) {
+  const forceSecureCookie = process.env.AUTH_COOKIE_SECURE === "true";
+  const forwardedProto = request?.headers?.get?.("x-forwarded-proto");
+  const isHttpsRequest = forwardedProto === "https";
+  return forceSecureCookie || isHttpsRequest;
+}
+
+export async function createDashboardAuthToken(claims = {}) {
+  return new SignJWT({ authenticated: true, ...claims })
+    .setProtectedHeader({ alg: "HS256" })
+    .setIssuedAt()
+    .setExpirationTime("24h")
+    .sign(SECRET);
+}
+
+export async function verifyDashboardAuthToken(token) {
+  if (!token) return false;
+  try {
+    await jwtVerify(token, SECRET);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function getDashboardAuthSession(token) {
+  if (!token) return null;
+  try {
+    const { payload } = await jwtVerify(token, SECRET);
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+export async function setDashboardAuthCookie(cookieStore, request, claims = {}) {
+  const token = await createDashboardAuthToken(claims);
+  cookieStore.set("auth_token", token, {
+    httpOnly: true,
+    secure: shouldUseSecureCookie(request),
+    sameSite: "lax",
+    path: "/",
+  });
+}
+
+export function clearDashboardAuthCookie(cookieStore) {
+  cookieStore.delete("auth_token");
+}
+
+// Verify the current dashboard password (re-auth for sensitive actions).
+export async function verifyDashboardPassword(password) {
+  if (typeof password !== "string" || !password) return false;
+  const settings = await getSettings();
+  const storedHash = settings?.password;
+  if (storedHash) return bcrypt.compare(password, storedHash);
+  const initialPassword = process.env.INITIAL_PASSWORD || DEFAULT_PASSWORD;
+  return password === initialPassword;
+}
diff --git a/src/lib/auth/loginLimiter.js b/src/lib/auth/loginLimiter.js
new file mode 100644
index 0000000..43dec55
--- /dev/null
+++ b/src/lib/auth/loginLimiter.js
@@ -0,0 +1,60 @@
+// In-memory progressive lockout for dashboard login. Resets on process restart.
+
+const MAX_FAILS_BEFORE_LOCK = 5;
+const LOCK_STEPS_MS = [30_000, 120_000, 600_000, 1_800_000]; // 30s, 2m, 10m, 30m
+const FAIL_WINDOW_MS = 60 * 60 * 1000; // 1h since last fail → auto reset
+
+const attempts = new Map(); // ip → { fails, lockUntil, lockLevel, lastFailAt }
+
+function now() { return Date.now(); }
+
+function getEntry(ip) {
+  const e = attempts.get(ip);
+  if (!e) return null;
+  // Auto reset if window expired and not currently locked
+  if (e.lastFailAt && now() - e.lastFailAt > FAIL_WINDOW_MS && (!e.lockUntil || now() >= e.lockUntil)) {
+    attempts.delete(ip);
+    return null;
+  }
+  return e;
+}
+
+export function checkLock(ip) {
+  const e = getEntry(ip);
+  if (!e || !e.lockUntil) return { locked: false };
+  const remaining = e.lockUntil - now();
+  if (remaining <= 0) return { locked: false };
+  return { locked: true, retryAfter: Math.ceil(remaining / 1000) };
+}
+
+export function recordFail(ip) {
+  const e = getEntry(ip) || { fails: 0, lockUntil: 0, lockLevel: 0, lastFailAt: 0 };
+  e.fails += 1;
+  e.lastFailAt = now();
+  if (e.fails >= MAX_FAILS_BEFORE_LOCK) {
+    const step = LOCK_STEPS_MS[Math.min(e.lockLevel, LOCK_STEPS_MS.length - 1)];
+    e.lockUntil = now() + step;
+    e.lockLevel += 1;
+    e.fails = 0;
+  }
+  attempts.set(ip, e);
+  return { remainingBeforeLock: Math.max(0, MAX_FAILS_BEFORE_LOCK - e.fails) };
+}
+
+export function recordSuccess(ip) {
+  attempts.delete(ip);
+}
+
+export function getClientIp(request) {
+  // Trusted: set from TCP socket by custom-server.js (client cannot spoof).
+  const realIp = request.headers.get("x-9r-real-ip");
+  if (realIp) return realIp;
+  // Behind a trusted reverse proxy that overwrites XFF with the real client IP.
+  if (process.env.TRUST_PROXY === "true") {
+    const xff = request.headers.get("x-forwarded-for");
+    if (xff) return xff.split(",")[0].trim();
+  }
+  // Direct exposure without custom-server: single bucket so spoofed XFF
+  // rotation cannot escape the limiter.
+  return "unknown";
+}
diff --git a/src/lib/auth/oidc.js b/src/lib/auth/oidc.js
new file mode 100644
index 0000000..dcabcb5
--- /dev/null
+++ b/src/lib/auth/oidc.js
@@ -0,0 +1,234 @@
+import crypto from "node:crypto";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { getSettings } from "@/lib/localDb";
+
+export const OIDC_COOKIE_NAMES = {
+  state: "oidc_state",
+  nonce: "oidc_nonce",
+  verifier: "oidc_code_verifier",
+};
+
+const DEFAULT_SCOPES = "openid profile email";
+const DEFAULT_LOGIN_LABEL = "Sign in with OIDC";
+
+function trimTrailingSlashes(value) {
+  return (value || "").trim().replace(/\/+$/, "");
+}
+
+function normalizeScopes(value) {
+  return (value || DEFAULT_SCOPES).trim() || DEFAULT_SCOPES;
+}
+
+export function getPublicOrigin(request) {
+  const configuredBaseUrl =
+    process.env.BASE_URL ||
+    process.env.NEXT_PUBLIC_BASE_URL ||
+    "";
+
+  if (configuredBaseUrl) {
+    return trimTrailingSlashes(configuredBaseUrl);
+  }
+
+  const forwardedProto = request?.headers?.get?.("x-forwarded-proto") || "";
+  const forwardedHost = request?.headers?.get?.("x-forwarded-host") || "";
+  const host = forwardedHost || request?.headers?.get?.("host") || "";
+  if (host) {
+    const protocol = (forwardedProto || new URL(request.url).protocol || "http:").replace(/:$/, "");
+    return `${protocol}://${host}`.replace(/\/+$/, "");
+  }
+
+  return trimTrailingSlashes(new URL(request.url).origin);
+}
+
+export function isOidcConfigured(settings) {
+  return !!(
+    trimTrailingSlashes(settings?.oidcIssuerUrl) &&
+    (settings?.oidcClientId || "").trim() &&
+    (settings?.oidcClientSecret || "").trim()
+  );
+}
+
+export async function getOidcRuntimeConfig() {
+  const settings = await getSettings();
+  if (!["oidc", "both"].includes(settings.authMode) || !isOidcConfigured(settings)) return null;
+
+  const issuerUrl = trimTrailingSlashes(settings.oidcIssuerUrl);
+  return {
+    issuerUrl,
+    clientId: settings.oidcClientId.trim(),
+    clientSecret: settings.oidcClientSecret.trim(),
+    scopes: normalizeScopes(settings.oidcScopes),
+    loginLabel: (settings.oidcLoginLabel || DEFAULT_LOGIN_LABEL).trim() || DEFAULT_LOGIN_LABEL,
+  };
+}
+
+export async function fetchOidcDiscovery(issuerUrl) {
+  const discoveryUrl = `${trimTrailingSlashes(issuerUrl)}/.well-known/openid-configuration`;
+  const res = await fetch(discoveryUrl, { cache: "no-store" });
+  if (!res.ok) {
+    throw new Error(`Failed to load OIDC discovery document from ${discoveryUrl}`);
+  }
+  return await res.json();
+}
+
+export function createPkcePair() {
+  const verifier = crypto.randomBytes(32).toString("base64url");
+  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+
+export function createOidcState() {
+  return crypto.randomBytes(16).toString("base64url");
+}
+
+export function createOidcNonce() {
+  return crypto.randomBytes(16).toString("base64url");
+}
+
+export function buildOidcAuthorizationUrl({
+  authorizationEndpoint,
+  clientId,
+  redirectUri,
+  scopes = DEFAULT_SCOPES,
+  state,
+  nonce,
+  codeChallenge,
+}) {
+  const url = new URL(authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", clientId);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("scope", normalizeScopes(scopes));
+  url.searchParams.set("state", state);
+  url.searchParams.set("nonce", nonce);
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  return url.toString();
+}
+
+export async function exchangeOidcCode({
+  tokenEndpoint,
+  clientId,
+  clientSecret,
+  code,
+  redirectUri,
+  codeVerifier,
+}) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    client_id: clientId,
+    code,
+    redirect_uri: redirectUri,
+    code_verifier: codeVerifier,
+  });
+
+  if (clientSecret) {
+    body.set("client_secret", clientSecret);
+  }
+
+  const res = await fetch(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body,
+  });
+
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const message = data?.error_description || data?.error || `OIDC token exchange failed (${res.status})`;
+    throw new Error(message);
+  }
+
+  return data;
+}
+
+export async function probeOidcClientSecret({
+  tokenEndpoint,
+  clientId,
+  clientSecret,
+  redirectUri,
+}) {
+  if (!clientSecret) {
+    return {
+      tested: false,
+      valid: null,
+      message: "No client secret was provided, so secret validation was skipped.",
+    };
+  }
+
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    client_id: clientId,
+    client_secret: clientSecret,
+    code: "__oidc_test_invalid_code__",
+    redirect_uri: redirectUri,
+    code_verifier: "__oidc_test_invalid_verifier__",
+  });
+
+  const res = await fetch(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body,
+  });
+
+  const data = await res.json().catch(() => ({}));
+  const error = (data?.error || "").toLowerCase();
+  const errorDescription = data?.error_description || data?.error || "";
+
+  if (res.ok) {
+    return {
+      tested: true,
+      valid: true,
+      message: "Client secret was accepted by the token endpoint.",
+      raw: data,
+    };
+  }
+
+  if (error === "invalid_client" || error === "unauthorized_client" || /client.*(invalid|failed|mismatch)/i.test(errorDescription)) {
+    return {
+      tested: true,
+      valid: false,
+      message: errorDescription || "Client secret is not valid.",
+      raw: data,
+    };
+  }
+
+  if (error === "invalid_grant" || error === "invalid_code" || /grant|code/i.test(errorDescription)) {
+    return {
+      tested: true,
+      valid: true,
+      message: "Client secret was accepted; the token exchange failed only because the test authorization code is invalid.",
+      raw: data,
+    };
+  }
+
+  return {
+    tested: true,
+    valid: null,
+    message: errorDescription || `Token endpoint responded with ${res.status}`,
+    raw: data,
+  };
+}
+
+export async function verifyOidcIdToken({
+  idToken,
+  issuer,
+  audience,
+  jwksUri,
+  nonce,
+}) {
+  const jwks = createRemoteJWKSet(new URL(jwksUri));
+  const { payload } = await jwtVerify(idToken, jwks, {
+    issuer,
+    audience,
+    nonce,
+  });
+  return payload;
+}
+
+export function pickOidcDisplayName(payload = {}) {
+  return payload.preferred_username || payload.email || payload.name || payload.given_name || payload.sub || "OIDC user";
+}
+
+export function pickOidcEmail(payload = {}) {
+  return payload.email || "";
+}
diff --git a/src/lib/consoleLogBuffer.js b/src/lib/consoleLogBuffer.js
new file mode 100644
index 0000000..9ace30f
--- /dev/null
+++ b/src/lib/consoleLogBuffer.js
@@ -0,0 +1,108 @@
+import { EventEmitter } from "events";
+import { CONSOLE_LOG_CONFIG } from "@/shared/constants/config.js";
+
+const consoleLevels = ["log", "info", "warn", "error", "debug"];
+
+if (!global._consoleLogBufferState) {
+  global._consoleLogBufferState = {
+    logs: [],
+    patched: false,
+    originals: {},
+    emitter: new EventEmitter(),
+  };
+  global._consoleLogBufferState.emitter.setMaxListeners(50);
+}
+
+const state = global._consoleLogBufferState;
+
+// Ensure emitter exists (handles hot reload with stale global)
+if (!state.emitter) {
+  state.emitter = new EventEmitter();
+  state.emitter.setMaxListeners(50);
+}
+
+if (!state.pendingLines) state.pendingLines = [];
+if (!state.flushTimer) state.flushTimer = null;
+
+const FLUSH_INTERVAL_MS = 100;
+const MAX_BATCH_LINES = 50;
+
+function flushPendingLines() {
+  state.flushTimer = null;
+  if (!state.pendingLines.length) return;
+
+  const lines = state.pendingLines.splice(0, state.pendingLines.length);
+  state.emitter.emit("lines", lines);
+}
+
+function scheduleFlush() {
+  if (state.flushTimer) return;
+  state.flushTimer = setTimeout(flushPendingLines, FLUSH_INTERVAL_MS);
+  state.flushTimer?.unref?.();
+}
+
+function toLogLine(level, args) {
+  return args.map(formatArg).join(" ");
+}
+
+// Strip ANSI escape codes so terminal colors don't bleed into UI
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function stripAnsi(str) {
+  return str.replace(ANSI_RE, "");
+}
+
+function formatArg(arg) {
+  if (typeof arg === "string") return stripAnsi(arg);
+  if (arg instanceof Error) return stripAnsi(arg.stack || arg.message || String(arg));
+  try {
+    return stripAnsi(JSON.stringify(arg));
+  } catch {
+    return stripAnsi(String(arg));
+  }
+}
+
+function appendLine(line) {
+  state.logs.push(line);
+  const maxLines = CONSOLE_LOG_CONFIG.maxLines;
+  if (state.logs.length > maxLines) {
+    state.logs = state.logs.slice(-maxLines);
+  }
+  state.pendingLines.push(line);
+  if (state.pendingLines.length >= MAX_BATCH_LINES) {
+    if (state.flushTimer) {
+      clearTimeout(state.flushTimer);
+      state.flushTimer = null;
+    }
+    flushPendingLines();
+  } else {
+    scheduleFlush();
+  }
+}
+
+export function initConsoleLogCapture() {
+  if (state.patched) return;
+
+  for (const level of consoleLevels) {
+    state.originals[level] = console[level];
+    console[level] = (...args) => {
+      appendLine(toLogLine(level, args));
+      state.originals[level](...args);
+    };
+  }
+
+  state.patched = true;
+}
+
+export function getConsoleLogs() {
+  return state.logs;
+}
+
+export function clearConsoleLogs() {
+  state.logs = [];
+  state.emitter.emit("clear");
+}
+
+export function getConsoleEmitter() {
+  return state.emitter;
+}
diff --git a/src/lib/dataDir.js b/src/lib/dataDir.js
new file mode 100644
index 0000000..dff51e9
--- /dev/null
+++ b/src/lib/dataDir.js
@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "path";
+import os from "os";
+
+const APP_NAME = "9router";
+
+function defaultDir() {
+  if (process.platform === "win32") {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), APP_NAME);
+  }
+  return path.join(os.homedir(), `.${APP_NAME}`);
+}
+
+export function getDataDir() {
+  const configured = process.env.DATA_DIR;
+  if (!configured) return defaultDir();
+
+  // On Windows, ignore Unix-style absolute paths (e.g. /var/lib/...) that come
+  // from a Linux-targeted .env or Docker config — they are not valid here.
+  if (process.platform === "win32" && /^\//.test(configured)) {
+    console.warn(`[DATA_DIR] '${configured}' is a Unix path on Windows → fallback to default`);
+    return defaultDir();
+  }
+
+  try {
+    fs.mkdirSync(configured, { recursive: true });
+    return configured;
+  } catch (e) {
+    if (e?.code === "EACCES" || e?.code === "EPERM") {
+      console.warn(`[DATA_DIR] '${configured}' not writable → fallback ~/.${APP_NAME}`);
+      return defaultDir();
+    }
+    throw e;
+  }
+}
+
+export const DATA_DIR = getDataDir();
diff --git a/src/lib/db/adapters/betterSqliteAdapter.js b/src/lib/db/adapters/betterSqliteAdapter.js
new file mode 100644
index 0000000..4fc8a0e
--- /dev/null
+++ b/src/lib/db/adapters/betterSqliteAdapter.js
@@ -0,0 +1,55 @@
+import Database from "better-sqlite3";
+import { PRAGMA_SQL } from "../schema.js";
+
+// Periodic checkpoint to keep WAL file small (avoid huge -wal/-shm growth)
+const CHECKPOINT_INTERVAL_MS = 60 * 1000;
+
+export function createBetterSqliteAdapter(filePath) {
+  const db = new Database(filePath);
+  db.exec(PRAGMA_SQL);
+  // Schema is created/synced by migrate.js after adapter init
+
+  const stmtCache = new Map();
+
+  function prepare(sql) {
+    let stmt = stmtCache.get(sql);
+    if (!stmt) {
+      stmt = db.prepare(sql);
+      stmtCache.set(sql, stmt);
+    }
+    return stmt;
+  }
+
+  // Truncate WAL periodically so file stays small for backup/copy
+  const checkpointTimer = setInterval(() => {
+    try { db.pragma("wal_checkpoint(TRUNCATE)"); } catch {}
+  }, CHECKPOINT_INTERVAL_MS);
+  if (typeof checkpointTimer.unref === "function") checkpointTimer.unref();
+
+  function gracefulClose() {
+    try { db.pragma("wal_checkpoint(TRUNCATE)"); } catch {}
+    try { stmtCache.clear(); } catch {}
+    try { db.close(); } catch {}
+  }
+
+  // Ensure WAL is flushed and -wal/-shm files removed on shutdown
+  const onShutdown = () => gracefulClose();
+  process.once("beforeExit", onShutdown);
+  process.once("SIGINT", () => { onShutdown(); process.exit(0); });
+  process.once("SIGTERM", () => { onShutdown(); process.exit(0); });
+
+  return {
+    driver: "better-sqlite3",
+    run(sql, params = []) { return prepare(sql).run(params); },
+    get(sql, params = []) { return prepare(sql).get(params); },
+    all(sql, params = []) { return prepare(sql).all(params); },
+    exec(sql) { return db.exec(sql); },
+    transaction(fn) { return db.transaction(fn)(); },
+    checkpoint() { try { db.pragma("wal_checkpoint(TRUNCATE)"); } catch {} },
+    close() {
+      clearInterval(checkpointTimer);
+      gracefulClose();
+    },
+    raw: db,
+  };
+}
diff --git a/src/lib/db/adapters/bunSqliteAdapter.js b/src/lib/db/adapters/bunSqliteAdapter.js
new file mode 100644
index 0000000..764304a
--- /dev/null
+++ b/src/lib/db/adapters/bunSqliteAdapter.js
@@ -0,0 +1,63 @@
+// Bun runtime adapter — uses built-in bun:sqlite (native, fastest under Bun).
+// Loaded only when process.versions.bun is present.
+import { PRAGMA_SQL } from "../schema.js";
+
+const CHECKPOINT_INTERVAL_MS = 60 * 1000;
+
+export async function createBunSqliteAdapter(filePath) {
+  // Dynamic import — only resolves under Bun runtime
+  const { Database } = await import("bun:sqlite");
+  const db = new Database(filePath, { create: true });
+  db.exec(PRAGMA_SQL);
+
+  const stmtCache = new Map();
+  function prepare(sql) {
+    let stmt = stmtCache.get(sql);
+    if (!stmt) {
+      stmt = db.prepare(sql);
+      stmtCache.set(sql, stmt);
+    }
+    return stmt;
+  }
+
+  const checkpointTimer = setInterval(() => {
+    try { db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); } catch {}
+  }, CHECKPOINT_INTERVAL_MS);
+  if (typeof checkpointTimer.unref === "function") checkpointTimer.unref();
+
+  function gracefulClose() {
+    try { db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); } catch {}
+    try { stmtCache.clear(); } catch {}
+    try { db.close(); } catch {}
+  }
+  const onShutdown = () => gracefulClose();
+  process.once("beforeExit", onShutdown);
+  process.once("SIGINT", () => { onShutdown(); process.exit(0); });
+  process.once("SIGTERM", () => { onShutdown(); process.exit(0); });
+
+  return {
+    driver: "bun:sqlite",
+    run(sql, params = []) {
+      const r = prepare(sql).run(...params);
+      return { changes: Number(r.changes ?? 0), lastInsertRowid: Number(r.lastInsertRowid ?? 0) };
+    },
+    get(sql, params = []) {
+      return prepare(sql).get(...params);
+    },
+    all(sql, params = []) {
+      return prepare(sql).all(...params);
+    },
+    exec(sql) { return db.exec(sql); },
+    transaction(fn) {
+      // bun:sqlite has db.transaction() API (similar to better-sqlite3)
+      const tx = db.transaction(fn);
+      return tx();
+    },
+    checkpoint() { try { db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); } catch {} },
+    close() {
+      clearInterval(checkpointTimer);
+      gracefulClose();
+    },
+    raw: db,
+  };
+}
diff --git a/src/lib/db/adapters/nodeSqliteAdapter.js b/src/lib/db/adapters/nodeSqliteAdapter.js
new file mode 100644
index 0000000..9948449
--- /dev/null
+++ b/src/lib/db/adapters/nodeSqliteAdapter.js
@@ -0,0 +1,84 @@
+// Built-in node:sqlite adapter — available in Node >= 22.5.0.
+// No native build, no npm install. API mirrors betterSqliteAdapter.
+import { PRAGMA_SQL } from "../schema.js";
+
+const CHECKPOINT_INTERVAL_MS = 60 * 1000;
+
+export async function createNodeSqliteAdapter(filePath) {
+  // Suppress "ExperimentalWarning: SQLite is an experimental feature" from node:sqlite.
+  // Stable enough for production use as of Node 22.x (RC quality).
+  const origEmit = process.emit;
+  process.emit = function (name, data, ...rest) {
+    if (name === "warning" && data?.name === "ExperimentalWarning" && /SQLite/i.test(data.message || "")) {
+      return false;
+    }
+    return origEmit.call(process, name, data, ...rest);
+  };
+
+  // Dynamic import — fails on Node < 22.5 → driver.js falls back to sql.js
+  const sqlite = await import("node:sqlite");
+  const Database = sqlite.DatabaseSync;
+  const db = new Database(filePath);
+
+  db.exec(PRAGMA_SQL);
+
+  const stmtCache = new Map();
+  function prepare(sql) {
+    let stmt = stmtCache.get(sql);
+    if (!stmt) {
+      stmt = db.prepare(sql);
+      stmtCache.set(sql, stmt);
+    }
+    return stmt;
+  }
+
+  // Periodic WAL checkpoint to keep -wal/-shm small
+  const checkpointTimer = setInterval(() => {
+    try { db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); } catch {}
+  }, CHECKPOINT_INTERVAL_MS);
+  if (typeof checkpointTimer.unref === "function") checkpointTimer.unref();
+
+  function gracefulClose() {
+    try { db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); } catch {}
+    try { stmtCache.clear(); } catch {}
+    try { db.close(); } catch {}
+  }
+  const onShutdown = () => gracefulClose();
+  process.once("beforeExit", onShutdown);
+  process.once("SIGINT", () => { onShutdown(); process.exit(0); });
+  process.once("SIGTERM", () => { onShutdown(); process.exit(0); });
+
+  return {
+    driver: "node:sqlite",
+    run(sql, params = []) {
+      const r = prepare(sql).run(...params);
+      return { changes: Number(r.changes ?? 0), lastInsertRowid: Number(r.lastInsertRowid ?? 0) };
+    },
+    get(sql, params = []) {
+      return prepare(sql).get(...params);
+    },
+    all(sql, params = []) {
+      return prepare(sql).all(...params);
+    },
+    exec(sql) { return db.exec(sql); },
+    transaction(fn) {
+      // node:sqlite has no transaction wrapper. Use SAVEPOINT for nested support.
+      const sp = `sp_${Math.random().toString(36).slice(2)}`;
+      db.exec(`SAVEPOINT ${sp}`);
+      try {
+        const r = fn();
+        db.exec(`RELEASE ${sp}`);
+        return r;
+      } catch (e) {
+        try { db.exec(`ROLLBACK TO ${sp}`); db.exec(`RELEASE ${sp}`); } catch {}
+        throw e;
+      }
+    },
+    checkpoint() { try { db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); } catch {} },
+    close() {
+      clearInterval(checkpointTimer);
+      gracefulClose();
+    },
+    raw: db,
+  };
+}
diff --git a/src/lib/db/adapters/sqljsAdapter.js b/src/lib/db/adapters/sqljsAdapter.js
new file mode 100644
index 0000000..613798e
--- /dev/null
+++ b/src/lib/db/adapters/sqljsAdapter.js
@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import initSqlJs from "sql.js";
+import { PRAGMA_SQL } from "../schema.js";
+
+let SQL = null;
+
+async function loadSql() {
+  if (SQL) return SQL;
+  SQL = await initSqlJs();
+  return SQL;
+}
+
+export async function createSqlJsAdapter(filePath) {
+  const SQLLib = await loadSql();
+  const buf = fs.existsSync(filePath) ? fs.readFileSync(filePath) : null;
+  const db = new SQLLib.Database(buf);
+  db.exec(PRAGMA_SQL);
+  // Schema is created/synced by migrate.js after adapter init
+
+  let dirty = false;
+  let saveTimer = null;
+  const SAVE_DEBOUNCE_MS = 100;
+
+  function persist() {
+    const data = db.export();
+    fs.writeFileSync(filePath, Buffer.from(data));
+    dirty = false;
+  }
+
+  function scheduleSave() {
+    dirty = true;
+    if (saveTimer) clearTimeout(saveTimer);
+    saveTimer = setTimeout(() => {
+      saveTimer = null;
+      if (dirty) {
+        try { persist(); } catch (e) { console.error("[sqljs] save failed:", e); }
+      }
+    }, SAVE_DEBOUNCE_MS);
+  }
+
+  function paramsObj(params) {
+    if (!params || (Array.isArray(params) && params.length === 0)) return undefined;
+    return params;
+  }
+
+  function run(sql, params = []) {
+    const stmt = db.prepare(sql);
+    try {
+      stmt.bind(paramsObj(params));
+      stmt.step();
+      const changes = db.getRowsModified();
+      const lastInsertRowid = db.exec("SELECT last_insert_rowid() as id")[0]?.values?.[0]?.[0] ?? null;
+      scheduleSave();
+      return { changes, lastInsertRowid };
+    } finally {
+      stmt.free();
+    }
+  }
+
+  function get(sql, params = []) {
+    const stmt = db.prepare(sql);
+    try {
+      stmt.bind(paramsObj(params));
+      if (stmt.step()) return stmt.getAsObject();
+      return undefined;
+    } finally {
+      stmt.free();
+    }
+  }
+
+  function all(sql, params = []) {
+    const stmt = db.prepare(sql);
+    try {
+      stmt.bind(paramsObj(params));
+      const rows = [];
+      while (stmt.step()) rows.push(stmt.getAsObject());
+      return rows;
+    } finally {
+      stmt.free();
+    }
+  }
+
+  function exec(sql) {
+    db.exec(sql);
+    scheduleSave();
+  }
+
+  function transaction(fn) {
+    const sp = `sp_${Math.random().toString(36).slice(2)}`;
+    db.exec(`SAVEPOINT ${sp}`);
+    try {
+      const result = fn();
+      db.exec(`RELEASE ${sp}`);
+      scheduleSave();
+      return result;
+    } catch (e) {
+      try { db.exec(`ROLLBACK TO ${sp}`); db.exec(`RELEASE ${sp}`); } catch {}
+      throw e;
+    }
+  }
+
+  function close() {
+    if (saveTimer) clearTimeout(saveTimer);
+    if (dirty) persist();
+    db.close();
+  }
+
+  // Flush on shutdown
+  const flush = () => { if (dirty) try { persist(); } catch {} };
+  process.on("beforeExit", flush);
+  process.on("SIGINT", flush);
+  process.on("SIGTERM", flush);
+
+  return { driver: "sql.js", run, get, all, exec, transaction, close, raw: db };
+}
diff --git a/src/lib/db/backup.js b/src/lib/db/backup.js
new file mode 100644
index 0000000..f3a7ed1
--- /dev/null
+++ b/src/lib/db/backup.js
@@ -0,0 +1,75 @@
+// DB safety backups — taken ONLY before a schema change (see migrate.js).
+//
+// ⚠️ AGENT/DEV NOTES:
+// - Backups are a best-effort safety net before schema migrations. There is NO
+//   automated restore path; recovery is manual (copy a backup file back).
+// - Backups intentionally EXCLUDE the `requestDetails` table (observability log,
+//   auto-pruned, non-critical) so a multi-hundred-MB DB backs up as a few MB.
+// - Only the newest KEEP_BACKUPS are kept; older ones are pruned automatically.
+import fs from "node:fs";
+import path from "node:path";
+import { BACKUPS_DIR, ensureDirs } from "./paths.js";
+import { timestampSlug, getAppVersion } from "./version.js";
+
+const KEEP_BACKUPS = 3;
+
+// Tables excluded from safety backups (large, non-critical, reproducible).
+const BACKUP_EXCLUDE_TABLES = ["requestDetails"];
+
+export function makeBackupDir(label) {
+  ensureDirs();
+  const ver = getAppVersion();
+  const slug = `${label}-${ver}-${timestampSlug()}`;
+  const dir = path.join(BACKUPS_DIR, slug);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function backupFile(srcPath, destDir, destName = null) {
+  if (!fs.existsSync(srcPath)) return null;
+  const name = destName || path.basename(srcPath);
+  const dest = path.join(destDir, name);
+  fs.copyFileSync(srcPath, dest);
+  return dest;
+}
+
+// Lightweight DB backup via ATTACH: create an empty sqlite file, copy every
+// table EXCEPT the excluded ones into it. Avoids duplicating the huge
+// observability log, so the backup stays small regardless of DB size.
+export function backupDbLite(adapter, destDir, destName = "data.sqlite") {
+  const dest = path.join(destDir, destName);
+  try { fs.rmSync(dest, { force: true }); } catch {}
+  const escaped = dest.replace(/'/g, "''");
+
+  adapter.exec(`ATTACH DATABASE '${escaped}' AS bak`);
+  try {
+    const excluded = new Set(BACKUP_EXCLUDE_TABLES);
+    const tables = adapter
+      .all(`SELECT name, sql FROM main.sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`)
+      .filter((t) => !excluded.has(t.name));
+
+    adapter.transaction(() => {
+      for (const t of tables) {
+        // Recreate table structure in backup DB, then copy rows.
+        const createSql = t.sql.replace(/CREATE TABLE\s+/i, "CREATE TABLE bak.");
+        adapter.exec(createSql);
+        adapter.exec(`INSERT INTO bak.${t.name} SELECT * FROM main.${t.name}`);
+      }
+    });
+  } finally {
+    try { adapter.exec("DETACH DATABASE bak"); } catch {}
+  }
+  return dest;
+}
+
+export function pruneOldBackups() {
+  if (!fs.existsSync(BACKUPS_DIR)) return;
+  const entries = fs.readdirSync(BACKUPS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => ({ name: e.name, full: path.join(BACKUPS_DIR, e.name), mtime: fs.statSync(path.join(BACKUPS_DIR, e.name)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+
+  for (const old of entries.slice(KEEP_BACKUPS)) {
+    try { fs.rmSync(old.full, { recursive: true, force: true }); } catch {}
+  }
+}
diff --git a/src/lib/db/driver.js b/src/lib/db/driver.js
new file mode 100644
index 0000000..050514d
--- /dev/null
+++ b/src/lib/db/driver.js
@@ -0,0 +1,85 @@
+import { ensureDirs, DATA_FILE } from "./paths.js";
+
+// Use global to survive Next.js dev hot-reload (module state resets on reload)
+if (!global._dbAdapter) global._dbAdapter = { instance: null, initPromise: null, logged: false };
+const state = global._dbAdapter;
+
+async function tryBunSqlite() {
+  // Bun runtime only — built-in, no install needed
+  if (!process.versions.bun) return null;
+  try {
+    const { createBunSqliteAdapter } = await import("./adapters/bunSqliteAdapter.js");
+    return await createBunSqliteAdapter(DATA_FILE);
+  } catch (e) {
+    console.warn(`[DB] bun:sqlite unavailable: ${e.message}`);
+    return null;
+  }
+}
+
+async function tryBetterSqlite() {
+  // Skip on Bun — better-sqlite3 native bindings unsupported
+  if (process.versions.bun) return null;
+  try {
+    const { createBetterSqliteAdapter } = await import("./adapters/betterSqliteAdapter.js");
+    return createBetterSqliteAdapter(DATA_FILE);
+  } catch (e) {
+    console.warn(`[DB] better-sqlite3 unavailable: ${e.message}`);
+    return null;
+  }
+}
+
+async function tryNodeSqlite() {
+  // Built-in since Node 22.5.0 — no install needed. Skip under Bun (no node:sqlite).
+  if (process.versions.bun) return null;
+  const [maj, min] = process.versions.node.split(".").map(Number);
+  if (maj < 22 || (maj === 22 && min < 5)) return null;
+  try {
+    const { createNodeSqliteAdapter } = await import("./adapters/nodeSqliteAdapter.js");
+    return await createNodeSqliteAdapter(DATA_FILE);
+  } catch (e) {
+    console.warn(`[DB] node:sqlite unavailable: ${e.message}`);
+    return null;
+  }
+}
+
+async function trySqlJs() {
+  try {
+    const { createSqlJsAdapter } = await import("./adapters/sqljsAdapter.js");
+    return await createSqlJsAdapter(DATA_FILE);
+  } catch (e) {
+    console.warn(`[DB] sql.js unavailable: ${e.message}`);
+    return null;
+  }
+}
+
+async function initAdapter() {
+  ensureDirs();
+  // Order per runtime:
+  //   Bun:  bun:sqlite → sql.js
+  //   Node: better-sqlite3 → node:sqlite (≥22.5) → sql.js
+  let adapter = await tryBunSqlite();
+  if (!adapter) adapter = await tryBetterSqlite();
+  if (!adapter) adapter = await tryNodeSqlite();
+  if (!adapter) adapter = await trySqlJs();
+  if (!adapter) throw new Error("[DB] No SQLite driver available (bun/better/node/sql.js all failed)");
+
+  if (!state.logged) {
+    console.log(`[DB] Driver: ${adapter.driver} | file: ${DATA_FILE}`);
+    state.logged = true;
+  }
+
+  const { runMigrationOnce } = await import("./migrate.js");
+  await runMigrationOnce(adapter);
+  return adapter;
+}
+
+export async function getAdapter() {
+  if (state.instance) return state.instance;
+  if (!state.initPromise) state.initPromise = initAdapter().then((a) => { state.instance = a; return a; });
+  return state.initPromise;
+}
+
+export function getAdapterSync() {
+  if (!state.instance) throw new Error("[DB] adapter not initialized — await getAdapter() first");
+  return state.instance;
+}
diff --git a/src/lib/db/helpers/jsonCol.js b/src/lib/db/helpers/jsonCol.js
new file mode 100644
index 0000000..48a4f08
--- /dev/null
+++ b/src/lib/db/helpers/jsonCol.js
@@ -0,0 +1,9 @@
+export function parseJson(str, fallback = null) {
+  if (str == null) return fallback;
+  if (typeof str !== "string") return str;
+  try { return JSON.parse(str); } catch { return fallback; }
+}
+
+export function stringifyJson(value) {
+  return JSON.stringify(value ?? null);
+}
diff --git a/src/lib/db/helpers/kvStore.js b/src/lib/db/helpers/kvStore.js
new file mode 100644
index 0000000..70ffa92
--- /dev/null
+++ b/src/lib/db/helpers/kvStore.js
@@ -0,0 +1,39 @@
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "./jsonCol.js";
+
+export function makeKv(scope) {
+  return {
+    async get(key, fallback = null) {
+      const db = await getAdapter();
+      const row = db.get(`SELECT value FROM kv WHERE scope = ? AND key = ?`, [scope, key]);
+      return row ? parseJson(row.value, fallback) : fallback;
+    },
+    async getAll() {
+      const db = await getAdapter();
+      const rows = db.all(`SELECT key, value FROM kv WHERE scope = ?`, [scope]);
+      const out = {};
+      for (const r of rows) out[r.key] = parseJson(r.value);
+      return out;
+    },
+    async set(key, value) {
+      const db = await getAdapter();
+      db.run(`INSERT INTO kv(scope, key, value) VALUES(?, ?, ?) ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`, [scope, key, stringifyJson(value)]);
+    },
+    async setMany(obj) {
+      const db = await getAdapter();
+      db.transaction(() => {
+        for (const [k, v] of Object.entries(obj)) {
+          db.run(`INSERT INTO kv(scope, key, value) VALUES(?, ?, ?) ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`, [scope, k, stringifyJson(v)]);
+        }
+      });
+    },
+    async remove(key) {
+      const db = await getAdapter();
+      db.run(`DELETE FROM kv WHERE scope = ? AND key = ?`, [scope, key]);
+    },
+    async clear() {
+      const db = await getAdapter();
+      db.run(`DELETE FROM kv WHERE scope = ?`, [scope]);
+    },
+  };
+}
diff --git a/src/lib/db/helpers/metaStore.js b/src/lib/db/helpers/metaStore.js
new file mode 100644
index 0000000..f42fb7c
--- /dev/null
+++ b/src/lib/db/helpers/metaStore.js
@@ -0,0 +1,22 @@
+import { getAdapter } from "../driver.js";
+
+export async function getMeta(key, fallback = null) {
+  const db = await getAdapter();
+  const row = db.get(`SELECT value FROM _meta WHERE key = ?`, [key]);
+  return row ? row.value : fallback;
+}
+
+export async function setMeta(key, value) {
+  const db = await getAdapter();
+  db.run(`INSERT INTO _meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`, [key, String(value)]);
+}
+
+// Sync versions for use during migration (adapter passed directly)
+export function getMetaSync(adapter, key, fallback = null) {
+  const row = adapter.get(`SELECT value FROM _meta WHERE key = ?`, [key]);
+  return row ? row.value : fallback;
+}
+
+export function setMetaSync(adapter, key, value) {
+  adapter.run(`INSERT INTO _meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`, [key, String(value)]);
+}
diff --git a/src/lib/db/index.js b/src/lib/db/index.js
new file mode 100644
index 0000000..e1c6847
--- /dev/null
+++ b/src/lib/db/index.js
@@ -0,0 +1,171 @@
+// Public API barrel — all DB functions
+import { getAdapter } from "./driver.js";
+import { stringifyJson, parseJson } from "./helpers/jsonCol.js";
+
+// Settings
+export {
+  getSettings, updateSettings, isCloudEnabled, getCloudUrl, exportSettings,
+} from "./repos/settingsRepo.js";
+
+// Provider connections
+export {
+  getProviderConnections, getProviderConnectionById,
+  createProviderConnection, updateProviderConnection,
+  deleteProviderConnection, deleteProviderConnectionsByProvider,
+  reorderProviderConnections, cleanupProviderConnections,
+} from "./repos/connectionsRepo.js";
+
+// Provider nodes
+export {
+  getProviderNodes, getProviderNodeById,
+  createProviderNode, updateProviderNode, deleteProviderNode,
+} from "./repos/nodesRepo.js";
+
+// Proxy pools
+export {
+  getProxyPools, getProxyPoolById,
+  createProxyPool, updateProxyPool, deleteProxyPool,
+} from "./repos/proxyPoolsRepo.js";
+
+// API keys
+export {
+  getApiKeys, getApiKeyById, createApiKey, updateApiKey, deleteApiKey, validateApiKey,
+} from "./repos/apiKeysRepo.js";
+
+// Combos
+export {
+  getCombos, getComboById, getComboByName,
+  createCombo, updateCombo, deleteCombo,
+} from "./repos/combosRepo.js";
+
+// Aliases (model + custom + mitm)
+export {
+  getModelAliases, setModelAlias, deleteModelAlias,
+  getCustomModels, addCustomModel, deleteCustomModel,
+  getMitmAlias, setMitmAliasAll,
+} from "./repos/aliasRepo.js";
+
+// Pricing
+export {
+  getPricing, getPricingForModel, updatePricing, resetPricing, resetAllPricing,
+} from "./repos/pricingRepo.js";
+
+// Disabled models
+export {
+  getDisabledModels, getDisabledByProvider, disableModels, enableModels,
+} from "./repos/disabledModelsRepo.js";
+
+// Usage
+export {
+  statsEmitter, trackPendingRequest, getActiveRequests,
+  saveRequestUsage, getUsageHistory, getUsageStats, getChartData,
+  appendRequestLog, getRecentLogs,
+} from "./repos/usageRepo.js";
+
+// Request details
+export {
+  saveRequestDetail, getRequestDetails, getRequestDetailById, getDistinctProviders,
+} from "./repos/requestDetailsRepo.js";
+
+// Export/import full DB
+export async function exportDb() {
+  const db = await getAdapter();
+  const { exportSettings } = await import("./repos/settingsRepo.js");
+
+  const out = {
+    settings: await exportSettings(),
+    providerConnections: db.all(`SELECT * FROM providerConnections`).map((r) => ({ ...parseJson(r.data, {}), id: r.id, provider: r.provider, authType: r.authType, name: r.name, email: r.email, priority: r.priority, isActive: r.isActive === 1, createdAt: r.createdAt, updatedAt: r.updatedAt })),
+    providerNodes: db.all(`SELECT * FROM providerNodes`).map((r) => ({ ...parseJson(r.data, {}), id: r.id, type: r.type, name: r.name, createdAt: r.createdAt, updatedAt: r.updatedAt })),
+    proxyPools: db.all(`SELECT * FROM proxyPools`).map((r) => ({ ...parseJson(r.data, {}), id: r.id, isActive: r.isActive === 1, testStatus: r.testStatus, createdAt: r.createdAt, updatedAt: r.updatedAt })),
+    apiKeys: db.all(`SELECT * FROM apiKeys`).map((r) => ({ id: r.id, key: r.key, name: r.name, machineId: r.machineId, isActive: r.isActive === 1, createdAt: r.createdAt })),
+    combos: db.all(`SELECT * FROM combos`).map((r) => ({ id: r.id, name: r.name, kind: r.kind, models: parseJson(r.models, []), createdAt: r.createdAt, updatedAt: r.updatedAt })),
+    modelAliases: {},
+    customModels: [],
+    mitmAlias: {},
+    pricing: {},
+  };
+
+  for (const r of db.all(`SELECT key, value FROM kv WHERE scope = 'modelAliases'`)) out.modelAliases[r.key] = parseJson(r.value);
+  for (const r of db.all(`SELECT key, value FROM kv WHERE scope = 'customModels'`)) out.customModels.push(parseJson(r.value));
+  for (const r of db.all(`SELECT key, value FROM kv WHERE scope = 'mitmAlias'`)) out.mitmAlias[r.key] = parseJson(r.value);
+  for (const r of db.all(`SELECT key, value FROM kv WHERE scope = 'pricing'`)) out.pricing[r.key] = parseJson(r.value);
+
+  return out;
+}
+
+export async function importDb(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("Invalid database payload");
+  }
+  const db = await getAdapter();
+
+  db.transaction(() => {
+    // Wipe all tables (keep _meta)
+    db.run(`DELETE FROM settings`);
+    db.run(`DELETE FROM providerConnections`);
+    db.run(`DELETE FROM providerNodes`);
+    db.run(`DELETE FROM proxyPools`);
+    db.run(`DELETE FROM apiKeys`);
+    db.run(`DELETE FROM combos`);
+    db.run(`DELETE FROM kv WHERE scope IN ('modelAliases', 'customModels', 'mitmAlias', 'pricing')`);
+
+    // Settings
+    if (payload.settings) {
+      db.run(`INSERT INTO settings(id, data) VALUES(1, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data`, [stringifyJson(payload.settings)]);
+    }
+
+    for (const c of payload.providerConnections || []) {
+      const { id, provider, authType, name, email, priority, isActive, createdAt, updatedAt, ...rest } = c;
+      db.run(
+        `INSERT OR REPLACE INTO providerConnections(id, provider, authType, name, email, priority, isActive, data, createdAt, updatedAt) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [id, provider, authType || "oauth", name || null, email || null, priority || null, isActive === false ? 0 : 1, stringifyJson(rest), createdAt || new Date().toISOString(), updatedAt || new Date().toISOString()]
+      );
+    }
+    for (const n of payload.providerNodes || []) {
+      const { id, type, name, createdAt, updatedAt, ...rest } = n;
+      db.run(
+        `INSERT OR REPLACE INTO providerNodes(id, type, name, data, createdAt, updatedAt) VALUES(?, ?, ?, ?, ?, ?)`,
+        [id, type || null, name || null, stringifyJson(rest), createdAt || new Date().toISOString(), updatedAt || new Date().toISOString()]
+      );
+    }
+    for (const p of payload.proxyPools || []) {
+      const { id, isActive, testStatus, createdAt, updatedAt, ...rest } = p;
+      db.run(
+        `INSERT OR REPLACE INTO proxyPools(id, isActive, testStatus, data, createdAt, updatedAt) VALUES(?, ?, ?, ?, ?, ?)`,
+        [id, isActive === false ? 0 : 1, testStatus || "unknown", stringifyJson(rest), createdAt || new Date().toISOString(), updatedAt || new Date().toISOString()]
+      );
+    }
+    for (const k of payload.apiKeys || []) {
+      db.run(
+        `INSERT OR REPLACE INTO apiKeys(id, key, name, machineId, isActive, createdAt) VALUES(?, ?, ?, ?, ?, ?)`,
+        [k.id, k.key, k.name || null, k.machineId || null, k.isActive === false ? 0 : 1, k.createdAt || new Date().toISOString()]
+      );
+    }
+    for (const c of payload.combos || []) {
+      db.run(
+        `INSERT OR REPLACE INTO combos(id, name, kind, models, createdAt, updatedAt) VALUES(?, ?, ?, ?, ?, ?)`,
+        [c.id, c.name, c.kind || null, stringifyJson(c.models || []), c.createdAt || new Date().toISOString(), c.updatedAt || new Date().toISOString()]
+      );
+    }
+    for (const [a, m] of Object.entries(payload.modelAliases || {})) {
+      db.run(`INSERT OR REPLACE INTO kv(scope, key, value) VALUES('modelAliases', ?, ?)`, [a, stringifyJson(m)]);
+    }
+    for (const m of payload.customModels || []) {
+      const k = `${m.providerAlias}|${m.id}|${m.type || "llm"}`;
+      db.run(`INSERT OR REPLACE INTO kv(scope, key, value) VALUES('customModels', ?, ?)`, [k, stringifyJson(m)]);
+    }
+    for (const [tool, mappings] of Object.entries(payload.mitmAlias || {})) {
+      db.run(`INSERT OR REPLACE INTO kv(scope, key, value) VALUES('mitmAlias', ?, ?)`, [tool, stringifyJson(mappings || {})]);
+    }
+    for (const [provider, models] of Object.entries(payload.pricing || {})) {
+      db.run(`INSERT OR REPLACE INTO kv(scope, key, value) VALUES('pricing', ?, ?)`, [provider, stringifyJson(models || {})]);
+    }
+  });
+
+  return await exportDb();
+}
+
+// Eager init helper (optional)
+export async function initDb() {
+  await getAdapter();
+}
diff --git a/src/lib/db/migrate.js b/src/lib/db/migrate.js
new file mode 100644
index 0000000..0cca4da
--- /dev/null
+++ b/src/lib/db/migrate.js
@@ -0,0 +1,297 @@
+import fs from "node:fs";
+import path from "node:path";
+import { LEGACY_FILES, DB_DIR } from "./paths.js";
+import { TABLES, buildCreateTableSql, SCHEMA_VERSION } from "./schema.js";
+import { MIGRATIONS, latestVersion } from "./migrations/index.js";
+import { getMetaSync, setMetaSync } from "./helpers/metaStore.js";
+import { makeBackupDir, backupFile, backupDbLite, pruneOldBackups } from "./backup.js";
+import { getAppVersion } from "./version.js";
+import { stringifyJson } from "./helpers/jsonCol.js";
+
+// Marker file: prevents re-importing legacy JSON when user wipes data.sqlite.
+const MIGRATED_MARKER = path.join(DB_DIR, ".migrated-from-json");
+
+// Track per-adapter so reusing same adapter skips re-run, but new adapter (after reset) re-runs.
+const _migratedAdapters = new WeakSet();
+
+// Thrown when row-count assertion fails. Outer transaction rolls back,
+// legacy db.json kept intact, marker not written → next boot retries.
+export class MigrationAborted extends Error {
+  constructor(message, droppedRows) {
+    super(message);
+    this.name = "MigrationAborted";
+    this.droppedRows = droppedRows;
+  }
+}
+
+// Insert rows one-by-one, collect failures, then assert COUNT(*) matches input length.
+function importWithAssertion(adapter, tableName, rows, insertFn, rowMeta) {
+  const dropped = [];
+  for (const row of rows) {
+    try { insertFn(row); }
+    catch (err) { dropped.push({ ...rowMeta(row), reason: err.message }); }
+  }
+  const inserted = adapter.get(`SELECT COUNT(*) as c FROM ${tableName}`)?.c ?? 0;
+  if (inserted !== rows.length) {
+    console.warn(`[DB][migrate] ${tableName} row-count mismatch: expected ${rows.length}, got ${inserted}. Dropped:`, dropped);
+    throw new MigrationAborted(`${tableName} row-count mismatch: expected ${rows.length}, got ${inserted}`, dropped);
+  }
+}
+
+function readJsonSafe(file) {
+  if (!fs.existsSync(file)) return null;
+  try { return JSON.parse(fs.readFileSync(file, "utf-8")); } catch { return null; }
+}
+
+function isFreshDb(adapter) {
+  // Table _meta may not exist yet on truly fresh DB
+  try {
+    const row = adapter.get(`SELECT COUNT(*) as c FROM _meta`);
+    return !row || row.c === 0;
+  } catch {
+    return true;
+  }
+}
+
+// ─── Versioned migrations runner (skip-version safe) ─────────────────────
+function runVersionedMigrations(adapter) {
+  // Bootstrap _meta first so we can read schemaVersion
+  adapter.exec(buildCreateTableSql("_meta", TABLES._meta));
+
+  const current = parseInt(getMetaSync(adapter, "schemaVersion", "0"), 10) || 0;
+  const target = latestVersion();
+  if (current >= target) return { applied: 0, from: current, to: current };
+
+  const pending = MIGRATIONS.filter((m) => m.version > current);
+  let lastApplied = current;
+  for (const m of pending) {
+    adapter.transaction(() => {
+      m.up(adapter);
+      setMetaSync(adapter, "schemaVersion", m.version);
+    });
+    lastApplied = m.version;
+    console.log(`[DB][migrate] applied #${m.version} ${m.name}`);
+  }
+  return { applied: pending.length, from: current, to: lastApplied };
+}
+
+// ─── Auto-sync (additive only): add missing tables/columns/indexes ───────
+function syncSchemaFromTables(adapter) {
+  for (const [tableName, def] of Object.entries(TABLES)) {
+    // Create table if absent
+    adapter.exec(buildCreateTableSql(tableName, def));
+
+    // Diff columns
+    const existing = adapter.all(`PRAGMA table_info(${tableName})`);
+    const existingNames = new Set(existing.map((r) => r.name));
+    for (const [colName, colDef] of Object.entries(def.columns)) {
+      if (!existingNames.has(colName)) {
+        // SQLite ADD COLUMN restrictions: no PRIMARY KEY / UNIQUE w/o NULL ok.
+        // We strip PRIMARY KEY / UNIQUE since those are only valid at create time.
+        const safeDef = colDef
+          .replace(/PRIMARY KEY( AUTOINCREMENT)?/i, "")
+          .replace(/UNIQUE/i, "")
+          .trim();
+        try {
+          adapter.exec(`ALTER TABLE ${tableName} ADD COLUMN ${colName} ${safeDef}`);
+          console.log(`[DB][sync] +column ${tableName}.${colName}`);
+        } catch (e) {
+          console.warn(`[DB][sync] add column ${tableName}.${colName} failed: ${e.message}`);
+        }
+      }
+    }
+
+    // Indexes (idempotent)
+    for (const idx of def.indexes || []) {
+      try { adapter.exec(idx); } catch {}
+    }
+  }
+}
+
+// ─── Legacy JSON import (one-time) ───────────────────────────────────────
+function importLegacyMain(adapter, data) {
+  if (!data || typeof data !== "object") return;
+
+  if (data.settings) {
+    adapter.run(`INSERT INTO settings(id, data) VALUES(1, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data`, [stringifyJson(data.settings)]);
+  }
+
+  importWithAssertion(adapter, "providerConnections", data.providerConnections || [], (c) => {
+    const { id, provider, authType, name, email, priority, isActive, createdAt, updatedAt, ...rest } = c;
+    adapter.run(
+      `INSERT OR REPLACE INTO providerConnections(id, provider, authType, name, email, priority, isActive, data, createdAt, updatedAt) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [id, provider, authType || "oauth", name || null, email || null, priority || null, isActive === false ? 0 : 1, stringifyJson(rest), createdAt || new Date().toISOString(), updatedAt || new Date().toISOString()]
+    );
+  }, (c) => ({ id: c.id ?? null, provider: c.provider ?? null, name: c.name ?? null }));
+
+  importWithAssertion(adapter, "providerNodes", data.providerNodes || [], (n) => {
+    const { id, type, name, createdAt, updatedAt, ...rest } = n;
+    adapter.run(
+      `INSERT OR REPLACE INTO providerNodes(id, type, name, data, createdAt, updatedAt) VALUES(?, ?, ?, ?, ?, ?)`,
+      [id, type || null, name || null, stringifyJson(rest), createdAt || new Date().toISOString(), updatedAt || new Date().toISOString()]
+    );
+  }, (n) => ({ id: n.id ?? null, type: n.type ?? null, name: n.name ?? null }));
+
+  importWithAssertion(adapter, "proxyPools", data.proxyPools || [], (p) => {
+    const { id, isActive, testStatus, createdAt, updatedAt, ...rest } = p;
+    adapter.run(
+      `INSERT OR REPLACE INTO proxyPools(id, isActive, testStatus, data, createdAt, updatedAt) VALUES(?, ?, ?, ?, ?, ?)`,
+      [id, isActive === false ? 0 : 1, testStatus || "unknown", stringifyJson(rest), createdAt || new Date().toISOString(), updatedAt || new Date().toISOString()]
+    );
+  }, (p) => ({ id: p.id ?? null }));
+
+  importWithAssertion(adapter, "apiKeys", data.apiKeys || [], (k) => {
+    adapter.run(
+      `INSERT OR REPLACE INTO apiKeys(id, key, name, machineId, isActive, createdAt) VALUES(?, ?, ?, ?, ?, ?)`,
+      [k.id, k.key, k.name || null, k.machineId || null, k.isActive === false ? 0 : 1, k.createdAt || new Date().toISOString()]
+    );
+  }, (k) => ({ id: k.id ?? null, name: k.name ?? null }));
+
+  importWithAssertion(adapter, "combos", data.combos || [], (c) => {
+    adapter.run(
+      `INSERT OR REPLACE INTO combos(id, name, kind, models, createdAt, updatedAt) VALUES(?, ?, ?, ?, ?, ?)`,
+      [c.id, c.name, c.kind || null, stringifyJson(c.models || []), c.createdAt || new Date().toISOString(), c.updatedAt || new Date().toISOString()]
+    );
+  }, (c) => ({ id: c.id ?? null, name: c.name ?? null }));
+
+  for (const [alias, model] of Object.entries(data.modelAliases || {})) {
+    adapter.run(`INSERT OR REPLACE INTO kv(scope, key, value) VALUES('modelAliases', ?, ?)`, [alias, stringifyJson(model)]);
+  }
+  for (const m of data.customModels || []) {
+    const k = `${m.providerAlias}|${m.id}|${m.type || "llm"}`;
+    adapter.run(`INSERT OR REPLACE INTO kv(scope, key, value) VALUES('customModels', ?, ?)`, [k, stringifyJson(m)]);
+  }
+  for (const [tool, mappings] of Object.entries(data.mitmAlias || {})) {
+    adapter.run(`INSERT OR REPLACE INTO kv(scope, key, value) VALUES('mitmAlias', ?, ?)`, [tool, stringifyJson(mappings || {})]);
+  }
+  for (const [provider, models] of Object.entries(data.pricing || {})) {
+    adapter.run(`INSERT OR REPLACE INTO kv(scope, key, value) VALUES('pricing', ?, ?)`, [provider, stringifyJson(models || {})]);
+  }
+}
+
+function importLegacyUsage(adapter, data) {
+  if (!data || typeof data !== "object") return;
+  for (const e of data.history || []) {
+    const t = e.tokens || {};
+    adapter.run(
+      `INSERT INTO usageHistory(timestamp, provider, model, connectionId, apiKey, endpoint, promptTokens, completionTokens, cost, status, tokens, meta) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        e.timestamp || new Date().toISOString(),
+        e.provider || null, e.model || null, e.connectionId || null, e.apiKey || null, e.endpoint || null,
+        t.prompt_tokens || t.input_tokens || 0,
+        t.completion_tokens || t.output_tokens || 0,
+        e.cost || 0,
+        e.status || "ok",
+        stringifyJson(t),
+        stringifyJson({}),
+      ]
+    );
+  }
+  for (const [dateKey, day] of Object.entries(data.dailySummary || {})) {
+    adapter.run(`INSERT OR REPLACE INTO usageDaily(dateKey, data) VALUES(?, ?)`, [dateKey, stringifyJson(day)]);
+  }
+  if (typeof data.totalRequestsLifetime === "number") {
+    setMetaSync(adapter, "totalRequestsLifetime", data.totalRequestsLifetime);
+  }
+}
+
+function importLegacyDisabled(adapter, data) {
+  if (!data || typeof data.disabled !== "object") return;
+  for (const [provider, ids] of Object.entries(data.disabled)) {
+    adapter.run(`INSERT OR REPLACE INTO kv(scope, key, value) VALUES('disabledModels', ?, ?)`, [provider, stringifyJson(ids || [])]);
+  }
+}
+
+function importLegacyDetails(adapter, data) {
+  if (!data || !Array.isArray(data.records)) return;
+  for (const r of data.records) {
+    adapter.run(
+      `INSERT OR REPLACE INTO requestDetails(id, timestamp, provider, model, connectionId, status, data) VALUES(?, ?, ?, ?, ?, ?, ?)`,
+      [r.id, r.timestamp || new Date().toISOString(), r.provider || null, r.model || null, r.connectionId || null, r.status || null, stringifyJson(r)]
+    );
+  }
+}
+
+// ─── Main entry ──────────────────────────────────────────────────────────
+export async function runMigrationOnce(adapter) {
+  if (_migratedAdapters.has(adapter)) return;
+  _migratedAdapters.add(adapter);
+
+  // Capture freshness BEFORE migrations stamp _meta (otherwise we'd misclassify
+  // a brand-new DB as non-fresh once schemaVersion is written).
+  const fresh = isFreshDb(adapter);
+
+  // Prune stale backups every boot so old oversized backups shrink to KEEP.
+  pruneOldBackups();
+
+  // Bootstrap _meta so we can read the stored backup schema version below
+  // (runVersionedMigrations also ensures this, but we need it earlier here).
+  adapter.exec(buildCreateTableSql("_meta", TABLES._meta));
+
+  // Detect a pending schema change via the central SCHEMA_VERSION const.
+  // A lightweight backup is taken BEFORE any schema mutation below.
+  const storedSchemaVer = parseInt(getMetaSync(adapter, "backupSchemaVersion", "0"), 10) || 0;
+  const schemaChanging = !fresh && storedSchemaVer < SCHEMA_VERSION;
+  if (schemaChanging) {
+    try {
+      const backupDir = makeBackupDir(`schema-${storedSchemaVer}-to-${SCHEMA_VERSION}`);
+      backupDbLite(adapter, backupDir);
+      pruneOldBackups();
+      console.log(`[DB][migrate] pre-schema backup ${storedSchemaVer} → ${SCHEMA_VERSION}: ${backupDir}`);
+    } catch (e) {
+      console.warn(`[DB][migrate] pre-schema backup failed (continuing): ${e.message}`);
+    }
+  }
+
+  // 1. Always run versioned migrations chain (skip-version safe)
+  const migInfo = runVersionedMigrations(adapter);
+
+  // 2. Additive sync (auto add missing columns/indexes declared in TABLES)
+  syncSchemaFromTables(adapter);
+
+  // Stamp the schema version we just reached so future boots skip re-backup.
+  setMetaSync(adapter, "backupSchemaVersion", SCHEMA_VERSION);
+
+  // 3. One-time legacy JSON import (only if DB was fresh on entry)
+  const alreadyImported = fs.existsSync(MIGRATED_MARKER);
+  const legacyMain = readJsonSafe(LEGACY_FILES.main);
+  const legacyUsage = readJsonSafe(LEGACY_FILES.usage);
+  const legacyDisabled = readJsonSafe(LEGACY_FILES.disabled);
+  const legacyDetails = readJsonSafe(LEGACY_FILES.details);
+  const hasLegacy = !!(legacyMain || legacyUsage || legacyDisabled || legacyDetails);
+
+  if (fresh && hasLegacy && !alreadyImported) {
+    const t0 = Date.now();
+    const backupDir = makeBackupDir("migrate-from-json");
+    for (const f of Object.values(LEGACY_FILES)) backupFile(f, backupDir);
+
+    try {
+      adapter.transaction(() => {
+        importLegacyMain(adapter, legacyMain);
+        importLegacyUsage(adapter, legacyUsage);
+        importLegacyDisabled(adapter, legacyDisabled);
+        importLegacyDetails(adapter, legacyDetails);
+        setMetaSync(adapter, "appVersion", getAppVersion());
+        setMetaSync(adapter, "backupSchemaVersion", SCHEMA_VERSION);
+        setMetaSync(adapter, "migratedAt", new Date().toISOString());
+      });
+    } catch (err) {
+      if (err instanceof MigrationAborted) {
+        console.error(`[DB][migrate] aborted: ${err.message} | legacy JSON kept | backup: ${backupDir}`);
+        return;
+      }
+      throw err;
+    }
+
+    try { fs.writeFileSync(MIGRATED_MARKER, new Date().toISOString()); } catch {}
+    pruneOldBackups();
+    console.log(`[DB][migrate] JSON → SQLite in ${Date.now() - t0}ms | legacy JSON kept at DATA_DIR | backup: ${backupDir}`);
+    return;
+  }
+
+  // Track app version for informational purposes only. App version bumps no
+  // longer trigger a DB backup — only real schema changes (SCHEMA_VERSION) do.
+  const newVer = getAppVersion();
+  const oldVer = getMetaSync(adapter, "appVersion", null);
+  if (oldVer !== newVer) setMetaSync(adapter, "appVersion", newVer);
+}
diff --git a/src/lib/db/migrations/001-initial.js b/src/lib/db/migrations/001-initial.js
new file mode 100644
index 0000000..3b1c74b
--- /dev/null
+++ b/src/lib/db/migrations/001-initial.js
@@ -0,0 +1,14 @@
+// Initial schema bootstrap. For fresh DB this creates all tables/indexes.
+// For existing DB at version 0 (legacy unstamped), it's idempotent (IF NOT EXISTS).
+import { TABLES, buildCreateTableSql } from "../schema.js";
+
+export default {
+  version: 1,
+  name: "initial",
+  up(db) {
+    for (const [name, def] of Object.entries(TABLES)) {
+      db.exec(buildCreateTableSql(name, def));
+      for (const idx of def.indexes || []) db.exec(idx);
+    }
+  },
+};
diff --git a/src/lib/db/migrations/index.js b/src/lib/db/migrations/index.js
new file mode 100644
index 0000000..13fb4bf
--- /dev/null
+++ b/src/lib/db/migrations/index.js
@@ -0,0 +1,10 @@
+// Migration registry — append new entries when schema changes.
+// Each migration: { version: number, name: string, up(db): void }
+// Versions MUST be unique and monotonically increasing.
+import m001 from "./001-initial.js";
+
+export const MIGRATIONS = [m001].sort((a, b) => a.version - b.version);
+
+export function latestVersion() {
+  return MIGRATIONS.length ? MIGRATIONS[MIGRATIONS.length - 1].version : 0;
+}
diff --git a/src/lib/db/paths.js b/src/lib/db/paths.js
new file mode 100644
index 0000000..5757f7b
--- /dev/null
+++ b/src/lib/db/paths.js
@@ -0,0 +1,18 @@
+import path from "node:path";
+import fs from "node:fs";
+import { DATA_DIR } from "@/lib/dataDir.js";
+
+export const DB_DIR = path.join(DATA_DIR, "db");
+export const DATA_FILE = path.join(DB_DIR, "data.sqlite");
+export const BACKUPS_DIR = path.join(DB_DIR, "backups");
+export const LEGACY_FILES = {
+  main: path.join(DATA_DIR, "db.json"),
+  usage: path.join(DATA_DIR, "usage.json"),
+  disabled: path.join(DATA_DIR, "disabledModels.json"),
+  details: path.join(DATA_DIR, "request-details.json"),
+};
+export function ensureDirs() {
+  for (const dir of [DATA_DIR, DB_DIR, BACKUPS_DIR]) {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+}
diff --git a/src/lib/db/repos/aliasRepo.js b/src/lib/db/repos/aliasRepo.js
new file mode 100644
index 0000000..fe4ef22
--- /dev/null
+++ b/src/lib/db/repos/aliasRepo.js
@@ -0,0 +1,62 @@
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+import { makeKv } from "../helpers/kvStore.js";
+
+const aliasKv = makeKv("modelAliases");
+const customKv = makeKv("customModels");
+const mitmKv = makeKv("mitmAlias");
+
+// modelAliases: key=alias, value=modelString
+export async function getModelAliases() {
+  return await aliasKv.getAll();
+}
+
+export async function setModelAlias(alias, model) {
+  await aliasKv.set(alias, model);
+}
+
+export async function deleteModelAlias(alias) {
+  await aliasKv.remove(alias);
+}
+
+// customModels: key=`${providerAlias}|${id}|${type}`, value=full model object
+function customKey(providerAlias, id, type) {
+  return `${providerAlias}|${id}|${type}`;
+}
+
+export async function getCustomModels() {
+  const all = await customKv.getAll();
+  return Object.values(all);
+}
+
+// Atomic check-then-insert inside transaction to prevent duplicate races
+export async function addCustomModel({ providerAlias, id, type = "llm", name }) {
+  const k = customKey(providerAlias, id, type);
+  const db = await getAdapter();
+  let added = false;
+  db.transaction(() => {
+    const row = db.get(`SELECT 1 FROM kv WHERE scope = 'customModels' AND key = ?`, [k]);
+    if (row) return;
+    const value = stringifyJson({ providerAlias, id, type, name: name || id });
+    db.run(`INSERT INTO kv(scope, key, value) VALUES('customModels', ?, ?)`, [k, value]);
+    added = true;
+  });
+  return added;
+}
+
+export async function deleteCustomModel({ providerAlias, id, type = "llm" }) {
+  await customKv.remove(customKey(providerAlias, id, type));
+}
+
+// mitmAlias: key=toolName, value=mappings object
+export async function getMitmAlias(toolName) {
+  if (toolName) {
+    const v = await mitmKv.get(toolName);
+    return v || {};
+  }
+  return await mitmKv.getAll();
+}
+
+export async function setMitmAliasAll(toolName, mappings) {
+  await mitmKv.set(toolName, mappings || {});
+}
diff --git a/src/lib/db/repos/apiKeysRepo.js b/src/lib/db/repos/apiKeysRepo.js
new file mode 100644
index 0000000..ff09d92
--- /dev/null
+++ b/src/lib/db/repos/apiKeysRepo.js
@@ -0,0 +1,75 @@
+import { v4 as uuidv4 } from "uuid";
+import { getAdapter } from "../driver.js";
+
+function rowToKey(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    key: row.key,
+    name: row.name,
+    machineId: row.machineId,
+    isActive: row.isActive === 1 || row.isActive === true,
+    createdAt: row.createdAt,
+  };
+}
+
+export async function getApiKeys() {
+  const db = await getAdapter();
+  const rows = db.all(`SELECT * FROM apiKeys ORDER BY createdAt ASC`);
+  return rows.map(rowToKey);
+}
+
+export async function getApiKeyById(id) {
+  const db = await getAdapter();
+  const row = db.get(`SELECT * FROM apiKeys WHERE id = ?`, [id]);
+  return rowToKey(row);
+}
+
+export async function createApiKey(name, machineId) {
+  if (!machineId) throw new Error("machineId is required");
+  const db = await getAdapter();
+  const { generateApiKeyWithMachine } = await import("@/shared/utils/apiKey");
+  const result = generateApiKeyWithMachine(machineId);
+  const apiKey = {
+    id: uuidv4(),
+    name,
+    key: result.key,
+    machineId,
+    isActive: true,
+    createdAt: new Date().toISOString(),
+  };
+  db.run(
+    `INSERT INTO apiKeys(id, key, name, machineId, isActive, createdAt) VALUES(?, ?, ?, ?, ?, ?)`,
+    [apiKey.id, apiKey.key, apiKey.name, apiKey.machineId, 1, apiKey.createdAt]
+  );
+  return apiKey;
+}
+
+export async function updateApiKey(id, data) {
+  const db = await getAdapter();
+  let result = null;
+  db.transaction(() => {
+    const row = db.get(`SELECT * FROM apiKeys WHERE id = ?`, [id]);
+    if (!row) return;
+    const merged = { ...rowToKey(row), ...data };
+    db.run(
+      `UPDATE apiKeys SET key = ?, name = ?, machineId = ?, isActive = ? WHERE id = ?`,
+      [merged.key, merged.name, merged.machineId, merged.isActive ? 1 : 0, id]
+    );
+    result = merged;
+  });
+  return result;
+}
+
+export async function deleteApiKey(id) {
+  const db = await getAdapter();
+  const res = db.run(`DELETE FROM apiKeys WHERE id = ?`, [id]);
+  return (res?.changes ?? 0) > 0;
+}
+
+export async function validateApiKey(key) {
+  const db = await getAdapter();
+  const row = db.get(`SELECT isActive FROM apiKeys WHERE key = ?`, [key]);
+  if (!row) return false;
+  return row.isActive === 1 || row.isActive === true;
+}
diff --git a/src/lib/db/repos/combosRepo.js b/src/lib/db/repos/combosRepo.js
new file mode 100644
index 0000000..11e72a3
--- /dev/null
+++ b/src/lib/db/repos/combosRepo.js
@@ -0,0 +1,73 @@
+import { v4 as uuidv4 } from "uuid";
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+
+function rowToCombo(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    name: row.name,
+    kind: row.kind,
+    models: parseJson(row.models, []),
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export async function getCombos() {
+  const db = await getAdapter();
+  const rows = db.all(`SELECT * FROM combos ORDER BY createdAt ASC`);
+  return rows.map(rowToCombo);
+}
+
+export async function getComboById(id) {
+  const db = await getAdapter();
+  const row = db.get(`SELECT * FROM combos WHERE id = ?`, [id]);
+  return rowToCombo(row);
+}
+
+export async function getComboByName(name) {
+  const db = await getAdapter();
+  const row = db.get(`SELECT * FROM combos WHERE name = ?`, [name]);
+  return rowToCombo(row);
+}
+
+export async function createCombo(data) {
+  const db = await getAdapter();
+  const now = new Date().toISOString();
+  const combo = {
+    id: uuidv4(),
+    name: data.name,
+    kind: data.kind || null,
+    models: data.models || [],
+    createdAt: now,
+    updatedAt: now,
+  };
+  db.run(
+    `INSERT INTO combos(id, name, kind, models, createdAt, updatedAt) VALUES(?, ?, ?, ?, ?, ?)`,
+    [combo.id, combo.name, combo.kind, stringifyJson(combo.models), combo.createdAt, combo.updatedAt]
+  );
+  return combo;
+}
+
+export async function updateCombo(id, data) {
+  const db = await getAdapter();
+  let result = null;
+  db.transaction(() => {
+    const row = db.get(`SELECT * FROM combos WHERE id = ?`, [id]);
+    if (!row) return;
+    const merged = { ...rowToCombo(row), ...data, updatedAt: new Date().toISOString() };
+    db.run(
+      `UPDATE combos SET name = ?, kind = ?, models = ?, updatedAt = ? WHERE id = ?`,
+      [merged.name, merged.kind, stringifyJson(merged.models || []), merged.updatedAt, id]
+    );
+    result = merged;
+  });
+  return result;
+}
+
+export async function deleteCombo(id) {
+  const db = await getAdapter();
+  const res = db.run(`DELETE FROM combos WHERE id = ?`, [id]);
+  return (res?.changes ?? 0) > 0;
+}
diff --git a/src/lib/db/repos/connectionsRepo.js b/src/lib/db/repos/connectionsRepo.js
new file mode 100644
index 0000000..4181843
--- /dev/null
+++ b/src/lib/db/repos/connectionsRepo.js
@@ -0,0 +1,261 @@
+import { v4 as uuidv4 } from "uuid";
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+
+const OPTIONAL_FIELDS = [
+  "displayName", "email", "globalPriority", "defaultModel",
+  "accessToken", "refreshToken", "expiresAt", "tokenType",
+  "scope", "projectId", "apiKey", "testStatus",
+  "lastTested", "lastError", "lastErrorAt", "rateLimitedUntil", "expiresIn", "errorCode",
+  "consecutiveUseCount", "idToken", "lastRefreshAt",
+];
+
+function rowToConn(row) {
+  if (!row) return null;
+  const extra = parseJson(row.data, {});
+  return {
+    ...extra,
+    id: row.id,
+    provider: row.provider,
+    authType: row.authType,
+    name: row.name,
+    email: row.email,
+    priority: row.priority,
+    isActive: row.isActive === 1 || row.isActive === true,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function connToRow(c) {
+  const { id, provider, authType, name, email, priority, isActive, createdAt, updatedAt, ...rest } = c;
+  return {
+    id,
+    provider,
+    authType,
+    name: name ?? null,
+    email: email ?? null,
+    priority: priority ?? null,
+    isActive: isActive === false ? 0 : 1,
+    data: stringifyJson(rest),
+    createdAt,
+    updatedAt,
+  };
+}
+
+function upsert(db, c) {
+  const r = connToRow(c);
+  db.run(
+    `INSERT INTO providerConnections(id, provider, authType, name, email, priority, isActive, data, createdAt, updatedAt)
+     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       provider=excluded.provider, authType=excluded.authType, name=excluded.name,
+       email=excluded.email, priority=excluded.priority, isActive=excluded.isActive,
+       data=excluded.data, updatedAt=excluded.updatedAt`,
+    [r.id, r.provider, r.authType, r.name, r.email, r.priority, r.isActive, r.data, r.createdAt, r.updatedAt]
+  );
+}
+
+function deriveConnectionName(data, fallbackName) {
+  if (data.provider === "github") {
+    return data.providerSpecificData?.githubLogin
+      || data.providerSpecificData?.githubEmail
+      || data.email
+      || data.providerSpecificData?.githubName
+      || fallbackName;
+  }
+  return fallbackName;
+}
+
+export async function getProviderConnections(filter = {}) {
+  const db = await getAdapter();
+  const where = [];
+  const params = [];
+  if (filter.provider) { where.push("provider = ?"); params.push(filter.provider); }
+  if (filter.isActive !== undefined) { where.push("isActive = ?"); params.push(filter.isActive ? 1 : 0); }
+  const sql = `SELECT * FROM providerConnections${where.length ? ` WHERE ${where.join(" AND ")}` : ""}`;
+  const rows = db.all(sql, params);
+  const list = rows.map(rowToConn);
+  list.sort((a, b) => (a.priority || 999) - (b.priority || 999));
+  return list;
+}
+
+export async function getProviderConnectionById(id) {
+  const db = await getAdapter();
+  const row = db.get(`SELECT * FROM providerConnections WHERE id = ?`, [id]);
+  return rowToConn(row);
+}
+
+// Internal sync reorder — must be called INSIDE a transaction
+function reorderInTx(db, providerId) {
+  const list = db.all(`SELECT * FROM providerConnections WHERE provider = ?`, [providerId]).map(rowToConn);
+  list.sort((a, b) => {
+    const pDiff = (a.priority || 0) - (b.priority || 0);
+    if (pDiff !== 0) return pDiff;
+    return new Date(b.updatedAt || 0) - new Date(a.updatedAt || 0);
+  });
+  list.forEach((c, i) => {
+    db.run(`UPDATE providerConnections SET priority = ? WHERE id = ?`, [i + 1, c.id]);
+  });
+}
+
+export async function createProviderConnection(data) {
+  const db = await getAdapter();
+  const now = new Date().toISOString();
+  let result;
+
+  db.transaction(() => {
+    const all = db.all(`SELECT * FROM providerConnections WHERE provider = ?`, [data.provider]).map(rowToConn);
+
+    let existing = null;
+    if (data.authType === "oauth" && data.email) {
+      const incomingUsername = data.providerSpecificData?.username;
+      const incomingWs = data.providerSpecificData?.chatgptAccountId;
+      existing = all.find(c => {
+        if (c.authType !== "oauth" || c.email !== data.email) return false;
+
+        // Codex/OpenAI can issue multiple OAuth grants for the same email.
+        // Refresh tokens are rotated single-use; collapsing a new login onto an
+        // existing bare-email row overwrites the first account's token pair and
+        // makes it look "invalid" after adding a second account. Only update an
+        // existing Codex row when both rows expose the same ChatGPT account ID.
+        if (data.provider === "codex") {
+          const existingWs = c.providerSpecificData?.chatgptAccountId;
+          return !!incomingWs && !!existingWs && incomingWs === existingWs;
+        }
+
+        // Workspace providers use workspace ID when both sides have it
+        const existingWs = c.providerSpecificData?.chatgptAccountId;
+        if (incomingWs && existingWs) return incomingWs === existingWs;
+        if (incomingWs && !existingWs) return false;
+        if (!incomingWs && existingWs) return false;
+        // Non-workspace providers: match on (email + username) so cross-IdP
+        // accounts don't overwrite each other. Require username on both sides
+        // — if only one side has it, treat as a distinct identity rather than
+        // collapsing onto the bare-email fallback (which would re-introduce
+        // the cross-IdP overwrite).
+        const existingUsername = c.providerSpecificData?.username;
+        if (incomingUsername && existingUsername) {
+          return incomingUsername === existingUsername;
+        }
+        if (incomingUsername || existingUsername) return false;
+        return true;
+      });
+    } else if (data.authType === "apikey" && data.name) {
+      existing = all.find(c => c.authType === "apikey" && c.name === data.name);
+    }
+    // access_token: never dedup — user manages duplicates manually
+
+    if (existing) {
+      const merged = { ...existing, ...data, updatedAt: now };
+      upsert(db, merged);
+      result = merged;
+      return;
+    }
+
+    let connectionName = data.name || null;
+    if (!connectionName && (data.authType === "oauth" || data.authType === "access_token")) {
+      connectionName = deriveConnectionName(data, data.email || `Account ${all.length + 1}`);
+    }
+    let connectionPriority = data.priority;
+    if (!connectionPriority) {
+      connectionPriority = all.reduce((m, c) => Math.max(m, c.priority || 0), 0) + 1;
+    }
+
+    const conn = {
+      id: uuidv4(),
+      provider: data.provider,
+      authType: data.authType || "oauth",
+      name: connectionName,
+      priority: connectionPriority,
+      isActive: data.isActive !== undefined ? data.isActive : true,
+      createdAt: now,
+      updatedAt: now,
+    };
+    for (const f of OPTIONAL_FIELDS) {
+      if (data[f] !== undefined && data[f] !== null) conn[f] = data[f];
+    }
+    if (data.providerSpecificData && Object.keys(data.providerSpecificData).length > 0) {
+      conn.providerSpecificData = data.providerSpecificData;
+    }
+    if (data.email !== undefined) conn.email = data.email;
+
+    upsert(db, conn);
+    reorderInTx(db, data.provider);
+    result = conn;
+  });
+
+  return result;
+}
+
+// Critical: OAuth refresh token race — atomic merge inside transaction
+export async function updateProviderConnection(id, data) {
+  const db = await getAdapter();
+  let result;
+  db.transaction(() => {
+    const row = db.get(`SELECT * FROM providerConnections WHERE id = ?`, [id]);
+    if (!row) { result = null; return; }
+    const existing = rowToConn(row);
+    const merged = { ...existing, ...data, updatedAt: new Date().toISOString() };
+    upsert(db, merged);
+    if (data.priority !== undefined) reorderInTx(db, existing.provider);
+    result = merged;
+  });
+  return result;
+}
+
+export async function deleteProviderConnection(id) {
+  const db = await getAdapter();
+  let ok = false;
+  db.transaction(() => {
+    const row = db.get(`SELECT provider FROM providerConnections WHERE id = ?`, [id]);
+    if (!row) return;
+    db.run(`DELETE FROM providerConnections WHERE id = ?`, [id]);
+    reorderInTx(db, row.provider);
+    ok = true;
+  });
+  return ok;
+}
+
+export async function deleteProviderConnectionsByProvider(providerId) {
+  const db = await getAdapter();
+  const before = db.get(`SELECT COUNT(*) AS n FROM providerConnections WHERE provider = ?`, [providerId]);
+  db.run(`DELETE FROM providerConnections WHERE provider = ?`, [providerId]);
+  return before?.n || 0;
+}
+
+export async function reorderProviderConnections(providerId) {
+  const db = await getAdapter();
+  db.transaction(() => reorderInTx(db, providerId));
+}
+
+export async function cleanupProviderConnections() {
+  const db = await getAdapter();
+  const fieldsToCheck = [
+    "displayName", "email", "globalPriority", "defaultModel",
+    "accessToken", "refreshToken", "expiresAt", "tokenType",
+    "scope", "projectId", "apiKey", "testStatus",
+    "lastTested", "lastError", "lastErrorAt", "rateLimitedUntil", "expiresIn",
+    "consecutiveUseCount",
+  ];
+  let cleaned = 0;
+  db.transaction(() => {
+    const rows = db.all(`SELECT * FROM providerConnections`);
+    for (const row of rows) {
+      const conn = rowToConn(row);
+      let dirty = false;
+      for (const f of fieldsToCheck) {
+        if (conn[f] === null || conn[f] === undefined) {
+          if (f in conn) { delete conn[f]; cleaned++; dirty = true; }
+        }
+      }
+      if (conn.providerSpecificData && Object.keys(conn.providerSpecificData).length === 0) {
+        delete conn.providerSpecificData;
+        cleaned++;
+        dirty = true;
+      }
+      if (dirty) upsert(db, conn);
+    }
+  });
+  return cleaned;
+}
diff --git a/src/lib/db/repos/disabledModelsRepo.js b/src/lib/db/repos/disabledModelsRepo.js
new file mode 100644
index 0000000..9f1675f
--- /dev/null
+++ b/src/lib/db/repos/disabledModelsRepo.js
@@ -0,0 +1,56 @@
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+
+const SCOPE = "disabledModels";
+
+export async function getDisabledModels() {
+  const db = await getAdapter();
+  const rows = db.all(`SELECT key, value FROM kv WHERE scope = ?`, [SCOPE]);
+  const out = {};
+  for (const r of rows) out[r.key] = parseJson(r.value, []);
+  return out;
+}
+
+export async function getDisabledByProvider(providerAlias) {
+  const db = await getAdapter();
+  const row = db.get(`SELECT value FROM kv WHERE scope = ? AND key = ?`, [SCOPE, providerAlias]);
+  return row ? (parseJson(row.value, []) || []) : [];
+}
+
+// Atomic read-merge-write inside a transaction (no JS yield mid-transaction).
+export async function disableModels(providerAlias, ids) {
+  if (!providerAlias || !Array.isArray(ids)) return;
+  const db = await getAdapter();
+  db.transaction(() => {
+    const row = db.get(`SELECT value FROM kv WHERE scope = ? AND key = ?`, [SCOPE, providerAlias]);
+    const current = row ? (parseJson(row.value, []) || []) : [];
+    const merged = [...new Set([...current, ...ids])];
+    db.run(
+      `INSERT INTO kv(scope, key, value) VALUES(?, ?, ?) ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`,
+      [SCOPE, providerAlias, stringifyJson(merged)]
+    );
+  });
+}
+
+export async function enableModels(providerAlias, ids) {
+  if (!providerAlias) return;
+  const db = await getAdapter();
+  db.transaction(() => {
+    if (!Array.isArray(ids) || ids.length === 0) {
+      db.run(`DELETE FROM kv WHERE scope = ? AND key = ?`, [SCOPE, providerAlias]);
+      return;
+    }
+    const row = db.get(`SELECT value FROM kv WHERE scope = ? AND key = ?`, [SCOPE, providerAlias]);
+    const current = row ? (parseJson(row.value, []) || []) : [];
+    const removeSet = new Set(ids);
+    const next = current.filter((id) => !removeSet.has(id));
+    if (next.length === 0) {
+      db.run(`DELETE FROM kv WHERE scope = ? AND key = ?`, [SCOPE, providerAlias]);
+    } else {
+      db.run(
+        `INSERT INTO kv(scope, key, value) VALUES(?, ?, ?) ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`,
+        [SCOPE, providerAlias, stringifyJson(next)]
+      );
+    }
+  });
+}
diff --git a/src/lib/db/repos/nodesRepo.js b/src/lib/db/repos/nodesRepo.js
new file mode 100644
index 0000000..cd63b5b
--- /dev/null
+++ b/src/lib/db/repos/nodesRepo.js
@@ -0,0 +1,95 @@
+import { v4 as uuidv4 } from "uuid";
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+
+function rowToNode(row) {
+  if (!row) return null;
+  const extra = parseJson(row.data, {});
+  return {
+    ...extra,
+    id: row.id,
+    type: row.type,
+    name: row.name,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function nodeToRow(n) {
+  const { id, type, name, createdAt, updatedAt, ...rest } = n;
+  return {
+    id,
+    type: type ?? null,
+    name: name ?? null,
+    data: stringifyJson(rest),
+    createdAt,
+    updatedAt,
+  };
+}
+
+function upsert(db, n) {
+  const r = nodeToRow(n);
+  db.run(
+    `INSERT INTO providerNodes(id, type, name, data, createdAt, updatedAt)
+     VALUES(?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       type=excluded.type, name=excluded.name, data=excluded.data, updatedAt=excluded.updatedAt`,
+    [r.id, r.type, r.name, r.data, r.createdAt, r.updatedAt]
+  );
+}
+
+export async function getProviderNodes(filter = {}) {
+  const db = await getAdapter();
+  const where = [];
+  const params = [];
+  if (filter.type) { where.push("type = ?"); params.push(filter.type); }
+  const sql = `SELECT * FROM providerNodes${where.length ? ` WHERE ${where.join(" AND ")}` : ""}`;
+  return db.all(sql, params).map(rowToNode);
+}
+
+export async function getProviderNodeById(id) {
+  const db = await getAdapter();
+  return rowToNode(db.get(`SELECT * FROM providerNodes WHERE id = ?`, [id]));
+}
+
+export async function createProviderNode(data) {
+  const db = await getAdapter();
+  const now = new Date().toISOString();
+  const node = {
+    id: data.id || uuidv4(),
+    type: data.type,
+    name: data.name,
+    prefix: data.prefix,
+    apiType: data.apiType,
+    baseUrl: data.baseUrl,
+    createdAt: now,
+    updatedAt: now,
+  };
+  upsert(db, node);
+  return node;
+}
+
+export async function updateProviderNode(id, data) {
+  const db = await getAdapter();
+  let result = null;
+  db.transaction(() => {
+    const row = db.get(`SELECT * FROM providerNodes WHERE id = ?`, [id]);
+    if (!row) return;
+    const merged = { ...rowToNode(row), ...data, updatedAt: new Date().toISOString() };
+    upsert(db, merged);
+    result = merged;
+  });
+  return result;
+}
+
+export async function deleteProviderNode(id) {
+  const db = await getAdapter();
+  let removed = null;
+  db.transaction(() => {
+    const row = db.get(`SELECT * FROM providerNodes WHERE id = ?`, [id]);
+    if (!row) return;
+    removed = rowToNode(row);
+    db.run(`DELETE FROM providerNodes WHERE id = ?`, [id]);
+  });
+  return removed;
+}
diff --git a/src/lib/db/repos/pricingRepo.js b/src/lib/db/repos/pricingRepo.js
new file mode 100644
index 0000000..6467274
--- /dev/null
+++ b/src/lib/db/repos/pricingRepo.js
@@ -0,0 +1,108 @@
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+import { makeKv } from "../helpers/kvStore.js";
+
+const pricingKv = makeKv("pricing");
+const CACHE_TTL_MS = 5000;
+
+let cache = { value: null, expiresAt: 0 };
+
+function invalidate() {
+  cache = { value: null, expiresAt: 0 };
+}
+
+async function getUserPricing() {
+  return await pricingKv.getAll();
+}
+
+export async function getPricing() {
+  const now = Date.now();
+  if (cache.value && cache.expiresAt > now) return cache.value;
+
+  const userPricing = await getUserPricing();
+  const { PROVIDER_PRICING } = await import("open-sse/providers/pricing.js");
+  const merged = {};
+
+  for (const [provider, models] of Object.entries(PROVIDER_PRICING)) {
+    merged[provider] = { ...models };
+    if (userPricing[provider]) {
+      for (const [model, pricing] of Object.entries(userPricing[provider])) {
+        merged[provider][model] = merged[provider][model]
+          ? { ...merged[provider][model], ...pricing }
+          : pricing;
+      }
+    }
+  }
+
+  for (const [provider, models] of Object.entries(userPricing)) {
+    if (!merged[provider]) {
+      merged[provider] = { ...models };
+    } else {
+      for (const [model, pricing] of Object.entries(models)) {
+        if (!merged[provider][model]) merged[provider][model] = pricing;
+      }
+    }
+  }
+
+  cache = { value: merged, expiresAt: now + CACHE_TTL_MS };
+  return merged;
+}
+
+export async function getPricingForModel(provider, model) {
+  if (!model) return null;
+  const userPricing = await getUserPricing();
+  if (provider && userPricing[provider]?.[model]) return userPricing[provider][model];
+  const { getPricingForModel: resolveConst } = await import("open-sse/providers/pricing.js");
+  return resolveConst(provider, model);
+}
+
+// Atomic merge inside transaction (per-provider read-modify-write)
+export async function updatePricing(pricingData) {
+  const db = await getAdapter();
+  db.transaction(() => {
+    for (const [provider, models] of Object.entries(pricingData)) {
+      const row = db.get(`SELECT value FROM kv WHERE scope = 'pricing' AND key = ?`, [provider]);
+      const current = row ? (parseJson(row.value, {}) || {}) : {};
+      const merged = { ...current };
+      for (const [model, pricing] of Object.entries(models)) {
+        merged[model] = pricing;
+      }
+      db.run(
+        `INSERT INTO kv(scope, key, value) VALUES('pricing', ?, ?) ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`,
+        [provider, stringifyJson(merged)]
+      );
+    }
+  });
+  invalidate();
+  return await getUserPricing();
+}
+
+export async function resetPricing(provider, model) {
+  if (!provider) return await getUserPricing();
+  const db = await getAdapter();
+  db.transaction(() => {
+    if (!model) {
+      db.run(`DELETE FROM kv WHERE scope = 'pricing' AND key = ?`, [provider]);
+      return;
+    }
+    const row = db.get(`SELECT value FROM kv WHERE scope = 'pricing' AND key = ?`, [provider]);
+    const current = row ? (parseJson(row.value, {}) || {}) : {};
+    delete current[model];
+    if (Object.keys(current).length === 0) {
+      db.run(`DELETE FROM kv WHERE scope = 'pricing' AND key = ?`, [provider]);
+    } else {
+      db.run(
+        `INSERT INTO kv(scope, key, value) VALUES('pricing', ?, ?) ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`,
+        [provider, stringifyJson(current)]
+      );
+    }
+  });
+  invalidate();
+  return await getUserPricing();
+}
+
+export async function resetAllPricing() {
+  await pricingKv.clear();
+  invalidate();
+  return {};
+}
diff --git a/src/lib/db/repos/proxyPoolsRepo.js b/src/lib/db/repos/proxyPoolsRepo.js
new file mode 100644
index 0000000..9c1535c
--- /dev/null
+++ b/src/lib/db/repos/proxyPoolsRepo.js
@@ -0,0 +1,103 @@
+import { v4 as uuidv4 } from "uuid";
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+
+function rowToPool(row) {
+  if (!row) return null;
+  const extra = parseJson(row.data, {});
+  return {
+    ...extra,
+    id: row.id,
+    isActive: row.isActive === 1 || row.isActive === true,
+    testStatus: row.testStatus,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function poolToRow(p) {
+  const { id, isActive, testStatus, createdAt, updatedAt, ...rest } = p;
+  return {
+    id,
+    isActive: isActive === false ? 0 : 1,
+    testStatus: testStatus ?? null,
+    data: stringifyJson(rest),
+    createdAt,
+    updatedAt,
+  };
+}
+
+function upsert(db, p) {
+  const r = poolToRow(p);
+  db.run(
+    `INSERT INTO proxyPools(id, isActive, testStatus, data, createdAt, updatedAt)
+     VALUES(?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       isActive=excluded.isActive, testStatus=excluded.testStatus,
+       data=excluded.data, updatedAt=excluded.updatedAt`,
+    [r.id, r.isActive, r.testStatus, r.data, r.createdAt, r.updatedAt]
+  );
+}
+
+export async function getProxyPools(filter = {}) {
+  const db = await getAdapter();
+  const where = [];
+  const params = [];
+  if (filter.isActive !== undefined) { where.push("isActive = ?"); params.push(filter.isActive ? 1 : 0); }
+  if (filter.testStatus) { where.push("testStatus = ?"); params.push(filter.testStatus); }
+  const sql = `SELECT * FROM proxyPools${where.length ? ` WHERE ${where.join(" AND ")}` : ""}`;
+  const list = db.all(sql, params).map(rowToPool);
+  list.sort((a, b) => new Date(b.updatedAt || 0) - new Date(a.updatedAt || 0));
+  return list;
+}
+
+export async function getProxyPoolById(id) {
+  const db = await getAdapter();
+  return rowToPool(db.get(`SELECT * FROM proxyPools WHERE id = ?`, [id]));
+}
+
+export async function createProxyPool(data) {
+  const db = await getAdapter();
+  const now = new Date().toISOString();
+  const pool = {
+    id: data.id || uuidv4(),
+    name: data.name,
+    proxyUrl: data.proxyUrl,
+    noProxy: data.noProxy || "",
+    type: data.type || "http",
+    isActive: data.isActive !== undefined ? data.isActive : true,
+    strictProxy: data.strictProxy === true,
+    testStatus: data.testStatus || "unknown",
+    lastTestedAt: data.lastTestedAt || null,
+    lastError: data.lastError || null,
+    createdAt: now,
+    updatedAt: now,
+  };
+  upsert(db, pool);
+  return pool;
+}
+
+export async function updateProxyPool(id, data) {
+  const db = await getAdapter();
+  let result = null;
+  db.transaction(() => {
+    const row = db.get(`SELECT * FROM proxyPools WHERE id = ?`, [id]);
+    if (!row) return;
+    const merged = { ...rowToPool(row), ...data, updatedAt: new Date().toISOString() };
+    upsert(db, merged);
+    result = merged;
+  });
+  return result;
+}
+
+export async function deleteProxyPool(id) {
+  const db = await getAdapter();
+  let removed = null;
+  db.transaction(() => {
+    const row = db.get(`SELECT * FROM proxyPools WHERE id = ?`, [id]);
+    if (!row) return;
+    removed = rowToPool(row);
+    db.run(`DELETE FROM proxyPools WHERE id = ?`, [id]);
+  });
+  return removed;
+}
diff --git a/src/lib/db/repos/requestDetailsRepo.js b/src/lib/db/repos/requestDetailsRepo.js
new file mode 100644
index 0000000..defd294
--- /dev/null
+++ b/src/lib/db/repos/requestDetailsRepo.js
@@ -0,0 +1,207 @@
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+
+const DEFAULT_MAX_RECORDS = 200;
+const DEFAULT_BATCH_SIZE = 20;
+const DEFAULT_FLUSH_INTERVAL_MS = 5000;
+const DEFAULT_MAX_JSON_SIZE = 5 * 1024;
+const CONFIG_CACHE_TTL_MS = 5000;
+
+let cachedConfig = null;
+let cachedConfigTs = 0;
+
+async function getObservabilityConfig() {
+  if (cachedConfig && (Date.now() - cachedConfigTs) < CONFIG_CACHE_TTL_MS) return cachedConfig;
+  try {
+    const { getSettings } = await import("./settingsRepo.js");
+    const settings = await getSettings();
+    const envEnabled = process.env.OBSERVABILITY_ENABLED !== "false";
+    const enabled = typeof settings.enableObservability2 === "boolean"
+      ? settings.enableObservability2
+      : envEnabled;
+    cachedConfig = {
+      enabled,
+      maxRecords: settings.observabilityMaxRecords || parseInt(process.env.OBSERVABILITY_MAX_RECORDS || String(DEFAULT_MAX_RECORDS), 10),
+      batchSize: settings.observabilityBatchSize || parseInt(process.env.OBSERVABILITY_BATCH_SIZE || String(DEFAULT_BATCH_SIZE), 10),
+      flushIntervalMs: settings.observabilityFlushIntervalMs || parseInt(process.env.OBSERVABILITY_FLUSH_INTERVAL_MS || String(DEFAULT_FLUSH_INTERVAL_MS), 10),
+      maxJsonSize: (settings.observabilityMaxJsonSize || parseInt(process.env.OBSERVABILITY_MAX_JSON_SIZE || "5", 10)) * 1024,
+    };
+  } catch {
+    cachedConfig = {
+      enabled: false,
+      maxRecords: DEFAULT_MAX_RECORDS,
+      batchSize: DEFAULT_BATCH_SIZE,
+      flushIntervalMs: DEFAULT_FLUSH_INTERVAL_MS,
+      maxJsonSize: DEFAULT_MAX_JSON_SIZE,
+    };
+  }
+  cachedConfigTs = Date.now();
+  return cachedConfig;
+}
+
+let writeBuffer = [];
+let flushTimer = null;
+let isFlushing = false;
+
+function sanitizeHeaders(headers) {
+  if (!headers || typeof headers !== "object") return {};
+  const sensitiveKeys = ["authorization", "x-api-key", "cookie", "token", "api-key"];
+  const sanitized = { ...headers };
+  for (const key of Object.keys(sanitized)) {
+    if (sensitiveKeys.some((s) => key.toLowerCase().includes(s))) delete sanitized[key];
+  }
+  return sanitized;
+}
+
+function generateDetailId(model) {
+  const timestamp = new Date().toISOString();
+  const random = Math.random().toString(36).substring(2, 8);
+  const modelPart = model ? model.replace(/[^a-zA-Z0-9-]/g, "-") : "unknown";
+  return `${timestamp}-${random}-${modelPart}`;
+}
+
+function truncateField(obj, maxSize) {
+  const str = JSON.stringify(obj || {});
+  if (str.length > maxSize) {
+    return { _truncated: true, _originalSize: str.length, _preview: str.substring(0, 200) };
+  }
+  return obj || {};
+}
+
+async function flushToDatabase() {
+  if (isFlushing) return;
+  if (writeBuffer.length === 0) return;
+  isFlushing = true;
+  try {
+    // Drain entire buffer (loop in case more pushed during await)
+    while (writeBuffer.length > 0) {
+      const items = writeBuffer.splice(0, writeBuffer.length);
+      const db = await getAdapter();
+      const config = await getObservabilityConfig();
+
+      db.transaction(() => {
+        for (const item of items) {
+          if (!item.id) item.id = generateDetailId(item.model);
+          if (!item.timestamp) item.timestamp = new Date().toISOString();
+          if (item.request?.headers) item.request.headers = sanitizeHeaders(item.request.headers);
+
+          const record = {
+            id: item.id,
+            provider: item.provider || null,
+            model: item.model || null,
+            connectionId: item.connectionId || null,
+            timestamp: item.timestamp,
+            status: item.status || null,
+            latency: item.latency || {},
+            tokens: item.tokens || {},
+            request: truncateField(item.request, config.maxJsonSize),
+            providerRequest: truncateField(item.providerRequest, config.maxJsonSize),
+            providerResponse: truncateField(item.providerResponse, config.maxJsonSize),
+            response: truncateField(item.response, config.maxJsonSize),
+            pxpipe: item.pxpipe || undefined,
+          };
+
+          db.run(
+            `INSERT INTO requestDetails(id, timestamp, provider, model, connectionId, status, data) VALUES(?, ?, ?, ?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET timestamp = excluded.timestamp, provider = excluded.provider, model = excluded.model, connectionId = excluded.connectionId, status = excluded.status, data = excluded.data`,
+            [record.id, record.timestamp, record.provider, record.model, record.connectionId, record.status, stringifyJson(record)]
+          );
+        }
+
+        const cnt = db.get(`SELECT COUNT(*) as c FROM requestDetails`);
+        if (cnt && cnt.c > config.maxRecords) {
+          db.run(
+            `DELETE FROM requestDetails WHERE id IN (SELECT id FROM requestDetails ORDER BY timestamp ASC LIMIT ?)`,
+            [cnt.c - config.maxRecords]
+          );
+        }
+      });
+    }
+  } catch (e) {
+    console.error("[requestDetailsRepo] Batch write failed:", e);
+  } finally {
+    isFlushing = false;
+  }
+}
+
+export async function saveRequestDetail(detail) {
+  const config = await getObservabilityConfig();
+  if (!config.enabled) return;
+
+  writeBuffer.push(detail);
+
+  // Trigger immediate flush if batch threshold reached.
+  // flushToDatabase() drains entire buffer in a loop, so all pushes during await are persisted.
+  if (writeBuffer.length >= config.batchSize) {
+    if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+    flushToDatabase().catch((e) => console.error("[requestDetailsRepo] flush err:", e));
+  } else if (!flushTimer) {
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      flushToDatabase().catch(() => {});
+    }, config.flushIntervalMs);
+  }
+}
+
+export async function getRequestDetails(filter = {}) {
+  const db = await getAdapter();
+  const conds = [];
+  const params = [];
+
+  if (filter.provider) { conds.push("provider = ?"); params.push(filter.provider); }
+  if (filter.model) { conds.push("model = ?"); params.push(filter.model); }
+  if (filter.connectionId) { conds.push("connectionId = ?"); params.push(filter.connectionId); }
+  if (filter.status) { conds.push("status = ?"); params.push(filter.status); }
+  if (filter.startDate) { conds.push("timestamp >= ?"); params.push(new Date(filter.startDate).toISOString()); }
+  if (filter.endDate) { conds.push("timestamp <= ?"); params.push(new Date(filter.endDate).toISOString()); }
+
+  const where = conds.length ? `WHERE ${conds.join(" AND ")}` : "";
+  const cntRow = db.get(`SELECT COUNT(*) as c FROM requestDetails ${where}`, params);
+  const totalItems = cntRow ? cntRow.c : 0;
+
+  const page = filter.page || 1;
+  const pageSize = filter.pageSize || 50;
+  const totalPages = Math.ceil(totalItems / pageSize);
+  const offset = (page - 1) * pageSize;
+
+  const rows = db.all(
+    `SELECT data FROM requestDetails ${where} ORDER BY timestamp DESC LIMIT ? OFFSET ?`,
+    [...params, pageSize, offset]
+  );
+  const details = rows.map((r) => parseJson(r.data, {}));
+
+  return {
+    details,
+    pagination: { page, pageSize, totalItems, totalPages, hasNext: page < totalPages, hasPrev: page > 1 },
+  };
+}
+
+export async function getDistinctProviders() {
+  const db = await getAdapter();
+  const rows = db.all(`SELECT DISTINCT provider FROM requestDetails WHERE provider IS NOT NULL ORDER BY provider ASC`);
+  return rows.map((r) => r.provider);
+}
+
+export async function getRequestDetailById(id) {
+  const db = await getAdapter();
+  const row = db.get(`SELECT data FROM requestDetails WHERE id = ?`, [id]);
+  return row ? parseJson(row.data, null) : null;
+}
+
+const _shutdownHandler = async () => {
+  if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+  if (writeBuffer.length > 0) await flushToDatabase();
+};
+
+function ensureShutdownHandler() {
+  process.off("beforeExit", _shutdownHandler);
+  process.off("SIGINT", _shutdownHandler);
+  process.off("SIGTERM", _shutdownHandler);
+  process.off("exit", _shutdownHandler);
+
+  process.on("beforeExit", _shutdownHandler);
+  process.on("SIGINT", _shutdownHandler);
+  process.on("SIGTERM", _shutdownHandler);
+  process.on("exit", _shutdownHandler);
+}
+
+ensureShutdownHandler();
diff --git a/src/lib/db/repos/settingsRepo.js b/src/lib/db/repos/settingsRepo.js
new file mode 100644
index 0000000..7b147e1
--- /dev/null
+++ b/src/lib/db/repos/settingsRepo.js
@@ -0,0 +1,114 @@
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+
+const DEFAULT_MITM_ROUTER_BASE = "http://localhost:20128";
+const DEFAULT_HEADROOM_URL = process.env.HEADROOM_URL || "http://localhost:8787";
+
+const DEFAULT_SETTINGS = {
+  cloudEnabled: false,
+  tunnelEnabled: false,
+  tunnelUrl: "",
+  tunnelProvider: "cloudflare",
+  tailscaleEnabled: false,
+  tailscaleUrl: "",
+  stickyRoundRobinLimit: 3,
+  providerStrategies: {},
+  comboStrategy: "fallback",
+  comboStickyRoundRobinLimit: 1,
+  comboStrategies: {},
+  requireLogin: true,
+  tunnelDashboardAccess: true,
+  authMode: "password",
+  oidcIssuerUrl: "",
+  oidcClientId: "",
+  oidcClientSecret: "",
+  oidcScopes: "openid profile email",
+  oidcLoginLabel: "Sign in with OIDC",
+  enableObservability: true,
+  observabilityMaxRecords: 1000,
+  observabilityBatchSize: 20,
+  observabilityFlushIntervalMs: 5000,
+  observabilityMaxJsonSize: 5,
+  outboundProxyEnabled: false,
+  outboundProxyUrl: "",
+  outboundNoProxy: "",
+  mitmRouterBaseUrl: DEFAULT_MITM_ROUTER_BASE,
+  dnsToolEnabled: {},
+  rtkEnabled: true,
+  headroomEnabled: false,
+  headroomUrl: DEFAULT_HEADROOM_URL,
+  headroomCompressUserMessages: false,
+  cavemanEnabled: false,
+  cavemanLevel: "full",
+  ponytailEnabled: false,
+  ponytailLevel: "full",
+  pxpipeEnabled: false,
+  pxpipeAutoInstall: true,
+  pxpipeMinChars: 25000,
+  pxpipeTimeoutMs: 15000,
+};
+
+async function readRaw() {
+  const db = await getAdapter();
+  const row = db.get(`SELECT data FROM settings WHERE id = 1`);
+  return row ? parseJson(row.data, {}) : {};
+}
+
+// Merge raw settings with defaults; backward-compat for missing keys
+function mergeWithDefaults(raw) {
+  const merged = { ...DEFAULT_SETTINGS, ...(raw || {}) };
+  for (const [key, defVal] of Object.entries(DEFAULT_SETTINGS)) {
+    if (merged[key] === undefined) {
+      if (
+        key === "outboundProxyEnabled" &&
+        typeof merged.outboundProxyUrl === "string" &&
+        merged.outboundProxyUrl.trim()
+      ) {
+        merged[key] = true;
+      } else {
+        merged[key] = defVal;
+      }
+    }
+  }
+  return merged;
+}
+
+export async function getSettings() {
+  const raw = await readRaw();
+  return mergeWithDefaults(raw);
+}
+
+// Atomic read-merge-write inside transaction (prevents losing concurrent updates)
+export async function updateSettings(updates) {
+  const db = await getAdapter();
+  let next;
+  db.transaction(() => {
+    const row = db.get(`SELECT data FROM settings WHERE id = 1`);
+    const current = row ? parseJson(row.data, {}) : {};
+    next = { ...current, ...updates };
+    db.run(
+      `INSERT INTO settings(id, data) VALUES(1, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data`,
+      [stringifyJson(next)]
+    );
+  });
+  return mergeWithDefaults(next);
+}
+
+export async function isCloudEnabled() {
+  const settings = await getSettings();
+  return settings.cloudEnabled === true;
+}
+
+export async function getCloudUrl() {
+  const settings = await getSettings();
+  return (
+    settings.cloudUrl ||
+    process.env.CLOUD_URL ||
+    process.env.NEXT_PUBLIC_CLOUD_URL ||
+    ""
+  );
+}
+
+export async function exportSettings() {
+  return await readRaw();
+}
diff --git a/src/lib/db/repos/usageRepo.js b/src/lib/db/repos/usageRepo.js
new file mode 100644
index 0000000..6b1966c
--- /dev/null
+++ b/src/lib/db/repos/usageRepo.js
@@ -0,0 +1,772 @@
+import { EventEmitter } from "events";
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+import { getMeta, setMeta } from "../helpers/metaStore.js";
+
+function maskApiKey(key) {
+  if (!key || typeof key !== "string") return null;
+  if (key.length <= 8) return key.charAt(0) + "***";
+  return key.slice(0, 8) + "***";
+}
+
+const PENDING_TIMEOUT_MS = 60 * 1000;
+const RING_CAP = 50;
+const CONN_CACHE_TTL_MS = 30 * 1000;
+const PERIOD_MS = { "24h": 86400000, "7d": 604800000, "30d": 2592000000, "60d": 5184000000 };
+
+// In-memory state shared across Next.js modules
+if (!global._pendingRequests) global._pendingRequests = { byModel: {}, byAccount: {} };
+if (!global._lastErrorProvider) global._lastErrorProvider = { provider: "", ts: 0 };
+if (!global._statsEmitter) {
+  global._statsEmitter = new EventEmitter();
+  global._statsEmitter.setMaxListeners(50);
+}
+if (!global._pendingTimers) global._pendingTimers = {};
+if (!global._recentRing) global._recentRing = { items: [], initialized: false };
+if (!global._connectionMapCache) global._connectionMapCache = { map: {}, ts: 0 };
+if (!global._statsEmitTimers) global._statsEmitTimers = { pending: null, update: null };
+
+const pendingRequests = global._pendingRequests;
+const lastErrorProvider = global._lastErrorProvider;
+const pendingTimers = global._pendingTimers;
+const recentRing = global._recentRing;
+const connCache = global._connectionMapCache;
+const statsEmitTimers = global._statsEmitTimers;
+
+export const statsEmitter = global._statsEmitter;
+
+function scheduleStatsEvent(event, delayMs = 150) {
+  const key = event === "update" ? "update" : "pending";
+  if (statsEmitTimers[key]) return;
+  statsEmitTimers[key] = setTimeout(() => {
+    statsEmitTimers[key] = null;
+    statsEmitter.emit(event);
+  }, delayMs);
+  statsEmitTimers[key]?.unref?.();
+}
+
+function getLocalDateKey(timestamp) {
+  const d = timestamp ? new Date(timestamp) : new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+function addToCounter(target, key, values) {
+  if (!target[key]) target[key] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0 };
+  target[key].requests += values.requests || 1;
+  target[key].promptTokens += values.promptTokens || 0;
+  target[key].completionTokens += values.completionTokens || 0;
+  target[key].cachedTokens += values.cachedTokens || 0;
+  target[key].cost += values.cost || 0;
+  if (values.meta) Object.assign(target[key], values.meta);
+}
+
+function aggregateEntryToDay(day, entry) {
+  const promptTokens = entry.tokens?.prompt_tokens || entry.tokens?.input_tokens || 0;
+  const completionTokens = entry.tokens?.completion_tokens || entry.tokens?.output_tokens || 0;
+  const cachedTokens = entry.tokens?.cached_tokens || entry.tokens?.cache_read_input_tokens || 0;
+  const cost = entry.cost || 0;
+  const vals = { promptTokens, completionTokens, cachedTokens, cost };
+
+  day.requests = (day.requests || 0) + 1;
+  day.promptTokens = (day.promptTokens || 0) + promptTokens;
+  day.completionTokens = (day.completionTokens || 0) + completionTokens;
+  day.cachedTokens = (day.cachedTokens || 0) + cachedTokens;
+  day.cost = (day.cost || 0) + cost;
+
+  day.byProvider ||= {};
+  day.byModel ||= {};
+  day.byAccount ||= {};
+  day.byApiKey ||= {};
+  day.byEndpoint ||= {};
+
+  if (entry.provider) addToCounter(day.byProvider, entry.provider, vals);
+
+  const modelKey = entry.provider ? `${entry.model}|${entry.provider}` : entry.model;
+  addToCounter(day.byModel, modelKey, { ...vals, meta: { rawModel: entry.model, provider: entry.provider } });
+
+  if (entry.connectionId) {
+    addToCounter(day.byAccount, entry.connectionId, { ...vals, meta: { rawModel: entry.model, provider: entry.provider } });
+  }
+
+  const apiKeyVal = entry.apiKey && typeof entry.apiKey === "string" ? entry.apiKey : "local-no-key";
+  const akModelKey = `${apiKeyVal}|${entry.model}|${entry.provider || "unknown"}`;
+  addToCounter(day.byApiKey, akModelKey, { ...vals, meta: { rawModel: entry.model, provider: entry.provider, apiKey: entry.apiKey || null } });
+
+  const endpoint = entry.endpoint || "Unknown";
+  const epKey = `${endpoint}|${entry.model}|${entry.provider || "unknown"}`;
+  addToCounter(day.byEndpoint, epKey, { ...vals, meta: { endpoint, rawModel: entry.model, provider: entry.provider } });
+}
+
+function pushToRing(entry) {
+  recentRing.items.push(entry);
+  if (recentRing.items.length > RING_CAP) {
+    recentRing.items = recentRing.items.slice(-RING_CAP);
+  }
+}
+
+async function getConnectionMapCached() {
+  if (Date.now() - connCache.ts < CONN_CACHE_TTL_MS) return connCache.map;
+  try {
+    const { getProviderConnections } = await import("./connectionsRepo.js");
+    const all = await getProviderConnections();
+    const map = {};
+    for (const c of all) map[c.id] = c.name || c.email || c.id;
+    connCache.map = map;
+    connCache.ts = Date.now();
+  } catch {}
+  return connCache.map;
+}
+
+async function ensureRingInitialized() {
+  if (recentRing.initialized) return;
+  recentRing.initialized = true;
+  try {
+    const db = await getAdapter();
+    const rows = db.all(`SELECT timestamp, provider, model, connectionId, apiKey, endpoint, cost, status, tokens FROM usageHistory ORDER BY id DESC LIMIT ?`, [RING_CAP]);
+    recentRing.items = rows.reverse().map((r) => ({
+      timestamp: r.timestamp, provider: r.provider, model: r.model, connectionId: r.connectionId,
+      apiKey: r.apiKey, endpoint: r.endpoint, cost: r.cost, status: r.status,
+      tokens: parseJson(r.tokens, {}),
+    }));
+  } catch {}
+}
+
+async function calculateCost(provider, model, tokens) {
+  if (!tokens || !provider || !model) return 0;
+  try {
+    const { getPricingForModel } = await import("./pricingRepo.js");
+    const pricing = await getPricingForModel(provider, model);
+    if (!pricing) return 0;
+
+    // Delegate the actual math to the single source of truth (avoids the two
+    // copies drifting apart — see open-sse/providers/pricing.js for the
+    // cache-inclusive prompt_tokens convention this assumes).
+    const { calculateCostFromTokens } = await import("open-sse/providers/pricing.js");
+    return calculateCostFromTokens(tokens, pricing);
+  } catch (e) {
+    console.error("Error calculating cost:", e);
+    return 0;
+  }
+}
+
+export function trackPendingRequest(model, provider, connectionId, started, error = false) {
+  const modelKey = provider ? `${model} (${provider})` : model;
+  const timerKey = `${connectionId}|${modelKey}`;
+
+  if (!pendingRequests.byModel[modelKey]) pendingRequests.byModel[modelKey] = 0;
+  pendingRequests.byModel[modelKey] = Math.max(0, pendingRequests.byModel[modelKey] + (started ? 1 : -1));
+  if (pendingRequests.byModel[modelKey] === 0) delete pendingRequests.byModel[modelKey];
+
+  if (connectionId) {
+    if (!pendingRequests.byAccount[connectionId]) pendingRequests.byAccount[connectionId] = {};
+    if (!pendingRequests.byAccount[connectionId][modelKey]) pendingRequests.byAccount[connectionId][modelKey] = 0;
+    pendingRequests.byAccount[connectionId][modelKey] = Math.max(0, pendingRequests.byAccount[connectionId][modelKey] + (started ? 1 : -1));
+    if (pendingRequests.byAccount[connectionId][modelKey] === 0) {
+      delete pendingRequests.byAccount[connectionId][modelKey];
+      if (Object.keys(pendingRequests.byAccount[connectionId]).length === 0) {
+        delete pendingRequests.byAccount[connectionId];
+      }
+    }
+  }
+
+  if (started) {
+    clearTimeout(pendingTimers[timerKey]);
+    pendingTimers[timerKey] = setTimeout(() => {
+      delete pendingTimers[timerKey];
+      if (pendingRequests.byModel[modelKey] > 0) pendingRequests.byModel[modelKey] = 0;
+      if (connectionId && pendingRequests.byAccount[connectionId]?.[modelKey] > 0) {
+        pendingRequests.byAccount[connectionId][modelKey] = 0;
+      }
+      scheduleStatsEvent("pending");
+    }, PENDING_TIMEOUT_MS);
+  } else {
+    clearTimeout(pendingTimers[timerKey]);
+    delete pendingTimers[timerKey];
+  }
+
+  if (!started && error && provider) {
+    lastErrorProvider.provider = provider.toLowerCase();
+    lastErrorProvider.ts = Date.now();
+  }
+
+  // [PENDING] console line removed; lifecycle is visible via "▶" and "📊 done" lines
+  scheduleStatsEvent("pending");
+}
+
+export async function getActiveRequests() {
+  const activeRequests = [];
+  const connectionMap = await getConnectionMapCached();
+
+  for (const [connectionId, models] of Object.entries(pendingRequests.byAccount)) {
+    for (const [modelKey, count] of Object.entries(models)) {
+      if (count > 0) {
+        const accountName = connectionMap[connectionId] || `Account ${connectionId.slice(0, 8)}...`;
+        const match = modelKey.match(/^(.*) \((.*)\)$/);
+        activeRequests.push({
+          model: match ? match[1] : modelKey,
+          provider: match ? match[2] : "unknown",
+          account: accountName, count,
+        });
+      }
+    }
+  }
+
+  await ensureRingInitialized();
+  const seen = new Set();
+  const recentRequests = [...recentRing.items]
+    .sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp))
+    .map((e) => {
+      const t = e.tokens || {};
+      return {
+        timestamp: e.timestamp, model: e.model, provider: e.provider || "",
+        promptTokens: t.prompt_tokens || t.input_tokens || 0,
+        completionTokens: t.completion_tokens || t.output_tokens || 0,
+        status: e.status || "ok",
+      };
+    })
+    .filter((e) => {
+      if (e.promptTokens === 0 && e.completionTokens === 0) return false;
+      const minute = e.timestamp ? e.timestamp.slice(0, 16) : "";
+      const key = `${e.model}|${e.provider}|${e.promptTokens}|${e.completionTokens}|${minute}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .slice(0, 20);
+
+  const errorProvider = (Date.now() - lastErrorProvider.ts < 10000) ? lastErrorProvider.provider : "";
+  return { activeRequests, recentRequests, errorProvider };
+}
+
+export async function saveRequestUsage(entry) {
+  try {
+    const db = await getAdapter();
+
+    if (!entry.timestamp) entry.timestamp = new Date().toISOString();
+    entry.cost = await calculateCost(entry.provider, entry.model, entry.tokens);
+
+    const tokens = entry.tokens || {};
+    const promptTokens = tokens.prompt_tokens || tokens.input_tokens || 0;
+    const completionTokens = tokens.completion_tokens || tokens.output_tokens || 0;
+
+    let inserted = false;
+
+    // All 3 writes (history insert, daily upsert, lifetime counter) in ONE transaction.
+    // better-sqlite3 is sync → no JS yield mid-transaction → no race in same process.
+    db.transaction(() => {
+      const existing = db.get(
+        `SELECT id, endpoint FROM usageHistory
+         WHERE timestamp = ?
+           AND COALESCE(provider, '') = COALESCE(?, '')
+           AND COALESCE(model, '') = COALESCE(?, '')
+           AND COALESCE(connectionId, '') = COALESCE(?, '')
+           AND COALESCE(apiKey, '') = COALESCE(?, '')
+           AND promptTokens = ?
+           AND completionTokens = ?
+         ORDER BY id DESC LIMIT 1`,
+        [
+          entry.timestamp, entry.provider || null, entry.model || null,
+          entry.connectionId || null, entry.apiKey || null,
+          promptTokens, completionTokens,
+        ]
+      );
+
+      if (existing) {
+        if (!existing.endpoint && entry.endpoint) {
+          db.run(`UPDATE usageHistory SET endpoint = ? WHERE id = ?`, [entry.endpoint, existing.id]);
+        }
+        return;
+      }
+
+      db.run(
+        `INSERT INTO usageHistory(timestamp, provider, model, connectionId, apiKey, endpoint, promptTokens, completionTokens, cost, status, tokens, meta) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          entry.timestamp, entry.provider || null, entry.model || null,
+          entry.connectionId || null, entry.apiKey || null, entry.endpoint || null,
+          promptTokens, completionTokens, entry.cost || 0, entry.status || "ok",
+          stringifyJson(tokens), stringifyJson({}),
+        ]
+      );
+
+      const dateKey = getLocalDateKey(entry.timestamp);
+      const row = db.get(`SELECT data FROM usageDaily WHERE dateKey = ?`, [dateKey]);
+      const day = row ? parseJson(row.data, {}) : {
+        requests: 0, promptTokens: 0, completionTokens: 0, cost: 0,
+        byProvider: {}, byModel: {}, byAccount: {}, byApiKey: {}, byEndpoint: {},
+      };
+      aggregateEntryToDay(day, entry);
+      db.run(`INSERT INTO usageDaily(dateKey, data) VALUES(?, ?) ON CONFLICT(dateKey) DO UPDATE SET data = excluded.data`, [dateKey, stringifyJson(day)]);
+
+      // Atomic counter increment in same transaction
+      const cur = db.get(`SELECT value FROM _meta WHERE key = 'totalRequestsLifetime'`);
+      const next = (cur ? parseInt(cur.value, 10) : 0) + 1;
+      db.run(`INSERT INTO _meta(key, value) VALUES('totalRequestsLifetime', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`, [String(next)]);
+      inserted = true;
+    });
+
+    if (inserted) {
+      pushToRing(entry);
+      scheduleStatsEvent("update", 250);
+    }
+  } catch (e) {
+    console.error("Failed to save usage stats:", e);
+  }
+}
+
+export async function getUsageHistory(filter = {}) {
+  const db = await getAdapter();
+  const conds = [];
+  const params = [];
+
+  if (filter.provider) { conds.push("provider = ?"); params.push(filter.provider); }
+  if (filter.model) { conds.push("model = ?"); params.push(filter.model); }
+  if (filter.startDate) { conds.push("timestamp >= ?"); params.push(new Date(filter.startDate).toISOString()); }
+  if (filter.endDate) { conds.push("timestamp <= ?"); params.push(new Date(filter.endDate).toISOString()); }
+
+  const where = conds.length ? `WHERE ${conds.join(" AND ")}` : "";
+  const rows = db.all(`SELECT timestamp, provider, model, connectionId, apiKey, endpoint, cost, status, tokens FROM usageHistory ${where} ORDER BY id ASC`, params);
+
+  return rows.map((r) => ({
+    timestamp: r.timestamp, provider: r.provider, model: r.model,
+    connectionId: r.connectionId, apiKeyMasked: maskApiKey(r.apiKey), endpoint: r.endpoint,
+    cost: r.cost, status: r.status, tokens: parseJson(r.tokens, {}),
+  }));
+}
+
+function loadDaysInRange(adapter, maxDays) {
+  if (maxDays == null) {
+    return adapter.all(`SELECT dateKey, data FROM usageDaily`);
+  }
+  const today = new Date();
+  const cutoff = new Date(today.getFullYear(), today.getMonth(), today.getDate() - maxDays + 1);
+  const cutoffKey = `${cutoff.getFullYear()}-${String(cutoff.getMonth() + 1).padStart(2, "0")}-${String(cutoff.getDate()).padStart(2, "0")}`;
+  return adapter.all(`SELECT dateKey, data FROM usageDaily WHERE dateKey >= ?`, [cutoffKey]);
+}
+
+export async function getUsageStats(period = "all") {
+  const db = await getAdapter();
+
+  const [{ getProviderConnections }, { getApiKeys }, { getProviderNodes }] = await Promise.all([
+    import("./connectionsRepo.js"),
+    import("./apiKeysRepo.js"),
+    import("./nodesRepo.js"),
+  ]);
+
+  let allConnections = [];
+  try { allConnections = await getProviderConnections(); } catch {}
+  const connectionMap = {};
+  for (const c of allConnections) connectionMap[c.id] = c.name || c.email || c.id;
+
+  const providerNodeNameMap = {};
+  try {
+    const nodes = await getProviderNodes();
+    for (const n of nodes) if (n.id && n.name) providerNodeNameMap[n.id] = n.name;
+  } catch {}
+
+  let allApiKeys = [];
+  try { allApiKeys = await getApiKeys(); } catch {}
+  const apiKeyMap = {};
+  for (const k of allApiKeys) apiKeyMap[k.key] = { name: k.name, id: k.id, createdAt: k.createdAt };
+
+  // recentRequests from live history (last 100 entries enough for 20 deduped)
+  const recentRows = db.all(`SELECT timestamp, provider, model, tokens, status FROM usageHistory ORDER BY id DESC LIMIT 100`);
+  const seen = new Set();
+  const recentRequests = recentRows
+    .map((r) => {
+      const t = parseJson(r.tokens, {}) || {};
+      return {
+        timestamp: r.timestamp, model: r.model, provider: r.provider || "",
+        promptTokens: t.prompt_tokens || t.input_tokens || 0,
+        completionTokens: t.completion_tokens || t.output_tokens || 0,
+        cachedTokens: t.cached_tokens || t.cache_read_input_tokens || 0,
+        status: r.status || "ok",
+      };
+    })
+    .filter((e) => {
+      if (e.promptTokens === 0 && e.completionTokens === 0) return false;
+      const minute = e.timestamp ? e.timestamp.slice(0, 16) : "";
+      const key = `${e.model}|${e.provider}|${e.promptTokens}|${e.completionTokens}|${minute}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .slice(0, 20);
+
+  const stats = {
+    totalRequests: 0,
+    totalPromptTokens: 0, totalCompletionTokens: 0, totalCachedTokens: 0, totalCost: 0,
+    byProvider: {}, byModel: {}, byAccount: {}, byApiKey: {}, byEndpoint: {},
+    last10Minutes: [],
+    pending: pendingRequests,
+    activeRequests: [],
+    recentRequests,
+    errorProvider: (Date.now() - lastErrorProvider.ts < 10000) ? lastErrorProvider.provider : "",
+  };
+
+  // Active requests
+  for (const [connectionId, models] of Object.entries(pendingRequests.byAccount)) {
+    for (const [modelKey, count] of Object.entries(models)) {
+      if (count > 0) {
+        const accountName = connectionMap[connectionId] || `Account ${connectionId.slice(0, 8)}...`;
+        const match = modelKey.match(/^(.*) \((.*)\)$/);
+        stats.activeRequests.push({
+          model: match ? match[1] : modelKey,
+          provider: match ? match[2] : "unknown",
+          account: accountName, count,
+        });
+      }
+    }
+  }
+
+  // last10Minutes — query 10min window
+  const now = new Date();
+  const currentMinuteStart = new Date(Math.floor(now.getTime() / 60000) * 60000);
+  const tenMinutesAgo = new Date(currentMinuteStart.getTime() - 9 * 60 * 1000);
+  const bucketMap = {};
+  for (let i = 0; i < 10; i++) {
+    const ts = currentMinuteStart.getTime() - (9 - i) * 60 * 1000;
+    bucketMap[ts] = { requests: 0, promptTokens: 0, completionTokens: 0, cost: 0 };
+    stats.last10Minutes.push(bucketMap[ts]);
+  }
+  const recent10 = db.all(
+    `SELECT timestamp, promptTokens, completionTokens, cost FROM usageHistory WHERE timestamp >= ? AND timestamp <= ?`,
+    [tenMinutesAgo.toISOString(), now.toISOString()]
+  );
+  for (const r of recent10) {
+    const tt = new Date(r.timestamp).getTime();
+    const minuteStart = Math.floor(tt / 60000) * 60000;
+    if (bucketMap[minuteStart]) {
+      bucketMap[minuteStart].requests++;
+      bucketMap[minuteStart].promptTokens += r.promptTokens || 0;
+      bucketMap[minuteStart].completionTokens += r.completionTokens || 0;
+      bucketMap[minuteStart].cost += r.cost || 0;
+    }
+  }
+
+  const useDailySummary = period !== "24h" && period !== "today";
+
+  if (useDailySummary) {
+    const periodDays = { "7d": 7, "30d": 30, "60d": 60 };
+    const maxDays = periodDays[period] || null;
+    const dayRows = loadDaysInRange(db, maxDays);
+
+    for (const dr of dayRows) {
+      const dateKey = dr.dateKey;
+      const day = parseJson(dr.data, {});
+      stats.totalPromptTokens += day.promptTokens || 0;
+      stats.totalCompletionTokens += day.completionTokens || 0;
+      stats.totalCachedTokens += day.cachedTokens || 0;
+      stats.totalCost += day.cost || 0;
+
+      for (const [prov, p] of Object.entries(day.byProvider || {})) {
+        if (!stats.byProvider[prov]) stats.byProvider[prov] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0 };
+        stats.byProvider[prov].requests += p.requests || 0;
+        stats.byProvider[prov].promptTokens += p.promptTokens || 0;
+        stats.byProvider[prov].completionTokens += p.completionTokens || 0;
+        stats.byProvider[prov].cachedTokens += p.cachedTokens || 0;
+        stats.byProvider[prov].cost += p.cost || 0;
+      }
+
+      for (const [mk, m] of Object.entries(day.byModel || {})) {
+        const rawModel = m.rawModel || mk.split("|")[0];
+        const provider = m.provider || mk.split("|")[1] || "";
+        const statsKey = provider ? `${rawModel} (${provider})` : rawModel;
+        const providerDisplayName = providerNodeNameMap[provider] || provider;
+        if (!stats.byModel[statsKey]) {
+          stats.byModel[statsKey] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0, rawModel, provider: providerDisplayName, lastUsed: dateKey };
+        }
+        stats.byModel[statsKey].requests += m.requests || 0;
+        stats.byModel[statsKey].promptTokens += m.promptTokens || 0;
+        stats.byModel[statsKey].completionTokens += m.completionTokens || 0;
+        stats.byModel[statsKey].cachedTokens += m.cachedTokens || 0;
+        stats.byModel[statsKey].cost += m.cost || 0;
+        if (dateKey > (stats.byModel[statsKey].lastUsed || "")) stats.byModel[statsKey].lastUsed = dateKey;
+      }
+
+      for (const [connId, a] of Object.entries(day.byAccount || {})) {
+        const accountName = connectionMap[connId] || `Account ${connId.slice(0, 8)}...`;
+        const rawModel = a.rawModel || "";
+        const provider = a.provider || "";
+        const providerDisplayName = providerNodeNameMap[provider] || provider;
+        const accountKey = `${rawModel} (${provider} - ${accountName})`;
+        if (!stats.byAccount[accountKey]) {
+          stats.byAccount[accountKey] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0, rawModel, provider: providerDisplayName, connectionId: connId, accountName, lastUsed: dateKey };
+        }
+        stats.byAccount[accountKey].requests += a.requests || 0;
+        stats.byAccount[accountKey].promptTokens += a.promptTokens || 0;
+        stats.byAccount[accountKey].completionTokens += a.completionTokens || 0;
+        stats.byAccount[accountKey].cachedTokens += a.cachedTokens || 0;
+        stats.byAccount[accountKey].cost += a.cost || 0;
+        if (dateKey > (stats.byAccount[accountKey].lastUsed || "")) stats.byAccount[accountKey].lastUsed = dateKey;
+      }
+
+      for (const [akKey, ak] of Object.entries(day.byApiKey || {})) {
+        const rawModel = ak.rawModel || "";
+        const provider = ak.provider || "";
+        const providerDisplayName = providerNodeNameMap[provider] || provider;
+        const apiKeyVal = ak.apiKey;
+        const keyInfo = apiKeyVal ? apiKeyMap[apiKeyVal] : null;
+        const keyName = keyInfo?.name || (apiKeyVal ? apiKeyVal.slice(0, 8) + "..." : "Local (No API Key)");
+        const apiKeyMasked = maskApiKey(apiKeyVal);
+        const apiKeyKey = apiKeyMasked || "local-no-key";
+        if (!stats.byApiKey[akKey]) {
+          stats.byApiKey[akKey] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0, rawModel, provider: providerDisplayName, apiKeyMasked, keyName, apiKeyKey, lastUsed: dateKey };
+        }
+        stats.byApiKey[akKey].requests += ak.requests || 0;
+        stats.byApiKey[akKey].promptTokens += ak.promptTokens || 0;
+        stats.byApiKey[akKey].completionTokens += ak.completionTokens || 0;
+        stats.byApiKey[akKey].cachedTokens += ak.cachedTokens || 0;
+        stats.byApiKey[akKey].cost += ak.cost || 0;
+        if (dateKey > (stats.byApiKey[akKey].lastUsed || "")) stats.byApiKey[akKey].lastUsed = dateKey;
+      }
+
+      for (const [epKey, ep] of Object.entries(day.byEndpoint || {})) {
+        const endpoint = ep.endpoint || epKey.split("|")[0] || "Unknown";
+        const rawModel = ep.rawModel || "";
+        const provider = ep.provider || "";
+        const providerDisplayName = providerNodeNameMap[provider] || provider;
+        if (!stats.byEndpoint[epKey]) {
+          stats.byEndpoint[epKey] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0, endpoint, rawModel, provider: providerDisplayName, lastUsed: dateKey };
+        }
+        stats.byEndpoint[epKey].requests += ep.requests || 0;
+        stats.byEndpoint[epKey].promptTokens += ep.promptTokens || 0;
+        stats.byEndpoint[epKey].completionTokens += ep.completionTokens || 0;
+        stats.byEndpoint[epKey].cachedTokens += ep.cachedTokens || 0;
+        stats.byEndpoint[epKey].cost += ep.cost || 0;
+        if (dateKey > (stats.byEndpoint[epKey].lastUsed || "")) stats.byEndpoint[epKey].lastUsed = dateKey;
+      }
+    }
+
+    // Overlay precise lastUsed timestamps from history
+    const overlayCutoff = maxDays ? Date.now() - maxDays * 86400000 : 0;
+    const histRows = db.all(
+      `SELECT timestamp, provider, model, connectionId, apiKey, endpoint FROM usageHistory WHERE timestamp >= ?`,
+      [new Date(overlayCutoff).toISOString()]
+    );
+    for (const e of histRows) {
+      const ts = e.timestamp;
+      const modelKey = e.provider ? `${e.model} (${e.provider})` : e.model;
+      if (stats.byModel[modelKey] && new Date(ts) > new Date(stats.byModel[modelKey].lastUsed)) stats.byModel[modelKey].lastUsed = ts;
+
+      if (e.connectionId) {
+        const accountName = connectionMap[e.connectionId] || `Account ${e.connectionId.slice(0, 8)}...`;
+        const accountKey = `${e.model} (${e.provider} - ${accountName})`;
+        if (stats.byAccount[accountKey] && new Date(ts) > new Date(stats.byAccount[accountKey].lastUsed)) stats.byAccount[accountKey].lastUsed = ts;
+      }
+
+      const apiKeyKey = (e.apiKey && typeof e.apiKey === "string")
+        ? `${e.apiKey}|${e.model}|${e.provider || "unknown"}`
+        : "local-no-key";
+      if (stats.byApiKey[apiKeyKey] && new Date(ts) > new Date(stats.byApiKey[apiKeyKey].lastUsed)) stats.byApiKey[apiKeyKey].lastUsed = ts;
+
+      const endpoint = e.endpoint || "Unknown";
+      const endpointKey = `${endpoint}|${e.model}|${e.provider || "unknown"}`;
+      if (stats.byEndpoint[endpointKey] && new Date(ts) > new Date(stats.byEndpoint[endpointKey].lastUsed)) stats.byEndpoint[endpointKey].lastUsed = ts;
+    }
+  } else {
+    // 24h / today: live history
+    let cutoff;
+    if (period === "today") {
+      const startOfDay = new Date();
+      startOfDay.setHours(0, 0, 0, 0);
+      cutoff = startOfDay.toISOString();
+    } else {
+      cutoff = new Date(Date.now() - PERIOD_MS["24h"]).toISOString();
+    }
+    const filtered = db.all(
+      `SELECT timestamp, provider, model, connectionId, apiKey, endpoint, promptTokens, completionTokens, cost, tokens FROM usageHistory WHERE timestamp >= ?`,
+      [cutoff]
+    );
+
+    for (const r of filtered) {
+      const tokens = parseJson(r.tokens, {}) || {};
+      const promptTokens = tokens.prompt_tokens || 0;
+      const completionTokens = tokens.completion_tokens || 0;
+      const cachedTokens = tokens.cached_tokens || tokens.cache_read_input_tokens || 0;
+      const entryCost = r.cost || 0;
+      const providerDisplayName = providerNodeNameMap[r.provider] || r.provider;
+
+      stats.totalPromptTokens += promptTokens;
+      stats.totalCompletionTokens += completionTokens;
+      stats.totalCachedTokens += cachedTokens;
+      stats.totalCost += entryCost;
+
+      if (!stats.byProvider[r.provider]) stats.byProvider[r.provider] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0 };
+      stats.byProvider[r.provider].requests++;
+      stats.byProvider[r.provider].promptTokens += promptTokens;
+      stats.byProvider[r.provider].completionTokens += completionTokens;
+      stats.byProvider[r.provider].cachedTokens += cachedTokens;
+      stats.byProvider[r.provider].cost += entryCost;
+
+      const modelKey = r.provider ? `${r.model} (${r.provider})` : r.model;
+      if (!stats.byModel[modelKey]) {
+        stats.byModel[modelKey] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0, rawModel: r.model, provider: providerDisplayName, lastUsed: r.timestamp };
+      }
+      stats.byModel[modelKey].requests++;
+      stats.byModel[modelKey].promptTokens += promptTokens;
+      stats.byModel[modelKey].completionTokens += completionTokens;
+      stats.byModel[modelKey].cachedTokens += cachedTokens;
+      stats.byModel[modelKey].cost += entryCost;
+      if (new Date(r.timestamp) > new Date(stats.byModel[modelKey].lastUsed)) stats.byModel[modelKey].lastUsed = r.timestamp;
+
+      if (r.connectionId) {
+        const accountName = connectionMap[r.connectionId] || `Account ${r.connectionId.slice(0, 8)}...`;
+        const accountKey = `${r.model} (${r.provider} - ${accountName})`;
+        if (!stats.byAccount[accountKey]) {
+          stats.byAccount[accountKey] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0, rawModel: r.model, provider: providerDisplayName, connectionId: r.connectionId, accountName, lastUsed: r.timestamp };
+        }
+        stats.byAccount[accountKey].requests++;
+        stats.byAccount[accountKey].promptTokens += promptTokens;
+        stats.byAccount[accountKey].completionTokens += completionTokens;
+        stats.byAccount[accountKey].cachedTokens += cachedTokens;
+        stats.byAccount[accountKey].cost += entryCost;
+        if (new Date(r.timestamp) > new Date(stats.byAccount[accountKey].lastUsed)) stats.byAccount[accountKey].lastUsed = r.timestamp;
+      }
+
+      if (r.apiKey && typeof r.apiKey === "string") {
+        const keyInfo = apiKeyMap[r.apiKey];
+        const keyName = keyInfo?.name || r.apiKey.slice(0, 8) + "...";
+        const apiKeyMasked = maskApiKey(r.apiKey);
+        const akKey = `${apiKeyMasked}|${r.model}|${r.provider || "unknown"}`;
+        if (!stats.byApiKey[akKey]) {
+          stats.byApiKey[akKey] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0, rawModel: r.model, provider: providerDisplayName, apiKeyMasked, keyName, apiKeyKey: apiKeyMasked, lastUsed: r.timestamp };
+        }
+        const ake = stats.byApiKey[akKey];
+        ake.requests++; ake.promptTokens += promptTokens; ake.completionTokens += completionTokens; ake.cachedTokens += cachedTokens; ake.cost += entryCost;
+        if (new Date(r.timestamp) > new Date(ake.lastUsed)) ake.lastUsed = r.timestamp;
+      } else {
+        if (!stats.byApiKey["local-no-key"]) {
+          stats.byApiKey["local-no-key"] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0, rawModel: r.model, provider: providerDisplayName, apiKeyMasked: null, keyName: "Local (No API Key)", apiKeyKey: "local-no-key", lastUsed: r.timestamp };
+        }
+        const ake = stats.byApiKey["local-no-key"];
+        ake.requests++; ake.promptTokens += promptTokens; ake.completionTokens += completionTokens; ake.cachedTokens += cachedTokens; ake.cost += entryCost;
+        if (new Date(r.timestamp) > new Date(ake.lastUsed)) ake.lastUsed = r.timestamp;
+      }
+
+      const endpoint = r.endpoint || "Unknown";
+      const epKey = `${endpoint}|${r.model}|${r.provider || "unknown"}`;
+      if (!stats.byEndpoint[epKey]) {
+        stats.byEndpoint[epKey] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0, endpoint, rawModel: r.model, provider: providerDisplayName, lastUsed: r.timestamp };
+      }
+      const epe = stats.byEndpoint[epKey];
+      epe.requests++; epe.promptTokens += promptTokens; epe.completionTokens += completionTokens; epe.cachedTokens += cachedTokens; epe.cost += entryCost;
+      if (new Date(r.timestamp) > new Date(epe.lastUsed)) epe.lastUsed = r.timestamp;
+    }
+  }
+
+  stats.totalRequests = Object.values(stats.byProvider).reduce((sum, p) => sum + (p.requests || 0), 0);
+  return stats;
+}
+
+export async function getChartData(period = "7d") {
+  const db = await getAdapter();
+  const now = Date.now();
+
+  if (period === "today") {
+    const bucketCount = 24;
+    const bucketMs = 3600000;
+    const startOfDay = new Date();
+    startOfDay.setHours(0, 0, 0, 0);
+    const startTime = startOfDay.getTime();
+    const endTime = startTime + bucketCount * bucketMs;
+    const labelFn = (ts) => new Date(ts).toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit", hour12: false });
+    const buckets = Array.from({ length: bucketCount }, (_, i) => ({ label: labelFn(startTime + i * bucketMs), tokens: 0, cost: 0 }));
+
+    const rows = db.all(
+      `SELECT timestamp, promptTokens, completionTokens, cost FROM usageHistory WHERE timestamp >= ?`,
+      [new Date(startTime).toISOString()]
+    );
+    for (const r of rows) {
+      const t = new Date(r.timestamp).getTime();
+      if (t < startTime || t >= endTime) continue;
+      const idx = Math.floor((t - startTime) / bucketMs);
+      if (idx >= 0 && idx < bucketCount) {
+        buckets[idx].tokens += (r.promptTokens || 0) + (r.completionTokens || 0);
+        buckets[idx].cost += r.cost || 0;
+      }
+    }
+    return buckets;
+  }
+
+  if (period === "24h") {
+    const bucketCount = 24;
+    const bucketMs = 3600000;
+    const labelFn = (ts) => new Date(ts).toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit", hour12: false });
+    const startTime = now - bucketCount * bucketMs;
+    const buckets = Array.from({ length: bucketCount }, (_, i) => ({ label: labelFn(startTime + i * bucketMs), tokens: 0, cost: 0 }));
+
+    const rows = db.all(
+      `SELECT timestamp, promptTokens, completionTokens, cost FROM usageHistory WHERE timestamp >= ?`,
+      [new Date(startTime).toISOString()]
+    );
+    for (const r of rows) {
+      const t = new Date(r.timestamp).getTime();
+      if (t < startTime || t > now) continue;
+      const idx = Math.min(Math.floor((t - startTime) / bucketMs), bucketCount - 1);
+      buckets[idx].tokens += (r.promptTokens || 0) + (r.completionTokens || 0);
+      buckets[idx].cost += r.cost || 0;
+    }
+    return buckets;
+  }
+
+  const bucketCount = period === "7d" ? 7 : period === "30d" ? 30 : 60;
+  const today = new Date();
+  const labelFn = (d) => d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+
+  // Build map of dateKey → day data
+  const dayRows = loadDaysInRange(db, bucketCount);
+  const dayMap = {};
+  for (const r of dayRows) dayMap[r.dateKey] = parseJson(r.data, {});
+
+  return Array.from({ length: bucketCount }, (_, i) => {
+    const d = new Date(today);
+    d.setDate(d.getDate() - (bucketCount - 1 - i));
+    const dateKey = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+    const dayData = dayMap[dateKey];
+    return {
+      label: labelFn(d),
+      tokens: dayData ? (dayData.promptTokens || 0) + (dayData.completionTokens || 0) : 0,
+      cost: dayData ? (dayData.cost || 0) : 0,
+    };
+  });
+}
+
+function formatLogDate(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${pad(date.getDate())}-${pad(date.getMonth() + 1)}-${date.getFullYear()} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+// No-op: request log is now derived from usageHistory table on read.
+export async function appendRequestLog() {}
+
+export async function getRecentLogs(limit = 200) {
+  try {
+    const db = await getAdapter();
+    const rows = db.all(
+      `SELECT timestamp, provider, model, connectionId, promptTokens, completionTokens, status, tokens FROM usageHistory ORDER BY id DESC LIMIT ?`,
+      [limit],
+    );
+    if (!rows.length) return [];
+
+    const connMap = {};
+    try {
+      const { getProviderConnections } = await import("./connectionsRepo.js");
+      const connections = await getProviderConnections();
+      for (const c of connections) connMap[c.id] = c.name || c.email || "";
+    } catch {}
+
+    return rows.map((r) => {
+      const ts = formatLogDate(new Date(r.timestamp));
+      const p = r.provider?.toUpperCase() || "-";
+      const m = r.model || "-";
+      const account = connMap[r.connectionId] || (r.connectionId ? r.connectionId.slice(0, 8) : "-");
+      const tk = r.tokens ? parseJson(r.tokens, {}) : {};
+      const sent = r.promptTokens ?? tk.prompt_tokens ?? "-";
+      const received = r.completionTokens ?? tk.completion_tokens ?? "-";
+      return `${ts} | ${m} | ${p} | ${account} | ${sent} | ${received} | ${r.status || "-"}`;
+    });
+  } catch (e) {
+    console.error("[usageRepo] getRecentLogs failed:", e.message);
+    return [];
+  }
+}
diff --git a/src/lib/db/schema.js b/src/lib/db/schema.js
new file mode 100644
index 0000000..099386c
--- /dev/null
+++ b/src/lib/db/schema.js
@@ -0,0 +1,161 @@
+// ⚠️ AGENT/DEV: Bump this by +1 EVERY TIME you change the schema below
+// (add/remove/alter a table, column, or index in TABLES). It drives the
+// pre-change safety backup in migrate.js: when the stored version is lower,
+// one lightweight DB backup is taken before applying schema changes. Forgetting
+// to bump only skips that backup — it does NOT break the additive auto-sync.
+export const SCHEMA_VERSION = 1;
+
+export const PRAGMA_SQL = `
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = NORMAL;
+PRAGMA temp_store = MEMORY;
+PRAGMA mmap_size = 30000000;
+PRAGMA cache_size = -64000;
+PRAGMA foreign_keys = ON;
+PRAGMA busy_timeout = 5000;
+`;
+
+// Declarative current schema. Used by syncSchemaFromTables() to
+// auto-add missing tables/columns/indexes after versioned migrations.
+// For destructive changes (drop/rename/type-change), write a migration file.
+export const TABLES = {
+  _meta: {
+    columns: {
+      key: "TEXT PRIMARY KEY",
+      value: "TEXT NOT NULL",
+    },
+  },
+  settings: {
+    columns: {
+      id: "INTEGER PRIMARY KEY CHECK (id = 1)",
+      data: "TEXT NOT NULL",
+    },
+  },
+  providerConnections: {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      provider: "TEXT NOT NULL",
+      authType: "TEXT NOT NULL",
+      name: "TEXT",
+      email: "TEXT",
+      priority: "INTEGER",
+      isActive: "INTEGER DEFAULT 1",
+      data: "TEXT NOT NULL",
+      createdAt: "TEXT NOT NULL",
+      updatedAt: "TEXT NOT NULL",
+    },
+    indexes: [
+      "CREATE INDEX IF NOT EXISTS idx_pc_provider ON providerConnections(provider)",
+      "CREATE INDEX IF NOT EXISTS idx_pc_provider_active ON providerConnections(provider, isActive)",
+      "CREATE INDEX IF NOT EXISTS idx_pc_priority ON providerConnections(provider, priority)",
+    ],
+  },
+  providerNodes: {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      type: "TEXT",
+      name: "TEXT",
+      data: "TEXT NOT NULL",
+      createdAt: "TEXT NOT NULL",
+      updatedAt: "TEXT NOT NULL",
+    },
+    indexes: ["CREATE INDEX IF NOT EXISTS idx_pn_type ON providerNodes(type)"],
+  },
+  proxyPools: {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      isActive: "INTEGER DEFAULT 1",
+      testStatus: "TEXT",
+      data: "TEXT NOT NULL",
+      createdAt: "TEXT NOT NULL",
+      updatedAt: "TEXT NOT NULL",
+    },
+    indexes: [
+      "CREATE INDEX IF NOT EXISTS idx_pp_active ON proxyPools(isActive)",
+      "CREATE INDEX IF NOT EXISTS idx_pp_status ON proxyPools(testStatus)",
+    ],
+  },
+  apiKeys: {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      key: "TEXT UNIQUE NOT NULL",
+      name: "TEXT",
+      machineId: "TEXT",
+      isActive: "INTEGER DEFAULT 1",
+      createdAt: "TEXT NOT NULL",
+    },
+    indexes: ["CREATE INDEX IF NOT EXISTS idx_ak_key ON apiKeys(key)"],
+  },
+  combos: {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      name: "TEXT UNIQUE NOT NULL",
+      kind: "TEXT",
+      models: "TEXT NOT NULL",
+      createdAt: "TEXT NOT NULL",
+      updatedAt: "TEXT NOT NULL",
+    },
+    indexes: ["CREATE INDEX IF NOT EXISTS idx_combo_name ON combos(name)"],
+  },
+  kv: {
+    columns: {
+      scope: "TEXT NOT NULL",
+      key: "TEXT NOT NULL",
+      value: "TEXT NOT NULL",
+    },
+    primaryKey: "PRIMARY KEY (scope, key)",
+    indexes: ["CREATE INDEX IF NOT EXISTS idx_kv_scope ON kv(scope)"],
+  },
+  usageHistory: {
+    columns: {
+      id: "INTEGER PRIMARY KEY AUTOINCREMENT",
+      timestamp: "TEXT NOT NULL",
+      provider: "TEXT",
+      model: "TEXT",
+      connectionId: "TEXT",
+      apiKey: "TEXT",
+      endpoint: "TEXT",
+      promptTokens: "INTEGER DEFAULT 0",
+      completionTokens: "INTEGER DEFAULT 0",
+      cost: "REAL DEFAULT 0",
+      status: "TEXT",
+      tokens: "TEXT",
+      meta: "TEXT",
+    },
+    indexes: [
+      "CREATE INDEX IF NOT EXISTS idx_uh_ts ON usageHistory(timestamp DESC)",
+      "CREATE INDEX IF NOT EXISTS idx_uh_provider ON usageHistory(provider)",
+      "CREATE INDEX IF NOT EXISTS idx_uh_model ON usageHistory(model)",
+      "CREATE INDEX IF NOT EXISTS idx_uh_conn ON usageHistory(connectionId)",
+    ],
+  },
+  usageDaily: {
+    columns: {
+      dateKey: "TEXT PRIMARY KEY",
+      data: "TEXT NOT NULL",
+    },
+  },
+  requestDetails: {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      timestamp: "TEXT NOT NULL",
+      provider: "TEXT",
+      model: "TEXT",
+      connectionId: "TEXT",
+      status: "TEXT",
+      data: "TEXT NOT NULL",
+    },
+    indexes: [
+      "CREATE INDEX IF NOT EXISTS idx_rd_ts ON requestDetails(timestamp DESC)",
+      "CREATE INDEX IF NOT EXISTS idx_rd_provider ON requestDetails(provider)",
+      "CREATE INDEX IF NOT EXISTS idx_rd_model ON requestDetails(model)",
+      "CREATE INDEX IF NOT EXISTS idx_rd_conn ON requestDetails(connectionId)",
+    ],
+  },
+};
+
+export function buildCreateTableSql(name, def) {
+  const cols = Object.entries(def.columns).map(([k, v]) => `${k} ${v}`);
+  if (def.primaryKey) cols.push(def.primaryKey);
+  return `CREATE TABLE IF NOT EXISTS ${name} (${cols.join(", ")})`;
+}
diff --git a/src/lib/db/version.js b/src/lib/db/version.js
new file mode 100644
index 0000000..9b5045d
--- /dev/null
+++ b/src/lib/db/version.js
@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import path from "node:path";
+
+let cachedVersion = null;
+
+export function getAppVersion() {
+  if (cachedVersion) return cachedVersion;
+  try {
+    const pkgPath = path.join(process.cwd(), "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    cachedVersion = pkg.version || "0.0.0";
+  } catch {
+    cachedVersion = "0.0.0";
+  }
+  return cachedVersion;
+}
+
+export function timestampSlug(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
diff --git a/src/lib/disabledModelsDb.js b/src/lib/disabledModelsDb.js
new file mode 100644
index 0000000..044e014
--- /dev/null
+++ b/src/lib/disabledModelsDb.js
@@ -0,0 +1,4 @@
+// Shim → re-export from new SQLite-based DB layer (src/lib/db/)
+export {
+  getDisabledModels, getDisabledByProvider, disableModels, enableModels,
+} from "@/lib/db/index.js";
diff --git a/src/lib/headroom/detect.js b/src/lib/headroom/detect.js
new file mode 100644
index 0000000..0ba9e2b
--- /dev/null
+++ b/src/lib/headroom/detect.js
@@ -0,0 +1,192 @@
+import { execFileSync, execSync } from "child_process";
+import path from "path";
+
+// Extras that improve headroom compression quality. `proxy` is the base;
+// `code` adds tree-sitter AST compression; `ml` adds Kompress-v2 HF model.
+// Other `[all]` extras (image, voice, otel, reports, evals, ...) are not
+// useful for the 9router proxy use case, so we don't track them here.
+export const HEADROOM_COMPRESSION_EXTRAS = ["code", "ml"];
+
+// Marker packages that each extra pulls in. Detected from `pip list --format=json`
+// so one call can answer both the installed version and active extras.
+export const EXTRA_MARKERS = {
+  code: ["tree-sitter", "tree-sitter-language-pack"],
+  ml: ["torch", "huggingface-hub"],
+};
+
+const HEADROOM_PIP_TIMEOUT_MS = 8000;
+
+const IS_WIN = process.platform === "win32";
+const WHICH_CMD = IS_WIN ? "where" : "which";
+
+// Extra bin dirs often missing from a packaged/launchd PATH (Python installs headroom here).
+const EXTRA_BINS = IS_WIN
+  ? [
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python313\\Scripts`,
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python312\\Scripts`,
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python311\\Scripts`,
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python310\\Scripts`,
+      `${process.env.APPDATA || ""}\\Python\\Python313\\Scripts`,
+    ]
+  : [
+      "/usr/local/bin",
+      "/opt/homebrew/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.13/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.12/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.11/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.10/bin",
+      `${process.env.HOME || ""}/.local/bin`,
+      "/usr/bin",
+      "/bin",
+    ];
+
+const EXTENDED_PATH = [...EXTRA_BINS, process.env.PATH || ""].filter(Boolean).join(path.delimiter);
+const PYTHON_CANDIDATES = ["python3.13", "python3.12", "python3.11", "python3.10", "python3", "python"];
+const MIN_VERSION = [3, 10];
+const HEADROOM_HEALTH_TIMEOUT_MS = 1500;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"]);
+
+export const DEFAULT_HEADROOM_URL = process.env.HEADROOM_URL || "http://localhost:8787";
+
+// Detect whether the headroom CLI is installed and where its binary lives.
+export function findHeadroomBinary() {
+  try {
+    const out = execSync(`${WHICH_CMD} headroom`, {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    }).toString().trim();
+    // Windows `where` may return multiple lines — take the first.
+    return out ? out.split(/\r?\n/)[0].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+// Find a Python interpreter >= 3.10 (headroom-ai requires it). Returns null if none.
+// `python3`, `python3.13`, `python` can point at different envs on any OS. Prefer
+// the interpreter that can also see the installed `headroom-ai` package so the
+// dashboard probes and install action operate on the same interpreter as the CLI.
+// Falls back to the first version-eligible candidate when headroom-ai is not yet
+// installed anywhere (needed for the initial install).
+// Interpreters to probe, most specific first: the python next to the headroom
+// binary (guaranteed to have headroom-ai), then full paths from EXTRA_BINS, then
+// bare names resolved via PATH.
+function pythonCandidates() {
+  const list = [];
+  const bin = findHeadroomBinary();
+  if (bin) {
+    const dir = path.dirname(bin);
+    const names = IS_WIN ? ["python.exe", "python3.exe"] : ["python3", "python3.13", "python"];
+    for (const n of names) list.push(path.join(dir, n));
+  }
+  for (const dir of EXTRA_BINS) {
+    if (!dir) continue;
+    for (const n of PYTHON_CANDIDATES) list.push(path.join(dir, IS_WIN ? `${n}.exe` : n));
+  }
+  list.push(...PYTHON_CANDIDATES);
+  return list;
+}
+
+export function findPython310() {
+  let fallback = null;
+  for (const candidate of pythonCandidates()) {
+    try {
+      const ver = execSync(`${candidate} --version`, {
+        stdio: ["ignore", "pipe", "ignore"],
+        windowsHide: true,
+        env: { ...process.env, PATH: EXTENDED_PATH },
+      }).toString().trim();
+      const match = ver.match(/(\d+)\.(\d+)/);
+      if (!match) continue;
+      const [major, minor] = [parseInt(match[1], 10), parseInt(match[2], 10)];
+      if (!(major > MIN_VERSION[0] || (major === MIN_VERSION[0] && minor >= MIN_VERSION[1]))) continue;
+      if (!fallback) fallback = candidate;
+      try {
+        execFileSync(candidate, ["-m", "pip", "show", "headroom-ai"], {
+          stdio: ["ignore", "pipe", "ignore"],
+          windowsHide: true,
+          timeout: HEADROOM_PIP_TIMEOUT_MS,
+          env: { ...process.env, PATH: EXTENDED_PATH },
+        });
+        return candidate;
+      } catch {
+        // Keep scanning until an interpreter that sees headroom-ai is found.
+      }
+    } catch {
+      // candidate not present, try next
+    }
+  }
+  return fallback;
+}
+
+// Probe whether a Headroom proxy is reachable at the given URL by hitting /health.
+export async function probeProxyRunning(url) {
+  if (!url) return false;
+  const base = String(url).replace(/\/$/, "");
+  try {
+    const res = await fetch(`${base}/health`, { signal: AbortSignal.timeout(HEADROOM_HEALTH_TIMEOUT_MS) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export function isLoopbackHeadroomUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return LOOPBACK_HOSTS.has(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+// Aggregate status for the dashboard: installed, running, python interpreter.
+export async function getHeadroomStatus(url) {
+  const path = findHeadroomBinary();
+  const python = findPython310();
+  const installed = Boolean(path);
+  const running = await probeProxyRunning(url);
+  const localUrl = isLoopbackHeadroomUrl(url);
+  const extrasStatus = installed ? getInstalledHeadroomExtras(python) : { installed: false, version: null, extras: { code: false, ml: false } };
+  return {
+    installed,
+    path,
+    running,
+    python,
+    localUrl,
+    canStart: installed && localUrl,
+    version: extrasStatus.version,
+    extras: extrasStatus.extras,
+  };
+}
+
+// Parse installed headroom-ai version + which compression extras are
+// actually installed (detected via marker package presence). One `pip list`
+// call is enough to answer both questions.
+//
+// Returns: { installed: bool, version: string|null, extras: { code, ml } }
+export function getInstalledHeadroomExtras(python) {
+  const py = python || findPython310();
+  if (!py) return { installed: false, version: null, extras: { code: false, ml: false } };
+  try {
+    const out = execFileSync(py, ["-m", "pip", "list", "--format=json", "--disable-pip-version-check"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+      timeout: HEADROOM_PIP_TIMEOUT_MS,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    }).toString();
+    const packages = JSON.parse(out);
+    const names = new Set(packages.map((p) => String(p.name || "").toLowerCase()));
+    const installed = names.has("headroom-ai");
+    if (!installed) return { installed: false, version: null, extras: { code: false, ml: false } };
+    const version = packages.find((p) => p.name?.toLowerCase() === "headroom-ai")?.version || null;
+    const extras = {};
+    for (const extra of HEADROOM_COMPRESSION_EXTRAS) {
+      extras[extra] = EXTRA_MARKERS[extra].some((m) => names.has(m));
+    }
+    return { installed: true, version, extras };
+  } catch {
+    return { installed: false, version: null, extras: { code: false, ml: false } };
+  }
+}
diff --git a/src/lib/headroom/process.js b/src/lib/headroom/process.js
new file mode 100644
index 0000000..4172087
--- /dev/null
+++ b/src/lib/headroom/process.js
@@ -0,0 +1,260 @@
+import fs from "fs";
+import path from "path";
+import { spawn } from "child_process";
+import { DATA_DIR } from "@/lib/dataDir.js";
+import { findHeadroomBinary, findPython310, HEADROOM_COMPRESSION_EXTRAS, EXTRA_MARKERS, getInstalledHeadroomExtras } from "./detect.js";
+
+const HEADROOM_DIR = path.join(DATA_DIR, "headroom");
+const PID_FILE = path.join(HEADROOM_DIR, "proxy.pid");
+const LOG_FILE = path.join(HEADROOM_DIR, "proxy.log");
+const INSTALL_LOG_FILE = path.join(HEADROOM_DIR, "install.log");
+const DEFAULT_PORT = 8787;
+const STARTUP_TIMEOUT_MS = 8000;
+
+function ensureDir() {
+  if (!fs.existsSync(HEADROOM_DIR)) fs.mkdirSync(HEADROOM_DIR, { recursive: true });
+}
+
+function readPid() {
+  try {
+    if (fs.existsSync(PID_FILE)) return parseInt(fs.readFileSync(PID_FILE, "utf8"), 10);
+  } catch { /* ignore */ }
+  return null;
+}
+
+function writePid(pid) {
+  ensureDir();
+  fs.writeFileSync(PID_FILE, String(pid));
+}
+
+function clearPid() {
+  try { if (fs.existsSync(PID_FILE)) fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
+}
+
+// process.kill throws if pid is dead — use this to probe.
+export function isPidAlive(pid) {
+  if (!pid || typeof pid !== "number") return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export function getManagedPid() {
+  const pid = readPid();
+  return pid && isPidAlive(pid) ? pid : null;
+}
+
+// Build proxy CLI flags for the active compression extras. `[code]` (AST
+// compression) is off by default in headroom → pass --code-aware to turn it on;
+// `[ml]` (Kompress) is on by default → pass --disable-kompress to turn it off.
+function extrasProxyArgs({ codeAware, kompress } = {}) {
+  const args = [];
+  if (codeAware) args.push("--code-aware");
+  if (kompress === false) args.push("--disable-kompress");
+  return args;
+}
+
+export async function startHeadroomProxy({ port = DEFAULT_PORT, codeAware = false, kompress = true } = {}) {
+  const safePort = Number(port) > 0 && Number(port) < 65536 ? Number(port) : DEFAULT_PORT;
+  const binary = findHeadroomBinary();
+  if (!binary) {
+    const err = new Error("Headroom CLI not installed");
+    err.code = "NOT_INSTALLED";
+    throw err;
+  }
+
+  const existing = getManagedPid();
+  if (existing) return { pid: existing, alreadyRunning: true };
+
+  ensureDir();
+  // spawn stdio requires fd numbers, not WriteStream objects.
+  const outFd = fs.openSync(LOG_FILE, "a");
+
+  const args = ["proxy", "--port", String(safePort), ...extrasProxyArgs({ codeAware, kompress })];
+  const child = spawn(binary, args, {
+    stdio: ["ignore", outFd, outFd],
+    detached: true,
+    windowsHide: true,
+    env: { ...process.env },
+  });
+
+  if (!child.pid) {
+    fs.closeSync(outFd);
+    const err = new Error("Failed to spawn headroom proxy");
+    err.code = "SPAWN_FAILED";
+    throw err;
+  }
+
+  child.unref();
+  writePid(child.pid);
+
+  // Wait until the process either stays alive briefly (success) or exits fast (failure).
+  await new Promise((resolve, reject) => {
+    const startupTimer = setTimeout(() => {
+      if (isPidAlive(child.pid)) resolve();
+      else reject(new Error("headroom proxy exited during startup — see proxy.log"));
+    }, STARTUP_TIMEOUT_MS);
+
+    child.once("exit", (code) => {
+      clearTimeout(startupTimer);
+      clearPid();
+      fs.closeSync(outFd);
+      const e = new Error(`headroom proxy exited early (code=${code}) — see proxy.log`);
+      e.code = "EARLY_EXIT";
+      reject(e);
+    });
+  });
+
+  // Close parent's copy of the fd; child retains its own after unref.
+  fs.closeSync(outFd);
+
+  return { pid: child.pid, alreadyRunning: false };
+}
+
+export function stopHeadroomProxy() {
+  const pid = getManagedPid();
+  if (!pid) return { stopped: false, reason: "not_running" };
+  try {
+    process.kill(pid, "SIGTERM");
+    // Give it a moment, then force if still alive.
+    setTimeout(() => {
+      if (isPidAlive(pid)) {
+        try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
+      }
+    }, 2000);
+    clearPid();
+    return { stopped: true, pid };
+  } catch (e) {
+    clearPid();
+    const err = new Error(`Failed to stop headroom proxy: ${e.message}`);
+    err.code = "STOP_FAILED";
+    throw err;
+  }
+}
+
+// Stop the managed proxy (if any), wait for the pid to die, then start again
+// with the given flags. Used when toggling active extras that require a restart.
+export async function restartHeadroomProxy(opts = {}) {
+  const pid = getManagedPid();
+  if (pid) {
+    try { process.kill(pid, "SIGTERM"); } catch { /* already gone */ }
+    // Wait up to ~3s for graceful exit, force-kill if still alive.
+    for (let i = 0; i < 30 && isPidAlive(pid); i++) {
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    if (isPidAlive(pid)) {
+      try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
+      await new Promise((r) => setTimeout(r, 300));
+    }
+    clearPid();
+  }
+  return startHeadroomProxy(opts);
+}
+
+export function getHeadroomLogTail(maxLines = 200) {
+  try {
+    if (!fs.existsSync(LOG_FILE)) return "";
+    const content = fs.readFileSync(LOG_FILE, "utf8");
+    const lines = content.split(/\r?\n/).filter(Boolean);
+    return lines.slice(-maxLines).join("\n");
+  } catch { return ""; }
+}
+
+// Install (or upgrade) headroom-ai with the requested compression extras.
+// `extras` is a whitelist from HEADROOM_COMPRESSION_EXTRAS — anything else
+// is rejected to keep the install surface predictable. Always installs the
+// `proxy` base + whatever extras the user picked, regardless of what is
+// already present.
+export async function installHeadroomExtras(extras = []) {
+  const requested = Array.isArray(extras) ? extras.filter((e) => HEADROOM_COMPRESSION_EXTRAS.includes(e)) : [];
+  const py = findPython310();
+  if (!py) {
+    const err = new Error("Python >= 3.10 not found");
+    err.code = "NO_PYTHON";
+    throw err;
+  }
+  if (!findHeadroomBinary()) {
+    const err = new Error("headroom-ai not installed (run `pip install headroom-ai[proxy]` first)");
+    err.code = "NOT_INSTALLED";
+    throw err;
+  }
+  // pip install string is built from a closed set (HEADROOM_COMPRESSION_EXTRAS),
+  // so it cannot be poisoned by caller input — the comma-list is a fixed
+  // ['proxy', ...requested]. No shell interpolation.
+  const extrasList = ["proxy", ...requested].join(",");
+  const spec = `headroom-ai[${extrasList}]`;
+  const args = ["-m", "pip", "install", "--upgrade", spec];
+
+  ensureDir();
+  // Truncate ("w") so the log reflects only the current install for live progress.
+  const outFd = fs.openSync(INSTALL_LOG_FILE, "w");
+  const child = spawn(py, args, {
+    stdio: ["ignore", outFd, outFd],
+    windowsHide: true,
+    env: { ...process.env },
+  });
+
+  return new Promise((resolve, reject) => {
+    child.once("error", (e) => { fs.closeSync(outFd); reject(e); });
+    child.once("exit", (code) => {
+      fs.closeSync(outFd);
+      if (code === 0) {
+        const status = getInstalledHeadroomExtras(py);
+        resolve({ success: true, code, spec, extras: requested, ...status });
+      } else {
+        const err = new Error(`pip install exited with code=${code} — see headroom/install.log`);
+        err.code = "INSTALL_FAILED";
+        reject(err);
+      }
+    });
+  });
+}
+
+// Uninstall the marker packages that back a single extra (e.g. `ml` → torch,
+// huggingface-hub). `headroom-ai` base and the `proxy` extra are never removed.
+export async function uninstallHeadroomExtras(extras = []) {
+  const requested = Array.isArray(extras) ? extras.filter((e) => HEADROOM_COMPRESSION_EXTRAS.includes(e)) : [];
+  const py = findPython310();
+  if (!py) {
+    const err = new Error("Python >= 3.10 not found");
+    err.code = "NO_PYTHON";
+    throw err;
+  }
+  const pkgs = [...new Set(requested.flatMap((e) => EXTRA_MARKERS[e] || []))];
+  if (pkgs.length === 0) {
+    const err = new Error("No valid extras to remove");
+    err.code = "INVALID_EXTRAS";
+    throw err;
+  }
+  const args = ["-m", "pip", "uninstall", "-y", ...pkgs];
+
+  ensureDir();
+  const outFd = fs.openSync(INSTALL_LOG_FILE, "w");
+  const child = spawn(py, args, {
+    stdio: ["ignore", outFd, outFd],
+    windowsHide: true,
+    env: { ...process.env },
+  });
+
+  return new Promise((resolve, reject) => {
+    child.once("error", (e) => { fs.closeSync(outFd); reject(e); });
+    child.once("exit", (code) => {
+      fs.closeSync(outFd);
+      if (code === 0) {
+        const status = getInstalledHeadroomExtras(py);
+        resolve({ success: true, code, removed: pkgs, extras: requested, ...status });
+      } else {
+        const err = new Error(`pip uninstall exited with code=${code} — see headroom/install.log`);
+        err.code = "UNINSTALL_FAILED";
+        reject(err);
+      }
+    });
+  });
+}
+
+// Read the tail of the install/uninstall log for live progress in the UI.
+export function getInstallLogTail(maxLines = 15) {
+  try {
+    if (!fs.existsSync(INSTALL_LOG_FILE)) return "";
+    const lines = fs.readFileSync(INSTALL_LOG_FILE, "utf8").split(/\r?\n/).filter(Boolean);
+    return lines.slice(-maxLines).join("\n");
+  } catch { return ""; }
+}
diff --git a/src/lib/localDb.js b/src/lib/localDb.js
new file mode 100644
index 0000000..71d086e
--- /dev/null
+++ b/src/lib/localDb.js
@@ -0,0 +1,21 @@
+// Shim → re-export from new SQLite-based DB layer (src/lib/db/)
+// Kept for backward compatibility with existing imports.
+export {
+  getSettings, updateSettings, isCloudEnabled, getCloudUrl,
+  getProviderConnections, getProviderConnectionById,
+  createProviderConnection, updateProviderConnection,
+  deleteProviderConnection, deleteProviderConnectionsByProvider,
+  reorderProviderConnections, cleanupProviderConnections,
+  getProviderNodes, getProviderNodeById,
+  createProviderNode, updateProviderNode, deleteProviderNode,
+  getProxyPools, getProxyPoolById,
+  createProxyPool, updateProxyPool, deleteProxyPool,
+  getApiKeys, getApiKeyById, createApiKey, updateApiKey, deleteApiKey, validateApiKey,
+  getCombos, getComboById, getComboByName,
+  createCombo, updateCombo, deleteCombo,
+  getModelAliases, setModelAlias, deleteModelAlias,
+  getCustomModels, addCustomModel, deleteCustomModel,
+  getMitmAlias, setMitmAliasAll,
+  getPricing, getPricingForModel, updatePricing, resetPricing, resetAllPricing,
+  exportDb, importDb,
+} from "@/lib/db/index.js";
diff --git a/src/lib/mcp/stdioSseBridge.js b/src/lib/mcp/stdioSseBridge.js
new file mode 100644
index 0000000..1bdc426
--- /dev/null
+++ b/src/lib/mcp/stdioSseBridge.js
@@ -0,0 +1,183 @@
+// Inline stdio<->SSE bridge for MCP. Spawns one child per plugin on demand,
+// broadcasts JSON-RPC frames over SSE, accepts client messages via HTTP POST.
+
+const { spawn } = require("child_process");
+const crypto = require("crypto");
+const { LOCAL_STDIO_PLUGINS } = require("@/shared/constants/coworkPlugins");
+
+const G_KEY = "__9routerMcpBridges";
+const MAX_TEXT_CHARS = 50000;
+const COLLAPSE_THRESHOLD = 30;
+const COLLAPSE_KEEP_HEAD = 10;
+const COLLAPSE_KEEP_TAIL = 5;
+
+// Drop noise nodes, collapse repeated siblings, hard-truncate. Preserve [ref=eXX].
+function smartFilterText(text) {
+  if (typeof text !== "string" || text.length < 2000) return text;
+  let out = text;
+  out = out.replace(/^\s*-\s*generic:?\s*$/gm, "");
+  out = out.replace(/^\s*-\s*text:\s*""\s*$/gm, "");
+  out = collapseRepeated(out);
+  if (out.length > MAX_TEXT_CHARS) {
+    const head = out.slice(0, MAX_TEXT_CHARS - 300);
+    out = `${head}\n\n... [truncated ${text.length - head.length} chars by 9router bridge. Page is large; ask user to scroll/navigate to a specific section, or click an element with the refs shown above]`;
+  }
+  return out;
+}
+
+// Group consecutive lines sharing the same leading indent + role prefix; collapse if >= COLLAPSE_THRESHOLD.
+function collapseRepeated(text) {
+  const lines = text.split("\n");
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const m = line.match(/^(\s*)-\s*([a-zA-Z]+)\b/);
+    if (!m) { out.push(line); i++; continue; }
+    const indent = m[1];
+    const role = m[2];
+    let j = i;
+    while (j < lines.length) {
+      const ln = lines[j];
+      const mm = ln.match(/^(\s*)-\s*([a-zA-Z]+)\b/);
+      if (mm && mm[1] === indent && mm[2] === role) { j++; continue; }
+      if (ln.startsWith(`${indent} `) || ln.startsWith(`${indent}\t`)) { j++; continue; }
+      break;
+    }
+    const groupLen = j - i;
+    if (groupLen >= COLLAPSE_THRESHOLD) {
+      const headEnd = findNthSiblingEnd(lines, i, indent, role, COLLAPSE_KEEP_HEAD);
+      const tailStart = findLastNSiblingStart(lines, j, indent, role, COLLAPSE_KEEP_TAIL);
+      for (let k = i; k < headEnd; k++) out.push(lines[k]);
+      out.push(`${indent}... [${groupLen - COLLAPSE_KEEP_HEAD - COLLAPSE_KEEP_TAIL} similar "${role}" items omitted by 9router bridge]`);
+      for (let k = tailStart; k < j; k++) out.push(lines[k]);
+    } else {
+      for (let k = i; k < j; k++) out.push(lines[k]);
+    }
+    i = j;
+  }
+  return out.join("\n");
+}
+
+function findNthSiblingEnd(lines, start, indent, role, n) {
+  let count = 0;
+  for (let k = start; k < lines.length; k++) {
+    const mm = lines[k].match(/^(\s*)-\s*([a-zA-Z]+)\b/);
+    if (mm && mm[1] === indent && mm[2] === role) {
+      count++;
+      if (count > n) return k;
+    }
+  }
+  return lines.length;
+}
+
+function findLastNSiblingStart(lines, end, indent, role, n) {
+  const positions = [];
+  for (let k = 0; k < end; k++) {
+    const mm = lines[k].match(/^(\s*)-\s*([a-zA-Z]+)\b/);
+    if (mm && mm[1] === indent && mm[2] === role) positions.push(k);
+  }
+  return positions.length > n ? positions[positions.length - n] : end;
+}
+
+// Apply filter to JSON-RPC tool/result content text blocks only.
+function filterFrame(line) {
+  try {
+    const msg = JSON.parse(line);
+    const content = msg?.result?.content;
+    if (!Array.isArray(content)) return line;
+    let mutated = false;
+    for (const item of content) {
+      if (item?.type === "text" && typeof item.text === "string") {
+        const filtered = smartFilterText(item.text);
+        if (filtered !== item.text) { item.text = filtered; mutated = true; }
+      }
+    }
+    return mutated ? JSON.stringify(msg) : line;
+  } catch { return line; }
+}
+const getStore = () => {
+  if (!globalThis[G_KEY]) globalThis[G_KEY] = new Map();
+  return globalThis[G_KEY];
+};
+
+// Only preset stdio plugins may spawn. No user-defined commands (RCE prevention).
+function findPlugin(name) {
+  return LOCAL_STDIO_PLUGINS.find((p) => p.name === name) || null;
+}
+
+function getOrSpawn(name) {
+  const store = getStore();
+  let entry = store.get(name);
+  if (entry?.proc && !entry.proc.killed && entry.proc.exitCode === null) return entry;
+
+  const plugin = findPlugin(name);
+  if (!plugin) throw new Error(`Unknown local plugin: ${name}`);
+
+  const proc = spawn(plugin.command, plugin.args, { stdio: ["pipe", "pipe", "pipe"], env: process.env });
+  entry = { proc, sessions: new Map(), buffer: "" };
+  store.set(name, entry);
+
+  // Parse newline-delimited JSON-RPC from child stdout, broadcast to all sessions.
+  proc.stdout.on("data", (chunk) => {
+    entry.buffer += chunk.toString("utf8");
+    let idx;
+    while ((idx = entry.buffer.indexOf("\n")) >= 0) {
+      const raw = entry.buffer.slice(0, idx).trim();
+      entry.buffer = entry.buffer.slice(idx + 1);
+      if (!raw) continue;
+      const line = filterFrame(raw);
+      for (const send of entry.sessions.values()) {
+        try { send(`event: message\ndata: ${line}\n\n`); } catch { /* ignore broken pipe */ }
+      }
+    }
+  });
+
+  proc.stderr.on("data", (d) => console.log(`[mcp:${name}]`, d.toString().trim()));
+  proc.on("exit", (code) => {
+    console.log(`[mcp:${name}] exited`, code);
+    store.delete(name);
+  });
+
+  return entry;
+}
+
+function registerSession(name, sendFn) {
+  const entry = getOrSpawn(name);
+  const sid = crypto.randomUUID();
+  entry.sessions.set(sid, sendFn);
+  return sid;
+}
+
+function unregisterSession(name, sid) {
+  const entry = getStore().get(name);
+  if (!entry) return;
+  entry.sessions.delete(sid);
+  // No sessions left → kill child to avoid idle orphan process leak.
+  if (entry.sessions.size === 0) {
+    try { entry.proc.kill(); } catch { /* ignore */ }
+    getStore().delete(name);
+  }
+}
+
+// Kill all spawned MCP children — called on app shutdown to prevent orphans.
+function killAllBridges() {
+  const store = getStore();
+  for (const [name, entry] of store) {
+    try { entry.proc.kill(); } catch { /* ignore */ }
+    store.delete(name);
+  }
+}
+
+function sendToChild(name, jsonRpc) {
+  const entry = getStore().get(name);
+  if (!entry?.proc?.stdin?.writable) throw new Error(`Bridge not running: ${name}`);
+  entry.proc.stdin.write(`${JSON.stringify(jsonRpc)}\n`);
+}
+
+function isRunning(name) {
+  const entry = getStore().get(name);
+  return !!(entry?.proc && !entry.proc.killed && entry.proc.exitCode === null);
+}
+
+module.exports = { getOrSpawn, registerSession, unregisterSession, sendToChild, isRunning, findPlugin, killAllBridges };
diff --git a/src/lib/mitmAliasCache.js b/src/lib/mitmAliasCache.js
new file mode 100644
index 0000000..b6ae23c
--- /dev/null
+++ b/src/lib/mitmAliasCache.js
@@ -0,0 +1,46 @@
+// JSON cache for mitmAlias — read by standalone MITM server (no SQLite native binding).
+// Source of truth = SQLite kv['mitmAlias']. JSON is a read-replica synced on app start
+// and after every UI write.
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const DATA_DIR = process.env.DATA_DIR
+  || (process.platform === "win32"
+    ? path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "9router")
+    : path.join(os.homedir(), ".9router"));
+
+const CACHE_FILE = path.join(DATA_DIR, "mitm", "aliases.json");
+
+function writeAtomic(data) {
+  const dir = path.dirname(CACHE_FILE);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${CACHE_FILE}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), "utf8");
+  fs.renameSync(tmp, CACHE_FILE);
+}
+
+// Sync entire mitmAlias map from DB → JSON file
+export async function syncToJson() {
+  try {
+    const { getMitmAlias } = await import("@/lib/db/repos/aliasRepo.js");
+    const all = await getMitmAlias();
+    writeAtomic(all || {});
+  } catch (e) {
+    console.log("[mitmAliasCache] sync failed:", e.message);
+  }
+}
+
+// Update cache for a single tool after UI saves to DB
+export function writeAliasForTool(tool, mappings) {
+  try {
+    let current = {};
+    if (fs.existsSync(CACHE_FILE)) {
+      try { current = JSON.parse(fs.readFileSync(CACHE_FILE, "utf8")); } catch { /* corrupted → reset */ }
+    }
+    current[tool] = mappings || {};
+    writeAtomic(current);
+  } catch (e) {
+    console.log("[mitmAliasCache] write failed:", e.message);
+  }
+}
diff --git a/src/lib/network/connectionProxy.js b/src/lib/network/connectionProxy.js
new file mode 100644
index 0000000..9ecd253
--- /dev/null
+++ b/src/lib/network/connectionProxy.js
@@ -0,0 +1,187 @@
+import { getProxyPoolById } from "@/models";
+
+// Safely normalize any value into a trimmed string.
+function normalizeString(value) {
+  if (value === undefined || value === null) return "";
+  return String(value).trim();
+}
+
+// ─── Proxy pool rotation state (in-memory) ─────────────────────────
+const rotateState = new Map(); // providerId → { index }
+
+/**
+ * Pick one proxy pool ID from a list based on strategy.
+ * round-robin: cycle sequentially (in-memory, resets on restart)
+ * random:      uniform random pick
+ * none/single: return first entry
+ */
+export function pickProxyPoolId(poolIds, strategy, providerId) {
+  if (!poolIds || poolIds.length === 0) return null;
+  if (poolIds.length === 1) return poolIds[0];
+
+  if (strategy === "round-robin") {
+    const state = rotateState.get(providerId) || { index: -1 };
+    state.index = (state.index + 1) % poolIds.length;
+    rotateState.set(providerId, state);
+    return poolIds[state.index];
+  }
+
+  if (strategy === "random") {
+    return poolIds[Math.floor(Math.random() * poolIds.length)];
+  }
+
+  return poolIds[0]; // "none" or unknown
+}
+
+/**
+ * Normalize legacy proxy configuration.
+ */
+function normalizeLegacyProxy(providerSpecificData = {}) {
+  const connectionProxyEnabled =
+    providerSpecificData?.connectionProxyEnabled === true;
+
+  const connectionProxyUrl = normalizeString(
+    providerSpecificData?.connectionProxyUrl
+  );
+
+  const connectionNoProxy = normalizeString(
+    providerSpecificData?.connectionNoProxy
+  );
+
+  return {
+    connectionProxyEnabled,
+    connectionProxyUrl,
+    connectionNoProxy,
+  };
+}
+
+/**
+ * Resolve final proxy configuration.
+ *
+ * Priority:
+ * 1. Proxy Pool
+ * 2. Legacy Proxy
+ * 3. No Proxy
+ */
+export async function resolveConnectionProxyConfig(
+  providerSpecificData = {}
+) {
+  try {
+    const proxyPoolIdRaw = normalizeString(
+      providerSpecificData?.proxyPoolId
+    );
+
+    // "__none__" means explicitly disabled
+    const proxyPoolId =
+      proxyPoolIdRaw === "__none__" ? "" : proxyPoolIdRaw;
+
+    const legacy = normalizeLegacyProxy(providerSpecificData);
+
+    /**
+     * -----------------------------
+     * Proxy Pool Resolution
+     * -----------------------------
+     */
+    if (proxyPoolId) {
+      const proxyPool = await getProxyPoolById(proxyPoolId);
+
+      const proxyUrl = normalizeString(proxyPool?.proxyUrl);
+      const noProxy = normalizeString(proxyPool?.noProxy);
+
+      const isValidPool =
+        proxyPool &&
+        proxyPool.isActive === true &&
+        proxyUrl;
+
+      if (isValidPool) {
+        /**
+         * Vercel/Cloudflare relay proxies use base URL rewriting
+         * instead of HTTP_PROXY environment variables.
+         */
+        if (proxyPool.type === "vercel" || proxyPool.type === "cloudflare" || proxyPool.type === "deno") {
+          return {
+            source: proxyPool.type,
+
+            proxyPoolId,
+            proxyPool,
+
+            connectionProxyEnabled: false,
+            connectionProxyUrl: "",
+            connectionNoProxy: noProxy,
+
+            strictProxy: proxyPool.strictProxy === true,
+
+            vercelRelayUrl: proxyUrl, // Still mapped to vercelRelayUrl in the unified payload since they use the exact same header spec
+          };
+        }
+
+        /**
+         * Standard proxy pool
+         */
+        return {
+          source: "pool",
+
+          proxyPoolId,
+          proxyPool,
+
+          connectionProxyEnabled: true,
+          connectionProxyUrl: proxyUrl,
+          connectionNoProxy: noProxy,
+
+          strictProxy: proxyPool.strictProxy === true,
+        };
+      }
+    }
+
+    /**
+     * -----------------------------
+     * Legacy Proxy Fallback
+     * -----------------------------
+     */
+    if (
+      legacy.connectionProxyEnabled &&
+      legacy.connectionProxyUrl
+    ) {
+      return {
+        source: "legacy",
+
+        proxyPoolId: proxyPoolId || null,
+        proxyPool: null,
+
+        ...legacy,
+      };
+    }
+
+    /**
+     * -----------------------------
+     * No Proxy Config
+     * -----------------------------
+     */
+    return {
+      source: "none",
+
+      proxyPoolId: proxyPoolId || null,
+      proxyPool: null,
+
+      ...legacy,
+    };
+  } catch (error) {
+    console.error(
+      "[resolveConnectionProxyConfig] Failed to resolve proxy config:",
+      error
+    );
+
+    return {
+      source: "error",
+
+      proxyPoolId: null,
+      proxyPool: null,
+
+      connectionProxyEnabled: false,
+      connectionProxyUrl: "",
+      connectionNoProxy: "",
+
+      strictProxy: false,
+    };
+  }
+}
diff --git a/src/lib/network/initOutboundProxy.js b/src/lib/network/initOutboundProxy.js
new file mode 100644
index 0000000..52f3ca0
--- /dev/null
+++ b/src/lib/network/initOutboundProxy.js
@@ -0,0 +1,25 @@
+import { getSettings } from "@/lib/localDb";
+import { applyOutboundProxyEnv } from "@/lib/network/outboundProxy";
+
+let initialized = false;
+
+export async function ensureOutboundProxyInitialized() {
+  if (initialized) return true;
+
+  try {
+    const settings = await getSettings();
+    applyOutboundProxyEnv(settings);
+    initialized = true;
+  } catch (error) {
+    console.error("[ServerInit] Error initializing outbound proxy:", error);
+  }
+
+  return initialized;
+}
+
+// Defer init so HTTP server accepts connections first
+setImmediate(() => {
+  ensureOutboundProxyInitialized().catch(console.log);
+});
+
+export default ensureOutboundProxyInitialized;
diff --git a/src/lib/network/outboundProxy.js b/src/lib/network/outboundProxy.js
new file mode 100644
index 0000000..f85c63a
--- /dev/null
+++ b/src/lib/network/outboundProxy.js
@@ -0,0 +1,85 @@
+function normalizeString(value) {
+  if (value === undefined || value === null) return "";
+  return String(value).trim();
+}
+
+const ALLOWED_PROXY_SCHEMES = ["http:", "https:", "socks5:", "socks4:", "socks5h:", "socks4a:"];
+
+function validateProxyUrl(url) {
+  if (!url) return null;
+  if (/[\n\r`$]/.test(url)) return null;
+  try {
+    const parsed = new URL(url);
+    if (!ALLOWED_PROXY_SCHEMES.includes(parsed.protocol)) return null;
+    return parsed.href;
+  } catch {
+    return null;
+  }
+}
+
+export function applyOutboundProxyEnv(
+  { outboundProxyEnabled, outboundProxyUrl, outboundNoProxy } = {}
+) {
+  if (typeof process === "undefined" || !process.env) return;
+  const enabled = Boolean(outboundProxyEnabled);
+  const proxyUrl = normalizeString(outboundProxyUrl);
+  const noProxy = normalizeString(outboundNoProxy);
+
+  // If disabled, only clear env vars we previously managed.
+  if (!enabled) {
+    if (process.env.NINE_ROUTER_PROXY_MANAGED === "1") {
+      delete process.env.HTTP_PROXY;
+      delete process.env.HTTPS_PROXY;
+      delete process.env.ALL_PROXY;
+      delete process.env.NO_PROXY;
+      delete process.env.NINE_ROUTER_PROXY_MANAGED;
+      delete process.env.NINE_ROUTER_PROXY_URL;
+      delete process.env.NINE_ROUTER_NO_PROXY;
+    }
+    return;
+  }
+
+  // When enabled:
+  // - If values are provided, write them and mark as managed
+  // - If values are empty, do not touch externally-provided env,
+  //   but do clear values we previously managed.
+  const wasManaged = process.env.NINE_ROUTER_PROXY_MANAGED === "1";
+  let managed = false;
+
+  if (wasManaged) {
+    if (!proxyUrl) {
+      delete process.env.HTTP_PROXY;
+      delete process.env.HTTPS_PROXY;
+      delete process.env.ALL_PROXY;
+      delete process.env.NINE_ROUTER_PROXY_URL;
+    }
+    if (!noProxy) {
+      delete process.env.NO_PROXY;
+      delete process.env.NINE_ROUTER_NO_PROXY;
+    }
+  }
+
+  if (proxyUrl) {
+    const validated = validateProxyUrl(proxyUrl);
+    if (validated) {
+      process.env.HTTP_PROXY = validated;
+      process.env.HTTPS_PROXY = validated;
+      process.env.ALL_PROXY = validated;
+      process.env.NINE_ROUTER_PROXY_URL = validated;
+      managed = true;
+    }
+  }
+
+  if (noProxy) {
+    process.env.NO_PROXY = noProxy;
+    process.env.NINE_ROUTER_NO_PROXY = noProxy;
+    managed = true;
+  }
+
+  if (managed) {
+    process.env.NINE_ROUTER_PROXY_MANAGED = "1";
+  } else if (wasManaged) {
+    // If we previously managed env but now cleared everything, drop the marker.
+    delete process.env.NINE_ROUTER_PROXY_MANAGED;
+  }
+}
diff --git a/src/lib/network/proxyTest.js b/src/lib/network/proxyTest.js
new file mode 100644
index 0000000..402e679
--- /dev/null
+++ b/src/lib/network/proxyTest.js
@@ -0,0 +1,91 @@
+import { ProxyAgent, fetch as undiciFetch } from "undici";
+
+const DEFAULT_TEST_URL = "https://google.com/";
+const DEFAULT_TIMEOUT_MS = 8000;
+
+function getErrorMessage(err) {
+  if (!err) return "Unknown error";
+  const base = err?.message || String(err);
+  const causeCode = err?.cause?.code || err?.code;
+  const causeMessage = err?.cause?.message;
+
+  if (causeMessage && causeMessage !== base) {
+    return causeCode ? `${base}: ${causeMessage} (${causeCode})` : `${base}: ${causeMessage}`;
+  }
+
+  if (causeCode && !base.includes(causeCode)) {
+    return `${base} (${causeCode})`;
+  }
+
+  return base;
+}
+
+function normalizeString(value) {
+  if (value === undefined || value === null) return "";
+  return String(value).trim();
+}
+
+export async function testProxyUrl({ proxyUrl, testUrl, timeoutMs } = {}) {
+  const normalizedProxyUrl = normalizeString(proxyUrl);
+  if (!normalizedProxyUrl) {
+    return { ok: false, status: 400, error: "proxyUrl is required" };
+  }
+
+  const normalizedTestUrl = normalizeString(testUrl) || DEFAULT_TEST_URL;
+  const timeoutMsRaw = Number(timeoutMs);
+  const normalizedTimeoutMs =
+    Number.isFinite(timeoutMsRaw) && timeoutMsRaw > 0
+      ? Math.min(timeoutMsRaw, 30000)
+      : DEFAULT_TIMEOUT_MS;
+
+  let dispatcher;
+
+  try {
+    try {
+      dispatcher = new ProxyAgent({ uri: normalizedProxyUrl });
+    } catch (err) {
+      return {
+        ok: false,
+        status: 400,
+        error: `Invalid proxy URL: ${err?.message || String(err)}`,
+      };
+    }
+
+    const controller = new AbortController();
+    const startedAt = Date.now();
+    const timer = setTimeout(() => controller.abort(), normalizedTimeoutMs);
+
+    try {
+      const res = await undiciFetch(normalizedTestUrl, {
+        method: "HEAD",
+        dispatcher,
+        signal: controller.signal,
+        headers: {
+          "User-Agent": "9Router",
+        },
+      });
+
+      return {
+        ok: res.ok,
+        status: res.status,
+        statusText: res.statusText,
+        url: normalizedTestUrl,
+        elapsedMs: Date.now() - startedAt,
+      };
+    } catch (err) {
+      const message =
+        err?.name === "AbortError"
+          ? "Proxy test timed out"
+          : getErrorMessage(err);
+      return { ok: false, status: 500, error: message };
+    } finally {
+      clearTimeout(timer);
+    }
+  } finally {
+    try {
+      await dispatcher?.close?.();
+    } catch {
+      // ignore
+    }
+  }
+}
diff --git a/src/lib/oauth/constants/oauth.js b/src/lib/oauth/constants/oauth.js
new file mode 100644
index 0000000..1188b1f
--- /dev/null
+++ b/src/lib/oauth/constants/oauth.js
@@ -0,0 +1,145 @@
+/**
+ * OAuth Configuration Constants — static data lives in registry, re-exported here for consumers.
+ */
+import { platform, arch } from "os";
+import { ANTIGRAVITY_OAUTH_CLIENT, GOOGLE_OAUTH_CLIENT } from "open-sse/providers/shared.js";
+import { PROVIDER_OAUTH, PROVIDERS as REGISTRY_PROVIDERS } from "open-sse/providers/index.js";
+
+/**
+ * Get the platform enum value based on the current OS.
+ * Matches Antigravity binary's ClientMetadata.Platform enum.
+ */
+function getOAuthPlatformEnum() {
+  const os = platform();
+  const architecture = arch();
+  if (os === "darwin") return architecture === "arm64" ? 2 : 1;
+  if (os === "linux") return architecture === "arm64" ? 4 : 3;
+  if (os === "win32") return 5;
+  return 0;
+}
+
+// Claude OAuth Configuration (Authorization Code Flow with PKCE)
+export const CLAUDE_CONFIG = { ...PROVIDER_OAUTH["claude"] };
+
+// Codex (OpenAI) OAuth Configuration (Authorization Code Flow with PKCE)
+export const CODEX_CONFIG = { ...PROVIDER_OAUTH["codex"] };
+
+// Gemini (Google) OAuth Configuration (Standard OAuth2)
+// clientId/clientSecret from GOOGLE_OAUTH_CLIENT (shared.js) — not stored in registry
+export const GEMINI_CONFIG = { ...GOOGLE_OAUTH_CLIENT, ...PROVIDER_OAUTH["gemini-cli"] };
+
+// Qwen OAuth Configuration (Device Code Flow with PKCE)
+export const QWEN_CONFIG = { ...PROVIDER_OAUTH["qwen"] };
+
+// Qoder OAuth Configuration (Device Token Flow with PKCE).
+// Device tokens are long-lived (~30 days for access, ~360 for refresh).
+// The upstream refresh endpoint at center.qoder.sh returns 403 for our
+// flow — we accept that and surface it to the user as "re-login" instead
+// of attempting to silently rotate.
+export const QODER_CONFIG = { ...PROVIDER_OAUTH["qoder"] };
+
+// iFlow OAuth Configuration (Authorization Code)
+export const IFLOW_CONFIG = { ...PROVIDER_OAUTH["iflow"] };
+
+// Antigravity OAuth Configuration (Standard OAuth2 with Google)
+// clientId/clientSecret from ANTIGRAVITY_OAUTH_CLIENT (shared.js) — not stored in registry
+// loadCodeAssistClientMetadata is dynamic (runtime platform detection)
+export const ANTIGRAVITY_CONFIG = {
+  ...ANTIGRAVITY_OAUTH_CLIENT,
+  ...PROVIDER_OAUTH["antigravity"],
+  loadCodeAssistClientMetadata: JSON.stringify({ ideType: 9, platform: getOAuthPlatformEnum(), pluginType: 2 }),
+};
+
+/**
+ * Get client metadata using numeric enum values for API calls.
+ * @returns {{ ideType: number, platform: number, pluginType: number }}
+ */
+export function getOAuthClientMetadata() {
+  return { ideType: 9, platform: getOAuthPlatformEnum(), pluginType: 2 };
+}
+
+// OpenAI OAuth Configuration (Authorization Code Flow with PKCE)
+export const OPENAI_CONFIG = { ...PROVIDER_OAUTH["openai"] };
+
+// GitHub Copilot OAuth Configuration (Device Code Flow)
+export const GITHUB_CONFIG = { ...PROVIDER_OAUTH["github"] };
+
+// Kiro OAuth Configuration (multi-method: AWS Builder ID / IDC / Social / Import Token)
+export const KIRO_CONFIG = { ...PROVIDER_OAUTH["kiro"] };
+
+// AWS region allowlist pattern — prevents SSRF via region injection into upstream URLs (GHSA-6mwv-4mrm-5p3m)
+export const AWS_REGION_PATTERN = /^[a-z]{2}-[a-z]+-\d{1,2}$/;
+
+// Reject any region that is not a valid AWS region before interpolating it into a URL
+export function assertValidAwsRegion(region) {
+  if (typeof region !== "string" || !AWS_REGION_PATTERN.test(region)) {
+    throw new Error("Invalid region");
+  }
+  return region;
+}
+
+// Cursor OAuth Configuration (Import Token from Cursor IDE)
+// tokenStoragePaths: user-reference only, not stored in registry
+export const CURSOR_CONFIG = {
+  ...PROVIDER_OAUTH["cursor"],
+  tokenStoragePaths: {
+    linux: "~/.config/Cursor/User/globalStorage/state.vscdb",
+    macos: "/Users/<user>/Library/Application Support/Cursor/User/globalStorage/state.vscdb",
+    windows: "%APPDATA%\\Cursor\\User\\globalStorage\\state.vscdb",
+  },
+};
+
+// Kimi Coding OAuth Configuration (Device Code Flow)
+// clientId uses env override — dynamic, not stored in registry
+export const KIMI_CODING_CONFIG = {
+  ...PROVIDER_OAUTH["kimi-coding"],
+  clientId: process.env.KIMI_CODING_OAUTH_CLIENT_ID || REGISTRY_PROVIDERS["kimi-coding"]?.clientId,
+};
+
+// KiloCode OAuth Configuration (Custom Device Auth Flow)
+export const KILOCODE_CONFIG = { ...PROVIDER_OAUTH["kilocode"] };
+
+// Cline OAuth Configuration (Local Callback Flow via app.cline.bot)
+export const CLINE_CONFIG = { ...PROVIDER_OAUTH["cline"] };
+
+// ClinePass OAuth Configuration (shares Cline's OAuth endpoints)
+export const CLINEPASS_CONFIG = { ...PROVIDER_OAUTH["clinepass"] };
+
+// GitLab Duo OAuth Configuration (Authorization Code Flow with PKCE)
+export const GITLAB_CONFIG = { ...PROVIDER_OAUTH["gitlab"] };
+
+// CodeBuddy (Tencent) OAuth Configuration (Browser OAuth Polling Flow)
+export const CODEBUDDY_CONFIG = { ...PROVIDER_OAUTH["codebuddy-cn"] };
+
+// Kimchi OAuth Configuration (Browser token callback flow)
+export const KIMCHI_CONFIG = { ...PROVIDER_OAUTH["kimchi"] };
+
+// Grok CLI / Grok Build OAuth Configuration (Device Code Flow)
+// Endpoint: cli-chat-proxy.grok.com — same client_id as xai, different flow + scopes
+export const GROK_CLI_CONFIG = { ...PROVIDER_OAUTH["grok-cli"] };
+
+// OAuth timeout (5 minutes)
+export const OAUTH_TIMEOUT = 300000;
+
+// Provider list
+export const PROVIDERS = {
+  CLAUDE: "claude",
+  CODEX: "codex",
+  GEMINI: "gemini-cli",
+  QWEN: "qwen",
+  QODER: "qoder",
+  IFLOW: "iflow",
+  ANTIGRAVITY: "antigravity",
+  OPENAI: "openai",
+  GITHUB: "github",
+  KIRO: "kiro",
+  CURSOR: "cursor",
+  KIMI_CODING: "kimi-coding",
+  KILOCODE: "kilocode",
+  CLINE: "cline",
+  CLINEPASS: "clinepass",
+  GITLAB: "gitlab",
+  CODEBUDDY: "codebuddy-cn",
+  KIMCHI: "kimchi",
+  GROK_CLI: "grok-cli",
+};
diff --git a/src/lib/oauth/constants/xai.js b/src/lib/oauth/constants/xai.js
new file mode 100644
index 0000000..4bb22e3
--- /dev/null
+++ b/src/lib/oauth/constants/xai.js
@@ -0,0 +1,62 @@
+/**
+ * xAI (Grok) OAuth Configuration
+ *
+ * Source of truth: router-for-me/CLIProxyAPI internal/auth/xai/types.go
+ * Mirrors the upstream Go constants 1:1.
+ */
+import { PROVIDERS } from "open-sse/providers/index.js";
+
+// xAI client_id for OAuth (PKCE public client) — single source: registry xai.transport
+export const XAI_CLIENT_ID = PROVIDERS["xai"]?.clientId;
+
+// OAuth issuer + endpoints
+export const XAI_ISSUER = "https://auth.x.ai";
+export const XAI_AUTH_ENDPOINT_PATH = "/oauth2/authorize";
+export const XAI_TOKEN_ENDPOINT_PATH = "/oauth2/token";
+export const XAI_DISCOVERY_PATH = "/.well-known/openid-configuration";
+
+// Scopes (space-separated, matches Go upstream)
+export const XAI_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+
+// xAI inference API base URL
+export const XAI_API_BASE = "https://api.x.ai/v1";
+
+// Loopback callback (PKCE)
+export const XAI_LOOPBACK_PORT = 56121;
+export const XAI_CALLBACK_PATH = "/callback";
+export const XAI_REDIRECT_URI = `http://127.0.0.1:${XAI_LOOPBACK_PORT}${XAI_CALLBACK_PATH}`;
+
+// PKCE verifier length (bytes pre-base64url)
+export const XAI_PKCE_VERIFIER_BYTES = 96;
+
+// Refresh tokens this many seconds before expiry
+export const XAI_REFRESH_LEAD_SECONDS = 5 * 60;
+
+// User-Agent — mirror Go grok-cli UA. Version is best-effort; xAI does not pin a specific version.
+export const XAI_USER_AGENT = "grok-cli/9router";
+
+/**
+ * Aggregated config object — mirrors the shape of CLAUDE_CONFIG/CODEX_CONFIG in oauth.js.
+ * Includes both the discovery-derived defaults and the static fallbacks used when
+ * discovery is unavailable. Discovery results override authorizeUrl/tokenUrl at runtime.
+ */
+export const XAI_CONFIG = {
+  clientId: XAI_CLIENT_ID,
+  issuer: XAI_ISSUER,
+  authEndpointPath: XAI_AUTH_ENDPOINT_PATH,
+  tokenEndpointPath: XAI_TOKEN_ENDPOINT_PATH,
+  discoveryPath: XAI_DISCOVERY_PATH,
+  // Static fallbacks (these are also the values returned by xAI discovery today)
+  authorizeUrl: `${XAI_ISSUER}${XAI_AUTH_ENDPOINT_PATH}`,
+  tokenUrl: `${XAI_ISSUER}${XAI_TOKEN_ENDPOINT_PATH}`,
+  discoveryUrl: `${XAI_ISSUER}${XAI_DISCOVERY_PATH}`,
+  scope: XAI_SCOPE,
+  apiBaseUrl: XAI_API_BASE,
+  redirectUri: XAI_REDIRECT_URI,
+  loopbackPort: XAI_LOOPBACK_PORT,
+  callbackPath: XAI_CALLBACK_PATH,
+  pkceVerifierBytes: XAI_PKCE_VERIFIER_BYTES,
+  refreshLeadSeconds: XAI_REFRESH_LEAD_SECONDS,
+  userAgent: XAI_USER_AGENT,
+  codeChallengeMethod: "S256",
+};
diff --git a/src/lib/oauth/kiroExternalIdp.js b/src/lib/oauth/kiroExternalIdp.js
new file mode 100644
index 0000000..d07fb46
--- /dev/null
+++ b/src/lib/oauth/kiroExternalIdp.js
@@ -0,0 +1,155 @@
+const MICROSOFT_TOKEN_ENDPOINT_HOSTS = new Set([
+  "login.microsoftonline.com",
+  "login.microsoft.com",
+  "login.windows.net",
+]);
+
+const DEFAULT_REGION = "us-east-1";
+const DEFAULT_EXPIRES_IN = 3600;
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function validateMicrosoftTokenEndpoint(rawEndpoint) {
+  const tokenEndpoint = normalizeString(rawEndpoint);
+  if (!tokenEndpoint) throw new Error("token_endpoint is required");
+
+  let parsed;
+  try {
+    parsed = new URL(tokenEndpoint);
+  } catch {
+    throw new Error("token_endpoint must be a valid URL");
+  }
+
+  if (parsed.protocol !== "https:") {
+    throw new Error("token_endpoint must use https");
+  }
+
+  const host = parsed.hostname.toLowerCase();
+  if (!MICROSOFT_TOKEN_ENDPOINT_HOSTS.has(host)) {
+    throw new Error("token_endpoint must be a Microsoft login endpoint");
+  }
+
+  return parsed.toString();
+}
+
+export function normalizeScope(scopes) {
+  if (Array.isArray(scopes)) {
+    return scopes.map(normalizeString).filter(Boolean).join(" ");
+  }
+  return normalizeString(scopes);
+}
+
+export function decodeJwtPayload(jwt) {
+  try {
+    if (!jwt || typeof jwt !== "string") return null;
+    const parts = jwt.split(".");
+    if (parts.length !== 3) return null;
+    const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padding = (4 - (base64.length % 4)) % 4;
+    return JSON.parse(Buffer.from(`${base64}${"=".repeat(padding)}`, "base64").toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function resolveExpiresAt(input) {
+  const explicit = input.expired || input.expires_at || input.expiresAt;
+  if (explicit) {
+    const ms = new Date(explicit).getTime();
+    if (Number.isFinite(ms)) return new Date(ms).toISOString();
+  }
+
+  const expiresIn = Number(input.expires_in || input.expiresIn || 0);
+  if (Number.isFinite(expiresIn) && expiresIn > 0) {
+    return new Date(Date.now() + expiresIn * 1000).toISOString();
+  }
+
+  const payload = decodeJwtPayload(input.access_token || input.accessToken);
+  if (payload?.exp) {
+    return new Date(payload.exp * 1000).toISOString();
+  }
+
+  return new Date(Date.now() + DEFAULT_EXPIRES_IN * 1000).toISOString();
+}
+
+export function normalizeKiroExternalIdpAuth(rawAuth) {
+  let input = rawAuth;
+  if (typeof input === "string") {
+    try {
+      input = JSON.parse(input);
+    } catch {
+      throw new Error("CLIProxyAPI auth JSON is invalid");
+    }
+  }
+
+  if (!input || typeof input !== "object") {
+    throw new Error("CLIProxyAPI auth JSON is required");
+  }
+
+  const authMethod = normalizeString(input.auth_method || input.authMethod);
+  if (authMethod && authMethod !== "external_idp") {
+    throw new Error("Only external_idp Kiro auth is supported by this importer");
+  }
+
+  const accessToken = normalizeString(input.access_token || input.accessToken);
+  const refreshToken = normalizeString(input.refresh_token || input.refreshToken);
+  const clientId = normalizeString(input.client_id || input.clientId);
+  const tokenEndpoint = validateMicrosoftTokenEndpoint(input.token_endpoint || input.tokenEndpoint);
+  const profileArn = normalizeString(input.profile_arn || input.profileArn);
+  const region = normalizeString(input.region) || DEFAULT_REGION;
+  const scope = normalizeScope(input.scopes || input.scope);
+
+  if (!accessToken) throw new Error("access_token is required");
+  if (!refreshToken) throw new Error("refresh_token is required");
+  if (!clientId) throw new Error("client_id is required");
+  if (!scope) throw new Error("scopes is required");
+  if (!profileArn) throw new Error("profile_arn is required");
+
+  const payload = decodeJwtPayload(accessToken);
+  const email = input.email || payload?.email || payload?.preferred_username || payload?.upn || payload?.sub || null;
+
+  return {
+    accessToken,
+    refreshToken,
+    expiresAt: resolveExpiresAt(input),
+    email,
+    providerSpecificData: {
+      profileArn,
+      region,
+      authMethod: "external_idp",
+      provider: "CLIProxyAPI",
+      clientId,
+      tokenEndpoint,
+      scope,
+    },
+  };
+}
+
+export function buildExternalIdpRefreshParams(refreshToken, providerSpecificData = {}) {
+  const clientId = normalizeString(providerSpecificData.clientId || providerSpecificData.client_id);
+  const tokenEndpoint = validateMicrosoftTokenEndpoint(providerSpecificData.tokenEndpoint || providerSpecificData.token_endpoint);
+  const scope = normalizeScope(providerSpecificData.scope || providerSpecificData.scopes);
+
+  if (!refreshToken) throw new Error("refresh token is required");
+  if (!clientId) throw new Error("clientId is required for external_idp refresh");
+  if (!scope) throw new Error("scope is required for external_idp refresh");
+
+  return {
+    tokenEndpoint,
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: clientId,
+      refresh_token: refreshToken,
+      scope,
+    }),
+    providerSpecificData: {
+      ...providerSpecificData,
+      authMethod: "external_idp",
+      clientId,
+      tokenEndpoint,
+      scope,
+    },
+  };
+}
diff --git a/src/lib/oauth/providerHelpers.js b/src/lib/oauth/providerHelpers.js
new file mode 100644
index 0000000..0cb4693
--- /dev/null
+++ b/src/lib/oauth/providerHelpers.js
@@ -0,0 +1,90 @@
+const BASE64_BLOCK_SIZE = 4;
+
+function validateXaiOAuthEndpoint(rawUrl, field) {
+  const value = String(rawUrl || "").trim();
+  if (!value) throw new Error(`xai discovery ${field} is empty`);
+  let parsed;
+  try { parsed = new URL(value); } catch (err) {
+    throw new Error(`xai discovery ${field} is invalid: ${err.message}`);
+  }
+  if (parsed.protocol !== "https:") throw new Error(`xai discovery ${field} must use https: ${value}`);
+  const host = parsed.hostname.toLowerCase().trim();
+  if (host !== "x.ai" && !host.endsWith(".x.ai")) {
+    throw new Error(`xai discovery ${field} host ${host} is not on x.ai`);
+  }
+  return value;
+}
+
+function decodeXaiIdTokenEmail(idToken) {
+  if (!idToken || typeof idToken !== "string") return undefined;
+  const parts = idToken.split(".");
+  if (parts.length !== 3) return undefined;
+  try {
+    const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padding = (BASE64_BLOCK_SIZE - (base64.length % BASE64_BLOCK_SIZE)) % BASE64_BLOCK_SIZE;
+    const json = Buffer.from(base64 + "=".repeat(padding), "base64").toString("utf8");
+    const payload = JSON.parse(json);
+    return payload.email || payload.preferred_username || payload.sub || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function decodeJwtPayload(jwt) {
+  try {
+    if (!jwt || typeof jwt !== "string") return null;
+    const parts = jwt.split(".");
+    if (parts.length !== 3) return null;
+    const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const missingPadding = (BASE64_BLOCK_SIZE - (base64.length % BASE64_BLOCK_SIZE)) % BASE64_BLOCK_SIZE;
+    const padded = base64 + "=".repeat(missingPadding);
+    return JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function extractEmailFromAccessToken(accessToken) {
+  const payload = decodeJwtPayload(accessToken);
+  if (!payload) return undefined;
+  return payload.email || payload.preferred_username || payload.sub || undefined;
+}
+
+export async function fetchKiroProfileArn(accessToken) {
+  if (!accessToken) return null;
+  try {
+    const response = await fetch("https://codewhisperer.us-east-1.amazonaws.com/ListAvailableProfiles", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      },
+      body: JSON.stringify({ maxResults: 10 }),
+    });
+    if (!response.ok) return null;
+    const data = await response.json();
+    return data.profiles?.find((p) => p.arn?.trim())?.arn?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export function extractCodexAccountInfo(idToken) {
+  const payload = decodeJwtPayload(idToken);
+  if (!payload) return {};
+  const chatgpt = payload["https://api.openai.com/auth"] || {};
+  return {
+    email: payload.email,
+    chatgptAccountId: chatgpt.chatgpt_account_id || payload.account_id,
+    chatgptPlanType: chatgpt.chatgpt_plan_type || payload.plan_type,
+  };
+}
+
+export {
+  BASE64_BLOCK_SIZE,
+  validateXaiOAuthEndpoint,
+  decodeXaiIdTokenEmail,
+  decodeJwtPayload,
+  extractEmailFromAccessToken,
+};
diff --git a/src/lib/oauth/providers.js b/src/lib/oauth/providers.js
new file mode 100644
index 0000000..484ecf9
--- /dev/null
+++ b/src/lib/oauth/providers.js
@@ -0,0 +1,1681 @@
+/**
+ * OAuth Provider Configurations and Handlers
+ * Centralized DRY approach for all OAuth providers
+ */
+
+// Ensure outbound fetch respects HTTP(S)_PROXY/ALL_PROXY in Node runtime
+import "open-sse/index.js";
+import crypto from "crypto";
+
+import { generatePKCE, generateState } from "./utils/pkce";
+import {
+  CLAUDE_CONFIG,
+  CODEX_CONFIG,
+  GEMINI_CONFIG,
+  QWEN_CONFIG,
+  QODER_CONFIG,
+  IFLOW_CONFIG,
+  ANTIGRAVITY_CONFIG,
+  GITHUB_CONFIG,
+  KIRO_CONFIG,
+  assertValidAwsRegion,
+  CURSOR_CONFIG,
+  KIMI_CODING_CONFIG,
+  KILOCODE_CONFIG,
+  CLINE_CONFIG,
+  CLINEPASS_CONFIG,
+  GITLAB_CONFIG,
+  CODEBUDDY_CONFIG,
+  KIMCHI_CONFIG,
+  GROK_CLI_CONFIG,
+  getOAuthClientMetadata,
+} from "./constants/oauth";
+import { XAI_CONFIG, XAI_PKCE_VERIFIER_BYTES } from "./constants/xai";
+import {
+  validateXaiOAuthEndpoint,
+  decodeXaiIdTokenEmail,
+  extractEmailFromAccessToken,
+  extractCodexAccountInfo,
+  fetchKiroProfileArn,
+} from "./providerHelpers";
+
+export { extractCodexAccountInfo, fetchKiroProfileArn };
+
+// Inlined from services/xai.js to keep web route bundle free of `open` (CLI-only) package
+let cachedXaiDiscovery = null;
+
+async function discoverXaiEndpoints() {
+  if (cachedXaiDiscovery) return cachedXaiDiscovery;
+  try {
+    const res = await fetch(XAI_CONFIG.discoveryUrl, { headers: { Accept: "application/json" } });
+    if (res.ok) {
+      const data = await res.json();
+      cachedXaiDiscovery = {
+        authorizeUrl: validateXaiOAuthEndpoint(data.authorization_endpoint, "authorization_endpoint"),
+        tokenUrl: validateXaiOAuthEndpoint(data.token_endpoint, "token_endpoint"),
+      };
+      return cachedXaiDiscovery;
+    }
+  } catch { /* fall through to static fallback */ }
+  cachedXaiDiscovery = { authorizeUrl: XAI_CONFIG.authorizeUrl, tokenUrl: XAI_CONFIG.tokenUrl };
+  return cachedXaiDiscovery;
+}
+
+// Provider configurations
+const PROVIDERS = {
+  claude: {
+    config: CLAUDE_CONFIG,
+    flowType: "authorization_code_pkce",
+    buildAuthUrl: (config, redirectUri, state, codeChallenge) => {
+      const params = new URLSearchParams({
+        code: "true",
+        client_id: config.clientId,
+        response_type: "code",
+        redirect_uri: redirectUri,
+        scope: config.scopes.join(" "),
+        code_challenge: codeChallenge,
+        code_challenge_method: config.codeChallengeMethod,
+        state: state,
+      });
+      return `${config.authorizeUrl}?${params.toString()}`;
+    },
+    exchangeToken: async (config, code, redirectUri, codeVerifier, state) => {
+      // Parse code - may contain state after #
+      let authCode = code;
+      let codeState = "";
+      if (authCode.includes("#")) {
+        const parts = authCode.split("#");
+        authCode = parts[0];
+        codeState = parts[1] || "";
+      }
+
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body: JSON.stringify({
+          code: authCode,
+          state: codeState || state,
+          grant_type: "authorization_code",
+          client_id: config.clientId,
+          redirect_uri: redirectUri,
+          code_verifier: codeVerifier,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Token exchange failed: ${error}`);
+      }
+
+      return await response.json();
+    },
+    mapTokens: (tokens) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_in,
+      scope: tokens.scope,
+    }),
+  },
+
+  codex: {
+    config: CODEX_CONFIG,
+    flowType: "authorization_code_pkce",
+    fixedPort: CODEX_CONFIG.fixedPort,
+    callbackPath: CODEX_CONFIG.callbackPath,
+    buildAuthUrl: (config, redirectUri, state, codeChallenge) => {
+      const params = {
+        response_type: "code",
+        client_id: config.clientId,
+        redirect_uri: redirectUri,
+        scope: config.scope,
+        code_challenge: codeChallenge,
+        code_challenge_method: config.codeChallengeMethod,
+        ...config.extraParams,
+        state: state,
+      };
+      const queryString = Object.entries(params)
+        .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+        .join("&");
+      return `${config.authorizeUrl}?${queryString}`;
+    },
+    exchangeToken: async (config, code, redirectUri, codeVerifier) => {
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          client_id: config.clientId,
+          code: code,
+          redirect_uri: redirectUri,
+          code_verifier: codeVerifier,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Token exchange failed: ${error}`);
+      }
+
+      return await response.json();
+    },
+    mapTokens: (tokens) => {
+      const info = extractCodexAccountInfo(tokens.id_token);
+      const mapped = {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        idToken: tokens.id_token,
+        expiresIn: tokens.expires_in,
+        lastRefreshAt: new Date().toISOString(),
+      };
+      const email = info.email || extractEmailFromAccessToken(tokens.access_token);
+      if (email) mapped.email = email;
+      if (info.chatgptAccountId || info.chatgptPlanType) {
+        mapped.providerSpecificData = {
+          chatgptAccountId: info.chatgptAccountId,
+          chatgptPlanType: info.chatgptPlanType,
+        };
+      }
+      return mapped;
+    },
+  },
+
+  xai: {
+    config: XAI_CONFIG,
+    flowType: "authorization_code_pkce",
+    fixedPort: XAI_CONFIG.loopbackPort,
+    callbackPath: XAI_CONFIG.callbackPath,
+    pkceVerifierBytes: XAI_PKCE_VERIFIER_BYTES,
+    prepareConfig: async (config) => {
+      const endpoints = await discoverXaiEndpoints();
+      return {
+        ...config,
+        authorizeUrl: endpoints.authorizeUrl,
+        tokenUrl: endpoints.tokenUrl,
+      };
+    },
+    buildAuthUrl: (config, redirectUri, state, codeChallenge) => {
+      // Mirror CLIProxyAPI BuildAuthorizeURL: includes nonce, plan, referrer
+      const nonce = crypto.randomBytes(16).toString("hex");
+      const params = {
+        response_type: "code",
+        client_id: config.clientId,
+        redirect_uri: redirectUri,
+        scope: config.scope,
+        code_challenge: codeChallenge,
+        code_challenge_method: config.codeChallengeMethod,
+        state,
+        nonce,
+        plan: "generic",
+        referrer: "cli-proxy-api",
+      };
+      const qs = Object.entries(params)
+        .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+        .join("&");
+      return `${config.authorizeUrl}?${qs}`;
+    },
+    exchangeToken: async (config, code, redirectUri, codeVerifier) => {
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          client_id: config.clientId,
+          code,
+          redirect_uri: redirectUri,
+          code_verifier: codeVerifier,
+        }),
+      });
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`xAI token exchange failed: ${error}`);
+      }
+      return await response.json();
+    },
+    mapTokens: (tokens) => {
+      const mapped = {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+        scope: tokens.scope,
+      };
+      const email = decodeXaiIdTokenEmail(tokens.id_token);
+      if (email) mapped.email = email;
+      if (tokens.id_token) {
+        mapped.providerSpecificData = { idToken: tokens.id_token };
+      }
+      return mapped;
+    },
+  },
+
+  // Grok CLI / Grok Build — device code flow to auth.x.ai, inference on cli-chat-proxy.grok.com
+  "grok-cli": {
+    config: GROK_CLI_CONFIG,
+    flowType: "device_code",
+    requestDeviceCode: async (config) => {
+      const body = new URLSearchParams({
+        client_id: config.clientId,
+        scope: config.scope,
+      });
+      // Official CLI sends referrer=grok-build
+      if (config.referrer) body.set("referrer", config.referrer);
+
+      const response = await fetch(config.deviceCodeUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+          "User-Agent": "grok-pager/0.2.93 grok-shell/0.2.93 (linux; x86_64)",
+        },
+        body,
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Grok CLI device code request failed: ${error}`);
+      }
+
+      return await response.json();
+    },
+    pollToken: async (config, deviceCode) => {
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+          "User-Agent": "grok-pager/0.2.93 grok-shell/0.2.93 (linux; x86_64)",
+        },
+        body: new URLSearchParams({
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          device_code: deviceCode,
+          client_id: config.clientId,
+        }),
+      });
+
+      let data;
+      try {
+        data = await response.json();
+      } catch {
+        const text = await response.text();
+        data = { error: "invalid_response", error_description: text };
+      }
+
+      // Device flow: 400 + authorization_pending is expected while user authorizes
+      const pending =
+        data?.error === "authorization_pending" ||
+        data?.error === "slow_down";
+      return {
+        ok: response.ok || pending,
+        data,
+      };
+    },
+    postExchange: async (tokens) => {
+      // Best-effort user profile from cli-chat-proxy (non-fatal)
+      try {
+        const res = await fetch("https://cli-chat-proxy.grok.com/v1/user", {
+          headers: {
+            Authorization: `Bearer ${tokens.access_token}`,
+            Accept: "application/json",
+            "User-Agent": "grok-pager/0.2.93 grok-shell/0.2.93 (linux; x86_64)",
+            "x-xai-token-auth": "xai-grok-cli",
+            "x-grok-client-version": "0.2.93",
+          },
+        });
+        if (res.ok) return { user: await res.json() };
+      } catch {
+        /* ignore */
+      }
+      return { user: null };
+    },
+    mapTokens: (tokens, extra) => {
+      const email =
+        decodeXaiIdTokenEmail(tokens.id_token) ||
+        extractEmailFromAccessToken(tokens.access_token) ||
+        extra?.user?.email ||
+        null;
+      const userId =
+        extra?.user?.userId ||
+        extra?.user?.principalId ||
+        null;
+      const displayName = [extra?.user?.firstName, extra?.user?.lastName]
+        .filter(Boolean)
+        .join(" ")
+        .trim() || null;
+
+      return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token || null,
+        expiresIn: tokens.expires_in,
+        scope: tokens.scope,
+        // Top-level for dashboard connection cards
+        email: email || undefined,
+        displayName: displayName || undefined,
+        // Mirror identity into providerSpecificData so GrokCliExecutor can set
+        // x-email / x-userid without depending on top-level credential shape.
+        providerSpecificData: {
+          authMethod: "device_code",
+          idToken: tokens.id_token || null,
+          email: email || null,
+          userId,
+          hasGrokCodeAccess: extra?.user?.hasGrokCodeAccess ?? null,
+          subscriptionTier: extra?.user?.subscriptionTier ?? null,
+        },
+      };
+    },
+  },
+
+  "gemini-cli": {
+    config: GEMINI_CONFIG,
+    flowType: "authorization_code",
+    buildAuthUrl: (config, redirectUri, state) => {
+      const params = new URLSearchParams({
+        client_id: config.clientId,
+        response_type: "code",
+        redirect_uri: redirectUri,
+        scope: config.scopes.join(" "),
+        state: state,
+        access_type: "offline",
+        prompt: "consent",
+      });
+      return `${config.authorizeUrl}?${params.toString()}`;
+    },
+    exchangeToken: async (config, code, redirectUri) => {
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          client_id: config.clientId,
+          client_secret: config.clientSecret,
+          code: code,
+          redirect_uri: redirectUri,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Token exchange failed: ${error}`);
+      }
+
+      return await response.json();
+    },
+    postExchange: async (tokens) => {
+      // Fetch user info
+      const userInfoRes = await fetch(`${GEMINI_CONFIG.userInfoUrl}?alt=json`, {
+        headers: { Authorization: `Bearer ${tokens.access_token}` },
+      });
+      const userInfo = userInfoRes.ok ? await userInfoRes.json() : {};
+
+      // Fetch project ID
+      let projectId = "";
+      try {
+        const projectRes = await fetch(
+          "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+          {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${tokens.access_token}`,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+              metadata: getOAuthClientMetadata(),
+              mode: 1,
+            }),
+          }
+        );
+        if (projectRes.ok) {
+          const data = await projectRes.json();
+          projectId = data.cloudaicompanionProject?.id || data.cloudaicompanionProject || "";
+        }
+      } catch (e) {
+        console.log("Failed to fetch project ID:", e);
+      }
+
+      return { userInfo, projectId };
+    },
+    mapTokens: (tokens, extra) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_in,
+      scope: tokens.scope,
+      email: extra?.userInfo?.email,
+      projectId: extra?.projectId,
+    }),
+  },
+
+  antigravity: {
+    config: ANTIGRAVITY_CONFIG,
+    flowType: "authorization_code",
+    buildAuthUrl: (config, redirectUri, state) => {
+      const params = new URLSearchParams({
+        client_id: config.clientId,
+        response_type: "code",
+        redirect_uri: redirectUri,
+        scope: config.scopes.join(" "),
+        state: state,
+        access_type: "offline",
+        prompt: "consent",
+      });
+      return `${config.authorizeUrl}?${params.toString()}`;
+    },
+    exchangeToken: async (config, code, redirectUri) => {
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          client_id: config.clientId,
+          client_secret: config.clientSecret,
+          code: code,
+          redirect_uri: redirectUri,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Token exchange failed: ${error}`);
+      }
+
+      return await response.json();
+    },
+    postExchange: async (tokens) => {
+      // Numeric enums matching Antigravity binary ClientMetadata
+      const loadHeaders = {
+        "Authorization": `Bearer ${tokens.access_token}`,
+        "Content-Type": "application/json",
+        "User-Agent": ANTIGRAVITY_CONFIG.loadCodeAssistUserAgent,
+        "X-Goog-Api-Client": ANTIGRAVITY_CONFIG.loadCodeAssistApiClient,
+        "Client-Metadata": ANTIGRAVITY_CONFIG.loadCodeAssistClientMetadata,
+        "x-request-source": "local",
+      };
+      const metadata = getOAuthClientMetadata();
+
+      // Fetch user info
+      const userInfoRes = await fetch(`${ANTIGRAVITY_CONFIG.userInfoUrl}?alt=json`, {
+        headers: {
+          Authorization: `Bearer ${tokens.access_token}`,
+          "x-request-source": "local",
+        },
+      });
+      const userInfo = userInfoRes.ok ? await userInfoRes.json() : {};
+
+      // Load Code Assist to get project ID and tier
+      let projectId = "";
+      let tierId = "legacy-tier";
+      try {
+        const loadRes = await fetch(ANTIGRAVITY_CONFIG.loadCodeAssistEndpoint, {
+          method: "POST",
+          headers: loadHeaders,
+          body: JSON.stringify({ metadata }),
+        });
+        if (loadRes.ok) {
+          const data = await loadRes.json();
+          projectId = data.cloudaicompanionProject?.id || data.cloudaicompanionProject || "";
+          if (Array.isArray(data.allowedTiers)) {
+            for (const tier of data.allowedTiers) {
+              if (tier.isDefault && tier.id) {
+                tierId = tier.id.trim();
+                break;
+              }
+            }
+          }
+        }
+      } catch (e) {
+        console.log("Failed to load code assist:", e);
+      }
+
+      // Fire-and-forget onboarding — does not block DB save
+      if (projectId) {
+        const doOnboard = async () => {
+          for (let i = 0; i < 10; i++) {
+            try {
+              const onboardRes = await fetch(ANTIGRAVITY_CONFIG.onboardUserEndpoint, {
+                method: "POST",
+                headers: loadHeaders,
+                body: JSON.stringify({ tierId, metadata }),
+              });
+              if (onboardRes.ok) {
+                const result = await onboardRes.json();
+                if (result.done === true) break;
+              }
+            } catch (e) {
+              break;
+            }
+            await new Promise(resolve => setTimeout(resolve, 5000));
+          }
+        };
+        doOnboard().catch(() => {});
+      }
+
+      return { userInfo, projectId };
+    },
+    mapTokens: (tokens, extra) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_in,
+      scope: tokens.scope,
+      email: extra?.userInfo?.email,
+      projectId: extra?.projectId,
+    }),
+  },
+
+  iflow: {
+    config: IFLOW_CONFIG,
+    flowType: "authorization_code",
+    buildAuthUrl: (config, redirectUri, state) => {
+      const params = new URLSearchParams({
+        loginMethod: config.extraParams.loginMethod,
+        type: config.extraParams.type,
+        redirect: redirectUri,
+        state: state,
+        client_id: config.clientId,
+      });
+      return `${config.authorizeUrl}?${params.toString()}`;
+    },
+    exchangeToken: async (config, code, redirectUri) => {
+      // Create Basic Auth header
+      const basicAuth = Buffer.from(
+        `${config.clientId}:${config.clientSecret}`
+      ).toString("base64");
+
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+          Authorization: `Basic ${basicAuth}`,
+        },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code: code,
+          redirect_uri: redirectUri,
+          client_id: config.clientId,
+          client_secret: config.clientSecret,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Token exchange failed: ${error}`);
+      }
+
+      return await response.json();
+    },
+    postExchange: async (tokens) => {
+      // Fetch user info (MUST succeed to get API key)
+      const userInfoRes = await fetch(
+        `${IFLOW_CONFIG.userInfoUrl}?accessToken=${encodeURIComponent(tokens.access_token)}`,
+        {
+          headers: {
+            Accept: "application/json",
+          },
+        }
+      );
+      
+      if (!userInfoRes.ok) {
+        const errorText = await userInfoRes.text();
+        throw new Error(`Failed to fetch user info: ${errorText}`);
+      }
+      
+      const result = await userInfoRes.json();
+      if (!result.success) {
+        throw new Error(`User info request failed: ${result.message || 'Unknown error'}`);
+      }
+      
+      const userInfo = result.data || {};
+      
+      // Validate API key (critical for iFlow)
+      if (!userInfo.apiKey || userInfo.apiKey.trim() === "") {
+        throw new Error("Empty API key returned from iFlow");
+      }
+      
+      // Validate email/phone
+      const email = userInfo.email?.trim() || userInfo.phone?.trim();
+      if (!email) {
+        throw new Error("Missing account email/phone in user info");
+      }
+      
+      return { userInfo };
+    },
+    mapTokens: (tokens, extra) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_in,
+      apiKey: extra?.userInfo?.apiKey,
+      email: extra?.userInfo?.email || extra?.userInfo?.phone,
+      displayName: extra?.userInfo?.nickname || extra?.userInfo?.name,
+    }),
+  },
+
+  qoder: {
+    config: QODER_CONFIG,
+    flowType: "device_code",
+    // Qoder uses a custom device flow: PKCE + nonce + machine_id are generated
+    // locally, the user lands on qoder.com/device/selectAccounts in the
+    // browser, and we poll openapi.qoder.sh until a `dt-...` token appears.
+    requestDeviceCode: async (config) => {
+      const { QoderService } = await import("@/lib/oauth/services/qoder");
+      const flow = new QoderService().initiateDeviceFlow();
+      // Match the device_code shape the rest of the OAuthModal expects
+      // (device_code, user_code, verification_uri[_complete], interval).
+      // The poll endpoint identifies us by nonce+verifier, not by a
+      // server-issued device_code, so we plumb our own values through:
+      //   device_code   = nonce  (modal forwards as deviceCode on poll)
+      //   codeVerifier  = our PKCE verifier (route forwards as codeVerifier)
+      return {
+        device_code: flow.nonce,
+        user_code: flow.nonce.slice(0, 8).toUpperCase(),
+        verification_uri: config.loginUrl,
+        verification_uri_complete: flow.verificationUriComplete,
+        expires_in: 300,
+        interval: 2,
+        codeVerifier: flow.codeVerifier,
+        _qoderNonce: flow.nonce,
+        _qoderMachineId: flow.machineId,
+      };
+    },
+    pollToken: async (config, deviceCode, codeVerifier, extraData) => {
+      const { QoderService } = await import("@/lib/oauth/services/qoder");
+      const svc = new QoderService();
+      const nonce = deviceCode || extraData?._qoderNonce;
+      const verifier = codeVerifier || extraData?._qoderVerifier;
+      if (!nonce || !verifier) {
+        return {
+          ok: false,
+          data: { error: "invalid_request", error_description: "Missing nonce/verifier" },
+        };
+      }
+      let result;
+      try {
+        result = await svc.pollDeviceToken({ nonce, codeVerifier: verifier });
+      } catch (err) {
+        return {
+          ok: false,
+          data: { error: "poll_failed", error_description: err.message },
+        };
+      }
+      if (result.status === "pending") {
+        return { ok: false, data: { error: "authorization_pending" } };
+      }
+      // Best-effort profile lookup so we have a name/email to display.
+      const userInfo = await svc.fetchUserInfo(result.accessToken);
+      // expireTime is a Unix-ms timestamp from QoderService.parseExpiry,
+      // which already falls back to "now + 30 days" when the upstream
+      // omits expiry. Floor to a sane minimum (1 day) so a stale or
+      // skewed upstream timestamp doesn't truncate the stored token below
+      // something useful.
+      const minSeconds = 24 * 60 * 60;
+      const remainingSeconds = Math.floor((result.expireTime - Date.now()) / 1000);
+      const expiresIn = Math.max(minSeconds, remainingSeconds);
+      return {
+        ok: true,
+        data: {
+          access_token: result.accessToken,
+          refresh_token: result.refreshToken,
+          expires_in: expiresIn,
+          _qoderUserId: result.userId,
+          _qoderMachineId: extraData?._qoderMachineId || "",
+          _qoderName: userInfo.name,
+          _qoderEmail: userInfo.email,
+          _qoderOrganizationId: userInfo.organizationId,
+        },
+      };
+    },
+    mapTokens: (tokens) => {
+      const rawEmail = (tokens._qoderEmail || "").trim();
+      const displayName = (tokens._qoderName || "").trim() || null;
+      const userId = tokens._qoderUserId || "";
+      // Dedup in createProviderConnection requires a non-empty email. When
+      // fetchUserInfo silently fails (returns ""), fall back to a stable
+      // synthetic identifier derived from userId so re-logins update the
+      // existing row instead of accumulating "Account N" duplicates.
+      const email = rawEmail || (userId ? `qoder-user-${userId}` : null);
+      return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token || null,
+        expiresIn: tokens.expires_in,
+        email,
+        displayName,
+        providerSpecificData: {
+          authMethod: "device",
+          userId,
+          machineId: tokens._qoderMachineId || "",
+          organizationId: tokens._qoderOrganizationId || "",
+        },
+      };
+    },
+  },
+
+  qwen: {
+    config: QWEN_CONFIG,
+    flowType: "device_code",
+    requestDeviceCode: async (config, codeChallenge) => {
+      const response = await fetch(config.deviceCodeUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          client_id: config.clientId,
+          scope: config.scope,
+          code_challenge: codeChallenge,
+          code_challenge_method: config.codeChallengeMethod,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Device code request failed: ${error}`);
+      }
+
+      return await response.json();
+    },
+    pollToken: async (config, deviceCode, codeVerifier) => {
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          client_id: config.clientId,
+          device_code: deviceCode,
+          code_verifier: codeVerifier,
+        }),
+      });
+
+      return {
+        ok: response.ok,
+        data: await response.json(),
+      };
+    },
+    mapTokens: (tokens) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_in,
+      providerSpecificData: { resourceUrl: tokens.resource_url },
+    }),
+  },
+
+  github: {
+    config: GITHUB_CONFIG,
+    flowType: "device_code",
+    requestDeviceCode: async (config) => {
+      const response = await fetch(config.deviceCodeUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          client_id: config.clientId,
+          scope: config.scopes,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Device code request failed: ${error}`);
+      }
+
+      return await response.json();
+    },
+    pollToken: async (config, deviceCode) => {
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          client_id: config.clientId,
+          device_code: deviceCode,
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        }),
+      });
+
+      // Handle response properly - if not ok, try to get error as text first
+      let data;
+      try {
+        data = await response.json();
+      } catch (e) {
+        // If response is not JSON, get as text
+        const text = await response.text();
+        data = { error: "invalid_response", error_description: text };
+      }
+
+      return {
+        ok: response.ok,
+        data: data,
+      };
+    },
+    postExchange: async (tokens) => {
+      // Get Copilot token using GitHub access token
+      const copilotRes = await fetch(GITHUB_CONFIG.copilotTokenUrl, {
+        headers: {
+          Authorization: `Bearer ${tokens.access_token}`,
+          Accept: "application/json",
+          "X-GitHub-Api-Version": GITHUB_CONFIG.apiVersion,
+          "User-Agent": GITHUB_CONFIG.userAgent,
+        },
+      });
+      const copilotToken = copilotRes.ok ? await copilotRes.json() : {};
+
+      // Get user info from GitHub
+      const userRes = await fetch(GITHUB_CONFIG.userInfoUrl, {
+        headers: {
+          Authorization: `Bearer ${tokens.access_token}`,
+          Accept: "application/json",
+          "X-GitHub-Api-Version": GITHUB_CONFIG.apiVersion,
+          "User-Agent": GITHUB_CONFIG.userAgent,
+        },
+      });
+      const userInfo = userRes.ok ? await userRes.json() : {};
+
+      return { copilotToken, userInfo };
+    },
+    mapTokens: (tokens, extra) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_in,
+      name: extra?.userInfo?.login || extra?.userInfo?.name,
+      displayName: extra?.userInfo?.name || extra?.userInfo?.login,
+      email: extra?.userInfo?.email || null,
+      providerSpecificData: {
+        copilotToken: extra?.copilotToken?.token,
+        copilotTokenExpiresAt: extra?.copilotToken?.expires_at,
+        githubUserId: extra?.userInfo?.id,
+        githubLogin: extra?.userInfo?.login,
+        githubName: extra?.userInfo?.name,
+        githubEmail: extra?.userInfo?.email,
+      },
+    }),
+  },
+
+  kiro: {
+    config: KIRO_CONFIG,
+    flowType: "device_code",
+    // Kiro uses AWS SSO OIDC - requires client registration first
+    requestDeviceCode: async (config, codeChallenge, options = {}) => {
+      const trimmedRegion = typeof options.region === "string" ? options.region.trim() : "";
+      const region = trimmedRegion || "us-east-1";
+      assertValidAwsRegion(region);
+      const trimmedStartUrl = typeof options.startUrl === "string" ? options.startUrl.trim() : "";
+      const startUrl = trimmedStartUrl || config.startUrl;
+      const authMethod = options.authMethod === "idc" ? "idc" : "builder-id";
+      const registerClientUrl = `https://oidc.${region}.amazonaws.com/client/register`;
+      const deviceAuthUrl = `https://oidc.${region}.amazonaws.com/device_authorization`;
+
+      // Step 1: Register client with AWS SSO OIDC
+      const registerRes = await fetch(registerClientUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body: JSON.stringify({
+          clientName: config.clientName,
+          clientType: config.clientType,
+          scopes: config.scopes,
+          grantTypes: config.grantTypes,
+          issuerUrl: config.issuerUrl,
+        }),
+      });
+
+      if (!registerRes.ok) {
+        const error = await registerRes.text();
+        throw new Error(`Client registration failed: ${error}`);
+      }
+
+      const clientInfo = await registerRes.json();
+
+      // Step 2: Request device authorization
+      const deviceRes = await fetch(deviceAuthUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body: JSON.stringify({
+          clientId: clientInfo.clientId,
+          clientSecret: clientInfo.clientSecret,
+          startUrl,
+        }),
+      });
+
+      if (!deviceRes.ok) {
+        const error = await deviceRes.text();
+        throw new Error(`Device authorization failed: ${error}`);
+      }
+
+      const deviceData = await deviceRes.json();
+
+      // Return combined data for polling
+      return {
+        device_code: deviceData.deviceCode,
+        user_code: deviceData.userCode,
+        verification_uri: deviceData.verificationUri,
+        verification_uri_complete: deviceData.verificationUriComplete,
+        expires_in: deviceData.expiresIn,
+        interval: deviceData.interval || 5,
+        // Store client credentials for token exchange
+        _clientId: clientInfo.clientId,
+        _clientSecret: clientInfo.clientSecret,
+        _region: region,
+        _authMethod: authMethod,
+        _startUrl: startUrl,
+      };
+    },
+    pollToken: async (config, deviceCode, codeVerifier, extraData) => {
+      const region = extraData?._region || "us-east-1";
+      assertValidAwsRegion(region);
+      const tokenUrl = `https://oidc.${region}.amazonaws.com/token`;
+      const response = await fetch(tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body: JSON.stringify({
+          clientId: extraData?._clientId,
+          clientSecret: extraData?._clientSecret,
+          deviceCode: deviceCode,
+          grantType: "urn:ietf:params:oauth:grant-type:device_code",
+        }),
+      });
+
+      let data;
+      try {
+        data = await response.json();
+      } catch (e) {
+        const text = await response.text();
+        data = { error: "invalid_response", error_description: text };
+      }
+
+      // AWS SSO OIDC returns camelCase
+      if (data.accessToken) {
+        return {
+          ok: true,
+          data: {
+            access_token: data.accessToken,
+            refresh_token: data.refreshToken,
+            expires_in: data.expiresIn,
+            profile_arn: data?.profileArn || null,
+            // Store client credentials for refresh
+            _clientId: extraData?._clientId,
+            _clientSecret: extraData?._clientSecret,
+            _region: extraData?._region,
+            _authMethod: extraData?._authMethod,
+            _startUrl: extraData?._startUrl,
+          },
+        };
+      }
+
+      return {
+        ok: false,
+        data: {
+          error: data.error || "authorization_pending",
+          error_description: data.error_description || data.message,
+        },
+      };
+    },
+    mapTokens: (tokens) => {
+      const email = extractEmailFromAccessToken(tokens.access_token);
+      const mapped = {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+        email,
+        providerSpecificData: {
+          profileArn: tokens?.profile_arn || null,
+          clientId: tokens._clientId,
+          clientSecret: tokens._clientSecret,
+          region: tokens._region || "us-east-1",
+          authMethod: tokens._authMethod || "builder-id",
+          startUrl: tokens._startUrl || KIRO_CONFIG.startUrl,
+        },
+      };
+      return mapped;
+    },
+  },
+
+  cursor: {
+    config: CURSOR_CONFIG,
+    flowType: "import_token",
+    // Cursor uses import token flow - tokens are extracted from local SQLite database
+    // No OAuth flow needed, handled by /api/oauth/cursor/import route
+    mapTokens: (tokens) => ({
+      accessToken: tokens.accessToken,
+      refreshToken: null, // Cursor doesn't have public refresh endpoint
+      expiresIn: tokens.expiresIn || 86400,
+      providerSpecificData: {
+        machineId: tokens.machineId,
+        authMethod: "imported",
+      },
+    }),
+  },
+
+  "kimi-coding": {
+    config: KIMI_CODING_CONFIG,
+    flowType: "device_code",
+    requestDeviceCode: async (config) => {
+      const response = await fetch(config.deviceCodeUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+        body: new URLSearchParams({ client_id: config.clientId }),
+      });
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Device code request failed: ${error}`);
+      }
+      const data = await response.json();
+      return {
+        device_code: data.device_code,
+        user_code: data.user_code,
+        verification_uri: data.verification_uri || "https://www.kimi.com/code/authorize_device",
+        verification_uri_complete:
+          data.verification_uri_complete ||
+          `https://www.kimi.com/code/authorize_device?user_code=${data.user_code}`,
+        expires_in: data.expires_in,
+        interval: data.interval || 5,
+      };
+    },
+    pollToken: async (config, deviceCode) => {
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+        body: new URLSearchParams({
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          client_id: config.clientId,
+          device_code: deviceCode,
+        }),
+      });
+      let data;
+      try {
+        data = await response.json();
+      } catch (e) {
+        const text = await response.text();
+        data = { error: "invalid_response", error_description: text };
+      }
+      return { ok: response.ok, data };
+    },
+    mapTokens: (tokens) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_in,
+    }),
+  },
+
+  kilocode: {
+    config: KILOCODE_CONFIG,
+    flowType: "device_code",
+    requestDeviceCode: async (config) => {
+      const response = await fetch(config.initiateUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+      });
+      if (!response.ok) {
+        if (response.status === 429) {
+          throw new Error("Too many pending authorization requests. Please try again later.");
+        }
+        const error = await response.text();
+        throw new Error(`Device auth initiation failed: ${error}`);
+      }
+      const data = await response.json();
+      return {
+        device_code: data.code,
+        user_code: data.code,
+        verification_uri: data.verificationUrl,
+        verification_uri_complete: data.verificationUrl,
+        expires_in: data.expiresIn || 300,
+        interval: 3,
+      };
+    },
+    pollToken: async (config, deviceCode) => {
+      const response = await fetch(`${config.pollUrlBase}/${deviceCode}`);
+      if (response.status === 202) return { ok: false, data: { error: "authorization_pending" } };
+      if (response.status === 403) return { ok: false, data: { error: "access_denied", error_description: "Authorization denied by user" } };
+      if (response.status === 410) return { ok: false, data: { error: "expired_token", error_description: "Authorization code expired" } };
+      if (!response.ok) return { ok: false, data: { error: "poll_failed", error_description: `Poll failed: ${response.status}` } };
+      const data = await response.json();
+      if (data.status === "approved" && data.token) {
+        // Fetch profile to get orgId for X-Kilocode-OrganizationID header
+        let orgId = null;
+        try {
+          const profileRes = await fetch(`${config.apiBaseUrl}/api/profile`, {
+            headers: { "Authorization": `Bearer ${data.token}` }
+          });
+          if (profileRes.ok) {
+            const profile = await profileRes.json();
+            orgId = profile.organizations?.[0]?.id || null;
+          }
+        } catch {}
+        return { ok: true, data: { access_token: data.token, _userEmail: data.userEmail, _orgId: orgId } };
+      }
+      return { ok: false, data: { error: "authorization_pending" } };
+    },
+    mapTokens: (tokens) => ({
+      accessToken: tokens.access_token,
+      refreshToken: null,
+      expiresIn: null,
+      email: tokens._userEmail,
+      ...(tokens._orgId ? { providerSpecificData: { orgId: tokens._orgId } } : {}),
+    }),
+  },
+
+  cline: {
+    config: CLINE_CONFIG,
+    flowType: "authorization_code",
+    buildAuthUrl: (config, redirectUri) => {
+      const params = new URLSearchParams({
+        client_type: "extension",
+        callback_url: redirectUri,
+        redirect_uri: redirectUri,
+      });
+      return `${config.authorizeUrl}?${params.toString()}`;
+    },
+    exchangeToken: async (config, code, redirectUri) => {
+      try {
+        // Cline encodes token data as base64 in the code param
+        let base64 = code;
+        const padding = 4 - (base64.length % 4);
+        if (padding !== 4) base64 += "=".repeat(padding);
+        const decoded = Buffer.from(base64, "base64").toString("utf-8");
+        const lastBrace = decoded.lastIndexOf("}");
+        if (lastBrace === -1) throw new Error("No JSON found in decoded code");
+        const tokenData = JSON.parse(decoded.substring(0, lastBrace + 1));
+        return {
+          access_token: tokenData.accessToken,
+          refresh_token: tokenData.refreshToken,
+          email: tokenData.email,
+          firstName: tokenData.firstName,
+          lastName: tokenData.lastName,
+          expires_at: tokenData.expiresAt,
+        };
+      } catch (e) {
+        const response = await fetch(config.tokenExchangeUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Accept: "application/json" },
+          body: JSON.stringify({ grant_type: "authorization_code", code, client_type: "extension", redirect_uri: redirectUri }),
+        });
+        if (!response.ok) {
+          const error = await response.text();
+          throw new Error(`Cline token exchange failed: ${error}`);
+        }
+        const data = await response.json();
+        return {
+          access_token: data.data?.accessToken || data.accessToken,
+          refresh_token: data.data?.refreshToken || data.refreshToken,
+          email: data.data?.userInfo?.email || "",
+          expires_at: data.data?.expiresAt || data.expiresAt,
+        };
+      }
+    },
+    mapTokens: (tokens) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_at
+        ? Math.floor((new Date(tokens.expires_at).getTime() - Date.now()) / 1000)
+        : 3600,
+      email: tokens.email,
+      providerSpecificData: { firstName: tokens.firstName, lastName: tokens.lastName },
+    }),
+  },
+  clinepass: {
+    config: CLINEPASS_CONFIG,
+    flowType: "authorization_code",
+    buildAuthUrl: (config, redirectUri) => {
+      const params = new URLSearchParams({
+        client_type: "extension",
+        callback_url: redirectUri,
+        redirect_uri: redirectUri,
+      });
+      return `${config.authorizeUrl}?${params.toString()}`;
+    },
+    exchangeToken: async (config, code, redirectUri) => {
+      try {
+        // Cline encodes token data as base64 in the code param
+        let base64 = code;
+        const padding = 4 - (base64.length % 4);
+        if (padding !== 4) base64 += "=".repeat(padding);
+        const decoded = Buffer.from(base64, "base64").toString("utf-8");
+        const lastBrace = decoded.lastIndexOf("}");
+        if (lastBrace === -1) throw new Error("No JSON found in decoded code");
+        const tokenData = JSON.parse(decoded.substring(0, lastBrace + 1));
+        return {
+          access_token: tokenData.accessToken,
+          refresh_token: tokenData.refreshToken,
+          email: tokenData.email,
+          firstName: tokenData.firstName,
+          lastName: tokenData.lastName,
+          expires_at: tokenData.expiresAt,
+        };
+      } catch (e) {
+        const response = await fetch(config.tokenUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Accept: "application/json" },
+          body: JSON.stringify({ grant_type: "authorization_code", code, client_type: "extension", redirect_uri: redirectUri }),
+        });
+        if (!response.ok) {
+          const error = await response.text();
+          throw new Error(`ClinePass token exchange failed: ${error}`);
+        }
+        const data = await response.json();
+        return {
+          access_token: data.data?.accessToken || data.accessToken,
+          refresh_token: data.data?.refreshToken || data.refreshToken,
+          email: data.data?.userInfo?.email || "",
+          expires_at: data.data?.expiresAt || data.expiresAt,
+        };
+      }
+    },
+    mapTokens: (tokens) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_at
+        ? Math.floor((new Date(tokens.expires_at).getTime() - Date.now()) / 1000)
+        : 3600,
+      email: tokens.email,
+      providerSpecificData: { firstName: tokens.firstName, lastName: tokens.lastName },
+    }),
+  },
+  // GitLab Duo - Authorization Code Flow with PKCE
+  // Supports two login modes via loginMode metadata: "oauth" (default) or "pat"
+  gitlab: {
+    config: GITLAB_CONFIG,
+    flowType: "authorization_code_pkce",
+    buildAuthUrl: (config, redirectUri, state, codeChallenge, meta = {}) => {
+      const baseUrl = meta.baseUrl || config.defaultBaseUrl;
+      const clientId = meta.clientId || "";
+      const params = new URLSearchParams({
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        response_type: "code",
+        state,
+        scope: config.scope,
+        code_challenge: codeChallenge,
+        code_challenge_method: config.codeChallengeMethod,
+      });
+      return `${baseUrl}${config.authorizeUrlPath}?${params.toString()}`;
+    },
+    exchangeToken: async (config, code, redirectUri, codeVerifier, state, meta = {}) => {
+      const baseUrl = meta.baseUrl || config.defaultBaseUrl;
+      const clientId = meta.clientId || "";
+      const clientSecret = meta.clientSecret || "";
+      const body = new URLSearchParams({
+        client_id: clientId,
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier,
+      });
+      if (clientSecret) body.set("client_secret", clientSecret);
+      const response = await fetch(`${baseUrl}${config.tokenUrlPath}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+        body: body.toString(),
+      });
+      if (!response.ok) throw new Error(`GitLab token exchange failed: ${await response.text()}`);
+      const tokens = await response.json();
+      // Fetch user info
+      const userRes = await fetch(`${baseUrl}${config.userInfoUrlPath}`, {
+        headers: { Authorization: `Bearer ${tokens.access_token}` },
+      });
+      const user = userRes.ok ? await userRes.json() : {};
+      return { ...tokens, _user: user, _baseUrl: baseUrl, _clientId: clientId };
+    },
+    mapTokens: (tokens) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_in,
+      scope: tokens.scope,
+      providerSpecificData: {
+        username: tokens._user?.username || "",
+        email: tokens._user?.email || tokens._user?.public_email || "",
+        name: tokens._user?.name || "",
+        baseUrl: tokens._baseUrl,
+        clientId: tokens._clientId,
+        authKind: "oauth",
+      },
+    }),
+  },
+
+  // CodeBuddy (Tencent) - Browser OAuth Polling Flow
+  // 1. POST stateUrl → get { state, authUrl }
+  // 2. Open authUrl in browser
+  // 3. Poll tokenUrl with state until success (code 0) or timeout
+  "codebuddy-cn": {
+    config: CODEBUDDY_CONFIG,
+    flowType: "device_code",
+    requestDeviceCode: async (config) => {
+      const response = await fetch(`${config.stateUrl}?platform=${config.platform}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          "User-Agent": config.userAgent,
+          "X-Requested-With": "XMLHttpRequest",
+          "X-Domain": "copilot.tencent.com",
+          "X-No-Authorization": "true",
+          "X-No-User-Id": "true",
+          "X-Product": "SaaS",
+        },
+        body: "{}",
+      });
+      if (!response.ok) throw new Error(`CodeBuddy state request failed: ${await response.text()}`);
+      const data = await response.json();
+      if (data.code !== 0 || !data.data?.state || !data.data?.authUrl) {
+        throw new Error(`CodeBuddy state error: ${data.msg || "missing state/authUrl"}`);
+      }
+      return {
+        device_code: data.data.state,
+        verification_uri: data.data.authUrl,
+        user_code: "",
+        interval: config.pollInterval / 1000,
+        _isCodeBuddy: true,
+      };
+    },
+    pollToken: async (config, deviceCode) => {
+      // CodeBuddy polls the token endpoint via GET with the state as a query
+      // param (not POST/body) — matches the official CLI's /v2/plugin/auth/token?state=...
+      const response = await fetch(`${config.tokenUrl}?state=${encodeURIComponent(deviceCode)}`, {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          "User-Agent": config.userAgent,
+          "X-Requested-With": "XMLHttpRequest",
+          "X-Domain": "copilot.tencent.com",
+          "X-No-Authorization": "true",
+          "X-No-User-Id": "true",
+          "X-No-Enterprise-Id": "true",
+          "X-No-Department-Info": "true",
+          "X-Product": "SaaS",
+        },
+      });
+      if (!response.ok) return { ok: false, data: { error: "request_failed" } };
+      const data = await response.json();
+      // code 11217 = pending (RetryFetchToken), code 0 = success
+      if (data.code === 0 && data.data?.accessToken) {
+        return {
+          ok: true,
+          data: {
+            access_token: data.data.accessToken,
+            refresh_token: data.data.refreshToken || "",
+            token_type: data.data.tokenType || "Bearer",
+            expires_in: data.data.expiresIn,
+          },
+        };
+      }
+      if (data.code === 11217) return { ok: true, data: { error: "authorization_pending" } };
+      return { ok: false, data: { error: data.msg || "unknown_error" } };
+    },
+    mapTokens: (tokens) => ({
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresIn: tokens.expires_in || 86400,
+      providerSpecificData: {},
+    }),
+  },
+
+  kimchi: {
+    config: KIMCHI_CONFIG,
+    flowType: "browser_token",
+    buildAuthUrl: (config, redirectUri, state) => {
+      const baseUrl = (config.webAppUrl || "https://app.kimchi.dev").replace(/\/+$/, "");
+      const params = new URLSearchParams({
+        callback: redirectUri,
+        state,
+      });
+      return `${baseUrl}/cli-auth?${params.toString()}`;
+    },
+    exchangeToken: async (config, token) => {
+      const accessToken = String(token || "").trim();
+      if (!accessToken) {
+        throw new Error("Missing Kimchi token");
+      }
+
+      const validationUrl = config.validationUrl || "https://api.cast.ai/v1/llm/openai/supported-providers";
+      const validationRes = await fetch(validationUrl, {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${accessToken}`,
+        },
+      });
+      if (!validationRes.ok) {
+        throw new Error(`Kimchi token validation failed: ${validationRes.status}`);
+      }
+
+      let userInfo = {};
+      if (config.userInfoUrl) {
+        try {
+          const userRes = await fetch(config.userInfoUrl, {
+            method: "GET",
+            headers: {
+              Accept: "application/json",
+              Authorization: `Bearer ${accessToken}`,
+            },
+          });
+          if (userRes.ok) {
+            userInfo = await userRes.json();
+          }
+        } catch {
+          userInfo = {};
+        }
+      }
+
+      return {
+        access_token: accessToken,
+        token_type: "Bearer",
+        _kimchiUser: userInfo,
+      };
+    },
+    mapTokens: (tokens) => {
+      const user = tokens._kimchiUser || {};
+      const userId = user.id ? String(user.id) : "";
+      const username = user.username || "";
+      const email = user.email || (userId ? `kimchi-user-${userId}` : null);
+      return {
+        accessToken: tokens.access_token,
+        refreshToken: null,
+        email,
+        displayName: user.name || username || null,
+        providerSpecificData: {
+          authMethod: "browser_token",
+          userId,
+          username,
+        },
+      };
+    },
+  },
+};
+
+/**
+ * Get provider handler
+ */
+export function getProvider(name) {
+  const provider = PROVIDERS[name];
+  if (!provider) {
+    throw new Error(`Unknown provider: ${name}`);
+  }
+  return provider;
+}
+
+/**
+ * Get all provider names
+ */
+export function getProviderNames() {
+  return Object.keys(PROVIDERS);
+}
+
+/**
+ * Generate auth data for a provider
+ * @param {object} [meta] - Provider-specific metadata (e.g. gitlab clientId/baseUrl)
+ */
+export async function generateAuthData(providerName, redirectUri, meta) {
+  const provider = getProvider(providerName);
+  const config = provider.prepareConfig
+    ? await provider.prepareConfig(provider.config, meta || {})
+    : provider.config;
+  const { codeVerifier, codeChallenge, state } = generatePKCE(provider.pkceVerifierBytes);
+
+  let authUrl;
+  if (provider.flowType === "device_code") {
+    // Device code flow doesn't have auth URL upfront
+    authUrl = null;
+  } else if (provider.flowType === "authorization_code_pkce") {
+    authUrl = provider.buildAuthUrl(config, redirectUri, state, codeChallenge, meta || {});
+  } else {
+    authUrl = provider.buildAuthUrl(config, redirectUri, state, undefined, meta || {});
+  }
+
+  return {
+    authUrl,
+    state,
+    codeVerifier,
+    codeChallenge,
+    redirectUri,
+    flowType: provider.flowType,
+    fixedPort: provider.fixedPort,
+    callbackPath: provider.callbackPath || "/callback",
+  };
+}
+
+/**
+ * Exchange code for tokens
+ * @param {object} [meta] - Provider-specific metadata (e.g. gitlab clientId/baseUrl)
+ */
+export async function exchangeTokens(providerName, code, redirectUri, codeVerifier, state, meta) {
+  const provider = getProvider(providerName);
+  const config = provider.prepareConfig
+    ? await provider.prepareConfig(provider.config, meta || {})
+    : provider.config;
+
+  const tokens = await provider.exchangeToken(config, code, redirectUri, codeVerifier, state, meta || {});
+
+  let extra = null;
+  if (provider.postExchange) {
+    extra = await provider.postExchange(tokens);
+  }
+
+  return provider.mapTokens(tokens, extra);
+}
+
+/**
+ * Request device code (for device_code flow)
+ */
+export async function requestDeviceCode(providerName, codeChallenge, options) {
+  const provider = getProvider(providerName);
+  if (provider.flowType !== "device_code") {
+    throw new Error(`Provider ${providerName} does not support device code flow`);
+  }
+  return await provider.requestDeviceCode(provider.config, codeChallenge, options || {});
+}
+
+/**
+ * Poll for token (for device_code flow)
+ * @param {string} providerName - Provider name
+ * @param {string} deviceCode - Device code from requestDeviceCode
+ * @param {string} codeVerifier - PKCE code verifier (optional for some providers)
+ * @param {object} extraData - Extra data from device code response (e.g. clientId/clientSecret for Kiro)
+ */
+export async function pollForToken(providerName, deviceCode, codeVerifier, extraData) {
+  const provider = getProvider(providerName);
+  if (provider.flowType !== "device_code") {
+    throw new Error(`Provider ${providerName} does not support device code flow`);
+  }
+
+  const result = await provider.pollToken(provider.config, deviceCode, codeVerifier, extraData);
+
+  if (result.ok) {
+    // For device code flows, success is only when we have an access token
+    if (result.data.access_token) {
+      // Call postExchange to get additional data (copilotToken, userInfo, etc.)
+      let extra = null;
+      if (provider.postExchange) {
+        extra = await provider.postExchange(result.data);
+      }
+      const tokens = provider.mapTokens(result.data, extra);
+      // Kiro IDC/Builder-ID tokens lack profileArn; resolve it to avoid 403
+      if (providerName === "kiro" && !tokens.providerSpecificData?.profileArn) {
+        const profileArn = await fetchKiroProfileArn(tokens.accessToken);
+        if (profileArn) tokens.providerSpecificData.profileArn = profileArn;
+      }
+      return { success: true, tokens };
+    } else {
+      // Check if it's still pending authorization
+      if (result.data.error === 'authorization_pending' || result.data.error === 'slow_down') {
+        // This is not a failure, just still waiting
+        return {
+          success: false,
+          error: result.data.error,
+          errorDescription: result.data.error_description || result.data.message,
+          pending: result.data.error === 'authorization_pending'
+        };
+      } else {
+        // Actual error
+        return {
+          success: false,
+          error: result.data.error || 'no_access_token',
+          errorDescription: result.data.error_description || result.data.message || 'No access token received'
+        };
+      }
+    }
+  }
+
+  return { success: false, error: result.data.error, errorDescription: result.data.error_description };
+}
+
+// Run-once guard across the process lifetime
+let codexBackfillDone = false;
+
+// Backfill email + chatgpt account info for existing codex OAuth connections missing them
+export async function backfillCodexEmails() {
+  if (codexBackfillDone) return;
+  codexBackfillDone = true;
+  try {
+    const { getProviderConnections, updateProviderConnection } = await import("@/lib/localDb");
+    const connections = await getProviderConnections();
+    const targets = connections.filter((c) => {
+      if (c.provider !== "codex" || c.authType !== "oauth" || !c.idToken) return false;
+      const hasEmail = !!c.email;
+      const hasAccountInfo = !!c.providerSpecificData?.chatgptAccountId;
+      return !hasEmail || !hasAccountInfo;
+    });
+    for (const conn of targets) {
+      const info = extractCodexAccountInfo(conn.idToken);
+      if (!info.email && !info.chatgptAccountId) continue;
+      const patch = {};
+      if (!conn.email && info.email) patch.email = info.email;
+      if (info.chatgptAccountId || info.chatgptPlanType) {
+        patch.providerSpecificData = {
+          ...(conn.providerSpecificData || {}),
+          chatgptAccountId: info.chatgptAccountId,
+          chatgptPlanType: info.chatgptPlanType,
+        };
+      }
+      if (Object.keys(patch).length) {
+        await updateProviderConnection(conn.id, patch);
+      }
+    }
+  } catch (err) {
+    codexBackfillDone = false;
+    console.log("backfillCodexEmails failed:", err?.message || err);
+  }
+}
diff --git a/src/lib/oauth/services/antigravity.js b/src/lib/oauth/services/antigravity.js
new file mode 100644
index 0000000..cda6bde
--- /dev/null
+++ b/src/lib/oauth/services/antigravity.js
@@ -0,0 +1,321 @@
+import crypto from "crypto";
+import open from "open";
+import { ANTIGRAVITY_CONFIG, getOAuthClientMetadata } from "../constants/oauth.js";
+import { getServerCredentials } from "../config/index.js";
+import { startLocalServer } from "../utils/server.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+
+/**
+ * Antigravity OAuth Service
+ * Uses standard OAuth2 Authorization Code flow (similar to Gemini)
+ */
+export class AntigravityService {
+  constructor() {
+    this.config = ANTIGRAVITY_CONFIG;
+  }
+
+  /**
+   * Build Antigravity authorization URL
+   */
+  buildAuthUrl(redirectUri, state) {
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      response_type: "code",
+      redirect_uri: redirectUri,
+      scope: this.config.scopes.join(" "),
+      state: state,
+      access_type: "offline",
+      prompt: "consent",
+    });
+
+    return `${this.config.authorizeUrl}?${params.toString()}`;
+  }
+
+  /**
+   * Exchange authorization code for tokens
+   */
+  async exchangeCode(code, redirectUri) {
+    const response = await fetch(this.config.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+        code: code,
+        redirect_uri: redirectUri,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Get user info from Google
+   */
+  async getUserInfo(accessToken) {
+    const response = await fetch(`${this.config.userInfoUrl}?alt=json`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to get user info: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Get common headers for Antigravity API calls
+   */
+  getApiHeaders(accessToken) {
+    return {
+      "Authorization": `Bearer ${accessToken}`,
+      "Content-Type": "application/json",
+      "User-Agent": this.config.loadCodeAssistUserAgent,
+      "X-Goog-Api-Client": this.config.loadCodeAssistApiClient,
+      "Client-Metadata": this.config.loadCodeAssistClientMetadata,
+    };
+  }
+
+  /**
+   * Get metadata object for loadCodeAssist / onboardUser API calls.
+   * Uses numeric enum values matching Antigravity binary ClientMetadata.
+   */
+  getMetadata() {
+    return getOAuthClientMetadata();
+  }
+
+  /**
+   * Fetch Project ID and Tier from loadCodeAssist API
+   */
+  async loadCodeAssist(accessToken) {
+    const response = await fetch(this.config.loadCodeAssistEndpoint, {
+      method: "POST",
+      headers: this.getApiHeaders(accessToken),
+      body: JSON.stringify({ metadata: this.getMetadata() }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Failed to load code assist: ${errorText}`);
+    }
+
+    const data = await response.json();
+
+    // Extract project ID
+    let projectId = data.cloudaicompanionProject;
+    if (typeof projectId === 'object' && projectId !== null && projectId.id) {
+      projectId = projectId.id;
+    }
+
+    // Extract tier ID (default to legacy-tier)
+    let tierId = "legacy-tier";
+    if (Array.isArray(data.allowedTiers)) {
+      for (const tier of data.allowedTiers) {
+        if (tier.isDefault && tier.id) {
+          tierId = tier.id.trim();
+          break;
+        }
+      }
+    }
+
+    return { projectId, tierId, raw: data };
+  }
+
+  /**
+   * Onboard user to enable Gemini Code Assist for the project
+   */
+  async onboardUser(accessToken, projectId, tierId) {
+    const response = await fetch(this.config.onboardUserEndpoint, {
+      method: "POST",
+      headers: this.getApiHeaders(accessToken),
+      body: JSON.stringify({ tierId, metadata: this.getMetadata() }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Failed to onboard user: ${errorText}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Complete onboarding flow with retry
+   */
+  async completeOnboarding(accessToken, projectId, tierId, maxRetries = 10) {
+    for (let i = 0; i < maxRetries; i++) {
+      const result = await this.onboardUser(accessToken, projectId, tierId);
+
+      if (result.done === true) {
+        // Extract final project ID from response
+        let finalProjectId = projectId;
+        if (result.response?.cloudaicompanionProject) {
+          const respProject = result.response.cloudaicompanionProject;
+          if (typeof respProject === 'string') {
+            finalProjectId = respProject.trim();
+          } else if (respProject.id) {
+            finalProjectId = respProject.id.trim();
+          }
+        }
+        return { success: true, projectId: finalProjectId };
+      }
+
+      // Wait 5 seconds before retry
+      await new Promise(resolve => setTimeout(resolve, 5000));
+    }
+
+    throw new Error("Onboarding timeout - please try again");
+  }
+
+  /**
+   * Fetch Project ID from loadCodeAssist API (legacy method for compatibility)
+   */
+  async fetchProjectId(accessToken) {
+    const { projectId } = await this.loadCodeAssist(accessToken);
+    if (!projectId) {
+      throw new Error("No cloudaicompanionProject found in response");
+    }
+    return projectId;
+  }
+
+  /**
+   * Save Antigravity tokens to server
+   */
+  async saveTokens(tokens, userInfo, projectId) {
+    const { server, token, userId } = getServerCredentials();
+
+    const response = await fetch(`${server}/api/cli/providers/antigravity`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        "X-User-Id": userId,
+      },
+      body: JSON.stringify({
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+        scope: tokens.scope,
+        email: userInfo.email,
+        projectId: projectId, // Send projectId to server
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error || "Failed to save tokens");
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Complete Antigravity OAuth flow
+   */
+  async connect() {
+    const spinner = createSpinner("Starting Antigravity OAuth...").start();
+
+    try {
+      spinner.text = "Starting local server...";
+
+      // Start local server for callback
+      let callbackParams = null;
+      const { port, close } = await startLocalServer((params) => {
+        callbackParams = params;
+      });
+
+      const redirectUri = `http://localhost:${port}/callback`;
+      spinner.succeed(`Local server started on port ${port}`);
+
+      // Generate state
+      const state = crypto.randomBytes(32).toString("base64url");
+
+      // Build authorization URL
+      const authUrl = this.buildAuthUrl(redirectUri, state);
+
+      console.log("\nOpening browser for Antigravity authentication...");
+      console.log(`If browser doesn't open, visit:\n${authUrl}\n`);
+
+      // Open browser
+      await open(authUrl);
+
+      // Wait for callback
+      spinner.start("Waiting for Antigravity authorization...");
+
+      await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error("Authentication timeout (5 minutes)"));
+        }, 300000);
+
+        const checkInterval = setInterval(() => {
+          if (callbackParams) {
+            clearInterval(checkInterval);
+            clearTimeout(timeout);
+            resolve();
+          }
+        }, 100);
+      });
+
+      close();
+
+      if (callbackParams.error) {
+        throw new Error(callbackParams.error_description || callbackParams.error);
+      }
+
+      if (!callbackParams.code) {
+        throw new Error("No authorization code received");
+      }
+
+      spinner.start("Exchanging code for tokens...");
+
+      // Exchange code for tokens
+      const tokens = await this.exchangeCode(callbackParams.code, redirectUri);
+
+      spinner.text = "Fetching user info...";
+
+      // Get user info
+      const userInfo = await this.getUserInfo(tokens.access_token);
+
+      spinner.text = "Loading Code Assist configuration...";
+
+      // Load Code Assist to get project ID and tier
+      const { projectId, tierId } = await this.loadCodeAssist(tokens.access_token);
+
+      if (!projectId) {
+        throw new Error("No Google Cloud Project found. Please ensure you have a GCP project with Gemini Code Assist enabled.");
+      }
+
+      spinner.text = "Onboarding to Gemini Code Assist...";
+
+      // Complete onboarding to enable Gemini Code Assist
+      const onboardResult = await this.completeOnboarding(tokens.access_token, projectId, tierId);
+      const finalProjectId = onboardResult.projectId || projectId;
+
+      spinner.text = "Saving tokens to server...";
+
+      // Save tokens to server
+      await this.saveTokens(tokens, userInfo, finalProjectId);
+
+      spinner.succeed(`Antigravity connected successfully! (${userInfo.email}, Project: ${finalProjectId})`);
+      return true;
+    } catch (error) {
+      spinner.fail(`Failed: ${error.message}`);
+      throw error;
+    }
+  }
+}
+
diff --git a/src/lib/oauth/services/claude.js b/src/lib/oauth/services/claude.js
new file mode 100644
index 0000000..de713c2
--- /dev/null
+++ b/src/lib/oauth/services/claude.js
@@ -0,0 +1,136 @@
+import { OAuthService } from "./oauth.js";
+import { CLAUDE_CONFIG } from "../constants/oauth.js";
+import { getServerCredentials } from "../config/index.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+
+/**
+ * Claude OAuth Service
+ */
+export class ClaudeService extends OAuthService {
+  constructor() {
+    super(CLAUDE_CONFIG);
+  }
+
+  /**
+   * Build Claude authorization URL
+   */
+  buildClaudeAuthUrl(redirectUri, state, codeChallenge) {
+    const scopeStr = CLAUDE_CONFIG.scopes.join(" ");
+    const params = new URLSearchParams({
+      code: "true",
+      client_id: CLAUDE_CONFIG.clientId,
+      response_type: "code",
+      redirect_uri: redirectUri,
+      scope: scopeStr,
+      code_challenge: codeChallenge,
+      code_challenge_method: CLAUDE_CONFIG.codeChallengeMethod,
+      state: state,
+    });
+
+    return `${CLAUDE_CONFIG.authorizeUrl}?${params.toString()}`;
+  }
+
+  /**
+   * Exchange Claude authorization code (with special handling)
+   */
+  async exchangeClaudeCode(code, redirectUri, codeVerifier, state) {
+    // Parse code - may contain state after #
+    let authCode = code;
+    let codeState = "";
+    if (authCode.includes("#")) {
+      const parts = authCode.split("#");
+      authCode = parts[0];
+      codeState = parts[1] || "";
+    }
+
+    // Claude uses JSON format (not form-urlencoded)
+    const tokenPayload = {
+      code: authCode,
+      state: codeState || state,
+      grant_type: "authorization_code",
+      client_id: CLAUDE_CONFIG.clientId,
+      redirect_uri: redirectUri,
+      code_verifier: codeVerifier,
+    };
+
+    const response = await fetch(CLAUDE_CONFIG.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(tokenPayload),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Save Claude tokens to server
+   */
+  async saveTokens(tokens) {
+    const { server, token, userId } = getServerCredentials();
+
+    // Server will auto-generate displayName based on existing account count
+    const response = await fetch(`${server}/api/cli/providers/claude`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        "X-User-Id": userId,
+      },
+      body: JSON.stringify({
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+        scope: tokens.scope,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error || "Failed to save tokens");
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Complete Claude OAuth flow
+   */
+  async connect() {
+    const spinner = createSpinner("Starting Claude OAuth...").start();
+
+    try {
+      spinner.text = "Starting local server...";
+
+      // Authenticate and get authorization code
+      const { code, state, codeVerifier, redirectUri } = await this.authenticate(
+        "Claude",
+        this.buildClaudeAuthUrl.bind(this)
+      );
+
+      spinner.start("Exchanging code for tokens...");
+
+      // Exchange code for tokens
+      const tokens = await this.exchangeClaudeCode(code, redirectUri, codeVerifier, state);
+
+      spinner.text = "Saving tokens to server...";
+
+      // Save tokens to server
+      await this.saveTokens(tokens);
+
+      spinner.succeed("Claude connected successfully!");
+      return true;
+    } catch (error) {
+      spinner.fail(`Failed: ${error.message}`);
+      throw error;
+    }
+  }
+}
+
diff --git a/src/lib/oauth/services/codex.js b/src/lib/oauth/services/codex.js
new file mode 100644
index 0000000..fafa3c6
--- /dev/null
+++ b/src/lib/oauth/services/codex.js
@@ -0,0 +1,144 @@
+import open from "open";
+import { OAuthService } from "./oauth.js";
+import { CODEX_CONFIG } from "../constants/oauth.js";
+import { getServerCredentials } from "../config/index.js";
+import { startLocalServer } from "../utils/server.js";
+import { generatePKCE } from "../utils/pkce.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+
+/**
+ * Codex (OpenAI) OAuth Service
+ */
+export class CodexService extends OAuthService {
+  constructor() {
+    super(CODEX_CONFIG);
+  }
+
+  /**
+   * Build Codex authorization URL
+   */
+  buildCodexAuthUrl(redirectUri, state, codeChallenge) {
+    // Build URL manually to ensure space encoding as %20 instead of +
+    const params = {
+      response_type: "code",
+      client_id: CODEX_CONFIG.clientId,
+      redirect_uri: redirectUri,
+      scope: CODEX_CONFIG.scope,
+      code_challenge: codeChallenge,
+      code_challenge_method: CODEX_CONFIG.codeChallengeMethod,
+      ...CODEX_CONFIG.extraParams,
+      state: state,
+    };
+
+    const queryString = Object.entries(params)
+      .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+      .join("&");
+
+    return `${CODEX_CONFIG.authorizeUrl}?${queryString}`;
+  }
+
+  /**
+   * Save Codex tokens to server
+   */
+  async saveTokens(tokens) {
+    const { server, token, userId } = getServerCredentials();
+
+    const response = await fetch(`${server}/api/cli/providers/codex`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        "X-User-Id": userId,
+      },
+      body: JSON.stringify({
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+        lastRefreshAt: new Date().toISOString(),
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error || "Failed to save tokens");
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Complete Codex OAuth flow
+   */
+  async connect() {
+    const spinner = createSpinner("Starting Codex OAuth...").start();
+
+    try {
+      spinner.text = "Starting local server...";
+
+      // Start local server for callback (use fixed port 1455 like real Codex CLI)
+      const fixedPort = CODEX_CONFIG.fixedPort;
+      let callbackParams = null;
+      const { port, close } = await startLocalServer((params) => {
+        callbackParams = params;
+      }, fixedPort);
+
+      const redirectUri = `http://localhost:${port}/auth/callback`;
+      spinner.succeed(`Local server started on port ${port}`);
+
+      // Generate PKCE
+      const { codeVerifier, codeChallenge, state } = generatePKCE();
+
+      // Build authorization URL
+      const authUrl = this.buildCodexAuthUrl(redirectUri, state, codeChallenge);
+
+      console.log("\nOpening browser for OpenAI authentication...");
+      console.log(`If browser doesn't open, visit:\n${authUrl}\n`);
+
+      // Open browser
+      await open(authUrl);
+
+      // Wait for callback
+      spinner.start("Waiting for OpenAI authorization...");
+
+      await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error("Authentication timeout (5 minutes)"));
+        }, 300000);
+
+        const checkInterval = setInterval(() => {
+          if (callbackParams) {
+            clearInterval(checkInterval);
+            clearTimeout(timeout);
+            resolve();
+          }
+        }, 100);
+      });
+
+      close();
+
+      if (callbackParams.error) {
+        throw new Error(callbackParams.error_description || callbackParams.error);
+      }
+
+      if (!callbackParams.code) {
+        throw new Error("No authorization code received");
+      }
+
+      spinner.start("Exchanging code for tokens...");
+
+      // Exchange code for tokens (Codex uses form-urlencoded)
+      const tokens = await this.exchangeCode(callbackParams.code, redirectUri, codeVerifier, "application/x-www-form-urlencoded");
+
+      spinner.text = "Saving tokens to server...";
+
+      // Save tokens to server
+      await this.saveTokens(tokens);
+
+      spinner.succeed("Codex connected successfully!");
+      return true;
+    } catch (error) {
+      spinner.fail(`Failed: ${error.message}`);
+      throw error;
+    }
+  }
+}
diff --git a/src/lib/oauth/services/cursor.js b/src/lib/oauth/services/cursor.js
new file mode 100644
index 0000000..167eacd
--- /dev/null
+++ b/src/lib/oauth/services/cursor.js
@@ -0,0 +1,179 @@
+import { CURSOR_CONFIG } from "../constants/oauth.js";
+
+/**
+ * Cursor IDE OAuth Service
+ * Supports Import Token method from Cursor IDE's local SQLite database
+ *
+ * Token Location:
+ * - Linux: ~/.config/Cursor/User/globalStorage/state.vscdb
+ * - macOS: /Users/<user>/Library/Application Support/Cursor/User/globalStorage/state.vscdb
+ * - Windows: %APPDATA%\Cursor\User\globalStorage\state.vscdb
+ *
+ * Database Keys:
+ * - cursorAuth/accessToken: The access token
+ * - storage.serviceMachineId: Machine ID for checksum
+ */
+
+export class CursorService {
+  constructor() {
+    this.config = CURSOR_CONFIG;
+  }
+
+  /**
+   * Generate Cursor checksum (jyh cipher)
+   * Algorithm: XOR timestamp bytes with rolling key (initial 165), then base64 encode
+   * Format: {encoded_timestamp},{machineId}
+   */
+  generateChecksum(machineId) {
+    const timestamp = Math.floor(Date.now() / 1000).toString();
+    let key = 165;
+    const encoded = [];
+
+    for (let i = 0; i < timestamp.length; i++) {
+      const charCode = timestamp.charCodeAt(i);
+      encoded.push(charCode ^ key);
+      key = (key + charCode) & 0xff; // Rolling key update
+    }
+
+    const base64Encoded = Buffer.from(encoded).toString("base64");
+    return `${base64Encoded},${machineId}`;
+  }
+
+  /**
+   * Build request headers for Cursor API
+   */
+  buildHeaders(accessToken, machineId, ghostMode = false) {
+    const checksum = this.generateChecksum(machineId);
+
+    return {
+      Authorization: `Bearer ${accessToken}`,
+      "Content-Type": "application/connect+proto",
+      "Connect-Protocol-Version": "1",
+      "x-cursor-client-version": this.config.clientVersion,
+      "x-cursor-client-type": this.config.clientType,
+      "x-cursor-client-os": this.detectOS(),
+      "x-cursor-client-arch": this.detectArch(),
+      "x-cursor-client-device-type": "desktop",
+      "x-cursor-checksum": checksum,
+      "x-ghost-mode": ghostMode ? "true" : "false",
+    };
+  }
+
+  /**
+   * Detect OS for headers
+   */
+  detectOS() {
+    if (typeof process !== "undefined") {
+      const platform = process.platform;
+      if (platform === "win32") return "windows";
+      if (platform === "darwin") return "macos";
+      return "linux";
+    }
+    return "linux";
+  }
+
+  /**
+   * Detect architecture for headers
+   */
+  detectArch() {
+    if (typeof process !== "undefined") {
+      const arch = process.arch;
+      if (arch === "x64") return "x86_64";
+      if (arch === "arm64") return "aarch64";
+      return arch;
+    }
+    return "x86_64";
+  }
+
+  /**
+   * Validate and import token from Cursor IDE
+   * Note: We skip API validation because Cursor API uses complex protobuf format.
+   * Token will be validated when actually used for requests.
+   * @param {string} accessToken - Access token from state.vscdb
+   * @param {string} machineId - Machine ID from state.vscdb
+   */
+  async validateImportToken(accessToken, machineId) {
+    // Basic validation
+    if (!accessToken || typeof accessToken !== "string") {
+      throw new Error("Access token is required");
+    }
+
+    if (!machineId || typeof machineId !== "string") {
+      throw new Error("Machine ID is required");
+    }
+
+    // Token format validation (Cursor tokens are typically long strings)
+    if (accessToken.length < 50) {
+      throw new Error("Invalid token format. Token appears too short.");
+    }
+
+    // Machine ID format validation (should be UUID-like)
+    const uuidRegex = /^[a-f0-9-]{32,}$/i;
+    if (!uuidRegex.test(machineId.replace(/-/g, ""))) {
+      throw new Error("Invalid machine ID format. Expected UUID format.");
+    }
+
+    // Note: We don't validate against API because Cursor uses complex protobuf.
+    // Token will be validated when used for actual requests.
+
+    return {
+      accessToken,
+      machineId,
+      expiresIn: 86400, // Cursor tokens typically last 24 hours
+      authMethod: "imported",
+    };
+  }
+
+  /**
+   * Extract user info from token if possible
+   * Cursor tokens may contain encoded user info
+   */
+  extractUserInfo(accessToken) {
+    try {
+      // Try to decode as JWT
+      const parts = accessToken.split(".");
+      if (parts.length === 3) {
+        let payload = parts[1];
+        while (payload.length % 4) {
+          payload += "=";
+        }
+        const decoded = JSON.parse(
+          Buffer.from(payload.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString()
+        );
+        return {
+          email: decoded.email || decoded.sub,
+          userId: decoded.sub || decoded.user_id,
+        };
+      }
+    } catch {
+      // Token is not a JWT, that's okay
+    }
+
+    return null;
+  }
+
+  /**
+   * Get token storage path instructions for user
+   */
+  getTokenStorageInstructions() {
+    return {
+      title: "How to get your Cursor token",
+      steps: [
+        "1. Open Cursor IDE and make sure you're logged in",
+        "2. Find the state.vscdb file:",
+        `   - Linux: ${this.config.tokenStoragePaths.linux}`,
+        `   - macOS: ${this.config.tokenStoragePaths.macos}`,
+        `   - Windows: ${this.config.tokenStoragePaths.windows}`,
+        "3. Open the database with SQLite browser or CLI:",
+        "   sqlite3 state.vscdb \"SELECT value FROM itemTable WHERE key='cursorAuth/accessToken'\"",
+        "4. Also get the machine ID:",
+        "   sqlite3 state.vscdb \"SELECT value FROM itemTable WHERE key='storage.serviceMachineId'\"",
+        "5. Paste both values in the form below",
+      ],
+      alternativeMethod: [
+        "Or use this one-liner to get both values:",
+        "sqlite3 state.vscdb \"SELECT key, value FROM itemTable WHERE key IN ('cursorAuth/accessToken', 'storage.serviceMachineId')\"",
+      ],
+    };
+  }
+}
diff --git a/src/lib/oauth/services/gemini.js b/src/lib/oauth/services/gemini.js
new file mode 100644
index 0000000..fd8dca7
--- /dev/null
+++ b/src/lib/oauth/services/gemini.js
@@ -0,0 +1,240 @@
+import crypto from "crypto";
+import open from "open";
+import { GEMINI_CONFIG, getOAuthClientMetadata } from "../constants/oauth.js";
+import { getServerCredentials } from "../config/index.js";
+import { startLocalServer } from "../utils/server.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+
+/**
+ * Gemini CLI (Google Cloud Code Assist) OAuth Service
+ * Uses standard OAuth2 Authorization Code flow (no PKCE)
+ */
+export class GeminiCLIService {
+  constructor() {
+    this.config = GEMINI_CONFIG;
+  }
+
+  /**
+   * Build Gemini CLI authorization URL
+   */
+  buildAuthUrl(redirectUri, state) {
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      response_type: "code",
+      redirect_uri: redirectUri,
+      scope: this.config.scopes.join(" "),
+      state: state,
+      access_type: "offline",
+      prompt: "consent",
+    });
+
+    return `${this.config.authorizeUrl}?${params.toString()}`;
+  }
+
+  /**
+   * Exchange authorization code for tokens
+   */
+  async exchangeCode(code, redirectUri) {
+    const response = await fetch(this.config.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+        code: code,
+        redirect_uri: redirectUri,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Fetch project ID from Google Cloud Code Assist
+   */
+  async fetchProjectId(accessToken) {
+    const response = await fetch(
+      "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+      {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+          "User-Agent": "google-api-nodejs-client/9.15.1",
+          "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+          "Client-Metadata": JSON.stringify(getOAuthClientMetadata())
+        },
+        body: JSON.stringify({
+          metadata: getOAuthClientMetadata(),
+          mode: 1
+        })
+      }
+    );
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to fetch project ID: ${error}`);
+    }
+
+    const data = await response.json();
+
+    // Extract project ID
+    let projectId = "";
+    if (typeof data.cloudaicompanionProject === "string") {
+      projectId = data.cloudaicompanionProject.trim();
+    } else if (data.cloudaicompanionProject?.id) {
+      projectId = data.cloudaicompanionProject.id.trim();
+    }
+
+    if (!projectId) {
+      throw new Error("No project ID found in response");
+    }
+
+    return projectId;
+  }
+
+  /**
+   * Get user info from Google
+   */
+  async getUserInfo(accessToken) {
+    const response = await fetch(`${this.config.userInfoUrl}?alt=json`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to get user info: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Save Gemini CLI tokens to server
+   */
+  async saveTokens(tokens, userInfo, projectId) {
+    const { server, token, userId } = getServerCredentials();
+
+    const response = await fetch(`${server}/api/cli/providers/gemini-cli`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        "X-User-Id": userId,
+      },
+      body: JSON.stringify({
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+        scope: tokens.scope,
+        email: userInfo.email,
+        projectId: projectId,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error || "Failed to save tokens");
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Complete Gemini OAuth flow
+   */
+  async connect() {
+    const spinner = createSpinner("Starting Gemini OAuth...").start();
+
+    try {
+      spinner.text = "Starting local server...";
+
+      // Start local server for callback
+      let callbackParams = null;
+      const { port, close } = await startLocalServer((params) => {
+        callbackParams = params;
+      });
+
+      const redirectUri = `http://localhost:${port}/callback`;
+      spinner.succeed(`Local server started on port ${port}`);
+
+      // Generate state
+      const state = crypto.randomBytes(32).toString("base64url");
+
+      // Build authorization URL
+      const authUrl = this.buildAuthUrl(redirectUri, state);
+
+      console.log("\nOpening browser for Google authentication...");
+      console.log(`If browser doesn't open, visit:\n${authUrl}\n`);
+
+      // Open browser
+      await open(authUrl);
+
+      // Wait for callback
+      spinner.start("Waiting for Google authorization...");
+
+      await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error("Authentication timeout (5 minutes)"));
+        }, 300000);
+
+        const checkInterval = setInterval(() => {
+          if (callbackParams) {
+            clearInterval(checkInterval);
+            clearTimeout(timeout);
+            resolve();
+          }
+        }, 100);
+      });
+
+      close();
+
+      if (callbackParams.error) {
+        throw new Error(callbackParams.error_description || callbackParams.error);
+      }
+
+      if (!callbackParams.code) {
+        throw new Error("No authorization code received");
+      }
+
+      spinner.start("Exchanging code for tokens...");
+
+      // Exchange code for tokens
+      const tokens = await this.exchangeCode(callbackParams.code, redirectUri);
+
+      spinner.text = "Fetching user info...";
+
+      // Get user info
+      const userInfo = await this.getUserInfo(tokens.access_token);
+
+      spinner.text = "Fetching project ID...";
+
+      // Fetch project ID
+      const projectId = await this.fetchProjectId(tokens.access_token);
+
+      spinner.text = "Saving tokens to server...";
+
+      // Save tokens to server
+      await this.saveTokens(tokens, userInfo, projectId);
+
+      spinner.succeed(`Gemini CLI connected successfully! (${userInfo.email}, Project: ${projectId})`);
+      return true;
+    } catch (error) {
+      spinner.fail(`Failed: ${error.message}`);
+      throw error;
+    }
+  }
+}
+
diff --git a/src/lib/oauth/services/github.js b/src/lib/oauth/services/github.js
new file mode 100644
index 0000000..79f1e31
--- /dev/null
+++ b/src/lib/oauth/services/github.js
@@ -0,0 +1,225 @@
+import { OAuthService } from "./oauth.js";
+import { GITHUB_CONFIG } from "../constants/oauth.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+
+/**
+ * GitHub Copilot OAuth Service
+ * Uses Device Code Flow for authentication
+ */
+export class GitHubService extends OAuthService {
+  constructor() {
+    super(GITHUB_CONFIG);
+  }
+
+  /**
+   * Get device code for GitHub authentication
+   */
+  async getDeviceCode() {
+    const response = await fetch(`${GITHUB_CONFIG.deviceCodeUrl}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        client_id: GITHUB_CONFIG.clientId,
+        scope: GITHUB_CONFIG.scopes,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to get device code: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Poll for access token using device code
+   */
+  async pollAccessToken(deviceCode, verificationUri, userCode, interval = 5000) {
+    const spinner = createSpinner("Waiting for GitHub authentication...").start();
+    
+    // Show user code and verification URL
+    console.log(`\nPlease visit: ${verificationUri}`);
+    console.log(`Enter code: ${userCode}\n`);
+    
+    // Open browser automatically
+    try {
+      const open = (await import("open")).default;
+      await open(verificationUri);
+    } catch (error) {
+      console.log("Could not open browser automatically. Please visit the URL above manually.");
+    }
+
+    // Poll for access token
+    while (true) {
+      await new Promise(resolve => setTimeout(resolve, interval));
+
+      const response = await fetch(`${GITHUB_CONFIG.tokenUrl}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          client_id: GITHUB_CONFIG.clientId,
+          device_code: deviceCode,
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        }),
+      });
+
+      const data = await response.json();
+
+      if (data.access_token) {
+        spinner.succeed("GitHub authentication successful!");
+        return {
+          access_token: data.access_token,
+          token_type: data.token_type,
+          scope: data.scope,
+        };
+      } else if (data.error === "authorization_pending") {
+        // Continue polling
+        continue;
+      } else if (data.error === "slow_down") {
+        // Increase polling interval
+        interval += 5000;
+        continue;
+      } else if (data.error === "expired_token") {
+        spinner.fail("Device code expired. Please try again.");
+        throw new Error("Device code expired");
+      } else if (data.error === "access_denied") {
+        spinner.fail("Access denied by user.");
+        throw new Error("Access denied");
+      } else {
+        spinner.fail("Failed to get access token.");
+        throw new Error(data.error_description || data.error);
+      }
+    }
+  }
+
+  /**
+   * Get Copilot token using GitHub access token
+   */
+  async getCopilotToken(accessToken) {
+    const response = await fetch(`${GITHUB_CONFIG.copilotTokenUrl}`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`, // GitHub API typically uses Bearer
+        Accept: "application/json",
+        "X-GitHub-Api-Version": GITHUB_CONFIG.apiVersion,
+        "User-Agent": GITHUB_CONFIG.userAgent,
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to get Copilot token: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Get user info using GitHub access token
+   */
+  async getUserInfo(accessToken) {
+    const response = await fetch(`${GITHUB_CONFIG.userInfoUrl}`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`, // GitHub API typically uses Bearer
+        Accept: "application/json",
+        "X-GitHub-Api-Version": GITHUB_CONFIG.apiVersion,
+        "User-Agent": GITHUB_CONFIG.userAgent,
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to get user info: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Complete GitHub Copilot authentication flow
+   */
+  async authenticate() {
+    try {
+      // Get device code
+      const deviceResponse = await this.getDeviceCode();
+      
+      // Poll for access token
+      const tokenResponse = await this.pollAccessToken(
+        deviceResponse.device_code, 
+        deviceResponse.verification_uri, 
+        deviceResponse.user_code
+      );
+      
+      // Get Copilot token
+      const copilotToken = await this.getCopilotToken(tokenResponse.access_token);
+      
+      // Get user info
+      const userInfo = await this.getUserInfo(tokenResponse.access_token);
+      
+      console.log(`\n✅ Successfully authenticated as ${userInfo.login}`);
+      
+      return {
+        accessToken: tokenResponse.access_token,
+        copilotToken: copilotToken.token,
+        refreshToken: null, // GitHub device flow doesn't return refresh token
+        expiresIn: copilotToken.expires_at,
+        userInfo: {
+          id: userInfo.id,
+          login: userInfo.login,
+          name: userInfo.name,
+          email: userInfo.email,
+        },
+        copilotTokenInfo: copilotToken,
+      };
+    } catch (error) {
+      throw new Error(`GitHub authentication failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Connect to server with GitHub credentials
+   */
+  async connect() {
+    try {
+      // Authenticate with GitHub
+      const authResult = await this.authenticate();
+      
+      // Send credentials to server
+      const { server, token, userId } = await import("../config/index.js").then(m => m.getServerCredentials());
+      const spinner = (await import("../utils/ui.js")).spinner("Connecting to server...").start();
+      
+      const response = await fetch(`${server}/api/cli/providers/github`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`,
+          "X-User-Id": userId,
+        },
+        body: JSON.stringify({
+          accessToken: authResult.accessToken,
+          copilotToken: authResult.copilotToken,
+          userInfo: authResult.userInfo,
+          copilotTokenInfo: authResult.copilotTokenInfo,
+        }),
+      });
+      
+      if (!response.ok) {
+        const errorData = await response.json();
+        throw new Error(errorData.error || "Failed to connect to server");
+      }
+      
+      spinner.succeed("GitHub Copilot connected successfully!");
+      console.log(`\nConnected as: ${authResult.userInfo.login}`);
+    } catch (error) {
+      const { error: showError } = await import("../utils/ui.js");
+      showError(`GitHub connection failed: ${error.message}`);
+      throw error;
+    }
+  }
+}
diff --git a/src/lib/oauth/services/iflow.js b/src/lib/oauth/services/iflow.js
new file mode 100644
index 0000000..307522e
--- /dev/null
+++ b/src/lib/oauth/services/iflow.js
@@ -0,0 +1,202 @@
+import crypto from "crypto";
+import open from "open";
+import { IFLOW_CONFIG } from "../constants/oauth.js";
+import { getServerCredentials } from "../config/index.js";
+import { startLocalServer } from "../utils/server.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+
+/**
+ * iFlow OAuth Service
+ * Uses Authorization Code flow with Basic Auth
+ */
+export class IFlowService {
+  constructor() {
+    this.config = IFLOW_CONFIG;
+  }
+
+  /**
+   * Build iFlow authorization URL
+   */
+  buildAuthUrl(redirectUri, state) {
+    const params = new URLSearchParams({
+      loginMethod: this.config.extraParams.loginMethod,
+      type: this.config.extraParams.type,
+      redirect: redirectUri,
+      state: state,
+      client_id: this.config.clientId,
+    });
+
+    return `${this.config.authorizeUrl}?${params.toString()}`;
+  }
+
+  /**
+   * Exchange authorization code for tokens
+   */
+  async exchangeCode(code, redirectUri) {
+    // Create Basic Auth header
+    const basicAuth = Buffer.from(
+      `${this.config.clientId}:${this.config.clientSecret}`
+    ).toString("base64");
+
+    const response = await fetch(this.config.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+        Authorization: `Basic ${basicAuth}`,
+      },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code: code,
+        redirect_uri: redirectUri,
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Get user info from iFlow
+   */
+  async getUserInfo(accessToken) {
+    const response = await fetch(
+      `${this.config.userInfoUrl}?accessToken=${encodeURIComponent(accessToken)}`,
+      {
+        headers: {
+          Accept: "application/json",
+        },
+      }
+    );
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to get user info: ${error}`);
+    }
+
+    const result = await response.json();
+
+    if (!result.success) {
+      throw new Error("Failed to get user info");
+    }
+
+    return result.data;
+  }
+
+  /**
+   * Save iFlow tokens to server
+   */
+  async saveTokens(tokens, userInfo) {
+    const { server, token, userId } = getServerCredentials();
+
+    const response = await fetch(`${server}/api/cli/providers/iflow`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        "X-User-Id": userId,
+      },
+      body: JSON.stringify({
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+        apiKey: userInfo.apiKey,
+        email: userInfo.email || userInfo.phone,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error || "Failed to save tokens");
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Complete iFlow OAuth flow
+   */
+  async connect() {
+    const spinner = createSpinner("Starting iFlow OAuth...").start();
+
+    try {
+      spinner.text = "Starting local server...";
+
+      // Start local server for callback
+      let callbackParams = null;
+      const { port, close } = await startLocalServer((params) => {
+        callbackParams = params;
+      });
+
+      const redirectUri = `http://localhost:${port}/callback`;
+      spinner.succeed(`Local server started on port ${port}`);
+
+      // Generate state
+      const state = crypto.randomBytes(32).toString("base64url");
+
+      // Build authorization URL
+      const authUrl = this.buildAuthUrl(redirectUri, state);
+
+      console.log("\nOpening browser for iFlow authentication...");
+      console.log(`If browser doesn't open, visit:\n${authUrl}\n`);
+
+      // Open browser
+      await open(authUrl);
+
+      // Wait for callback
+      spinner.start("Waiting for iFlow authorization...");
+
+      await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error("Authentication timeout (5 minutes)"));
+        }, 300000);
+
+        const checkInterval = setInterval(() => {
+          if (callbackParams) {
+            clearInterval(checkInterval);
+            clearTimeout(timeout);
+            resolve();
+          }
+        }, 100);
+      });
+
+      close();
+
+      if (callbackParams.error) {
+        throw new Error(callbackParams.error_description || callbackParams.error);
+      }
+
+      if (!callbackParams.code) {
+        throw new Error("No authorization code received");
+      }
+
+      spinner.start("Exchanging code for tokens...");
+
+      // Exchange code for tokens
+      const tokens = await this.exchangeCode(callbackParams.code, redirectUri);
+
+      spinner.text = "Fetching user info...";
+
+      // Get user info (includes API key)
+      const userInfo = await this.getUserInfo(tokens.access_token);
+
+      spinner.text = "Saving tokens to server...";
+
+      // Save tokens to server
+      await this.saveTokens(tokens, userInfo);
+
+      spinner.succeed(`iFlow connected successfully! (${userInfo.email || userInfo.phone})`);
+      return true;
+    } catch (error) {
+      spinner.fail(`Failed: ${error.message}`);
+      throw error;
+    }
+  }
+}
+
diff --git a/src/lib/oauth/services/index.js b/src/lib/oauth/services/index.js
new file mode 100644
index 0000000..33cea03
--- /dev/null
+++ b/src/lib/oauth/services/index.js
@@ -0,0 +1,17 @@
+/**
+ * Export all services
+ */
+
+export { OAuthService } from "./oauth.js";
+export { ClaudeService } from "./claude.js";
+export { CodexService } from "./codex.js";
+export { GeminiCLIService } from "./gemini.js";
+export { QwenService } from "./qwen.js";
+export { IFlowService } from "./iflow.js";
+export { QoderService } from "./qoder.js";
+export { AntigravityService } from "./antigravity.js";
+export { OpenAIService } from "./openai.js";
+export { GitHubService } from "./github.js";
+export { KiroService } from "./kiro.js";
+export { CursorService } from "./cursor.js";
+
diff --git a/src/lib/oauth/services/kimchi.js b/src/lib/oauth/services/kimchi.js
new file mode 100644
index 0000000..7e929e9
--- /dev/null
+++ b/src/lib/oauth/services/kimchi.js
@@ -0,0 +1,133 @@
+// Kimchi browser-login service.
+//
+// Ports Kimchi CLI's authenticateViaBrowser (src/cli-auth/index.ts) onto
+// 9Router's shared startLocalServer util (same one xai/antigravity use).
+// Simpler than those: the token arrives directly on the callback query
+// string — no authorization-code exchange, no PKCE.
+//
+// In-flight logins are held in `sessions` keyed by state. The OAuthModal
+// device_code flow starts one via requestDeviceCode(); pollToken() peeks
+// at the resolved token; the generic [provider]/[action] route calls
+// createProviderConnection with the real token.
+import { randomBytes } from "node:crypto";
+import { startLocalServer } from "../utils/server.js";
+import { KIMCHI_CONFIG } from "../constants/oauth.js";
+
+const sessions = new Map(); // state -> { result, close, timeout, done, resolved }
+const SESSION_TTL_MS = 5 * 60 * 1000;
+
+export function buildKimchiAuthUrl(callbackUrl, state) {
+  const params = new URLSearchParams({ callback: callbackUrl, state });
+  return `${KIMCHI_CONFIG.webAppUrl}/cli-auth?${params.toString()}`;
+}
+
+export function generateState() {
+  return randomBytes(32).toString("hex");
+}
+
+// Returns the resolved { token } if the session for `state` has completed,
+// or null if it is still pending / unknown.
+export function getResolvedSession(state) {
+  const s = sessions.get(state);
+  if (!s || !s.done || !s.resolved) return null;
+  return s.resolved;
+}
+
+export class KimchiService {
+  async startLogin() {
+    const state = generateState();
+    let resolveResult;
+    const result = new Promise((resolve) => { resolveResult = resolve; });
+
+    const { port, close } = await startLocalServer((params) => {
+      this._handleCallback(params, state)
+        .then(resolveResult)
+        .catch((err) => resolveResult({ error: err.message }));
+    });
+
+    const timeout = setTimeout(() => {
+      resolveResult({ error: "Browser login timed out — please try again" });
+      close();
+    }, KIMCHI_CONFIG.callbackTimeoutMs);
+
+    sessions.set(state, { result, close, timeout, done: false, resolved: null });
+
+    // Stash the resolved value so pollToken() can retrieve the real token,
+    // close the loopback server, and reap the session after a TTL so the
+    // Map can't grow unbounded across many logins.
+    result.then((r) => {
+      const s = sessions.get(state);
+      if (!s) return;
+      s.done = true;
+      s.resolved = r;
+      clearTimeout(s.timeout);
+      try { s.close(); } catch { /* already closed */ }
+      setTimeout(() => sessions.delete(state), SESSION_TTL_MS).unref?.();
+    });
+
+    const callbackUrl = `http://127.0.0.1:${port}${KIMCHI_CONFIG.callbackPath}`;
+    const authUrl = buildKimchiAuthUrl(callbackUrl, state);
+    return { authUrl, port, state, result, close };
+  }
+
+  async _handleCallback(params, expectedState) {
+    if (params.error) {
+      throw new Error(params.error_description || params.error);
+    }
+    const candidate = params.state;
+    if (!candidate || candidate !== expectedState) {
+      throw new Error("This request isn't valid. Please restart the Kimchi login flow.");
+    }
+    const token = params.token;
+    if (!token) {
+      throw new Error("No token was returned by the Kimchi authentication server");
+    }
+    const check = await this.validateToken(token);
+    if (!check.valid) {
+      throw new Error(check.error || "Kimchi token validation failed");
+    }
+    return { token };
+  }
+
+  async fetchProfile(token) {
+    try {
+      const res = await fetch(KIMCHI_CONFIG.meUrl, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (!res.ok) return {};
+      const j = await res.json();
+      return { displayName: j.name, email: j.email, username: j.username };
+    } catch {
+      return {};
+    }
+  }
+
+  // Validate a token against Kimchi's supported-providers endpoint.
+  // 200 → valid; 401/403 → invalid; anything else (incl. network/timeout)
+  // → fail-open valid so a flaky validation never blocks a good login.
+  async validateToken(token) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    let status = 0;
+    try {
+      const res = await fetch(KIMCHI_CONFIG.validationUrl, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: "application/json",
+        },
+        signal: controller.signal,
+      });
+      status = res.status;
+    } catch {
+      // Network error / abort → fail-open
+      return { valid: true };
+    } finally {
+      clearTimeout(timer);
+    }
+    if (status === 200) return { valid: true };
+    if (status === 401) return { valid: false, error: "Kimchi token invalid or expired" };
+    if (status === 403) return { valid: false, error: "Kimchi token lacks required scope" };
+    return { valid: true };
+  }
+}
diff --git a/src/lib/oauth/services/kiro.js b/src/lib/oauth/services/kiro.js
new file mode 100644
index 0000000..a739661
--- /dev/null
+++ b/src/lib/oauth/services/kiro.js
@@ -0,0 +1,381 @@
+import { KIRO_CONFIG, assertValidAwsRegion } from "../constants/oauth.js";
+
+/**
+ * Kiro OAuth Service
+ * Supports multiple authentication methods:
+ * 1. AWS Builder ID (Device Code Flow)
+ * 2. AWS IAM Identity Center/IDC (Device Code Flow)
+ * 3. Google/GitHub Social Login (Authorization Code Flow + Manual Callback)
+ * 4. Import Token (Manual refresh token paste)
+ */
+
+const KIRO_AUTH_SERVICE = "https://prod.us-east-1.auth.desktop.kiro.dev";
+
+export class KiroService {
+  /**
+   * Register OIDC client with AWS SSO
+   * Returns clientId and clientSecret for device code flow
+   */
+  async registerClient(region = "us-east-1") {
+    assertValidAwsRegion(region);
+    const endpoint = `https://oidc.${region}.amazonaws.com/client/register`;
+
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        clientName: KIRO_CONFIG.clientName,
+        clientType: KIRO_CONFIG.clientType,
+        scopes: KIRO_CONFIG.scopes,
+        grantTypes: KIRO_CONFIG.grantTypes,
+        issuerUrl: KIRO_CONFIG.issuerUrl,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to register client: ${error}`);
+    }
+
+    const data = await response.json();
+    return {
+      clientId: data.clientId,
+      clientSecret: data.clientSecret,
+      clientSecretExpiresAt: data.clientSecretExpiresAt,
+    };
+  }
+
+  /**
+   * Start device authorization for AWS Builder ID or IDC
+   */
+  async startDeviceAuthorization(clientId, clientSecret, startUrl, region = "us-east-1") {
+    assertValidAwsRegion(region);
+    const endpoint = `https://oidc.${region}.amazonaws.com/device_authorization`;
+
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        clientId,
+        clientSecret,
+        startUrl,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to start device authorization: ${error}`);
+    }
+
+    const data = await response.json();
+    return {
+      deviceCode: data.deviceCode,
+      userCode: data.userCode,
+      verificationUri: data.verificationUri,
+      verificationUriComplete: data.verificationUriComplete,
+      expiresIn: data.expiresIn,
+      interval: data.interval || 5,
+    };
+  }
+
+  /**
+   * Poll for token using device code (AWS Builder ID/IDC)
+   */
+  async pollDeviceToken(clientId, clientSecret, deviceCode, region = "us-east-1") {
+    assertValidAwsRegion(region);
+    const endpoint = `https://oidc.${region}.amazonaws.com/token`;
+
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        clientId,
+        clientSecret,
+        deviceCode,
+        grantType: "urn:ietf:params:oauth:grant-type:device_code",
+      }),
+    });
+
+    const data = await response.json();
+
+    // Handle pending/slow_down/errors
+    if (!response.ok || data.error) {
+      return {
+        success: false,
+        error: data.error,
+        errorDescription: data.error_description,
+        pending: data.error === "authorization_pending" || data.error === "slow_down",
+      };
+    }
+
+    return {
+      success: true,
+      tokens: {
+        accessToken: data.accessToken,
+        refreshToken: data.refreshToken,
+        expiresIn: data.expiresIn,
+        tokenType: data.tokenType,
+      },
+    };
+  }
+
+  /**
+   * Build Google/GitHub social login URL
+   * Returns authorization URL for manual callback flow
+   * Uses kiro:// custom protocol as required by AWS Cognito whitelist
+   */
+  buildSocialLoginUrl(provider, codeChallenge, state) {
+    const idp = provider === "google" ? "Google" : "Github";
+    // AWS Cognito only whitelists kiro:// protocol, not localhost
+    const redirectUri = "kiro://kiro.kiroAgent/authenticate-success";
+    return `${KIRO_AUTH_SERVICE}/login?idp=${idp}&redirect_uri=${encodeURIComponent(redirectUri)}&code_challenge=${codeChallenge}&code_challenge_method=S256&state=${state}&prompt=select_account`;
+  }
+
+  /**
+   * Exchange authorization code for tokens (Social Login)
+   * Must use same redirect_uri as authorization request
+   */
+  async exchangeSocialCode(code, codeVerifier) {
+    // Must match the redirect_uri used in buildSocialLoginUrl
+    const redirectUri = "kiro://kiro.kiroAgent/authenticate-success";
+
+    const response = await fetch(`${KIRO_AUTH_SERVICE}/oauth/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        code,
+        code_verifier: codeVerifier,
+        redirect_uri: redirectUri,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+
+    const data = await response.json();
+    return {
+      accessToken: data.accessToken,
+      refreshToken: data.refreshToken,
+      profileArn: data.profileArn,
+      expiresIn: data.expiresIn || 3600,
+    };
+  }
+
+  /**
+   * Refresh token using refresh token
+   */
+  async refreshToken(refreshToken, providerSpecificData = {}) {
+    const { authMethod, clientId, clientSecret, region } = providerSpecificData;
+
+    // AWS SSO OIDC refresh (Builder ID or IDC)
+    if (clientId && clientSecret) {
+      const safeRegion = region || "us-east-1";
+      assertValidAwsRegion(safeRegion);
+      const endpoint = `https://oidc.${safeRegion}.amazonaws.com/token`;
+
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          clientId,
+          clientSecret,
+          refreshToken,
+          grantType: "refresh_token",
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Token refresh failed: ${error}`);
+      }
+
+      const data = await response.json();
+      return {
+        accessToken: data.accessToken,
+        refreshToken: data.refreshToken || refreshToken,
+        profileArn: data.profileArn,
+        expiresIn: data.expiresIn,
+      };
+    }
+
+    // Social auth refresh (Google/GitHub)
+    const response = await fetch(`${KIRO_AUTH_SERVICE}/refreshToken`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        refreshToken,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token refresh failed: ${error}`);
+    }
+
+    const data = await response.json();
+    return {
+      accessToken: data.accessToken,
+      refreshToken: data.refreshToken || refreshToken,
+      profileArn: data.profileArn,
+      expiresIn: data.expiresIn || 3600,
+    };
+  }
+
+  /**
+   * Validate and import refresh token
+   */
+  async validateImportToken(refreshToken) {
+    // Validate token format
+    if (!refreshToken.startsWith("aorAAAAAG")) {
+      throw new Error("Invalid token format. Token should start with aorAAAAAG...");
+    }
+
+    // Try to refresh to validate
+    try {
+      const result = await this.refreshToken(refreshToken);
+      return {
+        accessToken: result.accessToken,
+        refreshToken: result.refreshToken || refreshToken,
+        profileArn: result.profileArn,
+        expiresIn: result.expiresIn,
+        authMethod: "imported",
+      };
+    } catch (error) {
+      throw new Error(`Token validation failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * List available CodeWhisperer profiles for a token (or API key) and return
+   * the best-matching profileArn. AWS SSO OIDC logins return no profileArn, so
+   * it must be fetched separately — the same call works for API-key auth.
+   * Accepts both `arn` and `profileArn` response field names (the API-key
+   * JSON-1.0 surface returns `arn`).
+   */
+  async listAvailableProfiles(accessToken, region = "us-east-1") {
+    assertValidAwsRegion(region);
+    const endpoint = `https://codewhisperer.${region}.amazonaws.com`;
+
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-amz-json-1.0",
+        "x-amz-target": "AmazonCodeWhispererService.ListAvailableProfiles",
+        "Authorization": `Bearer ${accessToken}`,
+        "Accept": "application/json",
+      },
+      body: JSON.stringify({ maxResults: 10 }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to list profiles: ${error}`);
+    }
+
+    const data = await response.json();
+    const profiles = Array.isArray(data?.profiles) ? data.profiles : [];
+    const arnOf = (p) => p?.arn || p?.profileArn || null;
+    const match = profiles.find((p) => arnOf(p)?.split(":")[3] === region) || profiles[0];
+    return arnOf(match);
+  }
+
+  /**
+   * Validate an API-key credential by listing profiles with it. API keys are
+   * long-lived bearer tokens (no refresh), so the only way to validate one is
+   * to make an authenticated CodeWhisperer call. Returns a credential object
+   * ready to persist as a "kiro" connection with authMethod="api_key".
+   */
+  async validateApiKey(apiKey, region = "us-east-1") {
+    if (!apiKey || typeof apiKey !== "string" || !apiKey.trim()) {
+      throw new Error("API key is required");
+    }
+    const trimmed = apiKey.trim();
+
+    let profileArn = null;
+    try {
+      profileArn = await this.listAvailableProfiles(trimmed, region);
+    } catch (error) {
+      throw new Error(`API key validation failed: ${error.message}`);
+    }
+
+    return {
+      accessToken: trimmed,
+      refreshToken: null,
+      profileArn,
+      region,
+      authMethod: "api_key",
+    };
+  }
+
+  /**
+   * List available models from CodeWhisperer API
+   */
+  async listAvailableModels(accessToken, profileArn) {
+    const endpoint = "https://codewhisperer.us-east-1.amazonaws.com";
+    const target = "AmazonCodeWhispererService.ListAvailableModels";
+
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-amz-json-1.0",
+        "x-amz-target": target,
+        "Authorization": `Bearer ${accessToken}`,
+        "Accept": "application/json",
+      },
+      body: JSON.stringify({
+        origin: "AI_EDITOR",
+        profileArn,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to list models: ${error}`);
+    }
+
+    const data = await response.json();
+    return (data.models || []).map(m => ({
+      id: m.modelId,
+      name: m.modelName || m.modelId,
+      description: m.description,
+      rateMultiplier: m.rateMultiplier,
+      rateUnit: m.rateUnit,
+      maxInputTokens: m.tokenLimits?.maxInputTokens || 0,
+    }));
+  }
+
+  /**
+   * Fetch user email from access token (optional, for display)
+   */
+  extractEmailFromJWT(accessToken) {
+    try {
+      const parts = accessToken.split(".");
+      if (parts.length !== 3) return null;
+
+      // Decode payload (add padding if needed)
+      let payload = parts[1];
+      while (payload.length % 4) {
+        payload += "=";
+      }
+
+      const decoded = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/")));
+      return decoded.email || decoded.preferred_username || decoded.sub;
+    } catch {
+      return null;
+    }
+  }
+}
diff --git a/src/lib/oauth/services/oauth.js b/src/lib/oauth/services/oauth.js
new file mode 100644
index 0000000..f056171
--- /dev/null
+++ b/src/lib/oauth/services/oauth.js
@@ -0,0 +1,157 @@
+import open from "open";
+import { startLocalServer } from "../utils/server.js";
+import { generatePKCE } from "../utils/pkce.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+import { OAUTH_TIMEOUT } from "../constants/oauth.js";
+
+/**
+ * Generic OAuth Authorization Code Flow with PKCE
+ */
+export class OAuthService {
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Build authorization URL
+   */
+  buildAuthUrl(redirectUri, state, codeChallenge, extraParams = {}) {
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      response_type: "code",
+      redirect_uri: redirectUri,
+      state: state,
+      code_challenge: codeChallenge,
+      code_challenge_method: this.config.codeChallengeMethod,
+      ...extraParams,
+    });
+
+    return `${this.config.authorizeUrl}?${params.toString()}`;
+  }
+
+  /**
+   * Start local server and wait for callback
+   */
+  async startAuthFlow(authUrl, providerName) {
+    const spinner = createSpinner("Starting local server...").start();
+
+    // Start local server for callback
+    let callbackParams = null;
+    const { port, close } = await startLocalServer((params) => {
+      callbackParams = params;
+    });
+
+    const redirectUri = `http://localhost:${port}/callback`;
+    spinner.succeed(`Local server started on port ${port}`);
+
+    return {
+      redirectUri,
+      port,
+      close,
+      waitForCallback: async () => {
+        spinner.start(`Waiting for ${providerName} authorization...`);
+
+        await new Promise((resolve, reject) => {
+          const timeout = setTimeout(() => {
+            reject(new Error("Authentication timeout (5 minutes)"));
+          }, OAUTH_TIMEOUT);
+
+          const checkInterval = setInterval(() => {
+            if (callbackParams) {
+              clearInterval(checkInterval);
+              clearTimeout(timeout);
+              resolve();
+            }
+          }, 100);
+        });
+
+        spinner.stop();
+        close();
+
+        if (callbackParams.error) {
+          throw new Error(callbackParams.error_description || callbackParams.error);
+        }
+
+        if (!callbackParams.code) {
+          throw new Error("No authorization code received");
+        }
+
+        return callbackParams;
+      },
+    };
+  }
+
+  /**
+   * Exchange authorization code for tokens
+   */
+  async exchangeCode(code, redirectUri, codeVerifier, contentType = "application/x-www-form-urlencoded") {
+    const body =
+      contentType === "application/json"
+        ? JSON.stringify({
+            grant_type: "authorization_code",
+            client_id: this.config.clientId,
+            code: code,
+            redirect_uri: redirectUri,
+            code_verifier: codeVerifier,
+          })
+        : new URLSearchParams({
+            grant_type: "authorization_code",
+            client_id: this.config.clientId,
+            code: code,
+            redirect_uri: redirectUri,
+            code_verifier: codeVerifier,
+          });
+
+    const response = await fetch(this.config.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": contentType,
+        Accept: "application/json",
+      },
+      body: body,
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Complete OAuth flow
+   */
+  async authenticate(providerName, buildAuthUrlFn) {
+    // Generate PKCE
+    const { codeVerifier, codeChallenge, state } = generatePKCE();
+
+    // Start local server and get redirect URI
+    const { redirectUri, waitForCallback } = await this.startAuthFlow(null, providerName);
+
+    // Build authorization URL
+    const authUrl = buildAuthUrlFn(redirectUri, state, codeChallenge);
+
+    console.log(`\nOpening browser for ${providerName} authentication...`);
+    console.log(`If browser doesn't open, visit:\n${authUrl}\n`);
+
+    // Open browser
+    await open(authUrl);
+
+    // Wait for callback
+    const callbackParams = await waitForCallback();
+
+    // Validate state
+    if (callbackParams.state !== state) {
+      throw new Error("Invalid state parameter");
+    }
+
+    return {
+      code: callbackParams.code,
+      state: callbackParams.state,
+      codeVerifier,
+      redirectUri,
+    };
+  }
+}
+
diff --git a/src/lib/oauth/services/openai.js b/src/lib/oauth/services/openai.js
new file mode 100644
index 0000000..851260a
--- /dev/null
+++ b/src/lib/oauth/services/openai.js
@@ -0,0 +1,123 @@
+import { OAuthService } from "./oauth.js";
+import { OPENAI_CONFIG } from "../constants/oauth.js";
+import { getServerCredentials } from "../config/index.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+
+/**
+ * OpenAI OAuth Service (Native)
+ * Uses Authorization Code Flow with PKCE (similar to Codex)
+ */
+export class OpenAIService extends OAuthService {
+  constructor() {
+    super(OPENAI_CONFIG);
+  }
+
+  /**
+   * Build OpenAI authorization URL
+   */
+  buildOpenAIAuthUrl(redirectUri, state, codeChallenge) {
+    const params = new URLSearchParams({
+      client_id: OPENAI_CONFIG.clientId,
+      response_type: "code",
+      redirect_uri: redirectUri,
+      scope: OPENAI_CONFIG.scope,
+      state: state,
+      code_challenge: codeChallenge,
+      code_challenge_method: OPENAI_CONFIG.codeChallengeMethod,
+      ...OPENAI_CONFIG.extraParams,
+    });
+
+    return `${OPENAI_CONFIG.authorizeUrl}?${params.toString()}`;
+  }
+
+  /**
+   * Exchange OpenAI authorization code for tokens
+   */
+  async exchangeOpenAICode(code, redirectUri, codeVerifier) {
+    const response = await fetch(OPENAI_CONFIG.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: OPENAI_CONFIG.clientId,
+        code: code,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Save OpenAI tokens to server
+   */
+  async saveTokens(tokens) {
+    const { server, token, userId } = getServerCredentials();
+
+    const response = await fetch(`${server}/api/cli/providers/openai`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        "X-User-Id": userId,
+      },
+      body: JSON.stringify({
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+        idToken: tokens.id_token,
+        scope: tokens.scope,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error || "Failed to save tokens");
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Complete OpenAI OAuth flow
+   */
+  async connect() {
+    const spinner = createSpinner("Starting OpenAI OAuth...").start();
+
+    try {
+      spinner.text = "Starting local server...";
+
+      // Authenticate and get authorization code
+      const { code, codeVerifier, redirectUri } = await this.authenticate(
+        "OpenAI",
+        this.buildOpenAIAuthUrl.bind(this)
+      );
+
+      spinner.start("Exchanging code for tokens...");
+
+      // Exchange code for tokens
+      const tokens = await this.exchangeOpenAICode(code, redirectUri, codeVerifier);
+
+      spinner.text = "Saving tokens to server...";
+
+      // Save tokens to server
+      await this.saveTokens(tokens);
+
+      spinner.succeed("OpenAI connected successfully!");
+      return true;
+    } catch (error) {
+      spinner.fail(`Failed: ${error.message}`);
+      throw error;
+    }
+  }
+}
+
diff --git a/src/lib/oauth/services/qoder.js b/src/lib/oauth/services/qoder.js
new file mode 100644
index 0000000..861a99b
--- /dev/null
+++ b/src/lib/oauth/services/qoder.js
@@ -0,0 +1,216 @@
+import {
+  QODER_DEVICE_TOKEN_URL,
+  QODER_LOGIN_URL,
+  QODER_USERINFO_URL,
+} from "../../qoder/constants.js";
+import crypto from "crypto";
+import { v4 as uuidv4 } from "uuid";
+
+/**
+ * Qoder OAuth Service
+ * Implements the device-token flow:
+ *   1. Generate PKCE pair + nonce + machine_id locally.
+ *   2. Open https://qoder.com/device/selectAccounts?challenge=...&nonce=...
+ *      in the user's browser.
+ *   3. Poll openapi.qoder.sh/api/v1/deviceToken/poll until the user authorizes
+ *      and the upstream returns a `dt-...` access token.
+ *
+ * Tokens live ~30 days; refresh is a no-op (the upstream refresh endpoint
+ * returns 403 for our flow). Users re-run login when expired.
+ *
+ * Mirrors the structure of KiroService — the COSY signing / WAF-bypass body
+ * encoding / chat protocol live separately in src/lib/qoder/ because they're
+ * used by every signed request, not just OAuth.
+ */
+
+// Timeout for OAuth helper calls. The OAuth modal polls every 2s for up to
+// 5 minutes; an individual request that stalls beyond this is treated as a
+// failed poll attempt and the next poll iteration retries.
+const FETCH_TIMEOUT_MS = 15_000;
+
+function base64Url(buf) {
+  return buf
+    .toString("base64")
+    .replace(/=/g, "")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_");
+}
+
+/**
+ * Wrap fetch with an AbortController-based timeout. Without this, a stalled
+ * upstream socket hangs on Node's default keepalive timeout (minutes) and
+ * abandoned polls accumulate hung sockets.
+ */
+async function fetchWithTimeout(url, init = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort("timeout"), FETCH_TIMEOUT_MS);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export class QoderService {
+  /**
+   * Generate a PKCE verifier + S256 challenge pair.
+   * Uses 32 random bytes (matches qodercli/Veria).
+   */
+  generatePkcePair() {
+    const verifier = base64Url(crypto.randomBytes(32));
+    const challenge = base64Url(crypto.createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+  }
+
+  /**
+   * Initiate the device flow. Returns the URL to open in a browser plus the
+   * verifier/nonce/machineId we'll need to poll and to sign future requests.
+   */
+  initiateDeviceFlow() {
+    const { verifier, challenge } = this.generatePkcePair();
+    const nonce = uuidv4();
+    const machineId = uuidv4();
+
+    const params = new URLSearchParams({
+      challenge,
+      challenge_method: "S256",
+      machine_id: machineId,
+      nonce,
+    });
+
+    return {
+      verificationUriComplete: `${QODER_LOGIN_URL}?${params.toString()}`,
+      codeVerifier: verifier,
+      nonce,
+      machineId,
+    };
+  }
+
+  /**
+   * Single poll attempt. Returns one of:
+   *   { status: "pending" }       — keep polling
+   *   { status: "ok", token, ... } — user authorized, tokens captured
+   *   throws Error                 — terminal failure
+   *
+   * Upstream returns 202/404 while waiting; 200 with a JSON body when done.
+   */
+  async pollDeviceToken({ nonce, codeVerifier }) {
+    if (!nonce || !codeVerifier) {
+      throw new Error("pollDeviceToken: missing nonce or code verifier");
+    }
+    const url = `${QODER_DEVICE_TOKEN_URL}?nonce=${encodeURIComponent(nonce)}&verifier=${encodeURIComponent(codeVerifier)}&challenge_method=S256`;
+
+    const response = await fetchWithTimeout(url, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        "User-Agent": "Go-http-client/2.0",
+      },
+    });
+
+    // Pending — server has registered the device code but the user hasn't
+    // finished the browser flow yet. Both 202 and 404 mean "keep polling".
+    if (response.status === 202 || response.status === 404) {
+      return { status: "pending" };
+    }
+
+    const text = await response.text();
+
+    if (!response.ok) {
+      let message = `Qoder device token poll failed: HTTP ${response.status}`;
+      try {
+        const body = JSON.parse(text);
+        if (body.message) message = `Qoder device token poll failed: ${body.message}`;
+      } catch {}
+      throw new Error(message);
+    }
+
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch (err) {
+      throw new Error(`Qoder device token poll: invalid JSON response (${err.message})`);
+    }
+
+    // Defensive: 200 + empty token means the upstream changed shape.
+    if (!body.token) {
+      throw new Error("Qoder device token poll returned 200 but no token");
+    }
+
+    const expireMs = QoderService.parseExpiry(body.expires_at, body.expires_in);
+
+    return {
+      status: "ok",
+      accessToken: body.token,
+      refreshToken: body.refresh_token || "",
+      userId: body.user_id || "",
+      expireTime: expireMs,
+      rawResponse: body,
+    };
+  }
+
+  /**
+   * Fetch profile info for the freshly-issued token. Best-effort — failures
+   * shouldn't block login; returning empty strings is fine.
+   */
+  async fetchUserInfo(accessToken) {
+    try {
+      const response = await fetchWithTimeout(QODER_USERINFO_URL, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          Accept: "application/json",
+          "User-Agent": "Go-http-client/2.0",
+        },
+      });
+      if (!response.ok) return { name: "", email: "" };
+      const body = await response.json();
+      return {
+        name: (body.name || body.username || "").trim(),
+        email: (body.email || "").trim(),
+        organizationId: (body.organization_id || "").trim(),
+      };
+    } catch {
+      return { name: "", email: "" };
+    }
+  }
+
+  /**
+   * Convert the upstream's expiry hint into a Unix-millisecond timestamp.
+   * Accepts:
+   *   - numeric (ms-epoch): returned as-is
+   *   - numeric string of ms-epoch: e.g. "1781594470000"
+   *   - RFC3339 string: e.g. "2026-06-16T07:15:04Z"
+   *   - seconds-from-now via expiresInSeconds (>= 0)
+   * Falls back to "now + 30 days" when both are missing.
+   *
+   * Order matters: try numeric (string or number) before Date.parse, since
+   * Date.parse accepts short numeric strings like "2026" as years and would
+   * otherwise return a misleading year-2026 timestamp instead of falling
+   * through to the integer branch.
+   *
+   * Static so callers (and tests) can use it without instantiating.
+   */
+  static parseExpiry(expiresAt, expiresInSeconds) {
+    if (typeof expiresAt === "number" && Number.isFinite(expiresAt) && expiresAt > 0) {
+      return expiresAt;
+    }
+    const trimmed = typeof expiresAt === "string" ? expiresAt.trim() : "";
+    if (trimmed) {
+      // Pure numeric string → ms-epoch (don't let Date.parse swallow short
+      // numerics as years).
+      if (/^\d+$/.test(trimmed)) {
+        const ms = Number.parseInt(trimmed, 10);
+        if (Number.isFinite(ms) && ms > 0) return ms;
+      }
+      const parsed = Date.parse(trimmed);
+      if (!Number.isNaN(parsed)) return parsed;
+    }
+    // expiresInSeconds === 0 means "already expired"; honor that by returning
+    // the current time rather than fabricating a 30-day default.
+    if (typeof expiresInSeconds === "number" && Number.isFinite(expiresInSeconds) && expiresInSeconds >= 0) {
+      return Date.now() + expiresInSeconds * 1000;
+    }
+    return Date.now() + 30 * 24 * 60 * 60 * 1000;
+  }
+}
diff --git a/src/lib/oauth/services/qwen.js b/src/lib/oauth/services/qwen.js
new file mode 100644
index 0000000..ee4489e
--- /dev/null
+++ b/src/lib/oauth/services/qwen.js
@@ -0,0 +1,170 @@
+import open from "open";
+import { QWEN_CONFIG } from "../constants/oauth.js";
+import { getServerCredentials } from "../config/index.js";
+import { generatePKCE } from "../utils/pkce.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+
+/**
+ * Qwen OAuth Service
+ * Uses Device Code Flow with PKCE
+ */
+export class QwenService {
+  constructor() {
+    this.config = QWEN_CONFIG;
+  }
+
+  /**
+   * Request device code
+   */
+  async requestDeviceCode(codeChallenge) {
+    const response = await fetch(this.config.deviceCodeUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        client_id: this.config.clientId,
+        scope: this.config.scope,
+        code_challenge: codeChallenge,
+        code_challenge_method: this.config.codeChallengeMethod,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Device code request failed: ${error}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Poll for token
+   */
+  async pollForToken(deviceCode, codeVerifier, interval = 5) {
+    const maxAttempts = 60; // 5 minutes
+    const pollInterval = interval * 1000;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      await new Promise((r) => setTimeout(r, pollInterval));
+
+      const response = await fetch(this.config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          client_id: this.config.clientId,
+          device_code: deviceCode,
+          code_verifier: codeVerifier,
+        }),
+      });
+
+      if (response.ok) {
+        return await response.json();
+      }
+
+      const error = await response.json();
+
+      if (error.error === "authorization_pending") {
+        continue;
+      } else if (error.error === "slow_down") {
+        await new Promise((r) => setTimeout(r, 5000));
+        continue;
+      } else if (error.error === "expired_token") {
+        throw new Error("Device code expired");
+      } else if (error.error === "access_denied") {
+        throw new Error("Access denied");
+      } else {
+        throw new Error(error.error_description || error.error);
+      }
+    }
+
+    throw new Error("Authorization timeout");
+  }
+
+  /**
+   * Save Qwen tokens to server
+   */
+  async saveTokens(tokens) {
+    const { server, token, userId } = getServerCredentials();
+
+    const response = await fetch(`${server}/api/cli/providers/qwen`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        "X-User-Id": userId,
+      },
+      body: JSON.stringify({
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+        resourceUrl: tokens.resource_url,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error || "Failed to save tokens");
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Complete Qwen OAuth flow
+   */
+  async connect() {
+    const spinner = createSpinner("Starting Qwen OAuth...").start();
+
+    try {
+      spinner.text = "Generating PKCE...";
+
+      // Generate PKCE
+      const { codeVerifier, codeChallenge } = generatePKCE();
+
+      spinner.text = "Requesting device code...";
+
+      // Request device code
+      const deviceData = await this.requestDeviceCode(codeChallenge);
+
+      spinner.stop();
+
+      console.log("\n📋 Please visit the following URL and enter the code:\n");
+      console.log(`   ${deviceData.verification_uri}\n`);
+      console.log(`   Code: ${deviceData.user_code}\n`);
+
+      // Open browser
+      if (deviceData.verification_uri_complete) {
+        await open(deviceData.verification_uri_complete);
+      } else {
+        await open(deviceData.verification_uri);
+      }
+
+      spinner.start("Waiting for authorization...");
+
+      // Poll for token
+      const tokens = await this.pollForToken(
+        deviceData.device_code,
+        codeVerifier,
+        deviceData.interval || 5
+      );
+
+      spinner.text = "Saving tokens to server...";
+
+      // Save tokens to server
+      await this.saveTokens(tokens);
+
+      spinner.succeed("Qwen connected successfully!");
+      return true;
+    } catch (error) {
+      spinner.fail(`Failed: ${error.message}`);
+      throw error;
+    }
+  }
+}
+
diff --git a/src/lib/oauth/services/xai.js b/src/lib/oauth/services/xai.js
new file mode 100644
index 0000000..95c5185
--- /dev/null
+++ b/src/lib/oauth/services/xai.js
@@ -0,0 +1,238 @@
+import open from "open";
+import { OAuthService } from "./oauth.js";
+import crypto from "crypto";
+import { XAI_CONFIG, XAI_PKCE_VERIFIER_BYTES } from "../constants/xai.js";
+import { startLocalServer } from "../utils/server.js";
+import { generateCodeVerifier, generateCodeChallenge, generateState } from "../utils/pkce.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+
+/**
+ * xAI (Grok) OAuth Service
+ *
+ * Source of truth: router-for-me/CLIProxyAPI internal/auth/xai/xai.go
+ *
+ * Flow:
+ *  1. Discover endpoints from `${XAI_ISSUER}/.well-known/openid-configuration`
+ *  2. Bind loopback server on 127.0.0.1:56121, path /callback
+ *  3. PKCE S256 with 96-byte verifier
+ *  4. Exchange code with form-urlencoded body
+ *  5. id_token email decode (no signature verify, mirrors Go)
+ */
+
+const BASE64_BLOCK_SIZE = 4;
+
+let cachedDiscovery = null;
+
+export function validateOAuthEndpoint(rawUrl, field) {
+  const value = String(rawUrl || "").trim();
+  if (!value) throw new Error(`xai discovery ${field} is empty`);
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch (err) {
+    throw new Error(`xai discovery ${field} is invalid: ${err.message}`);
+  }
+
+  if (parsed.protocol !== "https:") {
+    throw new Error(`xai discovery ${field} must use https: ${value}`);
+  }
+
+  const host = parsed.hostname.toLowerCase().trim();
+  if (host !== "x.ai" && !host.endsWith(".x.ai")) {
+    throw new Error(`xai discovery ${field} host ${host} is not on x.ai`);
+  }
+
+  return value;
+}
+
+/**
+ * Discover authorization + token endpoints. Cached process-wide.
+ */
+export async function discoverEndpoints() {
+  if (cachedDiscovery) return cachedDiscovery;
+
+  try {
+    const res = await fetch(XAI_CONFIG.discoveryUrl, {
+      headers: { Accept: "application/json" },
+    });
+    if (res.ok) {
+      const data = await res.json();
+      cachedDiscovery = {
+        authorizeUrl: validateOAuthEndpoint(data.authorization_endpoint, "authorization_endpoint"),
+        tokenUrl: validateOAuthEndpoint(data.token_endpoint, "token_endpoint"),
+      };
+      return cachedDiscovery;
+    }
+  } catch {
+    // fall through to static fallback
+  }
+
+  cachedDiscovery = {
+    authorizeUrl: XAI_CONFIG.authorizeUrl,
+    tokenUrl: XAI_CONFIG.tokenUrl,
+  };
+  return cachedDiscovery;
+}
+
+/**
+ * Decode the `email` claim from an id_token JWT. No signature verification —
+ * mirrors CLIProxyAPI Go behavior. Returns undefined if not parseable.
+ */
+export function decodeIdTokenEmail(idToken) {
+  if (!idToken || typeof idToken !== "string") return undefined;
+  const parts = idToken.split(".");
+  if (parts.length !== 3) return undefined;
+  try {
+    const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padding = (BASE64_BLOCK_SIZE - (base64.length % BASE64_BLOCK_SIZE)) % BASE64_BLOCK_SIZE;
+    const json = Buffer.from(base64 + "=".repeat(padding), "base64").toString("utf8");
+    const payload = JSON.parse(json);
+    return payload.email || payload.preferred_username || payload.sub || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export class XaiService extends OAuthService {
+  constructor() {
+    super(XAI_CONFIG);
+  }
+
+  /**
+   * Build xAI authorization URL. Spaces in scope are encoded as %20.
+   */
+  buildXaiAuthUrl(redirectUri, state, codeChallenge, authorizeUrl) {
+    const nonce = crypto.randomBytes(16).toString("hex");
+    const params = {
+      response_type: "code",
+      client_id: XAI_CONFIG.clientId,
+      redirect_uri: redirectUri,
+      scope: XAI_CONFIG.scope,
+      code_challenge: codeChallenge,
+      code_challenge_method: XAI_CONFIG.codeChallengeMethod,
+      state,
+      nonce,
+      plan: "generic",
+      referrer: "cli-proxy-api",
+    };
+    const qs = Object.entries(params)
+      .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+      .join("&");
+    return `${authorizeUrl}?${qs}`;
+  }
+
+  /**
+   * Exchange authorization code for tokens.
+   * xAI is a public PKCE client — no client_secret.
+   */
+  async exchangeXaiCode({ tokenUrl, code, redirectUri, codeVerifier }) {
+    const res = await fetch(tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: XAI_CONFIG.clientId,
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier,
+      }),
+    });
+
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`xAI token exchange failed: ${err}`);
+    }
+    return await res.json();
+  }
+
+  /**
+   * Refresh an access token using a refresh_token.
+   */
+  async refreshAccessToken(refreshToken) {
+    const { tokenUrl } = await discoverEndpoints();
+    const res = await fetch(tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: XAI_CONFIG.clientId,
+        refresh_token: refreshToken,
+      }),
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`xAI token refresh failed: ${err}`);
+    }
+    return await res.json();
+  }
+
+  /**
+   * Complete xAI OAuth flow end-to-end (CLI entrypoint).
+   * Returns the raw token response plus extracted email.
+   */
+  async connect() {
+    const spinner = createSpinner("Starting xAI OAuth...").start();
+    try {
+      spinner.text = "Discovering xAI endpoints...";
+      const { authorizeUrl, tokenUrl } = await discoverEndpoints();
+
+      spinner.text = `Starting local server on port ${XAI_CONFIG.loopbackPort}...`;
+      let callbackParams = null;
+      const { port, close } = await startLocalServer((params) => {
+        callbackParams = params;
+      }, XAI_CONFIG.loopbackPort);
+      const redirectUri = `http://127.0.0.1:${port}${XAI_CONFIG.callbackPath}`;
+      spinner.succeed(`Local server started on port ${port}`);
+
+      const codeVerifier = generateCodeVerifier(XAI_PKCE_VERIFIER_BYTES);
+      const codeChallenge = generateCodeChallenge(codeVerifier);
+      const state = generateState();
+      const authUrl = this.buildXaiAuthUrl(redirectUri, state, codeChallenge, authorizeUrl);
+
+      console.log("\nOpening browser for xAI authentication...");
+      console.log(`If browser doesn't open, visit:\n${authUrl}\n`);
+      await open(authUrl);
+
+      spinner.start("Waiting for xAI authorization...");
+      await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error("Authentication timeout (5 minutes)")), 300000);
+        const iv = setInterval(() => {
+          if (callbackParams) {
+            clearInterval(iv);
+            clearTimeout(timeout);
+            resolve();
+          }
+        }, 100);
+      });
+      close();
+
+      if (callbackParams.error) {
+        throw new Error(callbackParams.error_description || callbackParams.error);
+      }
+      if (!callbackParams.code) throw new Error("No authorization code received");
+      if (callbackParams.state !== state) throw new Error("Invalid state parameter");
+
+      spinner.start("Exchanging code for tokens...");
+      const tokens = await this.exchangeXaiCode({
+        tokenUrl,
+        code: callbackParams.code,
+        redirectUri,
+        codeVerifier,
+      });
+
+      const email = decodeIdTokenEmail(tokens.id_token);
+      spinner.succeed("xAI connected successfully!");
+      return { tokens, email };
+    } catch (error) {
+      spinner.fail(`Failed: ${error.message}`);
+      throw error;
+    }
+  }
+}
diff --git a/src/lib/oauth/utils/banner.js b/src/lib/oauth/utils/banner.js
new file mode 100644
index 0000000..a5743e2
--- /dev/null
+++ b/src/lib/oauth/utils/banner.js
@@ -0,0 +1,63 @@
+import figlet from "figlet";
+import gradient from "gradient-string";
+import chalkAnimation from "chalk-animation";
+
+/**
+ * Display banner
+ */
+export function showBanner() {
+  const banner = figlet.textSync("LLM Proxy", {
+    font: "ANSI Shadow",
+    horizontalLayout: "default",
+    verticalLayout: "default",
+  });
+
+  console.log("\n" + gradient.pastel.multiline(banner));
+  console.log(gradient.cristal("  🚀 OAuth CLI for AI Providers\n"));
+}
+
+/**
+ * Display simple banner (no animation)
+ */
+export function showSimpleBanner() {
+  const banner = figlet.textSync("EP CLI", {
+    font: "Standard",
+    horizontalLayout: "default",
+  });
+  console.log(gradient.pastel.multiline(banner));
+  console.log(gradient.cristal("  OAuth CLI for AI Providers\n"));
+}
+
+/**
+ * Display success animation
+ */
+export async function showSuccess(message) {
+  return new Promise((resolve) => {
+    const animation = chalkAnimation.rainbow(`\n✨ ${message}\n`);
+    setTimeout(() => {
+      animation.stop();
+      resolve();
+    }, 1000);
+  });
+}
+
+/**
+ * Display loading animation
+ */
+export function showLoading(text) {
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let i = 0;
+  
+  const interval = setInterval(() => {
+    process.stdout.write(`\r${frames[i]} ${text}`);
+    i = (i + 1) % frames.length;
+  }, 80);
+
+  return {
+    stop: () => {
+      clearInterval(interval);
+      process.stdout.write("\r");
+    },
+  };
+}
+
diff --git a/src/lib/oauth/utils/pkce.js b/src/lib/oauth/utils/pkce.js
new file mode 100644
index 0000000..ec65165
--- /dev/null
+++ b/src/lib/oauth/utils/pkce.js
@@ -0,0 +1,39 @@
+import crypto from "crypto";
+
+/**
+ * Generate PKCE code verifier (43-128 characters)
+ *
+ * @param {number} [bytes=32] number of random bytes (xAI uses 96)
+ */
+export function generateCodeVerifier(bytes = 32) {
+  return crypto.randomBytes(bytes).toString("base64url");
+}
+
+/**
+ * Generate PKCE code challenge from verifier (S256 method)
+ */
+export function generateCodeChallenge(verifier) {
+  return crypto.createHash("sha256").update(verifier).digest("base64url");
+}
+
+/**
+ * Generate random state for CSRF protection
+ */
+export function generateState() {
+  return crypto.randomBytes(32).toString("base64url");
+}
+
+/**
+ * Generate complete PKCE pair
+ */
+export function generatePKCE(bytes = 32) {
+  const codeVerifier = generateCodeVerifier(bytes);
+  const codeChallenge = generateCodeChallenge(codeVerifier);
+  const state = generateState();
+
+  return {
+    codeVerifier,
+    codeChallenge,
+    state,
+  };
+}
diff --git a/src/lib/oauth/utils/server.js b/src/lib/oauth/utils/server.js
new file mode 100644
index 0000000..b11a9a4
--- /dev/null
+++ b/src/lib/oauth/utils/server.js
@@ -0,0 +1,426 @@
+import http from "http";
+import { URL } from "url";
+import { CODEX_CONFIG } from "../constants/oauth.js";
+
+/**
+ * Start a local HTTP server to receive OAuth callback
+ * @param {Function} onCallback - Called with query params when callback received
+ * @param {number} fixedPort - Optional fixed port number (default: random)
+ * @returns {Promise<{server: http.Server, port: number, close: Function}>}
+ */
+export function startLocalServer(onCallback, fixedPort = null) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost`);
+
+      if (url.pathname === "/callback" || url.pathname === "/auth/callback") {
+        const params = Object.fromEntries(url.searchParams);
+
+        // Send success response to browser with auto-close attempt
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(`<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Authentication Successful</title>
+  <style>
+    body { font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #f5f5f5; }
+    .container { text-align: center; padding: 2rem; background: white; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); }
+    .success { color: #22c55e; font-size: 3rem; }
+    h1 { margin: 1rem 0; }
+    p { color: #666; }
+    #countdown { font-weight: bold; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="success">&#10003;</div>
+    <h1>Authentication Successful</h1>
+    <p id="message">Closing in <span id="countdown">3</span> seconds...</p>
+  </div>
+  <script>
+    let count = 3;
+    const countdown = document.getElementById("countdown");
+    const message = document.getElementById("message");
+    const timer = setInterval(() => {
+      count--;
+      countdown.textContent = count;
+      if (count <= 0) {
+        clearInterval(timer);
+        window.close();
+        setTimeout(() => {
+          message.textContent = "Please close this tab manually.";
+        }, 500);
+      }
+    }, 1000);
+  </script>
+</body>
+</html>`);
+
+        // Call callback with params
+        onCallback(params);
+      } else {
+        res.writeHead(404);
+        res.end("Not found");
+      }
+    });
+
+    // Listen on fixed port or find available port
+    const portToUse = fixedPort || 0;
+    server.listen(portToUse, "127.0.0.1", () => {
+      const { port } = server.address();
+      resolve({
+        server,
+        port,
+        close: () => server.close(),
+      });
+    });
+
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE" && fixedPort) {
+        reject(new Error(`Port ${fixedPort} is already in use. Please close other applications using this port.`));
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+
+/**
+ * Wait for callback with timeout
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @returns {Promise<Object>} - Callback params
+ */
+export function waitForCallback(timeoutMs = 300000) {
+  return new Promise((resolve, reject) => {
+    let resolved = false;
+
+    const timeout = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        reject(new Error("Authentication timeout"));
+      }
+    }, timeoutMs);
+
+    const onCallback = (params) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        resolve(params);
+      }
+    };
+
+    // Return the callback function
+    resolve.__onCallback = onCallback;
+  });
+}
+
+// Singleton proxy server for Codex OAuth callback on fixed port
+let codexProxyServer = null;
+let codexProxyTimeout = null;
+
+const CODEX_PROXY_TIMEOUT_MS = 300000; // 5 minutes
+const CODEX_PORT = CODEX_CONFIG.fixedPort;
+
+// Pending exchange sessions keyed by state — used by server-side exchange mode
+const pendingExchanges = new Map();
+
+/**
+ * Register a pending exchange session for server-side mode.
+ * Modal client calls this before opening popup.
+ */
+export function registerCodexSession({ state, codeVerifier, redirectUri }) {
+  if (!state || !codeVerifier || !redirectUri) return false;
+  pendingExchanges.set(state, {
+    codeVerifier,
+    redirectUri,
+    status: "pending",
+    createdAt: Date.now(),
+  });
+  return true;
+}
+
+/**
+ * Read session status (modal polls this).
+ */
+export function getCodexSessionStatus(state) {
+  return pendingExchanges.get(state) || null;
+}
+
+/**
+ * Clear a session (called after modal consumes status).
+ */
+export function clearCodexSession(state) {
+  pendingExchanges.delete(state);
+}
+
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function renderCodexResultPage(success, message) {
+  const color = success ? "#22c55e" : "#ef4444";
+  const icon = success ? "&#10003;" : "&#10007;";
+  const title = success ? "Authentication Successful" : "Authentication Failed";
+  const safeMessage = escapeHtml(message);
+  return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>${title}</title>
+<style>body{font-family:system-ui;display:flex;justify-content:center;align-items:center;height:100vh;margin:0;background:#f5f5f5}.c{text-align:center;padding:2rem;background:#fff;border-radius:8px;box-shadow:0 2px 10px rgba(0,0,0,.1)}.i{color:${color};font-size:3rem}h1{margin:1rem 0}p{color:#666}</style>
+</head><body><div class="c"><div class="i">${icon}</div><h1>${title}</h1><p>${safeMessage}</p><p>Closing in <span id="cd">3</span>s...</p>
+<script>let n=3;const c=document.getElementById("cd");const t=setInterval(()=>{n--;c.textContent=n;if(n<=0){clearInterval(t);window.close();}},1000);</script>
+</div></body></html>`;
+}
+
+/**
+ * Start Codex proxy on fixed port 1455.
+ * Mode A (server-side): if any session was registered, proxy auto-exchanges + saves DB.
+ * Mode B (channel fallback): if no session, proxy 302 redirects to app port for legacy channel-based flow.
+ */
+export function startCodexProxy(appPort) {
+  return new Promise((resolve) => {
+    if (codexProxyServer) {
+      resolve({ success: true });
+      return;
+    }
+
+    const server = http.createServer(async (req, res) => {
+      const url = new URL(req.url, "http://localhost");
+
+      if (url.pathname !== "/callback" && url.pathname !== "/auth/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      const errorParam = url.searchParams.get("error");
+      const session = state ? pendingExchanges.get(state) : null;
+
+      // Mode A: server-side exchange (session registered)
+      if (session) {
+        try {
+          if (errorParam) {
+            throw new Error(url.searchParams.get("error_description") || errorParam);
+          }
+          if (!code) throw new Error("No authorization code received");
+
+          // Lazy import to avoid circular deps
+          const { exchangeTokens } = await import("../providers.js");
+          const { createProviderConnection } = await import("@/models");
+
+          const tokenData = await exchangeTokens(
+            "codex",
+            code,
+            session.redirectUri,
+            session.codeVerifier,
+            state
+          );
+          const connection = await createProviderConnection({
+            provider: "codex",
+            authType: "oauth",
+            ...tokenData,
+            expiresAt: tokenData.expiresIn
+              ? new Date(Date.now() + tokenData.expiresIn * 1000).toISOString()
+              : null,
+            testStatus: "active",
+          });
+
+          session.status = "done";
+          session.connectionId = connection.id;
+          session.email = connection.email;
+
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(renderCodexResultPage(true, "You can close this window."));
+        } catch (err) {
+          session.status = "error";
+          session.error = err.message;
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(renderCodexResultPage(false, err.message));
+        } finally {
+          stopCodexProxy();
+        }
+        return;
+      }
+
+      // Mode B: legacy channel fallback — 302 redirect to app /callback
+      const redirectUrl = `http://localhost:${appPort}/callback${url.search}`;
+      res.writeHead(302, { Location: redirectUrl });
+      res.end();
+      stopCodexProxy();
+    });
+
+    server.listen(CODEX_PORT, "127.0.0.1", () => {
+      codexProxyServer = server;
+      codexProxyTimeout = setTimeout(() => stopCodexProxy(), CODEX_PROXY_TIMEOUT_MS);
+      resolve({ success: true });
+    });
+
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        resolve({ success: false, reason: "port_busy" });
+      } else {
+        resolve({ success: false, reason: err.message });
+      }
+    });
+  });
+}
+
+/**
+ * Stop the Codex proxy server and cleanup
+ */
+export function stopCodexProxy() {
+  if (codexProxyTimeout) {
+    clearTimeout(codexProxyTimeout);
+    codexProxyTimeout = null;
+  }
+  if (codexProxyServer) {
+    codexProxyServer.close();
+    codexProxyServer = null;
+  }
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// xAI fixed-port proxy on 127.0.0.1:56121
+// Same shape as the Codex proxy. Kept as a parallel implementation rather than
+// generalizing the Codex one to keep the codex hot-path byte-equivalent.
+// ───────────────────────────────────────────────────────────────────────────
+
+let xaiProxyServer = null;
+let xaiProxyTimeout = null;
+const XAI_PROXY_TIMEOUT_MS = 300000; // 5 minutes
+const XAI_PROXY_PORT = 56121;
+const xaiPendingExchanges = new Map();
+
+export function registerXaiSession({ state, codeVerifier, redirectUri }) {
+  if (!state || !codeVerifier || !redirectUri) return false;
+  xaiPendingExchanges.set(state, {
+    codeVerifier,
+    redirectUri,
+    status: "pending",
+    createdAt: Date.now(),
+  });
+  return true;
+}
+
+export function getXaiSessionStatus(state) {
+  return xaiPendingExchanges.get(state) || null;
+}
+
+export function clearXaiSession(state) {
+  xaiPendingExchanges.delete(state);
+}
+
+function renderXaiResultPage(success, message) {
+  return renderCodexResultPage(success, message);
+}
+
+/**
+ * Start xAI proxy on fixed port 56121.
+ * Mode A (server-side): if any session was registered, proxy auto-exchanges + saves DB.
+ * Mode B (channel fallback): if no session, proxy 302 redirects to app port.
+ */
+export function startXaiProxy(appPort) {
+  return new Promise((resolve) => {
+    if (xaiProxyServer) {
+      resolve({ success: true });
+      return;
+    }
+
+    const server = http.createServer(async (req, res) => {
+      const url = new URL(req.url, "http://localhost");
+      if (url.pathname !== "/callback" && url.pathname !== "/auth/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      const errorParam = url.searchParams.get("error");
+      const session = state ? xaiPendingExchanges.get(state) : null;
+
+      // Mode A: server-side exchange
+      if (session) {
+        try {
+          if (errorParam) {
+            throw new Error(url.searchParams.get("error_description") || errorParam);
+          }
+          if (!code) throw new Error("No authorization code received");
+
+          const { exchangeTokens } = await import("../providers.js");
+          const { createProviderConnection } = await import("@/models");
+
+          const tokenData = await exchangeTokens(
+            "xai",
+            code,
+            session.redirectUri,
+            session.codeVerifier,
+            state
+          );
+          const connection = await createProviderConnection({
+            provider: "xai",
+            authType: "oauth",
+            ...tokenData,
+            expiresAt: tokenData.expiresIn
+              ? new Date(Date.now() + tokenData.expiresIn * 1000).toISOString()
+              : null,
+            testStatus: "active",
+          });
+
+          session.status = "done";
+          session.connectionId = connection.id;
+          session.email = connection.email;
+
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(renderXaiResultPage(true, "You can close this window."));
+        } catch (err) {
+          session.status = "error";
+          session.error = err.message;
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(renderXaiResultPage(false, err.message));
+        } finally {
+          stopXaiProxy();
+        }
+        return;
+      }
+
+      // Mode B: legacy fallback redirect
+      const redirectUrl = `http://localhost:${appPort}/callback${url.search}`;
+      res.writeHead(302, { Location: redirectUrl });
+      res.end();
+      stopXaiProxy();
+    });
+
+    server.listen(XAI_PROXY_PORT, "127.0.0.1", () => {
+      xaiProxyServer = server;
+      xaiProxyTimeout = setTimeout(() => stopXaiProxy(), XAI_PROXY_TIMEOUT_MS);
+      resolve({ success: true });
+    });
+
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        resolve({ success: false, reason: "port_busy" });
+      } else {
+        resolve({ success: false, reason: err.message });
+      }
+    });
+  });
+}
+
+export function stopXaiProxy() {
+  if (xaiProxyTimeout) {
+    clearTimeout(xaiProxyTimeout);
+    xaiProxyTimeout = null;
+  }
+  if (xaiProxyServer) {
+    xaiProxyServer.close();
+    xaiProxyServer = null;
+  }
+}
+
diff --git a/src/lib/oauth/utils/ui.js b/src/lib/oauth/utils/ui.js
new file mode 100644
index 0000000..a81ff48
--- /dev/null
+++ b/src/lib/oauth/utils/ui.js
@@ -0,0 +1,48 @@
+import chalk from "chalk";
+import ora from "ora";
+
+/**
+ * UI Helper Functions
+ */
+
+export function success(message) {
+  console.log(chalk.green(`\n✓ ${message}\n`));
+}
+
+export function error(message) {
+  console.log(chalk.red(`\n✗ ${message}\n`));
+}
+
+export function info(message) {
+  console.log(chalk.blue(`\n${message}\n`));
+}
+
+export function warn(message) {
+  console.log(chalk.yellow(`\n⚠ ${message}\n`));
+}
+
+export function gray(message) {
+  console.log(chalk.gray(message));
+}
+
+export function spinner(text) {
+  return ora(text);
+}
+
+export function printSection(title) {
+  console.log(chalk.blue(`\n${title}\n`));
+}
+
+export function printKeyValue(key, value, isSuccess = false) {
+  const color = isSuccess ? chalk.green : chalk.gray;
+  console.log(color(`  ${key}: ${value}`));
+}
+
+export function printList(items, isSuccess = false) {
+  const symbol = isSuccess ? "✓" : "✗";
+  const color = isSuccess ? chalk.green : chalk.gray;
+  items.forEach((item) => {
+    console.log(color(`  ${symbol} ${item}`));
+  });
+}
+
diff --git a/src/lib/providerNormalization.js b/src/lib/providerNormalization.js
new file mode 100644
index 0000000..8eb2a7e
--- /dev/null
+++ b/src/lib/providerNormalization.js
@@ -0,0 +1,45 @@
+import { AI_PROVIDERS } from "../shared/constants/providers.js";
+
+/**
+ * Detect xAI Grok models by id pattern (grok-*, Grok_*, etc).
+ * @param {string} modelId
+ * @returns {boolean}
+ */
+export function isXaiModel(modelId) {
+  return typeof modelId === "string" && /^grok[-_]/i.test(modelId.trim());
+}
+
+export function normalizeProviderId(provider) {
+  if (typeof provider !== "string") return provider;
+
+  const trimmed = provider.trim();
+  if (AI_PROVIDERS[trimmed]) return trimmed;
+
+  const slug = trimmed.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  if (AI_PROVIDERS[slug]) return slug;
+
+  const providerByName = Object.values(AI_PROVIDERS).find(
+    (entry) => entry.name?.toLowerCase() === trimmed.toLowerCase()
+  );
+  return providerByName?.id || trimmed;
+}
+
+export function normalizeProviderSpecificData(provider, body = {}, providerSpecificData = null) {
+  const next = providerSpecificData && typeof providerSpecificData === "object"
+    ? { ...providerSpecificData }
+    : {};
+
+  if (provider === "ollama-local") {
+    const baseUrl = (
+      next.baseUrl ||
+      body.baseUrl ||
+      body.baseURL ||
+      body.ollamaHostUrl ||
+      ""
+    ).trim();
+
+    if (baseUrl) next.baseUrl = baseUrl;
+  }
+
+  return Object.keys(next).length > 0 ? next : null;
+}
diff --git a/src/lib/pxpipe/events.js b/src/lib/pxpipe/events.js
new file mode 100644
index 0000000..b1bb880
--- /dev/null
+++ b/src/lib/pxpipe/events.js
@@ -0,0 +1,125 @@
+import fs from "fs";
+import path from "path";
+import { PXPIPE_DIR } from "./install.js";
+
+const EVENTS_FILE = path.join(PXPIPE_DIR, "events.jsonl");
+const ROTATED_FILE = path.join(PXPIPE_DIR, "events.jsonl.1");
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function ensureDir() {
+  if (!fs.existsSync(PXPIPE_DIR)) fs.mkdirSync(PXPIPE_DIR, { recursive: true });
+}
+
+// Fire-and-forget: stats must never break the request path.
+export function appendPxpipeEvent(event) {
+  try {
+    ensureDir();
+    try {
+      const stat = fs.statSync(EVENTS_FILE);
+      if (stat.size > MAX_FILE_BYTES) fs.renameSync(EVENTS_FILE, ROTATED_FILE);
+    } catch { /* no file yet */ }
+    fs.appendFile(EVENTS_FILE, JSON.stringify({ ts: Date.now(), ...event }) + "\n", () => {});
+  } catch { /* ignore */ }
+}
+
+export function readPxpipeEvents({ sinceMs = null, limit = null } = {}) {
+  const events = [];
+  for (const file of [ROTATED_FILE, EVENTS_FILE]) {
+    try {
+      if (!fs.existsSync(file)) continue;
+      for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+        if (!line) continue;
+        try {
+          const ev = JSON.parse(line);
+          if (sinceMs && ev.ts < sinceMs) continue;
+          events.push(ev);
+        } catch { /* skip corrupt line */ }
+      }
+    } catch { /* ignore */ }
+  }
+  events.sort((a, b) => a.ts - b.ts);
+  return limit ? events.slice(-limit) : events;
+}
+
+function emptyTotals() {
+  return {
+    requests: 0, compressed: 0, bypassed: 0, errors: 0,
+    tokensBeforeEst: 0, tokensAfterEst: 0, tokensSavedEst: 0, savedPct: 0,
+    imagesGenerated: 0, compressionTimeMs: 0, avgCompressionMs: 0,
+  };
+}
+
+function accumulate(totals, ev) {
+  totals.requests++;
+  if (ev.applied) {
+    totals.compressed++;
+    totals.tokensBeforeEst += ev.tokensBeforeEst || 0;
+    totals.tokensAfterEst += ev.tokensAfterEst || 0;
+    totals.tokensSavedEst += ev.tokensSavedEst || 0;
+    totals.imagesGenerated += ev.imageCount || 0;
+    totals.compressionTimeMs += ev.durationMs || 0;
+  } else if (ev.reason === "transform_error" || ev.reason === "timeout") {
+    totals.errors++;
+  } else {
+    totals.bypassed++;
+  }
+}
+
+function finalize(totals) {
+  totals.savedPct = totals.tokensBeforeEst > 0
+    ? +((totals.tokensSavedEst / totals.tokensBeforeEst) * 100).toFixed(2)
+    : 0;
+  totals.avgCompressionMs = totals.compressed > 0
+    ? Math.round(totals.compressionTimeMs / totals.compressed)
+    : 0;
+  return totals;
+}
+
+// Aggregated stats for the dashboard: all-time + windowed totals, a daily
+// tokens-saved timeline (last `timelineDays`), and the most recent events.
+export function getPxpipeStats({ timelineDays = 30, recentLimit = 100 } = {}) {
+  const events = readPxpipeEvents();
+  const now = Date.now();
+  const startOfToday = new Date(new Date(now).setHours(0, 0, 0, 0)).getTime();
+
+  const windows = {
+    all: emptyTotals(),
+    today: emptyTotals(),
+    yesterday: emptyTotals(),
+    last7d: emptyTotals(),
+    last30d: emptyTotals(),
+  };
+
+  const timeline = new Map();
+  for (let i = timelineDays - 1; i >= 0; i--) {
+    const day = new Date(startOfToday - i * DAY_MS);
+    timeline.set(day.toISOString().slice(0, 10), { date: day.toISOString().slice(0, 10), tokensSavedEst: 0, compressed: 0, requests: 0 });
+  }
+
+  for (const ev of events) {
+    accumulate(windows.all, ev);
+    if (ev.ts >= startOfToday) accumulate(windows.today, ev);
+    else if (ev.ts >= startOfToday - DAY_MS) accumulate(windows.yesterday, ev);
+    if (ev.ts >= now - 7 * DAY_MS) accumulate(windows.last7d, ev);
+    if (ev.ts >= now - 30 * DAY_MS) accumulate(windows.last30d, ev);
+
+    const key = new Date(ev.ts).toISOString().slice(0, 10);
+    const bucket = timeline.get(key);
+    if (bucket) {
+      bucket.requests++;
+      if (ev.applied) {
+        bucket.compressed++;
+        bucket.tokensSavedEst += ev.tokensSavedEst || 0;
+      }
+    }
+  }
+
+  for (const w of Object.values(windows)) finalize(w);
+
+  return {
+    windows,
+    timeline: [...timeline.values()],
+    recent: events.slice(-recentLimit).reverse(),
+  };
+}
diff --git a/src/lib/pxpipe/install.js b/src/lib/pxpipe/install.js
new file mode 100644
index 0000000..cdf5a8c
--- /dev/null
+++ b/src/lib/pxpipe/install.js
@@ -0,0 +1,123 @@
+import fs from "fs";
+import path from "path";
+import { spawn, execSync } from "child_process";
+import { DATA_DIR } from "@/lib/dataDir.js";
+
+export const PXPIPE_DIR = path.join(DATA_DIR, "pxpipe");
+export const PXPIPE_PACKAGE = "pxpipe-proxy";
+const INSTALL_LOG = path.join(PXPIPE_DIR, "install.log");
+const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
+
+const IS_WIN = process.platform === "win32";
+const NPM_CMD = IS_WIN ? "npm.cmd" : "npm";
+
+// Same PATH extension trick as headroom/detect.js: packaged/launchd environments
+// often miss the Node bin dirs.
+const EXTRA_BINS = IS_WIN
+  ? [`${process.env.ProgramFiles || ""}\\nodejs`, `${process.env.APPDATA || ""}\\npm`]
+  : ["/usr/local/bin", "/opt/homebrew/bin", `${process.env.HOME || ""}/.local/bin`, "/usr/bin", "/bin"];
+const EXTENDED_PATH = [...EXTRA_BINS, process.env.PATH || ""].filter(Boolean).join(path.delimiter);
+
+let installInFlight = null;
+
+function ensureDir() {
+  if (!fs.existsSync(PXPIPE_DIR)) fs.mkdirSync(PXPIPE_DIR, { recursive: true });
+}
+
+export function packageRoot() {
+  return path.join(PXPIPE_DIR, "node_modules", PXPIPE_PACKAGE);
+}
+
+export function libraryEntry() {
+  return path.join(packageRoot(), "dist", "core", "library.js");
+}
+
+export function findNpm() {
+  try {
+    const out = execSync(`${IS_WIN ? "where" : "which"} npm`, {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    }).toString().trim();
+    return out ? out.split(/\r?\n/)[0].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+// { installed, version, path } — installed means the library entry exists on disk.
+export function getInstallInfo() {
+  try {
+    const pkgJson = path.join(packageRoot(), "package.json");
+    if (!fs.existsSync(pkgJson) || !fs.existsSync(libraryEntry())) {
+      return { installed: false, version: null, path: null };
+    }
+    const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf8"));
+    return { installed: true, version: pkg.version || null, path: packageRoot() };
+  } catch {
+    return { installed: false, version: null, path: null };
+  }
+}
+
+export function isInstalling() {
+  return installInFlight !== null;
+}
+
+// Install (or repair by reinstalling) pxpipe-proxy into DATA_DIR/pxpipe.
+// Serialized: concurrent calls await the same run.
+export function installPxpipe() {
+  if (installInFlight) return installInFlight;
+  installInFlight = runInstall().finally(() => { installInFlight = null; });
+  return installInFlight;
+}
+
+async function runInstall() {
+  const npm = findNpm();
+  if (!npm) {
+    const err = new Error("npm not found on PATH — Node.js/npm is required to install PXPIPE");
+    err.code = "NPM_NOT_FOUND";
+    throw err;
+  }
+
+  ensureDir();
+  const pkgJson = path.join(PXPIPE_DIR, "package.json");
+  if (!fs.existsSync(pkgJson)) {
+    fs.writeFileSync(pkgJson, JSON.stringify({ name: "9router-pxpipe-host", private: true }, null, 2));
+  }
+
+  const outFd = fs.openSync(INSTALL_LOG, "a");
+  fs.writeSync(outFd, `\n[${new Date().toISOString()}] npm install ${PXPIPE_PACKAGE}@latest\n`);
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(npm, ["install", `${PXPIPE_PACKAGE}@latest`, "--no-audit", "--no-fund", "--omit=dev"], {
+      cwd: PXPIPE_DIR,
+      stdio: ["ignore", outFd, outFd],
+      windowsHide: true,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error("npm install timed out after 5 minutes — see install.log"));
+    }, INSTALL_TIMEOUT_MS);
+    child.once("error", (e) => { clearTimeout(timer); reject(e); });
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve();
+      else reject(new Error(`npm install exited with code ${code} — see install.log`));
+    });
+  }).finally(() => fs.closeSync(outFd));
+
+  const info = getInstallInfo();
+  if (!info.installed) throw new Error("install finished but package is missing — see install.log");
+  return info;
+}
+
+export function getInstallLogTail(maxLines = 200) {
+  try {
+    if (!fs.existsSync(INSTALL_LOG)) return "";
+    const lines = fs.readFileSync(INSTALL_LOG, "utf8").split(/\r?\n/).filter(Boolean);
+    return lines.slice(-maxLines).join("\n");
+  } catch {
+    return "";
+  }
+}
diff --git a/src/lib/pxpipe/loader.js b/src/lib/pxpipe/loader.js
new file mode 100644
index 0000000..fbd418f
--- /dev/null
+++ b/src/lib/pxpipe/loader.js
@@ -0,0 +1,70 @@
+import { pathToFileURL } from "url";
+import { getInstallInfo, libraryEntry } from "./install.js";
+
+// Module cache: pxpipe is loaded once per process ("started") and dropped on
+// "stop". In library mode start/stop govern the in-process module, not a daemon.
+let cached = null; // { module, version, loadedAt }
+let loadPromise = null;
+
+export function getLoadedInfo() {
+  return cached ? { loaded: true, version: cached.version, loadedAt: cached.loadedAt } : { loaded: false };
+}
+
+export async function loadPxpipe() {
+  if (cached) return cached;
+  if (loadPromise) return loadPromise;
+  loadPromise = doLoad().finally(() => { loadPromise = null; });
+  return loadPromise;
+}
+
+async function doLoad() {
+  const info = getInstallInfo();
+  if (!info.installed) {
+    const err = new Error("PXPIPE is not installed");
+    err.code = "NOT_INSTALLED";
+    throw err;
+  }
+  // Cache-bust per version so Repair/upgrade takes effect without a server restart.
+  const url = `${pathToFileURL(libraryEntry()).href}?v=${encodeURIComponent(info.version || "0")}`;
+  const mod = await import(/* webpackIgnore: true */ url);
+  if (typeof mod.transformAnthropicMessages !== "function") {
+    throw new Error("installed pxpipe package does not export transformAnthropicMessages");
+  }
+  cached = { module: mod, version: info.version, loadedAt: Date.now() };
+  return cached;
+}
+
+export function unloadPxpipe() {
+  const wasLoaded = !!cached;
+  cached = null;
+  return wasLoaded;
+}
+
+// Transform function for the request pipeline; null when unavailable (fail-open).
+// autoLoad controls whether a cold cache triggers a load (first request warms it).
+export async function getTransform({ autoLoad = true } = {}) {
+  try {
+    if (!cached && !autoLoad) return null;
+    const { module: mod } = await loadPxpipe();
+    return mod.transformAnthropicMessages;
+  } catch {
+    return null;
+  }
+}
+
+// Health self-test: run a tiny synthetic Claude request through the transformer.
+// A healthy module parses it and answers with a machine-readable reason.
+export async function selfTest() {
+  const startedAt = Date.now();
+  const { module: mod } = await loadPxpipe();
+  const body = new TextEncoder().encode(JSON.stringify({
+    model: "claude-fable-5",
+    max_tokens: 16,
+    messages: [{ role: "user", content: "ping" }],
+  }));
+  const result = await mod.transformAnthropicMessages({ body, model: "claude-fable-5" });
+  if (!result || typeof result.applied !== "boolean" || !(result.body instanceof Uint8Array)) {
+    throw new Error("transform returned an unexpected shape");
+  }
+  return { ok: true, reason: result.reason, durationMs: Date.now() - startedAt };
+}
diff --git a/src/lib/pxpipe/service.js b/src/lib/pxpipe/service.js
new file mode 100644
index 0000000..d117c82
--- /dev/null
+++ b/src/lib/pxpipe/service.js
@@ -0,0 +1,49 @@
+import { getInstallInfo, isInstalling, findNpm } from "./install.js";
+import { getLoadedInfo, loadPxpipe, selfTest } from "./loader.js";
+
+// Aggregate status for the Token Saver card and /api/pxpipe/status.
+// "running" in library mode = module loaded into this process.
+export function getPxpipeStatus() {
+  const install = getInstallInfo();
+  const loaded = getLoadedInfo();
+  return {
+    installed: install.installed,
+    installing: isInstalling(),
+    version: install.version,
+    path: install.path,
+    running: loaded.loaded,
+    loadedAt: loaded.loadedAt || null,
+    uptimeMs: loaded.loaded ? Date.now() - loaded.loadedAt : 0,
+    npmAvailable: !!findNpm(),
+    mode: "library", // in-process transform, not an external proxy
+  };
+}
+
+// PRD health checklist, adapted to library mode: installed? → module loads
+// (the "executable found / port listening" equivalent) → test request transforms.
+export async function runHealthCheck() {
+  const checks = [];
+  const fail = (error) => ({ healthy: false, checks, error });
+
+  const install = getInstallInfo();
+  checks.push({ id: "installed", label: "PXPIPE installed", ok: install.installed, detail: install.version ? `v${install.version}` : null });
+  if (!install.installed) return fail("pxpipe not installed");
+
+  try {
+    await loadPxpipe();
+    checks.push({ id: "module", label: "Transform module loads", ok: true, detail: `v${install.version}` });
+  } catch (e) {
+    checks.push({ id: "module", label: "Transform module loads", ok: false, detail: e.message });
+    return fail(`Cannot load module: ${e.message}`);
+  }
+
+  try {
+    const test = await selfTest();
+    checks.push({ id: "transform", label: "Test request transforms", ok: true, detail: `${test.durationMs}ms (${test.reason})` });
+  } catch (e) {
+    checks.push({ id: "transform", label: "Test request transforms", ok: false, detail: e.message });
+    return fail(`Self-test failed: ${e.message}`);
+  }
+
+  return { healthy: true, checks, error: null };
+}
diff --git a/src/lib/qoder/constants.js b/src/lib/qoder/constants.js
new file mode 100644
index 0000000..bd1fc98
--- /dev/null
+++ b/src/lib/qoder/constants.js
@@ -0,0 +1,2 @@
+// Re-export: qoder constants moved to open-sse/shared/qoder (open-sse self-contained, docs 00 §1b).
+export * from "../../../open-sse/shared/qoder/constants.js";
diff --git a/src/lib/qoder/cosy.js b/src/lib/qoder/cosy.js
new file mode 100644
index 0000000..02b9c33
--- /dev/null
+++ b/src/lib/qoder/cosy.js
@@ -0,0 +1,2 @@
+// Re-export: qoder cosy helpers moved to open-sse/shared/qoder (docs 00 §1b).
+export * from "../../../open-sse/shared/qoder/cosy.js";
diff --git a/src/lib/qoder/encoding.js b/src/lib/qoder/encoding.js
new file mode 100644
index 0000000..a96fb9a
--- /dev/null
+++ b/src/lib/qoder/encoding.js
@@ -0,0 +1,2 @@
+// Re-export: qoder encoding moved to open-sse/shared/qoder (docs 00 §1b).
+export * from "../../../open-sse/shared/qoder/encoding.js";
diff --git a/src/lib/requestDetailsDb.js b/src/lib/requestDetailsDb.js
new file mode 100644
index 0000000..0daaa8a
--- /dev/null
+++ b/src/lib/requestDetailsDb.js
@@ -0,0 +1,4 @@
+// Shim → re-export from new SQLite-based DB layer (src/lib/db/)
+export {
+  saveRequestDetail, getRequestDetails, getRequestDetailById, getDistinctProviders,
+} from "@/lib/db/index.js";
diff --git a/src/lib/tunnel/cloudflare/cloudflared.js b/src/lib/tunnel/cloudflare/cloudflared.js
new file mode 100644
index 0000000..38e4bf7
--- /dev/null
+++ b/src/lib/tunnel/cloudflare/cloudflared.js
@@ -0,0 +1,449 @@
+import fs from "fs";
+import path from "path";
+import https from "https";
+import os from "os";
+import { execSync, spawn } from "child_process";
+import { savePid, loadPid, clearPid } from "./pid.js";
+import { DATA_DIR } from "@/lib/dataDir.js";
+
+const BIN_DIR = path.join(DATA_DIR, "bin");
+const BINARY_NAME = "cloudflared";
+const IS_WINDOWS = os.platform() === "win32";
+const BIN_NAME = IS_WINDOWS ? `${BINARY_NAME}.exe` : BINARY_NAME;
+const BIN_PATH = path.join(BIN_DIR, BIN_NAME);
+const POWERSHELL_HIDDEN_COMMAND = "powershell -NoProfile -NonInteractive -WindowStyle Hidden -Command";
+const DEFAULT_QUICK_TUNNEL_PROTOCOL = "http2";
+const QUICK_TUNNEL_PROTOCOLS = new Set(["http2", "quic", "auto"]);
+
+const GITHUB_BASE_URL = "https://github.com/cloudflare/cloudflared/releases/latest/download";
+
+const PLATFORM_MAPPINGS = {
+  darwin: {
+    x64: "cloudflared-darwin-amd64.tgz",
+    arm64: "cloudflared-darwin-arm64.tgz"
+  },
+  win32: {
+    x64: "cloudflared-windows-amd64.exe",
+    ia32: "cloudflared-windows-386.exe",
+    arm64: "cloudflared-windows-386.exe"
+  },
+  linux: {
+    x64: "cloudflared-linux-amd64",
+    arm64: "cloudflared-linux-arm64"
+  }
+};
+
+// Fallback order: prefer smallest/most-compatible binary per platform
+const PLATFORM_FALLBACK = {
+  darwin: "cloudflared-darwin-amd64.tgz",
+  win32: "cloudflared-windows-386.exe",
+  linux: "cloudflared-linux-amd64"
+};
+
+function getDownloadUrl() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const platformMapping = PLATFORM_MAPPINGS[platform];
+  if (!platformMapping) {
+    throw new Error(`Unsupported platform: ${platform}`);
+  }
+
+  const binaryName = platformMapping[arch] || PLATFORM_FALLBACK[platform];
+  return `${GITHUB_BASE_URL}/${binaryName}`;
+}
+
+// Download state — shared so status API can read it
+const dlState = { downloading: false, progress: 0 };
+
+export function getDownloadStatus() {
+  return { downloading: dlState.downloading, progress: dlState.progress };
+}
+
+function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+
+    https.get(url, (response) => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+        file.close();
+        fs.unlinkSync(dest);
+        downloadFile(response.headers.location, dest).then(resolve).catch(reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        file.close();
+        fs.unlinkSync(dest);
+        reject(new Error(`Download failed with status ${response.statusCode}`));
+        return;
+      }
+
+      const totalBytes = parseInt(response.headers["content-length"], 10) || 0;
+      let receivedBytes = 0;
+      dlState.downloading = true;
+      dlState.progress = 0;
+
+      response.on("data", (chunk) => {
+        receivedBytes += chunk.length;
+        if (totalBytes > 0) dlState.progress = Math.round((receivedBytes / totalBytes) * 100);
+      });
+
+      response.pipe(file);
+
+      file.on("finish", () => {
+        dlState.downloading = false;
+        dlState.progress = 100;
+        file.close(() => resolve(dest));
+      });
+
+      file.on("error", (err) => {
+        dlState.downloading = false;
+        dlState.progress = 0;
+        file.close();
+        fs.unlinkSync(dest);
+        reject(err);
+      });
+    }).on("error", (err) => {
+      dlState.downloading = false;
+      dlState.progress = 0;
+      file.close();
+      if (fs.existsSync(dest)) fs.unlinkSync(dest);
+      reject(err);
+    });
+  });
+}
+
+const MIN_BINARY_SIZE = 1024 * 1024; // 1MB - cloudflared is ~30MB+
+
+// Validate binary is executable on current platform and not truncated
+function isValidBinary(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.size < MIN_BINARY_SIZE) return false;
+    const fd = fs.openSync(filePath, "r");
+    const buf = Buffer.alloc(4);
+    fs.readSync(fd, buf, 0, 4, 0);
+    fs.closeSync(fd);
+    const magic = buf.toString("hex");
+    if (IS_WINDOWS) return magic.startsWith("4d5a"); // PE (MZ)
+    if (os.platform() === "darwin") return magic.startsWith("cffaedfe") || magic.startsWith("cefaedfe");
+    return magic.startsWith("7f454c46"); // ELF (Linux)
+  } catch {
+    return false;
+  }
+}
+
+let downloadPromise = null;
+
+export async function ensureCloudflared() {
+  if (downloadPromise) return downloadPromise;
+  downloadPromise = _ensureCloudflared().finally(() => { downloadPromise = null; });
+  return downloadPromise;
+}
+
+async function _ensureCloudflared() {
+  if (!fs.existsSync(BIN_DIR)) {
+    fs.mkdirSync(BIN_DIR, { recursive: true });
+  }
+
+  // Clean up incomplete downloads from previous runs
+  const tmpPath = `${BIN_PATH}.tmp`;
+  if (fs.existsSync(tmpPath)) {
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+  }
+
+  if (fs.existsSync(BIN_PATH)) {
+    if (!isValidBinary(BIN_PATH)) {
+      console.log("[cloudflared] Invalid binary detected, re-downloading...");
+      fs.unlinkSync(BIN_PATH);
+    } else {
+      if (!IS_WINDOWS) fs.chmodSync(BIN_PATH, "755");
+      return BIN_PATH;
+    }
+  }
+
+  const url = getDownloadUrl();
+  const isArchive = url.endsWith(".tgz");
+  const downloadDest = isArchive ? path.join(BIN_DIR, "cloudflared.tgz.tmp") : tmpPath;
+
+  await downloadFile(url, downloadDest);
+
+  if (isArchive) {
+    execSync(`tar -xzf "${downloadDest}" -C "${BIN_DIR}"`, { stdio: "pipe", windowsHide: true });
+    fs.unlinkSync(downloadDest);
+  } else {
+    fs.renameSync(downloadDest, BIN_PATH);
+  }
+
+  if (!IS_WINDOWS) {
+    fs.chmodSync(BIN_PATH, "755");
+  }
+
+  return BIN_PATH;
+}
+
+let cloudflaredProcess = null;
+let unexpectedExitHandler = null;
+let intentionalKill = false; // suppress unexpected-exit callback during deliberate kill
+
+/** Register a callback to be called when cloudflared exits unexpectedly after connecting */
+export function setUnexpectedExitHandler(handler) {
+  unexpectedExitHandler = handler;
+}
+
+export async function spawnCloudflared(tunnelToken) {
+  const binaryPath = await ensureCloudflared();
+
+  const child = spawn(binaryPath, ["tunnel", "run", "--dns-resolver-addrs", "1.1.1.1:53", "--token", tunnelToken], {
+    detached: false,
+    windowsHide: true,
+    cwd: os.tmpdir(),
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+
+  cloudflaredProcess = child;
+  savePid(child.pid);
+
+  return new Promise((resolve, reject) => {
+    let connectionCount = 0;
+    let resolved = false;
+    const timeout = setTimeout(() => {
+      resolved = true;
+      resolve(child);
+    }, 90000);
+
+    const handleLog = (data) => {
+      const msg = data.toString();
+      // Count exact occurrences in this chunk (each chunk may contain multiple lines)
+      const matches = msg.match(/Registered tunnel connection/g);
+      if (matches) {
+        connectionCount += matches.length;
+        if (connectionCount >= 4 && !resolved) {
+          resolved = true;
+          clearTimeout(timeout);
+          resolve(child);
+        }
+      }
+    };
+
+    child.stdout.on("data", handleLog);
+    child.stderr.on("data", handleLog);
+
+    child.on("error", (err) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        reject(err);
+      }
+    });
+
+    child.on("exit", (code, signal) => {
+      cloudflaredProcess = null;
+      clearPid();
+      const wasConnected = resolved; // true = already connected successfully
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        // Collect stderr output for better error diagnosis
+        let stderrOutput = "";
+        if (child.stderr && !child.stderr.destroyed) {
+          // Try to read any buffered stderr (may not have all output but helps with common errors)
+          stderrOutput = " Check cloudflared logs for details.";
+        }
+        if (code === 1) {
+          // Common exit code 1 issues: invalid token, auth failure, network issues
+          reject(new Error(`cloudflared exited with code ${code}${stderrOutput} Ensure your tunnel token is valid and network is reachable.`));
+        } else if (code === 2) {
+          reject(new Error(`cloudflared exited with code ${code}${stderrOutput} Check if required arguments are correct.`));
+        } else {
+          reject(new Error(`cloudflared exited with code ${code}${stderrOutput}`));
+        }
+        return;
+      }
+      // Watchdog (initializeApp) handles recovery — no auto-reconnect here
+      if (intentionalKill) { intentionalKill = false; return; }
+      if (wasConnected && unexpectedExitHandler) unexpectedExitHandler();
+    });
+  });
+}
+
+/**
+ * Spawn cloudflared quick tunnel (no account needed)
+ * Returns the generated trycloudflare.com URL
+ */
+export async function spawnQuickTunnel(localPort, onUrlUpdate) {
+  const binaryPath = await ensureCloudflared();
+
+  const configDir = fs.mkdtempSync(path.join(os.tmpdir(), "cloudflared-quick-"));
+  const configPath = path.join(configDir, "config.yml");
+  // Avoid using default ~/.cloudflared/config.yml, which can conflict with quick tunnel behavior.
+  fs.writeFileSync(configPath, "# quick-tunnel config placeholder\n", "utf8");
+
+  let isCleaned = false;
+  const cleanup = () => {
+    if (isCleaned) return;
+    isCleaned = true;
+    try {
+      fs.rmSync(configDir, { recursive: true, force: true });
+    } catch (e) { /* ignore */ }
+  };
+
+  const requestedProtocol = String(process.env.TUNNEL_TRANSPORT_PROTOCOL || process.env.CLOUDFLARED_PROTOCOL || DEFAULT_QUICK_TUNNEL_PROTOCOL).trim().toLowerCase();
+  const tunnelProtocol = QUICK_TUNNEL_PROTOCOLS.has(requestedProtocol) ? requestedProtocol : DEFAULT_QUICK_TUNNEL_PROTOCOL;
+  const child = spawn(binaryPath, ["tunnel", "--url", `http://127.0.0.1:${localPort}`, "--config", configPath, "--no-autoupdate", "--retries", "99"], {
+    detached: false,
+    windowsHide: true,
+    cwd: os.tmpdir(),
+    env: {
+      ...process.env,
+      TUNNEL_TRANSPORT_PROTOCOL: tunnelProtocol,
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  cloudflaredProcess = child;
+  savePid(child.pid);
+
+  return new Promise((resolve, reject) => {
+    let resolved = false;
+    // Keep a small tail of raw cloudflared logs to surface real failure causes
+    let logTail = "";
+
+    function getQuickTunnelUrlFromLog(message) {
+      // cloudflared logs may contain "api.trycloudflare.com" as well,
+      // but that is NOT the quick-tunnel endpoint we need.
+      const regex = /https:\/\/([a-z0-9-]+)\.trycloudflare\.com/gi;
+      const candidates = [];
+
+      for (const match of message.matchAll(regex)) {
+        const host = match[1];
+        if (host === "api") continue;
+        candidates.push(`https://${host}.trycloudflare.com`);
+      }
+
+      if (!candidates.length) return null;
+      return candidates[candidates.length - 1];
+    }
+
+    const timeout = setTimeout(() => {
+      if (resolved) return;
+      resolved = true;
+      cleanup();
+      reject(new Error(`Quick tunnel timed out. Last log: ${logTail.slice(-800) || "(empty)"}`));
+    }, 90000);
+
+    let lastUrl = null;
+
+    const handleLog = (data) => {
+      const msg = data.toString();
+      logTail = (logTail + msg).slice(-4000);
+      const tunnelUrl = getQuickTunnelUrlFromLog(msg);
+      if (!tunnelUrl) return;
+
+      if (!resolved) {
+        // First URL — resolve the promise, do NOT call onUrlUpdate (caller handles initial register)
+        resolved = true;
+        lastUrl = tunnelUrl;
+        clearTimeout(timeout);
+        cleanup();
+        console.log(`[Tunnel] cloudflared URL: ${tunnelUrl}`);
+        resolve({ child, tunnelUrl });
+        return;
+      }
+
+      // URL changed after initial connect — notify caller to re-register
+      if (tunnelUrl !== lastUrl) {
+        console.log(`[Tunnel] cloudflared URL changed: ${tunnelUrl}`);
+        lastUrl = tunnelUrl;
+        if (onUrlUpdate) onUrlUpdate(tunnelUrl);
+      }
+    };
+
+    child.stdout.on("data", handleLog);
+    child.stderr.on("data", handleLog);
+
+    child.on("error", (err) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timeout);
+      cleanup();
+      reject(err);
+    });
+
+    child.on("exit", (code, signal) => {
+      cloudflaredProcess = null;
+      clearPid();
+      // Deliberate kill (restart/disable) — exit silently, no error noise
+      if (intentionalKill) {
+        intentionalKill = false;
+        clearTimeout(timeout);
+        cleanup();
+        if (!resolved) { resolved = true; reject(new Error("cloudflared killed")); }
+        return;
+      }
+      console.log(`[Tunnel] cloudflared exit code=${code} signal=${signal}`);
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        cleanup();
+        const tail = logTail.slice(-600).trim() || "(empty)";
+        if (code === 1) {
+          reject(new Error(`cloudflared quick tunnel exited (code 1). Common causes: (1) outbound port 7844 (TCP/UDP) blocked, (2) TryCloudflare service issue, (3) cannot reach 127.0.0.1:${localPort}, (4) protocol (http2/quic) blocked by network. Last log: ${tail}`));
+        } else if (code === 2) {
+          reject(new Error(`cloudflared exited (code 2). Bad arguments. Last log: ${tail}`));
+        } else {
+          reject(new Error(`cloudflared exited (code ${code}). Last log: ${tail}`));
+        }
+        return;
+      }
+      if (unexpectedExitHandler) unexpectedExitHandler();
+      cleanup();
+    });
+  });
+}
+
+// Kill cloudflared processes whose command line targets the given port (any host).
+// Boundary check ensures :20128 doesn't match :201280 or :202128.
+function killCloudflaredByPort(port) {
+  if (!port) return;
+  try {
+    if (IS_WINDOWS) {
+      const psCmd = `Get-CimInstance Win32_Process -Filter \\"Name='cloudflared.exe'\\" | Where-Object { $_.CommandLine -match ':${port}(\\D|$)' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }`;
+      execSync(`${POWERSHELL_HIDDEN_COMMAND} "${psCmd}"`, { stdio: "ignore", windowsHide: true });
+    } else {
+      execSync(`pkill -f "cloudflared.*:${port}([^0-9]|$)" 2>/dev/null || true`, { stdio: "ignore", windowsHide: true });
+    }
+  } catch (e) { /* ignore */ }
+}
+
+export function killCloudflared(localPort) {
+  intentionalKill = true;
+  if (cloudflaredProcess) {
+    try {
+      cloudflaredProcess.kill();
+    } catch (e) { /* ignore */ }
+    cloudflaredProcess = null;
+  }
+
+  const pid = loadPid();
+  if (pid) {
+    try {
+      process.kill(pid);
+    } catch (e) { /* ignore */ }
+    clearPid();
+  }
+
+  killCloudflaredByPort(localPort);
+}
+
+export function isCloudflaredRunning() {
+  const pid = loadPid();
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
diff --git a/src/lib/tunnel/cloudflare/config.js b/src/lib/tunnel/cloudflare/config.js
new file mode 100644
index 0000000..2cc3f9d
--- /dev/null
+++ b/src/lib/tunnel/cloudflare/config.js
@@ -0,0 +1,9 @@
+// Cloudflare quick tunnel: DNS propagates fast, short timeouts OK
+export const HEALTH_CHECK = {
+  intervalMs: 2000,
+  timeoutMs: 60000,
+  fetchTimeoutMs: 5000,
+  dnsTimeoutMs: 2000,
+};
+
+export const WORKER_URL = process.env.TUNNEL_WORKER_URL || "https://abc-tunnel.us";
diff --git a/src/lib/tunnel/cloudflare/healthCheck.js b/src/lib/tunnel/cloudflare/healthCheck.js
new file mode 100644
index 0000000..428b351
--- /dev/null
+++ b/src/lib/tunnel/cloudflare/healthCheck.js
@@ -0,0 +1,29 @@
+import { resolveDns } from "../shared/dnsResolver.js";
+import { HEALTH_CHECK } from "./config.js";
+
+export async function probeUrlAlive(url) {
+  if (!url) return false;
+  let hostname;
+  try { hostname = new URL(url).hostname; } catch { return false; }
+
+  if (!await resolveDns(hostname, HEALTH_CHECK.dnsTimeoutMs)) return false;
+
+  try {
+    const res = await fetch(`${url}/api/health`, {
+      signal: AbortSignal.timeout(HEALTH_CHECK.fetchTimeoutMs),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function waitForHealth(url, cancelToken = { cancelled: false }) {
+  const start = Date.now();
+  while (Date.now() - start < HEALTH_CHECK.timeoutMs) {
+    if (cancelToken.cancelled) throw new Error("cancelled");
+    if (await probeUrlAlive(url)) return true;
+    await new Promise((r) => setTimeout(r, HEALTH_CHECK.intervalMs));
+  }
+  throw new Error(`Health check timeout after ${HEALTH_CHECK.timeoutMs}ms`);
+}
diff --git a/src/lib/tunnel/cloudflare/manager.js b/src/lib/tunnel/cloudflare/manager.js
new file mode 100644
index 0000000..e15b47b
--- /dev/null
+++ b/src/lib/tunnel/cloudflare/manager.js
@@ -0,0 +1,151 @@
+import { loadState, saveState, generateShortId } from "../shared/state.js";
+import { spawnQuickTunnel, killCloudflared, isCloudflaredRunning, setUnexpectedExitHandler } from "./cloudflared.js";
+import { clearPid } from "./pid.js";
+import { waitForHealth, probeUrlAlive } from "./healthCheck.js";
+import { WORKER_URL } from "./config.js";
+import { getSettings, updateSettings } from "@/lib/localDb";
+
+const svc = {
+  cancelToken: { cancelled: false },
+  spawnInProgress: false,
+  lastRestartAt: 0,
+  activeLocalPort: null,
+};
+
+export function getTunnelService() { return svc; }
+export function isTunnelManuallyDisabled() { return svc.cancelToken.cancelled; }
+export function isTunnelReconnecting() { return svc.spawnInProgress; }
+
+let onUnexpectedExit = null;
+export function setTunnelUnexpectedExitCallback(cb) { onUnexpectedExit = cb; }
+
+async function registerTunnelUrl(shortId, tunnelUrl) {
+  await fetch(`${WORKER_URL}/api/tunnel/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ shortId, tunnelUrl })
+  });
+}
+
+function throwIfCancelled(token) {
+  if (token.cancelled) throw new Error("tunnel cancelled");
+}
+
+export async function enableTunnel(localPort = 20128) {
+  console.log(`[Tunnel] enable start (port=${localPort})`);
+  svc.cancelToken = { cancelled: false };
+  svc.activeLocalPort = localPort;
+  svc.spawnInProgress = true;
+  const token = svc.cancelToken;
+
+  try {
+    if (isCloudflaredRunning()) {
+      const existing = loadState();
+      if (existing?.tunnelUrl && existing?.shortId) {
+        const publicUrl = `https://r${existing.shortId}.abc-tunnel.us`;
+        // Reuse only if BOTH direct + public URL alive (avoid stale socket after network change)
+        const [directOk, publicOk] = await Promise.all([
+          probeUrlAlive(existing.tunnelUrl),
+          probeUrlAlive(publicUrl),
+        ]);
+        if (directOk && publicOk) {
+          console.log(`[Tunnel] already running, reuse: ${existing.tunnelUrl}`);
+          return { success: true, tunnelUrl: existing.tunnelUrl, shortId: existing.shortId, publicUrl, alreadyRunning: true };
+        }
+        console.log(`[Tunnel] stale (direct=${directOk} public=${publicOk}), respawn`);
+      }
+    }
+
+    killCloudflared(localPort);
+    console.log("[Tunnel] killed existing cloudflared");
+    throwIfCancelled(token);
+
+    const existing = loadState();
+    const shortId = existing?.shortId || generateShortId();
+
+    const onUrlUpdate = async (url) => {
+      if (token.cancelled) return;
+      console.log(`[Tunnel] url updated: ${url}`);
+      await registerTunnelUrl(shortId, url);
+      saveState({ shortId, tunnelUrl: url });
+      await updateSettings({ tunnelEnabled: true, tunnelUrl: url });
+    };
+
+    // Register exit handler BEFORE spawn so it fires even on early exit
+    setUnexpectedExitHandler(() => {
+      console.warn("[Tunnel] cloudflared exited unexpectedly, scheduling respawn");
+      if (onUnexpectedExit) onUnexpectedExit();
+    });
+
+    const { tunnelUrl } = await spawnQuickTunnel(localPort, onUrlUpdate);
+    console.log(`[Tunnel] spawned: ${tunnelUrl}`);
+    throwIfCancelled(token);
+
+    const publicUrl = `https://r${shortId}.abc-tunnel.us`;
+    await registerTunnelUrl(shortId, tunnelUrl);
+    saveState({ shortId, tunnelUrl });
+    await updateSettings({ tunnelEnabled: true, tunnelUrl });
+    console.log(`[Tunnel] registered shortId=${shortId} publicUrl=${publicUrl}`);
+
+    // Verify publicUrl first (worker route is reliable; direct *.trycloudflare.com DNS may lag)
+    await waitForHealth(publicUrl, token);
+    console.log("[Tunnel] public URL healthy");
+    // Direct tunnel probe is best-effort: DNS for *.trycloudflare.com can be slow/blocked
+    if (!(await probeUrlAlive(tunnelUrl))) {
+      console.warn("[Tunnel] direct URL not reachable yet, continuing via publicUrl");
+    } else {
+      console.log("[Tunnel] direct URL healthy");
+    }
+
+    console.log("[Tunnel] enable success");
+    return { success: true, tunnelUrl, shortId, publicUrl };
+  } catch (e) {
+    // Suppress noise when spawn was deliberately killed (restart/disable superseded it)
+    if (!/cloudflared killed|tunnel cancelled/.test(e.message)) {
+      console.error(`[Tunnel] enable error: ${e.message}`);
+    }
+    throw e;
+  } finally {
+    svc.spawnInProgress = false;
+  }
+}
+
+export async function disableTunnel() {
+  console.log("[Tunnel] disable");
+  // Abort any in-flight enable so it cannot resurrect state after we clear it
+  svc.cancelToken.cancelled = true;
+  setUnexpectedExitHandler(null);
+
+  try { killCloudflared(svc.activeLocalPort); } catch (e) { console.warn(`[Tunnel] kill warn: ${e.message}`); }
+  clearPid();
+
+  const state = loadState();
+  if (state) saveState({ shortId: state.shortId, tunnelUrl: null });
+
+  await updateSettings({ tunnelEnabled: false, tunnelUrl: "" });
+  // Force-clear flags so a subsequent enable is not blocked by a stuck spawnInProgress
+  svc.spawnInProgress = false;
+  svc.activeLocalPort = null;
+  return { success: true };
+}
+
+export async function getTunnelStatus() {
+  const settings = await getSettings();
+  const settingsEnabled = settings.tunnelEnabled === true;
+  const state = loadState();
+  const shortId = state?.shortId || "";
+  const publicUrl = shortId ? `https://r${shortId}.abc-tunnel.us` : "";
+  const tunnelUrl = state?.tunnelUrl || "";
+
+  // Lazy: skip PID probe entirely when user disabled tunnel
+  const running = settingsEnabled ? isCloudflaredRunning() : false;
+
+  return {
+    enabled: settingsEnabled && running,
+    settingsEnabled,
+    tunnelUrl,
+    shortId,
+    publicUrl,
+    running
+  };
+}
diff --git a/src/lib/tunnel/cloudflare/pid.js b/src/lib/tunnel/cloudflare/pid.js
new file mode 100644
index 0000000..919837c
--- /dev/null
+++ b/src/lib/tunnel/cloudflare/pid.js
@@ -0,0 +1,23 @@
+import fs from "fs";
+import path from "path";
+import { TUNNEL_DIR, ensureTunnelDir } from "../shared/state.js";
+
+const PID_FILE = path.join(TUNNEL_DIR, "cloudflared.pid");
+
+export function savePid(pid) {
+  ensureTunnelDir();
+  fs.writeFileSync(PID_FILE, pid.toString());
+}
+
+export function loadPid() {
+  try {
+    if (fs.existsSync(PID_FILE)) return parseInt(fs.readFileSync(PID_FILE, "utf8"));
+  } catch { /* ignore */ }
+  return null;
+}
+
+export function clearPid() {
+  try {
+    if (fs.existsSync(PID_FILE)) fs.unlinkSync(PID_FILE);
+  } catch { /* ignore */ }
+}
diff --git a/src/lib/tunnel/index.js b/src/lib/tunnel/index.js
new file mode 100644
index 0000000..3ffab37
--- /dev/null
+++ b/src/lib/tunnel/index.js
@@ -0,0 +1,53 @@
+// Cloudflare service
+export {
+  enableTunnel,
+  disableTunnel,
+  getTunnelStatus,
+  isTunnelManuallyDisabled,
+  isTunnelReconnecting,
+  getTunnelService,
+  setTunnelUnexpectedExitCallback,
+} from "./cloudflare/manager.js";
+export {
+  killCloudflared,
+  isCloudflaredRunning,
+  ensureCloudflared,
+  getDownloadStatus,
+} from "./cloudflare/cloudflared.js";
+export { probeUrlAlive as probeCloudflareAlive } from "./cloudflare/healthCheck.js";
+
+// Tailscale service
+export {
+  enableTailscale,
+  disableTailscale,
+  getTailscaleStatus,
+  isTailscaleReconnecting,
+  getTailscaleService,
+} from "./tailscale/manager.js";
+export {
+  isTailscaleInstalled,
+  isTailscaleRunning,
+  isTailscaleRunningStrict,
+  isTailscaleLoggedIn,
+  isTailscaleLoggedInStrict,
+  isSystemDaemonRunning,
+  isDaemonAlive,
+  startFunnel,
+  getTailscaleBin,
+  installTailscale,
+  startLogin,
+  startDaemonWithPassword,
+  TAILSCALE_SOCKET,
+} from "./tailscale/tailscale.js";
+export { probeUrlAlive as probeTailscaleAlive } from "./tailscale/healthCheck.js";
+
+// Shared
+export { loadState, generateShortId } from "./shared/state.js";
+export { checkInternet } from "./shared/internetCheck.js";
+export {
+  RESTART_COOLDOWN_MS,
+  NETWORK_SETTLE_MS,
+  WATCHDOG_INTERVAL_MS,
+  NETWORK_CHECK_INTERVAL_MS,
+  VIRTUAL_IFACE_REGEX,
+} from "./shared/watchdogConfig.js";
diff --git a/src/lib/tunnel/shared/dnsResolver.js b/src/lib/tunnel/shared/dnsResolver.js
new file mode 100644
index 0000000..e8fde7d
--- /dev/null
+++ b/src/lib/tunnel/shared/dnsResolver.js
@@ -0,0 +1,17 @@
+import dns from "dns";
+
+// Force public DNS to bypass OS negative cache (mDNSResponder holds NXDOMAIN)
+const resolver = new dns.promises.Resolver();
+resolver.setServers(["1.1.1.1", "1.0.0.1", "8.8.8.8"]);
+
+// Try custom public DNS first, fall back to OS resolver
+// (Cloudflare DNS may not resolve all hostnames, e.g. *.ts.net)
+export async function resolveDns(hostname, timeoutMs) {
+  const tryResolver = (fn) => Promise.race([
+    fn(),
+    new Promise((_, rej) => setTimeout(() => rej(new Error("dns timeout")), timeoutMs)),
+  ]).then(() => true).catch(() => false);
+
+  if (await tryResolver(() => resolver.resolve4(hostname))) return true;
+  return tryResolver(() => dns.promises.resolve4(hostname));
+}
diff --git a/src/lib/tunnel/shared/internetCheck.js b/src/lib/tunnel/shared/internetCheck.js
new file mode 100644
index 0000000..756640d
--- /dev/null
+++ b/src/lib/tunnel/shared/internetCheck.js
@@ -0,0 +1,26 @@
+import net from "net";
+
+const INTERNET_CHECK = {
+  host: "1.1.1.1",
+  port: 443,
+  timeoutMs: 3000,
+};
+
+export function checkInternet() {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      try { socket.destroy(); } catch { /* ignore */ }
+      resolve(ok);
+    };
+    socket.setTimeout(INTERNET_CHECK.timeoutMs);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+    try { socket.connect(INTERNET_CHECK.port, INTERNET_CHECK.host); }
+    catch { finish(false); }
+  });
+}
diff --git a/src/lib/tunnel/shared/state.js b/src/lib/tunnel/shared/state.js
new file mode 100644
index 0000000..6a16181
--- /dev/null
+++ b/src/lib/tunnel/shared/state.js
@@ -0,0 +1,41 @@
+import fs from "fs";
+import path from "path";
+import { DATA_DIR } from "@/lib/dataDir.js";
+
+const TUNNEL_DIR = path.join(DATA_DIR, "tunnel");
+const STATE_FILE = path.join(TUNNEL_DIR, "state.json");
+
+const SHORT_ID_LENGTH = 6;
+const SHORT_ID_CHARS = "abcdefghijklmnpqrstuvwxyz23456789";
+
+export function ensureTunnelDir() {
+  if (!fs.existsSync(TUNNEL_DIR)) fs.mkdirSync(TUNNEL_DIR, { recursive: true });
+}
+
+export function loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) return JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
+  } catch { /* ignore corrupt state */ }
+  return null;
+}
+
+export function saveState(state) {
+  ensureTunnelDir();
+  fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+export function clearState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) fs.unlinkSync(STATE_FILE);
+  } catch { /* ignore */ }
+}
+
+export function generateShortId() {
+  let result = "";
+  for (let i = 0; i < SHORT_ID_LENGTH; i++) {
+    result += SHORT_ID_CHARS.charAt(Math.floor(Math.random() * SHORT_ID_CHARS.length));
+  }
+  return result;
+}
+
+export { TUNNEL_DIR };
diff --git a/src/lib/tunnel/shared/watchdogConfig.js b/src/lib/tunnel/shared/watchdogConfig.js
new file mode 100644
index 0000000..0274997
--- /dev/null
+++ b/src/lib/tunnel/shared/watchdogConfig.js
@@ -0,0 +1,8 @@
+// Watchdog + network monitor timings (shared by both services)
+export const RESTART_COOLDOWN_MS = 120000;
+export const NETWORK_SETTLE_MS = 2500;
+export const WATCHDOG_INTERVAL_MS = 60000;
+export const NETWORK_CHECK_INTERVAL_MS = 5000;
+
+// Skip virtual/transient interfaces (tailscale utun, AirDrop awdl, bridges) that flap and cause false netchange
+export const VIRTUAL_IFACE_REGEX = /^(utun|awdl|llw|anpi|bridge|gif|stf|ipsec|ap|tun|tap|vmnet|veth|docker)/i;
diff --git a/src/lib/tunnel/tailscale/config.js b/src/lib/tunnel/tailscale/config.js
new file mode 100644
index 0000000..3195ad6
--- /dev/null
+++ b/src/lib/tunnel/tailscale/config.js
@@ -0,0 +1,7 @@
+// Tailscale Funnel: cert provisioning + *.ts.net DNS propagation slower → longer timeouts
+export const HEALTH_CHECK = {
+  intervalMs: 2000,
+  timeoutMs: 180000,
+  fetchTimeoutMs: 8000,
+  dnsTimeoutMs: 3000,
+};
diff --git a/src/lib/tunnel/tailscale/healthCheck.js b/src/lib/tunnel/tailscale/healthCheck.js
new file mode 100644
index 0000000..428b351
--- /dev/null
+++ b/src/lib/tunnel/tailscale/healthCheck.js
@@ -0,0 +1,29 @@
+import { resolveDns } from "../shared/dnsResolver.js";
+import { HEALTH_CHECK } from "./config.js";
+
+export async function probeUrlAlive(url) {
+  if (!url) return false;
+  let hostname;
+  try { hostname = new URL(url).hostname; } catch { return false; }
+
+  if (!await resolveDns(hostname, HEALTH_CHECK.dnsTimeoutMs)) return false;
+
+  try {
+    const res = await fetch(`${url}/api/health`, {
+      signal: AbortSignal.timeout(HEALTH_CHECK.fetchTimeoutMs),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function waitForHealth(url, cancelToken = { cancelled: false }) {
+  const start = Date.now();
+  while (Date.now() - start < HEALTH_CHECK.timeoutMs) {
+    if (cancelToken.cancelled) throw new Error("cancelled");
+    if (await probeUrlAlive(url)) return true;
+    await new Promise((r) => setTimeout(r, HEALTH_CHECK.intervalMs));
+  }
+  throw new Error(`Health check timeout after ${HEALTH_CHECK.timeoutMs}ms`);
+}
diff --git a/src/lib/tunnel/tailscale/manager.js b/src/lib/tunnel/tailscale/manager.js
new file mode 100644
index 0000000..7fe40e7
--- /dev/null
+++ b/src/lib/tunnel/tailscale/manager.js
@@ -0,0 +1,129 @@
+import { loadState, generateShortId } from "../shared/state.js";
+import { startFunnel, stopFunnel, isTailscaleRunning, isTailscaleRunningStrict, isTailscaleLoggedIn, isTailscaleLoggedInStrict, startLogin, startDaemonWithPassword, provisionCert } from "./tailscale.js";
+import { waitForHealth } from "./healthCheck.js";
+import { getSettings, updateSettings } from "@/lib/localDb";
+import { getCachedPassword, loadEncryptedPassword, initDbHooks } from "@/mitm/manager";
+
+initDbHooks(getSettings, updateSettings);
+
+const svc = {
+  cancelToken: { cancelled: false },
+  spawnInProgress: false,
+  lastRestartAt: 0,
+  activeLocalPort: null,
+};
+
+export function getTailscaleService() { return svc; }
+export function isTailscaleReconnecting() { return svc.spawnInProgress; }
+
+function throwIfCancelled(token) {
+  if (token.cancelled) throw new Error("tailscale cancelled");
+}
+
+export async function enableTailscale(localPort = 20128) {
+  console.log(`[Tailscale] enable start (port=${localPort})`);
+  svc.cancelToken = { cancelled: false };
+  svc.activeLocalPort = localPort;
+  svc.spawnInProgress = true;
+  const token = svc.cancelToken;
+
+  try {
+    const sudoPass = getCachedPassword() || await loadEncryptedPassword() || "";
+    await startDaemonWithPassword(sudoPass);
+    console.log("[Tailscale] daemon ready");
+    throwIfCancelled(token);
+
+    const existing = loadState();
+    const shortId = existing?.shortId || generateShortId();
+    const tsHostname = shortId;
+
+    const loggedIn = await isTailscaleLoggedInStrict();
+    console.log(`[Tailscale] loggedIn=${loggedIn}`);
+    if (!loggedIn) {
+      const loginResult = await startLogin(tsHostname);
+      if (loginResult.authUrl) {
+        console.log(`[Tailscale] needs login, authUrl=${loginResult.authUrl}`);
+        return { success: false, needsLogin: true, authUrl: loginResult.authUrl };
+      }
+      console.log("[Tailscale] login resolved alreadyLoggedIn");
+    }
+    throwIfCancelled(token);
+
+    stopFunnel();
+    let result;
+    try {
+      console.log("[Tailscale] starting funnel");
+      result = await startFunnel(localPort);
+    } catch (e) {
+      console.error(`[Tailscale] funnel error: ${e.message}`);
+      // Daemon not logged in / not ready → auto-trigger login flow so user stays in-app
+      if (/NoState|unexpected state|not logged in|Logged ?out|NeedsLogin/i.test(e.message || "")) {
+        console.log("[Tailscale] retry via startLogin");
+        const loginResult = await startLogin(tsHostname);
+        if (loginResult.authUrl) return { success: false, needsLogin: true, authUrl: loginResult.authUrl };
+      }
+      throw e;
+    }
+    throwIfCancelled(token);
+
+    if (result.funnelNotEnabled) {
+      console.log(`[Tailscale] funnel not enabled, enableUrl=${result.enableUrl}`);
+      return { success: false, funnelNotEnabled: true, enableUrl: result.enableUrl };
+    }
+
+    // Strict probe: bypass cache so we don't false-negative on first invocation
+    if (!(await isTailscaleLoggedInStrict()) || !(await isTailscaleRunningStrict())) {
+      console.error("[Tailscale] strict probe failed (device removed?)");
+      stopFunnel();
+      return { success: false, error: "Tailscale not connected. Device may have been removed. Please re-login." };
+    }
+
+    await updateSettings({ tailscaleEnabled: true, tailscaleUrl: result.tunnelUrl });
+    console.log(`[Tailscale] funnel up: ${result.tunnelUrl}`);
+
+    // Provision TLS cert so Funnel can serve HTTPS (non-fatal if fails)
+    const hostname = new URL(result.tunnelUrl).hostname;
+    await provisionCert(hostname);
+
+    // Verify funnel serves /api/health — timeout is non-fatal (DNS may still be propagating)
+    let reachableNow = false;
+    try {
+      await waitForHealth(result.tunnelUrl, token);
+      reachableNow = true;
+    } catch (he) {
+      if (!he.message.startsWith("Health check timeout")) throw he;
+      console.warn(`[Tailscale] health check timed out, will retry via watchdog`);
+    }
+    console.log(`[Tailscale] enable success (reachable=${reachableNow})`);
+    return { success: true, tunnelUrl: result.tunnelUrl };
+  } catch (e) {
+    console.error(`[Tailscale] enable error: ${e.message}`);
+    throw e;
+  } finally {
+    svc.spawnInProgress = false;
+  }
+}
+
+export async function disableTailscale() {
+  console.log("[Tailscale] disable");
+  svc.cancelToken.cancelled = true;
+  stopFunnel();
+  await updateSettings({ tailscaleEnabled: false, tailscaleUrl: "" });
+  return { success: true };
+}
+
+export async function getTailscaleStatus() {
+  const settings = await getSettings();
+  const settingsEnabled = settings.tailscaleEnabled === true;
+  const tunnelUrl = settings.tailscaleUrl || "";
+  // Skip probes entirely when disabled; check login before running (device removed = not logged in)
+  const loggedIn = settingsEnabled ? isTailscaleLoggedIn() : false;
+  const running = loggedIn ? isTailscaleRunning() : false;
+  return {
+    enabled: settingsEnabled && running,
+    settingsEnabled,
+    tunnelUrl,
+    running,
+    loggedIn
+  };
+}
diff --git a/src/lib/tunnel/tailscale/tailscale.js b/src/lib/tunnel/tailscale/tailscale.js
new file mode 100644
index 0000000..467ad28
--- /dev/null
+++ b/src/lib/tunnel/tailscale/tailscale.js
@@ -0,0 +1,859 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
+import { execSync, exec, spawn } from "child_process";
+import { promisify } from "util";
+import { execWithPassword } from "@/mitm/dns/dnsConfig";
+import { DATA_DIR } from "@/lib/dataDir.js";
+
+const execAsync = promisify(exec);
+
+const BIN_DIR = path.join(DATA_DIR, "bin");
+const IS_MAC = os.platform() === "darwin";
+const IS_LINUX = os.platform() === "linux";
+const IS_WINDOWS = os.platform() === "win32";
+const TAILSCALE_BIN = path.join(BIN_DIR, IS_WINDOWS ? "tailscale.exe" : "tailscale");
+
+// Custom socket for userspace-networking mode (no root required)
+const TAILSCALE_DIR = path.join(DATA_DIR, "tailscale");
+export const TAILSCALE_SOCKET = path.join(TAILSCALE_DIR, "tailscaled.sock");
+const SOCKET_FLAG = IS_WINDOWS ? [] : ["--socket", TAILSCALE_SOCKET];
+
+// System daemon socket (sudo install: apt/snap/systemd) — read-only status detection
+const SYSTEM_TAILSCALE_SOCKET = IS_WINDOWS ? null : "/var/run/tailscale/tailscaled.sock";
+const SYSTEM_SOCKET_FLAG = SYSTEM_TAILSCALE_SOCKET ? ["--socket", SYSTEM_TAILSCALE_SOCKET] : [];
+
+// Well-known Windows install path
+const WINDOWS_TAILSCALE_BIN = "C:\\Program Files\\Tailscale\\tailscale.exe";
+
+// Common Unix install paths to probe synchronously (system tailscale)
+const UNIX_TAILSCALE_CANDIDATES = [
+  "/usr/local/bin/tailscale",
+  "/opt/homebrew/bin/tailscale",
+  "/usr/sbin/tailscale",   // apt package on Debian/Ubuntu
+  "/usr/bin/tailscale",
+  "/snap/bin/tailscale",   // Snap package
+];
+
+// ─── Cache + background refresh (avoid blocking event loop on dead daemon) ──
+const PROBE_TTL_MS = 10000;
+const PROBE_TIMEOUT_MS = 1500;
+
+const binCache = { value: undefined, fetchedAt: 0, refreshing: false };
+const runningCache = { value: false, fetchedAt: 0, refreshing: false };
+const loggedInCache = { value: false, fetchedAt: 0, refreshing: false };
+const funnelUrlCache = { value: null, port: null, fetchedAt: 0, refreshing: false };
+
+function fallbackBin() {
+  if (fs.existsSync(TAILSCALE_BIN)) return TAILSCALE_BIN;
+  if (IS_WINDOWS && fs.existsSync(WINDOWS_TAILSCALE_BIN)) return WINDOWS_TAILSCALE_BIN;
+  if (!IS_WINDOWS) return UNIX_TAILSCALE_CANDIDATES.find((p) => fs.existsSync(p)) || null;
+  return null;
+}
+
+function bgRefreshBin() {
+  if (binCache.refreshing) return;
+  binCache.refreshing = true;
+  const cmd = IS_WINDOWS ? "where tailscale 2>nul" : "which tailscale 2>/dev/null";
+  execAsync(cmd, { windowsHide: true, timeout: PROBE_TIMEOUT_MS, env: { ...process.env, PATH: EXTENDED_PATH } })
+    .then(({ stdout }) => {
+      const sys = stdout.trim();
+      binCache.value = sys || fallbackBin();
+    })
+    .catch(() => { binCache.value = fallbackBin(); })
+    .finally(() => {
+      binCache.fetchedAt = Date.now();
+      binCache.refreshing = false;
+    });
+}
+
+// Sync getter: returns cached value, triggers background refresh if stale
+export function getTailscaleBin() {
+  if (Date.now() - binCache.fetchedAt > PROBE_TTL_MS) bgRefreshBin();
+  // First call: synchronously probe common install paths (no exec, no event-loop block)
+  if (binCache.value === undefined) {
+    if (fs.existsSync(TAILSCALE_BIN)) binCache.value = TAILSCALE_BIN;
+    else if (IS_WINDOWS && fs.existsSync(WINDOWS_TAILSCALE_BIN)) binCache.value = WINDOWS_TAILSCALE_BIN;
+    else if (!IS_WINDOWS) {
+      const found = UNIX_TAILSCALE_CANDIDATES.find((p) => fs.existsSync(p));
+      binCache.value = found || null;
+    } else binCache.value = null;
+  }
+  return binCache.value;
+}
+
+export function isTailscaleInstalled() {
+  return getTailscaleBin() !== null;
+}
+
+/** Build tailscale CLI args with custom socket (no root needed) */
+function tsArgs(...args) {
+  return [...SOCKET_FLAG, ...args];
+}
+
+// Async strict probe: authoritative, awaitable (never blocks event loop). Updates cache.
+export async function isTailscaleLoggedInStrict() {
+  const bin = getTailscaleBin();
+  if (!bin) return false;
+  try {
+    const { stdout } = await execAsync(`"${bin}" ${SOCKET_FLAG.join(" ")} status --json`, {
+      windowsHide: true,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+      timeout: 5000
+    });
+    const json = JSON.parse(stdout);
+    // BackendState=Running + Self.Online=true → device still exists in tailnet
+    const loggedIn = json.BackendState === "Running" && json.Self?.Online === true;
+    loggedInCache.value = loggedIn;
+    loggedInCache.fetchedAt = Date.now();
+    return loggedIn;
+  } catch {
+    return false;
+  }
+}
+
+function bgRefreshLoggedIn() {
+  if (loggedInCache.refreshing) return;
+  const bin = getTailscaleBin();
+  if (!bin) {
+    loggedInCache.value = false;
+    loggedInCache.fetchedAt = Date.now();
+    return;
+  }
+  loggedInCache.refreshing = true;
+  // Dual-socket aware: probe custom socket first, then system socket
+  probeStatusAsync(bin)
+    .then((json) => {
+      loggedInCache.value = !!json && json.BackendState === "Running" && json.Self?.Online === true;
+    })
+    .catch(() => { loggedInCache.value = false; })
+    .finally(() => {
+      loggedInCache.fetchedAt = Date.now();
+      loggedInCache.refreshing = false;
+    });
+}
+
+// Probe `status --json` over custom then system socket. Resolves parsed JSON or null. Never blocks event loop.
+async function probeStatusAsync(bin) {
+  for (const socketArgs of [SOCKET_FLAG, SYSTEM_SOCKET_FLAG]) {
+    try {
+      const { stdout } = await execAsync(`"${bin}" ${socketArgs.join(" ")} status --json`, {
+        windowsHide: true, env: { ...process.env, PATH: EXTENDED_PATH }, timeout: PROBE_TIMEOUT_MS,
+      });
+      return JSON.parse(stdout);
+    } catch { /* try next socket */ }
+  }
+  return null;
+}
+
+// Sync getter: never blocks; returns last known state, refreshes in background
+export function isTailscaleLoggedIn() {
+  if (Date.now() - loggedInCache.fetchedAt > PROBE_TTL_MS) bgRefreshLoggedIn();
+  return loggedInCache.value;
+}
+
+function bgRefreshRunning() {
+  if (runningCache.refreshing) return;
+  const bin = getTailscaleBin();
+  if (!bin) {
+    runningCache.value = false;
+    runningCache.fetchedAt = Date.now();
+    return;
+  }
+  runningCache.refreshing = true;
+  execAsync(`"${bin}" ${SOCKET_FLAG.join(" ")} funnel status --json`, { windowsHide: true, timeout: PROBE_TIMEOUT_MS })
+    .then(({ stdout }) => {
+      try {
+        const json = JSON.parse(stdout);
+        runningCache.value = Object.keys(json.AllowFunnel || {}).length > 0;
+      } catch { runningCache.value = false; }
+    })
+    .catch(() => { runningCache.value = false; })
+    .finally(() => {
+      runningCache.fetchedAt = Date.now();
+      runningCache.refreshing = false;
+    });
+}
+
+// Sync getter: never blocks; returns last known state, refreshes in background
+export function isTailscaleRunning() {
+  if (Date.now() - runningCache.fetchedAt > PROBE_TTL_MS) bgRefreshRunning();
+  return runningCache.value;
+}
+
+// Async strict probe for hot user-initiated paths (enable/connect flow).
+// Awaitable, never blocks event loop; updates cache as a side effect.
+export async function isTailscaleRunningStrict() {
+  const bin = getTailscaleBin();
+  if (!bin) return false;
+  try {
+    const { stdout } = await execAsync(`"${bin}" ${SOCKET_FLAG.join(" ")} funnel status --json`, {
+      windowsHide: true,
+      timeout: PROBE_TIMEOUT_MS,
+    });
+    const json = JSON.parse(stdout);
+    const running = Object.keys(json.AllowFunnel || {}).length > 0;
+    runningCache.value = running;
+    runningCache.fetchedAt = Date.now();
+    return running;
+  } catch {
+    return false;
+  }
+}
+
+// Check if a system-level tailscaled is running (uses system socket, not 9Router's custom one).
+export function isSystemDaemonRunning() {
+  if (IS_WINDOWS || !SYSTEM_TAILSCALE_SOCKET || !fs.existsSync(SYSTEM_TAILSCALE_SOCKET)) return false;
+  const bin = getTailscaleBin();
+  if (!bin) return false;
+  try {
+    const out = execSync(`"${bin}" ${SYSTEM_SOCKET_FLAG.join(" ")} status --json`, {
+      encoding: "utf8", windowsHide: true, env: { ...process.env, PATH: EXTENDED_PATH }, timeout: PROBE_TIMEOUT_MS,
+    });
+    return JSON.parse(out).BackendState === "Running";
+  } catch {
+    return false;
+  }
+}
+
+function bgRefreshFunnelUrl(port) {
+  if (funnelUrlCache.refreshing) return;
+  const bin = getTailscaleBin();
+  if (!bin) return;
+  funnelUrlCache.refreshing = true;
+  execAsync(`"${bin}" ${SOCKET_FLAG.join(" ")} status --json`, { windowsHide: true, timeout: PROBE_TIMEOUT_MS })
+    .then(({ stdout }) => {
+      try {
+        const json = JSON.parse(stdout);
+        const dnsName = json.Self?.DNSName?.replace(/\.$/, "");
+        funnelUrlCache.value = dnsName ? `https://${dnsName}` : null;
+      } catch { /* keep prev */ }
+    })
+    .catch(() => { /* keep prev */ })
+    .finally(() => {
+      funnelUrlCache.port = port;
+      funnelUrlCache.fetchedAt = Date.now();
+      funnelUrlCache.refreshing = false;
+    });
+}
+
+/** Get actual funnel URL from Self.DNSName (sync, authoritative — avoids hostname-conflict suffix). */
+function getActualFunnelUrl() {
+  const bin = getTailscaleBin();
+  if (!bin) return null;
+  try {
+    const out = execSync(`"${bin}" ${SOCKET_FLAG.join(" ")} status --json`, {
+      encoding: "utf8",
+      windowsHide: true,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+      timeout: 5000,
+    });
+    const json = JSON.parse(out);
+    const dnsName = json.Self?.DNSName?.replace(/\.$/, "");
+    return dnsName ? `https://${dnsName}` : null;
+  } catch { return null; }
+}
+
+/** Get funnel URL from tailscale status (cached, non-blocking) */
+export function getTailscaleFunnelUrl(port) {
+  if (Date.now() - funnelUrlCache.fetchedAt > PROBE_TTL_MS || funnelUrlCache.port !== port) {
+    bgRefreshFunnelUrl(port);
+  }
+  return funnelUrlCache.value;
+}
+
+/**
+ * Install tailscale.
+ * - macOS + brew: brew install tailscale (no sudo needed)
+ * - macOS no brew: download .pkg then sudo installer -pkg
+ * - Linux: fetch install.sh, pipe to sudo -S sh via stdin
+ * - Windows: download MSI via UAC-elevated PowerShell
+ */
+export async function installTailscale(sudoPassword, hostname, onProgress) {
+  const log = onProgress || (() => {});
+  if (IS_WINDOWS) {
+    await installTailscaleWindows(log);
+    return { success: true };
+  }
+  if (IS_MAC) await installTailscaleMac(sudoPassword, log);
+  else await installTailscaleLinux(sudoPassword, log);
+
+  log("Starting daemon...");
+  await startDaemonWithPassword(sudoPassword);
+  log("Logging in...");
+  return startLogin(hostname);
+}
+
+const EXTENDED_PATH = `/usr/local/bin:/opt/homebrew/bin:/usr/sbin:/usr/bin:/bin:/snap/bin:${process.env.PATH || ""}`;
+
+function hasBrew() {
+  try { execSync("which brew", { stdio: "ignore", windowsHide: true, env: { ...process.env, PATH: EXTENDED_PATH } }); return true; } catch { return false; }
+}
+
+async function installTailscaleMac(sudoPassword, log) {
+  if (hasBrew()) {
+    log("Installing via Homebrew...");
+    await new Promise((resolve, reject) => {
+      const child = spawn("brew", ["install", "tailscale"], {
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        env: { ...process.env, PATH: EXTENDED_PATH }
+      });
+      child.stdout.on("data", (d) => {
+        const line = d.toString().trim();
+        if (line) log(line);
+      });
+      child.stderr.on("data", (d) => {
+        const line = d.toString().trim();
+        if (line) log(line);
+      });
+      child.on("close", (c) => {
+        if (c === 0) resolve();
+        else reject(new Error(`brew install failed (code ${c})`));
+      });
+      child.on("error", reject);
+    });
+    return;
+  }
+
+  // No brew: download .pkg and install via sudo installer
+  const pkgUrl = "https://pkgs.tailscale.com/stable/tailscale-latest.pkg";
+  const pkgPath = path.join(os.tmpdir(), "tailscale.pkg");
+
+  log("Downloading Tailscale package...");
+  await new Promise((resolve, reject) => {
+    const child = spawn("curl", ["-fL", "--progress-bar", pkgUrl, "-o", pkgPath], {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+    child.stderr.on("data", (d) => {
+      const line = d.toString().trim();
+      if (line) log(line);
+    });
+    child.on("close", (c) => {
+      if (c === 0) resolve();
+      else reject(new Error("Download failed"));
+    });
+    child.on("error", reject);
+  });
+
+  log("Installing package...");
+  await new Promise((resolve, reject) => {
+    const child = spawn("sudo", ["-S", "installer", "-pkg", pkgPath, "-target", "/"], {
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true
+    });
+    let stderr = "";
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    child.stdout.on("data", (d) => {
+      const line = d.toString().trim();
+      if (line) log(line);
+    });
+    child.on("close", (c) => {
+      try { execSync(`rm -f ${pkgPath}`, { stdio: "ignore", windowsHide: true }); } catch { /* ignore */ }
+      if (c === 0) resolve();
+      else {
+        const msg = (stderr.includes("incorrect password") || stderr.includes("Sorry"))
+          ? "Wrong sudo password"
+          : stderr || `Exit code ${c}`;
+        reject(new Error(msg));
+      }
+    });
+    child.on("error", reject);
+    child.stdin.write(`${sudoPassword}\n`);
+    child.stdin.end();
+  });
+}
+
+async function installTailscaleLinux(sudoPassword, log) {
+  // Reject password containing newline → prevents stdin command injection
+  if (typeof sudoPassword !== "string" || sudoPassword.includes("\n")) {
+    throw new Error("Invalid sudo password");
+  }
+  log("Downloading install script...");
+  return new Promise((resolve, reject) => {
+    const curlChild = spawn("curl", ["-fsSL", "https://tailscale.com/install.sh"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+    let scriptContent = "";
+    let curlErr = "";
+    curlChild.stdout.on("data", (d) => { scriptContent += d.toString(); });
+    curlChild.stderr.on("data", (d) => { curlErr += d.toString(); });
+    curlChild.on("exit", (code) => {
+      if (code !== 0) return reject(new Error(`Failed to download install script: ${curlErr}`));
+      log("Running install script...");
+      // Persist script to temp file → exec by path (NOT via stdin) → sh never reads attacker-controlled stdin
+      const tmpScript = path.join(os.tmpdir(), `tailscale-install-${crypto.randomBytes(8).toString("hex")}.sh`);
+      try {
+        fs.writeFileSync(tmpScript, scriptContent, { mode: 0o700 });
+      } catch (e) {
+        return reject(new Error(`Failed to write install script: ${e.message}`));
+      }
+      const cleanup = () => { try { fs.unlinkSync(tmpScript); } catch {} };
+      const child = spawn("sudo", ["-S", "sh", tmpScript], { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+      let stderr = "";
+      child.stdout.on("data", (d) => {
+        const line = d.toString().trim();
+        if (line) log(line);
+      });
+      child.stderr.on("data", (d) => { stderr += d.toString(); });
+      child.on("close", (c) => {
+        cleanup();
+        if (c === 0) resolve();
+        else {
+          const msg = (stderr.includes("incorrect password") || stderr.includes("Sorry"))
+            ? "Wrong sudo password"
+            : stderr || `Exit code ${c}`;
+          reject(new Error(msg));
+        }
+      });
+      child.on("error", (e) => { cleanup(); reject(e); });
+      child.stdin.write(`${sudoPassword}\n`);
+      child.stdin.end();
+    });
+    curlChild.on("error", reject);
+  });
+}
+
+async function installTailscaleWindows(log) {
+  const msiUrl = "https://pkgs.tailscale.com/stable/tailscale-setup-latest-amd64.msi";
+  const msiPath = path.join(os.tmpdir(), "tailscale-setup.msi");
+
+  // Download MSI via curl.exe (built-in on Win10+) — no PowerShell window, streams progress
+  log("Downloading Tailscale installer...");
+  await new Promise((resolve, reject) => {
+    const child = spawn("curl.exe", ["-L", "-#", "-o", msiPath, msiUrl], {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+    // curl outputs progress to stderr with -# flag
+    let lastPct = "";
+    child.stderr.on("data", (d) => {
+      const text = d.toString();
+      const match = text.match(/(\d+\.\d)%/);
+      if (match && match[1] !== lastPct) {
+        lastPct = match[1];
+        log(`Downloading... ${lastPct}%`);
+      }
+    });
+    child.on("close", (c) => c === 0 ? resolve() : reject(new Error("Download failed")));
+    child.on("error", reject);
+  });
+
+  // Install MSI with UAC elevation via PowerShell Start-Process -Verb RunAs
+  log("Installing Tailscale (UAC prompt may appear)...");
+  await new Promise((resolve, reject) => {
+    const args = `'/i','${msiPath}','TS_NOLAUNCH=true','/quiet','/norestart'`;
+    const child = spawn("powershell", [
+      "-NoProfile", "-NonInteractive", "-Command",
+      `Start-Process msiexec -ArgumentList ${args} -Verb RunAs -Wait`
+    ], { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    child.stderr.on("data", (d) => { const l = d.toString().trim(); if (l) log(l); });
+    child.on("close", (c) => {
+      try { fs.unlinkSync(msiPath); } catch { /* ignore */ }
+      c === 0 ? resolve() : reject(new Error(`msiexec failed (code ${c})`));
+    });
+    child.on("error", reject);
+  });
+
+  // Verify tailscale.exe exists after install
+  log("Verifying installation...");
+  const maxWait = 10000;
+  const start = Date.now();
+  while (Date.now() - start < maxWait) {
+    if (fs.existsSync(WINDOWS_TAILSCALE_BIN)) {
+      log("Installation complete.");
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  throw new Error("Installation finished but tailscale.exe not found");
+}
+
+// Self-heal: if state dir/files were previously created by root (e.g. legacy sudo daemon),
+// reclaim ownership recursively so the user-mode daemon can read/write state files.
+async function ensureUserOwnedDir(dir) {
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+      return;
+    }
+    const uid = process.getuid();
+    const gid = process.getgid();
+
+    // Walk dir + all entries to find any non-user-owned items
+    const needsChown = (() => {
+      const stack = [dir];
+      while (stack.length) {
+        const cur = stack.pop();
+        try {
+          const st = fs.statSync(cur);
+          if (st.uid !== uid) return true;
+          if (st.isDirectory()) {
+            for (const name of fs.readdirSync(cur)) stack.push(path.join(cur, name));
+          }
+        } catch { /* ignore */ }
+      }
+      return false;
+    })();
+
+    if (!needsChown) return;
+
+    // Try direct chown first (works if already owned). Fallback to passwordless sudo.
+    try {
+      execSync(`chown -R ${uid}:${gid} "${dir}"`, { stdio: "ignore", timeout: 3000 });
+    } catch {
+      try { execSync(`sudo -n chown -R ${uid}:${gid} "${dir}"`, { stdio: "ignore", timeout: 3000 }); } catch { /* ignore */ }
+    }
+  } catch { /* ignore */ }
+}
+
+/** Check if running daemon uses TUN mode (Funnel TLS requires TUN). */
+function isDaemonTunMode() {
+  try {
+    const ps = execSync(`pgrep -af "tailscaled.*${TAILSCALE_SOCKET}"`, { encoding: "utf8", timeout: 2000 }).trim();
+    if (!ps) return null;
+    return !ps.includes("--tun=userspace-networking");
+  } catch { return null; }
+}
+
+/** Daemon process alive (independent of funnel state) — mirrors cloudflared PID check semantic. */
+export function isDaemonAlive() {
+  return isDaemonTunMode() !== null;
+}
+
+/**
+ * Start tailscaled.
+ * - With sudoPassword: TUN mode (root) → Funnel TLS works
+ * - Without: userspace-networking fallback (no sudo, but Funnel TLS unstable)
+ * State always lives in ~/.9router/tailscale/ via --statedir.
+ */
+export async function startDaemonWithPassword(sudoPassword) {
+  if (IS_WINDOWS) {
+    // Windows: tailscale runs as a Windows Service. Start it then poll BackendState
+    // until daemon finishes init (avoids "NoState" errors when calling funnel/up too early).
+    const bin = getTailscaleBin();
+    console.log("[Tailscale] win: net start Tailscale");
+    try { execSync("net start Tailscale", { stdio: "ignore", windowsHide: true, timeout: 10000 }); }
+    catch { /* may need admin, or already running */ }
+    if (!bin) return;
+    // Poll up to ~10s for backend to leave NoState
+    for (let i = 0; i < 20; i++) {
+      try {
+        const out = execSync(`"${bin}" status --json`, { encoding: "utf8", windowsHide: true, timeout: 2000 });
+        const j = JSON.parse(out);
+        if (j.BackendState && j.BackendState !== "NoState") {
+          console.log(`[Tailscale] win: BackendState=${j.BackendState} after ${i*500}ms`);
+          return;
+        }
+      } catch { /* daemon not ready */ }
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    console.log("[Tailscale] win: BackendState still NoState after poll");
+    return;
+  }
+
+  const currentMode = isDaemonTunMode(); // true=TUN, false=userspace, null=not running
+  // No password but a healthy TUN daemon already runs → keep TUN, never downgrade-kill it.
+  const wantTun = sudoPassword ? true : currentMode === true;
+
+  // Daemon already running in correct mode → reuse
+  if (currentMode !== null && currentMode === wantTun) {
+    try {
+      const bin = getTailscaleBin() || "tailscale";
+      execSync(`"${bin}" ${SOCKET_FLAG.join(" ")} status --json`, {
+        stdio: "ignore", windowsHide: true,
+        env: { ...process.env, PATH: EXTENDED_PATH }, timeout: 3000
+      });
+      return;
+    } catch { /* unresponsive, restart below */ }
+  }
+
+  // Mode mismatch or unresponsive → kill all daemons on our socket
+  try { execSync(`pkill -9 -f "tailscaled.*${TAILSCALE_SOCKET}"`, { stdio: "ignore", timeout: 3000 }); } catch { /* ignore */ }
+  if (sudoPassword) {
+    try { await execWithPassword(`pkill -9 -f "tailscaled.*${TAILSCALE_SOCKET}"`, sudoPassword); } catch { /* ignore */ }
+  } else {
+    try { execSync(`sudo -n pkill -9 -f "tailscaled.*${TAILSCALE_SOCKET}"`, { stdio: "ignore", timeout: 3000 }); } catch { /* ignore */ }
+  }
+  await new Promise((r) => setTimeout(r, 1500));
+
+  // Reclaim folder ownership (previous root daemon may have locked it)
+  await ensureUserOwnedDir(TAILSCALE_DIR);
+
+  const tailscaledBin = IS_MAC ? "/usr/local/bin/tailscaled" : "tailscaled";
+  const daemonArgs = [
+    `--socket=${TAILSCALE_SOCKET}`,
+    `--statedir=${TAILSCALE_DIR}`,
+  ];
+  if (!wantTun) daemonArgs.push("--tun=userspace-networking");
+
+  if (wantTun) {
+    // TUN mode: spawn via sudo, password via stdin. Detached so it survives parent exit.
+    const child = spawn("sudo", ["-S", tailscaledBin, ...daemonArgs], {
+      detached: true,
+      stdio: ["pipe", "ignore", "ignore"],
+      cwd: os.tmpdir(),
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    });
+    child.stdin.write(`${sudoPassword}\n`);
+    child.stdin.end();
+    child.unref();
+  } else {
+    const child = spawn(tailscaledBin, daemonArgs, {
+      detached: true,
+      stdio: "ignore",
+      cwd: os.tmpdir(),
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    });
+    child.unref();
+  }
+
+  // Wait for socket ready
+  await new Promise((r) => setTimeout(r, 3000));
+}
+
+/** Best-effort: ensure daemon running (used for login flow) */
+function ensureDaemon() {
+  startDaemonWithPassword("").catch(() => {});
+}
+
+/** Read AuthURL from `tailscale status --json` (Win exposes it there, not stdout). */
+function getAuthUrlFromStatus() {
+  const bin = getTailscaleBin();
+  if (!bin) return null;
+  try {
+    const out = execSync(`"${bin}" ${SOCKET_FLAG.join(" ")} status --json`, {
+      encoding: "utf8", windowsHide: true, timeout: 2000
+    });
+    const j = JSON.parse(out);
+    if (j.AuthURL) return j.AuthURL;
+    return null;
+  } catch { return null; }
+}
+
+/**
+ * Run `tailscale up` and capture the auth URL for browser login.
+ * Resolves with { authUrl } or { alreadyLoggedIn: true }.
+ * On Windows, AuthURL comes from `status --json` (not stdout) — must poll status.
+ */
+export function startLogin(hostname) {
+  const bin = getTailscaleBin();
+  if (!bin) return Promise.reject(new Error("Tailscale not installed"));
+
+  return new Promise((resolve, reject) => {
+    // Ensure daemon is running (best-effort, no sudo)
+    ensureDaemon();
+
+    // Check if already logged in
+    if (isTailscaleLoggedIn()) {
+      resolve({ alreadyLoggedIn: true });
+      return;
+    }
+
+    const args = tsArgs("up", "--accept-routes");
+    if (hostname) args.push(`--hostname=${hostname}`);
+    const child = spawn(bin, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: true,
+      windowsHide: true
+    });
+
+    let resolved = false;
+    let output = "";
+
+    const parseAuthUrl = (text) => {
+      const match = text.match(/https:\/\/login\.tailscale\.com\/a\/[a-zA-Z0-9]+/);
+      return match ? match[0] : null;
+    };
+
+    const finishWithUrl = (url, source) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timeout);
+      clearInterval(statusPoll);
+      console.log(`[Tailscale] login authUrl detected (${source})`);
+      child.unref();
+      resolve({ authUrl: url });
+    };
+
+    // Poll status --json every 500ms — Windows exposes AuthURL only there
+    const statusPoll = setInterval(() => {
+      if (resolved) return;
+      const url = getAuthUrlFromStatus();
+      if (url) finishWithUrl(url, "status");
+    }, 500);
+
+    const timeout = setTimeout(() => {
+      if (resolved) return;
+      resolved = true;
+      clearInterval(statusPoll);
+      child.unref();
+      const url = parseAuthUrl(output) || getAuthUrlFromStatus();
+      if (url) resolve({ authUrl: url });
+      else reject(new Error("tailscale up timed out without auth URL"));
+    }, 15000);
+
+    const handleData = (data) => {
+      output += data.toString();
+      const url = parseAuthUrl(output);
+      if (url) finishWithUrl(url, "stdout");
+    };
+
+    child.stdout.on("data", handleData);
+    child.stderr.on("data", handleData);
+
+    child.on("error", (err) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timeout);
+      clearInterval(statusPoll);
+      console.error(`[Tailscale] login spawn error: ${err.message}`);
+      reject(err);
+    });
+
+    child.on("exit", (code) => {
+      if (resolved) return;
+      console.log(`[Tailscale] login exit code=${code}`);
+      // Don't trust exit code alone — Win `tailscale up` exits 0 even when not logged in.
+      // Let status poll continue until AuthURL appears or timeout.
+      const url = parseAuthUrl(output) || getAuthUrlFromStatus();
+      if (url) {
+        finishWithUrl(url, "exit");
+        return;
+      }
+      // Only resolve alreadyLoggedIn if status confirms BackendState=Running
+      if (isTailscaleLoggedIn()) {
+        resolved = true;
+        clearTimeout(timeout);
+        clearInterval(statusPoll);
+        resolve({ alreadyLoggedIn: true });
+        return;
+      }
+      // Otherwise keep polling — daemon may publish AuthURL shortly after exit
+    });
+  });
+}
+
+/** Start tailscale funnel for the given port */
+export async function startFunnel(port) {
+  const bin = getTailscaleBin();
+  if (!bin) throw new Error("Tailscale not installed");
+
+  // Reset any existing funnel
+  try { execSync(`"${bin}" ${SOCKET_FLAG.join(" ")} funnel --bg reset`, { stdio: "ignore", windowsHide: true }); } catch (e) { /* ignore */ }
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, tsArgs("funnel", "--bg", `${port}`), {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+
+    let resolved = false;
+    let output = "";
+
+    const timeout = setTimeout(() => {
+      if (resolved) return;
+      resolved = true;
+      // --bg exits after setup, read actual hostname from status
+      const url = getActualFunnelUrl() || getTailscaleFunnelUrl(port);
+      if (url) resolve({ tunnelUrl: url });
+      else reject(new Error(`Tailscale funnel timed out: ${output.trim() || "no output"}`));
+    }, 30000);
+
+    // Always resolve via Self.DNSName to get the real hostname (avoids -1 suffix from conflicts)
+    const parseFunnelUrl = () => getActualFunnelUrl();
+
+    let funnelNotEnabled = false;
+
+    const handleData = (data) => {
+      output += data.toString();
+
+      if (output.includes("Funnel is not enabled")) funnelNotEnabled = true;
+
+      // Wait for the enable URL to arrive in a later chunk
+      if (funnelNotEnabled && !resolved) {
+        const enableMatch = output.match(/https:\/\/login\.tailscale\.com\/[^\s]+/);
+        if (enableMatch) {
+          resolved = true;
+          clearTimeout(timeout);
+          child.kill();
+          resolve({ funnelNotEnabled: true, enableUrl: enableMatch[0] });
+          return;
+        }
+      }
+
+      const url = parseFunnelUrl();
+      if (url && !resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        resolve({ tunnelUrl: url });
+      }
+    };
+
+    child.stdout.on("data", handleData);
+    child.stderr.on("data", handleData);
+
+    child.on("exit", (code) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timeout);
+      console.log(`[Tailscale] funnel exit code=${code} output="${output.trim().slice(0, 200)}"`);
+      const url = parseFunnelUrl() || getTailscaleFunnelUrl(port);
+      if (url) resolve({ tunnelUrl: url });
+      else reject(new Error(`tailscale funnel failed (code ${code}): ${output.trim()}`));
+    });
+
+    child.on("error", (err) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+
+/** Provision TLS cert for funnel domain (required before Funnel serves HTTPS). Best-effort. */
+export async function provisionCert(hostname) {
+  const bin = getTailscaleBin();
+  if (!bin || !hostname) return;
+  const certsDir = path.join(TAILSCALE_DIR, "certs");
+  fs.mkdirSync(certsDir, { recursive: true });
+  const certFile = path.join(certsDir, `${hostname}.crt`);
+  const keyFile = path.join(certsDir, `${hostname}.key`);
+  try {
+    await execAsync(
+      `"${bin}" ${SOCKET_FLAG.join(" ")} cert --cert-file "${certFile}" --key-file "${keyFile}" "${hostname}"`,
+      { windowsHide: true, env: { ...process.env, PATH: EXTENDED_PATH }, timeout: 30000 }
+    );
+    console.log(`[Tailscale] cert provisioned for ${hostname}`);
+  } catch (e) {
+    console.warn(`[Tailscale] cert provision failed (non-fatal): ${e.message}`);
+  }
+}
+
+/** Stop tailscale funnel */
+export function stopFunnel() {
+  const bin = getTailscaleBin();
+  if (!bin) return;
+  try { execSync(`"${bin}" ${SOCKET_FLAG.join(" ")} funnel --bg reset`, { stdio: "ignore", windowsHide: true }); } catch (e) { /* ignore */ }
+}
+
+/** Kill tailscaled daemon (runs as root, needs sudo) */
+export async function stopDaemon(sudoPassword) {
+  // Try non-sudo first
+  try { execSync("pkill -x tailscaled", { stdio: "ignore", windowsHide: true, timeout: 3000 }); } catch { /* ignore */ }
+
+  // Check if still alive
+  try { execSync("pgrep -x tailscaled", { stdio: "ignore", windowsHide: true, timeout: 2000 }); } catch { return; } // Dead, done
+
+  // Kill with sudo password
+  if (!IS_WINDOWS) {
+    try { await execWithPassword("pkill -x tailscaled", sudoPassword || ""); } catch { /* ignore */ }
+  }
+
+  // Cleanup socket
+  try { if (fs.existsSync(TAILSCALE_SOCKET)) fs.unlinkSync(TAILSCALE_SOCKET); } catch { /* ignore */ }
+}
diff --git a/src/lib/updater/updater.js b/src/lib/updater/updater.js
new file mode 100644
index 0000000..0ad48af
--- /dev/null
+++ b/src/lib/updater/updater.js
@@ -0,0 +1,235 @@
+// Standalone detached updater process.
+// Spawns `npm i -g <pkg>@latest`, exposes progress via tiny HTTP server.
+// Survives after parent Next server exits (detached + unref by spawner).
+
+const { spawn } = require("child_process");
+const http = require("http");
+const net = require("net");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+const packageName = process.env.UPDATER_PKG_NAME || "9router";
+const port = parseInt(process.env.UPDATER_PORT || "20129", 10);
+const tailLines = parseInt(process.env.UPDATER_TAIL_LINES || "8", 10);
+const maxRetries = parseInt(process.env.UPDATER_RETRIES || "3", 10);
+const retryDelayMs = parseInt(process.env.UPDATER_RETRY_DELAY_MS || "5000", 10);
+const lingerMs = parseInt(process.env.UPDATER_LINGER_MS || "30000", 10);
+const waitMinMs = parseInt(process.env.UPDATER_WAIT_MIN_MS || "3000", 10);
+const waitMaxMs = parseInt(process.env.UPDATER_WAIT_MAX_MS || "15000", 10);
+const waitCheckMs = parseInt(process.env.UPDATER_WAIT_CHECK_MS || "500", 10);
+const appPort = parseInt(process.env.UPDATER_APP_PORT || "20128", 10);
+
+// Data directory (match mitm/paths.js logic)
+function getDataDir() {
+  if (process.env.DATA_DIR) return process.env.DATA_DIR;
+  if (process.platform === "win32") {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "9router");
+  }
+  return path.join(os.homedir(), ".9router");
+}
+const updateDir = path.join(getDataDir(), "update");
+try { fs.mkdirSync(updateDir, { recursive: true }); } catch { /* best effort */ }
+const statusFile = path.join(updateDir, "status.json");
+const logFile = path.join(updateDir, "install.log");
+
+const state = {
+  phase: "starting",
+  packageName,
+  startedAt: Date.now(),
+  finishedAt: null,
+  attempt: 0,
+  maxRetries,
+  done: false,
+  success: false,
+  exitCode: null,
+  error: null,
+  logTail: [],
+};
+
+function pushLog(line) {
+  const trimmed = line.replace(/\r?\n$/, "");
+  if (!trimmed) return;
+  state.logTail.push(trimmed);
+  if (state.logTail.length > tailLines) state.logTail = state.logTail.slice(-tailLines);
+  try { fs.appendFileSync(logFile, `${trimmed}\n`); } catch { /* best effort */ }
+}
+
+function persistStatus() {
+  try { fs.writeFileSync(statusFile, JSON.stringify(state, null, 2)); } catch { /* best effort */ }
+}
+
+function setPhase(phase) {
+  state.phase = phase;
+  persistStatus();
+}
+
+// HTTP server exposing status (browser polls this while Next server is dead)
+const server = http.createServer((req, res) => {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Cache-Control", "no-store");
+  if (req.url === "/update/status" || req.url === "/") {
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(state));
+    return;
+  }
+  res.statusCode = 404;
+  res.end("not found");
+});
+
+server.on("error", (e) => {
+  state.error = `status server error: ${e.message}`;
+  persistStatus();
+});
+
+server.listen(port, "127.0.0.1", () => {
+  persistStatus();
+  waitForAppExit().then(runInstall);
+});
+
+// Check if app port is still being listened on (= app server still alive)
+function isAppPortBusy() {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    const done = (busy) => {
+      socket.destroy();
+      resolve(busy);
+    };
+    socket.setTimeout(300);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+    socket.connect(appPort, "127.0.0.1");
+  });
+}
+
+// Wait for app process to fully exit before running npm (avoids Windows file-lock)
+async function waitForAppExit() {
+  setPhase("waitingForExit");
+  pushLog(`[updater] waiting for app to exit (min ${Math.round(waitMinMs / 1000)}s)...`);
+
+  // Hard minimum delay: OS needs time to release file handles
+  await sleep(waitMinMs);
+
+  // Poll app port until free or max timeout
+  const deadline = Date.now() + (waitMaxMs - waitMinMs);
+  while (Date.now() < deadline) {
+    const busy = await isAppPortBusy();
+    if (!busy) {
+      pushLog(`[updater] app port :${appPort} is free, proceeding`);
+      return;
+    }
+    await sleep(waitCheckMs);
+  }
+  pushLog(`[updater] timeout waiting for app, proceeding anyway`);
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function runInstall() {
+  state.attempt += 1;
+  setPhase("installing");
+  pushLog(`[updater] attempt ${state.attempt}/${maxRetries} — npm i -g ${packageName} --prefer-online`);
+
+  const isWin = process.platform === "win32";
+  const cmd = isWin ? "npm.cmd" : "npm";
+  const args = ["i", "-g", packageName, "--prefer-online"];
+
+  const child = spawn(cmd, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+    shell: isWin,
+  });
+
+  child.stdout.on("data", (buf) => {
+    buf.toString().split(/\r?\n/).forEach(pushLog);
+    persistStatus();
+  });
+  child.stderr.on("data", (buf) => {
+    buf.toString().split(/\r?\n/).forEach(pushLog);
+    persistStatus();
+  });
+
+  child.on("error", (e) => {
+    pushLog(`[updater] spawn error: ${e.message}`);
+    finalize(false, null, e.message);
+  });
+
+  child.on("close", (code) => {
+    pushLog(`[updater] npm exited with code ${code}`);
+    if (code === 0) {
+      finalize(true, code, null);
+      return;
+    }
+    if (state.attempt < maxRetries) {
+      pushLog(`[updater] retrying in ${Math.round(retryDelayMs / 1000)}s...`);
+      setTimeout(runInstall, retryDelayMs);
+      return;
+    }
+    finalize(false, code, `Install failed after ${maxRetries} attempts`);
+  });
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? `open "${url}"`
+    : platform === "win32" ? `start "" "${url}"`
+    : `xdg-open "${url}"`;
+  try { spawn(cmd, { shell: true, detached: true, stdio: "ignore" }).unref(); } catch { /* ignore */ }
+}
+
+// Wait until app port is listening (server alive again), then open dashboard
+async function waitForAppAndOpenBrowser() {
+  const deadline = Date.now() + 30000;
+  while (Date.now() < deadline) {
+    const busy = await isAppPortBusy();
+    if (busy) {
+      openBrowser(`http://localhost:${appPort}/dashboard`);
+      pushLog(`[updater] app ready, opened dashboard`);
+      return;
+    }
+    await sleep(1000);
+  }
+  pushLog(`[updater] app not responding within 30s, skip browser open`);
+}
+
+function relaunchApp() {
+  if (process.env.UPDATER_RELAUNCH !== "1") return;
+  const cmd = process.env.UPDATER_RELAUNCH_CMD;
+  if (!cmd) return;
+  let args = [];
+  try { args = JSON.parse(process.env.UPDATER_RELAUNCH_ARGS || "[]"); } catch { /* noop */ }
+  const isWin = process.platform === "win32";
+  try {
+    const child = spawn(cmd, args, {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      shell: isWin,
+      env: { ...process.env, UPDATER_RELAUNCH: "", UPDATER_RELAUNCH_CMD: "", UPDATER_RELAUNCH_ARGS: "" },
+    });
+    child.unref();
+    pushLog(`[updater] relaunched: ${cmd} ${args.join(" ")} (pid=${child.pid})`);
+    // Wait for new app to come up, then auto-open browser so user sees the result
+    waitForAppAndOpenBrowser();
+  } catch (e) {
+    pushLog(`[updater] relaunch failed: ${e.message}`);
+  }
+}
+
+function finalize(success, exitCode, error) {
+  state.done = true;
+  state.success = success;
+  state.exitCode = exitCode;
+  state.error = error;
+  state.finishedAt = Date.now();
+  setPhase(success ? "done" : "error");
+  if (success) relaunchApp();
+  // Linger so browser can poll final status, then exit & close the port
+  setTimeout(() => {
+    try { server.close(); } catch { /* ignore */ }
+    process.exit(success ? 0 : 1);
+  }, lingerMs);
+}
diff --git a/src/lib/usageDb.js b/src/lib/usageDb.js
new file mode 100644
index 0000000..d56d58a
--- /dev/null
+++ b/src/lib/usageDb.js
@@ -0,0 +1,7 @@
+// Shim → re-export from new SQLite-based DB layer (src/lib/db/)
+export {
+  statsEmitter, trackPendingRequest, getActiveRequests,
+  saveRequestUsage, getUsageHistory, getUsageStats, getChartData,
+  appendRequestLog, getRecentLogs,
+  saveRequestDetail, getRequestDetails, getRequestDetailById,
+} from "@/lib/db/index.js";
diff --git a/src/mitm/antigravityIdeVersion.js b/src/mitm/antigravityIdeVersion.js
new file mode 100644
index 0000000..1b9458d
--- /dev/null
+++ b/src/mitm/antigravityIdeVersion.js
@@ -0,0 +1,50 @@
+"use strict";
+
+// Rewrite Antigravity IDE markers so upstream AG 2.x backend accepts the request.
+// User-Agent header (antigravity/<old>) and body.metadata.ideVersion are forced
+// to a known-good IDE version. Hardcoded MVP — toggle/version configurable later.
+
+const ANTIGRAVITY_IDE_VERSION = "1.23.2";
+const ANTIGRAVITY_IDE_VERSION_OVERRIDE_ENABLED = true;
+
+function shouldRewriteMetadata(metadata) {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return false;
+  if (String(metadata.ideName || "").toLowerCase() === "antigravity") return true;
+  if (String(metadata.ideType || "").toUpperCase() === "ANTIGRAVITY") return true;
+  return Object.prototype.hasOwnProperty.call(metadata, "ideVersion");
+}
+
+function rewriteAntigravityUserAgent(userAgent, version) {
+  if (typeof userAgent !== "string" || !userAgent.includes("antigravity/")) return userAgent;
+  return userAgent.replace(/antigravity\/[^\s]+/, `antigravity/${version}`);
+}
+
+function applyAntigravityIdeVersionOverride(bodyBuffer, headers) {
+  if (!ANTIGRAVITY_IDE_VERSION_OVERRIDE_ENABLED) {
+    return { bodyBuffer, headers, applied: false, version: ANTIGRAVITY_IDE_VERSION };
+  }
+
+  const nextHeaders = { ...headers };
+  const nextUserAgent = rewriteAntigravityUserAgent(nextHeaders["user-agent"], ANTIGRAVITY_IDE_VERSION);
+  const userAgentChanged = nextUserAgent !== nextHeaders["user-agent"];
+  if (userAgentChanged) nextHeaders["user-agent"] = nextUserAgent;
+
+  try {
+    const parsed = JSON.parse(bodyBuffer.toString());
+    if (!shouldRewriteMetadata(parsed?.metadata)) {
+      return { bodyBuffer, headers: nextHeaders, applied: userAgentChanged, version: ANTIGRAVITY_IDE_VERSION };
+    }
+
+    parsed.metadata.ideVersion = ANTIGRAVITY_IDE_VERSION;
+    const nextBodyBuffer = Buffer.from(JSON.stringify(parsed));
+    return { bodyBuffer: nextBodyBuffer, headers: nextHeaders, applied: true, version: ANTIGRAVITY_IDE_VERSION };
+  } catch {
+    return { bodyBuffer, headers: nextHeaders, applied: userAgentChanged, version: ANTIGRAVITY_IDE_VERSION };
+  }
+}
+
+module.exports = {
+  ANTIGRAVITY_IDE_VERSION,
+  applyAntigravityIdeVersionOverride,
+  rewriteAntigravityUserAgent,
+};
diff --git a/src/mitm/cert/generate.js b/src/mitm/cert/generate.js
new file mode 100644
index 0000000..e85f9dc
--- /dev/null
+++ b/src/mitm/cert/generate.js
@@ -0,0 +1,32 @@
+const path = require("path");
+const fs = require("fs");
+const { MITM_DIR } = require("../paths");
+const { generateRootCA, loadRootCA, generateLeafCert } = require("./rootCA");
+
+/**
+ * Generate Root CA certificate (one-time setup)
+ * This replaces the old static wildcard cert approach
+ */
+function generateCert() {
+  return generateRootCA();
+}
+
+/**
+ * Get certificate for a specific domain (dynamic generation)
+ * Used by SNICallback in server.js
+ */
+function getCertForDomain(domain) {
+  try {
+    const rootCA = loadRootCA();
+    const leafCert = generateLeafCert(domain, rootCA);
+    return {
+      key: leafCert.key,
+      cert: leafCert.cert
+    };
+  } catch (error) {
+    console.error(`Failed to generate cert for ${domain}:`, error.message);
+    return null;
+  }
+}
+
+module.exports = { generateCert, getCertForDomain };
diff --git a/src/mitm/cert/install.js b/src/mitm/cert/install.js
new file mode 100644
index 0000000..f8f8fe7
--- /dev/null
+++ b/src/mitm/cert/install.js
@@ -0,0 +1,269 @@
+const fs = require("fs");
+const crypto = require("crypto");
+const { exec } = require("child_process");
+const { execWithPassword, isSudoAvailable } = require("../dns/dnsConfig.js");
+const { runElevatedPowerShell, quotePs } = require("../winElevated.js");
+const { log, err } = require("../logger");
+
+const IS_WIN = process.platform === "win32";
+const IS_MAC = process.platform === "darwin";
+const LINUX_CERT_PATHS = [
+  // Debian / Ubuntu
+  { dir: "/usr/local/share/ca-certificates", cmd: "update-ca-certificates" },
+  // Arch Linux / CachyOS / Manjaro
+  { dir: "/etc/ca-certificates/trust-source/anchors", cmd: "update-ca-trust" },
+  // Fedora / RHEL / CentOS
+  { dir: "/etc/pki/ca-trust/source/anchors", cmd: "update-ca-trust" },
+  // openSUSE
+  { dir: "/etc/pki/trust/anchors", cmd: "update-ca-certificates" }
+];
+
+function getLinuxCertConfig() {
+  for (const config of LINUX_CERT_PATHS) {
+    if (fs.existsSync(config.dir)) {
+      return config;
+    }
+  }
+  // Fallback to Debian default if none exist
+  return LINUX_CERT_PATHS[0];
+}
+const ROOT_CA_CN = "9Router MITM Root CA";
+
+// Get SHA1 fingerprint from cert file using Node.js crypto
+function getCertFingerprint(certPath) {
+  const pem = fs.readFileSync(certPath, "utf-8");
+  const der = Buffer.from(pem.replace(/-----[^-]+-----/g, "").replace(/\s/g, ""), "base64");
+  return crypto.createHash("sha1").update(der).digest("hex").toUpperCase().match(/.{2}/g).join(":");
+}
+
+/**
+ * Check if certificate is already installed in system store
+ */
+async function checkCertInstalled(certPath) {
+  if (IS_WIN) return checkCertInstalledWindows(certPath);
+  if (IS_MAC) return checkCertInstalledMac(certPath);
+  return checkCertInstalledLinux();
+}
+
+function checkCertInstalledMac(certPath) {
+  return new Promise((resolve) => {
+    try {
+      const fingerprint = getCertFingerprint(certPath).replace(/:/g, "");
+      // Verify exact cert bytes match — same CN with different fingerprint = stale cert
+      exec(`security find-certificate -a -c "${ROOT_CA_CN}" -Z /Library/Keychains/System.keychain 2>/dev/null`, { windowsHide: true }, (error, stdout) => {
+        if (error || !stdout) return resolve(false);
+        const match = new RegExp(`SHA-1 hash:\\s*${fingerprint}`, "i").test(stdout);
+        if (!match) return resolve(false);
+        // Cert exists with matching fingerprint — confirm trust policy
+        exec(`security verify-cert -c "${certPath}" -p ssl -k /Library/Keychains/System.keychain 2>/dev/null`, { windowsHide: true }, (err2) => {
+          resolve(!err2);
+        });
+      });
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+function checkCertInstalledWindows(certPath) {
+  return new Promise((resolve) => {
+    // Check by SHA1 fingerprint — detects stale cert with same CN but different key
+    let fingerprint;
+    try {
+      fingerprint = getCertFingerprint(certPath).replace(/:/g, "");
+    } catch {
+      return resolve(false);
+    }
+    exec(`certutil -store Root ${fingerprint}`, { windowsHide: true }, (error) => {
+      resolve(!error);
+    });
+  });
+}
+
+/**
+ * Install SSL certificate to system trust store
+ */
+async function installCert(sudoPassword, certPath) {
+  if (!fs.existsSync(certPath)) {
+    throw new Error(`Certificate file not found: ${certPath}`);
+  }
+
+  const isInstalled = await checkCertInstalled(certPath);
+  if (isInstalled) {
+    log("🔐 Cert: already trusted ✅");
+    return;
+  }
+
+  if (IS_WIN) {
+    await installCertWindows(certPath);
+  } else if (IS_MAC) {
+    await installCertMac(sudoPassword, certPath);
+  } else {
+    await installCertLinux(sudoPassword, certPath);
+  }
+}
+
+async function installCertMac(sudoPassword, certPath) {
+  // Remove all old certs with same name first to avoid duplicate/stale cert conflict
+  const deleteOld = `security delete-certificate -c "9Router MITM Root CA" /Library/Keychains/System.keychain 2>/dev/null || true`;
+  const install = `security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${certPath}"`;
+  try {
+    await execWithPassword(`${deleteOld} && ${install}`, sudoPassword);
+    log("🔐 Cert: ✅ installed to system keychain");
+  } catch (error) {
+    const msg = error.message?.includes("canceled") ? "User canceled authorization" : "Certificate install failed";
+    throw new Error(msg);
+  }
+}
+
+async function installCertWindows(certPath) {
+  // Auto-elevate via UAC popup if not admin (zero popup if already admin).
+  // Delete any stale cert with same CN before adding to avoid duplicates.
+  const script = `
+    certutil -delstore Root ${quotePs(ROOT_CA_CN)} 2>$null | Out-Null
+    $exit = & certutil -addstore Root ${quotePs(certPath)} 2>&1
+    if ($LASTEXITCODE -ne 0) { throw "certutil exit $LASTEXITCODE" }
+  `;
+  try {
+    await runElevatedPowerShell(script);
+    log("🔐 Cert: ✅ installed to Windows Root store");
+  } catch (e) {
+    throw new Error(`Failed to install certificate: ${e.message}`);
+  }
+}
+
+/**
+ * Uninstall SSL certificate from system store
+ */
+async function uninstallCert(sudoPassword, certPath) {
+  const isInstalled = await checkCertInstalled(certPath);
+  if (!isInstalled) {
+    log("🔐 Cert: not found in system store");
+    return;
+  }
+
+  if (IS_WIN) {
+    await uninstallCertWindows();
+  } else if (IS_MAC) {
+    await uninstallCertMac(sudoPassword, certPath);
+  } else {
+    await uninstallCertLinux(sudoPassword);
+  }
+}
+
+async function uninstallCertMac(sudoPassword, certPath) {
+  const fingerprint = getCertFingerprint(certPath).replace(/:/g, "");
+  const command = `security delete-certificate -Z "${fingerprint}" /Library/Keychains/System.keychain`;
+  try {
+    await execWithPassword(command, sudoPassword);
+    log("🔐 Cert: ✅ uninstalled from system keychain");
+  } catch (err) {
+    throw new Error("Failed to uninstall certificate");
+  }
+}
+
+async function uninstallCertWindows() {
+  // Auto-elevate via UAC popup if not admin
+  const script = `certutil -delstore Root ${quotePs(ROOT_CA_CN)}`;
+  try {
+    await runElevatedPowerShell(script);
+    log("🔐 Cert: ✅ uninstalled from Windows Root store");
+  } catch (e) {
+    throw new Error(`Failed to uninstall certificate: ${e.message}`);
+  }
+}
+
+function checkCertInstalledLinux() {
+  const config = getLinuxCertConfig();
+  const certFile = `${config.dir}/9router-root-ca.crt`;
+  return Promise.resolve(fs.existsSync(certFile));
+}
+
+async function updateNssDatabases(certPath, action = 'add') {
+  const certName = "9Router MITM Root CA";
+  
+  const script = `
+    if ! command -v certutil &> /dev/null; then
+      exit 0
+    fi
+    
+    DIRS="$HOME/.pki/nssdb $HOME/snap/chromium/current/.pki/nssdb"
+    
+    if [ -d "$HOME/.mozilla/firefox" ]; then
+      for profile in "$HOME"/.mozilla/firefox/*/; do
+        if [ -f "\${profile}cert9.db" ] || [ -f "\${profile}cert8.db" ]; then
+          DIRS="$DIRS $profile"
+        fi
+      done
+    fi
+
+    if [ -d "$HOME/snap/firefox/common/.mozilla/firefox" ]; then
+      for profile in "$HOME"/snap/firefox/common/.mozilla/firefox/*/; do
+        if [ -f "\${profile}cert9.db" ] || [ -f "\${profile}cert8.db" ]; then
+          DIRS="$DIRS $profile"
+        fi
+      done
+    fi
+
+    for db in $DIRS; do
+      if [ -d "$db" ]; then
+        if [ "${action}" = "add" ]; then
+          certutil -d sql:"$db" -A -t "C,," -n "${certName}" -i "${certPath}" 2>/dev/null || \\
+          certutil -d "$db" -A -t "C,," -n "${certName}" -i "${certPath}" 2>/dev/null || true
+        else
+          certutil -d sql:"$db" -D -n "${certName}" 2>/dev/null || \\
+          certutil -d "$db" -D -n "${certName}" 2>/dev/null || true
+        fi
+      fi
+    done
+  `;
+  
+  return new Promise((resolve) => {
+    exec(script, { shell: "/bin/bash" }, () => resolve());
+  });
+}
+
+async function installCertLinux(sudoPassword, certPath) {
+  if (!isSudoAvailable()) {
+    log(`🔐 Cert: cannot install to system store without sudo — trust this file on clients: ${certPath}`);
+    // Still try to update user NSS DBs even if no sudo!
+    await updateNssDatabases(certPath, 'add');
+    return;
+  }
+  
+  const config = getLinuxCertConfig();
+  const destFile = `${config.dir}/9router-root-ca.crt`;
+  
+  // Copy to the discovered directory and execute the specific update command
+  const cmd = `cp "${certPath}" "${destFile}" && (${config.cmd} 2>/dev/null || true)`;
+  
+  try {
+    await execWithPassword(cmd, sudoPassword);
+    await updateNssDatabases(certPath, 'add');
+    log(`🔐 Cert: ✅ installed to Linux trust store (${config.dir}) and user browser databases`);
+  } catch (error) {
+    throw new Error(`Certificate install failed: ${error.message}`);
+  }
+}
+
+async function uninstallCertLinux(sudoPassword) {
+  // Always try to uninstall from user DBs even without sudo
+  await updateNssDatabases(null, 'delete');
+
+  if (!isSudoAvailable()) {
+    return;
+  }
+  
+  const config = getLinuxCertConfig();
+  const destFile = `${config.dir}/9router-root-ca.crt`;
+  const cmd = `rm -f "${destFile}" && (${config.cmd} 2>/dev/null || true)`;
+  
+  try {
+    await execWithPassword(cmd, sudoPassword);
+    log("🔐 Cert: ✅ uninstalled from Linux trust store and user browser databases");
+  } catch (error) {
+    throw new Error("Failed to uninstall certificate");
+  }
+}
+
+module.exports = { installCert, uninstallCert, checkCertInstalled };
diff --git a/src/mitm/cert/rootCA.js b/src/mitm/cert/rootCA.js
new file mode 100644
index 0000000..3f033f0
--- /dev/null
+++ b/src/mitm/cert/rootCA.js
@@ -0,0 +1,173 @@
+const path = require("path");
+const fs = require("fs");
+const forge = require("node-forge");
+const { MITM_DIR } = require("../paths");
+
+const ROOT_CA_KEY_PATH = path.join(MITM_DIR, "rootCA.key");
+const ROOT_CA_CERT_PATH = path.join(MITM_DIR, "rootCA.crt");
+
+/**
+ * Check if cert file is expired or expiring within 30 days
+ */
+function isCertExpired(certPath) {
+  try {
+    const cert = forge.pki.certificateFromPem(fs.readFileSync(certPath, "utf8"));
+    const expiryThreshold = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+    return cert.validity.notAfter < expiryThreshold;
+  } catch {
+    return true; // treat unreadable cert as expired
+  }
+}
+
+/**
+ * Generate Root CA certificate (only once, auto-regenerate if expired)
+ * This Root CA will sign all dynamic leaf certificates
+ */
+function generateRootCA() {
+  const exists = fs.existsSync(ROOT_CA_KEY_PATH) && fs.existsSync(ROOT_CA_CERT_PATH);
+  if (exists && !isCertExpired(ROOT_CA_CERT_PATH)) {
+    console.log("✅ Root CA already exists");
+    return { key: ROOT_CA_KEY_PATH, cert: ROOT_CA_CERT_PATH };
+  }
+  if (exists) {
+    console.log("🔐 Root CA expired or expiring soon — regenerating...");
+    try { fs.unlinkSync(ROOT_CA_KEY_PATH); } catch { /* ignore */ }
+    try { fs.unlinkSync(ROOT_CA_CERT_PATH); } catch { /* ignore */ }
+  }
+
+  if (!fs.existsSync(MITM_DIR)) {
+    fs.mkdirSync(MITM_DIR, { recursive: true });
+  }
+
+  console.log("🔐 Generating Root CA certificate...");
+
+  // Generate RSA key pair
+  const keys = forge.pki.rsa.generateKeyPair(2048);
+
+  // Create Root CA certificate
+  const cert = forge.pki.createCertificate();
+  cert.publicKey = keys.publicKey;
+  cert.serialNumber = "01";
+  cert.validity.notBefore = new Date();
+  cert.validity.notAfter = new Date();
+  cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 10);
+
+  const attrs = [
+    { name: "commonName", value: "9Router MITM Root CA" },
+    { name: "organizationName", value: "9Router" },
+    { name: "countryName", value: "US" }
+  ];
+
+  cert.setSubject(attrs);
+  cert.setIssuer(attrs); // Self-signed
+
+  cert.setExtensions([
+    {
+      name: "basicConstraints",
+      cA: true,
+      critical: true
+    },
+    {
+      name: "keyUsage",
+      keyCertSign: true,
+      cRLSign: true,
+      critical: true
+    },
+    {
+      name: "subjectKeyIdentifier"
+    }
+  ]);
+
+  // Self-sign the certificate
+  cert.sign(keys.privateKey, forge.md.sha256.create());
+
+  // Save to disk
+  const privateKeyPem = forge.pki.privateKeyToPem(keys.privateKey);
+  const certPem = forge.pki.certificateToPem(cert);
+
+  fs.writeFileSync(ROOT_CA_KEY_PATH, privateKeyPem);
+  fs.writeFileSync(ROOT_CA_CERT_PATH, certPem);
+
+  console.log("✅ Root CA generated successfully");
+  return { key: ROOT_CA_KEY_PATH, cert: ROOT_CA_CERT_PATH };
+}
+
+/**
+ * Load Root CA from disk
+ */
+function loadRootCA() {
+  if (!fs.existsSync(ROOT_CA_KEY_PATH) || !fs.existsSync(ROOT_CA_CERT_PATH)) {
+    throw new Error("Root CA not found. Generate it first.");
+  }
+
+  const keyPem = fs.readFileSync(ROOT_CA_KEY_PATH, "utf8");
+  const certPem = fs.readFileSync(ROOT_CA_CERT_PATH, "utf8");
+
+  return {
+    key: forge.pki.privateKeyFromPem(keyPem),
+    cert: forge.pki.certificateFromPem(certPem)
+  };
+}
+
+/**
+ * Generate leaf certificate for a specific domain, signed by Root CA
+ */
+function generateLeafCert(domain, rootCA) {
+  // Generate key pair for leaf cert
+  const keys = forge.pki.rsa.generateKeyPair(2048);
+
+  // Create leaf certificate
+  const cert = forge.pki.createCertificate();
+  cert.publicKey = keys.publicKey;
+  cert.serialNumber = Math.floor(Math.random() * 1000000).toString();
+  cert.validity.notBefore = new Date();
+  cert.validity.notAfter = new Date();
+  cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 1);
+
+  cert.setSubject([
+    { name: "commonName", value: domain }
+  ]);
+
+  cert.setIssuer(rootCA.cert.subject.attributes);
+
+  cert.setExtensions([
+    {
+      name: "basicConstraints",
+      cA: false
+    },
+    {
+      name: "keyUsage",
+      digitalSignature: true,
+      keyEncipherment: true
+    },
+    {
+      name: "extKeyUsage",
+      serverAuth: true,
+      clientAuth: true
+    },
+    {
+      name: "subjectAltName",
+      altNames: [
+        { type: 2, value: domain }, // DNS
+        { type: 2, value: `*.${domain}` } // Wildcard
+      ]
+    }
+  ]);
+
+  // Sign with Root CA
+  cert.sign(rootCA.key, forge.md.sha256.create());
+
+  return {
+    key: forge.pki.privateKeyToPem(keys.privateKey),
+    cert: forge.pki.certificateToPem(cert)
+  };
+}
+
+module.exports = {
+  generateRootCA,
+  loadRootCA,
+  generateLeafCert,
+  isCertExpired,
+  ROOT_CA_CERT_PATH,
+  ROOT_CA_KEY_PATH
+};
diff --git a/src/mitm/config.js b/src/mitm/config.js
new file mode 100644
index 0000000..e109ec9
--- /dev/null
+++ b/src/mitm/config.js
@@ -0,0 +1,89 @@
+// All intercepted domains + URL patterns per tool
+
+const fs = require("fs");
+
+const IS_DEV = process.env.NODE_ENV === "development";
+
+// Resolve lsof absolute path — packaged apps / sudo secure_path may strip /usr/sbin from PATH
+const LSOF_BIN = (() => {
+  if (process.platform === "win32") return null;
+  for (const p of ["/usr/sbin/lsof", "/usr/bin/lsof", "/sbin/lsof"]) {
+    try { fs.accessSync(p, fs.constants.X_OK); return p; } catch { /* try next */ }
+  }
+  return "lsof"; // last-resort fallback (depends on PATH)
+})();
+
+const TARGET_HOSTS = [
+  "daily-cloudcode-pa.googleapis.com",
+  "cloudcode-pa.googleapis.com",
+  "api.individual.githubcopilot.com",
+  "q.us-east-1.amazonaws.com",
+  "codewhisperer.us-east-1.amazonaws.com",
+  "runtime.us-east-1.kiro.dev",
+  "api2.cursor.sh",
+];
+
+const URL_PATTERNS = {
+  antigravity: [":generateContent", ":streamGenerateContent"],
+  copilot: ["/chat/completions", "/v1/messages", "/responses"],
+  kiro: ["/generateAssistantResponse"],
+  cursor: ["/BidiAppend", "/RunSSE", "/RunPoll", "/Run"],
+};
+
+// Synonym map: rawModel from request → canonical alias key in mitmAlias DB
+const MODEL_SYNONYMS = {
+  antigravity: {
+    "gemini-default": "gemini-3.5-flash-low",
+    "gemini-3.5-flash-high": "gemini-3-flash-agent",
+    "gemini-3.5-flash-medium": "gemini-3.5-flash-low",
+    "gemini-3.5-flash-extra-low": "gemini-3.5-flash-extra-low",
+    "gemini-3.1-pro-high": "gemini-pro-agent",
+    "gemini-3-pro-high": "gemini-pro-agent",
+    "gemini-3-pro-low": "gemini-3.1-pro-low",
+  },
+};
+
+// Pattern fallback: rawModel regex → canonical alias key (when exact + prefix match fail)
+// Order matters: more specific patterns first. Catches AG renamed variants (e.g. gemini-pro-agent)
+const MODEL_PATTERNS = {
+  antigravity: [
+    { match: /flash.*extra.*low|extra.*low.*flash|flash.*low|low.*flash/i, alias: "gemini-3.5-flash-extra-low" },
+    { match: /flash.*medium|medium.*flash/i,                       alias: "gemini-3.5-flash-low" },
+    { match: /flash.*agent|agent.*flash|flash/i,                   alias: "gemini-3-flash-agent" },
+    { match: /pro.*low|low.*pro/i,                                 alias: "gemini-3.1-pro-low" },
+    { match: /gemini.*pro|pro.*gemini/i,                           alias: "gemini-pro-agent" },
+    { match: /opus/i,                                              alias: "claude-opus-4-6-thinking" },
+    { match: /sonnet|claude/i,                                     alias: "claude-sonnet-4-6" },
+    { match: /gpt.*oss|oss/i,                                      alias: "gpt-oss-120b-medium" },
+  ],
+};
+
+// Models that must NEVER be re-routed — always passthrough to the real upstream, even when
+// the tool's other models are mapped. Antigravity's tab-autocomplete (`tab_jump_flash_lite_preview`,
+// `tab_flash_lite_preview`, requestType tab/tab_jump) is latency-critical inline completion; routing
+// it through 9Router to an external chat model makes typing laggy and burns provider quota per
+// keystroke. Without this guard the broad `flash` pattern in MODEL_PATTERNS hijacks them onto the
+// flash-agent slot. Verified via MITM dump capture of streamGenerateContent (see AI_JOURNAL).
+const MODEL_NO_MAP = {
+  antigravity: [/^tab[_-]/i],
+};
+
+// URL substrings whose request/response should NOT be dumped to file (telemetry, polling, empty)
+const LOG_BLACKLIST_URL_PARTS = [
+  "recordCodeAssistMetrics",
+  "recordTrajectoryAnalytics",
+  "fetchAdminControls",
+  "listExperiments",
+  "fetchUserInfo",
+];
+
+function getToolForHost(host) {
+  const h = (host || "").split(":")[0];
+  if (h === "api.individual.githubcopilot.com") return "copilot";
+  if (h === "daily-cloudcode-pa.googleapis.com" || h === "cloudcode-pa.googleapis.com") return "antigravity";
+  if (h === "q.us-east-1.amazonaws.com" || h === "codewhisperer.us-east-1.amazonaws.com" || h === "runtime.us-east-1.kiro.dev") return "kiro";
+  if (h === "api2.cursor.sh") return "cursor";
+  return null;
+}
+
+module.exports = { IS_DEV, LSOF_BIN, TARGET_HOSTS, URL_PATTERNS, MODEL_SYNONYMS, MODEL_PATTERNS, MODEL_NO_MAP, LOG_BLACKLIST_URL_PARTS, getToolForHost };
diff --git a/src/mitm/dbReader.js b/src/mitm/dbReader.js
new file mode 100644
index 0000000..7133947
--- /dev/null
+++ b/src/mitm/dbReader.js
@@ -0,0 +1,22 @@
+// CJS reader for MITM standalone process. Reads mitmAlias from JSON cache
+// at $DATA_DIR/mitm/aliases.json (synced by app from SQLite on startup + writes).
+// JSON-only: no SQLite native binding required in MITM bundle.
+const fs = require("fs");
+const path = require("path");
+const { DATA_DIR } = require("./paths");
+
+const CACHE_FILE = path.join(DATA_DIR, "mitm", "aliases.json");
+
+function readCache() {
+  try {
+    if (!fs.existsSync(CACHE_FILE)) return null;
+    return JSON.parse(fs.readFileSync(CACHE_FILE, "utf-8"));
+  } catch { return null; }
+}
+
+function getMitmAlias(toolName) {
+  const all = readCache();
+  return all?.[toolName] || null;
+}
+
+module.exports = { getMitmAlias };
diff --git a/src/mitm/dns/dnsConfig.js b/src/mitm/dns/dnsConfig.js
new file mode 100644
index 0000000..ae1568a
--- /dev/null
+++ b/src/mitm/dns/dnsConfig.js
@@ -0,0 +1,266 @@
+const { exec, spawn, execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { log, err } = require("../logger");
+const { TOOL_HOSTS } = require("../../shared/constants/mitmToolHosts.js");
+const { runElevatedPowerShell, isAdmin } = require("../winElevated.js");
+
+/**
+ * Atomic-ish write for Windows hosts file with rollback on failure.
+ * Strategy: write `.new` sibling → rename current to `.bak` → rename `.new` to target.
+ * If anything fails mid-way, restore from `.bak`. Same-volume renames are atomic on NTFS.
+ */
+function atomicWriteHostsWin(target, originalContent, newContent) {
+  const tmpNew = `${target}.9router.new`;
+  const tmpBak = `${target}.9router.bak`;
+  try {
+    fs.writeFileSync(tmpNew, newContent, "utf8");
+    try { fs.unlinkSync(tmpBak); } catch { /* none */ }
+    fs.renameSync(target, tmpBak);
+    try {
+      fs.renameSync(tmpNew, target);
+    } catch (e) {
+      // Rollback: restore original
+      try { fs.renameSync(tmpBak, target); } catch { fs.writeFileSync(target, originalContent, "utf8"); }
+      throw e;
+    }
+    try { fs.unlinkSync(tmpBak); } catch { /* best effort */ }
+  } finally {
+    try { fs.unlinkSync(tmpNew); } catch { /* already moved or never created */ }
+  }
+}
+
+const IS_WIN = process.platform === "win32";
+const IS_MAC = process.platform === "darwin";
+const HOSTS_FILE = IS_WIN
+  ? path.join(process.env.SystemRoot || "C:\\Windows", "System32", "drivers", "etc", "hosts")
+  : "/etc/hosts";
+
+/** True when `sudo` exists (e.g. missing on minimal Docker images like Alpine). */
+function isSudoAvailable() {
+  if (IS_WIN) return false;
+  try {
+    execSync("command -v sudo", { stdio: "ignore", windowsHide: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function canRunSudoWithoutPassword() {
+  if (IS_WIN || !isSudoAvailable()) return true;
+  try {
+    execSync("sudo -n true", { stdio: "ignore", windowsHide: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isSudoPasswordRequired() {
+  return !IS_WIN && isSudoAvailable() && !canRunSudoWithoutPassword();
+}
+
+/**
+ * Execute command with sudo password via stdin (macOS/Linux only).
+ * Without sudo in PATH (containers), runs via sh — same user, no elevation.
+ */
+function execWithPassword(command, password) {
+  return new Promise((resolve, reject) => {
+    const useSudo = isSudoAvailable();
+    const child = useSudo
+      ? spawn("sudo", ["-S", "sh", "-c", command], { stdio: ["pipe", "pipe", "pipe"], windowsHide: true })
+      : spawn("sh", ["-c", command], { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => { stdout += d; });
+    child.stderr.on("data", (d) => { stderr += d; });
+
+    child.on("close", (code) => {
+      if (code === 0) resolve(stdout);
+      else reject(new Error(stderr || `Exit code ${code}`));
+    });
+
+    if (useSudo) {
+      child.stdin.write(`${password}\n`);
+      child.stdin.end();
+    }
+  });
+}
+
+/**
+ * Trim trailing blank lines/whitespace, ensure file ends with exactly one newline.
+ */
+function normalizeHostsContent(content) {
+  const eol = IS_WIN ? "\r\n" : "\n";
+  return content.replace(/[\r\n\s]+$/g, "") + eol;
+}
+
+/**
+ * Flush DNS cache (macOS/Linux)
+ */
+async function flushDNS(sudoPassword) {
+  if (IS_WIN) return; // Windows flushes inline via ipconfig
+  if (IS_MAC) {
+    await execWithPassword("dscacheutil -flushcache && killall -HUP mDNSResponder", sudoPassword);
+  } else {
+    await execWithPassword("resolvectl flush-caches 2>/dev/null || true", sudoPassword);
+  }
+}
+
+/**
+ * Check if DNS entry exists for a specific host
+ */
+function checkDNSEntry(host = null) {
+  try {
+    const hostsContent = fs.readFileSync(HOSTS_FILE, "utf8");
+    if (host) return hostsContent.includes(host);
+    // Legacy: check all antigravity hosts (backward compat)
+    return TOOL_HOSTS.antigravity.every(h => hostsContent.includes(h));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check DNS status per tool — returns { [tool]: boolean }
+ */
+function checkAllDNSStatus() {
+  try {
+    const hostsContent = fs.readFileSync(HOSTS_FILE, "utf8");
+    const result = {};
+    for (const [tool, hosts] of Object.entries(TOOL_HOSTS)) {
+      result[tool] = hosts.every(h => hostsContent.includes(h));
+    }
+    return result;
+  } catch {
+    return Object.fromEntries(Object.keys(TOOL_HOSTS).map(t => [t, false]));
+  }
+}
+
+/**
+ * Add DNS entries for a specific tool
+ */
+async function addDNSEntry(tool, sudoPassword) {
+  const hosts = TOOL_HOSTS[tool];
+  if (!hosts) throw new Error(`Unknown tool: ${tool}`);
+
+  const entriesToAdd = hosts.filter(h => !checkDNSEntry(h));
+  if (entriesToAdd.length === 0) {
+    log(`🌐 DNS ${tool}: already active`);
+    return;
+  }
+
+  try {
+    if (IS_WIN) {
+      // Read → trim → append → atomic write (Node-side, no CLI size limit)
+      const current = fs.readFileSync(HOSTS_FILE, "utf8");
+      const trimmed = current.replace(/[\r\n\s]+$/g, "");
+      const toAppend = entriesToAdd.map(h => `127.0.0.1 ${h}`).join("\r\n");
+      const next = `${trimmed}\r\n${toAppend}\r\n`;
+      atomicWriteHostsWin(HOSTS_FILE, current, next);
+      await runElevatedPowerShell("ipconfig /flushdns | Out-Null");
+    } else {
+      const current = fs.readFileSync(HOSTS_FILE, "utf8");
+      const trimmed = current.replace(/[\r\n\s]+$/g, "");
+      const toAppend = entriesToAdd.map(h => `127.0.0.1 ${h}`).join("\n");
+      const next = `${trimmed}\n${toAppend}\n`;
+      // Use tee via sudo to overwrite atomically — escape single quotes in content
+      const escaped = next.replace(/'/g, "'\\''");
+      await execWithPassword(`printf '%s' '${escaped}' | tee ${HOSTS_FILE} > /dev/null`, sudoPassword);
+      await flushDNS(sudoPassword);
+    }
+    log(`🌐 DNS ${tool}: ✅ added ${entriesToAdd.join(", ")}`);
+  } catch (error) {
+    const msg = error.message?.includes("incorrect password") ? "Wrong sudo password" : `Failed to add DNS entry: ${error.message}`;
+    throw new Error(msg);
+  }
+}
+
+/**
+ * Remove DNS entries for a specific tool
+ */
+async function removeDNSEntry(tool, sudoPassword) {
+  const hosts = TOOL_HOSTS[tool];
+  if (!hosts) throw new Error(`Unknown tool: ${tool}`);
+
+  const entriesToRemove = hosts.filter(h => checkDNSEntry(h));
+  if (entriesToRemove.length === 0) {
+    log(`🌐 DNS ${tool}: already inactive`);
+    return;
+  }
+
+  try {
+    if (IS_WIN) {
+      const current = fs.readFileSync(HOSTS_FILE, "utf8");
+      const filtered = current.split(/\r?\n/).filter(l => !entriesToRemove.some(h => l.includes(h))).join("\r\n");
+      const next = filtered.replace(/[\r\n\s]+$/g, "") + "\r\n";
+      atomicWriteHostsWin(HOSTS_FILE, current, next);
+      await runElevatedPowerShell("ipconfig /flushdns | Out-Null");
+    } else {
+      const current = fs.readFileSync(HOSTS_FILE, "utf8");
+      const filtered = current.split(/\r?\n/).filter(l => !entriesToRemove.some(h => l.includes(h))).join("\n");
+      const next = filtered.replace(/[\r\n\s]+$/g, "") + "\n";
+      const escaped = next.replace(/'/g, "'\\''");
+      await execWithPassword(`printf '%s' '${escaped}' | tee ${HOSTS_FILE} > /dev/null`, sudoPassword);
+      await flushDNS(sudoPassword);
+    }
+    log(`🌐 DNS ${tool}: ✅ removed ${entriesToRemove.join(", ")}`);
+  } catch (error) {
+    const msg = error.message?.includes("incorrect password") ? "Wrong sudo password" : `Failed to remove DNS entry: ${error.message}`;
+    throw new Error(msg);
+  }
+}
+
+/**
+ * Remove ALL tool DNS entries (used when stopping server)
+ */
+async function removeAllDNSEntries(sudoPassword) {
+  for (const tool of Object.keys(TOOL_HOSTS)) {
+    try {
+      await removeDNSEntry(tool, sudoPassword);
+    } catch (e) {
+      err(`DNS ${tool}: failed to remove — ${e.message}`);
+    }
+  }
+}
+
+/**
+ * Sync removal of ALL tool DNS entries — for use during process shutdown
+ * when async ops aren't safe. Assumes caller already has root/admin rights.
+ */
+function removeAllDNSEntriesSync() {
+  try {
+    if (!fs.existsSync(HOSTS_FILE)) return;
+    const allHosts = Object.values(TOOL_HOSTS).flat();
+    const content = fs.readFileSync(HOSTS_FILE, "utf8");
+    const eol = IS_WIN ? "\r\n" : "\n";
+    const filtered = content.split(/\r?\n/).filter(l => !allHosts.some(h => l.includes(h))).join(eol);
+    const next = filtered.replace(/[\r\n\s]+$/g, "") + eol;
+    if (next === content) return;
+    fs.writeFileSync(HOSTS_FILE, next, "utf8");
+    if (IS_WIN) {
+      try { execSync("ipconfig /flushdns", { windowsHide: true, stdio: "ignore" }); } catch { /* ignore */ }
+    } else if (IS_MAC) {
+      try { execSync("dscacheutil -flushcache && killall -HUP mDNSResponder", { stdio: "ignore" }); } catch { /* ignore */ }
+    } else {
+      try { execSync("resolvectl flush-caches 2>/dev/null || true", { stdio: "ignore" }); } catch { /* ignore */ }
+    }
+  } catch { /* best effort during shutdown */ }
+}
+
+module.exports = {
+  TOOL_HOSTS,
+  addDNSEntry,
+  removeDNSEntry,
+  removeAllDNSEntries,
+  removeAllDNSEntriesSync,
+  execWithPassword,
+  isSudoAvailable,
+  canRunSudoWithoutPassword,
+  isSudoPasswordRequired,
+  checkDNSEntry,
+  checkAllDNSStatus,
+};
diff --git a/src/mitm/handlers/antigravity.js b/src/mitm/handlers/antigravity.js
new file mode 100644
index 0000000..aa9273f
--- /dev/null
+++ b/src/mitm/handlers/antigravity.js
@@ -0,0 +1,33 @@
+const { err, createResponseDumper } = require("../logger");
+const { IS_DEV } = require("../config");
+const { fetchRouter, pipeSSE } = require("./base");
+
+/**
+ * Intercept Antigravity request — forward Gemini body as-is to /v1/chat/completions.
+ * Router auto-detects format via body.userAgent==="antigravity" + body.request.contents,
+ * runs antigravity→openai→provider→openai→antigravity translators internally.
+ */
+async function intercept(req, res, bodyBuffer, mappedModel) {
+  const dumper = IS_DEV ? createResponseDumper(req, "intercept-antigravity") : null;
+  const isStream = req.url.includes(":streamGenerateContent");
+  try {
+    const body = JSON.parse(bodyBuffer.toString());
+    if (body.model) body.model = mappedModel;
+
+    const routerRes = await fetchRouter(body, "/v1/chat/completions", req.headers);
+    await pipeSSE(routerRes, res, dumper);
+  } catch (error) {
+    err(`[antigravity] ${error.message}`);
+    if (dumper) { dumper.writeChunk(`\n[ERROR] ${error.message}\n`); dumper.end(); }
+    // For stream endpoint, send SSE error chunk so SDK doesn't hang waiting
+    if (isStream) {
+      if (!res.headersSent) res.writeHead(200, { "Content-Type": "text/event-stream" });
+      res.end(`data: ${JSON.stringify({ error: { message: error.message } })}\r\n\r\n`);
+    } else {
+      if (!res.headersSent) res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: { message: error.message, type: "mitm_error" } }));
+    }
+  }
+}
+
+module.exports = { intercept };
diff --git a/src/mitm/handlers/base.js b/src/mitm/handlers/base.js
new file mode 100644
index 0000000..5f2d3d1
--- /dev/null
+++ b/src/mitm/handlers/base.js
@@ -0,0 +1,226 @@
+const { log, err } = require("../logger");
+
+const DEFAULT_LOCAL_ROUTER = "http://localhost:20128";
+const ROUTER_BASE = String(process.env.MITM_ROUTER_BASE || DEFAULT_LOCAL_ROUTER)
+  .trim()
+  .replace(/\/+$/, "") || DEFAULT_LOCAL_ROUTER;
+const API_KEY = process.env.ROUTER_API_KEY;
+
+// Headers that must not be forwarded to 9Router
+const STRIP_HEADERS = new Set([
+  "host", "content-length", "connection", "transfer-encoding",
+  "content-type", "authorization"
+]);
+
+/**
+ * Send body to 9Router at the given path and return the fetch Response object.
+ * Optionally forwards client headers (stripped of hop-by-hop / overridden keys).
+ */
+async function fetchRouter(openaiBody, path = "/v1/chat/completions", clientHeaders = {}) {
+  const forwarded = {};
+  for (const [k, v] of Object.entries(clientHeaders)) {
+    if (!STRIP_HEADERS.has(k.toLowerCase())) forwarded[k] = v;
+  }
+
+  const response = await fetch(`${ROUTER_BASE}${path}`, {
+    method: "POST",
+    headers: {
+      ...forwarded,
+      "Content-Type": "application/json",
+      ...(API_KEY && { "Authorization": `Bearer ${API_KEY}` })
+    },
+    body: JSON.stringify(openaiBody)
+  });
+
+  // Forward response as-is (status + body). pipeSSE will propagate status.
+  return response;
+}
+
+/**
+ * Pipe SSE stream from router directly to client response.
+ * Optional dumper tees the stream into a debug file.
+ */
+async function pipeSSE(routerRes, res, dumper) {
+  const ct = routerRes.headers.get("content-type") || "application/json";
+  const status = routerRes.status || 200;
+  const resHeaders = { "Content-Type": ct, "Cache-Control": "no-cache", "Connection": "keep-alive" };
+  if (ct.includes("text/event-stream")) resHeaders["X-Accel-Buffering"] = "no";
+  res.writeHead(status, resHeaders);
+  if (dumper) dumper.writeHeader(routerRes.status, Object.fromEntries(routerRes.headers));
+
+  if (!routerRes.body) {
+    const text = await routerRes.text().catch(() => "");
+    if (dumper) { dumper.writeChunk(text); dumper.end(); }
+    res.end(text);
+    return;
+  }
+
+  const reader = routerRes.body.getReader();
+  const decoder = new TextDecoder();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) { if (dumper) dumper.end(); res.end(); break; }
+    if (dumper) dumper.writeChunk(value);
+    res.write(decoder.decode(value, { stream: true }));
+  }
+}
+
+/**
+ * Pipe SSE stream from router, transforming each chunk through a user function.
+ * Reads SSE data: lines, parses JSON, calls transformFn(parsed, state),
+ * and writes returned SSE strings to the client response.
+ *
+ * @param {Response} routerRes - Fetch Response from 9Router
+ * @param {http.ServerResponse} res - Client response
+ * @param {Function} transformFn - (parsedChunk, state) => string|string[]|null
+ * @param {object} state - Mutable state object shared across chunks and flush
+ */
+async function pipeTransformedSSE(routerRes, res, transformFn, state) {
+  const ct = routerRes.headers.get("content-type") || "application/json";
+  const resHeaders = { "Content-Type": ct, "Cache-Control": "no-cache", "Connection": "keep-alive" };
+  if (ct.includes("text/event-stream")) resHeaders["X-Accel-Buffering"] = "no";
+  res.writeHead(200, resHeaders);
+
+  if (!routerRes.body) {
+    res.end(await routerRes.text().catch(() => ""));
+    return;
+  }
+
+  const reader = routerRes.body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() || "";
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || !trimmed.startsWith("data:")) continue;
+
+      const data = trimmed.slice(5).trim();
+      if (data === "[DONE]") continue;
+
+      if (process.env.DEBUG_MITM) {
+        log(`[SSE in] ${data.slice(0, 200)}`);
+      }
+
+      try {
+        const parsed = JSON.parse(data);
+        const result = transformFn(parsed, state);
+        if (result != null) {
+          const outputs = Array.isArray(result) ? result : [result];
+          for (const output of outputs) {
+            if (process.env.DEBUG_MITM) {
+              const len = output.length || output.byteLength || 0;
+              log(`[write binary frame] (${len}B) first 20B: ${Array.from(output.slice(0, 20)).join(',')}`);
+            }
+            res.write(Buffer.from(output));
+          }
+        }
+      } catch {
+        // Skip unparseable lines
+      }
+    }
+  }
+
+  // Flush: pass null to signal stream end
+  try {
+    const flushed = transformFn(null, state);
+    if (flushed != null) {
+      const outputs = Array.isArray(flushed) ? flushed : [flushed];
+      for (const output of outputs) {
+        res.write(output);
+      }
+    }
+  } catch { /* ignore flush errors */ }
+
+  res.end();
+}
+
+/**
+ * Pipe SSE stream from router, transforming each chunk through a user function,
+ * and writing binary EventStream frames to the client.
+ *
+ * Reads SSE data: lines, parses JSON, calls transformFn(parsed, state),
+ * and writes returned Uint8Array frames to the client response.
+ *
+ * @param {Response} routerRes - Fetch Response from 9Router
+ * @param {http.ServerResponse} res - Client response
+ * @param {Function} transformFn - (parsedChunk, state) => Uint8Array|Uint8Array[]|null
+ * @param {object} state - Mutable state object shared across chunks and flush
+ */
+async function pipeTransformedEventStream(routerRes, res, transformFn, state) {
+  const resHeaders = {
+    "Content-Type": "application/vnd.amazon.eventstream",
+    "Cache-Control": "no-cache",
+    "Connection": "keep-alive"
+  };
+  res.writeHead(200, resHeaders);
+
+  if (!routerRes.body) {
+    res.end(await routerRes.text().catch(() => ""));
+    return;
+  }
+
+  const reader = routerRes.body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() || "";
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || !trimmed.startsWith("data:")) continue;
+
+      const data = trimmed.slice(5).trim();
+      if (data === "[DONE]") continue;
+
+      if (process.env.DEBUG_MITM) {
+        log(`[SSE in] ${data.slice(0, 200)}`);
+      }
+
+      try {
+        const parsed = JSON.parse(data);
+        const result = transformFn(parsed, state);
+        if (result != null) {
+          const outputs = Array.isArray(result) ? result : [result];
+          for (const output of outputs) {
+            if (process.env.DEBUG_MITM) {
+              const len = output.length || output.byteLength || 0;
+              log(`[write binary frame] (${len}B) first 20B: ${Array.from(output.slice(0, 20)).join(',')}`);
+            }
+            res.write(Buffer.from(output));
+          }
+        }
+      } catch {
+        // Skip unparseable lines
+      }
+    }
+  }
+
+  // Flush: pass null to signal stream end
+  try {
+    const flushed = transformFn(null, state);
+    if (flushed != null) {
+      const outputs = Array.isArray(flushed) ? flushed : [flushed];
+      for (const output of outputs) {
+        res.write(output);
+      }
+    }
+  } catch { /* ignore flush errors */ }
+
+  res.end();
+}
+
+module.exports = { fetchRouter, pipeSSE, pipeTransformedSSE, pipeTransformedEventStream };
\ No newline at end of file
diff --git a/src/mitm/handlers/copilot.js b/src/mitm/handlers/copilot.js
new file mode 100644
index 0000000..cf6a920
--- /dev/null
+++ b/src/mitm/handlers/copilot.js
@@ -0,0 +1,35 @@
+const { err } = require("../logger");
+const { fetchRouter, pipeSSE } = require("./base");
+
+// Map Copilot endpoint → 9Router path
+const URL_MAP = {
+  "/chat/completions": "/v1/chat/completions",
+  "/v1/messages":      "/v1/messages",
+  "/responses":        "/v1/responses",
+};
+
+function resolveRouterPath(reqUrl) {
+  for (const [pattern, routerPath] of Object.entries(URL_MAP)) {
+    if (reqUrl.includes(pattern)) return routerPath;
+  }
+  return "/v1/chat/completions";
+}
+
+/**
+ * Intercept Copilot request — replace model and forward to matching 9Router endpoint
+ */
+async function intercept(req, res, bodyBuffer, mappedModel) {
+  try {
+    const body = JSON.parse(bodyBuffer.toString());
+    body.model = mappedModel;
+    const routerPath = resolveRouterPath(req.url);
+    const routerRes = await fetchRouter(body, routerPath, req.headers);
+    await pipeSSE(routerRes, res);
+  } catch (error) {
+    err(`[copilot] ${error.message}`);
+    if (!res.headersSent) res.writeHead(500, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { message: error.message, type: "mitm_error" } }));
+  }
+}
+
+module.exports = { intercept };
diff --git a/src/mitm/handlers/cursor.js b/src/mitm/handlers/cursor.js
new file mode 100644
index 0000000..0f38663
--- /dev/null
+++ b/src/mitm/handlers/cursor.js
@@ -0,0 +1,15 @@
+/**
+ * Cursor MITM handler — coming soon
+ * This feature is currently under development.
+ */
+async function intercept(req, res) {
+  res.writeHead(501, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({
+    error: {
+      message: "Cursor MITM support is coming soon.",
+      type: "not_implemented"
+    }
+  }));
+}
+
+module.exports = { intercept };
diff --git a/src/mitm/handlers/kiro.js b/src/mitm/handlers/kiro.js
new file mode 100644
index 0000000..b453d2c
--- /dev/null
+++ b/src/mitm/handlers/kiro.js
@@ -0,0 +1,526 @@
+const { err } = require("../logger");
+const { IS_DEV } = require("../config");
+const { fetchRouter, pipeTransformedEventStream } = require("./base");
+const fs = require("fs");
+const path = require("path");
+
+// Debug trace log — written to data/logs/mitm/kiro-debug.log (dev only)
+const DEBUG_LOG = path.join(__dirname, "../../../data/logs/mitm/kiro-debug.log");
+function dbg(msg) {
+  if (!IS_DEV) return;
+  try {
+    fs.appendFileSync(DEBUG_LOG, `${new Date().toISOString()} ${msg}\n`);
+  } catch {}
+}
+
+// ─── CRC32 (standard, polynomial 0xEDB88320 — same as AWS EventStream) ───────
+const CRC32_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c;
+  }
+  return t;
+})();
+
+function crc32(buf) {
+  let crc = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) {
+    crc = (crc >>> 8) ^ CRC32_TABLE[(crc ^ buf[i]) & 0xff];
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/**
+ * Initialize state for the Kiro response translator
+ */
+function initKiroState(modelId) {
+  return {
+    modelId: modelId || null,       // Model name from first chunk
+    toolCallInit: {},               // { [index]: { id, name } } — tracks seen tools
+    hasToolCalls: false,           // Whether this response uses tool calls
+    finishSent: false,             // Whether termination has been emitted
+    usage: null,                   // Accumulated usage from usage-only chunks
+    inThink: false,                // Whether inside a <thinking> block
+    thinkBuf: ""                   // Buffer for partial thinking content
+  };
+}
+
+/**
+ * Extract thinking blocks from text content.
+ * Handles both <thinking>...</thinking> and <think>...</think> tags,
+ * including partial tags split across SSE chunks.
+ */
+function extractThinking(text, state) {
+  if (!text) return { thinking: null, text: null };
+
+  let working = text;
+
+  // Prepend buffered partial thinking from previous chunk
+  if (state.inThink && state.thinkBuf) {
+    working = state.thinkBuf + working;
+    state.thinkBuf = "";
+    state.inThink = false;
+  }
+
+  // Match <thinking> or <think> opening tags
+  const startRe = /<thinking>|<think>/i;
+  const startMatch = working.match(startRe);
+
+  if (!startMatch) {
+    return { thinking: null, text: working };
+  }
+
+  const tag = startMatch[0].toLowerCase();
+  const closeTag = tag === "<think>" ? "</think>" : "</thinking>";
+  const startIdx = startMatch.index;
+  const endIdx = working.indexOf(closeTag, startIdx + tag.length);
+
+  if (endIdx === -1) {
+    // Opening tag without closing — buffer for next chunk
+    state.inThink = true;
+    state.thinkBuf = working.slice(startIdx);
+    const before = working.slice(0, startIdx).trim();
+    return { thinking: null, text: before || null };
+  }
+
+  // Complete block found
+  const thinking = working.slice(startIdx + tag.length, endIdx);
+  const before = working.slice(0, startIdx).trim();
+  const after = working.slice(endIdx + closeTag.length).trim();
+  const rest = [before, after].filter(Boolean).join("");
+
+  // Recursively process for more blocks
+  const recurse = rest
+    ? extractThinking(rest, { inThink: false, thinkBuf: "" })
+    : { thinking: null, text: null };
+
+  return {
+    thinking: thinking || null,
+    text: recurse.text || null
+  };
+}
+
+// ─── AWS EventStream frame builder ────────────────────────────────────────────
+/**
+ * Encode a single string header into the AWS EventStream binary format.
+ * Header wire format: [nameLen 1B][name][type=7 1B][valueLen 2B][value]
+ */
+function encodeHeader(name, value) {
+  const nameBuf = Buffer.from(name, "utf8");
+  const valueBuf = Buffer.from(value, "utf8");
+  const buf = Buffer.alloc(1 + nameBuf.length + 1 + 2 + valueBuf.length);
+  let o = 0;
+  buf[o++] = nameBuf.length;
+  nameBuf.copy(buf, o); o += nameBuf.length;
+  buf[o++] = 7; // string type
+  buf.writeUInt16BE(valueBuf.length, o); o += 2;
+  valueBuf.copy(buf, o);
+  return buf;
+}
+
+/**
+ * Build a single AWS EventStream binary frame with all Smithy-required headers.
+ *
+ * Frame layout (big-endian):
+ *   [totalLen 4B][headersLen 4B][preludeCRC 4B]
+ *   [headers ...][payload JSON ...][messageCRC 4B]
+ *
+ * The SmithyMessageDecoderStream layer requires three system headers on every frame:
+ *   :message-type  = "event"             (or "exception" / "error")
+ *   :event-type    = e.g. "assistantResponseEvent"
+ *   :content-type  = "application/json"
+ */
+function buildEventStreamFrame(eventType, payload) {
+  const payloadBuf = Buffer.from(
+    typeof payload === "string" ? payload : JSON.stringify(payload),
+    "utf8"
+  );
+
+  // All three Smithy system headers are required
+  const headersBuf = Buffer.concat([
+    encodeHeader(":message-type", "event"),
+    encodeHeader(":event-type", eventType),
+    encodeHeader(":content-type", "application/json"),
+  ]);
+  const headersLen = headersBuf.length;
+
+  const totalLen = 4 + 4 + 4 + headersLen + payloadBuf.length + 4;
+  const frame = Buffer.alloc(totalLen);
+
+  frame.writeUInt32BE(totalLen, 0);
+  frame.writeUInt32BE(headersLen, 4);
+  frame.writeUInt32BE(crc32(frame.slice(0, 8)), 8); // prelude CRC
+  headersBuf.copy(frame, 12);
+  payloadBuf.copy(frame, 12 + headersLen);
+  frame.writeUInt32BE(crc32(frame.slice(0, totalLen - 4)), totalLen - 4); // message CRC
+
+  return frame;
+}
+
+// ─── CodeWhisperer → OpenAI conversion ───────────────────────────────────────
+
+/**
+ * Safely stringify a tool-call input value.
+ * OpenAI expects `function.arguments` to be a JSON string, never an object.
+ * If 9router's Anthropic→OpenAI conversion passes the input as a pre-parsed object,
+ * this prevents the "" + object → "[object Object]" corruption.
+ */
+function safeArgsString(value) {
+  if (typeof value === "string") return value;
+  if (value == null) return "{}";
+  try { return JSON.stringify(value); } catch { return "{}"; }
+}
+
+/**
+ * Convert a CodeWhisperer userInputMessage to one or more OpenAI messages.
+ *
+ * A user turn can contain:
+ *   - plain text content  → { role:"user", content }
+ *   - toolResults only    → one { role:"tool", tool_call_id, content } per result
+ *   - both                → tool messages first, then the user text message
+ */
+function convertUserInputMessage(uim) {
+  const out = [];
+  const toolResults = uim.userInputMessageContext?.toolResults || [];
+
+  // Emit one "tool" message per tool result (OpenAI multi-tool format)
+  for (const tr of toolResults) {
+    const text = (tr.content || []).map(c => c.text || "").join("\n");
+    out.push({
+      role: "tool",
+      tool_call_id: tr.toolUseId || "",
+      content: text,
+    });
+  }
+
+  // Emit user text only if it exists alongside OR when there are no tool results
+  const text = (uim.content || "").trim();
+  if (text || toolResults.length === 0) {
+    out.push({ role: "user", content: text });
+  }
+
+  return out;
+}
+
+/**
+ * Convert a CodeWhisperer assistantResponseMessage to an OpenAI assistant message.
+ *
+ * The assistant turn can contain:
+ *   - plain text content
+ *   - toolUses (tool calls)  → tool_calls[] on the assistant message
+ */
+function convertAssistantResponseMessage(arm) {
+  const toolUses = arm.toolUses || [];
+
+  if (toolUses.length > 0) {
+    return {
+      role: "assistant",
+      content: arm.content || null,
+      tool_calls: toolUses.map(tu => ({
+        id: tu.toolUseId || `call_${Date.now()}`,
+        type: "function",
+        function: {
+          name: tu.name || "",
+          arguments: safeArgsString(tu.input),
+        },
+      })),
+    };
+  }
+
+  return { role: "assistant", content: arm.content || "" };
+}
+
+/**
+ * Convert AWS CodeWhisperer conversationState to an OpenAI messages array.
+ *
+ * Full multi-turn shape:
+ *   history: [
+ *     { userInputMessage: { content, userInputMessageContext?: { toolResults?, tools? } } },
+ *     { assistantResponseMessage: { content, toolUses?: [...] } },
+ *     ...
+ *   ]
+ *   currentMessage: { userInputMessage: { content, userInputMessageContext?: { toolResults? } } }
+ */
+function codeWhispererToMessages(body) {
+  const cs = body.conversationState || {};
+  const history = cs.history || [];
+  const currentMsg = cs.currentMessage;
+  const messages = [];
+
+  for (const item of history) {
+    if (item.userInputMessage) {
+      messages.push(...convertUserInputMessage(item.userInputMessage));
+    } else if (item.assistantResponseMessage) {
+      messages.push(convertAssistantResponseMessage(item.assistantResponseMessage));
+    }
+  }
+
+  // Append the current (latest) turn
+  if (currentMsg?.userInputMessage) {
+    messages.push(...convertUserInputMessage(currentMsg.userInputMessage));
+  }
+
+  return messages;
+}
+
+/**
+ * Extract tool definitions from a CodeWhisperer request and convert to OpenAI format.
+ *
+ * CodeWhisperer tools live in:
+ *   conversationState.currentMessage.userInputMessage.userInputMessageContext.tools
+ * OR (in multi-turn) the first history item's userInputMessageContext.tools
+ *
+ * CodeWhisperer tool shape:
+ *   { toolSpecification: { name, description, inputSchema: { json: <schema> } } }
+ *
+ * OpenAI tool shape:
+ *   { type: "function", function: { name, description, parameters: <schema> } }
+ */
+function extractTools(body) {
+  const cs = body.conversationState || {};
+
+  // Tools are typically on the currentMessage; may also appear on the first history item
+  const fromCurrent = cs.currentMessage?.userInputMessage?.userInputMessageContext?.tools || [];
+  const fromHistory = cs.history?.find(h => h.userInputMessage?.userInputMessageContext?.tools)
+    ?.userInputMessage?.userInputMessageContext?.tools || [];
+  const cwTools = fromCurrent.length > 0 ? fromCurrent : fromHistory;
+
+  if (!cwTools.length) return [];
+
+  return cwTools.map(item => {
+    const spec = item.toolSpecification || item;
+    return {
+      type: "function",
+      function: {
+        name: spec.name || "",
+        description: spec.description || `Tool: ${spec.name || "unknown"}`,
+        parameters: spec.inputSchema?.json || { type: "object", properties: {}, required: [] },
+      },
+    };
+  });
+}
+
+// ─── OpenAI SSE → EventStream binary conversion ───────────────────────────────
+
+/**
+ * Convert an OpenAI SSE chunk to AWS EventStream binary frame(s)
+ * This replaces pipeOpenAIasEventStream and works with pipeTransformedEventStream
+ *
+ * @param {object|null} chunk - Parsed OpenAI chat.completion.chunk, or null for flush
+ * @param {object} state - Mutable state object
+ * @returns {Uint8Array|Uint8Array[]|null} Binary EventStream frame(s) or null to skip
+ */
+function convertOpenAIToKiro(chunk, state) {
+  // Flush: ensure clean stream termination
+  if (!chunk) {
+    if (state.finishSent) return null;
+    // Flush any remaining buffered thinking
+    if (state.inThink && state.thinkBuf) {
+      state.inThink = false;
+      const thinking = state.thinkBuf;
+      state.thinkBuf = "";
+      return buildEventStreamFrame("reasoningContentEvent", {
+        content: thinking,
+        modelId: state.modelId || "kiro-unknown"
+      });
+    }
+    return buildEventStreamFrame("messageStopEvent", {});
+  }
+
+  const frames = [];
+  const choice = chunk.choices?.[0];
+  const delta = choice?.delta || {};
+
+  // Capture modelId from first chunk (real API includes it in every content frame)
+  if (!state.modelId && chunk.model) {
+    state.modelId = chunk.model;
+  }
+  const modelId = state.modelId || "unknown";
+
+  // Handle usage (may arrive standalone or with other chunks)
+  if (chunk.usage) {
+    state.usage = chunk.usage;
+  }
+
+  // Handle tool calls — stream incrementally, matching real API format
+  if (delta.tool_calls) {
+    state.hasToolCalls = true;
+    for (const tc of delta.tool_calls) {
+      const idx = tc.index ?? 0;
+
+      if (tc.id && tc.function?.name && !state.toolCallInit[idx]) {
+        // First appearance: emit frame with name + id, no input
+        state.toolCallInit[idx] = { id: tc.id, name: tc.function.name };
+        dbg(`toolUseEvent init: ${tc.function.name} (${tc.id})`);
+        frames.push(buildEventStreamFrame("toolUseEvent", {
+          name: tc.function.name,
+          toolUseId: tc.id
+        }));
+      }
+
+      // Emit incremental input fragment
+      if (tc.function?.arguments) {
+        const init = state.toolCallInit[idx];
+        dbg(`toolUseEvent fragment: ${tc.function.arguments.slice(0, 100)}`);
+        frames.push(buildEventStreamFrame("toolUseEvent", {
+          input: tc.function.arguments,
+          name: init?.name || tc.function?.name || "",
+          toolUseId: init?.id || tc.id || ""
+        }));
+      }
+    }
+  }
+
+  // Handle explicit reasoning_content (type-specific thinking channel)
+  if (delta.reasoning_content) {
+    frames.push(buildEventStreamFrame("reasoningContentEvent", {
+      content: delta.reasoning_content,
+      modelId
+    }));
+  }
+
+  // Handle text content — extract thinking blocks, emit rest as assistantResponseEvent
+  if (delta.content) {
+    const { thinking, text } = extractThinking(delta.content, state);
+
+    if (thinking) {
+      frames.push(buildEventStreamFrame("reasoningContentEvent", {
+        content: thinking,
+        modelId
+      }));
+    }
+
+    if (text) {
+      frames.push(buildEventStreamFrame("assistantResponseEvent", {
+        content: text,
+        modelId
+      }));
+    }
+  }
+
+  // Handle finish_reason
+  if (choice?.finish_reason) {
+    const finishFrames = emitFinish(state);
+    if (finishFrames) {
+      frames.push(...(Array.isArray(finishFrames) ? finishFrames : [finishFrames]));
+    }
+  }
+
+  if (frames.length === 0) return null;
+  return frames.length === 1 ? frames[0] : frames;
+}
+
+/**
+ * Emit termination frames. For tool-call responses, emits stop:true per tool.
+ * For text-only responses, emits messageStopEvent.
+ */
+function emitFinish(state) {
+  const frames = [];
+
+  if (state.hasToolCalls) {
+    // Tool-call response: emit stop:true for each tool
+    for (const idx of Object.keys(state.toolCallInit).sort()) {
+      const tc = state.toolCallInit[idx];
+      frames.push(buildEventStreamFrame("toolUseEvent", {
+        name: tc.name,
+        stop: true,
+        toolUseId: tc.id
+      }));
+    }
+  } else {
+    // Text-only response: emit messageStopEvent
+    frames.push(buildEventStreamFrame("messageStopEvent", {}));
+  }
+  state.finishSent = true;
+
+  // Emit usage if available
+  if (state.usage) {
+    frames.push(buildEventStreamFrame("usageEvent", {
+      inputTokens: state.usage.prompt_tokens || 0,
+      outputTokens: state.usage.completion_tokens || 0
+    }));
+  }
+
+  state.toolCallInit = {};
+  return frames.length > 0 ? frames : null;
+}
+
+// ─── MITM intercept entry point ───────────────────────────────────────────────
+/**
+ * Intercept Kiro IDE CodeWhisperer request and convert to EventStream response:
+ *   1. Parse CodeWhisperer JSON body (reject binary EventStream formats)
+ *   2. Convert CodeWhisperer format to OpenAI messages[] format
+ *   3. Forward to 9router /v1/chat/completions (OpenAI SSE)
+ *   4. Convert OpenAI SSE response → AWS EventStream binary frames
+ *   5. Stream EventStream frames back to Kiro IDE
+ * 
+ * @param {http.IncomingMessage} req - HTTP request from Kiro IDE
+ * @param {http.ServerResponse} res - HTTP response to Kiro IDE  
+ * @param {Buffer} bodyBuffer - Request body buffer
+ * @param {string} mappedModel - Model name after MITM alias mapping
+ */
+async function intercept(req, res, bodyBuffer, mappedModel) {
+  try {
+    // Detect and handle binary data (e.g., continuation requests with EventStream frames)
+    if (isBinaryEventStream(bodyBuffer)) {
+      // Binary EventStream requests are typically continuation/streaming frames
+      // that don't contain model info - pass them through directly to avoid JSON.parse crash
+      throw new Error(`Binary EventStream format detected (${bodyBuffer.length}B) - request should use passthrough instead of intercept`);
+    }
+    
+    const body = JSON.parse(bodyBuffer.toString());
+
+    // 1 + 2: CodeWhisperer → OpenAI messages + tools
+    const messages = codeWhispererToMessages(body);
+    if (messages.length === 0) {
+      throw new Error("codeWhispererToMessages produced 0 messages — check request body");
+    }
+
+    const tools = extractTools(body);
+
+    const openaiBody = {
+      model: mappedModel,
+      messages,
+      stream: true,
+      // Forward tools so Claude uses structured tool_calls instead of XML text fallback
+      ...(tools.length > 0 && { tools, tool_choice: "auto" }),
+    };
+
+    // 3: Forward to 9router
+    const routerRes = await fetchRouter(openaiBody, "/v1/chat/completions", req.headers);
+
+    // 4 + 5: Re-encode response as AWS EventStream binary using standard pipeline
+    const state = initKiroState(mappedModel);
+
+    await pipeTransformedEventStream(routerRes, res, convertOpenAIToKiro, state);
+  } catch (error) {
+    err(`[Kiro MITM] Request processing failed: ${error.message}`);
+    if (!res.headersSent) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+    }
+    res.end(JSON.stringify({ 
+      error: { 
+        message: error.message, 
+        type: "mitm_error",
+        handler: "kiro"
+      } 
+    }));
+  }
+}
+
+// Detect AWS EventStream binary format
+function isBinaryEventStream(buffer) {
+  if (!buffer || buffer.length < 12) return false;
+  // AWS EventStream signature: 
+  // - First 4 bytes: total frame length (big-endian)
+  // - Bytes 4-8: headers length (big-endian)
+  // - Typical frame length: 100-10000 bytes
+  const totalLen = buffer.readUInt32BE(0);
+  const headersLen = buffer.readUInt32BE(4);
+  // Sanity checks: frame length should be reasonable and headers should fit
+  return totalLen > 12 && totalLen < 1000000 && headersLen < totalLen - 12;
+}
+
+module.exports = { intercept };
diff --git a/src/mitm/logger.js b/src/mitm/logger.js
new file mode 100644
index 0000000..5e53210
--- /dev/null
+++ b/src/mitm/logger.js
@@ -0,0 +1,106 @@
+const fs = require("fs");
+const path = require("path");
+const zlib = require("zlib");
+const { DATA_DIR } = require("./paths");
+const { LOG_BLACKLIST_URL_PARTS } = require("./config");
+
+function time() {
+  return new Date().toLocaleTimeString("en-US", { hour12: false });
+}
+
+const log = (msg) => console.log(`[${time()}] [MITM] ${msg}`);
+const err = (msg) => console.error(`[${time()}] ❌ [MITM] ${msg}`);
+
+const DUMP_DIR = path.join(DATA_DIR, "logs", "mitm");
+if (!fs.existsSync(DUMP_DIR)) fs.mkdirSync(DUMP_DIR, { recursive: true });
+
+// Clear all files inside DUMP_DIR (called on MITM server start to avoid unbounded growth)
+function clearDumpDir() {
+  try {
+    if (!fs.existsSync(DUMP_DIR)) return;
+    for (const f of fs.readdirSync(DUMP_DIR)) {
+      try { fs.rmSync(path.join(DUMP_DIR, f), { recursive: true, force: true }); } catch { /* ignore */ }
+    }
+  } catch { /* ignore */ }
+}
+
+const EMPTY_BODY_RE = /^\s*(\{\s*\}|\[\s*\]|null)?\s*$/;
+
+function slugify(s, max = 80) {
+  return String(s).replace(/[^a-zA-Z0-9]/g, "_").substring(0, max);
+}
+
+function isBlacklisted(url) {
+  if (!url) return false;
+  return LOG_BLACKLIST_URL_PARTS.some(part => url.includes(part));
+}
+
+// Decode body buffer based on content-encoding header
+function decodeBody(buf, encoding) {
+  if (!buf || buf.length === 0) return buf;
+  try {
+    const enc = (encoding || "").toLowerCase();
+    if (enc.includes("gzip")) return zlib.gunzipSync(buf);
+    if (enc.includes("br")) return zlib.brotliDecompressSync(buf);
+    if (enc.includes("deflate")) return zlib.inflateSync(buf);
+  } catch { /* return raw on failure */ }
+  return buf;
+}
+
+// Save raw request: method + url + headers + body
+function dumpRequest(req, bodyBuffer, tag = "raw") {
+  if (isBlacklisted(req.url)) return null;
+  try {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const slug = slugify((req.headers.host || "") + req.url);
+    const file = path.join(DUMP_DIR, `${ts}_${tag}_${slug}.req.json`);
+    let parsed = null;
+    try { parsed = JSON.parse(bodyBuffer.toString()); } catch { /* not JSON */ }
+    fs.writeFileSync(file, JSON.stringify({
+      method: req.method,
+      url: req.url,
+      host: req.headers.host,
+      headers: req.headers,
+      body: parsed ?? bodyBuffer.toString("utf8")
+    }, null, 2));
+    return file;
+  } catch { return null; }
+}
+
+// Buffer-based response dumper — collects chunks then decodes + writes once on end()
+// Trade-off: holds response in RAM, but enables gzip/br decoding for readable output.
+function createResponseDumper(req, tag = "raw") {
+  if (isBlacklisted(req.url)) return null;
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const slug = slugify((req.headers.host || "") + req.url);
+  const file = path.join(DUMP_DIR, `${ts}_${tag}_${slug}.res.txt`);
+  let status = 0;
+  let headers = {};
+  const chunks = [];
+  return {
+    writeHeader: (s, h) => { status = s; headers = h || {}; },
+    writeChunk: (chunk) => {
+      if (chunk == null) return;
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    },
+    end: () => {
+      try {
+        const raw = Buffer.concat(chunks);
+        const enc = headers["content-encoding"] || headers["Content-Encoding"];
+        const decoded = decodeBody(raw, enc);
+        const text = decoded.toString("utf8");
+        // Skip empty / trivially-empty bodies
+        if (EMPTY_BODY_RE.test(text)) return;
+        // Strip content-encoding since body is now decoded
+        const cleanHeaders = { ...headers };
+        delete cleanHeaders["content-encoding"];
+        delete cleanHeaders["Content-Encoding"];
+        const out = `STATUS: ${status}\nHEADERS: ${JSON.stringify(cleanHeaders, null, 2)}\n---BODY---\n${text}`;
+        fs.writeFileSync(file, out);
+      } catch { /* ignore */ }
+    },
+    file
+  };
+}
+
+module.exports = { log, err, dumpRequest, createResponseDumper, clearDumpDir };
diff --git a/src/mitm/manager.js b/src/mitm/manager.js
new file mode 100644
index 0000000..a9d6e6a
--- /dev/null
+++ b/src/mitm/manager.js
@@ -0,0 +1,883 @@
+const { exec, spawn, execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+const net = require("net");
+const https = require("https");
+const crypto = require("crypto");
+const { addDNSEntry, removeDNSEntry, removeAllDNSEntries, removeAllDNSEntriesSync, checkAllDNSStatus, TOOL_HOSTS, isSudoAvailable, isSudoPasswordRequired } = require("./dns/dnsConfig");
+const { isAdmin } = require("./winElevated.js");
+
+const IS_WIN = process.platform === "win32";
+const IS_MAC = process.platform === "darwin";
+const { generateCert } = require("./cert/generate");
+const { installCert, uninstallCert } = require("./cert/install");
+const { isCertExpired } = require("./cert/rootCA");
+const { DATA_DIR, MITM_DIR } = require("./paths");
+const { log, err } = require("./logger");
+const { LSOF_BIN } = require("./config");
+
+const DEFAULT_MITM_ROUTER_BASE = "http://localhost:20128";
+
+function shellQuoteSingle(str) {
+  if (str == null || str === "") return "''";
+  return `'${String(str).replace(/'/g, "'\\''")}'`;
+}
+
+async function resolveMitmRouterBaseUrl() {
+  if (!_getSettings) return DEFAULT_MITM_ROUTER_BASE;
+  try {
+    const s = await _getSettings();
+    const raw = s && s.mitmRouterBaseUrl != null ? String(s.mitmRouterBaseUrl).trim() : "";
+    if (!raw) return DEFAULT_MITM_ROUTER_BASE;
+    const u = new URL(raw);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return DEFAULT_MITM_ROUTER_BASE;
+    return raw.replace(/\/+$/, "");
+  } catch {
+    return DEFAULT_MITM_ROUTER_BASE;
+  }
+}
+
+const MITM_PORT = 443;
+const MITM_WIN_NODE_PORT = 8443;
+const PID_FILE = path.join(MITM_DIR, ".mitm.pid");
+const LOCK_FILE = path.join(MITM_DIR, ".mitm.lock");
+
+const MITM_MAX_RESTARTS = 5;
+const MITM_RESTART_DELAYS_MS = [5000, 10000, 20000, 30000, 60000];
+const MITM_RESTART_RESET_MS = 60000;
+
+let mitmRestartCount = 0;
+let mitmLastStartTime = 0;
+let mitmIsRestarting = false;
+
+function resolveBundledServerPath() {
+  if (process.env.MITM_SERVER_PATH) return process.env.MITM_SERVER_PATH;
+  const sibling = path.join(__dirname, "server.js");
+  if (fs.existsSync(sibling)) return sibling;
+  const fromCwd = path.join(process.cwd(), "src", "mitm", "server.js");
+  if (fs.existsSync(fromCwd)) return fromCwd;
+  const fromNext = path.join(process.cwd(), "..", "src", "mitm", "server.js");
+  if (fs.existsSync(fromNext)) return fromNext;
+  return fromCwd;
+}
+
+// Copy bundled server.js into DATA_DIR so MITM doesn't lock node_modules
+// (prevents EBUSY on `npm i -g 9router@latest` while MITM is running).
+function ensureRuntimeServer(bundledPath) {
+  try {
+    if (!bundledPath || !fs.existsSync(bundledPath)) return bundledPath;
+
+    // Dev mode: source file has relative requires (./logger, ./config...),
+    // only the bundled file inside node_modules is self-contained + safe to copy.
+    if (!bundledPath.includes(`${path.sep}node_modules${path.sep}`)) {
+      return bundledPath;
+    }
+
+    const runtimeDir = path.join(DATA_DIR, "runtime", "mitm");
+    const runtimeServer = path.join(runtimeDir, "server.js");
+
+    // Skip copy if sizes match (bundle unchanged since last run)
+    if (fs.existsSync(runtimeServer)) {
+      try {
+        if (fs.statSync(bundledPath).size === fs.statSync(runtimeServer).size) return runtimeServer;
+      } catch { /* recopy */ }
+    }
+
+    fs.mkdirSync(runtimeDir, { recursive: true });
+    fs.copyFileSync(bundledPath, runtimeServer);
+    return runtimeServer;
+  } catch (e) {
+    try { log(`[MITM] runtime copy failed: ${e.message}`); } catch { /* ignore */ }
+    return bundledPath;
+  }
+}
+
+const SERVER_PATH = ensureRuntimeServer(resolveBundledServerPath());
+const ENCRYPT_ALGO = "aes-256-gcm";
+const ENCRYPT_SALT = "9router-mitm-pwd";
+
+function getProcessUsingPort443() {
+  try {
+    if (IS_WIN) {
+      const psCmd = `powershell -NonInteractive -WindowStyle Hidden -Command ` +
+        `"$c = Get-NetTCPConnection -LocalPort 443 -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1; if ($c) { $c.OwningProcess } else { 0 }"`;
+      const pidStr = execSync(psCmd, { encoding: "utf8", windowsHide: true }).trim();
+      const pid = parseInt(pidStr, 10);
+      if (pid && pid > 4) {
+        const tasklistResult = execSync(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`, { encoding: "utf8", windowsHide: true });
+        const processMatch = tasklistResult.match(/"([^"]+)"/);
+        if (processMatch) return processMatch[1].replace(".exe", "");
+      }
+    } else {
+      const result = execSync(`${LSOF_BIN} -i :443`, { encoding: "utf8", windowsHide: true });
+      const lines = result.trim().split("\n");
+      if (lines.length > 1) return lines[1].split(/\s+/)[0];
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+let serverProcess = null;
+let serverPid = null;
+
+function getCachedPassword() { return globalThis.__mitmSudoPassword || null; }
+function setCachedPassword(pwd) { globalThis.__mitmSudoPassword = pwd; }
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EACCES";
+  }
+}
+
+function killProcess(pid, force = false, sudoPassword = null) {
+  if (IS_WIN) {
+    const flag = force ? "/F " : "";
+    exec(`taskkill ${flag}/PID ${pid}`, { windowsHide: true }, () => { });
+  } else {
+    const sig = force ? "SIGKILL" : "SIGTERM";
+    const cmd = `pkill -${sig} -P ${pid} 2>/dev/null; kill -${sig} ${pid} 2>/dev/null`;
+    if (sudoPassword || isSudoAvailable()) {
+      const { execWithPassword } = require("./dns/dnsConfig");
+      execWithPassword(cmd, sudoPassword || "").catch(() => exec(cmd, { windowsHide: true }, () => { }));
+    } else {
+      exec(cmd, { windowsHide: true }, () => { });
+    }
+  }
+}
+
+function deriveKey() {
+  try {
+    const { machineIdSync } = require("node-machine-id");
+    const raw = machineIdSync();
+    return crypto.createHash("sha256").update(raw + ENCRYPT_SALT).digest();
+  } catch {
+    return crypto.createHash("sha256").update(ENCRYPT_SALT).digest();
+  }
+}
+
+function encryptPassword(plaintext) {
+  const key = deriveKey();
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv(ENCRYPT_ALGO, key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `${iv.toString("hex")}:${tag.toString("hex")}:${encrypted.toString("hex")}`;
+}
+
+function decryptPassword(stored) {
+  try {
+    const [ivHex, tagHex, dataHex] = stored.split(":");
+    if (!ivHex || !tagHex || !dataHex) return null;
+    const key = deriveKey();
+    const decipher = crypto.createDecipheriv(ENCRYPT_ALGO, key, Buffer.from(ivHex, "hex"));
+    decipher.setAuthTag(Buffer.from(tagHex, "hex"));
+    return decipher.update(Buffer.from(dataHex, "hex")) + decipher.final("utf8");
+  } catch {
+    return null;
+  }
+}
+
+let _getSettings = null;
+let _updateSettings = null;
+
+function initDbHooks(getSettingsFn, updateSettingsFn) {
+  _getSettings = getSettingsFn;
+  _updateSettings = updateSettingsFn;
+}
+
+async function saveMitmSettings(enabled, password) {
+  if (!_updateSettings) return;
+  try {
+    const updates = { mitmEnabled: enabled };
+    if (password) updates.mitmSudoEncrypted = encryptPassword(password);
+    await _updateSettings(updates);
+  } catch (e) {
+    err(`Failed to save settings: ${e.message}`);
+  }
+}
+
+async function clearEncryptedPassword() {
+  if (!_updateSettings) return;
+  try {
+    await _updateSettings({ mitmSudoEncrypted: null });
+  } catch (e) {
+    err(`Failed to clear encrypted password: ${e.message}`);
+  }
+}
+
+async function loadEncryptedPassword() {
+  if (!_getSettings) return null;
+  try {
+    const settings = await _getSettings();
+    if (!settings.mitmSudoEncrypted) return null;
+    return decryptPassword(settings.mitmSudoEncrypted);
+  } catch {
+    return null;
+  }
+}
+
+async function saveDnsToolState(tool, enabled) {
+  if (!_updateSettings || !_getSettings) return;
+  try {
+    const s = await _getSettings();
+    const next = { ...(s.dnsToolEnabled || {}), [tool]: enabled };
+    await _updateSettings({ dnsToolEnabled: next });
+  } catch (e) {
+    err(`Failed to save DNS state: ${e.message}`);
+  }
+}
+
+async function loadDnsToolState() {
+  if (!_getSettings) return {};
+  try {
+    const s = await _getSettings();
+    return s.dnsToolEnabled || {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Re-apply DNS for tools previously enabled — called on app startup after MITM running.
+ */
+async function restoreToolDNS(sudoPassword) {
+  const state = await loadDnsToolState();
+  const password = sudoPassword || getCachedPassword() || await loadEncryptedPassword();
+  for (const [tool, enabled] of Object.entries(state)) {
+    if (!enabled || !TOOL_HOSTS[tool]) continue;
+    try {
+      await addDNSEntry(tool, password);
+    } catch (e) {
+      err(`DNS ${tool}: restore failed — ${e.message}`);
+    }
+  }
+}
+
+/**
+ * Check if user has privilege to mutate hosts file.
+ * Win: needs admin. Mac/Linux: root OR cached/encrypted sudo password.
+ */
+async function hasDnsPrivilege() {
+  if (IS_WIN) return isAdmin();
+  if (isAdmin()) return true;
+  if (!isSudoPasswordRequired()) return true;
+  const pwd = getCachedPassword() || await loadEncryptedPassword();
+  return !!pwd;
+}
+
+function checkPort443Free() {
+  return new Promise((resolve) => {
+    const tester = net.createServer();
+    tester.once("error", (err) => {
+      if (err.code === "EADDRINUSE") resolve("in-use");
+      else resolve("no-permission");
+    });
+    tester.once("listening", () => { tester.close(() => resolve("free")); });
+    tester.listen(MITM_PORT, "127.0.0.1");
+  });
+}
+
+function getPort443Owner(sudoPassword) {
+  return new Promise((resolve) => {
+    if (IS_WIN) {
+      const psCmd = `powershell -NonInteractive -WindowStyle Hidden -Command "` +
+        `$c = Get-NetTCPConnection -LocalPort 443 -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1; ` +
+        `if ($c) { $c.OwningProcess } else { 0 }"`;    
+      exec(psCmd, { windowsHide: true }, (err, stdout) => {
+        if (err) return resolve(null);
+        const pid = parseInt(stdout.trim(), 10);
+        if (!pid || pid <= 4) return resolve(null);
+        exec(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`, { windowsHide: true }, (e2, out2) => {
+          const m = out2?.match(/"([^"]+)"/);
+          resolve({ pid, name: m ? m[1] : "unknown" });
+        });
+      });
+    } else {
+      // Only find process actually LISTENING on TCP port 443
+      exec(`${LSOF_BIN} -nP -iTCP:443 -sTCP:LISTEN -t`, { windowsHide: true }, (err, stdout) => {
+        if (err || !stdout?.trim()) return resolve(null);
+        const pid = parseInt(stdout.trim().split("\n")[0], 10);
+        if (!pid || isNaN(pid)) return resolve(null);
+        exec(`ps -p ${pid} -o comm=`, { windowsHide: true }, (e2, out2) => {
+          resolve({ pid, name: (out2?.trim() || "unknown") });
+        });
+      });
+    }
+  });
+}
+
+async function killLeftoverMitm(sudoPassword) {
+  if (serverProcess && !serverProcess.killed) {
+    try { serverProcess.kill("SIGKILL"); } catch { /* ignore */ }
+    serverProcess = null;
+    serverPid = null;
+  }
+  try {
+    if (fs.existsSync(PID_FILE)) {
+      const savedPid = parseInt(fs.readFileSync(PID_FILE, "utf-8").trim(), 10);
+      if (savedPid && isProcessAlive(savedPid)) {
+        killProcess(savedPid, true, sudoPassword);
+        await new Promise(r => setTimeout(r, 500));
+      }
+      fs.unlinkSync(PID_FILE);
+    }
+  } catch { /* ignore */ }
+  if (!IS_WIN && SERVER_PATH) {
+    try {
+      const escaped = SERVER_PATH.replace(/'/g, "'\\''");
+      if (sudoPassword || isSudoAvailable()) {
+        const { execWithPassword } = require("./dns/dnsConfig");
+        await execWithPassword(`pkill -SIGKILL -f "${escaped}" 2>/dev/null || true`, sudoPassword || "").catch(() => { });
+      } else {
+        exec(`pkill -SIGKILL -f "${escaped}" 2>/dev/null || true`, { windowsHide: true }, () => { });
+      }
+      await new Promise(r => setTimeout(r, 500));
+    } catch { /* ignore */ }
+  }
+}
+
+function pollMitmHealth(timeoutMs, port = MITM_PORT) {
+  return new Promise((resolve) => {
+    const deadline = Date.now() + timeoutMs;
+    const check = () => {
+      const req = https.request(
+        { hostname: "127.0.0.1", port, path: "/_mitm_health", method: "GET", rejectUnauthorized: false },
+        (res) => {
+          let body = "";
+          res.on("data", (d) => { body += d; });
+          res.on("end", () => {
+            try {
+              const json = JSON.parse(body);
+              resolve(json.ok === true ? { ok: true, pid: json.pid || null } : null);
+            } catch { resolve(null); }
+          });
+        }
+      );
+      req.on("error", () => {
+        if (Date.now() < deadline) setTimeout(check, 500);
+        else resolve(null);
+      });
+      req.end();
+    };
+    check();
+  });
+}
+
+/**
+ * Get full MITM status including per-tool DNS status
+ */
+async function getMitmStatus() {
+  let running = serverProcess !== null && !serverProcess.killed;
+  let pid = serverPid;
+
+  if (!running) {
+    try {
+      if (fs.existsSync(PID_FILE)) {
+        const savedPid = parseInt(fs.readFileSync(PID_FILE, "utf-8").trim(), 10);
+        if (savedPid && isProcessAlive(savedPid)) {
+          running = true;
+          pid = savedPid;
+        } else {
+          fs.unlinkSync(PID_FILE);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  const dnsStatus = checkAllDNSStatus();
+  const rootCACertPath = path.join(MITM_DIR, "rootCA.crt");
+  const certExists = fs.existsSync(rootCACertPath);
+  const { checkCertInstalled } = require("./cert/install");
+  const certTrusted = certExists ? await checkCertInstalled(rootCACertPath) : false;
+
+  return { running, pid, certExists, certTrusted, dnsStatus };
+}
+
+async function scheduleMitmRestart(apiKey) {
+  if (mitmIsRestarting) return;
+  // Set guard synchronously before any await to prevent concurrent calls
+  // from passing the check above.
+  mitmIsRestarting = true;
+
+  const aliveMs = Date.now() - mitmLastStartTime;
+  if (aliveMs >= MITM_RESTART_RESET_MS) mitmRestartCount = 0;
+
+  if (mitmRestartCount >= MITM_MAX_RESTARTS) {
+    err("Max restart attempts reached. Giving up.");
+    mitmIsRestarting = false;
+    return;
+  }
+
+  const attempt = mitmRestartCount;
+  const delay = MITM_RESTART_DELAYS_MS[Math.min(attempt, MITM_RESTART_DELAYS_MS.length - 1)];
+  mitmRestartCount++;
+
+  log(`Restarting in ${delay / 1000}s... (${mitmRestartCount}/${MITM_MAX_RESTARTS})`);
+  await new Promise((r) => setTimeout(r, delay));
+
+  try {
+    const settings = _getSettings ? await _getSettings() : null;
+    if (settings && !settings.mitmEnabled) {
+      log("MITM disabled, skipping restart");
+      mitmIsRestarting = false;
+      return;
+    }
+    const password = getCachedPassword() || await loadEncryptedPassword();
+    if (!password && !IS_WIN) {
+      err("No cached password, cannot auto-restart");
+      mitmIsRestarting = false;
+      return;
+    }
+    await startServer(apiKey, password);
+    log("🔄 Restarted successfully");
+    mitmRestartCount = 0;
+    mitmIsRestarting = false;
+  } catch (e) {
+    err(`Restart attempt ${mitmRestartCount}/${MITM_MAX_RESTARTS} failed: ${e.message}`);
+    mitmIsRestarting = false;
+    // Schedule next retry
+    scheduleMitmRestart(apiKey);
+  }
+}
+
+/**
+ * Start MITM server only (cert + server, no DNS)
+ */
+async function killPort443Owner(owner, sudoPassword) {
+  if (!owner || !owner.pid) return;
+  if (IS_WIN) {
+    try {
+      execSync(`powershell -NonInteractive -WindowStyle Hidden -Command "Stop-Process -Id ${owner.pid} -Force -ErrorAction SilentlyContinue"`, { windowsHide: true });
+    } catch { /* best effort */ }
+  } else {
+    try {
+      const { execWithPassword } = require("./dns/dnsConfig");
+      if (sudoPassword || isSudoAvailable()) {
+        await execWithPassword(`kill -9 ${owner.pid}`, sudoPassword || "");
+      } else {
+        execSync(`kill -9 ${owner.pid}`, { windowsHide: true });
+      }
+    } catch { /* best effort */ }
+  }
+  await new Promise(r => setTimeout(r, 800));
+}
+
+async function startServer(apiKey, sudoPassword, forceKillPort443 = false) {
+  if (!serverProcess || serverProcess.killed) {
+    try {
+      if (fs.existsSync(PID_FILE)) {
+        const savedPid = parseInt(fs.readFileSync(PID_FILE, "utf-8").trim(), 10);
+        if (savedPid && isProcessAlive(savedPid)) {
+          serverPid = savedPid;
+          log(`♻️ Reusing existing process (PID: ${savedPid})`);
+          await saveMitmSettings(true, sudoPassword);
+          if (sudoPassword) setCachedPassword(sudoPassword);
+          return { running: true, pid: savedPid };
+        } else {
+          fs.unlinkSync(PID_FILE);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (serverProcess && !serverProcess.killed) {
+    throw new Error("MITM server is already running");
+  }
+
+  // Atomically claim lock to prevent concurrent startServer across processes.
+  // O_EXCL (flag: "wx") fails with EEXIST if the file already exists.
+  try {
+    fs.writeFileSync(LOCK_FILE, String(process.pid), { flag: "wx" });
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      let stale = false;
+      try {
+        const pid = parseInt(fs.readFileSync(LOCK_FILE, "utf-8").trim(), 10);
+        stale = !pid || !isProcessAlive(pid);
+      } catch { stale = true; } // unreadable lock → treat as stale
+      if (!stale) throw new Error("MITM server is already starting (lock contention)");
+      try { fs.unlinkSync(LOCK_FILE); } catch { /* ignore */ }
+      fs.writeFileSync(LOCK_FILE, String(process.pid), { flag: "wx" });
+    } else throw e;
+  }
+
+  try {
+    await killLeftoverMitm(sudoPassword);
+
+  if (!IS_WIN) {
+    const portStatus = await checkPort443Free();
+    if (portStatus === "in-use" || portStatus === "no-permission") {
+      const owner = await getPort443Owner(sudoPassword);
+      if (owner) {
+        const shortName = owner.name.includes("/")
+          ? owner.name.split("/").filter(Boolean).pop()
+          : owner.name;
+        if (forceKillPort443) {
+          log(`Killing process on port 443 (PID ${owner.pid}, name=${shortName})...`);
+          await killPort443Owner(owner, sudoPassword);
+        } else {
+          const e = new Error(`Port 443 is already in use by "${shortName}" (PID ${owner.pid}).`);
+          e.code = "PORT_443_BUSY";
+          e.portOwner = { pid: owner.pid, name: shortName };
+          throw e;
+        }
+      }
+    }
+  }
+
+  // Step 1: Generate Root CA if missing or expired
+  const rootCACertPath = path.join(MITM_DIR, "rootCA.crt");
+  const rootCAKeyPath = path.join(MITM_DIR, "rootCA.key");
+  const certExists = fs.existsSync(rootCACertPath) && fs.existsSync(rootCAKeyPath);
+
+  if (!certExists || isCertExpired(rootCACertPath)) {
+    if (certExists) {
+      // Uninstall expired cert from system store before regenerating
+      log("🔐 Cert expired — uninstalling old cert...");
+      const password = sudoPassword || getCachedPassword() || await loadEncryptedPassword();
+      try { await uninstallCert(password, rootCACertPath); } catch { /* best effort */ }
+    }
+    log("🔐 Generating Root CA...");
+    await generateCert();
+  }
+
+  // Step 1.5: Auto-install Root CA if not trusted yet
+  const { checkCertInstalled } = require("./cert/install");
+  const rootCATrusted = await checkCertInstalled(rootCACertPath);
+  const linuxNoSystemTrust = !IS_WIN && !IS_MAC && !isSudoAvailable();
+  if (!rootCATrusted) {
+    log("🔐 Cert: not trusted → installing...");
+    const password = sudoPassword || getCachedPassword() || await loadEncryptedPassword();
+    if (linuxNoSystemTrust) {
+      log(`🔐 Cert: skipping system trust (no sudo). Install ${rootCACertPath} as a trusted CA on machines that use this proxy.`);
+    } else {
+      if (!password && isSudoPasswordRequired()) {
+        throw new Error("Sudo password required to install Root CA certificate");
+      }
+      try {
+        await installCert(password, rootCACertPath);
+        log("🔐 Cert: ✅ trusted");
+      } catch (e) {
+        throw new Error(`Failed to trust certificate: ${e.message}`);
+      }
+    }
+  } else {
+    log("🔐 Cert: already trusted ✅");
+  }
+
+  // Step 2: Spawn server (Root CA already installed in Step 1.5)
+  // Verify server.js exists — recopy if runtime file was deleted (antivirus/cleanup)
+  let effectiveServerPath = SERVER_PATH;
+  if (!effectiveServerPath || !fs.existsSync(effectiveServerPath)) {
+    log(`[MITM] server.js missing at ${effectiveServerPath} → recopying`);
+    effectiveServerPath = ensureRuntimeServer(resolveBundledServerPath());
+    if (!effectiveServerPath || !fs.existsSync(effectiveServerPath)) {
+      throw new Error(`MITM server.js not found at ${effectiveServerPath}. Reinstall 9router.`);
+    }
+  }
+  const mitmRouterBase = await resolveMitmRouterBaseUrl();
+  log(`🚀 Starting server... (router: ${mitmRouterBase})`);
+  if (IS_WIN) {
+    // Check port 443 — ask user before killing
+    const winOwner = await getPort443Owner(sudoPassword);
+    if (winOwner) {
+      if (forceKillPort443) {
+        log(`Killing process on port 443 (PID ${winOwner.pid}, name=${winOwner.name})...`);
+        await killPort443Owner(winOwner, sudoPassword);
+      } else {
+        const e = new Error(`Port 443 is already in use by "${winOwner.name}" (PID ${winOwner.pid}).`);
+        e.code = "PORT_443_BUSY";
+        e.portOwner = { pid: winOwner.pid, name: winOwner.name };
+        throw e;
+      }
+    }
+
+    // Spawn directly — process already has admin rights
+    // cwd=tmpdir so process doesn't lock the install dir on Windows (EBUSY on update)
+    serverProcess = spawn(
+      process.execPath,
+      [effectiveServerPath],
+      {
+        detached: false,
+        windowsHide: true,
+        cwd: os.tmpdir(),
+        stdio: ["ignore", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          ROUTER_API_KEY: apiKey,
+          NODE_ENV: "production",
+          MITM_ROUTER_BASE: mitmRouterBase,
+        },
+      }
+    );
+
+    if (_updateSettings) await _updateSettings({ mitmCertInstalled: true }).catch(() => { });
+  } else if (isSudoAvailable()) {
+    // Pass HOME explicitly so os.homedir() resolves to the unprivileged user's home
+    // instead of /root when sudo resets the environment.
+    const inlineCmd = [
+      `HOME=${shellQuoteSingle(os.homedir())}`,
+      `ROUTER_API_KEY=${shellQuoteSingle(apiKey)}`,
+      `MITM_ROUTER_BASE=${shellQuoteSingle(mitmRouterBase)}`,
+      "NODE_ENV=production",
+      shellQuoteSingle(process.execPath),
+      shellQuoteSingle(effectiveServerPath),
+    ].join(" ");
+    serverProcess = spawn(
+      "sudo", ["-S", "-E", "sh", "-c", inlineCmd],
+      { detached: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] }
+    );
+    serverProcess.stdin.write(`${sudoPassword}\n`);
+    serverProcess.stdin.end();
+  } else {
+    // Docker/minimal images: no sudo — same as Windows-style direct spawn
+    serverProcess = spawn(process.execPath, [effectiveServerPath], {
+      detached: false,
+      windowsHide: true,
+      cwd: os.tmpdir(),
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        ROUTER_API_KEY: apiKey,
+        NODE_ENV: "production",
+        MITM_ROUTER_BASE: mitmRouterBase,
+      },
+    });
+  }
+
+  if (serverProcess) {
+    serverPid = serverProcess.pid;
+    fs.writeFileSync(PID_FILE, String(serverPid));
+    mitmLastStartTime = Date.now();
+  }
+
+  // Set NODE_EXTRA_CA_CERTS so Node-based GUI apps (Electron/AG language_server) trust MITM cert
+  if (IS_MAC) {
+    const rootCAPath = path.join(MITM_DIR, "rootCA.crt");
+    if (fs.existsSync(rootCAPath)) {
+      exec(`launchctl setenv NODE_EXTRA_CA_CERTS "${rootCAPath}"`, { windowsHide: true }, (e) => {
+        if (e) log(`[launchctl] Failed to set NODE_EXTRA_CA_CERTS: ${e.message}`);
+        else log(`[launchctl] NODE_EXTRA_CA_CERTS set to ${rootCAPath}`);
+      });
+    }
+  } else if (IS_WIN) {
+    const rootCAPath = path.join(MITM_DIR, "rootCA.crt");
+    if (fs.existsSync(rootCAPath)) {
+      exec(`setx NODE_EXTRA_CA_CERTS "${rootCAPath}"`, { windowsHide: true }, (e) => {
+        if (e) log(`[setx] Failed to set NODE_EXTRA_CA_CERTS: ${e.message}`);
+        else log(`[setx] NODE_EXTRA_CA_CERTS set for current user`);
+      });
+    }
+  }
+
+  let startError = null;
+  if (serverProcess) {
+    serverProcess.stdout.on("data", (data) => {
+      // server.js already formats its own logs — print as-is
+      process.stdout.write(data);
+    });
+    serverProcess.stderr.on("data", (data) => {
+      const msg = data.toString().trim();
+      // Mac/Linux: filter sudo password prompt noise
+      if (msg && (IS_WIN || (!msg.includes("Password:") && !msg.includes("password for")))) {
+        err(msg);
+        startError = msg;
+      }
+      // Detect wrong/missing password — clear cache and stop retry loop
+      if (!IS_WIN && (msg.includes("incorrect password") || msg.includes("no password was provided"))) {
+        setCachedPassword(null);
+        clearEncryptedPassword();
+        mitmIsRestarting = true; // prevent scheduleMitmRestart from firing
+      }
+    });
+    serverProcess.on("exit", (code) => {
+      log(`Server exited (code: ${code})`);
+      serverProcess = null;
+      serverPid = null;
+      try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
+      try { fs.unlinkSync(LOCK_FILE); } catch { /* ignore */ }
+      // Auto-restart on unexpected exit
+      if (code !== 0 && !mitmIsRestarting) scheduleMitmRestart(apiKey);
+    });
+  }
+
+  const health = await pollMitmHealth(8000, MITM_PORT);
+  if (!health) {
+    if (serverProcess && !serverProcess.killed) { try { serverProcess.kill(); } catch { /* ignore */ } serverProcess = null; }
+    const processUsing443 = getProcessUsingPort443();
+    const portInfo = processUsing443 ? ` Port 443 already in use by ${processUsing443}.` : "";
+    const reason = startError || `Check sudo password or port 443 access.${portInfo}`;
+    throw new Error(`MITM server failed to start. ${reason}`);
+  }
+
+  if (_updateSettings) await _updateSettings({ mitmCertInstalled: true }).catch(() => { });
+
+  log(`✅ Server healthy (PID: ${serverPid || health.pid})`);
+
+  // Log DNS status per tool
+  const dnsStatus = checkAllDNSStatus();
+  for (const [tool, active] of Object.entries(dnsStatus)) {
+    log(`🌐 DNS ${tool}: ${active ? "✅ active" : "❌ inactive"}`);
+  }
+
+  await saveMitmSettings(true, sudoPassword);
+  if (sudoPassword) setCachedPassword(sudoPassword);
+
+  // Server is healthy — remove lock file (PID file persists as the marker)
+  try { fs.unlinkSync(LOCK_FILE); } catch { /* ignore */ }
+
+  return { running: true, pid: serverPid };
+  } catch (e) {
+    // Clean up lock on any failure
+    try { fs.unlinkSync(LOCK_FILE); } catch { /* ignore */ }
+    throw e;
+  }
+}
+
+/**
+ * Stop MITM server — removes ALL tool DNS entries first, then kills server
+ */
+async function stopServer(sudoPassword) {
+  // Prevent auto-restart from triggering on intentional stop
+  mitmIsRestarting = true;
+  mitmRestartCount = 0;
+  log("⏹ Stopping server...");
+
+  // Kill server process
+  const proc = serverProcess;
+  const pidToKill = proc && !proc.killed
+    ? proc.pid
+    : (() => { try { return parseInt(fs.readFileSync(PID_FILE, "utf-8").trim(), 10); } catch { return null; } })();
+
+  if (pidToKill && isProcessAlive(pidToKill)) {
+    log(`Killing server (PID: ${pidToKill})...`);
+    killProcess(pidToKill, false, sudoPassword);
+    await new Promise(r => setTimeout(r, 1000));
+    if (isProcessAlive(pidToKill)) killProcess(pidToKill, true, sudoPassword);
+  }
+  serverProcess = null;
+  serverPid = null;
+
+  if (IS_WIN) {
+    const hostsFile = path.join(process.env.SystemRoot || "C:\\Windows", "System32", "drivers", "etc", "hosts");
+    const allHosts = Object.values(TOOL_HOSTS).flat();
+    try {
+      const { isAdmin, runElevatedPowerShell, quotePs } = require("./winElevated.js");
+      if (isAdmin()) {
+        // Direct fs write — bypass PowerShell to avoid parser pitfalls
+        const content = fs.readFileSync(hostsFile, "utf8");
+        const filtered = content.split(/\r?\n/).filter(l => !allHosts.some(h => l.includes(h))).join("\r\n");
+        const next = filtered.replace(/[\r\n\s]+$/g, "") + "\r\n";
+        if (next !== content) fs.writeFileSync(hostsFile, next, "utf8");
+        try { require("child_process").execSync("ipconfig /flushdns", { windowsHide: true, stdio: "ignore" }); } catch { /* ignore */ }
+        log("🌐 DNS: ✅ all tool hosts removed");
+      } else {
+        const hostsList = allHosts.map(quotePs).join(",");
+        const script = `
+          $hosts = @(${hostsList})
+          $lines = Get-Content -LiteralPath ${quotePs(hostsFile)}
+          $filtered = $lines | Where-Object {
+            $line = $_
+            -not ($hosts | Where-Object { $line -match [regex]::Escape($_) })
+          }
+          Set-Content -LiteralPath ${quotePs(hostsFile)} -Value $filtered
+          ipconfig /flushdns | Out-Null
+        `;
+        await runElevatedPowerShell(script);
+      }
+    } catch (e) { err(`Failed to clean hosts: ${e.message}`); }
+  } else {
+    await removeAllDNSEntries(sudoPassword);
+  }
+
+  // Unset NODE_EXTRA_CA_CERTS so apps don't keep trusting stale MITM cert
+  if (IS_MAC) {
+    exec(`launchctl unsetenv NODE_EXTRA_CA_CERTS`, { windowsHide: true }, (e) => {
+      if (e) log(`[launchctl] Failed to unset NODE_EXTRA_CA_CERTS: ${e.message}`);
+      else log(`[launchctl] NODE_EXTRA_CA_CERTS unset`);
+    });
+  } else if (IS_WIN) {
+    exec(`reg delete HKCU\\Environment /F /V NODE_EXTRA_CA_CERTS`, { windowsHide: true }, (e) => {
+      if (e) log(`[reg] Failed to unset NODE_EXTRA_CA_CERTS: ${e.message}`);
+      else log(`[reg] NODE_EXTRA_CA_CERTS unset`);
+    });
+  }
+
+  try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
+  try { fs.unlinkSync(LOCK_FILE); } catch { /* ignore */ }
+  await saveMitmSettings(false, null);
+  mitmIsRestarting = false;
+
+  return { running: false, pid: null };
+}
+
+/**
+ * Enable DNS for a specific tool (requires server running)
+ */
+async function enableToolDNS(tool, sudoPassword) {
+  const status = await getMitmStatus();
+  if (!status.running) throw new Error("MITM server is not running. Start the server first.");
+
+  const password = sudoPassword || getCachedPassword() || await loadEncryptedPassword();
+  await addDNSEntry(tool, password);
+  await saveDnsToolState(tool, true);
+  return { success: true };
+}
+
+/**
+ * Disable DNS for a specific tool
+ */
+async function disableToolDNS(tool, sudoPassword) {
+  const password = sudoPassword || getCachedPassword() || await loadEncryptedPassword();
+  await removeDNSEntry(tool, password);
+  await saveDnsToolState(tool, false);
+  return { success: true };
+}
+
+/**
+ * Install Root CA to system trust store (standalone, no server start)
+ */
+async function trustCert(sudoPassword) {
+  const rootCACertPath = path.join(MITM_DIR, "rootCA.crt");
+  if (!fs.existsSync(rootCACertPath)) throw new Error("Root CA not found. Start server first to generate it.");
+  const { installCert } = require("./cert/install");
+  if (!IS_WIN && !IS_MAC && !isSudoAvailable()) {
+    log(`🔐 Cert: system trust unavailable (no sudo). Use file: ${rootCACertPath}`);
+    return;
+  }
+  const password = sudoPassword || getCachedPassword() || await loadEncryptedPassword();
+  if (!password && isSudoPasswordRequired()) throw new Error("Sudo password required to trust certificate");
+  await installCert(password, rootCACertPath);
+  if (password) setCachedPassword(password);
+}
+
+// Legacy aliases for backward compatibility
+const startMitm = startServer;
+const stopMitm = stopServer;
+
+module.exports = {
+  getMitmStatus,
+  startServer,
+  stopServer,
+  enableToolDNS,
+  disableToolDNS,
+  trustCert,
+  // Legacy
+  startMitm,
+  stopMitm,
+  getCachedPassword,
+  setCachedPassword,
+  loadEncryptedPassword,
+  clearEncryptedPassword,
+  isSudoPasswordRequired,
+  initDbHooks,
+  restoreToolDNS,
+  hasDnsPrivilege,
+  removeAllDNSEntriesSync,
+};
diff --git a/src/mitm/paths.js b/src/mitm/paths.js
new file mode 100644
index 0000000..892c225
--- /dev/null
+++ b/src/mitm/paths.js
@@ -0,0 +1,32 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const APP_NAME = "9router";
+
+function defaultDir() {
+  if (process.platform === "win32") {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), APP_NAME);
+  }
+  return path.join(os.homedir(), `.${APP_NAME}`);
+}
+
+function getDataDir() {
+  const configured = process.env.DATA_DIR;
+  if (!configured) return defaultDir();
+  try {
+    fs.mkdirSync(configured, { recursive: true });
+    return configured;
+  } catch (e) {
+    if (e?.code === "EACCES" || e?.code === "EPERM") {
+      console.warn(`[DATA_DIR] '${configured}' not writable → fallback ~/.${APP_NAME}`);
+      return defaultDir();
+    }
+    throw e;
+  }
+}
+
+const DATA_DIR = getDataDir();
+const MITM_DIR = path.join(DATA_DIR, "mitm");
+
+module.exports = { DATA_DIR, MITM_DIR };
diff --git a/src/mitm/server.js b/src/mitm/server.js
new file mode 100644
index 0000000..d675e6a
--- /dev/null
+++ b/src/mitm/server.js
@@ -0,0 +1,440 @@
+const https = require("https");
+const http2 = require("http2");
+const tls = require("tls");
+const fs = require("fs");
+const path = require("path");
+const dns = require("dns");
+const { promisify } = require("util");
+const { execSync } = require("child_process");
+const { log, err, dumpRequest, createResponseDumper, clearDumpDir } = require("./logger");
+const { IS_DEV, LSOF_BIN, TARGET_HOSTS, URL_PATTERNS, MODEL_SYNONYMS, MODEL_PATTERNS, MODEL_NO_MAP, getToolForHost } = require("./config");
+const { DATA_DIR, MITM_DIR } = require("./paths");
+const { generateCert, getCertForDomain } = require("./cert/generate");
+const { getMitmAlias } = require("./dbReader");
+const { applyAntigravityIdeVersionOverride } = require("./antigravityIdeVersion");
+const LOCAL_PORT = 443;
+const IS_WIN = process.platform === "win32";
+const ENABLE_FILE_LOG = IS_DEV;
+
+// Clear stale dump files on every MITM start (prevents unbounded disk usage)
+clearDumpDir();
+const INTERNAL_REQUEST_HEADER = { name: "x-request-source", value: "local" };
+
+// Host rewrite for upstream forward: PROD cloudcode-pa is rate-limited (429),
+// daily-cloudcode-pa (dev endpoint) accepts same body+token. Same trick as open-sse.
+const HOST_REWRITE = {
+  "cloudcode-pa.googleapis.com": "daily-cloudcode-pa.googleapis.com",
+};
+
+const handlers = {
+  antigravity: require("./handlers/antigravity"),
+  copilot: require("./handlers/copilot"),
+  kiro: require("./handlers/kiro"),
+  cursor: require("./handlers/cursor"),
+};
+
+// ── SSL / SNI ─────────────────────────────────────────────────
+
+const certCache = new Map();
+let rootCAPem;
+
+function sniCallback(servername, cb) {
+  try {
+    if (certCache.has(servername)) return cb(null, certCache.get(servername));
+    const certData = getCertForDomain(servername);
+    if (!certData) return cb(new Error(`Failed to generate cert for ${servername}`));
+    const ctx = require("tls").createSecureContext({
+      key: certData.key,
+      cert: `${certData.cert}\n${rootCAPem}`
+    });
+    certCache.set(servername, ctx);
+    cb(null, ctx);
+  } catch (e) {
+    err(`SNI error for ${servername}: ${e.message}`);
+    cb(e);
+  }
+}
+
+let sslOptions;
+try {
+  if (!fs.existsSync(path.join(MITM_DIR, "rootCA.key")) || !fs.existsSync(path.join(MITM_DIR, "rootCA.crt"))) {
+    log("Root CA missing, generating...");
+    generateCert();
+  }
+
+  const rootKey = fs.readFileSync(path.join(MITM_DIR, "rootCA.key"));
+  const rootCert = fs.readFileSync(path.join(MITM_DIR, "rootCA.crt"));
+  rootCAPem = rootCert.toString("utf8");
+  sslOptions = { key: rootKey, cert: rootCert, SNICallback: sniCallback };
+} catch (e) {
+  err(`Root CA not found: ${e.message}`);
+  process.exit(1);
+}
+
+// ── Helpers ───────────────────────────────────────────────────
+
+const cachedTargetIPs = {};
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+async function resolveTargetIP(hostname) {
+  const cached = cachedTargetIPs[hostname];
+  if (cached && Date.now() - cached.ts < CACHE_TTL_MS) return cached.ip;
+  const resolver = new dns.Resolver();
+  resolver.setServers(["8.8.8.8"]);
+  const resolve4 = promisify(resolver.resolve4.bind(resolver));
+  const addresses = await resolve4(hostname);
+  cachedTargetIPs[hostname] = { ip: addresses[0], ts: Date.now() };
+  return cachedTargetIPs[hostname].ip;
+}
+
+function collectBodyRaw(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", chunk => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+// Extract model from URL path (Gemini), body (OpenAI/Anthropic), or Kiro conversationState
+function extractModel(url, body) {
+  const urlMatch = url.match(/\/models\/([^/:]+)/);
+  if (urlMatch) return urlMatch[1];
+  
+  // Skip parsing if body is binary (AWS EventStream, Protocol Buffers, etc.)
+  if (isBinaryData(body)) return null;
+  
+  try {
+    const parsed = JSON.parse(body.toString());
+    if (parsed.conversationState) {
+      return parsed.conversationState.currentMessage?.userInputMessage?.modelId || null;
+    }
+    return parsed.model || null;
+  } catch { return null; }
+}
+
+// Detect binary data vs JSON text
+function isBinaryData(buffer) {
+  if (!buffer || buffer.length === 0) return false;
+  // AWS EventStream signature: first 4 bytes = frame length (big-endian uint32)
+  // Check for non-printable chars in first 100 bytes (common in binary protocols)
+  const sample = buffer.slice(0, Math.min(100, buffer.length));
+  let nonPrintable = 0;
+  for (let i = 0; i < sample.length; i++) {
+    const byte = sample[i];
+    // Count non-ASCII printable chars (excluding whitespace)
+    if (byte < 0x20 && byte !== 0x09 && byte !== 0x0A && byte !== 0x0D) {
+      nonPrintable++;
+    }
+    if (byte > 0x7E) nonPrintable++;
+  }
+  // If >30% non-printable, treat as binary
+  return (nonPrintable / sample.length) > 0.3;
+}
+
+function getMappedModel(tool, model) {
+  if (!model) return null;
+  try {
+    const aliases = getMitmAlias(tool);
+    if (!aliases) return null;
+    // Normalize via synonym map (e.g., public AG names -> backend model ids)
+    const normalizedModel = String(model).replace(/^models\//, "");
+    const lookup = MODEL_SYNONYMS?.[tool]?.[normalizedModel] || normalizedModel;
+    if (aliases[lookup]) return aliases[lookup];
+    // Prefix match fallback
+    const prefixKey = Object.keys(aliases).find(k => k && aliases[k] && (lookup.startsWith(k) || k.startsWith(lookup)));
+    if (prefixKey) return aliases[prefixKey];
+    // Pattern fallback: catches AG renamed variants (e.g. deprecated pro IDs → gemini-pro-agent)
+    const patterns = MODEL_PATTERNS?.[tool] || [];
+    for (const { match, alias } of patterns) {
+      if (match.test(lookup) && aliases[alias]) return aliases[alias];
+    }
+    return null;
+  } catch { return null; }
+}
+
+/**
+ * Forward request to real upstream.
+ * Optional onResponse(rawBuffer) callback — if provided, tees the response
+ * so it's both forwarded to client AND passed to the callback for inspection.
+ * Also tees full stream into a dump file when ENABLE_FILE_LOG is on.
+ */
+async function passthrough(req, res, bodyBuffer, onResponse) {
+  const originalHost = (req.headers.host || TARGET_HOSTS[0]).split(":")[0];
+  // Only rewrite host for chat endpoints — daily-cloudcode-pa rejects auth/login requests
+  const isChatEndpoint = req.url.includes(":generateContent") || req.url.includes(":streamGenerateContent");
+  const targetHost = isChatEndpoint ? (HOST_REWRITE[originalHost] || originalHost) : originalHost;
+  const dumper = ENABLE_FILE_LOG ? createResponseDumper(req, "passthrough") : null;
+
+  const tool = getToolForHost(req.headers.host);
+  const versionOverride = tool === "antigravity"
+    ? applyAntigravityIdeVersionOverride(bodyBuffer, req.headers)
+    : { bodyBuffer, headers: req.headers };
+  const bodyForForwarding = versionOverride.bodyBuffer;
+  const headersForForwarding = { ...versionOverride.headers, host: targetHost };
+  if (bodyForForwarding !== bodyBuffer) {
+    headersForForwarding["content-length"] = String(bodyForForwarding.length);
+  }
+
+  // ALPN negotiate: try HTTP/2 first (like browsers/mitmweb), fallback HTTP/1.1
+  try {
+    const proto = await negotiateAlpn(targetHost);
+    if (proto === "h2") {
+      return await passthroughHttp2(req, res, bodyForForwarding, headersForForwarding, targetHost, onResponse, dumper);
+    }
+  } catch (e) {
+    err(`[mitm] ALPN negotiate failed: ${e.message}, fallback to HTTP/1.1`);
+  }
+
+  return passthroughHttps(req, res, bodyForForwarding, headersForForwarding, targetHost, onResponse, dumper);
+}
+
+// ── ALPN negotiation cache ────────────────────────────────────
+const alpnCache = new Map(); // host → "h2" | "http/1.1"
+async function negotiateAlpn(host) {
+  if (alpnCache.has(host)) return alpnCache.get(host);
+  const ip = await resolveTargetIP(host);
+  return new Promise((resolve, reject) => {
+    const socket = tls.connect({
+      host: ip, port: 443, servername: host,
+      ALPNProtocols: ["h2", "http/1.1"], rejectUnauthorized: false,
+    }, () => {
+      const proto = socket.alpnProtocol || "http/1.1";
+      alpnCache.set(host, proto);
+      log(`🔗 [mitm] ALPN ${host} → ${proto}`);
+      socket.end();
+      resolve(proto);
+    });
+    socket.once("error", reject);
+    socket.setTimeout(5000, () => { socket.destroy(new Error("ALPN timeout")); });
+  });
+}
+
+// HTTP/2 passthrough using node:http2 native
+async function passthroughHttp2(req, res, bodyBuffer, headers, targetHost, onResponse, dumper) {
+  const targetIP = await resolveTargetIP(targetHost);
+  // HTTP/2 pseudo-headers required; strip HTTP/1.1-only headers
+  const h2Headers = {};
+  for (const [k, v] of Object.entries(headers)) {
+    const lk = k.toLowerCase();
+    if (lk === "host" || lk === "connection" || lk === "keep-alive" ||
+        lk === "transfer-encoding" || lk === "upgrade" || lk === "proxy-connection") continue;
+    h2Headers[lk] = v;
+  }
+  h2Headers[":method"] = req.method;
+  h2Headers[":path"] = req.url;
+  h2Headers[":scheme"] = "https";
+  h2Headers[":authority"] = targetHost;
+
+  return new Promise((resolve) => {
+    const client = http2.connect(`https://${targetHost}`, {
+      createConnection: () => tls.connect({
+        host: targetIP, port: 443, servername: targetHost,
+        ALPNProtocols: ["h2"], rejectUnauthorized: false,
+      }),
+    });
+    client.once("error", (e) => {
+      err(`[mitm] http2 client error: ${e.message}`);
+      if (dumper) { dumper.writeChunk(`\n[ERROR h2] ${e.message}\n`); dumper.end(); }
+      if (!res.headersSent) res.writeHead(502);
+      if (!res.writableEnded) res.end("Bad Gateway");
+      try { client.close(); } catch {}
+      resolve();
+    });
+
+    const stream = client.request(h2Headers, { endStream: bodyBuffer.length === 0 });
+    if (bodyBuffer.length > 0) stream.end(bodyBuffer);
+
+    stream.once("response", (responseHeaders) => {
+      const status = responseHeaders[":status"];
+      // Filter pseudo-headers + connection-specific
+      const outHeaders = {};
+      for (const [k, v] of Object.entries(responseHeaders)) {
+        if (k.startsWith(":")) continue;
+        if (k === "connection" || k === "keep-alive" || k === "transfer-encoding") continue;
+        outHeaders[k] = v;
+      }
+      res.writeHead(status, outHeaders);
+      if (dumper) dumper.writeHeader(status, outHeaders);
+
+      const chunks = [];
+      stream.on("data", chunk => {
+        if (dumper) dumper.writeChunk(chunk);
+        if (onResponse) chunks.push(chunk);
+        res.write(chunk);
+      });
+      stream.on("end", () => {
+        if (dumper) dumper.end();
+        if (!res.writableEnded) res.end();
+        if (onResponse) try { onResponse(Buffer.concat(chunks), outHeaders); } catch {}
+        try { client.close(); } catch {}
+        resolve();
+      });
+    });
+    stream.once("error", (e) => {
+      err(`[mitm] http2 stream error: ${e.message}`);
+      if (dumper) { dumper.writeChunk(`\n[ERROR h2-stream] ${e.message}\n`); dumper.end(); }
+      if (!res.headersSent) res.writeHead(502);
+      if (!res.writableEnded) res.end();
+      try { client.close(); } catch {}
+      resolve();
+    });
+  });
+}
+
+// Fallback: raw https.request HTTP/1.1 with custom DNS (bypasses /etc/hosts MITM loop)
+async function passthroughHttps(req, res, bodyBuffer, headers, targetHost, onResponse, dumper) {
+  const targetIP = await resolveTargetIP(targetHost);
+  const forwardReq = https.request({
+    hostname: targetIP,
+    port: 443,
+    path: req.url,
+    method: req.method,
+    headers,
+    servername: targetHost,
+    rejectUnauthorized: false
+  }, (forwardRes) => {
+    res.writeHead(forwardRes.statusCode, forwardRes.headers);
+    if (dumper) dumper.writeHeader(forwardRes.statusCode, forwardRes.headers);
+
+    if (!onResponse && !dumper) {
+      forwardRes.pipe(res);
+      return;
+    }
+
+    const chunks = [];
+    forwardRes.on("data", chunk => {
+      if (dumper) dumper.writeChunk(chunk);
+      if (onResponse) chunks.push(chunk);
+      res.write(chunk);
+    });
+    forwardRes.on("end", () => {
+      if (dumper) dumper.end();
+      res.end();
+      if (onResponse) try { onResponse(Buffer.concat(chunks), forwardRes.headers); } catch { /* ignore */ }
+    });
+  });
+
+  forwardReq.on("error", (e) => {
+    err(`Passthrough error: ${e.message}`);
+    if (dumper) { dumper.writeChunk(`\n[ERROR] ${e.message}\n`); dumper.end(); }
+    if (!res.headersSent) res.writeHead(502);
+    res.end("Bad Gateway");
+  });
+
+  if (bodyBuffer.length > 0) forwardReq.write(bodyBuffer);
+  forwardReq.end();
+}
+
+// ── Request handler ───────────────────────────────────────────
+
+const server = https.createServer(sslOptions, async (req, res) => {
+  try {
+    if (req.url === "/_mitm_health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true, pid: process.pid }));
+      return;
+    }
+
+    const bodyBuffer = await collectBodyRaw(req);
+    if (ENABLE_FILE_LOG) dumpRequest(req, bodyBuffer, "raw");
+
+    // Anti-loop: skip requests from 9Router
+    if (req.headers[INTERNAL_REQUEST_HEADER.name] === INTERNAL_REQUEST_HEADER.value) {
+      return passthrough(req, res, bodyBuffer);
+    }
+
+    const tool = getToolForHost(req.headers.host);
+    if (!tool) return passthrough(req, res, bodyBuffer);
+
+    const patterns = URL_PATTERNS[tool] || [];
+    const isChat = patterns.some(p => req.url.includes(p));
+    if (!isChat) return passthrough(req, res, bodyBuffer);
+
+    // Cursor uses binary proto — model extraction not possible at this layer.
+    // Delegate directly to handler which decodes proto internally.
+    if (tool === "cursor") {
+      return handlers[tool].intercept(req, res, bodyBuffer, null, passthrough);
+    }
+
+    const model = extractModel(req.url, bodyBuffer);
+
+    // Intentional passthrough: some models must never be re-routed (e.g. Antigravity
+    // tab-autocomplete) so latency-critical inline completion stays native. Silent — this
+    // is by design, not a leak, and fires per keystroke. See MODEL_NO_MAP in config.js.
+    if (model && (MODEL_NO_MAP[tool] || []).some((re) => re.test(model))) {
+      return passthrough(req, res, bodyBuffer);
+    }
+
+    const mappedModel = getMappedModel(tool, model);
+    if (!mappedModel) {
+      return passthrough(req, res, bodyBuffer);
+    }
+
+    return handlers[tool].intercept(req, res, bodyBuffer, mappedModel, passthrough);
+  } catch (e) {
+    err(`Unhandled error: ${e.message}`);
+    if (!res.headersSent) res.writeHead(500, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: { message: e.message, type: "mitm_error" } }));
+  }
+});
+
+// Kill only processes LISTENING on LOCAL_PORT (not outbound connections)
+function killPort(port) {
+  try {
+    let pidList = [];
+    if (IS_WIN) {
+      const psCmd = `powershell -NonInteractive -WindowStyle Hidden -Command ` +
+        `"Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess"`;
+      const out = execSync(psCmd, { encoding: "utf-8", windowsHide: true }).trim();
+      if (!out) return;
+      pidList = out.split(/\r?\n/).map(s => s.trim()).filter(p => p && Number(p) !== process.pid && Number(p) > 4);
+    } else {
+      const out = execSync(`${LSOF_BIN} -nP -iTCP:${port} -sTCP:LISTEN -t`, { encoding: "utf-8", windowsHide: true }).trim();
+      if (!out) return;
+      pidList = out.split("\n").filter(p => p && Number(p) !== process.pid);
+    }
+    if (pidList.length === 0) return;
+    pidList.forEach(pid => {
+      try {
+        if (IS_WIN) execSync(`taskkill /F /PID ${pid}`, { windowsHide: true });
+        else process.kill(Number(pid), "SIGKILL");
+      } catch (e) {
+        err(`Failed to kill PID ${pid}: ${e.message}`);
+      }
+    });
+    log(`Killed ${pidList.length} process(es) on port ${port}`);
+  } catch (e) {
+    if (e.status !== 1) throw e;
+  }
+}
+
+try {
+  killPort(LOCAL_PORT);
+} catch (e) {
+  err(`Cannot kill process on port ${LOCAL_PORT}: ${e.message}`);
+  process.exit(1);
+}
+
+server.listen(LOCAL_PORT, () => log(`🚀 Server ready on :${LOCAL_PORT}`));
+
+server.on("error", (e) => {
+  if (e.code === "EADDRINUSE") err(`Port ${LOCAL_PORT} already in use`);
+  else if (e.code === "EACCES") err(`Permission denied for port ${LOCAL_PORT}`);
+  else err(e.message);
+  process.exit(1);
+});
+
+const { removeAllDNSEntriesSync } = require("./dns/dnsConfig");
+let isShuttingDown = false;
+const shutdown = () => {
+  if (isShuttingDown) return;
+  isShuttingDown = true;
+  // Strip tool hosts from /etc/hosts so other apps aren't broken after exit
+  removeAllDNSEntriesSync();
+  const forceExit = setTimeout(() => process.exit(0), 1500);
+  server.close(() => { clearTimeout(forceExit); process.exit(0); });
+};
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+if (process.platform === "win32") process.on("SIGBREAK", shutdown);
diff --git a/src/mitm/winElevated.js b/src/mitm/winElevated.js
new file mode 100644
index 0000000..0ff6aa5
--- /dev/null
+++ b/src/mitm/winElevated.js
@@ -0,0 +1,81 @@
+const { exec, execSync } = require("child_process");
+
+const IS_WIN = process.platform === "win32";
+
+/**
+ * Detect if current Windows process has admin rights (no UAC popup needed).
+ * Uses `net session` which only succeeds when elevated.
+ */
+function isAdmin() {
+  if (IS_WIN) {
+    try {
+      execSync("net session >nul 2>&1", { windowsHide: true, stdio: "ignore" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return typeof process.getuid === "function" && process.getuid() === 0;
+}
+
+/**
+ * Quote a string safely for PowerShell single-quoted literal.
+ */
+function quotePs(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+/**
+ * Run PowerShell script — escalated via UAC popup if not already admin.
+ * Returns Promise resolving on exit code 0, rejecting otherwise.
+ *
+ * IMPORTANT: each call triggers ONE UAC popup. Batch multiple admin tasks
+ * into a single script string to minimize popups.
+ */
+function runElevatedPowerShell(script) {
+  if (!IS_WIN) return Promise.reject(new Error("Windows-only"));
+
+  const encoded = Buffer.from(script, "utf16le").toString("base64");
+
+  // If already admin, run directly — zero popup
+  if (isAdmin()) {
+    return new Promise((resolve, reject) => {
+      exec(
+        `powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encoded}`,
+        { windowsHide: true },
+        (error, stdout, stderr) => {
+          if (error) reject(new Error(stderr || error.message));
+          else resolve(stdout);
+        }
+      );
+    });
+  }
+
+  // Not admin — wrap with Start-Process -Verb RunAs (UAC popup)
+  const wrapper = `
+    $proc = Start-Process powershell -ArgumentList @(
+      '-NoProfile','-NonInteractive','-ExecutionPolicy','Bypass',
+      '-WindowStyle','Hidden','-EncodedCommand','${encoded}'
+    ) -Verb RunAs -Wait -PassThru -WindowStyle Hidden;
+    if ($proc.ExitCode -ne 0) { throw "Elevated command exited with code $($proc.ExitCode)" }
+  `;
+
+  return new Promise((resolve, reject) => {
+    exec(
+      `powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command ${quotePs(wrapper)}`,
+      { windowsHide: true },
+      (error, stdout, stderr) => {
+        if (error) {
+          const msg = stderr || error.message;
+          if (msg.includes("canceled by the user") || msg.includes("operation was canceled")) {
+            reject(new Error("User canceled UAC prompt"));
+          } else {
+            reject(new Error(msg));
+          }
+        } else resolve(stdout);
+      }
+    );
+  });
+}
+
+module.exports = { isAdmin, runElevatedPowerShell, quotePs };
diff --git a/src/models/index.js b/src/models/index.js
new file mode 100644
index 0000000..99444f6
--- /dev/null
+++ b/src/models/index.js
@@ -0,0 +1,38 @@
+// Database Models - Export all from localDb
+export {
+  getProviderConnections,
+  getProviderConnectionById,
+  createProviderConnection,
+  updateProviderConnection,
+  deleteProviderConnection,
+  getProviderNodes,
+  getProviderNodeById,
+  createProviderNode,
+  updateProviderNode,
+  deleteProviderNode,
+  getProxyPools,
+  getProxyPoolById,
+  createProxyPool,
+  updateProxyPool,
+  deleteProxyPool,
+  deleteProviderConnectionsByProvider,
+  getCombos,
+  getComboById,
+  getComboByName,
+  createCombo,
+  updateCombo,
+  deleteCombo,
+  getModelAliases,
+  setModelAlias,
+  deleteModelAlias,
+  getCustomModels,
+  addCustomModel,
+  deleteCustomModel,
+  getMitmAlias,
+  setMitmAliasAll,
+  getApiKeys,
+  createApiKey,
+  deleteApiKey,
+  validateApiKey,
+  isCloudEnabled,
+} from "@/lib/localDb";
diff --git a/src/proxy.js b/src/proxy.js
new file mode 100644
index 0000000..566dd14
--- /dev/null
+++ b/src/proxy.js
@@ -0,0 +1,9 @@
+import { proxy as dashboardProxy } from "./dashboardGuard";
+
+export default async function proxy(request) {
+  return dashboardProxy(request);
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon\\.ico).*)"],
+};
diff --git a/src/shared/components/AddCustomEmbeddingModal.js b/src/shared/components/AddCustomEmbeddingModal.js
new file mode 100644
index 0000000..db17fe7
--- /dev/null
+++ b/src/shared/components/AddCustomEmbeddingModal.js
@@ -0,0 +1,183 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import PropTypes from "prop-types";
+import { Modal, Input, Button, Badge } from "@/shared/components";
+
+const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+
+// Dual-mode modal: edit when `node` provided, add otherwise
+export default function AddCustomEmbeddingModal({ isOpen, onClose, onCreated, onSaved, node }) {
+  const isEdit = !!node;
+  const [formData, setFormData] = useState({
+    name: "",
+    prefix: "",
+    baseUrl: DEFAULT_BASE_URL,
+  });
+  const [submitting, setSubmitting] = useState(false);
+  const [checkKey, setCheckKey] = useState("");
+  const [checkModelId, setCheckModelId] = useState("");
+  const [validating, setValidating] = useState(false);
+  const [validationResult, setValidationResult] = useState(null);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    setValidationResult(null);
+    setCheckKey("");
+    setCheckModelId("");
+    if (isEdit) {
+      setFormData({
+        name: node.name || "",
+        prefix: node.prefix || "",
+        baseUrl: node.baseUrl || DEFAULT_BASE_URL,
+      });
+    } else {
+      setFormData({ name: "", prefix: "", baseUrl: DEFAULT_BASE_URL });
+    }
+  }, [isOpen, isEdit, node]);
+
+  const handleSubmit = async () => {
+    if (!formData.name.trim() || !formData.prefix.trim() || !formData.baseUrl.trim()) return;
+    setSubmitting(true);
+    try {
+      const url = isEdit ? `/api/provider-nodes/${node.id}` : "/api/provider-nodes";
+      const method = isEdit ? "PUT" : "POST";
+      const payload = {
+        name: formData.name,
+        prefix: formData.prefix,
+        baseUrl: formData.baseUrl,
+      };
+      if (!isEdit) payload.type = "custom-embedding";
+
+      const res = await fetch(url, {
+        method,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        if (isEdit) onSaved?.(data.node);
+        else onCreated?.(data.node);
+      }
+    } catch (error) {
+      console.log("Error saving custom embedding node:", error);
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleValidate = async () => {
+    setValidating(true);
+    try {
+      const res = await fetch("/api/provider-nodes/validate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          baseUrl: formData.baseUrl,
+          apiKey: checkKey,
+          type: "custom-embedding",
+          modelId: checkModelId.trim() || undefined,
+        }),
+      });
+      const data = await res.json();
+      setValidationResult(data);
+    } catch {
+      setValidationResult({ valid: false, error: "Network error" });
+    } finally {
+      setValidating(false);
+    }
+  };
+
+  const renderValidationResult = () => {
+    if (!validationResult) return null;
+    const { valid, error, dimensions } = validationResult;
+    if (valid) {
+      return (
+        <>
+          <Badge variant="success">Valid</Badge>
+          {dimensions && <span className="text-sm text-text-muted">{dimensions} dims</span>}
+        </>
+      );
+    }
+    return (
+      <div className="flex flex-col gap-1">
+        <Badge variant="error">Invalid</Badge>
+        {error && <span className="text-sm text-red-500">{error}</span>}
+      </div>
+    );
+  };
+
+  return (
+    <Modal isOpen={isOpen} title={isEdit ? "Edit Custom Embedding" : "Add Custom Embedding"} onClose={onClose}>
+      <div className="flex flex-col gap-4">
+        <Input
+          label="Name"
+          value={formData.name}
+          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+          placeholder="Voyage AI"
+          hint="Required. A friendly label for this embedding provider."
+        />
+        <Input
+          label="Prefix"
+          value={formData.prefix}
+          onChange={(e) => setFormData({ ...formData, prefix: e.target.value })}
+          placeholder="voyage"
+          hint="Required. Used as the provider prefix for model IDs (e.g. voyage/voyage-3)."
+        />
+        <Input
+          label="Base URL"
+          value={formData.baseUrl}
+          onChange={(e) => setFormData({ ...formData, baseUrl: e.target.value })}
+          placeholder="https://api.voyageai.com/v1"
+          hint="Most embedding APIs are OpenAI-compatible: Voyage, Cohere, Jina, Mistral, Together..."
+        />
+        <Input
+          label="API Key (for Check)"
+          type="password"
+          value={checkKey}
+          onChange={(e) => setCheckKey(e.target.value)}
+        />
+        <Input
+          label="Model ID (for Check)"
+          value={checkModelId}
+          onChange={(e) => setCheckModelId(e.target.value)}
+          placeholder="e.g. voyage-3, embed-english-v3.0, text-embedding-3-small"
+          hint="Required for validation. Will send a test embeddings request."
+        />
+        <div className="flex items-center gap-3">
+          <Button
+            onClick={handleValidate}
+            disabled={!checkKey || !checkModelId.trim() || validating || !formData.baseUrl.trim()}
+            variant="secondary"
+          >
+            {validating ? "Checking..." : "Check"}
+          </Button>
+          {renderValidationResult()}
+        </div>
+        <div className="flex gap-2">
+          <Button
+            onClick={handleSubmit}
+            fullWidth
+            disabled={!formData.name.trim() || !formData.prefix.trim() || !formData.baseUrl.trim() || submitting}
+          >
+            {submitting ? (isEdit ? "Saving..." : "Creating...") : (isEdit ? "Save" : "Create")}
+          </Button>
+          <Button onClick={onClose} variant="ghost" fullWidth>Cancel</Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+AddCustomEmbeddingModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  onClose: PropTypes.func.isRequired,
+  onCreated: PropTypes.func,
+  onSaved: PropTypes.func,
+  node: PropTypes.shape({
+    id: PropTypes.string,
+    name: PropTypes.string,
+    prefix: PropTypes.string,
+    baseUrl: PropTypes.string,
+  }),
+};
diff --git a/src/shared/components/Avatar.js b/src/shared/components/Avatar.js
new file mode 100644
index 0000000..ae0a755
--- /dev/null
+++ b/src/shared/components/Avatar.js
@@ -0,0 +1,88 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+export default function Avatar({
+  src,
+  alt = "Avatar",
+  name,
+  size = "md",
+  className,
+}) {
+  const sizes = {
+    xs: "size-6 text-xs",
+    sm: "size-8 text-sm",
+    md: "size-10 text-base",
+    lg: "size-12 text-lg",
+    xl: "size-16 text-xl",
+  };
+
+  // Get initials from name
+  const getInitials = (name) => {
+    if (!name) return "?";
+    const parts = name.split(" ");
+    if (parts.length >= 2) {
+      return `${parts[0][0]}${parts[1][0]}`.toUpperCase();
+    }
+    return name.substring(0, 2).toUpperCase();
+  };
+
+  // Generate color from name
+  const getColorFromName = (name) => {
+    if (!name) return "bg-primary";
+    const colors = [
+      "bg-red-500",
+      "bg-orange-500",
+      "bg-amber-500",
+      "bg-yellow-500",
+      "bg-lime-500",
+      "bg-green-500",
+      "bg-emerald-500",
+      "bg-teal-500",
+      "bg-cyan-500",
+      "bg-sky-500",
+      "bg-blue-500",
+      "bg-indigo-500",
+      "bg-violet-500",
+      "bg-purple-500",
+      "bg-fuchsia-500",
+      "bg-pink-500",
+      "bg-rose-500",
+    ];
+    const index = name.charCodeAt(0) % colors.length;
+    return colors[index];
+  };
+
+  if (src) {
+    return (
+      <div
+        className={cn(
+          "rounded-full bg-cover bg-center bg-no-repeat",
+          "ring-2 ring-white dark:ring-surface-dark shadow-sm",
+          sizes[size],
+          className
+        )}
+        style={{ backgroundImage: `url(${src})` }}
+        role="img"
+        aria-label={alt}
+      />
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "rounded-full flex items-center justify-center font-semibold text-white",
+        "ring-2 ring-white dark:ring-surface-dark shadow-sm",
+        sizes[size],
+        getColorFromName(name),
+        className
+      )}
+      role="img"
+      aria-label={alt}
+    >
+      {getInitials(name)}
+    </div>
+  );
+}
+
diff --git a/src/shared/components/Badge.js b/src/shared/components/Badge.js
new file mode 100644
index 0000000..6188cf5
--- /dev/null
+++ b/src/shared/components/Badge.js
@@ -0,0 +1,54 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+const variants = {
+  default: "bg-surface-2 text-text-muted",
+  primary: "bg-brand-500/10 text-brand-600 dark:text-brand-300",
+  success: "bg-green-500/10 text-green-600 dark:text-green-400",
+  warning: "bg-yellow-500/10 text-yellow-600 dark:text-yellow-400",
+  error: "bg-red-500/10 text-red-600 dark:text-red-400",
+  info: "bg-blue-500/10 text-blue-600 dark:text-blue-400",
+};
+
+const sizes = {
+  sm: "px-2 py-0.5 text-[10px]",
+  md: "px-2.5 py-1 text-xs",
+  lg: "px-3 py-1.5 text-sm",
+};
+
+export default function Badge({
+  children,
+  variant = "default",
+  size = "md",
+  dot = false,
+  icon,
+  className,
+}) {
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center gap-1.5 rounded-full font-semibold",
+        variants[variant],
+        sizes[size],
+        className
+      )}
+    >
+      {dot && (
+        <span
+          className={cn(
+            "size-1.5 rounded-full",
+            variant === "success" && "bg-green-500",
+            variant === "warning" && "bg-yellow-500",
+            variant === "error" && "bg-red-500",
+            variant === "info" && "bg-blue-500",
+            variant === "primary" && "bg-brand-500",
+            variant === "default" && "bg-gray-500"
+          )}
+        />
+      )}
+      {icon && <span className="material-symbols-outlined text-[14px]">{icon}</span>}
+      {children}
+    </span>
+  );
+}
diff --git a/src/shared/components/Button.js b/src/shared/components/Button.js
new file mode 100644
index 0000000..38ab4df
--- /dev/null
+++ b/src/shared/components/Button.js
@@ -0,0 +1,56 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+const variants = {
+  primary: "bg-brand-500 hover:bg-brand-600 text-white shadow-sm disabled:bg-surface-3 disabled:text-text-muted",
+  secondary: "bg-surface-2 hover:bg-surface-3 text-text-main border border-border disabled:opacity-50",
+  outline: "border border-border text-text-main hover:bg-surface-2 hover:border-brand-500/40",
+  ghost: "text-text-muted hover:bg-surface-2 hover:text-text-main",
+  danger: "bg-red-500 hover:bg-red-600 text-white shadow-sm disabled:bg-surface-3 disabled:text-text-muted",
+  success: "bg-green-600 hover:bg-green-700 text-white shadow-sm disabled:bg-surface-3 disabled:text-text-muted",
+};
+
+const sizes = {
+  sm: "h-7 px-3 text-xs rounded-[8px]",
+  md: "h-9 px-4 text-sm rounded-[10px]",
+  lg: "h-11 px-6 text-sm rounded-[10px]",
+};
+
+export default function Button({
+  children,
+  variant = "primary",
+  size = "md",
+  icon,
+  iconRight,
+  disabled = false,
+  loading = false,
+  fullWidth = false,
+  className,
+  ...props
+}) {
+  return (
+    <button
+      className={cn(
+        "inline-flex items-center justify-center gap-2 font-semibold transition-all duration-150 ease-out cursor-pointer",
+        "active:scale-[0.97] disabled:opacity-50 disabled:cursor-not-allowed disabled:active:scale-100",
+        variants[variant],
+        sizes[size],
+        fullWidth && "w-full",
+        className
+      )}
+      disabled={disabled || loading}
+      {...props}
+    >
+      {loading ? (
+        <span className="material-symbols-outlined animate-spin text-[18px]">progress_activity</span>
+      ) : icon ? (
+        <span className="material-symbols-outlined text-[18px]">{icon}</span>
+      ) : null}
+      {children}
+      {iconRight && !loading && (
+        <span className="material-symbols-outlined text-[18px]">{iconRight}</span>
+      )}
+    </button>
+  );
+}
diff --git a/src/shared/components/CapacityBadges.js b/src/shared/components/CapacityBadges.js
new file mode 100644
index 0000000..81c3418
--- /dev/null
+++ b/src/shared/components/CapacityBadges.js
@@ -0,0 +1,28 @@
+"use client";
+
+import { CAPACITY_META } from "@/shared/constants/models";
+import Tooltip from "./Tooltip";
+
+// Render small icon badges for a model's capabilities (only those set true).
+// colorOverride: force a single color class for all badges (default: per-cap color).
+// size: icon font-size in px (default 16).
+export default function CapacityBadges({ caps, className = "", colorOverride, size = 16 }) {
+  if (!caps) return null;
+  const active = Object.keys(CAPACITY_META).filter((k) => caps[k]);
+  if (active.length === 0) return null;
+
+  return (
+    <span className={`inline-flex items-center gap-0.5 ${className}`}>
+      {active.map((k) => (
+        <Tooltip key={k} text={`${CAPACITY_META[k].label} — ${CAPACITY_META[k].desc}`}>
+          <span
+            className={`material-symbols-outlined leading-none cursor-help ${colorOverride || CAPACITY_META[k].color}`}
+            style={{ fontSize: `${size}px` }}
+          >
+            {CAPACITY_META[k].icon}
+          </span>
+        </Tooltip>
+      ))}
+    </span>
+  );
+}
diff --git a/src/shared/components/Card.js b/src/shared/components/Card.js
new file mode 100644
index 0000000..765e622
--- /dev/null
+++ b/src/shared/components/Card.js
@@ -0,0 +1,116 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+export default function Card({
+  children,
+  title,
+  subtitle,
+  icon,
+  action,
+  padding = "md",
+  hover = false,
+  elev = false,
+  className,
+  ...props
+}) {
+  const paddings = {
+    none: "",
+    xs: "p-3",
+    sm: "p-4",
+    md: "p-6",
+    lg: "p-8",
+  };
+
+  return (
+    <div
+      className={cn(
+        "bg-surface border border-border-subtle",
+        elev ? "rounded-[14px] shadow-[var(--shadow-elev)]" : "rounded-[14px] shadow-[var(--shadow-soft)]",
+        hover && "hover:shadow-[var(--shadow-warm)] hover:border-brand-500/30 transition-all cursor-pointer",
+        paddings[padding],
+        className
+      )}
+      {...props}
+    >
+      {(title || action) && (
+        <div className="flex items-center justify-between mb-4">
+          <div className="flex items-center gap-3">
+            {icon && (
+              <div className="p-2 rounded-[10px] bg-bg text-text-muted">
+                <span className="material-symbols-outlined text-[20px]">{icon}</span>
+              </div>
+            )}
+            <div>
+              {title && (
+                <h3 className="text-text-main font-semibold">{title}</h3>
+              )}
+              {subtitle && (
+                <p className="text-sm text-text-muted">{subtitle}</p>
+              )}
+            </div>
+          </div>
+          {action}
+        </div>
+      )}
+      {children}
+    </div>
+  );
+}
+
+Card.Section = function CardSection({ children, className, ...props }) {
+  return (
+    <div
+      className={cn(
+        "p-4 rounded-[10px]",
+        "bg-bg border border-border-subtle",
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+Card.Row = function CardRow({ children, className, ...props }) {
+  return (
+    <div
+      className={cn(
+        "p-3 -mx-3 px-3 transition-colors",
+        "border-b border-border-subtle last:border-b-0",
+        "hover:bg-surface-2/50",
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+Card.ListItem = function CardListItem({
+  children,
+  actions,
+  className,
+  ...props
+}) {
+  return (
+    <div
+      className={cn(
+        "group flex items-center justify-between p-3 -mx-3 px-3",
+        "border-b border-border-subtle last:border-b-0",
+        "hover:bg-surface-2/50 transition-colors",
+        className
+      )}
+      {...props}
+    >
+      <div className="flex-1 min-w-0">{children}</div>
+      {actions && (
+        <div className="flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
+          {actions}
+        </div>
+      )}
+    </div>
+  );
+};
diff --git a/src/shared/components/ChangelogModal.js b/src/shared/components/ChangelogModal.js
new file mode 100644
index 0000000..591f6a9
--- /dev/null
+++ b/src/shared/components/ChangelogModal.js
@@ -0,0 +1,97 @@
+"use client";
+
+import { useEffect, useState, useRef } from "react";
+import { createPortal } from "react-dom";
+import PropTypes from "prop-types";
+import { marked } from "marked";
+import { GITHUB_CONFIG } from "@/shared/constants/config";
+
+marked.setOptions({ gfm: true, breaks: true });
+
+export default function ChangelogModal({ isOpen, onClose }) {
+  const [html, setHtml] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+  const modalRef = useRef(null);
+
+  useEffect(() => {
+    if (!isOpen || html) return;
+    setLoading(true);
+    setError("");
+    fetch(GITHUB_CONFIG.changelogUrl)
+      .then((res) => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.text();
+      })
+      .then((md) => setHtml(marked.parse(md)))
+      .catch((err) => setError(err.message || "Failed to load"))
+      .finally(() => setLoading(false));
+  }, [isOpen, html]);
+
+  useEffect(() => {
+    const handleClickOutside = (e) => {
+      if (modalRef.current && !modalRef.current.contains(e.target)) {
+        onClose();
+      }
+    };
+    if (isOpen) {
+      document.addEventListener("mousedown", handleClickOutside);
+      return () => document.removeEventListener("mousedown", handleClickOutside);
+    }
+  }, [isOpen, onClose]);
+
+  if (!isOpen || typeof document === "undefined") return null;
+
+  return createPortal(
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+      {/* Overlay */}
+      <div
+        className="absolute inset-0 bg-black/30 backdrop-blur-sm"
+        onClick={onClose}
+      />
+
+      {/* Modal content */}
+      <div
+        ref={modalRef}
+        className="relative w-full bg-surface border border-black/10 dark:border-white/10 rounded-xl shadow-2xl animate-in fade-in zoom-in-95 duration-200 max-w-3xl flex flex-col max-h-[85vh]"
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between p-3 border-b border-black/5 dark:border-white/5">
+          <h2 className="text-lg font-semibold text-text-main">Change Log</h2>
+          <button
+            onClick={onClose}
+            className="p-1.5 rounded-lg text-text-muted hover:bg-black/5 dark:hover:bg-white/5 transition-colors"
+            aria-label="Close"
+          >
+            <span className="material-symbols-outlined text-[20px]">close</span>
+          </button>
+        </div>
+
+        {/* Body */}
+        <div className="p-6 overflow-y-auto flex-1">
+          {loading && (
+            <div className="flex items-center justify-center py-10 text-text-muted">
+              <span className="material-symbols-outlined animate-spin mr-2">progress_activity</span>
+              Loading...
+            </div>
+          )}
+          {error && (
+            <div className="text-red-500 py-4">Failed to load changelog: {error}</div>
+          )}
+          {!loading && !error && html && (
+            <div
+              className="changelog-body text-text-main"
+              dangerouslySetInnerHTML={{ __html: html }}
+            />
+          )}
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+}
+
+ChangelogModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  onClose: PropTypes.func.isRequired,
+};
diff --git a/src/shared/components/ComboFormModal.js b/src/shared/components/ComboFormModal.js
new file mode 100644
index 0000000..d80732d
--- /dev/null
+++ b/src/shared/components/ComboFormModal.js
@@ -0,0 +1,176 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import Modal from "./Modal";
+import Input from "./Input";
+import Button from "./Button";
+import ModelSelectModal from "./ModelSelectModal";
+
+const VALID_NAME_REGEX = /^[a-zA-Z0-9_.\-]+$/;
+
+// Inline editable model item
+function ModelItem({ index, model, isFirst, isLast, onEdit, onMoveUp, onMoveDown, onRemove }) {
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState(model);
+  const commit = () => {
+    const trimmed = draft.trim();
+    if (trimmed && trimmed !== model) onEdit(trimmed);
+    else setDraft(model);
+    setEditing(false);
+  };
+  const handleKeyDown = (e) => {
+    if (e.key === "Enter") commit();
+    if (e.key === "Escape") { setDraft(model); setEditing(false); }
+  };
+  return (
+    <div className="group flex min-w-0 items-center gap-1.5 rounded-md bg-black/[0.02] px-2 py-1 transition-colors hover:bg-black/[0.04] dark:bg-white/[0.02] dark:hover:bg-white/[0.04]">
+      <span className="text-[10px] font-medium text-text-muted w-3 text-center shrink-0">{index + 1}</span>
+      {editing ? (
+        <input autoFocus value={draft} onChange={(e) => setDraft(e.target.value)} onBlur={commit} onKeyDown={handleKeyDown}
+          className="min-w-0 flex-1 rounded border border-primary/40 bg-white px-1.5 py-0.5 font-mono text-xs text-text-main outline-none dark:bg-black/20" />
+      ) : (
+        <div className="min-w-0 flex-1 cursor-text truncate rounded px-1.5 py-0.5 font-mono text-xs text-text-main hover:bg-black/5 dark:hover:bg-white/5"
+          onClick={() => setEditing(true)} title="Click to edit">{model}</div>
+      )}
+      <div className="flex shrink-0 items-center gap-0.5">
+        <button onClick={onMoveUp} disabled={isFirst}
+          className={`p-0.5 rounded ${isFirst ? "text-text-muted/20 cursor-not-allowed" : "text-text-muted hover:text-primary hover:bg-black/5 dark:hover:bg-white/5"}`} title="Move up">
+          <span className="material-symbols-outlined text-[12px]">arrow_upward</span>
+        </button>
+        <button onClick={onMoveDown} disabled={isLast}
+          className={`p-0.5 rounded ${isLast ? "text-text-muted/20 cursor-not-allowed" : "text-text-muted hover:text-primary hover:bg-black/5 dark:hover:bg-white/5"}`} title="Move down">
+          <span className="material-symbols-outlined text-[12px]">arrow_downward</span>
+        </button>
+      </div>
+      <button onClick={onRemove} className="p-0.5 hover:bg-red-500/10 rounded text-text-muted hover:text-red-500 transition-all" title="Remove">
+        <span className="material-symbols-outlined text-[12px]">close</span>
+      </button>
+    </div>
+  );
+}
+
+// Reusable Combo create/edit modal. forcePrefix auto-prepends to name.
+export default function ComboFormModal({ isOpen, combo, onClose, onSave, activeProviders, kindFilter = null, forcePrefix = "", title }) {
+  // Strip prefix when editing existing combo so user only edits suffix
+  const initialName = combo?.name
+    ? (forcePrefix && combo.name.startsWith(forcePrefix) ? combo.name.slice(forcePrefix.length) : combo.name)
+    : "";
+  const [name, setName] = useState(initialName);
+  const [models, setModels] = useState(combo?.models || []);
+  const [showModelSelect, setShowModelSelect] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [nameError, setNameError] = useState("");
+  const [modelAliases, setModelAliases] = useState({});
+
+  useEffect(() => {
+    if (!isOpen) return;
+    fetch("/api/models/alias").then((r) => r.ok ? r.json() : null).then((d) => d && setModelAliases(d.aliases || {})).catch(() => {});
+  }, [isOpen]);
+
+  const validateName = (value) => {
+    if (!value.trim()) { setNameError("Name is required"); return false; }
+    const full = forcePrefix + value;
+    if (!VALID_NAME_REGEX.test(full)) { setNameError("Only letters, numbers, -, _ and . allowed"); return false; }
+    setNameError("");
+    return true;
+  };
+
+  const handleNameChange = (e) => {
+    let value = e.target.value;
+    // If user types prefix manually, strip it (we always prepend)
+    if (forcePrefix && value.startsWith(forcePrefix)) value = value.slice(forcePrefix.length);
+    setName(value);
+    if (value) validateName(value); else setNameError("");
+  };
+
+  const handleAddModel = (model) => {
+    if (!models.includes(model.value)) setModels([...models, model.value]);
+  };
+  const handleDeselectModel = (model) => {
+    setModels(models.filter((m) => m !== model.value));
+  };
+  const handleRemoveModel = (i) => setModels(models.filter((_, idx) => idx !== i));
+  const handleMoveUp = (i) => {
+    if (i === 0) return;
+    const a = [...models]; [a[i - 1], a[i]] = [a[i], a[i - 1]]; setModels(a);
+  };
+  const handleMoveDown = (i) => {
+    if (i === models.length - 1) return;
+    const a = [...models]; [a[i], a[i + 1]] = [a[i + 1], a[i]]; setModels(a);
+  };
+
+  const handleSave = async () => {
+    if (!validateName(name)) return;
+    setSaving(true);
+    await onSave({ name: forcePrefix + name.trim(), models });
+    setSaving(false);
+  };
+
+  const isEdit = !!combo;
+
+  return (
+    <>
+      <Modal isOpen={isOpen} onClose={onClose} title={title || (isEdit ? "Edit Combo" : "Create Combo")}>
+        <div className="flex flex-col gap-3">
+          <div>
+            {forcePrefix ? (
+              <>
+                <label className="text-sm font-medium mb-1 block">Combo Name</label>
+                <div className="flex items-stretch">
+                  <span className="inline-flex items-center px-2 rounded-l border border-r-0 border-black/10 dark:border-white/10 bg-black/[0.04] dark:bg-white/[0.04] text-text-muted font-mono text-sm">{forcePrefix}</span>
+                  <input value={name} onChange={handleNameChange} placeholder="my-combo"
+                    className="flex-1 min-w-0 rounded-r border border-black/10 dark:border-white/10 bg-white dark:bg-black/20 px-2 py-1.5 font-mono text-sm outline-none focus:border-primary" />
+                </div>
+                {nameError && <p className="text-[11px] text-red-500 mt-0.5">{nameError}</p>}
+              </>
+            ) : (
+              <Input label="Combo Name" value={name} onChange={handleNameChange} placeholder="my-combo" error={nameError} />
+            )}
+            <p className="text-[10px] text-text-muted mt-0.5">
+              {forcePrefix ? `Auto-prefixed with "${forcePrefix}". ` : ""}Only letters, numbers, -, _ and . allowed
+            </p>
+          </div>
+
+          <div>
+            <label className="text-sm font-medium mb-1.5 block">Models</label>
+            {models.length === 0 ? (
+              <div className="text-center py-4 border border-dashed border-black/10 dark:border-white/10 rounded-lg bg-black/[0.01] dark:bg-white/[0.01]">
+                <span className="material-symbols-outlined text-text-muted text-xl mb-1">layers</span>
+                <p className="text-xs text-text-muted">No models added yet</p>
+              </div>
+            ) : (
+              <div className="flex max-h-[55vh] min-w-0 flex-col gap-1 overflow-y-auto sm:max-h-[350px]">
+                {models.map((model, index) => (
+                  <ModelItem key={index} index={index} model={model}
+                    isFirst={index === 0} isLast={index === models.length - 1}
+                    onEdit={(v) => { const a = [...models]; a[index] = v; setModels(a); }}
+                    onMoveUp={() => handleMoveUp(index)}
+                    onMoveDown={() => handleMoveDown(index)}
+                    onRemove={() => handleRemoveModel(index)} />
+                ))}
+              </div>
+            )}
+            <button onClick={() => setShowModelSelect(true)}
+              className="w-full mt-2 py-2 border border-dashed border-black/10 dark:border-white/10 rounded-lg text-xs text-primary font-medium hover:text-primary hover:border-primary/50 transition-colors flex items-center justify-center gap-1">
+              <span className="material-symbols-outlined text-[16px]">add</span>
+              Add Model
+            </button>
+          </div>
+
+          <div className="flex flex-col gap-2 pt-1 sm:flex-row">
+            <Button onClick={onClose} variant="ghost" fullWidth size="sm">Cancel</Button>
+            <Button onClick={handleSave} fullWidth size="sm" disabled={!name.trim() || !!nameError || saving}>
+              {saving ? "Saving..." : isEdit ? "Save" : "Create"}
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      <ModelSelectModal isOpen={showModelSelect} onClose={() => setShowModelSelect(false)}
+        onSelect={handleAddModel} onDeselect={handleDeselectModel}
+        activeProviders={activeProviders} modelAliases={modelAliases}
+        title="Add Model to Combo" kindFilter={kindFilter}
+        addedModelValues={models} closeOnSelect={false} />
+    </>
+  );
+}
diff --git a/src/shared/components/CursorAuthModal.js b/src/shared/components/CursorAuthModal.js
new file mode 100644
index 0000000..704db9b
--- /dev/null
+++ b/src/shared/components/CursorAuthModal.js
@@ -0,0 +1,212 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import PropTypes from "prop-types";
+import { Modal, Button, Input } from "@/shared/components";
+
+/**
+ * Cursor Auth Modal
+ * Auto-detect and import token from Cursor IDE's local SQLite database
+ */
+export default function CursorAuthModal({ isOpen, onSuccess, onClose }) {
+  const [accessToken, setAccessToken] = useState("");
+  const [machineId, setMachineId] = useState("");
+  const [error, setError] = useState(null);
+  const [importing, setImporting] = useState(false);
+  const [autoDetecting, setAutoDetecting] = useState(false);
+  const [autoDetected, setAutoDetected] = useState(false);
+  const [windowsManual, setWindowsManual] = useState(false);
+
+  const runAutoDetect = async () => {
+    setAutoDetecting(true);
+    setError(null);
+    setAutoDetected(false);
+    setWindowsManual(false);
+
+    try {
+      const res = await fetch("/api/oauth/cursor/auto-import");
+      const data = await res.json();
+
+      if (data.found) {
+        setAccessToken(data.accessToken);
+        setMachineId(data.machineId);
+        setAutoDetected(true);
+      } else if (data.windowsManual) {
+        setWindowsManual(true);
+      } else {
+        setError(data.error || "Could not auto-detect tokens");
+      }
+    } catch (err) {
+      setError("Failed to auto-detect tokens");
+    } finally {
+      setAutoDetecting(false);
+    }
+  };
+
+  // Auto-detect tokens when modal opens
+  useEffect(() => {
+    if (!isOpen) return;
+    runAutoDetect();
+  }, [isOpen]);
+
+  const handleImportToken = async () => {
+    if (!accessToken.trim()) {
+      setError("Please enter an access token");
+      return;
+    }
+
+    if (!machineId.trim()) {
+      setError("Please enter a machine ID");
+      return;
+    }
+
+    setImporting(true);
+    setError(null);
+
+    try {
+      const res = await fetch("/api/oauth/cursor/import", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          accessToken: accessToken.trim(),
+          machineId: machineId.trim(),
+        }),
+      });
+
+      const data = await res.json();
+
+      if (!res.ok) {
+        throw new Error(data.error || "Import failed");
+      }
+
+      onSuccess?.();
+      onClose();
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setImporting(false);
+    }
+  };
+
+  return (
+    <Modal isOpen={isOpen} title="Connect Cursor IDE" onClose={onClose}>
+      <div className="flex flex-col gap-4">
+        {/* Auto-detecting state */}
+        {autoDetecting && (
+          <div className="text-center py-6">
+            <div className="size-16 mx-auto mb-4 rounded-full bg-primary/10 flex items-center justify-center">
+              <span className="material-symbols-outlined text-3xl text-primary animate-spin">
+                progress_activity
+              </span>
+            </div>
+            <h3 className="text-lg font-semibold mb-2">Auto-detecting tokens...</h3>
+            <p className="text-sm text-text-muted">
+              Reading from Cursor IDE database
+            </p>
+          </div>
+        )}
+
+        {/* Form (shown after auto-detect completes) */}
+        {!autoDetecting && (
+          <>
+            {/* Success message if auto-detected */}
+            {autoDetected && (
+              <div className="bg-green-50 dark:bg-green-900/20 p-3 rounded-lg border border-green-200 dark:border-green-800">
+                <div className="flex gap-2">
+                  <span className="material-symbols-outlined text-green-600 dark:text-green-400">check_circle</span>
+                  <p className="text-sm text-green-800 dark:text-green-200">
+                    Tokens auto-detected from Cursor IDE successfully!
+                  </p>
+                </div>
+              </div>
+            )}
+
+            {/* Windows manual instructions */}
+            {windowsManual && (
+              <div className="bg-amber-50 dark:bg-amber-900/20 p-3 rounded-lg border border-amber-200 dark:border-amber-800 flex flex-col gap-2">
+                <div className="flex gap-2 items-center">
+                  <span className="material-symbols-outlined text-amber-600 dark:text-amber-400">info</span>
+                  <p className="text-sm font-medium text-amber-800 dark:text-amber-200">
+                    Could not read Cursor database automatically.
+                  </p>
+                </div>
+                <p className="text-xs text-amber-700 dark:text-amber-300">
+                  Make sure Cursor IDE has been opened at least once, then click <strong>Retry</strong>. If the problem persists, paste your tokens manually below.
+                </p>
+                <Button onClick={runAutoDetect} variant="outline" fullWidth>
+                  Retry
+                </Button>
+              </div>
+            )}
+
+            {/* Info message if not auto-detected */}
+            {!autoDetected && !windowsManual && !error && (
+              <div className="bg-blue-50 dark:bg-blue-900/20 p-3 rounded-lg border border-blue-200 dark:border-blue-800">
+                <div className="flex gap-2">
+                  <span className="material-symbols-outlined text-blue-600 dark:text-blue-400">info</span>
+                  <p className="text-sm text-blue-800 dark:text-blue-200">
+                    Cursor IDE not detected. Please paste your tokens manually.
+                  </p>
+                </div>
+              </div>
+            )}
+
+            {/* Access Token Input */}
+            <div>
+              <label className="block text-sm font-medium mb-2">
+                Access Token <span className="text-red-500">*</span>
+              </label>
+              <textarea
+                value={accessToken}
+                onChange={(e) => setAccessToken(e.target.value)}
+                placeholder="Access token will be auto-filled..."
+                rows={3}
+                className="w-full px-3 py-2 text-sm font-mono border border-border rounded-lg bg-background focus:outline-none focus:border-primary resize-none"
+              />
+            </div>
+
+            {/* Machine ID Input */}
+            <div>
+              <label className="block text-sm font-medium mb-2">
+                Machine ID <span className="text-red-500">*</span>
+              </label>
+              <Input
+                value={machineId}
+                onChange={(e) => setMachineId(e.target.value)}
+                placeholder="Machine ID will be auto-filled..."
+                className="font-mono text-sm"
+              />
+            </div>
+
+            {/* Error Display */}
+            {error && (
+              <div className="bg-red-50 dark:bg-red-900/20 p-3 rounded-lg border border-red-200 dark:border-red-800">
+                <p className="text-sm text-red-600 dark:text-red-400">{error}</p>
+              </div>
+            )}
+
+            {/* Action Buttons */}
+            <div className="flex gap-2">
+              <Button
+                onClick={handleImportToken}
+                fullWidth
+                disabled={importing || !accessToken.trim() || !machineId.trim()}
+              >
+                {importing ? "Importing..." : "Import Token"}
+              </Button>
+              <Button onClick={onClose} variant="ghost" fullWidth>
+                Cancel
+              </Button>
+            </div>
+          </>
+        )}
+      </div>
+    </Modal>
+  );
+}
+
+CursorAuthModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  onSuccess: PropTypes.func,
+  onClose: PropTypes.func.isRequired,
+};
diff --git a/src/shared/components/DonateModal.js b/src/shared/components/DonateModal.js
new file mode 100644
index 0000000..bf1e9af
--- /dev/null
+++ b/src/shared/components/DonateModal.js
@@ -0,0 +1,136 @@
+"use client";
+
+import { useEffect, useState, useRef } from "react";
+import { createPortal } from "react-dom";
+import PropTypes from "prop-types";
+import { GITHUB_CONFIG } from "@/shared/constants/config";
+
+export default function DonateModal({ isOpen, onClose }) {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+  const modalRef = useRef(null);
+
+  useEffect(() => {
+    if (!isOpen || data) return;
+    setLoading(true);
+    setError("");
+    fetch(GITHUB_CONFIG.donateUrl, { cache: "no-store" })
+      .then((res) => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      })
+      .then((json) => setData(json))
+      .catch((err) => setError(err.message || "Failed to load"))
+      .finally(() => setLoading(false));
+  }, [isOpen, data]);
+
+  useEffect(() => {
+    const handleClickOutside = (e) => {
+      if (modalRef.current && !modalRef.current.contains(e.target)) onClose();
+    };
+    if (isOpen) {
+      document.addEventListener("mousedown", handleClickOutside);
+      return () => document.removeEventListener("mousedown", handleClickOutside);
+    }
+  }, [isOpen, onClose]);
+
+  if (!isOpen || typeof document === "undefined") return null;
+
+  return createPortal(
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+      <div className="absolute inset-0 bg-black/30 backdrop-blur-sm" onClick={onClose} />
+      <div
+        ref={modalRef}
+        className="relative w-full bg-surface border border-black/10 dark:border-white/10 rounded-xl shadow-2xl animate-in fade-in zoom-in-95 duration-200 max-w-3xl flex flex-col max-h-[85vh]"
+      >
+        <div className="flex items-center justify-between p-3 border-b border-black/5 dark:border-white/5">
+          <h2 className="text-lg font-semibold text-text-main flex items-center gap-2">
+            <span className="material-symbols-outlined text-pink-500">volunteer_activism</span>
+            {data?.title || "Support 9Router"}
+          </h2>
+          <button
+            onClick={onClose}
+            className="p-1.5 rounded-lg text-text-muted hover:bg-black/5 dark:hover:bg-white/5 transition-colors"
+            aria-label="Close"
+          >
+            <span className="material-symbols-outlined text-[20px]">close</span>
+          </button>
+        </div>
+
+        <div className="p-6 overflow-y-auto flex-1">
+          {loading && (
+            <div className="flex items-center justify-center py-10 text-text-muted">
+              <span className="material-symbols-outlined animate-spin mr-2">progress_activity</span>
+              Loading...
+            </div>
+          )}
+          {error && (
+            <div className="text-red-500 py-4">Failed to load donate info: {error}</div>
+          )}
+          {!loading && !error && data && (
+            <>
+              {data.message && (
+                <p className="text-text-muted text-sm mb-6 text-center">{data.message}</p>
+              )}
+              <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
+                {data.channels?.map((ch) => (
+                  <DonateChannelCard key={ch.id} channel={ch} />
+                ))}
+              </div>
+            </>
+          )}
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+}
+
+function DonateChannelCard({ channel }) {
+  const { label, description, icon, color, url, qr } = channel;
+  const content = (
+    <>
+      <div
+        className="w-12 h-12 rounded-full flex items-center justify-center mb-3"
+        style={{ backgroundColor: `${color}20`, color }}
+      >
+        <span className="material-symbols-outlined text-[26px]">{icon}</span>
+      </div>
+      <div className="font-semibold text-text-main mb-1">{label}</div>
+      {description && (
+        <div className="text-xs text-text-muted mb-3 text-center">{description}</div>
+      )}
+      {qr && (
+        <img
+          src={qr}
+          alt={`${label} QR`}
+          className="w-full max-w-[180px] aspect-square object-contain rounded-lg bg-white p-1"
+        />
+      )}
+    </>
+  );
+
+  return (
+    <div className="flex flex-col items-center p-4 rounded-xl border border-black/10 dark:border-white/10 bg-surface/50 hover:border-pink-500/40 transition-colors">
+      {content}
+      {url && (
+        <a
+          href={url}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="mt-3 inline-flex items-center gap-1 px-3 py-1.5 rounded-lg text-sm font-medium text-white hover:opacity-90 transition-opacity"
+          style={{ backgroundColor: color }}
+        >
+          Open
+          <span className="material-symbols-outlined text-[16px]">open_in_new</span>
+        </a>
+      )}
+    </div>
+  );
+}
+
+DonateModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  onClose: PropTypes.func.isRequired,
+};
diff --git a/src/shared/components/Drawer.js b/src/shared/components/Drawer.js
new file mode 100644
index 0000000..e175e8e
--- /dev/null
+++ b/src/shared/components/Drawer.js
@@ -0,0 +1,82 @@
+"use client";
+
+import { useEffect } from "react";
+import { cn } from "@/shared/utils/cn";
+
+export default function Drawer({
+  isOpen,
+  onClose,
+  title,
+  children,
+  width = "md",
+  className
+}) {
+  const widths = {
+    sm: "w-[400px]",
+    md: "w-[500px]",
+    lg: "w-[600px]",
+    xl: "w-[800px]",
+    full: "w-full",
+  };
+
+  useEffect(() => {
+    if (isOpen) {
+      document.body.style.overflow = "hidden";
+    } else {
+      document.body.style.overflow = "";
+    }
+    return () => { document.body.style.overflow = ""; };
+  }, [isOpen]);
+
+  useEffect(() => {
+    const handleEscape = (e) => {
+      if (e.key === "Escape" && isOpen) onClose();
+    };
+    document.addEventListener("keydown", handleEscape);
+    return () => document.removeEventListener("keydown", handleEscape);
+  }, [isOpen, onClose]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50">
+      {/* Overlay */}
+      <div
+        className="absolute inset-0 bg-black/50 backdrop-blur-[2px] fade-in cursor-pointer"
+        onClick={onClose}
+        aria-hidden="true"
+      />
+
+      {/* Drawer panel */}
+      <div className={cn(
+        "absolute right-0 top-0 h-full bg-surface flex flex-col",
+        "shadow-[var(--shadow-elev)]",
+        "slide-in-right",
+        "border-l border-border-subtle",
+        widths[width] || widths.md,
+        className
+      )}>
+        {/* Header */}
+        <div className="flex items-center justify-between p-6 border-b border-border-subtle flex-shrink-0">
+          <div className="flex items-center gap-3">
+            {title && (
+              <h2 className="text-lg font-semibold text-text-main">{title}</h2>
+            )}
+          </div>
+          <button
+            type="button"
+            onClick={onClose}
+            className="p-1.5 rounded-[10px] text-text-muted hover:bg-surface-2 hover:text-text-main transition-colors"
+          >
+            <span className="material-symbols-outlined text-[20px]">close</span>
+          </button>
+        </div>
+
+        {/* Body */}
+        <div className="flex-1 overflow-y-auto p-6 custom-scrollbar">
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/shared/components/EditConnectionModal.js b/src/shared/components/EditConnectionModal.js
new file mode 100644
index 0000000..1cf13f1
--- /dev/null
+++ b/src/shared/components/EditConnectionModal.js
@@ -0,0 +1,316 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import PropTypes from "prop-types";
+import Modal from "@/shared/components/Modal";
+import Input from "@/shared/components/Input";
+import Button from "@/shared/components/Button";
+import Badge from "@/shared/components/Badge";
+import { isOpenAICompatibleProvider, isAnthropicCompatibleProvider, AI_PROVIDERS } from "@/shared/constants/providers";
+import Select from "@/shared/components/Select";
+
+export default function EditConnectionModal({ isOpen, connection, proxyPools, onSave, onClose }) {
+  const [formData, setFormData] = useState({
+    name: "",
+    priority: 1,
+    apiKey: "",
+  });
+  const [azureData, setAzureData] = useState({
+    azureEndpoint: "",
+    apiVersion: "2024-10-01-preview",
+    deployment: "",
+    organization: "",
+  });
+  const [cloudflareData, setCloudflareData] = useState({ accountId: "" });
+  const [region, setRegion] = useState("");
+  const [testing, setTesting] = useState(false);
+  const [testResult, setTestResult] = useState(null);
+  const [validating, setValidating] = useState(false);
+  const [validationResult, setValidationResult] = useState(null);
+  const [saving, setSaving] = useState(false);
+
+  useEffect(() => {
+    if (connection) {
+      setFormData({
+        name: connection.name || "",
+        priority: connection.priority || 1,
+        apiKey: "",
+      });
+      // Load Azure-specific data if present
+      if (connection.provider === "azure" && connection.providerSpecificData) {
+        setAzureData({
+          azureEndpoint: connection.providerSpecificData.azureEndpoint || "",
+          apiVersion: connection.providerSpecificData.apiVersion || "2024-10-01-preview",
+          deployment: connection.providerSpecificData.deployment || "",
+          organization: connection.providerSpecificData.organization || "",
+        });
+      }
+      if (connection.provider === "cloudflare-ai" && connection.providerSpecificData) {
+        setCloudflareData({ accountId: connection.providerSpecificData.accountId || "" });
+      }
+      // Load region for providers that support it (e.g. xiaomi-tokenplan)
+      const providerCfg = AI_PROVIDERS?.[connection.provider];
+      if (providerCfg?.regions) {
+        const savedRegion = connection.providerSpecificData?.region || providerCfg.defaultRegion || providerCfg.regions[0]?.id || "";
+        setRegion(savedRegion);
+      }
+      setTestResult(null);
+      setValidationResult(null);
+    }
+  }, [connection]);
+
+  const isOAuth = connection?.authType === "oauth";
+  const isAzure = connection?.provider === "azure";
+  const isCloudflareAi = connection?.provider === "cloudflare-ai";
+  const isCompatible = connection
+    ? (isOpenAICompatibleProvider(connection.provider) || isAnthropicCompatibleProvider(connection.provider))
+    : false;
+  const providerRegions = connection ? (AI_PROVIDERS?.[connection.provider]?.regions || null) : null;
+
+  // Build providerSpecificData for region-aware providers
+  const buildRegionSpecificData = () => {
+    if (providerRegions && region) return { ...((connection?.providerSpecificData) || {}), region };
+    return undefined;
+  };
+
+  const handleTest = async () => {
+    if (!connection?.provider) return;
+    setTesting(true);
+    setTestResult(null);
+    try {
+      const res = await fetch(`/api/providers/${connection.id}/test`, { method: "POST" });
+      const data = await res.json();
+      setTestResult(data.valid ? "success" : "failed");
+    } catch {
+      setTestResult("failed");
+    } finally {
+      setTesting(false);
+    }
+  };
+
+  const handleValidate = async () => {
+    if (!connection?.provider || !formData.apiKey) return;
+    setValidating(true);
+    setValidationResult(null);
+    try {
+      const res = await fetch("/api/providers/validate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          provider: connection.provider,
+          apiKey: formData.apiKey,
+          ...(isAzure ? { providerSpecificData: azureData } : {}),
+          ...(isCloudflareAi ? { providerSpecificData: cloudflareData } : {}),
+          ...(providerRegions ? { providerSpecificData: buildRegionSpecificData() } : {}),
+        }),
+      });
+      const data = await res.json();
+      setValidationResult(data.valid ? "success" : "failed");
+    } catch {
+      setValidationResult("failed");
+    } finally {
+      setValidating(false);
+    }
+  };
+
+  const handleSubmit = async () => {
+    if (!connection) return;
+    setSaving(true);
+    try {
+      const updates = {
+        name: formData.name,
+        priority: formData.priority,
+      };
+      if (!isOAuth && formData.apiKey) {
+        updates.apiKey = formData.apiKey;
+        let isValid = validationResult === "success";
+        if (!isValid) {
+          try {
+            setValidating(true);
+            setValidationResult(null);
+            const res = await fetch("/api/providers/validate", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({
+                provider: connection.provider,
+                apiKey: formData.apiKey,
+                ...(isAzure ? { providerSpecificData: azureData } : {}),
+                ...(isCloudflareAi ? { providerSpecificData: cloudflareData } : {}),
+                ...(providerRegions ? { providerSpecificData: buildRegionSpecificData() } : {}),
+              }),
+            });
+            const data = await res.json();
+            isValid = !!data.valid;
+            setValidationResult(isValid ? "success" : "failed");
+          } catch {
+            setValidationResult("failed");
+          } finally {
+            setValidating(false);
+          }
+        }
+        if (isValid) {
+          updates.testStatus = "active";
+          updates.lastError = null;
+          updates.lastErrorAt = null;
+        }
+      }
+      
+      // Add Azure-specific data if this is an Azure connection
+      if (isAzure) {
+        updates.providerSpecificData = {
+          azureEndpoint: azureData.azureEndpoint,
+          apiVersion: azureData.apiVersion,
+          deployment: azureData.deployment,
+          organization: azureData.organization,
+        };
+      }
+      if (isCloudflareAi) {
+        updates.providerSpecificData = { accountId: cloudflareData.accountId };
+      }
+      // Persist updated region for region-aware providers
+      if (providerRegions && region) {
+        updates.providerSpecificData = buildRegionSpecificData();
+      }
+      
+      await onSave(updates);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  if (!connection) return null;
+
+  return (
+    <Modal isOpen={isOpen} title="Edit Connection" onClose={onClose}>
+      <div className="flex flex-col gap-4">
+        <Input
+          label="Name"
+          value={formData.name}
+          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+          placeholder={isOAuth ? "Account name" : "Production Key"}
+        />
+        {isOAuth && connection.email && (
+          <div className="bg-sidebar/50 p-3 rounded-lg">
+            <p className="text-sm text-text-muted mb-1">Email</p>
+            <p className="font-medium">{connection.email}</p>
+          </div>
+        )}
+        <Input
+          label="Priority"
+          type="number"
+          value={formData.priority}
+          onChange={(e) => setFormData({ ...formData, priority: Number.parseInt(e.target.value, 10) || 1 })}
+        />
+
+        {!isOAuth && (
+          <>
+            <div className="flex gap-2">
+              <Input
+                label="API Key"
+                type="password"
+                value={formData.apiKey}
+                onChange={(e) => setFormData({ ...formData, apiKey: e.target.value })}
+                placeholder="Enter new API key"
+                hint="Leave blank to keep the current API key."
+                className="flex-1"
+              />
+              <div className="pt-6">
+                <Button onClick={handleValidate} disabled={!formData.apiKey || validating || saving} variant="secondary">
+                  {validating ? "Checking..." : "Check"}
+                </Button>
+              </div>
+            </div>
+            {validationResult && (
+              <Badge variant={validationResult === "success" ? "success" : "error"}>
+                {validationResult === "success" ? "Valid" : "Invalid"}
+              </Badge>
+            )}
+          </>
+        )}
+
+        {isAzure && (
+          <div className="bg-sidebar/50 p-4 rounded-lg border border-accent/20">
+            <h3 className="font-semibold mb-3 text-sm">Azure OpenAI Configuration</h3>
+            <div className="flex flex-col gap-3">
+              <Input
+                label="Azure Endpoint"
+                value={azureData.azureEndpoint}
+                onChange={(e) => setAzureData({ ...azureData, azureEndpoint: e.target.value })}
+                placeholder="https://your-resource.openai.azure.com"
+                hint="Your Azure OpenAI resource endpoint URL"
+              />
+              <Input
+                label="Deployment Name"
+                value={azureData.deployment}
+                onChange={(e) => setAzureData({ ...azureData, deployment: e.target.value })}
+                placeholder="gpt-4"
+                hint="The deployment name in your Azure resource"
+              />
+              <Input
+                label="API Version"
+                value={azureData.apiVersion}
+                onChange={(e) => setAzureData({ ...azureData, apiVersion: e.target.value })}
+                placeholder="2024-10-01-preview"
+                hint="Azure OpenAI API version to use"
+              />
+              <Input
+                label="Organization"
+                value={azureData.organization}
+                onChange={(e) => setAzureData({ ...azureData, organization: e.target.value })}
+                placeholder="Organization ID"
+                hint="Required for billing"
+              />
+            </div>
+          </div>
+        )}
+
+        {providerRegions && (
+          <Select
+            label="Region"
+            value={region}
+            onChange={(e) => setRegion(e.target.value)}
+            options={providerRegions.map((r) => ({ value: r.id, label: r.label }))}
+          />
+        )}
+
+        {!isCompatible && !isAzure && !isCloudflareAi && (
+          <div className="flex items-center gap-3">
+            <Button onClick={handleTest} variant="secondary" disabled={testing}>
+              {testing ? "Testing..." : "Test Connection"}
+            </Button>
+            {testResult && (
+              <Badge variant={testResult === "success" ? "success" : "error"}>
+                {testResult === "success" ? "Valid" : "Failed"}
+              </Badge>
+            )}
+          </div>
+        )}
+
+        <div className="flex gap-2">
+          <Button onClick={handleSubmit} fullWidth disabled={saving}>{saving ? "Saving..." : "Save"}</Button>
+          <Button onClick={onClose} variant="ghost" fullWidth>Cancel</Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+EditConnectionModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  connection: PropTypes.shape({
+    id: PropTypes.string,
+    name: PropTypes.string,
+    email: PropTypes.string,
+    priority: PropTypes.number,
+    authType: PropTypes.string,
+    provider: PropTypes.string,
+    providerSpecificData: PropTypes.object,
+  }),
+  proxyPools: PropTypes.arrayOf(PropTypes.shape({
+    id: PropTypes.string,
+    name: PropTypes.string,
+  })),
+  onSave: PropTypes.func.isRequired,
+  onClose: PropTypes.func.isRequired,
+};
+
diff --git a/src/shared/components/Footer.js b/src/shared/components/Footer.js
new file mode 100644
index 0000000..641ebdb
--- /dev/null
+++ b/src/shared/components/Footer.js
@@ -0,0 +1,132 @@
+"use client";
+
+import Link from "next/link";
+import { APP_CONFIG } from "@/shared/constants/config";
+
+const footerLinks = {
+  product: [
+    { label: "Features", href: "#features" },
+    { label: "Pricing", href: "#pricing" },
+    { label: "Changelog", href: "#" },
+  ],
+  resources: [
+    { label: "Documentation", href: "#" },
+    { label: "API Reference", href: "#" },
+    { label: "Help Center", href: "#" },
+  ],
+  company: [
+    { label: "About", href: "#" },
+    { label: "Blog", href: "#" },
+    { label: "Contact", href: "#" },
+  ],
+};
+
+export default function Footer() {
+  return (
+    <footer className="bg-bg border-t border-border pt-16 pb-12">
+      <div className="container mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="grid grid-cols-2 md:grid-cols-4 lg:grid-cols-5 gap-10 mb-12">
+          {/* Brand */}
+          <div className="col-span-2 lg:col-span-2">
+            <div className="flex items-center gap-2 mb-6">
+              <div className="size-6 text-primary">
+                <svg className="w-full h-full" fill="currentColor" viewBox="0 0 48 48">
+                  <path
+                    clipRule="evenodd"
+                    d="M12.0799 24L4 19.2479L9.95537 8.75216L18.04 13.4961L18.0446 4H29.9554L29.96 13.4961L38.0446 8.75216L44 19.2479L35.92 24L44 28.7521L38.0446 39.2479L29.96 34.5039L29.9554 44H18.0446L18.04 34.5039L9.95537 39.2479L4 28.7521L12.0799 24Z"
+                    fillRule="evenodd"
+                  />
+                </svg>
+              </div>
+              <span className="text-xl font-bold text-text-main">
+                {APP_CONFIG.name}
+              </span>
+            </div>
+            <p className="text-text-muted mb-6 max-w-sm font-light">
+              The unified interface for modern AI infrastructure. Secure, observable, and scalable.
+            </p>
+            {/* Social links */}
+            <div className="flex gap-4">
+              <a
+                href="#"
+                className="text-gray-400 hover:text-primary transition-colors"
+                aria-label="Twitter"
+              >
+                <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+                  <path d="M22.46 6c-.77.35-1.6.58-2.46.69.88-.53 1.56-1.37 1.88-2.38-.83.5-1.75.85-2.72 1.05C18.37 4.5 17.26 4 16 4c-2.35 0-4.27 1.92-4.27 4.29 0 .34.04.67.11.98C8.28 9.09 5.11 7.38 3 4.79c-.37.63-.58 1.37-.58 2.15 0 1.49.75 2.81 1.91 3.56-.71 0-1.37-.2-1.95-.5v.03c0 2.08 1.48 3.82 3.44 4.21a4.22 4.22 0 0 1-1.93.07 4.28 4.28 0 0 0 4 2.98 8.521 8.521 0 0 1-5.33 1.84c-.34 0-.68-.02-1.02-.06C3.44 20.29 5.7 21 8.12 21 16 21 20.33 14.46 20.33 8.79c0-.19 0-.37-.01-.56.84-.6 1.56-1.36 2.14-2.23z" />
+                </svg>
+              </a>
+              <a
+                href="#"
+                className="text-gray-400 hover:text-primary transition-colors"
+                aria-label="GitHub"
+              >
+                <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+                  <path d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0 1 12 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0 0 22 12.017C22 6.484 17.522 2 12 2z" />
+                </svg>
+              </a>
+            </div>
+          </div>
+
+          {/* Product */}
+          <div>
+            <h4 className="font-semibold text-text-main mb-4">Product</h4>
+            <ul className="flex flex-col gap-3 text-sm text-text-muted font-light">
+              {footerLinks.product.map((link) => (
+                <li key={link.label}>
+                  <Link href={link.href} className="hover:text-primary transition-colors">
+                    {link.label}
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </div>
+
+          {/* Resources */}
+          <div>
+            <h4 className="font-semibold text-text-main mb-4">Resources</h4>
+            <ul className="flex flex-col gap-3 text-sm text-text-muted font-light">
+              {footerLinks.resources.map((link) => (
+                <li key={link.label}>
+                  <Link href={link.href} className="hover:text-primary transition-colors">
+                    {link.label}
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </div>
+
+          {/* Company */}
+          <div>
+            <h4 className="font-semibold text-text-main mb-4">Company</h4>
+            <ul className="flex flex-col gap-3 text-sm text-text-muted font-light">
+              {footerLinks.company.map((link) => (
+                <li key={link.label}>
+                  <Link href={link.href} className="hover:text-primary transition-colors">
+                    {link.label}
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </div>
+        </div>
+
+        {/* Bottom */}
+        <div className="border-t border-border pt-8 flex flex-col md:flex-row justify-between items-center gap-4">
+          <p className="text-sm text-text-muted">
+            © {new Date().getFullYear()} {APP_CONFIG.name} Inc. All rights reserved.
+          </p>
+          <div className="flex gap-6 text-sm text-text-muted">
+            <Link href="#" className="hover:text-primary transition-colors">
+              Privacy Policy
+            </Link>
+            <Link href="#" className="hover:text-primary transition-colors">
+              Terms of Service
+            </Link>
+          </div>
+        </div>
+      </div>
+    </footer>
+  );
+}
+
diff --git a/src/shared/components/GitLabAuthModal.js b/src/shared/components/GitLabAuthModal.js
new file mode 100644
index 0000000..fa05a0c
--- /dev/null
+++ b/src/shared/components/GitLabAuthModal.js
@@ -0,0 +1,194 @@
+"use client";
+
+import { useState } from "react";
+import PropTypes from "prop-types";
+import { Modal, Button, Input, OAuthModal } from "@/shared/components";
+
+const GITLAB_COM = "https://gitlab.com";
+
+function getRedirectUri() {
+  if (typeof window === "undefined") return "http://localhost/callback";
+  const port = window.location.port || (window.location.protocol === "https:" ? "443" : "80");
+  return `http://localhost:${port}/callback`;
+}
+
+/**
+ * GitLab Duo Authentication Modal
+ * Supports two modes:
+ * - OAuth (PKCE): requires OAuth App Client ID (and optional Client Secret)
+ * - PAT: requires Personal Access Token
+ */
+export default function GitLabAuthModal({ isOpen, providerInfo, onSuccess, onClose }) {
+  const [mode, setMode] = useState(null); // null | "oauth" | "pat"
+  const [baseUrl, setBaseUrl] = useState(GITLAB_COM);
+  const [clientId, setClientId] = useState("");
+  const [clientSecret, setClientSecret] = useState("");
+  const [pat, setPat] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const [showOAuth, setShowOAuth] = useState(false);
+  const [oauthMeta, setOauthMeta] = useState(null);
+
+  const reset = () => {
+    setMode(null);
+    setBaseUrl(GITLAB_COM);
+    setClientId("");
+    setClientSecret("");
+    setPat("");
+    setError(null);
+    setLoading(false);
+    setShowOAuth(false);
+    setOauthMeta(null);
+  };
+
+  const handleClose = () => {
+    reset();
+    onClose();
+  };
+
+  const handleOAuthStart = () => {
+    if (!clientId.trim()) {
+      setError("Client ID is required");
+      return;
+    }
+    setError(null);
+    setOauthMeta({ baseUrl: baseUrl.trim() || GITLAB_COM, clientId: clientId.trim(), clientSecret: clientSecret.trim() });
+    setShowOAuth(true);
+  };
+
+  const handlePATSubmit = async () => {
+    if (!pat.trim()) {
+      setError("Personal Access Token is required");
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await fetch("/api/oauth/gitlab/pat", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ token: pat.trim(), baseUrl: baseUrl.trim() || GITLAB_COM }),
+      });
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error || "Authentication failed");
+      onSuccess?.();
+      handleClose();
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (!isOpen) return null;
+
+  // Sub-modal for OAuth PKCE flow
+  if (showOAuth && oauthMeta) {
+    return (
+      <OAuthModal
+        isOpen
+        provider="gitlab"
+        providerInfo={providerInfo}
+        oauthMeta={oauthMeta}
+        onSuccess={() => { onSuccess?.(); handleClose(); }}
+        onClose={() => { setShowOAuth(false); setOauthMeta(null); }}
+      />
+    );
+  }
+
+  return (
+    <Modal isOpen={isOpen} title="Connect GitLab Duo" onClose={handleClose} size="lg">
+      <div className="flex flex-col gap-4">
+        {/* Mode selection */}
+        {!mode && (
+          <>
+            <p className="text-sm text-text-muted">
+              Choose how to authenticate with GitLab Duo:
+            </p>
+            <div className="grid grid-cols-2 gap-3">
+              <button
+                onClick={() => setMode("oauth")}
+                className="flex flex-col items-center gap-2 p-4 rounded-lg border border-border hover:border-primary hover:bg-primary/5 transition-colors text-left"
+              >
+                <span className="material-symbols-outlined text-2xl text-primary">lock_open</span>
+                <div>
+                  <p className="text-sm font-medium">OAuth App</p>
+                  <p className="text-xs text-text-muted">Use a GitLab OAuth application</p>
+                </div>
+              </button>
+              <button
+                onClick={() => setMode("pat")}
+                className="flex flex-col items-center gap-2 p-4 rounded-lg border border-border hover:border-primary hover:bg-primary/5 transition-colors text-left"
+              >
+                <span className="material-symbols-outlined text-2xl text-primary">key</span>
+                <div>
+                  <p className="text-sm font-medium">Personal Access Token</p>
+                  <p className="text-xs text-text-muted">Use a GitLab PAT with api scope</p>
+                </div>
+              </button>
+            </div>
+          </>
+        )}
+
+        {/* OAuth mode */}
+        {mode === "oauth" && (
+          <>
+            <p className="text-xs text-text-muted">
+              Create an OAuth app at{" "}
+              <a href={`${baseUrl.trim() || GITLAB_COM}/-/profile/applications`} target="_blank" rel="noreferrer" className="text-primary underline">
+                GitLab Applications
+              </a>{" "}
+              with redirect URI{" "}
+              <code className="bg-sidebar px-1 rounded text-xs">{getRedirectUri()}</code>
+            </p>
+            <Input label="GitLab Base URL" value={baseUrl} onChange={(e) => setBaseUrl(e.target.value)} placeholder={GITLAB_COM} />
+            <Input label="Client ID" value={clientId} onChange={(e) => setClientId(e.target.value)} placeholder="Your OAuth application client ID" />
+            <Input label="Client Secret (optional for PKCE)" value={clientSecret} onChange={(e) => setClientSecret(e.target.value)} placeholder="Leave empty for public PKCE app" />
+            {error && <p className="text-sm text-red-500">{error}</p>}
+            <div className="flex gap-2">
+              <Button onClick={handleOAuthStart} fullWidth disabled={!clientId.trim()}>
+                Authorize
+              </Button>
+              <Button onClick={() => { setMode(null); setError(null); }} variant="ghost" fullWidth>
+                Back
+              </Button>
+            </div>
+          </>
+        )}
+
+        {/* PAT mode */}
+        {mode === "pat" && (
+          <>
+            <p className="text-xs text-text-muted">
+              Create a PAT at{" "}
+              <a href={`${baseUrl.trim() || GITLAB_COM}/-/user_settings/personal_access_tokens`} target="_blank" rel="noreferrer" className="text-primary underline">
+                GitLab Access Tokens
+              </a>{" "}
+              with scopes: <code className="bg-sidebar px-1 rounded text-xs">api</code>,{" "}
+              <code className="bg-sidebar px-1 rounded text-xs">read_user</code>, and{" "}
+              <code className="bg-sidebar px-1 rounded text-xs">ai_features</code>.
+            </p>
+            <Input label="GitLab Base URL" value={baseUrl} onChange={(e) => setBaseUrl(e.target.value)} placeholder={GITLAB_COM} />
+            <Input label="Personal Access Token" value={pat} onChange={(e) => setPat(e.target.value)} placeholder="glpat-xxxxxxxxxxxxxxxxxxxx" type="password" />
+            {error && <p className="text-sm text-red-500">{error}</p>}
+            <div className="flex gap-2">
+              <Button onClick={handlePATSubmit} fullWidth disabled={!pat.trim() || loading} loading={loading}>
+                Connect
+              </Button>
+              <Button onClick={() => { setMode(null); setError(null); }} variant="ghost" fullWidth>
+                Back
+              </Button>
+            </div>
+          </>
+        )}
+      </div>
+    </Modal>
+  );
+}
+
+GitLabAuthModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  providerInfo: PropTypes.shape({ name: PropTypes.string }),
+  onSuccess: PropTypes.func,
+  onClose: PropTypes.func.isRequired,
+};
diff --git a/src/shared/components/Header.js b/src/shared/components/Header.js
new file mode 100644
index 0000000..f70a012
--- /dev/null
+++ b/src/shared/components/Header.js
@@ -0,0 +1,369 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { usePathname } from "next/navigation";
+import Link from "next/link";
+import PropTypes from "prop-types";
+import ProviderIcon from "@/shared/components/ProviderIcon";
+import HeaderMenu from "@/shared/components/HeaderMenu";
+import HeaderLanguage from "@/shared/components/HeaderLanguage";
+import ThemeToggle from "@/shared/components/ThemeToggle";
+import DonateModal from "@/shared/components/DonateModal";
+import { useHeaderSearchStore } from "@/store/headerSearchStore";
+import { OAUTH_PROVIDERS, APIKEY_PROVIDERS } from "@/shared/constants/config";
+import { MEDIA_PROVIDER_KINDS, AI_PROVIDERS } from "@/shared/constants/providers";
+import { translate } from "@/i18n/runtime";
+
+const getPageInfo = (pathname) => {
+  if (!pathname) return { title: "", description: "", breadcrumbs: [] };
+
+  // Media provider detail: /dashboard/media-providers/[kind]/[id]
+  const mediaDetailMatch = pathname.match(/\/media-providers\/([^/]+)\/([^/]+)$/);
+  if (mediaDetailMatch) {
+    const kindId = mediaDetailMatch[1];
+    const providerId = mediaDetailMatch[2];
+    const kindConfig = MEDIA_PROVIDER_KINDS.find((k) => k.id === kindId);
+    const provider = AI_PROVIDERS[providerId];
+    return {
+      title: provider?.name || providerId,
+      description: "",
+      breadcrumbs: [
+        { label: "Media Providers", href: `/dashboard/media-providers/${kindId}` },
+        { label: kindConfig?.label || kindId, href: `/dashboard/media-providers/${kindId}` },
+        { label: provider?.name || providerId, image: `/providers/${providerId}.png` },
+      ],
+    };
+  }
+
+  // Media provider kind: /dashboard/media-providers/[kind]
+  const mediaKindMatch = pathname.match(/\/media-providers\/([^/]+)$/);
+  if (mediaKindMatch) {
+    const kindId = mediaKindMatch[1];
+    const kindConfig = MEDIA_PROVIDER_KINDS.find((k) => k.id === kindId);
+    return {
+      title: kindConfig?.label || kindId,
+      description: `Manage your ${kindConfig?.label || kindId} providers`,
+      icon: kindConfig?.icon || "perm_media",
+      breadcrumbs: [],
+    };
+  }
+
+  // Provider detail page: /dashboard/providers/[id]
+  const providerMatch = pathname.match(/\/providers\/([^/]+)$/);
+  if (providerMatch) {
+    const providerId = providerMatch[1];
+    const providerInfo =
+      OAUTH_PROVIDERS[providerId] || APIKEY_PROVIDERS[providerId];
+    if (providerInfo) {
+      return {
+        title: providerInfo.name,
+        description: "",
+        breadcrumbs: [
+          { label: "Providers", href: "/dashboard/providers" },
+          {
+            label: providerInfo.name,
+            image: `/providers/${providerInfo.id}.png`,
+          },
+        ],
+      };
+    }
+  }
+
+  if (pathname.includes("/providers") && !pathname.includes("/media-providers"))
+    return {
+      title: "Providers",
+      description: "Manage your AI provider connections",
+      icon: "dns",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/combos"))
+    return {
+      title: "Combos",
+      description: "Model combos with fallback",
+      icon: "layers",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/usage"))
+    return {
+      title: "Usage & Analytics",
+      description:
+        "Monitor your API usage, token consumption, and request logs",
+      icon: "bar_chart",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/auth-files"))
+    return {
+      title: "Auth Files",
+      description: "Map provider credentials stored in the local database",
+      icon: "vpn_key",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/quota"))
+    return {
+      title: "Quota Tracker",
+      description: "Track and manage your API quota limits",
+      icon: "data_usage",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/mitm"))
+    return {
+      title: "MITM Proxy",
+      description: "Intercept CLI tool traffic and route through 9Router",
+      icon: "security",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/token-saver"))
+    return {
+      title: "Token Saver",
+      description: "Compress prompts and outputs to save tokens",
+      icon: "savings",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/cli-tools"))
+    return {
+      title: "CLI Tools",
+      description: "Configure CLI tools",
+      icon: "terminal",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/proxy-pools"))
+    return {
+      title: "Proxy Pools",
+      description: "Manage your proxy pool configurations",
+      icon: "lan",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/skills"))
+    return {
+      title: "Agent Skills",
+      description: "Copy a link and paste to your AI to use 9Router — no install needed",
+      icon: "extension",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/endpoint"))
+    return {
+      title: "Endpoint",
+      description: "API endpoint configuration",
+      icon: "api",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/profile"))
+    return {
+      title: "Settings",
+      description: "Manage your preferences",
+      icon: "settings",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/translator"))
+    return {
+      title: "Translator",
+      description: "Debug translation flow between formats",
+      icon: "translate",
+      breadcrumbs: [],
+    };
+  if (pathname.includes("/console-log"))
+    return {
+      title: "Console Log",
+      description: "Live server console output",
+      icon: "monitor",
+      breadcrumbs: [],
+    };
+  if (pathname === "/dashboard")
+    return {
+      title: "Endpoint",
+      description: "API endpoint configuration",
+      icon: "api",
+      breadcrumbs: [],
+    };
+  return { title: "", description: "", breadcrumbs: [] };
+};
+
+export default function Header({ onMenuClick, showMenuButton = true }) {
+  const pathname = usePathname();
+  const [displayName, setDisplayName] = useState("");
+  const [loginMethod, setLoginMethod] = useState("");
+  const [donateOpen, setDonateOpen] = useState(false);
+
+  // Memoize page info to prevent unnecessary recalculations
+  const pageInfo = useMemo(() => getPageInfo(pathname), [pathname]);
+  const { title, description, icon, breadcrumbs } = pageInfo;
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function loadAuthStatus() {
+      try {
+        const res = await fetch("/api/auth/status", { cache: "no-store" });
+        if (!res.ok) return;
+        const data = await res.json();
+        if (!cancelled) {
+          setDisplayName(data?.displayName || data?.oidcName || data?.oidcEmail || "");
+          setLoginMethod(data?.loginMethod || "");
+        }
+      } catch {
+        if (!cancelled) {
+          setDisplayName("");
+          setLoginMethod("");
+        }
+      }
+    }
+
+    loadAuthStatus();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const handleLogout = async () => {
+    try {
+      const res = await fetch("/api/auth/logout", { method: "POST" });
+      if (res.ok) {
+        window.location.assign("/login");
+      }
+    } catch (err) {
+      console.error("Failed to logout:", err);
+    }
+  };
+
+  return (
+    <header className="shrink-0 flex items-center justify-between gap-3 px-4 lg:px-8 pt-3 pb-2 border-b border-border-subtle bg-surface/60 backdrop-blur-xl lg:bg-transparent lg:backdrop-blur-none z-20">
+      {/* Mobile menu button */}
+      <div className="flex items-center gap-3 lg:hidden shrink-0">
+        {showMenuButton && (
+          <button
+            onClick={onMenuClick}
+            className="text-text-main hover:text-primary transition-colors"
+          >
+            <span className="material-symbols-outlined">menu</span>
+          </button>
+        )}
+      </div>
+
+      {/* Page title with breadcrumbs */}
+      <div className="flex flex-col min-w-0 flex-1">
+        {breadcrumbs.length > 0 ? (
+          <div className="flex items-center gap-2">
+            {breadcrumbs.map((crumb, index) => (
+              <div
+                key={`${crumb.label}-${crumb.href || "current"}`}
+                className="flex items-center gap-2"
+              >
+                {index > 0 && (
+                  <span className="material-symbols-outlined text-text-muted text-base">
+                    chevron_right
+                  </span>
+                )}
+                {crumb.href ? (
+                  <Link
+                    href={crumb.href}
+                    className="text-text-muted hover:text-primary transition-colors"
+                  >
+                    {crumb.label}
+                  </Link>
+                ) : (
+                  <div className="flex items-center gap-2">
+                    {crumb.image && (
+                      <ProviderIcon
+                        src={crumb.image}
+                        alt={crumb.label}
+                        size={28}
+                        className="object-contain rounded max-w-[28px] max-h-[28px]"
+                        fallbackText={crumb.label.slice(0, 2).toUpperCase()}
+                      />
+                    )}
+                    <h1 className="text-base lg:text-2xl font-semibold text-text-main tracking-tight truncate">
+                      {translate(crumb.label)}
+                    </h1>
+                  </div>
+                )}
+              </div>
+            ))}
+          </div>
+        ) : title ? (
+          <div>
+            <div className="flex items-center gap-2">
+              {icon && (
+                <span className="material-symbols-outlined text-primary text-xl lg:text-2xl">
+                  {icon}
+                </span>
+              )}
+              <h1 className="text-base lg:text-2xl font-semibold tracking-tight truncate">
+                {translate(title)}
+              </h1>
+            </div>
+            {description && (
+              <p className="hidden lg:block text-sm text-text-muted truncate">
+                {translate(description)}
+              </p>
+            )}
+          </div>
+        ) : null}
+      </div>
+
+      {/* Right actions */}
+      <div className="flex items-center gap-1 shrink-0">
+        {displayName && loginMethod === "OIDC" && (
+          <div className="hidden sm:flex items-center max-w-[220px] px-3 py-1.5 rounded-full border border-border bg-surface/70 text-xs text-text-muted truncate">
+            <span className="material-symbols-outlined text-[14px] mr-1.5 text-primary">person</span>
+            <span className="truncate">{displayName}</span>
+            <span className="ml-2 shrink-0 rounded-full bg-primary/10 px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-primary">
+              OIDC
+            </span>
+          </div>
+        )}
+        <HeaderSearch />
+        <button
+          onClick={() => setDonateOpen(true)}
+          className="flex items-center gap-1.5 px-3 h-8 rounded-lg border border-pink-500/30 bg-pink-500/10 text-pink-600 dark:text-pink-400 hover:bg-pink-500/20 transition-colors text-sm font-medium"
+          aria-label="Donate"
+        >
+          <span className="material-symbols-outlined text-[18px]">volunteer_activism</span>
+          <span className="hidden sm:inline">Donate</span>
+        </button>
+        <ThemeToggle />
+        <HeaderLanguage />
+        <HeaderMenu onLogout={handleLogout} />
+      </div>
+      <DonateModal isOpen={donateOpen} onClose={() => setDonateOpen(false)} />
+    </header>
+  );
+}
+
+function HeaderSearch() {
+  const visible = useHeaderSearchStore((s) => s.visible);
+  const query = useHeaderSearchStore((s) => s.query);
+  const placeholder = useHeaderSearchStore((s) => s.placeholder);
+  const setQuery = useHeaderSearchStore((s) => s.setQuery);
+
+  if (!visible) return null;
+
+  return (
+    <div className="relative w-[160px] sm:w-[220px]">
+      <span className="material-symbols-outlined absolute left-2 top-1/2 -translate-y-1/2 text-text-muted text-[16px] pointer-events-none">
+        search
+      </span>
+      <input
+        type="text"
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder={placeholder}
+        className="w-full h-8 pl-7 pr-7 rounded-lg border border-border bg-surface/60 text-sm focus:outline-none focus:border-primary/50 transition-colors"
+      />
+      {query && (
+        <button
+          type="button"
+          onClick={() => setQuery("")}
+          className="absolute right-1 top-1/2 -translate-y-1/2 text-text-muted hover:text-text-main p-0.5 rounded"
+          aria-label="Clear search"
+        >
+          <span className="material-symbols-outlined text-[16px]">close</span>
+        </button>
+      )}
+    </div>
+  );
+}
+
+Header.propTypes = {
+  onMenuClick: PropTypes.func,
+  showMenuButton: PropTypes.bool,
+};
diff --git a/src/shared/components/HeaderLanguage.js b/src/shared/components/HeaderLanguage.js
new file mode 100644
index 0000000..0e24d3c
--- /dev/null
+++ b/src/shared/components/HeaderLanguage.js
@@ -0,0 +1,46 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { LOCALE_COOKIE, normalizeLocale } from "@/i18n/config";
+import { LOCALE_FLAGS } from "@/shared/constants/locales";
+import LanguageSwitcher from "./LanguageSwitcher";
+
+function getLocaleFromCookie() {
+  if (typeof document === "undefined") return "en";
+  const cookie = document.cookie
+    .split(";")
+    .find((c) => c.trim().startsWith(`${LOCALE_COOKIE}=`));
+  const value = cookie ? decodeURIComponent(cookie.split("=")[1]) : "en";
+  return normalizeLocale(value);
+}
+
+export default function HeaderLanguage() {
+  const [open, setOpen] = useState(false);
+  const [locale, setLocale] = useState("en");
+
+  useEffect(() => {
+    setLocale(getLocaleFromCookie());
+  }, [open]);
+
+  return (
+    <>
+      <button
+        onClick={() => setOpen(true)}
+        className="flex items-center justify-center p-2 rounded-lg text-text-muted hover:text-text-main hover:bg-black/5 dark:hover:bg-white/5 transition-all"
+        title="Language"
+        data-i18n-skip="true"
+      >
+        <span className="text-lg leading-none">{LOCALE_FLAGS[locale] || "🌐"}</span>
+      </button>
+
+      <LanguageSwitcher
+        hideTrigger
+        isOpen={open}
+        onClose={(next) => {
+          setOpen(false);
+          setLocale(next);
+        }}
+      />
+    </>
+  );
+}
diff --git a/src/shared/components/HeaderMenu.js b/src/shared/components/HeaderMenu.js
new file mode 100644
index 0000000..54ba676
--- /dev/null
+++ b/src/shared/components/HeaderMenu.js
@@ -0,0 +1,126 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import PropTypes from "prop-types";
+import { useTheme } from "@/shared/hooks/useTheme";
+import ChangelogModal from "./ChangelogModal";
+import { ConfirmModal } from "./Modal";
+
+function MenuItem({ icon, label, onClick, trailing, danger }) {
+  return (
+    <button
+      onClick={onClick}
+      className={`flex items-center gap-3 w-full px-4 py-2.5 text-sm transition-colors ${
+        danger
+          ? "text-red-500 hover:bg-red-500/10"
+          : "text-text-main hover:bg-black/5 dark:hover:bg-white/5"
+      }`}
+    >
+      <span className={`material-symbols-outlined text-[20px] ${danger ? "" : "text-text-muted"}`}>
+        {icon}
+      </span>
+      <span className="flex-1 text-left">{label}</span>
+      {trailing && <span className="text-base">{trailing}</span>}
+    </button>
+  );
+}
+
+MenuItem.propTypes = {
+  icon: PropTypes.string.isRequired,
+  label: PropTypes.string.isRequired,
+  onClick: PropTypes.func.isRequired,
+  trailing: PropTypes.node,
+  danger: PropTypes.bool,
+};
+
+export default function HeaderMenu({ onLogout }) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [changelogOpen, setChangelogOpen] = useState(false);
+  const [shutdownOpen, setShutdownOpen] = useState(false);
+  const [isShuttingDown, setIsShuttingDown] = useState(false);
+  const { toggleTheme, isDark } = useTheme();
+  const menuRef = useRef(null);
+
+  const handleShutdown = async () => {
+    setIsShuttingDown(true);
+    try {
+      await fetch("/api/version/shutdown", { method: "POST" });
+    } catch (e) {
+      // Expected to fail as server shuts down; ignore error
+    }
+    setIsShuttingDown(false);
+    setShutdownOpen(false);
+  };
+
+  useEffect(() => {
+    const handleClickOutside = (e) => {
+      if (menuRef.current && !menuRef.current.contains(e.target)) {
+        setIsOpen(false);
+      }
+    };
+    if (isOpen) {
+      document.addEventListener("mousedown", handleClickOutside);
+      return () => document.removeEventListener("mousedown", handleClickOutside);
+    }
+  }, [isOpen]);
+
+  const close = () => setIsOpen(false);
+
+  return (
+    <>
+      <div className="relative" ref={menuRef}>
+        <button
+          onClick={() => setIsOpen((v) => !v)}
+          className="flex items-center justify-center p-2 rounded-lg text-text-muted hover:text-text-main hover:bg-black/5 dark:hover:bg-white/5 transition-all"
+          title="Menu"
+        >
+          <span className="material-symbols-outlined">grid_view</span>
+        </button>
+
+        {isOpen && (
+          <div className="absolute right-0 top-full mt-2 w-60 bg-surface border border-black/10 dark:border-white/10 rounded-xl shadow-2xl z-50 animate-in fade-in zoom-in-95 duration-150 overflow-hidden py-1">
+            <MenuItem
+              icon="history"
+              label="Change Log"
+              onClick={() => { close(); setChangelogOpen(true); }}
+            />
+            <MenuItem
+              icon={isDark ? "light_mode" : "dark_mode"}
+              label="Theme"
+              onClick={() => { toggleTheme(); close(); }}
+            />
+            <MenuItem
+              icon="power_settings_new"
+              label="Shutdown"
+              danger
+              onClick={() => { close(); setShutdownOpen(true); }}
+            />
+            <MenuItem
+              icon="logout"
+              label="Logout"
+              danger
+              onClick={() => { close(); onLogout(); }}
+            />
+          </div>
+        )}
+      </div>
+
+      <ChangelogModal isOpen={changelogOpen} onClose={() => setChangelogOpen(false)} />
+      <ConfirmModal
+        isOpen={shutdownOpen}
+        onClose={() => setShutdownOpen(false)}
+        onConfirm={handleShutdown}
+        title="Close Proxy"
+        message="Are you sure you want to close the proxy server?"
+        confirmText="Close"
+        cancelText="Cancel"
+        variant="danger"
+        loading={isShuttingDown}
+      />
+    </>
+  );
+}
+
+HeaderMenu.propTypes = {
+  onLogout: PropTypes.func.isRequired,
+};
diff --git a/src/shared/components/IFlowCookieModal.js b/src/shared/components/IFlowCookieModal.js
new file mode 100644
index 0000000..b033fc2
--- /dev/null
+++ b/src/shared/components/IFlowCookieModal.js
@@ -0,0 +1,132 @@
+"use client";
+
+import { useState } from "react";
+import PropTypes from "prop-types";
+import { Modal, Button, Input } from "@/shared/components";
+
+/**
+ * iFlow Cookie Authentication Modal
+ * User pastes browser cookie to get fresh API key
+ */
+export default function IFlowCookieModal({ isOpen, onSuccess, onClose }) {
+  const [cookie, setCookie] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const [success, setSuccess] = useState(false);
+
+  const handleSubmit = async () => {
+    if (!cookie.trim()) {
+      setError("Please paste your cookie");
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const res = await fetch("/api/oauth/iflow/cookie", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ cookie: cookie.trim() }),
+      });
+
+      const data = await res.json();
+
+      if (!res.ok) {
+        throw new Error(data.error || "Authentication failed");
+      }
+
+      setSuccess(true);
+      setTimeout(() => {
+        onSuccess?.();
+        handleClose();
+      }, 1500);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleClose = () => {
+    setCookie("");
+    setError(null);
+    setSuccess(false);
+    onClose?.();
+  };
+
+  return (
+    <Modal isOpen={isOpen} onClose={handleClose} title="iFlow Cookie Authentication">
+      <div className="space-y-4">
+        {success ? (
+          <div className="text-center py-8">
+            <div className="text-6xl mb-4">✅</div>
+            <p className="text-lg font-medium text-text-primary">Authentication Successful!</p>
+            <p className="text-sm text-text-muted mt-2">Fresh API key obtained</p>
+          </div>
+        ) : (
+          <>
+            <div className="space-y-2">
+              <p className="text-sm text-text-muted">
+                To get a fresh API key, paste your browser cookie from{" "}
+                <a
+                  href="https://platform.iflow.cn"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-primary hover:underline"
+                >
+                  platform.iflow.cn
+                </a>
+              </p>
+              <div className="bg-surface-secondary p-3 rounded-lg text-xs space-y-2">
+                <p className="font-medium text-text-primary">How to get cookie:</p>
+                <ol className="list-decimal list-inside space-y-1 text-text-muted">
+                  <li>Open platform.iflow.cn in your browser</li>
+                  <li>Login to your account</li>
+                  <li>Open DevTools (F12) → Application/Storage → Cookies</li>
+                  <li>Copy the entire cookie string (must include BXAuth)</li>
+                  <li>Paste it below</li>
+                </ol>
+              </div>
+            </div>
+
+            <div className="space-y-2">
+              <label className="block text-sm font-medium text-text-primary">
+                Cookie String
+              </label>
+              <textarea
+                value={cookie}
+                onChange={(e) => setCookie(e.target.value)}
+                placeholder="BXAuth=xxx; ..."
+                className="w-full px-3 py-2 bg-surface-secondary border border-border rounded-lg text-sm text-text-primary placeholder-text-muted focus:outline-none focus:ring-2 focus:ring-primary resize-none"
+                rows={4}
+                disabled={loading}
+              />
+            </div>
+
+            {error && (
+              <div className="p-3 bg-error/10 border border-error/20 rounded-lg">
+                <p className="text-sm text-error">{error}</p>
+              </div>
+            )}
+
+            <div className="flex gap-3 pt-2">
+              <Button variant="secondary" onClick={handleClose} disabled={loading} fullWidth>
+                Cancel
+              </Button>
+              <Button onClick={handleSubmit} loading={loading} fullWidth>
+                Authenticate
+              </Button>
+            </div>
+          </>
+        )}
+      </div>
+    </Modal>
+  );
+}
+
+IFlowCookieModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  onSuccess: PropTypes.func,
+  onClose: PropTypes.func,
+};
diff --git a/src/shared/components/Input.js b/src/shared/components/Input.js
new file mode 100644
index 0000000..b6de734
--- /dev/null
+++ b/src/shared/components/Input.js
@@ -0,0 +1,65 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+export default function Input({
+  label,
+  type = "text",
+  placeholder,
+  value,
+  onChange,
+  error,
+  hint,
+  icon,
+  disabled = false,
+  required = false,
+  className,
+  inputClassName,
+  ...props
+}) {
+  return (
+    <div className={cn("flex flex-col gap-1.5", className)}>
+      {label && (
+        <label className="text-sm font-medium text-text-main">
+          {label}
+          {required && <span className="text-red-500 ml-1">*</span>}
+        </label>
+      )}
+      <div className="relative">
+        {icon && (
+          <div className="absolute inset-y-0 left-0 flex items-center pl-3 pointer-events-none text-text-muted">
+            <span className="material-symbols-outlined text-[20px]">{icon}</span>
+          </div>
+        )}
+        <input
+          type={type}
+          placeholder={placeholder}
+          value={value}
+          onChange={onChange}
+          disabled={disabled}
+          className={cn(
+            "w-full py-2.5 px-3 text-sm text-text-main bg-surface-2 rounded-[10px]",
+            "border border-transparent placeholder-text-muted/70",
+            "focus:outline-none focus:ring-2 focus:ring-brand-500/30 focus:border-brand-500/40",
+            "transition-all duration-150 ease-out disabled:opacity-50 disabled:cursor-not-allowed",
+            // iOS zoom fix
+            "text-[16px] sm:text-sm",
+            icon && "pl-10",
+            error && "ring-1 ring-red-500 focus:ring-2 focus:ring-red-500/40 border-red-500/40",
+            inputClassName
+          )}
+          {...props}
+        />
+      </div>
+      {error && (
+        <p className="text-xs text-red-500 flex items-center gap-1">
+          <span className="material-symbols-outlined text-[14px]">error</span>
+          {error}
+        </p>
+      )}
+      {hint && !error && (
+        <p className="text-xs text-text-muted">{hint}</p>
+      )}
+    </div>
+  );
+}
diff --git a/src/shared/components/KiroAuthModal.js b/src/shared/components/KiroAuthModal.js
new file mode 100644
index 0000000..dcc56cc
--- /dev/null
+++ b/src/shared/components/KiroAuthModal.js
@@ -0,0 +1,595 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import PropTypes from "prop-types";
+import { Modal, Button, Input } from "@/shared/components";
+
+/**
+ * Kiro Auth Method Selection Modal
+ * Auto-detects token from AWS SSO cache or allows manual import
+ */
+export default function KiroAuthModal({ isOpen, onMethodSelect, onClose }) {
+  const [selectedMethod, setSelectedMethod] = useState(null);
+  const [idcStartUrl, setIdcStartUrl] = useState("");
+  const [idcRegion, setIdcRegion] = useState("us-east-1");
+  const [refreshToken, setRefreshToken] = useState("");
+  const [cliProxyJson, setCliProxyJson] = useState("");
+  const [apiKey, setApiKey] = useState("");
+  const [apiKeyRegion, setApiKeyRegion] = useState("us-east-1");
+  const [error, setError] = useState(null);
+  const [importing, setImporting] = useState(false);
+  const [autoDetecting, setAutoDetecting] = useState(false);
+  const [autoDetected, setAutoDetected] = useState(false);
+  const [idcCredentials, setIdcCredentials] = useState(null);
+
+  // Auto-detect token when import method is selected
+  useEffect(() => {
+    if (selectedMethod !== "import" || !isOpen) return;
+
+    const autoDetect = async () => {
+      setAutoDetecting(true);
+      setError(null);
+      setAutoDetected(false);
+      setIdcCredentials(null);
+
+      try {
+        const res = await fetch("/api/oauth/kiro/auto-import");
+        const data = await res.json();
+
+        if (data.found) {
+          setRefreshToken(data.refreshToken);
+          setAutoDetected(true);
+          // Store IDC/organization credentials if present
+          if (data.clientId && data.clientSecret) {
+            setIdcCredentials({
+              clientId: data.clientId,
+              clientSecret: data.clientSecret,
+              region: data.region,
+              authMethod: data.authMethod,
+              profileArn: data.profileArn,
+            });
+          }
+        } else {
+          setError(data.error || "Could not auto-detect token");
+        }
+      } catch (err) {
+        setError("Failed to auto-detect token");
+      } finally {
+        setAutoDetecting(false);
+      }
+    };
+
+    autoDetect();
+  }, [selectedMethod, isOpen]);
+
+  const handleMethodSelect = (method) => {
+    setSelectedMethod(method);
+    setError(null);
+  };
+
+  const handleBack = () => {
+    setSelectedMethod(null);
+    setError(null);
+  };
+
+  const handleImportToken = async () => {
+    if (!refreshToken.trim()) {
+      setError("Please enter a refresh token");
+      return;
+    }
+
+    setImporting(true);
+    setError(null);
+
+    try {
+      const res = await fetch("/api/oauth/kiro/import", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          refreshToken: refreshToken.trim(),
+          ...(idcCredentials || {}),
+        }),
+      });
+
+      const data = await res.json();
+
+      if (!res.ok) {
+        throw new Error(data.error || "Import failed");
+      }
+
+      // Success - notify parent to refresh connections
+      onMethodSelect("import");
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setImporting(false);
+    }
+  };
+
+  const handleImportCliProxyJson = async () => {
+    if (!cliProxyJson.trim()) {
+      setError("Please paste CLIProxyAPI auth JSON");
+      return;
+    }
+
+    setImporting(true);
+    setError(null);
+
+    try {
+      const res = await fetch("/api/oauth/kiro/import-cli-proxy", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ json: cliProxyJson.trim() }),
+      });
+
+      const data = await res.json();
+
+      if (!res.ok) {
+        throw new Error(data.error || "CLIProxyAPI import failed");
+      }
+
+      onMethodSelect("import-cli-proxy");
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setImporting(false);
+    }
+  };
+
+  const handleIdcContinue = () => {
+    if (!idcStartUrl.trim()) {
+      setError("Please enter your IDC start URL");
+      return;
+    }
+    onMethodSelect("idc", { startUrl: idcStartUrl.trim(), region: idcRegion });
+  };
+
+  const handleApiKeyImport = async () => {
+    if (!apiKey.trim()) {
+      setError("Please enter an API key");
+      return;
+    }
+
+    setImporting(true);
+    setError(null);
+
+    try {
+      const res = await fetch("/api/oauth/kiro/api-key", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          apiKey: apiKey.trim(),
+          region: apiKeyRegion.trim() || "us-east-1",
+        }),
+      });
+
+      const data = await res.json();
+
+      if (!res.ok) {
+        throw new Error(data.error || "Import failed");
+      }
+
+      // Success - notify parent to refresh connections
+      onMethodSelect("api-key");
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setImporting(false);
+    }
+  };
+
+  const handleSocialLogin = (provider) => {
+    onMethodSelect("social", { provider });
+  };
+
+  return (
+    <Modal isOpen={isOpen} title="Connect Kiro" onClose={onClose} size="lg">
+      <div className="flex flex-col gap-4">
+        {/* Method Selection */}
+        {!selectedMethod && (
+          <div className="space-y-3">
+            <p className="text-sm text-text-muted mb-4">
+              Choose your authentication method:
+            </p>
+
+            {/* AWS Builder ID */}
+            <button
+              onClick={() => onMethodSelect("builder-id")}
+              className="w-full p-4 text-left border border-border rounded-lg hover:bg-sidebar transition-colors"
+            >
+              <div className="flex items-start gap-3">
+                <span className="material-symbols-outlined text-primary mt-0.5">shield</span>
+                <div className="flex-1">
+                  <h3 className="font-semibold mb-1">AWS Builder ID</h3>
+                  <p className="text-sm text-text-muted">
+                    Recommended for most users. Free AWS account required.
+                  </p>
+                </div>
+              </div>
+            </button>
+
+            {/* AWS IAM Identity Center (IDC) */}
+            <button
+              onClick={() => handleMethodSelect("idc")}
+              className="w-full p-4 text-left border border-border rounded-lg hover:bg-sidebar transition-colors"
+            >
+              <div className="flex items-start gap-3">
+                <span className="material-symbols-outlined text-primary mt-0.5">business</span>
+                <div className="flex-1">
+                  <h3 className="font-semibold mb-1">AWS IAM Identity Center</h3>
+                  <p className="text-sm text-text-muted">
+                    For enterprise users with custom AWS IAM Identity Center.
+                  </p>
+                </div>
+              </div>
+            </button>
+
+            {/* AWS API Key */}
+            <button
+              onClick={() => handleMethodSelect("api-key")}
+              className="w-full p-4 text-left border border-border rounded-lg hover:bg-sidebar transition-colors"
+            >
+              <div className="flex items-start gap-3">
+                <span className="material-symbols-outlined text-primary mt-0.5">key</span>
+                <div className="flex-1">
+                  <h3 className="font-semibold mb-1">API Key</h3>
+                  <p className="text-sm text-text-muted">
+                    Use a long-lived Kiro/CodeWhisperer API key (headless auth).
+                  </p>
+                </div>
+              </div>
+            </button>
+
+            {/* Google Social Login - HIDDEN */}
+            <button
+              onClick={() => handleMethodSelect("social-google")}
+              className="hidden w-full p-4 text-left border border-border rounded-lg hover:bg-sidebar transition-colors"
+            >
+              <div className="flex items-start gap-3">
+                <span className="material-symbols-outlined text-primary mt-0.5">account_circle</span>
+                <div className="flex-1">
+                  <h3 className="font-semibold mb-1">Google Account</h3>
+                  <p className="text-sm text-text-muted">
+                    Login with your Google account (manual callback).
+                  </p>
+                </div>
+              </div>
+            </button>
+
+            {/* GitHub Social Login - HIDDEN */}
+            <button
+              onClick={() => handleMethodSelect("social-github")}
+              className="hidden w-full p-4 text-left border border-border rounded-lg hover:bg-sidebar transition-colors"
+            >
+              <div className="flex items-start gap-3">
+                <span className="material-symbols-outlined text-primary mt-0.5">code</span>
+                <div className="flex-1">
+                  <h3 className="font-semibold mb-1">GitHub Account</h3>
+                  <p className="text-sm text-text-muted">
+                    Login with your GitHub account (manual callback).
+                  </p>
+                </div>
+              </div>
+            </button>
+
+            {/* Import Token */}
+            <button
+              onClick={() => handleMethodSelect("import")}
+              className="w-full p-4 text-left border border-border rounded-lg hover:bg-sidebar transition-colors"
+            >
+              <div className="flex items-start gap-3">
+                <span className="material-symbols-outlined text-primary mt-0.5">file_upload</span>
+                <div className="flex-1">
+                  <h3 className="font-semibold mb-1">Import Token</h3>
+                  <p className="text-sm text-text-muted">
+                    Paste refresh token from Kiro IDE.
+                  </p>
+                </div>
+              </div>
+            </button>
+
+            {/* Import CLIProxyAPI JSON */}
+            <button
+              onClick={() => handleMethodSelect("import-cli-proxy")}
+              className="w-full p-4 text-left border border-border rounded-lg hover:bg-sidebar transition-colors"
+            >
+              <div className="flex items-start gap-3">
+                <span className="material-symbols-outlined text-primary mt-0.5">data_object</span>
+                <div className="flex-1">
+                  <h3 className="font-semibold mb-1">Import CLIProxyAPI JSON</h3>
+                  <p className="text-sm text-text-muted">
+                    Paste external_idp auth JSON from CLIProxyAPI/Kiro Microsoft login.
+                  </p>
+                </div>
+              </div>
+            </button>
+          </div>
+        )}
+
+        {/* IDC Configuration */}
+        {selectedMethod === "idc" && (
+          <div className="space-y-4">
+            <div>
+              <label className="block text-sm font-medium mb-2">
+                IDC Start URL <span className="text-red-500">*</span>
+              </label>
+              <Input
+                value={idcStartUrl}
+                onChange={(e) => setIdcStartUrl(e.target.value)}
+                placeholder="https://your-org.awsapps.com/start"
+                className="font-mono text-sm"
+              />
+              <p className="text-xs text-text-muted mt-1">
+                Your organization&apos;s AWS IAM Identity Center URL
+              </p>
+            </div>
+
+            <div>
+              <label className="block text-sm font-medium mb-2">
+                AWS Region
+              </label>
+              <Input
+                value={idcRegion}
+                onChange={(e) => setIdcRegion(e.target.value)}
+                placeholder="us-east-1"
+                className="font-mono text-sm"
+              />
+              <p className="text-xs text-text-muted mt-1">
+                AWS region for your Identity Center (default: us-east-1)
+              </p>
+            </div>
+
+            {error && (
+              <p className="text-sm text-red-600">{error}</p>
+            )}
+
+            <div className="flex gap-2">
+              <Button onClick={handleIdcContinue} fullWidth>
+                Continue
+              </Button>
+              <Button onClick={handleBack} variant="ghost" fullWidth>
+                Back
+              </Button>
+            </div>
+          </div>
+        )}
+
+        {/* API Key */}
+        {selectedMethod === "api-key" && (
+          <div className="space-y-4">
+            <div className="bg-blue-50 dark:bg-blue-900/20 p-3 rounded-lg border border-blue-200 dark:border-blue-800">
+              <div className="flex gap-2">
+                <span className="material-symbols-outlined text-blue-600 dark:text-blue-400">info</span>
+                <p className="text-sm text-blue-800 dark:text-blue-200">
+                  Paste a long-lived Kiro/CodeWhisperer API key. It is validated
+                  against AWS and stored directly as a bearer credential (no refresh).
+                </p>
+              </div>
+            </div>
+
+            <div>
+              <label className="block text-sm font-medium mb-2">
+                API Key <span className="text-red-500">*</span>
+              </label>
+              <Input
+                value={apiKey}
+                onChange={(e) => setApiKey(e.target.value)}
+                placeholder="Paste your Kiro API key..."
+                className="font-mono text-sm"
+              />
+            </div>
+
+            <div>
+              <label className="block text-sm font-medium mb-2">
+                AWS Region
+              </label>
+              <Input
+                value={apiKeyRegion}
+                onChange={(e) => setApiKeyRegion(e.target.value)}
+                placeholder="us-east-1"
+                className="font-mono text-sm"
+              />
+              <p className="text-xs text-text-muted mt-1">
+                AWS region for the key (default: us-east-1)
+              </p>
+            </div>
+
+            {error && (
+              <div className="bg-red-50 dark:bg-red-900/20 p-3 rounded-lg border border-red-200 dark:border-red-800">
+                <p className="text-sm text-red-600 dark:text-red-400">{error}</p>
+              </div>
+            )}
+
+            <div className="flex gap-2">
+              <Button onClick={handleApiKeyImport} fullWidth disabled={importing || !apiKey.trim()}>
+                {importing ? "Validating..." : "Add API Key"}
+              </Button>
+              <Button onClick={handleBack} variant="ghost" fullWidth>
+                Back
+              </Button>
+            </div>
+          </div>
+        )}
+
+        {/* Social Login Info (Google) */}
+        {selectedMethod === "social-google" && (
+          <div className="space-y-4">
+            <div className="bg-amber-50 dark:bg-amber-900/20 p-4 rounded-lg border border-amber-200 dark:border-amber-800">
+              <div className="flex gap-2">
+                <span className="material-symbols-outlined text-amber-600 dark:text-amber-400">info</span>
+                <div className="flex-1 text-sm">
+                  <p className="font-medium text-amber-900 dark:text-amber-100 mb-1">
+                    Manual Callback Required
+                  </p>
+                  <p className="text-amber-800 dark:text-amber-200">
+                    After login, you&apos;ll need to copy the callback URL from your browser and paste it back here.
+                  </p>
+                </div>
+              </div>
+            </div>
+
+            <div className="flex gap-2">
+              <Button onClick={() => handleSocialLogin("google")} fullWidth>
+                Continue with Google
+              </Button>
+              <Button onClick={handleBack} variant="ghost" fullWidth>
+                Back
+              </Button>
+            </div>
+          </div>
+        )}
+
+        {/* Social Login Info (GitHub) */}
+        {selectedMethod === "social-github" && (
+          <div className="space-y-4">
+            <div className="bg-amber-50 dark:bg-amber-900/20 p-4 rounded-lg border border-amber-200 dark:border-amber-800">
+              <div className="flex gap-2">
+                <span className="material-symbols-outlined text-amber-600 dark:text-amber-400">info</span>
+                <div className="flex-1 text-sm">
+                  <p className="font-medium text-amber-900 dark:text-amber-100 mb-1">
+                    Manual Callback Required
+                  </p>
+                  <p className="text-amber-800 dark:text-amber-200">
+                    After login, you&apos;ll need to copy the callback URL from your browser and paste it back here.
+                  </p>
+                </div>
+              </div>
+            </div>
+
+            <div className="flex gap-2">
+              <Button onClick={() => handleSocialLogin("github")} fullWidth>
+                Continue with GitHub
+              </Button>
+              <Button onClick={handleBack} variant="ghost" fullWidth>
+                Back
+              </Button>
+            </div>
+          </div>
+        )}
+
+        {/* Import Token */}
+        {selectedMethod === "import" && (
+          <div className="space-y-4">
+            {/* Auto-detecting state */}
+            {autoDetecting && (
+              <div className="text-center py-6">
+                <div className="size-16 mx-auto mb-4 rounded-full bg-primary/10 flex items-center justify-center">
+                  <span className="material-symbols-outlined text-3xl text-primary animate-spin">
+                    progress_activity
+                  </span>
+                </div>
+                <h3 className="text-lg font-semibold mb-2">Auto-detecting token...</h3>
+                <p className="text-sm text-text-muted">
+                  Reading from AWS SSO cache
+                </p>
+              </div>
+            )}
+
+            {/* Form (shown after auto-detect completes) */}
+            {!autoDetecting && (
+              <>
+                {/* Success message if auto-detected */}
+                {autoDetected && (
+                  <div className="bg-green-50 dark:bg-green-900/20 p-3 rounded-lg border border-green-200 dark:border-green-800">
+                    <div className="flex gap-2">
+                      <span className="material-symbols-outlined text-green-600 dark:text-green-400">check_circle</span>
+                      <p className="text-sm text-green-800 dark:text-green-200">
+                        Token auto-detected from Kiro IDE successfully!
+                      </p>
+                    </div>
+                  </div>
+                )}
+
+                {/* Info message if not auto-detected */}
+                {!autoDetected && !error && (
+                  <div className="bg-blue-50 dark:bg-blue-900/20 p-3 rounded-lg border border-blue-200 dark:border-blue-800">
+                    <div className="flex gap-2">
+                      <span className="material-symbols-outlined text-blue-600 dark:text-blue-400">info</span>
+                      <p className="text-sm text-blue-800 dark:text-blue-200">
+                        Kiro IDE not detected. Please paste your refresh token manually.
+                      </p>
+                    </div>
+                  </div>
+                )}
+
+                <div>
+                  <label className="block text-sm font-medium mb-2">
+                    Refresh Token <span className="text-red-500">*</span>
+                  </label>
+                  <Input
+                    value={refreshToken}
+                    onChange={(e) => setRefreshToken(e.target.value)}
+                    placeholder="Token will be auto-filled..."
+                    className="font-mono text-sm"
+                  />
+                </div>
+
+                {error && (
+                  <div className="bg-red-50 dark:bg-red-900/20 p-3 rounded-lg border border-red-200 dark:border-red-800">
+                    <p className="text-sm text-red-600 dark:text-red-400">{error}</p>
+                  </div>
+                )}
+
+                <div className="flex gap-2">
+                  <Button onClick={handleImportToken} fullWidth disabled={importing || !refreshToken.trim()}>
+                    {importing ? "Importing..." : "Import Token"}
+                  </Button>
+                  <Button onClick={handleBack} variant="ghost" fullWidth>
+                    Back
+                  </Button>
+                </div>
+              </>
+            )}
+          </div>
+        )}
+
+        {/* Import CLIProxyAPI JSON */}
+        {selectedMethod === "import-cli-proxy" && (
+          <div className="space-y-4">
+            <div className="bg-blue-50 dark:bg-blue-900/20 p-3 rounded-lg border border-blue-200 dark:border-blue-800">
+              <div className="flex gap-2">
+                <span className="material-symbols-outlined text-blue-600 dark:text-blue-400">info</span>
+                <p className="text-sm text-blue-800 dark:text-blue-200">
+                  Paste the Kiro CLIProxyAPI auth JSON containing auth_method=external_idp. Only Microsoft login token endpoints are accepted.
+                </p>
+              </div>
+            </div>
+
+            <div>
+              <label className="block text-sm font-medium mb-2">
+                CLIProxyAPI Auth JSON <span className="text-red-500">*</span>
+              </label>
+              <textarea
+                value={cliProxyJson}
+                onChange={(e) => setCliProxyJson(e.target.value)}
+                placeholder={'{"auth_method":"external_idp","access_token":"...","refresh_token":"...","client_id":"...","token_endpoint":"https://login.microsoftonline.com/.../oauth2/v2.0/token","profile_arn":"...","scopes":"..."}'}
+                className="min-h-40 w-full rounded-md border border-border bg-background p-3 font-mono text-sm outline-none focus:border-primary"
+              />
+            </div>
+
+            {error && (
+              <div className="bg-red-50 dark:bg-red-900/20 p-3 rounded-lg border border-red-200 dark:border-red-800">
+                <p className="text-sm text-red-600 dark:text-red-400">{error}</p>
+              </div>
+            )}
+
+            <div className="flex gap-2">
+              <Button onClick={handleImportCliProxyJson} fullWidth disabled={importing || !cliProxyJson.trim()}>
+                {importing ? "Importing..." : "Import CLIProxyAPI JSON"}
+              </Button>
+              <Button onClick={handleBack} variant="ghost" fullWidth>
+                Back
+              </Button>
+            </div>
+          </div>
+        )}
+      </div>
+    </Modal>
+  );
+}
+
+KiroAuthModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  onMethodSelect: PropTypes.func.isRequired,
+  onClose: PropTypes.func.isRequired,
+};
diff --git a/src/shared/components/KiroOAuthWrapper.js b/src/shared/components/KiroOAuthWrapper.js
new file mode 100644
index 0000000..ec50f3a
--- /dev/null
+++ b/src/shared/components/KiroOAuthWrapper.js
@@ -0,0 +1,103 @@
+"use client";
+
+import { useState, useCallback } from "react";
+import PropTypes from "prop-types";
+import OAuthModal from "./OAuthModal";
+import KiroAuthModal from "./KiroAuthModal";
+import KiroSocialOAuthModal from "./KiroSocialOAuthModal";
+
+/**
+ * Kiro OAuth Wrapper
+ * Orchestrates between method selection, device code flow, and social login flow
+ */
+export default function KiroOAuthWrapper({ isOpen, providerInfo, onSuccess, onClose }) {
+  const [authMethod, setAuthMethod] = useState(null); // null | "builder-id" | "idc" | "social" | "import"
+  const [socialProvider, setSocialProvider] = useState(null); // "google" | "github"
+  const [idcConfig, setIdcConfig] = useState(null);
+
+  const handleMethodSelect = useCallback((method, config) => {
+    if (method === "builder-id") {
+      // Use device code flow (AWS Builder ID)
+      setAuthMethod("builder-id");
+    } else if (method === "idc") {
+      // Use device code flow with IDC config
+      setAuthMethod("idc");
+      setIdcConfig(config);
+    } else if (method === "social") {
+      // Use social login with manual callback
+      setAuthMethod("social");
+      setSocialProvider(config.provider);
+    } else if (method === "import" || method === "api-key") {
+      // Import / API-key handled in KiroAuthModal, just close
+      onSuccess?.();
+    }
+  }, [onSuccess]);
+
+  const handleBack = () => {
+    setAuthMethod(null);
+    setSocialProvider(null);
+    setIdcConfig(null);
+  };
+
+  const handleSocialSuccess = () => {
+    setAuthMethod(null);
+    setSocialProvider(null);
+    onSuccess?.();
+    onClose?.(); // Close modal after success
+  };
+
+  const handleDeviceSuccess = () => {
+    setAuthMethod(null);
+    setIdcConfig(null);
+    onSuccess?.();
+    onClose?.(); // Close modal after success
+  };
+
+  // Show method selection first
+  if (!authMethod) {
+    return (
+      <KiroAuthModal
+        isOpen={isOpen}
+        onMethodSelect={handleMethodSelect}
+        onClose={onClose}
+      />
+    );
+  }
+
+  // Show device code flow (Builder ID or IDC)
+  if (authMethod === "builder-id" || authMethod === "idc") {
+    return (
+      <OAuthModal
+        isOpen={isOpen}
+        provider="kiro"
+        providerInfo={providerInfo}
+        onSuccess={handleDeviceSuccess}
+        onClose={handleBack}
+        idcConfig={idcConfig}
+      />
+    );
+  }
+
+  // Show social login flow (Google/GitHub with manual callback)
+  if (authMethod === "social" && socialProvider) {
+    return (
+      <KiroSocialOAuthModal
+        isOpen={isOpen}
+        provider={socialProvider}
+        onSuccess={handleSocialSuccess}
+        onClose={handleBack}
+      />
+    );
+  }
+
+  return null;
+}
+
+KiroOAuthWrapper.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  providerInfo: PropTypes.shape({
+    name: PropTypes.string,
+  }),
+  onSuccess: PropTypes.func,
+  onClose: PropTypes.func.isRequired,
+};
diff --git a/src/shared/components/KiroSocialOAuthModal.js b/src/shared/components/KiroSocialOAuthModal.js
new file mode 100644
index 0000000..76cc95f
--- /dev/null
+++ b/src/shared/components/KiroSocialOAuthModal.js
@@ -0,0 +1,214 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import PropTypes from "prop-types";
+import { Modal, Button, Input } from "@/shared/components";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+
+/**
+ * Kiro Social OAuth Modal (Google/GitHub)
+ * Handles manual callback URL flow for social login
+ */
+export default function KiroSocialOAuthModal({ isOpen, provider, onSuccess, onClose }) {
+  const [step, setStep] = useState("loading"); // loading | input | success | error
+  const [authUrl, setAuthUrl] = useState("");
+  const [authData, setAuthData] = useState(null);
+  const [callbackUrl, setCallbackUrl] = useState("");
+  const [error, setError] = useState(null);
+  const { copied, copy } = useCopyToClipboard();
+  const openedRef = useRef(false);
+
+  // Reset auto-open guard when modal closes so it can re-open next session.
+  useEffect(() => {
+    if (!isOpen) openedRef.current = false;
+  }, [isOpen]);
+
+  // Initialize auth flow
+  useEffect(() => {
+    if (!isOpen || !provider) return;
+
+    const initAuth = async () => {
+      try {
+        setError(null);
+        setStep("loading");
+
+        const res = await fetch(`/api/oauth/kiro/social-authorize?provider=${provider}`);
+        const data = await res.json();
+
+        if (!res.ok) {
+          throw new Error(data.error);
+        }
+
+        setAuthData(data);
+        setAuthUrl(data.authUrl);
+        setStep("input");
+
+        // Auto-open browser once per modal session.
+        if (!openedRef.current) {
+          openedRef.current = true;
+          window.open(data.authUrl, "_blank");
+        }
+      } catch (err) {
+        setError(err.message);
+        setStep("error");
+      }
+    };
+
+    initAuth();
+  }, [isOpen, provider]);
+
+  const handleManualSubmit = async () => {
+    try {
+      setError(null);
+      
+      // Parse callback URL - can be either kiro:// or http://localhost format
+      let url;
+      try {
+        url = new URL(callbackUrl);
+      } catch (e) {
+        // If URL parsing fails, might be malformed
+        throw new Error("Invalid callback URL format");
+      }
+
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      const errorParam = url.searchParams.get("error");
+
+      if (errorParam) {
+        throw new Error(url.searchParams.get("error_description") || errorParam);
+      }
+
+      if (!code) {
+        throw new Error("No authorization code found in URL");
+      }
+
+      // Exchange code for tokens
+      const res = await fetch("/api/oauth/kiro/social-exchange", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          code,
+          codeVerifier: authData.codeVerifier,
+          provider,
+        }),
+      });
+
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error);
+
+      setStep("success");
+      onSuccess?.();
+    } catch (err) {
+      setError(err.message);
+      setStep("error");
+    }
+  };
+
+  const providerName = provider === "google" ? "Google" : "GitHub";
+
+  return (
+    <Modal isOpen={isOpen} title={`Connect Kiro via ${providerName}`} onClose={onClose} size="lg">
+      <div className="flex flex-col gap-4">
+        {/* Loading */}
+        {step === "loading" && (
+          <div className="text-center py-6">
+            <div className="size-16 mx-auto mb-4 rounded-full bg-primary/10 flex items-center justify-center">
+              <span className="material-symbols-outlined text-3xl text-primary animate-spin">
+                progress_activity
+              </span>
+            </div>
+            <h3 className="text-lg font-semibold mb-2">Initializing...</h3>
+            <p className="text-sm text-text-muted">
+              Setting up {providerName} authentication
+            </p>
+          </div>
+        )}
+
+        {/* Manual Input Step */}
+        {step === "input" && (
+          <>
+            <div className="space-y-4">
+              <div>
+                <p className="text-sm font-medium mb-2">Step 1: Open this URL in your browser</p>
+                <div className="flex gap-2">
+                  <Input value={authUrl} readOnly className="flex-1 font-mono text-xs" />
+                  <Button 
+                    variant="secondary" 
+                    icon={copied === "auth_url" ? "check" : "content_copy"} 
+                    onClick={() => copy(authUrl, "auth_url")}
+                  >
+                    Copy
+                  </Button>
+                </div>
+              </div>
+
+              <div>
+                <p className="text-sm font-medium mb-2">Step 2: Paste the callback URL here</p>
+                <p className="text-xs text-text-muted mb-2">
+                  After authorization, copy the full URL from your browser address bar.
+                </p>
+                <Input
+                  value={callbackUrl}
+                  onChange={(e) => setCallbackUrl(e.target.value)}
+                  placeholder="kiro://kiro.kiroAgent/authenticate-success?code=..."
+                  className="font-mono text-xs"
+                />
+              </div>
+            </div>
+
+            <div className="flex gap-2">
+              <Button onClick={handleManualSubmit} fullWidth disabled={!callbackUrl}>
+                Connect
+              </Button>
+              <Button onClick={onClose} variant="ghost" fullWidth>
+                Cancel
+              </Button>
+            </div>
+          </>
+        )}
+
+        {/* Success */}
+        {step === "success" && (
+          <div className="text-center py-6">
+            <div className="size-16 mx-auto mb-4 rounded-full bg-green-100 dark:bg-green-900/30 flex items-center justify-center">
+              <span className="material-symbols-outlined text-3xl text-green-600">check_circle</span>
+            </div>
+            <h3 className="text-lg font-semibold mb-2">Connected Successfully!</h3>
+            <p className="text-sm text-text-muted mb-4">
+              Your Kiro account via {providerName} has been connected.
+            </p>
+            <Button onClick={onClose} fullWidth>
+              Done
+            </Button>
+          </div>
+        )}
+
+        {/* Error */}
+        {step === "error" && (
+          <div className="text-center py-6">
+            <div className="size-16 mx-auto mb-4 rounded-full bg-red-100 dark:bg-red-900/30 flex items-center justify-center">
+              <span className="material-symbols-outlined text-3xl text-red-600">error</span>
+            </div>
+            <h3 className="text-lg font-semibold mb-2">Connection Failed</h3>
+            <p className="text-sm text-red-600 mb-4">{error}</p>
+            <div className="flex gap-2">
+              <Button onClick={() => setStep("input")} variant="secondary" fullWidth>
+                Try Again
+              </Button>
+              <Button onClick={onClose} variant="ghost" fullWidth>
+                Cancel
+              </Button>
+            </div>
+          </div>
+        )}
+      </div>
+    </Modal>
+  );
+}
+
+KiroSocialOAuthModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  provider: PropTypes.oneOf(["google", "github"]).isRequired,
+  onSuccess: PropTypes.func,
+  onClose: PropTypes.func.isRequired,
+};
diff --git a/src/shared/components/LanguageSwitcher.js b/src/shared/components/LanguageSwitcher.js
new file mode 100644
index 0000000..7697e64
--- /dev/null
+++ b/src/shared/components/LanguageSwitcher.js
@@ -0,0 +1,191 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+import { LOCALES, LOCALE_COOKIE, normalizeLocale } from "@/i18n/config";
+import { reloadTranslations } from "@/i18n/runtime";
+
+function getLocaleFromCookie() {
+  if (typeof document === "undefined") return "en";
+  const cookie = document.cookie
+    .split(";")
+    .find((c) => c.trim().startsWith(`${LOCALE_COOKIE}=`));
+  const value = cookie ? decodeURIComponent(cookie.split("=")[1]) : "en";
+  return normalizeLocale(value);
+}
+
+// Locale display names and flags - will be translated by runtime i18n
+const getLocaleInfo = (locale) => {
+  const locales = {
+    "en": { name: "English", flag: "🇺🇸" },
+    "vi": { name: "Tiếng Việt", flag: "🇻🇳" },
+    "zh-CN": { name: "简体中文", flag: "🇨🇳" },
+    "zh-TW": { name: "繁體中文", flag: "🇹🇼" },
+    "ja": { name: "日本語", flag: "🇯🇵" },
+    "pt-BR": { name: "Português (Brasil)", flag: "🇧🇷" },
+    "pt-PT": { name: "Português (Portugal)", flag: "🇵🇹" },
+    "ko": { name: "한국어", flag: "🇰🇷" },
+    "es": { name: "Español", flag: "🇪🇸" },
+    "de": { name: "Deutsch", flag: "🇩🇪" },
+    "fr": { name: "Français", flag: "🇫🇷" },
+    "he": { name: "עברית", flag: "🇮🇱" },
+    "ar": { name: "العربية", flag: "🇸🇦" },
+    "ru": { name: "Русский", flag: "🇷🇺" },
+    "pl": { name: "Polski", flag: "🇵🇱" },
+    "cs": { name: "Čeština", flag: "🇨🇿" },
+    "nl": { name: "Nederlands", flag: "🇳🇱" },
+    "tr": { name: "Türkçe", flag: "🇹🇷" },
+    "uk": { name: "Українська", flag: "🇺🇦" },
+    "tl": { name: "Tagalog", flag: "🇵🇭" },
+    "id": { name: "Indonesia", flag: "🇮🇩" },
+    "th": { name: "ไทย", flag: "🇹🇭" },
+    "hi": { name: "हिन्दी", flag: "🇮🇳" },
+    "bn": { name: "বাংলা", flag: "🇧🇩" },
+    "ur": { name: "اردو", flag: "🇵🇰" },
+    "ro": { name: "Română", flag: "🇷🇴" },
+    "sv": { name: "Svenska", flag: "🇸🇪" },
+    "it": { name: "Italiano", flag: "🇮🇹" },
+    "el": { name: "Ελληνικά", flag: "🇬🇷" },
+    "hu": { name: "Magyar", flag: "🇭🇺" },
+    "fi": { name: "Suomi", flag: "🇫🇮" },
+    "da": { name: "Dansk", flag: "🇩🇰" },
+    "no": { name: "Norsk", flag: "🇳🇴" },
+    "fa": { name: "فارسی", flag: "🇮🇷" }
+  };
+  return locales[locale] || { name: locale, flag: "🌐" };
+};
+
+export default function LanguageSwitcher({ className = "", isOpen: controlledOpen, onClose, hideTrigger = false }) {
+  const [locale, setLocale] = useState("en");
+  const [isPending, setIsPending] = useState(false);
+  const [internalOpen, setInternalOpen] = useState(false);
+  const modalRef = useRef(null);
+
+  const isControlled = typeof controlledOpen === "boolean";
+  const isOpen = isControlled ? controlledOpen : internalOpen;
+  const setIsOpen = (value) => {
+    if (isControlled) {
+      if (!value && onClose) onClose(locale);
+    } else {
+      setInternalOpen(value);
+    }
+  };
+
+  useEffect(() => {
+    setLocale(getLocaleFromCookie());
+  }, []);
+
+  // Close modal when clicking outside
+  useEffect(() => {
+    function handleClickOutside(event) {
+      if (modalRef.current && !modalRef.current.contains(event.target)) {
+        setIsOpen(false);
+      }
+    }
+    if (isOpen) {
+      document.addEventListener("mousedown", handleClickOutside);
+      return () => document.removeEventListener("mousedown", handleClickOutside);
+    }
+  }, [isOpen]);
+
+  const handleSetLocale = async (nextLocale) => {
+    if (nextLocale === locale || isPending) return;
+
+    setIsPending(true);
+    setIsOpen(false);
+    try {
+      await fetch("/api/locale", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ locale: nextLocale }),
+      });
+      
+      // Reload translations without full page reload
+      await reloadTranslations();
+      setLocale(nextLocale);
+    } catch (err) {
+      console.error("Failed to set locale:", err);
+    } finally {
+      setIsPending(false);
+    }
+  };
+
+  return (
+    <div className={className}>
+      {/* Trigger button */}
+      {!hideTrigger && (
+        <button
+          onClick={() => setIsOpen(!isOpen)}
+          disabled={isPending}
+          className="flex items-center gap-2 px-3 py-2 rounded-lg text-text-muted hover:text-text-main hover:bg-surface/60 transition-colors"
+          title="Language"
+          data-i18n-skip="true"
+        >
+          <span className="material-symbols-outlined text-[20px]">language</span>
+          <span className="text-sm font-medium">{getLocaleInfo(locale).name}</span>
+          <span className="text-lg">{getLocaleInfo(locale).flag}</span>
+        </button>
+      )}
+
+      {/* Portal modal - renders at document.body to avoid parent layout constraints */}
+      {isOpen && createPortal(
+        <div className="fixed inset-0 z-50 flex items-center justify-center p-4" data-i18n-skip="true">
+          {/* Overlay */}
+          <div
+            className="absolute inset-0 bg-black/30 backdrop-blur-sm"
+            onClick={() => setIsOpen(false)}
+          />
+
+          {/* Modal content */}
+          <div
+            ref={modalRef}
+            className="relative w-full bg-surface border border-black/10 dark:border-white/10 rounded-xl shadow-2xl animate-in fade-in zoom-in-95 duration-200 max-w-2xl flex flex-col max-h-[80vh]"
+          >
+            {/* Modal header */}
+            <div className="flex items-center justify-between p-3 border-b border-black/5 dark:border-white/5">
+              <h2 className="text-lg font-semibold text-text-main">Select Language</h2>
+              <button
+                onClick={() => setIsOpen(false)}
+                className="p-1.5 rounded-lg text-text-muted hover:bg-black/5 dark:hover:bg-white/5 transition-colors"
+                aria-label="Close"
+              >
+                <span className="material-symbols-outlined text-[20px]">close</span>
+              </button>
+            </div>
+
+            {/* Modal body - fixed grid columns, equal sizing */}
+            <div className="p-6 overflow-y-auto flex-1">
+              <div className="grid grid-cols-[repeat(auto-fill,minmax(100px,1fr))] gap-2">
+                {LOCALES.map((item) => {
+                  const active = locale === item;
+                  const info = getLocaleInfo(item);
+                  return (
+                    <button
+                      key={item}
+                      onClick={() => handleSetLocale(item)}
+                      disabled={isPending}
+                      className={`flex flex-col items-center justify-start gap-1 px-2 py-3 rounded-lg text-xs font-medium transition-colors w-full ${
+                        active
+                          ? "bg-primary/15 text-primary ring-2 ring-primary"
+                          : "text-text-main hover:bg-black/5 dark:hover:bg-white/5"
+                      } ${isPending ? "opacity-70 cursor-wait" : ""}`}
+                      title={info.name}
+                    >
+                      <span className="text-2xl">{info.flag}</span>
+                      {/* Fixed 2-line height so all cards are uniform */}
+                      <span className="text-center leading-tight line-clamp-2 h-8 flex items-center">{info.name}</span>
+                      {active && (
+                        <span className="material-symbols-outlined text-sm">check</span>
+                      )}
+                    </button>
+                  );
+                })}
+              </div>
+            </div>
+          </div>
+        </div>,
+        document.body
+      )}
+    </div>
+  );
+}
diff --git a/src/shared/components/Loading.js b/src/shared/components/Loading.js
new file mode 100644
index 0000000..c187583
--- /dev/null
+++ b/src/shared/components/Loading.js
@@ -0,0 +1,75 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+// Spinner loading
+export function Spinner({ size = "md", className }) {
+  const sizes = {
+    sm: "size-4",
+    md: "size-6",
+    lg: "size-8",
+    xl: "size-12",
+  };
+
+  return (
+    <span
+      className={cn(
+        "material-symbols-outlined animate-spin text-brand-500",
+        sizes[size],
+        className
+      )}
+    >
+      progress_activity
+    </span>
+  );
+}
+
+// Full page loading
+export function PageLoading({ message = "Loading..." }) {
+  return (
+    <div className="fixed inset-0 z-50 flex flex-col items-center justify-center bg-bg">
+      <Spinner size="xl" />
+      <p className="mt-4 text-text-muted">{message}</p>
+    </div>
+  );
+}
+
+// Skeleton loading
+export function Skeleton({ className, ...props }) {
+  return (
+    <div
+      className={cn(
+        "animate-pulse rounded-[10px] bg-surface-2",
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+// Card skeleton
+export function CardSkeleton() {
+  return (
+    <div className="p-6 rounded-[14px] border border-border-subtle bg-surface shadow-[var(--shadow-soft)]">
+      <div className="flex items-center justify-between mb-4">
+        <Skeleton className="h-4 w-24" />
+        <Skeleton className="size-10 rounded-[10px]" />
+      </div>
+      <Skeleton className="h-8 w-16 mb-2" />
+      <Skeleton className="h-3 w-20" />
+    </div>
+  );
+}
+
+export default function Loading({ type = "spinner", ...props }) {
+  switch (type) {
+    case "page":
+      return <PageLoading {...props} />;
+    case "skeleton":
+      return <Skeleton {...props} />;
+    case "card":
+      return <CardSkeleton {...props} />;
+    default:
+      return <Spinner {...props} />;
+  }
+}
diff --git a/src/shared/components/ManualConfigModal.js b/src/shared/components/ManualConfigModal.js
new file mode 100644
index 0000000..6f2b1d3
--- /dev/null
+++ b/src/shared/components/ManualConfigModal.js
@@ -0,0 +1,44 @@
+"use client";
+
+import { useState } from "react";
+import Modal from "./Modal";
+import Button from "./Button";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+
+export default function ManualConfigModal({ isOpen, onClose, title = "Manual Configuration", configs = [] }) {
+  const { copy } = useCopyToClipboard();
+  const [copiedIndex, setCopiedIndex] = useState(null);
+
+  const copyConfig = (text, index) => {
+    copy(text, `manualconfig-${index}`);
+    setCopiedIndex(index);
+    setTimeout(() => setCopiedIndex(null), 2000);
+  };
+
+  return (
+    <Modal isOpen={isOpen} onClose={onClose} title={title} size="xl">
+      <div className="flex flex-col gap-4">
+        {configs.map((config, index) => (
+          <div key={index} className="flex flex-col gap-2">
+            <div className="flex items-center justify-between">
+              <span className="text-sm font-medium text-text-main">{config.filename}</span>
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => copyConfig(config.content, index)}
+              >
+                <span className="material-symbols-outlined text-[14px] mr-1">
+                  {copiedIndex === index ? "check" : "content_copy"}
+                </span>
+                {copiedIndex === index ? "Copied!" : "Copy"}
+              </Button>
+            </div>
+            <pre className="px-3 py-2 bg-black/5 dark:bg-white/5 rounded font-mono text-xs overflow-x-auto whitespace-pre-wrap break-all max-h-60 overflow-y-auto border border-border">
+              {config.content}
+            </pre>
+          </div>
+        ))}
+      </div>
+    </Modal>
+  );
+}
diff --git a/src/shared/components/McpMarketplaceModal.js b/src/shared/components/McpMarketplaceModal.js
new file mode 100644
index 0000000..5b18dfb
--- /dev/null
+++ b/src/shared/components/McpMarketplaceModal.js
@@ -0,0 +1,255 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import Modal from "./Modal";
+
+const REGISTRY_ENDPOINT = "/api/cli-tools/cowork-mcp-registry";
+const TOOLS_ENDPOINT = "/api/cli-tools/cowork-mcp-tools";
+
+export default function McpMarketplaceModal({ isOpen, onClose, onAdd, addedNames = [] }) {
+  const [servers, setServers] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [search, setSearch] = useState("");
+  const [filter, setFilter] = useState("all");
+  const [error, setError] = useState(null);
+  const [expandedUrl, setExpandedUrl] = useState(null);
+  const [toolsCache, setToolsCache] = useState({});
+  const [toolsLoading, setToolsLoading] = useState({});
+  const [toolSelection, setToolSelection] = useState({});
+
+  useEffect(() => {
+    if (!isOpen) return;
+    if (servers.length > 0) return;
+    setLoading(true);
+    fetch(REGISTRY_ENDPOINT)
+      .then((r) => r.json())
+      .then((d) => {
+        if (d.error) setError(d.error);
+        else setServers(d.servers || []);
+      })
+      .catch((e) => setError(e.message))
+      .finally(() => setLoading(false));
+  }, [isOpen]);
+
+  const addedSet = useMemo(() => new Set(addedNames), [addedNames]);
+
+  const filtered = useMemo(() => {
+    const q = search.trim().toLowerCase();
+    return servers.filter((s) => {
+      if (filter === "authless" && s.oauth) return false;
+      if (filter === "oauth" && !s.oauth) return false;
+      if (!q) return true;
+      return (
+        (s.title || "").toLowerCase().includes(q) ||
+        (s.description || "").toLowerCase().includes(q) ||
+        (s.name || "").toLowerCase().includes(q)
+      );
+    });
+  }, [servers, search, filter]);
+
+  const fetchTools = async (server) => {
+    if (toolsCache[server.url]) return;
+    setToolsLoading((p) => ({ ...p, [server.url]: true }));
+    try {
+      const r = await fetch(TOOLS_ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ url: server.url }),
+      });
+      const d = await r.json();
+      const tools = d.tools || [];
+      const fallback = Array.isArray(server.toolNames) ? server.toolNames : [];
+      const toolNames = tools.length > 0 ? tools.map((t) => t.name) : fallback;
+      setToolsCache((p) => ({ ...p, [server.url]: { tools, requiresAuth: !!d.requiresAuth, error: d.error } }));
+      // Default: all checked
+      setToolSelection((p) => ({ ...p, [server.url]: Object.fromEntries(toolNames.map((t) => [t, true])) }));
+    } catch (e) {
+      setToolsCache((p) => ({ ...p, [server.url]: { tools: [], error: e.message } }));
+    } finally {
+      setToolsLoading((p) => ({ ...p, [server.url]: false }));
+    }
+  };
+
+  const expandServer = (server) => {
+    if (expandedUrl === server.url) {
+      setExpandedUrl(null);
+      return;
+    }
+    setExpandedUrl(server.url);
+    fetchTools(server);
+  };
+
+  const toggleTool = (url, tool) => {
+    setToolSelection((prev) => ({ ...prev, [url]: { ...prev[url], [tool]: !prev[url]?.[tool] } }));
+  };
+
+  const setAllTools = (url, value) => {
+    const sel = toolSelection[url] || {};
+    setToolSelection((prev) => ({ ...prev, [url]: Object.fromEntries(Object.keys(sel).map((t) => [t, value])) }));
+  };
+
+  const confirmAdd = (server) => {
+    const sel = toolSelection[server.url] || {};
+    const enabled = Object.keys(sel).filter((t) => sel[t]);
+    onAdd?.({
+      name: server.slug || server.name,
+      title: server.title,
+      description: server.description,
+      url: server.url,
+      transport: server.transport,
+      oauth: server.oauth,
+      toolNames: enabled,
+    });
+    setExpandedUrl(null);
+  };
+
+  return (
+    <Modal isOpen={isOpen} onClose={onClose} title="Browse MCP Marketplace" size="lg">
+      <div className="flex flex-col gap-3">
+        <div className="flex items-center gap-2">
+          <input
+            type="text"
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            placeholder="Search by name or description..."
+            className="flex-1 px-2 py-1.5 bg-surface rounded text-xs border border-border focus:outline-none focus:ring-1 focus:ring-primary/50"
+          />
+          <select
+            value={filter}
+            onChange={(e) => setFilter(e.target.value)}
+            className="px-2 py-1.5 bg-surface rounded text-xs border border-border focus:outline-none focus:ring-1 focus:ring-primary/50"
+          >
+            <option value="all">All</option>
+            <option value="authless">Authless</option>
+            <option value="oauth">OAuth</option>
+          </select>
+        </div>
+
+        {error && (
+          <div className="px-2 py-1.5 rounded text-xs bg-red-500/10 text-red-600">{error}</div>
+        )}
+
+        {loading && (
+          <div className="flex items-center gap-2 text-text-muted text-xs py-4 justify-center">
+            <span className="material-symbols-outlined animate-spin text-[18px]">progress_activity</span>
+            <span>Loading registry...</span>
+          </div>
+        )}
+
+        {!loading && (
+          <div className="flex flex-col gap-1 max-h-[60vh] overflow-y-auto">
+            {filtered.length === 0 && (
+              <div className="text-center text-xs text-text-muted py-6">No servers match filter</div>
+            )}
+            {filtered.map((s) => {
+              const added = addedSet.has(s.slug || s.name);
+              const expanded = expandedUrl === s.url;
+              const cache = toolsCache[s.url];
+              const isLoadingTools = toolsLoading[s.url];
+              const sel = toolSelection[s.url] || {};
+              const toolKeys = Object.keys(sel);
+              const selectedCount = Object.values(sel).filter(Boolean).length;
+              return (
+                <div key={s.url} className="rounded border border-transparent hover:border-border">
+                  <div className="flex items-start gap-2 px-2 py-2 hover:bg-black/5 dark:hover:bg-white/5">
+                    {s.iconUrl ? (
+                      // eslint-disable-next-line @next/next/no-img-element
+                      <img src={s.iconUrl} alt="" className="size-7 rounded shrink-0 object-contain" onError={(e) => { e.target.style.display = "none"; }} />
+                    ) : (
+                      <div className="size-7 rounded bg-surface shrink-0" />
+                    )}
+                    <div className="flex-1 min-w-0">
+                      <div className="flex items-center gap-1.5 flex-wrap">
+                        <span className="font-medium text-xs">{s.title}</span>
+                        {s.oauth ? (
+                          <span className="px-1 py-0.5 text-[9px] rounded bg-amber-500/10 text-amber-600">OAuth</span>
+                        ) : (
+                          <span className="px-1 py-0.5 text-[9px] rounded bg-green-500/10 text-green-600">Authless</span>
+                        )}
+                        {s.toolCount > 0 && (
+                          <span className="text-[10px] text-text-muted">{s.toolCount} tools</span>
+                        )}
+                      </div>
+                      {s.description && (
+                        <p className="text-[10px] text-text-muted line-clamp-2 mt-0.5">{s.description}</p>
+                      )}
+                    </div>
+                    <button
+                      onClick={() => added ? null : expandServer(s)}
+                      disabled={added}
+                      className={`shrink-0 px-2 py-1 rounded text-[10px] font-medium transition-colors ${
+                        added
+                          ? "bg-green-500/10 text-green-600 cursor-default"
+                          : expanded
+                          ? "bg-surface border border-border text-text-muted hover:bg-black/5"
+                          : "bg-primary/10 border border-primary/40 text-primary hover:bg-primary/20"
+                      }`}
+                    >
+                      {added ? "Added" : expanded ? "Cancel" : "+ Add"}
+                    </button>
+                  </div>
+                  {expanded && (
+                    <div className="px-3 py-2 bg-surface/40 border-t border-border flex flex-col gap-2">
+                      {isLoadingTools && (
+                        <div className="flex items-center gap-2 text-text-muted text-[10px] py-1">
+                          <span className="material-symbols-outlined animate-spin text-[14px]">progress_activity</span>
+                          <span>Probing server for tools...</span>
+                        </div>
+                      )}
+                      {!isLoadingTools && cache?.requiresAuth && (
+                        <p className="text-[10px] text-amber-600 bg-amber-500/10 px-2 py-1 rounded">
+                          🔐 OAuth required. Add now and authenticate after Apply; tool list will be discovered after first connect.
+                        </p>
+                      )}
+                      {!isLoadingTools && cache?.error && !cache?.requiresAuth && (
+                        <p className="text-[10px] text-red-600 bg-red-500/10 px-2 py-1 rounded">Probe failed: {cache.error}</p>
+                      )}
+                      {!isLoadingTools && toolKeys.length === 0 && !cache?.requiresAuth && !cache?.error && (
+                        <p className="text-[10px] text-text-muted">No tools advertised by server.</p>
+                      )}
+                      {!isLoadingTools && toolKeys.length > 0 && (
+                        <>
+                          <div className="flex items-center justify-between">
+                            <span className="text-[10px] text-text-muted">{selectedCount}/{toolKeys.length} tools enabled</span>
+                            <div className="flex gap-1">
+                              <button onClick={() => setAllTools(s.url, true)} className="text-[10px] text-primary hover:underline">All</button>
+                              <span className="text-[10px] text-text-muted">·</span>
+                              <button onClick={() => setAllTools(s.url, false)} className="text-[10px] text-primary hover:underline">None</button>
+                            </div>
+                          </div>
+                          <div className="grid grid-cols-2 gap-1 max-h-40 overflow-y-auto">
+                            {toolKeys.map((t) => (
+                              <label key={t} className="flex items-center gap-1.5 text-[10px] cursor-pointer hover:bg-black/5 dark:hover:bg-white/5 px-1 rounded">
+                                <input
+                                  type="checkbox"
+                                  checked={!!sel[t]}
+                                  onChange={() => toggleTool(s.url, t)}
+                                  className="size-3"
+                                />
+                                <span className="truncate">{t}</span>
+                              </label>
+                            ))}
+                          </div>
+                        </>
+                      )}
+                      <button
+                        onClick={() => confirmAdd(s)}
+                        className="self-end px-2 py-1 rounded text-[10px] font-medium bg-primary text-white hover:bg-primary/90"
+                      >
+                        ✓ Confirm Add
+                      </button>
+                    </div>
+                  )}
+                </div>
+              );
+            })}
+          </div>
+        )}
+
+        <div className="text-[10px] text-text-muted text-right">
+          {filtered.length} of {servers.length} servers
+        </div>
+      </div>
+    </Modal>
+  );
+}
diff --git a/src/shared/components/Modal.js b/src/shared/components/Modal.js
new file mode 100644
index 0000000..4b5f1f5
--- /dev/null
+++ b/src/shared/components/Modal.js
@@ -0,0 +1,146 @@
+"use client";
+
+import { useEffect } from "react";
+import { cn } from "@/shared/utils/cn";
+import Button from "./Button";
+import Tooltip from "./Tooltip";
+
+export default function Modal({
+  isOpen,
+  onClose,
+  title,
+  children,
+  footer,
+  size = "md",
+  closeOnOverlay = true,
+  showTrafficLights = true,
+  className,
+}) {
+  const sizes = {
+    sm: "max-w-sm",
+    md: "max-w-md",
+    lg: "max-w-lg",
+    xl: "max-w-xl",
+    full: "max-w-4xl",
+  };
+
+  useEffect(() => {
+    if (isOpen) {
+      document.body.style.overflow = "hidden";
+    } else {
+      document.body.style.overflow = "";
+    }
+    return () => { document.body.style.overflow = ""; };
+  }, [isOpen]);
+
+  useEffect(() => {
+    const handleEscape = (e) => {
+      if (e.key === "Escape" && isOpen) onClose();
+    };
+    document.addEventListener("keydown", handleEscape);
+    return () => document.removeEventListener("keydown", handleEscape);
+  }, [isOpen, onClose]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+      {/* Overlay */}
+      <div
+        className="absolute inset-0 bg-black/50 backdrop-blur-[2px] fade-in"
+        onClick={closeOnOverlay ? onClose : undefined}
+      />
+
+      {/* Modal content */}
+      <div
+        className={cn(
+          "relative w-full bg-surface",
+          "border border-border-subtle",
+          "rounded-[14px] shadow-[var(--shadow-elev)]",
+          "fade-in",
+          sizes[size],
+          className
+        )}
+      >
+        {/* Header */}
+        {(title || showTrafficLights) && (
+          <div className="flex items-center justify-between p-2 border-b border-border-subtle">
+            <div className="flex items-center">
+              {/* Traffic lights — desktop only */}
+              {showTrafficLights && (
+                <div className="hidden md:flex items-center gap-2 mr-4 ml-2">
+                  <Tooltip text="Close" position="top" color="#FF5F56">
+                    <button
+                      onClick={onClose}
+                      aria-label="Close"
+                      title="Close"
+                      className="w-4 h-4 rounded-full bg-[#FF5F56] hover:brightness-90 transition-all cursor-pointer flex items-center justify-center group/dot"
+                    >
+                      <span className="text-[9px] font-bold text-white opacity-0 group-hover/dot:opacity-100 transition-opacity leading-none">✕</span>
+                    </button>
+                  </Tooltip>
+                  <div className="w-4 h-4 rounded-full bg-[#3a3a3a]/20 dark:bg-white/15 cursor-not-allowed" />
+                  <div className="w-4 h-4 rounded-full bg-[#3a3a3a]/20 dark:bg-white/15 cursor-not-allowed" />
+                </div>
+              )}
+              {title && (
+                <h2 className="text-lg font-semibold text-text-main">{title}</h2>
+              )}
+            </div>
+            {/* X button — mobile only */}
+            <button
+              onClick={onClose}
+              aria-label="Close"
+              className="md:hidden p-1.5 rounded-[10px] text-text-muted hover:bg-surface-2 hover:text-text-main transition-colors"
+            >
+              <span className="material-symbols-outlined text-[20px]">close</span>
+            </button>
+          </div>
+        )}
+
+        {/* Body */}
+        <div className="p-6 max-h-[calc(85vh-100px)] overflow-y-auto custom-scrollbar">{children}</div>
+
+        {/* Footer */}
+        {footer && (
+          <div className="flex items-center justify-end gap-3 p-6 border-t border-border-subtle">
+            {footer}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export function ConfirmModal({
+  isOpen,
+  onClose,
+  onConfirm,
+  title = "Confirm",
+  message,
+  confirmText = "Confirm",
+  cancelText = "Cancel",
+  variant = "danger",
+  loading = false,
+}) {
+  return (
+    <Modal
+      isOpen={isOpen}
+      onClose={onClose}
+      title={title}
+      size="sm"
+      footer={
+        <>
+          <Button variant="ghost" onClick={onClose} disabled={loading}>
+            {cancelText}
+          </Button>
+          <Button variant={variant} onClick={onConfirm} loading={loading}>
+            {confirmText}
+          </Button>
+        </>
+      }
+    >
+      <p className="text-text-muted">{message}</p>
+    </Modal>
+  );
+}
diff --git a/src/shared/components/ModelSelectModal.js b/src/shared/components/ModelSelectModal.js
new file mode 100644
index 0000000..5708807
--- /dev/null
+++ b/src/shared/components/ModelSelectModal.js
@@ -0,0 +1,581 @@
+"use client";
+
+import { useState, useMemo, useEffect } from "react";
+import PropTypes from "prop-types";
+import Modal from "./Modal";
+import ProviderIcon from "./ProviderIcon";
+import CapacityBadges from "./CapacityBadges";
+import { useModelCaps } from "@/shared/hooks/useModelCaps";
+import { getModelsByProviderId, getModelKind } from "@/shared/constants/models";
+import { OAUTH_PROVIDERS, APIKEY_PROVIDERS, FREE_PROVIDERS, FREE_TIER_PROVIDERS, AI_PROVIDERS, isOpenAICompatibleProvider, isAnthropicCompatibleProvider, getProviderAlias } from "@/shared/constants/providers";
+
+// Provider order: OAuth first, then Free Tier, then API Key (matches dashboard/providers)
+const PROVIDER_ORDER = [
+  ...Object.keys(OAUTH_PROVIDERS),
+  ...Object.keys(FREE_PROVIDERS),
+  ...Object.keys(FREE_TIER_PROVIDERS),
+  ...Object.keys(APIKEY_PROVIDERS),
+];
+
+// Providers that need no auth — always show in model selector
+const NO_AUTH_PROVIDER_IDS = Object.keys(FREE_PROVIDERS).filter(id => FREE_PROVIDERS[id].noAuth);
+
+export default function ModelSelectModal({
+  isOpen,
+  onClose,
+  onSelect,
+  onDeselect,
+  selectedModel,
+  activeProviders = [],
+  title = "Select Model",
+  modelAliases = {},
+  kindFilter = null,
+  addedModelValues = [],
+  closeOnSelect = true,
+}) {
+  // Filter activeProviders by serviceKinds when kindFilter set (e.g. "webSearch", "webFetch")
+  const filteredActiveProviders = useMemo(() => {
+    if (!kindFilter) return activeProviders;
+    return activeProviders.filter((p) => {
+      const info = AI_PROVIDERS[p.provider];
+      const kinds = info?.serviceKinds || ["llm"];
+      return kinds.includes(kindFilter);
+    });
+  }, [activeProviders, kindFilter]);
+  const { getCaps } = useModelCaps();
+  const [searchQuery, setSearchQuery] = useState("");
+  const [combos, setCombos] = useState([]);
+  const [providerNodes, setProviderNodes] = useState([]);
+  const [customModels, setCustomModels] = useState([]);
+  const [disabledModels, setDisabledModels] = useState({});
+
+  const fetchCombos = async () => {
+    try {
+      const res = await fetch("/api/combos");
+      if (!res.ok) throw new Error(`Failed to fetch combos: ${res.status}`);
+      const data = await res.json();
+      setCombos(data.combos || []);
+    } catch (error) {
+      console.error("Error fetching combos:", error);
+      setCombos([]);
+    }
+  };
+
+  useEffect(() => {
+    if (isOpen) fetchCombos();
+  }, [isOpen]);
+
+  const fetchProviderNodes = async () => {
+    try {
+      const res = await fetch("/api/provider-nodes");
+      if (!res.ok) throw new Error(`Failed to fetch provider nodes: ${res.status}`);
+      const data = await res.json();
+      setProviderNodes(data.nodes || []);
+    } catch (error) {
+      console.error("Error fetching provider nodes:", error);
+      setProviderNodes([]);
+    }
+  };
+
+  useEffect(() => {
+    if (isOpen) fetchProviderNodes();
+  }, [isOpen]);
+
+  const fetchCustomModels = async () => {
+    try {
+      const res = await fetch("/api/models/custom");
+      if (!res.ok) throw new Error(`Failed to fetch custom models: ${res.status}`);
+      const data = await res.json();
+      setCustomModels(data.models || []);
+    } catch (error) {
+      console.error("Error fetching custom models:", error);
+      setCustomModels([]);
+    }
+  };
+
+  useEffect(() => {
+    if (isOpen) fetchCustomModels();
+  }, [isOpen]);
+
+  const fetchDisabledModels = async () => {
+    try {
+      const res = await fetch("/api/models/disabled");
+      if (!res.ok) throw new Error(`Failed to fetch disabled models: ${res.status}`);
+      const data = await res.json();
+      setDisabledModels(data.disabled || {});
+    } catch (error) {
+      console.error("Error fetching disabled models:", error);
+      setDisabledModels({});
+    }
+  };
+
+  useEffect(() => {
+    if (isOpen) fetchDisabledModels();
+  }, [isOpen]);
+
+  const allProviders = useMemo(() => ({ ...OAUTH_PROVIDERS, ...FREE_PROVIDERS, ...FREE_TIER_PROVIDERS, ...APIKEY_PROVIDERS }), []);
+
+  // Group models by provider with priority order
+  const groupedModels = useMemo(() => {
+    const groups = {};
+
+    // Kinds where the provider IS the model (no per-model selection needed)
+    const PROVIDER_AS_MODEL_KINDS = new Set(["webSearch", "webFetch"]);
+    // Kinds that map directly to model.type field
+    const TYPED_KINDS = new Set(["image", "tts", "stt", "embedding", "imageToText"]);
+    // For these kinds, providers without hardcoded models can still be picked (provider-as-model fallback)
+    const ALLOW_PROVIDER_FALLBACK_KINDS = new Set(["tts", "image", "webFetch"]);
+
+    // Filter a models[] array by kindFilter (keep only matching kind)
+    const filterByKind = (models) => {
+      // No kindFilter means the LLM selector. Keep custom models visible because
+      // user-added models may have typed capabilities (for example imageToText)
+      // while still being valid chat/combo targets.
+      if (!kindFilter) return models.filter((m) => m.isPlaceholder || m.isCustom || !getModelKind(m) || getModelKind(m) === "llm");
+      if (!TYPED_KINDS.has(kindFilter)) return models;
+      return models.filter((m) => m.isPlaceholder || getModelKind(m) === kindFilter);
+    };
+
+    // Get all active provider IDs from connections (filtered by kindFilter if set)
+    const activeConnectionIds = filteredActiveProviders.map(p => p.provider);
+
+    // No-auth providers: filter by kindFilter as well
+    const noAuthIds = kindFilter
+      ? NO_AUTH_PROVIDER_IDS.filter((id) => (AI_PROVIDERS[id]?.serviceKinds || ["llm"]).includes(kindFilter))
+      : NO_AUTH_PROVIDER_IDS;
+
+    // Only show connected providers (including both standard and custom)
+    const providerIdsToShow = new Set([
+      ...activeConnectionIds,  // Only connected providers
+      ...noAuthIds,            // No-auth providers (kind-filtered)
+    ]);
+
+    // Sort by PROVIDER_ORDER
+    const sortedProviderIds = [...providerIdsToShow].sort((a, b) => {
+      const indexA = PROVIDER_ORDER.indexOf(a);
+      const indexB = PROVIDER_ORDER.indexOf(b);
+      return (indexA === -1 ? 999 : indexA) - (indexB === -1 ? 999 : indexB);
+    });
+
+    sortedProviderIds.forEach((providerId) => {
+      const alias = getProviderAlias(providerId);
+      const providerInfo = allProviders[providerId] || { name: providerId, color: "#666" };
+      const isCustomProvider = isOpenAICompatibleProvider(providerId) || isAnthropicCompatibleProvider(providerId);
+
+      // For provider-as-model kinds (webSearch/webFetch): emit a single entry where value === providerId
+      if (kindFilter && PROVIDER_AS_MODEL_KINDS.has(kindFilter)) {
+        groups[providerId] = {
+          name: providerInfo.name,
+          alias,
+          color: providerInfo.color,
+          models: [{ id: providerId, name: providerInfo.name, value: providerId }],
+        };
+        return;
+      }
+
+      if (providerInfo.passthroughModels) {
+        const aliasModels = Object.entries(modelAliases)
+          .filter(([, fullModel]) => fullModel.startsWith(`${alias}/`))
+          .map(([aliasName, fullModel]) => ({
+            id: fullModel.replace(`${alias}/`, ""),
+            name: aliasName,
+            value: fullModel,
+          }));
+        const customRegisteredModels = customModels
+          .filter((m) => m.providerAlias === alias)
+          .map((m) => ({
+            id: m.id,
+            name: m.name || m.id,
+            value: `${alias}/${m.id}`,
+            kind: getModelKind(m),
+            isCustom: true,
+          }));
+
+        // For typed kinds, only include hardcoded typed models (aliases are typically LLM-only and lack type info)
+        let combined = aliasModels;
+        if (kindFilter && TYPED_KINDS.has(kindFilter)) {
+          const registeredTyped = customRegisteredModels.filter((m) => getModelKind(m) === kindFilter);
+          combined = [
+            ...registeredTyped,
+            ...getModelsByProviderId(providerId)
+            .filter((m) => getModelKind(m) === kindFilter)
+            .map((m) => ({ id: m.id, name: m.name, value: `${alias}/${m.id}`, kind: getModelKind(m) }))
+            .filter((m) => !registeredTyped.some((registered) => registered.value === m.value)),
+          ];
+          // Fallback: provider-as-model when no hardcoded models match (tts/image/webFetch only)
+          if (combined.length === 0 && ALLOW_PROVIDER_FALLBACK_KINDS.has(kindFilter)) {
+            const supports = (providerInfo.serviceKinds || ["llm"]).includes(kindFilter);
+            if (supports) combined = [{ id: providerId, name: providerInfo.name, value: alias }];
+          }
+        } else {
+          // LLM/null kind: merge hardcoded models (e.g. mimo-free → mimo-auto) with user-added models
+          const registeredLlms = customRegisteredModels.filter((m) => !getModelKind(m) || getModelKind(m) === "llm");
+          const seen = new Set([...aliasModels, ...registeredLlms].map((m) => m.value));
+          const hardcoded = getModelsByProviderId(providerId)
+            .filter((m) => !getModelKind(m) || getModelKind(m) === "llm")
+            .map((m) => ({ id: m.id, name: m.name, value: `${alias}/${m.id}`, kind: getModelKind(m) }))
+            .filter((m) => !seen.has(m.value));
+          combined = [...registeredLlms, ...aliasModels.filter((m) => !registeredLlms.some((registered) => registered.value === m.value)), ...hardcoded];
+        }
+
+        if (combined.length > 0) {
+          // Check for custom name from providerNodes (for compatible providers)
+          const matchedNode = providerNodes.find(node => node.id === providerId);
+          const displayName = matchedNode?.name || providerInfo.name;
+
+          groups[providerId] = {
+            name: displayName,
+            alias: alias,
+            color: providerInfo.color,
+            models: combined,
+          };
+        }
+      } else if (isCustomProvider) {
+        // Custom (openai/anthropic-compatible) providers are LLM-only — skip for typed media kinds
+        if (kindFilter && TYPED_KINDS.has(kindFilter)) return;
+        // Find connection object to get prefix synchronously without waiting for providerNodes fetch
+        const connection = activeProviders.find(p => p.provider === providerId);
+        const matchedNode = providerNodes.find(node => node.id === providerId);
+        const displayName = matchedNode?.name || connection?.name || providerInfo.name;
+        const nodePrefix = connection?.providerSpecificData?.prefix || matchedNode?.prefix || providerId;
+
+        // Aliases are stored using the raw providerId as key (e.g. "openai-compatible-chat-<uuid>/glm-4.7"),
+        // so we must filter by providerId, not by the display prefix.
+        const nodeModels = Object.entries(modelAliases)
+          .filter(([, fullModel]) => fullModel.startsWith(`${providerId}/`))
+          .map(([aliasName, fullModel]) => ({
+            id: fullModel.replace(`${providerId}/`, ""),
+            name: aliasName,
+            value: `${nodePrefix}/${fullModel.replace(`${providerId}/`, "")}`,
+          }));
+
+        // Merge custom models registered via /api/models/custom for this provider
+        // providerAlias in DB uses the raw providerId, not the display prefix
+        const registeredCustom = customModels
+          .filter((m) => m.providerAlias === providerId)
+          .map((m) => ({
+            id: m.id,
+            name: m.name || m.id,
+            value: `${nodePrefix}/${m.id}`,
+            isCustom: true,
+          }));
+        const seen = new Set(nodeModels.map((m) => m.value));
+        const mergedModels = [...nodeModels, ...registeredCustom.filter((m) => !seen.has(m.value))];
+
+        // Always show compatible providers that are connected, even with no aliases.
+        // When no aliases exist, show a placeholder so users know it's available.
+        const modelsToShow = mergedModels.length > 0 ? mergedModels : [{
+          id: `__placeholder__${providerId}`,
+          name: `${nodePrefix}/model-id`,
+          value: `${nodePrefix}/model-id`,
+          isPlaceholder: true,
+        }];
+
+        groups[providerId] = {
+          name: displayName,
+          alias: nodePrefix,
+          color: providerInfo.color,
+          models: modelsToShow,
+          isCustom: true,
+          hasModels: mergedModels.length > 0,
+        };
+      } else {
+        const hardcodedModels = getModelsByProviderId(providerId);
+        const hardcodedIds = new Set(hardcodedModels.map((m) => m.id));
+
+        // Custom models: if no hardcoded models (e.g. openrouter), show all aliases for this provider
+        // Otherwise only show aliases where aliasName === modelId ("Add Model" button pattern)
+        const hasHardcoded = hardcodedModels.length > 0;
+        const customAliasModels = Object.entries(modelAliases)
+          .filter(([aliasName, fullModel]) =>
+            fullModel.startsWith(`${alias}/`) &&
+            (hasHardcoded ? aliasName === fullModel.replace(`${alias}/`, "") : true) &&
+            !hardcodedIds.has(fullModel.replace(`${alias}/`, ""))
+          )
+          .map(([aliasName, fullModel]) => {
+            const modelId = fullModel.replace(`${alias}/`, "");
+            return { id: modelId, name: aliasName, value: fullModel, isCustom: true };
+          });
+
+        // Custom models registered via /api/models/custom (provider "Add Model" button)
+        const customAliasIds = new Set(customAliasModels.map((m) => m.id));
+        const customRegisteredModels = customModels
+          .filter((m) => m.providerAlias === alias && !hardcodedIds.has(m.id) && !customAliasIds.has(m.id))
+          .map((m) => ({ id: m.id, name: m.name || m.id, value: `${alias}/${m.id}`, isCustom: true }));
+
+        const merged = [
+          ...hardcodedModels.map((m) => ({ id: m.id, name: m.name, value: `${alias}/${m.id}`, kind: getModelKind(m) })),
+          ...customAliasModels,
+          ...customRegisteredModels,
+        ];
+        // Dedupe by value (alias may equal hardcoded id, causing React key collision)
+        const seen = new Set();
+        let allModels = filterByKind(merged.filter((m) => {
+          if (seen.has(m.value)) return false;
+          seen.add(m.value);
+          return true;
+        }));
+
+        // Provider-as-model fallback: providers that support the kind but have no hardcoded models
+        // can still be picked (value = providerAlias). Skips embedding (always needs model).
+        if (allModels.length === 0 && kindFilter && ALLOW_PROVIDER_FALLBACK_KINDS.has(kindFilter)) {
+          const supports = (providerInfo.serviceKinds || ["llm"]).includes(kindFilter);
+          if (supports) {
+            allModels = [{ id: providerId, name: providerInfo.name, value: alias }];
+          }
+        }
+
+        if (allModels.length > 0) {
+          groups[providerId] = {
+            name: providerInfo.name,
+            alias: alias,
+            color: providerInfo.color,
+            models: allModels,
+          };
+        }
+      }
+    });
+
+    // Filter out disabled models per provider (disabled keyed by storage alias OR providerId)
+    Object.entries(groups).forEach(([providerId, group]) => {
+      const aliasKey = getProviderAlias(providerId);
+      const disabledIds = new Set([
+        ...(disabledModels[aliasKey] || []),
+        ...(disabledModels[providerId] || []),
+      ]);
+      if (disabledIds.size === 0) return;
+      group.models = group.models.filter((m) => !disabledIds.has(m.id));
+      if (group.models.length === 0) delete groups[providerId];
+    });
+
+    return groups;
+  }, [filteredActiveProviders, modelAliases, allProviders, providerNodes, customModels, disabledModels, kindFilter, activeProviders]);
+
+  // Filter combos by search query (and hide combos when kindFilter is set — combos are LLM-only by design)
+  const filteredCombos = useMemo(() => {
+    if (kindFilter) return [];
+    if (!searchQuery.trim()) return combos;
+    const query = searchQuery.toLowerCase();
+    return combos.filter(c => c.name.toLowerCase().includes(query));
+  }, [combos, searchQuery, kindFilter]);
+
+  // Sort models alphabetically, with added models floated to top
+  const sortModels = (models) => {
+    const added = models.filter(m => addedModelValues.includes(m.value)).sort((a, b) => a.name.localeCompare(b.name));
+    const rest = models.filter(m => !addedModelValues.includes(m.value)).sort((a, b) => a.name.localeCompare(b.name));
+    return [...added, ...rest];
+  };
+
+  // Filter models by search query
+  const filteredGroups = useMemo(() => {
+    const query = searchQuery.trim().toLowerCase();
+
+    const filtered = {};
+    Object.entries(groupedModels).forEach(([providerId, group]) => {
+      let models = group.models;
+      if (query) {
+        const providerNameMatches = group.name.toLowerCase().includes(query);
+        models = models.filter(
+          (m) =>
+            m.name.toLowerCase().includes(query) ||
+            m.id.toLowerCase().includes(query)
+        );
+        if (models.length === 0 && !providerNameMatches) return;
+      }
+      filtered[providerId] = {
+        ...group,
+        models: sortModels(models),
+      };
+    });
+
+    return filtered;
+  }, [groupedModels, searchQuery, addedModelValues]);
+
+  const handleSelect = (model) => {
+    const value = model?.value || model?.name || model;
+    const isAdded = addedModelValues.includes(value);
+
+    if (isAdded && onDeselect) {
+      onDeselect(model);
+    } else {
+      onSelect(model);
+    }
+
+    if (closeOnSelect) {
+      onClose();
+      setSearchQuery("");
+    }
+  };
+
+  return (
+    <Modal
+      isOpen={isOpen}
+      onClose={() => {
+        onClose();
+        setSearchQuery("");
+      }}
+      title={title}
+      size="md"
+      className="p-4!"
+      footer={null}
+    >
+      {/* Info bar */}
+      <div className="flex items-center gap-2 mb-3 px-2.5 py-2 bg-primary/8 border border-primary/20 rounded-lg text-xs text-text-muted">
+        <span className="material-symbols-outlined text-primary shrink-0" style={{ fontSize: "14px" }}>info</span>
+        <span>Click to add, click again to remove. Changes are saved automatically.</span>
+      </div>
+
+      {/* Search - compact */}
+      <div className="mb-3">
+        <div className="relative">
+          <span className="material-symbols-outlined absolute left-2.5 top-1/2 -translate-y-1/2 text-text-muted text-[16px]">
+            search
+          </span>
+          <input
+            type="text"
+            placeholder="Search..."
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
+            className="w-full pl-8 pr-3 py-1.5 bg-surface border border-border rounded text-xs focus:outline-none focus:ring-1 focus:ring-primary/50"
+          />
+        </div>
+      </div>
+
+      {/* Models grouped by provider - compact */}
+      <div className="max-h-[400px] overflow-y-auto space-y-3">
+        {/* Combos section - always first */}
+        {filteredCombos.length > 0 && (
+          <div>
+            <div className="flex items-center gap-1.5 mb-1.5 sticky top-0 bg-surface py-0.5">
+              <span className="material-symbols-outlined text-primary text-[14px]">layers</span>
+              <span className="text-xs font-medium text-primary">Combos</span>
+              <span className="text-[10px] text-text-muted">({filteredCombos.length})</span>
+            </div>
+            <div className="flex flex-wrap gap-1.5">
+              {filteredCombos.map((combo) => {
+                const isSelected = selectedModel === combo.name;
+                return (
+                  <button
+                    key={combo.id}
+                    onClick={() => handleSelect({ id: combo.name, name: combo.name, value: combo.name })}
+                    className={`
+                      px-2 py-1 rounded-xl text-xs font-medium transition-all border hover:cursor-pointer flex items-center gap-1
+                      ${isSelected
+                        ? "bg-primary text-white border-primary"
+                        : addedModelValues.includes(combo.name)
+                          ? "bg-primary border-primary text-white hover:bg-primary-hover"
+                          : "bg-surface border-border text-text-main hover:border-primary/50 hover:bg-primary/5"
+                      }
+                    `}
+                  >
+                    {addedModelValues.includes(combo.name) && (
+                      <span className="material-symbols-outlined leading-none" style={{ fontSize: "10px" }}>check</span>
+                    )}
+                    {combo.name}
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Provider models */}
+        {Object.entries(filteredGroups).map(([providerId, group]) => (
+          <div key={providerId}>
+            {/* Provider header */}
+            <div className="flex items-center gap-1.5 mb-1.5 sticky top-0 bg-surface py-0.5">
+              <ProviderIcon
+                src={`/providers/${providerId}.png`}
+                alt={group.name}
+                size={14}
+                fallbackText={(group.name || providerId).slice(0, 2).toUpperCase()}
+                fallbackColor={group.color}
+              />
+              <span className="text-xs font-medium text-primary">
+                {group.name}
+              </span>
+              <span className="text-[10px] text-text-muted">
+                ({group.models.length})
+              </span>
+            </div>
+
+            <div className="flex flex-wrap gap-1.5">
+              {group.models.map((model) => {
+                const isSelected = selectedModel === model.value;
+                const isPlaceholder = model.isPlaceholder;
+                return (
+                  <button
+                    key={model.value}
+                    onClick={() => handleSelect(model)}
+                    title={isPlaceholder ? "Select to pre-fill, then edit model ID in the input" : undefined}
+                    className={`
+                      px-2 py-1 rounded-xl text-xs font-medium transition-all border hover:cursor-pointer
+                      ${isPlaceholder
+                        ? "border-dashed border-border text-text-muted hover:border-primary/50 hover:text-primary bg-surface italic"
+                        : isSelected
+                          ? "bg-primary text-white border-primary"
+                          : addedModelValues.includes(model.value)
+                            ? "bg-primary border-primary text-white hover:bg-primary-hover"
+                            : "bg-surface border-border text-text-main hover:border-primary/50 hover:bg-primary/5"
+                      }
+                    `}
+                  >
+                    <span className="flex items-center gap-1">
+                      {addedModelValues.includes(model.value) && !isPlaceholder && (
+                        <span className="material-symbols-outlined leading-none" style={{ fontSize: "10px" }}>check</span>
+                      )}
+                      {isPlaceholder ? (
+                        <>
+                          <span className="material-symbols-outlined text-[11px]">edit</span>
+                          {model.name}
+                        </>
+                      ) : model.isCustom ? (
+                        <>
+                          {model.name}
+                          <span className="text-[9px] opacity-60 font-normal">custom</span>
+                          <CapacityBadges caps={getCaps(model.value)} />
+                        </>
+                      ) : (
+                        <>
+                          {model.name}
+                          <CapacityBadges caps={getCaps(model.value)} />
+                        </>
+                      )}
+                    </span>
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        ))}
+
+        {Object.keys(filteredGroups).length === 0 && filteredCombos.length === 0 && (
+          <div className="text-center py-4 text-text-muted">
+            <span className="material-symbols-outlined text-2xl mb-1 block">
+              search_off
+            </span>
+            <p className="text-xs">No models found</p>
+          </div>
+        )}
+      </div>
+    </Modal>
+  );
+}
+
+ModelSelectModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  onClose: PropTypes.func.isRequired,
+  onSelect: PropTypes.func.isRequired,
+  onDeselect: PropTypes.func,
+  selectedModel: PropTypes.string,
+  activeProviders: PropTypes.arrayOf(
+    PropTypes.shape({
+      provider: PropTypes.string.isRequired,
+    })
+  ),
+  title: PropTypes.string,
+  modelAliases: PropTypes.object,
+  kindFilter: PropTypes.string,
+  addedModelValues: PropTypes.arrayOf(PropTypes.string),
+  closeOnSelect: PropTypes.bool,
+};
diff --git a/src/shared/components/NineRemoteButton.js b/src/shared/components/NineRemoteButton.js
new file mode 100644
index 0000000..c71ed8e
--- /dev/null
+++ b/src/shared/components/NineRemoteButton.js
@@ -0,0 +1,23 @@
+"use client";
+
+import { useState } from "react";
+import NineRemotePromoModal from "./NineRemotePromoModal";
+
+export default function NineRemoteButton() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button
+        onClick={() => setIsOpen(true)}
+        className="relative flex items-center gap-1.5 px-2.5 py-1.5 rounded-lg transition-all text-text-muted hover:text-text-main hover:bg-black/5 dark:hover:bg-white/5"
+        title="9Remote"
+      >
+        <span className="material-symbols-outlined text-[18px]">computer</span>
+        <span className="text-xs font-medium">Remote</span>
+      </button>
+
+      <NineRemotePromoModal isOpen={isOpen} onClose={() => setIsOpen(false)} />
+    </>
+  );
+}
diff --git a/src/shared/components/NineRemotePromoModal.js b/src/shared/components/NineRemotePromoModal.js
new file mode 100644
index 0000000..27baf79
--- /dev/null
+++ b/src/shared/components/NineRemotePromoModal.js
@@ -0,0 +1,99 @@
+"use client";
+
+import { useEffect } from "react";
+import { createPortal } from "react-dom";
+
+const FEATURES = [
+  { icon: "terminal", label: "Terminal", desc: "Full shell access" },
+  { icon: "cast", label: "Desktop", desc: "Screen sharing" },
+  { icon: "folder_open", label: "Files", desc: "Browse & edit files" },
+];
+
+const BULLETS = [
+  { icon: "qr_code_scanner", text: "Scan QR to connect instantly" },
+  { icon: "wifi_off", text: "No port forwarding needed" },
+  { icon: "devices", text: "Works on any device" },
+];
+
+const NINE_REMOTE_URL = "https://9remote.cc";
+
+export default function NineRemotePromoModal({ isOpen, onClose }) {
+  useEffect(() => {
+    if (!isOpen) return;
+    document.body.style.overflow = "hidden";
+    const onEsc = (e) => { if (e.key === "Escape") onClose(); };
+    document.addEventListener("keydown", onEsc);
+    return () => { document.body.style.overflow = ""; document.removeEventListener("keydown", onEsc); };
+  }, [isOpen, onClose]);
+
+  if (!isOpen) return null;
+
+  return createPortal(
+    <div className="fixed inset-0 z-[9999] flex items-center justify-center p-4">
+      <div className="absolute inset-0 bg-black/50 backdrop-blur-[2px] fade-in" onClick={onClose} />
+
+      <div className="relative w-full max-w-sm rounded-[14px] overflow-hidden shadow-[var(--shadow-elev)] fade-in flex flex-col bg-surface border border-border-subtle">
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 py-3 border-b border-border-subtle">
+          <div className="flex items-center gap-3">
+            <div className="w-7 h-7 rounded-[8px] flex items-center justify-center bg-primary">
+              <span className="material-symbols-outlined text-white text-base">terminal</span>
+            </div>
+            <span className="text-xs font-bold uppercase tracking-wider text-primary font-mono">9Remote</span>
+          </div>
+          <button
+            onClick={onClose}
+            className="p-1.5 rounded-[10px] text-text-muted hover:bg-surface-2 hover:text-text-main transition-colors"
+          >
+            <span className="material-symbols-outlined text-base">close</span>
+          </button>
+        </div>
+
+        {/* Body */}
+        <div className="px-7 py-7 pb-9 flex flex-col gap-6">
+          {/* Hero */}
+          <div className="flex flex-col items-center gap-2 text-center mt-2">
+            <div className="w-14 h-14 rounded-[14px] flex items-center justify-center mb-1 bg-primary shadow-[var(--shadow-warm)]">
+              <span className="material-symbols-outlined text-white text-[30px]">terminal</span>
+            </div>
+            <h1 className="text-lg font-bold text-text-main tracking-tight">9Remote</h1>
+            <p className="text-xs text-text-muted leading-5 max-w-[220px]">
+              Access your terminal, desktop &amp; files from anywhere
+            </p>
+          </div>
+
+          {/* Feature cards */}
+          <div className="flex gap-2 w-full">
+            {FEATURES.map(({ icon, label, desc }) => (
+              <div key={label} className="flex-1 flex flex-col items-center gap-1.5 py-4 px-1 rounded-[10px] border border-border-subtle bg-surface-2">
+                <span className="material-symbols-outlined text-primary text-[22px]">{icon}</span>
+                <p className="text-xs font-semibold text-text-main">{label}</p>
+                <p className="text-[10px] text-text-muted text-center leading-4">{desc}</p>
+              </div>
+            ))}
+          </div>
+
+          {/* Bullets */}
+          <div className="flex flex-col gap-3 w-full">
+            {BULLETS.map(({ icon, text }) => (
+              <div key={icon} className="flex items-center gap-2.5">
+                <span className="material-symbols-outlined flex-shrink-0 text-primary text-[16px]">{icon}</span>
+                <span className="text-xs text-text-muted">{text}</span>
+              </div>
+            ))}
+          </div>
+
+          {/* CTA */}
+          <button
+            onClick={() => window.open(NINE_REMOTE_URL, "_blank")}
+            className="w-full py-3 flex items-center justify-center gap-2 text-sm font-semibold text-white rounded-[10px] bg-primary hover:bg-primary-hover shadow-[var(--shadow-warm)] active:scale-[0.98] transition-all"
+          >
+            <span className="material-symbols-outlined text-base">open_in_new</span>
+            Get 9Remote
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+}
diff --git a/src/shared/components/NoAuthProxyCard.js b/src/shared/components/NoAuthProxyCard.js
new file mode 100644
index 0000000..6229e60
--- /dev/null
+++ b/src/shared/components/NoAuthProxyCard.js
@@ -0,0 +1,134 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import PropTypes from "prop-types";
+import Card from "./Card";
+import Select from "./Select";
+import Badge from "./Badge";
+
+const NONE_PROXY_POOL_VALUE = "__none__";
+const STRATEGIES = [
+  { value: "none", label: "None (single pool)" },
+  { value: "round-robin", label: "Round-robin" },
+  { value: "random", label: "Random" },
+];
+
+export default function NoAuthProxyCard({ providerId }) {
+  const [proxyPools, setProxyPools] = useState([]);
+  const [proxyPoolId, setProxyPoolId] = useState(NONE_PROXY_POOL_VALUE);
+  const [rotateStrategy, setRotateStrategy] = useState("none");
+  const [saving, setSaving] = useState(false);
+  const [savedFlash, setSavedFlash] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    Promise.all([
+      fetch("/api/proxy-pools?isActive=true", { cache: "no-store" }).then((r) => r.ok ? r.json() : { proxyPools: [] }),
+      fetch("/api/settings", { cache: "no-store" }).then((r) => r.ok ? r.json() : {}),
+    ]).then(([poolData, settingsData]) => {
+      if (cancelled) return;
+      setProxyPools(poolData.proxyPools || []);
+      const override = (settingsData.providerStrategies || {})[providerId] || {};
+      setProxyPoolId(override.proxyPoolId || NONE_PROXY_POOL_VALUE);
+      setRotateStrategy(override.rotateStrategy || "none");
+    }).catch(() => {});
+    return () => { cancelled = true; };
+  }, [providerId]);
+
+  const save = useCallback(async (poolId, strategy) => {
+    setSaving(true);
+    try {
+      const res = await fetch("/api/settings", { cache: "no-store" });
+      const data = res.ok ? await res.json() : {};
+      const current = data.providerStrategies || {};
+      const override = { ...(current[providerId] || {}) };
+      if (poolId === NONE_PROXY_POOL_VALUE) delete override.proxyPoolId;
+      else override.proxyPoolId = poolId;
+      if (strategy === "none") delete override.rotateStrategy;
+      else override.rotateStrategy = strategy;
+      const updated = { ...current };
+      if (Object.keys(override).length === 0) delete updated[providerId];
+      else updated[providerId] = override;
+      await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ providerStrategies: updated }),
+      });
+      setSavedFlash(true);
+      setTimeout(() => setSavedFlash(false), 1500);
+    } catch (e) {
+      console.log("Save proxy config error:", e);
+    } finally {
+      setSaving(false);
+    }
+  }, [providerId]);
+
+  const handlePoolChange = (newPoolId) => {
+    setProxyPoolId(newPoolId);
+    save(newPoolId, rotateStrategy);
+  };
+
+  const handleStrategyChange = (newStrategy) => {
+    setRotateStrategy(newStrategy);
+    save(proxyPoolId, newStrategy);
+  };
+
+  const canRotate = proxyPools.length >= 2;
+  const isRotation = rotateStrategy !== "none";
+
+  return (
+    <Card>
+      <div className="flex items-center gap-3 mb-4">
+        <div className="inline-flex items-center justify-center w-10 h-10 rounded-full bg-green-500/10 text-green-500">
+          <span className="material-symbols-outlined text-[20px]">lock_open</span>
+        </div>
+        <div className="flex-1">
+          <p className="text-sm font-medium">No authentication required</p>
+          <p className="text-xs text-text-muted">This provider is ready to use. Optionally route requests through a proxy pool to bypass IP-based limits.</p>
+        </div>
+        {savedFlash && <Badge variant="success" size="sm">Saved</Badge>}
+      </div>
+
+      <Select
+        label="Proxy Pool"
+        value={proxyPoolId}
+        onChange={(e) => handlePoolChange(e.target.value)}
+        disabled={saving || isRotation}
+        options={[
+          { value: NONE_PROXY_POOL_VALUE, label: "None (direct)" },
+          ...proxyPools.map((pool) => ({ value: pool.id, label: pool.name })),
+        ]}
+        hint={isRotation ? "Pool selector is ignored when rotation is active — all active pools are used." : undefined}
+      />
+
+      <div className="flex flex-col gap-2 mt-4">
+        <label className="text-sm font-medium text-text-main">Rotation Strategy</label>
+        <select
+          value={rotateStrategy}
+          onChange={(e) => handleStrategyChange(e.target.value)}
+          disabled={saving}
+          className="py-2 px-3 text-sm text-text-main bg-white dark:bg-white/5 border border-black/10 dark:border-white/10 rounded-md focus:ring-1 focus:ring-primary/30 focus:border-primary/50 focus:outline-none transition-all disabled:opacity-50"
+        >
+          {STRATEGIES.map((s) => (
+            <option key={s.value} value={s.value} disabled={s.value !== "none" && !canRotate}>
+              {s.label}
+            </option>
+          ))}
+        </select>
+        <p className="text-xs text-text-muted">
+          {!canRotate
+            ? `Need at least 2 active proxy pools for rotation.`
+            : isRotation
+              ? rotateStrategy === "round-robin"
+                ? `Rotating through all ${proxyPools.length} active pools in order. State is in-memory (resets on restart).`
+                : `Picking a random pool from ${proxyPools.length} active pools each request.`
+              : `Uses the selected pool above. Set to Round-robin or Random to rotate across all active pools.`}
+        </p>
+      </div>
+    </Card>
+  );
+}
+
+NoAuthProxyCard.propTypes = {
+  providerId: PropTypes.string.isRequired,
+};
diff --git a/src/shared/components/OAuthModal.js b/src/shared/components/OAuthModal.js
new file mode 100644
index 0000000..6d7b2bb
--- /dev/null
+++ b/src/shared/components/OAuthModal.js
@@ -0,0 +1,724 @@
+"use client";
+
+import { useState, useEffect, useRef, useCallback } from "react";
+import PropTypes from "prop-types";
+import { Modal, Button, Input } from "@/shared/components";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+
+/**
+ * OAuth Modal Component
+ * - Localhost: Auto callback via popup message
+ * - Remote: Manual paste callback URL
+ */
+export default function OAuthModal({ isOpen, provider, providerInfo, onSuccess, onClose, oauthMeta, idcConfig }) {
+  const [step, setStep] = useState("waiting"); // waiting | input | success | error
+  const [authData, setAuthData] = useState(null);
+  const [callbackUrl, setCallbackUrl] = useState("");
+  const [error, setError] = useState(null);
+  const [isDeviceCode, setIsDeviceCode] = useState(false);
+  const [deviceData, setDeviceData] = useState(null);
+  const [polling, setPolling] = useState(false);
+  const popupRef = useRef(null);
+  const pollingAbortRef = useRef(false);
+  const openedRef = useRef(false);
+  const { copied, copy } = useCopyToClipboard();
+
+  // State for client-only values to avoid hydration mismatch
+  const [isLocalhost, setIsLocalhost] = useState(false);
+  const [placeholderUrl, setPlaceholderUrl] = useState("/callback?code=...");
+  const callbackProcessedRef = useRef(false);
+
+  // Detect if running on localhost (client-side only)
+  useEffect(() => {
+    if (typeof window !== "undefined") {
+      setIsLocalhost(
+        window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1"
+      );
+      setPlaceholderUrl(`${window.location.origin}/callback?code=...`);
+    }
+  }, []);
+
+  // Define all useCallback hooks BEFORE the useEffects that reference them
+
+  // Exchange tokens
+  const exchangeTokens = useCallback(async (code, state) => {
+    if (!authData) return;
+    try {
+      const res = await fetch(`/api/oauth/${provider}/exchange`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          code,
+          redirectUri: authData.redirectUri,
+          codeVerifier: authData.codeVerifier,
+          state,
+          ...(oauthMeta ? { meta: oauthMeta } : {}),
+        }),
+      });
+
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error);
+
+      setStep("success");
+      onSuccess?.();
+    } catch (err) {
+      setError(err.message);
+      setStep("error");
+    }
+  }, [authData, provider, onSuccess, oauthMeta]);
+
+  const completeXaiManualCode = useCallback(async (code) => {
+    if (!authData?.state) return;
+    try {
+      const res = await fetch("/api/oauth/xai/manual-code", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ code, state: authData.state }),
+      });
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error);
+
+      setStep("success");
+      onSuccess?.();
+    } catch (err) {
+      setError(err.message);
+      setStep("error");
+    }
+  }, [authData, onSuccess]);
+
+  // Poll for device code token
+  const startPolling = useCallback(async (deviceCode, codeVerifier, interval, extraData, deadlineMs) => {
+    pollingAbortRef.current = false;
+    setPolling(true);
+    // Honor the upstream's expires_in when supplied (qoder sets 300s) so we
+    // don't time out earlier than the device code itself. Default 120s
+    // matches the prior behavior for providers that don't surface a value.
+    const startedAt = Date.now();
+    const deadline = startedAt + (Number.isFinite(deadlineMs) && deadlineMs > 0 ? deadlineMs : 120_000);
+
+    while (Date.now() < deadline) {
+      // Check if polling should be aborted
+      if (pollingAbortRef.current) {
+        console.log("[OAuthModal] Polling aborted");
+        setPolling(false);
+        return;
+      }
+
+      await new Promise((r) => setTimeout(r, interval * 1000));
+
+      // Check again after sleep
+      if (pollingAbortRef.current) {
+        console.log("[OAuthModal] Polling aborted after sleep");
+        setPolling(false);
+        return;
+      }
+
+      try {
+        const res = await fetch(`/api/oauth/${provider}/poll`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ deviceCode, codeVerifier, extraData }),
+        });
+
+        const data = await res.json();
+
+        if (data.success) {
+          pollingAbortRef.current = true; // Stop polling immediately
+          setStep("success");
+          setPolling(false);
+          onSuccess?.();
+          return;
+        }
+
+        if (data.error === "expired_token" || data.error === "access_denied") {
+          throw new Error(data.errorDescription || data.error);
+        }
+
+        if (data.error === "slow_down") {
+          interval = Math.min(interval + 5, 30);
+        }
+      } catch (err) {
+        setError(err.message);
+        setStep("error");
+        setPolling(false);
+        return;
+      }
+    }
+
+    setError("Authorization timeout");
+    setStep("error");
+    setPolling(false);
+  }, [provider, onSuccess]);
+
+  // Start OAuth flow
+  const startOAuthFlow = useCallback(async () => {
+    if (!provider) return;
+    try {
+      setError(null);
+
+      // Device code flow providers (must match oauth providers with flowType: "device_code")
+      const deviceCodeProviders = [
+        "github",
+        "qwen",
+        "kiro",
+        "kimi-coding",
+        "kilocode",
+        "codebuddy-cn",
+        "qoder",
+        "grok-cli",
+      ];
+      if (deviceCodeProviders.includes(provider)) {
+        setIsDeviceCode(true);
+        setStep("waiting");
+
+        const deviceCodeUrl = new URL(`/api/oauth/${provider}/device-code`, window.location.origin);
+        if (provider === "kiro" && idcConfig?.startUrl) {
+          deviceCodeUrl.searchParams.set("start_url", idcConfig.startUrl);
+          if (idcConfig.region) {
+            deviceCodeUrl.searchParams.set("region", idcConfig.region);
+          }
+          deviceCodeUrl.searchParams.set("auth_method", "idc");
+        }
+        const res = await fetch(deviceCodeUrl.toString());
+        const data = await res.json();
+        if (!res.ok) throw new Error(data.error);
+
+        setDeviceData(data);
+
+        // Auto-open verification URL in new tab
+        const verifyUrl = data.verification_uri_complete || data.verification_uri;
+        if (verifyUrl) window.open(verifyUrl, "_blank", "noopener,noreferrer");
+
+        // Pass extraData for Kiro (contains _clientId, _clientSecret) and
+        // Qoder (contains _qoderMachineId / _qoderNonce — needed so mapTokens
+        // can persist the machine id alongside the token).
+        const extraData = provider === "kiro"
+          ? {
+              _clientId: data._clientId,
+              _clientSecret: data._clientSecret,
+              _region: data._region,
+              _authMethod: data._authMethod,
+              _startUrl: data._startUrl,
+            }
+          : provider === "qoder"
+          ? {
+              _qoderNonce: data._qoderNonce,
+              _qoderMachineId: data._qoderMachineId,
+              _qoderVerifier: data.codeVerifier,
+            }
+          : null;
+        startPolling(
+          data.device_code,
+          data.codeVerifier,
+          data.interval || 5,
+          extraData,
+          // Use the upstream's expires_in if present so we don't time out
+          // before the device code itself (qoder gives 300s).
+          Number.isFinite(data.expires_in) && data.expires_in > 0
+            ? data.expires_in * 1000
+            : undefined,
+        );
+        return;
+      }
+
+      // Authorization code flow - build redirect URI (some providers require fixed ports)
+      const appPort = window.location.port || (window.location.protocol === "https:" ? "443" : "80");
+      let redirectUri;
+      if (provider === "codex") {
+        redirectUri = "http://localhost:1455/auth/callback";
+      } else if (provider === "xai") {
+        redirectUri = "http://127.0.0.1:56121/callback";
+      } else {
+        redirectUri = `http://localhost:${appPort}/callback`;
+      }
+
+      // Build authorize URL first to get codeVerifier/state for codex server-side mode
+      const authorizeUrl = new URL(`/api/oauth/${provider}/authorize`, window.location.origin);
+      authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+      if (oauthMeta) {
+        Object.entries(oauthMeta).forEach(([k, v]) => { if (v) authorizeUrl.searchParams.set(k, v); });
+      }
+      const res = await fetch(authorizeUrl.toString());
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error);
+
+      // Codex: start proxy with server-side session (auto-exchange) + fallback to channels
+      let codexProxyActive = false;
+      let codexServerSide = false;
+      if (provider === "codex") {
+        try {
+          const proxyUrl = new URL(`/api/oauth/codex/start-proxy`, window.location.origin);
+          proxyUrl.searchParams.set("app_port", appPort);
+          proxyUrl.searchParams.set("state", data.state);
+          proxyUrl.searchParams.set("code_verifier", data.codeVerifier);
+          proxyUrl.searchParams.set("redirect_uri", redirectUri);
+          const proxyRes = await fetch(proxyUrl.toString());
+          const proxyData = await proxyRes.json();
+          codexProxyActive = proxyData.success;
+          codexServerSide = !!proxyData.serverSide;
+        } catch {
+          codexProxyActive = false;
+        }
+      }
+
+      // xAI: same fixed-port server-side proxy pattern as codex (port 56121)
+      let xaiProxyActive = false;
+      let xaiServerSide = false;
+      if (provider === "xai") {
+        try {
+          const proxyUrl = new URL(`/api/oauth/xai/start-proxy`, window.location.origin);
+          proxyUrl.searchParams.set("app_port", appPort);
+          proxyUrl.searchParams.set("state", data.state);
+          proxyUrl.searchParams.set("code_verifier", data.codeVerifier);
+          proxyUrl.searchParams.set("redirect_uri", redirectUri);
+          const proxyRes = await fetch(proxyUrl.toString());
+          const proxyData = await proxyRes.json();
+          xaiProxyActive = proxyData.success;
+          xaiServerSide = !!proxyData.serverSide;
+          if (!xaiProxyActive && proxyData.reason === "port_busy") {
+            throw new Error("Port 56121 in use; close the conflicting process and retry");
+          }
+        } catch (e) {
+          if (e?.message) throw e;
+          xaiProxyActive = false;
+        }
+      }
+
+      setAuthData({ ...data, redirectUri, codexServerSide, xaiServerSide });
+
+      // Guard: device_code providers return authUrl:null from /authorize. Never window.open(null)
+      // (browsers coerce it to the relative path ".../null").
+      if (!data.authUrl) {
+        if (data.flowType === "device_code") {
+          throw new Error(
+            `Provider ${provider} uses device-code login but is not wired in the OAuth modal device-code list`
+          );
+        }
+        throw new Error("No authorization URL returned from OAuth provider");
+      }
+
+      if (provider === "codex" && codexProxyActive) {
+        // Proxy active: callback will be handled server-side (auto-exchange) or via channels (fallback)
+        setStep("waiting");
+        popupRef.current = window.open(data.authUrl, "oauth_popup", "width=600,height=700");
+        if (!popupRef.current) {
+          setStep("input");
+        }
+      } else if (provider === "xai" && xaiProxyActive) {
+        setStep("waiting");
+        popupRef.current = window.open(data.authUrl, "oauth_popup", "width=600,height=700");
+        if (!popupRef.current) {
+          setStep("input");
+        }
+      } else if (!isLocalhost || provider === "codex" || provider === "xai") {
+        // Non-localhost or proxy failed: manual input mode
+        setStep("input");
+        window.open(data.authUrl, "_blank");
+      } else {
+        // Localhost (non-Codex/xAI): Open popup and wait for message
+        setStep("waiting");
+        popupRef.current = window.open(data.authUrl, "oauth_popup", "width=600,height=700");
+        if (!popupRef.current) {
+          setStep("input");
+        }
+      }
+    } catch (err) {
+      setError(err.message);
+      setStep("error");
+    }
+  }, [provider, isLocalhost, startPolling, oauthMeta, idcConfig]);
+
+  // Reset state and start OAuth when modal opens
+  useEffect(() => {
+    if (isOpen && provider) {
+      // Guard against StrictMode/effect re-runs auto-opening multiple tabs.
+      if (openedRef.current) return;
+      openedRef.current = true;
+      setAuthData(null);
+      setCallbackUrl("");
+      setError(null);
+      setIsDeviceCode(false);
+      setDeviceData(null);
+      setPolling(false);
+      pollingAbortRef.current = false;
+      startOAuthFlow();
+    } else if (!isOpen) {
+      // Abort polling and cleanup proxy when modal closes
+      pollingAbortRef.current = true;
+      openedRef.current = false;
+      if (provider === "codex") {
+        fetch("/api/oauth/codex/stop-proxy").catch(() => {});
+      } else if (provider === "xai") {
+        fetch("/api/oauth/xai/stop-proxy").catch(() => {});
+      }
+    }
+  }, [isOpen, provider, startOAuthFlow]);
+
+  // Fixed-port server-side mode: poll status (proxy auto-exchanges + saves DB)
+  useEffect(() => {
+    const pollProvider = authData?.codexServerSide ? "codex" : authData?.xaiServerSide ? "xai" : null;
+    if (!pollProvider || !authData?.state) return;
+    if (callbackProcessedRef.current) return;
+    let cancelled = false;
+    const POLL_INTERVAL_MS = 1500;
+    const MAX_ATTEMPTS = 200; // ~5 minutes
+    let attempts = 0;
+
+    const tick = async () => {
+      if (cancelled || callbackProcessedRef.current) return;
+      attempts += 1;
+      try {
+          const res = await fetch(`/api/oauth/${pollProvider}/poll-status?state=${encodeURIComponent(authData.state)}`);
+        const data = await res.json();
+        if (cancelled || callbackProcessedRef.current) return;
+        if (data.status === "done") {
+          callbackProcessedRef.current = true;
+          setStep("success");
+          onSuccess?.();
+          return;
+        }
+        if (data.status === "error") {
+          callbackProcessedRef.current = true;
+          setError(data.error || "Authentication failed");
+          setStep("error");
+          return;
+        }
+      } catch {
+        // Network error, keep polling
+      }
+      if (attempts >= MAX_ATTEMPTS) {
+        callbackProcessedRef.current = true;
+        setError("Authentication timeout");
+        setStep("error");
+        return;
+      }
+      setTimeout(tick, POLL_INTERVAL_MS);
+    };
+    setTimeout(tick, POLL_INTERVAL_MS);
+    return () => { cancelled = true; };
+  }, [authData, onSuccess]);
+
+  // Listen for OAuth callback via multiple methods
+  useEffect(() => {
+    if (!authData) return;
+    callbackProcessedRef.current = false; // Reset when authData changes
+
+    // Handler for callback data - only process once
+    const handleCallback = async (data) => {
+      if (callbackProcessedRef.current) return; // Already processed
+
+      const { code, token, state, error: callbackError, errorDescription } = data;
+
+      if (callbackError) {
+        callbackProcessedRef.current = true;
+        setError(errorDescription || callbackError);
+        setStep("error");
+        return;
+      }
+
+      if (token || code) {
+        callbackProcessedRef.current = true;
+        await exchangeTokens(token || code, state);
+      }
+    };
+
+    // Method 1: postMessage from popup
+    const handleMessage = (event) => {
+      // Allow messages from same origin or localhost (any port)
+      const isLocalhost = event.origin.includes("localhost") || event.origin.includes("127.0.0.1");
+      const isSameOrigin = event.origin === window.location.origin;
+      if (!isLocalhost && !isSameOrigin) return;
+      
+      if (event.data?.type === "oauth_callback") {
+        handleCallback(event.data.data);
+      }
+    };
+    window.addEventListener("message", handleMessage);
+
+    // Method 2: BroadcastChannel
+    let channel;
+    try {
+      channel = new BroadcastChannel("oauth_callback");
+      channel.onmessage = (event) => handleCallback(event.data);
+    } catch (e) {
+      console.log("BroadcastChannel not supported");
+    }
+
+    // Method 3: localStorage event
+    const handleStorage = (event) => {
+      if (event.key === "oauth_callback" && event.newValue) {
+        try {
+          const data = JSON.parse(event.newValue);
+          handleCallback(data);
+          localStorage.removeItem("oauth_callback");
+        } catch (e) {
+          console.log("Failed to parse localStorage data");
+        }
+      }
+    };
+    window.addEventListener("storage", handleStorage);
+
+    // Also check localStorage on mount (in case callback already happened)
+    try {
+      const stored = localStorage.getItem("oauth_callback");
+      if (stored) {
+        const data = JSON.parse(stored);
+        if (data.timestamp && Date.now() - data.timestamp < 30000) {
+          handleCallback(data);
+        }
+        localStorage.removeItem("oauth_callback");
+      }
+    } catch {
+      // localStorage may be unavailable or data may be malformed - ignore silently
+    }
+
+    return () => {
+      window.removeEventListener("message", handleMessage);
+      window.removeEventListener("storage", handleStorage);
+      if (channel) channel.close();
+    };
+  }, [authData, exchangeTokens]);
+
+  // Handle manual URL input
+  const handleManualSubmit = async () => {
+    try {
+      setError(null);
+
+      const input = callbackUrl.trim();
+
+      // Detect raw JWT access token (starts with eyJ) — skip URL parsing
+      if (input.startsWith("eyJ") && input.includes(".")) {
+        await exchangeTokens(input, null);
+        return;
+      }
+
+      if (provider === "xai" && input && !input.includes("://") && !input.includes("?") && !input.includes("code=")) {
+        await completeXaiManualCode(input);
+        return;
+      }
+
+      if (provider === "kimchi" && input && !input.includes("://") && !input.includes("?")) {
+        await exchangeTokens(input, null);
+        return;
+      }
+
+      const url = new URL(input);
+      const code = url.searchParams.get("code");
+      const token = url.searchParams.get("token");
+      const state = url.searchParams.get("state");
+      const errorParam = url.searchParams.get("error");
+
+      if (errorParam) {
+        throw new Error(url.searchParams.get("error_description") || errorParam);
+      }
+
+      if (!code && !token) {
+        throw new Error(
+          provider === "xai"
+            ? "Paste the callback URL or copied xAI code"
+            : provider === "kimchi"
+              ? "No Kimchi token found in URL"
+              : "No authorization code found in URL"
+        );
+      }
+
+      await exchangeTokens(token || code, state);
+    } catch (err) {
+      setError(err.message);
+      setStep("error");
+    }
+  };
+
+  // Clear session on modal close + cleanup proxy
+  const handleClose = useCallback(() => {
+    if (provider === "codex") {
+      fetch("/api/oauth/codex/stop-proxy").catch(() => {});
+    } else if (provider === "xai") {
+      fetch("/api/oauth/xai/stop-proxy").catch(() => {});
+    }
+    onClose();
+  }, [onClose, provider]);
+
+  if (!provider || !providerInfo) return null;
+  const isXaiProvider = provider === "xai";
+  const isKimchiProvider = provider === "kimchi";
+  const deviceLoginUrl = deviceData?.verification_uri_complete || deviceData?.verification_uri || "";
+  const modalTitle = isXaiProvider ? "Connect Grok Build OAuth" : `Connect ${providerInfo.name}`;
+  const manualPlaceholder = isXaiProvider
+    ? "http://127.0.0.1:56121/callback?code=... or copied code"
+    : isKimchiProvider
+      ? `${placeholderUrl.replace("code=...", "token=...")} or copied token`
+      : placeholderUrl;
+
+  return (
+    <Modal isOpen={isOpen} title={modalTitle} onClose={handleClose} size="lg">
+      <div className="flex flex-col gap-4">
+        {/* Waiting + Manual Input combined (non-device-code) */}
+        {(step === "waiting" || step === "input") && !isDeviceCode && (
+          <>
+            {/* Option A: Auto via popup */}
+            <div className="flex items-center gap-2 px-3 py-2 border border-border rounded-lg bg-sidebar/50">
+              <span className="material-symbols-outlined text-base text-primary animate-spin">
+                progress_activity
+              </span>
+              <span className="text-sm">
+                {isXaiProvider ? "Waiting for Grok Build OAuth…" : "Waiting for popup authorization…"}
+              </span>
+            </div>
+
+            {/* Divider */}
+            <div className="flex items-center gap-3 my-1">
+              <div className="flex-1 h-px bg-border" />
+              <span className="text-xs text-text-muted uppercase tracking-wider">Or paste callback URL manually</span>
+              <div className="flex-1 h-px bg-border" />
+            </div>
+
+            {/* Option B: Manual paste */}
+            <div className="space-y-4">
+              <div>
+                <p className="text-sm font-medium mb-2">
+                  Step 1: Open this {isXaiProvider ? "Grok Build OAuth URL" : "URL"} in your browser
+                </p>
+                <div className="flex gap-2">
+                  <Input value={authData?.authUrl || ""} readOnly className="flex-1 font-mono text-xs" />
+                  <Button variant="secondary" icon={copied === "auth_url" ? "check" : "content_copy"} onClick={() => copy(authData?.authUrl, "auth_url")} disabled={!authData?.authUrl}>
+                    Copy
+                  </Button>
+                </div>
+              </div>
+
+              <div>
+                <p className="text-sm font-medium mb-2">
+                  Step 2: Paste the {provider === "xai" ? "callback URL or copied code" : isKimchiProvider ? "callback URL or copied token" : "callback URL"} here
+                </p>
+                <p className="text-xs text-text-muted mb-2">
+                  {provider === "xai"
+                    ? "If xAI shows a code instead of redirecting, paste that code here."
+                    : isKimchiProvider
+                      ? "After authorization, copy the full callback URL or token from your browser."
+                    : "After authorization, copy the full URL from your browser."}
+                </p>
+                <Input
+                  value={callbackUrl}
+                  onChange={(e) => setCallbackUrl(e.target.value)}
+                  placeholder={manualPlaceholder}
+                  className="font-mono text-xs"
+                />
+              </div>
+            </div>
+
+            <div className="flex gap-2">
+              <Button onClick={handleManualSubmit} fullWidth disabled={!callbackUrl}>
+                Connect
+              </Button>
+              <Button onClick={handleClose} variant="ghost" fullWidth>
+                Cancel
+              </Button>
+            </div>
+          </>
+        )}
+
+        {/* Device Code Flow - Waiting */}
+        {step === "waiting" && isDeviceCode && deviceData && (
+          <>
+            <div className="text-center py-4">
+              <p className="text-sm text-text-muted mb-4">
+                Visit the login URL below and authorize:
+              </p>
+              <div className="bg-sidebar p-4 rounded-lg mb-4">
+                <p className="text-xs text-text-muted mb-1">Login URL</p>
+                <div className="flex items-center gap-2">
+                  <code className="flex-1 text-sm break-all">{deviceLoginUrl}</code>
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    icon={copied === "login_url" ? "check" : "content_copy"}
+                    onClick={() => copy(deviceLoginUrl, "login_url")}
+                    disabled={!deviceLoginUrl}
+                  />
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    icon="open_in_new"
+                    onClick={() => window.open(deviceLoginUrl, "_blank", "noopener,noreferrer")}
+                    disabled={!deviceLoginUrl}
+                  >
+                    Open
+                  </Button>
+                </div>
+              </div>
+              <div className="bg-primary/10 p-4 rounded-lg">
+                <p className="text-xs text-text-muted mb-1">Your Code</p>
+                <div className="flex items-center justify-center gap-2">
+                  <p className="text-2xl font-mono font-bold text-primary">{deviceData.user_code}</p>
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    icon={copied === "user_code" ? "check" : "content_copy"}
+                    onClick={() => copy(deviceData.user_code, "user_code")}
+                  />
+                </div>
+              </div>
+            </div>
+            {polling && (
+              <div className="flex items-center justify-center gap-2 text-sm text-text-muted">
+                <span className="material-symbols-outlined animate-spin">progress_activity</span>
+                Waiting for authorization...
+              </div>
+            )}
+          </>
+        )}
+
+        {/* Success Step */}
+        {step === "success" && (
+          <div className="text-center py-6">
+            <div className="size-16 mx-auto mb-4 rounded-full bg-green-100 dark:bg-green-900/30 flex items-center justify-center">
+              <span className="material-symbols-outlined text-3xl text-green-600">check_circle</span>
+            </div>
+            <h3 className="text-lg font-semibold mb-2">Connected Successfully!</h3>
+            <p className="text-sm text-text-muted mb-4">
+              Your {providerInfo.name} account has been connected.
+            </p>
+            <Button onClick={handleClose} fullWidth>
+              Done
+            </Button>
+          </div>
+        )}
+
+        {/* Error Step */}
+        {step === "error" && (
+          <div className="text-center py-6">
+            <div className="size-16 mx-auto mb-4 rounded-full bg-red-100 dark:bg-red-900/30 flex items-center justify-center">
+              <span className="material-symbols-outlined text-3xl text-red-600">error</span>
+            </div>
+            <h3 className="text-lg font-semibold mb-2">Connection Failed</h3>
+            <p className="text-sm text-red-600 mb-4">{error}</p>
+            <div className="flex gap-2">
+              <Button onClick={startOAuthFlow} variant="secondary" fullWidth>
+                Try Again
+              </Button>
+              <Button onClick={handleClose} variant="ghost" fullWidth>
+                Cancel
+              </Button>
+            </div>
+          </div>
+        )}
+      </div>
+    </Modal>
+  );
+}
+
+OAuthModal.propTypes = {
+  isOpen: PropTypes.bool.isRequired,
+  provider: PropTypes.string,
+  providerInfo: PropTypes.shape({ name: PropTypes.string }),
+  onSuccess: PropTypes.func,
+  onClose: PropTypes.func.isRequired,
+  /** Extra metadata passed to /authorize and /exchange (e.g. gitlab clientId/baseUrl) */
+  oauthMeta: PropTypes.object,
+  /** Optional Kiro IDC config for AWS IAM Identity Center device flow */
+  idcConfig: PropTypes.shape({
+    startUrl: PropTypes.string,
+    region: PropTypes.string,
+  }),
+};
diff --git a/src/shared/components/Pagination.js b/src/shared/components/Pagination.js
new file mode 100644
index 0000000..9efa9b5
--- /dev/null
+++ b/src/shared/components/Pagination.js
@@ -0,0 +1,150 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+import Button from "./Button";
+
+export default function Pagination({
+  currentPage,
+  pageSize,
+  totalItems,
+  onPageChange,
+  onPageSizeChange,
+  className,
+}) {
+  const totalPages = Math.ceil(totalItems / pageSize);
+  const startItem = totalItems > 0 ? (currentPage - 1) * pageSize + 1 : 0;
+  const endItem = Math.min(currentPage * pageSize, totalItems);
+
+  const getPageNumbers = () => {
+    const pages = [];
+    const showMax = 5;
+
+    let start = Math.max(1, currentPage - 2);
+    let end = Math.min(totalPages, start + showMax - 1);
+
+    if (end - start + 1 < showMax) {
+      start = Math.max(1, end - showMax + 1);
+    }
+
+    for (let i = start; i <= end; i++) {
+      pages.push(i);
+    }
+    return pages;
+  };
+
+  const pageNumbers = getPageNumbers();
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col sm:flex-row items-center justify-between gap-4 py-4 px-2",
+        className
+      )}
+    >
+      {/* Info text */}
+      {totalItems > 0 && (
+        <div className="text-sm text-text-muted">
+          Showing <span className="font-medium text-text-main">{startItem}</span> to{" "}
+          <span className="font-medium text-text-main">{endItem}</span> of{" "}
+          <span className="font-medium text-text-main">{totalItems}</span> results
+        </div>
+      )}
+
+      <div className="flex flex-wrap items-center justify-center gap-2 sm:gap-4">
+        {/* Page size selector */}
+        {onPageSizeChange && (
+          <div className="flex items-center gap-2">
+            <span className="text-sm text-text-muted">Rows:</span>
+            <select
+              value={pageSize}
+              onChange={(e) => onPageSizeChange(Number(e.target.value))}
+              className={cn(
+                "h-9 rounded-lg border border-black/10 dark:border-white/10 bg-surface",
+                "text-sm text-text-main focus:outline-none focus:ring-2 focus:ring-primary/20",
+                "cursor-pointer"
+              )}
+              style={{ colorScheme: 'auto' }}
+            >
+              {[10, 20, 50].map((size) => (
+                <option key={size} value={size}>
+                  {size}
+                </option>
+              ))}
+            </select>
+          </div>
+        )}
+
+        {totalPages > 1 && (
+          <div className="flex items-center gap-1">
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => onPageChange(currentPage - 1)}
+              disabled={currentPage === 1}
+              className="w-9 px-0"
+            >
+              <span className="material-symbols-outlined text-[18px]">chevron_left</span>
+            </Button>
+
+            {pageNumbers[0] > 1 && (
+              <>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => onPageChange(1)}
+                  className="w-9 px-0 hidden sm:inline-flex"
+                >
+                  1
+                </Button>
+                {pageNumbers[0] > 2 && (
+                  <span className="text-text-muted px-1 hidden sm:inline">...</span>
+                )}
+              </>
+            )}
+
+            {pageNumbers.map((page) => (
+              <Button
+                key={page}
+                variant={currentPage === page ? "primary" : "ghost"}
+                size="sm"
+                onClick={() => onPageChange(page)}
+                className={cn(
+                  "w-9 px-0",
+                  currentPage === page ? "inline-flex" : "hidden sm:inline-flex"
+                )}
+              >
+                {page}
+              </Button>
+            ))}
+
+            {pageNumbers[pageNumbers.length - 1] < totalPages && (
+              <>
+                {pageNumbers[pageNumbers.length - 1] < totalPages - 1 && (
+                  <span className="text-text-muted px-1 hidden sm:inline">...</span>
+                )}
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => onPageChange(totalPages)}
+                  className="w-9 px-0 hidden sm:inline-flex"
+                >
+                  {totalPages}
+                </Button>
+              </>
+            )}
+
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => onPageChange(currentPage + 1)}
+              disabled={currentPage === totalPages}
+              className="w-9 px-0"
+            >
+              <span className="material-symbols-outlined text-[18px]">chevron_right</span>
+            </Button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/shared/components/PricingModal.js b/src/shared/components/PricingModal.js
new file mode 100644
index 0000000..1e89231
--- /dev/null
+++ b/src/shared/components/PricingModal.js
@@ -0,0 +1,208 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { getDefaultPricing, formatCost } from "open-sse/providers/pricing.js";
+
+export default function PricingModal({ isOpen, onClose, onSave }) {
+  const [pricingData, setPricingData] = useState({});
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+
+  useEffect(() => {
+    if (isOpen) {
+      loadPricing();
+    }
+  }, [isOpen]);
+
+  const loadPricing = async () => {
+    setLoading(true);
+    try {
+      const response = await fetch("/api/pricing");
+      if (response.ok) {
+        const data = await response.json();
+        setPricingData(data);
+      } else {
+        // Fallback to defaults
+        const defaults = getDefaultPricing();
+        setPricingData(defaults);
+      }
+    } catch (error) {
+      console.error("Failed to load pricing:", error);
+      const defaults = getDefaultPricing();
+      setPricingData(defaults);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handlePricingChange = (provider, model, field, value) => {
+    const numValue = parseFloat(value);
+    if (isNaN(numValue) || numValue < 0) return;
+
+    setPricingData(prev => {
+      const newData = { ...prev };
+      if (!newData[provider]) newData[provider] = {};
+      if (!newData[provider][model]) newData[provider][model] = {};
+      newData[provider][model][field] = numValue;
+      return newData;
+    });
+  };
+
+  const handleSave = async () => {
+    setSaving(true);
+    try {
+      const response = await fetch("/api/pricing", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(pricingData)
+      });
+
+      if (response.ok) {
+        onSave?.();
+        onClose();
+      } else {
+        const error = await response.json();
+        alert(`Failed to save pricing: ${error.error}`);
+      }
+    } catch (error) {
+      console.error("Failed to save pricing:", error);
+      alert("Failed to save pricing");
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleReset = async () => {
+    if (!confirm("Reset all pricing to defaults? This cannot be undone.")) return;
+
+    try {
+      const response = await fetch("/api/pricing", { method: "DELETE" });
+      if (response.ok) {
+        const defaults = getDefaultPricing();
+        setPricingData(defaults);
+      }
+    } catch (error) {
+      console.error("Failed to reset pricing:", error);
+      alert("Failed to reset pricing");
+    }
+  };
+
+  if (!isOpen) return null;
+
+  // Get all unique providers and models for display
+  const allProviders = Object.keys(pricingData).sort();
+  const pricingFields = ["input", "output", "cached", "reasoning", "cache_creation"];
+
+  return (
+    <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50 p-4">
+      <div className="bg-bg-base border border-border rounded-lg shadow-xl max-w-6xl w-full max-h-[90vh] overflow-hidden flex flex-col">
+        {/* Header */}
+        <div className="p-4 border-b border-border flex items-center justify-between">
+          <h2 className="text-xl font-semibold">Pricing Configuration</h2>
+          <button
+            onClick={onClose}
+            className="text-text-muted hover:text-text text-2xl leading-none"
+          >
+            ×
+          </button>
+        </div>
+
+        {/* Content */}
+        <div className="flex-1 overflow-auto p-4">
+          {loading ? (
+            <div className="text-center py-8 text-text-muted">Loading pricing data...</div>
+          ) : (
+            <div className="space-y-6">
+              {/* Instructions */}
+              <div className="bg-bg-subtle border border-border rounded-lg p-3 text-sm">
+                <p className="font-medium mb-1">Pricing Rates Format</p>
+                <p className="text-text-muted">
+                  All rates are in <strong>dollars per million tokens</strong> ($/1M tokens).
+                  Example: Input rate of 2.50 means $2.50 per 1,000,000 input tokens.
+                </p>
+              </div>
+
+              {/* Pricing Tables */}
+              {allProviders.map(provider => {
+                const models = Object.keys(pricingData[provider]).sort();
+                return (
+                  <div key={provider} className="border border-border rounded-lg overflow-hidden">
+                    <div className="bg-bg-subtle px-4 py-2 font-semibold text-sm">
+                      {provider.toUpperCase()}
+                    </div>
+                    <div className="overflow-x-auto">
+                      <table className="w-full text-sm">
+                        <thead className="bg-bg-hover text-text-muted uppercase text-xs">
+                          <tr>
+                            <th className="px-3 py-2 text-left">Model</th>
+                            <th className="px-3 py-2 text-right">Input</th>
+                            <th className="px-3 py-2 text-right">Output</th>
+                            <th className="px-3 py-2 text-right">Cached</th>
+                            <th className="px-3 py-2 text-right">Reasoning</th>
+                            <th className="px-3 py-2 text-right">Cache Creation</th>
+                          </tr>
+                        </thead>
+                        <tbody className="divide-y divide-border">
+                          {models.map(model => (
+                            <tr key={model} className="hover:bg-bg-subtle/50">
+                              <td className="px-3 py-2 font-medium">{model}</td>
+                              {pricingFields.map(field => (
+                                <td key={field} className="px-3 py-2">
+                                  <input
+                                    type="number"
+                                    step="0.01"
+                                    min="0"
+                                    value={pricingData[provider][model][field] || 0}
+                                    onChange={(e) => handlePricingChange(provider, model, field, e.target.value)}
+                                    className="w-20 px-2 py-1 text-right bg-bg-base border border-border rounded focus:outline-none focus:border-primary"
+                                  />
+                                </td>
+                              ))}
+                            </tr>
+                          ))}
+                        </tbody>
+                      </table>
+                    </div>
+                  </div>
+                );
+              })}
+
+              {allProviders.length === 0 && (
+                <div className="text-center py-8 text-text-muted">
+                  No pricing data available
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+
+        {/* Footer */}
+        <div className="p-4 border-t border-border flex items-center justify-between gap-2">
+          <button
+            onClick={handleReset}
+            className="px-4 py-2 text-sm text-red-500 hover:bg-red-500/10 rounded border border-red-500/20 transition-colors"
+            disabled={saving}
+          >
+            Reset to Defaults
+          </button>
+          <div className="flex gap-2">
+            <button
+              onClick={onClose}
+              className="px-4 py-2 text-sm text-text-muted hover:text-text border border-border rounded transition-colors"
+              disabled={saving}
+            >
+              Cancel
+            </button>
+            <button
+              onClick={handleSave}
+              className="px-4 py-2 text-sm bg-primary text-white rounded hover:bg-primary/90 transition-colors disabled:opacity-50"
+              disabled={saving}
+            >
+              {saving ? "Saving..." : "Save Changes"}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/shared/components/ProviderIcon.js b/src/shared/components/ProviderIcon.js
new file mode 100644
index 0000000..ca55850
--- /dev/null
+++ b/src/shared/components/ProviderIcon.js
@@ -0,0 +1,51 @@
+"use client";
+
+import { useState } from "react";
+import PropTypes from "prop-types";
+
+export default function ProviderIcon({
+  src,
+  alt,
+  size = 32,
+  className = "",
+  fallbackText = "?",
+  fallbackColor,
+}) {
+  const [errored, setErrored] = useState(false);
+
+  if (!src || errored) {
+    return (
+      <span
+        className={`inline-flex items-center justify-center font-bold rounded-lg ${className}`.trim()}
+        style={{
+          width: size,
+          height: size,
+          color: fallbackColor,
+          fontSize: Math.max(10, Math.floor(size * 0.38)),
+        }}
+      >
+        {fallbackText}
+      </span>
+    );
+  }
+
+  return (
+    <img
+      src={src}
+      alt={alt}
+      width={size}
+      height={size}
+      className={className}
+      onError={() => setErrored(true)}
+    />
+  );
+}
+
+ProviderIcon.propTypes = {
+  src: PropTypes.string,
+  alt: PropTypes.string,
+  size: PropTypes.number,
+  className: PropTypes.string,
+  fallbackText: PropTypes.string,
+  fallbackColor: PropTypes.string,
+};
diff --git a/src/shared/components/ProviderInfoCard.js b/src/shared/components/ProviderInfoCard.js
new file mode 100644
index 0000000..1957f89
--- /dev/null
+++ b/src/shared/components/ProviderInfoCard.js
@@ -0,0 +1,82 @@
+"use client";
+
+import Card from "./Card";
+
+// Only show fields user actually cares about
+const FIELD_SCHEMA = {
+  mode:             { label: "Mode",       format: (v) => v },
+  defaultModel:     { label: "Model",      format: (v) => v, mono: true },
+  baseUrl:          { label: "Endpoint",   format: (v) => v, isLink: true, mono: true },
+  costPerQuery:     { label: "Cost / call", format: (v) => v === 0 ? "Free" : `$${v.toFixed(4)}` },
+  pricingUrl:       { label: "Pricing",    format: () => "View pricing", isLink: true },
+  freeTier:         { label: "Free tier",  format: (v) => v },
+  freeMonthlyQuota: { label: "Free quota",  format: (v) => v === 0 ? "—" : v >= 999999 ? "Unlimited" : `${v.toLocaleString()} / mo` },
+  searchTypes:      { label: "Types",      format: (v) => v.join(", ") },
+  formats:          { label: "Formats",    format: (v) => v.join(", ") },
+  maxMaxResults:    { label: "Max results", format: (v) => v },
+  maxCharacters:    { label: "Max chars",  format: (v) => v.toLocaleString() },
+};
+
+export default function ProviderInfoCard({ config, provider, title = "Provider Info" }) {
+  if (!config) return null;
+
+  const rows = Object.entries(FIELD_SCHEMA)
+    .filter(([key]) => config[key] !== undefined && config[key] !== null && config[key] !== "")
+    .map(([key, schema]) => ({
+      key,
+      label: schema.label,
+      value: schema.format(config[key]),
+      isLink: schema.isLink,
+      mono: schema.mono,
+      raw: config[key],
+    }));
+
+  const signupUrl = provider?.notice?.apiKeyUrl || provider?.website;
+  const noticeText = provider?.notice?.text;
+
+  return (
+    <Card>
+      <div className="flex items-center justify-between mb-3">
+        <h2 className="text-lg font-semibold">{title}</h2>
+        {signupUrl && (
+          <a
+            href={signupUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-xs text-primary hover:underline inline-flex items-center gap-1"
+          >
+            <span className="material-symbols-outlined text-sm">open_in_new</span>
+            Get API Key
+          </a>
+        )}
+      </div>
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-2">
+        {rows.map((r) => (
+          <div key={r.key} className="flex items-center gap-3 min-w-0">
+            <span className="text-xs text-text-muted w-28 shrink-0">{r.label}</span>
+            {r.isLink ? (
+              <a
+                href={r.raw}
+                target="_blank"
+                rel="noopener noreferrer"
+                className={`text-sm text-primary hover:underline truncate ${r.mono ? "font-mono" : ""}`}
+              >
+                {r.value}
+              </a>
+            ) : (
+              <span className={`text-sm text-text-main truncate ${r.mono ? "font-mono" : ""}`}>
+                {r.value}
+              </span>
+            )}
+          </div>
+        ))}
+        {noticeText && (
+          <div className="flex items-start gap-3 min-w-0 sm:col-span-2">
+            <span className="text-xs text-text-muted w-28 shrink-0 mt-0.5">Notice</span>
+            <span className="text-sm text-text-main leading-relaxed">{noticeText}</span>
+          </div>
+        )}
+      </div>
+    </Card>
+  );
+}
diff --git a/src/shared/components/RequestLogger.js b/src/shared/components/RequestLogger.js
new file mode 100644
index 0000000..f13b518
--- /dev/null
+++ b/src/shared/components/RequestLogger.js
@@ -0,0 +1,121 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import Card from "./Card";
+
+export default function RequestLogger() {
+  const [logs, setLogs] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [autoRefresh, setAutoRefresh] = useState(true);
+
+  useEffect(() => {
+    fetchLogs();
+  }, []);
+
+  useEffect(() => {
+    let interval;
+    if (autoRefresh) {
+      interval = setInterval(() => {
+        fetchLogs(false);
+      }, 3000);
+    }
+    return () => clearInterval(interval);
+  }, [autoRefresh]);
+
+  const fetchLogs = async (showLoading = true) => {
+    if (showLoading) setLoading(true);
+    try {
+      const res = await fetch("/api/usage/request-logs");
+      if (res.ok) {
+        const data = await res.json();
+        setLogs(data);
+      }
+    } catch (error) {
+      console.error("Failed to fetch logs:", error);
+    } finally {
+      if (showLoading) setLoading(false);
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center justify-between">
+        <h2 className="text-xl font-semibold">Request Logs</h2>
+        <div className="flex items-center gap-2">
+          <label className="text-sm font-medium text-text-muted flex items-center gap-2 cursor-pointer">
+            <span>Auto Refresh (3s)</span>
+            <div
+              onClick={() => setAutoRefresh(!autoRefresh)}
+              className={`relative inline-flex h-5 w-9 items-center rounded-full transition-colors focus:outline-none ${autoRefresh ? "bg-primary" : "bg-bg-subtle border border-border"
+                }`}
+            >
+              <span
+                className={`inline-block h-3 w-3 transform rounded-full bg-white transition-transform ${autoRefresh ? "translate-x-5" : "translate-x-1"
+                  }`}
+              />
+            </div>
+          </label>
+        </div>
+      </div>
+
+      <Card className="overflow-hidden bg-black/5 dark:bg-black/20">
+        <div className="p-0 overflow-x-auto max-h-[600px] overflow-y-auto font-mono text-xs">
+          {loading && logs.length === 0 ? (
+            <div className="p-8 text-center text-text-muted">Loading logs...</div>
+          ) : logs.length === 0 ? (
+            <div className="p-8 text-center text-text-muted">No logs recorded yet.</div>
+          ) : (
+            <table className="w-full text-left border-collapse whitespace-nowrap">
+              <thead className="sticky top-0 bg-bg-subtle border-b border-border z-10">
+                <tr>
+                  <th className="px-3 py-2 border-r border-border">DateTime</th>
+                  <th className="px-3 py-2 border-r border-border">Model</th>
+                  <th className="px-3 py-2 border-r border-border">Provider</th>
+                  <th className="px-3 py-2 border-r border-border">Account</th>
+                  <th className="px-3 py-2 border-r border-border">In</th>
+                  <th className="px-3 py-2 border-r border-border">Out</th>
+                  <th className="px-3 py-2">Status</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-border/50">
+                {logs.map((log, i) => {
+                  const parts = log.split(" | ");
+                  if (parts.length < 7) return null;
+
+                  const status = parts[6];
+                  const isPending = status.includes("PENDING");
+                  const isFailed = status.includes("FAILED");
+                  const isSuccess = status.includes("OK");
+
+                  return (
+                    <tr key={i} className={`hover:bg-primary/5 transition-colors ${isPending ? 'bg-primary/5' : ''}`}>
+                      <td className="px-3 py-1.5 border-r border-border text-text-muted">{parts[0]}</td>
+                      <td className="px-3 py-1.5 border-r border-border font-medium">{parts[1]}</td>
+                      <td className="px-3 py-1.5 border-r border-border">
+                        <span className="px-1.5 py-0.5 rounded bg-bg-subtle border border-border text-[10px] uppercase font-bold">
+                          {parts[2]}
+                        </span>
+                      </td>
+                      <td className="px-3 py-1.5 border-r border-border truncate max-w-[150px]" title={parts[3]}>{parts[3]}</td>
+                      <td className="px-3 py-1.5 border-r border-border text-right text-primary">{parts[4]}</td>
+                      <td className="px-3 py-1.5 border-r border-border text-right text-success">{parts[5]}</td>
+                      <td className={`px-3 py-1.5 font-bold ${isSuccess ? 'text-success' :
+                          isFailed ? 'text-error' :
+                            'text-primary animate-pulse'
+                        }`}>
+                        {status}
+                      </td>
+                    </tr>
+                  );
+                })}
+              </tbody>
+            </table>
+          )}
+        </div>
+      </Card>
+      <div className="text-[10px] text-text-muted italic">
+        Logs are loaded from the request history database.
+      </div>
+    </div>
+  );
+}
diff --git a/src/shared/components/SegmentedControl.js b/src/shared/components/SegmentedControl.js
new file mode 100644
index 0000000..d63ad8d
--- /dev/null
+++ b/src/shared/components/SegmentedControl.js
@@ -0,0 +1,48 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+export default function SegmentedControl({
+  options = [],
+  value,
+  onChange,
+  size = "md",
+  className,
+}) {
+  const sizes = {
+    sm: "h-7 text-xs",
+    md: "h-9 text-sm",
+    lg: "h-11 text-base",
+  };
+
+  return (
+    <div
+      className={cn(
+        "inline-flex items-center p-1 rounded-[10px] overflow-x-auto",
+        "bg-surface-2",
+        className
+      )}
+    >
+      {options.map((option) => (
+        <button
+          key={option.value}
+          onClick={() => onChange(option.value)}
+          className={cn(
+            "shrink-0 px-4 rounded-[8px] font-medium transition-all",
+            sizes[size],
+            value === option.value
+              ? "bg-surface text-text-main shadow-sm"
+              : "text-text-muted hover:text-text-main"
+          )}
+        >
+          {option.icon && (
+            <span className="material-symbols-outlined text-[16px] mr-1.5">
+              {option.icon}
+            </span>
+          )}
+          {option.label}
+        </button>
+      ))}
+    </div>
+  );
+}
diff --git a/src/shared/components/Select.js b/src/shared/components/Select.js
new file mode 100644
index 0000000..73b4e5f
--- /dev/null
+++ b/src/shared/components/Select.js
@@ -0,0 +1,67 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+export default function Select({
+  label,
+  options = [],
+  value,
+  onChange,
+  placeholder = "Select an option",
+  error,
+  hint,
+  disabled = false,
+  required = false,
+  className,
+  selectClassName,
+  ...props
+}) {
+  return (
+    <div className={cn("flex flex-col gap-1.5", className)}>
+      {label && (
+        <label className="text-sm font-medium text-text-main">
+          {label}
+          {required && <span className="text-red-500 ml-1">*</span>}
+        </label>
+      )}
+      <div className="relative">
+        <select
+          value={value}
+          onChange={onChange}
+          disabled={disabled}
+          className={cn(
+            "w-full py-2.5 px-3 pr-10 text-sm text-text-main",
+            "bg-surface-2 border border-transparent rounded-[10px] appearance-none",
+            "focus:outline-none focus:ring-2 focus:ring-brand-500/30 focus:border-brand-500/40",
+            "transition-all duration-150 disabled:opacity-50 disabled:cursor-not-allowed",
+            "text-[16px] sm:text-sm",
+            error && "ring-1 ring-red-500 focus:ring-2 focus:ring-red-500/40 border-red-500/40",
+            selectClassName
+          )}
+          {...props}
+        >
+          <option value="" disabled>
+            {placeholder}
+          </option>
+          {options.map((option) => (
+            <option key={option.value} value={option.value}>
+              {option.label}
+            </option>
+          ))}
+        </select>
+        <div className="absolute inset-y-0 right-0 flex items-center pr-3 pointer-events-none text-text-muted">
+          <span className="material-symbols-outlined text-[20px]">expand_more</span>
+        </div>
+      </div>
+      {error && (
+        <p className="text-xs text-red-500 flex items-center gap-1">
+          <span className="material-symbols-outlined text-[14px]">error</span>
+          {error}
+        </p>
+      )}
+      {hint && !error && (
+        <p className="text-xs text-text-muted">{hint}</p>
+      )}
+    </div>
+  );
+}
diff --git a/src/shared/components/Sidebar.js b/src/shared/components/Sidebar.js
new file mode 100644
index 0000000..77211f7
--- /dev/null
+++ b/src/shared/components/Sidebar.js
@@ -0,0 +1,441 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import PropTypes from "prop-types";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { cn } from "@/shared/utils/cn";
+import { APP_CONFIG, UPDATER_CONFIG } from "@/shared/constants/config";
+import { MEDIA_PROVIDER_KINDS } from "@/shared/constants/providers";
+import { useCopyToClipboard } from "@/shared/hooks/useCopyToClipboard";
+import Button from "./Button";
+import { ConfirmModal } from "./Modal";
+import NineRemotePromoModal from "./NineRemotePromoModal";
+
+// const VISIBLE_MEDIA_KINDS = ["embedding", "image", "imageToText", "tts", "stt", "webSearch", "webFetch", "video", "music"];
+const VISIBLE_MEDIA_KINDS = ["embedding", "image", "tts", "stt"];
+// Combined entry: webSearch + webFetch share one page at /dashboard/media-providers/web
+const COMBINED_WEB_ITEM = { id: "web", label: "Web Fetch & Search", icon: "travel_explore", href: "/dashboard/media-providers/web" };
+
+const navItems = [
+  { href: "/dashboard/endpoint", label: "Endpoint & Key", icon: "api" },
+  { href: "/dashboard/providers", label: "Providers", icon: "dns" },
+  // { href: "/dashboard/basic-chat", label: "Basic Chat", icon: "chat" }, // Hidden
+  { href: "/dashboard/combos", label: "Combos", icon: "layers" },
+  { href: "/dashboard/usage", label: "Usage", icon: "bar_chart" },
+  { href: "/dashboard/quota", label: "Quota Tracker", icon: "data_usage" },
+  { href: "/dashboard/token-saver", label: "Token Saver", icon: "savings" },
+  // { href: "/dashboard/pxpipe", label: "PXPIPE", icon: "image" },
+  { href: "/dashboard/cli-tools", label: "CLI Tools", icon: "terminal" },
+];
+
+const debugItems = [
+  { href: "/dashboard/console-log", label: "Console Log", icon: "terminal" },
+  { href: "/dashboard/translator", label: "Translator", icon: "translate" },
+];
+
+const systemItems = [
+  { href: "/dashboard/proxy-pools", label: "Proxy Pools", icon: "lan" },
+  { href: "/dashboard/skills", label: "Skills", icon: "extension" },
+];
+
+export default function Sidebar({ onClose }) {
+  const pathname = usePathname();
+  const [mediaOpen, setMediaOpen] = useState(false);
+  const [showRemoteModal, setShowRemoteModal] = useState(false);
+  const [isDisconnected, setIsDisconnected] = useState(false);
+  const [updateInfo, setUpdateInfo] = useState(null);
+  const [showUpdateModal, setShowUpdateModal] = useState(false);
+  const [isUpdating, setIsUpdating] = useState(false);
+  const [shutdownCountdown, setShutdownCountdown] = useState(0);
+  const [enableTranslator, setEnableTranslator] = useState(false);
+  const { copied, copy } = useCopyToClipboard(2000);
+
+  const INSTALL_CMD = UPDATER_CONFIG.installCmdLatest;
+
+  useEffect(() => {
+    fetch("/api/settings")
+      .then(res => res.json())
+      .then(data => { if (data.enableTranslator) setEnableTranslator(true); })
+      .catch(() => {});
+  }, []);
+
+  // Lazy check for new npm version on mount
+  useEffect(() => {
+    fetch("/api/version")
+      .then(res => res.json())
+      .then(data => { if (data.hasUpdate) setUpdateInfo(data); })
+      .catch(() => {});
+  }, []);
+
+  const isActive = (href) => {
+    if (href === "/dashboard/endpoint") {
+      return pathname === "/dashboard" || pathname.startsWith("/dashboard/endpoint");
+    }
+    return pathname.startsWith(href);
+  };
+
+  // Open manual update panel (no countdown yet — user must click Copy to trigger shutdown)
+  const handleUpdate = () => {
+    setShowUpdateModal(false);
+    setIsUpdating(true);
+  };
+
+  // Triggered by Copy button inside ManualUpdatePanel: copy + countdown + shutdown
+  const handleCopyAndShutdown = async () => {
+    try { await navigator.clipboard.writeText(INSTALL_CMD); } catch { /* clipboard blocked */ }
+    copy(INSTALL_CMD);
+    let remaining = UPDATER_CONFIG.shutdownCountdownSec;
+    setShutdownCountdown(remaining);
+    const timer = setInterval(() => {
+      remaining -= 1;
+      setShutdownCountdown(remaining);
+      if (remaining <= 0) {
+        clearInterval(timer);
+        fetch("/api/version/shutdown", { method: "POST" }).catch(() => {});
+        setIsDisconnected(true);
+      }
+    }, 1000);
+  };
+
+  const handleCancelUpdate = () => {
+    setIsUpdating(false);
+    setShutdownCountdown(0);
+  };
+
+  // Note: legacy updater poll removed. New flow: copy install cmd + shutdown server,
+  // user runs the command manually in another terminal.
+
+
+  return (
+    <>
+      <aside className="flex w-72 flex-col border-r border-border-subtle bg-vibrancy backdrop-blur-xl transition-colors duration-300 min-h-full">
+        {/* Traffic lights */}
+        <div className="flex items-center gap-2 px-6 pt-5 pb-2">
+          <div className="w-3 h-3 rounded-full bg-[#FF5F56]" />
+          <div className="w-3 h-3 rounded-full bg-[#FFBD2E]" />
+          <div className="w-3 h-3 rounded-full bg-[#27C93F]" />
+        </div>
+
+        {/* Logo */}
+        <div className="px-6 py-4 flex flex-col gap-2">
+          <Link href="/dashboard" className="flex items-center gap-3">
+            <div className="flex items-center justify-center size-9 rounded-[10px] bg-gradient-to-br from-brand-500 to-brand-700 shadow-[var(--shadow-warm)]">
+              <span className="material-symbols-outlined text-white text-[20px]">hub</span>
+            </div>
+            <div className="flex flex-col">
+              <h1 className="text-lg font-semibold tracking-tight text-text-main">
+                {APP_CONFIG.name}
+              </h1>
+              <span className="text-xs text-text-muted">v{APP_CONFIG.version}</span>
+            </div>
+          </Link>
+          {updateInfo && (
+            <div className="flex flex-col gap-1.5 rounded p-1 -m-1">
+              <span className="text-xs font-semibold text-green-600 dark:text-amber-500">
+                ↑ New version available: v{updateInfo.latestVersion}
+              </span>
+              <div className="flex items-center gap-2">
+                <button
+                  onClick={() => setShowUpdateModal(true)}
+                  className="px-2 py-1 rounded bg-green-600 hover:bg-green-700 dark:bg-amber-500 dark:hover:bg-amber-600 text-white text-[11px] font-semibold transition-colors cursor-pointer"
+                >
+                  Update now
+                </button>
+                <button
+                  onClick={() => copy(INSTALL_CMD)}
+                  title="Copy install command"
+                  className="flex-1 text-left hover:opacity-80 transition-opacity cursor-pointer min-w-0"
+                >
+                  <code className="block text-[10px] text-green-600/80 dark:text-amber-400/70 font-mono truncate">
+                    {copied ? "✓ copied!" : INSTALL_CMD}
+                  </code>
+                </button>
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* Navigation */}
+        <nav className="flex-1 px-4 py-2 space-y-0.5 overflow-y-auto custom-scrollbar">
+          {navItems.map((item) => (
+            <Link
+              key={item.href}
+              href={item.href}
+              onClick={onClose}
+              className={cn(
+                "flex items-center gap-3 px-3 py-1 rounded-lg transition-all group",
+                isActive(item.href)
+                  ? "bg-primary/10 text-primary"
+                  : "text-text-muted hover:bg-surface-2 hover:text-text-main"
+              )}
+            >
+              <span
+                className={cn(
+                  "material-symbols-outlined text-[18px]",
+                  isActive(item.href) ? "fill-1" : "group-hover:text-primary transition-colors"
+                )}
+              >
+                {item.icon}
+              </span>
+              <span className="text-[13px] font-medium">{item.label}</span>
+            </Link>
+          ))}
+
+          {/* System section */}
+          <div className="pt-3 mt-2 space-y-0.5">
+            <p className="px-4 text-xs font-semibold text-text-muted/60 uppercase tracking-wider mb-2">
+              System
+            </p>
+
+            {/* Media Providers accordion */}
+            <button
+              onClick={() => setMediaOpen((v) => !v)}
+              className={cn(
+                "w-full flex items-center gap-3 px-3 py-1 rounded-lg transition-all group",
+                pathname.startsWith("/dashboard/media-providers")
+                  ? "bg-primary/10 text-primary"
+                  : "text-text-muted hover:bg-surface-2 hover:text-text-main"
+              )}
+            >
+              <span className="material-symbols-outlined text-[18px]">perm_media</span>
+              <span className="text-[13px] font-medium flex-1 text-left">Media Providers</span>
+              <span className="material-symbols-outlined text-[14px] transition-transform" style={{ transform: mediaOpen ? "rotate(180deg)" : "rotate(0deg)" }}>
+                expand_more
+              </span>
+            </button>
+            {mediaOpen && (
+              <div className="pl-4">
+                {MEDIA_PROVIDER_KINDS.filter((k) => VISIBLE_MEDIA_KINDS.includes(k.id)).map((kind) => (
+                  <Link
+                    key={kind.id}
+                    href={`/dashboard/media-providers/${kind.id}`}
+                    onClick={onClose}
+                    className={cn(
+                      "flex items-center gap-3 px-4 py-1 rounded-lg transition-all group",
+                      pathname.startsWith(`/dashboard/media-providers/${kind.id}`)
+                        ? "bg-primary/10 text-primary"
+                        : "text-text-muted hover:bg-surface-2 hover:text-text-main"
+                    )}
+                  >
+                    <span className="material-symbols-outlined text-[16px]">{kind.icon}</span>
+                    <span className="text-sm">{kind.label}</span>
+                  </Link>
+                ))}
+                <Link
+                  key={COMBINED_WEB_ITEM.id}
+                  href={COMBINED_WEB_ITEM.href}
+                  onClick={onClose}
+                  className={cn(
+                    "flex items-center gap-3 px-4 py-1 rounded-lg transition-all group",
+                    pathname.startsWith(COMBINED_WEB_ITEM.href)
+                      ? "bg-primary/10 text-primary"
+                      : "text-text-muted hover:bg-surface-2 hover:text-text-main"
+                  )}
+                >
+                  <span className="material-symbols-outlined text-[16px]">{COMBINED_WEB_ITEM.icon}</span>
+                  <span className="text-sm">{COMBINED_WEB_ITEM.label}</span>
+                </Link>
+              </div>
+            )}
+
+            {systemItems.map((item) => (
+              <Link
+                key={item.href}
+                href={item.href}
+                onClick={onClose}
+                className={cn(
+                  "flex items-center gap-3 px-3 py-1 rounded-lg transition-all group",
+                  isActive(item.href)
+                    ? "bg-primary/10 text-primary"
+                    : "text-text-muted hover:bg-surface-2 hover:text-text-main"
+                )}
+              >
+                <span
+                  className={cn(
+                    "material-symbols-outlined text-[18px]",
+                    isActive(item.href) ? "fill-1" : "group-hover:text-primary transition-colors"
+                  )}
+                >
+                  {item.icon}
+                </span>
+                <span className="text-[13px] font-medium">{item.label}</span>
+              </Link>
+            ))}
+
+            {/* Debug items (inside System section, before Settings) */}
+            {debugItems.map((item) => {
+              const show = item.href !== "/dashboard/translator" || enableTranslator;
+              return show ? (
+                <Link
+                  key={item.href}
+                  href={item.href}
+                  onClick={onClose}
+                  className={cn(
+                    "flex items-center gap-3 px-3 py-1 rounded-lg transition-all group",
+                    isActive(item.href)
+                      ? "bg-primary/10 text-primary"
+                      : "text-text-muted hover:bg-surface-2 hover:text-text-main"
+                  )}
+                >
+                  <span
+                    className={cn(
+                      "material-symbols-outlined text-[18px]",
+                      isActive(item.href) ? "fill-1" : "group-hover:text-primary transition-colors"
+                    )}
+                  >
+                    {item.icon}
+                  </span>
+                  <span className="text-[13px] font-medium">{item.label}</span>
+                </Link>
+              ) : null;
+            })}
+
+            {/* Remote */}
+            <button
+              onClick={() => setShowRemoteModal(true)}
+              className={cn(
+                "flex items-center gap-3 px-3 py-1 rounded-lg transition-all group w-full",
+                "text-text-muted hover:bg-surface-2 hover:text-text-main"
+              )}
+            >
+              <span className="material-symbols-outlined text-[18px] group-hover:text-primary transition-colors">
+                computer
+              </span>
+              <span className="text-[13px] font-medium">Remote</span>
+            </button>
+
+            {/* Settings */}
+            <Link
+              href="/dashboard/profile"
+              onClick={onClose}
+              className={cn(
+                "flex items-center gap-3 px-3 py-1 rounded-lg transition-all group",
+                isActive("/dashboard/profile")
+                  ? "bg-primary/10 text-primary"
+                  : "text-text-muted hover:bg-surface-2 hover:text-text-main"
+              )}
+            >
+              <span
+                className={cn(
+                  "material-symbols-outlined text-[18px]",
+                  isActive("/dashboard/profile") ? "fill-1" : "group-hover:text-primary transition-colors"
+                )}
+              >
+                settings
+              </span>
+              <span className="text-[13px] font-medium">Settings</span>
+            </Link>
+          </div>
+        </nav>
+
+      </aside>
+
+      {/* Remote Promo Modal */}
+      <NineRemotePromoModal isOpen={showRemoteModal} onClose={() => setShowRemoteModal(false)} />
+
+      {/* Update Confirmation Modal */}
+      <ConfirmModal
+        isOpen={showUpdateModal}
+        onClose={() => setShowUpdateModal(false)}
+        onConfirm={handleUpdate}
+        title="Update 9Router"
+        message={`Show install command for v${updateInfo?.latestVersion || ""}? You can copy it and shutdown to install manually.`}
+        confirmText="Show Command"
+        cancelText="Cancel"
+        variant="primary"
+      />
+
+      {/* Disconnected / Updating Overlay */}
+      {(isDisconnected || isUpdating) && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/80 backdrop-blur-sm p-6">
+          {isUpdating ? (
+            <ManualUpdatePanel
+              latestVersion={updateInfo?.latestVersion}
+              installCmd={INSTALL_CMD}
+              copied={copied}
+              onCopyAndShutdown={handleCopyAndShutdown}
+              onCancel={handleCancelUpdate}
+              countdown={shutdownCountdown}
+              isDisconnected={isDisconnected}
+            />
+          ) : (
+            <div className="text-center p-8">
+              <div className="flex items-center justify-center size-16 rounded-full bg-red-500/20 text-red-500 mx-auto mb-4">
+                <span className="material-symbols-outlined text-[32px]">power_off</span>
+              </div>
+              <h2 className="text-xl font-semibold text-white mb-2">Server Disconnected</h2>
+              <p className="text-text-muted mb-6">The proxy server has been stopped.</p>
+              <Button variant="secondary" onClick={() => globalThis.location.reload()}>
+                Reload Page
+              </Button>
+            </div>
+          )}
+        </div>
+      )}
+    </>
+  );
+}
+
+Sidebar.propTypes = {
+  onClose: PropTypes.func,
+};
+
+function ManualUpdatePanel({ latestVersion, installCmd, copied, onCopyAndShutdown, onCancel, countdown, isDisconnected }) {
+  const isCountingDown = countdown > 0;
+  return (
+    <div className="w-full max-w-lg rounded-xl bg-neutral-900/95 border border-white/10 p-6 text-white">
+      <div className="flex items-center gap-3 mb-4">
+        <div className="flex items-center justify-center size-11 rounded-full bg-amber-500/20 text-amber-400">
+          <span className="material-symbols-outlined text-[24px]">content_copy</span>
+        </div>
+        <div>
+          <h2 className="text-lg font-semibold">Update 9Router{latestVersion ? ` to v${latestVersion}` : ""}</h2>
+          <p className="text-xs text-white/60">
+            {isDisconnected
+              ? "Server stopped. Paste the command into a terminal to install."
+              : isCountingDown
+                ? `Command copied. Server will stop in ${countdown}s...`
+                : "Click the button below to copy the install command and shutdown."}
+          </p>
+        </div>
+      </div>
+
+      <p className="text-sm text-white/80 mb-2">Install command:</p>
+      <div className="w-full px-3 py-2 rounded bg-white/5 mb-4">
+        <code className="text-xs font-mono text-amber-400 break-all">{installCmd}</code>
+      </div>
+
+      <ol className="text-xs text-white/70 space-y-1 list-decimal list-inside mb-4">
+        <li>Click <strong>Copy & Shutdown</strong> below.</li>
+        <li>Paste the command into your terminal and press Enter.</li>
+        <li>Run <code className="px-1 rounded bg-white/10 text-green-400">9router</code> again after install.</li>
+      </ol>
+
+      {isDisconnected ? (
+        <Button variant="secondary" fullWidth onClick={() => globalThis.location.reload()}>
+          Reload Page
+        </Button>
+      ) : (
+        <div className="flex gap-2">
+          <Button variant="secondary" onClick={onCancel} disabled={isCountingDown}>
+            Cancel
+          </Button>
+          <Button variant="primary" fullWidth onClick={onCopyAndShutdown} disabled={isCountingDown}>
+            {copied ? "✓ Copied — shutting down..." : isCountingDown ? `Shutting down in ${countdown}s` : "Copy & Shutdown"}
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+ManualUpdatePanel.propTypes = {
+  latestVersion: PropTypes.string,
+  installCmd: PropTypes.string.isRequired,
+  copied: PropTypes.bool,
+  onCopyAndShutdown: PropTypes.func.isRequired,
+  onCancel: PropTypes.func.isRequired,
+  countdown: PropTypes.number,
+  isDisconnected: PropTypes.bool,
+};
diff --git a/src/shared/components/ThemeProvider.js b/src/shared/components/ThemeProvider.js
new file mode 100644
index 0000000..a4745f4
--- /dev/null
+++ b/src/shared/components/ThemeProvider.js
@@ -0,0 +1,15 @@
+"use client";
+
+import { useEffect } from "react";
+import useThemeStore from "@/store/themeStore";
+
+export function ThemeProvider({ children }) {
+  const { initTheme } = useThemeStore();
+
+  useEffect(() => {
+    initTheme();
+  }, [initTheme]);
+
+  return <>{children}</>;
+}
+
diff --git a/src/shared/components/ThemeToggle.js b/src/shared/components/ThemeToggle.js
new file mode 100644
index 0000000..4ae9aba
--- /dev/null
+++ b/src/shared/components/ThemeToggle.js
@@ -0,0 +1,42 @@
+"use client";
+
+import { useTheme } from "@/shared/hooks/useTheme";
+import { cn } from "@/shared/utils/cn";
+
+export default function ThemeToggle({ className, variant = "default" }) {
+  const { isDark, toggleTheme } = useTheme();
+
+  const variants = {
+    default: cn(
+      "flex items-center justify-center size-10 rounded-full",
+      "text-text-muted hover:text-text-main",
+      "hover:bg-surface-2 transition-colors"
+    ),
+    card: cn(
+      "flex items-center justify-center size-11 rounded-full",
+      "bg-surface/60 hover:bg-surface",
+      "border border-border",
+      "backdrop-blur-md shadow-sm hover:shadow-[var(--shadow-warm)]",
+      "text-text-muted hover:text-brand-500",
+      "transition-all group"
+    ),
+  };
+
+  return (
+    <button
+      onClick={toggleTheme}
+      className={cn(variants[variant], className)}
+      aria-label={`Switch to ${isDark ? "light" : "dark"} mode`}
+      title={`Switch to ${isDark ? "light" : "dark"} mode`}
+    >
+      <span
+        className={cn(
+          "material-symbols-outlined text-[22px]",
+          variant === "card" && "transition-transform duration-300 group-hover:rotate-12"
+        )}
+      >
+        {isDark ? "light_mode" : "dark_mode"}
+      </span>
+    </button>
+  );
+}
diff --git a/src/shared/components/Toggle.js b/src/shared/components/Toggle.js
new file mode 100644
index 0000000..e9df860
--- /dev/null
+++ b/src/shared/components/Toggle.js
@@ -0,0 +1,69 @@
+"use client";
+
+import { cn } from "@/shared/utils/cn";
+
+export default function Toggle({
+  checked = false,
+  onChange,
+  label,
+  description,
+  disabled = false,
+  size = "md",
+  className,
+}) {
+  const sizes = {
+    sm: { track: "w-8 h-4", thumb: "size-3", translate: "translate-x-4" },
+    md: { track: "w-11 h-6", thumb: "size-5", translate: "translate-x-5" },
+    lg: { track: "w-14 h-7", thumb: "size-6", translate: "translate-x-7" },
+  };
+
+  const handleClick = () => {
+    if (!disabled && onChange) onChange(!checked);
+  };
+
+  return (
+    <div
+      className={cn(
+        "flex items-center gap-3",
+        disabled && "opacity-50 cursor-not-allowed",
+        className
+      )}
+    >
+      <button
+        type="button"
+        role="switch"
+        aria-checked={checked}
+        disabled={disabled}
+        onClick={handleClick}
+        className={cn(
+          "relative inline-flex shrink-0 cursor-pointer rounded-full",
+          "transition-colors duration-200 ease-in-out",
+          "focus:outline-none focus:ring-2 focus:ring-brand-500/30",
+          checked ? "bg-brand-500" : "bg-surface-3",
+          sizes[size].track,
+          disabled && "cursor-not-allowed"
+        )}
+      >
+        <span
+          className={cn(
+            "pointer-events-none inline-block rounded-full bg-white shadow-sm",
+            "transform transition duration-200 ease-in-out",
+            checked ? sizes[size].translate : "translate-x-0.5",
+            sizes[size].thumb,
+            "mt-0.5"
+          )}
+        />
+      </button>
+      {(label || description) && (
+        <div className="flex flex-col">
+          {label && (
+            <span className="text-sm font-medium text-text-main">{label}</span>
+          )}
+          {description && (
+            <span className="text-xs text-text-muted">{description}</span>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/shared/components/Tooltip.js b/src/shared/components/Tooltip.js
new file mode 100644
index 0000000..8473c0c
--- /dev/null
+++ b/src/shared/components/Tooltip.js
@@ -0,0 +1,25 @@
+"use client";
+
+export default function Tooltip({ text, children, position = "top", color }) {
+  const posClass = {
+    top: "bottom-full left-1/2 -translate-x-1/2 mb-1.5",
+    bottom: "top-full left-1/2 -translate-x-1/2 mt-1.5",
+    left: "right-full top-1/2 -translate-y-1/2 mr-1.5",
+    right: "left-full top-1/2 -translate-y-1/2 ml-1.5",
+  }[position];
+
+  const bgStyle = color ? { backgroundColor: color } : {};
+  const bgClass = color ? "" : "bg-gray-900";
+
+  return (
+    <div className="relative inline-flex group/tt">
+      {children}
+      <div
+        className={`pointer-events-none absolute ${posClass} z-50 w-max max-w-56 rounded px-2 py-1 text-[11px] leading-snug ${bgClass} text-white opacity-0 group-hover/tt:opacity-100 transition-opacity duration-150 whitespace-normal`}
+        style={bgStyle}
+      >
+        {text}
+      </div>
+    </div>
+  );
+}
diff --git a/src/shared/components/UsageStats.js b/src/shared/components/UsageStats.js
new file mode 100644
index 0000000..ecab40b
--- /dev/null
+++ b/src/shared/components/UsageStats.js
@@ -0,0 +1,533 @@
+"use client";
+
+import { useState, useEffect, useMemo, useCallback, useRef } from "react";
+import { useSearchParams, useRouter } from "next/navigation";
+import { FREE_PROVIDERS, AI_PROVIDERS } from "@/shared/constants/providers";
+
+// Keep providers without serviceKinds (default LLM) or with "llm" in serviceKinds
+function isLLMProvider(id) {
+  const p = AI_PROVIDERS[id];
+  if (!p?.serviceKinds) return true;
+  return p.serviceKinds.includes("llm");
+}
+import Badge from "./Badge";
+import Card from "./Card";
+import OverviewCards from "@/app/(dashboard)/dashboard/usage/components/OverviewCards";
+import UsageTable, { fmt, fmtTime } from "@/app/(dashboard)/dashboard/usage/components/UsageTable";
+import dynamic from "next/dynamic";
+// Lazy-load: keeps @xyflow/react out of the shared bundle until topology renders
+const ProviderTopology = dynamic(() => import("@/app/(dashboard)/dashboard/usage/components/ProviderTopology"), { ssr: false });
+import UsageChart from "@/app/(dashboard)/dashboard/usage/components/UsageChart";
+
+function timeAgo(timestamp) {
+  const diff = Math.floor((Date.now() - new Date(timestamp)) / 1000);
+  if (diff < 60) return `${diff}s ago`;
+  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
+  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`;
+  return `${Math.floor(diff / 86400)}d ago`;
+}
+
+// Auto-update time display every second without re-rendering parent
+function TimeAgo({ timestamp }) {
+  const [, setTick] = useState(0);
+  
+  useEffect(() => {
+    const timer = setInterval(() => setTick(t => t + 1), 1000);
+    return () => clearInterval(timer);
+  }, []);
+  
+  return <>{timeAgo(timestamp)}</>;
+}
+
+function RecentRequests({ requests = [] }) {
+  return (
+    <Card className="flex min-w-0 flex-col overflow-hidden" padding="sm" style={{ height: 480 }}>
+      {/* Header */}
+      <div className="px-1 py-2 border-b border-border shrink-0">
+        <span className="text-xs font-semibold text-text-muted uppercase tracking-wide">Recent Requests</span>
+      </div>
+
+      {!requests.length ? (
+        <div className="flex-1 flex items-center justify-center text-text-muted text-sm">No requests yet.</div>
+      ) : (
+        <div className="flex-1 overflow-y-auto">
+          <table className="w-full min-w-[300px] border-collapse text-xs">
+            <thead className="sticky top-0 bg-bg z-10">
+              <tr className="border-b border-border">
+                <th className="py-1.5 text-left font-semibold text-text-muted w-2"></th>
+                <th className="py-1.5 text-left font-semibold text-text-muted">Model</th>
+                <th className="py-1.5 text-right font-semibold text-text-muted whitespace-nowrap">In / Out</th>
+                <th className="py-1.5 text-right font-semibold text-text-muted">When</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-border/50">
+              {requests.map((r, i) => {
+                const ok = !r.status || r.status === "ok" || r.status === "success";
+                return (
+                  <tr key={i} className="hover:bg-bg-subtle transition-colors">
+                    <td className="py-1.5">
+                      <span className={`block w-1.5 h-1.5 rounded-full ${ok ? "bg-success" : "bg-error"}`} />
+                    </td>
+                    <td className="py-1.5 font-mono truncate max-w-[120px]" title={r.model}>{r.model}</td>
+                    <td className="py-1.5 text-right whitespace-nowrap">
+                      <span className="text-primary">{fmt(r.promptTokens)}↑</span>
+                      {" "}
+                      <span className="text-success">{fmt(r.completionTokens)}↓</span>
+                    </td>
+                    <td className="py-1.5 text-right text-text-muted whitespace-nowrap"><TimeAgo timestamp={r.timestamp} /></td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </Card>
+  );
+}
+
+function sortData(dataMap, pendingMap = {}, sortBy, sortOrder) {
+  return Object.entries(dataMap || {})
+    .map(([key, data]) => {
+      const totalTokens = (data.promptTokens || 0) + (data.completionTokens || 0);
+      const totalCost = data.cost || 0;
+      // ponytail: cost split is a token-share allocation of the (rate-accurate)
+      // server total, not a per-rate recompute. cached is a subset of prompt, so
+      // peel it out of the input share. Upgrade to a stored per-component cost
+      // breakdown if exact cached-rate cost display is needed.
+      const cachedTokens = data.cachedTokens || 0;
+      const nonCachedInput = Math.max(0, (data.promptTokens || 0) - cachedTokens);
+      const inputCost = totalTokens > 0 ? nonCachedInput * (totalCost / totalTokens) : 0;
+      const cachedCost = totalTokens > 0 ? cachedTokens * (totalCost / totalTokens) : 0;
+      const outputCost = totalTokens > 0 ? (data.completionTokens || 0) * (totalCost / totalTokens) : 0;
+      return { ...data, key, totalTokens, totalCost, inputCost, cachedCost, outputCost, pending: pendingMap[key] || 0 };
+    })
+    .sort((a, b) => {
+      let valA = a[sortBy];
+      let valB = b[sortBy];
+      if (typeof valA === "string") valA = valA.toLowerCase();
+      if (typeof valB === "string") valB = valB.toLowerCase();
+      if (valA < valB) return sortOrder === "asc" ? -1 : 1;
+      if (valA > valB) return sortOrder === "asc" ? 1 : -1;
+      return 0;
+    });
+}
+
+function getGroupKey(item, keyField) {
+  switch (keyField) {
+    case "rawModel": return item.rawModel || "Unknown Model";
+    case "accountName": return item.accountName || `Account ${item.connectionId?.slice(0, 8)}...` || "Unknown Account";
+    case "keyName": return item.keyName || "Unknown Key";
+    case "endpoint": return item.endpoint || "Unknown Endpoint";
+    default: return item[keyField] || "Unknown";
+  }
+}
+
+function groupDataByKey(data, keyField) {
+  if (!Array.isArray(data)) return [];
+  const groups = {};
+  data.forEach((item) => {
+    const gk = getGroupKey(item, keyField);
+    if (!groups[gk]) {
+      groups[gk] = {
+        groupKey: gk,
+        summary: { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, totalTokens: 0, cost: 0, inputCost: 0, cachedCost: 0, outputCost: 0, lastUsed: null, pending: 0 },
+        items: [],
+      };
+    }
+    const s = groups[gk].summary;
+    s.requests += item.requests || 0;
+    s.promptTokens += item.promptTokens || 0;
+    s.completionTokens += item.completionTokens || 0;
+    s.cachedTokens += item.cachedTokens || 0;
+    s.totalTokens += item.totalTokens || 0;
+    s.cost += item.cost || 0;
+    s.inputCost += item.inputCost || 0;
+    s.cachedCost += item.cachedCost || 0;
+    s.outputCost += item.outputCost || 0;
+    s.pending += item.pending || 0;
+    if (item.lastUsed && (!s.lastUsed || new Date(item.lastUsed) > new Date(s.lastUsed))) {
+      s.lastUsed = item.lastUsed;
+    }
+    groups[gk].items.push(item);
+  });
+  return Object.values(groups);
+}
+
+const MODEL_COLUMNS = [
+  { field: "rawModel", label: "Model" },
+  { field: "provider", label: "Provider" },
+  { field: "requests", label: "Requests", align: "right" },
+  { field: "lastUsed", label: "Last Used", align: "right" },
+];
+
+const ACCOUNT_COLUMNS = [
+  { field: "rawModel", label: "Model" },
+  { field: "provider", label: "Provider" },
+  { field: "accountName", label: "Account" },
+  { field: "requests", label: "Requests", align: "right" },
+  { field: "lastUsed", label: "Last Used", align: "right" },
+];
+
+const API_KEY_COLUMNS = [
+  { field: "keyName", label: "API Key Name" },
+  { field: "rawModel", label: "Model" },
+  { field: "provider", label: "Provider" },
+  { field: "requests", label: "Requests", align: "right" },
+  { field: "lastUsed", label: "Last Used", align: "right" },
+];
+
+const ENDPOINT_COLUMNS = [
+  { field: "endpoint", label: "Endpoint" },
+  { field: "rawModel", label: "Model" },
+  { field: "provider", label: "Provider" },
+  { field: "requests", label: "Requests", align: "right" },
+  { field: "lastUsed", label: "Last Used", align: "right" },
+];
+
+const TABLE_OPTIONS = [
+  { value: "model", label: "Usage by Model" },
+  { value: "account", label: "Usage by Account" },
+  { value: "apiKey", label: "Usage by API Key" },
+  { value: "endpoint", label: "Usage by Endpoint" },
+];
+
+const PERIODS = [
+  { value: "today", label: "Today" },
+  { value: "24h", label: "24h" },
+  { value: "7d", label: "7D" },
+  { value: "30d", label: "30D" },
+  { value: "60d", label: "60D" },
+];
+
+export default function UsageStats({ period: periodProp, setPeriod: setPeriodProp, hidePeriodSelector = false } = {}) {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+
+  const sortBy = searchParams.get("sortBy") || "rawModel";
+  const sortOrder = searchParams.get("sortOrder") || "asc";
+
+  const [stats, setStats] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [fetching, setFetching] = useState(false);
+  const [tableView, setTableView] = useState("model");
+  const [viewMode, setViewMode] = useState("costs");
+  const [providers, setProviders] = useState([]);
+  const [periodLocal, setPeriodLocal] = useState("today");
+  const isInitialLoad = useRef(true);
+  const hasLoadedStats = useRef(false);
+  const period = periodProp ?? periodLocal;
+  const setPeriod = setPeriodProp ?? setPeriodLocal;
+
+  // Fetch connected providers once, deduplicate by provider type
+  // Always include noAuth free providers (e.g. opencode) regardless of connections
+  useEffect(() => {
+    Promise.all([
+      fetch("/api/providers").then((r) => r.ok ? r.json() : null),
+      fetch("/api/provider-nodes").then((r) => r.ok ? r.json() : null),
+    ])
+      .then(([d, nodesData]) => {
+        // Build node name lookup for custom providers
+        const nodeNameMap = {};
+        for (const node of (nodesData?.nodes || [])) {
+          nodeNameMap[node.id] = node.name;
+        }
+        const seen = new Set();
+        const unique = (d?.connections || []).filter((c) => {
+          if (c.isActive === false) return false;
+          if (!isLLMProvider(c.provider)) return false;
+          if (seen.has(c.provider)) return false;
+          seen.add(c.provider);
+          return true;
+        }).map((c) => ({
+          ...c,
+          nodeName: nodeNameMap[c.provider] || null,
+        }));
+        const noAuthProviders = Object.values(FREE_PROVIDERS)
+          .filter((p) => p.noAuth && !seen.has(p.id) && isLLMProvider(p.id))
+          .map((p) => ({ provider: p.id, name: p.name }));
+        setProviders([...unique, ...noAuthProviders]);
+      })
+      .catch(() => {});
+  }, []);
+
+  // Fetch filtered stats via REST when period changes
+  useEffect(() => {
+    // First load: show full spinner; subsequent: show subtle fetching indicator
+    if (isInitialLoad.current) {
+      isInitialLoad.current = false;
+      setLoading(true);
+    } else {
+      setFetching(true);
+    }
+
+    fetch(`/api/usage/stats?period=${period}`)
+      .then((r) => r.ok ? r.json() : null)
+      .then((data) => {
+        if (data) {
+          hasLoadedStats.current = true;
+          setStats((prev) => ({ ...prev, ...data }));
+        }
+      })
+      .catch(() => {})
+      .finally(() => {
+        setLoading(false);
+        setFetching(false);
+      });
+  }, [period]);
+
+  // SSE connection - real-time updates for activeRequests + recentRequests only
+  useEffect(() => {
+    const es = new EventSource("/api/usage/stream");
+
+    es.onmessage = (e) => {
+      try {
+        const data = JSON.parse(e.data);
+        // Always merge only real-time fields, never overwrite full stats from REST
+        setStats((prev) => {
+          if (!prev) return prev;
+          return {
+            ...prev,
+            activeRequests: data.activeRequests,
+            recentRequests: data.recentRequests,
+            errorProvider: data.errorProvider,
+            pending: data.pending,
+          };
+        });
+        if (hasLoadedStats.current) setLoading(false);
+      } catch (err) {
+        console.error("[SSE CLIENT] parse error:", err);
+      }
+    };
+
+    es.onerror = () => setLoading(false);
+
+    return () => es.close();
+  }, []);
+
+  const toggleSort = useCallback((tableType, field) => {
+    const params = new URLSearchParams(searchParams.toString());
+    if (params.get("sortBy") === field) {
+      params.set("sortOrder", params.get("sortOrder") === "asc" ? "desc" : "asc");
+    } else {
+      params.set("sortBy", field);
+      params.set("sortOrder", "asc");
+    }
+    router.replace(`?${params.toString()}`, { scroll: false });
+  }, [searchParams, router]);
+
+  // Compute active table data
+  const activeTableConfig = useMemo(() => {
+    if (!stats) return null;
+    switch (tableView) {
+      case "model": {
+        const pendingMap = stats.pending?.byModel || {};
+        return {
+          columns: MODEL_COLUMNS,
+          groupedData: groupDataByKey(sortData(stats.byModel, pendingMap, sortBy, sortOrder), "rawModel"),
+          storageKey: "usage-stats:expanded-models",
+          emptyMessage: "No usage recorded yet.",
+          renderSummaryCells: (group) => (
+            <>
+              <td className="px-6 py-3 text-text-muted">—</td>
+              <td className="px-6 py-3 text-right">{fmt(group.summary.requests)}</td>
+              <td className="px-6 py-3 text-right text-text-muted whitespace-nowrap">{fmtTime(group.summary.lastUsed)}</td>
+            </>
+          ),
+          renderDetailCells: (item) => (
+            <>
+              <td className={`px-6 py-3 font-medium transition-colors ${item.pending > 0 ? "text-primary" : ""}`}>{item.rawModel}</td>
+              <td className="px-6 py-3"><Badge variant={item.pending > 0 ? "primary" : "neutral"} size="sm">{item.provider}</Badge></td>
+              <td className="px-6 py-3 text-right">{fmt(item.requests)}</td>
+              <td className="px-6 py-3 text-right text-text-muted whitespace-nowrap">{fmtTime(item.lastUsed)}</td>
+            </>
+          ),
+        };
+      }
+      case "account": {
+        const pendingMap = {};
+        if (stats?.pending?.byAccount) {
+          Object.entries(stats.byAccount || {}).forEach(([accountKey, data]) => {
+            const connPending = stats.pending.byAccount[data.connectionId];
+            if (connPending) {
+              const modelKey = data.provider ? `${data.rawModel} (${data.provider})` : data.rawModel;
+              pendingMap[accountKey] = connPending[modelKey] || 0;
+            }
+          });
+        }
+        return {
+          columns: ACCOUNT_COLUMNS,
+          groupedData: groupDataByKey(sortData(stats.byAccount, pendingMap, sortBy, sortOrder), "accountName"),
+          storageKey: "usage-stats:expanded-accounts",
+          emptyMessage: "No account-specific usage recorded yet.",
+          renderSummaryCells: (group) => (
+            <>
+              <td className="px-6 py-3 text-text-muted">—</td>
+              <td className="px-6 py-3 text-text-muted">—</td>
+              <td className="px-6 py-3 text-right">{fmt(group.summary.requests)}</td>
+              <td className="px-6 py-3 text-right text-text-muted whitespace-nowrap">{fmtTime(group.summary.lastUsed)}</td>
+            </>
+          ),
+          renderDetailCells: (item) => (
+            <>
+              <td className={`px-6 py-3 font-medium transition-colors ${item.pending > 0 ? "text-primary" : ""}`}>{item.accountName || `Account ${item.connectionId?.slice(0, 8)}...`}</td>
+              <td className={`px-6 py-3 font-medium transition-colors ${item.pending > 0 ? "text-primary" : ""}`}>{item.rawModel}</td>
+              <td className="px-6 py-3"><Badge variant={item.pending > 0 ? "primary" : "neutral"} size="sm">{item.provider}</Badge></td>
+              <td className="px-6 py-3 text-right">{fmt(item.requests)}</td>
+              <td className="px-6 py-3 text-right text-text-muted whitespace-nowrap">{fmtTime(item.lastUsed)}</td>
+            </>
+          ),
+        };
+      }
+      case "apiKey": {
+        return {
+          columns: API_KEY_COLUMNS,
+          groupedData: groupDataByKey(sortData(stats.byApiKey, {}, sortBy, sortOrder), "keyName"),
+          storageKey: "usage-stats:expanded-apikeys",
+          emptyMessage: "No API key usage recorded yet.",
+          renderSummaryCells: (group) => (
+            <>
+              <td className="px-6 py-3 text-text-muted">—</td>
+              <td className="px-6 py-3 text-text-muted">—</td>
+              <td className="px-6 py-3 text-right">{fmt(group.summary.requests)}</td>
+              <td className="px-6 py-3 text-right text-text-muted whitespace-nowrap">{fmtTime(group.summary.lastUsed)}</td>
+            </>
+          ),
+          renderDetailCells: (item) => (
+            <>
+              <td className="px-6 py-3 font-medium">{item.keyName}</td>
+              <td className="px-6 py-3">{item.rawModel}</td>
+              <td className="px-6 py-3"><Badge variant="neutral" size="sm">{item.provider}</Badge></td>
+              <td className="px-6 py-3 text-right">{fmt(item.requests)}</td>
+              <td className="px-6 py-3 text-right text-text-muted whitespace-nowrap">{fmtTime(item.lastUsed)}</td>
+            </>
+          ),
+        };
+      }
+      case "endpoint":
+      default: {
+        return {
+          columns: ENDPOINT_COLUMNS,
+          groupedData: groupDataByKey(sortData(stats.byEndpoint, {}, sortBy, sortOrder), "endpoint"),
+          storageKey: "usage-stats:expanded-endpoints",
+          emptyMessage: "No endpoint usage recorded yet.",
+          renderSummaryCells: (group) => (
+            <>
+              <td className="px-6 py-3 text-text-muted">—</td>
+              <td className="px-6 py-3 text-text-muted">—</td>
+              <td className="px-6 py-3 text-right">{fmt(group.summary.requests)}</td>
+              <td className="px-6 py-3 text-right text-text-muted whitespace-nowrap">{fmtTime(group.summary.lastUsed)}</td>
+            </>
+          ),
+          renderDetailCells: (item) => (
+            <>
+              <td className="px-6 py-3 font-medium font-mono text-sm">{item.endpoint}</td>
+              <td className="px-6 py-3">{item.rawModel}</td>
+              <td className="px-6 py-3"><Badge variant="neutral" size="sm">{item.provider}</Badge></td>
+              <td className="px-6 py-3 text-right">{fmt(item.requests)}</td>
+              <td className="px-6 py-3 text-right text-text-muted whitespace-nowrap">{fmtTime(item.lastUsed)}</td>
+            </>
+          ),
+        };
+      }
+    }
+  }, [stats, tableView, sortBy, sortOrder]);
+
+  if (!stats && !loading) return <div className="text-text-muted">Failed to load usage statistics.</div>;
+
+  const spinner = (
+    <div className="flex items-center justify-center py-12 text-text-muted">
+      <span className="material-symbols-outlined text-[32px] animate-spin">progress_activity</span>
+    </div>
+  );
+
+  return (
+    <div className="flex min-w-0 flex-col gap-6">
+      {/* Period selector (hidden when controlled by parent) */}
+      {!hidePeriodSelector && (
+        <div className="flex w-full items-center gap-2 sm:w-auto sm:self-end">
+          <div className="grid flex-1 grid-cols-5 items-center gap-1 rounded-lg border border-border bg-bg-subtle p-1 sm:flex sm:flex-none">
+            {PERIODS.map((p) => (
+              <button
+                key={p.value}
+                onClick={() => setPeriod(p.value)}
+                disabled={fetching}
+                className={`rounded-md px-3 py-1 text-sm font-medium transition-colors ${period === p.value ? "bg-primary text-white shadow-sm" : "text-text-muted hover:bg-bg-hover hover:text-text"}`}
+              >
+                {p.label}
+              </button>
+            ))}
+          </div>
+          {fetching && (
+            <span className="material-symbols-outlined text-[16px] text-text-muted animate-spin">progress_activity</span>
+          )}
+        </div>
+      )}
+
+      {/* Overview cards */}
+      {loading ? spinner : <OverviewCards stats={stats} />}
+
+      {/* Provider topology + Recent Requests */}
+      {loading ? spinner : (
+        <div className="grid min-w-0 grid-cols-1 items-stretch gap-2 lg:grid-cols-[minmax(0,2fr)_minmax(280px,1fr)]">
+          <ProviderTopology
+            providers={providers}
+            activeRequests={stats.activeRequests || []}
+            lastProvider={stats.recentRequests?.[0]?.provider || ""}
+            errorProvider={stats.errorProvider || ""}
+          />
+          <RecentRequests requests={stats.recentRequests || []} />
+        </div>
+      )}
+
+      {/* Token / Cost chart - sync period */}
+      {loading ? spinner : <UsageChart period={period} />}
+
+      {/* Table with dropdown selector */}
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+          <select
+            value={tableView}
+            onChange={(e) => setTableView(e.target.value)}
+            className="w-full rounded-lg border border-border bg-surface px-3 py-1.5 text-sm font-medium text-text-main focus:outline-none focus:ring-2 focus:ring-primary/50 sm:w-auto"
+            style={{ colorScheme: 'auto' }}
+          >
+            {TABLE_OPTIONS.map((opt) => (
+              <option key={opt.value} value={opt.value}>{opt.label}</option>
+            ))}
+          </select>
+          <div className="grid grid-cols-2 items-center gap-1 rounded-lg border border-border bg-bg-subtle p-1 sm:flex">
+            <button
+              onClick={() => setViewMode("costs")}
+              className={`px-3 py-1 rounded-md text-sm font-medium transition-colors ${viewMode === "costs" ? "bg-primary text-white shadow-sm" : "text-text-muted hover:text-text hover:bg-bg-hover"}`}
+            >
+              Costs
+            </button>
+            <button
+              onClick={() => setViewMode("tokens")}
+              className={`px-3 py-1 rounded-md text-sm font-medium transition-colors ${viewMode === "tokens" ? "bg-primary text-white shadow-sm" : "text-text-muted hover:text-text hover:bg-bg-hover"}`}
+            >
+              Tokens
+            </button>
+          </div>
+        </div>
+        {loading ? spinner : activeTableConfig && (
+          <UsageTable
+            title=""
+            columns={activeTableConfig.columns}
+            groupedData={activeTableConfig.groupedData}
+            tableType={tableView}
+            sortBy={sortBy}
+            sortOrder={sortOrder}
+            onToggleSort={toggleSort}
+            viewMode={viewMode}
+            storageKey={activeTableConfig.storageKey}
+            renderSummaryCells={activeTableConfig.renderSummaryCells}
+            renderDetailCells={activeTableConfig.renderDetailCells}
+            emptyMessage={activeTableConfig.emptyMessage}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/shared/components/index.js b/src/shared/components/index.js
new file mode 100644
index 0000000..c04453a
--- /dev/null
+++ b/src/shared/components/index.js
@@ -0,0 +1,44 @@
+// Shared Components - Export all
+export { default as Button } from "./Button";
+export { default as Input } from "./Input";
+export { default as Select } from "./Select";
+export { default as Card } from "./Card";
+export { default as Modal, ConfirmModal } from "./Modal";
+export { default as Loading, Spinner, PageLoading, Skeleton, CardSkeleton } from "./Loading";
+export { default as Avatar } from "./Avatar";
+export { default as Badge } from "./Badge";
+export { default as Toggle } from "./Toggle";
+export { default as ThemeToggle } from "./ThemeToggle";
+export { ThemeProvider } from "./ThemeProvider";
+export { default as Sidebar } from "./Sidebar";
+export { default as Header } from "./Header";
+export { default as Footer } from "./Footer";
+export { default as OAuthModal } from "./OAuthModal";
+export { default as ModelSelectModal } from "./ModelSelectModal";
+export { default as ManualConfigModal } from "./ManualConfigModal";
+export { default as ComboFormModal } from "./ComboFormModal";
+export { default as McpMarketplaceModal } from "./McpMarketplaceModal";
+export { default as UsageStats } from "./UsageStats";
+export { default as LanguageSwitcher } from "./LanguageSwitcher";
+export { default as NineRemoteButton } from "./NineRemoteButton";
+export { default as HeaderMenu } from "./HeaderMenu";
+export { default as ChangelogModal } from "./ChangelogModal";
+export { default as RequestLogger } from "./RequestLogger";
+export { default as KiroAuthModal } from "./KiroAuthModal";
+export { default as KiroOAuthWrapper } from "./KiroOAuthWrapper";
+export { default as KiroSocialOAuthModal } from "./KiroSocialOAuthModal";
+export { default as CursorAuthModal } from "./CursorAuthModal";
+export { default as IFlowCookieModal } from "./IFlowCookieModal";
+export { default as GitLabAuthModal } from "./GitLabAuthModal";
+export { default as EditConnectionModal } from "./EditConnectionModal";
+export { default as AddCustomEmbeddingModal } from "./AddCustomEmbeddingModal";
+export { default as NoAuthProxyCard } from "./NoAuthProxyCard";
+export { default as SegmentedControl } from "./SegmentedControl";
+export { default as Tooltip } from "./Tooltip";
+export { default as ProviderInfoCard } from "./ProviderInfoCard";
+export { default as CapacityBadges } from "./CapacityBadges";
+
+// Layouts
+export * from "./layouts";
+
+
diff --git a/src/shared/components/layouts/AuthLayout.js b/src/shared/components/layouts/AuthLayout.js
new file mode 100644
index 0000000..790bda2
--- /dev/null
+++ b/src/shared/components/layouts/AuthLayout.js
@@ -0,0 +1,29 @@
+"use client";
+
+import PropTypes from "prop-types";
+import ThemeToggle from "../ThemeToggle";
+
+export default function AuthLayout({ children }) {
+  return (
+    <div className="min-h-screen flex flex-col relative bg-bg transition-colors duration-500 overflow-x-hidden selection:bg-primary/20 selection:text-primary">
+      {/* Background effects */}
+      <div className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[800px] h-[800px] bg-primary/5 dark:bg-primary/5 rounded-full blur-[100px] pointer-events-none z-0" />
+      <div className="fixed bottom-0 right-0 w-[600px] h-[600px] bg-orange-200/20 dark:bg-orange-900/10 rounded-full blur-[120px] pointer-events-none z-0 translate-y-1/3 translate-x-1/3" />
+
+      {/* Theme toggle */}
+      <div className="absolute top-6 right-6 z-20">
+        <ThemeToggle variant="card" />
+      </div>
+
+      {/* Content */}
+      <main className="flex-1 flex flex-col items-center justify-center p-4 sm:p-6 z-10 w-full h-full">
+        {children}
+      </main>
+    </div>
+  );
+}
+
+AuthLayout.propTypes = {
+  children: PropTypes.node.isRequired,
+};
+
diff --git a/src/shared/components/layouts/DashboardLayout.js b/src/shared/components/layouts/DashboardLayout.js
new file mode 100644
index 0000000..aa555bd
--- /dev/null
+++ b/src/shared/components/layouts/DashboardLayout.js
@@ -0,0 +1,104 @@
+"use client";
+
+import { useState } from "react";
+import { usePathname } from "next/navigation";
+import { useNotificationStore } from "@/store/notificationStore";
+import Sidebar from "../Sidebar";
+import Header from "../Header";
+
+function getToastStyle(type) {
+  if (type === "success") {
+    return {
+      wrapper: "border-green-500/30 bg-green-500/10 text-green-600 dark:text-green-400",
+      icon: "check_circle",
+    };
+  }
+  if (type === "error") {
+    return {
+      wrapper: "border-red-500/30 bg-red-500/10 text-red-600 dark:text-red-400",
+      icon: "error",
+    };
+  }
+  if (type === "warning") {
+    return {
+      wrapper: "border-amber-500/30 bg-amber-500/10 text-amber-600 dark:text-amber-400",
+      icon: "warning",
+    };
+  }
+  return {
+    wrapper: "border-blue-500/30 bg-blue-500/10 text-blue-600 dark:text-blue-400",
+    icon: "info",
+  };
+}
+
+export default function DashboardLayout({ children }) {
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+  const pathname = usePathname();
+  const notifications = useNotificationStore((state) => state.notifications);
+  const removeNotification = useNotificationStore((state) => state.removeNotification);
+
+  return (
+    <div className="flex h-screen w-full overflow-hidden bg-bg">
+      <div className="fixed top-4 right-4 z-[80] flex w-[min(92vw,380px)] flex-col gap-2">
+        {notifications.map((n) => {
+          const style = getToastStyle(n.type);
+          return (
+            <div
+              key={n.id}
+              className={`rounded-lg border px-3 py-2 shadow-lg backdrop-blur-sm ${style.wrapper}`}
+            >
+              <div className="flex items-start gap-2">
+                <span className="material-symbols-outlined text-[18px] leading-5">{style.icon}</span>
+                <div className="min-w-0 flex-1">
+                  {n.title ? <p className="text-xs font-semibold mb-0.5">{n.title}</p> : null}
+                  <p className="text-xs whitespace-pre-wrap break-words">{n.message}</p>
+                </div>
+                {n.dismissible ? (
+                  <button
+                    type="button"
+                    onClick={() => removeNotification(n.id)}
+                    className="text-current/70 hover:text-current"
+                    aria-label="Dismiss notification"
+                  >
+                    <span className="material-symbols-outlined text-[16px]">close</span>
+                  </button>
+                ) : null}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+      {/* Mobile sidebar overlay */}
+      {sidebarOpen && (
+        <div
+          className="fixed inset-0 z-40 bg-black/20 lg:hidden"
+          onClick={() => setSidebarOpen(false)}
+        />
+      )}
+
+      {/* Sidebar - Desktop */}
+      <div className="hidden lg:flex">
+        <Sidebar />
+      </div>
+
+      {/* Sidebar - Mobile */}
+      <div
+        className={`fixed inset-y-0 left-0 z-50 transform lg:hidden transition-transform duration-300 ease-in-out ${
+          sidebarOpen ? "translate-x-0" : "-translate-x-full"
+        }`}
+      >
+        <Sidebar onClose={() => setSidebarOpen(false)} />
+      </div>
+
+      {/* Main content */}
+      <main className="flex flex-col flex-1 h-full min-w-0 relative transition-colors duration-300 isolate">
+        {/* Faint grid background */}
+        <div className="landing-grid absolute inset-0 pointer-events-none -z-10" aria-hidden="true" />
+        <Header key={pathname} onMenuClick={() => setSidebarOpen(true)} />
+        <div className={`flex-1 overflow-y-auto custom-scrollbar ${pathname === "/dashboard/basic-chat" ? "" : "p-6 lg:p-10"} ${pathname === "/dashboard/basic-chat" ? "flex flex-col overflow-hidden" : ""}`}>
+          <div className={`${pathname === "/dashboard/basic-chat" ? "flex-1 w-full h-full flex flex-col" : "max-w-7xl mx-auto"}`}>{children}</div>
+        </div>
+      </main>
+    </div>
+  );
+}
diff --git a/src/shared/components/layouts/index.js b/src/shared/components/layouts/index.js
new file mode 100644
index 0000000..4b6ac5f
--- /dev/null
+++ b/src/shared/components/layouts/index.js
@@ -0,0 +1,4 @@
+// Layout Components - Export all
+export { default as DashboardLayout } from "./DashboardLayout";
+export { default as AuthLayout } from "./AuthLayout";
+
diff --git a/src/shared/constants/cliTools.js b/src/shared/constants/cliTools.js
new file mode 100644
index 0000000..b9d000c
--- /dev/null
+++ b/src/shared/constants/cliTools.js
@@ -0,0 +1,396 @@
+// MITM Tools — IDE tools intercepted via MITM proxy
+export const MITM_TOOLS = {
+  antigravity: {
+    id: "antigravity",
+    name: "Antigravity",
+    image: "/providers/antigravity.png",
+    color: "#4285F4",
+    description: "Google Antigravity IDE with MITM",
+    configType: "mitm",
+    mitmDomain: "daily-cloudcode-pa.googleapis.com",
+    modelAliases: ["gemini-3.5-flash-low", "gemini-3-flash-agent", "gemini-3.5-flash-extra-low", "gemini-3.1-pro-low", "gemini-pro-agent", "claude-sonnet-4-6", "claude-opus-4-6-thinking", "gpt-oss-120b-medium", "gemini-3-flash"],
+    defaultModels: [
+      { id: "gemini-3.5-flash-low", name: "Gemini 3.5 Flash (Medium) / Default", alias: "gemini-3.5-flash-low" },
+      { id: "gemini-3-flash-agent", name: "Gemini 3.5 Flash (High)", alias: "gemini-3-flash-agent" },
+      { id: "gemini-3.5-flash-extra-low", name: "Gemini 3.5 Flash (Low)", alias: "gemini-3.5-flash-extra-low" },
+      { id: "gemini-3.1-pro-low", name: "Gemini 3.1 Pro (Low)", alias: "gemini-3.1-pro-low" },
+      { id: "gemini-pro-agent", name: "Gemini 3.1 Pro (High)", alias: "gemini-pro-agent" },
+      { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6 (Thinking)", alias: "claude-sonnet-4-6" },
+      { id: "claude-opus-4-6-thinking", name: "Claude Opus 4.6 (Thinking)", alias: "claude-opus-4-6-thinking" },
+      { id: "gpt-oss-120b-medium", name: "GPT-OSS 120B (Medium)", alias: "gpt-oss-120b-medium" },
+      { id: "gemini-3-flash", name: "Gemini 3 Flash (Command)", alias: "gemini-3-flash" },
+    ],
+  },
+  copilot: {
+    id: "copilot",
+    name: "GitHub Copilot",
+    image: "/providers/copilot.png",
+    color: "#1F6FEB",
+    description: "GitHub Copilot IDE with MITM",
+    configType: "mitm",
+    mitmDomain: "api.individual.githubcopilot.com",
+    modelAliases: ["gpt-5-mini", "gpt-5.4-nano", "claude-haiku-4.5", "gpt-4o", "gpt-4.1"],
+    defaultModels: [
+      // Verified via live MITM passthrough capture of the GitHub Copilot CLI: its model
+      // picker offers "GPT-5 mini" (default → wire id "gpt-5-mini"), "Claude Haiku 4.5"
+      // ("claude-haiku-4.5") and "Auto". "Auto" is NOT a wire id — Copilot dispatches
+      // concrete models dynamically (observed "gpt-5.4-nano" for light tasks and
+      // "claude-haiku-4.5"), so it needs no slot of its own. Without a slot for
+      // gpt-5-mini / gpt-5.4-nano, getMappedModel returns null and the /chat/completions
+      // call is passed through to GitHub Copilot instead of the configured provider —
+      // and gpt-5-mini is the CLI default, so the primary turn leaks (same class as the
+      // Kiro "auto" misrouting). gpt-4o / gpt-4.1 are kept for the VS Code Copilot Chat picker.
+      { id: "gpt-5-mini", name: "GPT-5 mini", alias: "gpt-5-mini" },
+      { id: "gpt-5.4-nano", name: "GPT-5.4 nano", alias: "gpt-5.4-nano" },
+      { id: "claude-haiku-4.5", name: "Claude Haiku 4.5", alias: "claude-haiku-4.5" },
+      { id: "gpt-4o", name: "GPT-4o", alias: "gpt-4o" },
+      { id: "gpt-4.1", name: "GPT-4.1", alias: "gpt-4.1" },
+    ],
+  },
+  kiro: {
+    id: "kiro",
+    name: "Kiro",
+    image: "/providers/kiro.png",
+    color: "#FF6B00",
+    description: "Kiro IDE with MITM",
+    configType: "mitm",
+    mitmDomain: "q.us-east-1.amazonaws.com",
+    defaultModels: [
+      { id: "claude-sonnet-5", name: "Claude Sonnet 5", alias: "claude-sonnet-5" },
+      { id: "claude-sonnet-4.5", name: "Claude Sonnet 4.5", alias: "claude-sonnet-4.5" },
+      { id: "claude-sonnet-4", name: "Claude Sonnet 4", alias: "claude-sonnet-4" },
+      { id: "claude-haiku-4.5", name: "Claude Haiku 4.5", alias: "claude-haiku-4.5" },
+      { id: "deepseek-3.2", name: "DeepSeek 3.2", alias: "deepseek-3.2" },
+      { id: "minimax-m2.1", name: "MiniMax M2.1", alias: "minimax-m2.1" },
+      { id: "simple-task", name: "Qwen3 Coder Next", alias: "simple-task" },
+    ],
+  },
+  // cursor: {
+  //   id: "cursor",
+  //   name: "Cursor",
+  //   image: "/providers/cursor.png",
+  //   color: "#000000",
+  //   description: "Cursor IDE with MITM",
+  //   configType: "mitm",
+  //   mitmDomain: "api2.cursor.sh",
+  //   defaultModels: [
+  //     { id: "claude-sonnet-4-5", name: "Claude Sonnet 4.5", alias: "claude-sonnet-4-5" },
+  //     { id: "claude-opus-4", name: "Claude Opus 4", alias: "claude-opus-4" },
+  //     { id: "gpt-4o", name: "GPT-4o", alias: "gpt-4o" },
+  //   ],
+  // },
+};
+
+// CLI Tools configuration
+export const CLI_TOOLS = {
+  claude: {
+    id: "claude",
+    name: "Claude Code",
+    image: "/providers/claude.png",
+    color: "#D97757",
+    description: "Anthropic Claude Code CLI",
+    configType: "env",
+    envVars: {
+      baseUrl: "ANTHROPIC_BASE_URL",
+      model: "ANTHROPIC_MODEL",
+      opusModel: "ANTHROPIC_DEFAULT_OPUS_MODEL",
+      sonnetModel: "ANTHROPIC_DEFAULT_SONNET_MODEL",
+      fableModel: "ANTHROPIC_DEFAULT_FABLE_MODEL",
+      haikuModel: "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+    },
+    modelAliases: ["default", "sonnet", "opus", "fable", "haiku", "opusplan"],
+    settingsFile: "~/.claude/settings.json",
+    defaultModels: [
+      { id: "fable", name: "Claude Fable", alias: "fable", envKey: "ANTHROPIC_DEFAULT_FABLE_MODEL", defaultValue: "cc/claude-fable-5" },
+      { id: "opus", name: "Claude Opus", alias: "opus", envKey: "ANTHROPIC_DEFAULT_OPUS_MODEL", defaultValue: "cc/claude-opus-4-8" },
+      { id: "sonnet", name: "Claude Sonnet", alias: "sonnet", envKey: "ANTHROPIC_DEFAULT_SONNET_MODEL", defaultValue: "cc/claude-sonnet-5" },
+      { id: "haiku", name: "Claude Haiku", alias: "haiku", envKey: "ANTHROPIC_DEFAULT_HAIKU_MODEL", defaultValue: "cc/claude-haiku-4-5-20251001" },
+    ],
+  },
+  openclaw: {
+    id: "openclaw",
+    name: "Open Claw",
+    image: "/providers/openclaw.png",
+    color: "#FF6B35",
+    description: "Open Claw AI Assistant",
+    configType: "custom",
+  },
+  codex: {
+    id: "codex",
+    name: "OpenAI Codex CLI / App",
+    image: "/providers/codex.png",
+    color: "#10A37F",
+    description: "OpenAI Codex CLI",
+    configType: "custom",
+  },
+  opencode: {
+    id: "opencode",
+    name: "OpenCode",
+    image: "/providers/opencode.png",
+    color: "#E87040",
+    description: "OpenCode AI Terminal Assistant",
+    configType: "custom",
+  },
+  cowork: {
+    id: "cowork",
+    name: "Claude Cowork",
+    image: "/providers/claude.png",
+    color: "#D97757",
+    description: "Claude Desktop Cowork (third-party inference)",
+    configType: "custom",
+  },
+  hermes: {
+    id: "hermes",
+    name: "Hermes Agent",
+    image: "/providers/hermes.png",
+    color: "#8B5CF6",
+    description: "Nous Research self-improving AI agent",
+    configType: "custom",
+  },
+  droid: {
+    id: "droid",
+    name: "Factory Droid",
+    image: "/providers/droid.png",
+    color: "#00D4FF",
+    description: "Factory Droid AI Assistant",
+    configType: "custom",
+  },
+  cursor: {
+    id: "cursor",
+    name: "Cursor",
+    image: "/providers/cursor.png",
+    color: "#000000",
+    description: "Cursor AI Code Editor",
+    configType: "guide",
+    requiresExternalUrl: true,
+    notes: [
+      { type: "warning", text: "Requires Cursor Pro account to use this feature." },
+      { type: "cloudCheck", text: "Cursor routes requests through its own server, so local endpoint is not supported. Please enable Tunnel or Cloud Endpoint in Settings." },
+    ],
+    guideSteps: [
+      { step: 1, title: "Open Settings", desc: "Go to Settings → Models" },
+      { step: 2, title: "Enable OpenAI API", desc: "Enable \"OpenAI API key\" option" },
+      { step: 3, title: "Base URL", value: "{{baseUrl}}", copyable: true },
+      { step: 4, title: "API Key", type: "apiKeySelector" },
+      { step: 5, title: "Add Custom Model", desc: "Click \"View All Model\" → \"Add Custom Model\"" },
+      { step: 6, title: "Select Model", type: "modelSelector" },
+    ],
+  },
+  cline: {
+    id: "cline",
+    name: "Cline",
+    image: "/providers/cline.png",
+    color: "#00D1B2",
+    description: "Cline AI Coding Assistant",
+    configType: "custom",
+  },
+  kilo: {
+    id: "kilo",
+    name: "Kilo Code",
+    image: "/providers/kilocode.png",
+    color: "#FF6B6B",
+    description: "Kilo Code AI Assistant",
+    configType: "custom",
+  },
+  roo: {
+    id: "roo",
+    name: "Roo",
+    image: "/providers/roo.png",
+    color: "#FF6B6B",
+    description: "Roo AI Assistant",
+    configType: "guide",
+    guideSteps: [
+      { step: 1, title: "Open Settings", desc: "Go to Roo Settings panel" },
+      { step: 2, title: "Select Provider", desc: "Choose API Provider → Ollama" },
+      { step: 3, title: "Base URL", value: "{{baseUrl}}", copyable: true },
+      { step: 4, title: "API Key", type: "apiKeySelector" },
+      { step: 5, title: "Select Model", type: "modelSelector" },
+    ],
+  },
+  continue: {
+    id: "continue",
+    name: "Continue",
+    image: "/providers/continue.png",
+    color: "#7C3AED",
+    description: "Continue AI Assistant",
+    configType: "guide",
+    guideSteps: [
+      { step: 1, title: "Open Config", desc: "Open Continue configuration file" },
+      { step: 2, title: "API Key", type: "apiKeySelector" },
+      { step: 3, title: "Select Model", type: "modelSelector" },
+      { step: 4, title: "Add Model Config", desc: "Add the following configuration to your models array:" },
+    ],
+    codeBlock: {
+      language: "json",
+      code: `{
+  "apiBase": "{{baseUrl}}",
+  "title": "{{model}}",
+  "model": "{{model}}",
+  "provider": "openai",
+  "apiKey": "{{apiKey}}"
+}`,
+    },
+  },
+  amp: {
+    id: "amp",
+    name: "Amp CLI",
+    image: "/providers/amp.png",
+    color: "#F97316",
+    description: "Sourcegraph Amp coding assistant CLI",
+    docsUrl: "/docs?section=cli-tools&tool=amp",
+    configType: "guide",
+    defaultCommand: "amp",
+    modelAliases: ["g25p", "g25f", "cs45", "g54"],
+    notes: [
+      { type: "info", text: "Use 9Router model aliases to keep Amp shorthand mappings stable across provider updates." },
+      { type: "warning", text: "Suggested shorthand examples: g25p → gemini/gemini-2.5-pro, g25f → gemini/gemini-2.5-flash, cs45 → cc/claude-sonnet-4-5-20250929." },
+    ],
+    guideSteps: [
+      { step: 1, title: "Install Amp", desc: "Install the Amp CLI using the package manager supported by your environment." },
+      { step: 2, title: "API Key", type: "apiKeySelector" },
+      { step: 3, title: "Base URL", value: "{{baseUrl}}", copyable: true },
+      { step: 4, title: "Select Model", type: "modelSelector" },
+      { step: 5, title: "Add Shorthands", desc: "Map Amp shorthand names such as g25p or cs45 to 9Router aliases in your local config." },
+    ],
+    codeBlock: {
+      language: "bash",
+      code: `export OPENAI_API_KEY="{{apiKey}}"
+export OPENAI_BASE_URL="{{baseUrl}}"
+amp --model "{{model}}"
+# Example shorthand aliases you can map locally:
+# g25p -> gemini/gemini-2.5-pro
+# cs45 -> cc/claude-sonnet-4-5-20250929`,
+    },
+  },
+  qwen: {
+    id: "qwen",
+    name: "Qwen Code",
+    image: "/providers/qwen.png",
+    color: "#10B981",
+    description: "Alibaba Qwen Code CLI — supports OpenAI, Anthropic & Gemini providers via 9Router",
+    docsUrl: "https://qwenlm.github.io/qwen-code-docs/en/users/configuration/model-providers/",
+    configType: "guide",
+    defaultCommand: "qwen",
+    notes: [
+      { type: "info", text: "Qwen Code supports multiple provider types (openai, anthropic, gemini) via modelProviders in settings.json. 9Router works as an OpenAI-compatible endpoint." },
+      { type: "info", text: "Any model available in 9Router can be used — not just Qwen models. Select from Qwen, Claude, Gemini, GPT, and more." },
+      { type: "warning", text: "Config path: Linux/macOS ~/.qwen/settings.json • Windows %USERPROFILE%\\.qwen\\settings.json" },
+      { type: "error", text: "Qwen OAuth free tier was discontinued on 2026-04-15. Use 9Router with alicode/openrouter/anthropic/gemini providers instead." },
+    ],
+    modelAliases: ["coder-model", "qwen3-coder-plus", "qwen3-coder-flash", "vision-model", "claude-sonnet-4-6", "claude-opus-4-6-thinking", "gemini-3-flash", "gemini-3.1-pro-high"],
+    defaultModels: [
+      { id: "coder-model", name: "Coder Model (Qwen 3.6 Plus)", alias: "coder-model", envKey: "OPENAI_MODEL", defaultValue: "coder-model", isTopLevel: true },
+      { id: "qwen3-coder-plus", name: "Qwen 3 Coder Plus", alias: "qwen3-coder-plus", envKey: "OPENAI_MODEL", defaultValue: "qwen3-coder-plus" },
+      { id: "qwen3-coder-flash", name: "Qwen 3 Coder Flash", alias: "qwen3-coder-flash", envKey: "OPENAI_MODEL", defaultValue: "qwen3-coder-flash" },
+      { id: "vision-model", name: "Vision Model (Multimodal)", alias: "vision-model", envKey: "OPENAI_MODEL", defaultValue: "vision-model" },
+      { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6", alias: "claude-sonnet-4-6", envKey: "OPENAI_MODEL", defaultValue: "claude-sonnet-4-6" },
+      { id: "claude-opus-4-6-thinking", name: "Claude Opus 4.6 Thinking", alias: "claude-opus-4-6-thinking", envKey: "OPENAI_MODEL", defaultValue: "claude-opus-4-6-thinking" },
+      { id: "gemini-3.1-pro-high", name: "Gemini 3.1 Pro High", alias: "gemini-3.1-pro-high", envKey: "OPENAI_MODEL", defaultValue: "gemini-3.1-pro-high" },
+      { id: "gemini-3-flash", name: "Gemini 3 Flash", alias: "gemini-3-flash", envKey: "OPENAI_MODEL", defaultValue: "gemini-3-flash" },
+    ],
+    guideSteps: [
+      { step: 1, title: "Install Qwen Code", desc: "npm install -g @qwen-code/qwen-code" },
+      { step: 2, title: "API Key", type: "apiKeySelector" },
+      { step: 3, title: "Base URL", value: "{{baseUrl}}", copyable: true },
+      { step: 4, title: "Select Model", type: "modelSelector" },
+      { step: 5, title: "Save Config", desc: "Copy the JSON below to your ~/.qwen/settings.json file." },
+    ],
+    codeBlock: {
+      language: "json",
+      code: `{
+  "security": {
+    "auth": {
+      "selectedType": "openai",
+      "apiKey": "{{apiKey}}",
+      "baseUrl": "{{baseUrl}}"
+    }
+  },
+  "model": {
+    "name": "{{model}}"
+  }
+}`,
+    },
+  },
+  "deepseek-tui": {
+    id: "deepseek-tui",
+    name: "DeepSeek TUI",
+    image: "/providers/deepseek-tui.png",
+    color: "#4D6BFE",
+    description: "DeepSeek Terminal Coding Agent (Rust TUI)",
+    docsUrl: "https://github.com/DeepSeek-TUI/DeepSeek-TUI",
+    configType: "custom",
+    defaultCommand: "deepseek",
+    modelAliases: ["deepseek-v4-pro", "deepseek-v4-flash", "deepseek-chat", "deepseek-reasoner"],
+    defaultModels: [
+      { id: "deepseek-v4-pro", name: "DeepSeek V4 Pro", alias: "deepseek-v4-pro" },
+      { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash", alias: "deepseek-v4-flash" },
+      { id: "deepseek-chat", name: "DeepSeek V3 Chat", alias: "deepseek-chat" },
+    ],
+    notes: [
+      { type: "info", text: "DeepSeek TUI uses ~/.deepseek/config.toml for configuration. 9Router will update the provider to 'openai' mode with your base_url, api_key, and model." },
+      { type: "warning", text: "Config path: Linux/macOS ~/.deepseek/config.toml • Windows %USERPROFILE%\\.deepseek\\config.toml" },
+    ],
+  },
+  jcode: {
+    id: "jcode",
+    name: "jcode",
+    image: "/providers/jcode.png",
+    color: "#FF6B35",
+    description: "High-performance Rust-based coding agent harness",
+    configType: "custom",
+    docsUrl: "https://github.com/1jehuang/jcode",
+    notes: [
+      {
+        type: "info",
+        text: "jcode is a Rust-based coding agent with semantic memory, multi-agent swarms, and extreme performance (27.8 MB RAM, 14ms boot)."
+      },
+      {
+        type: "info",
+        text: "Configure 9router as an OpenAI-compatible provider to route all jcode requests through 9router's optimization layer."
+      },
+      {
+        type: "warning",
+        text: "Requires jcode installed. Install via: curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash"
+      },
+    ],
+    defaultModels: [
+      { id: "claude-opus-4-7", name: "Claude Opus 4.7", alias: "opus", defaultValue: "cc/claude-opus-4-7" },
+      { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6", alias: "sonnet", defaultValue: "cc/claude-sonnet-4-6" },
+      { id: "gpt-5.5", name: "GPT 5.5", alias: "gpt5", defaultValue: "cx/gpt-5.5" },
+      { id: "gemini-3.1-pro", name: "Gemini 3.1 Pro", alias: "gemini", defaultValue: "gemini/gemini-3.1-pro" },
+    ],
+  },
+  // HIDDEN: gemini-cli
+  // "gemini-cli": {
+  //   id: "gemini-cli",
+  //   name: "Gemini CLI",
+  //   icon: "terminal",
+  //   color: "#4285F4",
+  //   description: "Google Gemini CLI",
+  //   configType: "env",
+  //   envVars: {
+  //     baseUrl: "GEMINI_API_BASE_URL",
+  //     model: "GEMINI_MODEL",
+  //   },
+  //   defaultModels: [
+  //     { id: "gemini-2.5-pro", name: "Gemini 2.5 Pro", alias: "pro" },
+  //     { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash", alias: "flash" },
+  //   ],
+  // },
+};
+
+// Get all provider models for mapping dropdown
+export const getProviderModelsForMapping = (providers) => {
+  const result = [];
+  providers.forEach(conn => {
+    if (conn.isActive && (conn.testStatus === "active" || conn.testStatus === "success")) {
+      result.push({
+        connectionId: conn.id,
+        provider: conn.provider,
+        name: conn.name,
+        models: conn.models || [],
+      });
+    }
+  });
+  return result;
+};
diff --git a/src/shared/constants/colors.js b/src/shared/constants/colors.js
new file mode 100644
index 0000000..873f3e5
--- /dev/null
+++ b/src/shared/constants/colors.js
@@ -0,0 +1,77 @@
+// Claude-inspired color palette for Endpoint Proxy
+// Light theme: Warm beige/cream tones
+// Dark theme: Deep charcoal/brown tones
+
+export const COLORS = {
+  // Primary - Warm Coral/Terracotta (Claude-like)
+  primary: {
+    DEFAULT: "#D97757",
+    hover: "#C56243",
+    light: "#E8A58C",
+    dark: "#B0664D",
+  },
+
+  // Light theme backgrounds
+  light: {
+    bg: "#FBF9F6",
+    bgAlt: "#F5F1ED",
+    surface: "#FFFFFF",
+    sidebar: "rgba(246, 246, 246, 0.8)",
+    border: "rgba(0, 0, 0, 0.1)",
+    textMain: "#383733",
+    textMuted: "#75736E",
+  },
+
+  // Dark theme backgrounds
+  dark: {
+    bg: "#191918",
+    bgAlt: "#1F1F1E",
+    surface: "#242423",
+    sidebar: "rgba(30, 30, 30, 0.8)",
+    border: "rgba(255, 255, 255, 0.1)",
+    textMain: "#ECEBE8",
+    textMuted: "#9E9D99",
+  },
+
+  // Status colors
+  status: {
+    success: "#22C55E",
+    successLight: "#DCFCE7",
+    successDark: "#166534",
+    warning: "#F59E0B",
+    warningLight: "#FEF3C7",
+    warningDark: "#92400E",
+    error: "#EF4444",
+    errorLight: "#FEE2E2",
+    errorDark: "#991B1B",
+    info: "#3B82F6",
+    infoLight: "#DBEAFE",
+    infoDark: "#1E40AF",
+  },
+};
+
+// CSS Variables mapping for Tailwind
+export const CSS_VARIABLES = {
+  light: {
+    "--color-primary": COLORS.primary.DEFAULT,
+    "--color-primary-hover": COLORS.primary.hover,
+    "--color-bg": COLORS.light.bg,
+    "--color-bg-alt": COLORS.light.bgAlt,
+    "--color-surface": COLORS.light.surface,
+    "--color-sidebar": COLORS.light.sidebar,
+    "--color-border": COLORS.light.border,
+    "--color-text-main": COLORS.light.textMain,
+    "--color-text-muted": COLORS.light.textMuted,
+  },
+  dark: {
+    "--color-primary": COLORS.primary.DEFAULT,
+    "--color-primary-hover": COLORS.primary.hover,
+    "--color-bg": COLORS.dark.bg,
+    "--color-bg-alt": COLORS.dark.bgAlt,
+    "--color-surface": COLORS.dark.surface,
+    "--color-sidebar": COLORS.dark.sidebar,
+    "--color-border": COLORS.dark.border,
+    "--color-text-main": COLORS.dark.textMain,
+    "--color-text-muted": COLORS.dark.textMuted,
+  },
+};
diff --git a/src/shared/constants/config.js b/src/shared/constants/config.js
new file mode 100644
index 0000000..0650d08
--- /dev/null
+++ b/src/shared/constants/config.js
@@ -0,0 +1,109 @@
+import pkg from "../../../package.json" with { type: "json" };
+
+// App configuration
+export const APP_CONFIG = {
+  name: "9Router Proxy",
+  description: "AI Infrastructure Management",
+  version: pkg.version,
+};
+
+// GitHub configuration
+export const GITHUB_CONFIG = {
+  changelogUrl: "https://raw.githubusercontent.com/decolua/9router/refs/heads/master/CHANGELOG.md",
+  donateUrl: "https://9router.com/api/donate",
+};
+
+// Updater configuration
+export const UPDATER_CONFIG = {
+  npmPackageName: "9router",
+  installCmd: "npm i -g 9router",
+  installCmdLatest: "npm i -g 9router@latest --prefer-online",
+  shutdownCountdownSec: 3,
+  exitDelayMs: 500,
+  statusPort: 20129,
+  statusPollIntervalMs: 1000,
+  statusLogTailLines: 8,
+  installRetries: 3,
+  installRetryDelayMs: 5000,
+  lingerAfterDoneMs: 30000,
+  waitForExitMinMs: 5000,
+  waitForExitMaxMs: 20000,
+  waitForExitCheckMs: 500,
+  appPort: 20128,
+};
+
+// Theme configuration
+export const THEME_CONFIG = {
+  storageKey: "theme",
+  defaultTheme: "system", // "light" | "dark" | "system"
+};
+
+// Subscription
+export const SUBSCRIPTION_CONFIG = {
+  price: 1.0,
+  currency: "USD",
+  interval: "month",
+  planName: "Pro Plan",
+};
+
+// API endpoints
+export const API_ENDPOINTS = {
+  users: "/api/users",
+  providers: "/api/providers",
+  payments: "/api/payments",
+  auth: "/api/auth",
+};
+
+export const CONSOLE_LOG_CONFIG = {
+  maxLines: 200,
+  pollIntervalMs: 1000,
+};
+
+// Client-side store TTL: how long fetched data stays fresh before re-fetching
+export const CLIENT_STORE_TTL_MS = 60000;
+
+// Quota auto-ping: keep 5h windows warm by sending a tiny request right after reset.
+export const QUOTA_AUTOPING_CONFIG = {
+  tickIntervalMs: 60000,                // scheduler tick
+  pingLeadMs: 5000,                     // fire once reset passes (within tolerance)
+  refreshAheadMs: 300000,               // refetch usage when within 5min of reset
+  failureCooldownMs: 900000,            // avoid failed ping spam while upstream/auth is unhealthy
+  providers: {
+    claude: {
+      settingsKey: "claudeAutoPing",    // preserve existing settings contract
+      quotaKey: "session (5h)",         // quota key returned by usage handler
+      pingModel: "claude-haiku-4-5-20251001",
+      pingText: "hi",
+      pingMaxTokens: 1,
+    },
+    codex: {
+      settingsKey: "codexAutoPing",
+      quotaKey: "session",
+      pingWhenResetAtSlides: true,
+      resetAtDriftMs: 30000,
+      minPingIntervalMs: 600000,
+      skipWhenBlockingQuotaExhausted: true,
+      // Free and Plus Codex accounts both expose gpt-5.5; avoid fallback probes that waste requests.
+      pingModel: "gpt-5.5",
+      pingText: "hi",
+      pingInstructions: "Reply with OK.",
+      pingReasoningEffort: "none",
+    },
+  },
+};
+
+// Re-export from providers.js for backward compatibility
+export {
+  FREE_PROVIDERS,
+  OAUTH_PROVIDERS,
+  APIKEY_PROVIDERS,
+  WEB_COOKIE_PROVIDERS,
+  AI_PROVIDERS,
+  AUTH_METHODS,
+} from "./providers.js";
+
+// Re-export from models.js for backward compatibility
+export {
+  PROVIDER_MODELS,
+  AI_MODELS,
+} from "./models.js";
diff --git a/src/shared/constants/coworkPlugins.js b/src/shared/constants/coworkPlugins.js
new file mode 100644
index 0000000..b32f120
--- /dev/null
+++ b/src/shared/constants/coworkPlugins.js
@@ -0,0 +1,72 @@
+// Default remote plugins for Claude Cowork (3p managedMcpServers, HTTPS only).
+const DEFAULT_PLUGINS = [
+  {
+    name: "exa",
+    title: "Exa",
+    description: "Real-time web search and code documentation",
+    url: "https://mcp.exa.ai/mcp",
+    transport: "http",
+    oauth: false,
+    toolNames: ["web_search_exa", "web_fetch_exa"],
+  },
+  {
+    name: "tavily",
+    title: "Tavily",
+    description: "Real-time web search optimized for LLM agents",
+    url: "https://mcp.tavily.com/mcp",
+    transport: "http",
+    oauth: true,
+    toolNames: ["tavily_search", "tavily_extract", "tavily_crawl", "tavily_map"],
+  },
+];
+
+// Local stdio plugins bridged via inline SSE endpoint on the app's port.
+const LOCAL_STDIO_PLUGINS = [
+  {
+    name: "browsermcp",
+    title: "Browser MCP",
+    description: "Control your running Chrome (requires Chrome extension)",
+    extensionUrl: "https://chromewebstore.google.com/detail/browser-mcp-automate-your/bjfgambnhccakkhmkepdoekmckoijdlc",
+    command: "npx",
+    args: ["-y", "@browsermcp/mcp@latest"],
+    toolNames: ["browser_navigate", "browser_snapshot", "browser_click", "browser_type", "browser_screenshot", "browser_get_console_logs", "browser_wait", "browser_press_key", "browser_go_back", "browser_go_forward"],
+  },
+];
+
+function buildManagedMcpServers(plugins) {
+  const list = Array.isArray(plugins) ? plugins : [];
+  const out = [];
+  const seen = new Set();
+  for (const p of list) {
+    if (!p?.name || !p?.url || seen.has(p.name)) continue;
+    seen.add(p.name);
+    const entry = {
+      name: p.name,
+      url: p.url,
+      transport: p.transport || (/\/sse(\b|\/)/i.test(p.url) ? "sse" : "http"),
+    };
+    if (p.oauth) entry.oauth = true;
+    if (Array.isArray(p.toolNames) && p.toolNames.length > 0) {
+      // Strip any pre-existing "{name}-" prefixes (idempotent across re-applies),
+      // then emit both bare + single-prefixed variants to match runtime tool naming.
+      const prefix = `${p.name}-`;
+      const bare = new Set();
+      for (const raw of p.toolNames) {
+        if (typeof raw !== "string" || !raw) continue;
+        let t = raw;
+        while (t.startsWith(prefix)) t = t.slice(prefix.length);
+        bare.add(t);
+      }
+      const policy = {};
+      for (const t of bare) {
+        policy[t] = "allow";
+        policy[`${prefix}${t}`] = "allow";
+      }
+      entry.toolPolicy = policy;
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+module.exports = { DEFAULT_PLUGINS, LOCAL_STDIO_PLUGINS, buildManagedMcpServers };
diff --git a/src/shared/constants/index.js b/src/shared/constants/index.js
new file mode 100644
index 0000000..820029c
--- /dev/null
+++ b/src/shared/constants/index.js
@@ -0,0 +1,4 @@
+// Shared Constants - Export all
+export * from "./colors";
+export * from "./config";
+
diff --git a/src/shared/constants/locales.js b/src/shared/constants/locales.js
new file mode 100644
index 0000000..eff8654
--- /dev/null
+++ b/src/shared/constants/locales.js
@@ -0,0 +1,37 @@
+// Centralized locale display flags (shared across UI components)
+export const LOCALE_FLAGS = {
+  "en": "🇺🇸",
+  "vi": "🇻🇳",
+  "zh-CN": "🇨🇳",
+  "zh-TW": "🇹🇼",
+  "ja": "🇯🇵",
+  "pt-BR": "🇧🇷",
+  "pt-PT": "🇵🇹",
+  "ko": "🇰🇷",
+  "es": "🇪🇸",
+  "de": "🇩🇪",
+  "fr": "🇫🇷",
+  "he": "🇮🇱",
+  "ar": "🇸🇦",
+  "ru": "🇷🇺",
+  "pl": "🇵🇱",
+  "cs": "🇨🇿",
+  "nl": "🇳🇱",
+  "tr": "🇹🇷",
+  "uk": "🇺🇦",
+  "tl": "🇵🇭",
+  "id": "🇮🇩",
+  "th": "🇹🇭",
+  "hi": "🇮🇳",
+  "bn": "🇧🇩",
+  "ur": "🇵🇰",
+  "ro": "🇷🇴",
+  "sv": "🇸🇪",
+  "it": "🇮🇹",
+  "el": "🇬🇷",
+  "hu": "🇭🇺",
+  "fi": "🇫🇮",
+  "da": "🇩🇰",
+  "no": "🇳🇴",
+  "fa": "🇮🇷",
+};
diff --git a/src/shared/constants/mitmToolHosts.js b/src/shared/constants/mitmToolHosts.js
new file mode 100644
index 0000000..b1decb4
--- /dev/null
+++ b/src/shared/constants/mitmToolHosts.js
@@ -0,0 +1,12 @@
+/**
+ * Per-tool DNS hosts — written to hosts file as 127.0.0.1 when MITM DNS is enabled.
+ * Kept in sync with MITM routing; shared by Node (dnsConfig) and dashboard UI.
+ */
+const TOOL_HOSTS = {
+  antigravity: ["daily-cloudcode-pa.googleapis.com", "cloudcode-pa.googleapis.com"],
+  copilot: ["api.individual.githubcopilot.com"],
+  kiro: ["runtime.us-east-1.kiro.dev", "q.us-east-1.amazonaws.com", "codewhisperer.us-east-1.amazonaws.com"],
+  cursor: ["api2.cursor.sh"],
+};
+
+module.exports = { TOOL_HOSTS };
diff --git a/src/shared/constants/models.js b/src/shared/constants/models.js
new file mode 100644
index 0000000..297daae
--- /dev/null
+++ b/src/shared/constants/models.js
@@ -0,0 +1,47 @@
+// Import directly from file to avoid pulling in server-side dependencies via index.js
+export {
+  PROVIDER_MODELS,
+  getProviderModels,
+  getDefaultModel,
+  isValidModel as isValidModelCore,
+  findModelName,
+  getModelTargetFormat,
+  getModelStrip,
+  PROVIDER_ID_TO_ALIAS,
+  getModelsByProviderId,
+  getModelUpstreamId,
+  getModelQuotaFamily
+} from "open-sse/config/providerModels.js";
+
+import { AI_PROVIDERS, isOpenAICompatibleProvider } from "./providers.js";
+import { PROVIDER_MODELS as MODELS } from "open-sse/config/providerModels.js";
+
+// Providers that accept any model (passthrough)
+const PASSTHROUGH_PROVIDERS = new Set(
+  Object.entries(AI_PROVIDERS)
+    .filter(([, p]) => p.passthroughModels)
+    .map(([key]) => key)
+);
+
+// Wrap isValidModel with passthrough providers
+export function isValidModel(aliasOrId, modelId) {
+  if (isOpenAICompatibleProvider(aliasOrId)) return true;
+  if (PASSTHROUGH_PROVIDERS.has(aliasOrId)) return true;
+  const models = MODELS[aliasOrId];
+  if (!models) return false;
+  return models.some(m => m.id === modelId);
+}
+
+// Legacy AI_MODELS for backward compatibility
+export const AI_MODELS = Object.entries(MODELS).flatMap(([alias, models]) =>
+  models.map(m => ({ provider: alias, model: m.id, name: m.name }))
+);
+
+export const getModelKind = (m, fallback = null) => m?.kind || m?.type || fallback;
+
+// Capacity metadata for UI badges — icon + label + color per capability.
+export const CAPACITY_META = {
+  vision: { icon: "visibility", label: "Vision", desc: "Supports image input", color: "text-blue-500" },
+  // search: temporarily hidden (feature not wired yet)
+  reasoning: { icon: "neurology", label: "Reasoning", desc: "Supports reasoning / thinking", color: "text-amber-500" },
+};
diff --git a/src/shared/constants/providers.js b/src/shared/constants/providers.js
new file mode 100644
index 0000000..34356cb
--- /dev/null
+++ b/src/shared/constants/providers.js
@@ -0,0 +1,165 @@
+// Provider definitions
+import REGISTRY from "open-sse/providers/registry/index.js";
+import { RISK_NOTICE } from "@/shared/constants/providersDisplay";
+
+const MEDIA_ENTRY_KEYS = [
+  "serviceKinds", "ttsConfig", "sttConfig", "embeddingConfig",
+  "imageConfig", "imageToTextConfig", "videoConfig", "musicConfig",
+  "searchViaChat", "searchConfig", "fetchConfig",
+  "modelsFetcher", "mediaPriority", "hiddenKinds",
+];
+
+// Build provider UI object from registry entry
+function buildProviderEntry(r) {
+  const mediaFields = {};
+  if (r.media) Object.assign(mediaFields, r.media);
+  for (const k of MEDIA_ENTRY_KEYS) {
+    if (r[k] !== undefined) mediaFields[k] = r[k];
+  }
+  const display = { ...(r.display || {}) };
+  if (display.deprecationNotice === "RISK_NOTICE") display.deprecationNotice = RISK_NOTICE;
+  return {
+    ...display,
+    id: r.id,
+    alias: r.uiAlias || r.alias,
+    ...(r.hidden ? { hidden: true } : {}),
+    ...mediaFields,
+    ...(r.priority !== undefined ? { priority: r.priority } : {}),
+    ...(r.hasFree ? { hasFree: true } : {}),
+    ...(r.thinkingConfig ? { thinkingConfig: r.thinkingConfig } : {}),
+    ...(r.regions ? { regions: r.regions, defaultRegion: r.defaultRegion } : {}),
+    ...(r.hasProviderSpecificData ? { hasProviderSpecificData: true } : {}),
+    ...(r.noAuth ? { noAuth: true } : {}),
+    ...(r.passthroughModels ? { passthroughModels: true } : {}),
+    ...(r.hasOAuth ? { hasOAuth: true } : {}),
+    ...(r.authModes ? { authModes: r.authModes } : {}),
+    ...(r.authType ? { authType: r.authType } : {}),
+    ...(r.authHint ? { authHint: r.authHint } : {}),
+  };
+}
+
+const byCategory = (cat) => Object.fromEntries(
+  REGISTRY.filter(r => r.category === cat).map(r => [r.id, buildProviderEntry(r)])
+);
+
+export const FREE_PROVIDERS = byCategory("free");
+export const FREE_TIER_PROVIDERS = byCategory("freeTier");
+
+// Thinking config definitions
+// options: list of selectable modes ("auto" = no override from server)
+// defaultMode: fallback when user hasn't configured
+// extended: claude-style thinking (thinking.type + budget_tokens) — used by most providers
+// effort: openai-style reasoning_effort — only openai + codex
+export const THINKING_CONFIG = {
+  extended: {
+    options: ["auto", "on", "off"],
+    defaultMode: "auto",
+    defaultBudgetTokens: 10000
+  },
+  effort: {
+    options: ["auto", "none", "low", "medium", "high"],
+    defaultMode: "auto"
+  }
+};
+
+export const OAUTH_PROVIDERS = byCategory("oauth");
+export const APIKEY_PROVIDERS = byCategory("apikey");
+
+// Web Cookie Providers (use browser session cookie instead of API key)
+export const WEB_COOKIE_PROVIDERS = byCategory("webCookie");
+
+// Media provider kinds — each kind maps to a route and endpoint config
+export const MEDIA_PROVIDER_KINDS = [
+  { id: "embedding",   label: "Embedding",      icon: "data_array",        endpoint: { method: "POST", path: "/v1/embeddings" } },
+  { id: "image",       label: "Text to Image",  icon: "brush",             endpoint: { method: "POST", path: "/v1/images/generations" } },
+  { id: "imageToText", label: "Image to Text",  icon: "image_search",      endpoint: { method: "POST", path: "/v1/images/understanding" } },
+  { id: "tts",         label: "Text To Speech", icon: "record_voice_over", endpoint: { method: "POST", path: "/v1/audio/speech" } },
+  { id: "stt",         label: "Speech To Text", icon: "mic",               endpoint: { method: "POST", path: "/v1/audio/transcriptions" } },
+  { id: "webSearch",   label: "Web Search",     icon: "travel_explore",    endpoint: { method: "POST", path: "/v1/search" } },
+  { id: "webFetch",    label: "Web Fetch",      icon: "language",          endpoint: { method: "POST", path: "/v1/web/fetch" } },
+  { id: "video",       label: "Video",          icon: "movie",             endpoint: { method: "POST", path: "/v1/video/generations" } },
+  { id: "music",       label: "Music",          icon: "music_note",        endpoint: { method: "POST", path: "/v1/audio/music" } },
+];
+
+export const OPENAI_COMPATIBLE_PREFIX = "openai-compatible-";
+export const ANTHROPIC_COMPATIBLE_PREFIX = "anthropic-compatible-";
+export const CUSTOM_EMBEDDING_PREFIX = "custom-embedding-";
+
+export function isOpenAICompatibleProvider(providerId) {
+  return typeof providerId === "string" && providerId.startsWith(OPENAI_COMPATIBLE_PREFIX);
+}
+
+export function isAnthropicCompatibleProvider(providerId) {
+  return typeof providerId === "string" && providerId.startsWith(ANTHROPIC_COMPATIBLE_PREFIX);
+}
+
+export function isCustomEmbeddingProvider(providerId) {
+  return typeof providerId === "string" && providerId.startsWith(CUSTOM_EMBEDDING_PREFIX);
+}
+
+// All providers (combined)
+export const AI_PROVIDERS = { ...FREE_PROVIDERS, ...FREE_TIER_PROVIDERS, ...OAUTH_PROVIDERS, ...APIKEY_PROVIDERS, ...WEB_COOKIE_PROVIDERS };
+
+// Auth methods
+export const AUTH_METHODS = {
+  oauth: { id: "oauth" },
+  apikey: { id: "apikey" },
+  cookie: { id: "cookie" },
+};
+
+// Helper: Get provider by alias
+export function getProviderByAlias(alias) {
+  for (const provider of Object.values(AI_PROVIDERS)) {
+    if (provider.alias === alias || provider.id === alias) {
+      return provider;
+    }
+  }
+  return null;
+}
+
+// Helper: Get provider ID from alias
+export function resolveProviderId(aliasOrId) {
+  const provider = getProviderByAlias(aliasOrId);
+  return provider?.id || aliasOrId;
+}
+
+// Helper: Get alias from provider ID
+export function getProviderAlias(providerId) {
+  const provider = AI_PROVIDERS[providerId];
+  return provider?.alias || providerId;
+}
+
+// Alias to ID mapping (for quick lookup)
+export const ALIAS_TO_ID = Object.values(AI_PROVIDERS).reduce((acc, p) => {
+  acc[p.alias] = p.id;
+  return acc;
+}, {});
+
+// ID to Alias mapping
+export const ID_TO_ALIAS = Object.values(AI_PROVIDERS).reduce((acc, p) => {
+  acc[p.id] = p.alias;
+  return acc;
+}, {});
+
+// Helper: Get providers by service kind (e.g. "tts", "embedding", "image")
+// Providers without serviceKinds default to ["llm"]
+export function getProvidersByKind(kind) {
+  return Object.values(AI_PROVIDERS)
+    .filter((p) => {
+      const kinds = p.serviceKinds ?? ["llm"];
+      if (!kinds.includes(kind)) return false;
+      if (p.hidden) return false;
+      if (p.hiddenKinds?.includes(kind)) return false;
+      return true;
+    })
+    .sort((a, b) => (a.priority ?? a.mediaPriority ?? 999) - (b.priority ?? b.mediaPriority ?? 999));
+}
+
+// Derive từ registry features flags
+export const USAGE_SUPPORTED_PROVIDERS = REGISTRY
+  .filter(r => r.features?.usage)
+  .map(r => r.id);
+
+export const USAGE_APIKEY_PROVIDERS = REGISTRY
+  .filter(r => r.features?.usageApikey)
+  .map(r => r.id);
diff --git a/src/shared/constants/providersDisplay.js b/src/shared/constants/providersDisplay.js
new file mode 100644
index 0000000..cd1d54a
--- /dev/null
+++ b/src/shared/constants/providersDisplay.js
@@ -0,0 +1,12 @@
+// UI display config — all providers derive from registry.display.
+import REGISTRY from "open-sse/providers/registry/index.js";
+
+export const RISK_NOTICE = "⚠️ Risk Notice: This provider uses a subscription/OAuth session not officially licensed for proxy/router use. Account may be restricted or banned. Use at your own risk.";
+
+// Resolve "RISK_NOTICE" token → real notice text (registry stores token to avoid import cycle)
+const resolveDisplay = (d) =>
+  d.deprecationNotice === "RISK_NOTICE" ? { ...d, deprecationNotice: RISK_NOTICE } : d;
+
+export const PROVIDER_DISPLAY = Object.fromEntries(
+  REGISTRY.filter((r) => r.display).map((r) => [r.id, resolveDisplay(r.display)]),
+);
diff --git a/src/shared/constants/skills.js b/src/shared/constants/skills.js
new file mode 100644
index 0000000..1f758e3
--- /dev/null
+++ b/src/shared/constants/skills.js
@@ -0,0 +1,78 @@
+// Agent Skills metadata — single source of truth for /dashboard/skills page.
+// Each skill = 1 raw GitHub URL the user copies and pastes to any AI agent.
+
+const REPO = "decolua/9router";
+const BRANCH = "master";
+const SKILL_PATH = "skills";
+
+export const SKILLS_REPO_URL = `https://github.com/${REPO}`;
+export const SKILLS_RAW_BASE = `https://raw.githubusercontent.com/${REPO}/refs/heads/${BRANCH}/${SKILL_PATH}`;
+export const SKILLS_BLOB_BASE = `https://github.com/${REPO}/blob/${BRANCH}/${SKILL_PATH}`;
+
+export const SKILLS = [
+  {
+    id: "9router",
+    name: "9Router (Entry)",
+    description: "Setup + index of all capabilities. Start here — covers base URL, auth, model discovery, and links to every capability skill.",
+    endpoint: null,
+    icon: "hub",
+    isEntry: true,
+  },
+  {
+    id: "9router-chat",
+    name: "Chat",
+    description: "Chat / code-gen via OpenAI or Anthropic format with streaming.",
+    endpoint: "/v1/chat/completions",
+    icon: "chat",
+  },
+  {
+    id: "9router-image",
+    name: "Image Generation",
+    description: "Text-to-image via DALL-E, Imagen, FLUX, MiniMax, SDWebUI…",
+    endpoint: "/v1/images/generations",
+    icon: "image",
+  },
+  {
+    id: "9router-tts",
+    name: "Text-to-Speech",
+    description: "OpenAI / ElevenLabs / Edge / Google / Deepgram voices.",
+    endpoint: "/v1/audio/speech",
+    icon: "record_voice_over",
+  },
+  {
+    id: "9router-stt",
+    name: "Speech-to-Text",
+    description: "Transcribe audio via OpenAI Whisper, Groq, Gemini, Deepgram, AssemblyAI…",
+    endpoint: "/v1/audio/transcriptions",
+    icon: "mic",
+  },
+  {
+    id: "9router-embeddings",
+    name: "Embeddings",
+    description: "Vectors for RAG / semantic search via OpenAI, Gemini, Mistral…",
+    endpoint: "/v1/embeddings",
+    icon: "scatter_plot",
+  },
+  {
+    id: "9router-web-search",
+    name: "Web Search",
+    description: "Tavily / Exa / Brave / Serper / SearXNG / Google PSE / You.com.",
+    endpoint: "/v1/search",
+    icon: "search",
+  },
+  {
+    id: "9router-web-fetch",
+    name: "Web Fetch",
+    description: "URL → markdown / text / HTML via Firecrawl, Jina, Tavily, Exa.",
+    endpoint: "/v1/web/fetch",
+    icon: "language",
+  },
+];
+
+export function getSkillRawUrl(id) {
+  return `${SKILLS_RAW_BASE}/${id}/SKILL.md`;
+}
+
+export function getSkillBlobUrl(id) {
+  return `${SKILLS_BLOB_BASE}/${id}/SKILL.md`;
+}
diff --git a/src/shared/constants/ttsProviders.js b/src/shared/constants/ttsProviders.js
new file mode 100644
index 0000000..f1b990d
--- /dev/null
+++ b/src/shared/constants/ttsProviders.js
@@ -0,0 +1,138 @@
+/**
+ * TTS Provider Configuration
+ * Centralized config for TTS provider UI behavior
+ */
+export const TTS_PROVIDER_CONFIG = {
+  "google-tts": {
+    hasLanguageDropdown: false,
+    hasModelSelector: false,
+    hasBrowseButton: true,
+    voiceSource: "hardcoded", // languages built from providerModels at runtime
+  },
+  "openai": {
+    hasLanguageDropdown: false,
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    voiceSource: "hardcoded",
+    modelKey: "openai-tts-models",
+    voiceKey: "openai-tts-voices",
+    voicesPerModel: true,
+  },
+  "openrouter": {
+    hasLanguageDropdown: false,
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    voiceSource: "hardcoded",
+    modelKey: "openrouter-tts-models",
+    voiceKey: "openrouter-tts-voices",
+    voicesPerModel: true,
+  },
+  "elevenlabs": {
+    hasLanguageDropdown: false,
+    hasModelSelector: true,
+    hasBrowseButton: true,
+    hasVoiceIdInput: true, // allow manual voice id entry
+    voiceSource: "api-language", // grouped by language from backend
+    modelKey: "elevenlabs-tts-models",
+    apiEndpoint: "/api/media-providers/tts/elevenlabs/voices",
+  },
+  "edge-tts": {
+    hasLanguageDropdown: false,
+    hasModelSelector: false,
+    hasBrowseButton: true,
+    voiceSource: "api-language", // from API with language picker
+  },
+  "local-device": {
+    hasLanguageDropdown: false,
+    hasModelSelector: false,
+    hasBrowseButton: true,
+    voiceSource: "api-language", // from API with language picker
+  },
+  // ── Config-driven providers (load models from providers.js → ttsConfig.models) ──
+  "nvidia": {
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    hasVoiceIdInput: true,
+    voiceSource: "config",
+  },
+  "hyperbolic": {
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    voiceSource: "config",
+  },
+  "deepgram": {
+    hasModelSelector: false,
+    hasBrowseButton: true,
+    voiceSource: "api-language",
+    apiEndpoint: "/api/media-providers/tts/deepgram/voices",
+  },
+  "huggingface": {
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    voiceSource: "config",
+  },
+  "cartesia": {
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    hasVoiceIdInput: true,
+    voiceSource: "config",
+  },
+  "playht": {
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    hasVoiceIdInput: true,
+    voiceSource: "config",
+  },
+  "coqui": {
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    hasVoiceIdInput: true,
+    voiceSource: "config",
+  },
+  "tortoise": {
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    hasVoiceIdInput: true,
+    voiceSource: "config",
+  },
+  "inworld": {
+    hasModelSelector: true,
+    hasBrowseButton: true,
+    hasVoiceIdInput: true,
+    voiceSource: "api-language",
+    modelKey: "inworld-tts-models",
+    apiEndpoint: "/api/media-providers/tts/inworld/voices",
+  },
+  "qwen": {
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    hasVoiceIdInput: true,
+    voiceSource: "config",
+  },
+  "minimax": {
+    hasModelSelector: true,
+    hasBrowseButton: true,
+    hasVoiceIdInput: true,
+    voiceSource: "api-language",
+    apiEndpoint: "/api/media-providers/tts/minimax/voices",
+    defaultVoiceId: "English_expressive_narrator",
+  },
+  "minimax-cn": {
+    hasModelSelector: true,
+    hasBrowseButton: true,
+    hasVoiceIdInput: true,
+    voiceSource: "api-language",
+    apiEndpoint: "/api/media-providers/tts/minimax/voices?provider=minimax-cn",
+    defaultVoiceId: "English_expressive_narrator",
+  },
+  "gemini": {
+    hasLanguageDropdown: false,
+    hasLanguageHint: true, // sends body.language to guide TTS pronunciation
+    hasModelSelector: true,
+    hasBrowseButton: false,
+    voiceSource: "hardcoded",
+    modelKey: "gemini-tts-models",
+    voiceKey: "gemini-tts-voices",
+    voicesPerModel: true,
+  },
+};
diff --git a/src/shared/hooks/index.js b/src/shared/hooks/index.js
new file mode 100644
index 0000000..0e5f64b
--- /dev/null
+++ b/src/shared/hooks/index.js
@@ -0,0 +1,3 @@
+// Shared Hooks - Export all
+export { useTheme } from "./useTheme";
+export { useModelCaps } from "./useModelCaps";
diff --git a/src/shared/hooks/useCopyToClipboard.js b/src/shared/hooks/useCopyToClipboard.js
new file mode 100644
index 0000000..fa5afed
--- /dev/null
+++ b/src/shared/hooks/useCopyToClipboard.js
@@ -0,0 +1,43 @@
+"use client";
+
+import { useState, useCallback, useRef } from "react";
+
+/**
+ * Hook for copy to clipboard with feedback
+ * @param {number} resetDelay - Time in ms before resetting copied state (default: 2000)
+ * @returns {{ copied: string|null, copy: (text: string, id?: string) => void }}
+ */
+export function useCopyToClipboard(resetDelay = 2000) {
+  const [copied, setCopied] = useState(null);
+  const timeoutRef = useRef(null);
+
+  const copy = useCallback((text, id = "default") => {
+    const write = async () => {
+      if (navigator?.clipboard?.writeText) {
+        await navigator.clipboard.writeText(text);
+      } else {
+        const textarea = document.createElement("textarea");
+        textarea.value = text;
+        textarea.style.position = "fixed";
+        textarea.style.opacity = "0";
+        document.body.appendChild(textarea);
+        textarea.select();
+        document.execCommand("copy");
+        document.body.removeChild(textarea);
+      }
+    };
+    write();
+    setCopied(id);
+
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+
+    timeoutRef.current = setTimeout(() => {
+      setCopied(null);
+    }, resetDelay);
+  }, [resetDelay]);
+
+  return { copied, copy };
+}
+
diff --git a/src/shared/hooks/useModelCaps.js b/src/shared/hooks/useModelCaps.js
new file mode 100644
index 0000000..3dbdcdd
--- /dev/null
+++ b/src/shared/hooks/useModelCaps.js
@@ -0,0 +1,44 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { getCapabilitiesForModel } from "open-sse/providers/capabilities.js";
+
+// Fetch model capabilities once and expose a lookup by fullModel ("provider/model") or bare model id.
+export function useModelCaps() {
+  const [byFull, setByFull] = useState({});
+  const [byId, setById] = useState({});
+
+  useEffect(() => {
+    let alive = true;
+    (async () => {
+      try {
+        const res = await fetch("/api/models");
+        if (!res.ok) return;
+        const data = await res.json();
+        const full = {};
+        const id = {};
+        for (const m of data.models || []) {
+          if (!m.caps) continue;
+          if (m.fullModel) full[m.fullModel] = m.caps;
+          if (m.model) id[m.model] = m.caps;
+        }
+        if (alive) { setByFull(full); setById(id); }
+      } catch { /* ignore */ }
+    })();
+    return () => { alive = false; };
+  }, []);
+
+  // Resolve caps from a "provider/model" string or a bare model id.
+  const getCaps = (key) => {
+    if (!key) return null;
+    if (byFull[key]) return byFull[key];
+    const bare = key.includes("/") ? key.slice(key.indexOf("/") + 1) : key;
+    if (byId[bare]) return byId[bare];
+    // Fallback: compute caps for dynamic models (passthrough/custom/suggested) not in static list
+    const provider = key.includes("/") ? key.slice(0, key.indexOf("/")) : null;
+    const c = getCapabilitiesForModel(provider, bare);
+    return { vision: c.vision, search: c.search, reasoning: c.reasoning };
+  };
+
+  return { getCaps };
+}
diff --git a/src/shared/hooks/useTheme.js b/src/shared/hooks/useTheme.js
new file mode 100644
index 0000000..45dae99
--- /dev/null
+++ b/src/shared/hooks/useTheme.js
@@ -0,0 +1,60 @@
+"use client";
+
+import { useEffect, useState, useSyncExternalStore } from "react";
+import useThemeStore from "@/store/themeStore";
+
+// Subscribe to system theme changes
+function subscribeToSystemTheme(callback) {
+  if (typeof window === "undefined") return () => {};
+  const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+  mediaQuery.addEventListener("change", callback);
+  return () => mediaQuery.removeEventListener("change", callback);
+}
+
+// Get current system theme preference
+function getSystemThemeSnapshot() {
+  if (typeof window === "undefined") return false;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+// Server snapshot always returns false
+function getServerSnapshot() {
+  return false;
+}
+
+export function useTheme() {
+  const { theme, setTheme, toggleTheme, initTheme } = useThemeStore();
+
+  // Use useSyncExternalStore to safely subscribe to system theme
+  const systemPrefersDark = useSyncExternalStore(
+    subscribeToSystemTheme,
+    getSystemThemeSnapshot,
+    getServerSnapshot
+  );
+
+  useEffect(() => {
+    initTheme();
+  }, [initTheme]);
+
+  // Listen for system theme changes when theme is "system"
+  useEffect(() => {
+    if (theme !== "system") return;
+
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    const handleChange = () => initTheme();
+
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, [theme, initTheme]);
+
+  // Compute isDark from current state (no effect needed)
+  const isDark = theme === "dark" || (theme === "system" && systemPrefersDark);
+
+  return {
+    theme,
+    setTheme,
+    toggleTheme,
+    isDark,
+  };
+}
+
diff --git a/src/shared/services/bootstrap.js b/src/shared/services/bootstrap.js
new file mode 100644
index 0000000..a4e03da
--- /dev/null
+++ b/src/shared/services/bootstrap.js
@@ -0,0 +1,12 @@
+import initializeApp from "./initializeApp.js";
+
+// Skip during Next.js build/prerender — bootstrap would download cloudflared, init DNS, etc.
+const isBuildPhase = process.env.NEXT_PHASE === "phase-production-build"
+  || process.env.NEXT_PHASE === "phase-export"
+  || process.env.NEXT_PHASE === "phase-static";
+
+// Server-only singleton: guard via global so HMR / re-imports don't double-init
+if (typeof window === "undefined" && !isBuildPhase && !global.__appBootstrapped) {
+  global.__appBootstrapped = true;
+  initializeApp().catch((e) => console.error("[Bootstrap] init failed:", e.message));
+}
diff --git a/src/shared/services/initializeApp.js b/src/shared/services/initializeApp.js
new file mode 100644
index 0000000..e8f5acf
--- /dev/null
+++ b/src/shared/services/initializeApp.js
@@ -0,0 +1,296 @@
+import os from "os";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { existsSync } from "fs";
+import { cleanupProviderConnections, getSettings, updateSettings, getApiKeys } from "@/lib/localDb";
+import {
+  enableTunnel, enableTailscale,
+  isTunnelManuallyDisabled, isTunnelReconnecting, isTailscaleReconnecting,
+  getTunnelService, getTailscaleService, setTunnelUnexpectedExitCallback,
+  killCloudflared, isCloudflaredRunning, ensureCloudflared,
+  isTailscaleRunning, isTailscaleRunningStrict, isDaemonAlive, startFunnel,
+  checkInternet,
+  RESTART_COOLDOWN_MS, NETWORK_SETTLE_MS,
+  WATCHDOG_INTERVAL_MS, NETWORK_CHECK_INTERVAL_MS, VIRTUAL_IFACE_REGEX,
+} from "@/lib/tunnel";
+import { getMitmStatus, startMitm, loadEncryptedPassword, initDbHooks, restoreToolDNS, removeAllDNSEntriesSync } from "@/mitm/manager";
+import { startQuotaAutoPing } from "@/shared/services/quotaAutoPing";
+import { syncToJson as syncMitmAliasCache } from "@/lib/mitmAliasCache";
+import { killAllBridges } from "@/lib/mcp/stdioSseBridge";
+
+// Inject correct paths and DB hooks into manager.js (CJS) from ESM context
+(function bootstrapMitm() {
+  if (!process.env.MITM_SERVER_PATH) {
+    try {
+      const thisFile = fileURLToPath(import.meta.url);
+      const appSrc = dirname(dirname(thisFile));
+      const candidate = join(appSrc, "mitm", "server.js");
+      if (existsSync(candidate)) process.env.MITM_SERVER_PATH = candidate;
+    } catch { /* ignore */ }
+  }
+  try { initDbHooks(getSettings, updateSettings); } catch { /* ignore */ }
+})();
+
+process.setMaxListeners(20);
+
+// Defer heavy startup work so the first HTTP request (login → dashboard) isn't
+// starved by DB cleanup, cloudflared download, lsof/DNS probes and OAuth pings.
+const STARTUP_DEFER_MS = 3000;
+
+// Survive Next.js hot reload
+const g = global.__appSingleton ??= {
+  signalHandlersRegistered: false,
+  watchdogInterval: null,
+  networkMonitorInterval: null,
+  lastNetworkFingerprint: null,
+  lastWatchdogTick: Date.now(),
+  lastOnline: null,
+  mitmStartInProgress: false,
+  tunnelAutoResumed: false,
+  tailscaleAutoResumed: false,
+};
+
+export async function initializeApp() {
+  try {
+    // Register cleanup + exit-respawn callback immediately so signals and
+    // unexpected cloudflared exits are handled even during the deferred window.
+    if (!g.signalHandlersRegistered) {
+      const cleanup = () => {
+        try { removeAllDNSEntriesSync(); } catch { /* best effort */ }
+        try { killAllBridges(); } catch { /* best effort */ }
+        killCloudflared();
+        process.exit();
+      };
+      process.on("SIGINT", cleanup);
+      process.on("SIGTERM", cleanup);
+      process.on("exit", () => { try { removeAllDNSEntriesSync(); } catch { /* ignore */ } });
+      g.signalHandlersRegistered = true;
+    }
+
+    setTunnelUnexpectedExitCallback(() => {
+      safeRestartTunnel("unexpected-exit").catch(() => {});
+    });
+
+    // Defer the heavy work — nothing here blocks incoming requests.
+    setTimeout(() => {
+      runHeavyStartup().catch((e) => console.error("[InitApp] deferred startup failed:", e.message));
+    }, STARTUP_DEFER_MS);
+  } catch (error) {
+    console.error("[InitApp] Error:", error);
+  }
+}
+
+async function runHeavyStartup() {
+  await cleanupProviderConnections();
+  const settings = await getSettings();
+
+  // Auto-resume tunnel (once per process)
+  if (settings.tunnelEnabled && !g.tunnelAutoResumed) {
+    g.tunnelAutoResumed = true;
+    console.log("[InitApp] Tunnel was enabled, auto-resuming...");
+    safeRestartTunnel("startup").catch((e) => console.log("[InitApp] Tunnel resume failed:", e.message));
+  }
+
+  // Auto-resume tailscale (once per process)
+  if (settings.tailscaleEnabled && !g.tailscaleAutoResumed) {
+    g.tailscaleAutoResumed = true;
+    console.log("[InitApp] Tailscale was enabled, auto-resuming...");
+    safeRestartTailscale("startup").catch((e) => console.log("[InitApp] Tailscale resume failed:", e.message));
+  }
+
+  ensureCloudflared().catch(() => {});
+
+  // Sync mitmAlias DB → JSON cache so standalone MITM server can read it
+  syncMitmAliasCache().catch(() => {});
+
+  startWatchdog();
+  startNetworkMonitor();
+  autoStartMitm();
+  startQuotaAutoPing();
+}
+
+async function autoStartMitm() {
+  if (g.mitmStartInProgress) return;
+  g.mitmStartInProgress = true;
+  try {
+    const settings = await getSettings();
+    if (!settings.mitmEnabled) return;
+    const mitmStatus = await getMitmStatus();
+    if (mitmStatus.running) return;
+
+    const password = await loadEncryptedPassword();
+    if (!password && process.platform !== "win32") {
+      console.log("[InitApp] MITM was enabled but no saved password found, skipping auto-start");
+      return;
+    }
+
+    const keys = await getApiKeys();
+    const activeKey = keys.find(k => k.isActive !== false);
+
+    console.log("[InitApp] MITM was enabled, auto-starting...");
+    await startMitm(activeKey?.key || "sk_9router", password);
+    console.log("[InitApp] MITM auto-started");
+    try {
+      await restoreToolDNS(password);
+      console.log("[InitApp] DNS restored from saved state");
+    } catch (e) {
+      console.log("[InitApp] DNS restore failed:", e.message);
+    }
+  } catch (err) {
+    console.log("[InitApp] MITM auto-start failed:", err.message);
+  } finally {
+    g.mitmStartInProgress = false;
+  }
+}
+
+// Cooldown only applies to repeating watchdog ticks (anti hammer-loop).
+// Network/exit events are one-shot transitions → bypass to recover fast.
+const FORCE_RESTART_REASONS = /^(startup|netchange|sleep|sleep\+netchange|online|unexpected-exit)$/;
+
+// ─── Safe restart (4 guards: spawn / cooldown / alive / internet) ────────────
+
+async function safeRestartTunnel(reason) {
+  const svc = getTunnelService();
+  const settings = await getSettings();
+  if (!settings.tunnelEnabled) return;
+  if (svc.cancelToken.cancelled) return;
+  if (svc.spawnInProgress) return;
+
+  const force = FORCE_RESTART_REASONS.test(reason);
+
+  // Process alive = trust cloudflared (self-reconnects via --retries 99, keeps same URL).
+  // Killing a live process on network change drops the tunnel and rotates the quick-tunnel URL.
+  if (isCloudflaredRunning()) return;
+
+  if (!force && Date.now() - svc.lastRestartAt < RESTART_COOLDOWN_MS) {
+    console.log(`[Tunnel] degraded but cooldown active, skip (${reason})`);
+    return;
+  }
+  if (!await checkInternet()) return;
+
+  console.log(`[Tunnel] safeRestart (${reason}) — tunnel unreachable${force ? " [force]" : ""}`);
+  try {
+    await enableTunnel();
+    svc.lastRestartAt = Date.now();
+    console.log("[Tunnel] restart success");
+  } catch (err) {
+    if (!/cloudflared killed|tunnel cancelled/.test(err.message)) {
+      console.log("[Tunnel] restart failed:", err.message);
+    }
+  }
+}
+
+async function safeRestartTailscale(reason) {
+  const svc = getTailscaleService();
+  const settings = await getSettings();
+  if (!settings.tailscaleEnabled) return;
+  if (svc.cancelToken.cancelled) return;
+  if (svc.spawnInProgress) return;
+
+  // Tailscale daemon is OS-level with built-in reconnect; trust it when running (even on netchange).
+  // Startup uses strict probe — cached state is cold after process/dev reload.
+  const running = reason === "startup" ? await isTailscaleRunningStrict() : isTailscaleRunning();
+  if (running) return;
+
+  // Daemon alive but funnel dropped → recover funnel only; never full-restart (preserves login/daemon).
+  if (isDaemonAlive() && svc.activeLocalPort) {
+    try {
+      await startFunnel(svc.activeLocalPort);
+      svc.lastRestartAt = Date.now();
+      console.log("[Tailscale] funnel re-established (daemon alive)");
+    } catch (err) {
+      console.log("[Tailscale] funnel recovery failed:", err.message);
+    }
+    return;
+  }
+
+  const force = FORCE_RESTART_REASONS.test(reason);
+  if (!force && Date.now() - svc.lastRestartAt < RESTART_COOLDOWN_MS) {
+    console.log(`[Tailscale] degraded but cooldown active, skip (${reason})`);
+    return;
+  }
+  if (!await checkInternet()) return;
+
+  console.log(`[Tailscale] safeRestart (${reason}) — daemon not running${force ? " [force]" : ""}`);
+  try {
+    await enableTailscale();
+    svc.lastRestartAt = Date.now();
+    console.log("[Tailscale] restart success");
+  } catch (err) {
+    console.log("[Tailscale] restart failed:", err.message);
+  }
+}
+
+// ─── Watchdog: 60s tick check both services ──────────────────────────────────
+
+function startWatchdog() {
+  if (g.watchdogInterval) return;
+  g.watchdogInterval = setInterval(() => {
+    safeRestartTunnel("watchdog").catch(() => {});
+    safeRestartTailscale("watchdog").catch(() => {});
+  }, WATCHDOG_INTERVAL_MS);
+  if (g.watchdogInterval.unref) g.watchdogInterval.unref();
+}
+
+// ─── Network monitor: detect IPv4 fingerprint change + sleep/wake ────────────
+
+function getNetworkFingerprint() {
+  const interfaces = os.networkInterfaces();
+  const active = [];
+  for (const [name, addrs] of Object.entries(interfaces)) {
+    if (!addrs) continue;
+    if (VIRTUAL_IFACE_REGEX.test(name)) continue;
+    for (const addr of addrs) {
+      if (!addr.internal && addr.family === "IPv4") {
+        active.push(`${name}:${addr.address}`);
+      }
+    }
+  }
+  return active.sort().join("|");
+}
+
+function startNetworkMonitor() {
+  if (g.networkMonitorInterval) return;
+
+  g.lastNetworkFingerprint = getNetworkFingerprint();
+  g.lastWatchdogTick = Date.now();
+  g.lastOnline = null;
+
+  g.networkMonitorInterval = setInterval(async () => {
+    try {
+      const now = Date.now();
+      const elapsed = now - g.lastWatchdogTick;
+      g.lastWatchdogTick = now;
+
+      const currentFingerprint = getNetworkFingerprint();
+      const networkChanged = currentFingerprint !== g.lastNetworkFingerprint;
+      const wasSleep = elapsed > NETWORK_CHECK_INTERVAL_MS * 6;
+      if (networkChanged) g.lastNetworkFingerprint = currentFingerprint;
+
+      // Real reachability check (TCP 1.1.1.1:443) — not just interface presence
+      const online = await checkInternet();
+      const wasOffline = g.lastOnline === false;
+      g.lastOnline = online;
+
+      if (!online) return; // no internet → idle, don't restart
+
+      const onlineEdge = wasOffline; // offline → online transition
+      if (!networkChanged && !wasSleep && !onlineEdge) return;
+
+      // Wait for DHCP/DNS to settle before probing
+      await new Promise((r) => setTimeout(r, NETWORK_SETTLE_MS));
+
+      const reason = onlineEdge ? "online"
+        : wasSleep && networkChanged ? "sleep+netchange"
+        : wasSleep ? "sleep" : "netchange";
+      safeRestartTunnel(reason).catch(() => {});
+      safeRestartTailscale(reason).catch(() => {});
+    } catch (err) {
+      console.log("[NetworkMonitor] error:", err.message);
+    }
+  }, NETWORK_CHECK_INTERVAL_MS);
+
+  if (g.networkMonitorInterval.unref) g.networkMonitorInterval.unref();
+}
+
+export default initializeApp;
diff --git a/src/shared/services/quotaAutoPing.js b/src/shared/services/quotaAutoPing.js
new file mode 100644
index 0000000..694a5e2
--- /dev/null
+++ b/src/shared/services/quotaAutoPing.js
@@ -0,0 +1,298 @@
+// Quota auto-ping scheduler: warms 5h windows by sending tiny opt-in requests right after reset.
+import "open-sse/index.js";
+
+import { getSettings, getProviderConnections, updateProviderConnection } from "@/lib/localDb";
+import { getClaudeUsage } from "open-sse/services/usage/claude.js";
+import { getCodexUsage } from "open-sse/services/usage/codex.js";
+import { getExecutor } from "open-sse/executors/index.js";
+import { CLAUDE_CLI_SPOOF_HEADERS } from "open-sse/providers/shared.js";
+import { proxyAwareFetch } from "open-sse/utils/proxyFetch.js";
+import { resolveConnectionProxyConfig } from "@/lib/network/connectionProxy";
+import { refreshAndUpdateCredentials } from "@/app/api/usage/[connectionId]/route.js";
+import { QUOTA_AUTOPING_CONFIG } from "@/shared/constants/config";
+
+const C = QUOTA_AUTOPING_CONFIG;
+const CLAUDE_PING_URL = "https://api.anthropic.com/v1/messages?beta=true";
+
+const providerHandlers = {
+  claude: {
+    getUsage: getClaudeUsage,
+    sendPing: sendClaudePing,
+  },
+  codex: {
+    getUsage: getCodexUsage,
+    sendPing: sendCodexPing,
+  },
+};
+
+// Survive Next.js hot reload and keep one scheduler per server process.
+const g = (global.__quotaAutoPing ??= {
+  interval: null,
+  running: false,
+  resetCache: {},
+  failureCache: {},
+});
+
+function cacheKey(provider, connectionId) {
+  return `${provider}:${connectionId}`;
+}
+
+function normalizeResetKey(resetAt) {
+  const ms = new Date(resetAt).getTime();
+  if (!Number.isFinite(ms)) return resetAt;
+  return new Date(Math.floor(ms / 60000) * 60000).toISOString();
+}
+
+function getResetDriftMs(previousResetAt, nextResetAt) {
+  const previousMs = new Date(previousResetAt).getTime();
+  const nextMs = new Date(nextResetAt).getTime();
+  if (!Number.isFinite(previousMs) || !Number.isFinite(nextMs)) return 0;
+  return nextMs - previousMs;
+}
+
+function toFiniteNumber(value, fallback = null) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return fallback;
+}
+
+function isQuotaExhausted(quota) {
+  if (!quota || quota.unlimited === true) return false;
+  const remaining = toFiniteNumber(quota.remaining);
+  if (remaining !== null) return remaining <= 0;
+
+  const used = toFiniteNumber(quota.used);
+  const total = toFiniteNumber(quota.total);
+  return total !== null && total > 0 && used !== null && used >= total;
+}
+
+function wasPingedRecently(connection, intervalMs, nowMs = Date.now()) {
+  if (!intervalMs) return false;
+  const lastPingAtMs = new Date(connection.lastPingAt).getTime();
+  return Number.isFinite(lastPingAtMs) && nowMs - lastPingAtMs < intervalMs;
+}
+
+function isBlockingQuotaName(name, sessionKey) {
+  if (name === sessionKey) return false;
+  return !String(name).toLowerCase().includes("session");
+}
+
+function hasExhaustedBlockingQuota(quotas, sessionKey) {
+  return Object.entries(quotas || {}).some(([name, quota]) => isBlockingQuotaName(name, sessionKey) && isQuotaExhausted(quota));
+}
+
+function shouldPingForReset(providerConfig, cachedReset, resetAt, now) {
+  if (providerConfig.pingWhenResetAtSlides) {
+    return Boolean(cachedReset) && getResetDriftMs(cachedReset, resetAt) >= (providerConfig.resetAtDriftMs || 0);
+  }
+
+  const resetMs = new Date(resetAt).getTime();
+  return Number.isFinite(resetMs) && now >= resetMs - C.pingLeadMs;
+}
+
+function buildProxyOptions(cfg) {
+  return {
+    connectionProxyEnabled: cfg.connectionProxyEnabled === true,
+    connectionProxyUrl: cfg.connectionProxyUrl || "",
+    connectionNoProxy: cfg.connectionNoProxy || "",
+    vercelRelayUrl: cfg.vercelRelayUrl || "",
+    strictProxy: false,
+  };
+}
+
+async function sendClaudePing(connection, providerConfig, proxyOptions, deps) {
+  const res = await deps.proxyAwareFetch(CLAUDE_PING_URL, {
+    method: "POST",
+    headers: {
+      ...CLAUDE_CLI_SPOOF_HEADERS,
+      "Authorization": `Bearer ${connection.accessToken}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      model: providerConfig.pingModel,
+      max_tokens: providerConfig.pingMaxTokens,
+      messages: [{ role: "user", content: providerConfig.pingText }],
+    }),
+  }, proxyOptions);
+  return res.ok;
+}
+
+function buildCodexPingInput(text) {
+  return [{
+    type: "message",
+    role: "user",
+    content: [{ type: "input_text", text }],
+  }];
+}
+
+async function drainResponseBody(response) {
+  if (typeof response?.text === "function") {
+    await response.text();
+    return;
+  }
+
+  const reader = response?.body?.getReader?.();
+  if (!reader) return;
+
+  try {
+    while (true) {
+      const { done } = await reader.read();
+      if (done) return;
+    }
+  } finally {
+    reader.releaseLock?.();
+  }
+}
+
+async function sendCodexPing(connection, providerConfig, proxyOptions, deps) {
+  const executor = deps.getExecutor("codex");
+  const { response } = await executor.execute({
+    model: providerConfig.pingModel,
+    stream: true,
+    credentials: {
+      accessToken: connection.accessToken,
+      connectionId: connection.id,
+      providerSpecificData: connection.providerSpecificData,
+    },
+    proxyOptions,
+    log: console,
+    body: {
+      model: providerConfig.pingModel,
+      input: buildCodexPingInput(providerConfig.pingText),
+      instructions: providerConfig.pingInstructions,
+      reasoning: providerConfig.pingReasoningEffort
+        ? { effort: providerConfig.pingReasoningEffort, summary: "auto" }
+        : undefined,
+      store: false,
+      stream: true,
+    },
+  });
+  if (!response.ok) {
+    try { await response.body?.cancel?.(); } catch { /* noop */ }
+    return false;
+  }
+
+  // Codex only starts the 5h window after the streaming response completes.
+  await drainResponseBody(response);
+  return true;
+}
+
+function shouldSkipAfterFailure(state, key, nowMs = Date.now()) {
+  const failedAt = state.failureCache[key];
+  return failedAt && nowMs - failedAt < C.failureCooldownMs;
+}
+
+async function pingConnection(conn, provider, providerConfig, handler, deps, state = g) {
+  const key = cacheKey(provider, conn.id);
+
+  // resetAt is stable for time-based windows; Codex polls every tick because inactive windows slide forward.
+  const cachedReset = state.resetCache[key];
+  if (!providerConfig.pingWhenResetAtSlides && cachedReset && Date.now() < new Date(cachedReset).getTime() - C.refreshAheadMs) return;
+
+  // Avoid hammering provider auth/quota endpoints if a ping failed recently.
+  if (shouldSkipAfterFailure(state, key)) return;
+
+  const proxyCfg = await deps.resolveConnectionProxyConfig(conn.providerSpecificData);
+  const proxyOptions = buildProxyOptions(proxyCfg);
+
+  let connection = conn;
+  try {
+    const r = await deps.refreshAndUpdateCredentials(connection, false, proxyOptions);
+    connection = r.connection;
+  } catch (e) {
+    state.failureCache[key] = Date.now();
+    console.warn(`[AutoPing] ${provider}:${conn.id}: refresh failed: ${e.message}`);
+    return;
+  }
+
+  const usage = await handler.getUsage(connection.accessToken, proxyOptions);
+  const quotas = usage?.quotas || {};
+  const quota = quotas?.[providerConfig.quotaKey];
+  const resetAt = quota?.resetAt;
+  if (!resetAt) return;
+
+  state.resetCache[key] = resetAt;
+
+  if (providerConfig.skipWhenBlockingQuotaExhausted && hasExhaustedBlockingQuota(quotas, providerConfig.quotaKey)) return;
+  if (isQuotaExhausted(quota)) return;
+
+  const now = Date.now();
+  const resetKey = normalizeResetKey(resetAt);
+  const lastPingedResetKey = connection.lastPingedResetKey || normalizeResetKey(connection.lastPingedResetAt);
+
+  // Claude waits for reset. Codex pings only when resetAt slides, which means the 5h window is inactive.
+  if (!shouldPingForReset(providerConfig, cachedReset, resetAt, now)) return;
+  if (wasPingedRecently(connection, providerConfig.minPingIntervalMs, now)) return;
+  if (lastPingedResetKey === resetKey) return;
+
+  const ok = await handler.sendPing(connection, providerConfig, proxyOptions, deps);
+  if (!ok) {
+    // Do not mark reset as pinged unless upstream accepted the tiny request.
+    state.failureCache[key] = Date.now();
+    console.warn(`[AutoPing] ${provider}:${connection.id}: ping failed (reset ${resetAt})`);
+    return;
+  }
+
+  delete state.failureCache[key];
+  await deps.updateProviderConnection(connection.id, {
+    lastPingedResetAt: resetAt,
+    lastPingedResetKey: resetKey,
+    lastPingAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  });
+  console.log(`[AutoPing] ${provider}:${connection.id}: ping sent (reset ${resetAt})`);
+}
+
+function createDefaultDeps() {
+  return {
+    getSettings,
+    getProviderConnections,
+    updateProviderConnection,
+    resolveConnectionProxyConfig,
+    refreshAndUpdateCredentials,
+    proxyAwareFetch,
+    getExecutor,
+  };
+}
+
+export async function runQuotaAutoPingTick(deps = createDefaultDeps(), state = g) {
+  if (state.running) return;
+  state.running = true;
+  try {
+    const settings = await deps.getSettings();
+
+    for (const [provider, providerConfig] of Object.entries(C.providers)) {
+      const handler = providerHandlers[provider];
+      if (!handler) continue;
+
+      const enabledMap = settings?.[providerConfig.settingsKey]?.connections || {};
+      if (Object.keys(enabledMap).length === 0) continue;
+
+      const conns = await deps.getProviderConnections({ provider, isActive: true });
+      const targets = conns.filter((conn) => conn.authType === "oauth" && enabledMap[conn.id] === true);
+      for (const conn of targets) {
+        try {
+          await pingConnection(conn, provider, providerConfig, handler, deps, state);
+        } catch (e) {
+          state.failureCache[cacheKey(provider, conn.id)] = Date.now();
+          console.warn(`[AutoPing] ${provider}:${conn.id}: ${e.message}`);
+        }
+      }
+    }
+  } catch (e) {
+    console.warn("[AutoPing] tick error:", e.message);
+  } finally {
+    state.running = false;
+  }
+}
+
+export function startQuotaAutoPing() {
+  if (g.interval) return;
+  console.log("[AutoPing] scheduler started");
+  runQuotaAutoPingTick().catch(() => {});
+  g.interval = setInterval(() => { runQuotaAutoPingTick().catch(() => {}); }, C.tickIntervalMs);
+  if (g.interval.unref) g.interval.unref();
+}
diff --git a/src/shared/utils/api.js b/src/shared/utils/api.js
new file mode 100644
index 0000000..5712ef9
--- /dev/null
+++ b/src/shared/utils/api.js
@@ -0,0 +1,93 @@
+/**
+ * API utility functions for making HTTP requests
+ */
+
+const DEFAULT_HEADERS = {
+  "Content-Type": "application/json",
+};
+
+/**
+ * Make a GET request
+ * @param {string} url - API endpoint
+ * @param {object} options - Fetch options
+ * @returns {Promise<object>}
+ */
+export async function get(url, options = {}) {
+  const response = await fetch(url, {
+    method: "GET",
+    headers: { ...DEFAULT_HEADERS, ...options.headers },
+    ...options,
+  });
+  return handleResponse(response);
+}
+
+/**
+ * Make a POST request
+ * @param {string} url - API endpoint
+ * @param {object} data - Request body
+ * @param {object} options - Fetch options
+ * @returns {Promise<object>}
+ */
+export async function post(url, data, options = {}) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { ...DEFAULT_HEADERS, ...options.headers },
+    body: JSON.stringify(data),
+    ...options,
+  });
+  return handleResponse(response);
+}
+
+/**
+ * Make a PUT request
+ * @param {string} url - API endpoint
+ * @param {object} data - Request body
+ * @param {object} options - Fetch options
+ * @returns {Promise<object>}
+ */
+export async function put(url, data, options = {}) {
+  const response = await fetch(url, {
+    method: "PUT",
+    headers: { ...DEFAULT_HEADERS, ...options.headers },
+    body: JSON.stringify(data),
+    ...options,
+  });
+  return handleResponse(response);
+}
+
+/**
+ * Make a DELETE request
+ * @param {string} url - API endpoint
+ * @param {object} options - Fetch options
+ * @returns {Promise<object>}
+ */
+export async function del(url, options = {}) {
+  const response = await fetch(url, {
+    method: "DELETE",
+    headers: { ...DEFAULT_HEADERS, ...options.headers },
+    ...options,
+  });
+  return handleResponse(response);
+}
+
+/**
+ * Handle API response
+ * @param {Response} response - Fetch response
+ * @returns {Promise<object>}
+ */
+async function handleResponse(response) {
+  const data = await response.json();
+
+  if (!response.ok) {
+    const error = new Error(data.error || "An error occurred");
+    error.status = response.status;
+    error.data = data;
+    throw error;
+  }
+
+  return data;
+}
+
+const api = { get, post, put, del };
+export default api;
+
diff --git a/src/shared/utils/apiKey.js b/src/shared/utils/apiKey.js
new file mode 100644
index 0000000..046abce
--- /dev/null
+++ b/src/shared/utils/apiKey.js
@@ -0,0 +1,98 @@
+import crypto from "crypto";
+
+const API_KEY_SECRET = process.env.API_KEY_SECRET || "endpoint-proxy-api-key-secret";
+
+/**
+ * Generate 6-char random keyId
+ */
+function generateKeyId() {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  for (let i = 0; i < 6; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+/**
+ * Generate CRC (8-char HMAC)
+ */
+function generateCrc(machineId, keyId) {
+  return crypto
+    .createHmac("sha256", API_KEY_SECRET)
+    .update(machineId + keyId)
+    .digest("hex")
+    .slice(0, 8);
+}
+
+/**
+ * Generate API key with machineId embedded
+ * Format: sk-{machineId}-{keyId}-{crc8}
+ * @param {string} machineId - 16-char machine ID
+ * @returns {{ key: string, keyId: string }}
+ */
+export function generateApiKeyWithMachine(machineId) {
+  const keyId = generateKeyId();
+  const crc = generateCrc(machineId, keyId);
+  const key = `sk-${machineId}-${keyId}-${crc}`;
+  return { key, keyId };
+}
+
+/**
+ * Parse API key and extract machineId + keyId
+ * Supports both formats:
+ * - New: sk-{machineId}-{keyId}-{crc8}
+ * - Old: sk-{random8}
+ * @param {string} apiKey
+ * @returns {{ machineId: string, keyId: string, isNewFormat: boolean } | null}
+ */
+export function parseApiKey(apiKey) {
+  if (!apiKey || !apiKey.startsWith("sk-")) return null;
+
+  const parts = apiKey.split("-");
+  
+  // New format: sk-{machineId}-{keyId}-{crc8} = 4 parts
+  if (parts.length === 4) {
+    const [, machineId, keyId, crc] = parts;
+    
+    // Validate CRC
+    const expectedCrc = generateCrc(machineId, keyId);
+    if (crc !== expectedCrc) return null;
+    
+    return { machineId, keyId, isNewFormat: true };
+  }
+  
+  // Old format: sk-{random8} = 2 parts
+  if (parts.length === 2) {
+    return { machineId: null, keyId: parts[1], isNewFormat: false };
+  }
+  
+  return null;
+}
+
+/**
+ * Verify API key CRC (only for new format)
+ * @param {string} apiKey
+ * @returns {boolean}
+ */
+export function verifyApiKeyCrc(apiKey) {
+  const parsed = parseApiKey(apiKey);
+  if (!parsed) return false;
+  
+  // Old format doesn't have CRC, always valid if parsed
+  if (!parsed.isNewFormat) return true;
+  
+  // New format already verified in parseApiKey
+  return true;
+}
+
+/**
+ * Check if API key is new format (contains machineId)
+ * @param {string} apiKey
+ * @returns {boolean}
+ */
+export function isNewFormatKey(apiKey) {
+  const parsed = parseApiKey(apiKey);
+  return parsed?.isNewFormat === true;
+}
+
diff --git a/src/shared/utils/clineAuth.js b/src/shared/utils/clineAuth.js
new file mode 100644
index 0000000..a5bda1c
--- /dev/null
+++ b/src/shared/utils/clineAuth.js
@@ -0,0 +1 @@
+export * from "../../../open-sse/shared/clineAuth.js";
diff --git a/src/shared/utils/cn.js b/src/shared/utils/cn.js
new file mode 100644
index 0000000..cbcfe06
--- /dev/null
+++ b/src/shared/utils/cn.js
@@ -0,0 +1,11 @@
+// Utility function to merge class names
+// Handles conditional classes and removes duplicates
+
+export function cn(...classes) {
+  return classes
+    .filter(Boolean)
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
diff --git a/src/shared/utils/connectionStatus.js b/src/shared/utils/connectionStatus.js
new file mode 100644
index 0000000..5d44fdf
--- /dev/null
+++ b/src/shared/utils/connectionStatus.js
@@ -0,0 +1,6 @@
+export function getStatusVariant(isActive, effectiveStatus) {
+  if (isActive === false) return "default";
+  if (effectiveStatus === "active" || effectiveStatus === "success") return "success";
+  if (effectiveStatus === "error" || effectiveStatus === "expired" || effectiveStatus === "unavailable") return "error";
+  return "default";
+}
diff --git a/src/shared/utils/index.js b/src/shared/utils/index.js
new file mode 100644
index 0000000..f64461a
--- /dev/null
+++ b/src/shared/utils/index.js
@@ -0,0 +1,40 @@
+// Shared Utils - Export all
+export { cn } from "./cn";
+export * as api from "./api";
+
+import { v4 as uuidv4 } from "uuid";
+
+/**
+ * Generate unique ID (UUID v4)
+ * @returns {string} UUID v4 string
+ */
+export const generateId = uuidv4;
+
+/**
+ * Extract error code from error message (401, 429, 503...)
+ * @param {string} lastError - Error message
+ * @returns {string|null} Error code or null
+ */
+export function getErrorCode(lastError) {
+  if (!lastError) return null;
+  const match = lastError.match(/\b([45]\d{2})\b/);
+  return match ? match[1] : "ERR";
+}
+
+/**
+ * Get relative time string (e.g. "5 min ago")
+ * @param {string} isoDate - ISO date string
+ * @returns {string} Relative time
+ */
+export function getRelativeTime(isoDate) {
+  if (!isoDate) return "";
+  const diff = Date.now() - new Date(isoDate).getTime();
+  const mins = Math.floor(diff / 60000);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
diff --git a/src/shared/utils/machine.js b/src/shared/utils/machine.js
new file mode 100644
index 0000000..8979a14
--- /dev/null
+++ b/src/shared/utils/machine.js
@@ -0,0 +1,6 @@
+import { getConsistentMachineId } from "./machineId";
+
+// Get machine ID using node-machine-id with salt
+export async function getMachineId() {
+  return await getConsistentMachineId();
+}
diff --git a/src/shared/utils/machineId.js b/src/shared/utils/machineId.js
new file mode 100644
index 0000000..92ceb21
--- /dev/null
+++ b/src/shared/utils/machineId.js
@@ -0,0 +1,66 @@
+import { machineIdSync } from 'node-machine-id';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DATA_DIR } from '@/lib/dataDir';
+
+const MACHINE_ID_FILE = path.join(DATA_DIR, 'machine-id');
+const AUTH_DIR = path.join(DATA_DIR, 'auth');
+const CLI_SECRET_FILE = path.join(AUTH_DIR, 'cli-secret');
+const CLI_AUTH_SALT = '9r-cli-auth';
+let cachedRawId = null;
+let cachedCliSecret = null;
+
+// Persist raw machine ID to file → guarantees CLI/server/middleware see same value
+// even when machineIdSync fails or returns inconsistent values across runtimes.
+function loadRawMachineId() {
+  if (cachedRawId) return cachedRawId;
+  try {
+    cachedRawId = fs.readFileSync(MACHINE_ID_FILE, 'utf8').trim();
+    if (cachedRawId) return cachedRawId;
+  } catch {}
+  try {
+    cachedRawId = machineIdSync();
+  } catch {
+    cachedRawId = crypto.randomUUID();
+  }
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    fs.writeFileSync(MACHINE_ID_FILE, cachedRawId, { mode: 0o600 });
+  } catch {}
+  return cachedRawId;
+}
+
+// Random secret persisted on first run → unpredictable CLI token even when machineId leaks.
+function loadCliSecret() {
+  if (cachedCliSecret) return cachedCliSecret;
+  try {
+    cachedCliSecret = fs.readFileSync(CLI_SECRET_FILE, 'utf8').trim();
+    if (cachedCliSecret) return cachedCliSecret;
+  } catch {}
+  cachedCliSecret = crypto.randomBytes(32).toString('hex');
+  try {
+    fs.mkdirSync(AUTH_DIR, { recursive: true });
+    fs.writeFileSync(CLI_SECRET_FILE, cachedCliSecret, { mode: 0o600 });
+  } catch {}
+  return cachedCliSecret;
+}
+
+export async function getConsistentMachineId(salt = null) {
+  const saltValue = salt || process.env.MACHINE_ID_SALT || 'endpoint-proxy-salt';
+  const raw = loadRawMachineId();
+  const extra = saltValue === CLI_AUTH_SALT ? loadCliSecret() : '';
+  return crypto.createHash('sha256').update(raw + saltValue + extra).digest('hex').substring(0, 16);
+}
+
+export async function getRawMachineId() {
+  return loadRawMachineId();
+}
+
+/**
+ * Check if we're running in browser or server environment
+ * @returns {boolean} True if in browser, false if in server
+ */
+export function isBrowser() {
+  return typeof window !== 'undefined';
+}
diff --git a/src/shared/utils/providerCustomModels.js b/src/shared/utils/providerCustomModels.js
new file mode 100644
index 0000000..1e7c7a7
--- /dev/null
+++ b/src/shared/utils/providerCustomModels.js
@@ -0,0 +1,54 @@
+function modelType(model) {
+  return model?.kind || model?.type || "llm";
+}
+
+export function getProviderCustomModelRows({
+  customModels = [],
+  modelAliases = {},
+  providerAlias,
+  builtInModels = [],
+  type = "llm",
+  includeLegacyAliases = true,
+}) {
+  const builtInIds = new Set(builtInModels.map((model) => model.id));
+  const seenFullModels = new Set();
+  const rows = [];
+
+  for (const model of customModels) {
+    if (!model?.id || model.providerAlias !== providerAlias) continue;
+    const rowType = modelType(model);
+    if (type && rowType !== type) continue;
+    if (builtInIds.has(model.id)) continue;
+
+    const fullModel = `${providerAlias}/${model.id}`;
+    if (seenFullModels.has(fullModel)) continue;
+    seenFullModels.add(fullModel);
+    rows.push({
+      id: model.id,
+      name: model.name || model.id,
+      fullModel,
+      source: "custom",
+      type: rowType,
+    });
+  }
+
+  if (!includeLegacyAliases) return rows;
+
+  const prefix = `${providerAlias}/`;
+  for (const [alias, fullModel] of Object.entries(modelAliases || {})) {
+    if (typeof fullModel !== "string" || !fullModel.startsWith(prefix)) continue;
+    const id = fullModel.slice(prefix.length);
+    if (!id || builtInIds.has(id) || seenFullModels.has(fullModel)) continue;
+
+    seenFullModels.add(fullModel);
+    rows.push({
+      id,
+      alias,
+      fullModel,
+      source: "legacyAlias",
+      type: type || "llm",
+    });
+  }
+
+  return rows;
+}
diff --git a/src/shared/utils/providerModelsFetcher.js b/src/shared/utils/providerModelsFetcher.js
new file mode 100644
index 0000000..3ba1bab
--- /dev/null
+++ b/src/shared/utils/providerModelsFetcher.js
@@ -0,0 +1,30 @@
+// Fetch and cache suggested models for providers that expose a public models API
+// Fetches via backend proxy to avoid CORS issues
+
+const CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const cache = new Map(); // key: fetcher.url → { data, expiresAt }
+
+/**
+ * Fetch suggested models for a provider using its modelsFetcher config.
+ * Results are cached in-memory for CACHE_TTL_MS.
+ * @param {{ url: string, type: string }} fetcher
+ * @returns {Promise<Array<{ id: string, name: string, contextLength?: number }>>}
+ */
+export async function fetchSuggestedModels(fetcher) {
+  if (!fetcher?.url || !fetcher?.type) return [];
+
+  const cached = cache.get(fetcher.url);
+  if (cached && Date.now() < cached.expiresAt) return cached.data;
+
+  try {
+    const params = new URLSearchParams({ url: fetcher.url, type: fetcher.type });
+    const res = await fetch(`/api/providers/suggested-models?${params}`);
+    if (!res.ok) return [];
+    const json = await res.json();
+    const data = json.data ?? [];
+    cache.set(fetcher.url, { data, expiresAt: Date.now() + CACHE_TTL_MS });
+    return data;
+  } catch {
+    return [];
+  }
+}
diff --git a/src/shared/utils/ssrfGuard.js b/src/shared/utils/ssrfGuard.js
new file mode 100644
index 0000000..40336ac
--- /dev/null
+++ b/src/shared/utils/ssrfGuard.js
@@ -0,0 +1,56 @@
+// SSRF guard: block internal/private/metadata targets for server-side fetch.
+
+const BLOCKED_HOSTNAMES = new Set(["localhost", "ip6-localhost", "ip6-loopback"]);
+const BLOCKED_SUFFIXES = [".internal", ".local", ".localhost"];
+
+// Parse dotted IPv4 to 32-bit integer, or null if not a valid IPv4 literal.
+function ipv4ToInt(host) {
+  const parts = host.split(".");
+  if (parts.length !== 4) return null;
+  let value = 0;
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null;
+    const octet = Number(part);
+    if (octet > 255) return null;
+    value = value * 256 + octet;
+  }
+  return value >>> 0;
+}
+
+// Private/reserved IPv4 ranges as [startInt, maskBits].
+const BLOCKED_V4_RANGES = [
+  [ipv4ToInt("0.0.0.0"), 8],
+  [ipv4ToInt("10.0.0.0"), 8],
+  [ipv4ToInt("127.0.0.0"), 8],
+  [ipv4ToInt("169.254.0.0"), 16],
+  [ipv4ToInt("172.16.0.0"), 12],
+  [ipv4ToInt("192.168.0.0"), 16],
+];
+
+function isBlockedIpv4(host) {
+  const ip = ipv4ToInt(host);
+  if (ip === null) return false;
+  return BLOCKED_V4_RANGES.some(([base, bits]) => {
+    const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0;
+    return (ip & mask) === (base & mask);
+  });
+}
+
+function isBlockedIpv6(host) {
+  const h = host.replace(/^\[|\]$/g, "").toLowerCase();
+  const v4Mapped = h.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (v4Mapped) return isBlockedIpv4(v4Mapped[1]);
+  if (h === "::1" || h === "::") return true;
+  return h.startsWith("fe80:") || h.startsWith("fc") || h.startsWith("fd");
+}
+
+// Throw if URL targets a non-public host. Caller should map to 400.
+export function assertPublicUrl(rawUrl) {
+  const parsed = new URL(rawUrl);
+  const host = parsed.hostname.toLowerCase();
+
+  if (BLOCKED_HOSTNAMES.has(host)) throw new Error("Blocked URL: internal host");
+  if (BLOCKED_SUFFIXES.some((s) => host.endsWith(s))) throw new Error("Blocked URL: internal host");
+  if (isBlockedIpv4(host)) throw new Error("Blocked URL: private IP");
+  if (host.includes(":") && isBlockedIpv6(host)) throw new Error("Blocked URL: private IP");
+}
diff --git a/src/sse/handlers/chat.js b/src/sse/handlers/chat.js
new file mode 100644
index 0000000..77f450c
--- /dev/null
+++ b/src/sse/handlers/chat.js
@@ -0,0 +1,287 @@
+import "open-sse/index.js";
+
+import {
+  getProviderCredentials,
+  markAccountUnavailable,
+  clearAccountError,
+  extractApiKey,
+  isValidApiKey,
+} from "../services/auth.js";
+import { cacheClaudeHeaders } from "open-sse/utils/claudeHeaderCache.js";
+import { getSettings } from "@/lib/localDb";
+import { getModelInfo, getComboModels } from "../services/model.js";
+import { handleChatCore } from "open-sse/handlers/chatCore.js";
+import { DEFAULT_HEADROOM_URL } from "@/lib/headroom/detect";
+import { getTransform as getPxpipeTransform } from "@/lib/pxpipe/loader.js";
+import { appendPxpipeEvent } from "@/lib/pxpipe/events.js";
+import { errorResponse, unavailableResponse } from "open-sse/utils/error.js";
+import { handleComboChat, handleFusionChat } from "open-sse/services/combo.js";
+import { handleBypassRequest } from "open-sse/utils/bypassHandler.js";
+import { HTTP_STATUS } from "open-sse/config/runtimeConfig.js";
+import { detectFormatByEndpoint } from "open-sse/translator/formats.js";
+import * as log from "../utils/logger.js";
+import { updateProviderCredentials, checkAndRefreshToken } from "../services/tokenRefresh.js";
+import { getProjectIdForConnection } from "open-sse/services/projectId.js";
+
+/**
+ * Handle chat completion request
+ * Supports: OpenAI, Claude, Gemini, OpenAI Responses API formats
+ * Format detection and translation handled by translator
+ */
+export async function handleChat(request, clientRawRequest = null) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    log.warn("CHAT", "Invalid JSON body");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid JSON body");
+  }
+
+  // Build clientRawRequest for logging (if not provided)
+  if (!clientRawRequest) {
+    const url = new URL(request.url);
+    clientRawRequest = {
+      endpoint: url.pathname,
+      body,
+      headers: Object.fromEntries(request.headers.entries())
+    };
+  }
+  cacheClaudeHeaders(clientRawRequest.headers);
+
+  const modelStr = body.model;
+
+  // Request summary is emitted as the unified "▶" line in chatCore (has fmt/thinking/account)
+
+  // Log API key (masked)
+  const authHeader = request.headers.get("Authorization");
+  const apiKey = extractApiKey(request);
+  if (authHeader && apiKey) {
+    const masked = log.maskKey(apiKey);
+    log.debug("AUTH", `API Key: ${masked}`);
+  } else {
+    log.debug("AUTH", "No API key provided (local mode)");
+  }
+
+  // Enforce API key if enabled in settings
+  const settings = await getSettings();
+  if (settings.requireApiKey) {
+    if (!apiKey) {
+      log.warn("AUTH", "Missing API key (requireApiKey=true)");
+      return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Missing API key");
+    }
+    const valid = await isValidApiKey(apiKey);
+    if (!valid) {
+      log.warn("AUTH", "Invalid API key (requireApiKey=true)");
+      return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Invalid API key");
+    }
+  }
+
+  if (!modelStr) {
+    log.warn("CHAT", "Missing model");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing model");
+  }
+
+  // Bypass naming/warmup requests before combo rotation to avoid wasting rotation slots
+  const userAgent = request?.headers?.get("user-agent") || "";
+  const bypassResponse = handleBypassRequest(body, modelStr, userAgent, !!settings.ccFilterNaming);
+  if (bypassResponse) return bypassResponse.response || bypassResponse;
+
+  // Check if model is a combo (has multiple models with fallback)
+  const comboModels = await getComboModels(modelStr);
+  if (comboModels) {
+    // Check for combo-specific strategy first, fallback to global
+    const comboStrategies = settings.comboStrategies || {};
+    const comboSpecificStrategy = comboStrategies[modelStr]?.fallbackStrategy;
+    const comboStrategy = comboSpecificStrategy || settings.comboStrategy || "fallback";
+
+    if (comboStrategy === "fusion") {
+      log.info("CHAT", `Combo "${modelStr}" with ${comboModels.length} models (strategy: fusion)`);
+      return handleFusionChat({
+        body,
+        models: comboModels,
+        handleSingleModel: (b, m, isPanel) => {
+          let cleanRawReq = clientRawRequest;
+          if (isPanel && clientRawRequest) {
+            const { tools, tool_choice, ...cleanBody } = clientRawRequest.body || {};
+            cleanRawReq = { ...clientRawRequest, body: cleanBody };
+          }
+          return handleSingleModelChat(b, m, cleanRawReq, request, apiKey);
+        },
+        log,
+        comboName: modelStr,
+        judgeModel: comboStrategies[modelStr]?.judgeModel,
+        tuning: comboStrategies[modelStr]?.fusionTuning,
+      });
+    }
+
+    const comboStickyLimit = settings.comboStickyRoundRobinLimit;
+    log.info("CHAT", `Combo "${modelStr}" with ${comboModels.length} models (strategy: ${comboStrategy}, sticky: ${comboStickyLimit})`);
+    return handleComboChat({
+      body,
+      models: comboModels,
+      handleSingleModel: (b, m) => handleSingleModelChat(b, m, clientRawRequest, request, apiKey),
+      log,
+      comboName: modelStr,
+      comboStrategy,
+      comboStickyLimit
+    });
+  }
+
+  // Single model request
+  return handleSingleModelChat(body, modelStr, clientRawRequest, request, apiKey);
+}
+
+/**
+ * Handle single model chat request
+ */
+async function handleSingleModelChat(body, modelStr, clientRawRequest = null, request = null, apiKey = null) {
+  const modelInfo = await getModelInfo(modelStr);
+
+  // If provider is null, this might be a combo name - check and handle
+  if (!modelInfo.provider) {
+    const comboModels = await getComboModels(modelStr);
+    if (comboModels) {
+      const chatSettings = await getSettings();
+      // Check for combo-specific strategy first, fallback to global
+      const comboStrategies = chatSettings.comboStrategies || {};
+      const comboSpecificStrategy = comboStrategies[modelStr]?.fallbackStrategy;
+      const comboStrategy = comboSpecificStrategy || chatSettings.comboStrategy || "fallback";
+
+      if (comboStrategy === "fusion") {
+        log.info("CHAT", `Combo "${modelStr}" with ${comboModels.length} models (strategy: fusion)`);
+        return handleFusionChat({
+          body,
+          models: comboModels,
+          handleSingleModel: (b, m, isPanel) => {
+            let cleanRawReq = clientRawRequest;
+            if (isPanel && clientRawRequest) {
+              const { tools, tool_choice, ...cleanBody } = clientRawRequest.body || {};
+              cleanRawReq = { ...clientRawRequest, body: cleanBody };
+            }
+            return handleSingleModelChat(b, m, cleanRawReq, request, apiKey);
+          },
+          log,
+          comboName: modelStr,
+          judgeModel: comboStrategies[modelStr]?.judgeModel,
+          tuning: comboStrategies[modelStr]?.fusionTuning,
+        });
+      }
+
+      const comboStickyLimit = chatSettings.comboStickyRoundRobinLimit;
+      log.info("CHAT", `Combo "${modelStr}" with ${comboModels.length} models (strategy: ${comboStrategy}, sticky: ${comboStickyLimit})`);
+      return handleComboChat({
+        body,
+        models: comboModels,
+        handleSingleModel: (b, m) => handleSingleModelChat(b, m, clientRawRequest, request, apiKey),
+        log,
+        comboName: modelStr,
+        comboStrategy,
+        comboStickyLimit
+      });
+    }
+    log.warn("CHAT", "Invalid model format", { model: modelStr });
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid model format");
+  }
+
+  const { provider, model } = modelInfo;
+
+  // Routing shown in the unified "▶" line (client model → provider/model)
+
+  // Extract userAgent from request
+  const userAgent = request?.headers?.get("user-agent") || "";
+
+  // Try with available accounts (fallback on errors)
+  const excludeConnectionIds = new Set();
+  let lastError = null;
+  let lastStatus = null;
+
+  while (true) {
+    const credentials = await getProviderCredentials(provider, excludeConnectionIds, model);
+
+    // All accounts unavailable
+    if (!credentials || credentials.allRateLimited) {
+      if (credentials?.allRateLimited) {
+        const errorMsg = lastError || credentials.lastError || "Unavailable";
+        const status = lastStatus || Number(credentials.lastErrorCode) || HTTP_STATUS.SERVICE_UNAVAILABLE;
+        log.warn("CHAT", `[${provider}/${model}] ${errorMsg} (${credentials.retryAfterHuman})`);
+        return unavailableResponse(status, `[${provider}/${model}] ${errorMsg}`, credentials.retryAfter, credentials.retryAfterHuman);
+      }
+      if (excludeConnectionIds.size === 0) {
+        log.warn("AUTH", `No active credentials for provider: ${provider}`);
+        return errorResponse(HTTP_STATUS.NOT_FOUND, `No active credentials for provider: ${provider}`);
+      }
+      log.warn("CHAT", "No more accounts available", { provider });
+      return errorResponse(lastStatus || HTTP_STATUS.SERVICE_UNAVAILABLE, lastError || "All accounts unavailable");
+    }
+
+    // Account selection shown in the unified "▶" line (acc:...)
+    const refreshedCredentials = await checkAndRefreshToken(provider, credentials);
+
+    // Ensure real project ID is available for providers that need it (P0 fix: cold miss)
+    if ((provider === "antigravity" || provider === "gemini-cli") && !refreshedCredentials.projectId) {
+      const pid = await getProjectIdForConnection(credentials.connectionId, refreshedCredentials.accessToken);
+      if (pid) {
+        refreshedCredentials.projectId = pid;
+        // Persist to DB in background so subsequent requests have it immediately
+        updateProviderCredentials(credentials.connectionId, { projectId: pid }).catch(() => { });
+      }
+    }
+
+    // Use shared chatCore
+    const chatSettings = await getSettings();
+    const providerThinking = (chatSettings.providerThinking || {})[provider] || null;
+    const result = await handleChatCore({
+      body: { ...body, model: `${provider}/${model}` },
+      modelInfo: { provider, model },
+      credentials: refreshedCredentials,
+      log,
+      clientRawRequest,
+      connectionId: credentials.connectionId,
+      userAgent,
+      apiKey,
+      ccFilterNaming: !!chatSettings.ccFilterNaming,
+      rtkEnabled: !!chatSettings.rtkEnabled,
+      headroomEnabled: !!chatSettings.headroomEnabled,
+      headroomUrl: chatSettings.headroomUrl || DEFAULT_HEADROOM_URL,
+      headroomCompressUserMessages: !!chatSettings.headroomCompressUserMessages,
+      cavemanEnabled: !!chatSettings.cavemanEnabled,
+      cavemanLevel: chatSettings.cavemanLevel || "full",
+      ponytailEnabled: !!chatSettings.ponytailEnabled,
+      ponytailLevel: chatSettings.ponytailLevel || "full",
+      pxpipeEnabled: !!chatSettings.pxpipeEnabled,
+      pxpipeMinChars: chatSettings.pxpipeMinChars,
+      pxpipeTimeoutMs: chatSettings.pxpipeTimeoutMs,
+      // Lazily warms the in-process module on first use; null when not installed (fail-open)
+      pxpipeTransform: chatSettings.pxpipeEnabled ? await getPxpipeTransform() : null,
+      onPxpipeEvent: appendPxpipeEvent,
+      providerThinking,
+      // Detect source format by endpoint + body
+      sourceFormatOverride: request?.url ? detectFormatByEndpoint(new URL(request.url).pathname, body) : null,
+      onCredentialsRefreshed: async (newCreds) => {
+        await updateProviderCredentials(credentials.connectionId, {
+          ...newCreds,
+          existingProviderSpecificData: credentials.providerSpecificData,
+          testStatus: "active"
+        });
+      },
+      onRequestSuccess: async () => {
+        await clearAccountError(credentials.connectionId, credentials, model);
+      }
+    });
+
+    if (result.success) return result.response;
+
+    // Mark account unavailable (auto-calculates cooldown with exponential backoff, or precise resetsAtMs)
+    const { shouldFallback } = await markAccountUnavailable(credentials.connectionId, result.status, result.error, provider, model, result.resetsAtMs);
+
+    if (shouldFallback) {
+      log.warn("FALLBACK", `⇄ ACC:${credentials.connectionName} UNAVAILABLE (${result.status}) → NEXT ACCOUNT`);
+      excludeConnectionIds.add(credentials.connectionId);
+      lastError = result.error;
+      lastStatus = result.status;
+      continue;
+    }
+
+    return result.response;
+  }
+}
diff --git a/src/sse/handlers/embeddings.js b/src/sse/handlers/embeddings.js
new file mode 100644
index 0000000..cde0d41
--- /dev/null
+++ b/src/sse/handlers/embeddings.js
@@ -0,0 +1,141 @@
+import {
+  getProviderCredentials,
+  markAccountUnavailable,
+  clearAccountError,
+  extractApiKey,
+  isValidApiKey,
+} from "../services/auth.js";
+import { getSettings } from "@/lib/localDb";
+import { getModelInfo } from "../services/model.js";
+import { handleEmbeddingsCore } from "open-sse/handlers/embeddingsCore.js";
+import { errorResponse, unavailableResponse } from "open-sse/utils/error.js";
+import { HTTP_STATUS } from "open-sse/config/runtimeConfig.js";
+import * as log from "../utils/logger.js";
+import { updateProviderCredentials, checkAndRefreshToken } from "../services/tokenRefresh.js";
+
+/**
+ * Handle embeddings request for the SSE/Next.js server.
+ * Follows the same auth + fallback pattern as handleChat.
+ *
+ * @param {Request} request
+ */
+export async function handleEmbeddings(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    log.warn("EMBEDDINGS", "Invalid JSON body");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid JSON body");
+  }
+
+  const url = new URL(request.url);
+  const modelStr = body.model;
+
+  log.request("POST", `${url.pathname} | ${modelStr}`);
+
+  // Log API key (masked)
+  const apiKey = extractApiKey(request);
+  if (apiKey) {
+    log.debug("AUTH", `API Key: ${log.maskKey(apiKey)}`);
+  } else {
+    log.debug("AUTH", "No API key provided (local mode)");
+  }
+
+  // Enforce API key if enabled in settings
+  const settings = await getSettings();
+  if (settings.requireApiKey) {
+    if (!apiKey) {
+      log.warn("AUTH", "Missing API key (requireApiKey=true)");
+      return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Missing API key");
+    }
+    const valid = await isValidApiKey(apiKey);
+    if (!valid) {
+      log.warn("AUTH", "Invalid API key (requireApiKey=true)");
+      return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Invalid API key");
+    }
+  }
+
+  if (!modelStr) {
+    log.warn("EMBEDDINGS", "Missing model");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing model");
+  }
+
+  if (!body.input) {
+    log.warn("EMBEDDINGS", "Missing input");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing required field: input");
+  }
+
+  const modelInfo = await getModelInfo(modelStr);
+  if (!modelInfo.provider) {
+    log.warn("EMBEDDINGS", "Invalid model format", { model: modelStr });
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid model format");
+  }
+
+  const { provider, model } = modelInfo;
+
+  if (modelStr !== `${provider}/${model}`) {
+    log.info("ROUTING", `${modelStr} → ${provider}/${model}`);
+  } else {
+    log.info("ROUTING", `Provider: ${provider}, Model: ${model}`);
+  }
+
+  // Credential + fallback loop (mirrors handleChat)
+  const excludeConnectionIds = new Set();
+  let lastError = null;
+  let lastStatus = null;
+
+  while (true) {
+    const credentials = await getProviderCredentials(provider, excludeConnectionIds, model);
+
+    // All accounts unavailable
+    if (!credentials || credentials.allRateLimited) {
+      if (credentials?.allRateLimited) {
+        const errorMsg = lastError || credentials.lastError || "Unavailable";
+        const status = lastStatus || Number(credentials.lastErrorCode) || HTTP_STATUS.SERVICE_UNAVAILABLE;
+        log.warn("EMBEDDINGS", `[${provider}/${model}] ${errorMsg} (${credentials.retryAfterHuman})`);
+        return unavailableResponse(status, `[${provider}/${model}] ${errorMsg}`, credentials.retryAfter, credentials.retryAfterHuman);
+      }
+      if (excludeConnectionIds.size === 0) {
+        log.error("AUTH", `No credentials for provider: ${provider}`);
+        return errorResponse(HTTP_STATUS.BAD_REQUEST, `No credentials for provider: ${provider}`);
+      }
+      log.warn("EMBEDDINGS", "No more accounts available", { provider });
+      return errorResponse(lastStatus || HTTP_STATUS.SERVICE_UNAVAILABLE, lastError || "All accounts unavailable");
+    }
+
+    log.info("AUTH", `\x1b[32mUsing ${provider} account: ${credentials.connectionName}\x1b[0m`);
+
+    const refreshedCredentials = await checkAndRefreshToken(provider, credentials);
+
+    const result = await handleEmbeddingsCore({
+      body: { ...body, model: `${provider}/${model}` },
+      modelInfo: { provider, model },
+      credentials: refreshedCredentials,
+      log,
+      onCredentialsRefreshed: async (newCreds) => {
+        await updateProviderCredentials(credentials.connectionId, {
+          ...newCreds,
+          existingProviderSpecificData: credentials.providerSpecificData,
+          testStatus: "active"
+        });
+      },
+      onRequestSuccess: async () => {
+        await clearAccountError(credentials.connectionId, credentials, model);
+      }
+    });
+
+    if (result.success) return result.response;
+
+    const { shouldFallback } = await markAccountUnavailable(credentials.connectionId, result.status, result.error, provider, model);
+
+    if (shouldFallback) {
+      log.warn("AUTH", `Account ${credentials.connectionName} unavailable (${result.status}), trying fallback`);
+      excludeConnectionIds.add(credentials.connectionId);
+      lastError = result.error;
+      lastStatus = result.status;
+      continue;
+    }
+
+    return result.response;
+  }
+}
diff --git a/src/sse/handlers/fetch.js b/src/sse/handlers/fetch.js
new file mode 100644
index 0000000..db62a8c
--- /dev/null
+++ b/src/sse/handlers/fetch.js
@@ -0,0 +1,222 @@
+import {
+  getProviderCredentials,
+  markAccountUnavailable,
+  clearAccountError,
+  extractApiKey,
+  isValidApiKey,
+} from "../services/auth.js";
+import { getSettings, getCombos } from "@/lib/localDb";
+import { AI_PROVIDERS, resolveProviderId } from "@/shared/constants/providers.js";
+import { handleFetchCore } from "open-sse/handlers/fetch/index.js";
+import { errorResponse, unavailableResponse } from "open-sse/utils/error.js";
+import { HTTP_STATUS } from "open-sse/config/runtimeConfig.js";
+import * as log from "../utils/logger.js";
+import { updateProviderCredentials, checkAndRefreshToken } from "../services/tokenRefresh.js";
+import { handleComboChat, getComboModelsFromData } from "open-sse/services/combo.js";
+import { assertPublicUrl } from "@/shared/utils/ssrfGuard.js";
+
+/**
+ * Handle web fetch (URL extraction) request for the SSE/Next.js server.
+ * Provider IS the model. Mirrors handleEmbeddings auth + fallback flow.
+ *
+ * @param {Request} request
+ */
+export async function handleFetch(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    log.warn("FETCH", "Invalid JSON body");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid JSON body");
+  }
+
+  const reqUrl = new URL(request.url);
+  // Accept either `provider` or `model` (UI sends `model` since provider IS the model for webFetch)
+  const providerInput = body.provider || body.model;
+  const targetUrl = body.url;
+  const format = body.format;
+  const maxCharacters = body.max_characters;
+
+  log.request("POST", `${reqUrl.pathname} | ${providerInput}`);
+
+  // Log API key (masked)
+  const apiKey = extractApiKey(request);
+  if (apiKey) {
+    log.debug("AUTH", `API Key: ${log.maskKey(apiKey)}`);
+  } else {
+    log.debug("AUTH", "No API key provided (local mode)");
+  }
+
+  // Enforce API key if enabled in settings
+  const settings = await getSettings();
+  if (settings.requireApiKey) {
+    if (!apiKey) {
+      log.warn("AUTH", "Missing API key (requireApiKey=true)");
+      return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Missing API key");
+    }
+    const valid = await isValidApiKey(apiKey);
+    if (!valid) {
+      log.warn("AUTH", "Invalid API key (requireApiKey=true)");
+      return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Invalid API key");
+    }
+  }
+
+  if (!providerInput || typeof providerInput !== "string") {
+    log.warn("FETCH", "Missing provider/model");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing required field: provider (or model)");
+  }
+
+  if (!targetUrl || typeof targetUrl !== "string") {
+    log.warn("FETCH", "Missing url");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing required field: url");
+  }
+
+  // Validate URL format
+  try {
+    new URL(targetUrl);
+  } catch {
+    log.warn("FETCH", "Invalid URL", { url: targetUrl });
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid URL format");
+  }
+
+  // SSRF guard: reject internal/private/metadata targets
+  try {
+    assertPublicUrl(targetUrl);
+  } catch (err) {
+    log.warn("FETCH", "Blocked URL", { url: targetUrl });
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, err.message);
+  }
+
+  // Combo expansion: providerInput may be a combo name → run fallback/round-robin across providers
+  const combos = await getCombos();
+  const comboModels = getComboModelsFromData(providerInput, combos);
+  if (comboModels) {
+    const comboStrategies = settings.comboStrategies || {};
+    const comboStrategy = comboStrategies[providerInput]?.fallbackStrategy || settings.comboStrategy || "fallback";
+    const comboStickyLimit = settings.comboStickyRoundRobinLimit;
+    log.info("FETCH", `Combo "${providerInput}" with ${comboModels.length} providers (strategy: ${comboStrategy}, sticky: ${comboStickyLimit})`);
+    return handleComboChat({
+      body,
+      models: comboModels,
+      handleSingleModel: (b, m) => handleSingleProviderFetch(b, m, request, apiKey, settings),
+      log,
+      comboName: providerInput,
+      comboStrategy,
+      comboStickyLimit
+    });
+  }
+
+  return handleSingleProviderFetch(body, providerInput, request, apiKey, settings);
+}
+
+async function handleSingleProviderFetch(body, providerInput, request, apiKey, settings) {
+  const targetUrl = body.url;
+  const format = body.format;
+  const maxCharacters = body.max_characters;
+  const providerId = resolveProviderId(providerInput);
+  const resolvedProvider = AI_PROVIDERS[providerId];
+
+  if (!resolvedProvider) {
+    log.warn("FETCH", "Unknown provider", { provider: providerInput });
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, `Unknown provider: ${providerInput}`);
+  }
+
+  const providerConfig = resolvedProvider.fetchConfig;
+  if (!providerConfig) {
+    log.warn("FETCH", "Provider does not support web fetch", { provider: providerId });
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, `Provider ${providerId} does not support web fetch`);
+  }
+
+  if (providerInput !== providerId) {
+    log.info("ROUTING", `${providerInput} → ${providerId}`);
+  } else {
+    log.info("ROUTING", `Provider: ${providerId}`);
+  }
+
+  // No-auth fetch path (kept for parity though no current fetch provider sets noAuth)
+  if (resolvedProvider.noAuth) {
+    log.info("AUTH", `\x1b[32m${providerId} no-auth mode\x1b[0m`);
+    const result = await handleFetchCore({
+      url: targetUrl,
+      format,
+      maxCharacters,
+      provider: resolvedProvider.id,
+      providerConfig,
+      credentials: null,
+      log
+    });
+    if (result.success) {
+      return new Response(JSON.stringify(result.data), {
+        headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" }
+      });
+    }
+    return errorResponse(result.status || HTTP_STATUS.BAD_GATEWAY, result.error || "Fetch failed");
+  }
+
+  // Credential + fallback loop
+  const excludeConnectionIds = new Set();
+  let lastError = null;
+  let lastStatus = null;
+
+  while (true) {
+    const credentials = await getProviderCredentials(providerId, excludeConnectionIds);
+
+    if (!credentials || credentials.allRateLimited) {
+      if (credentials?.allRateLimited) {
+        const errorMsg = lastError || credentials.lastError || "Unavailable";
+        const status = lastStatus || Number(credentials.lastErrorCode) || HTTP_STATUS.SERVICE_UNAVAILABLE;
+        log.warn("FETCH", `[${providerId}] ${errorMsg} (${credentials.retryAfterHuman})`);
+        return unavailableResponse(status, `[${providerId}] ${errorMsg}`, credentials.retryAfter, credentials.retryAfterHuman);
+      }
+      if (excludeConnectionIds.size === 0) {
+        log.error("AUTH", `No credentials for provider: ${providerId}`);
+        return errorResponse(HTTP_STATUS.BAD_REQUEST, `No credentials for provider: ${providerId}`);
+      }
+      log.warn("FETCH", "No more accounts available", { provider: providerId });
+      return errorResponse(lastStatus || HTTP_STATUS.SERVICE_UNAVAILABLE, lastError || "All accounts unavailable");
+    }
+
+    log.info("AUTH", `\x1b[32mUsing ${providerId} account: ${credentials.connectionName}\x1b[0m`);
+
+    const refreshedCredentials = await checkAndRefreshToken(providerId, credentials);
+
+    const result = await handleFetchCore({
+      url: targetUrl,
+      format,
+      maxCharacters,
+      provider: resolvedProvider.id,
+      providerConfig,
+      credentials: refreshedCredentials,
+      log,
+      onCredentialsRefreshed: async (newCreds) => {
+        await updateProviderCredentials(credentials.connectionId, {
+          accessToken: newCreds.accessToken,
+          refreshToken: newCreds.refreshToken,
+          providerSpecificData: newCreds.providerSpecificData,
+          testStatus: "active"
+        });
+      },
+      onRequestSuccess: async () => {
+        await clearAccountError(credentials.connectionId, credentials);
+      }
+    });
+
+    if (result.success) {
+      return new Response(JSON.stringify(result.data), {
+        headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" }
+      });
+    }
+
+    const { shouldFallback } = await markAccountUnavailable(credentials.connectionId, result.status, result.error, providerId);
+
+    if (shouldFallback) {
+      log.warn("AUTH", `Account ${credentials.connectionName} unavailable (${result.status}), trying fallback`);
+      excludeConnectionIds.add(credentials.connectionId);
+      lastError = result.error;
+      lastStatus = result.status;
+      continue;
+    }
+
+    return errorResponse(result.status || HTTP_STATUS.BAD_GATEWAY, result.error || "Fetch failed");
+  }
+}
diff --git a/src/sse/handlers/imageGeneration.js b/src/sse/handlers/imageGeneration.js
new file mode 100644
index 0000000..78e738d
--- /dev/null
+++ b/src/sse/handlers/imageGeneration.js
@@ -0,0 +1,142 @@
+import {
+  getProviderCredentials,
+  markAccountUnavailable,
+  clearAccountError,
+  extractApiKey,
+  isValidApiKey,
+} from "../services/auth.js";
+import { getSettings } from "@/lib/localDb";
+import { getModelInfo, getComboModels } from "../services/model.js";
+import { handleImageGenerationCore } from "open-sse/handlers/imageGenerationCore.js";
+import { errorResponse, unavailableResponse } from "open-sse/utils/error.js";
+import { HTTP_STATUS } from "open-sse/config/runtimeConfig.js";
+import { updateProviderCredentials, checkAndRefreshToken } from "../services/tokenRefresh.js";
+import { handleComboChat } from "open-sse/services/combo.js";
+import * as log from "../utils/logger.js";
+
+// Providers that don't require credentials (noAuth)
+const NO_AUTH_PROVIDERS = new Set(["sdwebui", "comfyui"]);
+
+/**
+ * Handle image generation request
+ * @param {Request} request
+ */
+export async function handleImageGeneration(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid JSON body");
+  }
+
+  const url = new URL(request.url);
+  const preferredConnectionId = request.headers.get("x-connection-id") || null;
+  const wantsStream = (request.headers.get("accept") || "").includes("text/event-stream");
+  const binaryOutput = url.searchParams.get("response_format") === "binary";
+  const modelStr = body.model;
+
+  const apiKey = extractApiKey(request);
+  const settings = await getSettings();
+  if (settings.requireApiKey) {
+    if (!apiKey) return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Missing API key");
+    const valid = await isValidApiKey(apiKey);
+    if (!valid) return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Invalid API key");
+  }
+
+  if (!modelStr) return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing model");
+  if (!body.prompt) return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing required field: prompt");
+
+  // Combo expansion: model may be a combo name → run fallback/round-robin across models
+  const comboModels = await getComboModels(modelStr);
+  if (comboModels) {
+    const comboStrategies = settings.comboStrategies || {};
+    const comboStrategy = comboStrategies[modelStr]?.fallbackStrategy || settings.comboStrategy || "fallback";
+    const comboStickyLimit = settings.comboStickyRoundRobinLimit;
+    log.info("IMAGE", `Combo "${modelStr}" with ${comboModels.length} models (strategy: ${comboStrategy}, sticky: ${comboStickyLimit})`);
+    return handleComboChat({
+      body,
+      models: comboModels,
+      handleSingleModel: (b, m) => handleSingleModelImage(b, m, { wantsStream, binaryOutput, preferredConnectionId }),
+      log,
+      comboName: modelStr,
+      comboStrategy,
+      comboStickyLimit,
+    });
+  }
+
+  return handleSingleModelImage(body, modelStr, { wantsStream, binaryOutput, preferredConnectionId });
+}
+
+async function handleSingleModelImage(body, modelStr, { wantsStream, binaryOutput, preferredConnectionId } = {}) {
+  const modelInfo = await getModelInfo(modelStr);
+  if (!modelInfo.provider) return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid model format");
+
+  const { provider, model } = modelInfo;
+
+  // noAuth providers — no credential needed
+  if (NO_AUTH_PROVIDERS.has(provider)) {
+    const result = await handleImageGenerationCore({
+      body,
+      modelInfo: { provider, model },
+      credentials: null,
+      binaryOutput,
+    });
+    if (result.success) return result.response;
+    return errorResponse(result.status || HTTP_STATUS.BAD_GATEWAY, result.error || "Image generation failed");
+  }
+
+  // Credentialed providers — fallback loop
+  const excludeConnectionIds = new Set();
+  let lastError = null;
+  let lastStatus = null;
+
+  while (true) {
+    const credentials = await getProviderCredentials(provider, excludeConnectionIds, model, { preferredConnectionId });
+
+    if (!credentials || credentials.allRateLimited) {
+      if (credentials?.allRateLimited) {
+        const errorMsg = lastError || credentials.lastError || "Unavailable";
+        const status = lastStatus || Number(credentials.lastErrorCode) || HTTP_STATUS.SERVICE_UNAVAILABLE;
+        return unavailableResponse(status, `[${provider}/${model}] ${errorMsg}`, credentials.retryAfter, credentials.retryAfterHuman);
+      }
+      if (excludeConnectionIds.size === 0) {
+        return errorResponse(HTTP_STATUS.BAD_REQUEST, `No credentials for provider: ${provider}`);
+      }
+      return errorResponse(lastStatus || HTTP_STATUS.SERVICE_UNAVAILABLE, lastError || "All accounts unavailable");
+    }
+
+    const refreshedCredentials = await checkAndRefreshToken(provider, credentials);
+
+    const result = await handleImageGenerationCore({
+      body,
+      modelInfo: { provider, model },
+      credentials: refreshedCredentials,
+      streamToClient: wantsStream,
+      binaryOutput,
+      onCredentialsRefreshed: async (newCreds) => {
+        await updateProviderCredentials(credentials.connectionId, {
+          accessToken: newCreds.accessToken,
+          refreshToken: newCreds.refreshToken,
+          providerSpecificData: newCreds.providerSpecificData,
+          testStatus: "active"
+        });
+      },
+      onRequestSuccess: async () => {
+        await clearAccountError(credentials.connectionId, credentials, model);
+      }
+    });
+
+    if (result.success) return result.response;
+
+    const { shouldFallback } = await markAccountUnavailable(credentials.connectionId, result.status, result.error, provider, model);
+
+    if (shouldFallback) {
+      excludeConnectionIds.add(credentials.connectionId);
+      lastError = result.error;
+      lastStatus = result.status;
+      continue;
+    }
+
+    return result.response;
+  }
+}
diff --git a/src/sse/handlers/search.js b/src/sse/handlers/search.js
new file mode 100644
index 0000000..d8ee6b7
--- /dev/null
+++ b/src/sse/handlers/search.js
@@ -0,0 +1,206 @@
+import {
+  getProviderCredentials,
+  markAccountUnavailable,
+  clearAccountError,
+  extractApiKey,
+  isValidApiKey,
+} from "../services/auth.js";
+import { getSettings, getCombos } from "@/lib/localDb";
+import { AI_PROVIDERS, resolveProviderId } from "@/shared/constants/providers.js";
+import { handleSearchCore } from "open-sse/handlers/search/index.js";
+import { errorResponse, unavailableResponse } from "open-sse/utils/error.js";
+import { HTTP_STATUS } from "open-sse/config/runtimeConfig.js";
+import * as log from "../utils/logger.js";
+import { updateProviderCredentials, checkAndRefreshToken } from "../services/tokenRefresh.js";
+import { handleComboChat, getComboModelsFromData } from "open-sse/services/combo.js";
+
+/**
+ * Handle web search request for the SSE/Next.js server.
+ * Provider IS the model (no model field). Mirrors handleEmbeddings auth + fallback flow.
+ *
+ * @param {Request} request
+ */
+export async function handleSearch(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    log.warn("SEARCH", "Invalid JSON body");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid JSON body");
+  }
+
+  const url = new URL(request.url);
+  // Accept either `provider` or `model` (UI sends `model` since provider IS the model for webSearch)
+  const providerInput = body.provider || body.model;
+  const query = body.query;
+
+  log.request("POST", `${url.pathname} | ${providerInput}`);
+
+  // Log API key (masked)
+  const apiKey = extractApiKey(request);
+  if (apiKey) {
+    log.debug("AUTH", `API Key: ${log.maskKey(apiKey)}`);
+  } else {
+    log.debug("AUTH", "No API key provided (local mode)");
+  }
+
+  // Enforce API key if enabled in settings
+  const settings = await getSettings();
+  if (settings.requireApiKey) {
+    if (!apiKey) {
+      log.warn("AUTH", "Missing API key (requireApiKey=true)");
+      return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Missing API key");
+    }
+    const valid = await isValidApiKey(apiKey);
+    if (!valid) {
+      log.warn("AUTH", "Invalid API key (requireApiKey=true)");
+      return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Invalid API key");
+    }
+  }
+
+  if (!providerInput || typeof providerInput !== "string") {
+    log.warn("SEARCH", "Missing provider/model");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing required field: provider (or model)");
+  }
+
+  if (!query || typeof query !== "string" || !query.trim()) {
+    log.warn("SEARCH", "Missing query");
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing required field: query");
+  }
+
+  // Combo expansion: providerInput may be a combo name → run fallback/round-robin across providers
+  const combos = await getCombos();
+  const comboModels = getComboModelsFromData(providerInput, combos);
+  if (comboModels) {
+    const comboStrategies = settings.comboStrategies || {};
+    const comboStrategy = comboStrategies[providerInput]?.fallbackStrategy || settings.comboStrategy || "fallback";
+    const comboStickyLimit = settings.comboStickyRoundRobinLimit;
+    log.info("SEARCH", `Combo "${providerInput}" with ${comboModels.length} providers (strategy: ${comboStrategy}, sticky: ${comboStickyLimit})`);
+    return handleComboChat({
+      body,
+      models: comboModels,
+      handleSingleModel: (b, m) => handleSingleProviderSearch(b, m, request, apiKey, settings),
+      log,
+      comboName: providerInput,
+      comboStrategy,
+      comboStickyLimit
+    });
+  }
+
+  return handleSingleProviderSearch(body, providerInput, request, apiKey, settings);
+}
+
+async function handleSingleProviderSearch(body, providerInput, request, apiKey, settings) {
+  const query = body.query;
+  const providerId = resolveProviderId(providerInput);
+  const resolvedProvider = AI_PROVIDERS[providerId];
+
+  if (!resolvedProvider) {
+    log.warn("SEARCH", "Unknown provider", { provider: providerInput });
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, `Unknown provider: ${providerInput}`);
+  }
+
+  const providerConfig = resolvedProvider.searchConfig;
+  const supportsSearch = !!providerConfig || !!resolvedProvider.searchViaChat;
+
+  if (!supportsSearch) {
+    log.warn("SEARCH", "Provider does not support web search", { provider: providerId });
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, `Provider ${providerId} does not support web search`);
+  }
+
+  if (providerInput !== providerId) {
+    log.info("ROUTING", `${providerInput} → ${providerId}`);
+  } else {
+    log.info("ROUTING", `Provider: ${providerId}`);
+  }
+
+  // Sanitized body forwarded to core
+  const coreBody = {
+    query: query.trim(),
+    provider: providerId,
+    max_results: body.max_results,
+    search_type: body.search_type,
+    country: body.country,
+    language: body.language,
+    time_range: body.time_range,
+    offset: body.offset,
+    domain_filter: body.domain_filter,
+    content_options: body.content_options,
+    provider_options: body.provider_options
+  };
+
+  // No-auth providers (e.g. searxng) bypass credential lookup
+  if (resolvedProvider.noAuth) {
+    log.info("AUTH", `\x1b[32m${providerId} no-auth mode\x1b[0m`);
+    const result = await handleSearchCore({
+      body: coreBody,
+      provider: resolvedProvider,
+      providerConfig,
+      credentials: null,
+      log
+    });
+    if (result.success) return result.response;
+    return result.response;
+  }
+
+  // Credential + fallback loop
+  const excludeConnectionIds = new Set();
+  let lastError = null;
+  let lastStatus = null;
+
+  while (true) {
+    const credentials = await getProviderCredentials(providerId, excludeConnectionIds);
+
+    if (!credentials || credentials.allRateLimited) {
+      if (credentials?.allRateLimited) {
+        const errorMsg = lastError || credentials.lastError || "Unavailable";
+        const status = lastStatus || Number(credentials.lastErrorCode) || HTTP_STATUS.SERVICE_UNAVAILABLE;
+        log.warn("SEARCH", `[${providerId}] ${errorMsg} (${credentials.retryAfterHuman})`);
+        return unavailableResponse(status, `[${providerId}] ${errorMsg}`, credentials.retryAfter, credentials.retryAfterHuman);
+      }
+      if (excludeConnectionIds.size === 0) {
+        log.error("AUTH", `No credentials for provider: ${providerId}`);
+        return errorResponse(HTTP_STATUS.BAD_REQUEST, `No credentials for provider: ${providerId}`);
+      }
+      log.warn("SEARCH", "No more accounts available", { provider: providerId });
+      return errorResponse(lastStatus || HTTP_STATUS.SERVICE_UNAVAILABLE, lastError || "All accounts unavailable");
+    }
+
+    log.info("AUTH", `\x1b[32mUsing ${providerId} account: ${credentials.connectionName}\x1b[0m`);
+
+    const refreshedCredentials = await checkAndRefreshToken(providerId, credentials);
+
+    const result = await handleSearchCore({
+      body: coreBody,
+      provider: resolvedProvider,
+      providerConfig,
+      credentials: refreshedCredentials,
+      log,
+      onCredentialsRefreshed: async (newCreds) => {
+        await updateProviderCredentials(credentials.connectionId, {
+          accessToken: newCreds.accessToken,
+          refreshToken: newCreds.refreshToken,
+          providerSpecificData: newCreds.providerSpecificData,
+          testStatus: "active"
+        });
+      },
+      onRequestSuccess: async () => {
+        await clearAccountError(credentials.connectionId, credentials);
+      }
+    });
+
+    if (result.success) return result.response;
+
+    const { shouldFallback } = await markAccountUnavailable(credentials.connectionId, result.status, result.error, providerId);
+
+    if (shouldFallback) {
+      log.warn("AUTH", `Account ${credentials.connectionName} unavailable (${result.status}), trying fallback`);
+      excludeConnectionIds.add(credentials.connectionId);
+      lastError = result.error;
+      lastStatus = result.status;
+      continue;
+    }
+
+    return result.response;
+  }
+}
diff --git a/src/sse/handlers/stt.js b/src/sse/handlers/stt.js
new file mode 100644
index 0000000..1840965
--- /dev/null
+++ b/src/sse/handlers/stt.js
@@ -0,0 +1,88 @@
+import {
+  extractApiKey, isValidApiKey,
+  getProviderCredentials, markAccountUnavailable,
+} from "../services/auth.js";
+import { getSettings } from "@/lib/localDb";
+import { getModelInfo } from "../services/model.js";
+import { handleSttCore } from "open-sse/handlers/sttCore.js";
+import { errorResponse, unavailableResponse } from "open-sse/utils/error.js";
+import { HTTP_STATUS } from "open-sse/config/runtimeConfig.js";
+import { AI_PROVIDERS } from "@/shared/constants/providers";
+import * as log from "../utils/logger.js";
+
+// Providers requiring credentials for STT
+const CREDENTIALED_PROVIDERS = new Set(
+  Object.entries(AI_PROVIDERS)
+    .filter(([, p]) => p.serviceKinds?.includes("stt") && !p.noAuth && p.sttConfig?.authType !== "none")
+    .map(([id]) => id)
+);
+
+export async function handleStt(request) {
+  let formData;
+  try {
+    formData = await request.formData();
+  } catch {
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid multipart form data");
+  }
+
+  const modelStr = formData.get("model");
+  log.request("POST", `/v1/audio/transcriptions | ${modelStr}`);
+
+  const settings = await getSettings();
+  if (settings.requireApiKey) {
+    const apiKey = extractApiKey(request);
+    if (!apiKey) return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Missing API key");
+    const valid = await isValidApiKey(apiKey);
+    if (!valid) return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Invalid API key");
+  }
+
+  if (!modelStr) return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing model");
+  if (!formData.get("file")) return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing required field: file");
+
+  const modelInfo = await getModelInfo(modelStr);
+  if (!modelInfo.provider) return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid model format");
+
+  const { provider, model } = modelInfo;
+  log.info("ROUTING", `Provider: ${provider}, Model: ${model}`);
+
+  // noAuth providers
+  if (!CREDENTIALED_PROVIDERS.has(provider)) {
+    const result = await handleSttCore({ provider, model, formData, sttConfig: AI_PROVIDERS[provider]?.sttConfig });
+    if (result.success) return result.response;
+    return errorResponse(result.status || HTTP_STATUS.BAD_GATEWAY, result.error || "STT failed");
+  }
+
+  // Credentialed — fallback loop
+  const excludeConnectionIds = new Set();
+  let lastError = null;
+  let lastStatus = null;
+
+  while (true) {
+    const credentials = await getProviderCredentials(provider, excludeConnectionIds, model);
+
+    if (!credentials || credentials.allRateLimited) {
+      if (credentials?.allRateLimited) {
+        const msg = lastError || credentials.lastError || "Unavailable";
+        const status = lastStatus || Number(credentials.lastErrorCode) || HTTP_STATUS.SERVICE_UNAVAILABLE;
+        return unavailableResponse(status, `[${provider}/${model}] ${msg}`, credentials.retryAfter, credentials.retryAfterHuman);
+      }
+      if (excludeConnectionIds.size === 0) return errorResponse(HTTP_STATUS.BAD_REQUEST, `No credentials for provider: ${provider}`);
+      return errorResponse(lastStatus || HTTP_STATUS.SERVICE_UNAVAILABLE, lastError || "All accounts unavailable");
+    }
+
+    log.info("AUTH", `\x1b[32mUsing ${provider} account: ${credentials.connectionName}\x1b[0m`);
+
+    const result = await handleSttCore({ provider, model, formData, credentials, sttConfig: AI_PROVIDERS[provider]?.sttConfig });
+
+    if (result.success) return result.response;
+
+    const { shouldFallback } = await markAccountUnavailable(credentials.connectionId, result.status, result.error, provider, model);
+    if (shouldFallback) {
+      excludeConnectionIds.add(credentials.connectionId);
+      lastError = result.error;
+      lastStatus = result.status;
+      continue;
+    }
+    return result.response || errorResponse(result.status, result.error);
+  }
+}
diff --git a/src/sse/handlers/tts.js b/src/sse/handlers/tts.js
new file mode 100644
index 0000000..828d45b
--- /dev/null
+++ b/src/sse/handlers/tts.js
@@ -0,0 +1,114 @@
+import {
+  extractApiKey, isValidApiKey,
+  getProviderCredentials, markAccountUnavailable,
+} from "../services/auth.js";
+import { getSettings } from "@/lib/localDb";
+import { getModelInfo, getComboModels } from "../services/model.js";
+import { handleTtsCore } from "open-sse/handlers/ttsCore.js";
+import { errorResponse, unavailableResponse } from "open-sse/utils/error.js";
+import { HTTP_STATUS } from "open-sse/config/runtimeConfig.js";
+import { AI_PROVIDERS } from "@/shared/constants/providers";
+import { handleComboChat } from "open-sse/services/combo.js";
+import * as log from "../utils/logger.js";
+
+// Derived from providers.js: any TTS provider not noAuth requires stored credentials
+const CREDENTIALED_PROVIDERS = new Set(
+  Object.entries(AI_PROVIDERS)
+    .filter(([, p]) => p.serviceKinds?.includes("tts") && !p.noAuth && p.ttsConfig?.authType !== "none")
+    .map(([id]) => id)
+);
+
+export async function handleTts(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid JSON body");
+  }
+
+  const url = new URL(request.url);
+  const modelStr = body.model;
+  const responseFormat = url.searchParams.get("response_format") || "mp3"; // mp3 (default) | json
+  const language = body.language || ""; // Optional language hint (currently used by Gemini)
+  log.request("POST", `${url.pathname} | ${modelStr} | format=${responseFormat}${language ? ` | lang=${language}` : ""}`);
+
+  const settings = await getSettings();
+  if (settings.requireApiKey) {
+    const apiKey = extractApiKey(request);
+    if (!apiKey) return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Missing API key");
+    const valid = await isValidApiKey(apiKey);
+    if (!valid) return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Invalid API key");
+  }
+
+  if (!modelStr) return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing model");
+  if (!body.input) return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing required field: input");
+
+  // Combo expansion: model may be a combo name → run fallback/round-robin across models
+  const comboModels = await getComboModels(modelStr);
+  if (comboModels) {
+    const comboStrategies = settings.comboStrategies || {};
+    const comboStrategy = comboStrategies[modelStr]?.fallbackStrategy || settings.comboStrategy || "fallback";
+    const comboStickyLimit = settings.comboStickyRoundRobinLimit;
+    log.info("TTS", `Combo "${modelStr}" with ${comboModels.length} models (strategy: ${comboStrategy}, sticky: ${comboStickyLimit})`);
+    return handleComboChat({
+      body,
+      models: comboModels,
+      handleSingleModel: (b, m) => handleSingleModelTts(b, m, responseFormat, language),
+      log,
+      comboName: modelStr,
+      comboStrategy,
+      comboStickyLimit,
+    });
+  }
+
+  return handleSingleModelTts(body, modelStr, responseFormat, language);
+}
+
+async function handleSingleModelTts(body, modelStr, responseFormat, language) {
+  const modelInfo = await getModelInfo(modelStr);
+  if (!modelInfo.provider) return errorResponse(HTTP_STATUS.BAD_REQUEST, "Invalid model format");
+
+  const { provider, model } = modelInfo;
+  log.info("ROUTING", `Provider: ${provider}, Voice: ${model}`);
+
+  // noAuth providers — no credential needed
+  if (!CREDENTIALED_PROVIDERS.has(provider)) {
+    const result = await handleTtsCore({ provider, model, input: body.input, responseFormat, language });
+    if (result.success) return result.response;
+    return errorResponse(result.status || HTTP_STATUS.BAD_GATEWAY, result.error || "TTS failed");
+  }
+
+  // Credentialed providers — fallback loop (same pattern as embeddings)
+  const excludeConnectionIds = new Set();
+  let lastError = null;
+  let lastStatus = null;
+
+  while (true) {
+    const credentials = await getProviderCredentials(provider, excludeConnectionIds, model);
+
+    if (!credentials || credentials.allRateLimited) {
+      if (credentials?.allRateLimited) {
+        const msg = lastError || credentials.lastError || "Unavailable";
+        const status = lastStatus || Number(credentials.lastErrorCode) || HTTP_STATUS.SERVICE_UNAVAILABLE;
+        return unavailableResponse(status, `[${provider}/${model}] ${msg}`, credentials.retryAfter, credentials.retryAfterHuman);
+      }
+      if (excludeConnectionIds.size === 0) return errorResponse(HTTP_STATUS.BAD_REQUEST, `No credentials for provider: ${provider}`);
+      return errorResponse(lastStatus || HTTP_STATUS.SERVICE_UNAVAILABLE, lastError || "All accounts unavailable");
+    }
+
+    log.info("AUTH", `\x1b[32mUsing ${provider} account: ${credentials.connectionName}\x1b[0m`);
+
+    const result = await handleTtsCore({ provider, model, input: body.input, credentials, responseFormat, language });
+
+    if (result.success) return result.response;
+
+    const { shouldFallback } = await markAccountUnavailable(credentials.connectionId, result.status, result.error, provider, model);
+    if (shouldFallback) {
+      excludeConnectionIds.add(credentials.connectionId);
+      lastError = result.error;
+      lastStatus = result.status;
+      continue;
+    }
+    return result.response || errorResponse(result.status, result.error);
+  }
+}
diff --git a/src/sse/services/auth.js b/src/sse/services/auth.js
new file mode 100644
index 0000000..f931209
--- /dev/null
+++ b/src/sse/services/auth.js
@@ -0,0 +1,319 @@
+import { getProviderConnections, validateApiKey, updateProviderConnection, getSettings, getProxyPools } from "@/lib/localDb";
+import { resolveConnectionProxyConfig, pickProxyPoolId } from "@/lib/network/connectionProxy";
+import { formatRetryAfter, checkFallbackError, isModelLockActive, buildModelLockUpdate, getEarliestModelLockUntil } from "open-sse/services/accountFallback.js";
+import { MAX_RATE_LIMIT_COOLDOWN_MS } from "open-sse/config/errorConfig.js";
+import { resolveProviderId, FREE_PROVIDERS } from "@/shared/constants/providers.js";
+import * as log from "../utils/logger.js";
+
+// Mutex to prevent race conditions during account selection
+let selectionMutex = Promise.resolve();
+
+/**
+ * Get provider credentials from localDb
+ * Filters out unavailable accounts and returns the selected account based on strategy
+ * @param {string} provider - Provider name
+ * @param {Set<string>|string|null} excludeConnectionIds - Connection ID(s) to exclude (for retry with next account)
+ * @param {string|null} model - Model name for per-model rate limit filtering
+ */
+export async function getProviderCredentials(provider, excludeConnectionIds = null, model = null, options = {}) {
+  // Normalize to Set for consistent handling
+  const excludeSet = excludeConnectionIds instanceof Set
+    ? excludeConnectionIds
+    : (excludeConnectionIds ? new Set([excludeConnectionIds]) : new Set());
+  const preferredConnectionId = options?.preferredConnectionId || null;
+  // Acquire mutex to prevent race conditions
+  const currentMutex = selectionMutex;
+  let resolveMutex;
+  selectionMutex = new Promise(resolve => { resolveMutex = resolve; });
+
+  try {
+    await currentMutex;
+
+    // Resolve alias to provider ID (e.g., "kc" -> "kilocode")
+    const providerId = resolveProviderId(provider);
+
+    // Inject a virtual connection for no-auth free providers (with optional proxy pool from settings)
+    if (FREE_PROVIDERS[providerId]?.noAuth) {
+      const settings = await getSettings();
+      const override = (settings.providerStrategies || {})[providerId] || {};
+      const strategy = override.rotateStrategy || "none";
+      let pickedId = override.proxyPoolId || null;
+      if (strategy !== "none") {
+        const allPools = await getProxyPools({ isActive: true });
+        const poolIds = allPools.filter(p => p.proxyUrl).map(p => p.id);
+        pickedId = pickProxyPoolId(poolIds, strategy, providerId);
+      }
+      const resolvedProxy = await resolveConnectionProxyConfig({ proxyPoolId: pickedId || "" });
+      return {
+        id: "noauth",
+        connectionName: "Public",
+        isActive: true,
+        accessToken: "public",
+        providerSpecificData: {
+          connectionProxyEnabled: resolvedProxy.connectionProxyEnabled,
+          connectionProxyUrl: resolvedProxy.connectionProxyUrl,
+          connectionNoProxy: resolvedProxy.connectionNoProxy,
+          connectionProxyPoolId: resolvedProxy.proxyPoolId || null,
+          vercelRelayUrl: resolvedProxy.vercelRelayUrl || "",
+        },
+      };
+    }
+
+    const connections = await getProviderConnections({ provider: providerId, isActive: true });
+    log.debug("AUTH", `${provider} | total connections: ${connections.length}, excludeIds: ${excludeSet.size > 0 ? [...excludeSet].join(",") : "none"}, model: ${model || "any"}`);
+
+    if (connections.length === 0) {
+      log.warn("AUTH", `No credentials for ${provider}`);
+      return null;
+    }
+
+    // Filter out model-locked and excluded connections
+    const availableConnections = connections.filter(c => {
+      if (excludeSet.has(c.id)) return false;
+      if (isModelLockActive(c, model)) return false;
+      return true;
+    });
+
+    log.debug("AUTH", `${provider} | available: ${availableConnections.length}/${connections.length}`);
+    connections.forEach(c => {
+      const excluded = excludeSet.has(c.id);
+      const locked = isModelLockActive(c, model);
+      if (excluded || locked) {
+        const lockUntil = getEarliestModelLockUntil(c);
+        log.debug("AUTH", `  → ${c.id?.slice(0, 8)} | ${excluded ? "excluded" : ""} ${locked ? `modelLocked(${model}) until ${lockUntil}` : ""}`);
+      }
+    });
+
+    if (availableConnections.length === 0) {
+      // Find earliest lock expiry across all connections for retry timing
+      const lockedConns = connections.filter(c => isModelLockActive(c, model));
+      const expiries = lockedConns.map(c => getEarliestModelLockUntil(c)).filter(Boolean);
+      const earliest = expiries.sort()[0] || null;
+      if (earliest) {
+        const earliestConn = lockedConns[0];
+        log.warn("AUTH", `${provider} | all ${connections.length} accounts locked for ${model || "all"} (${formatRetryAfter(earliest)}) | lastError=${earliestConn?.lastError?.slice(0, 50)}`);
+        return {
+          allRateLimited: true,
+          retryAfter: earliest,
+          retryAfterHuman: formatRetryAfter(earliest),
+          lastError: earliestConn?.lastError || null,
+          lastErrorCode: earliestConn?.errorCode || null
+        };
+      }
+      log.warn("AUTH", `${provider} | all ${connections.length} accounts unavailable`);
+      return null;
+    }
+
+    const settings = await getSettings();
+    // Per-provider strategy overrides global setting
+    const providerOverride = (settings.providerStrategies || {})[providerId] || {};
+    const strategy = providerOverride.fallbackStrategy || settings.fallbackStrategy || "fill-first";
+
+    let connection;
+    // Pin to preferred connection if specified and available
+    if (preferredConnectionId) {
+      connection = availableConnections.find((c) => c.id === preferredConnectionId);
+      if (connection) {
+        log.info("AUTH", `${provider} | pinned to ${connection.id?.slice(0, 8)} (${connection.name || connection.email || "unnamed"})`);
+      }
+    }
+    if (connection) {
+      // skip strategy
+    } else if (strategy === "round-robin") {
+      const stickyLimit = providerOverride.stickyRoundRobinLimit || settings.stickyRoundRobinLimit || 3;
+
+      // Sort by lastUsed (most recent first) to find current candidate
+      const byRecency = [...availableConnections].sort((a, b) => {
+        if (!a.lastUsedAt && !b.lastUsedAt) return (a.priority || 999) - (b.priority || 999);
+        if (!a.lastUsedAt) return 1;
+        if (!b.lastUsedAt) return -1;
+        return new Date(b.lastUsedAt) - new Date(a.lastUsedAt);
+      });
+
+      const current = byRecency[0];
+      const currentCount = current?.consecutiveUseCount || 0;
+
+      if (current && current.lastUsedAt && currentCount < stickyLimit) {
+        // Stay with current account
+        connection = current;
+        // Update lastUsedAt and increment count (await to ensure persistence)
+        await updateProviderConnection(connection.id, {
+          lastUsedAt: new Date().toISOString(),
+          consecutiveUseCount: (connection.consecutiveUseCount || 0) + 1
+        });
+      } else {
+        // Pick the least recently used (excluding current if possible)
+        const sortedByOldest = [...availableConnections].sort((a, b) => {
+          if (!a.lastUsedAt && !b.lastUsedAt) return (a.priority || 999) - (b.priority || 999);
+          if (!a.lastUsedAt) return -1;
+          if (!b.lastUsedAt) return 1;
+          return new Date(a.lastUsedAt) - new Date(b.lastUsedAt);
+        });
+
+        connection = sortedByOldest[0];
+
+        // Update lastUsedAt and reset count to 1 (await to ensure persistence)
+        await updateProviderConnection(connection.id, {
+          lastUsedAt: new Date().toISOString(),
+          consecutiveUseCount: 1
+        });
+      }
+    } else {
+      // Default: fill-first (already sorted by priority in getProviderConnections)
+      connection = availableConnections[0];
+    }
+
+    const resolvedProxy = await resolveConnectionProxyConfig(connection.providerSpecificData || {});
+
+    return {
+      authType: connection.authType,
+      apiKey: connection.apiKey,
+      accessToken: connection.accessToken,
+      refreshToken: connection.refreshToken,
+      idToken: connection.idToken,
+      expiresAt: connection.expiresAt,
+      expiresIn: connection.expiresIn,
+      lastRefreshAt: connection.lastRefreshAt,
+      projectId: connection.projectId,
+      connectionName: connection.displayName || connection.name || connection.email || connection.id,
+      copilotToken: connection.providerSpecificData?.copilotToken,
+      providerSpecificData: {
+        ...(connection.providerSpecificData || {}),
+        connectionProxyEnabled: resolvedProxy.connectionProxyEnabled,
+        connectionProxyUrl: resolvedProxy.connectionProxyUrl,
+        connectionNoProxy: resolvedProxy.connectionNoProxy,
+        connectionProxyPoolId: resolvedProxy.proxyPoolId || null,
+        vercelRelayUrl: resolvedProxy.vercelRelayUrl || "",
+      },
+      connectionId: connection.id,
+      // Include current status for optimization check
+      testStatus: connection.testStatus,
+      lastError: connection.lastError,
+      // Pass full connection for clearAccountError to read modelLock_* keys
+      _connection: connection
+    };
+  } finally {
+    if (resolveMutex) resolveMutex();
+  }
+}
+
+/**
+ * Mark account+model as unavailable — locks modelLock_${model} in DB.
+ * All errors (429, 401, 5xx, etc.) lock per model, not per account.
+ * @param {string} connectionId
+ * @param {number} status - HTTP status code from upstream
+ * @param {string} errorText
+ * @param {string|null} provider
+ * @param {string|null} model - The specific model that triggered the error
+ * @returns {{ shouldFallback: boolean, cooldownMs: number }}
+ */
+export async function markAccountUnavailable(connectionId, status, errorText, provider = null, model = null, resetsAtMs = null) {
+  if (!connectionId || connectionId === "noauth") return { shouldFallback: false, cooldownMs: 0 };
+  const connections = await getProviderConnections({ provider });
+  const conn = connections.find(c => c.id === connectionId);
+  const backoffLevel = conn?.backoffLevel || 0;
+
+  // Provider-specific precise cooldown (e.g. codex usage_limit_reached resets_at) overrides backoff
+  let shouldFallback, cooldownMs, newBackoffLevel;
+  if (resetsAtMs && resetsAtMs > Date.now()) {
+    shouldFallback = true;
+    cooldownMs = Math.min(resetsAtMs - Date.now(), MAX_RATE_LIMIT_COOLDOWN_MS);
+    newBackoffLevel = 0;
+  } else {
+    ({ shouldFallback, cooldownMs, newBackoffLevel } = checkFallbackError(status, errorText, backoffLevel));
+  }
+  if (!shouldFallback) return { shouldFallback: false, cooldownMs: 0 };
+
+  const reason = typeof errorText === "string" ? errorText.slice(0, 100) : "Provider error";
+  const lockUpdate = buildModelLockUpdate(model, cooldownMs);
+
+  await updateProviderConnection(connectionId, {
+    ...lockUpdate,
+    testStatus: "unavailable",
+    lastError: reason,
+    errorCode: status,
+    lastErrorAt: new Date().toISOString(),
+    backoffLevel: newBackoffLevel ?? backoffLevel
+  });
+
+  const lockKey = Object.keys(lockUpdate)[0];
+  const connName = conn?.displayName || conn?.name || conn?.email || connectionId.slice(0, 8);
+  log.warn("AUTH", `${connName} locked ${lockKey} for ${Math.round(cooldownMs / 1000)}s [${status}]`);
+
+  if (provider && status && reason) {
+    console.error(`❌ ${provider} [${status}]: ${reason}`);
+  }
+
+  return { shouldFallback: true, cooldownMs };
+}
+
+/**
+ * Clear account error status on successful request.
+ * - Clears modelLock_${model} (the model that just succeeded)
+ * - Lazy-cleans any other expired modelLock_* keys
+ * - Resets error state only if no active locks remain
+ * @param {string} connectionId
+ * @param {object} currentConnection - credentials object (has _connection) or raw connection
+ * @param {string|null} model - model that succeeded
+ */
+export async function clearAccountError(connectionId, currentConnection, model = null) {
+  if (!connectionId || connectionId === "noauth") return;
+  const conn = currentConnection._connection || currentConnection;
+  const now = Date.now();
+  const allLockKeys = Object.keys(conn).filter(k => k.startsWith("modelLock_"));
+
+  if (!conn.testStatus && !conn.lastError && allLockKeys.length === 0) return;
+
+  // Keys to clear: current model's lock + all expired locks
+  const keysToClear = allLockKeys.filter(k => {
+    if (model && k === `modelLock_${model}`) return true; // succeeded model
+    if (model && k === "modelLock___all") return true;    // account-level lock
+    const expiry = conn[k];
+    return expiry && new Date(expiry).getTime() <= now;   // expired
+  });
+
+  if (keysToClear.length === 0 && conn.testStatus !== "unavailable" && !conn.lastError) return;
+
+  // Check if any active locks remain after clearing
+  const remainingActiveLocks = allLockKeys.filter(k => {
+    if (keysToClear.includes(k)) return false;
+    const expiry = conn[k];
+    return expiry && new Date(expiry).getTime() > now;
+  });
+
+  const clearObj = Object.fromEntries(keysToClear.map(k => [k, null]));
+
+  // Only reset error state if no active locks remain
+  if (remainingActiveLocks.length === 0) {
+    Object.assign(clearObj, { testStatus: "active", lastError: null, lastErrorAt: null, backoffLevel: 0 });
+  }
+
+  await updateProviderConnection(connectionId, clearObj);
+}
+
+/**
+ * Extract API key from request headers
+ */
+export function extractApiKey(request) {
+  // Check Authorization header first
+  const authHeader = request.headers.get("Authorization");
+  if (authHeader?.startsWith("Bearer ")) {
+    return authHeader.slice(7);
+  }
+
+  // Check Anthropic x-api-key header
+  const xApiKey = request.headers.get("x-api-key");
+  if (xApiKey) {
+    return xApiKey;
+  }
+
+  return null;
+}
+
+/**
+ * Validate API key (optional - for local use can skip)
+ */
+export async function isValidApiKey(apiKey) {
+  if (!apiKey) return false;
+  return await validateApiKey(apiKey);
+}
diff --git a/src/sse/services/model.js b/src/sse/services/model.js
new file mode 100644
index 0000000..ba4cc6c
--- /dev/null
+++ b/src/sse/services/model.js
@@ -0,0 +1,94 @@
+// Re-export from open-sse with localDb integration
+import { getModelAliases, getComboByName, getProviderNodes } from "@/lib/localDb";
+import { parseModel as parseModelCore, resolveModelAliasFromMap, getModelInfoCore } from "open-sse/services/model.js";
+import REGISTRY from "open-sse/providers/registry/index.js";
+
+// Local provider alias overrides (HMR-friendly, applied on top of open-sse map)
+const LOCAL_PROVIDER_ALIASES = {
+  xmtp: "xiaomi-tokenplan",
+  "xiaomi-tokenplan": "xiaomi-tokenplan",
+};
+
+const RESERVED_PROVIDER_PREFIXES = new Set(Object.keys(LOCAL_PROVIDER_ALIASES));
+for (const entry of REGISTRY) {
+  RESERVED_PROVIDER_PREFIXES.add(entry.id);
+  if (entry.alias) RESERVED_PROVIDER_PREFIXES.add(entry.alias);
+  for (const alias of entry.aliases || []) RESERVED_PROVIDER_PREFIXES.add(alias);
+}
+
+export function parseModel(modelStr) {
+  const parsed = parseModelCore(modelStr);
+  if (parsed?.providerAlias && LOCAL_PROVIDER_ALIASES[parsed.providerAlias]) {
+    return { ...parsed, provider: LOCAL_PROVIDER_ALIASES[parsed.providerAlias] };
+  }
+  return parsed;
+}
+
+/**
+ * Resolve model alias from localDb
+ */
+export async function resolveModelAlias(alias) {
+  const aliases = await getModelAliases();
+  return resolveModelAliasFromMap(alias, aliases);
+}
+
+/**
+ * Get full model info (parse or resolve)
+ */
+export async function getModelInfo(modelStr) {
+  const parsed = parseModel(modelStr);
+
+  if (!parsed.isAlias) {
+    // Provider-node prefixes are user-defined. They must not override built-in
+    // provider ids/aliases such as `cf`, `cloudflare-ai`, `openai`, or `hf`.
+    if (!RESERVED_PROVIDER_PREFIXES.has(parsed.providerAlias)) {
+      const openaiNodes = await getProviderNodes({ type: "openai-compatible" });
+      const matchedOpenAI = openaiNodes.find((node) => node.prefix === parsed.providerAlias);
+      if (matchedOpenAI) {
+        return { provider: matchedOpenAI.id, model: parsed.model };
+      }
+
+      const anthropicNodes = await getProviderNodes({ type: "anthropic-compatible" });
+      const matchedAnthropic = anthropicNodes.find((node) => node.prefix === parsed.providerAlias);
+      if (matchedAnthropic) {
+        return { provider: matchedAnthropic.id, model: parsed.model };
+      }
+
+      const embeddingNodes = await getProviderNodes({ type: "custom-embedding" });
+      const matchedEmbedding = embeddingNodes.find((node) => node.prefix === parsed.providerAlias);
+      if (matchedEmbedding) {
+        return { provider: matchedEmbedding.id, model: parsed.model };
+      }
+    }
+    return {
+      provider: parsed.provider,
+      model: parsed.model
+    };
+  }
+
+  // Check if this is a combo name before resolving as alias
+  // This prevents combo names from being incorrectly routed to providers
+  const combo = await getComboByName(parsed.model);
+  if (combo) {
+    // Return null provider to signal this should be handled as combo
+    // The caller (handleChat) will detect this and handle it as combo
+    return { provider: null, model: parsed.model };
+  }
+
+  return getModelInfoCore(modelStr, getModelAliases);
+}
+
+/**
+ * Check if model is a combo and get models list
+ * @returns {Promise<string[]|null>} Array of models or null if not a combo
+ */
+export async function getComboModels(modelStr) {
+  // Only check if it's not in provider/model format
+  if (modelStr.includes("/")) return null;
+
+  const combo = await getComboByName(modelStr);
+  if (combo && combo.models && combo.models.length > 0) {
+    return combo.models;
+  }
+  return null;
+}
diff --git a/src/sse/services/tokenRefresh.js b/src/sse/services/tokenRefresh.js
new file mode 100644
index 0000000..d6fe288
--- /dev/null
+++ b/src/sse/services/tokenRefresh.js
@@ -0,0 +1,325 @@
+// Re-export from open-sse with local logger
+import * as log from "../utils/logger.js";
+import { updateProviderConnection } from "../../lib/localDb.js";
+import {
+  getProjectIdForConnection,
+  invalidateProjectId,
+  removeConnection,
+} from "open-sse/services/projectId.js";
+import {
+  TOKEN_EXPIRY_BUFFER_MS as BUFFER_MS,
+  refreshAccessToken as _refreshAccessToken,
+  refreshClaudeOAuthToken as _refreshClaudeOAuthToken,
+  refreshGoogleToken as _refreshGoogleToken,
+  refreshQwenToken as _refreshQwenToken,
+  refreshCodexToken as _refreshCodexToken,
+  refreshIflowToken as _refreshIflowToken,
+  refreshGitHubToken as _refreshGitHubToken,
+  refreshCopilotToken as _refreshCopilotToken,
+  getAccessToken as _getAccessToken,
+  refreshTokenByProvider as _refreshTokenByProvider,
+  formatProviderCredentials as _formatProviderCredentials,
+  getAllAccessTokens as _getAllAccessTokens,
+  refreshKiroToken as _refreshKiroToken,
+  getRefreshLeadMs as _getRefreshLeadMs
+} from "open-sse/services/tokenRefresh.js";
+import {
+  refreshProviderCredentials as _refreshProviderCredentials,
+  shouldRefreshCredentials as _shouldRefreshCredentials,
+} from "open-sse/services/oauthCredentialManager.js";
+
+export const TOKEN_EXPIRY_BUFFER_MS = BUFFER_MS;
+
+// ─── Re-exports wrapped with local logger ─────────────────────────────────────
+
+export const refreshAccessToken = (provider, refreshToken, credentials) =>
+  _refreshAccessToken(provider, refreshToken, credentials, log);
+
+export const refreshClaudeOAuthToken = (refreshToken) =>
+  _refreshClaudeOAuthToken(refreshToken, log);
+
+export const refreshGoogleToken = (refreshToken, clientId, clientSecret) =>
+  _refreshGoogleToken(refreshToken, clientId, clientSecret, log);
+
+export const refreshQwenToken = (refreshToken) =>
+  _refreshQwenToken(refreshToken, log);
+
+export const refreshCodexToken = (refreshToken) =>
+  _refreshCodexToken(refreshToken, log);
+
+export const refreshIflowToken = (refreshToken) =>
+  _refreshIflowToken(refreshToken, log);
+
+export const refreshGitHubToken = (refreshToken) =>
+  _refreshGitHubToken(refreshToken, log);
+
+export const refreshCopilotToken = (githubAccessToken) =>
+  _refreshCopilotToken(githubAccessToken, log);
+
+export const refreshKiroToken = (refreshToken, providerSpecificData) =>
+  _refreshKiroToken(refreshToken, providerSpecificData, log);
+
+export const getAccessToken = (provider, credentials) =>
+  _getAccessToken(provider, credentials, log);
+
+export const refreshTokenByProvider = (provider, credentials) =>
+  _refreshTokenByProvider(provider, credentials, log);
+
+export const formatProviderCredentials = (provider, credentials) =>
+  _formatProviderCredentials(provider, credentials, log);
+
+export const getAllAccessTokens = (userInfo) =>
+  _getAllAccessTokens(userInfo, log);
+
+export const shouldRefreshCredentials = (provider, credentials) =>
+  _shouldRefreshCredentials(provider, credentials);
+
+// ─── Lifecycle hook ───────────────────────────────────────────────────────────
+
+/**
+ * Call this when a connection is fully closed / removed.
+ * Aborts any in-flight projectId fetch and evicts its cache entry,
+ * preventing the module-level Maps from accumulating stale entries.
+ *
+ * @param {string} connectionId
+ */
+export function releaseConnection(connectionId) {
+  if (!connectionId) return;
+  removeConnection(connectionId);
+  log.debug("TOKEN_REFRESH", "Released connection resources", { connectionId });
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Compute an ISO expiry timestamp from a relative expiresIn (seconds).
+ * @param {number} expiresIn
+ * @returns {string}
+ */
+function toExpiresAt(expiresIn) {
+  return new Date(Date.now() + expiresIn * 1000).toISOString();
+}
+
+function normalizeExpiresAt(expiresAt) {
+  if (!expiresAt) return null;
+  const date = new Date(expiresAt);
+  if (!Number.isFinite(date.getTime())) return null;
+  return date.toISOString();
+}
+
+/**
+ * Providers that carry a real Google project ID.
+ * @param {string} provider
+ * @returns {boolean}
+ */
+function needsProjectId(provider) {
+  return provider === "antigravity" || provider === "gemini-cli";
+}
+
+/**
+ * Non-blocking: fetch the project ID for a connection after a token refresh and
+ * persist it to localDb.  Invalidates the stale cached value first so the fetch
+ * always retrieves a fresh one.
+ *
+ * @param {string} provider
+ * @param {string} connectionId
+ * @param {string} accessToken
+ */
+function _refreshProjectId(provider, connectionId, accessToken) {
+  if (!needsProjectId(provider) || !connectionId || !accessToken) return;
+
+  // Evict the stale cached entry so getProjectIdForConnection does a real fetch
+  invalidateProjectId(connectionId);
+
+  getProjectIdForConnection(connectionId, accessToken)
+    .then((projectId) => {
+      if (!projectId) return;
+      updateProviderCredentials(connectionId, { projectId }).catch((err) => {
+        log.debug("TOKEN_REFRESH", "Failed to persist refreshed projectId", {
+          connectionId,
+          error: err?.message ?? err,
+        });
+      });
+    })
+    .catch((err) => {
+      log.debug("TOKEN_REFRESH", "Failed to fetch projectId after token refresh", {
+        connectionId,
+        error: err?.message ?? err,
+      });
+    });
+}
+
+// ─── Local-specific: persist credentials to localDb ──────────────────────────
+
+/**
+ * Persist updated credentials for a connection to localDb.
+ * Only fields that are present in `newCredentials` are written.
+ *
+ * @param {string} connectionId
+ * @param {object} newCredentials
+ * @returns {Promise<boolean>}
+ */
+export async function updateProviderCredentials(connectionId, newCredentials) {
+  try {
+    const updates = {};
+
+    if (newCredentials.accessToken)         updates.accessToken  = newCredentials.accessToken;
+    if (newCredentials.refreshToken)        updates.refreshToken = newCredentials.refreshToken;
+    if (newCredentials.idToken)             updates.idToken = newCredentials.idToken;
+    if (newCredentials.lastRefreshAt)       updates.lastRefreshAt = newCredentials.lastRefreshAt;
+    if (newCredentials.expiresAt)           updates.expiresAt = newCredentials.expiresAt;
+    if (newCredentials.expiresIn) {
+      updates.expiresAt = toExpiresAt(newCredentials.expiresIn);
+      updates.expiresIn = newCredentials.expiresIn;
+    } else if (newCredentials.expiresAt) {
+      const expiresAt = normalizeExpiresAt(newCredentials.expiresAt);
+      if (expiresAt) {
+        updates.expiresAt = expiresAt;
+        updates.expiresIn = Math.max(1, Math.floor((new Date(expiresAt).getTime() - Date.now()) / 1000));
+      }
+    }
+    if (newCredentials.providerSpecificData) {
+      updates.providerSpecificData = {
+        ...(newCredentials.existingProviderSpecificData || {}),
+        ...newCredentials.providerSpecificData,
+      };
+    }
+    if (newCredentials.copilotToken || newCredentials.copilotTokenExpiresAt) {
+      updates.providerSpecificData = {
+        ...(updates.providerSpecificData || newCredentials.existingProviderSpecificData || {}),
+        ...(newCredentials.copilotToken ? { copilotToken: newCredentials.copilotToken } : {}),
+        ...(newCredentials.copilotTokenExpiresAt ? { copilotTokenExpiresAt: newCredentials.copilotTokenExpiresAt } : {}),
+      };
+    }
+    if (newCredentials.projectId)            updates.projectId = newCredentials.projectId;
+
+    const result = await updateProviderConnection(connectionId, updates);
+    log.info("TOKEN_REFRESH", "Credentials updated in localDb", {
+      connectionId,
+      success: !!result
+    });
+    return !!result;
+  } catch (error) {
+    log.error("TOKEN_REFRESH", "Error updating credentials in localDb", {
+      connectionId,
+      error: error.message,
+    });
+    return false;
+  }
+}
+
+// ─── Local-specific: proactive token refresh ─────────────────────────────────
+
+/**
+ * Check whether the provider token (and, for GitHub, the Copilot token) is
+ * about to expire and refresh it proactively.
+ *
+ * @param {string} provider
+ * @param {object} credentials
+ * @returns {Promise<object>} updated credentials object
+ */
+export async function checkAndRefreshToken(provider, credentials) {
+  let creds = { ...credentials };
+  if (!creds.connectionId && creds.id) {
+    creds.connectionId = creds.id;
+  }
+
+  // ── 1. Regular access-token expiry ────────────────────────────────────────
+  if (_shouldRefreshCredentials(provider, creds)) {
+    const expiresAt = creds.expiresAt ? new Date(creds.expiresAt).getTime() : null;
+    const remaining = expiresAt ? expiresAt - Date.now() : null;
+    const refreshLead = _getRefreshLeadMs(provider);
+
+    log.info("TOKEN_REFRESH", "Refreshing provider credentials proactively", {
+      provider,
+      expiresIn: remaining === null ? null : Math.round(remaining / 1000),
+      refreshLeadMs: refreshLead,
+      lastRefreshAt: creds.lastRefreshAt || null,
+    });
+
+    const newCreds = await _refreshProviderCredentials(provider, creds, log);
+    if (newCreds?.accessToken || newCreds?.apiKey || newCreds?.copilotToken) {
+      const mergedCreds = {
+        ...newCreds,
+        existingProviderSpecificData: creds.providerSpecificData,
+      };
+
+      // Persist to DB (non-blocking path continues below)
+      await updateProviderCredentials(creds.connectionId, mergedCreds);
+
+      creds = {
+        ...creds,
+        ...newCreds,
+        expiresAt: newCreds.expiresIn
+          ? toExpiresAt(newCreds.expiresIn)
+          : normalizeExpiresAt(newCreds.expiresAt) || newCreds.expiresAt || creds.expiresAt,
+        providerSpecificData: newCreds.providerSpecificData
+          ? { ...creds.providerSpecificData, ...newCreds.providerSpecificData }
+          : creds.providerSpecificData,
+      };
+
+      // Non-blocking: refresh projectId with the new access token
+      _refreshProjectId(provider, creds.connectionId, creds.accessToken);
+    }
+  }
+
+  // ── 2. GitHub Copilot token expiry ────────────────────────────────────────
+  if (provider === "github") {
+    const copilotToken = creds.providerSpecificData?.copilotToken;
+    const copilotExpiresAt = creds.providerSpecificData?.copilotTokenExpiresAt
+      ? creds.providerSpecificData.copilotTokenExpiresAt * 1000
+      : 0;
+    const now              = Date.now();
+    const remaining        = copilotExpiresAt - now;
+
+    if (!copilotToken || remaining < TOKEN_EXPIRY_BUFFER_MS) {
+      log.info("TOKEN_REFRESH", "Copilot token expiring soon or missing, refreshing proactively", {
+        provider,
+        expiresIn: copilotToken ? Math.round(remaining / 1000) : "missing",
+      });
+
+      const copilotTokenResult = await refreshCopilotToken(creds.accessToken);
+      if (copilotTokenResult) {
+        const updatedSpecific = {
+          ...creds.providerSpecificData,
+          copilotToken:          copilotTokenResult.token,
+          copilotTokenExpiresAt: copilotTokenResult.expiresAt,
+        };
+
+        await updateProviderCredentials(creds.connectionId, {
+          providerSpecificData: updatedSpecific,
+        });
+
+        creds.providerSpecificData = updatedSpecific;
+        creds.copilotToken = copilotTokenResult.token;
+      }
+    }
+  }
+
+  return creds;
+}
+
+// ─── Local-specific: combined GitHub + Copilot refresh ───────────────────────
+
+/**
+ * Refresh the GitHub OAuth token and immediately exchange it for a fresh
+ * Copilot token.
+ *
+ * @param {object} credentials  – must contain `refreshToken`
+ * @returns {Promise<object|null>} merged credentials or the raw GitHub credentials on Copilot failure
+ */
+export async function refreshGitHubAndCopilotTokens(credentials) {
+  const newGitHubCreds = await refreshGitHubToken(credentials.refreshToken);
+  if (!newGitHubCreds?.accessToken) return newGitHubCreds;
+
+  const copilotToken = await refreshCopilotToken(newGitHubCreds.accessToken);
+  if (!copilotToken) return newGitHubCreds;
+
+  return {
+    ...newGitHubCreds,
+    providerSpecificData: {
+      copilotToken:          copilotToken.token,
+      copilotTokenExpiresAt: copilotToken.expiresAt,
+    },
+  };
+}
diff --git a/src/sse/utils/logger.js b/src/sse/utils/logger.js
new file mode 100644
index 0000000..a9c631e
--- /dev/null
+++ b/src/sse/utils/logger.js
@@ -0,0 +1,117 @@
+// Logger utility for cloud
+
+const LOG_LEVELS = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3
+};
+
+const LEVEL = LOG_LEVELS[process.env.LOG_LEVEL?.toUpperCase?.()] ?? LOG_LEVELS.INFO;
+
+function formatTime() {
+  return new Date().toLocaleTimeString("en-US", { hour12: false });
+}
+
+// Colored-dot tags to correlate request lines by session (same session → same color)
+const REQ_TAGS = ["🟢", "🔵", "🟣", "🟡", "🟠", "🔴", "⚪", "🟤"];
+let tagCursor = 0;
+
+// Allocate next rotating tag (fallback when no session seed available)
+export function nextTag() {
+  const tag = REQ_TAGS[tagCursor % REQ_TAGS.length];
+  tagCursor++;
+  return tag;
+}
+
+// Stable tag derived from a session/connection seed: same seed always maps to the same color
+export function tagForSession(seed) {
+  if (!seed) return nextTag();
+  let h = 0;
+  for (let i = 0; i < seed.length; i++) h = (h * 31 + seed.charCodeAt(i)) | 0;
+  return REQ_TAGS[Math.abs(h) % REQ_TAGS.length];
+}
+
+// Print one correlated line: [time] tag symbol message
+export function line(tag, symbol, message) {
+  if (LEVEL > LOG_LEVELS.INFO) return;
+  console.log(`[${formatTime()}] ${tag} ${symbol} ${message}`);
+}
+
+// Like line() but always printed regardless of LOG_LEVEL (errors must never be hidden)
+export function errorLine(tag, symbol, message) {
+  console.log(`[${formatTime()}] ${tag} ${symbol} ${message}`);
+}
+
+// Format thinking intent for the request line ("high(10k)" / "off" / "auto")
+export function fmtThink(intent) {
+  if (!intent || !intent.mode) return null;
+  if (intent.mode === "none") return "off";
+  if (intent.mode === "auto") return "auto";
+  if (intent.mode === "budget") {
+    const k = intent.budget >= 1000 ? `${Math.round(intent.budget / 1000)}k` : `${intent.budget}`;
+    return k;
+  }
+  if (intent.mode === "level") return intent.level;
+  return null;
+}
+
+function formatData(data) {
+  if (!data) return "";
+  if (typeof data === "string") return data;
+  try {
+    return JSON.stringify(data);
+  } catch {
+    return String(data);
+  }
+}
+
+export function debug(tag, message, data) {
+  if (LEVEL <= LOG_LEVELS.DEBUG) {
+    const dataStr = data ? ` ${formatData(data)}` : "";
+    console.log(`[${formatTime()}] 🔍 [${tag}] ${message}${dataStr}`);
+  }
+}
+
+export function info(tag, message, data) {
+  if (LEVEL <= LOG_LEVELS.INFO) {
+    const dataStr = data ? ` ${formatData(data)}` : "";
+    console.log(`[${formatTime()}] ℹ️  [${tag}] ${message}${dataStr}`);
+  }
+}
+
+export function warn(tag, message, data) {
+  if (LEVEL <= LOG_LEVELS.WARN) {
+    const dataStr = data ? ` ${formatData(data)}` : "";
+    console.warn(`[${formatTime()}] ⚠️  [${tag}] ${message}${dataStr}`);
+  }
+}
+
+export function error(tag, message, data) {
+  if (LEVEL <= LOG_LEVELS.ERROR) {
+    const dataStr = data ? ` ${formatData(data)}` : "";
+    console.log(`[${formatTime()}] ❌ [${tag}] ${message}${dataStr}`);
+  }
+}
+
+export function request(method, path, extra) {
+  const dataStr = extra ? ` ${formatData(extra)}` : "";
+  console.log(`\x1b[36m[${formatTime()}] 📥 ${method} ${path}${dataStr}\x1b[0m`);
+}
+
+export function response(status, duration, extra) {
+  const icon = status < 400 ? "📤" : "💥";
+  const dataStr = extra ? ` ${formatData(extra)}` : "";
+  console.log(`[${formatTime()}] ${icon} ${status} (${duration}ms)${dataStr}`);
+}
+
+export function stream(event, data) {
+  const dataStr = data ? ` ${formatData(data)}` : "";
+  console.log(`[${formatTime()}] 🌊 [STREAM] ${event}${dataStr}`);
+}
+
+// Mask sensitive data
+export function maskKey(key) {
+  if (!key || key.length < 8) return "***";
+  return `${key.slice(0, 4)}...${key.slice(-4)}`;
+}
diff --git a/src/store/headerSearchStore.js b/src/store/headerSearchStore.js
new file mode 100644
index 0000000..7792787
--- /dev/null
+++ b/src/store/headerSearchStore.js
@@ -0,0 +1,19 @@
+/**
+ * Header Search Store — Zustand-based reusable search input in Header.
+ * Pages register placeholder on mount, read query, unregister on unmount.
+ */
+
+import { create } from "zustand";
+
+export const useHeaderSearchStore = create((set) => ({
+  query: "",
+  placeholder: "",
+  visible: false,
+
+  setQuery: (query) => set({ query }),
+
+  register: (placeholder = "Search...") =>
+    set({ visible: true, placeholder, query: "" }),
+
+  unregister: () => set({ visible: false, placeholder: "", query: "" }),
+}));
diff --git a/src/store/index.js b/src/store/index.js
new file mode 100644
index 0000000..e057a0e
--- /dev/null
+++ b/src/store/index.js
@@ -0,0 +1,6 @@
+// Zustand Stores - Export all
+export { default as useThemeStore } from "./themeStore";
+export { default as useUserStore } from "./userStore";
+export { default as useProviderStore } from "./providerStore";
+export { useNotificationStore } from "./notificationStore";
+
diff --git a/src/store/notificationStore.js b/src/store/notificationStore.js
new file mode 100644
index 0000000..ea51715
--- /dev/null
+++ b/src/store/notificationStore.js
@@ -0,0 +1,45 @@
+/**
+ * Notification Store — Zustand-based global toast notification system.
+ * Centralized feedback for dashboard actions.
+ */
+
+import { create } from "zustand";
+
+let idCounter = 0;
+
+export const useNotificationStore = create((set, get) => ({
+  notifications: [],
+
+  addNotification: (notification) => {
+    const id = ++idCounter;
+    const entry = {
+      id,
+      type: notification.type || "info",
+      message: notification.message,
+      title: notification.title || null,
+      duration: notification.duration ?? 5000,
+      dismissible: notification.dismissible ?? true,
+      createdAt: Date.now(),
+    };
+
+    set((s) => ({ notifications: [...s.notifications, entry] }));
+
+    // Auto-dismiss
+    if (entry.duration > 0) {
+      setTimeout(() => get().removeNotification(id), entry.duration);
+    }
+
+    return id;
+  },
+
+  removeNotification: (id) => {
+    set((s) => ({ notifications: s.notifications.filter((n) => n.id !== id) }));
+  },
+
+  clearAll: () => set({ notifications: [] }),
+
+  success: (message, title) => get().addNotification({ type: "success", message, title }),
+  error: (message, title) => get().addNotification({ type: "error", message, title, duration: 8000 }),
+  warning: (message, title) => get().addNotification({ type: "warning", message, title }),
+  info: (message, title) => get().addNotification({ type: "info", message, title }),
+}));
diff --git a/src/store/providerStore.js b/src/store/providerStore.js
new file mode 100644
index 0000000..6743c7f
--- /dev/null
+++ b/src/store/providerStore.js
@@ -0,0 +1,55 @@
+"use client";
+
+import { create } from "zustand";
+import { CLIENT_STORE_TTL_MS } from "@/shared/constants/config";
+
+const useProviderStore = create((set, get) => ({
+  providers: [],
+  loading: false,
+  error: null,
+  lastFetched: 0,
+
+  setProviders: (providers) => set({ providers, lastFetched: Date.now() }),
+
+  addProvider: (provider) =>
+    set((state) => ({ providers: [provider, ...state.providers] })),
+
+  updateProvider: (id, updates) =>
+    set((state) => ({
+      providers: state.providers.map((p) =>
+        p._id === id ? { ...p, ...updates } : p
+      ),
+    })),
+
+  removeProvider: (id) =>
+    set((state) => ({
+      providers: state.providers.filter((p) => p._id !== id),
+    })),
+
+  invalidate: () => set({ lastFetched: 0 }),
+
+  setLoading: (loading) => set({ loading }),
+
+  setError: (error) => set({ error }),
+
+  // Skips network when cache is fresh (< CLIENT_STORE_TTL_MS). Pass {force:true} to override.
+  fetchProviders: async ({ force = false } = {}) => {
+    const { lastFetched, providers } = get();
+    if (!force && providers.length > 0 && Date.now() - lastFetched < CLIENT_STORE_TTL_MS) return;
+    set({ loading: true, error: null });
+    try {
+      const response = await fetch("/api/providers");
+      const data = await response.json();
+      if (response.ok) {
+        set({ providers: data.connections || data.providers || [], loading: false, lastFetched: Date.now() });
+      } else {
+        set({ error: data.error, loading: false });
+      }
+    } catch (error) {
+      set({ error: "Failed to fetch providers", loading: false });
+    }
+  },
+}));
+
+export default useProviderStore;
+
diff --git a/src/store/settingsStore.js b/src/store/settingsStore.js
new file mode 100644
index 0000000..e5f0a71
--- /dev/null
+++ b/src/store/settingsStore.js
@@ -0,0 +1,51 @@
+"use client";
+
+import { create } from "zustand";
+import { CLIENT_STORE_TTL_MS } from "@/shared/constants/config";
+
+const useSettingsStore = create((set, get) => ({
+  settings: null,
+  loading: false,
+  error: null,
+  lastFetched: 0,
+
+  invalidate: () => set({ lastFetched: 0 }),
+
+  // Skips network when cache is fresh; pass {force:true} to override
+  fetchSettings: async ({ force = false } = {}) => {
+    const { lastFetched, settings } = get();
+    if (!force && settings && Date.now() - lastFetched < CLIENT_STORE_TTL_MS) return settings;
+    set({ loading: true, error: null });
+    try {
+      const res = await fetch("/api/settings");
+      const data = await res.json();
+      if (res.ok) {
+        set({ settings: data, loading: false, lastFetched: Date.now() });
+        return data;
+      }
+      set({ error: data.error, loading: false });
+    } catch (e) {
+      set({ error: "Failed to fetch settings", loading: false });
+    }
+    return null;
+  },
+
+  // PATCH server + merge into local cache (no extra fetch needed)
+  patchSettings: async (patch) => {
+    try {
+      const res = await fetch("/api/settings", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(patch),
+      });
+      if (!res.ok) return null;
+      const updated = await res.json();
+      set({ settings: updated, lastFetched: Date.now() });
+      return updated;
+    } catch {
+      return null;
+    }
+  },
+}));
+
+export default useSettingsStore;
diff --git a/src/store/themeStore.js b/src/store/themeStore.js
new file mode 100644
index 0000000..ecd9a09
--- /dev/null
+++ b/src/store/themeStore.js
@@ -0,0 +1,54 @@
+"use client";
+
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import { THEME_CONFIG } from "@/shared/constants/config";
+
+const useThemeStore = create(
+  persist(
+    (set, get) => ({
+      theme: THEME_CONFIG.defaultTheme,
+
+      setTheme: (theme) => {
+        set({ theme });
+        applyTheme(theme);
+      },
+
+      toggleTheme: () => {
+        const currentTheme = get().theme;
+        const newTheme = currentTheme === "dark" ? "light" : "dark";
+        set({ theme: newTheme });
+        applyTheme(newTheme);
+      },
+
+      initTheme: () => {
+        const theme = get().theme;
+        applyTheme(theme);
+      },
+    }),
+    {
+      name: THEME_CONFIG.storageKey,
+    }
+  )
+);
+
+// Apply theme to document
+function applyTheme(theme) {
+  if (typeof window === "undefined") return;
+
+  const root = document.documentElement;
+  const systemTheme = window.matchMedia("(prefers-color-scheme: dark)").matches
+    ? "dark"
+    : "light";
+
+  const effectiveTheme = theme === "system" ? systemTheme : theme;
+
+  if (effectiveTheme === "dark") {
+    root.classList.add("dark");
+  } else {
+    root.classList.remove("dark");
+  }
+}
+
+export default useThemeStore;
+
diff --git a/src/store/userStore.js b/src/store/userStore.js
new file mode 100644
index 0000000..a82e144
--- /dev/null
+++ b/src/store/userStore.js
@@ -0,0 +1,20 @@
+"use client";
+
+import { create } from "zustand";
+
+const useUserStore = create((set) => ({
+  user: null,
+  loading: false,
+  error: null,
+
+  setUser: (user) => set({ user }),
+
+  clearUser: () => set({ user: null }),
+
+  setLoading: (loading) => set({ loading }),
+
+  setError: (error) => set({ error }),
+}));
+
+export default useUserStore;
+
diff --git a/start.sh b/start.sh
new file mode 100755
index 0000000..0e75229
--- /dev/null
+++ b/start.sh
@@ -0,0 +1,4 @@
+docker stop 9router
+docker rm 9router
+docker build -t 9router .
+docker run -d --name 9router -p 20128:20128 --env-file .env -v 9router-data:/app/data 9router
\ No newline at end of file
diff --git a/tests/.gitignore b/tests/.gitignore
new file mode 100644
index 0000000..cfcafcc
--- /dev/null
+++ b/tests/.gitignore
@@ -0,0 +1,4 @@
+node_modules/
+package-lock.json
+.vite/
+coverage/
diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 0000000..807d5fb
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,51 @@
+# 9Router Embeddings Tests
+
+Unit tests for the `/v1/embeddings` endpoint implementation.
+
+## Setup
+
+Vitest must be installed globally or in `/tmp/node_modules` (due to npm workspace hoisting from the root Next.js project):
+
+```bash
+cd /tmp && npm install vitest
+```
+
+## Running Tests
+
+```bash
+cd tests/
+NODE_PATH=/tmp/node_modules /tmp/node_modules/.bin/vitest run --reporter=verbose --config ./vitest.config.js
+```
+
+Or using the package script (from the `tests/` directory):
+
+```bash
+npm test
+```
+
+## Test Files
+
+| File | What it tests |
+|------|--------------|
+| `unit/embeddingsCore.test.js` | `open-sse/handlers/embeddingsCore.js` — core logic: body builder, URL router, headers, handler flow |
+| `unit/embeddings.cloud.test.js` | `cloud/src/handlers/embeddings.js` — cloud worker handler: auth, validation, rate limits, CORS |
+
+## Coverage Summary (59 tests)
+
+### `embeddingsCore.test.js` (36 tests)
+- `buildEmbeddingsBody`: single string, array, encoding_format, default float
+- `buildEmbeddingsUrl`: openai, openrouter, openai-compatible-*, unsupported providers
+- `buildEmbeddingsHeaders`: per-provider header sets, fallback to accessToken
+- `handleEmbeddingsCore` input validation: missing, wrong type, null, empty
+- `handleEmbeddingsCore` success: response format, CORS, Content-Type, callbacks
+- `handleEmbeddingsCore` errors: 400/429/500, network error, invalid JSON
+- `handleEmbeddingsCore` token refresh: 401 retry, graceful fallback
+
+### `embeddings.cloud.test.js` (23 tests)
+- CORS OPTIONS: 200 response, empty body, correct headers
+- Authentication: missing key, bad format, old-format key, wrong key value, valid key
+- Body validation: invalid JSON, missing model, missing input, bad model
+- Happy path: single string, array, correct delegation, CORS header, machineId override
+- Rate limiting: all accounts rate-limited → 503 + Retry-After, no credentials → 400
+- Error propagation: non-fallback errors passed through, 429 exhausts accounts
+- machineId override: validates key, rejects wrong key
diff --git a/tests/__baseline__/alias-baseline.json b/tests/__baseline__/alias-baseline.json
new file mode 100644
index 0000000..c104335
--- /dev/null
+++ b/tests/__baseline__/alias-baseline.json
@@ -0,0 +1,247 @@
+{
+  "aliasToId": {
+    "cc": "claude",
+    "cx": "codex",
+    "gc": "gemini-cli",
+    "qw": "qwen",
+    "if": "iflow",
+    "ag": "antigravity",
+    "gh": "github",
+    "kr": "kiro",
+    "cu": "cursor",
+    "kc": "kilocode",
+    "kmc": "kimi-coding",
+    "cl": "cline",
+    "oc": "opencode",
+    "ocg": "opencode-go",
+    "qd": "qoder",
+    "qoder": "qoder",
+    "el": "elevenlabs",
+    "openai": "openai",
+    "vercel": "vercel-ai-gateway",
+    "vercel-ai-gateway": "vercel-ai-gateway",
+    "anthropic": "anthropic",
+    "gemini": "gemini",
+    "openrouter": "openrouter",
+    "glm": "glm",
+    "kimi": "kimi",
+    "minimax": "minimax",
+    "minimax-cn": "minimax-cn",
+    "hf": "huggingface",
+    "huggingface": "huggingface",
+    "ds": "deepseek",
+    "deepseek": "deepseek",
+    "cmc": "commandcode",
+    "commandcode": "commandcode",
+    "groq": "groq",
+    "xai": "xai",
+    "mistral": "mistral",
+    "pplx": "perplexity",
+    "perplexity": "perplexity",
+    "together": "together",
+    "fireworks": "fireworks",
+    "cerebras": "cerebras",
+    "cohere": "cohere",
+    "nvidia": "nvidia",
+    "nebius": "nebius",
+    "siliconflow": "siliconflow",
+    "hyp": "hyperbolic",
+    "hyperbolic": "hyperbolic",
+    "dg": "deepgram",
+    "deepgram": "deepgram",
+    "aai": "assemblyai",
+    "assemblyai": "assemblyai",
+    "nb": "nanobanana",
+    "nanobanana": "nanobanana",
+    "ch": "chutes",
+    "chutes": "chutes",
+    "ark": "volcengine-ark",
+    "volcengine-ark": "volcengine-ark",
+    "byteplus": "byteplus",
+    "bpm": "byteplus",
+    "cursor": "cursor",
+    "vx": "vertex",
+    "vertex": "vertex",
+    "vxp": "vertex-partner",
+    "vertex-partner": "vertex-partner",
+    "gw": "grok-web",
+    "grok-web": "grok-web",
+    "gcli": "grok-cli",
+    "gb": "grok-cli",
+    "grok-build": "grok-cli",
+    "grok-cli": "grok-cli",
+    "pw": "perplexity-web",
+    "perplexity-web": "perplexity-web",
+    "mimo": "xiaomi-mimo",
+    "xiaomi-mimo": "xiaomi-mimo",
+    "xmtp": "xiaomi-tokenplan",
+    "xiaomi-tokenplan": "xiaomi-tokenplan",
+    "cf": "cloudflare-ai",
+    "cloudflare-ai": "cloudflare-ai",
+    "fal": "fal-ai",
+    "fal-ai": "fal-ai",
+    "stability": "stability-ai",
+    "stability-ai": "stability-ai",
+    "bfl": "black-forest-labs",
+    "black-forest-labs": "black-forest-labs",
+    "recraft": "recraft",
+    "topaz": "topaz",
+    "runway": "runwayml",
+    "runwayml": "runwayml",
+    "jina": "jina-ai",
+    "jina-ai": "jina-ai",
+    "polly": "aws-polly",
+    "aws-polly": "aws-polly",
+    "bb": "blackbox",
+    "blackbox": "blackbox"
+  },
+  "idToAlias": {
+    "alicode": "alicode",
+    "alicode-intl": "alicode-intl",
+    "anthropic": "anthropic",
+    "antigravity": "ag",
+    "assemblyai": "assemblyai",
+    "azure": "azure",
+    "blackbox": "blackbox",
+    "byteplus": "byteplus",
+    "cerebras": "cerebras",
+    "chutes": "chutes",
+    "claude": "cc",
+    "cline": "cl",
+    "clinepass": "clinepass",
+    "cloudflare-ai": "cloudflare-ai",
+    "codebuddy-cn": "cbcn",
+    "codex": "cx",
+    "cohere": "cohere",
+    "commandcode": "commandcode",
+    "cursor": "cu",
+    "deepgram": "deepgram",
+    "deepseek": "deepseek",
+    "fireworks": "fireworks",
+    "gemini": "gemini",
+    "gemini-cli": "gc",
+    "github": "gh",
+    "gitlab": "gitlab",
+    "glm": "glm",
+    "glm-cn": "glm-cn",
+    "grok-cli": "gcli",
+    "grok-web": "grok-web",
+    "groq": "groq",
+    "hyperbolic": "hyperbolic",
+    "iflow": "if",
+    "kilocode": "kc",
+    "kimchi": "kimchi",
+    "kimi": "kimi",
+    "kimi-coding": "kmc",
+    "kiro": "kr",
+    "mimo-free": "mmf",
+    "minimax": "minimax",
+    "minimax-cn": "minimax-cn",
+    "mistral": "mistral",
+    "mmf": "mmf",
+    "nanobanana": "nanobanana",
+    "nebius": "nebius",
+    "nvidia": "nvidia",
+    "ollama": "ollama",
+    "ollama-local": "ollama-local",
+    "openai": "openai",
+    "opencode": "oc",
+    "opencode-go": "opencode-go",
+    "openrouter": "openrouter",
+    "perplexity": "perplexity",
+    "perplexity-web": "perplexity-web",
+    "qoder": "qd",
+    "qwen": "qw",
+    "siliconflow": "siliconflow",
+    "together": "together",
+    "venice": "venice",
+    "vercel-ai-gateway": "vercel-ai-gateway",
+    "vertex": "vertex",
+    "vertex-partner": "vertex-partner",
+    "volcengine-ark": "volcengine-ark",
+    "xai": "xai",
+    "xiaomi-mimo": "xiaomi-mimo",
+    "xiaomi-tokenplan": "xiaomi-tokenplan"
+  },
+  "modelKeys": [
+    "ag",
+    "alicode",
+    "alicode-intl",
+    "anthropic",
+    "assemblyai",
+    "black-forest-labs",
+    "blackbox",
+    "byteplus",
+    "cbcn",
+    "cc",
+    "cerebras",
+    "cl",
+    "clinepass",
+    "cloudflare-ai",
+    "cohere",
+    "comfyui",
+    "commandcode",
+    "cu",
+    "cx",
+    "deepgram",
+    "deepseek",
+    "edge-tts",
+    "elevenlabs-tts-models",
+    "fal-ai",
+    "fireworks",
+    "gc",
+    "gcli",
+    "gemini",
+    "gemini-tts-models",
+    "gemini-tts-voices",
+    "gh",
+    "glm",
+    "glm-cn",
+    "google-tts",
+    "grok-web",
+    "groq",
+    "huggingface",
+    "hyperbolic",
+    "if",
+    "kc",
+    "kimchi",
+    "kimi",
+    "kmc",
+    "kr",
+    "local-device",
+    "minimax",
+    "minimax-cn",
+    "mistral",
+    "mmf",
+    "nanobanana",
+    "nebius",
+    "nvidia",
+    "oc",
+    "ollama",
+    "openai",
+    "openai-tts-models",
+    "openai-tts-voices",
+    "opencode-go",
+    "openrouter",
+    "openrouter-tts-models",
+    "openrouter-tts-voices",
+    "perplexity",
+    "perplexity-web",
+    "qd",
+    "qw",
+    "recraft",
+    "runwayml",
+    "sdwebui",
+    "siliconflow",
+    "stability-ai",
+    "together",
+    "venice",
+    "vertex",
+    "vertex-partner",
+    "volcengine-ark",
+    "voyage-ai",
+    "xai",
+    "xiaomi-mimo",
+    "xiaomi-tokenplan"
+  ]
+}
\ No newline at end of file
diff --git a/tests/__baseline__/baseline-results.json b/tests/__baseline__/baseline-results.json
new file mode 100644
index 0000000..fa74516
--- /dev/null
+++ b/tests/__baseline__/baseline-results.json
@@ -0,0 +1 @@
+{"numTotalTestSuites":209,"numPassedTestSuites":192,"numFailedTestSuites":17,"numPendingTestSuites":0,"numTotalTests":674,"numPassedTests":628,"numFailedTests":26,"numPendingTests":20,"numTodoTests":0,"snapshot":{"added":0,"failure":false,"filesAdded":0,"filesRemoved":0,"filesRemovedList":[],"filesUnmatched":0,"filesUpdated":0,"matched":0,"total":0,"unchecked":0,"uncheckedKeysByFile":[],"unmatched":0,"updated":0,"didUpdate":false},"startTime":1781341952244,"success":false,"testResults":[{"assertionResults":[{"ancestorTitles":["Antigravity → OpenAI"],"fullName":"Antigravity → OpenAI functionResponse + functionCall in same content keeps both","status":"passed","title":"functionResponse + functionCall in same content keeps both","duration":29.259041999999994,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity → OpenAI"],"fullName":"Antigravity → OpenAI functionCall without id keeps a stable matchable id","status":"passed","title":"functionCall without id keeps a stable matchable id","duration":2.1429170000000113,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity → OpenAI"],"fullName":"Antigravity → OpenAI signature-only part does not produce empty text","status":"passed","title":"signature-only part does not produce empty text","duration":0.2324169999999981,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953823,"endTime":1781341953855.2324,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-antigravity.test.js"},{"assertionResults":[{"ancestorTitles":["Claude Code CLI context → OpenAI"],"fullName":"Claude Code CLI context → OpenAI system array keeps all text parts","status":"passed","title":"system array keeps all text parts","duration":28.801917000000003,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Claude Code CLI context → OpenAI"],"fullName":"Claude Code CLI context → OpenAI assistant thinking block survives Claude→Claude passthrough","status":"passed","title":"assistant thinking block survives Claude→Claude passthrough","duration":0.9545420000000036,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Claude Code CLI context → OpenAI"],"fullName":"Claude Code CLI context → OpenAI redacted_thinking block is not silently dropped","status":"passed","title":"redacted_thinking block is not silently dropped","duration":6.370875000000012,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Claude Code CLI context → OpenAI"],"fullName":"Claude Code CLI context → OpenAI tool_result image block is preserved","status":"passed","title":"tool_result image block is preserved","duration":1.200917000000004,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954140,"endTime":1781341954177.201,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-claudeCode-context.test.js"},{"assertionResults":[{"ancestorTitles":["Codex CLI Responses → OpenAI"],"fullName":"Codex CLI Responses → OpenAI assistant has no empty tool_calls array when all names are empty","status":"passed","title":"assistant has no empty tool_calls array when all names are empty","duration":26.32320900000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex CLI Responses → OpenAI"],"fullName":"Codex CLI Responses → OpenAI function_call arguments end up as a string","status":"passed","title":"function_call arguments end up as a string","duration":1.7851670000000013,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex CLI Responses → OpenAI"],"fullName":"Codex CLI Responses → OpenAI input_image with file_id is not used as a raw url","status":"passed","title":"input_image with file_id is not used as a raw url","duration":1.2574590000000114,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Codex Responses (reverse)"],"fullName":"OpenAI → Codex Responses (reverse) call_id longer than 64 chars is clamped","status":"passed","title":"call_id longer than 64 chars is clamped","duration":0.8494170000000167,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953875,"endTime":1781341953904.8494,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-codexCli-responses.test.js"},{"assertionResults":[{"ancestorTitles":["OpenAI → Gemini"],"fullName":"OpenAI → Gemini multiple system messages are all kept","status":"passed","title":"multiple system messages are all kept","duration":25.31804200000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Cursor"],"fullName":"OpenAI → Cursor image content is preserved","status":"passed","title":"image content is preserved","duration":0.6755830000000174,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Cursor"],"fullName":"OpenAI → Cursor respects client max_tokens","status":"passed","title":"respects client max_tokens","duration":1.0911250000000052,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → CommandCode"],"fullName":"OpenAI → CommandCode malformed tool arguments are not silently emptied","status":"passed","title":"malformed tool arguments are not silently emptied","duration":1.812041999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → CommandCode"],"fullName":"OpenAI → CommandCode image content is preserved","status":"passed","title":"image content is preserved","duration":0.8144159999999943,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954034,"endTime":1781341954064.8145,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-gemini-cursor-commandcode.test.js"},{"assertionResults":[{"ancestorTitles":["OpenAI → Kiro"],"fullName":"OpenAI → Kiro malformed tool arguments do not throw the whole request","status":"passed","title":"malformed tool arguments do not throw the whole request","duration":25.108249999999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Kiro"],"fullName":"OpenAI → Kiro respects client max_tokens","status":"passed","title":"respects client max_tokens","duration":2.615250000000003,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Kiro"],"fullName":"OpenAI → Kiro remote image url is preserved as an image, not text","status":"passed","title":"remote image url is preserved as an image, not text","duration":2.1727500000000077,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953962,"endTime":1781341953992.1729,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-kiro.test.js"},{"assertionResults":[{"ancestorTitles":["bug: Claude → OpenAI bridge data loss"],"fullName":"bug: Claude → OpenAI bridge data loss image with source.type=url is preserved (NOT dropped)","status":"passed","title":"image with source.type=url is preserved (NOT dropped)","duration":31.215708000000006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: Claude → OpenAI bridge data loss"],"fullName":"bug: Claude → OpenAI bridge data loss thinking block survives round-trip Claude→OpenAI→Claude","status":"passed","title":"thinking block survives round-trip Claude→OpenAI→Claude","duration":0.9626670000000104,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: Claude → OpenAI bridge data loss"],"fullName":"bug: Claude → OpenAI bridge data loss tool_result with image block is not turned into raw JSON / dropped","status":"passed","title":"tool_result with image block is not turned into raw JSON / dropped","duration":1.6023329999999874,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: Claude → OpenAI bridge data loss"],"fullName":"bug: Claude → OpenAI bridge data loss tool_result is_error flag is preserved","status":"passed","title":"tool_result is_error flag is preserved","duration":0.8553750000000093,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: Claude → OpenAI bridge data loss"],"fullName":"bug: Claude → OpenAI bridge data loss system array non-text parts are not silently dropped","status":"passed","title":"system array non-text parts are not silently dropped","duration":0.277417000000014,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: tool_call id stability across bridge"],"fullName":"bug: tool_call id stability across bridge sanitized tool id stays matched between call and result","status":"passed","title":"sanitized tool id stays matched between call and result","duration":0.2557079999999985,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: empty content message handling"],"fullName":"bug: empty content message handling assistant message with only tool_calls is not dropped","status":"passed","title":"assistant message with only tool_calls is not dropped","duration":0.1129590000000178,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954079,"endTime":1781341954115.2556,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-openai-bridge.test.js"},{"assertionResults":[{"ancestorTitles":["OpenAI → Claude context mapping"],"fullName":"OpenAI → Claude context mapping does not inject Claude Code system prompt for compatible providers","status":"passed","title":"does not inject Claude Code system prompt for compatible providers","duration":34.8485,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Claude context mapping"],"fullName":"OpenAI → Claude context mapping assistant reasoning_content becomes a thinking block","status":"passed","title":"assistant reasoning_content becomes a thinking block","duration":4.630207999999982,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Claude context mapping"],"fullName":"OpenAI → Claude context mapping tool_choice=none is not turned into auto","status":"passed","title":"tool_choice=none is not turned into auto","duration":8.317957999999976,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Claude context mapping"],"fullName":"OpenAI → Claude context mapping input_audio content is preserved","status":"passed","title":"input_audio content is preserved","duration":0.9009580000000028,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Claude context mapping"],"fullName":"OpenAI → Claude context mapping remote http image_url is preserved","status":"passed","title":"remote http image_url is preserved","duration":0.4690829999999835,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953880,"endTime":1781341953928.901,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-toClaude-context.test.js"},{"assertionResults":[{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cc': all models OpenAI→target","status":"passed","title":"'cc': all models OpenAI→target","duration":28.558791000000014,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cx': all models OpenAI→target","status":"passed","title":"'cx': all models OpenAI→target","duration":0.9200000000000159,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'gc': all models OpenAI→target","status":"passed","title":"'gc': all models OpenAI→target","duration":1.7412919999999872,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'qw': all models OpenAI→target","status":"passed","title":"'qw': all models OpenAI→target","duration":0.3331660000000056,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'if': all models OpenAI→target","status":"passed","title":"'if': all models OpenAI→target","duration":0.3586249999999609,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'ag': all models OpenAI→target","status":"passed","title":"'ag': all models OpenAI→target","duration":2.2445000000000164,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'gh': all models OpenAI→target","status":"passed","title":"'gh': all models OpenAI→target","duration":0.4223330000000374,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'kr': all models OpenAI→target","status":"passed","title":"'kr': all models OpenAI→target","duration":2.3559580000000437,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'qd': all models OpenAI→target","status":"passed","title":"'qd': all models OpenAI→target","duration":1.108791999999994,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cu': all models OpenAI→target","status":"passed","title":"'cu': all models OpenAI→target","duration":1.402749999999969,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'kmc': all models OpenAI→target","status":"passed","title":"'kmc': all models OpenAI→target","duration":0.49099999999998545,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'kc': all models OpenAI→target","status":"passed","title":"'kc': all models OpenAI→target","duration":0.42145800000002964,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'opencode-go': all models OpenAI→target","status":"passed","title":"'opencode-go': all models OpenAI→target","duration":0.42950000000001864,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'mmf': all models OpenAI→target","status":"passed","title":"'mmf': all models OpenAI→target","duration":0.09641700000003084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cl': all models OpenAI→target","status":"passed","title":"'cl': all models OpenAI→target","duration":0.27070800000001327,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openai': all models OpenAI→target","status":"passed","title":"'openai': all models OpenAI→target","duration":0.6065419999999904,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'anthropic': all models OpenAI→target","status":"passed","title":"'anthropic': all models OpenAI→target","duration":0.17037499999997863,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'gemini': all models OpenAI→target","status":"passed","title":"'gemini': all models OpenAI→target","duration":0.5722079999999892,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openrouter': all models OpenAI→target","status":"passed","title":"'openrouter': all models OpenAI→target","duration":0.46325000000001637,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'glm': all models OpenAI→target","status":"passed","title":"'glm': all models OpenAI→target","duration":0.19883399999997664,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'glm-cn': all models OpenAI→target","status":"passed","title":"'glm-cn': all models OpenAI→target","duration":0.1677909999999656,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'kimi': all models OpenAI→target","status":"passed","title":"'kimi': all models OpenAI→target","duration":0.17729200000002265,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'minimax': all models OpenAI→target","status":"passed","title":"'minimax': all models OpenAI→target","duration":0.38649999999995543,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'blackbox': all models OpenAI→target","status":"passed","title":"'blackbox': all models OpenAI→target","duration":0.6220419999999649,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'minimax-cn': all models OpenAI→target","status":"passed","title":"'minimax-cn': all models OpenAI→target","duration":0.1888749999999959,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'alicode': all models OpenAI→target","status":"passed","title":"'alicode': all models OpenAI→target","duration":0.23529200000001538,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'alicode-intl': all models OpenAI→target","status":"passed","title":"'alicode-intl': all models OpenAI→target","duration":0.20758299999999963,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'volcengine-ark': all models OpenAI→target","status":"passed","title":"'volcengine-ark': all models OpenAI→target","duration":0.2471659999999929,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cloudflare-ai': all models OpenAI→target","status":"passed","title":"'cloudflare-ai': all models OpenAI→target","duration":0.3372499999999832,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'byteplus': all models OpenAI→target","status":"passed","title":"'byteplus': all models OpenAI→target","duration":0.20375000000001364,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'deepseek': all models OpenAI→target","status":"passed","title":"'deepseek': all models OpenAI→target","duration":0.7097909999999956,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'commandcode': all models OpenAI→target","status":"passed","title":"'commandcode': all models OpenAI→target","duration":0.5875839999999926,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'groq': all models OpenAI→target","status":"passed","title":"'groq': all models OpenAI→target","duration":0.08074999999996635,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'xai': all models OpenAI→target","status":"passed","title":"'xai': all models OpenAI→target","duration":0.06304099999999835,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'mistral': all models OpenAI→target","status":"passed","title":"'mistral': all models OpenAI→target","duration":0.04779200000001538,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'perplexity': all models OpenAI→target","status":"passed","title":"'perplexity': all models OpenAI→target","duration":0.038334000000020296,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'together': all models OpenAI→target","status":"passed","title":"'together': all models OpenAI→target","duration":0.05616700000001629,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'fireworks': all models OpenAI→target","status":"passed","title":"'fireworks': all models OpenAI→target","duration":0.046790999999984706,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cerebras': all models OpenAI→target","status":"passed","title":"'cerebras': all models OpenAI→target","duration":0.07416599999999107,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cohere': all models OpenAI→target","status":"passed","title":"'cohere': all models OpenAI→target","duration":0.04558299999996507,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'nvidia': all models OpenAI→target","status":"passed","title":"'nvidia': all models OpenAI→target","duration":0.0376250000000482,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'nebius': all models OpenAI→target","status":"passed","title":"'nebius': all models OpenAI→target","duration":0.027874999999994543,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'voyage-ai': all models OpenAI→target","status":"passed","title":"'voyage-ai': all models OpenAI→target","duration":0.08220799999998007,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'siliconflow': all models OpenAI→target","status":"passed","title":"'siliconflow': all models OpenAI→target","duration":0.16133299999995643,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'xiaomi-mimo': all models OpenAI→target","status":"passed","title":"'xiaomi-mimo': all models OpenAI→target","duration":0.053625000000010914,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'xiaomi-tokenplan': all models OpenAI→target","status":"passed","title":"'xiaomi-tokenplan': all models OpenAI→target","duration":0.12087499999995543,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'hyperbolic': all models OpenAI→target","status":"passed","title":"'hyperbolic': all models OpenAI→target","duration":3.2661659999999983,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'ollama': all models OpenAI→target","status":"passed","title":"'ollama': all models OpenAI→target","duration":1.3428749999999923,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'vertex': all models OpenAI→target","status":"passed","title":"'vertex': all models OpenAI→target","duration":0.19454200000001265,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'vertex-partner': all models OpenAI→target","status":"passed","title":"'vertex-partner': all models OpenAI→target","duration":0.06704200000001492,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'grok-web': all models OpenAI→target","status":"passed","title":"'grok-web': all models OpenAI→target","duration":0.10920799999996689,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'perplexity-web': all models OpenAI→target","status":"passed","title":"'perplexity-web': all models OpenAI→target","duration":0.07041700000002038,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openai-tts-models': all models OpenAI→target","status":"passed","title":"'openai-tts-models': all models OpenAI→target","duration":0.043667000000027656,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openai-tts-voices': all models OpenAI→target","status":"passed","title":"'openai-tts-voices': all models OpenAI→target","duration":0.12312499999995907,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openrouter-tts-models': all models OpenAI→target","status":"passed","title":"'openrouter-tts-models': all models OpenAI→target","duration":0.04045899999999847,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openrouter-tts-voices': all models OpenAI→target","status":"passed","title":"'openrouter-tts-voices': all models OpenAI→target","duration":0.12166600000000471,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'elevenlabs-tts-models': all models OpenAI→target","status":"passed","title":"'elevenlabs-tts-models': all models OpenAI→target","duration":0.048583000000007814,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'edge-tts': all models OpenAI→target","status":"passed","title":"'edge-tts': all models OpenAI→target","duration":0.10500000000001819,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'local-device': all models OpenAI→target","status":"passed","title":"'local-device': all models OpenAI→target","duration":0.02400000000000091,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'google-tts': all models OpenAI→target","status":"passed","title":"'google-tts': all models OpenAI→target","duration":0.5091669999999908,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'gemini-tts-models': all models OpenAI→target","status":"passed","title":"'gemini-tts-models': all models OpenAI→target","duration":0.03308399999997391,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'gemini-tts-voices': all models OpenAI→target","status":"passed","title":"'gemini-tts-voices': all models OpenAI→target","duration":0.25729100000000926,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'nanobanana': all models OpenAI→target","status":"passed","title":"'nanobanana': all models OpenAI→target","duration":0.032166999999958534,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'sdwebui': all models OpenAI→target","status":"passed","title":"'sdwebui': all models OpenAI→target","duration":0.033708999999987554,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'comfyui': all models OpenAI→target","status":"passed","title":"'comfyui': all models OpenAI→target","duration":0.03345799999999599,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'huggingface': all models OpenAI→target","status":"passed","title":"'huggingface': all models OpenAI→target","duration":0.04895800000002737,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'agentrouter': all models OpenAI→target","status":"passed","title":"'agentrouter': all models OpenAI→target","duration":0.0731670000000122,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'aimlapi': all models OpenAI→target","status":"passed","title":"'aimlapi': all models OpenAI→target","duration":0.0574579999999969,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'novita': all models OpenAI→target","status":"passed","title":"'novita': all models OpenAI→target","duration":0.1038340000000062,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'modal': all models OpenAI→target","status":"passed","title":"'modal': all models OpenAI→target","duration":0.025041000000044278,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'reka': all models OpenAI→target","status":"passed","title":"'reka': all models OpenAI→target","duration":0.33941700000002584,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'nlpcloud': all models OpenAI→target","status":"passed","title":"'nlpcloud': all models OpenAI→target","duration":0.40483299999999645,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'bazaarlink': all models OpenAI→target","status":"passed","title":"'bazaarlink': all models OpenAI→target","duration":0.09070800000000645,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'completions': all models OpenAI→target","status":"passed","title":"'completions': all models OpenAI→target","duration":0.061082999999996446,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'enally': all models OpenAI→target","status":"passed","title":"'enally': all models OpenAI→target","duration":0.045416999999986274,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'freetheai': all models OpenAI→target","status":"passed","title":"'freetheai': all models OpenAI→target","duration":0.05154200000004039,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'llm7': all models OpenAI→target","status":"passed","title":"'llm7': all models OpenAI→target","duration":0.04487499999999045,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'lepton': all models OpenAI→target","status":"passed","title":"'lepton': all models OpenAI→target","duration":0.05233399999997346,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'kluster': all models OpenAI→target","status":"passed","title":"'kluster': all models OpenAI→target","duration":0.05058299999996052,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'ai21': all models OpenAI→target","status":"passed","title":"'ai21': all models OpenAI→target","duration":0.03291600000000017,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'inference-net': all models OpenAI→target","status":"passed","title":"'inference-net': all models OpenAI→target","duration":0.04341599999997925,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'predibase': all models OpenAI→target","status":"passed","title":"'predibase': all models OpenAI→target","duration":0.06450000000000955,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'bytez': all models OpenAI→target","status":"passed","title":"'bytez': all models OpenAI→target","duration":0.04129199999999855,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'morph': all models OpenAI→target","status":"passed","title":"'morph': all models OpenAI→target","duration":0.032083000000000084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'longcat': all models OpenAI→target","status":"passed","title":"'longcat': all models OpenAI→target","duration":0.0432920000000081,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'puter': all models OpenAI→target","status":"passed","title":"'puter': all models OpenAI→target","duration":0.05958299999997507,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'uncloseai': all models OpenAI→target","status":"passed","title":"'uncloseai': all models OpenAI→target","duration":0.3019170000000031,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'scaleway': all models OpenAI→target","status":"passed","title":"'scaleway': all models OpenAI→target","duration":0.1755420000000072,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'deepinfra': all models OpenAI→target","status":"passed","title":"'deepinfra': all models OpenAI→target","duration":0.13149999999995998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'sambanova': all models OpenAI→target","status":"passed","title":"'sambanova': all models OpenAI→target","duration":0.17849999999998545,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'nscale': all models OpenAI→target","status":"passed","title":"'nscale': all models OpenAI→target","duration":0.21641699999997854,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'baseten': all models OpenAI→target","status":"passed","title":"'baseten': all models OpenAI→target","duration":0.11929199999997309,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'publicai': all models OpenAI→target","status":"passed","title":"'publicai': all models OpenAI→target","duration":0.07558299999999463,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'nous-research': all models OpenAI→target","status":"passed","title":"'nous-research': all models OpenAI→target","duration":0.09041700000000219,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'glhf': all models OpenAI→target","status":"passed","title":"'glhf': all models OpenAI→target","duration":0.12537500000001955,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'deepgram': all models OpenAI→target","status":"passed","title":"'deepgram': all models OpenAI→target","duration":0.19912500000003774,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'assemblyai': all models OpenAI→target","status":"passed","title":"'assemblyai': all models OpenAI→target","duration":0.07058399999999665,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'fal-ai': all models OpenAI→target","status":"passed","title":"'fal-ai': all models OpenAI→target","duration":0.07900000000000773,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'stability-ai': all models OpenAI→target","status":"passed","title":"'stability-ai': all models OpenAI→target","duration":0.058625000000006366,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'black-forest-labs': all models OpenAI→target","status":"passed","title":"'black-forest-labs': all models OpenAI→target","duration":0.06612499999999955,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'recraft': all models OpenAI→target","status":"passed","title":"'recraft': all models OpenAI→target","duration":0.03249999999997044,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'runwayml': all models OpenAI→target","status":"passed","title":"'runwayml': all models OpenAI→target","duration":0.04958299999998417,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: image-strip models drop image content"],"fullName":"coverage: image-strip models drop image content 'kr'/'deepseek-3.2' strips image when strip=[image]","status":"passed","title":"'kr'/'deepseek-3.2' strips image when strip=[image]","duration":0.21595800000000054,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: image-strip models drop image content"],"fullName":"coverage: image-strip models drop image content 'kr'/'qwen3-coder-next' strips image when strip=[image]","status":"passed","title":"'kr'/'qwen3-coder-next' strips image when strip=[image]","duration":0.0574579999999969,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953506,"endTime":1781341953566.216,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/coverage-all-models.test.js"},{"assertionResults":[{"ancestorTitles":["roundtrip: Claude source preserves core fields → OpenAI"],"fullName":"roundtrip: Claude source preserves core fields → OpenAI system → system role","status":"passed","title":"system → system role","duration":0.9429159999999968,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: Claude source preserves core fields → OpenAI"],"fullName":"roundtrip: Claude source preserves core fields → OpenAI tool_use → assistant.tool_calls with matching id","status":"passed","title":"tool_use → assistant.tool_calls with matching id","duration":0.21020899999999187,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: Claude source preserves core fields → OpenAI"],"fullName":"roundtrip: Claude source preserves core fields → OpenAI tool_result → tool message with matching id","status":"passed","title":"tool_result → tool message with matching id","duration":0.14008299999997575,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: Claude source preserves core fields → OpenAI"],"fullName":"roundtrip: Claude source preserves core fields → OpenAI tool arguments are valid JSON string","status":"passed","title":"tool arguments are valid JSON string","duration":0.4514169999999922,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: OpenAI tools → Claude → keeps tool name"],"fullName":"roundtrip: OpenAI tools → Claude → keeps tool name tool name survives openai→claude","status":"passed","title":"tool name survives openai→claude","duration":0.1386669999999981,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: parallel tool calls keep distinct ids"],"fullName":"roundtrip: parallel tool calls keep distinct ids two tool_calls, two distinct ids","status":"passed","title":"two tool_calls, two distinct ids","duration":0.08362499999998363,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: parallel tool calls keep distinct ids"],"fullName":"roundtrip: parallel tool calls keep distinct ids each tool_call has a matching tool result","status":"passed","title":"each tool_call has a matching tool result","duration":0.1049589999999796,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954893,"endTime":1781341954895.4514,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/format-roundtrip.test.js"},{"assertionResults":[{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) has at least one active AG connection with refreshToken","status":"skipped","title":"has at least one active AG connection with refreshToken","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) same sessionId → cache hit on repeated call","status":"skipped","title":"same sessionId → cache hit on repeated call","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) different sessionId (same account) → cache still hits (session-independent)","status":"skipped","title":"different sessionId (same account) → cache still hits (session-independent)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) cross-account → cache SHARED (content-based global cache)","status":"skipped","title":"cross-account → cache SHARED (content-based global cache)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) codex-style sessionId vs random sessionId on unique prompt","status":"skipped","title":"codex-style sessionId vs random sessionId on unique prompt","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) unique prompt (never seen) → explore when cache starts hitting","status":"skipped","title":"unique prompt (never seen) → explore when cache starts hitting","failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952244,"endTime":1781341952244,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/antigravity-cache.test.js"},{"assertionResults":[{"ancestorTitles":["Antigravity MITM model handling"],"fullName":"Antigravity MITM model handling flags the out-of-box agent/Default model mandatory","status":"failed","title":"flags the out-of-box agent/Default model mandatory","duration":3.9357080000000053,"failureMessages":["AssertionError: expected undefined to be true // Object.is equality\n    at /Users/Working/router4/app/tests/unit/antigravity-mitm.test.js:17:86\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity MITM model handling"],"fullName":"Antigravity MITM model handling leaves models not proven auto-sent optional","status":"passed","title":"leaves models not proven auto-sent optional","duration":0.3245420000000081,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity MITM model handling"],"fullName":"Antigravity MITM model handling excludes tab-autocomplete model 'tab_jump_flash_lite_preview' from re-routing","status":"passed","title":"excludes tab-autocomplete model 'tab_jump_flash_lite_preview' from re-routing","duration":0.26379099999999767,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity MITM model handling"],"fullName":"Antigravity MITM model handling excludes tab-autocomplete model 'tab_flash_lite_preview' from re-routing","status":"passed","title":"excludes tab-autocomplete model 'tab_flash_lite_preview' from re-routing","duration":0.202541999999994,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity MITM model handling"],"fullName":"Antigravity MITM model handling does not exclude real agent models from re-routing","status":"passed","title":"does not exclude real agent models from re-routing","duration":0.15816700000002015,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952510,"endTime":1781341952515.1582,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/antigravity-mitm.test.js"},{"assertionResults":[{"ancestorTitles":["PR #1175 - buildOutput filter detection"],"fullName":"PR #1175 - buildOutput filter detection detects npm install output","status":"passed","title":"detects npm install output","duration":1.765874999999994,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - buildOutput filter detection"],"fullName":"PR #1175 - buildOutput filter detection detects cargo build output (no longer misdetected as git-status)","status":"passed","title":"detects cargo build output (no longer misdetected as git-status)","duration":0.6552499999999952,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - buildOutput compression behavior"],"fullName":"PR #1175 - buildOutput compression behavior compresses npm install with deprecations","status":"passed","title":"compresses npm install with deprecations","duration":0.9122080000000068,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - buildOutput compression behavior"],"fullName":"PR #1175 - buildOutput compression behavior compresses cargo build output","status":"passed","title":"compresses cargo build output","duration":0.2546250000000043,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - buildOutput compression behavior"],"fullName":"PR #1175 - buildOutput compression behavior keeps cargo errors verbatim","status":"passed","title":"keeps cargo errors verbatim","duration":0.12070799999999338,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - buildOutput compression behavior"],"fullName":"PR #1175 - buildOutput compression behavior keeps maven BUILD FAILED as error","status":"passed","title":"keeps maven BUILD FAILED as error","duration":0.1518339999999938,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regex fix edge cases"],"fullName":"PR #1175 - porcelain regex fix edge cases git status --porcelain workdir-only (space first char) STILL detects as gitStatus (minimal fix preserved old regex)","status":"passed","title":"git status --porcelain workdir-only (space first char) STILL detects as gitStatus (minimal fix preserved old regex)","duration":0.1607089999999971,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regex fix edge cases"],"fullName":"PR #1175 - porcelain regex fix edge cases git status --porcelain with staged (status code first char) still detects","status":"passed","title":"git status --porcelain with staged (status code first char) still detects","duration":0.06854199999999366,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regex fix edge cases"],"fullName":"PR #1175 - porcelain regex fix edge cases cargo Compiling lines NOT detected as git-status (porcelain false positive fix)","status":"passed","title":"cargo Compiling lines NOT detected as git-status (porcelain false positive fix)","duration":0.4844589999999869,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regex fix edge cases"],"fullName":"PR #1175 - porcelain regex fix edge cases long-form git status with 'On branch' always detects","status":"passed","title":"long-form git status with 'On branch' always detects","duration":0.181083000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - false positive risks"],"fullName":"PR #1175 - false positive risks generic app log with 'ERROR:' triggers buildOutput (potential false positive)","status":"passed","title":"generic app log with 'ERROR:' triggers buildOutput (potential false positive)","duration":0.7519999999999953,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - false positive risks"],"fullName":"PR #1175 - false positive risks generic 'Compiling templates' (non-build context) triggers buildOutput","status":"passed","title":"generic 'Compiling templates' (non-build context) triggers buildOutput","duration":0.24587499999999807,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - false positive risks"],"fullName":"PR #1175 - false positive risks plain text with no patterns falls through (no false positive)","status":"passed","title":"plain text with no patterns falls through (no false positive)","duration":0.14179200000000947,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - safety: no data corruption"],"fullName":"PR #1175 - safety: no data corruption empty input returns input","status":"passed","title":"empty input returns input","duration":0.10658399999999801,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - safety: no data corruption"],"fullName":"PR #1175 - safety: no data corruption input with only errors preserves all errors","status":"passed","title":"input with only errors preserves all errors","duration":0.062458000000006564,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - safety: no data corruption"],"fullName":"PR #1175 - safety: no data corruption input with no recognized patterns returns input (fallback)","status":"passed","title":"input with no recognized patterns returns input (fallback)","duration":0.046750000000002956,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - safety: no data corruption"],"fullName":"PR #1175 - safety: no data corruption limits warnings to 5 + summary line","status":"passed","title":"limits warnings to 5 + summary line","duration":0.08345800000000736,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954607,"endTime":1781341954613.2458,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/buildOutputFilter.test.js"},{"assertionResults":[{"ancestorTitles":["PR #1175 - priority with overlapping patterns"],"fullName":"PR #1175 - priority with overlapping patterns git-diff wins over buildOutput when both present","status":"passed","title":"git-diff wins over buildOutput when both present","duration":0.9039999999999964,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - priority with overlapping patterns"],"fullName":"PR #1175 - priority with overlapping patterns git-status (long form) wins over buildOutput","status":"passed","title":"git-status (long form) wins over buildOutput","duration":0.21708300000000236,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - DETECT_WINDOW boundary"],"fullName":"PR #1175 - DETECT_WINDOW boundary build pattern beyond DETECT_WINDOW chars: NOT detected","status":"passed","title":"build pattern beyond DETECT_WINDOW chars: NOT detected","duration":0.637999999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - DETECT_WINDOW boundary"],"fullName":"PR #1175 - DETECT_WINDOW boundary build pattern at very start: detected","status":"passed","title":"build pattern at very start: detected","duration":0.13683400000000745,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - line endings & whitespace"],"fullName":"PR #1175 - line endings & whitespace CRLF line endings still detect","status":"passed","title":"CRLF line endings still detect","duration":0.07237499999999386,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - line endings & whitespace"],"fullName":"PR #1175 - line endings & whitespace Tab-prefixed Compiling (real cargo output uses leading spaces, not tab)","status":"passed","title":"Tab-prefixed Compiling (real cargo output uses leading spaces, not tab)","duration":0.05783399999999972,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - line endings & whitespace"],"fullName":"PR #1175 - line endings & whitespace Compiling without leading spaces","status":"passed","title":"Compiling without leading spaces","duration":0.10770799999998815,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - adversarial: user code containing build strings"],"fullName":"PR #1175 - adversarial: user code containing build strings user JS code with console.log('npm warn ...') triggers buildOutput","status":"passed","title":"user JS code with console.log('npm warn ...') triggers buildOutput","duration":0.5646250000000066,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - adversarial: user code containing build strings"],"fullName":"PR #1175 - adversarial: user code containing build strings file content with 'BUILD SUCCESS' on its own line triggers buildOutput","status":"passed","title":"file content with 'BUILD SUCCESS' on its own line triggers buildOutput","duration":1.1124170000000078,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - adversarial: user code containing build strings"],"fullName":"PR #1175 - adversarial: user code containing build strings real cargo error spanning multiple lines preserves context","status":"passed","title":"real cargo error spanning multiple lines preserves context","duration":0.6519579999999934,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety input with only progress lines (no errors/warnings/summary) returns input fallback","status":"passed","title":"input with only progress lines (no errors/warnings/summary) returns input fallback","duration":0.6821249999999992,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety input with only Downloading lines","status":"passed","title":"input with only Downloading lines","duration":0.18079099999999926,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety input with ONLY a single ERROR: line","status":"passed","title":"input with ONLY a single ERROR: line","duration":0.12870800000000315,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety unicode/emoji in deprecation warning preserved (minimal fix keeps first 3 verbatim)","status":"passed","title":"unicode/emoji in deprecation warning preserved (minimal fix keeps first 3 verbatim)","duration":0.9698330000000084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety more than 3 deprecations: keep first 3 verbatim + count rest","status":"passed","title":"more than 3 deprecations: keep first 3 verbatim + count rest","duration":0.1322499999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety safeApply wraps buildOutput against panics","status":"passed","title":"safeApply wraps buildOutput against panics","duration":0.07620799999999406,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - integration with compressMessages"],"fullName":"PR #1175 - integration with compressMessages npm install output above MIN_COMPRESS_SIZE → compressed","status":"passed","title":"npm install output above MIN_COMPRESS_SIZE → compressed","duration":0.27745800000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - integration with compressMessages"],"fullName":"PR #1175 - integration with compressMessages input below MIN_COMPRESS_SIZE → NOT compressed","status":"passed","title":"input below MIN_COMPRESS_SIZE → NOT compressed","duration":0.06808300000000145,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - integration with compressMessages"],"fullName":"PR #1175 - integration with compressMessages compressed output never grows input (safety guard)","status":"passed","title":"compressed output never grows input (safety guard)","duration":0.07350000000000989,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - integration with compressMessages"],"fullName":"PR #1175 - integration with compressMessages tool_result with is_error:true is NOT compressed (preserve error traces)","status":"passed","title":"tool_result with is_error:true is NOT compressed (preserve error traces)","duration":0.12683299999999065,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regression deeper"],"fullName":"PR #1175 - porcelain regression deeper mixed staged + workdir + untracked porcelain → detected (has status code first char)","status":"passed","title":"mixed staged + workdir + untracked porcelain → detected (has status code first char)","duration":0.046916999999993436,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regression deeper"],"fullName":"PR #1175 - porcelain regression deeper 100% workdir-only porcelain → STILL detects gitStatus (minimal fix preserved old regex)","status":"passed","title":"100% workdir-only porcelain → STILL detects gitStatus (minimal fix preserved old regex)","duration":0.03754100000000449,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regression deeper"],"fullName":"PR #1175 - porcelain regression deeper manual gitStatus() call on workdir-only porcelain still parses correctly","status":"passed","title":"manual gitStatus() call on workdir-only porcelain still parses correctly","duration":0.18233399999999733,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - pathological"],"fullName":"PR #1175 - pathological very long single line (no newlines) with build pattern","status":"passed","title":"very long single line (no newlines) with build pattern","duration":0.05808399999999381,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - pathological"],"fullName":"PR #1175 - pathological 10000 Compiling lines don't crash","status":"passed","title":"10000 Compiling lines don't crash","duration":8.669416999999996,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - pathological"],"fullName":"PR #1175 - pathological input with only newlines","status":"passed","title":"input with only newlines","duration":0.10445799999999394,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - pathological"],"fullName":"PR #1175 - pathological null/undefined safety via safeApply","status":"passed","title":"null/undefined safety via safeApply","duration":0.31887499999999136,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954315,"endTime":1781341954332.3188,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/buildOutputFilterAdversarial.test.js"},{"assertionResults":[{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools suffixes client tool names and maps them back","status":"passed","title":"suffixes client tool names and maps them back","duration":0.9527080000000012,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools suffixes a forced tool_choice to match the renamed tool","status":"passed","title":"suffixes a forced tool_choice to match the renamed tool","duration":0.37870900000000063,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools suffixes only the chosen tool when several are present","status":"passed","title":"suffixes only the chosen tool when several are present","duration":0.22262499999999363,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools leaves non-forced tool_choice untouched","status":"passed","title":"leaves non-forced tool_choice untouched","duration":0.1737499999999983,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools does not suffix a forced choice that targets a non-client (decoy/built-in) tool","status":"passed","title":"does not suffix a forced choice that targets a non-client (decoy/built-in) tool","duration":0.07920800000000838,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools renames tool_use names in message history","status":"passed","title":"renames tool_use names in message history","duration":0.06791699999999423,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools returns the body unchanged when there are no tools","status":"passed","title":"returns the body unchanged when there are no tools","duration":0.1832080000000076,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954805,"endTime":1781341954807.183,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/claude-cloaking.test.js"},{"assertionResults":[{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache returns null before any headers are cached (cold start)","status":"passed","title":"returns null before any headers are cached (cold start)","duration":12.654708,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache caches headers when user-agent contains 'claude-code'","status":"passed","title":"caches headers when user-agent contains 'claude-code'","duration":1.0818340000000148,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache caches headers when user-agent contains 'claude-cli'","status":"passed","title":"caches headers when user-agent contains 'claude-cli'","duration":0.40508299999999053,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache caches headers when x-app is 'cli' (regardless of user-agent)","status":"passed","title":"caches headers when x-app is 'cli' (regardless of user-agent)","duration":0.4373329999999953,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache does NOT cache headers for non-Claude clients","status":"passed","title":"does NOT cache headers for non-Claude clients","duration":0.317292000000009,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache refreshes cache on each matching request","status":"passed","title":"refreshes cache on each matching request","duration":0.44520800000000804,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache ignores calls with null or non-object headers","status":"passed","title":"ignores calls with null or non-object headers","duration":0.4452500000000157,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache only stores keys that are actually present in the headers object","status":"passed","title":"only stores keys that are actually present in the headers object","duration":0.49358399999999847,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider overlays live cached headers over static provider defaults","status":"passed","title":"overlays live cached headers over static provider defaults","duration":88.14054100000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider removes conflicting Title-Case static keys when cached lowercase keys exist","status":"passed","title":"removes conflicting Title-Case static keys when cached lowercase keys exist","duration":1.5492920000000083,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider sets x-api-key auth when apiKey is provided","status":"passed","title":"sets x-api-key auth when apiKey is provided","duration":2.6088749999999834,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider sets Bearer Authorization when only accessToken is provided","status":"passed","title":"sets Bearer Authorization when only accessToken is provided","duration":1.2958749999999952,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider includes Accept: text/event-stream when stream=true","status":"passed","title":"includes Accept: text/event-stream when stream=true","duration":1.183917000000008,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider omits Accept: text/event-stream when stream=false","status":"passed","title":"omits Accept: text/event-stream when stream=false","duration":1.9054160000000024,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider cold start (no cache)"],"fullName":"DefaultExecutor.buildHeaders() — claude provider cold start (no cache) falls back to static provider headers when cache is empty","status":"passed","title":"falls back to static provider headers when cache is empty","duration":4.917624999999987,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider cold start (no cache)"],"fullName":"DefaultExecutor.buildHeaders() — claude provider cold start (no cache) does not throw when cache returns null","status":"passed","title":"does not throw when cache returns null","duration":1.159167000000025,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — anthropic-compatible stripping"],"fullName":"DefaultExecutor.buildHeaders() — anthropic-compatible stripping strips x-app and anthropic-dangerous-direct-browser-access for non-Anthropic host","status":"passed","title":"strips x-app and anthropic-dangerous-direct-browser-access for non-Anthropic host","duration":0.8272910000000024,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — anthropic-compatible stripping"],"fullName":"DefaultExecutor.buildHeaders() — anthropic-compatible stripping removes claude-code-20250219 from anthropic-beta for non-Anthropic host","status":"passed","title":"removes claude-code-20250219 from anthropic-beta for non-Anthropic host","duration":0.7397499999999582,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — anthropic-compatible stripping"],"fullName":"DefaultExecutor.buildHeaders() — anthropic-compatible stripping keeps other beta flags intact after stripping","status":"passed","title":"keeps other beta flags intact after stripping","duration":0.7302080000000046,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — anthropic-compatible stripping"],"fullName":"DefaultExecutor.buildHeaders() — anthropic-compatible stripping does NOT strip headers when baseUrl is api.anthropic.com","status":"passed","title":"does NOT strip headers when baseUrl is api.anthropic.com","duration":0.7953749999999786,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — anthropic-compatible stripping"],"fullName":"DefaultExecutor.buildHeaders() — anthropic-compatible stripping does NOT strip headers when baseUrl is empty (defaults to Anthropic)","status":"passed","title":"does NOT strip headers when baseUrl is empty (defaults to Anthropic)","duration":0.7852919999999699,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["proxyAwareFetch — api.anthropic.com routing"],"fullName":"proxyAwareFetch — api.anthropic.com routing routes api.anthropic.com to gotScraping (non-streaming) and returns ok response","status":"failed","title":"routes api.anthropic.com to gotScraping (non-streaming) and returns ok response","duration":1065.231041,"failureMessages":["AssertionError: expected \"vi.fn()\" to be called once, but got 0 times\n    at /Users/Working/router4/app/tests/unit/claude-header-forwarding.test.js:354:25\n    at processTicksAndRejections (node:internal/process/task_queues:105:5)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["proxyAwareFetch — api.anthropic.com routing"],"fullName":"proxyAwareFetch — api.anthropic.com routing falls back gracefully when got-scraping throws on non-streaming path","status":"passed","title":"falls back gracefully when got-scraping throws on non-streaming path","duration":4.496916999999939,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["proxyAwareFetch — api.anthropic.com routing"],"fullName":"proxyAwareFetch — api.anthropic.com routing does NOT route non-Anthropic hosts through gotScraping","status":"passed","title":"does NOT route non-Anthropic hosts through gotScraping","duration":4.849790999999868,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952497,"endTime":1781341953695.8499,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/claude-header-forwarding.test.js"},{"assertionResults":[{"ancestorTitles":["CodexExecutor image handling"],"fullName":"CodexExecutor image handling fetches 1MB remote image and inlines it as base64 data URI","status":"passed","title":"fetches 1MB remote image and inlines it as base64 data URI","duration":5.42908300000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["CodexExecutor image handling"],"fullName":"CodexExecutor image handling passes through existing data URIs without calling fetch","status":"passed","title":"passes through existing data URIs without calling fetch","duration":1.0504999999999995,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["CodexExecutor image handling"],"fullName":"CodexExecutor image handling falls back to original URL when remote fetch fails","status":"passed","title":"falls back to original URL when remote fetch fails","duration":0.7665409999999895,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["CodexExecutor image handling"],"fullName":"CodexExecutor image handling execute() prefetches images before sending to upstream","status":"passed","title":"execute() prefetches images before sending to upstream","duration":26.826583,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953660,"endTime":1781341953693.8267,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/codex-image-fetch.test.js"},{"assertionResults":[{"ancestorTitles":["Codex Refresh Token","refreshCodexToken"],"fullName":"Codex Refresh Token refreshCodexToken should return new refresh_token when server provides one (token rotation)","status":"passed","title":"should return new refresh_token when server provides one (token rotation)","duration":13.441666999999981,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","refreshCodexToken"],"fullName":"Codex Refresh Token refreshCodexToken should keep old refresh_token when server does not return new one","status":"passed","title":"should keep old refresh_token when server does not return new one","duration":1.8504580000000033,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","CodexExecutor credential lifecycle"],"fullName":"Codex Refresh Token CodexExecutor credential lifecycle should refresh Codex credentials and preserve omitted id_token","status":"passed","title":"should refresh Codex credentials and preserve omitted id_token","duration":30.283708999999988,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","CodexExecutor credential lifecycle"],"fullName":"Codex Refresh Token CodexExecutor credential lifecycle should refresh Codex when lastRefreshAt is older than the upstream stale window","status":"passed","title":"should refresh Codex when lastRefreshAt is older than the upstream stale window","duration":2.0495830000000126,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","CodexExecutor credential lifecycle"],"fullName":"Codex Refresh Token CodexExecutor credential lifecycle should de-duplicate concurrent refreshes for the same Codex connection","status":"passed","title":"should de-duplicate concurrent refreshes for the same Codex connection","duration":1.243832999999995,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","getRefreshLeadMs (early refresh config)"],"fullName":"Codex Refresh Token getRefreshLeadMs (early refresh config) should return provider-specific lead time for OAuth providers","status":"passed","title":"should return provider-specific lead time for OAuth providers","duration":1.8758339999999976,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","getRefreshLeadMs (early refresh config)"],"fullName":"Codex Refresh Token getRefreshLeadMs (early refresh config) should fallback to default buffer for unknown providers","status":"passed","title":"should fallback to default buffer for unknown providers","duration":4.077625000000012,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","getRefreshLeadMs (early refresh config)"],"fullName":"Codex Refresh Token getRefreshLeadMs (early refresh config) codex lead should be greater than default buffer","status":"passed","title":"codex lead should be greater than default buffer","duration":0.6485830000000021,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953293,"endTime":1781341953348.6487,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/codex-refresh-token.test.js"},{"assertionResults":[{"ancestorTitles":["combo round-robin routing"],"fullName":"combo round-robin routing keeps existing one-request round-robin behavior by default","status":"passed","title":"keeps existing one-request round-robin behavior by default","duration":1.6980420000000152,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["combo round-robin routing"],"fullName":"combo round-robin routing sticks to each combo model for the configured number of requests","status":"passed","title":"sticks to each combo model for the configured number of requests","duration":0.29670800000002373,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["combo round-robin routing"],"fullName":"combo round-robin routing tracks sticky rotation independently per combo","status":"passed","title":"tracks sticky rotation independently per combo","duration":0.21791699999999992,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["combo round-robin routing"],"fullName":"combo round-robin routing does not rotate fallback combos","status":"passed","title":"does not rotate fallback combos","duration":0.24245899999999665,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954939,"endTime":1781341954941.2424,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/combo-routing.test.js"},{"assertionResults":[{"ancestorTitles":["commandcode-to-openai — text-delta"],"fullName":"commandcode-to-openai — text-delta emits assistant role on first delta then content-only","status":"passed","title":"emits assistant role on first delta then content-only","duration":1.4774160000000052,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — reasoning-delta"],"fullName":"commandcode-to-openai — reasoning-delta maps reasoning-delta to reasoning_content delta","status":"passed","title":"maps reasoning-delta to reasoning_content delta","duration":0.19649999999998613,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — tool-input-* with id field (live schema)"],"fullName":"commandcode-to-openai — tool-input-* with id field (live schema) registers tool index using event.id (NOT toolCallId)","status":"passed","title":"registers tool index using event.id (NOT toolCallId)","duration":0.2172079999999994,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — tool-input-* with id field (live schema)"],"fullName":"commandcode-to-openai — tool-input-* with id field (live schema) ignores tool-input-delta when id is unknown (no prior start)","status":"passed","title":"ignores tool-input-delta when id is unknown (no prior start)","duration":0.08549999999999613,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — final tool-call event"],"fullName":"commandcode-to-openai — final tool-call event does NOT re-emit tool_calls when tool-input-* deltas already fired","status":"passed","title":"does NOT re-emit tool_calls when tool-input-* deltas already fired","duration":0.219916000000012,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — final tool-call event"],"fullName":"commandcode-to-openai — final tool-call event emits a consolidated tool_calls when only the final tool-call event arrives","status":"passed","title":"emits a consolidated tool_calls when only the final tool-call event arrives","duration":0.1807500000000175,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — finish"],"fullName":"commandcode-to-openai — finish emits a final chunk with finish_reason=tool_calls when finishReason is tool-calls","status":"passed","title":"emits a final chunk with finish_reason=tool_calls when finishReason is tool-calls","duration":0.1650419999999997,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — finish"],"fullName":"commandcode-to-openai — finish includes usage on the final chunk when totalUsage provided","status":"passed","title":"includes usage on the final chunk when totalUsage provided","duration":0.3331670000000031,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — error event"],"fullName":"commandcode-to-openai — error event stringifies object errors so client sees readable message","status":"passed","title":"stringifies object errors so client sees readable message","duration":0.46983400000002007,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954746,"endTime":1781341954749.4697,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/commandcode-to-openai.test.js"},{"assertionResults":[{"ancestorTitles":["compatible provider connections API"],"fullName":"compatible provider connections API creates one API-key connection for an OpenAI-compatible node","status":"passed","title":"creates one API-key connection for an OpenAI-compatible node","duration":198.799416,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["compatible provider connections API"],"fullName":"compatible provider connections API creates one API-key connection for an Anthropic-compatible node","status":"passed","title":"creates one API-key connection for an Anthropic-compatible node","duration":10.574166999999989,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["compatible provider connections API"],"fullName":"compatible provider connections API returns 400 for a duplicate connection on the same compatible node","status":"passed","title":"returns 400 for a duplicate connection on the same compatible node","duration":8.184416999999996,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952824,"endTime":1781341953041.1843,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/compatible-provider-connections.test.js"},{"assertionResults":[{"ancestorTitles":["CursorExecutor Composer thinking-field responses"],"fullName":"CursorExecutor Composer thinking-field responses uses visible content after </think> for non-streaming Composer responses","status":"passed","title":"uses visible content after </think> for non-streaming Composer responses","duration":9.042958999999996,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["CursorExecutor Composer thinking-field responses"],"fullName":"CursorExecutor Composer thinking-field responses streams only visible content after </think> for Composer responses","status":"passed","title":"streams only visible content after </think> for Composer responses","duration":0.9584999999999866,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["CursorExecutor Composer thinking-field responses"],"fullName":"CursorExecutor Composer thinking-field responses does not treat thinking as visible output for non-Composer models","status":"passed","title":"does not treat thinking as visible output for non-Composer models","duration":0.29512500000001296,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954501,"endTime":1781341954511.2952,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/cursor-composer-thinking.test.js"},{"assertionResults":[{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access allows loopback public LLM API without API key","status":"passed","title":"allows loopback public LLM API without API key","duration":13.260957999999988,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access rejects remote rewritten public LLM API without API key","status":"passed","title":"rejects remote rewritten public LLM API without API key","duration":0.4267080000000192,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access allows loopback rewritten public LLM API without API key","status":"passed","title":"allows loopback rewritten public LLM API without API key","duration":0.22408300000000736,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access rejects remote beta public LLM API without API key","status":"passed","title":"rejects remote beta public LLM API without API key","duration":0.23858400000000302,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access rejects remote rewritten beta public LLM API without API key","status":"passed","title":"rejects remote rewritten beta public LLM API without API key","duration":0.3176250000000209,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access allows remote public LLM API with valid bearer API key","status":"passed","title":"allows remote public LLM API with valid bearer API key","duration":0.7532500000000084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access allows remote public LLM API with valid x-api-key","status":"passed","title":"allows remote public LLM API with valid x-api-key","duration":0.3491249999999866,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access allows remote rewritten beta public LLM API with valid API key","status":"passed","title":"allows remote rewritten beta public LLM API with valid API key","duration":0.1612920000000031,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access rejects local-only route from non-loopback host without CLI token","status":"passed","title":"rejects local-only route from non-loopback host without CLI token","duration":0.40200000000001523,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access rejects local-only route on loopback when requireLogin=true and no JWT","status":"passed","title":"rejects local-only route on loopback when requireLogin=true and no JWT","duration":0.7724589999999978,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access allows local-only route on loopback when requireLogin=false","status":"passed","title":"allows local-only route on loopback when requireLogin=false","duration":0.2912080000000117,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access rejects local-only route from tunnel host even when requireLogin=false","status":"passed","title":"rejects local-only route from tunnel host even when requireLogin=false","duration":0.09441699999999287,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access rejects local-only route when Origin is non-loopback (CSRF block)","status":"passed","title":"rejects local-only route when Origin is non-loopback (CSRF block)","duration":0.08262500000000728,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access allows local-only route with valid CLI token","status":"passed","title":"allows local-only route with valid CLI token","duration":0.08770799999999213,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard helpers"],"fullName":"dashboard guard helpers extracts bearer API keys before x-api-key","status":"passed","title":"extracts bearer API keys before x-api-key","duration":0.06624999999999659,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954370,"endTime":1781341954388.0945,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/dashboard-guard.test.js"},{"assertionResults":[{"ancestorTitles":["DB Benchmark — SQLite vs Lowdb"],"fullName":"DB Benchmark — SQLite vs Lowdb INSERT 500 provider connections","status":"passed","title":"INSERT 500 provider connections","duration":1690.8371670000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Benchmark — SQLite vs Lowdb"],"fullName":"DB Benchmark — SQLite vs Lowdb READ 200 filtered queries","status":"passed","title":"READ 200 filtered queries","duration":619.4072079999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Benchmark — SQLite vs Lowdb"],"fullName":"DB Benchmark — SQLite vs Lowdb READ 200 by id (point lookup)","status":"passed","title":"READ 200 by id (point lookup)","duration":278.94766700000037,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Benchmark — SQLite vs Lowdb"],"fullName":"DB Benchmark — SQLite vs Lowdb saveRequestUsage 500 entries","status":"passed","title":"saveRequestUsage 500 entries","duration":1034.224334,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Benchmark — SQLite vs Lowdb"],"fullName":"DB Benchmark — SQLite vs Lowdb getUsageStats(24h) repeat 50x","status":"passed","title":"getUsageStats(24h) repeat 50x","duration":548.2327909999999,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952897,"endTime":1781341957069.233,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/db-benchmark.test.js"},{"assertionResults":[{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety 100 parallel saveRequestUsage → no count loss","status":"passed","title":"100 parallel saveRequestUsage → no count loss","duration":46.75924999999995,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety 200 parallel saveRequestDetail → all flushed","status":"passed","title":"200 parallel saveRequestDetail → all flushed","duration":6007.633709,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety mixed concurrent: usage + details + connections + aliases","status":"passed","title":"mixed concurrent: usage + details + connections + aliases","duration":36.467749999999796,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety updateSettings parallel → no merge loss","status":"passed","title":"updateSettings parallel → no merge loss","duration":3.7337079999997513,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety OAuth refresh race: parallel updateProviderConnection on same id","status":"passed","title":"OAuth refresh race: parallel updateProviderConnection on same id","duration":3.074166000000332,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety addCustomModel race: parallel duplicate adds → only 1 inserted","status":"passed","title":"addCustomModel race: parallel duplicate adds → only 1 inserted","duration":0.7979590000004464,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety updatePricing race: parallel adds different models → all merged","status":"passed","title":"updatePricing race: parallel adds different models → all merged","duration":3.21191699999963,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety daily summary aggregates correctly under parallel writes","status":"passed","title":"daily summary aggregates correctly under parallel writes","duration":11.900625000000218,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952891,"endTime":1781341959005.9006,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/db-concurrent.test.js"},{"assertionResults":[{"ancestorTitles":["Driver fallback chain"],"fullName":"Driver fallback chain default → picks better-sqlite3 when available","status":"passed","title":"default → picks better-sqlite3 when available","duration":66.51825000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Driver fallback chain"],"fullName":"Driver fallback chain falls back to node:sqlite when better-sqlite3 unavailable","status":"passed","title":"falls back to node:sqlite when better-sqlite3 unavailable","duration":36.785583,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Driver fallback chain"],"fullName":"Driver fallback chain falls back to sql.js when both native drivers unavailable","status":"passed","title":"falls back to sql.js when both native drivers unavailable","duration":68.19970799999999,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952828,"endTime":1781341952999.1997,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/db-driver-chain.test.js"},{"assertionResults":[{"ancestorTitles":["Schema migrations"],"fullName":"Schema migrations fresh DB → applies migrations & stamps schemaVersion","status":"passed","title":"fresh DB → applies migrations & stamps schemaVersion","duration":42.585083999999995,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Schema migrations"],"fullName":"Schema migrations existing DB at older schemaVersion → re-applies pending migrations on restart","status":"passed","title":"existing DB at older schemaVersion → re-applies pending migrations on restart","duration":18.36904100000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Schema migrations"],"fullName":"Schema migrations fresh DB + legacy db.json → imports data automatically","status":"passed","title":"fresh DB + legacy db.json → imports data automatically","duration":13.941790999999995,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Schema migrations"],"fullName":"Schema migrations auto-sync re-creates missing index when DB lacks it","status":"passed","title":"auto-sync re-creates missing index when DB lacks it","duration":11.89700000000002,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953154,"endTime":1781341953240.897,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/db-migration-chain.test.js"},{"assertionResults":[{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity settings: get → defaults; update → merge","status":"passed","title":"settings: get → defaults; update → merge","duration":1.3935839999999757,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity isCloudEnabled reflects settings","status":"passed","title":"isCloudEnabled reflects settings","duration":0.5900420000000111,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity apiKeys: create/get/validate/delete","status":"passed","title":"apiKeys: create/get/validate/delete","duration":6.596916999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity providerConnections: CRUD + reorder by priority","status":"passed","title":"providerConnections: CRUD + reorder by priority","duration":2.4412920000000042,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity providerConnections: optional fields persisted via JSON column","status":"passed","title":"providerConnections: optional fields persisted via JSON column","duration":0.7281250000000057,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity providerNodes: CRUD","status":"passed","title":"providerNodes: CRUD","duration":0.569833999999986,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity proxyPools: CRUD with sort by updatedAt desc","status":"passed","title":"proxyPools: CRUD with sort by updatedAt desc","duration":10.562999999999988,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity combos: CRUD","status":"passed","title":"combos: CRUD","duration":0.882125000000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity modelAliases: KV ops","status":"passed","title":"modelAliases: KV ops","duration":1.3499999999999943,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity customModels: add/list/delete with dedupe","status":"passed","title":"customModels: add/list/delete with dedupe","duration":1.154042000000004,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity mitmAlias: get/set per tool","status":"passed","title":"mitmAlias: get/set per tool","duration":0.4252079999999978,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity disabledModels: add/remove per provider","status":"passed","title":"disabledModels: add/remove per provider","duration":0.7045410000000061,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity usage: saveRequestUsage + getUsageHistory + getUsageStats","status":"passed","title":"usage: saveRequestUsage + getUsageHistory + getUsageStats","duration":6.1316670000000215,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity usage: pending tracking in-memory","status":"passed","title":"usage: pending tracking in-memory","duration":16.56729200000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity requestDetails: save → query with paging","status":"passed","title":"requestDetails: save → query with paging","duration":202.84779200000003,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity exportDb / importDb roundtrip","status":"passed","title":"exportDb / importDb roundtrip","duration":1.6865829999999846,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity pricing: user pricing merged with constants","status":"passed","title":"pricing: user pricing merged with constants","duration":0.5601249999999709,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity getChartData: 24h buckets","status":"passed","title":"getChartData: 24h buckets","duration":1.2631660000000124,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity getChartData: 7d buckets","status":"passed","title":"getChartData: 7d buckets","duration":0.43641700000000583,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952891,"endTime":1781341953148.4365,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/db-sqlite-vs-lowdb.test.js"},{"assertionResults":[],"startTime":1781341952244,"endTime":1781341952244,"status":"failed","message":"Cannot find module '/cloud/src/handlers/embeddings.js' imported from /Users/Working/router4/app/tests/unit/embeddings.cloud.test.js","name":"/Users/Working/router4/app/tests/unit/embeddings.cloud.test.js"},{"assertionResults":[{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody single string input — includes model and input, default encoding_format=float","status":"passed","title":"single string input — includes model and input, default encoding_format=float","duration":16.239874999999984,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody array input — passes array as-is","status":"passed","title":"array input — passes array as-is","duration":0.9856659999999806,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody custom encoding_format is forwarded","status":"passed","title":"custom encoding_format is forwarded","duration":0.7023749999999893,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody no encoding_format in body → defaults to float","status":"passed","title":"no encoding_format in body → defaults to float","duration":0.7042499999999734,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody gemini single input forwards dimensions as outputDimensionality","status":"passed","title":"gemini single input forwards dimensions as outputDimensionality","duration":0.9064580000000149,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody gemini batch input forwards dimensions on each request","status":"passed","title":"gemini batch input forwards dimensions on each request","duration":1.32891699999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl openai → https://api.openai.com/v1/embeddings","status":"passed","title":"openai → https://api.openai.com/v1/embeddings","duration":1.12175000000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl openrouter → https://openrouter.ai/api/v1/embeddings","status":"passed","title":"openrouter → https://openrouter.ai/api/v1/embeddings","duration":0.8117080000000101,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl vercel-ai-gateway → https://ai-gateway.vercel.sh/v1/embeddings","status":"passed","title":"vercel-ai-gateway → https://ai-gateway.vercel.sh/v1/embeddings","duration":3.307707999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl openai-compatible-* → uses baseUrl from providerSpecificData","status":"passed","title":"openai-compatible-* → uses baseUrl from providerSpecificData","duration":0.5133339999999862,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl openai-compatible-* strips trailing slash from baseUrl","status":"passed","title":"openai-compatible-* strips trailing slash from baseUrl","duration":0.35904100000001904,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl openai-compatible-* without baseUrl → falls back to api.openai.com","status":"passed","title":"openai-compatible-* without baseUrl → falls back to api.openai.com","duration":0.25020799999998644,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl unsupported provider (e.g. gemini-cli) → 400 error, no fetch called","status":"passed","title":"unsupported provider (e.g. gemini-cli) → 400 error, no fetch called","duration":0.7671670000000006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl antigravity (non-openai-compatible, no URL mapping) → 400","status":"passed","title":"antigravity (non-openai-compatible, no URL mapping) → 400","duration":0.4965830000000153,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsHeaders"],"fullName":"buildEmbeddingsHeaders openai → Authorization: Bearer, Content-Type: application/json","status":"passed","title":"openai → Authorization: Bearer, Content-Type: application/json","duration":0.42295899999999165,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsHeaders"],"fullName":"buildEmbeddingsHeaders openai — uses accessToken when apiKey is absent","status":"passed","title":"openai — uses accessToken when apiKey is absent","duration":1.280333000000013,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsHeaders"],"fullName":"buildEmbeddingsHeaders openrouter → adds HTTP-Referer and X-Title headers","status":"passed","title":"openrouter → adds HTTP-Referer and X-Title headers","duration":0.3557079999999928,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsHeaders"],"fullName":"buildEmbeddingsHeaders openai-compatible-* → Authorization: Bearer only (no extra headers)","status":"passed","title":"openai-compatible-* → Authorization: Bearer only (no extra headers)","duration":0.26295899999999506,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation missing input → 400 Bad Request","status":"passed","title":"missing input → 400 Bad Request","duration":0.22229199999998173,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation input is a number → 400 Bad Request","status":"passed","title":"input is a number → 400 Bad Request","duration":0.15945800000000077,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation input is an object → 400 Bad Request","status":"passed","title":"input is an object → 400 Bad Request","duration":0.17754199999998832,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation input is null → 400 Bad Request","status":"passed","title":"input is null → 400 Bad Request","duration":0.1240839999999821,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation empty string input passes validation","status":"passed","title":"empty string input passes validation","duration":0.18662499999999227,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation empty array input passes validation and reaches provider","status":"passed","title":"empty array input passes validation and reaches provider","duration":0.21987500000000182,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path returns success=true with Response on 200","status":"passed","title":"returns success=true with Response on 200","duration":0.271458999999993,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path response body is valid OpenAI-format JSON","status":"passed","title":"response body is valid OpenAI-format JSON","duration":0.3058340000000044,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path response includes CORS header Access-Control-Allow-Origin: *","status":"passed","title":"response includes CORS header Access-Control-Allow-Origin: *","duration":0.22829200000001038,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path response Content-Type is application/json","status":"passed","title":"response Content-Type is application/json","duration":0.259208000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path calls onRequestSuccess callback on success","status":"passed","title":"calls onRequestSuccess callback on success","duration":0.19941599999998516,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path does not call onRequestSuccess on provider error","status":"passed","title":"does not call onRequestSuccess on provider error","duration":0.2992500000000007,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path provider response with non-standard format is passed through as-is","status":"passed","title":"provider response with non-standard format is passed through as-is","duration":0.2692909999999813,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling provider 400 → returns success=false with status 400","status":"passed","title":"provider 400 → returns success=false with status 400","duration":1.9310409999999933,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling provider 429 → returns success=false with status 429","status":"passed","title":"provider 429 → returns success=false with status 429","duration":0.5789589999999976,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling provider 500 → returns success=false with status 500","status":"passed","title":"provider 500 → returns success=false with status 500","duration":0.25370799999998894,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling network error (fetch throws) → returns 502 Bad Gateway","status":"passed","title":"network error (fetch throws) → returns 502 Bad Gateway","duration":0.2712089999999989,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling invalid JSON from provider → returns 502","status":"passed","title":"invalid JSON from provider → returns 502","duration":0.22912500000001046,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling error result response has OpenAI-format error body","status":"passed","title":"error result response has OpenAI-format error body","duration":0.23895799999999667,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — token refresh on 401/403"],"fullName":"handleEmbeddingsCore — token refresh on 401/403 on 401, attempts retry after refresh; succeeds if refresh gives new token","status":"passed","title":"on 401, attempts retry after refresh; succeeds if refresh gives new token","duration":0.8112920000000088,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — token refresh on 401/403"],"fullName":"handleEmbeddingsCore — token refresh on 401/403 on 401 with no refresh token, falls back gracefully (no crash)","status":"passed","title":"on 401 with no refresh token, falls back gracefully (no crash)","duration":0.8482079999999996,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953606,"endTime":1781341953646.8481,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/embeddingsCore.test.js"},{"assertionResults":[{"ancestorTitles":["Gemini CLI usage project id resolution"],"fullName":"Gemini CLI usage project id resolution uses the projectId stored on the provider connection","status":"passed","title":"uses the projectId stored on the provider connection","duration":16.085374999999985,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Gemini CLI usage project id resolution"],"fullName":"Gemini CLI usage project id resolution normalizes project objects returned by loadCodeAssist","status":"passed","title":"normalizes project objects returned by loadCodeAssist","duration":1.0467910000000131,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Gemini CLI usage project id resolution"],"fullName":"Gemini CLI usage project id resolution returns actionable guidance when no project id is available","status":"passed","title":"returns actionable guidance when no project id is available","duration":0.3514590000000055,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954207,"endTime":1781341954224.3516,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/gemini-usage-projectid.test.js"},{"assertionResults":[{"ancestorTitles":["GithubExecutor.supportsResponsesEndpoint"],"fullName":"GithubExecutor.supportsResponsesEndpoint excludes Gemini models from the /responses endpoint","status":"passed","title":"excludes Gemini models from the /responses endpoint","duration":1.009541000000013,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GithubExecutor.supportsResponsesEndpoint"],"fullName":"GithubExecutor.supportsResponsesEndpoint excludes Claude models from the /responses endpoint","status":"passed","title":"excludes Claude models from the /responses endpoint","duration":0.1779160000000104,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GithubExecutor.supportsResponsesEndpoint"],"fullName":"GithubExecutor.supportsResponsesEndpoint allows OpenAI/codex models on the /responses endpoint","status":"passed","title":"allows OpenAI/codex models on the /responses endpoint","duration":0.10524999999998386,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GithubExecutor.supportsResponsesEndpoint"],"fullName":"GithubExecutor.supportsResponsesEndpoint is null-safe","status":"passed","title":"is null-safe","duration":0.4898330000000044,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GithubExecutor.execute cached-route guard (#1062)"],"fullName":"GithubExecutor.execute cached-route guard (#1062) does NOT use /responses for a Gemini model even if it was wrongly cached as codex","status":"passed","title":"does NOT use /responses for a Gemini model even if it was wrongly cached as codex","duration":1.2818340000000035,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954940,"endTime":1781341954943.2817,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/github-responses-routing.test.js"},{"assertionResults":[{"ancestorTitles":["HuggingFace model alias parsing"],"fullName":"HuggingFace model alias parsing resolves hf alias to huggingface provider","status":"passed","title":"resolves hf alias to huggingface provider","duration":1.1979169999999897,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341955037,"endTime":1781341955038.198,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/hf-model-routing.test.js"},{"assertionResults":[{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore validates required prompt field","status":"passed","title":"validates required prompt field","duration":14.353999999999985,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore rejects unsupported provider","status":"passed","title":"rejects unsupported provider","duration":0.882458999999983,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with OpenAI format","status":"passed","title":"generates image with OpenAI format","duration":4.473292000000015,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with Gemini format","status":"passed","title":"generates image with Gemini format","duration":0.7167499999999905,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with Minimax format","status":"passed","title":"generates image with Minimax format","duration":0.4477089999999748,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with NanoBanana format","status":"passed","title":"generates image with NanoBanana format","duration":2.06820799999997,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with SD WebUI format","status":"passed","title":"generates image with SD WebUI format","duration":0.8669160000000034,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore handles OpenRouter with HTTP-Referer header","status":"passed","title":"handles OpenRouter with HTTP-Referer header","duration":0.320541999999989,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore handles Vercel AI Gateway image generation as OpenAI-compatible","status":"passed","title":"handles Vercel AI Gateway image generation as OpenAI-compatible","duration":0.62175000000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore handles HuggingFace binary response","status":"passed","title":"handles HuggingFace binary response","duration":0.6194169999999986,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with Codex gpt-5.5-image using current Codex version header","status":"passed","title":"generates image with Codex gpt-5.5-image using current Codex version header","duration":0.9074170000000095,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with Cloudflare Workers AI JSON response","status":"passed","title":"generates image with Cloudflare Workers AI JSON response","duration":0.9313339999999926,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore uses multipart form data for Cloudflare FLUX.2 models","status":"passed","title":"uses multipart form data for Cloudflare FLUX.2 models","duration":0.8183750000000032,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore resolves Cloudflare img2img and inpainting URL inputs before sending","status":"passed","title":"resolves Cloudflare img2img and inpainting URL inputs before sending","duration":0.5497500000000173,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore handles provider error responses","status":"passed","title":"handles provider error responses","duration":0.2682500000000232,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore handles network errors","status":"passed","title":"handles network errors","duration":0.28875000000005,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore calls onRequestSuccess callback on success","status":"passed","title":"calls onRequestSuccess callback on success","duration":0.17154099999999062,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954278,"endTime":1781341954307.2888,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/image-generation.test.js"},{"assertionResults":[{"ancestorTitles":["Kiro MITM model slots"],"fullName":"Kiro MITM model slots exposes the kiro mitm tool","status":"passed","title":"exposes the kiro mitm tool","duration":0.8715840000000128,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro MITM model slots"],"fullName":"Kiro MITM model slots offers a mappable slot for the agent default model id 'auto'","status":"failed","title":"offers a mappable slot for the agent default model id 'auto'","duration":3.0175839999999994,"failureMessages":["AssertionError: expected undefined to be truthy\n    at /Users/Working/router4/app/tests/unit/kiro-model-slots.test.js:21:18\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["Kiro MITM model slots"],"fullName":"Kiro MITM model slots offers a mappable slot for the background sub-task model id 'simple-task'","status":"passed","title":"offers a mappable slot for the background sub-task model id 'simple-task'","duration":0.13508300000000872,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952509,"endTime":1781341952513.135,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/kiro-model-slots.test.js"},{"assertionResults":[{"ancestorTitles":["generateSessionId"],"fullName":"generateSessionId uses the ses_ prefix and a 24-char random suffix","status":"passed","title":"uses the ses_ prefix and a 24-char random suffix","duration":0.9750830000000121,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generateSessionId"],"fullName":"generateSessionId only emits lowercase alphanumeric characters in the suffix","status":"passed","title":"only emits lowercase alphanumeric characters in the suffix","duration":0.20624999999998295,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generateSessionId"],"fullName":"generateSessionId produces a fresh id on each call","status":"passed","title":"produces a fresh id on each call","duration":0.39204200000000355,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generateFingerprint"],"fullName":"generateFingerprint returns a 64-char hex sha256 digest","status":"passed","title":"returns a 64-char hex sha256 digest","duration":2.1698330000000112,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generateFingerprint"],"fullName":"generateFingerprint is stable per machine (deterministic across calls)","status":"passed","title":"is stable per machine (deterministic across calls)","duration":0.5714169999999967,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseJwtExp"],"fullName":"parseJwtExp derives the expiry from the JWT exp claim (ms)","status":"passed","title":"derives the expiry from the JWT exp claim (ms)","duration":0.18404200000000515,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseJwtExp"],"fullName":"parseJwtExp falls back to a future timestamp when the JWT is unparseable","status":"passed","title":"falls back to a future timestamp when the JWT is unparseable","duration":0.20987500000001091,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectSystemMarker"],"fullName":"injectSystemMarker prepends a system message with the marker when none is present","status":"passed","title":"prepends a system message with the marker when none is present","duration":0.20812499999999545,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectSystemMarker"],"fullName":"injectSystemMarker preserves the original user message after injection","status":"passed","title":"preserves the original user message after injection","duration":0.3542500000000075,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectSystemMarker"],"fullName":"injectSystemMarker keeps a caller-provided system prompt alongside the marker","status":"passed","title":"keeps a caller-provided system prompt alongside the marker","duration":0.12437499999998636,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectSystemMarker"],"fullName":"injectSystemMarker does not duplicate the marker when already present","status":"passed","title":"does not duplicate the marker when already present","duration":0.16825000000000045,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectSystemMarker"],"fullName":"injectSystemMarker leaves a body without a messages array untouched","status":"passed","title":"leaves a body without a messages array untouched","duration":0.05441600000000335,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt returns the jwt from the bootstrap response","status":"passed","title":"returns the jwt from the bootstrap response","duration":0.33950000000001523,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt sends the machine fingerprint as the bootstrap client","status":"passed","title":"sends the machine fingerprint as the bootstrap client","duration":0.2028750000000059,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt caches the jwt and does not re-fetch while still valid","status":"passed","title":"caches the jwt and does not re-fetch while still valid","duration":0.10479200000000333,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt re-fetches once the cached jwt is within the expiry buffer","status":"passed","title":"re-fetches once the cached jwt is within the expiry buffer","duration":0.25158300000001077,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt throws when the bootstrap response is not ok","status":"passed","title":"throws when the bootstrap response is not ok","duration":1.5023330000000215,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt throws when the bootstrap response has no jwt","status":"passed","title":"throws when the bootstrap response has no jwt","duration":0.4447499999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MimoFreeExecutor"],"fullName":"MimoFreeExecutor buildUrl returns the free-ai chat endpoint","status":"passed","title":"buildUrl returns the free-ai chat endpoint","duration":0.17679200000000606,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MimoFreeExecutor"],"fullName":"MimoFreeExecutor buildHeaders includes the MiMo source and session affinity","status":"passed","title":"buildHeaders includes the MiMo source and session affinity","duration":0.2583750000000009,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MimoFreeExecutor"],"fullName":"MimoFreeExecutor transformRequest injects the system marker","status":"passed","title":"transformRequest injects the system marker","duration":0.11554200000000492,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MimoFreeExecutor"],"fullName":"MimoFreeExecutor execute injects the marker and sends a Bearer JWT to the chat endpoint","status":"passed","title":"execute injects the marker and sends a Bearer JWT to the chat endpoint","duration":0.618124999999992,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MimoFreeExecutor"],"fullName":"MimoFreeExecutor re-bootstraps and retries once on a 403 from the chat endpoint","status":"passed","title":"re-bootstraps and retries once on a 403 from the chat endpoint","duration":0.8465419999999995,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiMo Free provider registration"],"fullName":"MiMo Free provider registration registers a specialized executor for mimo-free and the mmf alias","status":"passed","title":"registers a specialized executor for mimo-free and the mmf alias","duration":0.5119159999999852,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiMo Free provider registration"],"fullName":"MiMo Free provider registration registers mimo-free as a no-auth provider in open-sse config","status":"passed","title":"registers mimo-free as a no-auth provider in open-sse config","duration":0.16345799999999144,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiMo Free provider registration"],"fullName":"MiMo Free provider registration exposes only mimo-auto (the sole free-channel model)","status":"passed","title":"exposes only mimo-auto (the sole free-channel model)","duration":0.2980000000000018,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiMo Free provider registration"],"fullName":"MiMo Free provider registration maps the mimo-free alias to mmf","status":"passed","title":"maps the mimo-free alias to mmf","duration":0.11191700000000537,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiMo Free provider registration"],"fullName":"MiMo Free provider registration lists mimo-free in the dashboard FREE_PROVIDERS catalog","status":"passed","title":"lists mimo-free in the dashboard FREE_PROVIDERS catalog","duration":0.139458999999988,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954567,"endTime":1781341954580.1394,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/mimo-free.test.js"},{"assertionResults":[{"ancestorTitles":["MiniMax TTS"],"fullName":"MiniMax TTS sends MiniMax T2A payload and converts hex audio to base64 JSON","status":"passed","title":"sends MiniMax T2A payload and converts hex audio to base64 JSON","duration":22.590417000000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax TTS"],"fullName":"MiniMax TTS uses the default MiniMax voice when no voice is provided","status":"passed","title":"uses the default MiniMax voice when no voice is provided","duration":0.8071659999999952,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax TTS"],"fullName":"MiniMax TTS surfaces MiniMax base_resp errors","status":"passed","title":"surfaces MiniMax base_resp errors","duration":0.957000000000022,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953780,"endTime":1781341953804.957,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/minimax-tts.test.js"},{"assertionResults":[{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage parses token-plan TTS quota counts as used counts","status":"passed","title":"parses token-plan TTS quota counts as used counts","duration":24.569999999999993,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage parses coding-plan TTS quota counts as remaining counts","status":"passed","title":"parses coding-plan TTS quota counts as remaining counts","duration":0.731250000000017,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage keeps non-TTS MiniMax quota rows instead of filtering to text only","status":"passed","title":"keeps non-TTS MiniMax quota rows instead of filtering to text only","duration":0.8622079999999812,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage includes M-series percent-only buckets that have no count totals","status":"passed","title":"includes M-series percent-only buckets that have no count totals","duration":1.1722500000000196,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage normalizes M-series percent-only buckets on the coding_plan (countMeansRemaining) endpoint too","status":"passed","title":"normalizes M-series percent-only buckets on the coding_plan (countMeansRemaining) endpoint too","duration":0.8429580000000101,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage renders the M3-era MiniMax-M* wildcard as a friendly series label","status":"passed","title":"renders the M3-era MiniMax-M* wildcard as a friendly series label","duration":0.5390830000000051,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage prefers the upstream-provided remaining percent when counts are also present","status":"passed","title":"prefers the upstream-provided remaining percent when counts are also present","duration":0.2755830000000117,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954150,"endTime":1781341954179.2756,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/minimax-usage.test.js"},{"assertionResults":[{"ancestorTitles":["MiniMax voices API"],"fullName":"MiniMax voices API fetches global MiniMax voices with stored API key","status":"passed","title":"fetches global MiniMax voices with stored API key","duration":13.813832999999988,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax voices API"],"fullName":"MiniMax voices API fetches China MiniMax voices when provider=minimax-cn","status":"passed","title":"fetches China MiniMax voices when provider=minimax-cn","duration":1.227833000000004,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954298,"endTime":1781341954313.2278,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/minimax-voices.test.js"},{"assertionResults":[{"ancestorTitles":["model test route kind routing"],"fullName":"model test route kind routing routes image model tests to /api/v1/images/generations","status":"passed","title":"routes image model tests to /api/v1/images/generations","duration":50.23533300000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model test route kind routing"],"fullName":"model test route kind routing routes embedding model tests to /api/v1/embeddings","status":"passed","title":"routes embedding model tests to /api/v1/embeddings","duration":1.1932079999999985,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model test route kind routing"],"fullName":"model test route kind routing fails embedding model tests when provider returns no embedding data","status":"passed","title":"fails embedding model tests when provider returns no embedding data","duration":1.2713750000000061,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model test route kind routing"],"fullName":"model test route kind routing routes stt model tests to /api/v1/audio/transcriptions","status":"passed","title":"routes stt model tests to /api/v1/audio/transcriptions","duration":1.1822090000000003,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model test route kind routing"],"fullName":"model test route kind routing returns formatted HTTP errors for non-2xx embedding responses","status":"passed","title":"returns formatted HTTP errors for non-2xx embedding responses","duration":0.48833300000001145,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953330,"endTime":1781341953384.4883,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/model-test-routing.test.js"},{"assertionResults":[{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import returns not-found when no macOS cursor db paths are accessible","status":"failed","title":"returns not-found when no macOS cursor db paths are accessible","duration":23.516999999999996,"failureMessages":["AssertionError: expected 'Cursor database not found. Checked lo…' to contain 'Cursor database not found in known ma…'\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:74:33\n    at processTicksAndRejections (node:internal/process/task_queues:105:5)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import returns descriptive error if macOS db file exists but cannot be opened","status":"failed","title":"returns descriptive error if macOS db file exists but cannot be opened","duration":46.532667000000004,"failureMessages":["AssertionError: the given combination of arguments (undefined and string) is invalid for this assertion. You can use an array, a map, an object, a set, a string, or a weakset instead of a string\n    at Proxy.<anonymous> (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/expect/dist/index.js:1319:15)\n    at Proxy.<anonymous> (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/expect/dist/index.js:1156:15)\n    at Proxy.methodWrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/chai/index.js:1700:25)\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:84:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import extracts tokens using exact keys","status":"failed","title":"extracts tokens using exact keys","duration":38.234125000000006,"failureMessages":["AssertionError: expected false to be true // Object.is equality\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:101:33\n    at processTicksAndRejections (node:internal/process/task_queues:105:5)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import unwraps JSON-encoded string values","status":"failed","title":"unwraps JSON-encoded string values","duration":42.318708000000015,"failureMessages":["AssertionError: expected false to be true // Object.is equality\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:118:33\n    at processTicksAndRejections (node:internal/process/task_queues:105:5)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import falls back to fuzzy key matching on macOS when exact keys are missing","status":"failed","title":"falls back to fuzzy key matching on macOS when exact keys are missing","duration":38.566666999999995,"failureMessages":["AssertionError: expected false to be true // Object.is equality\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:142:33\n    at processTicksAndRejections (node:internal/process/task_queues:105:5)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import returns login-prompt error when tokens are missing even after fallback","status":"failed","title":"returns login-prompt error when tokens are missing even after fallback","duration":30.129125000000045,"failureMessages":["AssertionError: the given combination of arguments (undefined and string) is invalid for this assertion. You can use an array, a map, an object, a set, a string, or a weakset instead of a string\n    at Proxy.<anonymous> (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/expect/dist/index.js:1319:15)\n    at Proxy.<anonymous> (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/expect/dist/index.js:1156:15)\n    at Proxy.methodWrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/chai/index.js:1700:25)\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:156:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import linux uses single hardcoded path and original error message","status":"failed","title":"linux uses single hardcoded path and original error message","duration":3.6335000000000264,"failureMessages":["AssertionError: expected 'Cursor database not found. Checked lo…' to be 'Cursor database not found. Make sure …' // Object.is equality\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:169:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import unsupported platform returns 400","status":"failed","title":"unsupported platform returns 400","duration":0.4944579999999519,"failureMessages":["AssertionError: expected 200 to be 400 // Object.is equality\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:181:29\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]}],"startTime":1781341952502,"endTime":1781341952725.4944,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js"},{"assertionResults":[{"ancestorTitles":["OpenAI Responses streaming termination"],"fullName":"OpenAI Responses streaming termination emits a response.failed event when a Responses stream closes before a terminal event","status":"passed","title":"emits a response.failed event when a Responses stream closes before a terminal event","duration":45.59566699999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI Responses streaming termination"],"fullName":"OpenAI Responses streaming termination does not add response.failed when a Responses stream already completed","status":"passed","title":"does not add response.failed when a Responses stream already completed","duration":1.1238749999999982,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI Responses streaming termination"],"fullName":"OpenAI Responses streaming termination emits response.failed before DONE when a Responses stream sends DONE without a terminal event","status":"passed","title":"emits response.failed before DONE when a Responses stream sends DONE without a terminal event","duration":1.0654590000000042,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953551,"endTime":1781341953599.0654,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-responses-terminal-event.test.js"},{"assertionResults":[{"ancestorTitles":["openaiToClaudeResponse tool argument sanitization"],"fullName":"openaiToClaudeResponse tool argument sanitization drops invalid Read pages and clamps numeric bounds","status":"passed","title":"drops invalid Read pages and clamps numeric bounds","duration":1.2067090000000178,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeResponse tool argument sanitization"],"fullName":"openaiToClaudeResponse tool argument sanitization keeps valid PDF pages","status":"passed","title":"keeps valid PDF pages","duration":0.2722920000000215,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341955009,"endTime":1781341955010.2722,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-to-claude-response-tools.test.js"},{"assertionResults":[{"ancestorTitles":["openaiToClaudeRequest","response_format handling"],"fullName":"openaiToClaudeRequest response_format handling should inject JSON schema instructions for json_schema type","status":"passed","title":"should inject JSON schema instructions for json_schema type","duration":1.3559999999999945,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","response_format handling"],"fullName":"openaiToClaudeRequest response_format handling should inject basic JSON instructions for json_object type","status":"passed","title":"should inject basic JSON instructions for json_object type","duration":0.20066600000001245,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","response_format handling"],"fullName":"openaiToClaudeRequest response_format handling should not modify system prompt when response_format is missing","status":"passed","title":"should not modify system prompt when response_format is missing","duration":0.11874999999997726,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","response_format handling"],"fullName":"openaiToClaudeRequest response_format handling should preserve existing system messages when adding response_format","status":"passed","title":"should preserve existing system messages when adding response_format","duration":0.09975000000002865,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","tool_choice handling"],"fullName":"openaiToClaudeRequest tool_choice handling converts OpenAI forced tool ({type:'function'}) to Claude {type:'tool'}","status":"passed","title":"converts OpenAI forced tool ({type:'function'}) to Claude {type:'tool'}","duration":0.3407090000000039,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","tool_choice handling"],"fullName":"openaiToClaudeRequest tool_choice handling maps string tool_choice values","status":"passed","title":"maps string tool_choice values","duration":0.3358750000000441,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","tool_choice handling"],"fullName":"openaiToClaudeRequest tool_choice handling passes through Claude-native tool_choice objects unchanged","status":"passed","title":"passes through Claude-native tool_choice objects unchanged","duration":0.28229200000004084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","tool_choice handling"],"fullName":"openaiToClaudeRequest tool_choice handling never leaks an invalid type (falls back to auto)","status":"passed","title":"never leaks an invalid type (falls back to auto)","duration":0.14629100000001927,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","tool_choice handling"],"fullName":"openaiToClaudeRequest tool_choice handling omits tool_choice entirely when the request has none","status":"passed","title":"omits tool_choice entirely when the request has none","duration":0.34070800000000645,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeResponse"],"fullName":"openaiToClaudeResponse omits empty Read pages tool argument before emitting Claude input deltas","status":"failed","title":"omits empty Read pages tool argument before emitting Claude input deltas","duration":3.2385000000000446,"failureMessages":["AssertionError: expected undefined to be defined\n    at /Users/Working/router4/app/tests/unit/openai-to-claude.test.js:199:24\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]}],"startTime":1781341952666,"endTime":1781341952672.2385,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-to-claude.test.js"},{"assertionResults":[{"ancestorTitles":["openaiToCommandCode — basic envelope"],"fullName":"openaiToCommandCode — basic envelope returns the expected top-level envelope shape","status":"passed","title":"returns the expected top-level envelope shape","duration":2.6807090000000073,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCode — system handling"],"fullName":"openaiToCommandCode — system handling hoists system messages to params.system (string), not messages[]","status":"passed","title":"hoists system messages to params.system (string), not messages[]","duration":0.602833000000004,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCode — system handling"],"fullName":"openaiToCommandCode — system handling joins multiple system messages with blank line","status":"passed","title":"joins multiple system messages with blank line","duration":0.09312499999998636,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCode — system handling"],"fullName":"openaiToCommandCode — system handling omits params.system when no system messages","status":"passed","title":"omits params.system when no system messages","duration":0.1482910000000004,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCode — content shape"],"fullName":"openaiToCommandCode — content shape MUST always emit content as Array (never string) for user","status":"passed","title":"MUST always emit content as Array (never string) for user","duration":0.32695800000001896,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCode — content shape"],"fullName":"openaiToCommandCode — content shape MUST always emit content as Array for assistant","status":"passed","title":"MUST always emit content as Array for assistant","duration":0.14845800000000509,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCode — tool role / tool-result (AI SDK)"],"fullName":"openaiToCommandCode — tool role / tool-result (AI SDK) converts role:\"tool\" to role:\"tool\" with tool-result block; output is {type:\"text\",value}","status":"passed","title":"converts role:\"tool\" to role:\"tool\" with tool-result block; output is {type:\"text\",value}","duration":0.16566599999998743,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCode — assistant tool_calls / tool-call"],"fullName":"openaiToCommandCode — assistant tool_calls / tool-call converts assistant.tool_calls[] into content blocks of type tool-call","status":"passed","title":"converts assistant.tool_calls[] into content blocks of type tool-call","duration":0.2914159999999981,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCode — tools schema conversion"],"fullName":"openaiToCommandCode — tools schema conversion converts OpenAI {type:\"function\", function:{...}} to Anthropic plain {name, input_schema}","status":"passed","title":"converts OpenAI {type:\"function\", function:{...}} to Anthropic plain {name, input_schema}","duration":1.1217499999999916,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCode — tools schema conversion"],"fullName":"openaiToCommandCode — tools schema conversion preserves description on converted tool","status":"passed","title":"preserves description on converted tool","duration":0.28999999999999204,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCode — tools schema conversion"],"fullName":"openaiToCommandCode — tools schema conversion does not include tools field when input has none","status":"passed","title":"does not include tools field when input has none","duration":0.2631670000000099,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954661,"endTime":1781341954667.29,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-to-commandcode.test.js"},{"assertionResults":[{"ancestorTitles":["buildKiroPayload","basic message conversion"],"fullName":"buildKiroPayload basic message conversion should convert a simple text message","status":"passed","title":"should convert a simple text message","duration":4.0759589999999974,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildKiroPayload","basic message conversion"],"fullName":"buildKiroPayload basic message conversion should not include images field when no images are present","status":"passed","title":"should not include images field when no images are present","duration":0.1372920000000022,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildKiroPayload","image forwarding"],"fullName":"buildKiroPayload image forwarding should forward base64 image from image_url content part","status":"passed","title":"should forward base64 image from image_url content part","duration":0.6094170000000076,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildKiroPayload","image forwarding"],"fullName":"buildKiroPayload image forwarding should forward multiple base64 images","status":"passed","title":"should forward multiple base64 images","duration":0.3157500000000084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildKiroPayload","image forwarding"],"fullName":"buildKiroPayload image forwarding should not include images field when images array is empty","status":"passed","title":"should not include images field when images array is empty","duration":0.17062500000000114,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildKiroPayload","image forwarding"],"fullName":"buildKiroPayload image forwarding should include both images and text content together","status":"passed","title":"should include both images and text content together","duration":0.17804100000000744,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildKiroPayload","image forwarding"],"fullName":"buildKiroPayload image forwarding should treat http image URLs as text fallback (Kiro only supports base64)","status":"passed","title":"should treat http image URLs as text fallback (Kiro only supports base64)","duration":0.08979099999999107,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildKiroPayload","tool interaction without client-provided tools"],"fullName":"buildKiroPayload tool interaction without client-provided tools should flatten OpenAI tool_calls + tool result into history text with no tools array","status":"passed","title":"should flatten OpenAI tool_calls + tool result into history text with no tools array","duration":0.2427500000000009,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildKiroPayload","tool interaction without client-provided tools"],"fullName":"buildKiroPayload tool interaction without client-provided tools should flatten Claude tool_use / tool_result blocks with no tools array","status":"passed","title":"should flatten Claude tool_use / tool_result blocks with no tools array","duration":0.5468329999999924,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildKiroPayload","tool interaction without client-provided tools"],"fullName":"buildKiroPayload tool interaction without client-provided tools should keep structured tools when the client DOES provide a tools array","status":"passed","title":"should keep structured tools when the client DOES provide a tools array","duration":0.5298750000000041,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildKiroPayload","tool interaction without client-provided tools"],"fullName":"buildKiroPayload tool interaction without client-provided tools should salvage orphaned tool_result content as text instead of discarding it","status":"passed","title":"should salvage orphaned tool_result content as text instead of discarding it","duration":0.5457499999999982,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954621,"endTime":1781341954628.5457,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-to-kiro.test.js"},{"assertionResults":[{"ancestorTitles":["parseOpenAIMessages"],"fullName":"parseOpenAIMessages extracts system + history + current msg","status":"passed","title":"extracts system + history + current msg","duration":1.9275420000000025,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseOpenAIMessages"],"fullName":"parseOpenAIMessages treats developer role as system","status":"passed","title":"treats developer role as system","duration":0.2397500000000008,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseOpenAIMessages"],"fullName":"parseOpenAIMessages handles multi-part content (array of text blocks)","status":"passed","title":"handles multi-part content (array of text blocks)","duration":0.09729199999999594,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseOpenAIMessages"],"fullName":"parseOpenAIMessages skips empty content messages","status":"passed","title":"skips empty content messages","duration":0.2046670000000006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery first turn: returns JSON with instructions + query","status":"passed","title":"first turn: returns JSON with instructions + query","duration":1.2256249999999937,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery follow-up (with backendUuid): returns plain currentMsg, no JSON","status":"passed","title":"follow-up (with backendUuid): returns plain currentMsg, no JSON","duration":0.2997919999999965,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery includes history when present on first turn","status":"passed","title":"includes history when present on first turn","duration":0.42525000000000546,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery injects tools into instructions on first turn","status":"passed","title":"injects tools into instructions on first turn","duration":0.2048329999999936,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery ignores tools on follow-up turn (uses session)","status":"passed","title":"ignores tools on follow-up turn (uses session)","duration":0.4469579999999951,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery truncates query if JSON exceeds 96000 chars","status":"passed","title":"truncates query if JSON exceeds 96000 chars","duration":0.3808750000000032,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["formatToolsHint"],"fullName":"formatToolsHint returns empty string for no tools","status":"passed","title":"returns empty string for no tools","duration":0.125,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["formatToolsHint"],"fullName":"formatToolsHint handles OpenAI tool schema (function wrapper)","status":"passed","title":"handles OpenAI tool schema (function wrapper)","duration":0.05341700000001026,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["formatToolsHint"],"fullName":"formatToolsHint handles flat tool schema","status":"passed","title":"handles flat tool schema","duration":0.03962500000000091,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["formatToolsHint"],"fullName":"formatToolsHint truncates long descriptions to first line, max 200 chars","status":"passed","title":"truncates long descriptions to first line, max 200 chars","duration":0.08312499999999545,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildPplxRequestBody"],"fullName":"buildPplxRequestBody sets query_str at both top-level AND params (required by upstream API)","status":"passed","title":"sets query_str at both top-level AND params (required by upstream API)","duration":17.473457999999994,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildPplxRequestBody"],"fullName":"buildPplxRequestBody includes required params","status":"passed","title":"includes required params","duration":0.3769580000000019,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute maps pplx-auto → mode=concise, pref=pplx_pro","status":"passed","title":"maps pplx-auto → mode=concise, pref=pplx_pro","duration":33.671458,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute applies THINKING_MAP when reasoning_effort is set","status":"passed","title":"applies THINKING_MAP when reasoning_effort is set","duration":0.8192090000000007,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute sends Cookie header when credentials.apiKey provided","status":"passed","title":"sends Cookie header when credentials.apiKey provided","duration":0.39683400000001257,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute sends Bearer header when credentials.accessToken provided","status":"passed","title":"sends Bearer header when credentials.accessToken provided","duration":0.4372500000000059,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute injects body.tools into query_str instructions","status":"passed","title":"injects body.tools into query_str instructions","duration":1.2487079999999935,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute returns 400 on missing messages","status":"passed","title":"returns 400 on missing messages","duration":0.2294170000000122,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute surfaces upstream 401 with friendly auth message","status":"passed","title":"surfaces upstream 401 with friendly auth message","duration":0.6720830000000149,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute surfaces 429 with rate-limit message","status":"passed","title":"surfaces 429 with rate-limit message","duration":0.40945800000000077,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953140,"endTime":1781341953202.4094,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/perplexity-web.test.js"},{"assertionResults":[{"ancestorTitles":["MiniMax-M3 model registration"],"fullName":"MiniMax-M3 model registration includes MiniMax-M3 in PROVIDER_MODELS.minimax","status":"passed","title":"includes MiniMax-M3 in PROVIDER_MODELS.minimax","duration":2.8231250000000045,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 model registration"],"fullName":"MiniMax-M3 model registration includes MiniMax-M3 in PROVIDER_MODELS['minimax-cn']","status":"passed","title":"includes MiniMax-M3 in PROVIDER_MODELS['minimax-cn']","duration":0.28641600000000267,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 model registration"],"fullName":"MiniMax-M3 model registration exposes MiniMax-M3 through getModelsByProviderId for both provider IDs","status":"passed","title":"exposes MiniMax-M3 through getModelsByProviderId for both provider IDs","duration":0.16841700000000515,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 model registration"],"fullName":"MiniMax-M3 model registration does not regress the existing M2.7 / M2.5 / M2.1 entries","status":"passed","title":"does not regress the existing M2.7 / M2.5 / M2.1 entries","duration":0.9703750000000184,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954780,"endTime":1781341954783.9705,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/provider-models-minimax-m3.test.js"},{"assertionResults":[{"ancestorTitles":["MiniMax-M3 pricing"],"fullName":"MiniMax-M3 pricing includes MiniMax-M3 in MODEL_PRICING","status":"passed","title":"includes MiniMax-M3 in MODEL_PRICING","duration":1.8566669999999874,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 pricing"],"fullName":"MiniMax-M3 pricing MiniMax-M3 pricing has numeric shape (input, output, cached)","status":"passed","title":"MiniMax-M3 pricing has numeric shape (input, output, cached)","duration":0.9606660000000034,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 pricing"],"fullName":"MiniMax-M3 pricing MiniMax-M3 input price matches the design spec (0.30)","status":"passed","title":"MiniMax-M3 input price matches the design spec (0.30)","duration":0.13658300000000168,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 pricing"],"fullName":"MiniMax-M3 pricing MiniMax-M3 output price matches the design spec (1.20)","status":"passed","title":"MiniMax-M3 output price matches the design spec (1.20)","duration":0.12358399999999392,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 pricing"],"fullName":"MiniMax-M3 pricing MiniMax-M3 cached price matches the design spec (0.06)","status":"passed","title":"MiniMax-M3 cached price matches the design spec (0.06)","duration":0.07374999999998977,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954958,"endTime":1781341954961.1365,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/provider-pricing-minimax-m3.test.js"},{"assertionResults":[{"ancestorTitles":["provider test-models route kind routing"],"fullName":"provider test-models route kind routing routes huggingface image models to /api/v1/images/generations","status":"passed","title":"routes huggingface image models to /api/v1/images/generations","duration":46.917874999999995,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953458,"endTime":1781341953504.918,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/provider-test-models-routing.test.js"},{"assertionResults":[{"ancestorTitles":["Provider Validation API","OpenAI Compatible"],"fullName":"Provider Validation API OpenAI Compatible should return valid:true when /models succeeds","status":"passed","title":"should return valid:true when /models succeeds","duration":2.559916000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","OpenAI Compatible"],"fullName":"Provider Validation API OpenAI Compatible should fallback to chat/completions when /models fails and modelId provided","status":"passed","title":"should fallback to chat/completions when /models fails and modelId provided","duration":1.1536669999999987,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","OpenAI Compatible"],"fullName":"Provider Validation API OpenAI Compatible should return error when /models fails and no modelId","status":"passed","title":"should return error when /models fails and no modelId","duration":0.5454590000000081,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Anthropic Compatible"],"fullName":"Provider Validation API Anthropic Compatible should normalize URL by removing /messages suffix","status":"passed","title":"should normalize URL by removing /messages suffix","duration":0.1634999999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Anthropic Compatible"],"fullName":"Provider Validation API Anthropic Compatible should send correct headers for Anthropic API","status":"passed","title":"should send correct headers for Anthropic API","duration":0.4220420000000047,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - Network"],"fullName":"Provider Validation API Error Messages - Network should map ECONNREFUSED to user-friendly message","status":"passed","title":"should map ECONNREFUSED to user-friendly message","duration":0.08770800000000634,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - Network"],"fullName":"Provider Validation API Error Messages - Network should map ENOTFOUND to user-friendly message","status":"passed","title":"should map ENOTFOUND to user-friendly message","duration":0.10875000000000057,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - Network"],"fullName":"Provider Validation API Error Messages - Network should map timeout to user-friendly message","status":"passed","title":"should map timeout to user-friendly message","duration":0.0656670000000048,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - Network"],"fullName":"Provider Validation API Error Messages - Network should map CERT_HAS_EXPIRED to user-friendly message","status":"passed","title":"should map CERT_HAS_EXPIRED to user-friendly message","duration":0.2998750000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","URL Validation"],"fullName":"Provider Validation API URL Validation should validate correct URL format","status":"passed","title":"should validate correct URL format","duration":0.15687499999999943,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return auth error for 401","status":"passed","title":"should return auth error for 401","duration":0.12700000000000955,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return auth error for 403","status":"passed","title":"should return auth error for 403","duration":0.04416700000000162,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return not found for 404","status":"passed","title":"should return not found for 404","duration":0.0397920000000056,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return server error for 500","status":"passed","title":"should return server error for 500","duration":0.03629099999999141,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return server error for 502","status":"passed","title":"should return server error for 502","duration":0.03541699999999537,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return unexpected for other codes","status":"passed","title":"should return unexpected for other codes","duration":0.11166700000001129,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /chat/completions Status Codes"],"fullName":"Provider Validation API Error Messages - /chat/completions Status Codes should return auth error for 401","status":"passed","title":"should return auth error for 401","duration":0.048042000000009466,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /chat/completions Status Codes"],"fullName":"Provider Validation API Error Messages - /chat/completions Status Codes should return invalid model for 400","status":"passed","title":"should return invalid model for 400","duration":0.03537500000000193,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /chat/completions Status Codes"],"fullName":"Provider Validation API Error Messages - /chat/completions Status Codes should return not found for 404","status":"passed","title":"should return not found for 404","duration":0.03445899999999824,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /chat/completions Status Codes"],"fullName":"Provider Validation API Error Messages - /chat/completions Status Codes should return server error for 503","status":"passed","title":"should return server error for 503","duration":0.3260830000000112,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /chat/completions Status Codes"],"fullName":"Provider Validation API Error Messages - /chat/completions Status Codes should return failed for other codes","status":"passed","title":"should return failed for other codes","duration":0.2205419999999947,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Response Format"],"fullName":"Provider Validation API Response Format should return correct format for success via /models","status":"passed","title":"should return correct format for success via /models","duration":0.234958000000006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Response Format"],"fullName":"Provider Validation API Response Format should return correct format for success via chat","status":"passed","title":"should return correct format for success via chat","duration":0.2169590000000028,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Response Format"],"fullName":"Provider Validation API Response Format should return correct format for failure with error","status":"passed","title":"should return correct format for failure with error","duration":0.22245799999998894,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954472,"endTime":1781341954479.2349,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/provider-validation.test.js"},{"assertionResults":[{"ancestorTitles":["QODER_MODEL_MAP"],"fullName":"QODER_MODEL_MAP allows Qoder's latest model key","status":"passed","title":"allows Qoder's latest model key","duration":0.8066249999999968,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["QODER_MODEL_MAP"],"fullName":"QODER_MODEL_MAP exposes Qoder's latest model in the static provider catalog","status":"passed","title":"exposes Qoder's latest model in the static provider catalog","duration":0.14862500000000978,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody preserves base64 length (input length divisible by 3)","status":"passed","title":"preserves base64 length (input length divisible by 3)","duration":0.12604100000001495,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody preserves base64 length (input length not divisible by 3)","status":"passed","title":"preserves base64 length (input length not divisible by 3)","duration":0.2823750000000018,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody handles empty input without throwing","status":"passed","title":"handles empty input without throwing","duration":0.308290999999997,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody accepts string and Buffer inputs equivalently","status":"passed","title":"accepts string and Buffer inputs equivalently","duration":0.412208000000021,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody only emits characters from the custom alphabet","status":"passed","title":"only emits characters from the custom alphabet","duration":1.4707920000000172,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody is deterministic for identical input","status":"passed","title":"is deterministic for identical input","duration":0.17762500000000614,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody produces different output for different input","status":"passed","title":"produces different output for different input","duration":0.741375000000005,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generatePkcePair"],"fullName":"generatePkcePair produces base64url-safe verifier and challenge of the right length","status":"passed","title":"produces base64url-safe verifier and challenge of the right length","duration":0.5684589999999901,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generatePkcePair"],"fullName":"generatePkcePair verifier and challenge are different (challenge is sha256 of verifier)","status":"passed","title":"verifier and challenge are different (challenge is sha256 of verifier)","duration":0.16904199999999037,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generatePkcePair"],"fullName":"generatePkcePair returns codeVerifier (not verifier) on the higher-level helper","status":"passed","title":"returns codeVerifier (not verifier) on the higher-level helper","duration":0.2691250000000025,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["initiateDeviceFlow"],"fullName":"initiateDeviceFlow produces a verification URL pointing at qoder.com/device/selectAccounts","status":"passed","title":"produces a verification URL pointing at qoder.com/device/selectAccounts","duration":0.17804100000000744,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["initiateDeviceFlow"],"fullName":"initiateDeviceFlow returns nonce and machineId as UUIDs","status":"passed","title":"returns nonce and machineId as UUIDs","duration":0.1731670000000065,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders produces all required Cosy-* headers","status":"passed","title":"produces all required Cosy-* headers","duration":1.1843749999999886,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Authorization is a Bearer COSY token with payload+sig","status":"passed","title":"Authorization is a Bearer COSY token with payload+sig","duration":0.2520419999999888,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Cosy-Sigpath strips the leading /algo prefix","status":"passed","title":"Cosy-Sigpath strips the leading /algo prefix","duration":0.1384999999999934,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Cosy-Sigpath also handles the encoded chat URL","status":"passed","title":"Cosy-Sigpath also handles the encoded chat URL","duration":0.18312499999998977,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Cosy-Bodyhash is the MD5 of the request body, Cosy-Bodylength is the length","status":"passed","title":"Cosy-Bodyhash is the MD5 of the request body, Cosy-Bodylength is the length","duration":0.13412499999998317,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders empty body produces the canonical empty-MD5 hash","status":"passed","title":"empty body produces the canonical empty-MD5 hash","duration":0.12841699999998468,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Cosy-Machineid + Cosy-Machinetoken match the supplied machineId","status":"passed","title":"Cosy-Machineid + Cosy-Machinetoken match the supplied machineId","duration":0.11670800000001691,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders auto-generates a machineId when none is supplied","status":"passed","title":"auto-generates a machineId when none is supplied","duration":0.11650000000000205,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders throws when userId is missing","status":"passed","title":"throws when userId is missing","duration":0.36233400000000415,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders throws when authToken is missing","status":"passed","title":"throws when authToken is missing","duration":0.08412500000000023,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Cosy-User reflects the supplied userId verbatim","status":"passed","title":"Cosy-User reflects the supplied userId verbatim","duration":0.4283749999999884,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders two calls with identical inputs differ only in fields that include fresh randomness","status":"passed","title":"two calls with identical inputs differ only in fields that include fresh randomness","duration":0.263040999999987,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry accepts ms-epoch as a JSON number","status":"passed","title":"accepts ms-epoch as a JSON number","duration":0.07670799999999645,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry accepts ms-epoch as a numeric string","status":"passed","title":"accepts ms-epoch as a numeric string","duration":0.045250000000010004,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry accepts RFC3339 strings","status":"passed","title":"accepts RFC3339 strings","duration":0.05016700000001606,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry does not interpret short numeric strings as a year","status":"passed","title":"does not interpret short numeric strings as a year","duration":1.027957999999984,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry falls back to expiresInSeconds when expiresAt is missing","status":"passed","title":"falls back to expiresInSeconds when expiresAt is missing","duration":0.28316699999999173,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry treats expires_in: 0 as already expired (now), not 30-day fallback","status":"passed","title":"treats expires_in: 0 as already expired (now), not 30-day fallback","duration":0.12229200000001583,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry falls back to ~30 days when both inputs are missing","status":"passed","title":"falls back to ~30 days when both inputs are missing","duration":0.11966599999999517,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry falls back to ~30 days when both inputs are unparseable","status":"passed","title":"falls back to ~30 days when both inputs are unparseable","duration":0.12066699999999742,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["normalizeMessages"],"fullName":"normalizeMessages hoists role:system out of messages into systemText","status":"passed","title":"hoists role:system out of messages into systemText","duration":0.8931249999999977,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["normalizeMessages"],"fullName":"normalizeMessages flattens multipart text content into a string","status":"passed","title":"flattens multipart text content into a string","duration":0.06783300000000736,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["normalizeMessages"],"fullName":"normalizeMessages joins multiple system messages with a blank line","status":"passed","title":"joins multiple system messages with a blank line","duration":0.04445799999999167,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["normalizeMessages"],"fullName":"normalizeMessages returns empty results for empty input","status":"passed","title":"returns empty results for empty input","duration":0.10516700000002288,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE forwards an OpenAI envelope chunk and emits [DONE] in flush","status":"passed","title":"forwards an OpenAI envelope chunk and emits [DONE] in flush","duration":14.644790999999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE drains a trailing partial line without a newline in flush()","status":"passed","title":"drains a trailing partial line without a newline in flush()","duration":0.43524999999999636,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE does not forward chunks after [DONE] has been emitted","status":"passed","title":"does not forward chunks after [DONE] has been emitted","duration":0.4954169999999749,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE strips embedded newlines from inner body before forwarding","status":"passed","title":"strips embedded newlines from inner body before forwarding","duration":0.34987499999999727,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE upstream error envelope produces an error chunk + [DONE]","status":"passed","title":"upstream error envelope produces an error chunk + [DONE]","duration":1.3971249999999884,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE non-ok responses are returned unchanged (no transform)","status":"passed","title":"non-ok responses are returned unchanged (no transform)","duration":0.2725419999999872,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341953726,"endTime":1781341953756.3972,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/qoder.test.js"},{"assertionResults":[{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip injects reasoning_content on a deepseek- assistant message that lacks it","status":"passed","title":"injects reasoning_content on a deepseek- assistant message that lacks it","duration":1.046042,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip preserves an existing reasoning_content instead of overwriting it","status":"passed","title":"preserves an existing reasoning_content instead of overwriting it","duration":0.18099999999999739,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip applies provider-level rule for provider 'deepseek' (scope all)","status":"passed","title":"applies provider-level rule for provider 'deepseek' (scope all)","duration":0.08983299999999872,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip matches deepseek model id case-insensitively for custom providers (#1543)","status":"passed","title":"matches deepseek model id case-insensitively for custom providers (#1543)","duration":0.2608330000000052,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip does not touch non-deepseek providers/models","status":"passed","title":"does not touch non-deepseek providers/models","duration":0.1077499999999958,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip maps deepseek-v4-pro-none alias to disabled thinking and strips reasoning_effort","status":"passed","title":"maps deepseek-v4-pro-none alias to disabled thinking and strips reasoning_effort","duration":0.16420800000000213,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — MiniMax thinking round-trip"],"fullName":"injectReasoningContent — MiniMax thinking round-trip injects reasoning_content on a minimax assistant message that lacks it","status":"passed","title":"injects reasoning_content on a minimax assistant message that lacks it","duration":0.13658300000000168,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — MiniMax thinking round-trip"],"fullName":"injectReasoningContent — MiniMax thinking round-trip injects reasoning_content on minimax assistant message with tool_calls but no reasoning_content","status":"passed","title":"injects reasoning_content on minimax assistant message with tool_calls but no reasoning_content","duration":0.14687499999999432,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — MiniMax thinking round-trip"],"fullName":"injectReasoningContent — MiniMax thinking round-trip applies provider-level rule for provider 'minimax-cn' (scope all)","status":"passed","title":"applies provider-level rule for provider 'minimax-cn' (scope all)","duration":0.3428750000000065,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — MiniMax thinking round-trip"],"fullName":"injectReasoningContent — MiniMax thinking round-trip preserves an existing reasoning_content on minimax instead of overwriting","status":"passed","title":"preserves an existing reasoning_content on minimax instead of overwriting","duration":0.09175000000000466,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — MiniMax thinking round-trip"],"fullName":"injectReasoningContent — MiniMax thinking round-trip DefaultExecutor transformRequest runs the injector for minimax","status":"passed","title":"DefaultExecutor transformRequest runs the injector for minimax","duration":16.559542000000008,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenCodeExecutor — issue #1543 regression"],"fullName":"OpenCodeExecutor — issue #1543 regression runs the injector so deepseek-v4-flash-free round-trips reasoning_content","status":"passed","title":"runs the injector so deepseek-v4-flash-free round-trips reasoning_content","duration":0.12933400000000006,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954458,"endTime":1781341954477.5596,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/reasoningContentInjector.test.js"},{"assertionResults":[{"ancestorTitles":["Responses abort terminal synthesis"],"fullName":"Responses abort terminal synthesis emits response.failed + [DONE] when upstream errors (abort/stall)","status":"passed","title":"emits response.failed + [DONE] when upstream errors (abort/stall)","duration":2.157624999999996,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Responses abort terminal synthesis"],"fullName":"Responses abort terminal synthesis does not synthesize terminal for non-Responses streams (callback null)","status":"passed","title":"does not synthesize terminal for non-Responses streams (callback null)","duration":0.3221249999999998,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954821,"endTime":1781341954824.322,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/responses-abort-terminal.test.js"},{"assertionResults":[{"ancestorTitles":["RTK end-to-end"],"fullName":"RTK end-to-end server is reachable","status":"skipped","title":"server is reachable","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK end-to-end"],"fullName":"RTK end-to-end rtkEnabled flag is true (user must enable via dashboard)","status":"skipped","title":"rtkEnabled flag is true (user must enable via dashboard)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK end-to-end"],"fullName":"RTK end-to-end compresses git diff tool_result and writes [RTK] savings to log","status":"skipped","title":"compresses git diff tool_result and writes [RTK] savings to log","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK end-to-end"],"fullName":"RTK end-to-end compresses grep-style tool_result","status":"skipped","title":"compresses grep-style tool_result","failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952244,"endTime":1781341952244,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/rtk.e2e.test.js"},{"assertionResults":[{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E server reachable and rtkEnabled=true","status":"skipped","title":"server reachable and rtkEnabled=true","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for claude (cc/* → openai→claude)","status":"skipped","title":"compresses git diff for claude (cc/* → openai→claude)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for codex (cx/* → openai→openai-responses)","status":"skipped","title":"compresses git diff for codex (cx/* → openai→openai-responses)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for antigravity (ag/* → openai→antigravity)","status":"skipped","title":"compresses git diff for antigravity (ag/* → openai→antigravity)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for cursor (cu/* → openai→cursor)","status":"skipped","title":"compresses git diff for cursor (cu/* → openai→cursor)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for kiro (kr/* → openai→kiro)","status":"skipped","title":"compresses git diff for kiro (kr/* → openai→kiro)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for gemini (gemini/* → openai→gemini)","status":"skipped","title":"compresses git diff for gemini (gemini/* → openai→gemini)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for deepseek (deepseek/* → openai, passthrough)","status":"skipped","title":"compresses git diff for deepseek (deepseek/* → openai, passthrough)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for ollama (ollama/* → openai→ollama)","status":"skipped","title":"compresses git diff for ollama (ollama/* → openai→ollama)","failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952244,"endTime":1781341952244,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/rtk.multi-provider.e2e.test.js"},{"assertionResults":[{"ancestorTitles":["RTK flag"],"fullName":"RTK flag default off, toggle works","status":"failed","title":"default off, toggle works","duration":4.49670900000001,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:58:18\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters"],"fullName":"RTK filters gitDiff truncates hunks beyond 100 lines and preserves file header","status":"passed","title":"gitDiff truncates hunks beyond 100 lines and preserves file header","duration":0.7633749999999964,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters"],"fullName":"RTK filters gitStatus groups by kind and produces compact output (Rust format)","status":"passed","title":"gitStatus groups by kind and produces compact output (Rust format)","duration":0.5591249999999945,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters"],"fullName":"RTK filters grep groups matches by file and caps per-file lines (Rust format)","status":"passed","title":"grep groups matches by file and caps per-file lines (Rust format)","duration":0.6261669999999526,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters"],"fullName":"RTK filters find groups paths by parent dir, shows basenames (Rust format)","status":"passed","title":"find groups paths by parent dir, shows basenames (Rust format)","duration":0.3492080000000328,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters"],"fullName":"RTK filters dedupLog collapses consecutive duplicates","status":"passed","title":"dedupLog collapses consecutive duplicates","duration":0.22950000000003,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter"],"fullName":"autoDetectFilter detects git diff","status":"passed","title":"detects git diff","duration":0.20475000000004684,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter"],"fullName":"autoDetectFilter detects git status","status":"passed","title":"detects git status","duration":0.1265409999999747,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter"],"fullName":"autoDetectFilter detects grep","status":"passed","title":"detects grep","duration":0.9130000000000109,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter"],"fullName":"autoDetectFilter detects find","status":"passed","title":"detects find","duration":0.4925829999999678,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter"],"fullName":"autoDetectFilter falls back to dedupLog for generic text","status":"passed","title":"falls back to dedupLog for generic text","duration":0.238083999999958,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) ls: compact_ls strips perms/owner, keeps name + size","status":"passed","title":"ls: compact_ls strips perms/owner, keeps name + size","duration":5.035000000000025,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) ls: filters noise dirs","status":"passed","title":"ls: filters noise dirs","duration":0.31612499999999955,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) tree: removes summary, keeps structure","status":"passed","title":"tree: removes summary, keeps structure","duration":0.11891700000001038,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) smartTruncate: keeps head+tail, drops middle","status":"passed","title":"smartTruncate: keeps head+tail, drops middle","duration":0.5656249999999545,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) smartTruncate: passes through small input","status":"passed","title":"smartTruncate: passes through small input","duration":0.07941600000003746,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) readNumbered: compacts very long line-numbered dump","status":"passed","title":"readNumbered: compacts very long line-numbered dump","duration":0.3726660000000379,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) searchList: groups Cursor Glob output by parent dir","status":"passed","title":"searchList: groups Cursor Glob output by parent dir","duration":0.33254199999998946,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter (extras)"],"fullName":"autoDetectFilter (extras) detects tree via box-drawing glyphs","status":"passed","title":"detects tree via box-drawing glyphs","duration":3.9738330000000133,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter (extras)"],"fullName":"autoDetectFilter (extras) detects ls via total + perms rows","status":"passed","title":"detects ls via total + perms rows","duration":0.1468330000000151,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter (extras)"],"fullName":"autoDetectFilter (extras) detects Cursor search list","status":"passed","title":"detects Cursor search list","duration":0.09675000000004275,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["safeApply"],"fullName":"safeApply returns input if filter throws","status":"passed","title":"returns input if filter throws","duration":1.797124999999994,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["safeApply"],"fullName":"safeApply returns input if filter returns non-string","status":"passed","title":"returns input if filter returns non-string","duration":0.5574159999999893,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (disabled)"],"fullName":"compressMessages (disabled) returns null when disabled","status":"failed","title":"returns null when disabled","duration":0.4551660000000197,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:248:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) compresses OpenAI tool message (string content)","status":"failed","title":"compresses OpenAI tool message (string content)","duration":0.17854099999999562,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) compresses Claude string-form tool_result","status":"failed","title":"compresses Claude string-form tool_result","duration":0.21612500000003365,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) compresses Claude array-form tool_result text parts","status":"failed","title":"compresses Claude array-form tool_result text parts","duration":0.1908749999999486,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) skips is_error tool_result","status":"failed","title":"skips is_error tool_result","duration":0.09491599999995515,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) skips below MIN_COMPRESS_SIZE (<500 bytes)","status":"failed","title":"skips below MIN_COMPRESS_SIZE (<500 bytes)","duration":0.0896659999999656,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) never produces empty content (R14 guard)","status":"failed","title":"never produces empty content (R14 guard)","duration":0.24220800000000509,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) skips when body has no messages","status":"failed","title":"skips when body has no messages","duration":0.7291250000000105,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) handles mix of messages without crashing","status":"failed","title":"handles mix of messages without crashing","duration":0.5665829999999801,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["formatRtkLog"],"fullName":"formatRtkLog returns null when no hits","status":"passed","title":"returns null when no hits","duration":0.11216600000000199,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["formatRtkLog"],"fullName":"formatRtkLog formats savings line with percentage","status":"passed","title":"formats savings line with percentage","duration":0.07570900000001757,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952643,"endTime":1781341952670.112,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/rtk.test.js"},{"assertionResults":[{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support compresses tool results in Kiro conversationState.currentMessage","status":"passed","title":"compresses tool results in Kiro conversationState.currentMessage","duration":4.152083000000005,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support compresses tool results in Kiro conversationState.history","status":"passed","title":"compresses tool results in Kiro conversationState.history","duration":0.5366670000000084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support handles multiple tool results across history and currentMessage","status":"passed","title":"handles multiple tool results across history and currentMessage","duration":0.20529200000000003,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support preserves error tool results without compression","status":"passed","title":"preserves error tool results without compression","duration":0.14220799999999656,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support returns null when RTK is disabled","status":"passed","title":"returns null when RTK is disabled","duration":0.07141599999999926,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support handles Kiro body with no tool results gracefully","status":"passed","title":"handles Kiro body with no tool results gracefully","duration":0.0956249999999983,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support handles malformed Kiro body without crashing","status":"passed","title":"handles malformed Kiro body without crashing","duration":0.13066699999998832,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954658,"endTime":1781341954663.2053,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/rtkKiro.test.js"},{"assertionResults":[{"ancestorTitles":["request normalization"],"fullName":"request normalization claudeToOpenAIRequest flattens text-only content arrays into string","status":"failed","title":"claudeToOpenAIRequest flattens text-only content arrays into string","duration":6.6684999999999945,"failureMessages":["AssertionError: expected [ { type: 'text', text: 'hi' }, …(1) ] to be 'hi\\nthere' // Object.is equality\n    at /Users/Working/router4/app/tests/unit/translator-request-normalization.test.js:24:40\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization claudeToOpenAIRequest preserves multimodal arrays","status":"passed","title":"claudeToOpenAIRequest preserves multimodal arrays","duration":0.24016699999998536,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization filterToOpenAIFormat flattens text-only arrays to string","status":"failed","title":"filterToOpenAIFormat flattens text-only arrays to string","duration":0.7766249999999673,"failureMessages":["AssertionError: expected [ { type: 'text', text: 'a' }, …(1) ] to be 'a\\nb' // Object.is equality\n    at /Users/Working/router4/app/tests/unit/translator-request-normalization.test.js:65:40\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization translateRequest keeps /v1/messages Claude->OpenAI text payloads string-safe","status":"failed","title":"translateRequest keeps /v1/messages Claude->OpenAI text payloads string-safe","duration":25.448875000000044,"failureMessages":["AssertionError: expected 'object' to be 'string' // Object.is equality\n    at /Users/Working/router4/app/tests/unit/translator-request-normalization.test.js:95:40\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization translateRequest strips unsupported Anthropic output_config for MiniMax Claude-compatible endpoints","status":"passed","title":"translateRequest strips unsupported Anthropic output_config for MiniMax Claude-compatible endpoints","duration":0.41975000000002183,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization translateRequest preserves output_config for Anthropic Claude","status":"passed","title":"translateRequest preserves output_config for Anthropic Claude","duration":0.282792000000029,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization parseSSELine supports provider raw NDJSON stream lines","status":"failed","title":"parseSSELine supports provider raw NDJSON stream lines","duration":0.5476249999999823,"failureMessages":["AssertionError: expected null to deeply equal { model: 'gpt-oss:120b', …(2) }\n    at /Users/Working/router4/app/tests/unit/translator-request-normalization.test.js:175:20\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/hoanganh/.npm/_npx/69c381f8ad94b576/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization parseSSELine still supports SSE data lines","status":"passed","title":"parseSSELine still supports SSE data lines","duration":0.08062499999999773,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952674,"endTime":1781341952709.0806,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/translator-request-normalization.test.js"},{"assertionResults":[{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should return valid:true when response is 200","status":"passed","title":"should return valid:true when response is 200","duration":4.145083999999997,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should return valid:true when response is 400 (auth accepted but bad body)","status":"passed","title":"should return valid:true when response is 400 (auth accepted but bad body)","duration":0.2665840000000088,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should return valid:true when response is 429 (rate limited but auth ok)","status":"passed","title":"should return valid:true when response is 429 (rate limited but auth ok)","duration":0.309874999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should return valid:false with error when response is 401","status":"passed","title":"should return valid:false with error when response is 401","duration":0.1805000000000092,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should return valid:false with error when response is 403","status":"passed","title":"should return valid:false with error when response is 403","duration":0.18662499999999227,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should strip sso= prefix from apiKey","status":"passed","title":"should strip sso= prefix from apiKey","duration":0.15491699999999753,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should accept raw token without sso= prefix","status":"passed","title":"should accept raw token without sso= prefix","duration":0.14779199999999548,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should POST to /rest/app-chat/conversations/new","status":"passed","title":"should POST to /rest/app-chat/conversations/new","duration":1.5145409999999941,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should send Cloudflare-bypass headers","status":"passed","title":"should send Cloudflare-bypass headers","duration":1.4884169999999983,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should return valid:true when response is 200","status":"passed","title":"should return valid:true when response is 200","duration":0.19712499999999977,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should return valid:false when response is 401","status":"passed","title":"should return valid:false when response is 401","duration":0.1650419999999997,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should return valid:false when response is 403","status":"passed","title":"should return valid:false when response is 403","duration":0.061958000000004176,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should strip __Secure-next-auth.session-token= prefix","status":"passed","title":"should strip __Secure-next-auth.session-token= prefix","duration":0.05762499999998738,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should accept raw token without prefix","status":"passed","title":"should accept raw token without prefix","duration":0.051665999999997325,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should POST to /rest/sse/perplexity_ask","status":"passed","title":"should POST to /rest/sse/perplexity_ask","duration":1.7077910000000003,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954512,"endTime":1781341954522.7078,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/web-cookie-validation.test.js"},{"assertionResults":[{"ancestorTitles":["xai/oauth service"],"fullName":"xai/oauth service validates discovered endpoints are https x.ai URLs","status":"passed","title":"validates discovered endpoints are https x.ai URLs","duration":134.98812499999997,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/oauth service"],"fullName":"xai/oauth service discovers endpoints without custom user-agent headers","status":"passed","title":"discovers endpoints without custom user-agent headers","duration":3.3115840000000105,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/oauth service"],"fullName":"xai/oauth service builds authorize URLs with CLIProxyAPI query extras","status":"passed","title":"builds authorize URLs with CLIProxyAPI query extras","duration":2.2506250000000136,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/oauth service"],"fullName":"xai/oauth service generates dashboard auth data with CLIProxyAPI PKCE size and discovered endpoints","status":"passed","title":"generates dashboard auth data with CLIProxyAPI PKCE size and discovered endpoints","duration":462.350958,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/oauth service"],"fullName":"xai/oauth service exchanges dashboard codes against the discovered xAI token endpoint","status":"passed","title":"exchanges dashboard codes against the discovered xAI token endpoint","duration":13.094916999999896,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952822,"endTime":1781341953438.095,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/xai-oauth-service.test.js"},{"assertionResults":[{"ancestorTitles":["xai/token-refresh wrapper"],"fullName":"xai/token-refresh wrapper refreshXaiToken module loads without throwing","status":"passed","title":"refreshXaiToken module loads without throwing","duration":11.412832999999992,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/token-refresh wrapper"],"fullName":"xai/token-refresh wrapper formatProviderCredentials returns Bearer-shape for xai","status":"passed","title":"formatProviderCredentials returns Bearer-shape for xai","duration":0.6540839999999974,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/token-refresh wrapper"],"fullName":"xai/token-refresh wrapper refreshTokenByProvider returns null when refreshToken missing","status":"passed","title":"refreshTokenByProvider returns null when refreshToken missing","duration":0.3470000000000084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/token-refresh wrapper"],"fullName":"xai/token-refresh wrapper refreshTokenByProvider returns expiresIn for refreshed xai tokens","status":"passed","title":"refreshTokenByProvider returns expiresIn for refreshed xai tokens","duration":5.966542000000004,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341954298,"endTime":1781341954315.9666,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/xai-tokenRefresh.test.js"},{"assertionResults":[{"ancestorTitles":["REAL provider smoke"],"fullName":"REAL provider smoke has active providers in DB","status":"skipped","title":"has active providers in DB","failureMessages":[],"meta":{},"tags":[]}],"startTime":1781341952244,"endTime":1781341952244,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/real/smoke-providers.real.test.js"}]}
\ No newline at end of file
diff --git a/tests/__baseline__/current.json b/tests/__baseline__/current.json
new file mode 100644
index 0000000..d8a2e22
--- /dev/null
+++ b/tests/__baseline__/current.json
@@ -0,0 +1 @@
+{"numTotalTestSuites":276,"numPassedTestSuites":259,"numFailedTestSuites":17,"numPendingTestSuites":0,"numTotalTests":840,"numPassedTests":788,"numFailedTests":26,"numPendingTests":26,"numTodoTests":0,"snapshot":{"added":0,"failure":false,"filesAdded":0,"filesRemoved":0,"filesRemovedList":[],"filesUnmatched":0,"filesUpdated":0,"matched":99,"total":99,"unchecked":0,"uncheckedKeysByFile":[],"unmatched":0,"updated":0,"didUpdate":false},"startTime":1781497742906,"success":false,"testResults":[{"assertionResults":[{"ancestorTitles":["Antigravity → OpenAI"],"fullName":"Antigravity → OpenAI functionResponse + functionCall in same content keeps both","status":"passed","title":"functionResponse + functionCall in same content keeps both","duration":4.76124999999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity → OpenAI"],"fullName":"Antigravity → OpenAI functionCall without id keeps a stable matchable id","status":"passed","title":"functionCall without id keeps a stable matchable id","duration":0.2752909999999815,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity → OpenAI"],"fullName":"Antigravity → OpenAI signature-only part does not produce empty text","status":"passed","title":"signature-only part does not produce empty text","duration":0.12412499999999227,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745628,"endTime":1781497745633.2754,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-antigravity.test.js"},{"assertionResults":[{"ancestorTitles":["Claude Code CLI context → OpenAI"],"fullName":"Claude Code CLI context → OpenAI system array keeps all text parts","status":"passed","title":"system array keeps all text parts","duration":1.5511250000000132,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Claude Code CLI context → OpenAI"],"fullName":"Claude Code CLI context → OpenAI assistant thinking block survives Claude→Claude passthrough","status":"passed","title":"assistant thinking block survives Claude→Claude passthrough","duration":0.3392080000000135,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Claude Code CLI context → OpenAI"],"fullName":"Claude Code CLI context → OpenAI redacted_thinking block is not silently dropped","status":"passed","title":"redacted_thinking block is not silently dropped","duration":3.540666999999985,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Claude Code CLI context → OpenAI"],"fullName":"Claude Code CLI context → OpenAI tool_result image block is preserved","status":"passed","title":"tool_result image block is preserved","duration":1.1281659999999931,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745439,"endTime":1781497745446.1282,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-claudeCode-context.test.js"},{"assertionResults":[{"ancestorTitles":["Codex CLI Responses → OpenAI"],"fullName":"Codex CLI Responses → OpenAI assistant has no empty tool_calls array when all names are empty","status":"passed","title":"assistant has no empty tool_calls array when all names are empty","duration":3.1669160000000147,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex CLI Responses → OpenAI"],"fullName":"Codex CLI Responses → OpenAI function_call arguments end up as a string","status":"passed","title":"function_call arguments end up as a string","duration":1.9879589999999894,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex CLI Responses → OpenAI"],"fullName":"Codex CLI Responses → OpenAI input_image with file_id is not used as a raw url","status":"passed","title":"input_image with file_id is not used as a raw url","duration":0.8092090000000098,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Codex Responses (reverse)"],"fullName":"OpenAI → Codex Responses (reverse) call_id longer than 64 chars is clamped","status":"passed","title":"call_id longer than 64 chars is clamped","duration":0.31595799999999485,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745239,"endTime":1781497745245.316,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-codexCli-responses.test.js"},{"assertionResults":[{"ancestorTitles":["OpenAI → Gemini"],"fullName":"OpenAI → Gemini multiple system messages are all kept","status":"passed","title":"multiple system messages are all kept","duration":4.6682500000000005,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Cursor"],"fullName":"OpenAI → Cursor image content is preserved","status":"passed","title":"image content is preserved","duration":0.7739169999999831,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Cursor"],"fullName":"OpenAI → Cursor respects client max_tokens","status":"passed","title":"respects client max_tokens","duration":1.0494999999999948,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → CommandCode"],"fullName":"OpenAI → CommandCode malformed tool arguments are not silently emptied","status":"passed","title":"malformed tool arguments are not silently emptied","duration":1.5220410000000015,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → CommandCode"],"fullName":"OpenAI → CommandCode image content is preserved","status":"passed","title":"image content is preserved","duration":0.641541999999987,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744975,"endTime":1781497744984.6416,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-gemini-cursor-commandcode.test.js"},{"assertionResults":[{"ancestorTitles":["OpenAI → Kiro"],"fullName":"OpenAI → Kiro malformed tool arguments do not throw the whole request","status":"passed","title":"malformed tool arguments do not throw the whole request","duration":5.476499999999987,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Kiro"],"fullName":"OpenAI → Kiro respects client max_tokens","status":"passed","title":"respects client max_tokens","duration":5.955707999999987,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Kiro"],"fullName":"OpenAI → Kiro remote image url is preserved as an image, not text","status":"passed","title":"remote image url is preserved as an image, not text","duration":1.6610830000000192,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745126,"endTime":1781497745139.6611,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-kiro.test.js"},{"assertionResults":[{"ancestorTitles":["bug: Claude → OpenAI bridge data loss"],"fullName":"bug: Claude → OpenAI bridge data loss image with source.type=url is preserved (NOT dropped)","status":"passed","title":"image with source.type=url is preserved (NOT dropped)","duration":10.171915999999982,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: Claude → OpenAI bridge data loss"],"fullName":"bug: Claude → OpenAI bridge data loss thinking block survives round-trip Claude→OpenAI→Claude","status":"passed","title":"thinking block survives round-trip Claude→OpenAI→Claude","duration":0.5456669999999804,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: Claude → OpenAI bridge data loss"],"fullName":"bug: Claude → OpenAI bridge data loss tool_result with image block is not turned into raw JSON / dropped","status":"passed","title":"tool_result with image block is not turned into raw JSON / dropped","duration":0.9221660000000043,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: Claude → OpenAI bridge data loss"],"fullName":"bug: Claude → OpenAI bridge data loss tool_result is_error flag is preserved","status":"passed","title":"tool_result is_error flag is preserved","duration":0.8278750000000059,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: Claude → OpenAI bridge data loss"],"fullName":"bug: Claude → OpenAI bridge data loss system array non-text parts are not silently dropped","status":"passed","title":"system array non-text parts are not silently dropped","duration":0.3147920000000113,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: tool_call id stability across bridge"],"fullName":"bug: tool_call id stability across bridge sanitized tool id stays matched between call and result","status":"passed","title":"sanitized tool id stays matched between call and result","duration":0.18141699999998195,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bug: empty content message handling"],"fullName":"bug: empty content message handling assistant message with only tool_calls is not dropped","status":"passed","title":"assistant message with only tool_calls is not dropped","duration":0.09662499999998886,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745173,"endTime":1781497745186.3147,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-openai-bridge.test.js"},{"assertionResults":[{"ancestorTitles":["OpenAI → Claude context mapping"],"fullName":"OpenAI → Claude context mapping does not inject Claude Code system prompt for compatible providers","status":"passed","title":"does not inject Claude Code system prompt for compatible providers","duration":4.808250000000015,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Claude context mapping"],"fullName":"OpenAI → Claude context mapping assistant reasoning_content becomes a thinking block","status":"passed","title":"assistant reasoning_content becomes a thinking block","duration":1.5292910000000006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Claude context mapping"],"fullName":"OpenAI → Claude context mapping tool_choice=none is not turned into auto","status":"passed","title":"tool_choice=none is not turned into auto","duration":0.5632920000000183,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Claude context mapping"],"fullName":"OpenAI → Claude context mapping input_audio content is preserved","status":"passed","title":"input_audio content is preserved","duration":0.6614579999999819,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI → Claude context mapping"],"fullName":"OpenAI → Claude context mapping remote http image_url is preserved","status":"passed","title":"remote http image_url is preserved","duration":0.4367080000000101,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745088,"endTime":1781497745096.4368,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/bugs-toClaude-context.test.js"},{"assertionResults":[{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'alicode': all models OpenAI→target","status":"passed","title":"'alicode': all models OpenAI→target","duration":1.5401669999999967,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'alicode-intl': all models OpenAI→target","status":"passed","title":"'alicode-intl': all models OpenAI→target","duration":0.3819159999999897,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'anthropic': all models OpenAI→target","status":"passed","title":"'anthropic': all models OpenAI→target","duration":0.6794999999999902,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'ag': all models OpenAI→target","status":"passed","title":"'ag': all models OpenAI→target","duration":2.007499999999993,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'assemblyai': all models OpenAI→target","status":"passed","title":"'assemblyai': all models OpenAI→target","duration":0.1619579999999985,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'black-forest-labs': all models OpenAI→target","status":"passed","title":"'black-forest-labs': all models OpenAI→target","duration":0.12641600000000608,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'blackbox': all models OpenAI→target","status":"passed","title":"'blackbox': all models OpenAI→target","duration":0.27883399999998915,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'byteplus': all models OpenAI→target","status":"passed","title":"'byteplus': all models OpenAI→target","duration":0.1635830000000169,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cerebras': all models OpenAI→target","status":"passed","title":"'cerebras': all models OpenAI→target","duration":0.40587499999998045,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cc': all models OpenAI→target","status":"passed","title":"'cc': all models OpenAI→target","duration":0.5622909999999877,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cl': all models OpenAI→target","status":"passed","title":"'cl': all models OpenAI→target","duration":0.17329100000000608,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cloudflare-ai': all models OpenAI→target","status":"passed","title":"'cloudflare-ai': all models OpenAI→target","duration":0.30462499999998727,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cx': all models OpenAI→target","status":"passed","title":"'cx': all models OpenAI→target","duration":0.5545419999999979,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cohere': all models OpenAI→target","status":"passed","title":"'cohere': all models OpenAI→target","duration":1.1602499999999907,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'comfyui': all models OpenAI→target","status":"passed","title":"'comfyui': all models OpenAI→target","duration":0.05275000000000318,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'commandcode': all models OpenAI→target","status":"passed","title":"'commandcode': all models OpenAI→target","duration":2.2671670000000006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'cu': all models OpenAI→target","status":"passed","title":"'cu': all models OpenAI→target","duration":0.5327080000000137,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'deepgram': all models OpenAI→target","status":"passed","title":"'deepgram': all models OpenAI→target","duration":0.07883300000000304,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'deepseek': all models OpenAI→target","status":"passed","title":"'deepseek': all models OpenAI→target","duration":0.08516600000001517,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'fal-ai': all models OpenAI→target","status":"passed","title":"'fal-ai': all models OpenAI→target","duration":0.09375,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'fireworks': all models OpenAI→target","status":"passed","title":"'fireworks': all models OpenAI→target","duration":0.059750000000008185,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'gemini': all models OpenAI→target","status":"passed","title":"'gemini': all models OpenAI→target","duration":0.4443330000000003,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'gc': all models OpenAI→target","status":"passed","title":"'gc': all models OpenAI→target","duration":0.20691700000000424,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'gh': all models OpenAI→target","status":"passed","title":"'gh': all models OpenAI→target","duration":0.26637499999998226,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'glm': all models OpenAI→target","status":"passed","title":"'glm': all models OpenAI→target","duration":0.09554099999999721,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'glm-cn': all models OpenAI→target","status":"passed","title":"'glm-cn': all models OpenAI→target","duration":0.06779099999999971,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'grok-web': all models OpenAI→target","status":"passed","title":"'grok-web': all models OpenAI→target","duration":0.1133339999999805,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'groq': all models OpenAI→target","status":"passed","title":"'groq': all models OpenAI→target","duration":0.08833300000000577,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'huggingface': all models OpenAI→target","status":"passed","title":"'huggingface': all models OpenAI→target","duration":0.056417000000010376,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'hyperbolic': all models OpenAI→target","status":"passed","title":"'hyperbolic': all models OpenAI→target","duration":0.0877089999999896,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'if': all models OpenAI→target","status":"passed","title":"'if': all models OpenAI→target","duration":0.15245800000002419,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'kc': all models OpenAI→target","status":"passed","title":"'kc': all models OpenAI→target","duration":0.09424999999998818,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'kimi': all models OpenAI→target","status":"passed","title":"'kimi': all models OpenAI→target","duration":0.07729100000000244,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'kmc': all models OpenAI→target","status":"passed","title":"'kmc': all models OpenAI→target","duration":0.06441699999999173,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'kr': all models OpenAI→target","status":"passed","title":"'kr': all models OpenAI→target","duration":1.3660830000000033,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'mmf': all models OpenAI→target","status":"passed","title":"'mmf': all models OpenAI→target","duration":0.036000000000001364,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'minimax': all models OpenAI→target","status":"passed","title":"'minimax': all models OpenAI→target","duration":0.18295899999998255,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'minimax-cn': all models OpenAI→target","status":"passed","title":"'minimax-cn': all models OpenAI→target","duration":0.15725000000000477,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'mistral': all models OpenAI→target","status":"passed","title":"'mistral': all models OpenAI→target","duration":0.05583400000000438,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'nanobanana': all models OpenAI→target","status":"passed","title":"'nanobanana': all models OpenAI→target","duration":0.03562500000001023,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'nebius': all models OpenAI→target","status":"passed","title":"'nebius': all models OpenAI→target","duration":0.033959000000010064,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'nvidia': all models OpenAI→target","status":"passed","title":"'nvidia': all models OpenAI→target","duration":0.0689999999999884,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'ollama': all models OpenAI→target","status":"passed","title":"'ollama': all models OpenAI→target","duration":0.48220799999998576,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openai': all models OpenAI→target","status":"passed","title":"'openai': all models OpenAI→target","duration":0.335583999999983,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'opencode-go': all models OpenAI→target","status":"passed","title":"'opencode-go': all models OpenAI→target","duration":0.13745900000000688,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openrouter': all models OpenAI→target","status":"passed","title":"'openrouter': all models OpenAI→target","duration":0.16116700000000606,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'perplexity': all models OpenAI→target","status":"passed","title":"'perplexity': all models OpenAI→target","duration":0.038624999999996135,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'perplexity-web': all models OpenAI→target","status":"passed","title":"'perplexity-web': all models OpenAI→target","duration":0.16929200000001288,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'qd': all models OpenAI→target","status":"passed","title":"'qd': all models OpenAI→target","duration":0.14520900000002257,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'qw': all models OpenAI→target","status":"passed","title":"'qw': all models OpenAI→target","duration":0.05795799999998508,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'recraft': all models OpenAI→target","status":"passed","title":"'recraft': all models OpenAI→target","duration":0.03795800000000327,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'runwayml': all models OpenAI→target","status":"passed","title":"'runwayml': all models OpenAI→target","duration":0.06562500000001137,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'sdwebui': all models OpenAI→target","status":"passed","title":"'sdwebui': all models OpenAI→target","duration":0.03612499999999841,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'siliconflow': all models OpenAI→target","status":"passed","title":"'siliconflow': all models OpenAI→target","duration":0.1613749999999925,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'stability-ai': all models OpenAI→target","status":"passed","title":"'stability-ai': all models OpenAI→target","duration":0.062207999999998265,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'together': all models OpenAI→target","status":"passed","title":"'together': all models OpenAI→target","duration":0.07362499999999272,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'vertex': all models OpenAI→target","status":"passed","title":"'vertex': all models OpenAI→target","duration":0.1759580000000085,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'vertex-partner': all models OpenAI→target","status":"passed","title":"'vertex-partner': all models OpenAI→target","duration":0.05554100000000517,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'volcengine-ark': all models OpenAI→target","status":"passed","title":"'volcengine-ark': all models OpenAI→target","duration":0.09904099999999971,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'voyage-ai': all models OpenAI→target","status":"passed","title":"'voyage-ai': all models OpenAI→target","duration":0.0801670000000172,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'xai': all models OpenAI→target","status":"passed","title":"'xai': all models OpenAI→target","duration":0.06125000000000114,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'xiaomi-mimo': all models OpenAI→target","status":"passed","title":"'xiaomi-mimo': all models OpenAI→target","duration":0.05900000000002592,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'xiaomi-tokenplan': all models OpenAI→target","status":"passed","title":"'xiaomi-tokenplan': all models OpenAI→target","duration":0.11525000000000318,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openai-tts-models': all models OpenAI→target","status":"passed","title":"'openai-tts-models': all models OpenAI→target","duration":0.054250000000024556,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openai-tts-voices': all models OpenAI→target","status":"passed","title":"'openai-tts-voices': all models OpenAI→target","duration":0.12975000000000136,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openrouter-tts-models': all models OpenAI→target","status":"passed","title":"'openrouter-tts-models': all models OpenAI→target","duration":0.04179200000001515,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'openrouter-tts-voices': all models OpenAI→target","status":"passed","title":"'openrouter-tts-voices': all models OpenAI→target","duration":0.1319159999999897,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'elevenlabs-tts-models': all models OpenAI→target","status":"passed","title":"'elevenlabs-tts-models': all models OpenAI→target","duration":0.050333000000023276,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'edge-tts': all models OpenAI→target","status":"passed","title":"'edge-tts': all models OpenAI→target","duration":0.11104199999999764,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'local-device': all models OpenAI→target","status":"passed","title":"'local-device': all models OpenAI→target","duration":0.024541999999996733,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'google-tts': all models OpenAI→target","status":"passed","title":"'google-tts': all models OpenAI→target","duration":0.601083999999986,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'gemini-tts-models': all models OpenAI→target","status":"passed","title":"'gemini-tts-models': all models OpenAI→target","duration":0.034416999999990594,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: every model translates without throwing"],"fullName":"coverage: every model translates without throwing 'gemini-tts-voices': all models OpenAI→target","status":"passed","title":"'gemini-tts-voices': all models OpenAI→target","duration":0.2928750000000093,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: image-strip models drop image content"],"fullName":"coverage: image-strip models drop image content 'kr'/'deepseek-3.2' strips image when strip=[image]","status":"passed","title":"'kr'/'deepseek-3.2' strips image when strip=[image]","duration":0.229582999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["coverage: image-strip models drop image content"],"fullName":"coverage: image-strip models drop image content 'kr'/'qwen3-coder-next' strips image when strip=[image]","status":"passed","title":"'kr'/'qwen3-coder-next' strips image when strip=[image]","duration":0.05229199999999423,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744737,"endTime":1781497744757.2295,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/coverage-all-models.test.js"},{"assertionResults":[{"ancestorTitles":["roundtrip: Claude source preserves core fields → OpenAI"],"fullName":"roundtrip: Claude source preserves core fields → OpenAI system → system role","status":"passed","title":"system → system role","duration":0.8013749999999789,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: Claude source preserves core fields → OpenAI"],"fullName":"roundtrip: Claude source preserves core fields → OpenAI tool_use → assistant.tool_calls with matching id","status":"passed","title":"tool_use → assistant.tool_calls with matching id","duration":0.21670800000001122,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: Claude source preserves core fields → OpenAI"],"fullName":"roundtrip: Claude source preserves core fields → OpenAI tool_result → tool message with matching id","status":"passed","title":"tool_result → tool message with matching id","duration":0.1357500000000016,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: Claude source preserves core fields → OpenAI"],"fullName":"roundtrip: Claude source preserves core fields → OpenAI tool arguments are valid JSON string","status":"passed","title":"tool arguments are valid JSON string","duration":0.4172499999999957,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: OpenAI tools → Claude → keeps tool name"],"fullName":"roundtrip: OpenAI tools → Claude → keeps tool name tool name survives openai→claude","status":"passed","title":"tool name survives openai→claude","duration":0.12758400000001302,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: parallel tool calls keep distinct ids"],"fullName":"roundtrip: parallel tool calls keep distinct ids two tool_calls, two distinct ids","status":"passed","title":"two tool_calls, two distinct ids","duration":0.09441699999999287,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["roundtrip: parallel tool calls keep distinct ids"],"fullName":"roundtrip: parallel tool calls keep distinct ids each tool_call has a matching tool result","status":"passed","title":"each tool_call has a matching tool result","duration":0.10670799999999758,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745892,"endTime":1781497745894.1277,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/format-roundtrip.test.js"},{"assertionResults":[{"ancestorTitles":["GOLDEN request: OpenAI → Claude"],"fullName":"GOLDEN request: OpenAI → Claude full body (system/image/tool/tool_result)","status":"passed","title":"full body (system/image/tool/tool_result)","duration":3.2300419999999974,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN request: OpenAI → Claude"],"fullName":"GOLDEN request: OpenAI → Claude reasoning_effort → thinking budget","status":"passed","title":"reasoning_effort → thinking budget","duration":0.3754590000000064,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN request: OpenAI → Gemini"],"fullName":"GOLDEN request: OpenAI → Gemini full body (system/image/tool/tool_result)","status":"passed","title":"full body (system/image/tool/tool_result)","duration":1.0155839999999898,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN request: OpenAI → Kiro"],"fullName":"GOLDEN request: OpenAI → Kiro full body (image base64 + tool_result)","status":"passed","title":"full body (image base64 + tool_result)","duration":1.6666250000000105,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745201,"endTime":1781497745207.6665,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/golden-request.test.js"},{"assertionResults":[{"ancestorTitles":["GOLDEN response stream: Claude → OpenAI"],"fullName":"GOLDEN response stream: Claude → OpenAI text + thinking + tool_use + usage + finish","status":"passed","title":"text + thinking + tool_use + usage + finish","duration":2.77445800000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN response stream: Gemini → OpenAI"],"fullName":"GOLDEN response stream: Gemini → OpenAI text + thought(no-sig) + functionCall + usage + finish","status":"passed","title":"text + thought(no-sig) + functionCall + usage + finish","duration":0.6568750000000136,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN response stream: Gemini → OpenAI"],"fullName":"GOLDEN response stream: Gemini → OpenAI image output (inlineData → delta.images)","status":"passed","title":"image output (inlineData → delta.images)","duration":0.3387910000000147,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN response stream: Kiro → OpenAI"],"fullName":"GOLDEN response stream: Kiro → OpenAI text + reasoning + toolUse + usage + stop","status":"passed","title":"text + reasoning + toolUse + usage + stop","duration":0.38375000000002046,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN response stream: Ollama → OpenAI"],"fullName":"GOLDEN response stream: Ollama → OpenAI content + thinking + tool_calls + done usage","status":"passed","title":"content + thinking + tool_calls + done usage","duration":1.0436669999999992,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN response stream: OpenAI-Responses (codex) → OpenAI"],"fullName":"GOLDEN response stream: OpenAI-Responses (codex) → OpenAI text + reasoning + tool_call + completed usage","status":"passed","title":"text + reasoning + tool_call + completed usage","duration":1.1626249999999914,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN response stream: OpenAI-Responses (codex) → OpenAI"],"fullName":"GOLDEN response stream: OpenAI-Responses (codex) → OpenAI error event → error chunk (fallback id/created)","status":"passed","title":"error event → error chunk (fallback id/created)","duration":0.19799999999997908,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745325,"endTime":1781497745332.198,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/golden-response-stream.test.js"},{"assertionResults":[{"ancestorTitles":["GOLDEN response stream: CommandCode → OpenAI"],"fullName":"GOLDEN response stream: CommandCode → OpenAI text + reasoning + tool + finish-step usage","status":"passed","title":"text + reasoning + tool + finish-step usage","duration":2.500249999999994,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN response stream: Kiro → OpenAI (finish after tool)"],"fullName":"GOLDEN response stream: Kiro → OpenAI (finish after tool) toolUse then stop — lock current finish_reason behavior","status":"passed","title":"toolUse then stop — lock current finish_reason behavior","duration":0.523083000000014,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN response stream: Ollama → OpenAI (finish after tool)"],"fullName":"GOLDEN response stream: Ollama → OpenAI (finish after tool) tool_calls then done_reason=stop — lock current finish_reason","status":"passed","title":"tool_calls then done_reason=stop — lock current finish_reason","duration":0.3717499999999916,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN passthrough: same format = no translation"],"fullName":"GOLDEN passthrough: same format = no translation response openai→openai returns chunk unchanged","status":"passed","title":"response openai→openai returns chunk unchanged","duration":0.36454100000000267,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN passthrough: same format = no translation"],"fullName":"GOLDEN passthrough: same format = no translation request openai→openai keeps messages (filterToOpenAIFormat normalize)","status":"passed","title":"request openai→openai keeps messages (filterToOpenAIFormat normalize)","duration":0.4329580000000135,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN usage math: Claude prompt = input + cache (lock)"],"fullName":"GOLDEN usage math: Claude prompt = input + cache (lock) prompt_tokens sums input + cache_read + cache_creation","status":"passed","title":"prompt_tokens sums input + cache_read + cache_creation","duration":0.46229200000001924,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745672,"endTime":1781497745677.4624,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/golden-translator-concerns.test.js"},{"assertionResults":[{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) alicode → url (stream + non-stream)","status":"passed","title":"alicode → url (stream + non-stream)","duration":1.5889160000000118,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) alicode-intl → url (stream + non-stream)","status":"passed","title":"alicode-intl → url (stream + non-stream)","duration":0.2955000000000041,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) anthropic → url (stream + non-stream)","status":"passed","title":"anthropic → url (stream + non-stream)","duration":0.18279200000000628,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) assemblyai → url (stream + non-stream)","status":"passed","title":"assemblyai → url (stream + non-stream)","duration":0.16170900000000188,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) blackbox → url (stream + non-stream)","status":"passed","title":"blackbox → url (stream + non-stream)","duration":0.16091599999998607,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) byteplus → url (stream + non-stream)","status":"passed","title":"byteplus → url (stream + non-stream)","duration":0.09704099999999016,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) cerebras → url (stream + non-stream)","status":"passed","title":"cerebras → url (stream + non-stream)","duration":0.13083299999999554,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) chutes → url (stream + non-stream)","status":"passed","title":"chutes → url (stream + non-stream)","duration":0.09000000000000341,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) claude → url (stream + non-stream)","status":"passed","title":"claude → url (stream + non-stream)","duration":0.7322090000000117,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) cline → url (stream + non-stream)","status":"passed","title":"cline → url (stream + non-stream)","duration":0.1520840000000021,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) cloudflare-ai → url (stream + non-stream)","status":"passed","title":"cloudflare-ai → url (stream + non-stream)","duration":0.13470799999998917,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) codebuddy → url (stream + non-stream)","status":"passed","title":"codebuddy → url (stream + non-stream)","duration":0.05612500000000864,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) cohere → url (stream + non-stream)","status":"passed","title":"cohere → url (stream + non-stream)","duration":0.04800000000000182,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) deepgram → url (stream + non-stream)","status":"passed","title":"deepgram → url (stream + non-stream)","duration":0.04629099999999653,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) deepseek → url (stream + non-stream)","status":"passed","title":"deepseek → url (stream + non-stream)","duration":0.044749999999993406,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) fireworks → url (stream + non-stream)","status":"passed","title":"fireworks → url (stream + non-stream)","duration":0.08270799999999667,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) gemini → url (stream + non-stream)","status":"passed","title":"gemini → url (stream + non-stream)","duration":0.1741660000000138,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) gitlab → url (stream + non-stream)","status":"passed","title":"gitlab → url (stream + non-stream)","duration":0.2367089999999905,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) glm → url (stream + non-stream)","status":"passed","title":"glm → url (stream + non-stream)","duration":0.16345800000001987,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) glm-cn → url (stream + non-stream)","status":"passed","title":"glm-cn → url (stream + non-stream)","duration":0.132000000000005,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) groq → url (stream + non-stream)","status":"passed","title":"groq → url (stream + non-stream)","duration":0.11379199999998946,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) hyperbolic → url (stream + non-stream)","status":"passed","title":"hyperbolic → url (stream + non-stream)","duration":0.10858300000001009,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) kilocode → url (stream + non-stream)","status":"passed","title":"kilocode → url (stream + non-stream)","duration":0.10866699999999696,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) kimi → url (stream + non-stream)","status":"passed","title":"kimi → url (stream + non-stream)","duration":0.1123749999999859,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) kimi-coding → url (stream + non-stream)","status":"passed","title":"kimi-coding → url (stream + non-stream)","duration":0.10633300000000645,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) minimax → url (stream + non-stream)","status":"passed","title":"minimax → url (stream + non-stream)","duration":0.1094579999999894,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) minimax-cn → url (stream + non-stream)","status":"passed","title":"minimax-cn → url (stream + non-stream)","duration":0.10074999999997658,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) mistral → url (stream + non-stream)","status":"passed","title":"mistral → url (stream + non-stream)","duration":0.10183299999999917,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) mmf → url (stream + non-stream)","status":"passed","title":"mmf → url (stream + non-stream)","duration":0.10354100000000699,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) nanobanana → url (stream + non-stream)","status":"passed","title":"nanobanana → url (stream + non-stream)","duration":0.10554199999998559,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) nebius → url (stream + non-stream)","status":"passed","title":"nebius → url (stream + non-stream)","duration":0.10154199999999491,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) nvidia → url (stream + non-stream)","status":"passed","title":"nvidia → url (stream + non-stream)","duration":0.11525000000000318,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) ollama → url (stream + non-stream)","status":"passed","title":"ollama → url (stream + non-stream)","duration":0.11195900000001302,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) openai → url (stream + non-stream)","status":"passed","title":"openai → url (stream + non-stream)","duration":0.10616699999999923,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) openrouter → url (stream + non-stream)","status":"passed","title":"openrouter → url (stream + non-stream)","duration":0.10312499999997726,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) perplexity → url (stream + non-stream)","status":"passed","title":"perplexity → url (stream + non-stream)","duration":0.10266599999999926,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) siliconflow → url (stream + non-stream)","status":"passed","title":"siliconflow → url (stream + non-stream)","duration":0.10366700000000151,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) together → url (stream + non-stream)","status":"passed","title":"together → url (stream + non-stream)","duration":0.10412500000001046,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) vercel-ai-gateway → url (stream + non-stream)","status":"passed","title":"vercel-ai-gateway → url (stream + non-stream)","duration":0.10758300000000531,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) volcengine-ark → url (stream + non-stream)","status":"passed","title":"volcengine-ark → url (stream + non-stream)","duration":0.1039169999999956,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) xai → url (stream + non-stream)","status":"passed","title":"xai → url (stream + non-stream)","duration":0.1042500000000075,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildUrl (default executor providers)"],"fullName":"GOLDEN buildUrl (default executor providers) xiaomi-mimo → url (stream + non-stream)","status":"passed","title":"xiaomi-mimo → url (stream + non-stream)","duration":0.09854100000001154,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) alicode → headers (apiKey / oauth)","status":"passed","title":"alicode → headers (apiKey / oauth)","duration":0.9032919999999933,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) alicode-intl → headers (apiKey / oauth)","status":"passed","title":"alicode-intl → headers (apiKey / oauth)","duration":0.22862499999999386,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) anthropic → headers (apiKey / oauth)","status":"passed","title":"anthropic → headers (apiKey / oauth)","duration":0.4243749999999977,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) assemblyai → headers (apiKey / oauth)","status":"passed","title":"assemblyai → headers (apiKey / oauth)","duration":0.19870799999998212,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) blackbox → headers (apiKey / oauth)","status":"passed","title":"blackbox → headers (apiKey / oauth)","duration":0.16954200000000696,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) byteplus → headers (apiKey / oauth)","status":"passed","title":"byteplus → headers (apiKey / oauth)","duration":0.30637500000000273,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) cerebras → headers (apiKey / oauth)","status":"passed","title":"cerebras → headers (apiKey / oauth)","duration":0.2697909999999979,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) chutes → headers (apiKey / oauth)","status":"passed","title":"chutes → headers (apiKey / oauth)","duration":0.17108299999998167,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) claude → headers (apiKey / oauth)","status":"passed","title":"claude → headers (apiKey / oauth)","duration":0.5617090000000076,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) cline → headers (apiKey / oauth)","status":"passed","title":"cline → headers (apiKey / oauth)","duration":0.5082500000000039,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) cloudflare-ai → headers (apiKey / oauth)","status":"passed","title":"cloudflare-ai → headers (apiKey / oauth)","duration":0.20462499999999295,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) codebuddy → headers (apiKey / oauth)","status":"passed","title":"codebuddy → headers (apiKey / oauth)","duration":0.17416700000001129,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) cohere → headers (apiKey / oauth)","status":"passed","title":"cohere → headers (apiKey / oauth)","duration":0.1681250000000034,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) deepgram → headers (apiKey / oauth)","status":"passed","title":"deepgram → headers (apiKey / oauth)","duration":0.1633329999999944,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) deepseek → headers (apiKey / oauth)","status":"passed","title":"deepseek → headers (apiKey / oauth)","duration":0.16312499999997954,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) fireworks → headers (apiKey / oauth)","status":"passed","title":"fireworks → headers (apiKey / oauth)","duration":0.18991700000000833,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) gemini → headers (apiKey / oauth)","status":"passed","title":"gemini → headers (apiKey / oauth)","duration":0.1736669999999947,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) gitlab → headers (apiKey / oauth)","status":"passed","title":"gitlab → headers (apiKey / oauth)","duration":0.14516600000001745,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) glm → headers (apiKey / oauth)","status":"passed","title":"glm → headers (apiKey / oauth)","duration":1.4152919999999938,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) glm-cn → headers (apiKey / oauth)","status":"passed","title":"glm-cn → headers (apiKey / oauth)","duration":0.20041700000001583,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) groq → headers (apiKey / oauth)","status":"passed","title":"groq → headers (apiKey / oauth)","duration":0.1705829999999935,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) hyperbolic → headers (apiKey / oauth)","status":"passed","title":"hyperbolic → headers (apiKey / oauth)","duration":0.15741599999998357,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) kilocode → headers (apiKey / oauth)","status":"passed","title":"kilocode → headers (apiKey / oauth)","duration":0.21187500000002046,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) kimi → headers (apiKey / oauth)","status":"passed","title":"kimi → headers (apiKey / oauth)","duration":0.15887499999999477,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) kimi-coding → headers (apiKey / oauth)","status":"passed","title":"kimi-coding → headers (apiKey / oauth)","duration":0.18070800000000986,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) minimax → headers (apiKey / oauth)","status":"passed","title":"minimax → headers (apiKey / oauth)","duration":0.08241599999999494,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) minimax-cn → headers (apiKey / oauth)","status":"passed","title":"minimax-cn → headers (apiKey / oauth)","duration":0.07200000000000273,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) mistral → headers (apiKey / oauth)","status":"passed","title":"mistral → headers (apiKey / oauth)","duration":0.06116700000001174,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) mmf → headers (apiKey / oauth)","status":"passed","title":"mmf → headers (apiKey / oauth)","duration":0.0619999999999834,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) nanobanana → headers (apiKey / oauth)","status":"passed","title":"nanobanana → headers (apiKey / oauth)","duration":0.055499999999995,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) nebius → headers (apiKey / oauth)","status":"passed","title":"nebius → headers (apiKey / oauth)","duration":0.054291000000006306,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) nvidia → headers (apiKey / oauth)","status":"passed","title":"nvidia → headers (apiKey / oauth)","duration":0.05579199999999673,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) ollama → headers (apiKey / oauth)","status":"passed","title":"ollama → headers (apiKey / oauth)","duration":0.05500000000000682,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) openai → headers (apiKey / oauth)","status":"passed","title":"openai → headers (apiKey / oauth)","duration":0.055833000000006905,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) openrouter → headers (apiKey / oauth)","status":"passed","title":"openrouter → headers (apiKey / oauth)","duration":0.07183299999999804,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) perplexity → headers (apiKey / oauth)","status":"passed","title":"perplexity → headers (apiKey / oauth)","duration":0.05533300000001873,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) siliconflow → headers (apiKey / oauth)","status":"passed","title":"siliconflow → headers (apiKey / oauth)","duration":0.05587499999998613,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) together → headers (apiKey / oauth)","status":"passed","title":"together → headers (apiKey / oauth)","duration":0.05433300000001395,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) vercel-ai-gateway → headers (apiKey / oauth)","status":"passed","title":"vercel-ai-gateway → headers (apiKey / oauth)","duration":0.055999999999983174,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) volcengine-ark → headers (apiKey / oauth)","status":"passed","title":"volcengine-ark → headers (apiKey / oauth)","duration":0.05324999999999136,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) xai → headers (apiKey / oauth)","status":"passed","title":"xai → headers (apiKey / oauth)","duration":0.05379100000001813,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GOLDEN buildHeaders (default executor providers)"],"fullName":"GOLDEN buildHeaders (default executor providers) xiaomi-mimo → headers (apiKey / oauth)","status":"passed","title":"xiaomi-mimo → headers (apiKey / oauth)","duration":0.05316700000000196,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745034,"endTime":1781497745051.0537,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/golden-url-header.test.js"},{"assertionResults":[{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) has at least one active AG connection with refreshToken","status":"skipped","title":"has at least one active AG connection with refreshToken","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) same sessionId → cache hit on repeated call","status":"skipped","title":"same sessionId → cache hit on repeated call","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) different sessionId (same account) → cache still hits (session-independent)","status":"skipped","title":"different sessionId (same account) → cache still hits (session-independent)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) cross-account → cache SHARED (content-based global cache)","status":"skipped","title":"cross-account → cache SHARED (content-based global cache)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) codex-style sessionId vs random sessionId on unique prompt","status":"skipped","title":"codex-style sessionId vs random sessionId on unique prompt","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity cache behavior (real API)"],"fullName":"Antigravity cache behavior (real API) unique prompt (never seen) → explore when cache starts hitting","status":"skipped","title":"unique prompt (never seen) → explore when cache starts hitting","failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497742906,"endTime":1781497742906,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/antigravity-cache.test.js"},{"assertionResults":[{"ancestorTitles":["Antigravity MITM model handling"],"fullName":"Antigravity MITM model handling flags the out-of-box agent/Default model mandatory","status":"failed","title":"flags the out-of-box agent/Default model mandatory","duration":3.108542,"failureMessages":["AssertionError: expected undefined to be true // Object.is equality\n    at /Users/Working/router4/app/tests/unit/antigravity-mitm.test.js:17:86\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity MITM model handling"],"fullName":"Antigravity MITM model handling leaves models not proven auto-sent optional","status":"passed","title":"leaves models not proven auto-sent optional","duration":0.2819590000000005,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity MITM model handling"],"fullName":"Antigravity MITM model handling excludes tab-autocomplete model 'tab_jump_flash_lite_preview' from re-routing","status":"passed","title":"excludes tab-autocomplete model 'tab_jump_flash_lite_preview' from re-routing","duration":0.09350000000000591,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity MITM model handling"],"fullName":"Antigravity MITM model handling excludes tab-autocomplete model 'tab_flash_lite_preview' from re-routing","status":"passed","title":"excludes tab-autocomplete model 'tab_flash_lite_preview' from re-routing","duration":0.16445799999999622,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Antigravity MITM model handling"],"fullName":"Antigravity MITM model handling does not exclude real agent models from re-routing","status":"passed","title":"does not exclude real agent models from re-routing","duration":0.1379169999999874,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743076,"endTime":1781497743080.1646,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/antigravity-mitm.test.js"},{"assertionResults":[{"ancestorTitles":["antigravity oauth client (deduped)"],"fullName":"antigravity oauth client (deduped) shared source holds the canonical credentials","status":"passed","title":"shared source holds the canonical credentials","duration":2.948875000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["antigravity oauth client (deduped)"],"fullName":"antigravity oauth client (deduped) registry transport keeps clientId/clientSecret","status":"passed","title":"registry transport keeps clientId/clientSecret","duration":0.8634999999999877,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["antigravity oauth client (deduped)"],"fullName":"antigravity oauth client (deduped) google client shared by gemini + gemini-cli","status":"passed","title":"google client shared by gemini + gemini-cli","duration":2.8681669999999997,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["antigravity oauth client (deduped)"],"fullName":"antigravity oauth client (deduped) src oauth.js imports shared client + keeps full shape","status":"passed","title":"src oauth.js imports shared client + keeps full shape","duration":1.082250000000002,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745461,"endTime":1781497745469.0823,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/antigravity-oauth-client.test.js"},{"assertionResults":[{"ancestorTitles":["antigravity computeRetryDelay hook (D3)"],"fullName":"antigravity computeRetryDelay hook (D3) uses Retry-After header (seconds → ms) when within cap","status":"passed","title":"uses Retry-After header (seconds → ms) when within cap","duration":0.9103330000000085,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["antigravity computeRetryDelay hook (D3)"],"fullName":"antigravity computeRetryDelay hook (D3) vetoes (false) when Retry-After exceeds cap","status":"passed","title":"vetoes (false) when Retry-After exceeds cap","duration":0.17483300000000668,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["antigravity computeRetryDelay hook (D3)"],"fullName":"antigravity computeRetryDelay hook (D3) parses retry time from error body when no header","status":"passed","title":"parses retry time from error body when no header","duration":0.1621669999999824,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["antigravity computeRetryDelay hook (D3)"],"fullName":"antigravity computeRetryDelay hook (D3) exponential backoff for 429 when no retry info","status":"passed","title":"exponential backoff for 429 when no retry info","duration":0.20912500000000023,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["antigravity computeRetryDelay hook (D3)"],"fullName":"antigravity computeRetryDelay hook (D3) 503 without retry info → veto (no auto backoff)","status":"passed","title":"503 without retry info → veto (no auto backoff)","duration":0.11945800000000872,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["antigravity computeRetryDelay hook (D3)"],"fullName":"antigravity computeRetryDelay hook (D3) buildHeaders includes cached session id after transformRequest","status":"passed","title":"buildHeaders includes cached session id after transformRequest","duration":0.09604100000001381,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497746174,"endTime":1781497746175.2092,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/antigravity-retry-hook.test.js"},{"assertionResults":[{"ancestorTitles":["BaseExecutor.execute — retry by status (config-driven)"],"fullName":"BaseExecutor.execute — retry by status (config-driven) retries 502 `attempts` times then succeeds","status":"passed","title":"retries 502 `attempts` times then succeeds","duration":18.579083999999995,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["BaseExecutor.execute — retry by status (config-driven)"],"fullName":"BaseExecutor.execute — retry by status (config-driven) stops after exhausting 502 attempts on a single url and throws","status":"passed","title":"stops after exhausting 502 attempts on a single url and throws","duration":4.99199999999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["BaseExecutor.execute — baseUrls fallback"],"fullName":"BaseExecutor.execute — baseUrls fallback falls over to the next url on 429 (shouldRetry)","status":"passed","title":"falls over to the next url on 429 (shouldRetry)","duration":1.798833000000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["BaseExecutor.execute — network error retry/fallback"],"fullName":"BaseExecutor.execute — network error retry/fallback maps network exception to 502 retry config","status":"passed","title":"maps network exception to 502 retry config","duration":2.5506249999999966,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["BaseExecutor.execute — network error retry/fallback"],"fullName":"BaseExecutor.execute — network error retry/fallback throws when the only url fails with network error and no retries left","status":"passed","title":"throws when the only url fails with network error and no retries left","duration":0.7341250000000059,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["BaseExecutor.execute — computeRetryDelay hook veto"],"fullName":"BaseExecutor.execute — computeRetryDelay hook veto hook returning false skips retry (uses fallback path)","status":"passed","title":"hook returning false skips retry (uses fallback path)","duration":0.6470000000000198,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744566,"endTime":1781497744595.647,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/base-executor-retry.test.js"},{"assertionResults":[{"ancestorTitles":["PR #1175 - buildOutput filter detection"],"fullName":"PR #1175 - buildOutput filter detection detects npm install output","status":"passed","title":"detects npm install output","duration":1.7120840000000044,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - buildOutput filter detection"],"fullName":"PR #1175 - buildOutput filter detection detects cargo build output (no longer misdetected as git-status)","status":"passed","title":"detects cargo build output (no longer misdetected as git-status)","duration":0.6735829999999936,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - buildOutput compression behavior"],"fullName":"PR #1175 - buildOutput compression behavior compresses npm install with deprecations","status":"passed","title":"compresses npm install with deprecations","duration":0.964500000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - buildOutput compression behavior"],"fullName":"PR #1175 - buildOutput compression behavior compresses cargo build output","status":"passed","title":"compresses cargo build output","duration":0.25858300000000156,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - buildOutput compression behavior"],"fullName":"PR #1175 - buildOutput compression behavior keeps cargo errors verbatim","status":"passed","title":"keeps cargo errors verbatim","duration":0.12204200000000753,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - buildOutput compression behavior"],"fullName":"PR #1175 - buildOutput compression behavior keeps maven BUILD FAILED as error","status":"passed","title":"keeps maven BUILD FAILED as error","duration":0.1530830000000094,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regex fix edge cases"],"fullName":"PR #1175 - porcelain regex fix edge cases git status --porcelain workdir-only (space first char) STILL detects as gitStatus (minimal fix preserved old regex)","status":"passed","title":"git status --porcelain workdir-only (space first char) STILL detects as gitStatus (minimal fix preserved old regex)","duration":0.1834999999999951,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regex fix edge cases"],"fullName":"PR #1175 - porcelain regex fix edge cases git status --porcelain with staged (status code first char) still detects","status":"passed","title":"git status --porcelain with staged (status code first char) still detects","duration":0.0643749999999983,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regex fix edge cases"],"fullName":"PR #1175 - porcelain regex fix edge cases cargo Compiling lines NOT detected as git-status (porcelain false positive fix)","status":"passed","title":"cargo Compiling lines NOT detected as git-status (porcelain false positive fix)","duration":0.36316700000000424,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regex fix edge cases"],"fullName":"PR #1175 - porcelain regex fix edge cases long-form git status with 'On branch' always detects","status":"passed","title":"long-form git status with 'On branch' always detects","duration":0.08691699999999969,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - false positive risks"],"fullName":"PR #1175 - false positive risks generic app log with 'ERROR:' triggers buildOutput (potential false positive)","status":"passed","title":"generic app log with 'ERROR:' triggers buildOutput (potential false positive)","duration":0.5575410000000005,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - false positive risks"],"fullName":"PR #1175 - false positive risks generic 'Compiling templates' (non-build context) triggers buildOutput","status":"passed","title":"generic 'Compiling templates' (non-build context) triggers buildOutput","duration":0.20425000000000182,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - false positive risks"],"fullName":"PR #1175 - false positive risks plain text with no patterns falls through (no false positive)","status":"passed","title":"plain text with no patterns falls through (no false positive)","duration":0.11916700000000446,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - safety: no data corruption"],"fullName":"PR #1175 - safety: no data corruption empty input returns input","status":"passed","title":"empty input returns input","duration":0.09545899999999108,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - safety: no data corruption"],"fullName":"PR #1175 - safety: no data corruption input with only errors preserves all errors","status":"passed","title":"input with only errors preserves all errors","duration":0.05933400000000688,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - safety: no data corruption"],"fullName":"PR #1175 - safety: no data corruption input with no recognized patterns returns input (fallback)","status":"passed","title":"input with no recognized patterns returns input (fallback)","duration":0.04375000000000284,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - safety: no data corruption"],"fullName":"PR #1175 - safety: no data corruption limits warnings to 5 + summary line","status":"passed","title":"limits warnings to 5 + summary line","duration":0.08004100000000847,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745561,"endTime":1781497745568.0955,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/buildOutputFilter.test.js"},{"assertionResults":[{"ancestorTitles":["PR #1175 - priority with overlapping patterns"],"fullName":"PR #1175 - priority with overlapping patterns git-diff wins over buildOutput when both present","status":"passed","title":"git-diff wins over buildOutput when both present","duration":0.9644159999999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - priority with overlapping patterns"],"fullName":"PR #1175 - priority with overlapping patterns git-status (long form) wins over buildOutput","status":"passed","title":"git-status (long form) wins over buildOutput","duration":0.22029100000000312,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - DETECT_WINDOW boundary"],"fullName":"PR #1175 - DETECT_WINDOW boundary build pattern beyond DETECT_WINDOW chars: NOT detected","status":"passed","title":"build pattern beyond DETECT_WINDOW chars: NOT detected","duration":0.635666999999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - DETECT_WINDOW boundary"],"fullName":"PR #1175 - DETECT_WINDOW boundary build pattern at very start: detected","status":"passed","title":"build pattern at very start: detected","duration":0.13295799999998792,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - line endings & whitespace"],"fullName":"PR #1175 - line endings & whitespace CRLF line endings still detect","status":"passed","title":"CRLF line endings still detect","duration":0.07600000000000762,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - line endings & whitespace"],"fullName":"PR #1175 - line endings & whitespace Tab-prefixed Compiling (real cargo output uses leading spaces, not tab)","status":"passed","title":"Tab-prefixed Compiling (real cargo output uses leading spaces, not tab)","duration":0.05995800000000884,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - line endings & whitespace"],"fullName":"PR #1175 - line endings & whitespace Compiling without leading spaces","status":"passed","title":"Compiling without leading spaces","duration":0.1128750000000025,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - adversarial: user code containing build strings"],"fullName":"PR #1175 - adversarial: user code containing build strings user JS code with console.log('npm warn ...') triggers buildOutput","status":"passed","title":"user JS code with console.log('npm warn ...') triggers buildOutput","duration":0.5640000000000072,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - adversarial: user code containing build strings"],"fullName":"PR #1175 - adversarial: user code containing build strings file content with 'BUILD SUCCESS' on its own line triggers buildOutput","status":"passed","title":"file content with 'BUILD SUCCESS' on its own line triggers buildOutput","duration":1.0916249999999934,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - adversarial: user code containing build strings"],"fullName":"PR #1175 - adversarial: user code containing build strings real cargo error spanning multiple lines preserves context","status":"passed","title":"real cargo error spanning multiple lines preserves context","duration":0.27687499999998977,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety input with only progress lines (no errors/warnings/summary) returns input fallback","status":"passed","title":"input with only progress lines (no errors/warnings/summary) returns input fallback","duration":0.16362499999999613,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety input with only Downloading lines","status":"passed","title":"input with only Downloading lines","duration":0.05254200000000253,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety input with ONLY a single ERROR: line","status":"passed","title":"input with ONLY a single ERROR: line","duration":0.04375000000000284,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety unicode/emoji in deprecation warning preserved (minimal fix keeps first 3 verbatim)","status":"passed","title":"unicode/emoji in deprecation warning preserved (minimal fix keeps first 3 verbatim)","duration":0.42991600000000574,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety more than 3 deprecations: keep first 3 verbatim + count rest","status":"passed","title":"more than 3 deprecations: keep first 3 verbatim + count rest","duration":0.09487500000000182,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - corruption safety"],"fullName":"PR #1175 - corruption safety safeApply wraps buildOutput against panics","status":"passed","title":"safeApply wraps buildOutput against panics","duration":0.05741699999998673,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - integration with compressMessages"],"fullName":"PR #1175 - integration with compressMessages npm install output above MIN_COMPRESS_SIZE → compressed","status":"passed","title":"npm install output above MIN_COMPRESS_SIZE → compressed","duration":0.31862499999999727,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - integration with compressMessages"],"fullName":"PR #1175 - integration with compressMessages input below MIN_COMPRESS_SIZE → NOT compressed","status":"passed","title":"input below MIN_COMPRESS_SIZE → NOT compressed","duration":0.07425000000000637,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - integration with compressMessages"],"fullName":"PR #1175 - integration with compressMessages compressed output never grows input (safety guard)","status":"passed","title":"compressed output never grows input (safety guard)","duration":0.0800000000000125,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - integration with compressMessages"],"fullName":"PR #1175 - integration with compressMessages tool_result with is_error:true is NOT compressed (preserve error traces)","status":"passed","title":"tool_result with is_error:true is NOT compressed (preserve error traces)","duration":0.12983400000000245,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regression deeper"],"fullName":"PR #1175 - porcelain regression deeper mixed staged + workdir + untracked porcelain → detected (has status code first char)","status":"passed","title":"mixed staged + workdir + untracked porcelain → detected (has status code first char)","duration":0.047417000000010034,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regression deeper"],"fullName":"PR #1175 - porcelain regression deeper 100% workdir-only porcelain → STILL detects gitStatus (minimal fix preserved old regex)","status":"passed","title":"100% workdir-only porcelain → STILL detects gitStatus (minimal fix preserved old regex)","duration":0.038374999999987836,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - porcelain regression deeper"],"fullName":"PR #1175 - porcelain regression deeper manual gitStatus() call on workdir-only porcelain still parses correctly","status":"passed","title":"manual gitStatus() call on workdir-only porcelain still parses correctly","duration":0.17579200000000128,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - pathological"],"fullName":"PR #1175 - pathological very long single line (no newlines) with build pattern","status":"passed","title":"very long single line (no newlines) with build pattern","duration":0.06050000000000466,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - pathological"],"fullName":"PR #1175 - pathological 10000 Compiling lines don't crash","status":"passed","title":"10000 Compiling lines don't crash","duration":6.193375000000003,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - pathological"],"fullName":"PR #1175 - pathological input with only newlines","status":"passed","title":"input with only newlines","duration":0.08358299999999019,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PR #1175 - pathological"],"fullName":"PR #1175 - pathological null/undefined safety via safeApply","status":"passed","title":"null/undefined safety via safeApply","duration":0.28562500000001023,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744730,"endTime":1781497744743.2856,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/buildOutputFilterAdversarial.test.js"},{"assertionResults":[{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools suffixes client tool names and maps them back","status":"passed","title":"suffixes client tool names and maps them back","duration":0.9414170000000013,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools suffixes a forced tool_choice to match the renamed tool","status":"passed","title":"suffixes a forced tool_choice to match the renamed tool","duration":0.3693750000000193,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools suffixes only the chosen tool when several are present","status":"passed","title":"suffixes only the chosen tool when several are present","duration":0.14179099999998357,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools leaves non-forced tool_choice untouched","status":"passed","title":"leaves non-forced tool_choice untouched","duration":0.17320900000001416,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools does not suffix a forced choice that targets a non-client (decoy/built-in) tool","status":"passed","title":"does not suffix a forced choice that targets a non-client (decoy/built-in) tool","duration":0.07850000000001955,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools renames tool_use names in message history","status":"passed","title":"renames tool_use names in message history","duration":0.0681250000000091,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["cloakClaudeTools"],"fullName":"cloakClaudeTools returns the body unchanged when there are no tools","status":"passed","title":"returns the body unchanged when there are no tools","duration":0.18104199999999082,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745666,"endTime":1781497745668.1812,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/claude-cloaking.test.js"},{"assertionResults":[{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache returns null before any headers are cached (cold start)","status":"passed","title":"returns null before any headers are cached (cold start)","duration":13.243291,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache caches headers when user-agent contains 'claude-code'","status":"passed","title":"caches headers when user-agent contains 'claude-code'","duration":1.2785419999999874,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache caches headers when user-agent contains 'claude-cli'","status":"passed","title":"caches headers when user-agent contains 'claude-cli'","duration":0.48799999999999955,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache caches headers when x-app is 'cli' (regardless of user-agent)","status":"passed","title":"caches headers when x-app is 'cli' (regardless of user-agent)","duration":0.392832999999996,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache does NOT cache headers for non-Claude clients","status":"passed","title":"does NOT cache headers for non-Claude clients","duration":0.23779199999998468,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache refreshes cache on each matching request","status":"passed","title":"refreshes cache on each matching request","duration":0.29958299999998417,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache ignores calls with null or non-object headers","status":"passed","title":"ignores calls with null or non-object headers","duration":0.3752089999999839,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["claudeHeaderCache"],"fullName":"claudeHeaderCache only stores keys that are actually present in the headers object","status":"passed","title":"only stores keys that are actually present in the headers object","duration":0.44370900000001257,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider overlays live cached headers over static provider defaults","status":"passed","title":"overlays live cached headers over static provider defaults","duration":401.45075,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider removes conflicting Title-Case static keys when cached lowercase keys exist","status":"passed","title":"removes conflicting Title-Case static keys when cached lowercase keys exist","duration":9.436374999999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider sets x-api-key auth when apiKey is provided","status":"passed","title":"sets x-api-key auth when apiKey is provided","duration":9.251499999999965,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider sets Bearer Authorization when only accessToken is provided","status":"passed","title":"sets Bearer Authorization when only accessToken is provided","duration":5.920749999999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider includes Accept: text/event-stream when stream=true","status":"passed","title":"includes Accept: text/event-stream when stream=true","duration":5.748541000000046,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider"],"fullName":"DefaultExecutor.buildHeaders() — claude provider omits Accept: text/event-stream when stream=false","status":"passed","title":"omits Accept: text/event-stream when stream=false","duration":6.744332999999983,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider cold start (no cache)"],"fullName":"DefaultExecutor.buildHeaders() — claude provider cold start (no cache) falls back to static provider headers when cache is empty","status":"passed","title":"falls back to static provider headers when cache is empty","duration":9.551750000000084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — claude provider cold start (no cache)"],"fullName":"DefaultExecutor.buildHeaders() — claude provider cold start (no cache) does not throw when cache returns null","status":"passed","title":"does not throw when cache returns null","duration":4.636792000000014,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — anthropic-compatible stripping"],"fullName":"DefaultExecutor.buildHeaders() — anthropic-compatible stripping strips x-app and anthropic-dangerous-direct-browser-access for non-Anthropic host","status":"passed","title":"strips x-app and anthropic-dangerous-direct-browser-access for non-Anthropic host","duration":5.249957999999992,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — anthropic-compatible stripping"],"fullName":"DefaultExecutor.buildHeaders() — anthropic-compatible stripping removes claude-code-20250219 from anthropic-beta for non-Anthropic host","status":"passed","title":"removes claude-code-20250219 from anthropic-beta for non-Anthropic host","duration":6.692584000000011,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — anthropic-compatible stripping"],"fullName":"DefaultExecutor.buildHeaders() — anthropic-compatible stripping keeps other beta flags intact after stripping","status":"passed","title":"keeps other beta flags intact after stripping","duration":4.507333000000017,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — anthropic-compatible stripping"],"fullName":"DefaultExecutor.buildHeaders() — anthropic-compatible stripping does NOT strip headers when baseUrl is api.anthropic.com","status":"passed","title":"does NOT strip headers when baseUrl is api.anthropic.com","duration":5.089665999999966,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DefaultExecutor.buildHeaders() — anthropic-compatible stripping"],"fullName":"DefaultExecutor.buildHeaders() — anthropic-compatible stripping does NOT strip headers when baseUrl is empty (defaults to Anthropic)","status":"passed","title":"does NOT strip headers when baseUrl is empty (defaults to Anthropic)","duration":4.920790999999895,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["proxyAwareFetch — api.anthropic.com routing"],"fullName":"proxyAwareFetch — api.anthropic.com routing routes api.anthropic.com to gotScraping (non-streaming) and returns ok response","status":"failed","title":"routes api.anthropic.com to gotScraping (non-streaming) and returns ok response","duration":434.6886250000001,"failureMessages":["AssertionError: expected \"vi.fn()\" to be called once, but got 0 times\n    at /Users/Working/router4/app/tests/unit/claude-header-forwarding.test.js:354:25\n    at processTicksAndRejections (node:internal/process/task_queues:105:5)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["proxyAwareFetch — api.anthropic.com routing"],"fullName":"proxyAwareFetch — api.anthropic.com routing falls back gracefully when got-scraping throws on non-streaming path","status":"passed","title":"falls back gracefully when got-scraping throws on non-streaming path","duration":8.306916999999885,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["proxyAwareFetch — api.anthropic.com routing"],"fullName":"proxyAwareFetch — api.anthropic.com routing does NOT route non-Anthropic hosts through gotScraping","status":"passed","title":"does NOT route non-Anthropic hosts through gotScraping","duration":2.2377910000000156,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743088,"endTime":1781497744030.2378,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/claude-header-forwarding.test.js"},{"assertionResults":[{"ancestorTitles":["CodexExecutor image handling"],"fullName":"CodexExecutor image handling fetches 1MB remote image and inlines it as base64 data URI","status":"passed","title":"fetches 1MB remote image and inlines it as base64 data URI","duration":3.8890829999999994,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["CodexExecutor image handling"],"fullName":"CodexExecutor image handling passes through existing data URIs without calling fetch","status":"passed","title":"passes through existing data URIs without calling fetch","duration":0.40529200000000287,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["CodexExecutor image handling"],"fullName":"CodexExecutor image handling falls back to original URL when remote fetch fails","status":"passed","title":"falls back to original URL when remote fetch fails","duration":0.30504199999998605,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["CodexExecutor image handling"],"fullName":"CodexExecutor image handling execute() prefetches images before sending to upstream","status":"passed","title":"execute() prefetches images before sending to upstream","duration":22.720083000000017,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744486,"endTime":1781497744513.72,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/codex-image-fetch.test.js"},{"assertionResults":[{"ancestorTitles":["Codex Refresh Token","refreshCodexToken"],"fullName":"Codex Refresh Token refreshCodexToken should return new refresh_token when server provides one (token rotation)","status":"passed","title":"should return new refresh_token when server provides one (token rotation)","duration":71.50587500000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","refreshCodexToken"],"fullName":"Codex Refresh Token refreshCodexToken should keep old refresh_token when server does not return new one","status":"passed","title":"should keep old refresh_token when server does not return new one","duration":5.32650000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","CodexExecutor credential lifecycle"],"fullName":"Codex Refresh Token CodexExecutor credential lifecycle should refresh Codex credentials and preserve omitted id_token","status":"passed","title":"should refresh Codex credentials and preserve omitted id_token","duration":17.745959,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","CodexExecutor credential lifecycle"],"fullName":"Codex Refresh Token CodexExecutor credential lifecycle should refresh Codex when lastRefreshAt is older than the upstream stale window","status":"passed","title":"should refresh Codex when lastRefreshAt is older than the upstream stale window","duration":5.433375000000012,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","CodexExecutor credential lifecycle"],"fullName":"Codex Refresh Token CodexExecutor credential lifecycle should de-duplicate concurrent refreshes for the same Codex connection","status":"passed","title":"should de-duplicate concurrent refreshes for the same Codex connection","duration":7.746082999999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","getRefreshLeadMs (early refresh config)"],"fullName":"Codex Refresh Token getRefreshLeadMs (early refresh config) should return provider-specific lead time for OAuth providers","status":"passed","title":"should return provider-specific lead time for OAuth providers","duration":5.812375000000003,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","getRefreshLeadMs (early refresh config)"],"fullName":"Codex Refresh Token getRefreshLeadMs (early refresh config) should fallback to default buffer for unknown providers","status":"passed","title":"should fallback to default buffer for unknown providers","duration":4.4067079999999805,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Codex Refresh Token","getRefreshLeadMs (early refresh config)"],"fullName":"Codex Refresh Token getRefreshLeadMs (early refresh config) codex lead should be greater than default buffer","status":"passed","title":"codex lead should be greater than default buffer","duration":5.317875000000015,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744041,"endTime":1781497744165.3179,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/codex-refresh-token.test.js"},{"assertionResults":[{"ancestorTitles":["combo round-robin routing"],"fullName":"combo round-robin routing keeps existing one-request round-robin behavior by default","status":"passed","title":"keeps existing one-request round-robin behavior by default","duration":1.1964159999999993,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["combo round-robin routing"],"fullName":"combo round-robin routing sticks to each combo model for the configured number of requests","status":"passed","title":"sticks to each combo model for the configured number of requests","duration":0.25079100000000665,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["combo round-robin routing"],"fullName":"combo round-robin routing tracks sticky rotation independently per combo","status":"passed","title":"tracks sticky rotation independently per combo","duration":0.18804199999999582,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["combo round-robin routing"],"fullName":"combo round-robin routing does not rotate fallback combos","status":"passed","title":"does not rotate fallback combos","duration":0.21945800000000304,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745796,"endTime":1781497745798.2195,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/combo-routing.test.js"},{"assertionResults":[{"ancestorTitles":["commandcode-to-openai — text-delta"],"fullName":"commandcode-to-openai — text-delta emits assistant role on first delta then content-only","status":"passed","title":"emits assistant role on first delta then content-only","duration":2.4240000000000066,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — reasoning-delta"],"fullName":"commandcode-to-openai — reasoning-delta maps reasoning-delta to reasoning_content delta","status":"passed","title":"maps reasoning-delta to reasoning_content delta","duration":0.22212500000000546,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — tool-input-* with id field (live schema)"],"fullName":"commandcode-to-openai — tool-input-* with id field (live schema) registers tool index using event.id (NOT toolCallId)","status":"passed","title":"registers tool index using event.id (NOT toolCallId)","duration":0.204291000000012,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — tool-input-* with id field (live schema)"],"fullName":"commandcode-to-openai — tool-input-* with id field (live schema) ignores tool-input-delta when id is unknown (no prior start)","status":"passed","title":"ignores tool-input-delta when id is unknown (no prior start)","duration":0.069500000000005,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — final tool-call event"],"fullName":"commandcode-to-openai — final tool-call event does NOT re-emit tool_calls when tool-input-* deltas already fired","status":"passed","title":"does NOT re-emit tool_calls when tool-input-* deltas already fired","duration":0.24575000000001523,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — final tool-call event"],"fullName":"commandcode-to-openai — final tool-call event emits a consolidated tool_calls when only the final tool-call event arrives","status":"passed","title":"emits a consolidated tool_calls when only the final tool-call event arrives","duration":0.11754099999998857,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — finish"],"fullName":"commandcode-to-openai — finish emits a final chunk with finish_reason=tool_calls when finishReason is tool-calls","status":"passed","title":"emits a final chunk with finish_reason=tool_calls when finishReason is tool-calls","duration":0.14683299999998667,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — finish"],"fullName":"commandcode-to-openai — finish includes usage on the final chunk when totalUsage provided","status":"passed","title":"includes usage on the final chunk when totalUsage provided","duration":0.3611669999999947,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["commandcode-to-openai — error event"],"fullName":"commandcode-to-openai — error event stringifies object errors so client sees readable message","status":"passed","title":"stringifies object errors so client sees readable message","duration":0.4736249999999984,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745860,"endTime":1781497745865.4736,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/commandcode-to-openai.test.js"},{"assertionResults":[{"ancestorTitles":["compatible provider connections API"],"fullName":"compatible provider connections API creates one API-key connection for an OpenAI-compatible node","status":"passed","title":"creates one API-key connection for an OpenAI-compatible node","duration":153.804708,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["compatible provider connections API"],"fullName":"compatible provider connections API creates one API-key connection for an Anthropic-compatible node","status":"passed","title":"creates one API-key connection for an Anthropic-compatible node","duration":12.123792000000009,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["compatible provider connections API"],"fullName":"compatible provider connections API returns 400 for a duplicate connection on the same compatible node","status":"passed","title":"returns 400 for a duplicate connection on the same compatible node","duration":12.209874999999982,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743624,"endTime":1781497743802.21,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/compatible-provider-connections.test.js"},{"assertionResults":[{"ancestorTitles":["CursorExecutor Composer thinking-field responses"],"fullName":"CursorExecutor Composer thinking-field responses uses visible content after </think> for non-streaming Composer responses","status":"passed","title":"uses visible content after </think> for non-streaming Composer responses","duration":12.16758299999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["CursorExecutor Composer thinking-field responses"],"fullName":"CursorExecutor Composer thinking-field responses streams only visible content after </think> for Composer responses","status":"passed","title":"streams only visible content after </think> for Composer responses","duration":0.9765419999999949,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["CursorExecutor Composer thinking-field responses"],"fullName":"CursorExecutor Composer thinking-field responses does not treat thinking as visible output for non-Composer models","status":"passed","title":"does not treat thinking as visible output for non-Composer models","duration":0.2868750000000091,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744993,"endTime":1781497745006.2869,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/cursor-composer-thinking.test.js"},{"assertionResults":[{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access allows loopback public LLM API without API key","status":"passed","title":"allows loopback public LLM API without API key","duration":11.345667000000006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access rejects remote rewritten public LLM API without API key","status":"passed","title":"rejects remote rewritten public LLM API without API key","duration":0.40787499999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access allows loopback rewritten public LLM API without API key","status":"passed","title":"allows loopback rewritten public LLM API without API key","duration":0.20650000000000546,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access rejects remote beta public LLM API without API key","status":"passed","title":"rejects remote beta public LLM API without API key","duration":0.22237500000001376,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access rejects remote rewritten beta public LLM API without API key","status":"passed","title":"rejects remote rewritten beta public LLM API without API key","duration":0.22887500000000216,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access allows remote public LLM API with valid bearer API key","status":"passed","title":"allows remote public LLM API with valid bearer API key","duration":0.5850839999999948,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access allows remote public LLM API with valid x-api-key","status":"passed","title":"allows remote public LLM API with valid x-api-key","duration":0.3187500000000085,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard public LLM API access"],"fullName":"dashboard guard public LLM API access allows remote rewritten beta public LLM API with valid API key","status":"passed","title":"allows remote rewritten beta public LLM API with valid API key","duration":0.1506249999999909,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access rejects local-only route from non-loopback host without CLI token","status":"passed","title":"rejects local-only route from non-loopback host without CLI token","duration":0.38112499999999727,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access rejects local-only route on loopback when requireLogin=true and no JWT","status":"passed","title":"rejects local-only route on loopback when requireLogin=true and no JWT","duration":0.2264160000000004,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access allows local-only route on loopback when requireLogin=false","status":"passed","title":"allows local-only route on loopback when requireLogin=false","duration":0.19950000000000045,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access rejects local-only route from tunnel host even when requireLogin=false","status":"passed","title":"rejects local-only route from tunnel host even when requireLogin=false","duration":0.07450000000000045,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access rejects local-only route when Origin is non-loopback (CSRF block)","status":"passed","title":"rejects local-only route when Origin is non-loopback (CSRF block)","duration":0.07295899999999733,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard local-only access"],"fullName":"dashboard guard local-only access allows local-only route with valid CLI token","status":"passed","title":"allows local-only route with valid CLI token","duration":0.07587499999999636,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["dashboard guard helpers"],"fullName":"dashboard guard helpers extracts bearer API keys before x-api-key","status":"passed","title":"extracts bearer API keys before x-api-key","duration":0.059749999999993975,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744865,"endTime":1781497744880.076,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/dashboard-guard.test.js"},{"assertionResults":[{"ancestorTitles":["DB Benchmark — SQLite vs Lowdb"],"fullName":"DB Benchmark — SQLite vs Lowdb INSERT 500 provider connections","status":"passed","title":"INSERT 500 provider connections","duration":1194.752958,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Benchmark — SQLite vs Lowdb"],"fullName":"DB Benchmark — SQLite vs Lowdb READ 200 filtered queries","status":"passed","title":"READ 200 filtered queries","duration":520.2736670000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Benchmark — SQLite vs Lowdb"],"fullName":"DB Benchmark — SQLite vs Lowdb READ 200 by id (point lookup)","status":"passed","title":"READ 200 by id (point lookup)","duration":458.4993750000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Benchmark — SQLite vs Lowdb"],"fullName":"DB Benchmark — SQLite vs Lowdb saveRequestUsage 500 entries","status":"passed","title":"saveRequestUsage 500 entries","duration":1408.084792,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Benchmark — SQLite vs Lowdb"],"fullName":"DB Benchmark — SQLite vs Lowdb getUsageStats(24h) repeat 50x","status":"passed","title":"getUsageStats(24h) repeat 50x","duration":507.4391249999999,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743387,"endTime":1781497747476.4392,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/db-benchmark.test.js"},{"assertionResults":[{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety 100 parallel saveRequestUsage → no count loss","status":"passed","title":"100 parallel saveRequestUsage → no count loss","duration":23.122333999999967,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety 200 parallel saveRequestDetail → all flushed","status":"passed","title":"200 parallel saveRequestDetail → all flushed","duration":6004.98225,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety mixed concurrent: usage + details + connections + aliases","status":"passed","title":"mixed concurrent: usage + details + connections + aliases","duration":21.913375000000087,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety updateSettings parallel → no merge loss","status":"passed","title":"updateSettings parallel → no merge loss","duration":2.7496659999997064,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety OAuth refresh race: parallel updateProviderConnection on same id","status":"passed","title":"OAuth refresh race: parallel updateProviderConnection on same id","duration":1.968499999999949,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety addCustomModel race: parallel duplicate adds → only 1 inserted","status":"passed","title":"addCustomModel race: parallel duplicate adds → only 1 inserted","duration":0.5107500000003711,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety updatePricing race: parallel adds different models → all merged","status":"passed","title":"updatePricing race: parallel adds different models → all merged","duration":2.3576249999996435,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB Concurrency — atomic safety"],"fullName":"DB Concurrency — atomic safety daily summary aggregates correctly under parallel writes","status":"passed","title":"daily summary aggregates correctly under parallel writes","duration":8.111417000000074,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743380,"endTime":1781497749446.1113,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/db-concurrent.test.js"},{"assertionResults":[{"ancestorTitles":["Driver fallback chain"],"fullName":"Driver fallback chain default → picks better-sqlite3 when available","status":"passed","title":"default → picks better-sqlite3 when available","duration":18.590333,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Driver fallback chain"],"fullName":"Driver fallback chain falls back to node:sqlite when better-sqlite3 unavailable","status":"passed","title":"falls back to node:sqlite when better-sqlite3 unavailable","duration":9.896625,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Driver fallback chain"],"fullName":"Driver fallback chain falls back to sql.js when both native drivers unavailable","status":"passed","title":"falls back to sql.js when both native drivers unavailable","duration":41.571499999999986,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743956,"endTime":1781497744026.5715,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/db-driver-chain.test.js"},{"assertionResults":[{"ancestorTitles":["Schema migrations"],"fullName":"Schema migrations fresh DB → applies migrations & stamps schemaVersion","status":"passed","title":"fresh DB → applies migrations & stamps schemaVersion","duration":25.217416999999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Schema migrations"],"fullName":"Schema migrations existing DB at older schemaVersion → re-applies pending migrations on restart","status":"passed","title":"existing DB at older schemaVersion → re-applies pending migrations on restart","duration":10.831708000000006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Schema migrations"],"fullName":"Schema migrations fresh DB + legacy db.json → imports data automatically","status":"passed","title":"fresh DB + legacy db.json → imports data automatically","duration":7.295833000000016,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Schema migrations"],"fullName":"Schema migrations auto-sync re-creates missing index when DB lacks it","status":"passed","title":"auto-sync re-creates missing index when DB lacks it","duration":7.034208000000007,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744149,"endTime":1781497744199.0342,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/db-migration-chain.test.js"},{"assertionResults":[{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity settings: get → defaults; update → merge","status":"passed","title":"settings: get → defaults; update → merge","duration":1.102499999999992,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity isCloudEnabled reflects settings","status":"passed","title":"isCloudEnabled reflects settings","duration":0.3603339999999946,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity apiKeys: create/get/validate/delete","status":"passed","title":"apiKeys: create/get/validate/delete","duration":5.940334000000007,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity providerConnections: CRUD + reorder by priority","status":"passed","title":"providerConnections: CRUD + reorder by priority","duration":2.221416000000005,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity providerConnections: optional fields persisted via JSON column","status":"passed","title":"providerConnections: optional fields persisted via JSON column","duration":0.643084000000016,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity providerNodes: CRUD","status":"passed","title":"providerNodes: CRUD","duration":0.5239159999999856,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity proxyPools: CRUD with sort by updatedAt desc","status":"passed","title":"proxyPools: CRUD with sort by updatedAt desc","duration":11.301040999999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity combos: CRUD","status":"passed","title":"combos: CRUD","duration":0.5484170000000006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity modelAliases: KV ops","status":"passed","title":"modelAliases: KV ops","duration":0.5910000000000082,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity customModels: add/list/delete with dedupe","status":"passed","title":"customModels: add/list/delete with dedupe","duration":0.4903750000000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity mitmAlias: get/set per tool","status":"passed","title":"mitmAlias: get/set per tool","duration":0.270165999999989,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity disabledModels: add/remove per provider","status":"passed","title":"disabledModels: add/remove per provider","duration":0.8153340000000071,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity usage: saveRequestUsage + getUsageHistory + getUsageStats","status":"passed","title":"usage: saveRequestUsage + getUsageHistory + getUsageStats","duration":3.277417000000014,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity usage: pending tracking in-memory","status":"passed","title":"usage: pending tracking in-memory","duration":12.298000000000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity requestDetails: save → query with paging","status":"passed","title":"requestDetails: save → query with paging","duration":201.92520799999997,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity exportDb / importDb roundtrip","status":"passed","title":"exportDb / importDb roundtrip","duration":1.1673339999999826,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity pricing: user pricing merged with constants","status":"passed","title":"pricing: user pricing merged with constants","duration":1.464917000000014,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity getChartData: 24h buckets","status":"passed","title":"getChartData: 24h buckets","duration":1.7257079999999974,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["DB SQLite layer — public API parity"],"fullName":"DB SQLite layer — public API parity getChartData: 7d buckets","status":"passed","title":"getChartData: 7d buckets","duration":1.2842919999999935,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743819,"endTime":1781497744068.2842,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/db-sqlite-vs-lowdb.test.js"},{"assertionResults":[],"startTime":1781497742906,"endTime":1781497742906,"status":"failed","message":"Cannot find module '/cloud/src/handlers/embeddings.js' imported from /Users/Working/router4/app/tests/unit/embeddings.cloud.test.js","name":"/Users/Working/router4/app/tests/unit/embeddings.cloud.test.js"},{"assertionResults":[{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody single string input — includes model and input, default encoding_format=float","status":"passed","title":"single string input — includes model and input, default encoding_format=float","duration":14.96350000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody array input — passes array as-is","status":"passed","title":"array input — passes array as-is","duration":0.8353749999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody custom encoding_format is forwarded","status":"passed","title":"custom encoding_format is forwarded","duration":0.5032500000000084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody no encoding_format in body → defaults to float","status":"passed","title":"no encoding_format in body → defaults to float","duration":0.3033750000000168,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody gemini single input forwards dimensions as outputDimensionality","status":"passed","title":"gemini single input forwards dimensions as outputDimensionality","duration":0.7035000000000196,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsBody"],"fullName":"buildEmbeddingsBody gemini batch input forwards dimensions on each request","status":"passed","title":"gemini batch input forwards dimensions on each request","duration":0.7497499999999775,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl openai → https://api.openai.com/v1/embeddings","status":"passed","title":"openai → https://api.openai.com/v1/embeddings","duration":0.4544999999999959,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl openrouter → https://openrouter.ai/api/v1/embeddings","status":"passed","title":"openrouter → https://openrouter.ai/api/v1/embeddings","duration":0.2414590000000203,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl vercel-ai-gateway → https://ai-gateway.vercel.sh/v1/embeddings","status":"passed","title":"vercel-ai-gateway → https://ai-gateway.vercel.sh/v1/embeddings","duration":0.8683749999999861,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl openai-compatible-* → uses baseUrl from providerSpecificData","status":"passed","title":"openai-compatible-* → uses baseUrl from providerSpecificData","duration":0.3087910000000136,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl openai-compatible-* strips trailing slash from baseUrl","status":"passed","title":"openai-compatible-* strips trailing slash from baseUrl","duration":0.39629099999999085,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl openai-compatible-* without baseUrl → falls back to api.openai.com","status":"passed","title":"openai-compatible-* without baseUrl → falls back to api.openai.com","duration":0.19641699999999673,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl unsupported provider (e.g. gemini-cli) → 400 error, no fetch called","status":"passed","title":"unsupported provider (e.g. gemini-cli) → 400 error, no fetch called","duration":0.3387920000000122,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsUrl"],"fullName":"buildEmbeddingsUrl antigravity (non-openai-compatible, no URL mapping) → 400","status":"passed","title":"antigravity (non-openai-compatible, no URL mapping) → 400","duration":0.13645800000000463,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsHeaders"],"fullName":"buildEmbeddingsHeaders openai → Authorization: Bearer, Content-Type: application/json","status":"passed","title":"openai → Authorization: Bearer, Content-Type: application/json","duration":0.19033300000000963,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsHeaders"],"fullName":"buildEmbeddingsHeaders openai — uses accessToken when apiKey is absent","status":"passed","title":"openai — uses accessToken when apiKey is absent","duration":0.23954100000000267,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsHeaders"],"fullName":"buildEmbeddingsHeaders openrouter → adds HTTP-Referer and X-Title headers","status":"passed","title":"openrouter → adds HTTP-Referer and X-Title headers","duration":0.17924999999999613,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildEmbeddingsHeaders"],"fullName":"buildEmbeddingsHeaders openai-compatible-* → Authorization: Bearer only (no extra headers)","status":"passed","title":"openai-compatible-* → Authorization: Bearer only (no extra headers)","duration":0.17229199999999878,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation missing input → 400 Bad Request","status":"passed","title":"missing input → 400 Bad Request","duration":0.14400000000000546,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation input is a number → 400 Bad Request","status":"passed","title":"input is a number → 400 Bad Request","duration":0.12041700000000333,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation input is an object → 400 Bad Request","status":"passed","title":"input is an object → 400 Bad Request","duration":0.1479580000000169,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation input is null → 400 Bad Request","status":"passed","title":"input is null → 400 Bad Request","duration":0.17558299999998894,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation empty string input passes validation","status":"passed","title":"empty string input passes validation","duration":0.1440409999999872,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — input validation"],"fullName":"handleEmbeddingsCore — input validation empty array input passes validation and reaches provider","status":"passed","title":"empty array input passes validation and reaches provider","duration":0.1974999999999909,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path returns success=true with Response on 200","status":"passed","title":"returns success=true with Response on 200","duration":0.223542000000009,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path response body is valid OpenAI-format JSON","status":"passed","title":"response body is valid OpenAI-format JSON","duration":0.24145899999999187,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path response includes CORS header Access-Control-Allow-Origin: *","status":"passed","title":"response includes CORS header Access-Control-Allow-Origin: *","duration":0.18454199999999332,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path response Content-Type is application/json","status":"passed","title":"response Content-Type is application/json","duration":0.17466599999997356,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path calls onRequestSuccess callback on success","status":"passed","title":"calls onRequestSuccess callback on success","duration":0.1364590000000021,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path does not call onRequestSuccess on provider error","status":"passed","title":"does not call onRequestSuccess on provider error","duration":0.23904199999998355,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — success path"],"fullName":"handleEmbeddingsCore — success path provider response with non-standard format is passed through as-is","status":"passed","title":"provider response with non-standard format is passed through as-is","duration":0.19412500000001387,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling provider 400 → returns success=false with status 400","status":"passed","title":"provider 400 → returns success=false with status 400","duration":0.1668329999999969,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling provider 429 → returns success=false with status 429","status":"passed","title":"provider 429 → returns success=false with status 429","duration":0.2126249999999743,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling provider 500 → returns success=false with status 500","status":"passed","title":"provider 500 → returns success=false with status 500","duration":0.14108300000000895,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling network error (fetch throws) → returns 502 Bad Gateway","status":"passed","title":"network error (fetch throws) → returns 502 Bad Gateway","duration":0.16591599999998152,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling invalid JSON from provider → returns 502","status":"passed","title":"invalid JSON from provider → returns 502","duration":0.16704200000000924,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — provider error handling"],"fullName":"handleEmbeddingsCore — provider error handling error result response has OpenAI-format error body","status":"passed","title":"error result response has OpenAI-format error body","duration":0.16045800000000554,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — token refresh on 401/403"],"fullName":"handleEmbeddingsCore — token refresh on 401/403 on 401, attempts retry after refresh; succeeds if refresh gives new token","status":"passed","title":"on 401, attempts retry after refresh; succeeds if refresh gives new token","duration":0.2124589999999955,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleEmbeddingsCore — token refresh on 401/403"],"fullName":"handleEmbeddingsCore — token refresh on 401/403 on 401 with no refresh token, falls back gracefully (no crash)","status":"passed","title":"on 401 with no refresh token, falls back gracefully (no crash)","duration":0.1518339999999796,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744367,"endTime":1781497744393.2124,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/embeddingsCore.test.js"},{"assertionResults":[{"ancestorTitles":["compat base URLs / version"],"fullName":"compat base URLs / version OPENAI_COMPAT_BASE","status":"passed","title":"OPENAI_COMPAT_BASE","duration":0.9344170000000105,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["compat base URLs / version"],"fullName":"compat base URLs / version ANTHROPIC_COMPAT_BASE","status":"passed","title":"ANTHROPIC_COMPAT_BASE","duration":0.1442920000000072,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["compat base URLs / version"],"fullName":"compat base URLs / version ANTHROPIC_API_VERSION","status":"passed","title":"ANTHROPIC_API_VERSION","duration":0.07337499999999864,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["default token limits"],"fullName":"default token limits max/min","status":"passed","title":"max/min","duration":0.14066599999999596,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["provider baseUrl const (full path, no trailing slash)"],"fullName":"provider baseUrl const (full path, no trailing slash) mimo-free full path","status":"passed","title":"mimo-free full path","duration":0.06575000000000841,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["provider baseUrl const (full path, no trailing slash)"],"fullName":"provider baseUrl const (full path, no trailing slash) opencode no trailing slash","status":"passed","title":"opencode no trailing slash","duration":0.055292000000008557,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["antigravity retry (intentional change: 429=6, 503=3)"],"fullName":"antigravity retry (intentional change: 429=6, 503=3) 429 attempts = 6","status":"passed","title":"429 attempts = 6","duration":0.10516700000000867,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["antigravity retry (intentional change: 429=6, 503=3)"],"fullName":"antigravity retry (intentional change: 429=6, 503=3) 503 attempts = 3","status":"passed","title":"503 attempts = 3","duration":0.13358300000000156,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497746002,"endTime":1781497746004.1406,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/executor-const-guard.test.js"},{"assertionResults":[{"ancestorTitles":["toOpenAIFinish - gemini"],"fullName":"toOpenAIFinish - gemini SAFETY -> content_filter","status":"passed","title":"SAFETY -> content_filter","duration":1.2787079999999946,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - gemini"],"fullName":"toOpenAIFinish - gemini RECITATION -> content_filter","status":"passed","title":"RECITATION -> content_filter","duration":0.4854169999999982,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - gemini"],"fullName":"toOpenAIFinish - gemini BLOCKLIST -> content_filter","status":"passed","title":"BLOCKLIST -> content_filter","duration":0.2061250000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - gemini"],"fullName":"toOpenAIFinish - gemini PROHIBITED_CONTENT -> content_filter","status":"passed","title":"PROHIBITED_CONTENT -> content_filter","duration":0.23712499999999181,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - gemini"],"fullName":"toOpenAIFinish - gemini OTHER -> stop","status":"passed","title":"OTHER -> stop","duration":0.1419999999999959,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - gemini"],"fullName":"toOpenAIFinish - gemini UNKNOWN_XYZ -> stop","status":"passed","title":"UNKNOWN_XYZ -> stop","duration":0.4248750000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - gemini"],"fullName":"toOpenAIFinish - gemini STOP -> stop","status":"passed","title":"STOP -> stop","duration":0.22325000000000728,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - gemini"],"fullName":"toOpenAIFinish - gemini MAX_TOKENS -> length","status":"passed","title":"MAX_TOKENS -> length","duration":0.11591599999999858,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - ollama"],"fullName":"toOpenAIFinish - ollama length -> length","status":"passed","title":"length -> length","duration":1.2664159999999924,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - ollama"],"fullName":"toOpenAIFinish - ollama max_tokens -> length","status":"passed","title":"max_tokens -> length","duration":0.13979100000000244,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - ollama"],"fullName":"toOpenAIFinish - ollama tool_calls -> tool_calls","status":"passed","title":"tool_calls -> tool_calls","duration":0.10454099999999755,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - ollama"],"fullName":"toOpenAIFinish - ollama unknown_xyz -> stop","status":"passed","title":"unknown_xyz -> stop","duration":0.03537500000000193,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - kiro"],"fullName":"toOpenAIFinish - kiro tool_use -> tool_calls","status":"passed","title":"tool_use -> tool_calls","duration":0.03912499999999852,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - claude"],"fullName":"toOpenAIFinish - claude end_turn -> stop","status":"passed","title":"end_turn -> stop","duration":0.04241700000000037,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - claude"],"fullName":"toOpenAIFinish - claude max_tokens -> length","status":"passed","title":"max_tokens -> length","duration":0.025166999999996165,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - claude"],"fullName":"toOpenAIFinish - claude tool_use -> tool_calls","status":"passed","title":"tool_use -> tool_calls","duration":0.024791000000007557,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - commandcode"],"fullName":"toOpenAIFinish - commandcode tool-calls -> tool_calls","status":"passed","title":"tool-calls -> tool_calls","duration":0.03233300000000838,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIFinish - commandcode"],"fullName":"toOpenAIFinish - commandcode unknown passthrough","status":"passed","title":"unknown passthrough","duration":0.028417000000004577,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["fromOpenAIFinish round-trip - claude"],"fullName":"fromOpenAIFinish round-trip - claude tool_calls -> tool_use","status":"passed","title":"tool_calls -> tool_use","duration":0.04604100000000244,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["fromOpenAIFinish round-trip - claude"],"fullName":"fromOpenAIFinish round-trip - claude length -> max_tokens","status":"passed","title":"length -> max_tokens","duration":0.03079200000000526,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["enum literals (catch drift)"],"fullName":"enum literals (catch drift) OPENAI_FINISH literals","status":"passed","title":"OPENAI_FINISH literals","duration":0.056167000000002076,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["enum literals (catch drift)"],"fullName":"enum literals (catch drift) CLAUDE_STOP literals","status":"passed","title":"CLAUDE_STOP literals","duration":0.04520800000000236,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["enum literals (catch drift)"],"fullName":"enum literals (catch drift) GEMINI_FINISH literals","status":"passed","title":"GEMINI_FINISH literals","duration":0.04379200000001049,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745905,"endTime":1781497745911.0562,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/finish-reason-concern.test.js"},{"assertionResults":[{"ancestorTitles":["forceStream provider config"],"fullName":"forceStream provider config only openai/codex/commandcode force streaming","status":"passed","title":"only openai/codex/commandcode force streaming","duration":42.50274999999999,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743892,"endTime":1781497743934.5027,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/force-stream-config.test.js"},{"assertionResults":[{"ancestorTitles":["Gemini CLI usage project id resolution"],"fullName":"Gemini CLI usage project id resolution uses the projectId stored on the provider connection","status":"passed","title":"uses the projectId stored on the provider connection","duration":13.00954200000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Gemini CLI usage project id resolution"],"fullName":"Gemini CLI usage project id resolution normalizes project objects returned by loadCodeAssist","status":"passed","title":"normalizes project objects returned by loadCodeAssist","duration":0.6141660000000115,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Gemini CLI usage project id resolution"],"fullName":"Gemini CLI usage project id resolution returns actionable guidance when no project id is available","status":"passed","title":"returns actionable guidance when no project id is available","duration":0.3138749999999959,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744920,"endTime":1781497744934.314,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/gemini-usage-projectid.test.js"},{"assertionResults":[{"ancestorTitles":["GithubExecutor.supportsResponsesEndpoint"],"fullName":"GithubExecutor.supportsResponsesEndpoint excludes Gemini models from the /responses endpoint","status":"passed","title":"excludes Gemini models from the /responses endpoint","duration":0.8396669999999915,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GithubExecutor.supportsResponsesEndpoint"],"fullName":"GithubExecutor.supportsResponsesEndpoint excludes Claude models from the /responses endpoint","status":"passed","title":"excludes Claude models from the /responses endpoint","duration":0.17354199999999764,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GithubExecutor.supportsResponsesEndpoint"],"fullName":"GithubExecutor.supportsResponsesEndpoint allows OpenAI/codex models on the /responses endpoint","status":"passed","title":"allows OpenAI/codex models on the /responses endpoint","duration":0.09620799999999008,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GithubExecutor.supportsResponsesEndpoint"],"fullName":"GithubExecutor.supportsResponsesEndpoint is null-safe","status":"passed","title":"is null-safe","duration":0.15174999999999272,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["GithubExecutor.execute cached-route guard (#1062)"],"fullName":"GithubExecutor.execute cached-route guard (#1062) does NOT use /responses for a Gemini model even if it was wrongly cached as codex","status":"passed","title":"does NOT use /responses for a Gemini model even if it was wrongly cached as codex","duration":1.5804589999999905,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745886,"endTime":1781497745888.5806,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/github-responses-routing.test.js"},{"assertionResults":[{"ancestorTitles":["HuggingFace model alias parsing"],"fullName":"HuggingFace model alias parsing resolves hf alias to huggingface provider","status":"passed","title":"resolves hf alias to huggingface provider","duration":1.1622500000000002,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497746176,"endTime":1781497746177.1624,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/hf-model-routing.test.js"},{"assertionResults":[{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore validates required prompt field","status":"passed","title":"validates required prompt field","duration":8.38349999999997,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore rejects unsupported provider","status":"passed","title":"rejects unsupported provider","duration":0.46091599999999744,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with OpenAI format","status":"passed","title":"generates image with OpenAI format","duration":2.4228749999999764,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with Gemini format","status":"passed","title":"generates image with Gemini format","duration":0.6623339999999871,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with Minimax format","status":"passed","title":"generates image with Minimax format","duration":0.41925000000003365,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with NanoBanana format","status":"passed","title":"generates image with NanoBanana format","duration":1.9841670000000136,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with SD WebUI format","status":"passed","title":"generates image with SD WebUI format","duration":0.7345000000000255,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore handles OpenRouter with HTTP-Referer header","status":"passed","title":"handles OpenRouter with HTTP-Referer header","duration":0.29062499999997726,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore handles Vercel AI Gateway image generation as OpenAI-compatible","status":"passed","title":"handles Vercel AI Gateway image generation as OpenAI-compatible","duration":0.6404589999999644,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore handles HuggingFace binary response","status":"passed","title":"handles HuggingFace binary response","duration":0.5862079999999992,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with Codex gpt-5.5-image using current Codex version header","status":"passed","title":"generates image with Codex gpt-5.5-image using current Codex version header","duration":1.032083,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore generates image with Cloudflare Workers AI JSON response","status":"passed","title":"generates image with Cloudflare Workers AI JSON response","duration":0.6118330000000469,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore uses multipart form data for Cloudflare FLUX.2 models","status":"passed","title":"uses multipart form data for Cloudflare FLUX.2 models","duration":0.6202920000000063,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore resolves Cloudflare img2img and inpainting URL inputs before sending","status":"passed","title":"resolves Cloudflare img2img and inpainting URL inputs before sending","duration":0.481207999999981,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore handles provider error responses","status":"passed","title":"handles provider error responses","duration":0.23895799999996825,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore handles network errors","status":"passed","title":"handles network errors","duration":0.2672089999999798,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["handleImageGenerationCore"],"fullName":"handleImageGenerationCore calls onRequestSuccess callback on success","status":"passed","title":"calls onRequestSuccess callback on success","duration":0.16416700000002038,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744710,"endTime":1781497744730.164,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/image-generation.test.js"},{"assertionResults":[{"ancestorTitles":["Kiro MITM model slots"],"fullName":"Kiro MITM model slots exposes the kiro mitm tool","status":"passed","title":"exposes the kiro mitm tool","duration":0.864042000000012,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro MITM model slots"],"fullName":"Kiro MITM model slots offers a mappable slot for the agent default model id 'auto'","status":"failed","title":"offers a mappable slot for the agent default model id 'auto'","duration":2.297208000000012,"failureMessages":["AssertionError: expected undefined to be truthy\n    at /Users/Working/router4/app/tests/unit/kiro-model-slots.test.js:21:18\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["Kiro MITM model slots"],"fullName":"Kiro MITM model slots offers a mappable slot for the background sub-task model id 'simple-task'","status":"passed","title":"offers a mappable slot for the background sub-task model id 'simple-task'","duration":0.12016699999998082,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743076,"endTime":1781497743079.297,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/kiro-model-slots.test.js"},{"assertionResults":[{"ancestorTitles":["generateSessionId"],"fullName":"generateSessionId uses the ses_ prefix and a 24-char random suffix","status":"passed","title":"uses the ses_ prefix and a 24-char random suffix","duration":0.9622920000000192,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generateSessionId"],"fullName":"generateSessionId only emits lowercase alphanumeric characters in the suffix","status":"passed","title":"only emits lowercase alphanumeric characters in the suffix","duration":0.19820799999999394,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generateSessionId"],"fullName":"generateSessionId produces a fresh id on each call","status":"passed","title":"produces a fresh id on each call","duration":0.3919159999999806,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generateFingerprint"],"fullName":"generateFingerprint returns a 64-char hex sha256 digest","status":"passed","title":"returns a 64-char hex sha256 digest","duration":2.2920830000000194,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generateFingerprint"],"fullName":"generateFingerprint is stable per machine (deterministic across calls)","status":"passed","title":"is stable per machine (deterministic across calls)","duration":0.24879199999998036,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseJwtExp"],"fullName":"parseJwtExp derives the expiry from the JWT exp claim (ms)","status":"passed","title":"derives the expiry from the JWT exp claim (ms)","duration":0.14549999999997,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseJwtExp"],"fullName":"parseJwtExp falls back to a future timestamp when the JWT is unparseable","status":"passed","title":"falls back to a future timestamp when the JWT is unparseable","duration":0.17650000000003274,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectSystemMarker"],"fullName":"injectSystemMarker prepends a system message with the marker when none is present","status":"passed","title":"prepends a system message with the marker when none is present","duration":0.18308300000001054,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectSystemMarker"],"fullName":"injectSystemMarker preserves the original user message after injection","status":"passed","title":"preserves the original user message after injection","duration":0.3290420000000154,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectSystemMarker"],"fullName":"injectSystemMarker keeps a caller-provided system prompt alongside the marker","status":"passed","title":"keeps a caller-provided system prompt alongside the marker","duration":0.10591700000003357,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectSystemMarker"],"fullName":"injectSystemMarker does not duplicate the marker when already present","status":"passed","title":"does not duplicate the marker when already present","duration":0.1289160000000038,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectSystemMarker"],"fullName":"injectSystemMarker leaves a body without a messages array untouched","status":"passed","title":"leaves a body without a messages array untouched","duration":0.04612499999996089,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt returns the jwt from the bootstrap response","status":"passed","title":"returns the jwt from the bootstrap response","duration":0.3078750000000241,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt sends the machine fingerprint as the bootstrap client","status":"passed","title":"sends the machine fingerprint as the bootstrap client","duration":0.18720799999999826,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt caches the jwt and does not re-fetch while still valid","status":"passed","title":"caches the jwt and does not re-fetch while still valid","duration":0.09991700000000492,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt re-fetches once the cached jwt is within the expiry buffer","status":"passed","title":"re-fetches once the cached jwt is within the expiry buffer","duration":0.22233300000004874,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt throws when the bootstrap response is not ok","status":"passed","title":"throws when the bootstrap response is not ok","duration":0.6356250000000045,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["bootstrapJwt"],"fullName":"bootstrapJwt throws when the bootstrap response has no jwt","status":"passed","title":"throws when the bootstrap response has no jwt","duration":0.13337499999994407,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MimoFreeExecutor"],"fullName":"MimoFreeExecutor buildUrl returns the free-ai chat endpoint","status":"passed","title":"buildUrl returns the free-ai chat endpoint","duration":0.04995800000000372,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MimoFreeExecutor"],"fullName":"MimoFreeExecutor buildHeaders includes the MiMo source and session affinity","status":"passed","title":"buildHeaders includes the MiMo source and session affinity","duration":0.08025000000003502,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MimoFreeExecutor"],"fullName":"MimoFreeExecutor transformRequest injects the system marker","status":"passed","title":"transformRequest injects the system marker","duration":0.04804100000001199,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MimoFreeExecutor"],"fullName":"MimoFreeExecutor execute injects the marker and sends a Bearer JWT to the chat endpoint","status":"passed","title":"execute injects the marker and sends a Bearer JWT to the chat endpoint","duration":0.325999999999965,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MimoFreeExecutor"],"fullName":"MimoFreeExecutor re-bootstraps and retries once on a 403 from the chat endpoint","status":"passed","title":"re-bootstraps and retries once on a 403 from the chat endpoint","duration":0.21041600000000926,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiMo Free provider registration"],"fullName":"MiMo Free provider registration registers a specialized executor for mimo-free and the mmf alias","status":"passed","title":"registers a specialized executor for mimo-free and the mmf alias","duration":0.3289169999999899,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiMo Free provider registration"],"fullName":"MiMo Free provider registration registers mimo-free as a no-auth provider in open-sse config","status":"passed","title":"registers mimo-free as a no-auth provider in open-sse config","duration":0.08704099999999926,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiMo Free provider registration"],"fullName":"MiMo Free provider registration exposes only mimo-auto (the sole free-channel model)","status":"passed","title":"exposes only mimo-auto (the sole free-channel model)","duration":0.19325000000003456,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiMo Free provider registration"],"fullName":"MiMo Free provider registration maps the mimo-free alias to mmf","status":"passed","title":"maps the mimo-free alias to mmf","duration":0.04566599999998289,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiMo Free provider registration"],"fullName":"MiMo Free provider registration lists mimo-free in the dashboard FREE_PROVIDERS catalog","status":"passed","title":"lists mimo-free in the dashboard FREE_PROVIDERS catalog","duration":0.052666999999985364,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745368,"endTime":1781497745376.3289,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/mimo-free.test.js"},{"assertionResults":[{"ancestorTitles":["MiniMax TTS"],"fullName":"MiniMax TTS sends MiniMax T2A payload and converts hex audio to base64 JSON","status":"passed","title":"sends MiniMax T2A payload and converts hex audio to base64 JSON","duration":17.394040999999987,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax TTS"],"fullName":"MiniMax TTS uses the default MiniMax voice when no voice is provided","status":"passed","title":"uses the default MiniMax voice when no voice is provided","duration":0.5503329999999949,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax TTS"],"fullName":"MiniMax TTS surfaces MiniMax base_resp errors","status":"passed","title":"surfaces MiniMax base_resp errors","duration":0.6269580000000019,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744790,"endTime":1781497744808.627,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/minimax-tts.test.js"},{"assertionResults":[{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage parses token-plan TTS quota counts as used counts","status":"passed","title":"parses token-plan TTS quota counts as used counts","duration":14.350333000000006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage parses coding-plan TTS quota counts as remaining counts","status":"passed","title":"parses coding-plan TTS quota counts as remaining counts","duration":0.6160000000000139,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage keeps non-TTS MiniMax quota rows instead of filtering to text only","status":"passed","title":"keeps non-TTS MiniMax quota rows instead of filtering to text only","duration":0.4076249999999959,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage includes M-series percent-only buckets that have no count totals","status":"passed","title":"includes M-series percent-only buckets that have no count totals","duration":0.40441599999999767,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage normalizes M-series percent-only buckets on the coding_plan (countMeansRemaining) endpoint too","status":"passed","title":"normalizes M-series percent-only buckets on the coding_plan (countMeansRemaining) endpoint too","duration":0.9839999999999804,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage renders the M3-era MiniMax-M* wildcard as a friendly series label","status":"passed","title":"renders the M3-era MiniMax-M* wildcard as a friendly series label","duration":0.9829169999999863,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax usage"],"fullName":"MiniMax usage prefers the upstream-provided remaining percent when counts are also present","status":"passed","title":"prefers the upstream-provided remaining percent when counts are also present","duration":0.5825419999999895,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744762,"endTime":1781497744780.5825,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/minimax-usage.test.js"},{"assertionResults":[{"ancestorTitles":["MiniMax voices API"],"fullName":"MiniMax voices API fetches global MiniMax voices with stored API key","status":"passed","title":"fetches global MiniMax voices with stored API key","duration":12.843082999999979,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax voices API"],"fullName":"MiniMax voices API fetches China MiniMax voices when provider=minimax-cn","status":"passed","title":"fetches China MiniMax voices when provider=minimax-cn","duration":1.9652910000000077,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744876,"endTime":1781497744891.9653,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/minimax-voices.test.js"},{"assertionResults":[{"ancestorTitles":["model name regex fallback (C2)"],"fullName":"model name regex fallback (C2) derives display name from id per family","status":"passed","title":"derives display name from id per family","duration":1.8797079999999937,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model name regex fallback (C2)"],"fullName":"model name regex fallback (C2) falls back to id verbatim when no pattern matches","status":"passed","title":"falls back to id verbatim when no pattern matches","duration":0.4510840000000087,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model name regex fallback (C2)"],"fullName":"model name regex fallback (C2) normalizeModel: explicit name always wins over regex","status":"passed","title":"normalizeModel: explicit name always wins over regex","duration":0.20204199999999162,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model name regex fallback (C2)"],"fullName":"model name regex fallback (C2) normalizeModel: terse string id becomes object with derived name","status":"passed","title":"normalizeModel: terse string id becomes object with derived name","duration":0.31629200000000424,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497746003,"endTime":1781497746005.4512,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/model-name-regex.test.js"},{"assertionResults":[{"ancestorTitles":["model test route kind routing"],"fullName":"model test route kind routing routes image model tests to /api/v1/images/generations","status":"passed","title":"routes image model tests to /api/v1/images/generations","duration":86.22166600000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model test route kind routing"],"fullName":"model test route kind routing routes embedding model tests to /api/v1/embeddings","status":"passed","title":"routes embedding model tests to /api/v1/embeddings","duration":1.0232910000000004,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model test route kind routing"],"fullName":"model test route kind routing fails embedding model tests when provider returns no embedding data","status":"passed","title":"fails embedding model tests when provider returns no embedding data","duration":1.2170830000000024,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model test route kind routing"],"fullName":"model test route kind routing routes stt model tests to /api/v1/audio/transcriptions","status":"passed","title":"routes stt model tests to /api/v1/audio/transcriptions","duration":1.2928339999999992,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["model test route kind routing"],"fullName":"model test route kind routing returns formatted HTTP errors for non-2xx embedding responses","status":"passed","title":"returns formatted HTTP errors for non-2xx embedding responses","duration":0.4940830000000176,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744052,"endTime":1781497744142.4941,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/model-test-routing.test.js"},{"assertionResults":[{"ancestorTitles":["openai→claude: image_url.detail is dropped (docs 11 §4)"],"fullName":"openai→claude: image_url.detail is dropped (docs 11 §4) converts image to base64 source WITHOUT a detail field","status":"passed","title":"converts image to base64 source WITHOUT a detail field","duration":2.639125000000007,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openai→claude: image_url.detail is dropped (docs 11 §4)"],"fullName":"openai→claude: image_url.detail is dropped (docs 11 §4) drops input_audio entirely (claude has no audio block)","status":"passed","title":"drops input_audio entirely (claude has no audio block)","duration":0.1993750000000034,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openai→gemini: input_audio is mapped to inlineData (docs 11 §4)"],"fullName":"openai→gemini: input_audio is mapped to inlineData (docs 11 §4) maps wav → audio/wav inlineData","status":"passed","title":"maps wav → audio/wav inlineData","duration":0.17320899999998574,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openai→gemini: input_audio is mapped to inlineData (docs 11 §4)"],"fullName":"openai→gemini: input_audio is mapped to inlineData (docs 11 §4) maps mp3 → audio/mpeg inlineData","status":"passed","title":"maps mp3 → audio/mpeg inlineData","duration":0.06791699999999423,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openai→gemini: input_audio is mapped to inlineData (docs 11 §4)"],"fullName":"openai→gemini: input_audio is mapped to inlineData (docs 11 §4) drops image_url.detail (not carried into inlineData)","status":"passed","title":"drops image_url.detail (not carried into inlineData)","duration":0.19095799999999485,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497746080,"endTime":1781497746083.1995,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/multimodal-drop-lock.test.js"},{"assertionResults":[{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import returns not-found when no macOS cursor db paths are accessible","status":"failed","title":"returns not-found when no macOS cursor db paths are accessible","duration":33.883540999999994,"failureMessages":["AssertionError: expected 'Cursor database not found. Checked lo…' to contain 'Cursor database not found in known ma…'\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:74:33\n    at processTicksAndRejections (node:internal/process/task_queues:105:5)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import returns descriptive error if macOS db file exists but cannot be opened","status":"failed","title":"returns descriptive error if macOS db file exists but cannot be opened","duration":50.96504200000001,"failureMessages":["AssertionError: the given combination of arguments (undefined and string) is invalid for this assertion. You can use an array, a map, an object, a set, a string, or a weakset instead of a string\n    at Proxy.<anonymous> (file:///Users/Working/router4/app/tests/node_modules/@vitest/expect/dist/index.js:1319:15)\n    at Proxy.<anonymous> (file:///Users/Working/router4/app/tests/node_modules/@vitest/expect/dist/index.js:1156:15)\n    at Proxy.methodWrapper (file:///Users/Working/router4/app/tests/node_modules/chai/index.js:1700:25)\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:84:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import extracts tokens using exact keys","status":"failed","title":"extracts tokens using exact keys","duration":28.586375000000004,"failureMessages":["AssertionError: expected false to be true // Object.is equality\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:101:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import unwraps JSON-encoded string values","status":"failed","title":"unwraps JSON-encoded string values","duration":27.546208999999976,"failureMessages":["AssertionError: expected false to be true // Object.is equality\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:118:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import falls back to fuzzy key matching on macOS when exact keys are missing","status":"failed","title":"falls back to fuzzy key matching on macOS when exact keys are missing","duration":27.33104099999997,"failureMessages":["AssertionError: expected false to be true // Object.is equality\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:142:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import returns login-prompt error when tokens are missing even after fallback","status":"failed","title":"returns login-prompt error when tokens are missing even after fallback","duration":27.147790999999984,"failureMessages":["AssertionError: the given combination of arguments (undefined and string) is invalid for this assertion. You can use an array, a map, an object, a set, a string, or a weakset instead of a string\n    at Proxy.<anonymous> (file:///Users/Working/router4/app/tests/node_modules/@vitest/expect/dist/index.js:1319:15)\n    at Proxy.<anonymous> (file:///Users/Working/router4/app/tests/node_modules/@vitest/expect/dist/index.js:1156:15)\n    at Proxy.methodWrapper (file:///Users/Working/router4/app/tests/node_modules/chai/index.js:1700:25)\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:156:33\n    at processTicksAndRejections (node:internal/process/task_queues:105:5)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import linux uses single hardcoded path and original error message","status":"failed","title":"linux uses single hardcoded path and original error message","duration":1.2962089999999762,"failureMessages":["AssertionError: expected 'Cursor database not found. Checked lo…' to be 'Cursor database not found. Make sure …' // Object.is equality\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:169:33\n    at processTicksAndRejections (node:internal/process/task_queues:105:5)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]},{"ancestorTitles":["GET /api/oauth/cursor/auto-import"],"fullName":"GET /api/oauth/cursor/auto-import unsupported platform returns 400","status":"failed","title":"unsupported platform returns 400","duration":0.377125000000035,"failureMessages":["AssertionError: expected 200 to be 400 // Object.is equality\n    at /Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js:181:29\n    at processTicksAndRejections (node:internal/process/task_queues:105:5)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:20"],"meta":{},"tags":[]}],"startTime":1781497743057,"endTime":1781497743254.3772,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/oauth-cursor-auto-import.test.js"},{"assertionResults":[{"ancestorTitles":["OpenAI Responses streaming termination"],"fullName":"OpenAI Responses streaming termination emits a response.failed event when a Responses stream closes before a terminal event","status":"passed","title":"emits a response.failed event when a Responses stream closes before a terminal event","duration":19.862791999999985,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI Responses streaming termination"],"fullName":"OpenAI Responses streaming termination does not add response.failed when a Responses stream already completed","status":"passed","title":"does not add response.failed when a Responses stream already completed","duration":0.934584000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenAI Responses streaming termination"],"fullName":"OpenAI Responses streaming termination emits response.failed before DONE when a Responses stream sends DONE without a terminal event","status":"passed","title":"emits response.failed before DONE when a Responses stream sends DONE without a terminal event","duration":1.092250000000007,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744563,"endTime":1781497744585.0923,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-responses-terminal-event.test.js"},{"assertionResults":[{"ancestorTitles":["openaiToClaudeResponse tool argument sanitization"],"fullName":"openaiToClaudeResponse tool argument sanitization drops invalid Read pages and clamps numeric bounds","status":"passed","title":"drops invalid Read pages and clamps numeric bounds","duration":1.4875830000000008,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeResponse tool argument sanitization"],"fullName":"openaiToClaudeResponse tool argument sanitization keeps valid PDF pages","status":"passed","title":"keeps valid PDF pages","duration":0.23954200000000014,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497746278,"endTime":1781497746280.2395,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-to-claude-response-tools.test.js"},{"assertionResults":[{"ancestorTitles":["openaiToClaudeRequest","response_format handling"],"fullName":"openaiToClaudeRequest response_format handling should inject JSON schema instructions for json_schema type","status":"passed","title":"should inject JSON schema instructions for json_schema type","duration":1.4599580000000287,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","response_format handling"],"fullName":"openaiToClaudeRequest response_format handling should inject basic JSON instructions for json_object type","status":"passed","title":"should inject basic JSON instructions for json_object type","duration":0.2166659999999183,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","response_format handling"],"fullName":"openaiToClaudeRequest response_format handling should not modify system prompt when response_format is missing","status":"passed","title":"should not modify system prompt when response_format is missing","duration":0.1279580000000351,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","response_format handling"],"fullName":"openaiToClaudeRequest response_format handling should preserve existing system messages when adding response_format","status":"passed","title":"should preserve existing system messages when adding response_format","duration":0.10179199999993216,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","tool_choice handling"],"fullName":"openaiToClaudeRequest tool_choice handling converts OpenAI forced tool ({type:'function'}) to Claude {type:'tool'}","status":"passed","title":"converts OpenAI forced tool ({type:'function'}) to Claude {type:'tool'}","duration":0.42679199999997763,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","tool_choice handling"],"fullName":"openaiToClaudeRequest tool_choice handling maps string tool_choice values","status":"passed","title":"maps string tool_choice values","duration":0.30891699999995126,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","tool_choice handling"],"fullName":"openaiToClaudeRequest tool_choice handling passes through Claude-native tool_choice objects unchanged","status":"passed","title":"passes through Claude-native tool_choice objects unchanged","duration":0.3030420000000049,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","tool_choice handling"],"fullName":"openaiToClaudeRequest tool_choice handling never leaks an invalid type (falls back to auto)","status":"passed","title":"never leaks an invalid type (falls back to auto)","duration":0.09233300000005329,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeRequest","tool_choice handling"],"fullName":"openaiToClaudeRequest tool_choice handling omits tool_choice entirely when the request has none","status":"passed","title":"omits tool_choice entirely when the request has none","duration":0.5153749999999491,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToClaudeResponse"],"fullName":"openaiToClaudeResponse omits empty Read pages tool argument before emitting Claude input deltas","status":"failed","title":"omits empty Read pages tool argument before emitting Claude input deltas","duration":3.391124999999988,"failureMessages":["AssertionError: expected undefined to be defined\n    at /Users/Working/router4/app/tests/unit/openai-to-claude.test.js:199:24\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]}],"startTime":1781497743659,"endTime":1781497743666.391,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-to-claude.test.js"},{"assertionResults":[{"ancestorTitles":["openaiToCommandCodeRequest — basic envelope"],"fullName":"openaiToCommandCodeRequest — basic envelope returns the expected top-level envelope shape","status":"passed","title":"returns the expected top-level envelope shape","duration":2.0773749999999893,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCodeRequest — system handling"],"fullName":"openaiToCommandCodeRequest — system handling hoists system messages to params.system (string), not messages[]","status":"passed","title":"hoists system messages to params.system (string), not messages[]","duration":1.32216600000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCodeRequest — system handling"],"fullName":"openaiToCommandCodeRequest — system handling joins multiple system messages with blank line","status":"passed","title":"joins multiple system messages with blank line","duration":0.19858399999998255,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCodeRequest — system handling"],"fullName":"openaiToCommandCodeRequest — system handling omits params.system when no system messages","status":"passed","title":"omits params.system when no system messages","duration":0.0870830000000069,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCodeRequest — content shape"],"fullName":"openaiToCommandCodeRequest — content shape MUST always emit content as Array (never string) for user","status":"passed","title":"MUST always emit content as Array (never string) for user","duration":0.3846249999999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCodeRequest — content shape"],"fullName":"openaiToCommandCodeRequest — content shape MUST always emit content as Array for assistant","status":"passed","title":"MUST always emit content as Array for assistant","duration":0.11170799999999304,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCodeRequest — tool role / tool-result (AI SDK)"],"fullName":"openaiToCommandCodeRequest — tool role / tool-result (AI SDK) converts role:\"tool\" to role:\"tool\" with tool-result block; output is {type:\"text\",value}","status":"passed","title":"converts role:\"tool\" to role:\"tool\" with tool-result block; output is {type:\"text\",value}","duration":0.20983300000000327,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCodeRequest — assistant tool_calls / tool-call"],"fullName":"openaiToCommandCodeRequest — assistant tool_calls / tool-call converts assistant.tool_calls[] into content blocks of type tool-call","status":"passed","title":"converts assistant.tool_calls[] into content blocks of type tool-call","duration":0.13212500000000205,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCodeRequest — tools schema conversion"],"fullName":"openaiToCommandCodeRequest — tools schema conversion converts OpenAI {type:\"function\", function:{...}} to Anthropic plain {name, input_schema}","status":"passed","title":"converts OpenAI {type:\"function\", function:{...}} to Anthropic plain {name, input_schema}","duration":1.4018329999999821,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCodeRequest — tools schema conversion"],"fullName":"openaiToCommandCodeRequest — tools schema conversion preserves description on converted tool","status":"passed","title":"preserves description on converted tool","duration":0.14637500000000614,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToCommandCodeRequest — tools schema conversion"],"fullName":"openaiToCommandCodeRequest — tools schema conversion does not include tools field when input has none","status":"passed","title":"does not include tools field when input has none","duration":0.13049999999998363,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745495,"endTime":1781497745502.1306,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-to-commandcode.test.js"},{"assertionResults":[{"ancestorTitles":["openaiToKiroRequest","basic message conversion"],"fullName":"openaiToKiroRequest basic message conversion should convert a simple text message","status":"passed","title":"should convert a simple text message","duration":2.3461250000000007,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToKiroRequest","basic message conversion"],"fullName":"openaiToKiroRequest basic message conversion should not include images field when no images are present","status":"passed","title":"should not include images field when no images are present","duration":0.13599999999999568,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToKiroRequest","image forwarding"],"fullName":"openaiToKiroRequest image forwarding should forward base64 image from image_url content part","status":"passed","title":"should forward base64 image from image_url content part","duration":0.5616250000000207,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToKiroRequest","image forwarding"],"fullName":"openaiToKiroRequest image forwarding should forward multiple base64 images","status":"passed","title":"should forward multiple base64 images","duration":0.38591699999997786,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToKiroRequest","image forwarding"],"fullName":"openaiToKiroRequest image forwarding should not include images field when images array is empty","status":"passed","title":"should not include images field when images array is empty","duration":0.26304199999998445,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToKiroRequest","image forwarding"],"fullName":"openaiToKiroRequest image forwarding should include both images and text content together","status":"passed","title":"should include both images and text content together","duration":0.1582080000000019,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToKiroRequest","image forwarding"],"fullName":"openaiToKiroRequest image forwarding should treat http image URLs as text fallback (Kiro only supports base64)","status":"passed","title":"should treat http image URLs as text fallback (Kiro only supports base64)","duration":0.09537499999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToKiroRequest","tool interaction without client-provided tools"],"fullName":"openaiToKiroRequest tool interaction without client-provided tools should flatten OpenAI tool_calls + tool result into history text with no tools array","status":"passed","title":"should flatten OpenAI tool_calls + tool result into history text with no tools array","duration":0.28016700000000583,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToKiroRequest","tool interaction without client-provided tools"],"fullName":"openaiToKiroRequest tool interaction without client-provided tools should flatten Claude tool_use / tool_result blocks with no tools array","status":"passed","title":"should flatten Claude tool_use / tool_result blocks with no tools array","duration":0.5252499999999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToKiroRequest","tool interaction without client-provided tools"],"fullName":"openaiToKiroRequest tool interaction without client-provided tools should keep structured tools when the client DOES provide a tools array","status":"passed","title":"should keep structured tools when the client DOES provide a tools array","duration":0.2982910000000061,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToKiroRequest","tool interaction without client-provided tools"],"fullName":"openaiToKiroRequest tool interaction without client-provided tools should salvage orphaned tool_result content as text instead of discarding it","status":"passed","title":"should salvage orphaned tool_result content as text instead of discarding it","duration":0.18912499999999,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745406,"endTime":1781497745412.2983,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-to-kiro.test.js"},{"assertionResults":[{"ancestorTitles":["openaiToOllamaRequest - tool_calls arguments parsing"],"fullName":"openaiToOllamaRequest - tool_calls arguments parsing malformed JSON args -> {} (no throw)","status":"passed","title":"malformed JSON args -> {} (no throw)","duration":1.4967499999999916,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["openaiToOllamaRequest - tool_calls arguments parsing"],"fullName":"openaiToOllamaRequest - tool_calls arguments parsing valid JSON args -> parsed object","status":"passed","title":"valid JSON args -> parsed object","duration":0.1962919999999997,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497746200,"endTime":1781497746201.4968,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/openai-to-ollama-malformed.test.js"},{"assertionResults":[{"ancestorTitles":["parseOpenAIMessages"],"fullName":"parseOpenAIMessages extracts system + history + current msg","status":"passed","title":"extracts system + history + current msg","duration":1.162333000000018,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseOpenAIMessages"],"fullName":"parseOpenAIMessages treats developer role as system","status":"passed","title":"treats developer role as system","duration":0.1822909999999922,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseOpenAIMessages"],"fullName":"parseOpenAIMessages handles multi-part content (array of text blocks)","status":"passed","title":"handles multi-part content (array of text blocks)","duration":0.0841660000000104,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseOpenAIMessages"],"fullName":"parseOpenAIMessages skips empty content messages","status":"passed","title":"skips empty content messages","duration":0.11504199999998832,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery first turn: returns JSON with instructions + query","status":"passed","title":"first turn: returns JSON with instructions + query","duration":0.8047909999999945,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery follow-up (with backendUuid): returns plain currentMsg, no JSON","status":"passed","title":"follow-up (with backendUuid): returns plain currentMsg, no JSON","duration":0.12966699999998355,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery includes history when present on first turn","status":"passed","title":"includes history when present on first turn","duration":0.15929099999999607,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery injects tools into instructions on first turn","status":"passed","title":"injects tools into instructions on first turn","duration":0.13095899999999006,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery ignores tools on follow-up turn (uses session)","status":"passed","title":"ignores tools on follow-up turn (uses session)","duration":0.41712499999999864,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildQuery"],"fullName":"buildQuery truncates query if JSON exceeds 96000 chars","status":"passed","title":"truncates query if JSON exceeds 96000 chars","duration":0.3595409999999788,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["formatToolsHint"],"fullName":"formatToolsHint returns empty string for no tools","status":"passed","title":"returns empty string for no tools","duration":0.11683400000001143,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["formatToolsHint"],"fullName":"formatToolsHint handles OpenAI tool schema (function wrapper)","status":"passed","title":"handles OpenAI tool schema (function wrapper)","duration":0.05275000000000318,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["formatToolsHint"],"fullName":"formatToolsHint handles flat tool schema","status":"passed","title":"handles flat tool schema","duration":0.039083000000005086,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["formatToolsHint"],"fullName":"formatToolsHint truncates long descriptions to first line, max 200 chars","status":"passed","title":"truncates long descriptions to first line, max 200 chars","duration":0.08199999999999363,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildPplxRequestBody"],"fullName":"buildPplxRequestBody sets query_str at both top-level AND params (required by upstream API)","status":"passed","title":"sets query_str at both top-level AND params (required by upstream API)","duration":13.767791999999986,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildPplxRequestBody"],"fullName":"buildPplxRequestBody includes required params","status":"passed","title":"includes required params","duration":0.32579200000000696,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute maps pplx-auto → mode=concise, pref=pplx_pro","status":"passed","title":"maps pplx-auto → mode=concise, pref=pplx_pro","duration":19.535083000000014,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute applies THINKING_MAP when reasoning_effort is set","status":"passed","title":"applies THINKING_MAP when reasoning_effort is set","duration":0.7529169999999965,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute sends Cookie header when credentials.apiKey provided","status":"passed","title":"sends Cookie header when credentials.apiKey provided","duration":0.38212500000000205,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute sends Bearer header when credentials.accessToken provided","status":"passed","title":"sends Bearer header when credentials.accessToken provided","duration":0.3620420000000024,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute injects body.tools into query_str instructions","status":"passed","title":"injects body.tools into query_str instructions","duration":0.9731660000000204,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute returns 400 on missing messages","status":"passed","title":"returns 400 on missing messages","duration":0.21041699999997832,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute surfaces upstream 401 with friendly auth message","status":"passed","title":"surfaces upstream 401 with friendly auth message","duration":0.6443749999999966,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["PerplexityWebExecutor.execute"],"fullName":"PerplexityWebExecutor.execute surfaces 429 with rate-limit message","status":"passed","title":"surfaces 429 with rate-limit message","duration":0.4858330000000137,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744370,"endTime":1781497744411.6443,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/perplexity-web.test.js"},{"assertionResults":[{"ancestorTitles":["provider display split (E1)"],"fullName":"provider display split (E1) AI_PROVIDERS entries still carry merged display + transport","status":"passed","title":"AI_PROVIDERS entries still carry merged display + transport","duration":71.32433400000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["provider display split (E1)"],"fullName":"provider display split (E1) display fields source from providersDisplay.js","status":"passed","title":"display fields source from providersDisplay.js","duration":4.863624999999985,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["provider display split (E1)"],"fullName":"provider display split (E1) helpers still work after split","status":"passed","title":"helpers still work after split","duration":0.24837499999998158,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743790,"endTime":1781497743866.2483,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/provider-display-split.test.js"},{"assertionResults":[{"ancestorTitles":["MiniMax-M3 model registration"],"fullName":"MiniMax-M3 model registration includes MiniMax-M3 in PROVIDER_MODELS.minimax","status":"passed","title":"includes MiniMax-M3 in PROVIDER_MODELS.minimax","duration":1.2301250000000152,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 model registration"],"fullName":"MiniMax-M3 model registration includes MiniMax-M3 in PROVIDER_MODELS['minimax-cn']","status":"passed","title":"includes MiniMax-M3 in PROVIDER_MODELS['minimax-cn']","duration":0.25508400000001075,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 model registration"],"fullName":"MiniMax-M3 model registration exposes MiniMax-M3 through getModelsByProviderId for both provider IDs","status":"passed","title":"exposes MiniMax-M3 through getModelsByProviderId for both provider IDs","duration":0.46041700000000674,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 model registration"],"fullName":"MiniMax-M3 model registration does not regress the existing M2.7 / M2.5 / M2.1 entries","status":"passed","title":"does not regress the existing M2.7 / M2.5 / M2.1 entries","duration":0.9021669999999915,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745632,"endTime":1781497745634.902,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/provider-models-minimax-m3.test.js"},{"assertionResults":[{"ancestorTitles":["MiniMax-M3 pricing"],"fullName":"MiniMax-M3 pricing includes MiniMax-M3 in MODEL_PRICING","status":"passed","title":"includes MiniMax-M3 in MODEL_PRICING","duration":2.126125000000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 pricing"],"fullName":"MiniMax-M3 pricing MiniMax-M3 pricing has numeric shape (input, output, cached)","status":"passed","title":"MiniMax-M3 pricing has numeric shape (input, output, cached)","duration":0.6438750000000084,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 pricing"],"fullName":"MiniMax-M3 pricing MiniMax-M3 input price matches the design spec (0.30)","status":"passed","title":"MiniMax-M3 input price matches the design spec (0.30)","duration":0.11816699999999969,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 pricing"],"fullName":"MiniMax-M3 pricing MiniMax-M3 output price matches the design spec (1.20)","status":"passed","title":"MiniMax-M3 output price matches the design spec (1.20)","duration":0.11129200000000594,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["MiniMax-M3 pricing"],"fullName":"MiniMax-M3 pricing MiniMax-M3 cached price matches the design spec (0.06)","status":"passed","title":"MiniMax-M3 cached price matches the design spec (0.06)","duration":0.06304099999999835,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745869,"endTime":1781497745872.1182,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/provider-pricing-minimax-m3.test.js"},{"assertionResults":[{"ancestorTitles":["provider test-models route kind routing"],"fullName":"provider test-models route kind routing routes huggingface image models to /api/v1/images/generations","status":"passed","title":"routes huggingface image models to /api/v1/images/generations","duration":167.55883400000002,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743348,"endTime":1781497743515.5588,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/provider-test-models-routing.test.js"},{"assertionResults":[{"ancestorTitles":["Provider Validation API","OpenAI Compatible"],"fullName":"Provider Validation API OpenAI Compatible should return valid:true when /models succeeds","status":"passed","title":"should return valid:true when /models succeeds","duration":3.4523750000000035,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","OpenAI Compatible"],"fullName":"Provider Validation API OpenAI Compatible should fallback to chat/completions when /models fails and modelId provided","status":"passed","title":"should fallback to chat/completions when /models fails and modelId provided","duration":0.28020899999999926,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","OpenAI Compatible"],"fullName":"Provider Validation API OpenAI Compatible should return error when /models fails and no modelId","status":"passed","title":"should return error when /models fails and no modelId","duration":0.27941599999999767,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Anthropic Compatible"],"fullName":"Provider Validation API Anthropic Compatible should normalize URL by removing /messages suffix","status":"passed","title":"should normalize URL by removing /messages suffix","duration":0.18300000000000693,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Anthropic Compatible"],"fullName":"Provider Validation API Anthropic Compatible should send correct headers for Anthropic API","status":"passed","title":"should send correct headers for Anthropic API","duration":0.396458999999993,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - Network"],"fullName":"Provider Validation API Error Messages - Network should map ECONNREFUSED to user-friendly message","status":"passed","title":"should map ECONNREFUSED to user-friendly message","duration":0.0847920000000073,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - Network"],"fullName":"Provider Validation API Error Messages - Network should map ENOTFOUND to user-friendly message","status":"passed","title":"should map ENOTFOUND to user-friendly message","duration":0.10895800000000122,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - Network"],"fullName":"Provider Validation API Error Messages - Network should map timeout to user-friendly message","status":"passed","title":"should map timeout to user-friendly message","duration":0.06687499999999602,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - Network"],"fullName":"Provider Validation API Error Messages - Network should map CERT_HAS_EXPIRED to user-friendly message","status":"passed","title":"should map CERT_HAS_EXPIRED to user-friendly message","duration":0.2903750000000116,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","URL Validation"],"fullName":"Provider Validation API URL Validation should validate correct URL format","status":"passed","title":"should validate correct URL format","duration":0.15262500000000045,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return auth error for 401","status":"passed","title":"should return auth error for 401","duration":0.12070799999999338,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return auth error for 403","status":"passed","title":"should return auth error for 403","duration":0.04345899999999858,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return not found for 404","status":"passed","title":"should return not found for 404","duration":0.0401250000000033,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return server error for 500","status":"passed","title":"should return server error for 500","duration":0.035332999999994286,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return server error for 502","status":"passed","title":"should return server error for 502","duration":0.03491699999999298,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /models Status Codes"],"fullName":"Provider Validation API Error Messages - /models Status Codes should return unexpected for other codes","status":"passed","title":"should return unexpected for other codes","duration":0.10949999999999704,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /chat/completions Status Codes"],"fullName":"Provider Validation API Error Messages - /chat/completions Status Codes should return auth error for 401","status":"passed","title":"should return auth error for 401","duration":0.07479200000000219,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /chat/completions Status Codes"],"fullName":"Provider Validation API Error Messages - /chat/completions Status Codes should return invalid model for 400","status":"passed","title":"should return invalid model for 400","duration":0.061957999999989966,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /chat/completions Status Codes"],"fullName":"Provider Validation API Error Messages - /chat/completions Status Codes should return not found for 404","status":"passed","title":"should return not found for 404","duration":0.04449999999999932,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /chat/completions Status Codes"],"fullName":"Provider Validation API Error Messages - /chat/completions Status Codes should return server error for 503","status":"passed","title":"should return server error for 503","duration":0.04554200000001174,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Error Messages - /chat/completions Status Codes"],"fullName":"Provider Validation API Error Messages - /chat/completions Status Codes should return failed for other codes","status":"passed","title":"should return failed for other codes","duration":0.039667000000008557,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Response Format"],"fullName":"Provider Validation API Response Format should return correct format for success via /models","status":"passed","title":"should return correct format for success via /models","duration":0.07374999999998977,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Response Format"],"fullName":"Provider Validation API Response Format should return correct format for success via chat","status":"passed","title":"should return correct format for success via chat","duration":0.07337499999999864,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Provider Validation API","Response Format"],"fullName":"Provider Validation API Response Format should return correct format for failure with error","status":"passed","title":"should return correct format for failure with error","duration":0.060207999999988715,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745428,"endTime":1781497745435.0603,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/provider-validation.test.js"},{"assertionResults":[{"ancestorTitles":["QODER_MODEL_MAP"],"fullName":"QODER_MODEL_MAP allows Qoder's latest model key","status":"passed","title":"allows Qoder's latest model key","duration":0.8009169999999983,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["QODER_MODEL_MAP"],"fullName":"QODER_MODEL_MAP exposes Qoder's latest model in the static provider catalog","status":"passed","title":"exposes Qoder's latest model in the static provider catalog","duration":0.14654100000001336,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody preserves base64 length (input length divisible by 3)","status":"passed","title":"preserves base64 length (input length divisible by 3)","duration":0.12937500000001023,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody preserves base64 length (input length not divisible by 3)","status":"passed","title":"preserves base64 length (input length not divisible by 3)","duration":0.12062499999998977,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody handles empty input without throwing","status":"passed","title":"handles empty input without throwing","duration":0.06887499999999136,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody accepts string and Buffer inputs equivalently","status":"passed","title":"accepts string and Buffer inputs equivalently","duration":0.12420900000000756,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody only emits characters from the custom alphabet","status":"passed","title":"only emits characters from the custom alphabet","duration":0.8450829999999883,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody is deterministic for identical input","status":"passed","title":"is deterministic for identical input","duration":0.1368750000000034,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["qoderEncodeBody"],"fullName":"qoderEncodeBody produces different output for different input","status":"passed","title":"produces different output for different input","duration":0.6818749999999909,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generatePkcePair"],"fullName":"generatePkcePair produces base64url-safe verifier and challenge of the right length","status":"passed","title":"produces base64url-safe verifier and challenge of the right length","duration":0.5009579999999971,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generatePkcePair"],"fullName":"generatePkcePair verifier and challenge are different (challenge is sha256 of verifier)","status":"passed","title":"verifier and challenge are different (challenge is sha256 of verifier)","duration":0.15720799999999713,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["generatePkcePair"],"fullName":"generatePkcePair returns codeVerifier (not verifier) on the higher-level helper","status":"passed","title":"returns codeVerifier (not verifier) on the higher-level helper","duration":0.2604159999999922,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["initiateDeviceFlow"],"fullName":"initiateDeviceFlow produces a verification URL pointing at qoder.com/device/selectAccounts","status":"passed","title":"produces a verification URL pointing at qoder.com/device/selectAccounts","duration":0.15687500000001364,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["initiateDeviceFlow"],"fullName":"initiateDeviceFlow returns nonce and machineId as UUIDs","status":"passed","title":"returns nonce and machineId as UUIDs","duration":0.12408400000001052,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders produces all required Cosy-* headers","status":"passed","title":"produces all required Cosy-* headers","duration":1.2621249999999975,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Authorization is a Bearer COSY token with payload+sig","status":"passed","title":"Authorization is a Bearer COSY token with payload+sig","duration":0.2872910000000104,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Cosy-Sigpath strips the leading /algo prefix","status":"passed","title":"Cosy-Sigpath strips the leading /algo prefix","duration":0.1455829999999878,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Cosy-Sigpath also handles the encoded chat URL","status":"passed","title":"Cosy-Sigpath also handles the encoded chat URL","duration":0.19770900000000324,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Cosy-Bodyhash is the MD5 of the request body, Cosy-Bodylength is the length","status":"passed","title":"Cosy-Bodyhash is the MD5 of the request body, Cosy-Bodylength is the length","duration":0.13758300000000645,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders empty body produces the canonical empty-MD5 hash","status":"passed","title":"empty body produces the canonical empty-MD5 hash","duration":0.18999999999999773,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Cosy-Machineid + Cosy-Machinetoken match the supplied machineId","status":"passed","title":"Cosy-Machineid + Cosy-Machinetoken match the supplied machineId","duration":0.11337499999999068,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders auto-generates a machineId when none is supplied","status":"passed","title":"auto-generates a machineId when none is supplied","duration":0.12112500000000637,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders throws when userId is missing","status":"passed","title":"throws when userId is missing","duration":0.38579200000000924,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders throws when authToken is missing","status":"passed","title":"throws when authToken is missing","duration":0.09537499999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders Cosy-User reflects the supplied userId verbatim","status":"passed","title":"Cosy-User reflects the supplied userId verbatim","duration":0.4841250000000059,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["buildCosyHeaders"],"fullName":"buildCosyHeaders two calls with identical inputs differ only in fields that include fresh randomness","status":"passed","title":"two calls with identical inputs differ only in fields that include fresh randomness","duration":0.2708329999999819,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry accepts ms-epoch as a JSON number","status":"passed","title":"accepts ms-epoch as a JSON number","duration":0.06858299999998962,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry accepts ms-epoch as a numeric string","status":"passed","title":"accepts ms-epoch as a numeric string","duration":0.051208000000002585,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry accepts RFC3339 strings","status":"passed","title":"accepts RFC3339 strings","duration":0.04954200000000242,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry does not interpret short numeric strings as a year","status":"passed","title":"does not interpret short numeric strings as a year","duration":0.034458000000000766,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry falls back to expiresInSeconds when expiresAt is missing","status":"passed","title":"falls back to expiresInSeconds when expiresAt is missing","duration":0.08174999999999955,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry treats expires_in: 0 as already expired (now), not 30-day fallback","status":"passed","title":"treats expires_in: 0 as already expired (now), not 30-day fallback","duration":0.04333299999998985,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry falls back to ~30 days when both inputs are missing","status":"passed","title":"falls back to ~30 days when both inputs are missing","duration":0.04449999999999932,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseExpiry"],"fullName":"parseExpiry falls back to ~30 days when both inputs are unparseable","status":"passed","title":"falls back to ~30 days when both inputs are unparseable","duration":0.04329199999997968,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["normalizeMessages"],"fullName":"normalizeMessages hoists role:system out of messages into systemText","status":"passed","title":"hoists role:system out of messages into systemText","duration":0.3937080000000037,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["normalizeMessages"],"fullName":"normalizeMessages flattens multipart text content into a string","status":"passed","title":"flattens multipart text content into a string","duration":0.04283400000002757,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["normalizeMessages"],"fullName":"normalizeMessages joins multiple system messages with a blank line","status":"passed","title":"joins multiple system messages with a blank line","duration":0.036417000000000144,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["normalizeMessages"],"fullName":"normalizeMessages returns empty results for empty input","status":"passed","title":"returns empty results for empty input","duration":0.09170800000001122,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE forwards an OpenAI envelope chunk and emits [DONE] in flush","status":"passed","title":"forwards an OpenAI envelope chunk and emits [DONE] in flush","duration":11.420041999999995,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE drains a trailing partial line without a newline in flush()","status":"passed","title":"drains a trailing partial line without a newline in flush()","duration":0.34945899999999597,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE does not forward chunks after [DONE] has been emitted","status":"passed","title":"does not forward chunks after [DONE] has been emitted","duration":0.4539999999999793,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE strips embedded newlines from inner body before forwarding","status":"passed","title":"strips embedded newlines from inner body before forwarding","duration":0.33124999999998295,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE upstream error envelope produces an error chunk + [DONE]","status":"passed","title":"upstream error envelope produces an error chunk + [DONE]","duration":0.6365830000000017,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["wrapQoderSSE"],"fullName":"wrapQoderSSE non-ok responses are returned unchanged (no transform)","status":"passed","title":"non-ok responses are returned unchanged (no transform)","duration":0.2201249999999959,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744593,"endTime":1781497744616.2202,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/qoder.test.js"},{"assertionResults":[{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip injects reasoning_content on a deepseek- assistant message that lacks it","status":"passed","title":"injects reasoning_content on a deepseek- assistant message that lacks it","duration":0.9899999999999807,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip preserves an existing reasoning_content instead of overwriting it","status":"passed","title":"preserves an existing reasoning_content instead of overwriting it","duration":0.1647090000000162,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip applies provider-level rule for provider 'deepseek' (scope all)","status":"passed","title":"applies provider-level rule for provider 'deepseek' (scope all)","duration":0.08645800000002168,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip matches deepseek model id case-insensitively for custom providers (#1543)","status":"passed","title":"matches deepseek model id case-insensitively for custom providers (#1543)","duration":0.117416999999989,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip does not touch non-deepseek providers/models","status":"passed","title":"does not touch non-deepseek providers/models","duration":0.07787500000000591,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — DeepSeek thinking round-trip"],"fullName":"injectReasoningContent — DeepSeek thinking round-trip maps deepseek-v4-pro-none alias to disabled thinking and strips reasoning_effort","status":"passed","title":"maps deepseek-v4-pro-none alias to disabled thinking and strips reasoning_effort","duration":0.14287500000000364,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — MiniMax thinking round-trip"],"fullName":"injectReasoningContent — MiniMax thinking round-trip injects reasoning_content on a minimax assistant message that lacks it","status":"passed","title":"injects reasoning_content on a minimax assistant message that lacks it","duration":0.13037499999998658,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — MiniMax thinking round-trip"],"fullName":"injectReasoningContent — MiniMax thinking round-trip injects reasoning_content on minimax assistant message with tool_calls but no reasoning_content","status":"passed","title":"injects reasoning_content on minimax assistant message with tool_calls but no reasoning_content","duration":0.1220000000000141,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — MiniMax thinking round-trip"],"fullName":"injectReasoningContent — MiniMax thinking round-trip applies provider-level rule for provider 'minimax-cn' (scope all)","status":"passed","title":"applies provider-level rule for provider 'minimax-cn' (scope all)","duration":0.351791999999989,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — MiniMax thinking round-trip"],"fullName":"injectReasoningContent — MiniMax thinking round-trip preserves an existing reasoning_content on minimax instead of overwriting","status":"passed","title":"preserves an existing reasoning_content on minimax instead of overwriting","duration":0.08916700000000333,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["injectReasoningContent — MiniMax thinking round-trip"],"fullName":"injectReasoningContent — MiniMax thinking round-trip DefaultExecutor transformRequest runs the injector for minimax","status":"passed","title":"DefaultExecutor transformRequest runs the injector for minimax","duration":26.337582999999995,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["OpenCodeExecutor — issue #1543 regression"],"fullName":"OpenCodeExecutor — issue #1543 regression runs the injector so deepseek-v4-flash-free round-trips reasoning_content","status":"passed","title":"runs the injector so deepseek-v4-flash-free round-trips reasoning_content","duration":0.26958300000001145,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744378,"endTime":1781497744407.2695,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/reasoningContentInjector.test.js"},{"assertionResults":[{"ancestorTitles":["Responses abort terminal synthesis"],"fullName":"Responses abort terminal synthesis emits response.failed + [DONE] when upstream errors (abort/stall)","status":"passed","title":"emits response.failed + [DONE] when upstream errors (abort/stall)","duration":3.972332999999992,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Responses abort terminal synthesis"],"fullName":"Responses abort terminal synthesis does not synthesize terminal for non-Responses streams (callback null)","status":"passed","title":"does not synthesize terminal for non-Responses streams (callback null)","duration":0.7312919999999963,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497746017,"endTime":1781497746021.7312,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/responses-abort-terminal.test.js"},{"assertionResults":[{"ancestorTitles":["RTK end-to-end"],"fullName":"RTK end-to-end server is reachable","status":"skipped","title":"server is reachable","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK end-to-end"],"fullName":"RTK end-to-end rtkEnabled flag is true (user must enable via dashboard)","status":"skipped","title":"rtkEnabled flag is true (user must enable via dashboard)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK end-to-end"],"fullName":"RTK end-to-end compresses git diff tool_result and writes [RTK] savings to log","status":"skipped","title":"compresses git diff tool_result and writes [RTK] savings to log","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK end-to-end"],"fullName":"RTK end-to-end compresses grep-style tool_result","status":"skipped","title":"compresses grep-style tool_result","failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497742906,"endTime":1781497742906,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/rtk.e2e.test.js"},{"assertionResults":[{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E server reachable and rtkEnabled=true","status":"skipped","title":"server reachable and rtkEnabled=true","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for claude (cc/* → openai→claude)","status":"skipped","title":"compresses git diff for claude (cc/* → openai→claude)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for codex (cx/* → openai→openai-responses)","status":"skipped","title":"compresses git diff for codex (cx/* → openai→openai-responses)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for antigravity (ag/* → openai→antigravity)","status":"skipped","title":"compresses git diff for antigravity (ag/* → openai→antigravity)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for cursor (cu/* → openai→cursor)","status":"skipped","title":"compresses git diff for cursor (cu/* → openai→cursor)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for kiro (kr/* → openai→kiro)","status":"skipped","title":"compresses git diff for kiro (kr/* → openai→kiro)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for gemini (gemini/* → openai→gemini)","status":"skipped","title":"compresses git diff for gemini (gemini/* → openai→gemini)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for deepseek (deepseek/* → openai, passthrough)","status":"skipped","title":"compresses git diff for deepseek (deepseek/* → openai, passthrough)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK multi-provider E2E"],"fullName":"RTK multi-provider E2E compresses git diff for ollama (ollama/* → openai→ollama)","status":"skipped","title":"compresses git diff for ollama (ollama/* → openai→ollama)","failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497742906,"endTime":1781497742906,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/rtk.multi-provider.e2e.test.js"},{"assertionResults":[{"ancestorTitles":["RTK flag"],"fullName":"RTK flag default off, toggle works","status":"failed","title":"default off, toggle works","duration":4.233541000000002,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:58:18\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters"],"fullName":"RTK filters gitDiff truncates hunks beyond 100 lines and preserves file header","status":"passed","title":"gitDiff truncates hunks beyond 100 lines and preserves file header","duration":0.76724999999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters"],"fullName":"RTK filters gitStatus groups by kind and produces compact output (Rust format)","status":"passed","title":"gitStatus groups by kind and produces compact output (Rust format)","duration":0.4084169999999858,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters"],"fullName":"RTK filters grep groups matches by file and caps per-file lines (Rust format)","status":"passed","title":"grep groups matches by file and caps per-file lines (Rust format)","duration":0.7521249999999782,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters"],"fullName":"RTK filters find groups paths by parent dir, shows basenames (Rust format)","status":"passed","title":"find groups paths by parent dir, shows basenames (Rust format)","duration":0.4069160000000238,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters"],"fullName":"RTK filters dedupLog collapses consecutive duplicates","status":"passed","title":"dedupLog collapses consecutive duplicates","duration":0.2463329999999928,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter"],"fullName":"autoDetectFilter detects git diff","status":"passed","title":"detects git diff","duration":0.2906669999999849,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter"],"fullName":"autoDetectFilter detects git status","status":"passed","title":"detects git status","duration":0.14337499999999181,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter"],"fullName":"autoDetectFilter detects grep","status":"passed","title":"detects grep","duration":0.6494999999999891,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter"],"fullName":"autoDetectFilter detects find","status":"passed","title":"detects find","duration":0.249416999999994,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter"],"fullName":"autoDetectFilter falls back to dedupLog for generic text","status":"passed","title":"falls back to dedupLog for generic text","duration":0.23783299999996643,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) ls: compact_ls strips perms/owner, keeps name + size","status":"passed","title":"ls: compact_ls strips perms/owner, keeps name + size","duration":0.432124999999985,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) ls: filters noise dirs","status":"passed","title":"ls: filters noise dirs","duration":0.2501249999999686,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) tree: removes summary, keeps structure","status":"passed","title":"tree: removes summary, keeps structure","duration":0.17054200000001174,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) smartTruncate: keeps head+tail, drops middle","status":"passed","title":"smartTruncate: keeps head+tail, drops middle","duration":0.1548330000000533,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) smartTruncate: passes through small input","status":"passed","title":"smartTruncate: passes through small input","duration":0.04712499999999409,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) readNumbered: compacts very long line-numbered dump","status":"passed","title":"readNumbered: compacts very long line-numbered dump","duration":0.17983400000002803,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["RTK filters (extras)"],"fullName":"RTK filters (extras) searchList: groups Cursor Glob output by parent dir","status":"passed","title":"searchList: groups Cursor Glob output by parent dir","duration":0.3078339999999571,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter (extras)"],"fullName":"autoDetectFilter (extras) detects tree via box-drawing glyphs","status":"passed","title":"detects tree via box-drawing glyphs","duration":0.29241700000000037,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter (extras)"],"fullName":"autoDetectFilter (extras) detects ls via total + perms rows","status":"passed","title":"detects ls via total + perms rows","duration":0.06970799999999144,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["autoDetectFilter (extras)"],"fullName":"autoDetectFilter (extras) detects Cursor search list","status":"passed","title":"detects Cursor search list","duration":0.07862500000004502,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["safeApply"],"fullName":"safeApply returns input if filter throws","status":"passed","title":"returns input if filter throws","duration":0.4908750000000168,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["safeApply"],"fullName":"safeApply returns input if filter returns non-string","status":"passed","title":"returns input if filter returns non-string","duration":0.04033300000003237,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (disabled)"],"fullName":"compressMessages (disabled) returns null when disabled","status":"failed","title":"returns null when disabled","duration":0.3933749999999918,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:248:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) compresses OpenAI tool message (string content)","status":"failed","title":"compresses OpenAI tool message (string content)","duration":0.149249999999995,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) compresses Claude string-form tool_result","status":"failed","title":"compresses Claude string-form tool_result","duration":0.20562499999999773,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) compresses Claude array-form tool_result text parts","status":"failed","title":"compresses Claude array-form tool_result text parts","duration":0.20274999999998045,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) skips is_error tool_result","status":"failed","title":"skips is_error tool_result","duration":0.10024999999995998,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) skips below MIN_COMPRESS_SIZE (<500 bytes)","status":"failed","title":"skips below MIN_COMPRESS_SIZE (<500 bytes)","duration":0.09279099999997698,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) never produces empty content (R14 guard)","status":"failed","title":"never produces empty content (R14 guard)","duration":0.08608400000002803,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) skips when body has no messages","status":"failed","title":"skips when body has no messages","duration":0.12954200000001492,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["compressMessages (enabled)"],"fullName":"compressMessages (enabled) handles mix of messages without crashing","status":"failed","title":"handles mix of messages without crashing","duration":0.13733300000001236,"failureMessages":["TypeError: (0 , __vite_ssr_import_1__.setRtkEnabled) is not a function\n    at /Users/Working/router4/app/tests/unit/rtk.test.js:256:33\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at wrapper (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:722:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2621:52\n    at run (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1150:20)\n    at limiterFn (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1162:59)\n    at runHook (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2620:10)"],"meta":{},"tags":[]},{"ancestorTitles":["formatRtkLog"],"fullName":"formatRtkLog returns null when no hits","status":"passed","title":"returns null when no hits","duration":0.09549999999995862,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["formatRtkLog"],"fullName":"formatRtkLog formats savings line with percentage","status":"passed","title":"formats savings line with percentage","duration":0.17395800000002737,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743210,"endTime":1781497743224.174,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/rtk.test.js"},{"assertionResults":[{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support compresses tool results in Kiro conversationState.currentMessage","status":"passed","title":"compresses tool results in Kiro conversationState.currentMessage","duration":2.233125000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support compresses tool results in Kiro conversationState.history","status":"passed","title":"compresses tool results in Kiro conversationState.history","duration":0.47366699999999184,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support handles multiple tool results across history and currentMessage","status":"passed","title":"handles multiple tool results across history and currentMessage","duration":0.2462500000000034,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support preserves error tool results without compression","status":"passed","title":"preserves error tool results without compression","duration":0.1387500000000017,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support returns null when RTK is disabled","status":"passed","title":"returns null when RTK is disabled","duration":0.06720899999999119,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support handles Kiro body with no tool results gracefully","status":"passed","title":"handles Kiro body with no tool results gracefully","duration":0.09004099999999937,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["Kiro format RTK support"],"fullName":"Kiro format RTK support handles malformed Kiro body without crashing","status":"passed","title":"handles malformed Kiro body without crashing","duration":0.12937500000001023,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745751,"endTime":1781497745754.2463,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/rtkKiro.test.js"},{"assertionResults":[{"ancestorTitles":["resolveSessionId"],"fullName":"resolveSessionId stickiness: same body+connectionId+scope -> same id","status":"passed","title":"stickiness: same body+connectionId+scope -> same id","duration":1.4322499999999962,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["resolveSessionId"],"fullName":"resolveSessionId different connectionId -> different id","status":"passed","title":"different connectionId -> different id","duration":0.4677499999999952,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["resolveSessionId"],"fullName":"resolveSessionId different scope -> different id","status":"passed","title":"different scope -> different id","duration":0.26300000000000523,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["resolveSessionId"],"fullName":"resolveSessionId fallback: empty body+no header+no workspaceId -> deriveSessionId(connectionId)","status":"passed","title":"fallback: empty body+no header+no workspaceId -> deriveSessionId(connectionId)","duration":0.14791599999999505,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["resolveSessionId"],"fullName":"resolveSessionId client override: x-session-id header wins, skips later steps","status":"passed","title":"client override: x-session-id header wins, skips later steps","duration":0.13729100000000471,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["resolveSessionId"],"fullName":"resolveSessionId workspaceId path: empty body + workspaceId set -> normalized workspaceId","status":"passed","title":"workspaceId path: empty body + workspaceId set -> normalized workspaceId","duration":0.06274999999999409,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745986,"endTime":1781497745989.0627,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/session-manager.test.js"},{"assertionResults":[{"ancestorTitles":["tokenRefresh dispatch"],"fullName":"tokenRefresh dispatch getAccessToken returns null for missing/invalid refreshToken","status":"passed","title":"getAccessToken returns null for missing/invalid refreshToken","duration":77.544042,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["tokenRefresh dispatch"],"fullName":"tokenRefresh dispatch getAccessToken default: unsupported provider → null","status":"passed","title":"getAccessToken default: unsupported provider → null","duration":0.2103749999999991,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["tokenRefresh dispatch"],"fullName":"tokenRefresh dispatch refreshTokenByProvider returns null without refreshToken","status":"passed","title":"refreshTokenByProvider returns null without refreshToken","duration":0.09800000000001319,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744253,"endTime":1781497744331.2104,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/token-refresh-dispatch.test.js"},{"assertionResults":[{"ancestorTitles":["normalizeClaudePassthrough — haiku adaptive thinking (docs 11 §1)"],"fullName":"normalizeClaudePassthrough — haiku adaptive thinking (docs 11 §1) downgrades adaptive thinking to enabled+budget for haiku models","status":"passed","title":"downgrades adaptive thinking to enabled+budget for haiku models","duration":1.0424999999999898,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["normalizeClaudePassthrough — haiku adaptive thinking (docs 11 §1)"],"fullName":"normalizeClaudePassthrough — haiku adaptive thinking (docs 11 §1) keeps adaptive thinking for sonnet/opus","status":"passed","title":"keeps adaptive thinking for sonnet/opus","duration":0.23183299999999463,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["normalizeClaudePassthrough — haiku adaptive thinking (docs 11 §1)"],"fullName":"normalizeClaudePassthrough — haiku adaptive thinking (docs 11 §1) hoists mid-conversation system messages into top-level system","status":"passed","title":"hoists mid-conversation system messages into top-level system","duration":0.1904169999999965,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseDataUri / encodeDataUri (docs 11 §4)"],"fullName":"parseDataUri / encodeDataUri (docs 11 §4) parses a base64 data uri","status":"passed","title":"parses a base64 data uri","duration":0.11404200000001197,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseDataUri / encodeDataUri (docs 11 §4)"],"fullName":"parseDataUri / encodeDataUri (docs 11 §4) tolerates newlines inside base64 payload","status":"passed","title":"tolerates newlines inside base64 payload","duration":0.1861250000000041,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseDataUri / encodeDataUri (docs 11 §4)"],"fullName":"parseDataUri / encodeDataUri (docs 11 §4) returns null for http urls and non-strings","status":"passed","title":"returns null for http urls and non-strings","duration":0.10479200000000333,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["parseDataUri / encodeDataUri (docs 11 §4)"],"fullName":"parseDataUri / encodeDataUri (docs 11 §4) encode/parse roundtrip","status":"passed","title":"encode/parse roundtrip","duration":0.1755420000000072,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497746165,"endTime":1781497746167.186,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/translator-helpers-edge.test.js"},{"assertionResults":[{"ancestorTitles":["request normalization"],"fullName":"request normalization claudeToOpenAIRequest flattens text-only content arrays into string","status":"failed","title":"claudeToOpenAIRequest flattens text-only content arrays into string","duration":5.173790999999937,"failureMessages":["AssertionError: expected [ { type: 'text', text: 'hi' }, …(1) ] to be 'hi\\nthere' // Object.is equality\n    at /Users/Working/router4/app/tests/unit/translator-request-normalization.test.js:24:40\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization claudeToOpenAIRequest preserves multimodal arrays","status":"passed","title":"claudeToOpenAIRequest preserves multimodal arrays","duration":0.2379999999999427,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization filterToOpenAIFormat flattens text-only arrays to string","status":"failed","title":"filterToOpenAIFormat flattens text-only arrays to string","duration":0.7105000000000246,"failureMessages":["AssertionError: expected [ { type: 'text', text: 'a' }, …(1) ] to be 'a\\nb' // Object.is equality\n    at /Users/Working/router4/app/tests/unit/translator-request-normalization.test.js:65:40\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization translateRequest keeps /v1/messages Claude->OpenAI text payloads string-safe","status":"failed","title":"translateRequest keeps /v1/messages Claude->OpenAI text payloads string-safe","duration":1.4086670000000368,"failureMessages":["AssertionError: expected 'object' to be 'string' // Object.is equality\n    at /Users/Working/router4/app/tests/unit/translator-request-normalization.test.js:95:40\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization translateRequest strips unsupported Anthropic output_config for MiniMax Claude-compatible endpoints","status":"passed","title":"translateRequest strips unsupported Anthropic output_config for MiniMax Claude-compatible endpoints","duration":0.383707999999956,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization translateRequest preserves output_config for Anthropic Claude","status":"passed","title":"translateRequest preserves output_config for Anthropic Claude","duration":0.22670800000003055,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization parseSSELine supports provider raw NDJSON stream lines","status":"failed","title":"parseSSELine supports provider raw NDJSON stream lines","duration":0.47641699999996945,"failureMessages":["AssertionError: expected null to deeply equal { model: 'gpt-oss:120b', …(2) }\n    at /Users/Working/router4/app/tests/unit/translator-request-normalization.test.js:175:20\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:302:11\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:1903:26\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2326:20\n    at new Promise (<anonymous>)\n    at runWithCancel (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2323:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2305:20\n    at new Promise (<anonymous>)\n    at runWithTimeout (file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2272:10)\n    at file:///Users/Working/router4/app/tests/node_modules/@vitest/runner/dist/chunk-artifact.js:2955:64"],"meta":{},"tags":[]},{"ancestorTitles":["request normalization"],"fullName":"request normalization parseSSELine still supports SSE data lines","status":"passed","title":"parseSSELine still supports SSE data lines","duration":0.06995799999992869,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743663,"endTime":1781497743672.07,"status":"failed","message":"","name":"/Users/Working/router4/app/tests/unit/translator-request-normalization.test.js"},{"assertionResults":[{"ancestorTitles":["toOpenAIUsage"],"fullName":"toOpenAIUsage claude: folds cache read+create into prompt, exposes details","status":"passed","title":"claude: folds cache read+create into prompt, exposes details","duration":2.097583,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIUsage"],"fullName":"toOpenAIUsage claude: no cache -> no prompt_tokens_details","status":"passed","title":"claude: no cache -> no prompt_tokens_details","duration":0.48116600000000176,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIUsage"],"fullName":"toOpenAIUsage gemini: full fields, completion = candidates + thoughts","status":"passed","title":"gemini: full fields, completion = candidates + thoughts","duration":0.49329099999999926,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIUsage"],"fullName":"toOpenAIUsage gemini fallback: candidates=0 -> derive from total - prompt - thoughts","status":"passed","title":"gemini fallback: candidates=0 -> derive from total - prompt - thoughts","duration":0.23312500000000114,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIUsage"],"fullName":"toOpenAIUsage kiro: input/output straight","status":"passed","title":"kiro: input/output straight","duration":0.21391600000001176,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIUsage"],"fullName":"toOpenAIUsage ollama: prompt_eval_count/eval_count","status":"passed","title":"ollama: prompt_eval_count/eval_count","duration":0.18574999999999875,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIUsage"],"fullName":"toOpenAIUsage commandcode: keeps totalTokens fallback","status":"passed","title":"commandcode: keeps totalTokens fallback","duration":0.2881670000000014,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["toOpenAIUsage"],"fullName":"toOpenAIUsage unknown kind / null raw -> null","status":"passed","title":"unknown kind / null raw -> null","duration":0.1807500000000033,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745670,"endTime":1781497745674.288,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/usage-concern.test.js"},{"assertionResults":[{"ancestorTitles":["usage dispatch"],"fullName":"usage dispatch unsupported provider → not-implemented message","status":"passed","title":"unsupported provider → not-implemented message","duration":130.92683300000002,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["usage dispatch"],"fullName":"usage dispatch every supported provider routes to its handler (no fallback message)","status":"passed","title":"every supported provider routes to its handler (no fallback message)","duration":2.7001249999999857,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744176,"endTime":1781497744309.7002,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/usage-dispatch.test.js"},{"assertionResults":[{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should return valid:true when response is 200","status":"passed","title":"should return valid:true when response is 200","duration":2.4599170000000044,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should return valid:true when response is 400 (auth accepted but bad body)","status":"passed","title":"should return valid:true when response is 400 (auth accepted but bad body)","duration":0.2662079999999918,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should return valid:true when response is 429 (rate limited but auth ok)","status":"passed","title":"should return valid:true when response is 429 (rate limited but auth ok)","duration":0.30212499999998954,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should return valid:false with error when response is 401","status":"passed","title":"should return valid:false with error when response is 401","duration":0.17425000000000068,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should return valid:false with error when response is 403","status":"passed","title":"should return valid:false with error when response is 403","duration":0.18470800000000054,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should strip sso= prefix from apiKey","status":"passed","title":"should strip sso= prefix from apiKey","duration":0.15487499999998988,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should accept raw token without sso= prefix","status":"passed","title":"should accept raw token without sso= prefix","duration":0.14991700000000208,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should POST to /rest/app-chat/conversations/new","status":"passed","title":"should POST to /rest/app-chat/conversations/new","duration":1.0687499999999943,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["grok-web validation"],"fullName":"grok-web validation should send Cloudflare-bypass headers","status":"passed","title":"should send Cloudflare-bypass headers","duration":0.7276250000000033,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should return valid:true when response is 200","status":"passed","title":"should return valid:true when response is 200","duration":0.16533400000000142,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should return valid:false when response is 401","status":"passed","title":"should return valid:false when response is 401","duration":0.1534160000000071,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should return valid:false when response is 403","status":"passed","title":"should return valid:false when response is 403","duration":0.059916999999998666,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should strip __Secure-next-auth.session-token= prefix","status":"passed","title":"should strip __Secure-next-auth.session-token= prefix","duration":0.055292000000008557,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should accept raw token without prefix","status":"passed","title":"should accept raw token without prefix","duration":0.05283300000000679,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["perplexity-web validation"],"fullName":"perplexity-web validation should POST to /rest/sse/perplexity_ask","status":"passed","title":"should POST to /rest/sse/perplexity_ask","duration":0.18912499999999,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497745288,"endTime":1781497745294.1892,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/web-cookie-validation.test.js"},{"assertionResults":[{"ancestorTitles":["xai/oauth service"],"fullName":"xai/oauth service validates discovered endpoints are https x.ai URLs","status":"passed","title":"validates discovered endpoints are https x.ai URLs","duration":190.46754199999998,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/oauth service"],"fullName":"xai/oauth service discovers endpoints without custom user-agent headers","status":"passed","title":"discovers endpoints without custom user-agent headers","duration":9.25691599999999,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/oauth service"],"fullName":"xai/oauth service builds authorize URLs with CLIProxyAPI query extras","status":"passed","title":"builds authorize URLs with CLIProxyAPI query extras","duration":6.939084000000037,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/oauth service"],"fullName":"xai/oauth service generates dashboard auth data with CLIProxyAPI PKCE size and discovered endpoints","status":"passed","title":"generates dashboard auth data with CLIProxyAPI PKCE size and discovered endpoints","duration":370.40000000000003,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/oauth service"],"fullName":"xai/oauth service exchanges dashboard codes against the discovered xAI token endpoint","status":"passed","title":"exchanges dashboard codes against the discovered xAI token endpoint","duration":18.292500000000018,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497743345,"endTime":1781497743940.2925,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/xai-oauth-service.test.js"},{"assertionResults":[{"ancestorTitles":["xai/token-refresh wrapper"],"fullName":"xai/token-refresh wrapper refreshXaiToken module loads without throwing","status":"passed","title":"refreshXaiToken module loads without throwing","duration":71.10000000000001,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/token-refresh wrapper"],"fullName":"xai/token-refresh wrapper formatProviderCredentials returns Bearer-shape for xai","status":"passed","title":"formatProviderCredentials returns Bearer-shape for xai","duration":0.5020839999999964,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/token-refresh wrapper"],"fullName":"xai/token-refresh wrapper refreshTokenByProvider returns null when refreshToken missing","status":"passed","title":"refreshTokenByProvider returns null when refreshToken missing","duration":0.21816700000002243,"failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["xai/token-refresh wrapper"],"fullName":"xai/token-refresh wrapper refreshTokenByProvider returns expiresIn for refreshed xai tokens","status":"passed","title":"refreshTokenByProvider returns expiresIn for refreshed xai tokens","duration":8.605624999999975,"failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497744133,"endTime":1781497744213.6057,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/unit/xai-tokenRefresh.test.js"},{"assertionResults":[{"ancestorTitles":["REAL all-formats matrix"],"fullName":"REAL all-formats matrix has active providers in DB","status":"skipped","title":"has active providers in DB","failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497742906,"endTime":1781497742906,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/real/all-formats.real.test.js"},{"assertionResults":[{"ancestorTitles":["REAL provider behavior cases"],"fullName":"REAL provider behavior cases gemini: finish_reason stop","status":"skipped","title":"gemini: finish_reason stop","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["REAL provider behavior cases"],"fullName":"REAL provider behavior cases kiro: tool turn -> tool_calls","status":"skipped","title":"kiro: tool turn -> tool_calls","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["REAL provider behavior cases"],"fullName":"REAL provider behavior cases ollama: max_tokens -> length","status":"skipped","title":"ollama: max_tokens -> length","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["REAL provider behavior cases"],"fullName":"REAL provider behavior cases codex: session stickiness (cached_tokens on 2nd turn)","status":"skipped","title":"codex: session stickiness (cached_tokens on 2nd turn)","failureMessages":[],"meta":{},"tags":[]},{"ancestorTitles":["REAL provider behavior cases"],"fullName":"REAL provider behavior cases antigravity: responds OK","status":"skipped","title":"antigravity: responds OK","failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497742906,"endTime":1781497742906,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/real/provider-cases.real.test.js"},{"assertionResults":[{"ancestorTitles":["REAL provider smoke"],"fullName":"REAL provider smoke has active providers in DB","status":"skipped","title":"has active providers in DB","failureMessages":[],"meta":{},"tags":[]}],"startTime":1781497742906,"endTime":1781497742906,"status":"passed","message":"","name":"/Users/Working/router4/app/tests/translator/real/smoke-providers.real.test.js"}]}
\ No newline at end of file
diff --git a/tests/__baseline__/known-fails.txt b/tests/__baseline__/known-fails.txt
new file mode 100644
index 0000000..9ffd63f
--- /dev/null
+++ b/tests/__baseline__/known-fails.txt
@@ -0,0 +1,25 @@
+tests/unit/antigravity-mitm.test.js :: Antigravity MITM model handling flags the out-of-box agent/Default model mandatory
+tests/unit/claude-header-forwarding.test.js :: proxyAwareFetch — api.anthropic.com routing routes api.anthropic.com to gotScraping (non-streaming) and returns ok response
+tests/unit/oauth-cursor-auto-import.test.js :: GET /api/oauth/cursor/auto-import extracts tokens using exact keys
+tests/unit/oauth-cursor-auto-import.test.js :: GET /api/oauth/cursor/auto-import falls back to fuzzy key matching on macOS when exact keys are missing
+tests/unit/oauth-cursor-auto-import.test.js :: GET /api/oauth/cursor/auto-import linux uses single hardcoded path and original error message
+tests/unit/oauth-cursor-auto-import.test.js :: GET /api/oauth/cursor/auto-import returns descriptive error if macOS db file exists but cannot be opened
+tests/unit/oauth-cursor-auto-import.test.js :: GET /api/oauth/cursor/auto-import returns login-prompt error when tokens are missing even after fallback
+tests/unit/oauth-cursor-auto-import.test.js :: GET /api/oauth/cursor/auto-import returns not-found when no macOS cursor db paths are accessible
+tests/unit/oauth-cursor-auto-import.test.js :: GET /api/oauth/cursor/auto-import unsupported platform returns 400
+tests/unit/oauth-cursor-auto-import.test.js :: GET /api/oauth/cursor/auto-import unwraps JSON-encoded string values
+tests/unit/openai-to-claude.test.js :: openaiToClaudeResponse omits empty Read pages tool argument before emitting Claude input deltas
+tests/unit/rtk.test.js :: RTK flag default off, toggle works
+tests/unit/rtk.test.js :: compressMessages (disabled) returns null when disabled
+tests/unit/rtk.test.js :: compressMessages (enabled) compresses Claude array-form tool_result text parts
+tests/unit/rtk.test.js :: compressMessages (enabled) compresses Claude string-form tool_result
+tests/unit/rtk.test.js :: compressMessages (enabled) compresses OpenAI tool message (string content)
+tests/unit/rtk.test.js :: compressMessages (enabled) handles mix of messages without crashing
+tests/unit/rtk.test.js :: compressMessages (enabled) never produces empty content (R14 guard)
+tests/unit/rtk.test.js :: compressMessages (enabled) skips below MIN_COMPRESS_SIZE (<500 bytes)
+tests/unit/rtk.test.js :: compressMessages (enabled) skips is_error tool_result
+tests/unit/rtk.test.js :: compressMessages (enabled) skips when body has no messages
+tests/unit/translator-request-normalization.test.js :: request normalization claudeToOpenAIRequest flattens text-only content arrays into string
+tests/unit/translator-request-normalization.test.js :: request normalization filterToOpenAIFormat flattens text-only arrays to string
+tests/unit/translator-request-normalization.test.js :: request normalization parseSSELine supports provider raw NDJSON stream lines
+tests/unit/translator-request-normalization.test.js :: request normalization translateRequest keeps /v1/messages Claude->OpenAI text payloads string-safe
diff --git a/tests/__baseline__/oauth-urls-baseline.json b/tests/__baseline__/oauth-urls-baseline.json
new file mode 100644
index 0000000..e204919
--- /dev/null
+++ b/tests/__baseline__/oauth-urls-baseline.json
@@ -0,0 +1,57 @@
+{
+  "oauthEndpoints": {
+    "google": {
+      "token": "https://oauth2.googleapis.com/token",
+      "auth": "https://accounts.google.com/o/oauth2/auth"
+    },
+    "openai": {
+      "token": "https://auth.openai.com/oauth/token",
+      "auth": "https://auth.openai.com/oauth/authorize"
+    },
+    "anthropic": {
+      "token": "https://api.anthropic.com/v1/oauth/token",
+      "auth": "https://api.anthropic.com/v1/oauth/authorize"
+    },
+    "qwen": {
+      "token": "https://chat.qwen.ai/api/v1/oauth2/token",
+      "auth": "https://chat.qwen.ai/api/v1/oauth2/device/code"
+    },
+    "iflow": {
+      "token": "https://iflow.cn/oauth/token",
+      "auth": "https://iflow.cn/oauth"
+    },
+    "github": {
+      "token": "https://github.com/login/oauth/access_token",
+      "auth": "https://github.com/login/oauth/authorize",
+      "deviceCode": "https://github.com/login/device/code"
+    }
+  },
+  "tokenUrls": {
+    "claude": "https://api.anthropic.com/v1/oauth/token",
+    "codex": "https://auth.openai.com/oauth/token",
+    "qwen": "https://chat.qwen.ai/api/v1/oauth2/token",
+    "iflow": "https://iflow.cn/oauth/token",
+    "kiro": "https://prod.us-east-1.auth.desktop.kiro.dev/refreshToken",
+    "xai": "https://auth.x.ai/oauth2/token",
+    "grok-cli": "https://auth.x.ai/oauth2/token",
+    "cline": "https://api.cline.bot/api/v1/auth/token",
+    "kimi-coding": "https://auth.kimi.com/api/oauth/token"
+  },
+  "authUrls": {
+    "kiro": "https://prod.us-east-1.auth.desktop.kiro.dev"
+  },
+  "refreshUrls": {
+    "cline": "https://api.cline.bot/api/v1/auth/refresh",
+    "kimi-coding": "https://auth.kimi.com/api/oauth/token",
+    "xai": "https://auth.x.ai/oauth2/token",
+    "grok-cli": "https://auth.x.ai/oauth2/token"
+  },
+  "clientIds": {
+    "claude": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
+    "codex": "app_EMoamEEZ73f0CkXaXp7hrann",
+    "qwen": "f0304373b74a44d2b584a3fb70ca9e56",
+    "iflow": "10009311001",
+    "kimi-coding": "17e5f671-d194-4dfb-9706-5516cb48c098",
+    "grok-cli": "b1a00492-073a-47ea-816f-4c329264a828"
+  }
+}
\ No newline at end of file
diff --git a/tests/__baseline__/providers-baseline.json b/tests/__baseline__/providers-baseline.json
new file mode 100644
index 0000000..8635e9e
--- /dev/null
+++ b/tests/__baseline__/providers-baseline.json
@@ -0,0 +1,904 @@
+{
+  "alicode-intl": {
+    "baseUrl": "https://coding-intl.dashscope.aliyuncs.com/v1/chat/completions",
+    "headers": {},
+    "quirks": {
+      "preserveCacheControl": true
+    },
+    "format": "openai"
+  },
+  "alicode": {
+    "baseUrl": "https://coding.dashscope.aliyuncs.com/v1/chat/completions",
+    "headers": {},
+    "quirks": {
+      "preserveCacheControl": true
+    },
+    "format": "openai"
+  },
+  "anthropic": {
+    "baseUrl": "https://api.anthropic.com/v1/messages",
+    "format": "claude",
+    "headers": {
+      "Anthropic-Version": "2023-06-01",
+      "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+    }
+  },
+  "antigravity": {
+    "baseUrls": [
+      "https://daily-cloudcode-pa.googleapis.com",
+      "https://daily-cloudcode-pa.sandbox.googleapis.com"
+    ],
+    "format": "antigravity",
+    "headers": {
+      "User-Agent": "antigravity/1.107.0 darwin/arm64"
+    },
+    "retry": {
+      "429": {
+        "attempts": 3
+      },
+      "500": {
+        "attempts": 3
+      },
+      "503": {
+        "attempts": 3
+      }
+    },
+    "usage": {
+      "quotaApiUrl": "https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels",
+      "loadProjectApiUrl": "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+      "tokenUrl": "https://oauth2.googleapis.com/token"
+    },
+    "clientId": "1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com",
+    "clientSecret": "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",
+    "tokenUrl": "https://oauth2.googleapis.com/token"
+  },
+  "assemblyai": {
+    "baseUrl": "https://api.assemblyai.com/v1/audio/transcriptions",
+    "validateUrl": "https://api.assemblyai.com/v1/account",
+    "format": "openai"
+  },
+  "azure": {
+    "baseUrl": "",
+    "headers": {},
+    "format": "openai"
+  },
+  "blackbox": {
+    "baseUrl": "https://api.blackbox.ai/v1/chat/completions",
+    "thinkingFormat": "openai",
+    "format": "openai"
+  },
+  "byteplus": {
+    "baseUrl": "https://ark.ap-southeast.bytepluses.com/api/coding/v3/chat/completions",
+    "headers": {},
+    "format": "openai"
+  },
+  "cerebras": {
+    "baseUrl": "https://api.cerebras.ai/v1/chat/completions",
+    "validateUrl": "https://api.cerebras.ai/v1/models",
+    "quirks": {
+      "dropClientMetadata": true
+    },
+    "format": "openai"
+  },
+  "chutes": {
+    "baseUrl": "https://llm.chutes.ai/v1/chat/completions",
+    "validateUrl": "https://llm.chutes.ai/v1/models",
+    "format": "openai"
+  },
+  "claude": {
+    "baseUrl": "https://api.anthropic.com/v1/messages",
+    "format": "claude",
+    "urlSuffix": "?beta=true",
+    "headers": {
+      "Anthropic-Version": "2023-06-01",
+      "Anthropic-Beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28",
+      "Anthropic-Dangerous-Direct-Browser-Access": "true",
+      "User-Agent": "claude-cli/2.1.92 (external, sdk-cli)",
+      "X-App": "cli",
+      "X-Stainless-Helper-Method": "stream",
+      "X-Stainless-Retry-Count": "0",
+      "X-Stainless-Runtime-Version": "v24.14.0",
+      "X-Stainless-Package-Version": "0.80.0",
+      "X-Stainless-Runtime": "node",
+      "X-Stainless-Lang": "js",
+      "X-Stainless-Arch": "arm64",
+      "X-Stainless-Os": "MacOS",
+      "X-Stainless-Timeout": "600"
+    },
+    "quirks": {
+      "cloakToolsOnOAuth": true
+    },
+    "auth": {
+      "apiKey": {
+        "header": "x-api-key",
+        "scheme": "raw"
+      },
+      "oauth": {
+        "header": "Authorization",
+        "scheme": "bearer"
+      },
+      "hooks": [
+        "claudeOverlay"
+      ]
+    },
+    "usage": {
+      "oauthUrl": "https://api.anthropic.com/api/oauth/usage",
+      "orgUrl": "https://api.anthropic.com/v1/organizations/{org_id}/usage",
+      "settingsUrl": "https://api.anthropic.com/v1/settings"
+    },
+    "clientId": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
+    "tokenUrl": "https://api.anthropic.com/v1/oauth/token"
+  },
+  "cline": {
+    "baseUrl": "https://api.cline.bot/api/v1/chat/completions",
+    "headers": {
+      "HTTP-Referer": "https://cline.bot",
+      "X-Title": "Cline"
+    },
+    "tokenUrl": "https://api.cline.bot/api/v1/auth/token",
+    "refreshUrl": "https://api.cline.bot/api/v1/auth/refresh",
+    "auth": {
+      "combined": true,
+      "header": "Authorization",
+      "scheme": "bearer",
+      "hooks": [
+        "clineHeaders"
+      ]
+    },
+    "format": "openai"
+  },
+  "clinepass": {
+    "baseUrl": "https://api.cline.bot/api/v1/chat/completions",
+    "headers": {
+      "HTTP-Referer": "https://cline.bot",
+      "X-Title": "Cline"
+    },
+    "auth": {
+      "combined": true,
+      "header": "Authorization",
+      "scheme": "bearer",
+      "hooks": [
+        "clineHeaders"
+      ]
+    },
+    "format": "openai",
+    "tokenUrl": "https://api.cline.bot/api/v1/auth/token"
+  },
+  "cloudflare-ai": {
+    "baseUrl": "https://api.cloudflare.com/client/v4/accounts/{accountId}/ai/v1/chat/completions",
+    "thinkingFormat": "openai",
+    "format": "openai"
+  },
+  "codebuddy-cn": {
+    "baseUrl": "https://copilot.tencent.com/v2/chat/completions",
+    "forceStream": true,
+    "thinkingFormat": "openai",
+    "headers": {
+      "User-Agent": "CLI/2.108.1 CodeBuddy/2.108.1",
+      "X-Product": "SaaS",
+      "X-IDE-Type": "CLI",
+      "X-IDE-Name": "CLI",
+      "x-requested-with": "XMLHttpRequest",
+      "x-codebuddy-request": "1"
+    },
+    "auth": {
+      "combined": true,
+      "header": "Authorization",
+      "scheme": "bearer"
+    },
+    "usage": {
+      "url": "https://copilot.tencent.com/v2/billing/meter/get-user-resource"
+    },
+    "format": "openai",
+    "tokenUrl": "https://copilot.tencent.com/v2/plugin/auth/token"
+  },
+  "codex": {
+    "baseUrl": "https://chatgpt.com/backend-api/codex/responses",
+    "format": "openai-responses",
+    "forceStream": true,
+    "headers": {
+      "originator": "codex_cli_rs",
+      "User-Agent": "codex_cli_rs/0.136.0"
+    },
+    "usage": {
+      "url": "https://chatgpt.com/backend-api/wham/usage",
+      "resetCreditsUrl": "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits",
+      "resetCreditsConsumeUrl": "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume"
+    },
+    "clientId": "app_EMoamEEZ73f0CkXaXp7hrann",
+    "tokenUrl": "https://auth.openai.com/oauth/token"
+  },
+  "cohere": {
+    "baseUrl": "https://api.cohere.ai/v1/chat/completions",
+    "validateUrl": "https://api.cohere.ai/v1/models",
+    "format": "openai"
+  },
+  "commandcode": {
+    "baseUrl": "https://api.commandcode.ai/alpha/generate",
+    "format": "commandcode",
+    "forceStream": true,
+    "headers": {
+      "x-command-code-version": "0.25.7",
+      "x-cli-environment": "cli"
+    }
+  },
+  "cursor": {
+    "baseUrl": "https://api2.cursor.sh",
+    "chatPath": "/aiserver.v1.ChatService/StreamUnifiedChatWithTools",
+    "format": "cursor",
+    "headers": {
+      "connect-accept-encoding": "gzip",
+      "connect-protocol-version": "1",
+      "Content-Type": "application/connect+proto",
+      "User-Agent": "connect-es/1.6.1"
+    },
+    "clientVersion": "3.1.0"
+  },
+  "deepgram": {
+    "baseUrl": "https://api.deepgram.com/v1/listen",
+    "format": "openai"
+  },
+  "deepseek": {
+    "baseUrl": "https://api.deepseek.com/chat/completions",
+    "validateUrl": "https://api.deepseek.com/models",
+    "reasoningInject": {
+      "scope": "all"
+    },
+    "format": "openai",
+    "transports": [
+      {
+        "format": "openai",
+        "baseUrl": "https://api.deepseek.com/chat/completions",
+        "auth": {
+          "combined": true,
+          "header": "Authorization",
+          "scheme": "bearer"
+        }
+      },
+      {
+        "format": "claude",
+        "baseUrl": "https://api.deepseek.com/anthropic/v1/messages",
+        "headers": {
+          "Anthropic-Version": "2023-06-01",
+          "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+        },
+        "auth": {
+          "combined": true,
+          "header": "x-api-key",
+          "scheme": "raw"
+        }
+      }
+    ]
+  },
+  "fireworks": {
+    "baseUrl": "https://api.fireworks.ai/inference/v1/chat/completions",
+    "validateUrl": "https://api.fireworks.ai/inference/v1/models",
+    "format": "openai"
+  },
+  "gemini-cli": {
+    "baseUrl": "https://cloudcode-pa.googleapis.com/v1internal",
+    "format": "gemini-cli",
+    "cliVersion": "0.34.0",
+    "apiClient": "google-genai-sdk/1.41.0 gl-node/v22.19.0",
+    "usage": {
+      "quotaUrl": "https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuota",
+      "loadCodeAssistUrl": "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist"
+    },
+    "clientId": "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com",
+    "clientSecret": "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",
+    "tokenUrl": "https://oauth2.googleapis.com/token"
+  },
+  "gemini": {
+    "baseUrl": "https://generativelanguage.googleapis.com/v1beta/models",
+    "format": "gemini",
+    "clientId": "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com",
+    "clientSecret": "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",
+    "auth": {
+      "apiKey": {
+        "header": "x-goog-api-key",
+        "scheme": "raw"
+      },
+      "oauth": {
+        "header": "Authorization",
+        "scheme": "bearer"
+      }
+    }
+  },
+  "github": {
+    "baseUrl": "https://api.githubcopilot.com/chat/completions",
+    "responsesUrl": "https://api.githubcopilot.com/responses",
+    "headers": {
+      "copilot-integration-id": "vscode-chat",
+      "editor-version": "vscode/1.110.0",
+      "editor-plugin-version": "copilot-chat/0.38.0",
+      "user-agent": "GitHubCopilotChat/0.38.0",
+      "openai-intent": "conversation-panel",
+      "x-github-api-version": "2025-04-01",
+      "x-vscode-user-agent-library-version": "electron-fetch",
+      "X-Initiator": "user",
+      "Accept": "application/json",
+      "Content-Type": "application/json"
+    },
+    "copilot": {
+      "vscodeVersion": "1.110.0",
+      "chatVersion": "0.38.0",
+      "userAgent": "GitHubCopilotChat/0.38.0",
+      "apiVersion": "2025-04-01"
+    },
+    "usage": {
+      "url": "https://api.github.com/copilot_internal/user"
+    },
+    "format": "openai",
+    "clientId": "Iv1.b507a08c87ecfe98",
+    "tokenUrl": "https://github.com/login/oauth/access_token"
+  },
+  "gitlab": {
+    "baseUrl": "https://gitlab.com/api/v4/chat/completions",
+    "auth": {
+      "combined": true,
+      "header": "Authorization",
+      "scheme": "bearer"
+    },
+    "format": "openai"
+  },
+  "glm-cn": {
+    "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4/chat/completions",
+    "headers": {},
+    "usage": {
+      "url": "https://open.bigmodel.cn/api/monitor/usage/quota/limit"
+    },
+    "format": "openai"
+  },
+  "glm": {
+    "baseUrl": "https://api.z.ai/api/anthropic/v1/messages",
+    "format": "claude",
+    "urlSuffix": "?beta=true",
+    "headers": {
+      "Anthropic-Version": "2023-06-01",
+      "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+    },
+    "auth": {
+      "combined": true,
+      "header": "x-api-key",
+      "scheme": "raw"
+    },
+    "usage": {
+      "url": "https://api.z.ai/api/monitor/usage/quota/limit"
+    },
+    "transports": [
+      {
+        "format": "openai",
+        "baseUrl": "https://api.z.ai/api/coding/paas/v4/chat/completions",
+        "auth": {
+          "combined": true,
+          "header": "Authorization",
+          "scheme": "bearer"
+        }
+      },
+      {
+        "format": "claude",
+        "baseUrl": "https://api.z.ai/api/anthropic/v1/messages",
+        "urlSuffix": "?beta=true",
+        "headers": {
+          "Anthropic-Version": "2023-06-01",
+          "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+        },
+        "auth": {
+          "combined": true,
+          "header": "x-api-key",
+          "scheme": "raw"
+        }
+      }
+    ]
+  },
+  "grok-cli": {
+    "baseUrl": "https://cli-chat-proxy.grok.com/v1/responses",
+    "format": "openai-responses",
+    "forceStream": true,
+    "modelsUrl": "https://cli-chat-proxy.grok.com/v1/models",
+    "userUrl": "https://cli-chat-proxy.grok.com/v1/user",
+    "billingUrl": "https://cli-chat-proxy.grok.com/v1/billing",
+    "clientVersion": "0.2.93",
+    "clientIdentifier": "grok-pager",
+    "tokenAuth": "xai-grok-cli",
+    "headers": {
+      "User-Agent": "grok-pager/0.2.93 grok-shell/0.2.93 (linux; x86_64)",
+      "x-xai-token-auth": "xai-grok-cli",
+      "x-grok-client-identifier": "grok-pager",
+      "x-grok-client-version": "0.2.93",
+      "x-authenticateresponse": "authenticate-response"
+    },
+    "compactionAt": 400000,
+    "retry": {
+      "429": {
+        "attempts": 2,
+        "delayMs": 2000
+      },
+      "502": {
+        "attempts": 2,
+        "delayMs": 1500
+      },
+      "503": {
+        "attempts": 2,
+        "delayMs": 1500
+      }
+    },
+    "clientId": "b1a00492-073a-47ea-816f-4c329264a828",
+    "tokenUrl": "https://auth.x.ai/oauth2/token"
+  },
+  "grok-web": {
+    "baseUrl": "https://grok.com/rest/app-chat/conversations/new",
+    "format": "grok-web",
+    "authType": "cookie"
+  },
+  "groq": {
+    "baseUrl": "https://api.groq.com/openai/v1/chat/completions",
+    "validateUrl": "https://api.groq.com/openai/v1/models",
+    "format": "openai"
+  },
+  "hyperbolic": {
+    "baseUrl": "https://api.hyperbolic.xyz/v1/chat/completions",
+    "validateUrl": "https://api.hyperbolic.xyz/v1/models",
+    "format": "openai"
+  },
+  "iflow": {
+    "baseUrl": "https://apis.iflow.cn/v1/chat/completions",
+    "thinkingFormat": "openai",
+    "headers": {
+      "User-Agent": "iFlow-Cli"
+    },
+    "format": "openai",
+    "clientId": "10009311001",
+    "clientSecret": "4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW",
+    "tokenUrl": "https://iflow.cn/oauth/token"
+  },
+  "kilocode": {
+    "baseUrl": "https://api.kilo.ai/api/openrouter/chat/completions",
+    "headers": {},
+    "auth": {
+      "combined": true,
+      "header": "Authorization",
+      "scheme": "bearer",
+      "hooks": [
+        "kilocodeOrg"
+      ]
+    },
+    "format": "openai"
+  },
+  "kimchi": {
+    "baseUrl": "https://llm.kimchi.dev/openai/v1/chat/completions",
+    "format": "openai",
+    "headers": {
+      "User-Agent": "kimchi/0.1.50"
+    },
+    "auth": {
+      "combined": true,
+      "header": "Authorization",
+      "scheme": "bearer"
+    }
+  },
+  "kimi-coding": {
+    "baseUrl": "https://api.kimi.com/coding/v1/messages",
+    "format": "claude",
+    "urlSuffix": "?beta=true",
+    "headers": {
+      "Anthropic-Version": "2023-06-01",
+      "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+    },
+    "clientId": "17e5f671-d194-4dfb-9706-5516cb48c098",
+    "tokenUrl": "https://auth.kimi.com/api/oauth/token",
+    "refreshUrl": "https://auth.kimi.com/api/oauth/token",
+    "auth": {
+      "combined": true,
+      "header": "x-api-key",
+      "scheme": "raw",
+      "hooks": [
+        "kimiHeaders"
+      ]
+    },
+    "transports": [
+      {
+        "format": "openai",
+        "baseUrl": "https://api.kimi.com/coding/v1/chat/completions",
+        "auth": {
+          "combined": true,
+          "header": "Authorization",
+          "scheme": "bearer",
+          "hooks": [
+            "kimiHeaders"
+          ]
+        }
+      },
+      {
+        "format": "claude",
+        "baseUrl": "https://api.kimi.com/coding/v1/messages",
+        "urlSuffix": "?beta=true",
+        "headers": {
+          "Anthropic-Version": "2023-06-01",
+          "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+        },
+        "auth": {
+          "combined": true,
+          "header": "x-api-key",
+          "scheme": "raw",
+          "hooks": [
+            "kimiHeaders"
+          ]
+        }
+      }
+    ]
+  },
+  "kimi": {
+    "baseUrl": "https://api.kimi.com/coding/v1/messages",
+    "format": "claude",
+    "urlSuffix": "?beta=true",
+    "headers": {
+      "Anthropic-Version": "2023-06-01",
+      "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+    },
+    "auth": {
+      "combined": true,
+      "header": "x-api-key",
+      "scheme": "raw"
+    },
+    "transports": [
+      {
+        "format": "openai",
+        "baseUrl": "https://api.kimi.com/coding/v1/chat/completions",
+        "auth": {
+          "combined": true,
+          "header": "Authorization",
+          "scheme": "bearer"
+        }
+      },
+      {
+        "format": "claude",
+        "baseUrl": "https://api.kimi.com/coding/v1/messages",
+        "urlSuffix": "?beta=true",
+        "headers": {
+          "Anthropic-Version": "2023-06-01",
+          "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+        },
+        "auth": {
+          "combined": true,
+          "header": "x-api-key",
+          "scheme": "raw"
+        }
+      }
+    ]
+  },
+  "kiro": {
+    "baseUrl": "https://runtime.us-east-1.kiro.dev/generateAssistantResponse",
+    "baseUrls": [
+      "https://runtime.us-east-1.kiro.dev/generateAssistantResponse",
+      "https://codewhisperer.us-east-1.amazonaws.com/generateAssistantResponse",
+      "https://q.us-east-1.amazonaws.com/generateAssistantResponse"
+    ],
+    "format": "kiro",
+    "retry": {
+      "429": 0
+    },
+    "headers": {
+      "Content-Type": "application/json",
+      "Accept": "application/vnd.amazon.eventstream",
+      "X-Amz-Target": "AmazonCodeWhispererStreamingService.GenerateAssistantResponse",
+      "User-Agent": "AWS-SDK-JS/3.0.0 kiro-ide/1.0.0",
+      "X-Amz-User-Agent": "aws-sdk-js/3.0.0 kiro-ide/1.0.0"
+    },
+    "tokenUrl": "https://prod.us-east-1.auth.desktop.kiro.dev/refreshToken",
+    "authUrl": "https://prod.us-east-1.auth.desktop.kiro.dev",
+    "usage": {
+      "cwHost": "https://codewhisperer.us-east-1.amazonaws.com",
+      "qHost": "https://q.us-east-1.amazonaws.com",
+      "limitsPath": "/getUsageLimits"
+    }
+  },
+  "mimo-free": {
+    "baseUrl": "https://api.xiaomimimo.com/api/free-ai/openai/chat",
+    "noAuth": true,
+    "format": "openai"
+  },
+  "minimax-cn": {
+    "baseUrl": "https://api.minimaxi.com/anthropic/v1/messages",
+    "format": "claude",
+    "urlSuffix": "?beta=true",
+    "headers": {
+      "Anthropic-Version": "2023-06-01",
+      "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+    },
+    "quirks": {
+      "dropOutputConfig": true
+    },
+    "reasoningInject": {
+      "scope": "all"
+    },
+    "auth": {
+      "combined": true,
+      "header": "x-api-key",
+      "scheme": "raw"
+    },
+    "usage": {
+      "urls": [
+        "https://www.minimaxi.com/v1/api/openplatform/coding_plan/remains",
+        "https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains"
+      ]
+    },
+    "transports": [
+      {
+        "format": "openai",
+        "baseUrl": "https://api.minimaxi.com/v1/chat/completions",
+        "auth": {
+          "combined": true,
+          "header": "Authorization",
+          "scheme": "bearer"
+        }
+      },
+      {
+        "format": "claude",
+        "baseUrl": "https://api.minimaxi.com/anthropic/v1/messages",
+        "urlSuffix": "?beta=true",
+        "headers": {
+          "Anthropic-Version": "2023-06-01",
+          "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+        },
+        "auth": {
+          "combined": true,
+          "header": "x-api-key",
+          "scheme": "raw"
+        }
+      }
+    ]
+  },
+  "minimax": {
+    "baseUrl": "https://api.minimax.io/anthropic/v1/messages",
+    "format": "claude",
+    "urlSuffix": "?beta=true",
+    "headers": {
+      "Anthropic-Version": "2023-06-01",
+      "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+    },
+    "quirks": {
+      "dropOutputConfig": true
+    },
+    "reasoningInject": {
+      "scope": "all"
+    },
+    "auth": {
+      "combined": true,
+      "header": "x-api-key",
+      "scheme": "raw"
+    },
+    "usage": {
+      "urls": [
+        "https://www.minimax.io/v1/token_plan/remains",
+        "https://api.minimax.io/v1/api/openplatform/coding_plan/remains"
+      ]
+    },
+    "transports": [
+      {
+        "format": "openai",
+        "baseUrl": "https://api.minimax.io/v1/chat/completions",
+        "auth": {
+          "combined": true,
+          "header": "Authorization",
+          "scheme": "bearer"
+        }
+      },
+      {
+        "format": "claude",
+        "baseUrl": "https://api.minimax.io/anthropic/v1/messages",
+        "urlSuffix": "?beta=true",
+        "headers": {
+          "Anthropic-Version": "2023-06-01",
+          "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+        },
+        "auth": {
+          "combined": true,
+          "header": "x-api-key",
+          "scheme": "raw"
+        }
+      }
+    ]
+  },
+  "mistral": {
+    "baseUrl": "https://api.mistral.ai/v1/chat/completions",
+    "validateUrl": "https://api.mistral.ai/v1/models",
+    "quirks": {
+      "dropClientMetadata": true
+    },
+    "format": "openai"
+  },
+  "mmf": {
+    "baseUrl": "https://api.xiaomimimo.com/api/free-ai/openai/chat",
+    "noAuth": true,
+    "format": "openai"
+  },
+  "nanobanana": {
+    "baseUrl": "https://api.nanobananaapi.ai/v1/chat/completions",
+    "validateUrl": "https://api.nanobananaapi.ai/v1/models",
+    "format": "openai"
+  },
+  "nebius": {
+    "baseUrl": "https://api.studio.nebius.ai/v1/chat/completions",
+    "validateUrl": "https://api.studio.nebius.ai/v1/models",
+    "format": "openai"
+  },
+  "nvidia": {
+    "baseUrl": "https://integrate.api.nvidia.com/v1/chat/completions",
+    "validateUrl": "https://integrate.api.nvidia.com/v1/models",
+    "format": "openai"
+  },
+  "ollama-local": {
+    "baseUrl": "http://localhost:11434/api/chat",
+    "format": "ollama"
+  },
+  "ollama": {
+    "baseUrl": "https://ollama.com/api/chat",
+    "validateUrl": "https://ollama.com/api/tags",
+    "format": "ollama"
+  },
+  "openai": {
+    "baseUrl": "https://api.openai.com/v1/chat/completions",
+    "forceStream": true,
+    "format": "openai"
+  },
+  "opencode-go": {
+    "baseUrl": "https://opencode.ai/zen/go/v1/chat/completions",
+    "headers": {},
+    "format": "openai"
+  },
+  "opencode": {
+    "baseUrl": "https://opencode.ai",
+    "headers": {
+      "x-opencode-client": "desktop"
+    },
+    "noAuth": true,
+    "format": "openai"
+  },
+  "openrouter": {
+    "baseUrl": "https://openrouter.ai/api/v1/chat/completions",
+    "thinkingFormat": "openai",
+    "headers": {
+      "HTTP-Referer": "https://endpoint-proxy.local",
+      "X-Title": "Endpoint Proxy"
+    },
+    "format": "openai"
+  },
+  "perplexity-web": {
+    "baseUrl": "https://www.perplexity.ai/rest/sse/perplexity_ask",
+    "format": "perplexity-web",
+    "authType": "cookie"
+  },
+  "perplexity": {
+    "baseUrl": "https://api.perplexity.ai/chat/completions",
+    "validateUrl": "https://api.perplexity.ai/models",
+    "format": "openai"
+  },
+  "qoder": {
+    "baseUrl": "https://api3.qoder.sh/algo/api/v2/service/pro/sse/agent_chat_generation",
+    "headers": {},
+    "timeoutMs": 120000,
+    "stallTimeoutMs": 120000,
+    "usage": {
+      "url": "https://openapi.qoder.sh/api/v2/quota/usage"
+    },
+    "format": "openai"
+  },
+  "qwen": {
+    "baseUrl": "https://portal.qwen.ai/v1/chat/completions",
+    "format": "openai",
+    "clientId": "f0304373b74a44d2b584a3fb70ca9e56",
+    "tokenUrl": "https://chat.qwen.ai/api/v1/oauth2/token"
+  },
+  "siliconflow": {
+    "baseUrl": "https://api.siliconflow.com/v1/chat/completions",
+    "validateUrl": "https://api.siliconflow.com/v1/models",
+    "thinkingFormat": "openai",
+    "format": "openai"
+  },
+  "together": {
+    "baseUrl": "https://api.together.xyz/v1/chat/completions",
+    "validateUrl": "https://api.together.xyz/v1/models",
+    "format": "openai"
+  },
+  "venice": {
+    "baseUrl": "https://api.venice.ai/api/v1/chat/completions",
+    "validateUrl": "https://api.venice.ai/api/v1/models",
+    "thinkingFormat": "openai",
+    "format": "openai"
+  },
+  "vercel-ai-gateway": {
+    "baseUrl": "https://ai-gateway.vercel.sh/v1/chat/completions",
+    "thinkingFormat": "openai",
+    "retry": {
+      "429": 2
+    },
+    "usage": {
+      "url": "https://ai-gateway.vercel.sh/v1/credits"
+    },
+    "format": "openai"
+  },
+  "vertex-partner": {
+    "baseUrl": "https://aiplatform.googleapis.com",
+    "format": "openai"
+  },
+  "vertex": {
+    "baseUrl": "https://aiplatform.googleapis.com",
+    "format": "vertex"
+  },
+  "volcengine-ark": {
+    "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions",
+    "headers": {},
+    "format": "openai"
+  },
+  "xai": {
+    "baseUrl": "https://api.x.ai/v1/chat/completions",
+    "validateUrl": "https://api.x.ai/v1/models",
+    "responsesUrl": "https://api.x.ai/v1/responses",
+    "clientId": "b1a00492-073a-47ea-816f-4c329264a828",
+    "tokenUrl": "https://auth.x.ai/oauth2/token",
+    "refreshUrl": "https://auth.x.ai/oauth2/token",
+    "format": "openai"
+  },
+  "xiaomi-mimo": {
+    "baseUrl": "https://api.xiaomimimo.com/v1/chat/completions",
+    "validateUrl": "https://api.xiaomimimo.com/v1/models",
+    "format": "openai",
+    "transports": [
+      {
+        "format": "openai",
+        "baseUrl": "https://api.xiaomimimo.com/v1/chat/completions",
+        "auth": {
+          "combined": true,
+          "header": "Authorization",
+          "scheme": "bearer"
+        }
+      },
+      {
+        "format": "claude",
+        "baseUrl": "https://api.xiaomimimo.com/anthropic/v1/messages",
+        "headers": {
+          "Anthropic-Version": "2023-06-01",
+          "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+        },
+        "auth": {
+          "combined": true,
+          "header": "x-api-key",
+          "scheme": "raw"
+        }
+      }
+    ]
+  },
+  "xiaomi-tokenplan": {
+    "baseUrl": "https://token-plan-sgp.xiaomimimo.com/v1/chat/completions",
+    "regions": {
+      "sgp": "https://token-plan-sgp.xiaomimimo.com/v1",
+      "cn": "https://token-plan-cn.xiaomimimo.com/v1",
+      "ams": "https://token-plan-ams.xiaomimimo.com/v1"
+    },
+    "defaultRegion": "sgp",
+    "format": "openai",
+    "transports": [
+      {
+        "format": "openai",
+        "auth": {
+          "combined": true,
+          "header": "Authorization",
+          "scheme": "bearer"
+        }
+      },
+      {
+        "format": "claude",
+        "headers": {
+          "Anthropic-Version": "2023-06-01",
+          "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14"
+        },
+        "auth": {
+          "combined": true,
+          "header": "x-api-key",
+          "scheme": "raw"
+        }
+      }
+    ]
+  }
+}
\ No newline at end of file
diff --git a/tests/__baseline__/snapshot-providers.mjs b/tests/__baseline__/snapshot-providers.mjs
new file mode 100644
index 0000000..ceb39b6
--- /dev/null
+++ b/tests/__baseline__/snapshot-providers.mjs
@@ -0,0 +1,11 @@
+// Snapshot current PROVIDERS output to JSON (run on OLD code before refactor).
+// Usage: node tests/__baseline__/snapshot-providers.mjs
+import { writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { PROVIDERS } from "../../open-sse/config/providers.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const out = join(here, "providers-baseline.json");
+writeFileSync(out, JSON.stringify(PROVIDERS, null, 2));
+console.log(`Snapshot ${Object.keys(PROVIDERS).length} providers → ${out}`);
diff --git a/tests/__baseline__/verify-alias.mjs b/tests/__baseline__/verify-alias.mjs
new file mode 100644
index 0000000..56caca5
--- /dev/null
+++ b/tests/__baseline__/verify-alias.mjs
@@ -0,0 +1,55 @@
+// Verify alias resolution is byte-for-byte stable (both directions, all sources).
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { resolveProviderAlias } from "../../open-sse/services/model.js";
+import { PROVIDER_ID_TO_ALIAS, PROVIDER_MODELS } from "../../open-sse/config/providerModels.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const snapPath = join(here, "alias-baseline.json");
+
+// All known alias tokens to probe (collected from both maps' historical keys)
+const ALIAS_TOKENS = [
+  "cc","cx","gc","qw","if","ag","gh","kr","cu","kc","kmc","cl","oc","ocg","qd","qoder",
+  "el","openai","vercel","vercel-ai-gateway","anthropic","gemini","openrouter","glm","kimi",
+  "minimax","minimax-cn","hf","huggingface","ds","deepseek","cmc","commandcode","groq","xai",
+  "mistral","pplx","perplexity","together","fireworks","cerebras","cohere","nvidia","nebius",
+  "siliconflow","hyp","hyperbolic","dg","deepgram","aai","assemblyai","nb","nanobanana","ch",
+  "chutes","ark","volcengine-ark","byteplus","bpm","cursor","vx","vertex","vxp","vertex-partner",
+  "gw","grok-web","gcli","gb","grok-build","grok-cli","pw","perplexity-web","mimo","xiaomi-mimo",
+  "xmtp","xiaomi-tokenplan","cf",
+  "cloudflare-ai","fal","fal-ai","stability","stability-ai","bfl","black-forest-labs","recraft",
+  "topaz","runway","runwayml","jina","jina-ai","polly","aws-polly","bb","blackbox",
+];
+
+// Sort idToAlias by key — runtime accesses by key, order is irrelevant (content-based)
+const sortedIdToAlias = Object.fromEntries(
+  Object.keys(PROVIDER_ID_TO_ALIAS).sort().map(k => [k, PROVIDER_ID_TO_ALIAS[k]])
+);
+const resolved = {
+  aliasToId: Object.fromEntries(ALIAS_TOKENS.map(a => [a, resolveProviderAlias(a)])),
+  idToAlias: sortedIdToAlias,
+  modelKeys: Object.keys(PROVIDER_MODELS).sort(),
+};
+const current = JSON.parse(JSON.stringify(resolved));
+
+if (process.argv[2] === "--snapshot") {
+  writeFileSync(snapPath, JSON.stringify(current, null, 2));
+  console.log(`Snapshot alias resolution → ${snapPath}`);
+  process.exit(0);
+}
+if (!existsSync(snapPath)) { console.error("No baseline. Run --snapshot first."); process.exit(1); }
+const baseline = JSON.parse(readFileSync(snapPath, "utf8"));
+if (JSON.stringify(baseline) === JSON.stringify(current)) {
+  console.log(`✅ Alias resolution byte-for-byte equal (${ALIAS_TOKENS.length} tokens).`);
+  process.exit(0);
+}
+// Diff
+for (const a of ALIAS_TOKENS) {
+  if (baseline.aliasToId[a] !== current.aliasToId[a]) {
+    console.error(`~ alias ${a}: ${baseline.aliasToId[a]} -> ${current.aliasToId[a]}`);
+  }
+}
+if (JSON.stringify(baseline.idToAlias) !== JSON.stringify(current.idToAlias)) console.error("~ idToAlias changed");
+if (JSON.stringify(baseline.modelKeys) !== JSON.stringify(current.modelKeys)) console.error("~ modelKeys changed");
+process.exit(1);
diff --git a/tests/__baseline__/verify-no-regression.mjs b/tests/__baseline__/verify-no-regression.mjs
new file mode 100644
index 0000000..26466c2
--- /dev/null
+++ b/tests/__baseline__/verify-no-regression.mjs
@@ -0,0 +1,28 @@
+// Gate: so kết quả test hiện tại với baseline known-fails.
+// PASS nếu KHÔNG có test nào pass(baseline) → fail(now). Test mới được phép.
+// Usage: node tests/__baseline__/verify-no-regression.mjs <current-results.json>
+import { readFileSync } from "fs";
+
+const knownFails = new Set(
+  readFileSync(new URL("./known-fails.txt", import.meta.url), "utf8")
+    .split("\n").map(s => s.trim()).filter(Boolean)
+);
+
+const resultsPath = process.argv[2];
+if (!resultsPath) { console.error("Missing results.json path"); process.exit(2); }
+
+const r = JSON.parse(readFileSync(resultsPath, "utf8"));
+const nowFails = r.testResults.flatMap(f =>
+  f.assertionResults.filter(a => a.status === "failed")
+    .map(a => f.name.split("/app/")[1] + " :: " + a.fullName)
+);
+
+// Regression = fail bây giờ NHƯNG không có trong baseline known-fails
+const regressions = nowFails.filter(f => !knownFails.has(f));
+
+if (regressions.length) {
+  console.error(`\n❌ REGRESSION: ${regressions.length} test pass→fail:\n`);
+  regressions.forEach(f => console.error("  - " + f));
+  process.exit(1);
+}
+console.log(`✅ No regression. (now fails=${nowFails.length}, baseline known=${knownFails.size}, all known)`);
diff --git a/tests/__baseline__/verify-oauth-urls.mjs b/tests/__baseline__/verify-oauth-urls.mjs
new file mode 100644
index 0000000..b0c6a8f
--- /dev/null
+++ b/tests/__baseline__/verify-oauth-urls.mjs
@@ -0,0 +1,70 @@
+// Verify OAuth/token URLs resolve byte-for-byte vs snapshot (backend open-sse).
+// Captures every URL executors/tokenRefresh actually use, to guard DRY dedup.
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { OAUTH_ENDPOINTS } from "../../open-sse/config/appConstants.js";
+import { PROVIDERS } from "../../open-sse/config/providers.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const snapPath = join(here, "oauth-urls-baseline.json");
+
+// Collect resolved URLs that backend code depends on
+const resolved = {
+  oauthEndpoints: OAUTH_ENDPOINTS,
+  tokenUrls: {
+    claude: PROVIDERS.claude?.tokenUrl,
+    codex: PROVIDERS.codex?.tokenUrl,
+    qwen: PROVIDERS.qwen?.tokenUrl,
+    iflow: PROVIDERS.iflow?.tokenUrl,
+    kiro: PROVIDERS.kiro?.tokenUrl,
+    xai: PROVIDERS.xai?.tokenUrl,
+    // Grok CLI injects oauth.tokenUrl onto PROVIDERS via OAUTH_INJECT_FIELDS
+    "grok-cli": PROVIDERS["grok-cli"]?.tokenUrl,
+    cline: PROVIDERS.cline?.tokenUrl,
+    "kimi-coding": PROVIDERS["kimi-coding"]?.tokenUrl,
+  },
+  authUrls: {
+    qwen: PROVIDERS.qwen?.authUrl,
+    iflow: PROVIDERS.iflow?.authUrl,
+    kiro: PROVIDERS.kiro?.authUrl,
+  },
+  refreshUrls: {
+    cline: PROVIDERS.cline?.refreshUrl,
+    "kimi-coding": PROVIDERS["kimi-coding"]?.refreshUrl,
+    xai: PROVIDERS.xai?.refreshUrl,
+    "grok-cli": PROVIDERS["grok-cli"]?.tokenUrl,
+  },
+  clientIds: {
+    claude: PROVIDERS.claude?.clientId,
+    codex: PROVIDERS.codex?.clientId,
+    qwen: PROVIDERS.qwen?.clientId,
+    iflow: PROVIDERS.iflow?.clientId,
+    "kimi-coding": PROVIDERS["kimi-coding"]?.clientId,
+    "grok-cli": PROVIDERS["grok-cli"]?.clientId,
+  },
+};
+const current = JSON.parse(JSON.stringify(resolved));
+
+const mode = process.argv[2];
+if (mode === "--snapshot") {
+  writeFileSync(snapPath, JSON.stringify(current, null, 2));
+  console.log(`Snapshot OAuth URLs → ${snapPath}`);
+  process.exit(0);
+}
+
+if (!existsSync(snapPath)) {
+  console.error("No baseline. Run with --snapshot on OLD code first.");
+  process.exit(1);
+}
+const baseline = JSON.parse(readFileSync(snapPath, "utf8"));
+const a = JSON.stringify(baseline);
+const b = JSON.stringify(current);
+if (a === b) {
+  console.log("✅ OAuth URLs byte-for-byte equal.");
+  process.exit(0);
+}
+console.error("❌ OAuth URL mismatch:");
+console.error("baseline:", a);
+console.error("current :", b);
+process.exit(1);
diff --git a/tests/__baseline__/verify-providers.mjs b/tests/__baseline__/verify-providers.mjs
new file mode 100644
index 0000000..08bb327
--- /dev/null
+++ b/tests/__baseline__/verify-providers.mjs
@@ -0,0 +1,46 @@
+// Verify refactored PROVIDERS is byte-for-byte equal to baseline JSON.
+// Exit 1 + print precise per-provider/per-field diff on mismatch.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { PROVIDERS } from "../../open-sse/config/providers.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const baseline = JSON.parse(readFileSync(join(here, "providers-baseline.json"), "utf8"));
+
+// Fields intentionally added during refactor (verified by dedicated runtime tests, not byte-baseline).
+// authUrl: removed dead field (qwen/iflow) — no consumer reads config.authUrl (oauth block has authorize/deviceCode)
+const ADDED_FIELDS = new Set(["forceStream", "urlSuffix", "retry", "quirks", "auth", "validateUrl", "usage", "clientId", "clientSecret", "tokenUrl", "cliVersion", "apiClient", "copilot", "authorizeUrl", "authUrl", "regions", "defaultRegion", "reasoningInject", "priority", "hasFree"]);
+
+// Normalize via JSON roundtrip so function/undefined are dropped identically; drop added/removed fields.
+// ADDED_FIELDS are verified by dedicated runtime tests, so drop them from BOTH sides (added or intentionally removed).
+const current = JSON.parse(JSON.stringify(PROVIDERS));
+for (const f of ADDED_FIELDS) {
+  for (const id of Object.keys(current)) delete current[id][f];
+  for (const id of Object.keys(baseline)) delete baseline[id][f];
+}
+
+const diffs = [];
+const allIds = new Set([...Object.keys(baseline), ...Object.keys(current)]);
+for (const id of allIds) {
+  const a = baseline[id];
+  const b = current[id];
+  if (a === undefined) { diffs.push(`+ provider added: ${id}`); continue; }
+  if (b === undefined) { diffs.push(`- provider removed: ${id}`); continue; }
+  const sa = JSON.stringify(a);
+  const sb = JSON.stringify(b);
+  if (sa === sb) continue;
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const k of keys) {
+    const va = JSON.stringify(a[k]);
+    const vb = JSON.stringify(b[k]);
+    if (va !== vb) diffs.push(`~ ${id}.${k}: ${va} -> ${vb}`);
+  }
+}
+
+if (diffs.length) {
+  console.error(`❌ PROVIDERS mismatch (${diffs.length} field diffs):`);
+  for (const d of diffs) console.error("  " + d);
+  process.exit(1);
+}
+console.log(`✅ PROVIDERS byte-for-byte equal (${Object.keys(current).length} providers).`);
diff --git a/tests/package.json b/tests/package.json
new file mode 100644
index 0000000..0237ab1
--- /dev/null
+++ b/tests/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "9router-tests",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Unit tests for 9router embeddings endpoint",
+  "scripts": {
+    "test": "NODE_PATH=/tmp/node_modules /tmp/node_modules/.bin/vitest run --reporter=verbose",
+    "test:watch": "NODE_PATH=/tmp/node_modules /tmp/node_modules/.bin/vitest --reporter=verbose"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}
diff --git a/tests/translator/AGENTS.md b/tests/translator/AGENTS.md
new file mode 100644
index 0000000..7b80971
--- /dev/null
+++ b/tests/translator/AGENTS.md
@@ -0,0 +1,122 @@
+# Translation Layer Tests
+
+Tests for `open-sse/translator/`. Goals: (1) data-driven coverage of every provider/model, (2) expose bugs caused by using OpenAI as the intermediate format.
+
+## 1. Translation layer structure (`open-sse/translator/`)
+
+Pipeline uses **OpenAI as the intermediate format**:
+- Request: `source → openai → target` (`translateRequest`)
+- Response (SSE chunk): `target → openai → source` (`translateResponse`)
+- If `source === target` → translation is skipped (passthrough).
+
+Components:
+- `index.js` — `translateRequest` / `translateResponse` / `register(from, to, requestFn, responseFn)` / registry.
+- `formats.js` — `FORMATS` enum (openai, claude, gemini, gemini-cli, openai-responses, antigravity, kiro, cursor, commandcode, ollama, vertex).
+- `request/<from>-to-<to>.js` — one-way request translation.
+- `response/<from>-to-<to>.js` — one-way SSE response translation.
+- `schema/` — pure data enums (no logic): `roles.js` (ROLE, GEMINI_ROLE), `blocks.js` (OPENAI_BLOCK, CLAUDE_BLOCK, RESPONSES_ITEM, valid-type lists), `finishReasons.js` (OPENAI_FINISH, CLAUDE_STOP, GEMINI_FINISH), `defaults.js` (MODEL_FALLBACK, DEFAULT_IMAGE_MIME). Import via `schema/index.js`.
+- `concerns/` — cross-format translation LOGIC: `chunk.js`, `usage.js`, `reasoning.js`, `thinking.js` (effort↔budget/level), `toolCall.js`, `finishReason.js` (mapping fns), `image.js`, `json.js`.
+- `formats/` — per-format logic: `openai.js` (filterToOpenAIFormat), `claude.js`, `gemini.js`, `responsesApi.js`, `maxTokens.js`.
+
+**OpenAI-bridge pitfalls** (source of most bugs): going through OpenAI easily loses `thinking`/`reasoning`, image URLs (non-base64), `input_audio`, `is_error`; tool `id`/`index` become unstable (parallel tool calls), non-text system blocks, `tool_choice:"none"`.
+
+## 2. Test layout
+
+| File | Role |
+|---|---|
+| `matrix.js` | Reads `PROVIDER_MODELS` → builds matrix (alias, model, targetFormat, strip, upstreamId). DRY core. |
+| `registerAll.js` | Imports every translator to run `register()` side-effects. **Required** (see §5). |
+| `coverage-all-models.test.js` | Tier 1: every model translates without throwing; strip applied correctly. |
+| `format-roundtrip.test.js` | Tier 2: tool id/system/parallel survive the bridge. |
+| `bugs-openai-bridge.test.js` | Exposes concrete bugs (with source file:line). |
+
+## 3. Running
+
+Always pass `--config tests/vitest.config.js` (the alias config lives there; without it vitest may not resolve `@/...` subpaths).
+
+```bash
+# no-cred (default, offline): translator-only files
+cd app && npx vitest run --config tests/vitest.config.js "tests/translator/"
+cd app && npx vitest run --config tests/vitest.config.js "tests/translator/bugs-openai-bridge.test.js"
+
+# real (calls live providers using credentials from the local DB)
+cd app && RUN_REAL=1 npx vitest run --config tests/vitest.config.js "tests/translator/real/"
+```
+No-cred tests make NO network calls and need NO creds. Real tests (`real/`, gated by `RUN_REAL=1`) read active connections from `~/.9router/db/data.sqlite`, send a tiny prompt per provider through `handleChatCore`, and assert valid SSE. Account/quota errors (401/402/403/429) are treated as credential issues and skipped, not failures.
+
+## 4. Adding a new provider → tests cover it AUTOMATICALLY
+
+Add a provider by adding a key to `open-sse/config/providerModels.js` `PROVIDER_MODELS` (e.g. `newprov: [{ id, targetFormat?, strip?, upstreamModelId? }]`) plus its config in `open-sse/config/providers.js`.
+
+→ `coverage-all-models.test.js` **automatically** runs for the new models with **no test edits**. `matrix.js` reads config directly.
+
+Only add a dedicated test when a provider has a special format that does not round-trip cleanly (see §7).
+
+## 5. `registerAll.js` — why it is required
+
+`translator/index.js` uses `require(...)` (bundler-only) to lazy-load translators. Under vitest/ESM, `require` **silently no-ops** → empty registry → `translateRequest` skips the translation step → **false pass** (data is lost but the test goes green by mistake).
+
+→ Every test calling `translateRequest`/`translateResponse` MUST `import "./registerAll.js"` at the top of the file.
+
+## 6. Bug-exposure convention — `it.fails`
+
+- A bug confirmed in the app but NOT yet fixed → use `it.fails(...)`.
+- `it.fails` **passes while the app still has the bug**, **turns red once the bug is fixed** → a reminder to update the test (switch `it.fails` → `it` and confirm correct behavior).
+- Pattern for a new bug-exposure test: real input → assert the "should-be-kept" behavior → wrap in `it.fails` + a comment with the source `file:line`.
+
+## 7. Special formats to watch
+
+- `kiro` (binary AWS EventStream), `cursor` (protobuf ConnectRPC), `commandcode` (NDJSON) → responses do NOT round-trip cleanly through openai; test via their executors, not just the translator.
+- Single-provider-two-formats (most fragile): `opencode-go` (minimax models → claude, others openai), `github` (escalates `/chat/completions` → `/responses` at runtime), `xiaomi-tokenplan` (claude alias).
+- `gemini`/`gemini-cli`: only the LAST system message is kept → earlier system messages are lost.
+
+## 8. Current known bugs (currently `it.fails`)
+
+Grouped per CLI/provider test file. Each row is an `it.fails` case.
+
+**Claude (`bugs-openai-bridge.test.js`, `bugs-claudeCode-context.test.js`)**
+| Bug | Source |
+|---|---|
+| Claude image `source.type="url"` dropped (only base64) | `request/claude-to-openai.js:133-141` |
+| `tool_result` image block → raw JSON | `request/claude-to-openai.js:155-173` |
+| `tool_result.is_error` lost | `request/claude-to-openai.js:155-173` |
+| `thinking`/`redacted_thinking` dropped via bridge | `request/claude-to-openai.js:128` |
+
+**OpenAI → Claude (`bugs-toClaude-context.test.js`)**
+| Bug | Source |
+|---|---|
+| Always injects "You are Claude Code" system prompt | `request/openai-to-claude.js:124-134` |
+| `reasoning_content` not mapped to a thinking block | `request/openai-to-claude.js:268-273` |
+| `tool_choice:"none"` → `auto` | `request/openai-to-claude.js:298` |
+| `input_audio` dropped | `request/openai-to-claude.js` (no audio branch) |
+
+**Codex Responses (`bugs-codexCli-responses.test.js`)**
+| Bug | Source |
+|---|---|
+| Empty-name function_call can leave `tool_calls: []` | `request/openai-responses.js:103` |
+| `arguments` not coerced to string | `request/openai-responses.js:109-110` |
+| `input_image` uses `file_id` as raw url | `request/openai-responses.js:75-77` |
+
+**Antigravity (`bugs-antigravity.test.js`)**
+| Bug | Source |
+|---|---|
+| functionResponse + functionCall in same content → tool calls dropped | `request/antigravity-to-openai.js:177-189` |
+| functionCall without id → random unstable id | `request/antigravity-to-openai.js:167` |
+
+**Kiro (`bugs-kiro.test.js`)**
+| Bug | Source |
+|---|---|
+| `JSON.parse(arguments)` throws on bad JSON (no try/catch) | `request/openai-to-kiro.js:214-216` |
+| `max_tokens` hardcoded to 32000 | `request/openai-to-kiro.js:309` |
+| Remote image → `[Image: url]` text | `request/openai-to-kiro.js:132-134` |
+
+**Gemini / Cursor / CommandCode (`bugs-gemini-cursor-commandcode.test.js`)**
+| Bug | Source |
+|---|---|
+| Only the last system message kept | `request/openai-to-gemini.js:92-96` |
+| Cursor drops image content | `request/openai-to-cursor.js:12-24` |
+| Cursor `max_tokens` hardcoded to 32000 | `request/openai-to-cursor.js:179` |
+| CommandCode bad JSON args → `{}` silently | `request/openai-to-commandcode.js:53-57` |
+| CommandCode image → `[image omitted]` | `request/openai-to-commandcode.js:41-42` |
+
+Fixing a bug → rerun; the matching `it.fails` test turns RED → switch it to a regular `it` and verify correct behavior.
diff --git a/tests/translator/__snapshots__/golden-request.test.js.snap b/tests/translator/__snapshots__/golden-request.test.js.snap
new file mode 100644
index 0000000..17fa66d
--- /dev/null
+++ b/tests/translator/__snapshots__/golden-request.test.js.snap
@@ -0,0 +1,317 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`GOLDEN request: OpenAI → Claude > full body (system/image/tool/tool_result) 1`] = `
+{
+  "max_tokens": 64000,
+  "messages": [
+    {
+      "content": [
+        {
+          "text": "What's in this image?",
+          "type": "text",
+        },
+        {
+          "source": {
+            "data": "IMGDATA",
+            "media_type": "image/png",
+            "type": "base64",
+          },
+          "type": "image",
+        },
+      ],
+      "role": "user",
+    },
+    {
+      "content": [
+        {
+          "cache_control": {
+            "type": "ephemeral",
+          },
+          "id": "call_1",
+          "input": {
+            "city": "NYC",
+          },
+          "name": "get_weather",
+          "type": "tool_use",
+        },
+      ],
+      "role": "assistant",
+    },
+    {
+      "content": [
+        {
+          "content": "sunny",
+          "tool_use_id": "call_1",
+          "type": "tool_result",
+        },
+      ],
+      "role": "user",
+    },
+  ],
+  "model": "claude-opus-4-6",
+  "stream": true,
+  "system": [
+    {
+      "text": "You are Claude Code, Anthropic's official CLI for Claude.",
+      "type": "text",
+    },
+    {
+      "cache_control": {
+        "ttl": "1h",
+        "type": "ephemeral",
+      },
+      "text": "You are helpful.",
+      "type": "text",
+    },
+  ],
+  "temperature": 0.7,
+  "tools": [
+    {
+      "cache_control": {
+        "ttl": "1h",
+        "type": "ephemeral",
+      },
+      "description": "Get weather",
+      "input_schema": {
+        "properties": {
+          "city": {
+            "type": "string",
+          },
+        },
+        "required": [
+          "city",
+        ],
+        "type": "object",
+      },
+      "name": "get_weather",
+    },
+  ],
+}
+`;
+
+exports[`GOLDEN request: OpenAI → Claude > reasoning_effort → adaptive output_config (claude 4.6+) 1`] = `
+{
+  "max_tokens": 64000,
+  "messages": [
+    {
+      "content": [
+        {
+          "text": "hi",
+          "type": "text",
+        },
+      ],
+      "role": "user",
+    },
+  ],
+  "model": "claude-opus-4-6",
+  "output_config": {
+    "effort": "high",
+  },
+  "stream": true,
+  "system": [
+    {
+      "cache_control": {
+        "ttl": "1h",
+        "type": "ephemeral",
+      },
+      "text": "You are Claude Code, Anthropic's official CLI for Claude.",
+      "type": "text",
+    },
+  ],
+}
+`;
+
+exports[`GOLDEN request: OpenAI → Gemini > full body (system/image/tool/tool_result) 1`] = `
+{
+  "contents": [
+    {
+      "parts": [
+        {
+          "text": "What's in this image?",
+        },
+        {
+          "inlineData": {
+            "data": "IMGDATA",
+            "mime_type": "image/png",
+          },
+        },
+      ],
+      "role": "user",
+    },
+    {
+      "parts": [
+        {
+          "functionCall": {
+            "args": {
+              "city": "NYC",
+            },
+            "id": "call_1",
+            "name": "get_weather",
+          },
+          "thoughtSignature": "EuwGCukGAXLI2nxwZIq54WWSoL/YN0P3TsDZ7zRnLi8g0S4aVr2HUGxvaHKySuY6HAVzcE0GPGjXrytLIldxthSvfxgUlJh6Qa9Z+Oj5QZBlYdg6HaJ6yuY5R7waE6rdwBsRf7Ft2j3DJ9rMi9qhWFqApewYtPhls3VHtuvND3l8Rm09+lbAXQs6KKWEWrxNLKTBkfpMgXhRERc/TQRMZu1twAablm6/Zk1tsYRvfWKLsNbeKF+CCojJdXJKvnR/8Ouuoa+Y2Ti20hcW7aZIIjZDFYPU//k6Ybmhg69J/imbFai2ckhfLaisqdDkdoIiBJScTOUvYqP6AE9d4MsydSC+UlhIMk4hoP76R8vUSCZRMkjOaDXstf/QoVZKbt94wyRZgAJ1G0BqI8L5ow86kLpA4wJEtxsRGymOE4bKUvApveBakYDNM9APkf+LbtbzWSseGjoZcSlycF9iN8Q2XNYKRrHbv3Lr5Y8JjdH/5y/6SHkNehTEZugaeGnSPSyCTWto1kQgHpxdWmhkLfJGNUGLmue7Mesj4TSms4J33mRpYVhNB/J333FCqIP0hr/E7BkkjEn7yZ4X7SQlh+xKPurapsnHRwiKmtsilmEFrnTE9iQr+pMr6M29qqFNv1tr5yumbaJw8JW9sB15tNsRv+dW6BjNanbsKz7HCgKUBc8tGy+7YuhXzAfViyRefcjK7eZW0Fbyt7AbybJTKz78W8NH7ye6LAwzOebXpeZ4D43fNIt8bKh26qgduSQv/7o+pAflkuqHZ99YWgHQ8h8OkZFi3eOiSYjsjhdZ/czWOdoPI/OnqIldzMPF5YlrKBLFX8VhRKVmqgsmWf5PHGulHhMkVlS+XG2UIseGy69ARa93D78Gsa+1n1kJr7EEB7Rh+27vUMxVYLdz1yMSvE5nalTAlg/ZeG8+XQ0cHuAI3KbQpHW2Q++RdXfm5JzD5WdJZUU+Zn8t8UUn85BH4RxZLeE0qJikgSsKoYVBc6YhiMjhPgkR95ReimY4Z0xCJdRo1gjexOFeODZMpQF6Yxnoic7IrdgsFA3iePTbFnPp3IAM1fAThWhXJUn3QInUOTd5o1qmTmn6REbL15g/JQNl+dqUoPkhleeb2V3kjqp1okmO3wMZbPknR3S1LZNmlS72/iBQUm+n2b/RCn4PjmM2",
+        },
+      ],
+      "role": "model",
+    },
+    {
+      "parts": [
+        {
+          "functionResponse": {
+            "id": "call_1",
+            "name": "get_weather",
+            "response": {
+              "result": {
+                "result": "sunny",
+              },
+            },
+          },
+        },
+      ],
+      "role": "user",
+    },
+  ],
+  "generationConfig": {
+    "temperature": 0.7,
+  },
+  "model": "gemini-3-pro",
+  "safetySettings": [
+    {
+      "category": "HARM_CATEGORY_HATE_SPEECH",
+      "threshold": "OFF",
+    },
+    {
+      "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
+      "threshold": "OFF",
+    },
+    {
+      "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+      "threshold": "OFF",
+    },
+    {
+      "category": "HARM_CATEGORY_HARASSMENT",
+      "threshold": "OFF",
+    },
+    {
+      "category": "HARM_CATEGORY_CIVIC_INTEGRITY",
+      "threshold": "OFF",
+    },
+  ],
+  "systemInstruction": {
+    "parts": [
+      {
+        "text": "You are helpful.",
+      },
+    ],
+    "role": "user",
+  },
+  "tools": [
+    {
+      "functionDeclarations": [
+        {
+          "description": "Get weather",
+          "name": "get_weather",
+          "parameters": {
+            "properties": {
+              "city": {
+                "type": "string",
+              },
+            },
+            "required": [
+              "city",
+            ],
+            "type": "object",
+          },
+        },
+      ],
+    },
+  ],
+}
+`;
+
+exports[`GOLDEN request: OpenAI → Kiro > full body (image base64 + tool_result) 1`] = `
+{
+  "conversationState": {
+    "chatTriggerType": "MANUAL",
+    "currentMessage": {
+      "userInputMessage": {
+        "content": "[Context: Current time is <TS>
+
+continue",
+        "modelId": "claude-sonnet-4.5",
+        "origin": "AI_EDITOR",
+        "userInputMessageContext": {
+          "toolResults": [
+            {
+              "content": [
+                {
+                  "text": "sunny",
+                },
+              ],
+              "status": "success",
+              "toolUseId": "call_1",
+            },
+          ],
+          "tools": [
+            {
+              "toolSpecification": {
+                "description": "Get weather",
+                "inputSchema": {
+                  "json": {
+                    "properties": {
+                      "city": {
+                        "type": "string",
+                      },
+                    },
+                    "required": [
+                      "city",
+                    ],
+                    "type": "object",
+                  },
+                },
+                "name": "get_weather",
+              },
+            },
+          ],
+        },
+      },
+    },
+    "history": [
+      {
+        "userInputMessage": {
+          "content": "You are helpful.
+
+What's in this image?",
+          "images": [
+            {
+              "format": "png",
+              "source": {
+                "bytes": "IMGDATA",
+              },
+            },
+          ],
+          "modelId": "claude-sonnet-4.5",
+        },
+      },
+      {
+        "assistantResponseMessage": {
+          "content": "...",
+          "toolUses": [
+            {
+              "input": {
+                "city": "NYC",
+              },
+              "name": "get_weather",
+              "toolUseId": "call_1",
+            },
+          ],
+        },
+      },
+    ],
+  },
+  "inferenceConfig": {
+    "maxTokens": 32000,
+    "temperature": 0.7,
+  },
+  "profileArn": "arn:aws:codewhisperer:us-east-1:638616132270:profile/AAAACCCCXXXX",
+}
+`;
diff --git a/tests/translator/__snapshots__/golden-response-stream.test.js.snap b/tests/translator/__snapshots__/golden-response-stream.test.js.snap
new file mode 100644
index 0000000..190047f
--- /dev/null
+++ b/tests/translator/__snapshots__/golden-response-stream.test.js.snap
@@ -0,0 +1,570 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`GOLDEN response stream: Claude → OpenAI > text + thinking + tool_use + usage + finish 1`] = `
+[
+  {
+    "choices": [
+      {
+        "delta": {
+          "role": "assistant",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-msg_1",
+    "model": "claude-opus-4-6",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "content": "<think>",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-msg_1",
+    "model": "claude-opus-4-6",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "reasoning_content": "let me think",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-msg_1",
+    "model": "claude-opus-4-6",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "content": "</think>",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-msg_1",
+    "model": "claude-opus-4-6",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "content": "Hello",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-msg_1",
+    "model": "claude-opus-4-6",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "{"city":"NYC"}",
+                "name": "get_weather",
+              },
+              "id": "tu_1",
+              "index": 0,
+              "type": "function",
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-msg_1",
+    "model": "claude-opus-4-6",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "{"city":"NYC"}",
+              },
+              "id": "tu_1",
+              "index": 0,
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-msg_1",
+    "model": "claude-opus-4-6",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {},
+        "finish_reason": "tool_calls",
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-msg_1",
+    "model": "claude-opus-4-6",
+    "object": "chat.completion.chunk",
+    "usage": {
+      "completion_tokens": 5,
+      "prompt_tokens": 13,
+      "prompt_tokens_details": {
+        "cached_tokens": 3,
+      },
+      "total_tokens": 18,
+    },
+  },
+]
+`;
+
+exports[`GOLDEN response stream: Gemini → OpenAI > image output (inlineData → delta.images) 1`] = `
+[
+  {
+    "choices": [
+      {
+        "delta": {
+          "role": "assistant",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-resp_2",
+    "model": "gemini-3-flash-image",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "images": [
+            {
+              "image_url": {
+                "url": "data:image/png;base64,BASE64DATA",
+              },
+              "type": "image_url",
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-resp_2",
+    "model": "gemini-3-flash-image",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {},
+        "finish_reason": "stop",
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-resp_2",
+    "model": "gemini-3-flash-image",
+    "object": "chat.completion.chunk",
+  },
+]
+`;
+
+exports[`GOLDEN response stream: Gemini → OpenAI > text + thought(no-sig) + functionCall + usage + finish 1`] = `
+[
+  {
+    "choices": [
+      {
+        "delta": {
+          "role": "assistant",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-resp_1",
+    "model": "gemini-3-pro",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "reasoning_content": "thinking part",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-resp_1",
+    "model": "gemini-3-pro",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "content": "Answer",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-resp_1",
+    "model": "gemini-3-pro",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "{"q":"x"}",
+                "name": "search",
+              },
+              "id": "search-<TS>-0",
+              "index": 0,
+              "type": "function",
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-resp_1",
+    "model": "gemini-3-pro",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {},
+        "finish_reason": "tool_calls",
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-resp_1",
+    "model": "gemini-3-pro",
+    "object": "chat.completion.chunk",
+    "usage": {
+      "completion_tokens": 6,
+      "completion_tokens_details": {
+        "reasoning_tokens": 2,
+      },
+      "prompt_tokens": 8,
+      "prompt_tokens_details": {
+        "cached_tokens": 1,
+      },
+      "total_tokens": 14,
+    },
+  },
+]
+`;
+
+exports[`GOLDEN response stream: Kiro → OpenAI > text + reasoning + toolUse + usage + stop 1`] = `
+[
+  {
+    "choices": [
+      {
+        "delta": {
+          "content": "Hello",
+          "role": "assistant",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "kiro",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "reasoning_content": "thinking",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "kiro",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "{"city":"NYC"}",
+                "name": "get_weather",
+              },
+              "id": "tu_1",
+              "index": 0,
+              "type": "function",
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "kiro",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {},
+        "finish_reason": "tool_calls",
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "kiro",
+    "object": "chat.completion.chunk",
+    "usage": {
+      "completion_tokens": 5,
+      "prompt_tokens": 10,
+      "total_tokens": 15,
+    },
+  },
+]
+`;
+
+exports[`GOLDEN response stream: Ollama → OpenAI > content + thinking + tool_calls + done usage 1`] = `
+[
+  {
+    "choices": [
+      {
+        "delta": {
+          "content": "Hi",
+          "reasoning_content": "reason",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "qwen3",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "{"q":"x"}",
+                "name": "search",
+              },
+              "id": "call_0_<TS>",
+              "index": 0,
+              "type": "function",
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "qwen3",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {},
+        "finish_reason": "tool_calls",
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "qwen3",
+    "object": "chat.completion.chunk",
+    "usage": {
+      "completion_tokens": 4,
+      "prompt_tokens": 8,
+      "total_tokens": 12,
+    },
+  },
+]
+`;
+
+exports[`GOLDEN response stream: OpenAI-Responses (codex) → OpenAI > error event → error chunk (fallback id/created) 1`] = `
+[
+  {
+    "choices": [
+      {
+        "delta": {
+          "content": "[Error] model_not_found",
+        },
+        "finish_reason": "stop",
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "unknown",
+    "object": "chat.completion.chunk",
+  },
+]
+`;
+
+exports[`GOLDEN response stream: OpenAI-Responses (codex) → OpenAI > text + reasoning + tool_call + completed usage 1`] = `
+[
+  {
+    "choices": [
+      {
+        "delta": {
+          "content": "Hello",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "unknown",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "reasoning_content": "thinking",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "unknown",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "",
+                "name": "get_weather",
+              },
+              "id": "call_1",
+              "index": 0,
+              "type": "function",
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "unknown",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "{"city":"NYC"}",
+              },
+              "index": 0,
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "unknown",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {},
+        "finish_reason": "tool_calls",
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "unknown",
+    "object": "chat.completion.chunk",
+    "usage": {
+      "completion_tokens": 5,
+      "prompt_tokens": 10,
+      "prompt_tokens_details": {
+        "cached_tokens": 3,
+      },
+      "total_tokens": 15,
+    },
+  },
+]
+`;
diff --git a/tests/translator/__snapshots__/golden-translator-concerns.test.js.snap b/tests/translator/__snapshots__/golden-translator-concerns.test.js.snap
new file mode 100644
index 0000000..2d7cfc6
--- /dev/null
+++ b/tests/translator/__snapshots__/golden-translator-concerns.test.js.snap
@@ -0,0 +1,226 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`GOLDEN response stream: CommandCode → OpenAI > text + reasoning + tool + finish-step usage 1`] = `
+[
+  {
+    "choices": [
+      {
+        "delta": {
+          "content": "Hello",
+          "role": "assistant",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "commandcode",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "reasoning_content": "thinking",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "commandcode",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "",
+                "name": "get_weather",
+              },
+              "id": "t1",
+              "index": 0,
+              "type": "function",
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "commandcode",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "{"city":"NYC"}",
+              },
+              "index": 0,
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "commandcode",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {},
+        "finish_reason": "tool_calls",
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "commandcode",
+    "object": "chat.completion.chunk",
+    "usage": {
+      "completion_tokens": 5,
+      "prompt_tokens": 10,
+      "total_tokens": 15,
+    },
+  },
+]
+`;
+
+exports[`GOLDEN response stream: Kiro → OpenAI (finish after tool) > toolUse then stop — lock current finish_reason behavior 1`] = `
+[
+  {
+    "choices": [
+      {
+        "delta": {
+          "content": "Hi",
+          "role": "assistant",
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "kiro",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "{"q":"x"}",
+                "name": "search",
+              },
+              "id": "tu_1",
+              "index": 0,
+              "type": "function",
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "kiro",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {},
+        "finish_reason": "tool_calls",
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "kiro",
+    "object": "chat.completion.chunk",
+    "usage": {
+      "completion_tokens": 3,
+      "prompt_tokens": 7,
+      "total_tokens": 10,
+    },
+  },
+]
+`;
+
+exports[`GOLDEN response stream: Ollama → OpenAI (finish after tool) > tool_calls then done_reason=stop — lock current finish_reason 1`] = `
+[
+  {
+    "choices": [
+      {
+        "delta": {
+          "tool_calls": [
+            {
+              "function": {
+                "arguments": "{"q":"x"}",
+                "name": "search",
+              },
+              "id": "call_0_<TS>",
+              "index": 0,
+              "type": "function",
+            },
+          ],
+        },
+        "finish_reason": null,
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "qwen3",
+    "object": "chat.completion.chunk",
+  },
+  {
+    "choices": [
+      {
+        "delta": {},
+        "finish_reason": "tool_calls",
+        "index": 0,
+      },
+    ],
+    "created": 0,
+    "id": "chatcmpl-<TS>",
+    "model": "qwen3",
+    "object": "chat.completion.chunk",
+    "usage": {
+      "completion_tokens": 2,
+      "prompt_tokens": 5,
+      "total_tokens": 7,
+    },
+  },
+]
+`;
+
+exports[`GOLDEN usage math: Claude prompt = input + cache (lock) > prompt_tokens sums input + cache_read + cache_creation 1`] = `
+{
+  "completion_tokens": 5,
+  "prompt_tokens": 15,
+  "prompt_tokens_details": {
+    "cache_creation_tokens": 2,
+    "cached_tokens": 3,
+  },
+  "total_tokens": 20,
+}
+`;
diff --git a/tests/translator/__snapshots__/golden-url-header.test.js.snap b/tests/translator/__snapshots__/golden-url-header.test.js.snap
new file mode 100644
index 0000000..9482052
--- /dev/null
+++ b/tests/translator/__snapshots__/golden-url-header.test.js.snap
@@ -0,0 +1,1237 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`GOLDEN buildHeaders (default executor providers) > alicode → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > alicode-intl → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > anthropic → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "anthropic-version": "2023-06-01",
+    "x-api-key": "<CRED>",
+  },
+  "nonStream": {
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "anthropic-version": "2023-06-01",
+    "x-api-key": "<CRED>",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "anthropic-version": "2023-06-01",
+    "x-api-key": "<CRED>",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > assemblyai → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > blackbox → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > byteplus → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > cerebras → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > chutes → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > claude → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28",
+    "Anthropic-Dangerous-Direct-Browser-Access": "true",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "User-Agent": "claude-cli/2.1.92 (external, sdk-cli)",
+    "X-App": "cli",
+    "X-Stainless-Arch": "arm64",
+    "X-Stainless-Helper-Method": "stream",
+    "X-Stainless-Lang": "js",
+    "X-Stainless-Os": "MacOS",
+    "X-Stainless-Package-Version": "0.80.0",
+    "X-Stainless-Retry-Count": "0",
+    "X-Stainless-Runtime": "node",
+    "X-Stainless-Runtime-Version": "v24.14.0",
+    "X-Stainless-Timeout": "600",
+    "x-api-key": "<CRED>",
+  },
+  "nonStream": {
+    "Anthropic-Beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28",
+    "Anthropic-Dangerous-Direct-Browser-Access": "true",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "User-Agent": "claude-cli/2.1.92 (external, sdk-cli)",
+    "X-App": "cli",
+    "X-Stainless-Arch": "arm64",
+    "X-Stainless-Helper-Method": "stream",
+    "X-Stainless-Lang": "js",
+    "X-Stainless-Os": "MacOS",
+    "X-Stainless-Package-Version": "0.80.0",
+    "X-Stainless-Retry-Count": "0",
+    "X-Stainless-Runtime": "node",
+    "X-Stainless-Runtime-Version": "v24.14.0",
+    "X-Stainless-Timeout": "600",
+    "x-api-key": "<CRED>",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28",
+    "Anthropic-Dangerous-Direct-Browser-Access": "true",
+    "Anthropic-Version": "2023-06-01",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+    "User-Agent": "claude-cli/2.1.92 (external, sdk-cli)",
+    "X-App": "cli",
+    "X-Stainless-Arch": "arm64",
+    "X-Stainless-Helper-Method": "stream",
+    "X-Stainless-Lang": "js",
+    "X-Stainless-Os": "MacOS",
+    "X-Stainless-Package-Version": "0.80.0",
+    "X-Stainless-Retry-Count": "0",
+    "X-Stainless-Runtime": "node",
+    "X-Stainless-Runtime-Version": "v24.14.0",
+    "X-Stainless-Timeout": "600",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > cline → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+    "HTTP-Referer": "https://cline.bot",
+    "User-Agent": "9Router/0.4.80",
+    "X-CLIENT-TYPE": "9router",
+    "X-CLIENT-VERSION": "0.4.80",
+    "X-CORE-VERSION": "0.4.80",
+    "X-IS-MULTIROOT": "false",
+    "X-PLATFORM": "darwin",
+    "X-PLATFORM-VERSION": "v22.22.0",
+    "X-Title": "Cline",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+    "HTTP-Referer": "https://cline.bot",
+    "User-Agent": "9Router/0.4.80",
+    "X-CLIENT-TYPE": "9router",
+    "X-CLIENT-VERSION": "0.4.80",
+    "X-CORE-VERSION": "0.4.80",
+    "X-IS-MULTIROOT": "false",
+    "X-PLATFORM": "darwin",
+    "X-PLATFORM-VERSION": "v22.22.0",
+    "X-Title": "Cline",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+    "HTTP-Referer": "https://cline.bot",
+    "User-Agent": "9Router/0.4.80",
+    "X-CLIENT-TYPE": "9router",
+    "X-CLIENT-VERSION": "0.4.80",
+    "X-CORE-VERSION": "0.4.80",
+    "X-IS-MULTIROOT": "false",
+    "X-PLATFORM": "darwin",
+    "X-PLATFORM-VERSION": "v22.22.0",
+    "X-Title": "Cline",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > cloudflare-ai → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > codebuddy-cn → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+    "User-Agent": "CLI/2.108.1 CodeBuddy/2.108.1",
+    "X-IDE-Name": "CLI",
+    "X-IDE-Type": "CLI",
+    "X-Product": "SaaS",
+    "x-codebuddy-request": "1",
+    "x-requested-with": "XMLHttpRequest",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+    "User-Agent": "CLI/2.108.1 CodeBuddy/2.108.1",
+    "X-IDE-Name": "CLI",
+    "X-IDE-Type": "CLI",
+    "X-Product": "SaaS",
+    "x-codebuddy-request": "1",
+    "x-requested-with": "XMLHttpRequest",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+    "User-Agent": "CLI/2.108.1 CodeBuddy/2.108.1",
+    "X-IDE-Name": "CLI",
+    "X-IDE-Type": "CLI",
+    "X-Product": "SaaS",
+    "x-codebuddy-request": "1",
+    "x-requested-with": "XMLHttpRequest",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > cohere → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > deepgram → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > deepseek → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > fireworks → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > gemini → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Content-Type": "application/json",
+    "x-goog-api-key": "<CRED>",
+  },
+  "nonStream": {
+    "Content-Type": "application/json",
+    "x-goog-api-key": "<CRED>",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > gitlab → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > glm → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+  "nonStream": {
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > glm-cn → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > groq → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > hyperbolic → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > kilocode → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > kimi → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+  "nonStream": {
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > kimi-coding → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "X-Msh-Device-Id": "kimi-<TS>",
+    "X-Msh-Device-Model": "darwin arm64",
+    "X-Msh-Platform": "9router",
+    "X-Msh-Version": "2.1.2",
+    "x-api-key": "<CRED>",
+  },
+  "nonStream": {
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "X-Msh-Device-Id": "kimi-<TS>",
+    "X-Msh-Device-Model": "darwin arm64",
+    "X-Msh-Platform": "9router",
+    "X-Msh-Version": "2.1.2",
+    "x-api-key": "<CRED>",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "X-Msh-Device-Id": "kimi-<TS>",
+    "X-Msh-Device-Model": "darwin arm64",
+    "X-Msh-Platform": "9router",
+    "X-Msh-Version": "2.1.2",
+    "x-api-key": "<CRED>",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > minimax → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+  "nonStream": {
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > minimax-cn → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+  "nonStream": {
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
+    "Anthropic-Version": "2023-06-01",
+    "Content-Type": "application/json",
+    "x-api-key": "<CRED>",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > mistral → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > mmf → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > nanobanana → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > nebius → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > nvidia → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > ollama → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > openai → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > openrouter → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+    "HTTP-Referer": "https://endpoint-proxy.local",
+    "X-Title": "Endpoint Proxy",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+    "HTTP-Referer": "https://endpoint-proxy.local",
+    "X-Title": "Endpoint Proxy",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+    "HTTP-Referer": "https://endpoint-proxy.local",
+    "X-Title": "Endpoint Proxy",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > perplexity → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > siliconflow → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > together → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > vercel-ai-gateway → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > volcengine-ark → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > xai → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildHeaders (default executor providers) > xiaomi-mimo → headers (apiKey / oauth) 1`] = `
+{
+  "apiKey": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "nonStream": {
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+  "oauth": {
+    "Accept": "text/event-stream",
+    "Authorization": "Bearer <TOK>",
+    "Content-Type": "application/json",
+  },
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > alicode → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://coding.dashscope.aliyuncs.com/v1/chat/completions",
+  "stream": "https://coding.dashscope.aliyuncs.com/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > alicode-intl → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://coding-intl.dashscope.aliyuncs.com/v1/chat/completions",
+  "stream": "https://coding-intl.dashscope.aliyuncs.com/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > anthropic → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.anthropic.com/v1/messages",
+  "stream": "https://api.anthropic.com/v1/messages",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > assemblyai → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.assemblyai.com/v1/audio/transcriptions",
+  "stream": "https://api.assemblyai.com/v1/audio/transcriptions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > blackbox → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.blackbox.ai/chat/completions",
+  "stream": "https://api.blackbox.ai/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > byteplus → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://ark.ap-southeast.bytepluses.com/api/coding/v3/chat/completions",
+  "stream": "https://ark.ap-southeast.bytepluses.com/api/coding/v3/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > cerebras → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.cerebras.ai/v1/chat/completions",
+  "stream": "https://api.cerebras.ai/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > chutes → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://llm.chutes.ai/v1/chat/completions",
+  "stream": "https://llm.chutes.ai/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > claude → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.anthropic.com/v1/messages?beta=true",
+  "stream": "https://api.anthropic.com/v1/messages?beta=true",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > cline → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.cline.bot/api/v1/chat/completions",
+  "stream": "https://api.cline.bot/api/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > cloudflare-ai → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.cloudflare.com/client/v4/accounts/ACC123/ai/v1/chat/completions",
+  "stream": "https://api.cloudflare.com/client/v4/accounts/ACC123/ai/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > codebuddy-cn → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://copilot.tencent.com/v2/chat/completions",
+  "stream": "https://copilot.tencent.com/v2/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > cohere → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.cohere.ai/v1/chat/completions",
+  "stream": "https://api.cohere.ai/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > deepgram → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.deepgram.com/v1/listen",
+  "stream": "https://api.deepgram.com/v1/listen",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > deepseek → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.deepseek.com/chat/completions",
+  "stream": "https://api.deepseek.com/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > fireworks → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.fireworks.ai/inference/v1/chat/completions",
+  "stream": "https://api.fireworks.ai/inference/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > gemini → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://generativelanguage.googleapis.com/v1beta/models/test-model:generateContent",
+  "stream": "https://generativelanguage.googleapis.com/v1beta/models/test-model:streamGenerateContent?alt=sse",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > gitlab → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://gitlab.com/api/v4/chat/completions",
+  "stream": "https://gitlab.com/api/v4/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > glm → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.z.ai/api/anthropic/v1/messages?beta=true",
+  "stream": "https://api.z.ai/api/anthropic/v1/messages?beta=true",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > glm-cn → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://open.bigmodel.cn/api/coding/paas/v4/chat/completions",
+  "stream": "https://open.bigmodel.cn/api/coding/paas/v4/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > groq → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.groq.com/openai/v1/chat/completions",
+  "stream": "https://api.groq.com/openai/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > hyperbolic → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.hyperbolic.xyz/v1/chat/completions",
+  "stream": "https://api.hyperbolic.xyz/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > kilocode → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.kilo.ai/api/openrouter/chat/completions",
+  "stream": "https://api.kilo.ai/api/openrouter/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > kimi → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.kimi.com/coding/v1/messages?beta=true",
+  "stream": "https://api.kimi.com/coding/v1/messages?beta=true",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > kimi-coding → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.kimi.com/coding/v1/messages?beta=true",
+  "stream": "https://api.kimi.com/coding/v1/messages?beta=true",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > minimax → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.minimax.io/anthropic/v1/messages?beta=true",
+  "stream": "https://api.minimax.io/anthropic/v1/messages?beta=true",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > minimax-cn → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.minimaxi.com/anthropic/v1/messages?beta=true",
+  "stream": "https://api.minimaxi.com/anthropic/v1/messages?beta=true",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > mistral → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.mistral.ai/v1/chat/completions",
+  "stream": "https://api.mistral.ai/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > mmf → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.xiaomimimo.com/api/free-ai/openai/chat",
+  "stream": "https://api.xiaomimimo.com/api/free-ai/openai/chat",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > nanobanana → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.nanobananaapi.ai/v1/chat/completions",
+  "stream": "https://api.nanobananaapi.ai/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > nebius → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.studio.nebius.ai/v1/chat/completions",
+  "stream": "https://api.studio.nebius.ai/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > nvidia → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://integrate.api.nvidia.com/v1/chat/completions",
+  "stream": "https://integrate.api.nvidia.com/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > ollama → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://ollama.com/api/chat",
+  "stream": "https://ollama.com/api/chat",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > openai → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.openai.com/v1/chat/completions",
+  "stream": "https://api.openai.com/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > openrouter → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://openrouter.ai/api/v1/chat/completions",
+  "stream": "https://openrouter.ai/api/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > perplexity → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.perplexity.ai/chat/completions",
+  "stream": "https://api.perplexity.ai/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > siliconflow → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.siliconflow.com/v1/chat/completions",
+  "stream": "https://api.siliconflow.com/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > together → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.together.xyz/v1/chat/completions",
+  "stream": "https://api.together.xyz/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > vercel-ai-gateway → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://ai-gateway.vercel.sh/v1/chat/completions",
+  "stream": "https://ai-gateway.vercel.sh/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > volcengine-ark → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions",
+  "stream": "https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > xai → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.x.ai/v1/chat/completions",
+  "stream": "https://api.x.ai/v1/chat/completions",
+}
+`;
+
+exports[`GOLDEN buildUrl (default executor providers) > xiaomi-mimo → url (stream + non-stream) 1`] = `
+{
+  "nonStream": "https://api.xiaomimimo.com/v1/chat/completions",
+  "stream": "https://api.xiaomimimo.com/v1/chat/completions",
+}
+`;
diff --git a/tests/translator/bugs-antigravity.test.js b/tests/translator/bugs-antigravity.test.js
new file mode 100644
index 0000000..6ab37ef
--- /dev/null
+++ b/tests/translator/bugs-antigravity.test.js
@@ -0,0 +1,139 @@
+// Real Antigravity-MITM requests (Gemini-internal: { request: { contents, ... } }) → OpenAI.
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest, translateResponse, initState } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+import { AntigravityExecutor } from "../../open-sse/executors/antigravity.js";
+import { openaiToAntigravityRequest } from "../../open-sse/translator/request/openai-to-gemini.js";
+import { ANTIGRAVITY_DEFAULT_SYSTEM } from "../../open-sse/config/appConstants.js";
+
+const AG2O = (req) =>
+  translateRequest(FORMATS.ANTIGRAVITY, FORMATS.OPENAI, "m", { request: req }, true, null, null);
+
+describe("Antigravity → OpenAI", () => {
+  // antigravity-to-openai.js — content with BOTH functionResponse and functionCall/text
+  // previously returned toolResults early → dropped tool calls / text (fixed in #2225)
+  it("functionResponse + functionCall in same content keeps both", () => {
+    const out = AG2O({
+      contents: [{
+        role: "model",
+        parts: [
+          { functionResponse: { id: "c1", name: "prev", response: { result: "done" } } },
+          { functionCall: { id: "c2", name: "next", args: {} } },
+        ],
+      }],
+    });
+    const json = JSON.stringify(out);
+    expect(json, "functionCall lost when sharing content with functionResponse").toContain("\"next\"");
+  });
+
+  // antigravity-to-openai.js:167 — functionCall without id gets a random Date.now() id
+  // KNOWN BUG: unstable id breaks matching with its functionResponse
+  it("functionCall without id keeps a stable matchable id", () => {
+    const out = AG2O({
+      contents: [
+        { role: "model", parts: [{ functionCall: { name: "search", args: { q: "x" } } }] },
+        { role: "user", parts: [{ functionResponse: { name: "search", response: { result: "r" } } }] },
+      ],
+    });
+    const asst = out.messages.find((m) => m.tool_calls);
+    const tool = out.messages.find((m) => m.role === "tool");
+    expect(tool?.tool_call_id, "id mismatch between call and response").toBe(asst?.tool_calls?.[0]?.id);
+  });
+
+  // antigravity-to-openai.js:144-147 — signature-only part handling (regression guard)
+  it("signature-only part does not produce empty text", () => {
+    const out = AG2O({
+      contents: [{ role: "model", parts: [{ thoughtSignature: "sig", text: "" }] }],
+    });
+    const asst = out.messages.find((m) => m.role === "assistant");
+    const content = asst?.content;
+    const hasEmpty = Array.isArray(content)
+      ? content.some((c) => c.type === "text" && c.text === "")
+      : content === "";
+    expect(hasEmpty, "empty text part emitted").toBe(false);
+  });
+});
+
+describe("Antigravity → Claude", () => {
+  it("tool call input_json_delta includes Anthropic index", () => {
+    const state = initState(FORMATS.CLAUDE);
+    const events = translateResponse(FORMATS.ANTIGRAVITY, FORMATS.CLAUDE, {
+      response: {
+        responseId: "resp-1",
+        modelVersion: "gemini-pro-agent",
+        candidates: [{
+          content: {
+            role: "model",
+            parts: [{ functionCall: { name: "bash", args: { command: "git status" } } }],
+          },
+          finishReason: "STOP",
+          index: 0,
+        }],
+      },
+    }, state);
+
+    const jsonDelta = events.find(
+      (event) => event.type === "content_block_delta" && event.delta?.type === "input_json_delta"
+    );
+    expect(jsonDelta).toMatchObject({ index: expect.any(Number) });
+    expect(JSON.parse(jsonDelta.delta.partial_json)).toEqual({ command: "git status" });
+  });
+});
+
+describe("Antigravity executor", () => {
+  it("strips optional from nested tool schemas", () => {
+    const out = new AntigravityExecutor().transformRequest("gemini-2.5-pro", {
+      request: {
+        contents: [{ role: "user", parts: [{ text: "hi" }] }],
+        tools: [{
+          functionDeclarations: [{
+            name: "lookup",
+            description: "Lookup a value",
+            parameters: {
+              type: "object",
+              properties: {
+                query: {
+                  type: "string",
+                  description: "Search query",
+                  optional: true,
+                },
+              },
+            },
+          }],
+        }],
+      },
+    }, true, { projectId: "project-1", connectionId: "conn-1" });
+
+    const query = out.request.tools[0].functionDeclarations[0].parameters.properties.query;
+    expect(query).toEqual({ type: "string", description: "Search query" });
+  });
+
+  it("does not inject the legacy Antigravity default system prompt for Gemini-backed models", () => {
+    const out = openaiToAntigravityRequest("gemini-3.5-flash-low", {
+      messages: [
+        { role: "system", content: "USER_SYSTEM_PROMPT" },
+        { role: "user", content: "hello" },
+      ],
+    }, true, { projectId: "project-1", connectionId: "conn-1" });
+
+    const system = JSON.stringify(out.request.systemInstruction);
+    expect(system).toContain("USER_SYSTEM_PROMPT");
+    expect(system).not.toContain(ANTIGRAVITY_DEFAULT_SYSTEM);
+    expect(system).not.toContain("Please ignore the following [ignore]");
+  });
+
+  it("does not inject the legacy Antigravity default system prompt for Claude-backed models", () => {
+    const out = openaiToAntigravityRequest("claude-opus-4-6-thinking", {
+      messages: [
+        { role: "system", content: "USER_SYSTEM_PROMPT" },
+        { role: "user", content: "hello" },
+      ],
+    }, true, { projectId: "project-1", connectionId: "conn-1" });
+
+    const system = JSON.stringify(out.request.systemInstruction);
+    expect(system).toContain("USER_SYSTEM_PROMPT");
+    expect(system).not.toContain(ANTIGRAVITY_DEFAULT_SYSTEM);
+    expect(system).not.toContain("Please ignore the following [ignore]");
+  });
+});
diff --git a/tests/translator/bugs-claudeCode-context.test.js b/tests/translator/bugs-claudeCode-context.test.js
new file mode 100644
index 0000000..eb78211
--- /dev/null
+++ b/tests/translator/bugs-claudeCode-context.test.js
@@ -0,0 +1,73 @@
+// Real Claude Code CLI requests (Claude format) → non-Claude provider via OpenAI bridge.
+// Focuses on context components a real CLI sends: system arrays w/ cache_control, thinking
+// signatures, tool_result with images, audio. KNOWN BUG = it.fails (source file:line in comments).
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+const T = (src, tgt, body, provider = null) =>
+  translateRequest(src, tgt, "m", body, true, null, provider);
+
+describe("Claude Code CLI context → OpenAI", () => {
+  // claude-to-openai.js:24-27 — system array only maps .text; cache_control/non-text dropped
+  it("system array keeps all text parts", () => {
+    const out = T(FORMATS.CLAUDE, FORMATS.OPENAI, {
+      system: [
+        { type: "text", text: "You are Claude Code.", cache_control: { type: "ephemeral" } },
+        { type: "text", text: "Follow repo conventions." },
+      ],
+      messages: [{ role: "user", content: "hi" }],
+    });
+    const sys = out.messages.find((m) => m.role === "system");
+    expect(sys?.content).toContain("Claude Code");
+    expect(sys?.content).toContain("repo conventions");
+  });
+
+  // claude→claude is passthrough (same format) → thinking preserved. Guards against
+  // accidental routing through the OpenAI bridge for same-format requests.
+  it("assistant thinking block survives Claude→Claude passthrough", () => {
+    const out = T(FORMATS.CLAUDE, FORMATS.CLAUDE, {
+      messages: [
+        { role: "assistant", content: [
+          { type: "thinking", thinking: "step-by-step plan", signature: "abc123" },
+          { type: "text", text: "done" },
+        ] },
+        { role: "user", content: "next" },
+      ],
+    });
+    expect(JSON.stringify(out)).toContain("step-by-step plan");
+  });
+
+  // claude-to-openai.js:128 — redacted_thinking also dropped
+  // KNOWN BUG
+  it.fails("redacted_thinking block is not silently dropped", () => {
+    const out = T(FORMATS.CLAUDE, FORMATS.OPENAI, {
+      messages: [
+        { role: "assistant", content: [
+          { type: "redacted_thinking", data: "ENCRYPTED_BLOB" },
+          { type: "text", text: "answer" },
+        ] },
+        { role: "user", content: "go" },
+      ],
+    });
+    expect(JSON.stringify(out)).toContain("ENCRYPTED_BLOB");
+  });
+
+  // claude-to-openai.js:155-173 — tool_result image block stringified into raw JSON
+  // KNOWN BUG
+  it.fails("tool_result image block is preserved", () => {
+    const out = T(FORMATS.CLAUDE, FORMATS.OPENAI, {
+      messages: [
+        { role: "assistant", content: [{ type: "tool_use", id: "call_1", name: "screenshot", input: {} }] },
+        { role: "user", content: [
+          { type: "tool_result", tool_use_id: "call_1", content: [
+            { type: "image", source: { type: "base64", media_type: "image/png", data: "IMG" } },
+          ] },
+        ] },
+      ],
+    });
+    const tool = out.messages.find((m) => m.role === "tool");
+    expect(tool?.content, "image turned into raw JSON").not.toMatch(/^\[/);
+  });
+});
diff --git a/tests/translator/bugs-codexCli-responses.test.js b/tests/translator/bugs-codexCli-responses.test.js
new file mode 100644
index 0000000..c340134
--- /dev/null
+++ b/tests/translator/bugs-codexCli-responses.test.js
@@ -0,0 +1,77 @@
+// Real Codex CLI requests (OpenAI Responses API: { input:[], instructions }) → providers.
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+const R2O = (body) => translateRequest(FORMATS.OPENAI_RESPONSES, FORMATS.OPENAI, "m", body, true, null, null);
+const O2R = (body) => translateRequest(FORMATS.OPENAI, FORMATS.OPENAI_RESPONSES, "m", body, true, null, null);
+
+describe("Codex CLI Responses → OpenAI", () => {
+  // openai-responses.js:103 — function_call with empty name skipped, can leave tool_calls: []
+  // KNOWN BUG: empty tool_calls array is rejected by OpenAI/Codex
+  it.fails("assistant has no empty tool_calls array when all names are empty", () => {
+    const out = R2O({
+      input: [
+        { type: "function_call", call_id: "c1", name: "", arguments: "{}" },
+      ],
+    });
+    const asst = out.messages.find((m) => m.role === "assistant" && m.tool_calls);
+    expect(asst?.tool_calls?.length ?? 0, "empty tool_calls[] produced").toBeGreaterThan(0);
+  });
+
+  // openai-responses.js:109-110 — arguments passed through without ensuring string type
+  // KNOWN BUG
+  it.fails("function_call arguments end up as a string", () => {
+    const out = R2O({
+      input: [{ type: "function_call", call_id: "c1", name: "f", arguments: { a: 1 } }],
+    });
+    const asst = out.messages.find((m) => m.tool_calls);
+    expect(typeof asst.tool_calls[0].function.arguments).toBe("string");
+  });
+
+  // openai-responses.js:75-77 — input_image uses file_id as raw url
+  // KNOWN BUG
+  it.fails("input_image with file_id is not used as a raw url", () => {
+    const out = R2O({
+      input: [{ type: "message", role: "user", content: [
+        { type: "input_image", file_id: "file-abc" },
+      ] }],
+    });
+    const userMsg = out.messages.find((m) => m.role === "user");
+    const img = Array.isArray(userMsg?.content) ? userMsg.content.find((c) => c.type === "image_url") : null;
+    // A bare file_id is not a valid image URL
+    expect(img?.image_url?.url === "file-abc").toBe(false);
+  });
+});
+
+describe("OpenAI → Codex Responses (reverse)", () => {
+  it("maps developer messages to Responses API instructions", () => {
+    const out = O2R({
+      messages: [
+        { role: "developer", content: "Follow the project rules." },
+        { role: "user", content: "Hello" },
+      ],
+    });
+
+    expect(out.instructions).toBe("Follow the project rules.");
+    expect(out.input).toEqual([
+      { type: "message", role: "user", content: [{ type: "input_text", text: "Hello" }] },
+    ]);
+  });
+
+  // openai-responses.js:13 — clampCallId NOT applied on Responses→Chat; but here Chat→Responses must clamp
+  it("call_id longer than 64 chars is clamped", () => {
+    const longId = "call_" + "x".repeat(80);
+    const out = O2R({
+      messages: [
+        { role: "assistant", content: null, tool_calls: [
+          { id: longId, type: "function", function: { name: "f", arguments: "{}" } },
+        ] },
+        { role: "tool", tool_call_id: longId, content: "ok" },
+      ],
+    });
+    const fc = out.input.find((i) => i.type === "function_call");
+    expect(fc.call_id.length).toBeLessThanOrEqual(64);
+  });
+});
diff --git a/tests/translator/bugs-gemini-cursor-commandcode.test.js b/tests/translator/bugs-gemini-cursor-commandcode.test.js
new file mode 100644
index 0000000..4b74c60
--- /dev/null
+++ b/tests/translator/bugs-gemini-cursor-commandcode.test.js
@@ -0,0 +1,76 @@
+// OpenAI → Gemini / Cursor / CommandCode request translation.
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+const O2G = (body) => translateRequest(FORMATS.OPENAI, FORMATS.GEMINI, "m", body, true, null, "gemini");
+const O2C = (body) => translateRequest(FORMATS.OPENAI, FORMATS.CURSOR, "m", body, true, null, "cursor");
+const O2CC = (body) => translateRequest(FORMATS.OPENAI, FORMATS.COMMANDCODE, "m", body, true, null, "commandcode");
+
+describe("OpenAI → Gemini", () => {
+  // openai-to-gemini.js:92-96 — each system message overwrites systemInstruction → only last kept
+  // KNOWN BUG
+  it.fails("multiple system messages are all kept", () => {
+    const out = O2G({
+      messages: [
+        { role: "system", content: "RULE_ONE" },
+        { role: "system", content: "RULE_TWO" },
+        { role: "user", content: "hi" },
+      ],
+    });
+    expect(JSON.stringify(out.systemInstruction), "earlier system lost").toContain("RULE_ONE");
+  });
+});
+
+describe("OpenAI → Cursor", () => {
+  // openai-to-cursor.js:12-24 — image content fully dropped (text only)
+  // KNOWN BUG
+  it.fails("image content is preserved", () => {
+    const out = O2C({
+      messages: [{ role: "user", content: [
+        { type: "text", text: "look" },
+        { type: "image_url", image_url: { url: "data:image/png;base64,AAAA" } },
+      ] }],
+    });
+    expect(JSON.stringify(out), "image dropped").toContain("AAAA");
+  });
+
+  // openai-to-cursor.js:179 — max_tokens hardcoded to 32000
+  // KNOWN BUG
+  it.fails("respects client max_tokens", () => {
+    const out = O2C({ max_tokens: 200, messages: [{ role: "user", content: "hi" }] });
+    expect(out.max_tokens).toBe(200);
+  });
+});
+
+describe("OpenAI → CommandCode", () => {
+  // openai-to-commandcode.js:53-57 — safeParseJson returns {} on bad JSON (args silently lost)
+  // KNOWN BUG
+  it.fails("malformed tool arguments are not silently emptied", () => {
+    const out = O2CC({
+      messages: [
+        { role: "user", content: "go" },
+        { role: "assistant", content: "", tool_calls: [
+          { id: "c1", type: "function", function: { name: "f", arguments: "{bad" } },
+        ] },
+        { role: "tool", tool_call_id: "c1", content: "r" },
+      ],
+    });
+    const asst = out.params.messages.find((m) => m.role === "assistant");
+    const call = asst.content.find((b) => b.type === "tool-call");
+    expect(Object.keys(call.input).length, "arguments silently dropped to {}").toBeGreaterThan(0);
+  });
+
+  // openai-to-commandcode.js:41-42 — image becomes "[image omitted]"
+  // KNOWN BUG
+  it.fails("image content is preserved", () => {
+    const out = O2CC({
+      messages: [{ role: "user", content: [
+        { type: "text", text: "look" },
+        { type: "image_url", image_url: { url: "data:image/png;base64,BBBB" } },
+      ] }],
+    });
+    expect(JSON.stringify(out), "image omitted").toContain("BBBB");
+  });
+});
diff --git a/tests/translator/bugs-kiro.test.js b/tests/translator/bugs-kiro.test.js
new file mode 100644
index 0000000..7f3677f
--- /dev/null
+++ b/tests/translator/bugs-kiro.test.js
@@ -0,0 +1,44 @@
+// OpenAI → Kiro (AWS CodeWhisperer) request translation.
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+const O2K = (body) => translateRequest(FORMATS.OPENAI, FORMATS.KIRO, "m", body, true, null, "kiro");
+
+describe("OpenAI → Kiro", () => {
+  // openai-to-kiro.js — safeJSONParse guards bad tool-call JSON (fixed in PR #1582)
+  it("malformed tool arguments do not throw the whole request", () => {
+    expect(() =>
+      O2K({
+        messages: [
+          { role: "user", content: "go" },
+          { role: "assistant", content: "", tool_calls: [
+            { id: "c1", type: "function", function: { name: "f", arguments: "{not json" } },
+          ] },
+          { role: "tool", tool_call_id: "c1", content: "r" },
+        ],
+      })
+    ).not.toThrow();
+  });
+
+  // openai-to-kiro.js:309 — maxTokens hardcoded to 32000, ignores body.max_tokens
+  // KNOWN BUG
+  it.fails("respects client max_tokens", () => {
+    const out = O2K({ max_tokens: 100, messages: [{ role: "user", content: "hi" }] });
+    expect(out.inferenceConfig?.maxTokens, "client max_tokens ignored").toBe(100);
+  });
+
+  // openai-to-kiro.js:132-134 — remote http image becomes "[Image: url]" text (lost)
+  // KNOWN BUG
+  it.fails("remote image url is preserved as an image, not text", () => {
+    const out = O2K({
+      messages: [{ role: "user", content: [
+        { type: "text", text: "see" },
+        { type: "image_url", image_url: { url: "https://x.com/p.png" } },
+      ] }],
+    });
+    const content = out.conversationState?.currentMessage?.userInputMessage?.content || "";
+    expect(content, "remote image flattened to text").not.toContain("[Image:");
+  });
+});
diff --git a/tests/translator/bugs-openai-bridge.test.js b/tests/translator/bugs-openai-bridge.test.js
new file mode 100644
index 0000000..0214f5e
--- /dev/null
+++ b/tests/translator/bugs-openai-bridge.test.js
@@ -0,0 +1,120 @@
+// Expose bugs caused by OpenAI being the intermediate format: data lost/wrong on source → openai → target.
+// Each test describes the EXPECTED-correct behavior. A FAIL is evidence of the bug (with source file:line).
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+const T = (src, tgt, body, provider = null) =>
+  translateRequest(src, tgt, "m", body, true, null, provider);
+
+describe("bug: Claude → OpenAI bridge data loss", () => {
+  // claude-to-openai.js:133-141 — image source.type==="url" only handles base64
+  // KNOWN BUG: it.fails passes while app drops the url; flips to failing once fixed.
+  it.fails("image with source.type=url is preserved (NOT dropped)", () => {
+    const out = T(FORMATS.CLAUDE, FORMATS.OPENAI, {
+      messages: [{ role: "user", content: [
+        { type: "text", text: "look" },
+        { type: "image", source: { type: "url", url: "https://x.com/a.png" } },
+      ] }],
+    });
+    const json = JSON.stringify(out);
+    expect(json, "remote image url silently dropped").toContain("a.png");
+  });
+
+  // claude-to-openai.js:128 switch — missing thinking/redacted_thinking case
+  it("thinking block survives round-trip Claude→OpenAI→Claude", () => {
+    const body = {
+      messages: [{ role: "assistant", content: [
+        { type: "thinking", thinking: "secret reasoning", signature: "sig" },
+        { type: "text", text: "answer" },
+      ] }, { role: "user", content: "go" }],
+    };
+    const out = T(FORMATS.CLAUDE, FORMATS.CLAUDE, body);
+    const json = JSON.stringify(out);
+    expect(json, "thinking content lost via OpenAI bridge").toContain("secret reasoning");
+  });
+
+  // claude-to-openai.js:155-173 — tool_result image block dropped (text only)
+  // KNOWN BUG
+  it.fails("tool_result with image block is not turned into raw JSON / dropped", () => {
+    const out = T(FORMATS.CLAUDE, FORMATS.OPENAI, {
+      messages: [
+        { role: "assistant", content: [
+          { type: "tool_use", id: "call_1", name: "shot", input: {} },
+        ] },
+        { role: "user", content: [
+          { type: "tool_result", tool_use_id: "call_1", content: [
+            { type: "image", source: { type: "base64", media_type: "image/png", data: "ZZZ" } },
+          ] },
+        ] },
+      ],
+    });
+    const toolMsg = out.messages.find((m) => m.role === "tool");
+    // Should keep the image; currently stringifies the whole array into raw JSON
+    expect(toolMsg?.content, "image in tool_result lost").not.toMatch(/^\[/);
+  });
+
+  // claude-to-openai.js:155-173 — is_error lost
+  // KNOWN BUG
+  it.fails("tool_result is_error flag is preserved", () => {
+    const out = T(FORMATS.CLAUDE, FORMATS.OPENAI, {
+      messages: [
+        { role: "assistant", content: [{ type: "tool_use", id: "call_1", name: "f", input: {} }] },
+        { role: "user", content: [
+          { type: "tool_result", tool_use_id: "call_1", is_error: true, content: "boom" },
+        ] },
+      ],
+    });
+    const json = JSON.stringify(out);
+    expect(json, "is_error dropped → model can't see tool failure").toContain("is_error");
+  });
+
+  // claude-to-openai.js:24-27 — system array only takes .text, drops cache_control/non-text
+  it("system array non-text parts are not silently dropped", () => {
+    const out = T(FORMATS.CLAUDE, FORMATS.OPENAI, {
+      system: [
+        { type: "text", text: "rule1", cache_control: { type: "ephemeral" } },
+        { type: "text", text: "rule2" },
+      ],
+      messages: [{ role: "user", content: "hi" }],
+    });
+    const sys = out.messages.find((m) => m.role === "system");
+    expect(sys?.content).toContain("rule1");
+    expect(sys?.content).toContain("rule2");
+  });
+});
+
+describe("bug: tool_call id stability across bridge", () => {
+  // toolCallHelper.js:29-31 — sanitize changes tc.id but tool_call_id in another message may drift
+  it("sanitized tool id stays matched between call and result", () => {
+    const out = T(FORMATS.OPENAI, FORMATS.OPENAI, {
+      messages: [
+        { role: "assistant", tool_calls: [
+          { id: "call/with:bad*chars", type: "function", function: { name: "f", arguments: "{}" } },
+        ] },
+        { role: "tool", tool_call_id: "call/with:bad*chars", content: "ok" },
+      ],
+    });
+    const asst = out.messages.find((m) => m.role === "assistant");
+    const tool = out.messages.find((m) => m.role === "tool");
+    expect(tool.tool_call_id, "id mismatch after sanitize").toBe(asst.tool_calls[0].id);
+  });
+});
+
+describe("bug: empty content message handling", () => {
+  // openaiHelper.js:49-51,66-71 — empty content → {text:""} then filtered out
+  it("assistant message with only tool_calls is not dropped", () => {
+    const out = T(FORMATS.OPENAI, FORMATS.OPENAI, {
+      messages: [
+        { role: "user", content: "do it" },
+        { role: "assistant", content: "", tool_calls: [
+          { id: "call_1", type: "function", function: { name: "f", arguments: "{}" } },
+        ] },
+        { role: "tool", tool_call_id: "call_1", content: "done" },
+      ],
+    });
+    const asst = out.messages.find((m) => m.role === "assistant" && m.tool_calls);
+    expect(asst, "assistant tool_calls message dropped").toBeTruthy();
+  });
+});
diff --git a/tests/translator/bugs-toClaude-context.test.js b/tests/translator/bugs-toClaude-context.test.js
new file mode 100644
index 0000000..96b704e
--- /dev/null
+++ b/tests/translator/bugs-toClaude-context.test.js
@@ -0,0 +1,182 @@
+// OpenAI-format CLI → Claude provider. Context pollution + lossy mapping on the openai→claude leg.
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+import { prepareClaudeRequest } from "../../open-sse/translator/formats/claude.js";
+
+// anthropic-compatible provider so prepareClaudeRequest runs the openai→claude path
+const T = (body) =>
+  translateRequest(FORMATS.OPENAI, FORMATS.CLAUDE, "m", body, true, null, "anthropic-compatible-x");
+
+describe("OpenAI → Claude context mapping", () => {
+  // openai-to-claude.js:124-134 — always injects CLAUDE_SYSTEM_PROMPT ("You are Claude Code")
+  // KNOWN BUG: pollutes requests for non-official Claude-compatible providers
+  it.fails("does not inject Claude Code system prompt for compatible providers", () => {
+    const out = T({ messages: [{ role: "user", content: "hi" }] });
+    expect(JSON.stringify(out.system), "Claude Code prompt injected").not.toContain("Claude Code");
+  });
+
+  it("assistant reasoning_content becomes a thinking block", () => {
+    const out = T({
+      messages: [
+        { role: "user", content: "q" },
+        { role: "assistant", content: "a", reasoning_content: "my hidden reasoning" },
+        { role: "user", content: "next" },
+      ],
+    });
+    expect(JSON.stringify(out), "reasoning_content lost").toContain("my hidden reasoning");
+    const assistant = out.messages.find((m) => m.role === "assistant");
+    expect(assistant.content[0]).toEqual(expect.objectContaining({
+      type: "thinking",
+      thinking: "my hidden reasoning",
+    }));
+  });
+
+  // openai-to-claude.js:298 — tool_choice "none" mapped to {type:"auto"} (loses "do not call" intent)
+  // KNOWN BUG
+  it.fails("tool_choice=none is not turned into auto", () => {
+    const out = T({
+      messages: [{ role: "user", content: "hi" }],
+      tools: [{ type: "function", function: { name: "f", parameters: { type: "object", properties: {} } } }],
+      tool_choice: "none",
+    });
+    expect(out.tool_choice?.type, "none became auto → model may call tools").not.toBe("auto");
+  });
+
+  // getContentBlocksFromMessage — no input_audio branch → audio dropped
+  // KNOWN BUG
+  it.fails("input_audio content is preserved", () => {
+    const out = T({
+      messages: [{ role: "user", content: [
+        { type: "text", text: "transcribe" },
+        { type: "input_audio", input_audio: { data: "AUDIO_B64", format: "wav" } },
+      ] }],
+    });
+    expect(JSON.stringify(out), "audio dropped").toContain("AUDIO_B64");
+  });
+
+  // openai-to-claude.js:235-251 — remote http image_url is kept (regression guard)
+  it("remote http image_url is preserved", () => {
+    const out = T({
+      messages: [{ role: "user", content: [
+        { type: "text", text: "see" },
+        { type: "image_url", image_url: { url: "https://x.com/pic.png" } },
+      ] }],
+    });
+    expect(JSON.stringify(out), "remote image dropped").toContain("pic.png");
+  });
+
+  // prepareClaudeRequest reconciles max_tokens vs thinking.budget_tokens.
+  // applyThinking runs after adjustMaxTokens caps max_tokens, so a claude-budget
+  // model at "max" effort (budget 128000) can exceed the clamped max_tokens and
+  // trip Anthropic's "max_tokens > budget_tokens" rule (400). See claude.js.
+  describe("max_tokens vs thinking.budget_tokens reconciliation", () => {
+    // 64k-ceiling model (maxOutput 64000) + max-effort budget 128000: budget alone
+    // exceeds the ceiling → cap max_tokens at 64000 and shrink budget below it.
+    it("max effort budget on a 64k model → budget < max_tokens ≤ 64000", () => {
+      const out = prepareClaudeRequest({
+        model: "claude-opus-4-20250514",
+        max_tokens: 64000,
+        thinking: { type: "enabled", budget_tokens: 128000 },
+        messages: [{ role: "user", content: "q" }],
+      }, "anthropic");
+      expect(out.max_tokens).toBe(64000);
+      expect(out.thinking.budget_tokens).toBeLessThan(out.max_tokens);
+      expect(out.thinking.budget_tokens).toBeGreaterThan(0);
+    });
+
+    // Budget fits under the ceiling but exceeds a small client max_tokens →
+    // raise max_tokens to fit, preserving the requested thinking depth.
+    it("xhigh budget with a low client max_tokens → raise max_tokens, preserve budget", () => {
+      const out = prepareClaudeRequest({
+        model: "claude-opus-4-20250514",
+        max_tokens: 16000,
+        thinking: { type: "enabled", budget_tokens: 32768 },
+        messages: [{ role: "user", content: "q" }],
+      }, "anthropic");
+      expect(out.thinking.budget_tokens).toBe(32768);
+      expect(out.max_tokens).toBe(33792); // 32768 + 1024, under the 64000 ceiling
+    });
+
+    // Budget already below max_tokens → nothing to reconcile.
+    it("high budget under max_tokens → both unchanged", () => {
+      const out = prepareClaudeRequest({
+        model: "claude-opus-4-20250514",
+        max_tokens: 64000,
+        thinking: { type: "enabled", budget_tokens: 24576 },
+        messages: [{ role: "user", content: "q" }],
+      }, "anthropic");
+      expect(out.max_tokens).toBe(64000);
+      expect(out.thinking.budget_tokens).toBe(24576);
+    });
+
+    // Non-budget thinking shapes (adaptive / disabled) carry no budget_tokens →
+    // the reconciliation must never touch them.
+    it("adaptive thinking (no budget_tokens) is left untouched", () => {
+      const out = prepareClaudeRequest({
+        model: "claude-opus-4-20250514",
+        max_tokens: 64000,
+        thinking: { type: "adaptive" },
+        messages: [{ role: "user", content: "q" }],
+      }, "anthropic");
+      expect(out.max_tokens).toBe(64000);
+      expect(out.thinking).toEqual({ type: "adaptive" });
+    });
+
+    // Lifted ceiling: a claude-budget model whose caps declare maxOutput 128000
+    // (e.g. fable) may use the full budget at max effort instead of being pinned
+    // to the conservative 64000 default.
+    it("max effort budget on a 128k model → max_tokens up to 128000, budget preserved just under", () => {
+      const out = prepareClaudeRequest({
+        model: "claude-fable-5",
+        max_tokens: 64000,
+        thinking: { type: "enabled", budget_tokens: 128000 },
+        messages: [{ role: "user", content: "q" }],
+      }, "anthropic");
+      expect(out.max_tokens).toBe(128000);
+      expect(out.thinking.budget_tokens).toBe(126976); // 128000 - 1024
+      expect(out.thinking.budget_tokens).toBeLessThan(out.max_tokens);
+    });
+
+    // Regression: a default 64k-ceiling model still clamps an over-large client
+    // max_tokens down to 64000 (the lift is per-model, not global).
+    it("over-large client max_tokens on a 64k model is still clamped to 64000", () => {
+      const out = prepareClaudeRequest({
+        model: "claude-opus-4-20250514",
+        max_tokens: 120000,
+        messages: [{ role: "user", content: "q" }],
+      }, "anthropic");
+      expect(out.max_tokens).toBe(64000);
+    });
+
+    // Lifted ceiling for a 128k model: a large client max_tokens is now allowed
+    // through instead of being clamped to 64000.
+    it("large client max_tokens on a 128k model is allowed up to maxOutput", () => {
+      const out = prepareClaudeRequest({
+        model: "claude-fable-5",
+        max_tokens: 100000,
+        messages: [{ role: "user", content: "q" }],
+      }, "anthropic");
+      expect(out.max_tokens).toBe(100000);
+    });
+  });
+
+  it("DeepSeek Claude transport adds a thinking placeholder before tool_use in thinking mode", () => {
+    const out = prepareClaudeRequest({
+      model: "deepseek-v4-pro",
+      thinking: { type: "enabled" },
+      messages: [
+        { role: "user", content: [{ type: "text", text: "q" }] },
+        { role: "assistant", content: [{ type: "tool_use", id: "toolu_1", name: "Read", input: { file_path: "x" } }] },
+        { role: "user", content: [{ type: "tool_result", tool_use_id: "toolu_1", content: "ok" }] },
+        { role: "user", content: [{ type: "text", text: "continue" }] },
+      ],
+    }, "deepseek");
+
+    const assistant = out.messages.find((m) => m.role === "assistant");
+    expect(assistant.content[0]).toEqual({ type: "thinking", thinking: "." });
+    expect(assistant.content[1]).toEqual(expect.objectContaining({ type: "tool_use", id: "toolu_1" }));
+    expect(assistant.content[0].signature).toBeUndefined();
+  });
+});
diff --git a/tests/translator/claude-kiro-direct.test.js b/tests/translator/claude-kiro-direct.test.js
new file mode 100644
index 0000000..1b189ec
--- /dev/null
+++ b/tests/translator/claude-kiro-direct.test.js
@@ -0,0 +1,179 @@
+// Claude → Kiro (direct route) request translation + Kiro → Claude response.
+// Verifies the direct claude:kiro / kiro:claude routes added to bypass the
+// OpenAI pivot, and that the "Improperly formed request" 400-guards survive.
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest, translateResponse } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+const C2K = (body) =>
+  translateRequest(FORMATS.CLAUDE, FORMATS.KIRO, "claude-sonnet-4.5", body, true, null, "kiro");
+
+describe("Claude → Kiro (direct route)", () => {
+  it("produces a Kiro conversationState payload", () => {
+    const out = C2K({ messages: [{ role: "user", content: "hello" }] });
+    expect(out.conversationState).toBeTruthy();
+    expect(out.conversationState.currentMessage.userInputMessage.content).toContain("hello");
+  });
+
+  it("guard 1: with no tools, a dangling tool_result is flattened to text (no structured ref)", () => {
+    // Client omitted `tools` but kept a tool_result after compaction.
+    const out = C2K({
+      messages: [
+        { role: "user", content: "go" },
+        { role: "assistant", content: [{ type: "tool_use", id: "t1", name: "f", input: {} }] },
+        { role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content: "result" }] },
+      ],
+    });
+    // No userInputMessageContext.tools/toolResults anywhere → won't trip the
+    // "tools required" validator.
+    const cur = out.conversationState.currentMessage.userInputMessage;
+    expect(cur.userInputMessageContext?.toolResults).toBeFalsy();
+    const everyHistoryClean = out.conversationState.history.every(
+      (h) => !h.userInputMessage?.userInputMessageContext?.toolResults
+    );
+    expect(everyHistoryClean).toBe(true);
+  });
+
+  it("guard 2: with tools, an orphaned tool_result is folded into user text", () => {
+    const out = C2K({
+      tools: [{ name: "f", description: "fn", input_schema: { type: "object", properties: {} } }],
+      messages: [
+        { role: "user", content: "go" },
+        // tool_result references a tool_use that never appears → orphan
+        { role: "user", content: [{ type: "tool_result", tool_use_id: "ghost", content: "salvage me" }] },
+      ],
+    });
+    const cur = out.conversationState.currentMessage.userInputMessage;
+    // The orphan content survives as text, not as a dangling structured ref.
+    expect(cur.content).toContain("salvage me");
+    expect(cur.userInputMessageContext?.toolResults?.length ?? 0).toBe(0);
+  });
+
+  it("injects thinking_mode tag when model implies thinking", () => {
+    const out = translateRequest(
+      FORMATS.CLAUDE,
+      FORMATS.KIRO,
+      "claude-sonnet-4.5-thinking",
+      { messages: [{ role: "user", content: "hi" }] },
+      true,
+      null,
+      "kiro"
+    );
+    expect(out.conversationState.currentMessage.userInputMessage.content).toContain(
+      "<thinking_mode>enabled</thinking_mode>"
+    );
+  });
+
+  it("maps output_config.effort high to Kiro max_thinking_length 24576", () => {
+    const out = C2K({
+      output_config: { effort: "high" },
+      messages: [{ role: "user", content: "think with adaptive effort" }],
+    });
+
+    expect(out.conversationState.currentMessage.userInputMessage.content).toContain(
+      "<max_thinking_length>24576</max_thinking_length>"
+    );
+  });
+});
+
+describe("Kiro → Claude (direct route, OpenAI-shaped chunks from executor)", () => {
+  // KiroExecutor emits chat.completion.chunk objects; translateResponse must
+  // convert them to Claude SSE events.
+  const R = (chunk, state) => translateResponse(FORMATS.KIRO, FORMATS.CLAUDE, chunk, state);
+
+  it("first text chunk emits message_start + content_block_start + text_delta", () => {
+    const state = {};
+    const events = R(
+      {
+        id: "chatcmpl-1",
+        object: "chat.completion.chunk",
+        model: "claude-sonnet-4.5",
+        choices: [{ index: 0, delta: { role: "assistant", content: "Hi" }, finish_reason: null }],
+      },
+      state
+    );
+    const types = events.map((e) => e.type);
+    expect(types).toContain("message_start");
+    expect(types).toContain("content_block_start");
+    expect(types).toContain("content_block_delta");
+    const delta = events.find((e) => e.type === "content_block_delta");
+    expect(delta.delta).toEqual({ type: "text_delta", text: "Hi" });
+  });
+
+  it("finish chunk emits message_delta + message_stop with stop_reason", () => {
+    const state = {};
+    R(
+      {
+        id: "chatcmpl-1",
+        object: "chat.completion.chunk",
+        model: "m",
+        choices: [{ index: 0, delta: { content: "x" }, finish_reason: null }],
+      },
+      state
+    );
+    const events = R(
+      {
+        id: "chatcmpl-1",
+        object: "chat.completion.chunk",
+        model: "m",
+        choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+        usage: { prompt_tokens: 5, completion_tokens: 3 },
+      },
+      state
+    );
+    const md = events.find((e) => e.type === "message_delta");
+    expect(md.delta.stop_reason).toBe("end_turn");
+    expect(md.usage).toEqual({ input_tokens: 5, output_tokens: 3 });
+    expect(events.some((e) => e.type === "message_stop")).toBe(true);
+  });
+
+  it("reasoning_content maps to a thinking block", () => {
+    const state = {};
+    const events = R(
+      {
+        id: "chatcmpl-1",
+        object: "chat.completion.chunk",
+        model: "m",
+        choices: [{ index: 0, delta: { reasoning_content: "pondering" }, finish_reason: null }],
+      },
+      state
+    );
+    const start = events.find((e) => e.type === "content_block_start");
+    expect(start.content_block.type).toBe("thinking");
+    const delta = events.find((e) => e.type === "content_block_delta");
+    expect(delta.delta).toEqual({ type: "thinking_delta", thinking: "pondering" });
+  });
+
+  it("tool_calls map to a tool_use block with buffered input_json_delta", () => {
+    const state = {};
+    R(
+      {
+        id: "c", object: "chat.completion.chunk", model: "m",
+        choices: [{ index: 0, delta: { tool_calls: [{ index: 0, id: "tu1", type: "function", function: { name: "search", arguments: "" } }] }, finish_reason: null }],
+      },
+      state
+    );
+    R(
+      {
+        id: "c", object: "chat.completion.chunk", model: "m",
+        choices: [{ index: 0, delta: { tool_calls: [{ index: 0, function: { arguments: '{"q":"x"}' } }] }, finish_reason: null }],
+      },
+      state
+    );
+    const events = R(
+      {
+        id: "c", object: "chat.completion.chunk", model: "m",
+        choices: [{ index: 0, delta: {}, finish_reason: "tool_calls" }],
+      },
+      state
+    );
+    const jsonDelta = events.find(
+      (e) => e.type === "content_block_delta" && e.delta.type === "input_json_delta"
+    );
+    expect(jsonDelta.index).toBeDefined();
+    expect(jsonDelta.delta.partial_json).toBe('{"q":"x"}');
+    const md = events.find((e) => e.type === "message_delta");
+    expect(md.delta.stop_reason).toBe("tool_use");
+  });
+});
diff --git a/tests/translator/coverage-all-models.test.js b/tests/translator/coverage-all-models.test.js
new file mode 100644
index 0000000..b4ef5bd
--- /dev/null
+++ b/tests/translator/coverage-all-models.test.js
@@ -0,0 +1,53 @@
+// Tier 1 — Structural coverage: every model in PROVIDER_MODELS must translate
+// without throwing, correct upstreamId, strip applied. Data-driven → new providers auto-covered.
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+import { buildProviderGroups, buildModelMatrix, resolveTargetFormat } from "./matrix.js";
+
+// Base OpenAI-format request with text + tool + image (exercises strip + tool paths)
+function baseBody(modelId) {
+  return {
+    model: modelId,
+    stream: true,
+    max_tokens: 64,
+    messages: [
+      { role: "system", content: "You are a helper." },
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "Hello" },
+          { type: "image_url", image_url: { url: "data:image/png;base64,AAAA" } },
+        ],
+      },
+    ],
+    tools: [
+      { type: "function", function: { name: "get_time", description: "x", parameters: { type: "object", properties: {} } } },
+    ],
+  };
+}
+
+const groups = buildProviderGroups();
+
+describe("coverage: every model translates without throwing", () => {
+  it.each(groups)("$alias: all models OpenAI→target", ({ alias, models }) => {
+    for (const m of models) {
+      const target = resolveTargetFormat(alias, m.id);
+      const body = baseBody(m.id);
+      // source = openai (lingua franca); exercise openai → target path
+      const out = translateRequest(FORMATS.OPENAI, target, m.id, body, true, null, alias);
+      expect(out, `${alias}/${m.id} → ${target} returned falsy`).toBeTruthy();
+    }
+  });
+});
+
+const stripModels = buildModelMatrix().filter((r) => r.strip.includes("image"));
+describe.skipIf(stripModels.length === 0)("coverage: image-strip models drop image content", () => {
+  it.each(stripModels)("$alias/$modelId strips image when strip=[image]", (row) => {
+    const body = baseBody(row.modelId);
+    const out = translateRequest(FORMATS.OPENAI, row.targetFormat, row.modelId, body, true, null, row.alias, null, row.strip);
+    const json = JSON.stringify(out);
+    expect(json).not.toContain("data:image/png");
+  });
+});
diff --git a/tests/translator/format-roundtrip.test.js b/tests/translator/format-roundtrip.test.js
new file mode 100644
index 0000000..efc334d
--- /dev/null
+++ b/tests/translator/format-roundtrip.test.js
@@ -0,0 +1,76 @@
+// Tier 2 — Format-pair: for each CLI source format, translate to openai and verify
+// core parts (text, tool, system) survive. Exposes bridge data loss.
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+const T = (src, tgt, body, provider = null) =>
+  translateRequest(src, tgt, "m", body, true, null, provider);
+
+describe("roundtrip: Claude source preserves core fields → OpenAI", () => {
+  const body = {
+    system: "sys",
+    max_tokens: 100,
+    messages: [
+      { role: "user", content: "question" },
+      { role: "assistant", content: [{ type: "tool_use", id: "call_1", name: "search", input: { q: "x" } }] },
+      { role: "user", content: [{ type: "tool_result", tool_use_id: "call_1", content: "result" }] },
+    ],
+  };
+  const out = T(FORMATS.CLAUDE, FORMATS.OPENAI, body);
+
+  it("system → system role", () => {
+    expect(out.messages.some((m) => m.role === "system" && m.content === "sys")).toBe(true);
+  });
+  it("tool_use → assistant.tool_calls with matching id", () => {
+    const asst = out.messages.find((m) => m.tool_calls);
+    expect(asst?.tool_calls?.[0]?.id).toBe("call_1");
+  });
+  it("tool_result → tool message with matching id", () => {
+    const tool = out.messages.find((m) => m.role === "tool");
+    expect(tool?.tool_call_id).toBe("call_1");
+    expect(tool?.content).toContain("result");
+  });
+  it("tool arguments are valid JSON string", () => {
+    const asst = out.messages.find((m) => m.tool_calls);
+    expect(() => JSON.parse(asst.tool_calls[0].function.arguments)).not.toThrow();
+  });
+});
+
+describe("roundtrip: OpenAI tools → Claude → keeps tool name", () => {
+  const out = T(FORMATS.OPENAI, FORMATS.CLAUDE, {
+    messages: [{ role: "user", content: "hi" }],
+    tools: [{ type: "function", function: { name: "my_tool", description: "d", parameters: { type: "object", properties: {} } } }],
+  }, "anthropic-compatible-x");
+
+  it("tool name survives openai→claude", () => {
+    expect(JSON.stringify(out)).toContain("my_tool");
+  });
+});
+
+describe("roundtrip: parallel tool calls keep distinct ids", () => {
+  // Claude assistant with 2 parallel tool_use → openai must keep 2 distinct ids
+  const out = T(FORMATS.CLAUDE, FORMATS.OPENAI, {
+    messages: [
+      { role: "assistant", content: [
+        { type: "tool_use", id: "call_a", name: "f1", input: {} },
+        { type: "tool_use", id: "call_b", name: "f2", input: {} },
+      ] },
+      { role: "user", content: [
+        { type: "tool_result", tool_use_id: "call_a", content: "ra" },
+        { type: "tool_result", tool_use_id: "call_b", content: "rb" },
+      ] },
+    ],
+  });
+
+  it("two tool_calls, two distinct ids", () => {
+    const asst = out.messages.find((m) => m.tool_calls);
+    const ids = asst.tool_calls.map((tc) => tc.id);
+    expect(new Set(ids).size).toBe(2);
+  });
+  it("each tool_call has a matching tool result", () => {
+    const toolMsgs = out.messages.filter((m) => m.role === "tool");
+    expect(toolMsgs.length).toBe(2);
+  });
+});
diff --git a/tests/translator/golden-request.test.js b/tests/translator/golden-request.test.js
new file mode 100644
index 0000000..21cf49f
--- /dev/null
+++ b/tests/translator/golden-request.test.js
@@ -0,0 +1,103 @@
+// P0 GOLDEN: lock OUTPUT của translateRequest (body) cho các đích đặc biệt.
+// openai → claude/gemini/kiro: thinking, tools, image, system, tool_result.
+// Sau refactor chạy lại phải khớp y hệt.
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+// Body openai mẫu phủ nhiều concern (text, image, tool, tool_result, system, thinking).
+function baseBody() {
+  return {
+    messages: [
+      { role: "system", content: "You are helpful." },
+      { role: "user", content: [
+        { type: "text", text: "What's in this image?" },
+        { type: "image_url", image_url: { url: "data:image/png;base64,IMGDATA", detail: "high" } },
+      ] },
+      { role: "assistant", content: "", tool_calls: [
+        { id: "call_1", type: "function", function: { name: "get_weather", arguments: '{"city":"NYC"}' } },
+      ] },
+      { role: "tool", tool_call_id: "call_1", content: "sunny" },
+    ],
+    tools: [
+      { type: "function", function: { name: "get_weather", description: "Get weather", parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] } } },
+    ],
+    temperature: 0.7,
+  };
+}
+
+// Khử field động: toolNameMap, kiro conversationId (uuid), timestamp trong content.
+function clean(body) {
+  const s = JSON.stringify(body, (k, v) => {
+    if (k === "_toolNameMap" || k === "conversationId") return undefined;
+    return v;
+  }).replace(/Current time is [^"\\]+/g, "Current time is <TS>");
+  return JSON.parse(s);
+}
+
+describe("GOLDEN request: OpenAI → Claude", () => {
+  it("full body (system/image/tool/tool_result)", () => {
+    const out = translateRequest(FORMATS.OPENAI, FORMATS.CLAUDE, "claude-opus-4-6", baseBody(), true, { apiKey: "sk-x" }, "claude");
+    expect(clean(out)).toMatchSnapshot();
+  });
+
+  it("reasoning_effort → adaptive output_config (claude 4.6+)", () => {
+    const body = { messages: [{ role: "user", content: "hi" }], reasoning_effort: "high" };
+    const out = translateRequest(FORMATS.OPENAI, FORMATS.CLAUDE, "claude-opus-4-6", body, true, { apiKey: "sk-x" }, "anthropic");
+    expect(clean(out)).toMatchSnapshot();
+  });
+});
+
+describe("GOLDEN request: OpenAI → Gemini", () => {
+  it("full body (system/image/tool/tool_result)", () => {
+    const out = translateRequest(FORMATS.OPENAI, FORMATS.GEMINI, "gemini-3-pro", baseBody(), true, { apiKey: "k" }, "gemini");
+    expect(clean(out)).toMatchSnapshot();
+  });
+
+  it("Gemini CLI tool requests include validated toolConfig and enough output for high thinking", () => {
+    const body = {
+      messages: [{ role: "user", content: "Call add with 7 and 35." }],
+      tools: [
+        {
+          type: "function",
+          function: {
+            name: "add",
+            description: "Add two numbers",
+            parameters: {
+              type: "object",
+              properties: {
+                a: { type: "number" },
+                b: { type: "number" },
+              },
+              required: ["a", "b"],
+            },
+          },
+        },
+      ],
+      reasoning_effort: "high",
+      max_tokens: 128,
+    };
+    const out = translateRequest(
+      FORMATS.OPENAI,
+      FORMATS.GEMINI_CLI,
+      "gemini-3.1-pro-preview",
+      body,
+      true,
+      { accessToken: "t", projectId: "p" },
+      "gemini-cli"
+    );
+
+    expect(out.request.toolConfig).toEqual({ functionCallingConfig: { mode: "VALIDATED" } });
+    expect(out.request.safetySettings).toBeDefined();
+    expect(out.request.generationConfig.thinkingConfig).toEqual({ thinkingLevel: "high", includeThoughts: true });
+    expect(out.request.generationConfig.maxOutputTokens).toBe(65535);
+  });
+});
+
+describe("GOLDEN request: OpenAI → Kiro", () => {
+  it("full body (image base64 + tool_result)", () => {
+    const out = translateRequest(FORMATS.OPENAI, FORMATS.KIRO, "claude-sonnet-4.5", baseBody(), true, { accessToken: "t" }, "kiro");
+    expect(clean(out)).toMatchSnapshot();
+  });
+});
diff --git a/tests/translator/golden-response-stream.test.js b/tests/translator/golden-response-stream.test.js
new file mode 100644
index 0000000..a41a0b2
--- /dev/null
+++ b/tests/translator/golden-response-stream.test.js
@@ -0,0 +1,118 @@
+// P0 GOLDEN: lock OUTPUT của translateResponse (stream) cho các concern đặc biệt.
+// Feed chuỗi chunk THẬT (shape provider) → snapshot mảng chunk openai emit.
+// Sau refactor chạy lại phải khớp y hệt (chunk/usage/thinking/tool/finish).
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateResponse, initState } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+// Chuẩn hoá field động (Date.now trong created + id) để snapshot ổn định.
+function stripVolatile(chunks) {
+  return JSON.parse(JSON.stringify(chunks), (key, val) => {
+    if (key === "created") return 0;
+    if (key === "id" && typeof val === "string") {
+      return val
+        .replace(/-\d{10,}-(\d+)$/, "-<TS>-$1")   // gemini: name-<ts>-idx
+        .replace(/^chatcmpl-\d{10,}$/, "chatcmpl-<TS>")  // kiro/ollama stream id
+        .replace(/^call_(\d+)_\d{10,}$/, "call_$1_<TS>"); // ollama tool id
+    }
+    return val;
+  });
+}
+
+// Chạy 1 chuỗi event qua translateResponse, gom toàn bộ chunk emit.
+function runStream(targetFormat, sourceFormat, events) {
+  const state = initState(sourceFormat);
+  const all = [];
+  for (const ev of events) {
+    const out = translateResponse(targetFormat, sourceFormat, ev, state);
+    if (Array.isArray(out)) all.push(...out);
+    else if (out) all.push(out);
+  }
+  return stripVolatile(all);
+}
+
+describe("GOLDEN response stream: Claude → OpenAI", () => {
+  it("text + thinking + tool_use + usage + finish", () => {
+    const events = [
+      { type: "message_start", message: { id: "msg_1", model: "claude-opus-4-6" } },
+      { type: "content_block_start", index: 0, content_block: { type: "thinking" } },
+      { type: "content_block_delta", index: 0, delta: { type: "thinking_delta", thinking: "let me think" } },
+      { type: "content_block_stop", index: 0 },
+      { type: "content_block_start", index: 1, content_block: { type: "text" } },
+      { type: "content_block_delta", index: 1, delta: { type: "text_delta", text: "Hello" } },
+      { type: "content_block_stop", index: 1 },
+      { type: "content_block_start", index: 2, content_block: { type: "tool_use", id: "tu_1", name: "get_weather" } },
+      { type: "content_block_delta", index: 2, delta: { type: "input_json_delta", partial_json: '{"city":"NYC"}' } },
+      { type: "content_block_stop", index: 2 },
+      { type: "message_delta", delta: { stop_reason: "tool_use" }, usage: { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 3 } },
+      { type: "message_stop" },
+    ];
+    expect(runStream(FORMATS.CLAUDE, FORMATS.OPENAI, events)).toMatchSnapshot();
+  });
+});
+
+describe("GOLDEN response stream: Gemini → OpenAI", () => {
+  it("text + thought(no-sig) + functionCall + usage + finish", () => {
+    const events = [
+      { candidates: [{ content: { parts: [{ text: "thinking part", thought: true }] } }], responseId: "resp_1", modelVersion: "gemini-3-pro" },
+      { candidates: [{ content: { parts: [{ text: "Answer" }] } }] },
+      { candidates: [{ content: { parts: [{ functionCall: { name: "search", args: { q: "x" } } }] } }] },
+      { candidates: [{ finishReason: "STOP" }], usageMetadata: { promptTokenCount: 8, candidatesTokenCount: 4, thoughtsTokenCount: 2, totalTokenCount: 14, cachedContentTokenCount: 1 } },
+    ];
+    expect(runStream(FORMATS.GEMINI, FORMATS.OPENAI, events)).toMatchSnapshot();
+  });
+
+  it("image output (inlineData → delta.images)", () => {
+    const events = [
+      { candidates: [{ content: { parts: [{ inlineData: { mimeType: "image/png", data: "BASE64DATA" } }] } }], responseId: "resp_2", modelVersion: "gemini-3-flash-image" },
+      { candidates: [{ finishReason: "STOP" }] },
+    ];
+    expect(runStream(FORMATS.GEMINI, FORMATS.OPENAI, events)).toMatchSnapshot();
+  });
+});
+
+describe("GOLDEN response stream: Kiro → OpenAI", () => {
+  it("text + reasoning + toolUse + usage + stop", () => {
+    const events = [
+      { assistantResponseEvent: { content: "Hello" }, _eventType: "assistantResponseEvent" },
+      { reasoningContentEvent: { text: "thinking" }, _eventType: "reasoningContentEvent" },
+      { toolUseEvent: { toolUseId: "tu_1", name: "get_weather", input: { city: "NYC" } }, _eventType: "toolUseEvent" },
+      { usageEvent: { inputTokens: 10, outputTokens: 5 }, _eventType: "usageEvent" },
+      { _eventType: "messageStopEvent" },
+    ];
+    expect(runStream(FORMATS.KIRO, FORMATS.OPENAI, events)).toMatchSnapshot();
+  });
+});
+
+describe("GOLDEN response stream: Ollama → OpenAI", () => {
+  it("content + thinking + tool_calls + done usage", () => {
+    const events = [
+      { model: "qwen3", message: { role: "assistant", content: "Hi", thinking: "reason" } },
+      { model: "qwen3", message: { role: "assistant", tool_calls: [{ function: { name: "search", arguments: { q: "x" } } }] } },
+      { model: "qwen3", done: true, done_reason: "stop", prompt_eval_count: 8, eval_count: 4 },
+    ];
+    expect(runStream(FORMATS.OLLAMA, FORMATS.OPENAI, events)).toMatchSnapshot();
+  });
+});
+
+describe("GOLDEN response stream: OpenAI-Responses (codex) → OpenAI", () => {
+  it("text + reasoning + tool_call + completed usage", () => {
+    const events = [
+      { type: "response.output_text.delta", delta: "Hello" },
+      { type: "response.reasoning_summary_text.delta", delta: "thinking" },
+      { type: "response.output_item.added", item: { type: "function_call", call_id: "call_1", name: "get_weather" } },
+      { type: "response.function_call_arguments.delta", delta: '{"city":"NYC"}' },
+      { type: "response.output_item.done", item: { type: "function_call" } },
+      { type: "response.completed", response: { usage: { input_tokens: 10, output_tokens: 5, input_tokens_details: { cached_tokens: 3 } } } },
+    ];
+    expect(runStream(FORMATS.OPENAI_RESPONSES, FORMATS.OPENAI, events)).toMatchSnapshot();
+  });
+
+  it("error event → error chunk (fallback id/created)", () => {
+    const events = [
+      { type: "error", error: { message: "model_not_found" } },
+    ];
+    expect(runStream(FORMATS.OPENAI_RESPONSES, FORMATS.OPENAI, events)).toMatchSnapshot();
+  });
+});
diff --git a/tests/translator/golden-translator-concerns.test.js b/tests/translator/golden-translator-concerns.test.js
new file mode 100644
index 0000000..4efc2b9
--- /dev/null
+++ b/tests/translator/golden-translator-concerns.test.js
@@ -0,0 +1,106 @@
+// P0 GOLDEN (refactor2): lock OUTPUT translateResponse/Request cho các concern
+// SẮP refactor ở P1-P4 (usage field-map, finishReasonMap, reasoningDelta).
+// Bổ sung coverage còn thiếu so với golden-response-stream.test.js:
+//   - commandcode usage/finish
+//   - passthrough openai→openai (request + response)
+//   - kiro/ollama finish_reason sau tool (lock behavior HIỆN TẠI, kể cả bug đã biết)
+// Sau refactor chạy lại phải khớp y hệt. Lệch = regression.
+import { describe, it, expect } from "vitest";
+import "./registerAll.js";
+import { translateRequest, translateResponse, initState } from "../../open-sse/translator/index.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+// Strip volatile id/created so snapshots are stable across runs.
+function stripVolatile(chunks) {
+  return JSON.parse(JSON.stringify(chunks), (key, val) => {
+    if (key === "created") return 0;
+    if (key === "id" && typeof val === "string") {
+      return val
+        .replace(/-\d{10,}-(\d+)$/, "-<TS>-$1")
+        .replace(/^chatcmpl-\d{10,}$/, "chatcmpl-<TS>")
+        .replace(/^call_(\d+)_\d{10,}$/, "call_$1_<TS>")
+        .replace(/^call_\d{10,}_(\d+)$/, "call_<TS>_$1");
+    }
+    return val;
+  });
+}
+
+function runStream(targetFormat, sourceFormat, events) {
+  const state = initState(sourceFormat);
+  const all = [];
+  for (const ev of events) {
+    const out = translateResponse(targetFormat, sourceFormat, ev, state);
+    if (Array.isArray(out)) all.push(...out);
+    else if (out) all.push(out);
+  }
+  return stripVolatile(all);
+}
+
+describe("GOLDEN response stream: CommandCode → OpenAI", () => {
+  it("text + reasoning + tool + finish-step usage", () => {
+    const events = [
+      { type: "text-delta", text: "Hello" },
+      { type: "reasoning-delta", text: "thinking" },
+      { type: "tool-input-start", id: "t1", toolName: "get_weather" },
+      { type: "tool-input-delta", id: "t1", delta: '{"city":"NYC"}' },
+      { type: "finish-step", finishReason: "tool-calls", usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 } },
+      { type: "finish" },
+    ];
+    expect(runStream(FORMATS.COMMANDCODE, FORMATS.OPENAI, events)).toMatchSnapshot();
+  });
+});
+
+describe("GOLDEN response stream: Kiro → OpenAI (finish after tool)", () => {
+  it("toolUse then stop — lock current finish_reason behavior", () => {
+    const events = [
+      { assistantResponseEvent: { content: "Hi" }, _eventType: "assistantResponseEvent" },
+      { toolUseEvent: { toolUseId: "tu_1", name: "search", input: { q: "x" } }, _eventType: "toolUseEvent" },
+      { usageEvent: { inputTokens: 7, outputTokens: 3 }, _eventType: "usageEvent" },
+      { _eventType: "messageStopEvent" },
+    ];
+    expect(runStream(FORMATS.KIRO, FORMATS.OPENAI, events)).toMatchSnapshot();
+  });
+});
+
+describe("GOLDEN response stream: Ollama → OpenAI (finish after tool)", () => {
+  it("tool_calls then done_reason=stop — lock current finish_reason", () => {
+    const events = [
+      { model: "qwen3", message: { role: "assistant", tool_calls: [{ function: { name: "search", arguments: { q: "x" } } }] } },
+      { model: "qwen3", done: true, done_reason: "stop", prompt_eval_count: 5, eval_count: 2 },
+    ];
+    expect(runStream(FORMATS.OLLAMA, FORMATS.OPENAI, events)).toMatchSnapshot();
+  });
+});
+
+describe("GOLDEN passthrough: same format = no translation", () => {
+  it("response openai→openai returns chunk unchanged", () => {
+    const chunk = { id: "chatcmpl-x", object: "chat.completion.chunk", created: 1, model: "gpt-4o", choices: [{ index: 0, delta: { content: "hi" }, finish_reason: null }] };
+    const state = initState(FORMATS.OPENAI);
+    const out = translateResponse(FORMATS.OPENAI, FORMATS.OPENAI, chunk, state);
+    expect(out).toEqual([chunk]);
+  });
+
+  it("request openai→openai keeps messages (filterToOpenAIFormat normalize)", () => {
+    const body = { model: "gpt-4o", messages: [{ role: "user", content: "hi" }] };
+    const out = translateRequest(FORMATS.OPENAI, FORMATS.OPENAI, "gpt-4o", body, true);
+    expect(out.messages).toEqual([{ role: "user", content: "hi" }]);
+  });
+});
+
+describe("GOLDEN usage math: Claude prompt = input + cache (lock)", () => {
+  it("prompt_tokens sums input + cache_read + cache_creation", () => {
+    const events = [
+      { type: "message_start", message: { id: "msg_1", model: "claude-opus-4-6" } },
+      { type: "content_block_start", index: 0, content_block: { type: "text" } },
+      { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "ok" } },
+      { type: "content_block_stop", index: 0 },
+      { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 3, cache_creation_input_tokens: 2 } },
+      { type: "message_stop" },
+    ];
+    const out = runStream(FORMATS.CLAUDE, FORMATS.OPENAI, events);
+    const finalChunk = out.find(c => c.usage);
+    expect(finalChunk.usage.prompt_tokens).toBe(15); // 10 + 3 + 2
+    expect(finalChunk.usage.completion_tokens).toBe(5);
+    expect(finalChunk.usage).toMatchSnapshot();
+  });
+});
diff --git a/tests/translator/golden-url-header.test.js b/tests/translator/golden-url-header.test.js
new file mode 100644
index 0000000..b9f6bff
--- /dev/null
+++ b/tests/translator/golden-url-header.test.js
@@ -0,0 +1,72 @@
+// P0 GOLDEN: lock buildUrl + buildHeaders cho mọi provider trên code CŨ.
+// Sinh snapshot lần đầu (baseline) → sau refactor chạy lại phải khớp y hệt.
+// Mock proxyFetch + uuid-heavy executors KHÔNG cần ở đây vì chỉ gọi buildUrl/buildHeaders (pure).
+import { describe, it, expect } from "vitest";
+import { PROVIDERS } from "../../open-sse/config/providers.js";
+import { DefaultExecutor } from "../../open-sse/executors/default.js";
+
+// Credentials mẫu cố định (deterministic) — KHÔNG dùng Date.now/random.
+const API_KEY_CRED = { apiKey: "sk-test-APIKEY", providerSpecificData: {} };
+const OAUTH_CRED = { accessToken: "tok-test-ACCESS", providerSpecificData: {} };
+const SPECIAL_CRED = {
+  apiKey: "sk-test-APIKEY",
+  accessToken: "tok-test-ACCESS",
+  providerSpecificData: { accountId: "ACC123", region: "sgp", baseUrl: "https://custom.example.com/v1", orgId: "ORG9" },
+};
+
+// Provider cần executor riêng (buildUrl/buildHeaders không nằm ở DefaultExecutor) → bỏ qua ở golden này.
+// Chúng được lock riêng ở 11-provider edge tests / unit test chuyên biệt.
+const SPECIALIZED = new Set([
+  "antigravity", "azure", "gemini-cli", "github", "iflow", "qoder", "kiro",
+  "codex", "cursor", "vertex", "vertex-partner", "qwen", "opencode",
+  "opencode-go", "grok-web", "perplexity-web", "ollama-local", "commandcode",
+  "xiaomi-tokenplan", "mimo-free",
+]);
+
+// Sanitize header: khử token + field thời gian động (kimi X-Msh-Device-Id) để snapshot ổn định.
+function sanitize(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    out[k] = typeof v === "string"
+      ? v.replace(/Bearer .+/, "Bearer <TOK>")
+          .replace(/sk-test-APIKEY|tok-test-ACCESS/g, "<CRED>")
+          .replace(/kimi-\d{10,}/g, "kimi-<TS>")
+      : v;
+  }
+  return out;
+}
+
+const providerIds = Object.keys(PROVIDERS).filter((p) => !SPECIALIZED.has(p)).sort();
+
+describe("GOLDEN buildUrl (default executor providers)", () => {
+  for (const pid of providerIds) {
+    it(`${pid} → url (stream + non-stream)`, () => {
+      const ex = new DefaultExecutor(pid);
+      const cred = PROVIDERS[pid].noAuth ? {} : SPECIAL_CRED;
+      const model = "test-model";
+      const snap = {
+        stream: safe(() => ex.buildUrl(model, true, 0, cred)),
+        nonStream: safe(() => ex.buildUrl(model, false, 0, cred)),
+      };
+      expect(snap).toMatchSnapshot();
+    });
+  }
+});
+
+describe("GOLDEN buildHeaders (default executor providers)", () => {
+  for (const pid of providerIds) {
+    it(`${pid} → headers (apiKey / oauth)`, () => {
+      const ex = new DefaultExecutor(pid);
+      const snap = {
+        apiKey: safe(() => sanitize(ex.buildHeaders(PROVIDERS[pid].noAuth ? {} : API_KEY_CRED, true))),
+        oauth: safe(() => sanitize(ex.buildHeaders(PROVIDERS[pid].noAuth ? {} : OAUTH_CRED, true))),
+        nonStream: safe(() => sanitize(ex.buildHeaders(PROVIDERS[pid].noAuth ? {} : API_KEY_CRED, false))),
+      };
+      expect(snap).toMatchSnapshot();
+    });
+  }
+});
+
+function safe(fn) {
+  try { return fn(); } catch (e) { return `THROW: ${e.message}`; }
+}
diff --git a/tests/translator/matrix.js b/tests/translator/matrix.js
new file mode 100644
index 0000000..bc3a4e0
--- /dev/null
+++ b/tests/translator/matrix.js
@@ -0,0 +1,67 @@
+// Data-driven test matrix built from PROVIDER_MODELS (single source of truth).
+// Adding a new provider/model to config auto-extends coverage — no test edits needed.
+import {
+  PROVIDER_MODELS,
+  PROVIDER_ID_TO_ALIAS,
+  getModelTargetFormat,
+  getModelStrip,
+  getModelUpstreamId,
+} from "../../open-sse/config/providerModels.js";
+import { PROVIDERS } from "../../open-sse/config/providers.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+// Reverse alias → providerId to resolve provider-level config.format
+const ALIAS_TO_PROVIDER_ID = Object.fromEntries(
+  Object.entries(PROVIDER_ID_TO_ALIAS).map(([id, alias]) => [alias, id])
+);
+
+// Provider-level format fallback (mirrors getTargetFormat without compat-url logic)
+function providerFormat(alias) {
+  const providerId = ALIAS_TO_PROVIDER_ID[alias] || alias;
+  return PROVIDERS[providerId]?.format || FORMATS.OPENAI;
+}
+
+// Resolve effective target format for an (alias, model): model override → provider format
+export function resolveTargetFormat(alias, modelId) {
+  return getModelTargetFormat(alias, modelId) || providerFormat(alias);
+}
+
+// Flat matrix of every model across every provider
+export function buildModelMatrix() {
+  const rows = [];
+  for (const [alias, models] of Object.entries(PROVIDER_MODELS)) {
+    if (!Array.isArray(models)) continue;
+    for (const m of models) {
+      rows.push({
+        alias,
+        providerId: ALIAS_TO_PROVIDER_ID[alias] || alias,
+        modelId: m.id,
+        type: m.type || "llm",
+        targetFormat: resolveTargetFormat(alias, m.id),
+        strip: getModelStrip(alias, m.id),
+        upstreamId: getModelUpstreamId(alias, m.id),
+      });
+    }
+  }
+  return rows;
+}
+
+// Distinct provider list (one representative llm model each) for grouped assertions
+export function buildProviderGroups() {
+  const groups = [];
+  for (const [alias, models] of Object.entries(PROVIDER_MODELS)) {
+    if (!Array.isArray(models) || models.length === 0) continue;
+    const llm = models.filter((m) => (m.type || "llm") === "llm");
+    groups.push({ alias, models: llm.length ? llm : models });
+  }
+  return groups;
+}
+
+// CLI source formats that real clients emit (the "specials" the user cares about)
+export const CLI_SOURCE_FORMATS = [
+  FORMATS.CLAUDE,
+  FORMATS.OPENAI_RESPONSES,
+  FORMATS.GEMINI,
+  FORMATS.OPENAI,
+  FORMATS.ANTIGRAVITY,
+];
diff --git a/tests/translator/real/all-formats.real.test.js b/tests/translator/real/all-formats.real.test.js
new file mode 100644
index 0000000..c8455be
--- /dev/null
+++ b/tests/translator/real/all-formats.real.test.js
@@ -0,0 +1,293 @@
+// REAL matrix test: every active provider in DB x every inbound client format x 4 scenarios.
+// Goal: maximize translation-path coverage to surface real bugs (system, multimodal image,
+// tool-call/tool-result, reasoning) across all source formats.
+//
+//   RUN_REAL=1 npx vitest run --config tests/vitest.config.js tests/translator/real/all-formats.real.test.js
+//   RUN_REAL=1 REAL_PROVIDERS=gemini,kiro,codex npx vitest run ... (optional filter)
+//
+// Skips (console.warn + pass) when: no credential/model, auth/quota status (401/402/403/429),
+// or the model rejects a capability (e.g. image on a non-vision model).
+import { describe, it, expect } from "vitest";
+import { getProviderCredentials } from "../../../src/sse/services/auth.js";
+import { checkAndRefreshToken } from "../../../src/sse/services/tokenRefresh.js";
+import { handleChatCore } from "../../../open-sse/handlers/chatCore.js";
+import { getModelsByProviderId } from "../../../open-sse/config/providerModels.js";
+
+const RUN_REAL = process.env.RUN_REAL === "1";
+const TIMEOUT_MS = 90000;
+const CRED_ISSUE = [401, 402, 403, 429];
+// Account/plan/capability rejections -> skip (not a translate bug). Kept specific to avoid masking real bugs.
+const SKIP_MSG_RE = /image|multimodal|vision|modality|unsupported|not support|reasoning_effort|deprecated|temperature|subscription|valid.*plan|embedding|quota|insufficient|model not found|context length|organization policy|disallowed|allowedmodels|failed_precondition/i;
+
+const PROVIDER_FILTER = (process.env.REAL_PROVIDERS || "")
+  .split(",").map((s) => s.trim()).filter(Boolean);
+
+// Tiny 1x1 transparent PNG (data URI body + raw base64) for multimodal scenarios.
+const PNG_B64 =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+const PNG_DATA_URI = `data:image/png;base64,${PNG_B64}`;
+
+// Pick first chat LLM, excluding non-chat kinds (embedding/image/tts/stt/...).
+const NON_CHAT_KINDS = new Set(["embedding", "image", "imageToText", "tts", "stt", "video", "music", "webSearch"]);
+function firstLlmModel(providerId) {
+  const models = getModelsByProviderId(providerId);
+  const llm = models.find((m) => {
+    const kind = m.kind || m.type || "llm";
+    return kind === "llm" || (!NON_CHAT_KINDS.has(kind) && kind === "llm");
+  }) || models.find((m) => !NON_CHAT_KINDS.has(m.kind || m.type || "llm"));
+  return llm?.id || null;
+}
+
+async function drainSSE(response) {
+  if (!response?.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let out = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += decoder.decode(value, { stream: true });
+  }
+  return out;
+}
+
+async function prepare(providerId) {
+  const model = firstLlmModel(providerId);
+  if (!model) return null;
+  const credentials = await getProviderCredentials(providerId, new Set(), model);
+  if (!credentials || credentials.allRateLimited) return null;
+  const refreshed = await checkAndRefreshToken(providerId, credentials);
+  return { model, credentials, refreshed };
+}
+
+// Run one request. Returns { raw } | "skip" | throws (real translate/runtime bug).
+async function runChat(providerId, prep, body, sourceFormatOverride) {
+  const result = await handleChatCore({
+    body: { ...body, model: `${providerId}/${prep.model}` },
+    modelInfo: { provider: providerId, model: prep.model },
+    credentials: prep.refreshed,
+    connectionId: prep.credentials.connectionId,
+    sourceFormatOverride,
+  });
+  if (!result.success) {
+    const status = Number(result.status);
+    if (CRED_ISSUE.includes(status)) return "skip";
+    // Upstream 5xx and 406 are provider-side issues, not translate bugs.
+    if (status >= 500 || status === 406) return "skip";
+    // Account/plan/capability rejection (e.g. non-vision model + image) is not a translate bug.
+    if (status === 400 && SKIP_MSG_RE.test(String(result.error || ""))) return "skip";
+    throw new Error(`${providerId} [${result.status}]: ${result.error}`);
+  }
+  return { raw: await drainSSE(result.response) };
+}
+
+// SSE validity marker per inbound format (response is re-encoded back to source format).
+const SSE_MARKER = {
+  openai: /chat\.completion\.chunk|"delta"|\[DONE\]/,
+  "openai-responses": /response\.|"type"\s*:\s*"response|\[DONE\]/,
+  claude: /event:\s*\w|"type"\s*:\s*"(message_start|content_block|message_delta)"/,
+  gemini: /"candidates"|"content"|data:/,
+  "gemini-cli": /"candidates"|"content"|data:/,
+  antigravity: /"candidates"|"content"|data:/,
+};
+
+// ---- Body builders: per format x scenario (full, spec-correct shapes) ----
+
+const COMMON = { temperature: 0.3, top_p: 0.9, max_tokens: 256 };
+// Reasoning models often reject custom temperature (must be default/1) -> omit sampling.
+const REASON_TOK = { max_tokens: 1024 };
+
+// OpenAI Chat Completions
+const openaiBody = {
+  basic: () => ({
+    ...COMMON, stream: true, stream_options: { include_usage: true },
+    messages: [
+      { role: "system", content: "You are concise." },
+      { role: "user", content: "Reply with the single word: hi" },
+    ],
+  }),
+  multimodal: () => ({
+    ...COMMON, stream: true,
+    messages: [
+      { role: "system", content: "Describe images briefly." },
+      { role: "user", content: [
+        { type: "text", text: "What color dominates this image? One word." },
+        { type: "image_url", image_url: { url: PNG_DATA_URI } },
+      ] },
+    ],
+  }),
+  tools: () => ({
+    ...COMMON, stream: true, tool_choice: "auto",
+    tools: [{ type: "function", function: { name: "get_weather", description: "Get weather", parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] } } }],
+    messages: [
+      { role: "user", content: "Weather in Paris?" },
+      { role: "assistant", content: "", tool_calls: [{ id: "call_1", type: "function", function: { name: "get_weather", arguments: '{"city":"Paris"}' } }] },
+      { role: "tool", tool_call_id: "call_1", content: '{"temp":"20C"}' },
+      { role: "user", content: "Summarize in one short sentence." },
+    ],
+  }),
+  reasoning: () => ({
+    ...REASON_TOK, stream: true, reasoning_effort: "low",
+    messages: [{ role: "user", content: "What is 17 + 26? Reply with just the number." }],
+  }),
+};
+
+// OpenAI Responses API
+const responsesBody = {
+  basic: () => ({
+    ...COMMON, stream: true, max_output_tokens: 256,
+    instructions: "You are concise.",
+    input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "Reply with the single word: hi" }] }],
+  }),
+  multimodal: () => ({
+    ...COMMON, stream: true, max_output_tokens: 256,
+    instructions: "Describe images briefly.",
+    input: [{ type: "message", role: "user", content: [
+      { type: "input_text", text: "What color dominates? One word." },
+      { type: "input_image", image_url: PNG_DATA_URI },
+    ] }],
+  }),
+  tools: () => ({
+    ...COMMON, stream: true,
+    tools: [{ type: "function", name: "get_weather", description: "Get weather", parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] } }],
+    input: [
+      { type: "message", role: "user", content: [{ type: "input_text", text: "Weather in Paris?" }] },
+      { type: "function_call", call_id: "call_1", name: "get_weather", arguments: '{"city":"Paris"}' },
+      { type: "function_call_output", call_id: "call_1", output: '{"temp":"20C"}' },
+      { type: "message", role: "user", content: [{ type: "input_text", text: "Summarize in one short sentence." }] },
+    ],
+  }),
+  reasoning: () => ({
+    ...REASON_TOK, stream: true, max_output_tokens: 1024, reasoning: { effort: "low" },
+    input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "What is 17 + 26? Just the number." }] }],
+  }),
+};
+
+// Anthropic Messages (Claude)
+const claudeBody = {
+  basic: () => ({
+    ...COMMON, stream: true,
+    system: [{ type: "text", text: "You are concise." }],
+    messages: [{ role: "user", content: "Reply with the single word: hi" }],
+  }),
+  multimodal: () => ({
+    ...COMMON, stream: true,
+    system: [{ type: "text", text: "Describe images briefly." }],
+    messages: [{ role: "user", content: [
+      { type: "text", text: "What color dominates? One word." },
+      { type: "image", source: { type: "base64", media_type: "image/png", data: PNG_B64 } },
+    ] }],
+  }),
+  tools: () => ({
+    ...COMMON, stream: true,
+    tools: [{ name: "get_weather", description: "Get weather", input_schema: { type: "object", properties: { city: { type: "string" } }, required: ["city"] } }],
+    messages: [
+      { role: "user", content: "Weather in Paris?" },
+      { role: "assistant", content: [{ type: "tool_use", id: "toolu_1", name: "get_weather", input: { city: "Paris" } }] },
+      { role: "user", content: [{ type: "tool_result", tool_use_id: "toolu_1", content: '{"temp":"20C"}' }] },
+      { role: "user", content: "Summarize in one short sentence." },
+    ],
+  }),
+  reasoning: () => ({
+    ...REASON_TOK, stream: true, thinking: { type: "enabled", budget_tokens: 1024 },
+    messages: [{ role: "user", content: "What is 17 + 26? Just the number." }],
+  }),
+};
+
+// Gemini generateContent
+const geminiBody = {
+  basic: () => ({
+    systemInstruction: { parts: [{ text: "You are concise." }] },
+    contents: [{ role: "user", parts: [{ text: "Reply with the single word: hi" }] }],
+    generationConfig: { maxOutputTokens: 256, temperature: 0.3, topP: 0.9 },
+  }),
+  multimodal: () => ({
+    systemInstruction: { parts: [{ text: "Describe images briefly." }] },
+    contents: [{ role: "user", parts: [
+      { text: "What color dominates? One word." },
+      { inlineData: { mimeType: "image/png", data: PNG_B64 } },
+    ] }],
+    generationConfig: { maxOutputTokens: 256 },
+  }),
+  tools: () => ({
+    tools: [{ functionDeclarations: [{ name: "get_weather", description: "Get weather", parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] } }] }],
+    contents: [
+      { role: "user", parts: [{ text: "Weather in Paris?" }] },
+      { role: "model", parts: [{ functionCall: { name: "get_weather", args: { city: "Paris" } } }] },
+      { role: "user", parts: [{ functionResponse: { name: "get_weather", response: { temp: "20C" } } }] },
+      { role: "user", parts: [{ text: "Summarize in one short sentence." }] },
+    ],
+    generationConfig: { maxOutputTokens: 256 },
+  }),
+  reasoning: () => ({
+    contents: [{ role: "user", parts: [{ text: "What is 17 + 26? Just the number." }] }],
+    generationConfig: { maxOutputTokens: 1024, thinkingConfig: { thinkingBudget: 512, includeThoughts: true } },
+  }),
+};
+
+// Antigravity = Gemini body wrapped in { request, userAgent }.
+const wrapAntigravity = (fn) => () => ({ request: fn(), userAgent: "antigravity" });
+const antigravityBody = {
+  basic: wrapAntigravity(geminiBody.basic),
+  multimodal: wrapAntigravity(geminiBody.multimodal),
+  tools: wrapAntigravity(geminiBody.tools),
+  reasoning: wrapAntigravity(geminiBody.reasoning),
+};
+
+const BUILDERS = {
+  openai: openaiBody,
+  "openai-responses": responsesBody,
+  claude: claudeBody,
+  gemini: geminiBody,
+  "gemini-cli": geminiBody,
+  antigravity: antigravityBody,
+};
+
+const FORMATS = Object.keys(BUILDERS);
+const SCENARIOS = ["basic", "multimodal", "tools", "reasoning"];
+
+// Read active providers from DB at module-eval time (one test per provider/format/scenario).
+function targetProviders() {
+  try {
+    const Database = require("better-sqlite3");
+    const os = require("os");
+    const path = require("path");
+    const dbPath = process.env.DATA_DIR
+      ? path.join(process.env.DATA_DIR, "db", "data.sqlite")
+      : path.join(os.homedir(), ".9router", "db", "data.sqlite");
+    const db = new Database(dbPath, { readonly: true });
+    const rows = db.prepare("SELECT DISTINCT provider FROM providerConnections WHERE isActive = 1").all();
+    db.close();
+    let list = rows.map((r) => r.provider).sort();
+    if (PROVIDER_FILTER.length) list = list.filter((p) => PROVIDER_FILTER.includes(p));
+    return list;
+  } catch {
+    return [];
+  }
+}
+
+describe.skipIf(!RUN_REAL)("REAL all-formats matrix", () => {
+  const providers = RUN_REAL ? targetProviders() : [];
+
+  it("has active providers in DB", () => {
+    expect(providers.length).toBeGreaterThan(0);
+  });
+
+  for (const providerId of providers) {
+    for (const fmt of FORMATS) {
+      for (const scn of SCENARIOS) {
+        it.concurrent(`${providerId} | ${fmt} | ${scn}`, async () => {
+          const prep = await prepare(providerId);
+          if (!prep) { console.warn(`[skip] ${providerId}: no cred/model`); return expect(true).toBe(true); }
+
+          const body = BUILDERS[fmt][scn]();
+          const out = await runChat(providerId, prep, body, fmt);
+          if (out === "skip") { console.warn(`[skip] ${providerId} ${fmt}/${scn}: cred/quota/capability`); return expect(true).toBe(true); }
+
+          expect(out.raw.length, `${providerId} ${fmt}/${scn}: empty SSE`).toBeGreaterThan(0);
+          expect(SSE_MARKER[fmt].test(out.raw), `${providerId} ${fmt}/${scn}: invalid SSE shape`).toBe(true);
+        }, TIMEOUT_MS);
+      }
+    }
+  }
+});
diff --git a/tests/translator/real/antigravity-models.real.test.js b/tests/translator/real/antigravity-models.real.test.js
new file mode 100644
index 0000000..2b0886d
--- /dev/null
+++ b/tests/translator/real/antigravity-models.real.test.js
@@ -0,0 +1,127 @@
+// REAL integration test: hits localhost:20128/v1 with real API key for all antigravity models.
+// Verifies tool-call with optional field in schema doesn't cause 400 INVALID_ARGUMENT.
+//
+//   RUN_REAL=1 npx vitest run --config tests/vitest.config.js tests/translator/real/antigravity-models.real.test.js
+//   RUN_REAL=1 AG_URL=http://localhost:20128/v1 AG_KEY=sk-xxx npx vitest run ...
+//
+import { describe, it, expect } from "vitest";
+
+const RUN_REAL = process.env.RUN_REAL === "1";
+const BASE_URL = process.env.AG_URL || "http://localhost:20128/v1";
+const API_KEY = process.env.AG_KEY;
+const TIMEOUT_MS = 90000;
+
+// All antigravity models (from providers/registry/antigravity.js)
+const AG_MODELS = [
+  "ag/gemini-3-flash-agent",
+  "ag/gemini-3.5-flash-low",
+  "ag/gemini-3.5-flash-extra-low",
+  "ag/gemini-pro-agent",
+  "ag/gemini-3.1-pro-low",
+  "ag/claude-sonnet-4-6",
+  "ag/claude-opus-4-6-thinking",
+  "ag/gpt-oss-120b-medium",
+  "ag/gemini-3-flash",
+];
+
+// Simple text prompt — no tools
+const SIMPLE_BODY = (model) => ({
+  model,
+  stream: false,
+  max_tokens: 32,
+  messages: [{ role: "user", content: "Reply with the single word: hi" }],
+});
+
+// Tool call with `optional` field in schema — this is the bug scenario
+const TOOL_BODY = (model) => ({
+  model,
+  stream: false,
+  max_tokens: 64,
+  messages: [{ role: "user", content: "What is 2+2?" }],
+  tools: [
+    {
+      type: "function",
+      function: {
+        name: "calculate",
+        description: "Perform arithmetic",
+        parameters: {
+          type: "object",
+          properties: {
+            expression: { type: "string", description: "The math expression", optional: true },
+            precision: { type: "number", description: "Decimal precision", optional: true },
+            note: { type: "string", optional: true },
+          },
+          required: [],
+        },
+      },
+    },
+  ],
+});
+
+async function callChat(body) {
+  const res = await fetch(`${BASE_URL}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${API_KEY}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  const text = await res.text();
+  let json = null;
+  try { json = JSON.parse(text); } catch { /* non-json */ }
+
+  return { status: res.status, text, json };
+}
+
+describe.skipIf(!RUN_REAL).concurrent("antigravity models — real", () => {
+  for (const model of AG_MODELS) {
+    it(`${model}: simple prompt`, async () => {
+      const { status, json, text } = await callChat(SIMPLE_BODY(model));
+
+      // Credential/quota issues are not translation bugs → warn and pass
+      if ([401, 402, 403, 429].includes(status)) {
+        console.warn(`[skip] ${model}: ${status} (credential/quota)`);
+        return;
+      }
+
+      // Provider-side 400 (e.g. stream_options, model quirks) → skip
+      if (status === 400) {
+        console.warn(`[skip] ${model}: 400 (provider quirk): ${text.slice(0, 200)}`);
+        return;
+      }
+
+      expect(status, `${model} simple: ${text.slice(0, 300)}`).toBe(200);
+      // Accept either OpenAI-shaped or raw Gemini-shaped response
+      const hasContent =
+        json?.choices?.[0]?.message?.content ||
+        json?.choices?.[0]?.message?.tool_calls ||
+        json?.candidates?.[0]?.content?.parts?.length > 0 ||
+        json?.choices?.[0]?.finish_reason;
+      expect(hasContent, `${model} simple: no content in ${text.slice(0, 300)}`).toBeTruthy();
+    }, TIMEOUT_MS);
+
+    it(`${model}: tool call with optional field in schema`, async () => {
+      const { status, json, text } = await callChat(TOOL_BODY(model));
+
+      if ([401, 402, 403, 429].includes(status)) {
+        console.warn(`[skip] ${model}: ${status} (credential/quota)`);
+        return;
+      }
+
+      // 400 with "optional" + "Cannot find field" = the specific bug
+      if (status === 400) {
+        const errMsg = json?.error?.message || text;
+        if (/optional.*Cannot find field|Cannot find field.*optional|Unknown name.*optional/i.test(errMsg)) {
+          throw new Error(`BUG: ${model} — 400 due to optional field: ${errMsg.slice(0, 300)}`);
+        }
+        // Other 400 (e.g. model doesn't support tools, stream_options issue) → skip
+        console.warn(`[skip] ${model}: 400 non-optional error: ${errMsg.slice(0, 200)}`);
+        return;
+      }
+
+      expect(status, `${model} tool: ${text.slice(0, 300)}`).toBe(200);
+    }, TIMEOUT_MS);
+  }
+});
diff --git a/tests/translator/real/file-base64-survey.real.test.js b/tests/translator/real/file-base64-survey.real.test.js
new file mode 100644
index 0000000..d7d16f2
--- /dev/null
+++ b/tests/translator/real/file-base64-survey.real.test.js
@@ -0,0 +1,168 @@
+// REAL survey: send PDF/DOCX as base64 to every active provider, using the file/document
+// shape NATIVE to each provider's format (claude=document, gemini=inlineData, openai=file).
+// Purpose: discover which providers actually accept inline base64 documents and how they
+// reject DOCX. Survey-only: logs a grouped table, never asserts on accept/reject outcome.
+//
+//   RUN_REAL=1 npx vitest run --config tests/vitest.config.js tests/translator/real/file-base64-survey.real.test.js
+import { describe, it, expect, afterAll } from "vitest";
+import { getProviderCredentials } from "../../../src/sse/services/auth.js";
+import { checkAndRefreshToken } from "../../../src/sse/services/tokenRefresh.js";
+import { handleChatCore } from "../../../open-sse/handlers/chatCore.js";
+import { getModelsByProviderId } from "../../../open-sse/config/providerModels.js";
+import { getTargetFormat } from "../../../open-sse/services/provider.js";
+
+const RUN_REAL = process.env.RUN_REAL === "1";
+const TIMEOUT_MS = 90000;
+const CRED_ISSUE = [401, 402, 403, 429];
+const CRED_MSG_RE = /subscription|unauthorized|invalid api key|invalid access token|insufficient|credits|payment|spending|organization policy|disallowed|quota|exhausted|not supported when using|not available for integrator|requires a subscription|model.*not found|does not exist|not yet known|requires a role|invalid model id/i;
+const NON_CHAT_KINDS = new Set(["embedding", "image", "imageToText", "tts", "stt", "video", "music", "webSearch"]);
+
+const PROVIDER_FILTER = (process.env.REAL_PROVIDERS || "")
+  .split(",").map((s) => s.trim()).filter(Boolean);
+
+const PDF_B64 = "JVBERi0xLjEKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iagozIDAgb2JqPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9NZWRpYUJveFswIDAgMjAwIDIwMF0+PmVuZG9iagp4cmVmCjAgNAowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1MiAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCnRyYWlsZXI8PC9TaXplIDQvUm9vdCAxIDAgUj4+CnN0YXJ0eHJlZgoxNjYKJSVFT0Y=";
+const DOCX_B64 = "UEsDBBQAAAAIAMZiz1yRzx8FvQAAACkBAAATABwAW0NvbnRlbnRfVHlwZXNdLnhtbFVUCQADA4wvagOML2p1eAsAAQT1AQAABAAAAAB9kL0OwjAMhF8lyoqoCwMDassArMDAC1ipWyKaHyXm7+1xATEwMNrf3fnkanV3g7pSyjb4Ws+KUq+a6viIlJUQn2t9Yo5LgGxO5DAXIZIX0oXkkGVMPUQ0Z+wJ5mW5ABM8k+cpjxm6qTbU4WVgtb3L+n1F7Fqt37rxVK0xxsEaZMEwUmiqvZRKtiV1wMQ7dKKCW0gttMFcnDiL/zFX3/50nYaus4a+/jEtpmAoZ+t7NxRf4tD6yacHvJ7RPAFQSwMECgAAAAAAxmLPXAAAAAAAAAAAAAAAAAUAHAB3b3JkL1VUCQADA4wvagOML2p1eAsAAQT1AQAABAAAAABQSwMEFAAAAAgAxmLPXD1WbTiKAAAAwAAAABEAHAB3b3JkL2RvY3VtZW50LnhtbFVUCQADA4wvagOML2p1eAsAAQT1AQAABAAAAABFjtEOgjAMRX9l2QdQ9MEHMuDV30BWgWRbl7aK/r0bxvhymuakt9eNrxjME1k2Sr09Na0dB7d3nuZHxKSm6CTd3ttVNXcAMq8YJ2koYyruThwnLSsvsBP7zDSjyJaWGODctheI05ZsjbyRf9eZK7hChyuGQKYcBm8URc3vr4OqK/lgPviNgH+94QNQSwECHgMUAAAACADGYs9ckc8fBb0AAAApAQAAEwAYAAAAAAABAAAApIEAAAAAW0NvbnRlbnRfVHlwZXNdLnhtbFVUBQADA4wvanV4CwABBPUBAAAEAAAAAFBLAQIeAwoAAAAAAMZiz1wAAAAAAAAAAAAAAAAFABgAAAAAAAAAEADtQQoBAAB3b3JkL1VUBQADA4wvanV4CwABBPUBAAAEAAAAAFBLAQIeAxQAAAAIAMZiz1w9Vm04igAAAMAAAAARABgAAAAAAAEAAACkgUkBAAB3b3JkL2RvY3VtZW50LnhtbFVUBQADA4wvanV4CwABBPUBAAAEAAAAAFBLBQYAAAAAAwADAPsAAAAeAgAAAAA=";
+
+const PDF_MIME = "application/pdf";
+const DOCX_MIME = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+
+// Build a native-format request body carrying one base64 document.
+// fmt = provider target format; returns { sourceFormat, body } or null if format unsupported here.
+function buildFileBody(fmt, mime, b64) {
+  const ask = "Summarize this document in one word.";
+  if (fmt === "claude") {
+    return { sourceFormat: "claude", body: {
+      max_tokens: 64, stream: true,
+      messages: [{ role: "user", content: [
+        { type: "text", text: ask },
+        { type: "document", source: { type: "base64", media_type: mime, data: b64 } },
+      ] }],
+    } };
+  }
+  if (fmt === "gemini" || fmt === "gemini-cli" || fmt === "antigravity") {
+    const gem = {
+      contents: [{ role: "user", parts: [
+        { text: ask },
+        { inlineData: { mimeType: mime, data: b64 } },
+      ] }],
+      generationConfig: { maxOutputTokens: 64 },
+    };
+    return fmt === "antigravity"
+      ? { sourceFormat: "antigravity", body: { request: gem, userAgent: "antigravity" } }
+      : { sourceFormat: fmt, body: gem };
+  }
+  // openai + openai-compat: Chat Completions file block (file_data data URI).
+  return { sourceFormat: "openai", body: {
+    max_tokens: 64, stream: true,
+    messages: [{ role: "user", content: [
+      { type: "text", text: ask },
+      { type: "file", file: { filename: `doc.${mime === PDF_MIME ? "pdf" : "docx"}`, file_data: `data:${mime};base64,${b64}` } },
+    ] }],
+  } };
+}
+
+const results = [];
+
+async function drainSSE(response) {
+  if (!response?.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let out = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += decoder.decode(value, { stream: true });
+  }
+  return out;
+}
+
+function chatModels(providerId) {
+  return getModelsByProviderId(providerId).filter((m) => !NON_CHAT_KINDS.has(m.kind || m.type || "llm"));
+}
+
+function targetProviders() {
+  try {
+    const Database = require("better-sqlite3");
+    const os = require("os");
+    const path = require("path");
+    const dbPath = process.env.DATA_DIR
+      ? path.join(process.env.DATA_DIR, "db", "data.sqlite")
+      : path.join(os.homedir(), ".9router", "db", "data.sqlite");
+    const db = new Database(dbPath, { readonly: true });
+    const rows = db.prepare("SELECT DISTINCT provider FROM providerConnections WHERE isActive = 1").all();
+    db.close();
+    let list = rows.map((r) => r.provider).sort();
+    if (PROVIDER_FILTER.length) list = list.filter((p) => PROVIDER_FILTER.includes(p));
+    return list;
+  } catch {
+    return [];
+  }
+}
+
+// One model per provider is enough to learn provider-level document support (saves quota).
+const FILE_TYPES = [["pdf", PDF_MIME, PDF_B64], ["docx", DOCX_MIME, DOCX_B64]];
+
+describe.skipIf(!RUN_REAL)("REAL file base64 survey", () => {
+  const providers = RUN_REAL ? targetProviders() : [];
+
+  it("has active providers in DB", () => {
+    expect(providers.length).toBeGreaterThan(0);
+  });
+
+  for (const providerId of providers) {
+    const model = (RUN_REAL ? chatModels(providerId)[0]?.id : null);
+    if (!model) continue;
+    for (const [kind, mime, b64] of FILE_TYPES) {
+      it.concurrent(`${kind} | ${providerId} / ${model}`, async () => {
+        const fmt = getTargetFormat(providerId);
+        const { sourceFormat, body } = buildFileBody(fmt, mime, b64);
+
+        const credentials = await getProviderCredentials(providerId, new Set(), model);
+        if (!credentials || credentials.allRateLimited) {
+          results.push({ kind, providerId, model, fmt, status: "no-cred", verdict: "skip" });
+          return expect(true).toBe(true);
+        }
+        const refreshed = await checkAndRefreshToken(providerId, credentials);
+
+        const result = await handleChatCore({
+          body: { ...body, model: `${providerId}/${model}` },
+          modelInfo: { provider: providerId, model },
+          credentials: refreshed,
+          connectionId: credentials.connectionId,
+          sourceFormatOverride: sourceFormat,
+        });
+
+        const status = Number(result.status) || (result.success ? 200 : 0);
+        const errMsg = result.success ? "" : String(result.error || "");
+        const credIssue = CRED_ISSUE.includes(status) || CRED_MSG_RE.test(errMsg);
+        const ok = result.success;
+
+        let verdict;
+        if (credIssue) verdict = "skip-cred";
+        else if (ok) verdict = `ok-${kind}`;
+        else verdict = `reject-${kind}`;
+
+        if (ok) await drainSSE(result.response).catch(() => {});
+        results.push({ kind, providerId, model, fmt, status, verdict, error: ok ? "" : errMsg.slice(0, 90) });
+        return expect(true).toBe(true);
+      }, TIMEOUT_MS);
+    }
+  }
+
+  afterAll(() => {
+    const w = (s) => process.stdout.write(s + "\n");
+    if (!results.length) { w("[file-survey] no results collected"); return; }
+    const rank = (v) => (v.startsWith("ok") ? 0 : v.startsWith("reject") ? 1 : 2);
+    const groups = [...new Set(results.map((r) => r.verdict))].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+    w("\n================ FILE BASE64 SURVEY ================");
+    for (const g of groups) {
+      const rows = results.filter((r) => r.verdict === g);
+      if (!rows.length) continue;
+      w(`\n### ${g} (${rows.length})`);
+      for (const r of rows) {
+        w(`  [${r.status}] ${r.kind} ${r.providerId}/${r.model} fmt=${r.fmt}${r.error ? ` :: ${r.error}` : ""}`);
+      }
+    }
+    w("\n================ END SURVEY ================\n");
+  });
+});
diff --git a/tests/translator/real/nvidia-thinking.e2e.test.js b/tests/translator/real/nvidia-thinking.e2e.test.js
new file mode 100644
index 0000000..2e2f67e
--- /dev/null
+++ b/tests/translator/real/nvidia-thinking.e2e.test.js
@@ -0,0 +1,58 @@
+// E2E: hit live local proxy → verify nvidia MiniMax M2.7 doesn't 400 on
+// unsupported "thinking" param (nvidia NIM is OpenAI-compatible).
+// Requires dev server running on NV_E2E_PORT + an active router API key in DB.
+// RUN_E2E=1 npx vitest run --config tests/vitest.config.js tests/translator/real/nvidia-thinking.e2e.test.js
+import { describe, it, expect, beforeAll } from "vitest";
+import { getApiKeys } from "../../../src/lib/db/repos/apiKeysRepo.js";
+
+const PORT = process.env.NV_E2E_PORT || "20127";
+const BASE = `http://localhost:${PORT}`;
+const MODELS = [
+  "nvidia/minimaxai/minimax-m2.7",
+  "nvidia/minimaxai/minimax-m3",
+  "nvidia/z-ai/glm-5.2",
+  "nvidia/deepseek-ai/deepseek-v4-pro",
+  "nvidia/deepseek-ai/deepseek-v4-flash",
+  "nvidia/moonshotai/kimi-k2.6",
+  "nvidia/nvidia/nemotron-3-ultra-550b-a55b",
+];
+const RUN = process.env.RUN_E2E === "1";
+const maybe = RUN ? describe : describe.skip;
+
+async function drain(res) {
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let out = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += decoder.decode(value, { stream: true });
+  }
+  return out;
+}
+
+maybe("nvidia thinking e2e", () => {
+  let apiKey = "";
+  beforeAll(async () => {
+    const keys = await getApiKeys();
+    apiKey = keys.find((k) => k.isActive)?.key || process.env.NV_E2E_KEY || "";
+  });
+
+  it.each(MODELS)("%s with reasoning_effort -> no 'thinking' 400", async (model) => {
+    if (!apiKey) return expect(true).toBe(true);
+    const res = await fetch(`${BASE}/v1/chat/completions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify({
+        model,
+        stream: true,
+        max_tokens: 64,
+        reasoning_effort: "low",
+        messages: [{ role: "user", content: "Reply with the single word: hi" }],
+      }),
+    });
+    const raw = await drain(res);
+    expect(/Unsupported parameter.*thinking/i.test(raw), `${model} rejected 'thinking'`).toBe(false);
+    expect(res.status, `${model} bad status ${res.status}`).toBeLessThan(400);
+  }, 90000);
+});
diff --git a/tests/translator/real/provider-cases.real.test.js b/tests/translator/real/provider-cases.real.test.js
new file mode 100644
index 0000000..f7e9214
--- /dev/null
+++ b/tests/translator/real/provider-cases.real.test.js
@@ -0,0 +1,168 @@
+// B2: REAL behavior assertions for the risky provider-specific cases.
+// Unlike smoke (only "doesn't crash"), each test asserts concrete OUTPUT.
+// Gated by RUN_REAL=1; any provider lacking creds/model or returning an auth/quota
+// status (401/402/403/429) is skipped (console.warn + pass).
+//
+//   RUN_REAL=1 npx vitest run --config tests/vitest.config.js tests/translator/real/provider-cases.real.test.js
+import { describe, it, expect } from "vitest";
+import { getProviderCredentials } from "../../../src/sse/services/auth.js";
+import { checkAndRefreshToken } from "../../../src/sse/services/tokenRefresh.js";
+import { handleChatCore } from "../../../open-sse/handlers/chatCore.js";
+import { getModelsByProviderId } from "../../../open-sse/config/providerModels.js";
+
+const RUN_REAL = process.env.RUN_REAL === "1";
+const TIMEOUT_MS = 90000;
+const CRED_ISSUE = [401, 402, 403, 429];
+
+// Pick the first plain llm model for a provider.
+function firstLlmModel(providerId) {
+  const models = getModelsByProviderId(providerId);
+  const llm = models.find((m) => (m.type || "llm") === "llm");
+  return llm?.id || null;
+}
+
+async function drainSSE(response) {
+  if (!response?.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let out = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += decoder.decode(value, { stream: true });
+  }
+  return out;
+}
+
+// Resolve creds+model for a provider, or null when unavailable (caller skips).
+async function prepare(providerId) {
+  const model = firstLlmModel(providerId);
+  if (!model) {
+    console.warn(`[skip] ${providerId}: no llm model`);
+    return null;
+  }
+  const credentials = await getProviderCredentials(providerId, new Set(), model);
+  if (!credentials || credentials.allRateLimited) {
+    console.warn(`[skip] ${providerId}: no usable credential`);
+    return null;
+  }
+  const refreshed = await checkAndRefreshToken(providerId, credentials);
+  return { model, credentials, refreshed };
+}
+
+// Run handleChatCore + drain; returns { raw } or null if cred/quota issue (caller skips).
+async function runChat(providerId, prep, body) {
+  const result = await handleChatCore({
+    body: { model: `${providerId}/${prep.model}`, ...body },
+    modelInfo: { provider: providerId, model: prep.model },
+    credentials: prep.refreshed,
+    connectionId: prep.credentials.connectionId,
+  });
+  if (!result.success) {
+    if (CRED_ISSUE.includes(Number(result.status))) {
+      console.warn(`[skip] ${providerId}: ${result.status} (credential/quota)`);
+      return null;
+    }
+    throw new Error(`${providerId} failed: ${result.status} ${result.error}`);
+  }
+  return { raw: await drainSSE(result.response) };
+}
+
+describe.skipIf(!RUN_REAL)("REAL provider behavior cases", () => {
+  // Case #1: Gemini normal prompt -> finish_reason "stop".
+  it("gemini: finish_reason stop", async () => {
+    const prep = await prepare("gemini");
+    if (!prep) return expect(true).toBe(true);
+    // Generous max_tokens so reasoning models (gemini-3 pro) don't hit "length" first.
+    const out = await runChat("gemini", prep, {
+      stream: true,
+      max_tokens: 2048,
+      messages: [{ role: "user", content: "Reply with the single word: hi" }],
+    });
+    if (!out) return expect(true).toBe(true);
+    expect(/"finish_reason"\s*:\s*"stop"/.test(out.raw), "no stop finish_reason").toBe(true);
+  }, TIMEOUT_MS);
+
+  // Case #4: Kiro tool turn -> tool_calls finish_reason + tool_calls delta.
+  it("kiro: tool turn -> tool_calls", async () => {
+    const prep = await prepare("kiro");
+    if (!prep) return expect(true).toBe(true);
+    const out = await runChat("kiro", prep, {
+      stream: true,
+      max_tokens: 128,
+      tool_choice: "auto",
+      tools: [{
+        type: "function",
+        function: {
+          name: "get_weather",
+          description: "Get the current weather for a city",
+          parameters: {
+            type: "object",
+            properties: { city: { type: "string", description: "City name" } },
+            required: ["city"],
+          },
+        },
+      }],
+      messages: [{ role: "user", content: "What's the weather in Paris? Use the get_weather tool." }],
+    });
+    if (!out) return expect(true).toBe(true);
+    expect(/"finish_reason"\s*:\s*"tool_calls"/.test(out.raw), "no tool_calls finish_reason").toBe(true);
+    expect(/"tool_calls"/.test(out.raw), "no tool_calls delta").toBe(true);
+  }, TIMEOUT_MS);
+
+  // Case #3: Ollama tiny max_tokens + long prompt -> finish_reason "length".
+  it("ollama: max_tokens -> length", async () => {
+    const prep = await prepare("ollama");
+    if (!prep) return expect(true).toBe(true);
+    const out = await runChat("ollama", prep, {
+      stream: true,
+      max_tokens: 4,
+      messages: [{ role: "user", content: "Write a long detailed essay about the history of computing." }],
+    });
+    if (!out) return expect(true).toBe(true);
+    // length is model-dependent; if the model stopped on its own, skip rather than fail.
+    if (!/"finish_reason"\s*:\s*"length"/.test(out.raw)) {
+      console.warn("[skip] ollama: model did not hit length (output shorter than max_tokens)");
+      return expect(true).toBe(true);
+    }
+    expect(/"finish_reason"\s*:\s*"length"/.test(out.raw)).toBe(true);
+  }, TIMEOUT_MS);
+
+  // Case #4/#5: Codex multi-turn -> session stickiness (prompt-cache hit on 2nd turn).
+  it("codex: session stickiness (cached_tokens on 2nd turn)", async () => {
+    const prep = await prepare("codex");
+    if (!prep) return expect(true).toBe(true);
+    const longContext = "The capital of France is Paris. ".repeat(40);
+    const messages = [
+      { role: "user", content: longContext },
+      { role: "assistant", content: "Understood. I have noted that context." },
+      { role: "user", content: "Reply with the single word: ok" },
+    ];
+    const body = { stream: true, max_tokens: 32, messages };
+    const first = await runChat("codex", prep, body);
+    if (!first) return expect(true).toBe(true);
+    const second = await runChat("codex", prep, body);
+    if (!second) return expect(true).toBe(true);
+    // 2nd identical-context turn should hit prompt cache when session is sticky.
+    const m = second.raw.match(/"cached_tokens"\s*:\s*(\d+)/);
+    if (!m) {
+      console.warn("[skip] codex: no cached_tokens in usage (provider may not report)");
+      return expect(true).toBe(true);
+    }
+    expect(Number(m[1]), "cached_tokens not > 0 on 2nd turn").toBeGreaterThan(0);
+  }, TIMEOUT_MS);
+
+  // Case #1/#2: Antigravity normal prompt -> valid SSE response.
+  it("antigravity: responds OK", async () => {
+    const prep = await prepare("antigravity");
+    if (!prep) return expect(true).toBe(true);
+    const out = await runChat("antigravity", prep, {
+      stream: true,
+      max_tokens: 32,
+      messages: [{ role: "user", content: "Reply with the single word: hi" }],
+    });
+    if (!out) return expect(true).toBe(true);
+    expect(out.raw.length, "empty response").toBeGreaterThan(0);
+    expect(/data:|finish_reason|"delta"|"content"|event:/.test(out.raw), "not SSE").toBe(true);
+  }, TIMEOUT_MS);
+});
diff --git a/tests/translator/real/smoke-providers.real.test.js b/tests/translator/real/smoke-providers.real.test.js
new file mode 100644
index 0000000..576f8fd
--- /dev/null
+++ b/tests/translator/real/smoke-providers.real.test.js
@@ -0,0 +1,123 @@
+// REAL integration smoke test: sends a tiny prompt to EVERY provider that has an
+// active credential in the local DB, through the full production path (handleChatCore).
+// Gated by RUN_REAL=1 so the default `vitest run` never touches the network.
+//
+//   RUN_REAL=1 npx vitest run "tests/translator/real/"
+//
+// Each provider becomes its own test; providers without an llm model or without an
+// active credential are skipped automatically.
+import { describe, it, expect, beforeAll } from "vitest";
+import { getProviderConnections } from "../../../src/lib/localDb.js";
+import { getProviderCredentials } from "../../../src/sse/services/auth.js";
+import { checkAndRefreshToken } from "../../../src/sse/services/tokenRefresh.js";
+import { handleChatCore } from "../../../open-sse/handlers/chatCore.js";
+import { getModelsByProviderId } from "../../../open-sse/config/providerModels.js";
+
+const RUN_REAL = process.env.RUN_REAL === "1";
+const MAX_TOKENS = 32;
+const TIMEOUT_MS = 90000;
+// Optional comma-separated filter: REAL_PROVIDERS=kiro,codex,antigravity
+const PROVIDER_FILTER = (process.env.REAL_PROVIDERS || "")
+  .split(",").map((s) => s.trim()).filter(Boolean);
+
+// Pick the first plain llm model for a provider (skip image/tts/embedding/etc).
+function firstLlmModel(providerId) {
+  const models = getModelsByProviderId(providerId);
+  const llm = models.find((m) => (m.type || "llm") === "llm");
+  return llm?.id || null;
+}
+
+// Drain the full Web Response SSE body into raw text.
+async function drainSSE(response) {
+  if (!response?.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let out = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += decoder.decode(value, { stream: true });
+  }
+  return out;
+}
+
+let providerIds = [];
+
+beforeAll(async () => {
+  if (!RUN_REAL) return;
+  providerIds = targetProviders();
+});
+
+describe.skipIf(!RUN_REAL).concurrent("REAL provider smoke", () => {
+  it("has active providers in DB", () => {
+    expect(providerIds.length).toBeGreaterThan(0);
+  });
+
+  // One concurrent test per provider; resolved lazily inside the test.
+  for (const providerId of (RUN_REAL ? targetProviders() : [])) {
+    it.concurrent(
+      `${providerId}: responds to a short prompt`,
+      async () => {
+        const model = firstLlmModel(providerId);
+        if (!model) return expect(true).toBe(true); // no llm model → skip silently
+
+        const credentials = await getProviderCredentials(providerId, new Set(), model);
+        if (!credentials || credentials.allRateLimited) {
+          console.warn(`[skip] ${providerId}: no usable credential`);
+          return expect(true).toBe(true);
+        }
+
+        const refreshed = await checkAndRefreshToken(providerId, credentials);
+        const result = await handleChatCore({
+          body: {
+            model: `${providerId}/${model}`,
+            stream: true,
+            max_tokens: MAX_TOKENS,
+            messages: [{ role: "user", content: "Reply with the single word: hi" }],
+          },
+          modelInfo: { provider: providerId, model },
+          credentials: refreshed,
+          connectionId: credentials.connectionId,
+        });
+
+        if (!result.success) {
+          // Account/quota/auth problems are credential issues, not translation bugs → skip.
+          const credIssue = [401, 402, 403, 429].includes(Number(result.status));
+          if (credIssue) {
+            console.warn(`[skip] ${providerId}: ${result.status} (credential/quota)`);
+            return expect(true).toBe(true);
+          }
+          throw new Error(`${providerId} failed: ${result.status} ${result.error}`);
+        }
+
+        const raw = await drainSSE(result.response);
+        // Minimal sanity: got SSE data and a terminal signal or content.
+        expect(raw.length, `${providerId}: empty response`).toBeGreaterThan(0);
+        expect(/data:|finish_reason|"delta"|"content"|event:/.test(raw), `${providerId}: not SSE`).toBe(true);
+      },
+      TIMEOUT_MS
+    );
+  }
+});
+
+// Read the DB file directly (sync) at module-eval time so vitest can generate one
+// test per provider before beforeAll runs. Applies REAL_PROVIDERS filter.
+// Tolerates any failure (returns []).
+function targetProviders() {
+  try {
+    const Database = require("better-sqlite3");
+    const os = require("os");
+    const path = require("path");
+    const dbPath = process.env.DATA_DIR
+      ? path.join(process.env.DATA_DIR, "db", "data.sqlite")
+      : path.join(os.homedir(), ".9router", "db", "data.sqlite");
+    const db = new Database(dbPath, { readonly: true });
+    const rows = db.prepare("SELECT DISTINCT provider FROM providerConnections WHERE isActive = 1").all();
+    db.close();
+    let list = rows.map((r) => r.provider).sort();
+    if (PROVIDER_FILTER.length) list = list.filter((p) => PROVIDER_FILTER.includes(p));
+    return list;
+  } catch {
+    return [];
+  }
+}
diff --git a/tests/translator/real/thinking.real.test.js b/tests/translator/real/thinking.real.test.js
new file mode 100644
index 0000000..32b0294
--- /dev/null
+++ b/tests/translator/real/thinking.real.test.js
@@ -0,0 +1,122 @@
+// REAL integration test for thinking normalization: sends a reasoning prompt with
+// reasoning_effort to every thinking-capable provider that has an active credential,
+// then asserts the upstream accepted it (no 400) and emitted reasoning output.
+// Gated by RUN_REAL=1 so the default `vitest run` never touches the network.
+//
+//   RUN_REAL=1 npx vitest run -c tests/vitest.config.js "tests/translator/real/thinking"
+//   RUN_REAL=1 REAL_PROVIDERS=claude,glm,deepseek npx vitest run -c tests/vitest.config.js "tests/translator/real/thinking"
+//
+import { describe, it, expect } from "vitest";
+import { getProviderCredentials } from "../../../src/sse/services/auth.js";
+import { checkAndRefreshToken } from "../../../src/sse/services/tokenRefresh.js";
+import { handleChatCore } from "../../../open-sse/handlers/chatCore.js";
+import { getModelsByProviderId } from "../../../open-sse/config/providerModels.js";
+import { getCapabilitiesForModel } from "../../../open-sse/providers/capabilities.js";
+
+const RUN_REAL = process.env.RUN_REAL === "1";
+const MAX_TOKENS = 512;
+const TIMEOUT_MS = 120000;
+const EFFORT = process.env.THINK_EFFORT || "high";
+const PROVIDER_FILTER = (process.env.REAL_PROVIDERS || "")
+  .split(",").map((s) => s.trim()).filter(Boolean);
+
+// First plain llm model that the capability registry marks as reasoning-capable.
+function firstReasoningModel(providerId) {
+  const models = getModelsByProviderId(providerId);
+  for (const m of models) {
+    if ((m.type || "llm") !== "llm") continue;
+    if (/embedding|image|tts|whisper|rerank|vision-model/i.test(m.id)) continue;
+    if (getCapabilitiesForModel(providerId, m.id).reasoning) return m.id;
+  }
+  return null;
+}
+
+async function drainSSE(response) {
+  if (!response?.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let out = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += decoder.decode(value, { stream: true });
+  }
+  return out;
+}
+
+describe.skipIf(!RUN_REAL).concurrent("REAL thinking normalization", () => {
+  it("has active providers in DB", () => {
+    expect(targetProviders().length).toBeGreaterThan(0);
+  });
+
+  for (const providerId of (RUN_REAL ? targetProviders() : [])) {
+    it.concurrent(
+      `${providerId}: accepts reasoning_effort=${EFFORT} and reasons`,
+      async () => {
+        const model = firstReasoningModel(providerId);
+        if (!model) {
+          console.warn(`[skip] ${providerId}: no reasoning-capable model`);
+          return expect(true).toBe(true);
+        }
+
+        const credentials = await getProviderCredentials(providerId, new Set(), model);
+        if (!credentials || credentials.allRateLimited) {
+          console.warn(`[skip] ${providerId}: no usable credential`);
+          return expect(true).toBe(true);
+        }
+
+        const refreshed = await checkAndRefreshToken(providerId, credentials);
+        const result = await handleChatCore({
+          body: {
+            model: `${providerId}/${model}`,
+            stream: true,
+            max_tokens: MAX_TOKENS,
+            reasoning_effort: EFFORT,
+            messages: [{ role: "user", content: "Think step by step, then answer: what is 17 * 23?" }],
+          },
+          modelInfo: { provider: providerId, model },
+          credentials: refreshed,
+          connectionId: credentials.connectionId,
+        });
+
+        if (!result.success) {
+          // 400 = our thinking payload was rejected → real bug. Other codes = credential/quota.
+          const credIssue = [401, 402, 403, 429].includes(Number(result.status));
+          if (credIssue) {
+            console.warn(`[skip] ${providerId}: ${result.status} (credential/quota)`);
+            return expect(true).toBe(true);
+          }
+          console.error(`[REJECT] ${providerId}/${model} ${result.status}:`, JSON.stringify(result.error)?.slice(0, 600));
+          throw new Error(`${providerId}/${model} thinking REJECTED: ${result.status}`);
+        }
+
+        const raw = await drainSSE(result.response);
+        expect(raw.length, `${providerId}: empty response`).toBeGreaterThan(0);
+        const hasReasoning = /reasoning_content|"thinking"|reasoning_details|<think/.test(raw);
+        // Log so the operator can eyeball which providers actually streamed reasoning.
+        console.log(`[ok] ${providerId}/${model} reasoning=${hasReasoning}`);
+        expect(/data:|"delta"|"content"|finish_reason/.test(raw), `${providerId}: not SSE`).toBe(true);
+      },
+      TIMEOUT_MS
+    );
+  }
+});
+
+function targetProviders() {
+  try {
+    const Database = require("better-sqlite3");
+    const os = require("os");
+    const path = require("path");
+    const dbPath = process.env.DATA_DIR
+      ? path.join(process.env.DATA_DIR, "db", "data.sqlite")
+      : path.join(os.homedir(), ".9router", "db", "data.sqlite");
+    const db = new Database(dbPath, { readonly: true });
+    const rows = db.prepare("SELECT DISTINCT provider FROM providerConnections WHERE isActive = 1").all();
+    db.close();
+    let list = rows.map((r) => r.provider).sort();
+    if (PROVIDER_FILTER.length) list = list.filter((p) => PROVIDER_FILTER.includes(p));
+    return list;
+  } catch {
+    return [];
+  }
+}
diff --git a/tests/translator/real/vision-capability-survey.real.test.js b/tests/translator/real/vision-capability-survey.real.test.js
new file mode 100644
index 0000000..c1bf0f8
--- /dev/null
+++ b/tests/translator/real/vision-capability-survey.real.test.js
@@ -0,0 +1,183 @@
+// REAL survey: send an image to EVERY chat LLM (all providers with active creds) and
+// record how each model behaves vs its declared vision capability.
+// Purpose: discover where non-vision models 400 on image input (need auto-strip) and
+// where capability data is wrong. This is a SURVEY: it logs a table, it does not fail
+// on capability mismatches (only real harness errors throw).
+//
+//   RUN_REAL=1 npx vitest run --config tests/vitest.config.js tests/translator/real/vision-capability-survey.real.test.js
+//   RUN_REAL=1 REAL_PROVIDERS=mistral,nvidia npx vitest run ... (optional filter)
+import { describe, it, expect, afterAll } from "vitest";
+import { getProviderCredentials } from "../../../src/sse/services/auth.js";
+import { checkAndRefreshToken } from "../../../src/sse/services/tokenRefresh.js";
+import { handleChatCore } from "../../../open-sse/handlers/chatCore.js";
+import { getModelsByProviderId } from "../../../open-sse/config/providerModels.js";
+import { getCapabilitiesForModel } from "../../../open-sse/providers/capabilities.js";
+
+const RUN_REAL = process.env.RUN_REAL === "1";
+const TIMEOUT_MS = 90000;
+const CRED_ISSUE = [401, 402, 403, 429];
+const NON_CHAT_KINDS = new Set(["embedding", "image", "imageToText", "tts", "stt", "video", "music", "webSearch"]);
+
+const PROVIDER_FILTER = (process.env.REAL_PROVIDERS || "")
+  .split(",").map((s) => s.trim()).filter(Boolean);
+
+// Valid 16x16 red PNG (1x1 is rejected as malformed by some strict providers).
+const PNG_DATA_URI = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAFklEQVR4nGO4I2JDEmIY1TCqYfhqAAAeBCwQ8YdREQAAAABJRU5ErkJggg==";
+// Tiny silent WAV (44-byte header, no samples) — enough to probe audioInput acceptance.
+const WAV_B64 = "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=";
+// Stable public image URL (probe remote-URL handling vs base64).
+const IMAGE_REMOTE_URL = "https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png";
+// Tiny valid PDF (probe file/document handling).
+const PDF_B64 = "JVBERi0xLjEKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iagozIDAgb2JqPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9NZWRpYUJveFswIDAgMjAwIDIwMF0+PmVuZG9iagp4cmVmCjAgNAowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1MiAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCnRyYWlsZXI8PC9TaXplIDQvUm9vdCAxIDAgUj4+CnN0YXJ0eHJlZgoxNjYKJSVFT0Y=";
+const PDF_DATA_URI = `data:application/pdf;base64,${PDF_B64}`;
+
+// Capability probes: each sends one modality-specific content block. cap = capability flag tested.
+const CAPABILITY_PROBES = {
+  vision: {
+    cap: "vision",
+    content: [
+      { type: "text", text: "What is in this image? One word." },
+      { type: "image_url", image_url: { url: PNG_DATA_URI } },
+    ],
+  },
+  audio: {
+    cap: "audioInput",
+    content: [
+      { type: "text", text: "Transcribe this audio. One word." },
+      { type: "input_audio", input_audio: { data: WAV_B64, format: "wav" } },
+    ],
+  },
+  imageUrl: {
+    cap: "vision",
+    content: [
+      { type: "text", text: "What is in this image? One word." },
+      { type: "image_url", image_url: { url: IMAGE_REMOTE_URL } },
+    ],
+  },
+  file: {
+    cap: "pdf",
+    content: [
+      { type: "text", text: "Summarize this document. One word." },
+      { type: "file", file: { filename: "doc.pdf", file_data: PDF_DATA_URI } },
+    ],
+  },
+};
+// Set PROBES=vision,audio (default vision only to limit live quota).
+const ACTIVE_PROBES = (process.env.PROBES || "vision").split(",").map((s) => s.trim()).filter(Boolean);
+
+// Status/message patterns that indicate account/credential issues (not a vision-capability signal).
+const CRED_MSG_RE = /subscription|unauthorized|invalid api key|invalid access token|insufficient|credits|payment|spending|organization policy|disallowed|quota|exhausted|not supported when using|not available for integrator|requires a subscription|model.*not found|does not exist|not yet known|requires a role/i;
+
+// Collected rows for the end-of-run summary table.
+const results = [];
+
+async function drainSSE(response) {
+  if (!response?.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let out = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += decoder.decode(value, { stream: true });
+  }
+  return out;
+}
+
+function chatModels(providerId) {
+  return getModelsByProviderId(providerId).filter((m) => !NON_CHAT_KINDS.has(m.kind || m.type || "llm"));
+}
+
+function targetProviders() {
+  try {
+    const Database = require("better-sqlite3");
+    const os = require("os");
+    const path = require("path");
+    const dbPath = process.env.DATA_DIR
+      ? path.join(process.env.DATA_DIR, "db", "data.sqlite")
+      : path.join(os.homedir(), ".9router", "db", "data.sqlite");
+    const db = new Database(dbPath, { readonly: true });
+    const rows = db.prepare("SELECT DISTINCT provider FROM providerConnections WHERE isActive = 1").all();
+    db.close();
+    let list = rows.map((r) => r.provider).sort();
+    if (PROVIDER_FILTER.length) list = list.filter((p) => PROVIDER_FILTER.includes(p));
+    return list;
+  } catch {
+    return [];
+  }
+}
+
+describe.skipIf(!RUN_REAL)("REAL vision capability survey", () => {
+  const providers = RUN_REAL ? targetProviders() : [];
+
+  it("has active providers in DB", () => {
+    expect(providers.length).toBeGreaterThan(0);
+  });
+
+  for (const providerId of providers) {
+    for (const m of (RUN_REAL ? chatModels(providerId) : [])) {
+      const model = m.id;
+      for (const probeName of ACTIVE_PROBES) {
+      const probe = CAPABILITY_PROBES[probeName];
+      it.concurrent(`${probeName} | ${providerId} / ${model}`, async () => {
+        const caps = getCapabilitiesForModel(providerId, model);
+        const capOn = !!caps[probe.cap];
+        const credentials = await getProviderCredentials(providerId, new Set(), model);
+        if (!credentials || credentials.allRateLimited) {
+          results.push({ probe: probeName, providerId, model, cap: capOn, status: "no-cred", verdict: "skip" });
+          return expect(true).toBe(true);
+        }
+        const refreshed = await checkAndRefreshToken(providerId, credentials);
+
+        const result = await handleChatCore({
+          body: {
+            model: `${providerId}/${model}`,
+            stream: true,
+            max_tokens: 64,
+            messages: [{ role: "user", content: probe.content }],
+          },
+          modelInfo: { provider: providerId, model },
+          credentials: refreshed,
+          connectionId: credentials.connectionId,
+        });
+
+        const status = Number(result.status) || (result.success ? 200 : 0);
+        const errMsg = result.success ? "" : String(result.error || "");
+        const credIssue = CRED_ISSUE.includes(status) || CRED_MSG_RE.test(errMsg);
+        const ok = result.success;
+
+        // Classify outcome vs declared capability (cred/account noise filtered out).
+        let verdict;
+        if (credIssue) verdict = "skip-cred";
+        else if (ok && capOn) verdict = `ok-${probeName}`;
+        else if (ok && !capOn) verdict = `ok-no${probeName}-tolerated`; // provider silently ignored modality
+        else if (!ok && !capOn) verdict = `FAIL-no${probeName}-needs-strip`; // target problem
+        else verdict = `FAIL-${probeName}-capdata-wrong`; // declared cap but rejected
+
+        if (ok) await drainSSE(result.response).catch(() => {});
+        results.push({ probe: probeName, providerId, model, cap: capOn, status, verdict, error: ok ? "" : String(result.error || "").slice(0, 80) });
+        // Survey never fails on capability outcome.
+        return expect(true).toBe(true);
+      }, TIMEOUT_MS);
+      }
+    }
+  }
+
+  afterAll(() => {
+    if (!results.length) return;
+    // FAIL groups first (most actionable), then ok/skip; alphabetical within rank.
+    const rank = (v) => (v.startsWith("FAIL") ? 0 : v.startsWith("ok") ? 1 : 2);
+    const groups = [...new Set(results.map((r) => r.verdict))]
+      .sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+    console.log("\n================ CAPABILITY SURVEY ================");
+    for (const g of groups) {
+      const rows = results.filter((r) => r.verdict === g);
+      if (!rows.length) continue;
+      console.log(`\n### ${g} (${rows.length})`);
+      for (const r of rows) {
+        console.log(`  [${r.status}] ${r.probe} ${r.providerId}/${r.model} cap=${r.cap}${r.error ? ` :: ${r.error}` : ""}`);
+      }
+    }
+    console.log("\n================ END SURVEY ================\n");
+  });
+});
diff --git a/tests/translator/registerAll.js b/tests/translator/registerAll.js
new file mode 100644
index 0000000..85b21b7
--- /dev/null
+++ b/tests/translator/registerAll.js
@@ -0,0 +1,24 @@
+// Eagerly import every translator so register() side-effects run under ESM/vitest.
+// translator/index.js uses require() (bundler-only) which no-ops in vitest → import directly.
+import "../../open-sse/translator/request/claude-to-openai.js";
+import "../../open-sse/translator/request/openai-to-claude.js";
+import "../../open-sse/translator/request/gemini-to-openai.js";
+import "../../open-sse/translator/request/openai-to-gemini.js";
+import "../../open-sse/translator/request/openai-to-vertex.js";
+import "../../open-sse/translator/request/antigravity-to-openai.js";
+import "../../open-sse/translator/request/openai-responses.js";
+import "../../open-sse/translator/request/openai-to-kiro.js";
+import "../../open-sse/translator/request/openai-to-cursor.js";
+import "../../open-sse/translator/request/openai-to-ollama.js";
+import "../../open-sse/translator/request/openai-to-commandcode.js";
+import "../../open-sse/translator/request/claude-to-kiro.js";
+import "../../open-sse/translator/response/claude-to-openai.js";
+import "../../open-sse/translator/response/openai-to-claude.js";
+import "../../open-sse/translator/response/gemini-to-openai.js";
+import "../../open-sse/translator/response/openai-to-antigravity.js";
+import "../../open-sse/translator/response/openai-responses.js";
+import "../../open-sse/translator/response/kiro-to-openai.js";
+import "../../open-sse/translator/response/cursor-to-openai.js";
+import "../../open-sse/translator/response/ollama-to-openai.js";
+import "../../open-sse/translator/response/commandcode-to-openai.js";
+import "../../open-sse/translator/response/kiro-to-claude.js";
diff --git a/tests/translator/thinking-unified.test.js b/tests/translator/thinking-unified.test.js
new file mode 100644
index 0000000..3132ce8
--- /dev/null
+++ b/tests/translator/thinking-unified.test.js
@@ -0,0 +1,171 @@
+// Unit tests for unified thinking normalization (thinkingUnified.js).
+// Covers extract, suffix parse, and per-provider apply per MATRIX (.docs/thinking/plan.md).
+import { describe, it, expect } from "vitest";
+import {
+  parseSuffix,
+  extractThinking,
+  applyThinking,
+} from "../../open-sse/translator/concerns/thinkingUnified.js";
+import { extractReasoningText } from "../../open-sse/translator/concerns/reasoning.js";
+
+const apply = (targetFormat, model, body, provider) => {
+  const b = JSON.parse(JSON.stringify(body));
+  applyThinking(targetFormat, model, b, provider);
+  return b;
+};
+
+describe("parseSuffix", () => {
+  it("parses level suffix", () => {
+    expect(parseSuffix("gpt-5(high)")).toEqual({ cleanModel: "gpt-5", override: { mode: "level", level: "high" } });
+  });
+  it("parses numeric budget suffix", () => {
+    expect(parseSuffix("model(8192)")).toEqual({ cleanModel: "model", override: { mode: "budget", budget: 8192 } });
+  });
+  it("parses auto / none", () => {
+    expect(parseSuffix("m(auto)").override).toEqual({ mode: "auto" });
+    expect(parseSuffix("m(none)").override).toEqual({ mode: "none" });
+  });
+  it("no suffix → passthrough", () => {
+    expect(parseSuffix("claude-opus-4.7")).toEqual({ cleanModel: "claude-opus-4.7", override: null });
+  });
+});
+
+describe("extractThinking", () => {
+  it("claude enabled+budget", () => {
+    expect(extractThinking({ thinking: { type: "enabled", budget_tokens: 4096 } })).toEqual({ mode: "budget", budget: 4096 });
+  });
+  it("claude disabled", () => {
+    expect(extractThinking({ thinking: { type: "disabled" } })).toEqual({ mode: "none" });
+  });
+  it("openai reasoning_effort", () => {
+    expect(extractThinking({ reasoning_effort: "high" })).toEqual({ mode: "level", level: "high" });
+  });
+  it("responses reasoning.effort none", () => {
+    expect(extractThinking({ reasoning: { effort: "none" } })).toEqual({ mode: "none" });
+  });
+  it("gemini thinkingBudget 0 → none", () => {
+    expect(extractThinking({ thinkingConfig: { thinkingBudget: 0 } })).toEqual({ mode: "none" });
+  });
+  it("qwen enable_thinking false", () => {
+    expect(extractThinking({ enable_thinking: false })).toEqual({ mode: "none" });
+  });
+  it("no intent → null", () => {
+    expect(extractThinking({ messages: [] })).toBeNull();
+  });
+});
+
+describe("applyThinking per provider format", () => {
+  it("claude 4.6+ → adaptive output_config (no budget_tokens)", () => {
+    const out = apply("claude", "claude-opus-4.7", { reasoning_effort: "high" }, "claude");
+    expect(out.output_config).toEqual({ effort: "high" });
+    expect(out.thinking).toBeUndefined();
+  });
+  it("claude haiku → enabled+budget", () => {
+    const out = apply("claude", "claude-haiku-4.5", { reasoning_effort: "high" }, "claude");
+    expect(out.thinking).toEqual({ type: "enabled", budget_tokens: 24576 });
+  });
+  it("gemini-3 → thinkingLevel", () => {
+    const out = apply("gemini", "gemini-3-pro", { reasoning_effort: "medium" }, "gemini");
+    expect(out.generationConfig.thinkingConfig.thinkingLevel).toBe("medium");
+  });
+  it("gemini-3 clamps unsupported max/xhigh thinking levels to high", () => {
+    const outMax = apply("gemini", "gemini-3-pro", { reasoning_effort: "max" }, "gemini");
+    const outXhigh = apply("gemini", "gemini-3-pro", { reasoning_effort: "xhigh" }, "gemini");
+    expect(outMax.generationConfig.thinkingConfig.thinkingLevel).toBe("high");
+    expect(outXhigh.generationConfig.thinkingConfig.thinkingLevel).toBe("high");
+  });
+  it("gemini-3 maps auto thinking level to high instead of sending unsupported auto", () => {
+    const out = apply("gemini", "gemini-3-pro", { reasoning_effort: "auto" }, "gemini");
+    expect(out.generationConfig.thinkingConfig.thinkingLevel).toBe("high");
+  });
+  it("gemini-3 high thinking raises too-small maxOutputTokens", () => {
+    const out = apply("gemini-cli", "gemini-3.1-pro-preview", {
+      request: { generationConfig: { maxOutputTokens: 128 } },
+      reasoning_effort: "high",
+    }, "gemini-cli");
+    expect(out.request.generationConfig.thinkingConfig).toEqual({ thinkingLevel: "high", includeThoughts: true });
+    expect(out.request.generationConfig.maxOutputTokens).toBe(65535);
+  });
+  it("gemini-2.5 → thinkingBudget", () => {
+    const out = apply("gemini", "gemini-2.5-flash", { reasoning_effort: "high" }, "gemini");
+    expect(out.generationConfig.thinkingConfig.thinkingBudget).toBe(24576);
+    expect(out.generationConfig.thinkingConfig.thinkingLevel).toBeUndefined();
+  });
+  it("gemini-2.5 budget thinking keeps enough room for answer tokens", () => {
+    const out = apply("gemini-cli", "gemini-2.5-pro", {
+      request: { generationConfig: { maxOutputTokens: 1024 } },
+      reasoning_effort: "high",
+    }, "gemini-cli");
+    expect(out.request.generationConfig.thinkingConfig).toEqual({ thinkingBudget: 24576, includeThoughts: true });
+    expect(out.request.generationConfig.maxOutputTokens).toBe(32768);
+  });
+  it("GLM off → enable_thinking:false (not thinking.disabled)", () => {
+    const out = apply("openai", "glm-4.6", { reasoning_effort: "none" }, "glm");
+    expect(out.enable_thinking).toBe(false);
+    expect(out.thinking).toBeUndefined();
+  });
+  it("Qwen on → enable_thinking + thinking_budget", () => {
+    const out = apply("openai", "qwen3-max", { reasoning_effort: "medium" }, "qwen");
+    expect(out.enable_thinking).toBe(true);
+    expect(out.thinking_budget).toBe(8192);
+  });
+  it("QwQ cannot disable → clamp minimal", () => {
+    const out = apply("openai", "qwq-32b", { reasoning_effort: "none" }, "qwen");
+    expect(out.enable_thinking).toBe(true);
+  });
+  it("DeepSeek → enabled + reasoning_effort high (low→high)", () => {
+    const out = apply("openai", "deepseek-v4-pro", { reasoning_effort: "low" }, "deepseek");
+    expect(out.thinking).toEqual({ type: "enabled" });
+    expect(out.reasoning_effort).toBe("high");
+  });
+  it("Kimi on → reasoning_effort", () => {
+    const out = apply("openai", "kimi-k2.6", { reasoning_effort: "high" }, "kimi");
+    expect(out.reasoning_effort).toBe("high");
+  });
+  it("Kimi auto → supported reasoning_effort", () => {
+    const out = apply("openai", "kimi-k2.7", { reasoning_effort: "auto" }, "kimchi");
+    expect(out.reasoning_effort).toBe("high");
+  });
+  it("Kimi unsupported OpenAI levels → supported reasoning_effort", () => {
+    const minimal = apply("openai", "kimi-k2.7", { reasoning_effort: "minimal" }, "kimchi");
+    const xhigh = apply("openai", "kimi-k2.7", { reasoning_effort: "xhigh" }, "kimchi");
+    expect(minimal.reasoning_effort).toBe("low");
+    expect(xhigh.reasoning_effort).toBe("max");
+  });
+  it("MiniMax M3 → adaptive", () => {
+    const out = apply("claude", "MiniMax-M3", { reasoning_effort: "high" }, "minimax");
+    expect(out.thinking).toEqual({ type: "adaptive" });
+  });
+  it("non-reasoning model → strips thinking", () => {
+    const out = apply("openai", "gpt-4o", { reasoning_effort: "high" }, "openai");
+    expect(out.reasoning_effort).toBeUndefined();
+  });
+  it("aggregator (siliconflow) GLM model → forced openai reasoning_effort", () => {
+    const out = apply("openai", "zai-org/GLM-5", { reasoning_effort: "high" }, "siliconflow");
+    expect(out.reasoning_effort).toBe("high");
+    expect(out.enable_thinking).toBeUndefined();
+  });
+  it("suffix overrides body", () => {
+    const out = apply("openai", "gpt-5(low)", { reasoning_effort: "high" }, "openai");
+    expect(out.reasoning_effort).toBe("low");
+  });
+  it("openai keeps xhigh for reasoning models", () => {
+    const out = apply("openai", "gpt-5.3-codex", { reasoning_effort: "xhigh" }, "codex");
+    expect(out.reasoning_effort).toBe("xhigh");
+  });
+});
+
+describe("extractReasoningText (response shapes)", () => {
+  it("reasoning_content (GLM/Qwen/DeepSeek)", () => {
+    expect(extractReasoningText({ reasoning_content: "abc" })).toBe("abc");
+  });
+  it("reasoning fallback", () => {
+    expect(extractReasoningText({ reasoning: "xyz" })).toBe("xyz");
+  });
+  it("reasoning_details[] (MiniMax split)", () => {
+    expect(extractReasoningText({ reasoning_details: [{ text: "a" }, { content: "b" }, "c"] })).toBe("abc");
+  });
+  it("no reasoning → empty", () => {
+    expect(extractReasoningText({ content: "hello" })).toBe("");
+  });
+});
diff --git a/tests/unit/alicode-cache-control-2069.test.js b/tests/unit/alicode-cache-control-2069.test.js
new file mode 100644
index 0000000..53d15e7
--- /dev/null
+++ b/tests/unit/alicode-cache-control-2069.test.js
@@ -0,0 +1,66 @@
+// #2069 — cache_control markers stripped for alicode/alicode-intl (DashScope) providers.
+// DashScope supports explicit cache_control: { type: "ephemeral" } in content blocks,
+// but the default filterToOpenAIFormat strips them. preserveCacheControl quirk opts-in.
+import { describe, it, expect } from "vitest";
+import { filterToOpenAIFormat } from "../../open-sse/translator/formats/openai.js";
+
+const msgWithCache = [
+  {
+    role: "user",
+    content: [
+      { type: "text", text: "large context", cache_control: { type: "ephemeral" } },
+    ],
+  },
+  {
+    role: "assistant",
+    content: [
+      { type: "text", text: "reply", cache_control: { type: "ephemeral" } },
+    ],
+  },
+];
+
+describe("filterToOpenAIFormat cache_control handling (#2069)", () => {
+  it("strips cache_control by default (all standard OpenAI providers)", () => {
+    const body = { messages: JSON.parse(JSON.stringify(msgWithCache)) };
+    filterToOpenAIFormat(body);
+    for (const msg of body.messages) {
+      for (const block of msg.content) {
+        expect(block.cache_control).toBeUndefined();
+      }
+    }
+  });
+
+  it("preserves cache_control when preserveCacheControl option is true (alicode/DashScope)", () => {
+    const body = { messages: JSON.parse(JSON.stringify(msgWithCache)) };
+    filterToOpenAIFormat(body, { preserveCacheControl: true });
+    for (const msg of body.messages) {
+      for (const block of msg.content) {
+        expect(block.cache_control).toEqual({ type: "ephemeral" });
+      }
+    }
+  });
+
+  it("always strips signature regardless of preserveCacheControl", () => {
+    const body = {
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: "hi", signature: "sig123", cache_control: { type: "ephemeral" } },
+          ],
+        },
+      ],
+    };
+    filterToOpenAIFormat(body, { preserveCacheControl: true });
+    expect(body.messages[0].content[0].signature).toBeUndefined();
+    expect(body.messages[0].content[0].cache_control).toEqual({ type: "ephemeral" });
+  });
+
+  it("does not add cache_control when block had none (preserveCacheControl: true)", () => {
+    const body = {
+      messages: [{ role: "user", content: [{ type: "text", text: "no cache" }] }],
+    };
+    filterToOpenAIFormat(body, { preserveCacheControl: true });
+    expect(body.messages[0].content[0].cache_control).toBeUndefined();
+  });
+});
diff --git a/tests/unit/antigravity-cache.test.js b/tests/unit/antigravity-cache.test.js
new file mode 100644
index 0000000..e81cf40
--- /dev/null
+++ b/tests/unit/antigravity-cache.test.js
@@ -0,0 +1,216 @@
+/**
+ * Integration test: Antigravity (AG) prompt caching behavior.
+ *
+ * Verifies:
+ *  1. Same sessionId + repeated long prompt → cache hit (cachedContentTokenCount > 0)
+ *  2. Different sessionId (same account) → cache miss
+ *  3. Cross-account cache share? (call A warmup → B same prompt/session, check hit)
+ *
+ * Reads real OAuth refreshToken from ~/.9router/db.json.
+ * Enable with: AG_CACHE_TEST=1 npm test
+ */
+
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { PROVIDERS } from "../../open-sse/config/providers.js";
+import { ANTIGRAVITY_HEADERS, INTERNAL_REQUEST_HEADER } from "../../open-sse/config/appConstants.js";
+
+const ENABLE = process.env.AG_CACHE_TEST === "1";
+const DB_PATH = path.join(os.homedir(), ".9router", "db.json");
+const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const MIN_CACHE_TOKENS = 100; // AG implicit cache threshold observed ~1024-2048
+const LONG_TEXT = ("You are a careful assistant. Always follow these rules. ".repeat(300)).trim();
+
+function loadAgConnections() {
+  if (!fs.existsSync(DB_PATH)) return [];
+  const db = JSON.parse(fs.readFileSync(DB_PATH, "utf8"));
+  return (db.providerConnections || []).filter(
+    c => c.provider === "antigravity" && c.isActive && c.refreshToken && c.projectId
+  );
+}
+
+async function refreshAccessToken(refreshToken) {
+  const { clientId, clientSecret } = PROVIDERS.antigravity;
+  const res = await fetch(OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: clientId,
+      client_secret: clientSecret
+    })
+  });
+  if (!res.ok) throw new Error(`refresh failed ${res.status}`);
+  const json = await res.json();
+  return json.access_token;
+}
+
+async function callAg({ accessToken, projectId, sessionId, longText, userText }) {
+  const baseUrl = PROVIDERS.antigravity.baseUrls[0];
+  const body = {
+    project: projectId,
+    model: "gemini-3-flash",
+    userAgent: "antigravity",
+    requestType: "agent",
+    requestId: `agent-${crypto.randomUUID()}`,
+    request: {
+      systemInstruction: { role: "system", parts: [{ text: longText }] },
+      contents: [{ role: "user", parts: [{ text: userText }] }],
+      sessionId
+    }
+  };
+  const res = await fetch(`${baseUrl}/v1internal:generateContent`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${accessToken}`,
+      "User-Agent": ANTIGRAVITY_HEADERS["User-Agent"],
+      [INTERNAL_REQUEST_HEADER.name]: INTERNAL_REQUEST_HEADER.value,
+      "X-Machine-Session-Id": sessionId
+    },
+    body: JSON.stringify(body)
+  });
+  const json = await res.json();
+  const usage = json?.response?.usageMetadata || json?.usageMetadata || {};
+  return {
+    status: res.status,
+    promptTokens: usage.promptTokenCount || 0,
+    cachedTokens: usage.cachedContentTokenCount || 0,
+    totalTokens: usage.totalTokenCount || 0,
+    raw: json
+  };
+}
+
+describe.skipIf(!ENABLE)("Antigravity cache behavior (real API)", () => {
+  const conns = loadAgConnections();
+
+  it("has at least one active AG connection with refreshToken", () => {
+    expect(conns.length).toBeGreaterThan(0);
+  });
+
+  it("same sessionId → cache hit on repeated call", async () => {
+    const [acc] = conns;
+    const token = await refreshAccessToken(acc.refreshToken);
+    const sessionId = `test-same-${crypto.randomUUID()}`;
+
+    const r1 = await callAg({ accessToken: token, projectId: acc.projectId, sessionId, longText: LONG_TEXT, userText: "Reply with OK only." });
+    const r2 = await callAg({ accessToken: token, projectId: acc.projectId, sessionId, longText: LONG_TEXT, userText: "Reply with OK only." });
+
+    console.log(`[same-session ${acc.email}] r1: prompt=${r1.promptTokens} cached=${r1.cachedTokens} | r2: prompt=${r2.promptTokens} cached=${r2.cachedTokens}`);
+
+    expect(r1.status).toBe(200);
+    expect(r2.status).toBe(200);
+    expect(r2.cachedTokens).toBeGreaterThanOrEqual(MIN_CACHE_TOKENS);
+  }, 60000);
+
+  it("different sessionId (same account) → cache still hits (session-independent)", async () => {
+    const [acc] = conns;
+    const token = await refreshAccessToken(acc.refreshToken);
+
+    const r1 = await callAg({ accessToken: token, projectId: acc.projectId, sessionId: `test-diff-a-${crypto.randomUUID()}`, longText: LONG_TEXT, userText: "Reply with OK only." });
+    const r2 = await callAg({ accessToken: token, projectId: acc.projectId, sessionId: `test-diff-b-${crypto.randomUUID()}`, longText: LONG_TEXT, userText: "Reply with OK only." });
+
+    console.log(`[diff-session ${acc.email}] r1: cached=${r1.cachedTokens} | r2: cached=${r2.cachedTokens}`);
+
+    expect(r1.status).toBe(200);
+    expect(r2.status).toBe(200);
+    // AG cache is content-based, not session-based → both calls hit
+    expect(r2.cachedTokens).toBeGreaterThanOrEqual(MIN_CACHE_TOKENS);
+  }, 60000);
+
+  it.skipIf(conns.length < 2)("cross-account → cache SHARED (content-based global cache)", async () => {
+    const [accA, accB] = conns;
+    const [tokenA, tokenB] = await Promise.all([
+      refreshAccessToken(accA.refreshToken),
+      refreshAccessToken(accB.refreshToken)
+    ]);
+
+    // Account A warmup with its own sessionId
+    const a1 = await callAg({ accessToken: tokenA, projectId: accA.projectId, sessionId: `cross-a-${crypto.randomUUID()}`, longText: LONG_TEXT, userText: "Reply with OK only." });
+    // Account B with DIFFERENT sessionId → if cache shares across accounts, it still hits
+    const b1 = await callAg({ accessToken: tokenB, projectId: accB.projectId, sessionId: `cross-b-${crypto.randomUUID()}`, longText: LONG_TEXT, userText: "Reply with OK only." });
+
+    console.log(`[cross-account] A cached=${a1.cachedTokens} | B cached=${b1.cachedTokens} (${accA.email} → ${accB.email})`);
+
+    expect(a1.status).toBe(200);
+    expect(b1.status).toBe(200);
+    // Cache is shared globally across accounts (content-based)
+    expect(b1.cachedTokens).toBeGreaterThanOrEqual(MIN_CACHE_TOKENS);
+  }, 90000);
+
+  // ─── Codex-style sessionId comparison ────────────────────────────────
+  // Codex derives sessionId from hash(conversation history), keeping it
+  // stable per-conversation. Test whether this strategy improves cache
+  // hit rate vs random sessionId on AG with a fresh unique prompt.
+  it("codex-style sessionId vs random sessionId on unique prompt", async () => {
+    const [acc] = conns;
+    const token = await refreshAccessToken(acc.refreshToken);
+
+    // Build a unique conversation so no pre-existing cache can interfere
+    const uniqueMarker = crypto.randomUUID();
+    const uniqueLong = `MARKER-${uniqueMarker}. ${LONG_TEXT}`;
+    const userText = "Reply with OK only.";
+
+    // Codex-style: sess_${sha256(systemInstruction + userContent).slice(0,32)}
+    const hash = crypto.createHash("sha256").update(uniqueLong + "\n" + userText).digest("hex").slice(0, 32);
+    const codexStyleSessionId = `sess_${hash}`;
+
+    const N = 4;
+    const randomResults = [];
+    const codexResults = [];
+
+    // Strategy A: random sessionId each call
+    for (let i = 0; i < N; i++) {
+      const r = await callAg({
+        accessToken: token, projectId: acc.projectId,
+        sessionId: `rand-${crypto.randomUUID()}`,
+        longText: uniqueLong, userText
+      });
+      randomResults.push(r);
+      console.log(`[random   call ${i + 1}] cached=${r.cachedTokens}`);
+    }
+
+    // Strategy B: codex-style stable sessionId (same hash for every call)
+    for (let i = 0; i < N; i++) {
+      const r = await callAg({
+        accessToken: token, projectId: acc.projectId,
+        sessionId: codexStyleSessionId,
+        longText: uniqueLong, userText
+      });
+      codexResults.push(r);
+      console.log(`[codex    call ${i + 1}] cached=${r.cachedTokens}`);
+    }
+
+    const randomHitRate = randomResults.filter(r => r.cachedTokens >= MIN_CACHE_TOKENS).length / N;
+    const codexHitRate = codexResults.filter(r => r.cachedTokens >= MIN_CACHE_TOKENS).length / N;
+    console.log(`[summary] randomHitRate=${randomHitRate} codexHitRate=${codexHitRate}`);
+
+    randomResults.forEach(r => expect(r.status).toBe(200));
+    codexResults.forEach(r => expect(r.status).toBe(200));
+    // No strict comparison — just report. AG cache is session-independent per prior tests.
+  }, 180000);
+
+  it("unique prompt (never seen) → explore when cache starts hitting", async () => {
+    const [acc] = conns;
+    const token = await refreshAccessToken(acc.refreshToken);
+    // Unique marker to guarantee no one has cached this exact prompt before
+    const uniqueLong = `UNIQUE-${crypto.randomUUID()}. ${LONG_TEXT}`;
+    const sessionId = `unique-${crypto.randomUUID()}`;
+
+    const results = [];
+    for (let i = 0; i < 5; i++) {
+      const r = await callAg({ accessToken: token, projectId: acc.projectId, sessionId, longText: uniqueLong, userText: "Reply with OK only." });
+      results.push(r);
+      console.log(`[unique-prompt call ${i + 1}] prompt=${r.promptTokens} cached=${r.cachedTokens}`);
+    }
+
+    results.forEach(r => expect(r.status).toBe(200));
+    // Log whether any call ever hits cache — no strict assertion (exploratory)
+    const anyHit = results.some(r => r.cachedTokens >= MIN_CACHE_TOKENS);
+    console.log(`[unique-prompt] any-hit=${anyHit}`);
+  }, 90000);
+});
diff --git a/tests/unit/antigravity-mitm.test.js b/tests/unit/antigravity-mitm.test.js
new file mode 100644
index 0000000..defed97
--- /dev/null
+++ b/tests/unit/antigravity-mitm.test.js
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { createRequire } from "module";
+import { MITM_TOOLS } from "../../src/shared/constants/cliTools.js";
+
+// config.js is the CJS MITM bundle module (dependency-isolated for the runtime copy).
+const require = createRequire(import.meta.url);
+const { MODEL_NO_MAP } = require("../../src/mitm/config.js");
+
+// All assertions below are grounded in a live MITM dump capture of Antigravity's
+// streamGenerateContent requests (see AI_JOURNAL): the agent loop sends
+// `gemini-3.5-flash-low`, tab-autocomplete sends `tab_jump_flash_lite_preview` /
+// `tab_flash_lite_preview`.
+describe("Antigravity MITM model handling", () => {
+  const ag = MITM_TOOLS.antigravity;
+
+  it("flags the out-of-box agent/Default model mandatory", () => {
+    expect(ag.defaultModels.find((m) => m.id === "gemini-3.5-flash-low")?.mandatory).toBe(true);
+  });
+
+  it("leaves models not proven auto-sent optional", () => {
+    for (const id of ["gemini-3-flash-agent", "gemini-3.1-pro-low", "claude-sonnet-4-6", "gpt-oss-120b-medium"]) {
+      expect(ag.defaultModels.find((m) => m.id === id)?.mandatory).toBeFalsy();
+    }
+  });
+
+  // Tab-autocomplete is latency-critical inline completion — it must passthrough natively,
+  // never get re-routed onto a chat-model mapping by the broad `flash` pattern.
+  it.each(["tab_jump_flash_lite_preview", "tab_flash_lite_preview"])(
+    "excludes tab-autocomplete model '%s' from re-routing",
+    (id) => {
+      expect((MODEL_NO_MAP.antigravity || []).some((re) => re.test(id))).toBe(true);
+    }
+  );
+
+  it("does not exclude real agent models from re-routing", () => {
+    for (const id of ["gemini-3.5-flash-low", "gemini-3-flash-agent", "claude-sonnet-4-6"]) {
+      expect((MODEL_NO_MAP.antigravity || []).some((re) => re.test(id))).toBe(false);
+    }
+  });
+});
diff --git a/tests/unit/antigravity-oauth-client.test.js b/tests/unit/antigravity-oauth-client.test.js
new file mode 100644
index 0000000..9a2aee9
--- /dev/null
+++ b/tests/unit/antigravity-oauth-client.test.js
@@ -0,0 +1,50 @@
+// Guards the deduped Antigravity OAuth client: same values across all 3 sources after refactor.
+import { describe, it, expect } from "vitest";
+
+const EXPECTED = {
+  clientId: "1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com",
+  clientSecret: "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",
+};
+const GOOGLE = {
+  clientId: "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com",
+  clientSecret: "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",
+};
+
+describe("antigravity oauth client (deduped)", () => {
+  it("shared source holds the canonical credentials", async () => {
+    const { ANTIGRAVITY_OAUTH_CLIENT } = await import("../../open-sse/providers/shared.js");
+    expect(ANTIGRAVITY_OAUTH_CLIENT).toEqual(EXPECTED);
+  });
+
+  it("registry transport keeps clientId/clientSecret", async () => {
+    const ag = (await import("../../open-sse/providers/registry/antigravity.js")).default;
+    expect(ag.transport.clientId).toBe(EXPECTED.clientId);
+    expect(ag.transport.clientSecret).toBe(EXPECTED.clientSecret);
+  });
+
+  it("google client shared by gemini + gemini-cli", async () => {
+    const { GOOGLE_OAUTH_CLIENT } = await import("../../open-sse/providers/shared.js");
+    expect(GOOGLE_OAUTH_CLIENT).toEqual(GOOGLE);
+    const gemini = (await import("../../open-sse/providers/registry/gemini.js")).default;
+    const gc = (await import("../../open-sse/providers/registry/gemini-cli.js")).default;
+    expect(gemini.transport.clientSecret).toBe(GOOGLE.clientSecret);
+    expect(gc.transport.clientSecret).toBe(GOOGLE.clientSecret);
+  });
+
+  // Guard: oauth.js must spread shared clients + derive from registry (PROVIDER_OAUTH).
+  it("src oauth.js imports shared client + keeps full shape", async () => {
+    const { readFileSync } = await import("node:fs");
+    const { fileURLToPath } = await import("node:url");
+    const { dirname, join } = await import("node:path");
+    const here = dirname(fileURLToPath(import.meta.url));
+    const src = readFileSync(join(here, "../../src/lib/oauth/constants/oauth.js"), "utf8");
+    expect(src).toContain('import { ANTIGRAVITY_OAUTH_CLIENT, GOOGLE_OAUTH_CLIENT } from "open-sse/providers/shared.js"');
+    expect(src).toContain("...ANTIGRAVITY_OAUTH_CLIENT");
+    expect(src).toContain("...GOOGLE_OAUTH_CLIENT");
+    // authorizeUrl now lives in registry; oauth.js derives via PROVIDER_OAUTH spread
+    expect(src).toContain('PROVIDER_OAUTH["antigravity"]');
+    expect(src).toContain('PROVIDER_OAUTH["gemini-cli"]');
+    expect(src).not.toContain(EXPECTED.clientSecret); // antigravity secret no longer hardcoded here
+    expect(src).not.toContain(GOOGLE.clientSecret);   // gemini secret no longer hardcoded here
+  });
+});
diff --git a/tests/unit/antigravity-retry-hook.test.js b/tests/unit/antigravity-retry-hook.test.js
new file mode 100644
index 0000000..989dd88
--- /dev/null
+++ b/tests/unit/antigravity-retry-hook.test.js
@@ -0,0 +1,101 @@
+// Guards D3: antigravity 429/503 retry merged into base via computeRetryDelay hook.
+import { describe, it, expect } from "vitest";
+import { AntigravityExecutor } from "../../open-sse/executors/antigravity.js";
+import antigravity from "../../open-sse/providers/registry/antigravity.js";
+
+const MAX = 10000;
+function res(status, headers = {}, body = null) {
+  return {
+    status,
+    headers: { get: (k) => headers[k.toLowerCase()] ?? null },
+    clone: () => ({ text: async () => (body == null ? "" : JSON.stringify(body)) }),
+  };
+}
+
+describe("antigravity computeRetryDelay hook (D3)", () => {
+  const ag = new AntigravityExecutor();
+
+  it("uses Retry-After header (seconds → ms) when within cap", async () => {
+    expect(await ag.computeRetryDelay(res(429, { "retry-after": "5" }), 1)).toBe(5000);
+  });
+
+  it("vetoes (false) when Retry-After exceeds cap", async () => {
+    expect(await ag.computeRetryDelay(res(429, { "retry-after": "60" }), 1)).toBe(false);
+  });
+
+  it("parses retry time from error body when no header", async () => {
+    const r = res(429, {}, { error: { message: "quota will reset after 3s" } });
+    expect(await ag.computeRetryDelay(r, 1)).toBe(3000);
+  });
+
+  it("exponential backoff for 429 when no retry info", async () => {
+    expect(await ag.computeRetryDelay(res(429), 1)).toBe(Math.min(1000 * 2 ** 1, MAX));
+    expect(await ag.computeRetryDelay(res(429), 3)).toBe(Math.min(1000 * 2 ** 3, MAX));
+  });
+
+  it("503 without retry info → transient backoff", async () => {
+    expect(await ag.computeRetryDelay(res(503), 1)).toBe(2000);
+  });
+
+  it("retries Antigravity agent terminated body even when status is not 429", async () => {
+    const r = res(500, {}, { error: { message: "Agent execution terminated due to error" } });
+    expect(await ag.computeRetryDelay(r, 1)).toBe(2000);
+  });
+
+  it("retries high traffic body", async () => {
+    const r = res(500, {}, { error: { message: "Our servers are experiencing high traffic" } });
+    expect(await ag.computeRetryDelay(r, 2)).toBe(4000);
+  });
+
+  it("does not retry non-transient 400 errors", async () => {
+    const r = res(400, {}, { error: { message: "Invalid request" } });
+    expect(await ag.computeRetryDelay(r, 1)).toBe(false);
+  });
+
+  it("deduplicates sanitized tool names", () => {
+    const out = ag.transformRequest("claude-opus-4-6-thinking", {
+      request: {
+        contents: [{ role: "user", parts: [{ text: "hi" }] }],
+        tools: [{ functionDeclarations: [
+          { name: "read/file", parameters: { type: "object", properties: {} } },
+          { name: "read file", parameters: { type: "object", properties: {} } },
+          { name: "read/file", parameters: { type: "object", properties: {} } },
+        ] }],
+      },
+    }, true, { projectId: "project-1", connectionId: "conn-1" });
+
+    expect(out.request.tools[0].functionDeclarations.map(fn => fn.name)).toEqual(["read_file"]);
+  });
+
+  it("registry uses the official IDE cloudcode host and user agent", () => {
+    expect(antigravity.transport.baseUrls).toEqual(["https://cloudcode-pa.googleapis.com"]);
+    expect(antigravity.transport.headers["User-Agent"]).toBe("antigravity/ide/2.1.1 darwin/arm64");
+  });
+
+  it("buildHeaders matches official IDE stream headers", () => {
+    ag._lastSessionId = "sess-123";
+    const h = ag.buildHeaders({ accessToken: "tok" }, true);
+    expect(h["User-Agent"]).toBe("antigravity/ide/2.1.1 darwin/arm64");
+    expect(h["Content-Type"]).toBe("application/json");
+    expect(h["Authorization"]).toBe("Bearer tok");
+    expect(h).not.toHaveProperty("X-Machine-Session-Id");
+    expect(h).not.toHaveProperty("x-request-source");
+    expect(h).not.toHaveProperty("Accept");
+  });
+
+  it("transforms chat requests with official IDE requestId shape and 64000 token cap", () => {
+    const out = ag.transformRequest("claude-opus-4-6-thinking", {
+      request: {
+        contents: [
+          { role: "user", parts: [{ text: "hi" }] },
+          { role: "model", parts: [{ text: "hello" }] },
+        ],
+        generationConfig: { maxOutputTokens: 90000 },
+        sessionId: "-3750763034362895579",
+      },
+    }, true, { projectId: "project-1", connectionId: "conn-1" });
+
+    expect(out.requestId).toMatch(/^agent\/[0-9a-f-]{36}\/\d{13}\/[0-9a-f-]{36}\/\d+$/);
+    expect(out.request.generationConfig.maxOutputTokens).toBe(64000);
+  });
+});
diff --git a/tests/unit/antigravity-usage-headers.test.js b/tests/unit/antigravity-usage-headers.test.js
new file mode 100644
index 0000000..9608755
--- /dev/null
+++ b/tests/unit/antigravity-usage-headers.test.js
@@ -0,0 +1,30 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const proxyAwareFetch = vi.fn(async (url) => ({
+  ok: true,
+  status: 200,
+  json: async () => url.includes(":loadCodeAssist")
+    ? { cloudaicompanionProject: "project-1", currentTier: { name: "Pro" } }
+    : { models: {} },
+  text: async () => "{}",
+}));
+
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch,
+}));
+
+describe("Antigravity usage headers", () => {
+  beforeEach(() => proxyAwareFetch.mockClear());
+
+  it("uses the official IDE user agent and omits router-only source headers", async () => {
+    const { getAntigravityUsage } = await import("../../open-sse/services/usage/google.js");
+
+    await getAntigravityUsage("access-token", {});
+
+    expect(proxyAwareFetch).toHaveBeenCalledTimes(2);
+    for (const [, options] of proxyAwareFetch.mock.calls) {
+      expect(options.headers["User-Agent"]).toBe("antigravity/ide/2.1.1 darwin/arm64");
+      expect(options.headers).not.toHaveProperty("x-request-source");
+    }
+  });
+});
diff --git a/tests/unit/base-executor-retry.test.js b/tests/unit/base-executor-retry.test.js
new file mode 100644
index 0000000..b303d7b
--- /dev/null
+++ b/tests/unit/base-executor-retry.test.js
@@ -0,0 +1,107 @@
+// Locks BaseExecutor.execute retry/fallback behavior (docs 04 GAP #1, docs 11 §7).
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock the network layer so we can script upstream responses.
+const fetchMock = vi.fn();
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch: (...args) => fetchMock(...args),
+}));
+
+const { BaseExecutor } = await import("../../open-sse/executors/base.js");
+
+function res(status) {
+  return { status, headers: { get: () => "" } };
+}
+
+function makeExec(config) {
+  const ex = new BaseExecutor("test", config);
+  // make headers trivial; credentials empty
+  return ex;
+}
+
+const creds = { apiKey: "k" };
+
+beforeEach(() => fetchMock.mockReset());
+
+describe("BaseExecutor.execute — retry by status (config-driven)", () => {
+  it("retries 502 `attempts` times then succeeds", async () => {
+    const ex = makeExec({ baseUrl: "https://x/api", retry: { 502: { attempts: 3, delayMs: 0 } } });
+    fetchMock
+      .mockResolvedValueOnce(res(502))
+      .mockResolvedValueOnce(res(502))
+      .mockResolvedValueOnce(res(200));
+    const out = await ex.execute({ model: "m", body: {}, stream: false, credentials: creds });
+    expect(out.response.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+
+  it("stops after exhausting 502 attempts on a single url and throws", async () => {
+    const ex = makeExec({ baseUrl: "https://x/api", retry: { 502: { attempts: 2, delayMs: 0 } } });
+    fetchMock.mockResolvedValue(res(502));
+    // single url: 1 initial + 2 retries = 3 calls, then returns the 502 response (no fallback url)
+    const out = await ex.execute({ model: "m", body: {}, stream: false, credentials: creds });
+    expect(out.response.status).toBe(502);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+});
+
+describe("BaseExecutor.execute — baseUrls fallback", () => {
+  it("falls over to the next url on 429 (shouldRetry)", async () => {
+    const ex = makeExec({ baseUrls: ["https://a/api", "https://b/api"], retry: { 429: { attempts: 0 } } });
+    fetchMock
+      .mockResolvedValueOnce(res(429)) // url[0] → fallback
+      .mockResolvedValueOnce(res(200)); // url[1] ok
+    const out = await ex.execute({ model: "m", body: {}, stream: false, credentials: creds });
+    expect(out.response.status).toBe(200);
+    expect(out.url).toBe("https://b/api");
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("BaseExecutor.execute — network error retry/fallback", () => {
+  it("maps network exception to 502 retry config", async () => {
+    const ex = makeExec({ baseUrl: "https://x/api", retry: { 502: { attempts: 1, delayMs: 0 } } });
+    fetchMock
+      .mockImplementationOnce(async () => { throw new Error("ECONNRESET"); })
+      .mockResolvedValueOnce(res(200));
+    const out = await ex.execute({ model: "m", body: {}, stream: false, credentials: creds });
+    expect(out.response.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("throws when the only url fails with network error and no retries left", async () => {
+    const ex = makeExec({ baseUrl: "https://x/api", retry: { 502: { attempts: 0 } } });
+    // mockImplementationOnce (not persistent) avoids vitest flagging a reused rejection.
+    fetchMock.mockImplementationOnce(async () => { throw new Error("boom"); });
+    let thrown = null;
+    try {
+      await ex.execute({ model: "m", body: {}, stream: false, credentials: creds });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown?.message).toBe("boom");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("BaseExecutor.execute — computeRetryDelay hook veto", () => {
+  it("only invokes computeRetryDelay when status has retry config", async () => {
+    const ex = makeExec({ baseUrl: "https://x/api", retry: { 503: { attempts: 1, delayMs: 0 } } });
+    ex.computeRetryDelay = vi.fn().mockResolvedValue(0);
+    fetchMock.mockResolvedValueOnce(res(500));
+    const out = await ex.execute({ model: "m", body: {}, stream: false, credentials: creds });
+    expect(out.response.status).toBe(500);
+    expect(ex.computeRetryDelay).not.toHaveBeenCalled();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("hook returning false skips retry (uses fallback path)", async () => {
+    const ex = makeExec({ baseUrl: "https://x/api", retry: { 429: { attempts: 5, delayMs: 0 } } });
+    ex.computeRetryDelay = vi.fn().mockResolvedValue(false);
+    fetchMock.mockResolvedValueOnce(res(429));
+    const out = await ex.execute({ model: "m", body: {}, stream: false, credentials: creds });
+    // hook vetoes retry → no fallback url → returns the 429 response as-is
+    expect(out.response.status).toBe(429);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/tests/unit/buildOutputFilter.test.js b/tests/unit/buildOutputFilter.test.js
new file mode 100644
index 0000000..cf217f1
--- /dev/null
+++ b/tests/unit/buildOutputFilter.test.js
@@ -0,0 +1,232 @@
+// Tests for PR #1175: build output filter + porcelain regex fix
+// Covers edge cases: porcelain workdir-only, cargo misdetection, false positives, compression
+import { describe, it, expect } from "vitest";
+import { autoDetectFilter } from "../../open-sse/rtk/autodetect.js";
+import { buildOutput } from "../../open-sse/rtk/filters/buildOutput.js";
+import { gitStatus } from "../../open-sse/rtk/filters/gitStatus.js";
+
+describe("PR #1175 - buildOutput filter detection", () => {
+  it("detects npm install output", () => {
+    const input = [
+      "npm warn deprecated har-validator@5.1.5: this library is no longer supported",
+      "npm warn deprecated uuid@3.4.0: uuid@10 and below is no longer supported",
+      "npm warn deprecated request@2.88.2: request has been deprecated",
+      "added 47 packages, and audited 48 packages in 13s",
+      "3 packages are looking for funding",
+      "  run `npm fund` for details",
+      "4 vulnerabilities (2 moderate, 2 critical)",
+      "Run `npm audit` for details."
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    expect(filter).toBe(buildOutput);
+  });
+
+  it("detects cargo build output (no longer misdetected as git-status)", () => {
+    const input = [
+      "   Compiling proc-macro2 v1.0.95",
+      "   Compiling unicode-ident v1.0.18",
+      "   Compiling quote v1.0.40",
+      "   Compiling syn v2.0.104",
+      "   Compiling my-project v0.1.0 (/home/user/my-project)",
+      "    Finished `dev` profile [unoptimized + debuginfo] target(s) in 12.34s"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    expect(filter).toBe(buildOutput);
+    expect(filter).not.toBe(gitStatus);
+  });
+});
+
+describe("PR #1175 - buildOutput compression behavior", () => {
+  it("compresses npm install with deprecations", () => {
+    const input = [
+      "npm warn deprecated har-validator@5.1.5: this library is no longer supported",
+      "npm warn deprecated uuid@3.4.0: uuid@10 and below is no longer supported",
+      "npm warn deprecated request@2.88.2: request has been deprecated",
+      "added 47 packages, and audited 48 packages in 13s",
+      "3 packages are looking for funding",
+      "  run `npm fund` for details",
+      "4 vulnerabilities (2 moderate, 2 critical)",
+      "Run `npm audit` for details."
+    ].join("\n");
+    const out = buildOutput(input);
+    // Minimal fix: keep first 3 deprecations verbatim (no truncation needed since count == 3)
+    expect(out).toContain("har-validator@5.1.5");
+    expect(out).toContain("uuid@3.4.0");
+    expect(out).toContain("request@2.88.2");
+    expect(out).toContain("added 47 packages");
+    expect(out).toContain("4 vulnerabilities");
+    // 3 deprecations kept verbatim → no size win on this small input
+    expect(out.length).toBeLessThanOrEqual(input.length);
+  });
+
+  it("compresses cargo build output", () => {
+    const input = [
+      "   Compiling proc-macro2 v1.0.95",
+      "   Compiling unicode-ident v1.0.18",
+      "   Compiling quote v1.0.40",
+      "   Compiling syn v2.0.104",
+      "   Compiling serde v1.0.219",
+      "   Compiling serde_derive v1.0.219",
+      "   Compiling serde_json v1.0.140",
+      "   Compiling tokio v1.45.0",
+      "   Compiling hyper v1.6.0",
+      "   Compiling my-project v0.1.0 (/home/user/my-project)",
+      "    Finished `dev` profile [unoptimized + debuginfo] target(s) in 12.34s"
+    ].join("\n");
+    const out = buildOutput(input);
+    expect(out).toContain("Compiled 10 packages");
+    expect(out).toContain("Finished");
+    expect(out.length).toBeLessThan(input.length * 0.5);
+  });
+
+  it("keeps cargo errors verbatim", () => {
+    const input = [
+      "   Compiling foo v0.1.0",
+      "error[E0308]: mismatched types",
+      "  --> src/main.rs:5:9",
+      "   |",
+      "5  |     let x: u32 = \"hello\";",
+      "   |            ---   ^^^^^^^ expected `u32`, found `&str`",
+      "error: aborting due to previous error"
+    ].join("\n");
+    const out = buildOutput(input);
+    expect(out).toContain("error[E0308]");
+    expect(out).toContain("error: aborting");
+  });
+
+  it("keeps maven BUILD FAILED as error", () => {
+    const input = [
+      "[INFO] Scanning for projects...",
+      "[ERROR] Failed to execute goal",
+      "[ERROR] Could not resolve dependencies",
+      "BUILD FAILED"
+    ].join("\n");
+    const out = buildOutput(input);
+    expect(out).toContain("[ERROR] Failed to execute goal");
+    expect(out).toContain("BUILD FAILED");
+  });
+});
+
+describe("PR #1175 - porcelain regex fix edge cases", () => {
+  it("git status --porcelain workdir-only (space first char) STILL detects as gitStatus (minimal fix preserved old regex)", () => {
+    const input = [
+      " M src/a.js",
+      " M src/b.js",
+      " D src/c.js",
+      "?? new.js"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    expect(filter).toBe(gitStatus);
+  });
+
+  it("git status --porcelain with staged (status code first char) still detects", () => {
+    const input = [
+      "M  src/a.js",
+      "A  src/new.js",
+      "?? untracked.js",
+      "M  src/b.js"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    expect(filter).toBe(gitStatus);
+  });
+
+  it("cargo Compiling lines NOT detected as git-status (porcelain false positive fix)", () => {
+    const input = [
+      "   Compiling proc-macro2 v1.0.95",
+      "   Compiling unicode-ident v1.0.18",
+      "   Compiling quote v1.0.40"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    expect(filter).not.toBe(gitStatus);
+  });
+
+  it("long-form git status with 'On branch' always detects", () => {
+    const input = [
+      "On branch main",
+      "Your branch is up to date with 'origin/main'.",
+      "",
+      "Changes not staged for commit:",
+      "\tmodified:   src/a.js"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    expect(filter).toBe(gitStatus);
+  });
+});
+
+describe("PR #1175 - false positive risks", () => {
+  it("generic app log with 'ERROR:' triggers buildOutput (potential false positive)", () => {
+    const input = [
+      "2026-05-16 10:00:00 INFO Server started on port 3000",
+      "2026-05-16 10:00:05 INFO Request received: GET /api/users",
+      "ERROR: Database connection timeout",
+      "2026-05-16 10:00:10 INFO Retrying connection",
+      "2026-05-16 10:00:15 INFO Connection restored"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    // Document actual behavior — may detect as buildOutput
+    console.log("[generic-error-log] detected:", filter?.filterName || "null");
+    // Whatever the detection, the filter should NOT corrupt the data
+    if (filter === buildOutput) {
+      const out = buildOutput(input);
+      expect(out).toContain("ERROR: Database connection timeout");
+    }
+  });
+
+  it("generic 'Compiling templates' (non-build context) triggers buildOutput", () => {
+    const input = [
+      "[INFO] Starting application",
+      "[INFO]   Compiling templates for view layer",
+      "[INFO]   Compiling assets for production",
+      "[INFO] Application ready"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    console.log("[compiling-templates] detected:", filter?.filterName || "null");
+    if (filter === buildOutput) {
+      const out = buildOutput(input);
+      // Should at least preserve structure (count compiling)
+      expect(out).toContain("Compiled");
+    }
+  });
+
+  it("plain text with no patterns falls through (no false positive)", () => {
+    const input = [
+      "Hello world",
+      "This is a normal message",
+      "Nothing special here"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    expect(filter).not.toBe(buildOutput);
+  });
+});
+
+describe("PR #1175 - safety: no data corruption", () => {
+  it("empty input returns input", () => {
+    expect(buildOutput("")).toBe("");
+  });
+
+  it("input with only errors preserves all errors", () => {
+    const input = "npm ERR! code ENOENT\nnpm ERR! syscall open\nnpm ERR! path /tmp/foo";
+    const out = buildOutput(input);
+    expect(out).toContain("npm ERR! code ENOENT");
+    expect(out).toContain("npm ERR! syscall open");
+    expect(out).toContain("npm ERR! path /tmp/foo");
+  });
+
+  it("input with no recognized patterns returns input (fallback)", () => {
+    const input = "random text\nmore random\nstill random";
+    const out = buildOutput(input);
+    // When nothing matches, returns input via `|| input`
+    expect(out).toBe(input);
+  });
+
+  it("limits warnings to 5 + summary line", () => {
+    const warnings = [];
+    for (let i = 0; i < 10; i++) warnings.push(`npm warn config foo${i} something`);
+    const input = warnings.join("\n");
+    const out = buildOutput(input);
+    expect(out).toContain("npm warn config foo0");
+    expect(out).toContain("npm warn config foo4");
+    expect(out).toContain("... +5 more warnings");
+    expect(out).not.toContain("npm warn config foo9");
+  });
+});
diff --git a/tests/unit/buildOutputFilterAdversarial.test.js b/tests/unit/buildOutputFilterAdversarial.test.js
new file mode 100644
index 0000000..799f503
--- /dev/null
+++ b/tests/unit/buildOutputFilterAdversarial.test.js
@@ -0,0 +1,393 @@
+// Adversarial / edge-case tests for PR #1175
+// Goals: find corruption, boundary bugs, false positives, integration regressions
+import { describe, it, expect } from "vitest";
+import { autoDetectFilter } from "../../open-sse/rtk/autodetect.js";
+import { buildOutput } from "../../open-sse/rtk/filters/buildOutput.js";
+import { gitDiff } from "../../open-sse/rtk/filters/gitDiff.js";
+import { gitLog } from "../../open-sse/rtk/filters/gitLog.js";
+import { gitStatus } from "../../open-sse/rtk/filters/gitStatus.js";
+import { safeApply } from "../../open-sse/rtk/applyFilter.js";
+import { compressMessages } from "../../open-sse/rtk/index.js";
+import { DETECT_WINDOW, MIN_COMPRESS_SIZE } from "../../open-sse/rtk/constants.js";
+
+// ============================================================
+// 1. PRIORITY / OVERLAPPING PATTERNS
+// ============================================================
+describe("PR #1175 - priority with overlapping patterns", () => {
+  it("git-diff wins over buildOutput when both present", () => {
+    const input = [
+      "diff --git a/Cargo.toml b/Cargo.toml",
+      "index abc..def 100644",
+      "--- a/Cargo.toml",
+      "+++ b/Cargo.toml",
+      "@@ -1,3 +1,3 @@",
+      "-version = \"0.1.0\"",
+      "+version = \"0.2.0\"",
+      "   Compiling foo v0.1.0"
+    ].join("\n");
+    expect(autoDetectFilter(input)).toBe(gitDiff);
+  });
+
+  it("git-status (long form) wins over buildOutput", () => {
+    const input = [
+      "On branch main",
+      "Changes not staged for commit:",
+      "\tmodified:   Cargo.toml",
+      "   Compiling foo v0.1.0"
+    ].join("\n");
+    expect(autoDetectFilter(input)).toBe(gitStatus);
+  });
+});
+
+// ============================================================
+// 2. BOUNDARY: DETECT_WINDOW
+// ============================================================
+describe("PR #1175 - DETECT_WINDOW boundary", () => {
+  it("build pattern beyond DETECT_WINDOW chars: NOT detected", () => {
+    const padding = "x".repeat(DETECT_WINDOW + 100);
+    const input = `${padding}\n   Compiling foo v0.1.0\n    Finished release in 1.2s`;
+    const filter = autoDetectFilter(input);
+    // Pattern lives past detection window — won't be seen
+    expect(filter).not.toBe(buildOutput);
+  });
+
+  it("build pattern at very start: detected", () => {
+    const input = "   Compiling foo v0.1.0\n" + "y".repeat(2000);
+    expect(autoDetectFilter(input)).toBe(buildOutput);
+  });
+});
+
+// ============================================================
+// 3. LINE ENDINGS / WHITESPACE QUIRKS
+// ============================================================
+describe("PR #1175 - line endings & whitespace", () => {
+  it("CRLF line endings still detect", () => {
+    const input = "npm warn deprecated foo@1.0.0\r\nadded 5 packages in 2s\r\n";
+    expect(autoDetectFilter(input)).toBe(buildOutput);
+  });
+
+  it("Tab-prefixed Compiling (real cargo output uses leading spaces, not tab)", () => {
+    const input = "\tCompiling foo v0.1.0\n\tCompiling bar v0.2.0\n\tFinished dev in 1s";
+    const filter = autoDetectFilter(input);
+    // \s matches tab, so should detect
+    expect(filter).toBe(buildOutput);
+  });
+
+  it("Compiling without leading spaces", () => {
+    const input = "Compiling foo v0.1.0\nCompiling bar v0.2.0\nFinished dev in 1s";
+    expect(autoDetectFilter(input)).toBe(buildOutput);
+  });
+});
+
+// ============================================================
+// 4. ADVERSARIAL: USER CODE / STRING LITERALS
+// ============================================================
+describe("PR #1175 - adversarial: user code containing build strings", () => {
+  it("user JS code with console.log('npm warn ...') triggers buildOutput", () => {
+    // This is a realistic case: LLM is reading a file with this code
+    const input = [
+      "function logWarning() {",
+      "  console.log('npm warn this is a warning');",
+      "  return true;",
+      "}",
+      "function logError() {",
+      "  console.log('npm error something bad');",
+      "}"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    // Regex uses `m` flag, so ^ matches line start — these are inside indented code
+    // BUT: regex uses 'i' so case-insensitive, and `^npm warn` requires line to START with it
+    console.log("[user-code-npm-warn] detected:", filter?.filterName || "null");
+    // Expectation: should NOT detect (lines start with spaces)
+    expect(filter).not.toBe(buildOutput);
+  });
+
+  it("file content with 'BUILD SUCCESS' on its own line triggers buildOutput", () => {
+    const input = [
+      "Here is the deployment script:",
+      "It outputs:",
+      "BUILD SUCCESS",
+      "when complete."
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    console.log("[file-content-build-success] detected:", filter?.filterName || "null");
+    // Document behavior — buildOutput should preserve non-pattern lines as fallback
+    if (filter === buildOutput) {
+      const out = buildOutput(input);
+      // BUILD SUCCESS preserved
+      expect(out).toContain("BUILD SUCCESS");
+    }
+  });
+
+  it("real cargo error spanning multiple lines preserves context", () => {
+    const input = [
+      "   Compiling my-app v0.1.0",
+      "error[E0432]: unresolved import `foo::bar`",
+      " --> src/main.rs:2:5",
+      "  |",
+      "2 | use foo::bar;",
+      "  |     ^^^^^^^^ no `bar` in `foo`",
+      "",
+      "error: aborting due to previous error",
+      "",
+      "For more information about this error, try `rustc --explain E0432`.",
+      "error: could not compile `my-app` (bin \"my-app\") due to previous error"
+    ].join("\n");
+    const out = buildOutput(input);
+    expect(out).toContain("error[E0432]");
+    expect(out).toContain("error: aborting");
+    expect(out).toContain("error: could not compile");
+    // Minimal fix: cargo error context lines now preserved
+    expect(out).toContain("use foo::bar");
+    expect(out).toContain("no `bar`");
+  });
+});
+
+// ============================================================
+// 5. CORRUPTION / SAFETY: NO EMPTY OUTPUT
+// ============================================================
+describe("PR #1175 - corruption safety", () => {
+  it("input with only progress lines (no errors/warnings/summary) returns input fallback", () => {
+    const input = [
+      "   Compiling a v0.1.0",
+      "   Compiling b v0.1.0",
+      "   Compiling c v0.1.0"
+    ].join("\n");
+    const out = buildOutput(input);
+    // out = "Compiled 3 packages" (non-empty)
+    expect(out.length).toBeGreaterThan(0);
+    expect(out).toContain("Compiled 3 packages");
+  });
+
+  it("input with only Downloading lines", () => {
+    const input = [
+      "   Downloading foo v0.1.0",
+      "   Downloading bar v0.2.0",
+      "Fetching baz from registry"
+    ].join("\n");
+    const out = buildOutput(input);
+    expect(out).toContain("Downloaded");
+  });
+
+  it("input with ONLY a single ERROR: line", () => {
+    const input = "ERROR: Something failed";
+    const out = buildOutput(input);
+    expect(out).toContain("ERROR: Something failed");
+  });
+
+  it("unicode/emoji in deprecation warning preserved (minimal fix keeps first 3 verbatim)", () => {
+    const input = [
+      "npm warn deprecated 📦 foo@1.0.0: 🚫 deprecated reason",
+      "added 1 package ✨",
+      "Run `npm audit` for details."
+    ].join("\n");
+    const out = buildOutput(input);
+    expect(out).toContain("📦");
+    expect(out).toContain("foo@1.0.0");
+    expect(out).toContain("added 1 package ✨");
+  });
+
+  it("more than 3 deprecations: keep first 3 verbatim + count rest", () => {
+    const input = [
+      "npm warn deprecated a@1.0.0: reason A",
+      "npm warn deprecated b@1.0.0: reason B",
+      "npm warn deprecated c@1.0.0: reason C",
+      "npm warn deprecated d@1.0.0: reason D",
+      "npm warn deprecated e@1.0.0: reason E",
+      "added 5 packages"
+    ].join("\n");
+    const out = buildOutput(input);
+    expect(out).toContain("a@1.0.0");
+    expect(out).toContain("b@1.0.0");
+    expect(out).toContain("c@1.0.0");
+    expect(out).not.toContain("d@1.0.0");
+    expect(out).not.toContain("e@1.0.0");
+    expect(out).toContain("... +2 more deprecated packages");
+  });
+
+  it("safeApply wraps buildOutput against panics", () => {
+    // Pass a non-string input via direct call — safeApply should catch
+    const out = safeApply(buildOutput, "npm warn deprecated foo\nadded 1 package\n");
+    expect(typeof out).toBe("string");
+  });
+});
+
+// ============================================================
+// 6. INTEGRATION: compressMessages pipeline
+// ============================================================
+describe("PR #1175 - integration with compressMessages", () => {
+  function buildBody(toolResultText) {
+    return {
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "tool_result", tool_use_id: "id1", content: toolResultText }
+          ]
+        }
+      ]
+    };
+  }
+
+  it("npm install output above MIN_COMPRESS_SIZE → compressed", () => {
+    const padding = "npm warn deprecated foo@1.0.0: this is a deprecation warning\n".repeat(20);
+    const text = padding + "added 47 packages, and audited 48 packages in 13s\n4 vulnerabilities (2 moderate, 2 critical)\nRun `npm audit` for details.";
+    expect(text.length).toBeGreaterThan(MIN_COMPRESS_SIZE);
+    const body = buildBody(text);
+    const stats = compressMessages(body, true);
+    expect(stats).toBeTruthy();
+    expect(stats.hits.length).toBe(1);
+    expect(stats.hits[0].filter).toBe("build-output");
+    expect(stats.bytesAfter).toBeLessThan(stats.bytesBefore);
+    const compressed = body.messages[0].content[0].content;
+    expect(compressed).toContain("... +17 more deprecated packages");
+  });
+
+  it("input below MIN_COMPRESS_SIZE → NOT compressed", () => {
+    const text = "npm warn deprecated foo\nadded 1 package";
+    expect(text.length).toBeLessThan(MIN_COMPRESS_SIZE);
+    const body = buildBody(text);
+    const stats = compressMessages(body, true);
+    expect(stats.hits.length).toBe(0);
+    expect(body.messages[0].content[0].content).toBe(text);
+  });
+
+  it("compressed output never grows input (safety guard)", () => {
+    // Pathological: every line is something buildOutput keeps verbatim
+    const text = "npm ERR! error line 1\nnpm ERR! error line 2\nnpm ERR! error line 3\n".repeat(20);
+    const body = buildBody(text);
+    const stats = compressMessages(body, true);
+    // either no hit (grew) or hit and shrunk
+    const after = body.messages[0].content[0].content;
+    expect(after.length).toBeLessThanOrEqual(text.length);
+  });
+
+  it("tool_result with is_error:true is NOT compressed (preserve error traces)", () => {
+    const text = "npm warn deprecated foo@1.0.0\n".repeat(30) + "added 5 packages in 2s";
+    const body = {
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "tool_result", tool_use_id: "id1", content: text, is_error: true }
+          ]
+        }
+      ]
+    };
+    const stats = compressMessages(body, true);
+    expect(stats.hits.length).toBe(0);
+    expect(body.messages[0].content[0].content).toBe(text);
+  });
+});
+
+// ============================================================
+// 6.5. GIT-LOG PRIORITY
+// ============================================================
+describe("git-log priority", () => {
+  it("git-log chosen over build-output when commit header present in first window", () => {
+    const input = [
+      "commit abc1234def5678abc1234def5678abc1234def5",
+      "Author: Dev One <dev1@example.com>",
+      "Date:   Sun Jul 6 10:00:00 2026 +0700",
+      "",
+      "    Add auth middleware",
+      "",
+      "diff --git a/src/auth.js b/src/auth.js",
+      "index abc..def 100644",
+      "--- a/src/auth.js",
+      "+++ b/src/auth.js",
+      "@@ -1 +1 @@",
+      "+new line"
+    ].join("\n");
+    expect(autoDetectFilter(input)).toBe(gitLog);
+  });
+
+  it("pure git diff still stays git-diff", () => {
+    const input = [
+      "diff --git a/src/auth.js b/src/auth.js",
+      "index abc..def 100644",
+      "--- a/src/auth.js",
+      "+++ b/src/auth.js",
+      "@@ -1 +1 @@",
+      "+new line"
+    ].join("\n");
+    expect(autoDetectFilter(input)).toBe(gitDiff);
+  });
+});
+
+// ============================================================
+// 7. PORCELAIN REGRESSION DEEPER TESTS
+// ============================================================
+describe("PR #1175 - porcelain regression deeper", () => {
+  it("mixed staged + workdir + untracked porcelain → detected (has status code first char)", () => {
+    const input = [
+      "M  src/staged.js",   // staged modified
+      " M src/workdir.js",  // workdir modified (space first)
+      "?? new.js",
+      "A  src/added.js"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    // M and A and ?? lines have status code first → 4/4 lines hit? No — " M" has space first
+    // isMostlyPorcelain requires >= 60% hit. With new regex, hits = M/?/A = 3, total = 4, 75% ≥ 60%
+    expect(filter).toBe(gitStatus);
+  });
+
+  it("100% workdir-only porcelain → STILL detects gitStatus (minimal fix preserved old regex)", () => {
+    const input = [
+      " M src/a.js",
+      " M src/b.js",
+      " M src/c.js",
+      " D src/d.js"
+    ].join("\n");
+    const filter = autoDetectFilter(input);
+    expect(filter).toBe(gitStatus);
+  });
+
+  it("manual gitStatus() call on workdir-only porcelain still parses correctly", () => {
+    const input = [
+      " M src/a.js",
+      " M src/b.js",
+      " D src/c.js"
+    ].join("\n");
+    const out = gitStatus(input);
+    expect(out).toContain("Modified: 3 files");
+  });
+});
+
+// ============================================================
+// 8. PATHOLOGICAL INPUTS
+// ============================================================
+describe("PR #1175 - pathological", () => {
+  it("very long single line (no newlines) with build pattern", () => {
+    const input = "npm warn deprecated foo@1.0.0: " + "x".repeat(5000);
+    const filter = autoDetectFilter(input);
+    // Pattern at start (within DETECT_WINDOW)
+    expect(filter).toBe(buildOutput);
+    // Should NOT crash
+    const out = buildOutput(input);
+    expect(typeof out).toBe("string");
+  });
+
+  it("10000 Compiling lines don't crash", () => {
+    const lines = [];
+    for (let i = 0; i < 10000; i++) lines.push(`   Compiling pkg${i} v0.1.0`);
+    lines.push("    Finished dev in 60s");
+    const input = lines.join("\n");
+    const out = buildOutput(input);
+    expect(out).toContain("Compiled 10000 packages");
+    expect(out).toContain("Finished");
+    expect(out.length).toBeLessThan(input.length / 100);
+  });
+
+  it("input with only newlines", () => {
+    const input = "\n\n\n\n";
+    const out = buildOutput(input);
+    expect(typeof out).toBe("string");
+  });
+
+  it("null/undefined safety via safeApply", () => {
+    // buildOutput would throw on null.split() — safeApply must catch
+    const out = safeApply(buildOutput, null);
+    expect(out).toBe(null);
+  });
+});
diff --git a/tests/unit/cached-token-e2e.test.js b/tests/unit/cached-token-e2e.test.js
new file mode 100644
index 0000000..f32f6a3
--- /dev/null
+++ b/tests/unit/cached-token-e2e.test.js
@@ -0,0 +1,84 @@
+// End-to-end: a cache-bearing request flows through canonicalizeUsage →
+// saveRequestUsage → getUsageStats, proving cached tokens are persisted,
+// aggregated, and cost is computed correctly (the bug this branch fixes).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
+import { canonicalizeUsage } from "../../open-sse/utils/usageTracking.js";
+
+const originalDataDir = process.env.DATA_DIR;
+let tempDir;
+let db;
+
+beforeAll(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "9router-cached-e2e-"));
+  process.env.DATA_DIR = tempDir;
+  vi.resetModules();
+  db = await import("@/lib/db/index.js");
+  await db.initDb();
+});
+
+afterAll(() => {
+  if (tempDir) fs.rmSync(tempDir, { recursive: true, force: true });
+  if (originalDataDir === undefined) delete process.env.DATA_DIR;
+  else process.env.DATA_DIR = originalDataDir;
+});
+
+describe("cached-token end-to-end (persist + aggregate + cost)", () => {
+  it("Claude cache usage: canonical prompt is inclusive, cached persisted, cost correct", async () => {
+    // Raw Claude usage (cache-EXCLUSIVE prompt): input 100, cache_read 200, cache_creation 30, output 50
+    const canonical = canonicalizeUsage({
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      cache_read_input_tokens: 200,
+      cache_creation_input_tokens: 30,
+    });
+    expect(canonical.prompt_tokens).toBe(330); // inclusive
+
+    await db.saveRequestUsage({
+      provider: "anthropic",
+      model: "claude-sonnet-4-6",
+      connectionId: "c-cache",
+      tokens: canonical,
+      endpoint: "/v1/messages",
+      status: "ok",
+    });
+
+    const stats = await db.getUsageStats("24h");
+    expect(stats.totalCachedTokens).toBe(200);
+    expect(stats.totalPromptTokens).toBe(330);
+    expect(stats.byProvider.anthropic.cachedTokens).toBe(200);
+
+    // Cost: nonCached=330-200-30=100 @3 + cached 200 @0.30 + creation 30 @3.75 + output 50 @15
+    const expected = (100 * 3 + 200 * 0.3 + 30 * 3.75 + 50 * 15) / 1_000_000;
+    const hist = await db.getUsageHistory({ provider: "anthropic" });
+    expect(hist.length).toBe(1);
+    expect(hist[0].cost).toBeCloseTo(expected, 12);
+    expect(hist[0].tokens.cached_tokens).toBe(200);
+    expect(hist[0].tokens.cache_creation_input_tokens).toBe(30);
+  });
+
+  it("OpenAI cache usage: inclusive prompt passes through, cached counted once", async () => {
+    const canonical = canonicalizeUsage({
+      prompt_tokens: 1000,        // already includes cached
+      completion_tokens: 200,
+      cached_tokens: 600,
+    });
+    expect(canonical.prompt_tokens).toBe(1000);
+    expect(canonical.cached_tokens).toBe(600);
+
+    await db.saveRequestUsage({
+      provider: "openai",
+      model: "gpt-4o",
+      connectionId: "c-oai",
+      tokens: canonical,
+      endpoint: "/v1/chat/completions",
+      status: "ok",
+    });
+
+    const hist = await db.getUsageHistory({ provider: "openai" });
+    expect(hist[0].tokens.prompt_tokens).toBe(1000);
+    expect(hist[0].tokens.cached_tokens).toBe(600);
+  });
+});
diff --git a/tests/unit/cached-token-usage.test.js b/tests/unit/cached-token-usage.test.js
new file mode 100644
index 0000000..878110d
--- /dev/null
+++ b/tests/unit/cached-token-usage.test.js
@@ -0,0 +1,188 @@
+import { describe, it, expect } from "vitest";
+import { canonicalizeUsage, extractUsage, mergeUsage } from "../../open-sse/utils/usageTracking.js";
+import { calculateCostFromTokens } from "../../open-sse/providers/pricing.js";
+import { toOpenAIUsage } from "../../open-sse/translator/concerns/usage.js";
+
+// Canonical convention (single source of truth for storage + cost):
+//   prompt_tokens             = total input INCLUDING cache read + cache creation
+//   cached_tokens             = cache-read portion (subset of prompt_tokens)
+//   cache_creation_input_tokens = cache-write portion (subset of prompt_tokens)
+//   completion_tokens         = output
+// Discriminator: Claude reports cache separately (prompt EXCLUDES cache);
+// OpenAI/Gemini report prompt INCLUDING cached_tokens.
+describe("canonicalizeUsage", () => {
+  it("folds Claude exclusive cache into an inclusive prompt count", () => {
+    // Claude: input_tokens excludes cache; cache_read + cache_creation are separate
+    const out = canonicalizeUsage({
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      cache_read_input_tokens: 200,
+      cache_creation_input_tokens: 30,
+    });
+    expect(out.prompt_tokens).toBe(330); // 100 + 200 + 30
+    expect(out.completion_tokens).toBe(50);
+    expect(out.cached_tokens).toBe(200);
+    expect(out.cache_creation_input_tokens).toBe(30);
+  });
+
+  it("passes through OpenAI inclusive prompt unchanged", () => {
+    // OpenAI: prompt_tokens already includes cached_tokens (a subset)
+    const out = canonicalizeUsage({
+      prompt_tokens: 330,
+      completion_tokens: 50,
+      cached_tokens: 200,
+    });
+    expect(out.prompt_tokens).toBe(330);
+    expect(out.cached_tokens).toBe(200);
+    expect(out.cache_creation_input_tokens).toBe(0);
+  });
+
+  it("passes through Gemini inclusive prompt (cachedContent already counted)", () => {
+    const out = canonicalizeUsage({
+      prompt_tokens: 500,
+      completion_tokens: 80,
+      cached_tokens: 120,
+      reasoning_tokens: 40,
+    });
+    expect(out.prompt_tokens).toBe(500);
+    expect(out.cached_tokens).toBe(120);
+    expect(out.reasoning_tokens).toBe(40);
+  });
+
+  it("handles no-cache usage", () => {
+    const out = canonicalizeUsage({ prompt_tokens: 100, completion_tokens: 50 });
+    expect(out.prompt_tokens).toBe(100);
+    expect(out.cached_tokens).toBe(0);
+    expect(out.cache_creation_input_tokens).toBe(0);
+  });
+
+  it("is idempotent (running twice yields the same canonical shape)", () => {
+    const once = canonicalizeUsage({
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      cache_read_input_tokens: 200,
+      cache_creation_input_tokens: 30,
+    });
+    const twice = canonicalizeUsage(once);
+    expect(twice.prompt_tokens).toBe(330);
+    expect(twice.cached_tokens).toBe(200);
+    expect(twice.cache_creation_input_tokens).toBe(30);
+    expect(twice.completion_tokens).toBe(50);
+  });
+
+  it("returns null for invalid input", () => {
+    expect(canonicalizeUsage(null)).toBeNull();
+    expect(canonicalizeUsage(undefined)).toBeNull();
+  });
+
+  it("folds a Claude cache-miss first write (cache_creation only, no cache_read yet)", () => {
+    // Cache-miss on first write: upstream emits cache_creation_input_tokens but
+    // no cache_read_input_tokens at all (not even 0). Must still fold into prompt
+    // instead of falling through to the OpenAI passthrough branch.
+    const out = canonicalizeUsage({
+      prompt_tokens: 100,
+      completion_tokens: 20,
+      cache_creation_input_tokens: 500,
+    });
+    expect(out.prompt_tokens).toBe(600); // 100 + 0 (no read) + 500
+    expect(out.cached_tokens).toBe(0);
+    expect(out.cache_creation_input_tokens).toBe(500);
+  });
+});
+
+describe("calculateCostFromTokens (canonical inclusive convention)", () => {
+  const pricing = { input: 3, output: 15, cached: 0.3, cache_creation: 3.75 };
+
+  it("prices cached + cache_creation as subsets of an inclusive prompt without double-counting", () => {
+    // prompt=330 includes 200 cached + 30 cache_creation → 100 full-price input
+    const cost = calculateCostFromTokens(
+      { prompt_tokens: 330, completion_tokens: 50, cached_tokens: 200, cache_creation_input_tokens: 30 },
+      pricing
+    );
+    const expected =
+      (100 * 3 + 200 * 0.3 + 30 * 3.75 + 50 * 15) / 1_000_000;
+    expect(cost).toBeCloseTo(expected, 12);
+  });
+
+  it("does not let cache_creation drive nonCached negative", () => {
+    // pathological: cached + creation exceeds prompt → nonCached clamps at 0
+    const cost = calculateCostFromTokens(
+      { prompt_tokens: 100, completion_tokens: 0, cached_tokens: 80, cache_creation_input_tokens: 40 },
+      pricing
+    );
+    const expected = (0 * 3 + 80 * 0.3 + 40 * 3.75) / 1_000_000;
+    expect(cost).toBeCloseTo(expected, 12);
+  });
+
+  it("matches plain input pricing when no cache present", () => {
+    const cost = calculateCostFromTokens({ prompt_tokens: 100, completion_tokens: 50 }, pricing);
+    expect(cost).toBeCloseTo((100 * 3 + 50 * 15) / 1_000_000, 12);
+  });
+});
+
+describe("Anthropic streaming usage (message_start carries cache, message_delta output-only)", () => {
+  it("extractUsage reads input + cache from message_start", () => {
+    const u = extractUsage({
+      type: "message_start",
+      message: { usage: { input_tokens: 100, output_tokens: 1, cache_read_input_tokens: 200, cache_creation_input_tokens: 30 } },
+    });
+    expect(u.prompt_tokens).toBe(100);
+    expect(u.cache_read_input_tokens).toBe(200);
+    expect(u.cache_creation_input_tokens).toBe(30);
+  });
+
+  it("merges message_start cache with message_delta output without clobbering", () => {
+    // Real Anthropic SSE: cache only in message_start, real output only in message_delta.
+    const start = extractUsage({
+      type: "message_start",
+      message: { usage: { input_tokens: 100, output_tokens: 1, cache_read_input_tokens: 200, cache_creation_input_tokens: 30 } },
+    });
+    const delta = extractUsage({ type: "message_delta", usage: { output_tokens: 50 } });
+    const merged = mergeUsage(start, delta);
+    expect(merged.prompt_tokens).toBe(100);
+    expect(merged.cache_read_input_tokens).toBe(200);
+    expect(merged.cache_creation_input_tokens).toBe(30);
+    expect(merged.completion_tokens).toBe(50);
+
+    // And it canonicalizes to a cache-inclusive prompt for storage/cost.
+    const canon = canonicalizeUsage(merged);
+    expect(canon.prompt_tokens).toBe(330); // 100 + 200 + 30
+    expect(canon.cached_tokens).toBe(200);
+    expect(canon.cache_creation_input_tokens).toBe(30);
+    expect(canon.completion_tokens).toBe(50);
+  });
+
+  it("does not let a NaN field poison the running max-merge", () => {
+    // typeof NaN === "number", so a naive Math.max(prev, NaN) is NaN — one
+    // malformed chunk must not wipe out an already-accumulated good value.
+    const prev = { prompt_tokens: 100, cache_read_input_tokens: 200 };
+    const bad = { prompt_tokens: NaN, completion_tokens: 50 };
+    const merged = mergeUsage(prev, bad);
+    expect(merged.prompt_tokens).toBe(100);
+    expect(merged.cache_read_input_tokens).toBe(200);
+    expect(merged.completion_tokens).toBe(50);
+  });
+});
+
+describe("Kiro usage pass-through", () => {
+  it("passes through plain input/output when no cache fields are present", () => {
+    const out = toOpenAIUsage({ inputTokens: 100, outputTokens: 50 }, "kiro");
+    expect(out.prompt_tokens).toBe(100);
+    expect(out.completion_tokens).toBe(50);
+    expect(out.total_tokens).toBe(150);
+    expect(out.prompt_tokens_details).toBeUndefined();
+  });
+
+  it("forward-compat: surfaces cache fields if Kiro event shape grows them", () => {
+    // ponytail: Amazon Q upstream doesn't expose cache today, but if it starts
+    // sending cache_read_input_tokens / cache_creation_input_tokens / cachedTokens,
+    // cost tracking should pick them up automatically without another change.
+    const out = toOpenAIUsage(
+      { inputTokens: 500, outputTokens: 100, cache_read_input_tokens: 200, cache_creation_input_tokens: 50 },
+      "kiro"
+    );
+    expect(out.prompt_tokens_details).toBeDefined();
+    expect(out.prompt_tokens_details.cached_tokens).toBe(200);
+    expect(out.prompt_tokens_details.cache_creation_tokens).toBe(50);
+  });
+});
diff --git a/tests/unit/capabilities-opus-context.test.js b/tests/unit/capabilities-opus-context.test.js
new file mode 100644
index 0000000..9bb7518
--- /dev/null
+++ b/tests/unit/capabilities-opus-context.test.js
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+
+import { getCapabilitiesForModel } from "../../open-sse/providers/capabilities.js";
+
+// Claude Opus 4.6+ ships a 1M-token context window (GA, standard pricing).
+// The registry exposes dashed ids (claude-opus-4-8, claude-opus-4-7), which
+// must resolve to the 1M context + adaptive thinking caps rather than falling
+// through to the generic *claude*opus* pattern (200k / budget thinking).
+describe("Claude Opus 1M context capabilities", () => {
+  const expected = {
+    contextWindow: 1000000,
+    maxOutput: 128000,
+    thinkingFormat: "claude-adaptive",
+    reasoning: true,
+    vision: true,
+    search: true,
+  };
+
+  for (const model of [
+    "claude-opus-4-8",
+    "claude-opus-4.8",
+    "claude-opus-4-7",
+    "claude-opus-4.7",
+    "claude-opus-4-6",
+  ]) {
+    it(`resolves ${model} to a 1M context window`, () => {
+      expect(getCapabilitiesForModel("cc", model)).toMatchObject(expected);
+    });
+  }
+
+  it("keeps the older Opus 4.5 at the standard 200k context", () => {
+    expect(getCapabilitiesForModel("cc", "claude-opus-4-5-20251101").contextWindow).toBe(200000);
+  });
+});
diff --git a/tests/unit/capabilities-service-kind.test.js b/tests/unit/capabilities-service-kind.test.js
new file mode 100644
index 0000000..e5019af
--- /dev/null
+++ b/tests/unit/capabilities-service-kind.test.js
@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+
+import { capabilitiesFromServiceKind } from "../../open-sse/providers/capabilities.js";
+
+describe("capabilitiesFromServiceKind", () => {
+  it("maps imageToText custom models to vision-capable runtime models", () => {
+    expect(capabilitiesFromServiceKind("imageToText")).toMatchObject({ vision: true });
+  });
+
+  it("maps media output/input custom model kinds to runtime capabilities", () => {
+    expect(capabilitiesFromServiceKind("image")).toMatchObject({ imageOutput: true });
+    expect(capabilitiesFromServiceKind("stt")).toMatchObject({ audioInput: true });
+    expect(capabilitiesFromServiceKind("tts")).toMatchObject({ audioOutput: true });
+  });
+});
diff --git a/tests/unit/capabilities.test.js b/tests/unit/capabilities.test.js
new file mode 100644
index 0000000..31512e9
--- /dev/null
+++ b/tests/unit/capabilities.test.js
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { getCapabilitiesForModel } from "../../open-sse/providers/capabilities.js";
+
+describe("getCapabilitiesForModel", () => {
+  const claudeSonnet5Expected = {
+    contextWindow: 1000000,
+    maxOutput: 128000,
+    thinkingFormat: "claude-adaptive",
+    reasoning: true,
+    vision: true,
+    search: true,
+  };
+
+  it("reports Kiro Claude Opus 4.8 as a 1M context model", () => {
+    expect(getCapabilitiesForModel("kiro", "claude-opus-4.8").contextWindow).toBe(1000000);
+    expect(getCapabilitiesForModel("kiro", "anthropic/claude-opus-4.8").contextWindow).toBe(1000000);
+    expect(getCapabilitiesForModel("kiro", "claude-opus-4-8").contextWindow).toBe(1000000);
+    expect(getCapabilitiesForModel("kiro", "claude-opus-4.8-thinking").contextWindow).toBe(1000000);
+    expect(getCapabilitiesForModel("kiro", "claude-opus-4-8-thinking").contextWindow).toBe(1000000);
+  });
+
+  it("reports Kiro Claude Sonnet 5 as a 1M adaptive-thinking model", () => {
+    expect(getCapabilitiesForModel("kiro", "claude-sonnet-5")).toMatchObject(claudeSonnet5Expected);
+    expect(getCapabilitiesForModel("kiro", "anthropic/claude-sonnet-5")).toMatchObject(claudeSonnet5Expected);
+    expect(getCapabilitiesForModel("kiro", "claude-sonnet-5-thinking")).toMatchObject(claudeSonnet5Expected);
+    expect(getCapabilitiesForModel("kiro", "claude-sonnet-5-agentic")).toMatchObject(claudeSonnet5Expected);
+    expect(getCapabilitiesForModel("kiro", "claude-sonnet-5-thinking-agentic")).toMatchObject(claudeSonnet5Expected);
+  });
+});
diff --git a/tests/unit/caveman-prompts.test.js b/tests/unit/caveman-prompts.test.js
new file mode 100644
index 0000000..0b92dc8
--- /dev/null
+++ b/tests/unit/caveman-prompts.test.js
@@ -0,0 +1,79 @@
+import { describe, it, expect } from "vitest";
+import { CAVEMAN_LEVELS, CAVEMAN_PROMPTS } from "../../open-sse/rtk/cavemanPrompts.js";
+
+const LEVEL_KEYS = [
+  CAVEMAN_LEVELS.LITE,
+  CAVEMAN_LEVELS.FULL,
+  CAVEMAN_LEVELS.ULTRA,
+  CAVEMAN_LEVELS.WENYAN_LITE,
+  CAVEMAN_LEVELS.WENYAN,
+  CAVEMAN_LEVELS.WENYAN_ULTRA,
+];
+
+describe("Caveman prompt coverage", () => {
+  it("every level key has matching prompt and vice versa", () => {
+    const levelValues = Object.values(CAVEMAN_LEVELS);
+    for (const key of LEVEL_KEYS) {
+      expect(levelValues).toContain(key);
+    }
+    for (const value of levelValues) {
+      expect(LEVEL_KEYS).toContain(value);
+    }
+  });
+
+  it("has a prompt string for every level", () => {
+    for (const level of LEVEL_KEYS) {
+      expect(typeof CAVEMAN_PROMPTS[level]).toBe("string");
+      expect(CAVEMAN_PROMPTS[level].length).toBeGreaterThan(0);
+    }
+  });
+
+  it("adds no-invented-abbreviations guidance to every level", () => {
+    for (const level of LEVEL_KEYS) {
+      expect(CAVEMAN_PROMPTS[level]).toContain("No invented abbreviations");
+    }
+  });
+
+  it("adds preserve-user-language guidance to every level", () => {
+    for (const level of LEVEL_KEYS) {
+      expect(CAVEMAN_PROMPTS[level]).toContain("Preserve the user's dominant language");
+    }
+  });
+
+  it("adds no-self-reference guidance to every level", () => {
+    for (const level of LEVEL_KEYS) {
+      expect(CAVEMAN_PROMPTS[level]).toContain("No self-reference");
+    }
+  });
+
+  it("adds no-decorative-emoji guidance to every level", () => {
+    for (const level of LEVEL_KEYS) {
+      expect(CAVEMAN_PROMPTS[level]).toContain("No decorative emoji");
+    }
+  });
+});
+
+describe("Caveman internal consistency", () => {
+  it("no level uses Unicode arrow (SHARED_NO_DECORATION bans arrow shorthand)", () => {
+    // SHARED_NO_DECORATION uses ASCII -> to quote the banned pattern.
+    // Unicode → is the character old ULTRA used in "Pattern: [thing] → [result]".
+    // Verify no level now uses it.
+    for (const level of LEVEL_KEYS) {
+      expect(CAVEMAN_PROMPTS[level]).not.toContain("→");
+    }
+  });
+});
+
+describe("Caveman ULTRA targeted sync", () => {
+  it("does not encourage invented abbreviations", () => {
+    const ultra = CAVEMAN_PROMPTS[CAVEMAN_LEVELS.ULTRA];
+    expect(ultra).not.toContain("req/res/fn/impl");
+    expect(ultra).not.toContain("Abbreviate (DB/auth/config/req/res/fn/impl)");
+  });
+
+  it("does not encourage arrow shorthand", () => {
+    const ultra = CAVEMAN_PROMPTS[CAVEMAN_LEVELS.ULTRA];
+    expect(ultra).not.toContain("use arrows for causality");
+    expect(ultra).not.toContain("X → Y");
+  });
+});
diff --git a/tests/unit/claude-cloaking.test.js b/tests/unit/claude-cloaking.test.js
new file mode 100644
index 0000000..6b6e5dc
--- /dev/null
+++ b/tests/unit/claude-cloaking.test.js
@@ -0,0 +1,76 @@
+/**
+ * Unit tests for open-sse/utils/claudeCloaking.js
+ *
+ * Tests cover:
+ *  - cloakClaudeTools() - tool renaming and forced tool_choice suffixing
+ */
+
+import { describe, it, expect } from "vitest";
+import { cloakClaudeTools } from "../../open-sse/utils/claudeCloaking.js";
+import { CLAUDE_TOOL_SUFFIX } from "../../open-sse/config/appConstants.js";
+
+describe("cloakClaudeTools", () => {
+  const baseBody = {
+    tools: [{ name: "todo_write", description: "write todos", input_schema: { type: "object", properties: {} } }],
+    messages: [{ role: "user", content: [{ type: "text", text: "add a todo" }] }]
+  };
+
+  it("suffixes client tool names and maps them back", () => {
+    const { body, toolNameMap } = cloakClaudeTools(baseBody);
+    const suffixed = `todo_write${CLAUDE_TOOL_SUFFIX}`;
+    expect(body.tools.find(t => t.name === suffixed)).toBeDefined();
+    expect(toolNameMap.get(suffixed)).toBe("todo_write");
+  });
+
+  it("suffixes a forced tool_choice to match the renamed tool", () => {
+    const { body } = cloakClaudeTools({
+      ...baseBody,
+      tool_choice: { type: "tool", name: "todo_write" }
+    });
+    // Without this, Claude rejects: "Tool 'todo_write' not found in provided tools".
+    expect(body.tool_choice).toEqual({ type: "tool", name: `todo_write${CLAUDE_TOOL_SUFFIX}` });
+  });
+
+  it("suffixes only the chosen tool when several are present", () => {
+    const { body } = cloakClaudeTools({
+      tools: [
+        { name: "search", input_schema: { type: "object", properties: {} } },
+        { name: "todo_write", input_schema: { type: "object", properties: {} } }
+      ],
+      tool_choice: { type: "tool", name: "todo_write" }
+    });
+    expect(body.tool_choice).toEqual({ type: "tool", name: `todo_write${CLAUDE_TOOL_SUFFIX}` });
+  });
+
+  it("leaves non-forced tool_choice untouched", () => {
+    const auto = cloakClaudeTools({ ...baseBody, tool_choice: { type: "auto" } });
+    expect(auto.body.tool_choice).toEqual({ type: "auto" });
+
+    const none = cloakClaudeTools({ ...baseBody });
+    expect(none.body.tool_choice).toBeUndefined();
+  });
+
+  it("does not suffix a forced choice that targets a non-client (decoy/built-in) tool", () => {
+    // "Bash" is an injected decoy sent unsuffixed; forcing it must stay as-is.
+    const { body } = cloakClaudeTools({ ...baseBody, tool_choice: { type: "tool", name: "Bash" } });
+    expect(body.tool_choice).toEqual({ type: "tool", name: "Bash" });
+  });
+
+  it("renames tool_use names in message history", () => {
+    const { body } = cloakClaudeTools({
+      ...baseBody,
+      messages: [
+        { role: "assistant", content: [{ type: "tool_use", id: "t1", name: "todo_write", input: {} }] }
+      ]
+    });
+    const block = body.messages[0].content[0];
+    expect(block.name).toBe(`todo_write${CLAUDE_TOOL_SUFFIX}`);
+  });
+
+  it("returns the body unchanged when there are no tools", () => {
+    const input = { messages: [{ role: "user", content: "hi" }], tool_choice: { type: "tool", name: "x" } };
+    const { body, toolNameMap } = cloakClaudeTools(input);
+    expect(body).toBe(input);
+    expect(toolNameMap).toBeNull();
+  });
+});
diff --git a/tests/unit/claude-header-forwarding.test.js b/tests/unit/claude-header-forwarding.test.js
new file mode 100644
index 0000000..acad66a
--- /dev/null
+++ b/tests/unit/claude-header-forwarding.test.js
@@ -0,0 +1,417 @@
+/**
+ * Unit tests for Anthropic header caching + forwarding pipeline
+ *
+ * Tests cover:
+ *  - claudeHeaderCache: detection, capture, and retrieval of Claude Code headers
+ *  - default.js buildHeaders(): live header overlay for "claude" provider
+ *  - default.js buildHeaders(): cold-start fallback when cache is empty
+ *  - default.js buildHeaders(): anthropic-compatible non-Anthropic host stripping
+ *  - default.js buildHeaders(): anthropic-compatible official host keeps headers
+ *  - proxyFetch.js: api.anthropic.com routes through anthropicFetch path
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// ─── claudeHeaderCache ────────────────────────────────────────────────────────
+
+describe("claudeHeaderCache", () => {
+  let cacheModule;
+
+  beforeEach(async () => {
+    // Re-import fresh module each time to reset singleton state
+    vi.resetModules();
+    cacheModule = await import("open-sse/utils/claudeHeaderCache.js");
+  });
+
+  it("returns null before any headers are cached (cold start)", () => {
+    expect(cacheModule.getCachedClaudeHeaders()).toBeNull();
+  });
+
+  it("caches headers when user-agent contains 'claude-code'", () => {
+    cacheModule.cacheClaudeHeaders({
+      "user-agent": "claude-code/2.1.63 node/24.3.0",
+      "anthropic-beta": "claude-code-20250219,oauth-2025-04-20",
+      "anthropic-version": "2023-06-01",
+      "x-app": "cli",
+      "x-stainless-os": "MacOS",
+      "x-stainless-arch": "arm64",
+      "x-stainless-lang": "js",
+      "x-stainless-runtime": "node",
+      "x-stainless-runtime-version": "v24.3.0",
+      "x-stainless-package-version": "0.74.0",
+      "x-stainless-helper-method": "stream",
+      "x-stainless-retry-count": "0",
+      "x-stainless-timeout": "600",
+      "anthropic-dangerous-direct-browser-access": "true",
+      // Non-identity header — should NOT be captured
+      "content-type": "application/json",
+    });
+
+    const cached = cacheModule.getCachedClaudeHeaders();
+    expect(cached).not.toBeNull();
+    expect(cached["user-agent"]).toBe("claude-code/2.1.63 node/24.3.0");
+    expect(cached["anthropic-beta"]).toBe("claude-code-20250219,oauth-2025-04-20");
+    expect(cached["x-app"]).toBe("cli");
+    expect(cached["x-stainless-os"]).toBe("MacOS");
+    // Non-identity header must not leak in
+    expect(cached["content-type"]).toBeUndefined();
+  });
+
+  it("caches headers when user-agent contains 'claude-cli'", () => {
+    cacheModule.cacheClaudeHeaders({
+      "user-agent": "claude-cli/1.0.0",
+      "anthropic-version": "2023-06-01",
+    });
+    expect(cacheModule.getCachedClaudeHeaders()).not.toBeNull();
+    expect(cacheModule.getCachedClaudeHeaders()["user-agent"]).toBe("claude-cli/1.0.0");
+  });
+
+  it("caches headers when x-app is 'cli' (regardless of user-agent)", () => {
+    cacheModule.cacheClaudeHeaders({
+      "user-agent": "axios/1.7.0",
+      "x-app": "cli",
+      "anthropic-version": "2023-06-01",
+    });
+    expect(cacheModule.getCachedClaudeHeaders()).not.toBeNull();
+  });
+
+  it("does NOT cache headers for non-Claude clients", () => {
+    cacheModule.cacheClaudeHeaders({
+      "user-agent": "PostmanRuntime/7.43.0",
+      "anthropic-version": "2023-06-01",
+    });
+    expect(cacheModule.getCachedClaudeHeaders()).toBeNull();
+  });
+
+  it("refreshes cache on each matching request", () => {
+    cacheModule.cacheClaudeHeaders({
+      "user-agent": "claude-code/2.0.0",
+      "x-stainless-package-version": "0.70.0",
+    });
+    cacheModule.cacheClaudeHeaders({
+      "user-agent": "claude-code/2.1.63",
+      "x-stainless-package-version": "0.74.0",
+    });
+    const cached = cacheModule.getCachedClaudeHeaders();
+    expect(cached["user-agent"]).toBe("claude-code/2.1.63");
+    expect(cached["x-stainless-package-version"]).toBe("0.74.0");
+  });
+
+  it("ignores calls with null or non-object headers", () => {
+    cacheModule.cacheClaudeHeaders(null);
+    cacheModule.cacheClaudeHeaders(undefined);
+    cacheModule.cacheClaudeHeaders("string");
+    expect(cacheModule.getCachedClaudeHeaders()).toBeNull();
+  });
+
+  it("only stores keys that are actually present in the headers object", () => {
+    cacheModule.cacheClaudeHeaders({
+      "user-agent": "claude-code/2.1.63",
+      // Most stainless headers absent
+    });
+    const cached = cacheModule.getCachedClaudeHeaders();
+    expect(cached["x-stainless-os"]).toBeUndefined();
+    expect(cached["user-agent"]).toBe("claude-code/2.1.63");
+  });
+});
+
+// ─── DefaultExecutor.buildHeaders() ──────────────────────────────────────────
+
+describe("DefaultExecutor.buildHeaders() — claude provider", () => {
+  let DefaultExecutor;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    // Prime the cache with live client headers before importing executor
+    const cache = await import("open-sse/utils/claudeHeaderCache.js");
+    cache.cacheClaudeHeaders({
+      "user-agent": "claude-code/2.1.63 node/24.3.0",
+      "anthropic-beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14",
+      "anthropic-version": "2023-06-01",
+      "anthropic-dangerous-direct-browser-access": "true",
+      "x-app": "cli",
+      "x-stainless-os": "MacOS",
+      "x-stainless-arch": "arm64",
+      "x-stainless-lang": "js",
+      "x-stainless-runtime": "node",
+      "x-stainless-runtime-version": "v24.3.0",
+      "x-stainless-package-version": "0.74.0",
+      "x-stainless-helper-method": "stream",
+      "x-stainless-retry-count": "0",
+      "x-stainless-timeout": "600",
+    });
+    const mod = await import("open-sse/executors/default.js");
+    DefaultExecutor = mod.DefaultExecutor || mod.default;
+  });
+
+  it("overlays live cached headers over static provider defaults", () => {
+    const executor = new DefaultExecutor("claude");
+    const headers = executor.buildHeaders({ apiKey: "sk-test" }, true);
+
+    // Live values should win over static providers.js values
+    expect(headers["user-agent"]).toBe("claude-code/2.1.63 node/24.3.0");
+    // Beta flags are MERGED (static + cached) to preserve required flags like oauth
+    const betaFlags = headers["anthropic-beta"].split(",").map(s => s.trim());
+    expect(betaFlags).toContain("claude-code-20250219");
+    expect(betaFlags).toContain("oauth-2025-04-20");
+    expect(betaFlags).toContain("interleaved-thinking-2025-05-14");
+    expect(headers["x-stainless-package-version"]).toBe("0.74.0");
+    expect(headers["x-stainless-os"]).toBe("MacOS");
+  });
+
+  it("removes conflicting Title-Case static keys when cached lowercase keys exist", () => {
+    const executor = new DefaultExecutor("claude");
+    const headers = executor.buildHeaders({ apiKey: "sk-test" }, true);
+
+    // Title-Case variants from providers.js must be gone
+    expect(headers["Anthropic-Version"]).toBeUndefined();
+    expect(headers["Anthropic-Beta"]).toBeUndefined();
+    expect(headers["User-Agent"]).toBeUndefined();
+    expect(headers["X-App"]).toBeUndefined();
+    // Lowercase variants must be present
+    expect(headers["anthropic-version"]).toBe("2023-06-01");
+    expect(headers["x-app"]).toBe("cli");
+  });
+
+  it("sets x-api-key auth when apiKey is provided", () => {
+    const executor = new DefaultExecutor("claude");
+    const headers = executor.buildHeaders({ apiKey: "sk-live-key" }, true);
+    expect(headers["x-api-key"]).toBe("sk-live-key");
+    expect(headers["Authorization"]).toBeUndefined();
+  });
+
+  it("sets Bearer Authorization when only accessToken is provided", () => {
+    const executor = new DefaultExecutor("claude");
+    const headers = executor.buildHeaders({ accessToken: "tok-abc" }, true);
+    expect(headers["Authorization"]).toBe("Bearer tok-abc");
+    expect(headers["x-api-key"]).toBeUndefined();
+  });
+
+  it("includes Accept: text/event-stream when stream=true", () => {
+    const executor = new DefaultExecutor("claude");
+    const headers = executor.buildHeaders({ apiKey: "k" }, true);
+    expect(headers["Accept"]).toBe("text/event-stream");
+  });
+
+  it("omits Accept: text/event-stream when stream=false", () => {
+    const executor = new DefaultExecutor("claude");
+    const headers = executor.buildHeaders({ apiKey: "k" }, false);
+    expect(headers["Accept"]).toBeUndefined();
+  });
+});
+
+describe("DefaultExecutor.buildHeaders() — claude provider cold start (no cache)", () => {
+  let DefaultExecutor;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    // Do NOT prime cache — simulate cold start
+    const mod = await import("open-sse/executors/default.js");
+    DefaultExecutor = mod.DefaultExecutor || mod.default;
+  });
+
+  it("falls back to static provider headers when cache is empty", () => {
+    const executor = new DefaultExecutor("claude");
+    const headers = executor.buildHeaders({ apiKey: "sk-test" }, true);
+
+    // Static fallback values from providers.js must still be present
+    // They may be Title-Case since no cache to conflict with them
+    const hasVersion =
+      headers["Anthropic-Version"] === "2023-06-01" ||
+      headers["anthropic-version"] === "2023-06-01";
+    expect(hasVersion).toBe(true);
+  });
+
+  it("does not throw when cache returns null", () => {
+    const executor = new DefaultExecutor("claude");
+    expect(() => executor.buildHeaders({ apiKey: "sk" }, false)).not.toThrow();
+  });
+});
+
+// ─── anthropic-compatible header stripping ────────────────────────────────────
+
+describe("DefaultExecutor.buildHeaders() — anthropic-compatible stripping", () => {
+  let DefaultExecutor;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    const mod = await import("open-sse/executors/default.js");
+    DefaultExecutor = mod.DefaultExecutor || mod.default;
+  });
+
+  it("strips x-app and anthropic-dangerous-direct-browser-access for non-Anthropic host", () => {
+    const executor = new DefaultExecutor("anthropic-compatible-custom");
+    const headers = executor.buildHeaders(
+      {
+        apiKey: "key",
+        providerSpecificData: { baseUrl: "https://myproxy.example.com/v1" },
+      },
+      true
+    );
+
+    expect(headers["x-app"]).toBeUndefined();
+    expect(headers["X-App"]).toBeUndefined();
+    expect(headers["anthropic-dangerous-direct-browser-access"]).toBeUndefined();
+    expect(headers["Anthropic-Dangerous-Direct-Browser-Access"]).toBeUndefined();
+  });
+
+  it("removes claude-code-20250219 from anthropic-beta for non-Anthropic host", () => {
+    const executor = new DefaultExecutor("anthropic-compatible-custom");
+    const headers = executor.buildHeaders(
+      {
+        apiKey: "key",
+        providerSpecificData: { baseUrl: "https://myproxy.example.com/v1" },
+      },
+      true
+    );
+
+    const betaVal = headers["anthropic-beta"] || headers["Anthropic-Beta"] || "";
+    expect(betaVal).not.toContain("claude-code-20250219");
+  });
+
+  it("keeps other beta flags intact after stripping", () => {
+    const executor = new DefaultExecutor("anthropic-compatible-custom");
+    // The static CLAUDE_API_HEADERS used by anthropic-compatible providers include
+    // 'interleaved-thinking-2025-05-14' — check it survives stripping
+    const headers = executor.buildHeaders(
+      {
+        apiKey: "key",
+        providerSpecificData: { baseUrl: "https://myproxy.example.com/v1" },
+      },
+      false
+    );
+
+    const betaVal = headers["anthropic-beta"] || headers["Anthropic-Beta"] || "";
+    // If any beta value remains it should not be empty and should not have the stripped value
+    if (betaVal) {
+      expect(betaVal).not.toContain("claude-code-20250219");
+    }
+  });
+
+  it("does NOT strip headers when baseUrl is api.anthropic.com", () => {
+    const executor = new DefaultExecutor("anthropic-compatible-official");
+    const headers = executor.buildHeaders(
+      {
+        apiKey: "key",
+        providerSpecificData: { baseUrl: "https://api.anthropic.com/v1" },
+      },
+      true
+    );
+
+    // No stripping — anthropic-version should survive
+    const hasVersion =
+      headers["Anthropic-Version"] || headers["anthropic-version"];
+    expect(hasVersion).toBeDefined();
+  });
+
+  it("does NOT strip headers when baseUrl is empty (defaults to Anthropic)", () => {
+    const executor = new DefaultExecutor("anthropic-compatible-official");
+    const headers = executor.buildHeaders(
+      {
+        apiKey: "key",
+        providerSpecificData: {},
+      },
+      true
+    );
+
+    const hasVersion =
+      headers["Anthropic-Version"] || headers["anthropic-version"];
+    expect(hasVersion).toBeDefined();
+  });
+});
+
+// ─── proxyFetch anthropicFetch routing ────────────────────────────────────────
+
+describe("proxyAwareFetch — api.anthropic.com routing", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("routes api.anthropic.com to gotScraping (non-streaming) and returns ok response", async () => {
+    // Mock got-scraping before module load
+    vi.doMock("got-scraping", () => {
+      const mockGotScraping = vi.fn().mockResolvedValue({
+        statusCode: 200,
+        statusMessage: "OK",
+        headers: { "content-type": "application/json" },
+        rawBody: Buffer.from(JSON.stringify({ id: "msg_test" })),
+      });
+      mockGotScraping.stream = vi.fn();
+      return { gotScraping: mockGotScraping };
+    });
+
+    vi.resetModules();
+    const { proxyAwareFetch } = await import("open-sse/utils/proxyFetch.js");
+    const { gotScraping } = await import("got-scraping");
+
+    const res = await proxyAwareFetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      // No Accept: text/event-stream → non-streaming path
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ model: "claude-3-5-sonnet-20241022", messages: [] }),
+    });
+
+    expect(gotScraping).toHaveBeenCalledOnce();
+    expect(res.ok).toBe(true);
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data.id).toBe("msg_test");
+  });
+
+  it("falls back gracefully when got-scraping throws on non-streaming path", async () => {
+    vi.doMock("got-scraping", () => {
+      const fn = vi.fn().mockRejectedValue(new Error("TLS error"));
+      fn.stream = vi.fn();
+      return { gotScraping: fn };
+    });
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: "OK",
+      headers: new Headers(),
+      body: null,
+      text: async () => "{}",
+      json: async () => ({}),
+    });
+
+    vi.resetModules();
+    const { proxyAwareFetch } = await import("open-sse/utils/proxyFetch.js");
+
+    const res = await proxyAwareFetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "{}",
+    });
+
+    expect(res.ok).toBe(true);
+    globalThis.fetch = originalFetch;
+  });
+
+  it("does NOT route non-Anthropic hosts through gotScraping", async () => {
+    const gotScrapingMock = vi.fn();
+    vi.doMock("got-scraping", () => ({ gotScraping: gotScrapingMock }));
+
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: "OK",
+      headers: new Headers(),
+      body: null,
+      text: async () => "{}",
+      json: async () => ({}),
+    });
+
+    vi.resetModules();
+    const { proxyAwareFetch } = await import("open-sse/utils/proxyFetch.js");
+
+    await proxyAwareFetch("https://openrouter.ai/api/v1/chat/completions", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "{}",
+    });
+
+    expect(gotScrapingMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/unit/codebuddy-cn-bonus-recurring.test.js b/tests/unit/codebuddy-cn-bonus-recurring.test.js
new file mode 100644
index 0000000..7d75942
--- /dev/null
+++ b/tests/unit/codebuddy-cn-bonus-recurring.test.js
@@ -0,0 +1,30 @@
+// CodeBuddy CN mixes recurring refill packs with one-shot bonus packs.
+// Bonus packs ("Bonus Pack N") must surface recurring:false so the dashboard
+// shows "Expires in" instead of implying a monthly refill. The usage handler
+// tags the flag and parseQuotaData must forward it.
+import { describe, it, expect } from "vitest";
+import { parseQuotaData } from "@/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.js";
+
+describe("parseQuotaData codebuddy-cn recurring flag", () => {
+  it("forwards recurring:false for bonus packs and true for refill packs", () => {
+    const data = {
+      plan: "CodeBuddy CN",
+      quotas: {
+        Monthly: { used: 6.54, total: 500, resetAt: "2026-07-31T00:00:00Z", recurring: true },
+        "Bonus Pack 1": { used: 12, total: 100, resetAt: "2026-07-15T00:00:00Z", recurring: false },
+      },
+    };
+
+    const out = parseQuotaData("codebuddy-cn", data);
+    const byName = Object.fromEntries(out.map((q) => [q.name, q]));
+
+    expect(byName["Monthly"].recurring).toBe(true);
+    expect(byName["Bonus Pack 1"].recurring).toBe(false);
+  });
+
+  it("defaults recurring to true when the flag is absent (back-compat)", () => {
+    const data = { quotas: { Monthly: { used: 0, total: 100, resetAt: null } } };
+    const out = parseQuotaData("codebuddy-cn", data);
+    expect(out[0].recurring).toBe(true);
+  });
+});
diff --git a/tests/unit/codebuddy-reasoning-optin.test.js b/tests/unit/codebuddy-reasoning-optin.test.js
new file mode 100644
index 0000000..1bfaf15
--- /dev/null
+++ b/tests/unit/codebuddy-reasoning-optin.test.js
@@ -0,0 +1,37 @@
+// #2071 — CodeBuddy forced reasoning_effort:"medium" + reasoning_summary:"auto"
+// on requests where the client never asked for reasoning, tripping CodeBuddy's
+// content filter ("model return error"). Reasoning params must be opt-in.
+import { describe, it, expect } from "vitest";
+import { CodeBuddyExecutor } from "../../open-sse/executors/codebuddy-cn.js";
+
+describe("CodeBuddyExecutor reasoning params are opt-in (#2071)", () => {
+  const exec = new CodeBuddyExecutor();
+
+  it("does NOT force reasoning when the client did not request it", () => {
+    const out = exec.transformRequest("glm-5.2", { messages: [{ role: "user", content: "hi" }] }, false, {});
+    expect(out.reasoning_effort).toBeUndefined();
+    expect(out.reasoning_summary).toBeUndefined();
+  });
+
+  it("mirrors reasoning_summary:auto when the client explicitly requested reasoning", () => {
+    const out = exec.transformRequest(
+      "glm-5.2",
+      { messages: [{ role: "user", content: "hi" }], reasoning_effort: "high" },
+      false,
+      {}
+    );
+    expect(out.reasoning_effort).toBe("high");
+    expect(out.reasoning_summary).toBe("auto");
+  });
+
+  it("omits reasoning_effort for none/off and adds no reasoning_summary", () => {
+    const out = exec.transformRequest(
+      "glm-5.2",
+      { messages: [{ role: "user", content: "hi" }], reasoning_effort: "none" },
+      false,
+      {}
+    );
+    expect(out.reasoning_effort).toBeUndefined();
+    expect(out.reasoning_summary).toBeUndefined();
+  });
+});
diff --git a/tests/unit/codex-fast-capacity.test.js b/tests/unit/codex-fast-capacity.test.js
new file mode 100644
index 0000000..aad8528
--- /dev/null
+++ b/tests/unit/codex-fast-capacity.test.js
@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { CodexExecutor } from "../../open-sse/executors/codex.js";
+
+function streamFromText(text) {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(encoder.encode(text));
+      controller.close();
+    },
+  });
+}
+
+describe("Codex fast tier and capacity handling", () => {
+  it("maps Codex fast tier to priority and max reasoning to xhigh", () => {
+    const executor = new CodexExecutor();
+    const body = executor.transformRequest("gpt-5.5", {
+      model: "gpt-5.5",
+      input: "hi",
+      reasoning_effort: "max",
+      service_tier: "fast",
+    }, true, {});
+
+    expect(body.service_tier).toBe("priority");
+    expect(body.reasoning.effort).toBe("xhigh");
+  });
+
+  it("uses ChatGPT workspace header fallback", () => {
+    const executor = new CodexExecutor();
+    const headers = executor.buildHeaders({
+      accessToken: "token",
+      connectionId: "conn_1",
+      providerSpecificData: { chatgptAccountId: "acct_1" },
+    });
+
+    expect(headers["ChatGPT-Account-ID"]).toBe("acct_1");
+  });
+
+  it("classifies 200-SSE model capacity as account fallback", async () => {
+    const executor = new CodexExecutor();
+    const response = new Response(streamFromText([
+      "event: error",
+      'data: {"error":{"message":"Selected model is at capacity. Please try a different model."}}',
+      "",
+    ].join("\n")), {
+      status: 200,
+      headers: { "Content-Type": "text/event-stream" },
+    });
+
+    const peek = await executor._peekSseTransientError(response);
+    expect(peek.accountFallback).toBe(true);
+    expect(peek.message).toBe("Selected model is at capacity. Please try a different model.");
+  });
+
+  it("reassembles normal SSE after peeking", async () => {
+    const executor = new CodexExecutor();
+    const text = [
+      "event: response.output_text.delta",
+      'data: {"type":"response.output_text.delta","delta":"OK"}',
+      "",
+    ].join("\n");
+    const response = new Response(streamFromText(text), {
+      status: 200,
+      headers: { "Content-Type": "text/event-stream" },
+    });
+
+    const peek = await executor._peekSseTransientError(response);
+    expect(peek.matched).toBeNull();
+    await expect(new Response(peek.replacementBody).text()).resolves.toBe(text);
+  });
+});
diff --git a/tests/unit/codex-image-fetch.test.js b/tests/unit/codex-image-fetch.test.js
new file mode 100644
index 0000000..d50614a
--- /dev/null
+++ b/tests/unit/codex-image-fetch.test.js
@@ -0,0 +1,161 @@
+/**
+ * Codex executor: verify remote image URLs are fetched and inlined as
+ * base64 data URIs BEFORE the request body reaches the upstream API.
+ *
+ * Covers bug #575:
+ *  - prefetchImages must await async image fetches
+ *  - execute() must run prefetchImages before super.execute so the body
+ *    sent to upstream contains base64 data, not remote URLs
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+// Mock DNS so the SSRF guard treats example.com as public.
+vi.mock("node:dns/promises", () => ({ lookup: async () => ({ address: "93.184.216.34" }) }));
+
+import { CodexExecutor } from "../../open-sse/executors/codex.js";
+import * as proxyFetchModule from "../../open-sse/utils/proxyFetch.js";
+
+const IMAGE_1MB_BYTES = 1024 * 1024;
+const REMOTE_URL = "https://example.com/big.jpg";
+const DATA_URI = "data:image/png;base64,iVBORw0KGgo=";
+// JPEG magic bytes (FF D8 FF) so magic-byte verification passes.
+const JPEG_MAGIC = [0xff, 0xd8, 0xff];
+
+function makeImageBuffer(sizeBytes) {
+  const buf = new Uint8Array(sizeBytes);
+  for (let i = 0; i < JPEG_MAGIC.length; i++) buf[i] = JPEG_MAGIC[i];
+  for (let i = JPEG_MAGIC.length; i < sizeBytes; i++) buf[i] = i & 0xff;
+  return buf;
+}
+
+// Mock a streaming Response body (getReader) as the hardened fetcher expects.
+function mockImageFetch(sizeBytes) {
+  const bytes = makeImageBuffer(sizeBytes);
+  return {
+    ok: true,
+    body: {
+      getReader() {
+        let sent = false;
+        return {
+          read: async () => sent ? { done: true } : (sent = true, { done: false, value: bytes }),
+          cancel: async () => {},
+        };
+      },
+    },
+  };
+}
+
+describe("CodexExecutor image handling", () => {
+  let originalFetch;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  it("fetches 1MB remote image and inlines it as base64 data URI", async () => {
+    global.fetch = vi.fn(async () => mockImageFetch(IMAGE_1MB_BYTES));
+
+    const executor = new CodexExecutor();
+    const body = {
+      input: [
+        {
+          role: "user",
+          content: [
+            { type: "input_text", text: "describe this" },
+            { type: "image_url", image_url: { url: REMOTE_URL, detail: "high" } },
+          ],
+        },
+      ],
+    };
+
+    await executor.prefetchImages(body);
+
+    const imgBlock = body.input[0].content.find((c) => c.type === "input_image");
+    expect(imgBlock, "input_image block must be present after prefetch").toBeDefined();
+    expect(imgBlock.image_url.startsWith("data:image/jpeg;base64,")).toBe(true);
+    expect(imgBlock.detail).toBe("high");
+
+    const base64Payload = imgBlock.image_url.split(",")[1];
+    const decodedLen = Buffer.from(base64Payload, "base64").length;
+    expect(decodedLen).toBe(IMAGE_1MB_BYTES);
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes through existing data URIs without calling fetch", async () => {
+    global.fetch = vi.fn();
+
+    const executor = new CodexExecutor();
+    const body = {
+      input: [
+        {
+          role: "user",
+          content: [{ type: "image_url", image_url: { url: DATA_URI } }],
+        },
+      ],
+    };
+
+    await executor.prefetchImages(body);
+
+    const imgBlock = body.input[0].content.find((c) => c.type === "input_image");
+    expect(imgBlock.image_url).toBe(DATA_URI);
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it("falls back to original URL when remote fetch fails", async () => {
+    global.fetch = vi.fn(async () => { throw new Error("network down"); });
+
+    const executor = new CodexExecutor();
+    const body = {
+      input: [
+        {
+          role: "user",
+          content: [{ type: "image_url", image_url: { url: REMOTE_URL } }],
+        },
+      ],
+    };
+
+    await executor.prefetchImages(body);
+
+    const imgBlock = body.input[0].content.find((c) => c.type === "input_image");
+    expect(imgBlock.image_url).toBe(REMOTE_URL);
+  });
+
+  it("execute() prefetches images before sending to upstream", async () => {
+    global.fetch = vi.fn(async () => mockImageFetch(IMAGE_1MB_BYTES));
+
+    let capturedBodyString = null;
+    vi.spyOn(proxyFetchModule, "proxyAwareFetch").mockImplementation(async (url, init) => {
+      capturedBodyString = init.body;
+      return { ok: true, status: 200, headers: new Map() };
+    });
+
+    const executor = new CodexExecutor();
+    const body = {
+      input: [
+        {
+          role: "user",
+          content: [{ type: "image_url", image_url: { url: REMOTE_URL } }],
+        },
+      ],
+    };
+
+    await executor.execute({
+      model: "gpt-5.3-codex",
+      body,
+      stream: true,
+      credentials: { accessToken: "test" },
+    });
+
+    expect(capturedBodyString).toBeTypeOf("string");
+    expect(capturedBodyString).not.toBe("{}");
+    const parsed = JSON.parse(capturedBodyString);
+    const imgBlock = parsed.input[0].content.find((c) => c.type === "input_image");
+    expect(imgBlock.image_url.startsWith("data:image/jpeg;base64,")).toBe(true);
+  });
+});
diff --git a/tests/unit/codex-refresh-token.test.js b/tests/unit/codex-refresh-token.test.js
new file mode 100644
index 0000000..3b702af
--- /dev/null
+++ b/tests/unit/codex-refresh-token.test.js
@@ -0,0 +1,172 @@
+/**
+ * Unit tests for Codex (OpenAI) refresh token mechanism
+ *
+ * Verifies that:
+ * - Early refresh lead times are configured per provider (synced with CLIProxyAPI)
+ * - New refresh_token from response is persisted (token rotation)
+ * - Falls back to old refresh_token when server doesn't return new one
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+const originalFetch = global.fetch;
+
+describe("Codex Refresh Token", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+    global.fetch = originalFetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  function mockFetchWithJson(payload) {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(payload),
+    });
+    global.fetch = fetchMock;
+    return fetchMock;
+  }
+
+  describe("refreshCodexToken", () => {
+    it("should return new refresh_token when server provides one (token rotation)", async () => {
+      const fetchMock = mockFetchWithJson({
+          access_token: "new-access",
+          refresh_token: "rotated-refresh-token",
+          id_token: "new-id-token",
+          expires_in: 3600,
+      });
+
+      const { refreshCodexToken } = await import("../../open-sse/services/tokenRefresh.js");
+      const result = await refreshCodexToken("old-refresh-token", null);
+
+      expect(result.refreshToken).toBe("rotated-refresh-token");
+      expect(result.accessToken).toBe("new-access");
+      expect(result.idToken).toBe("new-id-token");
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://auth.openai.com/oauth/token",
+        expect.objectContaining({
+          method: "POST",
+          headers: expect.objectContaining({
+            "Content-Type": "application/json",
+            Accept: "application/json",
+          }),
+          body: JSON.stringify({
+            client_id: "app_EMoamEEZ73f0CkXaXp7hrann",
+            grant_type: "refresh_token",
+            refresh_token: "old-refresh-token",
+          }),
+        })
+      );
+    });
+
+    it("should keep old refresh_token when server does not return new one", async () => {
+      mockFetchWithJson({
+          access_token: "new-access",
+          expires_in: 3600,
+      });
+
+      const { refreshCodexToken } = await import("../../open-sse/services/tokenRefresh.js");
+      const result = await refreshCodexToken("old-refresh-token-without-rotation", null);
+
+      expect(result.refreshToken).toBe("old-refresh-token-without-rotation");
+    });
+  });
+
+  describe("CodexExecutor credential lifecycle", () => {
+    it("should refresh Codex credentials and preserve omitted id_token", async () => {
+      mockFetchWithJson({
+          access_token: "new-access",
+          refresh_token: "rotated-refresh-token",
+          expires_in: 3600,
+      });
+
+      const { CodexExecutor } = await import("../../open-sse/executors/codex.js");
+      const executor = new CodexExecutor();
+      const result = await executor.refreshCredentials({
+        connectionId: "codex-1",
+        refreshToken: "old-refresh-token",
+        idToken: "old-id-token",
+      }, null);
+
+      expect(result.accessToken).toBe("new-access");
+      expect(result.refreshToken).toBe("rotated-refresh-token");
+      expect(result.idToken).toBe("old-id-token");
+      expect(result.lastRefreshAt).toBeTruthy();
+      expect(result.expiresAt).toBeTruthy();
+    });
+
+    it("should refresh Codex when lastRefreshAt is older than the upstream stale window", async () => {
+      const { CodexExecutor } = await import("../../open-sse/executors/codex.js");
+      const executor = new CodexExecutor();
+      const farFuture = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();
+      const staleRefresh = new Date(Date.now() - 9 * 24 * 60 * 60 * 1000).toISOString();
+      const recentRefresh = new Date(Date.now() - 1 * 24 * 60 * 60 * 1000).toISOString();
+
+      expect(executor.needsRefresh({
+        refreshToken: "refresh-token",
+        expiresAt: farFuture,
+        lastRefreshAt: staleRefresh,
+      })).toBe(true);
+
+      expect(executor.needsRefresh({
+        refreshToken: "refresh-token",
+        expiresAt: farFuture,
+        lastRefreshAt: recentRefresh,
+      })).toBe(false);
+    });
+
+    it("should de-duplicate concurrent refreshes for the same Codex connection", async () => {
+      const fetchMock = mockFetchWithJson({
+          access_token: "new-access",
+          refresh_token: "rotated-refresh-token",
+          expires_in: 3600,
+      });
+
+      const { refreshProviderCredentials } = await import("../../open-sse/services/oauthCredentialManager.js");
+      const credentials = {
+        connectionId: "codex-single-flight",
+        refreshToken: "old-refresh-token",
+      };
+
+      const [first, second] = await Promise.all([
+        refreshProviderCredentials("codex", credentials, null),
+        refreshProviderCredentials("codex", credentials, null),
+      ]);
+
+      expect(first.accessToken).toBe("new-access");
+      expect(second.accessToken).toBe("new-access");
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("getRefreshLeadMs (early refresh config)", () => {
+    it("should return provider-specific lead time for OAuth providers", async () => {
+      const { getRefreshLeadMs } = await import("../../open-sse/services/tokenRefresh.js");
+
+      // Synced with CLIProxyAPI refresh_registry
+      expect(getRefreshLeadMs("codex")).toBe(5 * 24 * 60 * 60 * 1000);   // 5 days
+      expect(getRefreshLeadMs("claude")).toBe(4 * 60 * 60 * 1000);       // 4 hours
+      expect(getRefreshLeadMs("iflow")).toBe(24 * 60 * 60 * 1000);       // 24 hours
+      expect(getRefreshLeadMs("qwen")).toBe(20 * 60 * 1000);             // 20 minutes
+      expect(getRefreshLeadMs("kimi-coding")).toBe(5 * 60 * 1000);       // 5 minutes
+      expect(getRefreshLeadMs("antigravity")).toBe(5 * 60 * 1000);       // 5 minutes
+    });
+
+    it("should fallback to default buffer for unknown providers", async () => {
+      const { getRefreshLeadMs, TOKEN_EXPIRY_BUFFER_MS } = await import("../../open-sse/services/tokenRefresh.js");
+
+      expect(getRefreshLeadMs("unknown-provider")).toBe(TOKEN_EXPIRY_BUFFER_MS);
+      expect(getRefreshLeadMs("openai")).toBe(TOKEN_EXPIRY_BUFFER_MS);
+    });
+
+    it("codex lead should be greater than default buffer", async () => {
+      const { getRefreshLeadMs, TOKEN_EXPIRY_BUFFER_MS } = await import("../../open-sse/services/tokenRefresh.js");
+
+      expect(getRefreshLeadMs("codex")).toBeGreaterThan(TOKEN_EXPIRY_BUFFER_MS);
+    });
+  });
+});
diff --git a/tests/unit/codex-reset-credits.test.js b/tests/unit/codex-reset-credits.test.js
new file mode 100644
index 0000000..c8b4c6f
--- /dev/null
+++ b/tests/unit/codex-reset-credits.test.js
@@ -0,0 +1,198 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  proxyAwareFetch: vi.fn(),
+  getProviderConnectionById: vi.fn(),
+  resolveConnectionProxyConfig: vi.fn(),
+  refreshAndUpdateCredentials: vi.fn(),
+  getCodexRateLimitResetCredits: vi.fn(),
+  consumeCodexRateLimitResetCredit: vi.fn(),
+}));
+
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch: mocks.proxyAwareFetch,
+}));
+
+vi.mock("open-sse/index.js", () => ({}));
+
+vi.mock("@/lib/localDb", () => ({
+  getProviderConnectionById: mocks.getProviderConnectionById,
+}));
+
+vi.mock("@/lib/network/connectionProxy", () => ({
+  resolveConnectionProxyConfig: mocks.resolveConnectionProxyConfig,
+}));
+
+vi.mock("@/app/api/usage/[connectionId]/route.js", () => ({
+  refreshAndUpdateCredentials: mocks.refreshAndUpdateCredentials,
+}));
+
+vi.mock("open-sse/services/usage.js", () => ({
+  getCodexRateLimitResetCredits: mocks.getCodexRateLimitResetCredits,
+  consumeCodexRateLimitResetCredit: mocks.consumeCodexRateLimitResetCredit,
+}));
+
+describe("Codex reset credits", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.resolveConnectionProxyConfig.mockResolvedValue({});
+  });
+
+  it("returns normalized reset credit expiry details", async () => {
+    mocks.proxyAwareFetch.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        available_count: 2,
+        credits: [
+          {
+            status: "available",
+            granted_at: "2026-06-18T00:25:18Z",
+            expires_at: "2026-07-18T00:25:18Z",
+          },
+          {
+            status: "redeemed",
+            granted_at: "bad-date",
+            expires_at: null,
+          },
+        ],
+      }),
+    });
+
+    const { getCodexRateLimitResetCredits } = await import("../../open-sse/services/usage/codex.js");
+    const result = await getCodexRateLimitResetCredits("token", { strictProxy: false }, { workspaceId: "acct_123" });
+
+    expect(mocks.proxyAwareFetch).toHaveBeenCalledWith(
+      expect.stringContaining("/rate-limit-reset-credits"),
+      expect.objectContaining({
+        method: "GET",
+        headers: expect.objectContaining({
+          Authorization: "Bearer token",
+          "ChatGPT-Account-ID": "acct_123",
+        }),
+      }),
+      { strictProxy: false },
+    );
+    expect(result).toEqual({
+      availableCount: 2,
+      credits: [
+        {
+          status: "available",
+          grantedAt: "2026-06-18T00:25:18.000Z",
+          expiresAt: "2026-07-18T00:25:18.000Z",
+        },
+        {
+          status: "redeemed",
+          grantedAt: null,
+          expiresAt: null,
+        },
+      ],
+    });
+  });
+
+  it("GET refreshes OAuth credentials before returning reset credit details", async () => {
+    const connection = {
+      id: "conn_1",
+      provider: "codex",
+      authType: "oauth",
+      accessToken: "old-token",
+      refreshToken: "refresh-token",
+      providerSpecificData: { workspaceId: "acct_123" },
+    };
+    const refreshedConnection = { ...connection, accessToken: "new-token" };
+    const resetCredits = {
+      availableCount: 1,
+      credits: [{ status: "available", grantedAt: "2026-06-18T00:25:18.000Z", expiresAt: "2026-07-18T00:25:18.000Z" }],
+    };
+    mocks.getProviderConnectionById.mockResolvedValue(connection);
+    mocks.resolveConnectionProxyConfig.mockResolvedValue({ connectionProxyEnabled: true, connectionProxyUrl: "http://proxy.local" });
+    mocks.refreshAndUpdateCredentials.mockResolvedValue({ connection: refreshedConnection });
+    mocks.getCodexRateLimitResetCredits.mockResolvedValue(resetCredits);
+
+    const { GET } = await import("../../src/app/api/usage/[connectionId]/codex-reset-credits/route.js");
+    const response = await GET(new Request("http://localhost/api/usage/conn_1/codex-reset-credits"), {
+      params: Promise.resolve({ connectionId: "conn_1" }),
+    });
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual(resetCredits);
+    expect(mocks.refreshAndUpdateCredentials).toHaveBeenCalledWith(
+      connection,
+      false,
+      expect.objectContaining({ connectionProxyEnabled: true, connectionProxyUrl: "http://proxy.local", strictProxy: false }),
+    );
+    expect(mocks.getCodexRateLimitResetCredits).toHaveBeenCalledWith(
+      "new-token",
+      expect.objectContaining({ connectionProxyEnabled: true, connectionProxyUrl: "http://proxy.local", strictProxy: false }),
+      { workspaceId: "acct_123" },
+    );
+  });
+
+  it("GET force-refreshes OAuth credentials when reset credit fetch reports expired auth", async () => {
+    const connection = {
+      id: "conn_1",
+      provider: "codex",
+      authType: "oauth",
+      accessToken: "old-token",
+      refreshToken: "refresh-token",
+      providerSpecificData: {},
+    };
+    const refreshedConnection = { ...connection, accessToken: "new-token" };
+    const forcedConnection = { ...connection, accessToken: "forced-token" };
+    const resetCredits = { availableCount: 0, credits: [] };
+    mocks.getProviderConnectionById.mockResolvedValue(connection);
+    mocks.refreshAndUpdateCredentials
+      .mockResolvedValueOnce({ connection: refreshedConnection })
+      .mockResolvedValueOnce({ connection: forcedConnection });
+    mocks.getCodexRateLimitResetCredits
+      .mockRejectedValueOnce(new Error("Unauthorized 401"))
+      .mockResolvedValueOnce(resetCredits);
+
+    const { GET } = await import("../../src/app/api/usage/[connectionId]/codex-reset-credits/route.js");
+    const response = await GET(new Request("http://localhost/api/usage/conn_1/codex-reset-credits"), {
+      params: Promise.resolve({ connectionId: "conn_1" }),
+    });
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual(resetCredits);
+    expect(mocks.refreshAndUpdateCredentials).toHaveBeenNthCalledWith(1, connection, false, expect.any(Object));
+    expect(mocks.refreshAndUpdateCredentials).toHaveBeenNthCalledWith(2, refreshedConnection, true, expect.any(Object));
+    expect(mocks.getCodexRateLimitResetCredits).toHaveBeenNthCalledWith(2, "forced-token", expect.any(Object), {});
+  });
+
+  it("POST returns 409 when there are no reset credits to consume", async () => {
+    mocks.getProviderConnectionById.mockResolvedValue({
+      id: "conn_1",
+      provider: "codex",
+      authType: "access_token",
+      accessToken: "token",
+      providerSpecificData: {},
+    });
+    mocks.consumeCodexRateLimitResetCredit.mockResolvedValue({
+      ok: false,
+      noCredit: true,
+      status: 200,
+      code: "no_credit",
+      windowsReset: 0,
+    });
+
+    const { POST } = await import("../../src/app/api/usage/[connectionId]/codex-reset-credits/route.js");
+    const response = await POST(new Request("http://localhost/api/usage/conn_1/codex-reset-credits", { method: "POST" }), {
+      params: Promise.resolve({ connectionId: "conn_1" }),
+    });
+
+    expect(response.status).toBe(409);
+    expect(await response.json()).toMatchObject({
+      code: "no_credit",
+      reset: false,
+      windows_reset: 0,
+      message: "No Codex reset credits available.",
+    });
+    expect(mocks.consumeCodexRateLimitResetCredit).toHaveBeenCalledWith(
+      "token",
+      expect.any(String),
+      expect.objectContaining({ strictProxy: false }),
+    );
+  });
+});
diff --git a/tests/unit/codex-tool-normalization.test.js b/tests/unit/codex-tool-normalization.test.js
new file mode 100644
index 0000000..d1b5901
--- /dev/null
+++ b/tests/unit/codex-tool-normalization.test.js
@@ -0,0 +1,140 @@
+import { describe, expect, it } from "vitest";
+
+import { CodexExecutor } from "../../open-sse/executors/codex.js";
+
+function normalizeTools(tools) {
+  const executor = new CodexExecutor();
+  const body = {
+    model: "gpt-5.5",
+    input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "probe" }] }],
+    tools,
+    stream: true,
+  };
+
+  executor.transformRequest("gpt-5.5", body, true, {
+    connectionId: "test-codex-tools",
+    providerSpecificData: {},
+  });
+
+  return body.tools;
+}
+
+describe("CodexExecutor tool normalization", () => {
+  it("preserves Responses text.format for structured outputs", () => {
+    const executor = new CodexExecutor();
+    const schema = {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        title: { type: "string" },
+      },
+      required: ["title"],
+    };
+    const body = {
+      model: "gpt-5.4-mini",
+      input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "test for session title" }] }],
+      stream: true,
+      metadata: { unsupported: true },
+      text: {
+        format: {
+          type: "json_schema",
+          name: "codex_output_schema",
+          strict: true,
+          schema,
+        },
+      },
+    };
+
+    executor.transformRequest("gpt-5.4-mini", body, true, {
+      connectionId: "test-codex-structured-output",
+      providerSpecificData: {},
+    });
+
+    expect(body.text).toEqual({
+      format: {
+        type: "json_schema",
+        name: "codex_output_schema",
+        strict: true,
+        schema,
+      },
+    });
+    expect(body.metadata).toBeUndefined();
+  });
+
+  it("preserves Responses-native tool_search tools", () => {
+    const tools = normalizeTools([
+      {
+        type: "tool_search",
+        execution: "sync",
+        description: "Discover deferred tools",
+        parameters: { type: "object", properties: {} },
+      },
+      {
+        type: "namespace",
+        name: "codex_app",
+        description: "app tools",
+        tools: [
+          {
+            type: "function",
+            name: "automation_update",
+            description: "automation",
+            parameters: { type: "object", properties: {} },
+            defer_loading: true,
+          },
+        ],
+      },
+      {
+        type: "function",
+        name: "plain_fn",
+        description: "plain",
+        parameters: { type: "object", properties: {} },
+      },
+    ]);
+
+    expect(tools.map((tool) => `${tool.type}:${tool.name || ""}`)).toEqual([
+      "tool_search:",
+      "namespace:codex_app",
+      "function:plain_fn",
+    ]);
+  });
+
+  it("preserves hosted Responses tools", () => {
+    const tools = normalizeTools([
+      { type: "web_search", search_context_size: "medium" },
+      { type: "image_generation", size: "1024x1024" },
+      { type: "mcp", server_label: "docs", server_url: "https://example.com/mcp" },
+      { type: "local_shell" },
+      { type: "code_interpreter", container: { type: "auto" } },
+      { type: "computer", display_width: 1024, display_height: 768, environment: "browser" },
+    ]);
+
+    expect(tools.map((tool) => tool.type)).toEqual([
+      "web_search",
+      "image_generation",
+      "mcp",
+      "local_shell",
+      "code_interpreter",
+      "computer",
+    ]);
+  });
+
+  it("preserves custom freeform tools with format payloads", () => {
+    const tools = normalizeTools([
+      {
+        type: "custom",
+        name: "apply_patch",
+        description: "patch",
+        format: { type: "grammar", syntax: "lark", definition: "start: /.+/" },
+      },
+    ]);
+
+    expect(tools).toEqual([
+      {
+        type: "custom",
+        name: "apply_patch",
+        description: "patch",
+        format: { type: "grammar", syntax: "lark", definition: "start: /.+/" },
+      },
+    ]);
+  });
+});
diff --git a/tests/unit/combo-autoswitch.test.js b/tests/unit/combo-autoswitch.test.js
new file mode 100644
index 0000000..904d9e5
--- /dev/null
+++ b/tests/unit/combo-autoswitch.test.js
@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { detectRequiredCapabilities, reorderByCapabilities } from "../../open-sse/services/combo.js";
+
+describe("detectRequiredCapabilities", () => {
+  it("text-only -> empty", () => {
+    const r = detectRequiredCapabilities({ messages: [{ role: "user", content: "hi" }] });
+    expect(r.size).toBe(0);
+  });
+
+  it("openai image_url -> vision", () => {
+    const r = detectRequiredCapabilities({ messages: [{ role: "user", content: [
+      { type: "image_url", image_url: { url: "x" } },
+    ] }] });
+    expect(r.has("vision")).toBe(true);
+  });
+
+  it("openai file -> pdf", () => {
+    const r = detectRequiredCapabilities({ messages: [{ role: "user", content: [
+      { type: "file", file: { file_data: "data:application/pdf;base64,x" } },
+    ] }] });
+    expect(r.has("pdf")).toBe(true);
+  });
+
+  it("gemini inlineData image -> vision", () => {
+    const r = detectRequiredCapabilities({ contents: [{ role: "user", parts: [
+      { inlineData: { mimeType: "image/png", data: "x" } },
+    ] }] });
+    expect(r.has("vision")).toBe(true);
+  });
+
+  it("antigravity request.contents image -> vision", () => {
+    const r = detectRequiredCapabilities({ request: { contents: [{ role: "user", parts: [
+      { inlineData: { mimeType: "image/jpeg", data: "x" } },
+    ] }] } });
+    expect(r.has("vision")).toBe(true);
+  });
+
+  it("web_search tool -> search", () => {
+    const r = detectRequiredCapabilities({ messages: [{ role: "user", content: "q" }], tools: [
+      { type: "web_search" },
+    ] });
+    expect(r.has("search")).toBe(true);
+  });
+
+  it("responses input_image -> vision", () => {
+    const r = detectRequiredCapabilities({ input: [{ role: "user", content: [
+      { type: "input_image", image_url: "x" },
+    ] }] });
+    expect(r.has("vision")).toBe(true);
+  });
+});
+
+describe("reorderByCapabilities", () => {
+  it("no required -> unchanged", () => {
+    const models = ["a/x", "b/y"];
+    expect(reorderByCapabilities(models, new Set())).toBe(models);
+  });
+
+  it("floats vision-capable model to front, keeps fallback", () => {
+    // deepseek-chat = no vision; claude-sonnet = vision
+    const models = ["deepseek/deepseek-chat", "anthropic/claude-sonnet-4.6"];
+    const out = reorderByCapabilities(models, new Set(["vision"]));
+    expect(out[0]).toBe("anthropic/claude-sonnet-4.6");
+    expect(out).toContain("deepseek/deepseek-chat"); // not dropped
+    expect(out).toHaveLength(2);
+  });
+
+  it("keeps order when no model matches", () => {
+    const models = ["deepseek/deepseek-chat", "deepseek/deepseek-reasoner"];
+    const out = reorderByCapabilities(models, new Set(["vision"]));
+    expect(out).toBe(models);
+  });
+
+  it("single model -> unchanged", () => {
+    const models = ["a/x"];
+    expect(reorderByCapabilities(models, new Set(["vision"]))).toBe(models);
+  });
+});
diff --git a/tests/unit/combo-fusion.test.js b/tests/unit/combo-fusion.test.js
new file mode 100644
index 0000000..52949cb
--- /dev/null
+++ b/tests/unit/combo-fusion.test.js
@@ -0,0 +1,216 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { handleFusionChat } from "../../open-sse/services/combo.js";
+
+const log = { info: () => {}, warn: () => {}, debug: () => {} };
+
+// Minimal OpenAI-chat Response stub with the .ok + .clone().json() surface the engine uses.
+function okResponse(content, { delayMs = 0 } = {}) {
+  const json = { choices: [{ message: { role: "assistant", content } }] };
+  const make = () => ({ ok: true, status: 200, clone: make, json: async () => json });
+  const res = make();
+  return delayMs > 0 ? new Promise((r) => setTimeout(() => r(res), delayMs)) : res;
+}
+
+function errResponse(status = 500) {
+  const make = () => ({ ok: false, status, clone: make, json: async () => ({ error: { message: "boom" } }) });
+  return make();
+}
+
+describe("fusion combo", () => {
+  it("answers directly with a single-model panel (nothing to fuse)", async () => {
+    const handleSingleModel = vi.fn(async () => okResponse("solo"));
+    await handleFusionChat({
+      body: { messages: [{ role: "user", content: "hi" }] },
+      models: ["p/only"],
+      handleSingleModel,
+      log,
+    });
+    expect(handleSingleModel).toHaveBeenCalledTimes(1);
+    expect(handleSingleModel.mock.calls[0][1]).toBe("p/only");
+  });
+
+  it("fans out to the panel then routes a synthesis turn to the judge", async () => {
+    const seen = [];
+    const handleSingleModel = vi.fn(async (body, model, isPanel) => {
+      seen.push(model);
+      if (model === "p/judge") return okResponse("FINAL");
+      return okResponse(`ans-${model}`);
+    });
+
+    const res = await handleFusionChat({
+      body: { messages: [{ role: "user", content: "Q" }], stream: true, tools: [{ name: "x" }] },
+      models: ["p/a", "p/b", "p/c"],
+      handleSingleModel,
+      log,
+      judgeModel: "p/judge",
+    });
+
+    // 3 panel calls + 1 judge call.
+    expect(handleSingleModel).toHaveBeenCalledTimes(4);
+    expect(seen.slice(0, 3).sort()).toEqual(["p/a", "p/b", "p/c"]);
+    expect(seen[3]).toBe("p/judge");
+
+    // Panel calls are non-streaming with tools stripped.
+    for (const [body, model, isPanel] of handleSingleModel.mock.calls.filter(([, m]) => m !== "p/judge")) {
+      expect(body.stream).toBe(false);
+      expect(body.tools).toBeUndefined();
+      expect(isPanel).toBe(true);
+    }
+
+    // Judge call carries every panel answer + keeps the client's stream flag.
+    const [judgeBody, , isPanel] = handleSingleModel.mock.calls.find(([, m]) => m === "p/judge");
+    const judgeText = judgeBody.messages.at(-1).content;
+    expect(judgeText).toContain("ans-p/a");
+    expect(judgeText).toContain("ans-p/b");
+    expect(judgeText).toContain("ans-p/c");
+    expect(judgeText).toContain("Source 1");
+    expect(judgeBody.stream).toBe(true);
+    expect(isPanel).toBeUndefined();
+
+    expect(res.ok).toBe(true);
+  });
+
+  it("defaults the judge to the first panel model when none is set", async () => {
+    const seen = [];
+    const handleSingleModel = vi.fn(async (_body, model) => { seen.push(model); return okResponse(`ans-${model}`); });
+    await handleFusionChat({
+      body: { messages: [{ role: "user", content: "Q" }] },
+      models: ["p/first", "p/second"],
+      handleSingleModel,
+      log,
+    });
+    // Last call is the judge; defaults to panel[0].
+    expect(seen.at(-1)).toBe("p/first");
+  });
+
+  it("proceeds on quorum without waiting for a straggler (grace window)", async () => {
+    const handleSingleModel = vi.fn(async (_body, model) => {
+      if (model === "p/slow") return okResponse("slow", { delayMs: 5000 });
+      if (model === "p/judge") return okResponse("FINAL");
+      return okResponse(`fast-${model}`);
+    });
+
+    const t0 = Date.now();
+    await handleFusionChat({
+      body: { messages: [{ role: "user", content: "Q" }] },
+      models: ["p/x", "p/y", "p/slow"],
+      handleSingleModel,
+      log,
+      judgeModel: "p/judge",
+      tuning: { minPanel: 2, stragglerGraceMs: 50, panelHardTimeoutMs: 10000 },
+    });
+    const elapsed = Date.now() - t0;
+
+    // Two fast answers reach quorum; grace is 50ms, so we never wait ~5s for p/slow.
+    expect(elapsed).toBeLessThan(2000);
+
+    const judgeCall = handleSingleModel.mock.calls.find(([, m]) => m === "p/judge");
+    const judgeText = judgeCall[0].messages.at(-1).content;
+    expect(judgeText).toContain("fast-p/x");
+    expect(judgeText).toContain("fast-p/y");
+    expect(judgeText).not.toContain("slow");
+  });
+
+  it("returns the lone survivor directly when only one panel model succeeds", async () => {
+    const handleSingleModel = vi.fn(async (_body, model) => {
+      if (model === "p/ok") return okResponse("lone");
+      return errResponse(500);
+    });
+    await handleFusionChat({
+      body: { messages: [{ role: "user", content: "Q" }] },
+      models: ["p/ok", "p/bad"],
+      handleSingleModel,
+      log,
+      judgeModel: "p/judge",
+      tuning: { minPanel: 2, stragglerGraceMs: 50, panelHardTimeoutMs: 5000 },
+    });
+    // No judge call — single answer means there is nothing to fuse.
+    const judged = handleSingleModel.mock.calls.some(([, m]) => m === "p/judge");
+    expect(judged).toBe(false);
+  });
+
+  it("returns 503 when the whole panel fails", async () => {
+    const handleSingleModel = vi.fn(async () => errResponse(500));
+    const res = await handleFusionChat({
+      body: { messages: [{ role: "user", content: "Q" }] },
+      models: ["p/a", "p/b"],
+      handleSingleModel,
+      log,
+      tuning: { minPanel: 2, stragglerGraceMs: 50, panelHardTimeoutMs: 5000 },
+    });
+    expect(res.status).toBe(503);
+  });
+
+  it("flattens previous tool history and assistant tool_calls into prose for panel calls", async () => {
+    const handleSingleModel = vi.fn(async () => okResponse("ans"));
+    await handleFusionChat({
+      body: {
+        messages: [
+          { role: "user", content: "find files" },
+          { role: "assistant", content: "", tool_calls: [{ id: "c1", type: "function", function: { name: "find" } }] },
+          { role: "tool", tool_call_id: "c1", content: "['a.js']" },
+          { role: "user", content: "describe it" }
+        ],
+        tools: [{ type: "function" }]
+      },
+      models: ["p/a", "p/b"],
+      handleSingleModel,
+      log,
+      judgeModel: "p/judge"
+    });
+
+    // Panel calls keep every turn but tool turns are flattened to assistant prose.
+    const panelCalls = handleSingleModel.mock.calls.filter(([,, isPanel]) => isPanel === true);
+    expect(panelCalls.length).toBe(2);
+    for (const [panelBody] of panelCalls) {
+      expect(panelBody.tools).toBeUndefined();
+      expect(panelBody.messages.length).toBe(4);
+      expect(panelBody.messages[0]).toEqual({ role: "user", content: "find files" });
+      expect(panelBody.messages[1].tool_calls).toBeUndefined();
+      expect(panelBody.messages[1].content).toContain("find");
+      expect(panelBody.messages[2].role).toBe("assistant");
+      expect(panelBody.messages[2].content).toContain("['a.js']");
+      expect(panelBody.messages[3]).toEqual({ role: "user", content: "describe it" });
+    }
+
+    // Judge call still receives the unmodified history + synthesis prompt.
+    const judgeCall = handleSingleModel.mock.calls.find(([, m]) => m === "p/judge");
+    expect(judgeCall).toBeDefined();
+    const judgeBody = judgeCall[0];
+    expect(judgeBody.messages.length).toBe(5); // original 4 + judge prompt turn
+    expect(judgeBody.messages[1].tool_calls).toBeDefined();
+    expect(judgeBody.messages[2].role).toBe("tool");
+  });
+
+  it("flattens Anthropic-style tool_use and tool_result blocks in arrays", async () => {
+    const handleSingleModel = vi.fn(async () => okResponse("ans"));
+    await handleFusionChat({
+      body: {
+        messages: [
+          { role: "user", content: "do it" },
+          { role: "assistant", content: [{ type: "text", text: "ok" }, { type: "tool_use", id: "t1", name: "run" }] },
+          { role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content: "done" }] }
+        ],
+        tools: [{ name: "run", description: "d" }]
+      },
+      models: ["p/a", "p/b"],
+      handleSingleModel,
+      log,
+      judgeModel: "p/judge"
+    });
+
+    const panelCalls = handleSingleModel.mock.calls.filter(([,, isPanel]) => isPanel === true);
+    expect(panelCalls.length).toBe(2);
+    const panelBody = panelCalls[0][0];
+    
+    expect(panelBody.tools).toBeUndefined();
+    expect(panelBody.messages.length).toBe(3);
+    
+    // Flattened tool_use
+    expect(panelBody.messages[1].content).toBe("ok\n[Called tools: run]");
+    
+    // Flattened tool_result
+    expect(panelBody.messages[2].content).toBe("[Tool result: done]");
+  });
+});
diff --git a/tests/unit/combo-routing.test.js b/tests/unit/combo-routing.test.js
new file mode 100644
index 0000000..d6ef4d0
--- /dev/null
+++ b/tests/unit/combo-routing.test.js
@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach } from "vitest";
+
+import { getRotatedModels, resetComboRotation } from "../../open-sse/services/combo.js";
+
+describe("combo round-robin routing", () => {
+  beforeEach(() => {
+    resetComboRotation();
+  });
+
+  it("keeps existing one-request round-robin behavior by default", () => {
+    const models = ["provider/model-a", "provider/model-b"];
+
+    const firstChoices = Array.from({ length: 4 }, () => (
+      getRotatedModels(models, "code-xhigh", "round-robin")[0]
+    ));
+
+    expect(firstChoices).toEqual([
+      "provider/model-a",
+      "provider/model-b",
+      "provider/model-a",
+      "provider/model-b",
+    ]);
+  });
+
+  it("sticks to each combo model for the configured number of requests", () => {
+    const models = ["provider/model-a", "provider/model-b"];
+
+    const firstChoices = Array.from({ length: 6 }, () => (
+      getRotatedModels(models, "code-xhigh", "round-robin", 2)[0]
+    ));
+
+    expect(firstChoices).toEqual([
+      "provider/model-a",
+      "provider/model-a",
+      "provider/model-b",
+      "provider/model-b",
+      "provider/model-a",
+      "provider/model-a",
+    ]);
+  });
+
+  it("tracks sticky rotation independently per combo", () => {
+    const models = ["provider/model-a", "provider/model-b"];
+
+    expect(getRotatedModels(models, "code-high", "round-robin", 2)[0]).toBe("provider/model-a");
+    expect(getRotatedModels(models, "code-xhigh", "round-robin", 2)[0]).toBe("provider/model-a");
+    expect(getRotatedModels(models, "code-high", "round-robin", 2)[0]).toBe("provider/model-a");
+    expect(getRotatedModels(models, "code-high", "round-robin", 2)[0]).toBe("provider/model-b");
+    expect(getRotatedModels(models, "code-xhigh", "round-robin", 2)[0]).toBe("provider/model-a");
+  });
+
+  it("does not rotate fallback combos", () => {
+    const models = ["provider/model-a", "provider/model-b"];
+
+    expect(getRotatedModels(models, "code-xhigh", "fallback", 2)).toEqual(models);
+    expect(getRotatedModels(models, "code-xhigh", "fallback", 2)).toEqual(models);
+  });
+});
diff --git a/tests/unit/commandcode-to-openai.test.js b/tests/unit/commandcode-to-openai.test.js
new file mode 100644
index 0000000..36c5f75
--- /dev/null
+++ b/tests/unit/commandcode-to-openai.test.js
@@ -0,0 +1,127 @@
+/**
+ * Unit tests for open-sse/translator/response/commandcode-to-openai.js
+ *
+ * Verified live against upstream stream (curl, 2026-05-07):
+ *  - tool-input-start: { id, toolName }   (id, NOT toolCallId)
+ *  - tool-input-delta: { id, delta }      (id, NOT toolCallId; delta, NOT inputTextDelta)
+ *  - tool-input-end:   { id }
+ *  - tool-call (final): { toolCallId, toolName, input }
+ */
+
+import { describe, it, expect } from "vitest";
+import { commandCodeToOpenAIResponse } from "../../open-sse/translator/response/commandcode-to-openai.js";
+
+function feed(events) {
+  const state = {};
+  const all = [];
+  for (const e of events) {
+    const out = commandCodeToOpenAIResponse(JSON.stringify(e), state);
+    if (out) for (const c of out) all.push(c);
+  }
+  return { state, chunks: all };
+}
+
+describe("commandcode-to-openai — text-delta", () => {
+  it("emits assistant role on first delta then content-only", () => {
+    const { chunks } = feed([
+      { type: "text-delta", text: "Hello" },
+      { type: "text-delta", text: " world" },
+    ]);
+    expect(chunks[0].choices[0].delta.role).toBe("assistant");
+    expect(chunks[0].choices[0].delta.content).toBe("Hello");
+    expect(chunks[1].choices[0].delta.role).toBeUndefined();
+    expect(chunks[1].choices[0].delta.content).toBe(" world");
+  });
+});
+
+describe("commandcode-to-openai — reasoning-delta", () => {
+  it("maps reasoning-delta to reasoning_content delta", () => {
+    const { chunks } = feed([
+      { type: "reasoning-delta", text: "thinking..." },
+    ]);
+    expect(chunks[0].choices[0].delta.reasoning_content).toBe("thinking...");
+  });
+});
+
+describe("commandcode-to-openai — tool-input-* with id field (live schema)", () => {
+  it("registers tool index using event.id (NOT toolCallId)", () => {
+    const { chunks } = feed([
+      { type: "tool-input-start", id: "call_X", toolName: "Bash" },
+      { type: "tool-input-delta", id: "call_X", delta: "{\"cmd" },
+      { type: "tool-input-delta", id: "call_X", delta: "\":\"ls\"}" },
+    ]);
+
+    // First chunk emits tool_calls with id
+    const startChunk = chunks[0].choices[0].delta.tool_calls[0];
+    expect(startChunk.id).toBe("call_X");
+    expect(startChunk.function.name).toBe("Bash");
+
+    // Subsequent deltas accumulate arguments
+    expect(chunks[1].choices[0].delta.tool_calls[0].function.arguments).toBe("{\"cmd");
+    expect(chunks[2].choices[0].delta.tool_calls[0].function.arguments).toBe("\":\"ls\"}");
+  });
+
+  it("ignores tool-input-delta when id is unknown (no prior start)", () => {
+    const { chunks } = feed([
+      { type: "tool-input-delta", id: "unknown", delta: "x" },
+    ]);
+    expect(chunks.length).toBe(0);
+  });
+});
+
+describe("commandcode-to-openai — final tool-call event", () => {
+  it("does NOT re-emit tool_calls when tool-input-* deltas already fired", () => {
+    const { chunks } = feed([
+      { type: "tool-input-start", id: "call_Y", toolName: "Write" },
+      { type: "tool-input-delta", id: "call_Y", delta: "{\"file\":\"a\"}" },
+      { type: "tool-call", toolCallId: "call_Y", toolName: "Write", input: { file: "a" } },
+    ]);
+    // Should be exactly 2 chunks (start + delta), no duplicate from final tool-call
+    expect(chunks.length).toBe(2);
+  });
+
+  it("emits a consolidated tool_calls when only the final tool-call event arrives", () => {
+    const { chunks } = feed([
+      { type: "tool-call", toolCallId: "call_Z", toolName: "Read", input: { path: "/x" } },
+    ]);
+    expect(chunks.length).toBe(1);
+    const tc = chunks[0].choices[0].delta.tool_calls[0];
+    expect(tc.id).toBe("call_Z");
+    expect(tc.function.name).toBe("Read");
+    expect(tc.function.arguments).toBe(JSON.stringify({ path: "/x" }));
+  });
+});
+
+describe("commandcode-to-openai — finish", () => {
+  it("emits a final chunk with finish_reason=tool_calls when finishReason is tool-calls", () => {
+    const { chunks } = feed([
+      { type: "tool-input-start", id: "call_F", toolName: "Bash" },
+      { type: "tool-input-delta", id: "call_F", delta: "{}" },
+      { type: "finish-step", finishReason: "tool-calls" },
+      { type: "finish" },
+    ]);
+    const last = chunks[chunks.length - 1];
+    expect(last.choices[0].finish_reason).toBe("tool_calls");
+  });
+
+  it("includes usage on the final chunk when totalUsage provided", () => {
+    const { chunks } = feed([
+      { type: "text-delta", text: "hi" },
+      { type: "finish-step", finishReason: "stop", usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 } },
+      { type: "finish", totalUsage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 } },
+    ]);
+    const last = chunks[chunks.length - 1];
+    expect(last.usage).toEqual({ prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 });
+  });
+});
+
+describe("commandcode-to-openai — error event", () => {
+  it("stringifies object errors so client sees readable message", () => {
+    const { chunks } = feed([
+      { type: "error", error: { type: "server_error", message: "Boom" } },
+    ]);
+    const text = chunks[0].choices[0].delta.content;
+    expect(text).toContain("Boom");
+    expect(text).not.toContain("[object Object]");
+  });
+});
diff --git a/tests/unit/compatible-provider-connections.test.js b/tests/unit/compatible-provider-connections.test.js
new file mode 100644
index 0000000..0fe146f
--- /dev/null
+++ b/tests/unit/compatible-provider-connections.test.js
@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+const originalDataDir = process.env.DATA_DIR;
+
+async function setupTestContext(nodeData) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "9router-compatible-provider-"));
+  process.env.DATA_DIR = tempDir;
+  vi.resetModules();
+  vi.doMock("next/server", () => ({
+    NextResponse: {
+      json(body, init = {}) {
+        return new Response(JSON.stringify(body), {
+          status: init.status || 200,
+          headers: { "Content-Type": "application/json" },
+        });
+      },
+    },
+  }));
+
+  const { POST } = await import("@/app/api/providers/route.js");
+  const {
+    createProviderNode,
+    getProviderConnections,
+  } = await import("@/models/index.js");
+
+  const node = await createProviderNode(nodeData);
+
+  return {
+    node,
+    POST,
+    getProviderConnections,
+    cleanup() {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    },
+  };
+}
+
+function makeRequest(provider, name = "Test Connection") {
+  return new Request("https://9router.local/api/providers", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      provider,
+      apiKey: "test-key",
+      name,
+      defaultModel: "test-model",
+    }),
+  });
+}
+
+function expectCompatibleConnection(connection, node, { apiType } = {}) {
+  expect(connection.provider).toBe(node.id);
+  expect(connection.authType).toBe("apikey");
+  expect(connection.defaultModel).toBe("test-model");
+  expect(connection.providerSpecificData).toMatchObject({
+    prefix: node.prefix,
+    baseUrl: node.baseUrl,
+    nodeName: node.name,
+  });
+
+  if (apiType !== undefined) {
+    expect(connection.providerSpecificData.apiType).toBe(apiType);
+  }
+}
+
+describe("compatible provider connections API", () => {
+  let cleanup = () => {};
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.doUnmock("next/server");
+    vi.resetModules();
+    vi.clearAllMocks();
+    cleanup();
+    cleanup = () => {};
+    if (originalDataDir === undefined) delete process.env.DATA_DIR;
+    else process.env.DATA_DIR = originalDataDir;
+  });
+
+  it("creates one API-key connection for an OpenAI-compatible node", async () => {
+    const ctx = await setupTestContext({
+      id: "openai-compatible-test",
+      type: "openai-compatible",
+      name: "OpenAI Compatible Test Node",
+      prefix: "oct",
+      apiType: "chat",
+      baseUrl: "https://openai-compatible.test/v1",
+    });
+    cleanup = ctx.cleanup;
+
+    const response = await ctx.POST(makeRequest(ctx.node.id));
+    const body = await response.json();
+    const connection = body.connection;
+    const storedConnections = await ctx.getProviderConnections({ provider: ctx.node.id });
+
+    expect(response.status).toBe(201);
+    expect(storedConnections).toHaveLength(1);
+    expectCompatibleConnection(connection, ctx.node, { apiType: "chat" });
+    expect(storedConnections[0]).toMatchObject({
+      provider: ctx.node.id,
+      authType: "apikey",
+      defaultModel: "test-model",
+      providerSpecificData: {
+        prefix: ctx.node.prefix,
+        apiType: "chat",
+        baseUrl: ctx.node.baseUrl,
+        nodeName: ctx.node.name,
+      },
+    });
+  });
+
+  it("creates one API-key connection for an Anthropic-compatible node", async () => {
+    const ctx = await setupTestContext({
+      id: "anthropic-compatible-test",
+      type: "anthropic-compatible",
+      name: "Anthropic Compatible Test Node",
+      prefix: "act",
+      baseUrl: "https://anthropic-compatible.test/v1",
+    });
+    cleanup = ctx.cleanup;
+
+    const response = await ctx.POST(makeRequest(ctx.node.id));
+    const body = await response.json();
+    const connection = body.connection;
+    const storedConnections = await ctx.getProviderConnections({ provider: ctx.node.id });
+
+    expect(response.status).toBe(201);
+    expect(storedConnections).toHaveLength(1);
+    expectCompatibleConnection(connection, ctx.node);
+    expect(storedConnections[0]).toMatchObject({
+      provider: ctx.node.id,
+      authType: "apikey",
+      defaultModel: "test-model",
+      providerSpecificData: {
+        prefix: ctx.node.prefix,
+        baseUrl: ctx.node.baseUrl,
+        nodeName: ctx.node.name,
+      },
+    });
+  });
+
+  it("allows multiple connections on the same compatible node", async () => {
+    const ctx = await setupTestContext({
+      id: "openai-compatible-multiple-test",
+      type: "openai-compatible",
+      name: "Multiple Connections Node",
+      prefix: "mul",
+      apiType: "chat",
+      baseUrl: "https://multiple-connections.test/v1",
+    });
+    cleanup = ctx.cleanup;
+
+    const firstResponse = await ctx.POST(makeRequest(ctx.node.id, "Key A"));
+    const secondResponse = await ctx.POST(makeRequest(ctx.node.id, "Key B"));
+    const storedConnections = await ctx.getProviderConnections({ provider: ctx.node.id });
+
+    expect(firstResponse.status).toBe(201);
+    expect(secondResponse.status).toBe(201);
+    expect(storedConnections).toHaveLength(2);
+    expectCompatibleConnection(storedConnections[0], ctx.node, { apiType: "chat" });
+    expectCompatibleConnection(storedConnections[1], ctx.node, { apiType: "chat" });
+  });
+});
diff --git a/tests/unit/count-tokens.test.js b/tests/unit/count-tokens.test.js
new file mode 100644
index 0000000..92f7f9c
--- /dev/null
+++ b/tests/unit/count-tokens.test.js
@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+
+import { POST } from "../../src/app/api/v1/messages/count_tokens/route.js";
+
+async function countTokens(body) {
+  const response = await POST(new Request("https://9router.local/v1/messages/count_tokens", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  }));
+
+  expect(response.status).toBe(200);
+  return response.json();
+}
+
+describe("Anthropic count_tokens estimator", () => {
+  it("preserves the existing plain text estimate", async () => {
+    const result = await countTokens({
+      messages: [
+        {
+          role: "user",
+          content: "hello world",
+        },
+      ],
+    });
+
+    expect(result.input_tokens).toBe(3);
+  });
+
+  it("counts tool and thinking content blocks that carry context", async () => {
+    const result = await countTokens({
+      messages: [
+        {
+          role: "assistant",
+          content: [
+            {
+              type: "tool_use",
+              id: "toolu_01",
+              name: "Read",
+              input: { file_path: "/tmp/example.txt" },
+            },
+            {
+              type: "thinking",
+              thinking: "Need to inspect the file before answering.",
+            },
+          ],
+        },
+        {
+          role: "user",
+          content: [
+            {
+              type: "tool_result",
+              tool_use_id: "toolu_01",
+              content: "line1 line2 line3 some file content here",
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.input_tokens).toBeGreaterThan(0);
+  });
+
+  it("counts system prompts and tool definitions", async () => {
+    const result = await countTokens({
+      system: "You are a coding assistant.",
+      tools: [
+        {
+          name: "Read",
+          description: "Read a file",
+          input_schema: {
+            type: "object",
+            properties: {
+              file_path: { type: "string" },
+            },
+          },
+        },
+      ],
+      messages: [],
+    });
+
+    expect(result.input_tokens).toBeGreaterThan(0);
+  });
+});
diff --git a/tests/unit/cursor-composer-thinking.test.js b/tests/unit/cursor-composer-thinking.test.js
new file mode 100644
index 0000000..7033231
--- /dev/null
+++ b/tests/unit/cursor-composer-thinking.test.js
@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest";
+
+import { CursorExecutor } from "../../open-sse/executors/cursor.js";
+import { encodeField, wrapConnectRPCFrame } from "../../open-sse/utils/cursorProtobuf.js";
+
+const LEN = 2;
+
+function cursorResponseFrame({ text = "", thinking = "" }) {
+  const responseFields = [];
+
+  if (text) {
+    responseFields.push(encodeField(1, LEN, text));
+  }
+
+  if (thinking) {
+    const thinkingMessage = encodeField(1, LEN, thinking);
+    responseFields.push(encodeField(25, LEN, thinkingMessage));
+  }
+
+  const response = Buffer.concat(responseFields.map((field) => Buffer.from(field)));
+  const envelope = encodeField(2, LEN, response);
+  return Buffer.from(wrapConnectRPCFrame(envelope));
+}
+
+function parseSSE(text) {
+  return text
+    .split("\n\n")
+    .filter((chunk) => chunk.startsWith("data: "))
+    .map((chunk) => chunk.slice("data: ".length))
+    .filter((data) => data !== "[DONE]")
+    .map((data) => JSON.parse(data));
+}
+
+describe("CursorExecutor Composer thinking-field responses", () => {
+  it("uses visible content after </think> for non-streaming Composer responses", async () => {
+    const executor = new CursorExecutor();
+    const buffer = cursorResponseFrame({
+      thinking: "private reasoning that must not leak</think>OK",
+    });
+
+    const response = executor.transformProtobufToJSON(buffer, "cu/composer-2.5", {
+      messages: [{ role: "user", content: "reply OK" }],
+    });
+    const payload = await response.json();
+
+    expect(payload.choices[0].message.content).toBe("OK");
+    expect(JSON.stringify(payload)).not.toContain("private reasoning");
+    expect(payload.usage.completion_tokens).toBeGreaterThan(0);
+  });
+
+  it("streams only visible content after </think> for Composer responses", async () => {
+    const executor = new CursorExecutor();
+    const buffer = Buffer.concat([
+      cursorResponseFrame({ thinking: "private reasoning" }),
+      cursorResponseFrame({ thinking: " that must not leak</think>O" }),
+      cursorResponseFrame({ thinking: "K" }),
+    ]);
+
+    const response = executor.transformProtobufToSSE(buffer, "composer-2.5-fast", {
+      messages: [{ role: "user", content: "reply OK" }],
+    });
+    const events = parseSSE(await response.text());
+    const content = events
+      .map((event) => event.choices?.[0]?.delta?.content || "")
+      .join("");
+
+    expect(content).toBe("OK");
+    expect(JSON.stringify(events)).not.toContain("private reasoning");
+    expect(events.at(-1).usage.completion_tokens).toBeGreaterThan(0);
+  });
+
+  it("does not treat thinking as visible output for non-Composer models", async () => {
+    const executor = new CursorExecutor();
+    const buffer = cursorResponseFrame({
+      thinking: "private reasoning</think>SHOULD_NOT_APPEAR",
+    });
+
+    const response = executor.transformProtobufToJSON(buffer, "gpt-5.3-codex", {
+      messages: [{ role: "user", content: "hi" }],
+    });
+    const payload = await response.json();
+
+    expect(payload.choices[0].message.content).toBeNull();
+    expect(JSON.stringify(payload)).not.toContain("SHOULD_NOT_APPEAR");
+  });
+});
diff --git a/tests/unit/dashboard-guard.test.js b/tests/unit/dashboard-guard.test.js
new file mode 100644
index 0000000..099cbde
--- /dev/null
+++ b/tests/unit/dashboard-guard.test.js
@@ -0,0 +1,279 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  nextResponse: Symbol("next"),
+  jsonResponse: vi.fn((body, init) => ({
+    status: init?.status || 200,
+    body,
+  })),
+  getSettings: vi.fn(),
+  validateApiKey: vi.fn(),
+  getConsistentMachineId: vi.fn(),
+  verifyDashboardAuthToken: vi.fn(),
+}));
+
+vi.mock("next/server", () => ({
+  NextResponse: {
+    next: vi.fn(() => mocks.nextResponse),
+    json: mocks.jsonResponse,
+    redirect: vi.fn((url) => ({ status: 307, url })),
+  },
+}));
+
+vi.mock("@/lib/localDb", () => ({
+  getSettings: mocks.getSettings,
+  validateApiKey: mocks.validateApiKey,
+}));
+
+vi.mock("@/shared/utils/machineId", () => ({
+  getConsistentMachineId: mocks.getConsistentMachineId,
+}));
+
+vi.mock("@/lib/auth/dashboardSession", () => ({
+  verifyDashboardAuthToken: mocks.verifyDashboardAuthToken,
+}));
+
+const { proxy, __test__ } = await import("../../src/dashboardGuard.js");
+
+function request(pathname, headers = {}) {
+  const normalizedHeaders = new Headers(headers);
+  return {
+    nextUrl: { pathname, searchParams: new URL(`http://localhost${pathname}`).searchParams },
+    headers: normalizedHeaders,
+    cookies: { get: vi.fn(() => undefined) },
+    url: `http://localhost${pathname}`,
+  };
+}
+
+describe("dashboard guard public LLM API access", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getSettings.mockResolvedValue({ requireLogin: true });
+    mocks.validateApiKey.mockResolvedValue(false);
+    mocks.getConsistentMachineId.mockResolvedValue("cli-token");
+    mocks.verifyDashboardAuthToken.mockResolvedValue(false);
+  });
+
+  it("allows loopback public LLM API without API key", async () => {
+    const response = await proxy(request("/v1/chat/completions", { host: "localhost:20128" }));
+
+    expect(response).toBe(mocks.nextResponse);
+    expect(mocks.validateApiKey).not.toHaveBeenCalled();
+  });
+
+  it("rejects remote Host-spoof when real peer IP is non-loopback", async () => {
+    const response = await proxy(request("/v1/chat/completions", {
+      host: "localhost",
+      "x-9r-real-ip": "10.204.111.34",
+    }));
+
+    expect(response.status).toBe(401);
+    expect(response.body.error).toBe("API key required for remote API access");
+  });
+
+  it("allows loopback peer IP regardless of Host", async () => {
+    const response = await proxy(request("/v1/chat/completions", {
+      host: "localhost:20128",
+      "x-9r-real-ip": "127.0.0.1",
+    }));
+
+    expect(response).toBe(mocks.nextResponse);
+    expect(mocks.validateApiKey).not.toHaveBeenCalled();
+  });
+
+  it("rejects remote rewritten public LLM API without API key", async () => {
+    const response = await proxy(request("/api/v1/chat/completions", { host: "router.example.com" }));
+
+    expect(response.status).toBe(401);
+    expect(response.body.error).toBe("API key required for remote API access");
+  });
+
+  it("allows loopback rewritten public LLM API without API key", async () => {
+    const response = await proxy(request("/api/v1/chat/completions", { host: "localhost:20128" }));
+
+    expect(response).toBe(mocks.nextResponse);
+    expect(mocks.validateApiKey).not.toHaveBeenCalled();
+  });
+
+  it("rejects remote beta public LLM API without API key", async () => {
+    const response = await proxy(request("/v1beta/models", { host: "router.example.com" }));
+
+    expect(response.status).toBe(401);
+    expect(response.body.error).toBe("API key required for remote API access");
+  });
+
+  it("rejects remote rewritten beta public LLM API without API key", async () => {
+    const response = await proxy(request("/api/v1beta/models", { host: "router.example.com" }));
+
+    expect(response.status).toBe(401);
+    expect(response.body.error).toBe("API key required for remote API access");
+  });
+
+  it("rejects remote codex rewrite without API key", async () => {
+    const response = await proxy(request("/codex/x", { host: "router.example.com" }));
+
+    expect(response.status).toBe(401);
+    expect(response.body.error).toBe("API key required for remote API access");
+  });
+
+  it("allows remote codex rewrite with valid API key", async () => {
+    mocks.validateApiKey.mockResolvedValue(true);
+
+    const response = await proxy(request("/codex/x", {
+      host: "router.example.com",
+      authorization: "Bearer sk-valid",
+    }));
+
+    expect(response).toBe(mocks.nextResponse);
+    expect(mocks.validateApiKey).toHaveBeenCalledWith("sk-valid");
+  });
+
+  it("allows remote public LLM API with valid bearer API key", async () => {
+    mocks.validateApiKey.mockResolvedValue(true);
+
+    const response = await proxy(request("/api/v1/chat/completions", {
+      host: "router.example.com",
+      authorization: "Bearer sk-valid",
+    }));
+
+    expect(response).toBe(mocks.nextResponse);
+    expect(mocks.validateApiKey).toHaveBeenCalledWith("sk-valid");
+  });
+
+  it("allows remote public LLM API with valid x-api-key", async () => {
+    mocks.validateApiKey.mockResolvedValue(true);
+
+    const response = await proxy(request("/v1/web/fetch", {
+      host: "router.example.com",
+      "x-api-key": "sk-valid",
+    }));
+
+    expect(response).toBe(mocks.nextResponse);
+    expect(mocks.validateApiKey).toHaveBeenCalledWith("sk-valid");
+  });
+
+  it("allows remote rewritten beta public LLM API with valid API key", async () => {
+    mocks.validateApiKey.mockResolvedValue(true);
+
+    const response = await proxy(request("/api/v1beta/models", {
+      host: "router.example.com",
+      "x-api-key": "sk-valid",
+    }));
+
+    expect(response).toBe(mocks.nextResponse);
+    expect(mocks.validateApiKey).toHaveBeenCalledWith("sk-valid");
+  });
+
+  it("allows remote beta public LLM API with valid Google API key header", async () => {
+    mocks.validateApiKey.mockResolvedValue(true);
+
+    const response = await proxy(request("/v1beta/models", {
+      host: "router.example.com",
+      "x-goog-api-key": "sk-valid",
+    }));
+
+    expect(response).toBe(mocks.nextResponse);
+    expect(mocks.validateApiKey).toHaveBeenCalledWith("sk-valid");
+  });
+
+  it("allows remote beta public LLM API with valid Google key query parameter", async () => {
+    mocks.validateApiKey.mockResolvedValue(true);
+
+    const response = await proxy(request("/v1beta/models?key=sk-valid", {
+      host: "router.example.com",
+    }));
+
+    expect(response).toBe(mocks.nextResponse);
+    expect(mocks.validateApiKey).toHaveBeenCalledWith("sk-valid");
+  });
+});
+
+describe("dashboard guard local-only access", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getSettings.mockResolvedValue({ requireLogin: true });
+    mocks.validateApiKey.mockResolvedValue(false);
+    mocks.getConsistentMachineId.mockResolvedValue("cli-token");
+    mocks.verifyDashboardAuthToken.mockResolvedValue(false);
+  });
+
+  it("rejects local-only route from non-loopback host without CLI token", async () => {
+    const response = await proxy(request("/api/mcp/filesystem/sse", {
+      host: "router.example.com",
+    }));
+
+    expect(response.status).toBe(403);
+    expect(response.body.error).toBe("Local only: CLI token required");
+  });
+
+  it("rejects local-only route on loopback when requireLogin=true and no JWT", async () => {
+    const response = await proxy(request("/api/mcp/filesystem/sse", {
+      host: "localhost:20128",
+      origin: "http://localhost:20128",
+    }));
+
+    expect(response.status).toBe(403);
+    expect(response.body.error).toBe("Local only: CLI token required");
+  });
+
+  it("allows local-only route on loopback when requireLogin=false", async () => {
+    mocks.getSettings.mockResolvedValue({ requireLogin: false });
+
+    const response = await proxy(request("/api/cli-tools/antigravity-mitm", {
+      host: "localhost:20128",
+      origin: "http://localhost:20128",
+    }));
+
+    expect(response).toBe(mocks.nextResponse);
+  });
+
+  it("rejects local-only route from tunnel host even when requireLogin=false", async () => {
+    mocks.getSettings.mockResolvedValue({ requireLogin: false });
+
+    const response = await proxy(request("/api/cli-tools/antigravity-mitm", {
+      host: "router.example.com",
+    }));
+
+    expect(response.status).toBe(403);
+  });
+
+  it("rejects local-only route when Origin is non-loopback (CSRF block)", async () => {
+    mocks.getSettings.mockResolvedValue({ requireLogin: false });
+
+    const response = await proxy(request("/api/cli-tools/antigravity-mitm", {
+      host: "localhost:20128",
+      origin: "http://evil.example.com",
+    }));
+
+    expect(response.status).toBe(403);
+  });
+
+  it("allows local-only route with valid CLI token", async () => {
+    const response = await proxy(request("/api/mcp/filesystem/sse", {
+      host: "router.example.com",
+      "x-9r-cli-token": "cli-token",
+    }));
+
+    expect(response).toBe(mocks.nextResponse);
+  });
+});
+
+describe("dashboard guard helpers", () => {
+  it("extracts bearer API keys before x-api-key", () => {
+    const apiRequest = request("/v1/chat/completions", {
+      authorization: "Bearer bearer-key",
+      "x-api-key": "header-key",
+    });
+
+    expect(__test__.extractApiKey(apiRequest)).toBe("bearer-key");
+  });
+
+  it("extracts Google API keys after x-api-key", () => {
+    const apiRequest = request("/v1beta/models?key=query-key", {
+      "x-api-key": "header-key",
+      "x-goog-api-key": "google-key",
+    });
+
+    expect(__test__.extractApiKey(apiRequest)).toBe("header-key");
+  });
+});
diff --git a/tests/unit/db-benchmark.test.js b/tests/unit/db-benchmark.test.js
new file mode 100644
index 0000000..e1c382d
--- /dev/null
+++ b/tests/unit/db-benchmark.test.js
@@ -0,0 +1,174 @@
+// Benchmark: SQLite vs lowdb on equivalent workloads.
+// Run: cd app/tests && npm test -- db-benchmark
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, beforeAll, afterAll, vi } from "vitest";
+
+const N_ITEMS = 500;
+const N_QUERIES = 200;
+
+const originalDataDir = process.env.DATA_DIR;
+let tempSqlite, tempLowdb;
+let sqliteDb, lowDb;
+
+function fmt(ms) { return `${ms.toFixed(2)}ms`; }
+
+async function bench(label, fn) {
+  // warmup
+  await fn();
+  const t0 = performance.now();
+  await fn();
+  const dt = performance.now() - t0;
+  console.log(`  ${label.padEnd(40)} ${fmt(dt)}`);
+  return dt;
+}
+
+beforeAll(async () => {
+  // SQLite setup
+  tempSqlite = fs.mkdtempSync(path.join(os.tmpdir(), "9router-bench-sqlite-"));
+  process.env.DATA_DIR = tempSqlite;
+  vi.resetModules();
+  sqliteDb = await import("@/lib/db/index.js");
+  await sqliteDb.initDb();
+
+  // Lowdb setup — direct lowdb usage (mimics legacy behavior)
+  tempLowdb = fs.mkdtempSync(path.join(os.tmpdir(), "9router-bench-lowdb-"));
+  const { Low } = await import("lowdb");
+  const { JSONFile } = await import("lowdb/node");
+  const dbFile = path.join(tempLowdb, "db.json");
+  fs.writeFileSync(dbFile, JSON.stringify({ providerConnections: [], usageHistory: [] }));
+  lowDb = new Low(new JSONFile(dbFile), { providerConnections: [], usageHistory: [] });
+  await lowDb.read();
+});
+
+afterAll(() => {
+  if (tempSqlite) fs.rmSync(tempSqlite, { recursive: true, force: true });
+  if (tempLowdb) fs.rmSync(tempLowdb, { recursive: true, force: true });
+  if (originalDataDir === undefined) delete process.env.DATA_DIR;
+  else process.env.DATA_DIR = originalDataDir;
+});
+
+describe("DB Benchmark — SQLite vs Lowdb", () => {
+  it(`INSERT ${N_ITEMS} provider connections`, async () => {
+    console.log(`\n[INSERT ${N_ITEMS}]`);
+
+    const sqliteTime = await bench("SQLite createProviderConnection", async () => {
+      for (let i = 0; i < N_ITEMS; i++) {
+        await sqliteDb.createProviderConnection({
+          provider: `bench-p${i % 5}`, authType: "apikey",
+          name: `name-${i}`, apiKey: `k-${i}`,
+        });
+      }
+    });
+
+    const lowdbTime = await bench("Lowdb push + write", async () => {
+      for (let i = 0; i < N_ITEMS; i++) {
+        lowDb.data.providerConnections.push({
+          id: `id-${i}`, provider: `bench-p${i % 5}`, authType: "apikey",
+          name: `name-${i}`, apiKey: `k-${i}`, priority: i + 1, isActive: true,
+          createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(),
+        });
+        await lowDb.write();
+      }
+    });
+
+    const speedup = (lowdbTime / sqliteTime).toFixed(2);
+    console.log(`  → SQLite is ${speedup}x faster`);
+  }, 60000);
+
+  it(`READ ${N_QUERIES} filtered queries`, async () => {
+    console.log(`\n[READ ${N_QUERIES} filtered queries]`);
+
+    const sqliteTime = await bench("SQLite getProviderConnections(filter)", async () => {
+      for (let i = 0; i < N_QUERIES; i++) {
+        await sqliteDb.getProviderConnections({ provider: `bench-p${i % 5}` });
+      }
+    });
+
+    const lowdbTime = await bench("Lowdb read + filter", async () => {
+      for (let i = 0; i < N_QUERIES; i++) {
+        await lowDb.read();
+        lowDb.data.providerConnections.filter((c) => c.provider === `bench-p${i % 5}`);
+      }
+    });
+
+    const speedup = (lowdbTime / sqliteTime).toFixed(2);
+    console.log(`  → SQLite is ${speedup}x faster`);
+  }, 60000);
+
+  it(`READ ${N_QUERIES} by id (point lookup)`, async () => {
+    console.log(`\n[READ ${N_QUERIES} by id]`);
+
+    const sqliteAll = await sqliteDb.getProviderConnections();
+    const ids = sqliteAll.slice(0, N_QUERIES).map((c) => c.id);
+
+    const sqliteTime = await bench("SQLite getProviderConnectionById", async () => {
+      for (const id of ids) await sqliteDb.getProviderConnectionById(id);
+    });
+
+    const lowdbIds = lowDb.data.providerConnections.slice(0, N_QUERIES).map((c) => c.id);
+    const lowdbTime = await bench("Lowdb find by id", async () => {
+      for (const id of lowdbIds) {
+        await lowDb.read();
+        lowDb.data.providerConnections.find((c) => c.id === id);
+      }
+    });
+
+    const speedup = (lowdbTime / sqliteTime).toFixed(2);
+    console.log(`  → SQLite is ${speedup}x faster`);
+  }, 60000);
+
+  it(`saveRequestUsage ${N_ITEMS} entries`, async () => {
+    console.log(`\n[saveRequestUsage ${N_ITEMS}]`);
+
+    const sqliteTime = await bench("SQLite saveRequestUsage", async () => {
+      for (let i = 0; i < N_ITEMS; i++) {
+        await sqliteDb.saveRequestUsage({
+          provider: "openai", model: `m-${i % 10}`, connectionId: `c-${i % 5}`,
+          tokens: { prompt_tokens: 100 + i, completion_tokens: 50 + i },
+          endpoint: "/v1/chat/completions", status: "ok",
+        });
+      }
+    });
+
+    const lowdbTime = await bench("Lowdb push history + write", async () => {
+      lowDb.data.usageHistory = [];
+      for (let i = 0; i < N_ITEMS; i++) {
+        lowDb.data.usageHistory.push({
+          timestamp: new Date().toISOString(), provider: "openai", model: `m-${i % 10}`,
+          connectionId: `c-${i % 5}`, tokens: { prompt_tokens: 100 + i, completion_tokens: 50 + i },
+          endpoint: "/v1/chat/completions", status: "ok", cost: 0,
+        });
+        await lowDb.write();
+      }
+    });
+
+    const speedup = (lowdbTime / sqliteTime).toFixed(2);
+    console.log(`  → SQLite is ${speedup}x faster`);
+  }, 120000);
+
+  it(`getUsageStats(24h) repeat 50x`, async () => {
+    console.log(`\n[getUsageStats(24h) x 50]`);
+
+    const sqliteTime = await bench("SQLite getUsageStats(24h)", async () => {
+      for (let i = 0; i < 50; i++) await sqliteDb.getUsageStats("24h");
+    });
+
+    const lowdbTime = await bench("Lowdb read + aggregate", async () => {
+      for (let i = 0; i < 50; i++) {
+        await lowDb.read();
+        const cutoff = Date.now() - 86400000;
+        const hist = lowDb.data.usageHistory.filter((h) => new Date(h.timestamp).getTime() >= cutoff);
+        const stats = { byProvider: {}, byModel: {} };
+        for (const e of hist) {
+          if (!stats.byProvider[e.provider]) stats.byProvider[e.provider] = { requests: 0 };
+          stats.byProvider[e.provider].requests++;
+        }
+      }
+    });
+
+    const speedup = (lowdbTime / sqliteTime).toFixed(2);
+    console.log(`  → SQLite is ${speedup}x faster`);
+  }, 60000);
+});
diff --git a/tests/unit/db-concurrent.test.js b/tests/unit/db-concurrent.test.js
new file mode 100644
index 0000000..0b2ebac
--- /dev/null
+++ b/tests/unit/db-concurrent.test.js
@@ -0,0 +1,171 @@
+// Concurrency stress test — simulate many parallel saveRequestUsage / saveRequestDetail
+// to verify atomic counter, no data loss, no race conditions.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
+
+const originalDataDir = process.env.DATA_DIR;
+let tempDir;
+let db;
+
+beforeAll(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "9router-concurrent-"));
+  process.env.DATA_DIR = tempDir;
+  vi.resetModules();
+  db = await import("@/lib/db/index.js");
+  await db.initDb();
+});
+
+afterAll(() => {
+  if (tempDir) fs.rmSync(tempDir, { recursive: true, force: true });
+  if (originalDataDir === undefined) delete process.env.DATA_DIR;
+  else process.env.DATA_DIR = originalDataDir;
+});
+
+describe("DB Concurrency — atomic safety", () => {
+  it("100 parallel saveRequestUsage → no count loss", async () => {
+    const N = 100;
+    const promises = [];
+    for (let i = 0; i < N; i++) {
+      promises.push(db.saveRequestUsage({
+        provider: "openai", model: "gpt-4", connectionId: "c1",
+        tokens: { prompt_tokens: 10, completion_tokens: 5 },
+        endpoint: "/v1/chat", status: "ok",
+      }));
+    }
+    await Promise.all(promises);
+
+    const stats = await db.getUsageStats("24h");
+    expect(stats.totalRequests).toBe(N);
+    expect(stats.byProvider.openai.requests).toBe(N);
+    expect(stats.byProvider.openai.promptTokens).toBe(N * 10);
+
+    const hist = await db.getUsageHistory({ provider: "openai" });
+    expect(hist.length).toBe(N);
+  });
+
+  it("200 parallel saveRequestDetail → all flushed", async () => {
+    await db.updateSettings({ enableObservability: true, observabilityBatchSize: 10 });
+
+    const N = 200;
+    const promises = [];
+    for (let i = 0; i < N; i++) {
+      promises.push(db.saveRequestDetail({
+        id: `det-${i}`, provider: "openai", model: "gpt-4",
+        connectionId: "c1", status: "ok",
+        tokens: { prompt_tokens: 1 }, request: { i }, response: { ok: true },
+      }));
+    }
+    await Promise.all(promises);
+
+    // Wait for any timer-based flush
+    await new Promise((r) => setTimeout(r, 6000));
+
+    const list = await db.getRequestDetails({ provider: "openai", pageSize: 500 });
+    expect(list.pagination.totalItems).toBeGreaterThanOrEqual(N);
+  }, 15000);
+
+  it("mixed concurrent: usage + details + connections + aliases", async () => {
+    const ops = [];
+    for (let i = 0; i < 50; i++) {
+      ops.push(db.saveRequestUsage({
+        provider: "anthropic", model: `m-${i % 3}`, connectionId: "c2",
+        tokens: { prompt_tokens: 20 }, status: "ok",
+      }));
+      ops.push(db.setModelAlias(`a-${i}`, `target-${i}`));
+      ops.push(db.disableModels("openai", [`d-${i}`]));
+    }
+    await Promise.all(ops);
+
+    const aliases = await db.getModelAliases();
+    expect(Object.keys(aliases).filter((k) => k.startsWith("a-")).length).toBe(50);
+
+    const disabled = await db.getDisabledByProvider("openai");
+    expect(disabled.length).toBeGreaterThanOrEqual(50);
+
+    const stats = await db.getUsageStats("24h");
+    expect(stats.byProvider.anthropic.requests).toBe(50);
+  }, 30000);
+
+  it("updateSettings parallel → no merge loss", async () => {
+    const N = 50;
+    await db.updateSettings({ counter: 0 });
+    const promises = [];
+    for (let i = 0; i < N; i++) {
+      promises.push(db.updateSettings({ [`field${i}`]: `v${i}` }));
+    }
+    await Promise.all(promises);
+    const s = await db.getSettings();
+    for (let i = 0; i < N; i++) {
+      expect(s[`field${i}`]).toBe(`v${i}`); // all updates preserved
+    }
+  });
+
+  it("OAuth refresh race: parallel updateProviderConnection on same id", async () => {
+    const conn = await db.createProviderConnection({
+      provider: "oauth-test", authType: "oauth", email: "x@y.com",
+      accessToken: "initial", refreshToken: "rt-initial",
+    });
+
+    // 20 parallel updates each with a unique field
+    const N = 20;
+    const promises = [];
+    for (let i = 0; i < N; i++) {
+      promises.push(db.updateProviderConnection(conn.id, { [`marker${i}`]: i }));
+    }
+    await Promise.all(promises);
+
+    const after = await db.getProviderConnectionById(conn.id);
+    for (let i = 0; i < N; i++) {
+      expect(after[`marker${i}`]).toBe(i); // no field lost
+    }
+    expect(after.refreshToken).toBe("rt-initial"); // base preserved
+  });
+
+  it("addCustomModel race: parallel duplicate adds → only 1 inserted", async () => {
+    const N = 30;
+    const promises = [];
+    for (let i = 0; i < N; i++) {
+      promises.push(db.addCustomModel({ providerAlias: "racep", id: "racemodel", type: "llm", name: "r" }));
+    }
+    const results = await Promise.all(promises);
+    const trueCount = results.filter((r) => r === true).length;
+    expect(trueCount).toBe(1); // exactly one wins
+    const all = await db.getCustomModels();
+    expect(all.filter((m) => m.providerAlias === "racep" && m.id === "racemodel").length).toBe(1);
+  });
+
+  it("updatePricing race: parallel adds different models → all merged", async () => {
+    const N = 30;
+    const promises = [];
+    for (let i = 0; i < N; i++) {
+      promises.push(db.updatePricing({ "race-prov": { [`m${i}`]: { input: i, output: i * 2 } } }));
+    }
+    await Promise.all(promises);
+    const p = await db.getPricing();
+    for (let i = 0; i < N; i++) {
+      expect(p["race-prov"][`m${i}`]).toEqual({ input: i, output: i * 2 });
+    }
+  });
+
+  it("daily summary aggregates correctly under parallel writes", async () => {
+    const N = 50;
+    const promises = [];
+    for (let i = 0; i < N; i++) {
+      promises.push(db.saveRequestUsage({
+        provider: "google", model: "gemini-pro", connectionId: "cG",
+        tokens: { prompt_tokens: 100, completion_tokens: 50 },
+        status: "ok",
+      }));
+    }
+    await Promise.all(promises);
+
+    const stats = await db.getUsageStats("7d");
+    const g = stats.byProvider.google;
+    expect(g).toBeDefined();
+    expect(g.requests).toBe(N);
+    expect(g.promptTokens).toBe(N * 100);
+    expect(g.completionTokens).toBe(N * 50);
+  });
+});
diff --git a/tests/unit/db-driver-chain.test.js b/tests/unit/db-driver-chain.test.js
new file mode 100644
index 0000000..cc96d5a
--- /dev/null
+++ b/tests/unit/db-driver-chain.test.js
@@ -0,0 +1,59 @@
+// Verify 3-tier driver fallback: better-sqlite3 → node:sqlite → sql.js
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+let tempDir;
+const originalDataDir = process.env.DATA_DIR;
+
+beforeEach(() => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "9router-chain-"));
+  process.env.DATA_DIR = tempDir;
+  delete global._dbAdapter;
+  vi.resetModules();
+});
+
+afterEach(() => {
+  try { global._dbAdapter?.instance?.close?.(); } catch {}
+  delete global._dbAdapter;
+  if (tempDir) fs.rmSync(tempDir, { recursive: true, force: true });
+  if (originalDataDir === undefined) delete process.env.DATA_DIR;
+  else process.env.DATA_DIR = originalDataDir;
+});
+
+describe("Driver fallback chain", () => {
+  it("default → picks better-sqlite3 when available", async () => {
+    const { getAdapter } = await import("@/lib/db/driver.js");
+    const db = await getAdapter();
+    expect(["better-sqlite3", "node:sqlite", "sql.js"]).toContain(db.driver);
+  });
+
+  it("falls back to node:sqlite when better-sqlite3 unavailable", async () => {
+    // Mock the better-sqlite3 adapter to throw
+    vi.doMock("@/lib/db/adapters/betterSqliteAdapter.js", () => {
+      throw new Error("simulated unavailable");
+    });
+    const { getAdapter } = await import("@/lib/db/driver.js");
+    const db = await getAdapter();
+    // Node 22.5+ should give node:sqlite, else sql.js
+    const [maj, min] = process.versions.node.split(".").map(Number);
+    if (maj > 22 || (maj === 22 && min >= 5)) {
+      expect(db.driver).toBe("node:sqlite");
+    } else {
+      expect(db.driver).toBe("sql.js");
+    }
+  });
+
+  it("falls back to sql.js when both native drivers unavailable", async () => {
+    vi.doMock("@/lib/db/adapters/betterSqliteAdapter.js", () => {
+      throw new Error("simulated unavailable");
+    });
+    vi.doMock("@/lib/db/adapters/nodeSqliteAdapter.js", () => {
+      throw new Error("simulated unavailable");
+    });
+    const { getAdapter } = await import("@/lib/db/driver.js");
+    const db = await getAdapter();
+    expect(db.driver).toBe("sql.js");
+  });
+});
diff --git a/tests/unit/db-migration-chain.test.js b/tests/unit/db-migration-chain.test.js
new file mode 100644
index 0000000..4a0a4c5
--- /dev/null
+++ b/tests/unit/db-migration-chain.test.js
@@ -0,0 +1,100 @@
+// Verify schema migration chain runs correctly across versions.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+let tempDir;
+const originalDataDir = process.env.DATA_DIR;
+
+beforeEach(() => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "9router-mig-"));
+  process.env.DATA_DIR = tempDir;
+  // Reset global singleton so each test gets fresh adapter pointed at tempDir
+  delete global._dbAdapter;
+  vi.resetModules();
+});
+
+afterEach(() => {
+  // Close adapter to release file handles before rm
+  try { global._dbAdapter?.instance?.close?.(); } catch {}
+  delete global._dbAdapter;
+  if (tempDir) fs.rmSync(tempDir, { recursive: true, force: true });
+  if (originalDataDir === undefined) delete process.env.DATA_DIR;
+  else process.env.DATA_DIR = originalDataDir;
+});
+
+describe("Schema migrations", () => {
+  it("fresh DB → applies migrations & stamps schemaVersion", async () => {
+    const { getAdapter } = await import("@/lib/db/driver.js");
+    const { latestVersion } = await import("@/lib/db/migrations/index.js");
+    const db = await getAdapter();
+    const row = db.get(`SELECT value FROM _meta WHERE key='schemaVersion'`);
+    expect(parseInt(row.value, 10)).toBe(latestVersion());
+
+    const tables = db.all(`SELECT name FROM sqlite_master WHERE type='table'`).map(t => t.name);
+    expect(tables).toEqual(expect.arrayContaining([
+      "_meta", "settings", "providerConnections", "providerNodes",
+      "proxyPools", "apiKeys", "combos", "kv", "usageHistory", "usageDaily", "requestDetails",
+    ]));
+  });
+
+  it("existing DB at older schemaVersion → re-applies pending migrations on restart", async () => {
+    // 1st boot
+    const { getAdapter } = await import("@/lib/db/driver.js");
+    const db = await getAdapter();
+    db.run(`INSERT INTO settings(id, data) VALUES(1, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data`, ['{"foo":"bar"}']);
+    db.run(`UPDATE _meta SET value = '0' WHERE key = 'schemaVersion'`);
+    db.close?.();
+
+    // 2nd boot: full reset to simulate process restart
+    delete global._dbAdapter;
+    vi.resetModules();
+    const { getAdapter: getAdapter2 } = await import("@/lib/db/driver.js");
+    const { latestVersion } = await import("@/lib/db/migrations/index.js");
+    const db2 = await getAdapter2();
+    const row = db2.get(`SELECT value FROM _meta WHERE key='schemaVersion'`);
+    expect(parseInt(row.value, 10)).toBe(latestVersion());
+
+    const settings = db2.get(`SELECT data FROM settings WHERE id=1`);
+    expect(JSON.parse(settings.data)).toEqual({ foo: "bar" });
+  });
+
+  it("fresh DB + legacy db.json → imports data automatically", async () => {
+    // Simulate user upgrading: place legacy JSON in DATA_DIR before first boot
+    const legacy = {
+      settings: { foo: "legacy-value" },
+      apiKeys: [{ id: "k1", key: "abc", name: "test", createdAt: new Date().toISOString() }],
+      modelAliases: { "gpt-4": "gpt-4-turbo" },
+    };
+    fs.writeFileSync(path.join(tempDir, "db.json"), JSON.stringify(legacy));
+
+    const { getAdapter } = await import("@/lib/db/driver.js");
+    const db = await getAdapter();
+
+    const settings = db.get(`SELECT data FROM settings WHERE id=1`);
+    expect(JSON.parse(settings.data)).toEqual({ foo: "legacy-value" });
+
+    const keys = db.all(`SELECT * FROM apiKeys`);
+    expect(keys).toHaveLength(1);
+    expect(keys[0].key).toBe("abc");
+
+    const aliases = db.all(`SELECT * FROM kv WHERE scope='modelAliases'`);
+    expect(aliases).toHaveLength(1);
+  });
+
+  it("auto-sync re-creates missing index when DB lacks it", async () => {
+    const { getAdapter } = await import("@/lib/db/driver.js");
+    const db = await getAdapter();
+    db.exec(`DROP INDEX IF EXISTS idx_pn_type`);
+    expect(db.all(`PRAGMA index_list(providerNodes)`).map(i => i.name)).not.toContain("idx_pn_type");
+    db.close?.();
+
+    delete global._dbAdapter;
+    vi.resetModules();
+    const { getAdapter: getAdapter2 } = await import("@/lib/db/driver.js");
+    const db2 = await getAdapter2();
+    const idx = db2.all(`PRAGMA index_list(providerNodes)`).map(i => i.name);
+    expect(idx).toContain("idx_pn_type");
+  });
+});
diff --git a/tests/unit/db-sqlite-vs-lowdb.test.js b/tests/unit/db-sqlite-vs-lowdb.test.js
new file mode 100644
index 0000000..52a8088
--- /dev/null
+++ b/tests/unit/db-sqlite-vs-lowdb.test.js
@@ -0,0 +1,287 @@
+// Compare new SQLite-backed DB layer vs legacy lowdb behavior.
+// Verifies: same public API signatures + equivalent results for core operations.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
+
+const originalDataDir = process.env.DATA_DIR;
+let tempDir;
+let sqliteDb;
+
+beforeAll(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "9router-db-compare-"));
+  process.env.DATA_DIR = tempDir;
+  vi.resetModules();
+  sqliteDb = await import("@/lib/db/index.js");
+  await sqliteDb.initDb();
+});
+
+afterAll(() => {
+  if (tempDir) fs.rmSync(tempDir, { recursive: true, force: true });
+  if (originalDataDir === undefined) delete process.env.DATA_DIR;
+  else process.env.DATA_DIR = originalDataDir;
+});
+
+describe("DB SQLite layer — public API parity", () => {
+  it("settings: get → defaults; update → merge", async () => {
+    const s = await sqliteDb.getSettings();
+    expect(s).toBeDefined();
+    expect(s.cloudEnabled).toBe(false);
+    expect(s.requireLogin).toBe(true);
+
+    const updated = await sqliteDb.updateSettings({ cloudEnabled: true, customField: "x" });
+    expect(updated.cloudEnabled).toBe(true);
+    expect(updated.customField).toBe("x");
+    expect(updated.requireLogin).toBe(true); // default preserved
+
+    const re = await sqliteDb.getSettings();
+    expect(re.cloudEnabled).toBe(true);
+    expect(re.customField).toBe("x");
+  });
+
+  it("isCloudEnabled reflects settings", async () => {
+    await sqliteDb.updateSettings({ cloudEnabled: true });
+    expect(await sqliteDb.isCloudEnabled()).toBe(true);
+    await sqliteDb.updateSettings({ cloudEnabled: false });
+    expect(await sqliteDb.isCloudEnabled()).toBe(false);
+  });
+
+  it("apiKeys: create/get/validate/delete", async () => {
+    const k = await sqliteDb.createApiKey("test-key", "machine-abc");
+    expect(k.id).toBeDefined();
+    expect(k.key).toMatch(/^sk-/);
+    expect(k.machineId).toBe("machine-abc");
+    expect(k.isActive).toBe(true);
+
+    const all = await sqliteDb.getApiKeys();
+    expect(all.find((x) => x.id === k.id)).toBeDefined();
+
+    expect(await sqliteDb.validateApiKey(k.key)).toBeTruthy();
+    expect(await sqliteDb.validateApiKey("invalid")).toBeFalsy();
+
+    const deleted = await sqliteDb.deleteApiKey(k.id);
+    expect(deleted).toBe(true);
+    expect(await sqliteDb.getApiKeyById(k.id)).toBeNull();
+  });
+
+  it("providerConnections: CRUD + reorder by priority", async () => {
+    const c1 = await sqliteDb.createProviderConnection({ provider: "test", authType: "apikey", name: "a", apiKey: "k1" });
+    const c2 = await sqliteDb.createProviderConnection({ provider: "test", authType: "apikey", name: "b", apiKey: "k2" });
+    const c3 = await sqliteDb.createProviderConnection({ provider: "test", authType: "apikey", name: "c", apiKey: "k3" });
+
+    const list = await sqliteDb.getProviderConnections({ provider: "test" });
+    expect(list).toHaveLength(3);
+    expect(list[0].priority).toBe(1);
+    expect(list[1].priority).toBe(2);
+    expect(list[2].priority).toBe(3);
+
+    // Update priority and reorder
+    await sqliteDb.updateProviderConnection(c3.id, { priority: 1 });
+    const reordered = await sqliteDb.getProviderConnections({ provider: "test" });
+    expect(reordered[0].name).toBe("c");
+
+    // Delete reorders remaining
+    await sqliteDb.deleteProviderConnection(c1.id);
+    const after = await sqliteDb.getProviderConnections({ provider: "test" });
+    expect(after).toHaveLength(2);
+    expect(after.every((c) => [1, 2].includes(c.priority))).toBe(true);
+  });
+
+  it("providerConnections: optional fields persisted via JSON column", async () => {
+    const c = await sqliteDb.createProviderConnection({
+      provider: "p2", authType: "oauth", email: "x@y.com",
+      accessToken: "tok", refreshToken: "rtok", expiresAt: 12345,
+      providerSpecificData: { foo: "bar" },
+    });
+    const back = await sqliteDb.getProviderConnectionById(c.id);
+    expect(back.accessToken).toBe("tok");
+    expect(back.refreshToken).toBe("rtok");
+    expect(back.expiresAt).toBe(12345);
+    expect(back.providerSpecificData).toEqual({ foo: "bar" });
+  });
+
+  it("providerConnections: GitHub OAuth uses account identity as fallback name", async () => {
+    const c = await sqliteDb.createProviderConnection({
+      provider: "github",
+      authType: "oauth",
+      accessToken: "tok",
+      providerSpecificData: { githubLogin: "octocat" },
+    });
+
+    expect(c.name).toBe("octocat");
+    const back = await sqliteDb.getProviderConnectionById(c.id);
+    expect(back.name).toBe("octocat");
+  });
+
+  it("providerNodes: CRUD", async () => {
+    const n = await sqliteDb.createProviderNode({ type: "openai", name: "Test", baseUrl: "https://api.test", apiType: "openai" });
+    expect(n.id).toBeDefined();
+    expect(n.baseUrl).toBe("https://api.test");
+
+    const all = await sqliteDb.getProviderNodes({ type: "openai" });
+    expect(all.find((x) => x.id === n.id)).toBeDefined();
+
+    await sqliteDb.updateProviderNode(n.id, { name: "Test2" });
+    const updated = await sqliteDb.getProviderNodeById(n.id);
+    expect(updated.name).toBe("Test2");
+
+    await sqliteDb.deleteProviderNode(n.id);
+    expect(await sqliteDb.getProviderNodeById(n.id)).toBeNull();
+  });
+
+  it("proxyPools: CRUD with sort by updatedAt desc", async () => {
+    const p1 = await sqliteDb.createProxyPool({ name: "p1", proxyUrl: "http://a", type: "http" });
+    await new Promise((r) => setTimeout(r, 10));
+    const p2 = await sqliteDb.createProxyPool({ name: "p2", proxyUrl: "http://b", type: "http" });
+    const list = await sqliteDb.getProxyPools();
+    expect(list[0].id).toBe(p2.id); // newest first
+    await sqliteDb.deleteProxyPool(p1.id);
+    await sqliteDb.deleteProxyPool(p2.id);
+  });
+
+  it("combos: CRUD", async () => {
+    const c = await sqliteDb.createCombo({ name: "combo1", models: ["m1", "m2"], kind: "fallback" });
+    expect(c.id).toBeDefined();
+    expect(c.models).toEqual(["m1", "m2"]);
+    const byName = await sqliteDb.getComboByName("combo1");
+    expect(byName.id).toBe(c.id);
+    await sqliteDb.updateCombo(c.id, { models: ["m3"] });
+    const updated = await sqliteDb.getComboById(c.id);
+    expect(updated.models).toEqual(["m3"]);
+    expect(await sqliteDb.deleteCombo(c.id)).toBe(true);
+  });
+
+  it("modelAliases: KV ops", async () => {
+    await sqliteDb.setModelAlias("alias1", "real-model-1");
+    await sqliteDb.setModelAlias("alias2", "real-model-2");
+    const all = await sqliteDb.getModelAliases();
+    expect(all.alias1).toBe("real-model-1");
+    expect(all.alias2).toBe("real-model-2");
+    await sqliteDb.deleteModelAlias("alias1");
+    expect((await sqliteDb.getModelAliases()).alias1).toBeUndefined();
+  });
+
+  it("customModels: add/list/delete with dedupe", async () => {
+    const ok1 = await sqliteDb.addCustomModel({ providerAlias: "p1", id: "m1", type: "llm", name: "Model 1" });
+    const dup = await sqliteDb.addCustomModel({ providerAlias: "p1", id: "m1", type: "llm" });
+    expect(ok1).toBe(true);
+    expect(dup).toBe(false);
+    const list = await sqliteDb.getCustomModels();
+    expect(list.find((m) => m.id === "m1")).toBeDefined();
+    await sqliteDb.deleteCustomModel({ providerAlias: "p1", id: "m1" });
+    const after = await sqliteDb.getCustomModels();
+    expect(after.find((m) => m.id === "m1")).toBeUndefined();
+  });
+
+  it("mitmAlias: get/set per tool", async () => {
+    await sqliteDb.setMitmAliasAll("cursor", { "gpt-5": "claude-3" });
+    const a = await sqliteDb.getMitmAlias("cursor");
+    expect(a["gpt-5"]).toBe("claude-3");
+    const all = await sqliteDb.getMitmAlias();
+    expect(all.cursor).toEqual({ "gpt-5": "claude-3" });
+  });
+
+  it("disabledModels: add/remove per provider", async () => {
+    await sqliteDb.disableModels("openai", ["gpt-3", "gpt-4"]);
+    expect(await sqliteDb.getDisabledByProvider("openai")).toEqual(expect.arrayContaining(["gpt-3", "gpt-4"]));
+    await sqliteDb.enableModels("openai", ["gpt-3"]);
+    expect(await sqliteDb.getDisabledByProvider("openai")).toEqual(["gpt-4"]);
+    await sqliteDb.enableModels("openai", []);
+    expect(await sqliteDb.getDisabledByProvider("openai")).toEqual([]);
+  });
+
+  it("usage: saveRequestUsage + getUsageHistory + getUsageStats", async () => {
+    await sqliteDb.saveRequestUsage({
+      provider: "openai", model: "gpt-4", connectionId: "c1",
+      tokens: { prompt_tokens: 100, completion_tokens: 50 },
+      endpoint: "/v1/chat/completions", status: "ok",
+    });
+    await sqliteDb.saveRequestUsage({
+      provider: "openai", model: "gpt-4", connectionId: "c1",
+      tokens: { prompt_tokens: 200, completion_tokens: 100 },
+      endpoint: "/v1/chat/completions", status: "ok",
+    });
+
+    const hist = await sqliteDb.getUsageHistory({ provider: "openai" });
+    expect(hist.length).toBeGreaterThanOrEqual(2);
+    expect(hist[0].tokens.prompt_tokens).toBeDefined();
+
+    const stats = await sqliteDb.getUsageStats("24h");
+    expect(stats.totalRequests).toBeGreaterThanOrEqual(2);
+    expect(stats.byProvider.openai).toBeDefined();
+    expect(stats.byProvider.openai.requests).toBeGreaterThanOrEqual(2);
+    expect(stats.byProvider.openai.promptTokens).toBeGreaterThanOrEqual(300);
+  });
+
+  it("usage: pending tracking in-memory", () => {
+    sqliteDb.trackPendingRequest("gpt-4", "openai", "c1", true);
+    expect(global._pendingRequests.byModel["gpt-4 (openai)"]).toBe(1);
+    sqliteDb.trackPendingRequest("gpt-4", "openai", "c1", false);
+    expect(global._pendingRequests.byModel["gpt-4 (openai)"]).toBeUndefined();
+  });
+
+  it("requestDetails: save → query with paging", async () => {
+    // Enable observability first
+    await sqliteDb.updateSettings({ enableObservability: true, observabilityBatchSize: 1 });
+
+    await sqliteDb.saveRequestDetail({
+      id: "d1", provider: "openai", model: "gpt-4", connectionId: "c1",
+      status: "ok", tokens: { prompt_tokens: 10 },
+      request: { method: "POST" }, response: { status: 200 },
+    });
+
+    // Wait for buffer flush
+    await new Promise((r) => setTimeout(r, 200));
+
+    const got = await sqliteDb.getRequestDetailById("d1");
+    expect(got).toBeDefined();
+    expect(got.id).toBe("d1");
+
+    const list = await sqliteDb.getRequestDetails({ provider: "openai" });
+    expect(list.details.length).toBeGreaterThanOrEqual(1);
+    expect(list.pagination.totalItems).toBeGreaterThanOrEqual(1);
+  });
+
+  it("exportDb / importDb roundtrip", async () => {
+    const exported = await sqliteDb.exportDb();
+    expect(exported.settings).toBeDefined();
+    expect(Array.isArray(exported.providerConnections)).toBe(true);
+    expect(typeof exported.modelAliases).toBe("object");
+
+    // Add marker, export, import a different payload, verify reset
+    await sqliteDb.setModelAlias("marker", "before");
+    const snap = await sqliteDb.exportDb();
+
+    await sqliteDb.setModelAlias("marker", "after");
+    expect((await sqliteDb.getModelAliases()).marker).toBe("after");
+
+    await sqliteDb.importDb(snap);
+    expect((await sqliteDb.getModelAliases()).marker).toBe("before");
+  });
+
+  it("pricing: user pricing merged with constants", async () => {
+    await sqliteDb.updatePricing({ openai: { "gpt-test": { input: 1, output: 2 } } });
+    const p = await sqliteDb.getPricing();
+    expect(p.openai["gpt-test"]).toEqual({ input: 1, output: 2 });
+
+    const single = await sqliteDb.getPricingForModel("openai", "gpt-test");
+    expect(single).toEqual({ input: 1, output: 2 });
+
+    await sqliteDb.resetPricing("openai", "gpt-test");
+    expect((await sqliteDb.getPricing()).openai?.["gpt-test"]).toBeUndefined();
+  });
+
+  it("getChartData: 24h buckets", async () => {
+    const data = await sqliteDb.getChartData("24h");
+    expect(data).toHaveLength(24);
+    expect(data[0]).toHaveProperty("label");
+    expect(data[0]).toHaveProperty("tokens");
+    expect(data[0]).toHaveProperty("cost");
+  });
+
+  it("getChartData: 7d buckets", async () => {
+    const data = await sqliteDb.getChartData("7d");
+    expect(data).toHaveLength(7);
+  });
+});
diff --git a/tests/unit/embeddings.cloud.test.js b/tests/unit/embeddings.cloud.test.js
new file mode 100644
index 0000000..725f7dd
--- /dev/null
+++ b/tests/unit/embeddings.cloud.test.js
@@ -0,0 +1,524 @@
+/**
+ * Unit tests for cloud/src/handlers/embeddings.js
+ *
+ * Tests cover:
+ *  - CORS OPTIONS → 200 with CORS headers
+ *  - Auth: missing Bearer → 401
+ *  - Auth: invalid key format → 401
+ *  - Auth: valid new-format key but wrong key value → 401
+ *  - Body validation: missing model → 400, missing input → 400
+ *  - Invalid model format → 400
+ *  - Happy path → delegates to handleEmbeddingsCore and returns response
+ *  - Rate-limited provider → 503 with Retry-After
+ *  - No credentials → 400
+ *
+ * Strategy: mock all external dependencies (D1 storage, handleEmbeddingsCore, apiKey utils)
+ * so tests run without Cloudflare Workers runtime.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// ─── Module mocks (hoisted before imports) ───────────────────────────────────
+
+vi.mock("../../open-sse/services/model.js", () => ({
+  getModelInfoCore: vi.fn(),
+}));
+
+vi.mock("../../open-sse/handlers/embeddingsCore.js", () => ({
+  handleEmbeddingsCore: vi.fn(),
+}));
+
+vi.mock("../../open-sse/utils/error.js", async (importOriginal) => {
+  // Use real errorResponse implementation so response bodies are realistic
+  const actual = await importOriginal();
+  return actual;
+});
+
+vi.mock("../../open-sse/services/accountFallback.js", async (importOriginal) => {
+  const actual = await importOriginal();
+  return actual;
+});
+
+vi.mock("../../cloud/src/utils/logger.js", () => ({
+  info: vi.fn(),
+  debug: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+}));
+
+vi.mock("../../cloud/src/utils/apiKey.js", () => ({
+  parseApiKey: vi.fn(),
+  extractBearerToken: vi.fn(),
+}));
+
+vi.mock("../../cloud/src/services/storage.js", () => ({
+  getMachineData: vi.fn(),
+  saveMachineData: vi.fn(),
+}));
+
+// ─── Imports (after mocks) ────────────────────────────────────────────────────
+
+import { handleEmbeddings } from "../../cloud/src/handlers/embeddings.js";
+import { getModelInfoCore } from "../../open-sse/services/model.js";
+import { handleEmbeddingsCore } from "../../open-sse/handlers/embeddingsCore.js";
+import { parseApiKey, extractBearerToken } from "../../cloud/src/utils/apiKey.js";
+import { getMachineData, saveMachineData } from "../../cloud/src/services/storage.js";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const MACHINE_ID = "mach01";
+const VALID_API_KEY = "sk-mach01-key01-ab12cd34"; // new format shape
+const VALID_EMBEDDING_RESPONSE_BODY = {
+  object: "list",
+  data: [{ object: "embedding", index: 0, embedding: [0.1, 0.2, 0.3] }],
+  model: "text-embedding-ada-002",
+  usage: { prompt_tokens: 3, total_tokens: 3 },
+};
+
+/** Build a minimal mock env (Cloudflare Worker env bindings) */
+function makeEnv() {
+  return { DB: {}, KV: {} };
+}
+
+/** Build a mock machine data record stored in D1 */
+function makeMachineData(overrides = {}) {
+  return {
+    machineId: MACHINE_ID,
+    apiKeys: [{ key: VALID_API_KEY, label: "test" }],
+    providers: {
+      "conn-001": {
+        provider: "openai",
+        apiKey: "sk-openai-provider-key",
+        isActive: true,
+        priority: 1,
+        status: "active",
+        rateLimitedUntil: null,
+        lastError: null,
+      },
+    },
+    modelAliases: {},
+    ...overrides,
+  };
+}
+
+/** Make a Request object */
+function makeRequest(method = "POST", body = null, authHeader = `Bearer ${VALID_API_KEY}`) {
+  const headers = { "Content-Type": "application/json" };
+  if (authHeader) headers["Authorization"] = authHeader;
+
+  return new Request("https://9cli.hxd.app/v1/embeddings", {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+}
+
+// ─── Tests: CORS OPTIONS ──────────────────────────────────────────────────────
+
+describe("handleEmbeddings — CORS OPTIONS", () => {
+  it("OPTIONS request → 200 with Access-Control-Allow-Origin: *", async () => {
+    const req = makeRequest("OPTIONS", null, null);
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("*");
+    expect(res.headers.get("Access-Control-Allow-Methods")).toMatch(/POST/);
+  });
+
+  it("OPTIONS request → body is empty/null", async () => {
+    const req = makeRequest("OPTIONS", null, null);
+    const res = await handleEmbeddings(req, makeEnv(), {});
+    const text = await res.text();
+    expect(text).toBe("");
+  });
+});
+
+// ─── Tests: Authentication ────────────────────────────────────────────────────
+
+describe("handleEmbeddings — authentication", () => {
+  beforeEach(() => {
+    vi.mocked(extractBearerToken).mockReturnValue(null);
+    vi.mocked(parseApiKey).mockResolvedValue(null);
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData());
+    vi.mocked(getModelInfoCore).mockResolvedValue({ provider: "openai", model: "text-embedding-ada-002" });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("missing Authorization header → 401", async () => {
+    vi.mocked(extractBearerToken).mockReturnValue(null);
+
+    const req = makeRequest("POST", { model: "ag/gemini-embedding-001", input: "hello" }, null);
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/missing api key/i);
+  });
+
+  it("Authorization header without Bearer scheme → 401", async () => {
+    vi.mocked(extractBearerToken).mockReturnValue(null);
+
+    const req = makeRequest("POST", { model: "ag/gemini-embedding-001", input: "hello" }, "Token abc123");
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(401);
+  });
+
+  it("Bearer key that fails parseApiKey → 401", async () => {
+    vi.mocked(extractBearerToken).mockReturnValue("sk-invalidkey");
+    vi.mocked(parseApiKey).mockResolvedValue(null);
+
+    const req = makeRequest("POST", { model: "ag/gemini-embedding-001", input: "hello" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/invalid api key format/i);
+  });
+
+  it("old-format key (no machineId) → 400 asking to use machineId endpoint", async () => {
+    vi.mocked(extractBearerToken).mockReturnValue("sk-oldfmt8");
+    vi.mocked(parseApiKey).mockResolvedValue({ machineId: null, keyId: "oldfmt8", isNewFormat: false });
+
+    const req = makeRequest("POST", { model: "ag/gemini-embedding-001", input: "hello" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/machineId/i);
+  });
+
+  it("valid key format but key value not in machine apiKeys → 401", async () => {
+    vi.mocked(extractBearerToken).mockReturnValue("sk-mach01-key01-ab12cd34");
+    vi.mocked(parseApiKey).mockResolvedValue({ machineId: MACHINE_ID, keyId: "key01", isNewFormat: true });
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData({
+      apiKeys: [{ key: "sk-different-key" }], // key doesn't match
+    }));
+
+    const req = makeRequest("POST", { model: "ag/gemini-embedding-001", input: "hello" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/invalid api key/i);
+  });
+
+  it("valid key → passes auth (proceeds to body parsing)", async () => {
+    vi.mocked(extractBearerToken).mockReturnValue(VALID_API_KEY);
+    vi.mocked(parseApiKey).mockResolvedValue({ machineId: MACHINE_ID, keyId: "key01", isNewFormat: true });
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData());
+    vi.mocked(getModelInfoCore).mockResolvedValue({ provider: "openai", model: "text-embedding-ada-002" });
+    vi.mocked(handleEmbeddingsCore).mockResolvedValue({
+      success: true,
+      response: new Response(JSON.stringify(VALID_EMBEDDING_RESPONSE_BODY), {
+        status: 200,
+        headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
+      }),
+    });
+
+    const req = makeRequest("POST", { model: "openai/text-embedding-ada-002", input: "hello" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    // Should not be 401
+    expect(res.status).not.toBe(401);
+    expect(res.status).not.toBe(403);
+  });
+});
+
+// ─── Tests: Body validation ───────────────────────────────────────────────────
+
+describe("handleEmbeddings — body validation", () => {
+  beforeEach(() => {
+    vi.mocked(extractBearerToken).mockReturnValue(VALID_API_KEY);
+    vi.mocked(parseApiKey).mockResolvedValue({ machineId: MACHINE_ID, keyId: "key01", isNewFormat: true });
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData());
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("invalid JSON body → 400", async () => {
+    const req = new Request("https://9cli.hxd.app/v1/embeddings", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${VALID_API_KEY}`,
+      },
+      body: "{ bad json",
+    });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/invalid json/i);
+  });
+
+  it("missing model field → 400", async () => {
+    const req = makeRequest("POST", { input: "hello world" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/missing model/i);
+  });
+
+  it("missing input field → 400", async () => {
+    const req = makeRequest("POST", { model: "ag/gemini-embedding-001" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/missing required field: input/i);
+  });
+
+  it("model with no provider mapping → 400", async () => {
+    vi.mocked(getModelInfoCore).mockResolvedValue({ provider: null, model: null });
+
+    const req = makeRequest("POST", { model: "nonexistent/model", input: "hello" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/invalid model format/i);
+  });
+});
+
+// ─── Tests: Happy path — valid request ────────────────────────────────────────
+
+describe("handleEmbeddings — valid request (happy path)", () => {
+  beforeEach(() => {
+    vi.mocked(extractBearerToken).mockReturnValue(VALID_API_KEY);
+    vi.mocked(parseApiKey).mockResolvedValue({ machineId: MACHINE_ID, keyId: "key01", isNewFormat: true });
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData());
+    vi.mocked(getModelInfoCore).mockResolvedValue({ provider: "openai", model: "text-embedding-ada-002" });
+    vi.mocked(handleEmbeddingsCore).mockResolvedValue({
+      success: true,
+      response: new Response(JSON.stringify(VALID_EMBEDDING_RESPONSE_BODY), {
+        status: 200,
+        headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
+      }),
+    });
+    vi.mocked(saveMachineData).mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("single string input → 200 with embeddings data", async () => {
+    const req = makeRequest("POST", {
+      model: "openai/text-embedding-ada-002",
+      input: "Hello world test embedding",
+    });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.object).toBe("list");
+    expect(Array.isArray(body.data)).toBe(true);
+  });
+
+  it("array input → 200 with embeddings data", async () => {
+    const req = makeRequest("POST", {
+      model: "openai/text-embedding-ada-002",
+      input: ["Hello", "World"],
+    });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.object).toBe("list");
+  });
+
+  it("delegates to handleEmbeddingsCore with correct args", async () => {
+    const req = makeRequest("POST", {
+      model: "openai/text-embedding-ada-002",
+      input: "Test",
+    });
+    await handleEmbeddings(req, makeEnv(), {});
+
+    expect(handleEmbeddingsCore).toHaveBeenCalledOnce();
+    const callArgs = vi.mocked(handleEmbeddingsCore).mock.calls[0][0];
+    expect(callArgs.body.input).toBe("Test");
+    expect(callArgs.modelInfo.provider).toBe("openai");
+    expect(callArgs.modelInfo.model).toBe("text-embedding-ada-002");
+    expect(callArgs.credentials).toBeDefined();
+  });
+
+  it("response has CORS header from addCorsHeaders wrapper", async () => {
+    const req = makeRequest("POST", {
+      model: "openai/text-embedding-ada-002",
+      input: "Hello",
+    });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("*");
+  });
+
+  it("machineId-override path: /{machineId}/v1/embeddings works", async () => {
+    // Direct call with machineId override (old format URL path)
+    const req = new Request(`https://9cli.hxd.app/${MACHINE_ID}/v1/embeddings`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${VALID_API_KEY}`,
+      },
+      body: JSON.stringify({ model: "openai/text-embedding-ada-002", input: "Hello" }),
+    });
+
+    const res = await handleEmbeddings(req, makeEnv(), {}, MACHINE_ID);
+    expect(res.status).toBe(200);
+  });
+});
+
+// ─── Tests: Rate limiting ──────────────────────────────────────────────────────
+
+describe("handleEmbeddings — rate limit fallback", () => {
+  beforeEach(() => {
+    vi.mocked(extractBearerToken).mockReturnValue(VALID_API_KEY);
+    vi.mocked(parseApiKey).mockResolvedValue({ machineId: MACHINE_ID, keyId: "key01", isNewFormat: true });
+    vi.mocked(getModelInfoCore).mockResolvedValue({ provider: "openai", model: "text-embedding-ada-002" });
+    vi.mocked(saveMachineData).mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("all provider accounts rate-limited → 503 with Retry-After header", async () => {
+    const rateLimitedUntil = new Date(Date.now() + 60000).toISOString(); // 60s from now
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData({
+      providers: {
+        "conn-001": {
+          provider: "openai",
+          apiKey: "sk-key",
+          isActive: true,
+          priority: 1,
+          status: "unavailable",
+          rateLimitedUntil,  // rate-limited
+          lastError: "Rate limit exceeded",
+          errorCode: 429,
+          backoffLevel: 1,
+        },
+      },
+    }));
+
+    const req = makeRequest("POST", { model: "openai/text-embedding-ada-002", input: "hello" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(429);
+    expect(res.headers.get("Retry-After")).toBeDefined();
+    const retryAfter = parseInt(res.headers.get("Retry-After"));
+    expect(retryAfter).toBeGreaterThan(0);
+  });
+
+  it("provider account not found → 400 No credentials", async () => {
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData({
+      providers: {}, // no providers
+    }));
+
+    const req = makeRequest("POST", { model: "openai/text-embedding-ada-002", input: "hello" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/no credentials/i);
+  });
+
+  it("core returns non-fallback error → propagates error response directly", async () => {
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData());
+    vi.mocked(handleEmbeddingsCore).mockResolvedValue({
+      success: false,
+      status: 400,
+      error: "input must be a string or array",
+      response: new Response(
+        JSON.stringify({ error: { message: "input must be a string or array" } }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      ),
+    });
+
+    const req = makeRequest("POST", { model: "openai/text-embedding-ada-002", input: "hello" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    // Non-fallback error (400) should not trigger account cycle; returns error directly
+    expect(res.status).toBe(400);
+  });
+
+  it("core returns 429 → marks account unavailable, then no more accounts → 503", async () => {
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData());
+    vi.mocked(handleEmbeddingsCore).mockResolvedValue({
+      success: false,
+      status: 429,
+      error: "Rate limit exceeded",
+      response: new Response(
+        JSON.stringify({ error: { message: "Rate limit exceeded" } }),
+        { status: 429, headers: { "Content-Type": "application/json" } }
+      ),
+    });
+
+    const req = makeRequest("POST", { model: "openai/text-embedding-ada-002", input: "hello" });
+    const res = await handleEmbeddings(req, makeEnv(), {});
+
+    // After fallback loop exhausts accounts
+    expect([429, 503]).toContain(res.status);
+  });
+});
+
+// ─── Tests: machineId-override (old-format URL path) ─────────────────────────
+
+describe("handleEmbeddings — machineId override path", () => {
+  beforeEach(() => {
+    // When machineId is provided via URL, no apiKey parsing needed for machineId
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData());
+    vi.mocked(getModelInfoCore).mockResolvedValue({ provider: "openai", model: "text-embedding-ada-002" });
+    vi.mocked(handleEmbeddingsCore).mockResolvedValue({
+      success: true,
+      response: new Response(JSON.stringify(VALID_EMBEDDING_RESPONSE_BODY), {
+        status: 200,
+        headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
+      }),
+    });
+    vi.mocked(saveMachineData).mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("with machineIdOverride, still validates API key via Authorization header", async () => {
+    // Key IS in the machine's apiKeys → should succeed
+    const req = new Request(`https://9cli.hxd.app/${MACHINE_ID}/v1/embeddings`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${VALID_API_KEY}`,
+      },
+      body: JSON.stringify({ model: "openai/text-embedding-ada-002", input: "test" }),
+    });
+
+    const res = await handleEmbeddings(req, makeEnv(), {}, MACHINE_ID);
+    expect(res.status).toBe(200);
+  });
+
+  it("with machineIdOverride, wrong API key → 401", async () => {
+    vi.mocked(getMachineData).mockResolvedValue(makeMachineData({
+      apiKeys: [{ key: "sk-correct-key" }],
+    }));
+
+    const req = new Request(`https://9cli.hxd.app/${MACHINE_ID}/v1/embeddings`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": "Bearer sk-wrong-key",
+      },
+      body: JSON.stringify({ model: "openai/text-embedding-ada-002", input: "test" }),
+    });
+
+    const res = await handleEmbeddings(req, makeEnv(), {}, MACHINE_ID);
+    expect(res.status).toBe(401);
+  });
+});
diff --git a/tests/unit/embeddingsCore.test.js b/tests/unit/embeddingsCore.test.js
new file mode 100644
index 0000000..62239ed
--- /dev/null
+++ b/tests/unit/embeddingsCore.test.js
@@ -0,0 +1,646 @@
+/**
+ * Unit tests for open-sse/handlers/embeddingsCore.js
+ *
+ * Tests cover:
+ *  - buildEmbeddingsBody()     — request body construction
+ *  - buildEmbeddingsUrl()      — URL per provider
+ *  - buildEmbeddingsHeaders()  — headers per provider
+ *  - handleEmbeddingsCore()    — full handler: success, errors, validation
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// ─── Mock the executors/index.js to avoid transitive uuid dependency ─────────
+// kiro.js (imported by executors/index.js) requires 'uuid' which isn't
+// installed in the test environment. We mock the whole executor layer.
+vi.mock("../../open-sse/executors/index.js", () => ({
+  getExecutor: vi.fn(() => ({
+    refreshCredentials: vi.fn().mockResolvedValue(null),
+  })),
+  hasSpecializedExecutor: vi.fn(() => false),
+}));
+
+// Also mock tokenRefresh to avoid side effects
+vi.mock("../../open-sse/services/tokenRefresh.js", () => ({
+  refreshWithRetry: vi.fn().mockResolvedValue(null),
+}));
+
+// Mock proxyFetch to avoid proxy-agent imports in test env
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  default: vi.fn(),
+}));
+
+import { handleEmbeddingsCore } from "../../open-sse/handlers/embeddingsCore.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Build a minimal success Response from a provider */
+function makeProviderResponse(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+/** Build a minimal error Response from a provider */
+function makeProviderErrorResponse(status, message) {
+  return new Response(JSON.stringify({ error: { message } }), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+/** Standard valid embeddings response in OpenAI format */
+const VALID_EMBEDDING_RESPONSE = {
+  object: "list",
+  data: [
+    {
+      object: "embedding",
+      index: 0,
+      embedding: [0.1, 0.2, 0.3],
+    },
+  ],
+  model: "text-embedding-ada-002",
+  usage: { prompt_tokens: 3, total_tokens: 3 },
+};
+
+/** Standard handleEmbeddingsCore options for OpenAI provider */
+function makeOptions(overrides = {}) {
+  return {
+    body: { model: "text-embedding-ada-002", input: "Hello world" },
+    modelInfo: { provider: "openai", model: "text-embedding-ada-002" },
+    credentials: { apiKey: "sk-test-key" },
+    log: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+    onCredentialsRefreshed: vi.fn(),
+    onRequestSuccess: vi.fn(),
+    ...overrides,
+  };
+}
+
+// ─── Test: buildEmbeddingsBody (via handleEmbeddingsCore internals) ──────────
+// We test body construction indirectly by verifying the fetch call payload.
+
+describe("buildEmbeddingsBody", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("single string input — includes model and input, default encoding_format=float", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      body: { model: "text-embedding-ada-002", input: "Hello world" },
+    }));
+
+    const [, init] = vi.mocked(fetch).mock.calls[0];
+    const sent = JSON.parse(init.body);
+    expect(sent.model).toBe("text-embedding-ada-002");
+    expect(sent.input).toBe("Hello world");
+    expect(sent.encoding_format).toBe("float");
+  });
+
+  it("array input — passes array as-is", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      body: { model: "text-embedding-ada-002", input: ["Hello", "World"] },
+    }));
+
+    const [, init] = vi.mocked(fetch).mock.calls[0];
+    const sent = JSON.parse(init.body);
+    expect(sent.input).toEqual(["Hello", "World"]);
+  });
+
+  it("custom encoding_format is forwarded", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      body: {
+        model: "text-embedding-ada-002",
+        input: "test",
+        encoding_format: "base64",
+      },
+    }));
+
+    const [, init] = vi.mocked(fetch).mock.calls[0];
+    const sent = JSON.parse(init.body);
+    expect(sent.encoding_format).toBe("base64");
+  });
+
+  it("no encoding_format in body → defaults to float", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      body: { model: "text-embedding-ada-002", input: "test" },
+    }));
+
+    const [, init] = vi.mocked(fetch).mock.calls[0];
+    const sent = JSON.parse(init.body);
+    expect(sent.encoding_format).toBe("float");
+  });
+
+  it("gemini single input forwards dimensions as outputDimensionality", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse({
+      embedding: { values: [0.1, 0.2, 0.3] },
+    }));
+
+    await handleEmbeddingsCore(makeOptions({
+      body: {
+        model: "gemini/gemini-embedding-2-preview",
+        input: "test",
+        dimensions: 1536,
+      },
+      modelInfo: { provider: "gemini", model: "gemini-embedding-2-preview" },
+      credentials: { apiKey: "gemini-key" },
+    }));
+
+    const [, init] = vi.mocked(fetch).mock.calls[0];
+    const sent = JSON.parse(init.body);
+    expect(sent.outputDimensionality).toBe(1536);
+  });
+
+  it("gemini batch input forwards dimensions on each request", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse({
+      embeddings: [
+        { values: [0.1, 0.2, 0.3] },
+        { values: [0.4, 0.5, 0.6] },
+      ],
+    }));
+
+    await handleEmbeddingsCore(makeOptions({
+      body: {
+        model: "gemini/gemini-embedding-2-preview",
+        input: ["hello", "world"],
+        dimensions: 1536,
+      },
+      modelInfo: { provider: "gemini", model: "gemini-embedding-2-preview" },
+      credentials: { apiKey: "gemini-key" },
+    }));
+
+    const [, init] = vi.mocked(fetch).mock.calls[0];
+    const sent = JSON.parse(init.body);
+    expect(sent.requests).toHaveLength(2);
+    expect(sent.requests[0].outputDimensionality).toBe(1536);
+    expect(sent.requests[1].outputDimensionality).toBe(1536);
+  });
+});
+
+// ─── Test: buildEmbeddingsUrl ────────────────────────────────────────────────
+
+describe("buildEmbeddingsUrl", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("openai → https://api.openai.com/v1/embeddings", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "openai", model: "text-embedding-ada-002" },
+      credentials: { apiKey: "sk-test" },
+    }));
+
+    const [url] = vi.mocked(fetch).mock.calls[0];
+    expect(url).toBe("https://api.openai.com/v1/embeddings");
+  });
+
+  it("openrouter → https://openrouter.ai/api/v1/embeddings", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "openrouter", model: "openai/text-embedding-ada-002" },
+      credentials: { apiKey: "sk-or-test" },
+    }));
+
+    const [url] = vi.mocked(fetch).mock.calls[0];
+    expect(url).toBe("https://openrouter.ai/api/v1/embeddings");
+  });
+
+  it("vercel-ai-gateway → https://ai-gateway.vercel.sh/v1/embeddings", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "vercel-ai-gateway", model: "openai/text-embedding-3-small" },
+      credentials: { apiKey: "vag-test-key" },
+    }));
+
+    const [url, init] = vi.mocked(fetch).mock.calls[0];
+    const sent = JSON.parse(init.body);
+    expect(url).toBe("https://ai-gateway.vercel.sh/v1/embeddings");
+    expect(init.headers.Authorization).toBe("Bearer vag-test-key");
+    expect(sent.model).toBe("openai/text-embedding-3-small");
+  });
+
+  it("openai-compatible-* → uses baseUrl from providerSpecificData", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "openai-compatible-custom", model: "embed-v1" },
+      credentials: {
+        apiKey: "sk-custom",
+        providerSpecificData: { baseUrl: "https://custom.ai/v1" },
+      },
+    }));
+
+    const [url] = vi.mocked(fetch).mock.calls[0];
+    expect(url).toBe("https://custom.ai/v1/embeddings");
+  });
+
+  it("openai-compatible-* strips trailing slash from baseUrl", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "openai-compatible-myhost", model: "embed-v1" },
+      credentials: {
+        apiKey: "sk-x",
+        providerSpecificData: { baseUrl: "https://myhost.ai/v1/" },
+      },
+    }));
+
+    const [url] = vi.mocked(fetch).mock.calls[0];
+    expect(url).toBe("https://myhost.ai/v1/embeddings");
+  });
+
+  it("openai-compatible-* without baseUrl → falls back to api.openai.com", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "openai-compatible-fallback", model: "embed" },
+      credentials: { apiKey: "sk-x", providerSpecificData: {} },
+    }));
+
+    const [url] = vi.mocked(fetch).mock.calls[0];
+    expect(url).toBe("https://api.openai.com/v1/embeddings");
+  });
+
+  it("unsupported provider (e.g. gemini-cli) → 400 error, no fetch called", async () => {
+    const result = await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "gemini-cli", model: "gemini-embedding" },
+      credentials: { apiKey: "token" },
+    }));
+
+    expect(vi.mocked(fetch)).not.toHaveBeenCalled();
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(400);
+    expect(result.error).toMatch(/does not support embeddings/i);
+  });
+
+  it("antigravity (non-openai-compatible, no URL mapping) → 400", async () => {
+    const result = await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "antigravity", model: "some-embed" },
+      credentials: { apiKey: "ag-token" },
+    }));
+
+    expect(vi.mocked(fetch)).not.toHaveBeenCalled();
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(400);
+  });
+});
+
+// ─── Test: buildEmbeddingsHeaders ───────────────────────────────────────────
+
+describe("buildEmbeddingsHeaders", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("openai → Authorization: Bearer, Content-Type: application/json", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "openai", model: "text-embedding-ada-002" },
+      credentials: { apiKey: "sk-mykey" },
+    }));
+
+    const [, init] = vi.mocked(fetch).mock.calls[0];
+    expect(init.headers["Authorization"]).toBe("Bearer sk-mykey");
+    expect(init.headers["Content-Type"]).toBe("application/json");
+  });
+
+  it("openai — uses accessToken when apiKey is absent", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "openai", model: "text-embedding-ada-002" },
+      credentials: { accessToken: "at-mytoken" },
+    }));
+
+    const [, init] = vi.mocked(fetch).mock.calls[0];
+    expect(init.headers["Authorization"]).toBe("Bearer at-mytoken");
+  });
+
+  it("openrouter → adds HTTP-Referer and X-Title headers", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "openrouter", model: "openai/text-embedding-ada-002" },
+      credentials: { apiKey: "sk-or-key" },
+    }));
+
+    const [, init] = vi.mocked(fetch).mock.calls[0];
+    expect(init.headers["HTTP-Referer"]).toBeDefined();
+    expect(init.headers["X-Title"]).toBeDefined();
+    expect(init.headers["Authorization"]).toBe("Bearer sk-or-key");
+  });
+
+  it("openai-compatible-* → Authorization: Bearer only (no extra headers)", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "openai-compatible-local", model: "nomic-embed" },
+      credentials: {
+        apiKey: "local-key",
+        providerSpecificData: { baseUrl: "http://localhost:11434/v1" },
+      },
+    }));
+
+    const [, init] = vi.mocked(fetch).mock.calls[0];
+    expect(init.headers["Authorization"]).toBe("Bearer local-key");
+    expect(init.headers["HTTP-Referer"]).toBeUndefined();
+    expect(init.headers["X-Title"]).toBeUndefined();
+  });
+});
+
+// ─── Test: handleEmbeddingsCore — input validation ───────────────────────────
+
+describe("handleEmbeddingsCore — input validation", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("missing input → 400 Bad Request", async () => {
+    const result = await handleEmbeddingsCore(makeOptions({
+      body: { model: "text-embedding-ada-002" }, // no input
+    }));
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(400);
+    expect(result.error).toMatch(/missing required field: input/i);
+  });
+
+  it("input is a number → 400 Bad Request", async () => {
+    const result = await handleEmbeddingsCore(makeOptions({
+      body: { model: "text-embedding-ada-002", input: 42 },
+    }));
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(400);
+    expect(result.error).toMatch(/input must be a string or array/i);
+  });
+
+  it("input is an object → 400 Bad Request", async () => {
+    const result = await handleEmbeddingsCore(makeOptions({
+      body: { model: "text-embedding-ada-002", input: { text: "hello" } },
+    }));
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(400);
+    expect(result.error).toMatch(/input must be a string or array/i);
+  });
+
+  it("input is null → 400 Bad Request", async () => {
+    const result = await handleEmbeddingsCore(makeOptions({
+      body: { model: "text-embedding-ada-002", input: null },
+    }));
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(400);
+  });
+
+  it("empty string input passes validation", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValueOnce(
+      makeProviderResponse(VALID_EMBEDDING_RESPONSE)
+    ));
+    const result = await handleEmbeddingsCore(makeOptions({
+      body: { model: "text-embedding-ada-002", input: "" },
+    }));
+    // Empty string is falsy → treated as missing
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(400);
+  });
+
+  it("empty array input passes validation and reaches provider", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValueOnce(
+      makeProviderResponse(VALID_EMBEDDING_RESPONSE)
+    ));
+    const result = await handleEmbeddingsCore(makeOptions({
+      body: { model: "text-embedding-ada-002", input: [] },
+    }));
+    // Empty array is truthy → passes, fetch is called
+    expect(fetch).toHaveBeenCalledOnce();
+    expect(result.success).toBe(true);
+  });
+});
+
+// ─── Test: handleEmbeddingsCore — success path ───────────────────────────────
+
+describe("handleEmbeddingsCore — success path", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("returns success=true with Response on 200", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    const result = await handleEmbeddingsCore(makeOptions());
+
+    expect(result.success).toBe(true);
+    expect(result.response).toBeInstanceOf(Response);
+    expect(result.response.status).toBe(200);
+  });
+
+  it("response body is valid OpenAI-format JSON", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    const result = await handleEmbeddingsCore(makeOptions());
+    const body = await result.response.json();
+
+    expect(body.object).toBe("list");
+    expect(Array.isArray(body.data)).toBe(true);
+    expect(body.data[0]).toHaveProperty("embedding");
+    expect(body.data[0]).toHaveProperty("index");
+  });
+
+  it("response includes CORS header Access-Control-Allow-Origin: *", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    const result = await handleEmbeddingsCore(makeOptions());
+
+    expect(result.response.headers.get("Access-Control-Allow-Origin")).toBe("*");
+  });
+
+  it("response Content-Type is application/json", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    const result = await handleEmbeddingsCore(makeOptions());
+
+    expect(result.response.headers.get("Content-Type")).toContain("application/json");
+  });
+
+  it("calls onRequestSuccess callback on success", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+    const onRequestSuccess = vi.fn();
+
+    await handleEmbeddingsCore(makeOptions({ onRequestSuccess }));
+
+    expect(onRequestSuccess).toHaveBeenCalledOnce();
+  });
+
+  it("does not call onRequestSuccess on provider error", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderErrorResponse(500, "Server exploded"));
+    const onRequestSuccess = vi.fn();
+
+    await handleEmbeddingsCore(makeOptions({ onRequestSuccess }));
+
+    expect(onRequestSuccess).not.toHaveBeenCalled();
+  });
+
+  it("provider response with non-standard format is passed through as-is", async () => {
+    const nonStandardBody = { embeddings: [[0.1, 0.2]], model: "custom" };
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(nonStandardBody));
+
+    const result = await handleEmbeddingsCore(makeOptions());
+    const body = await result.response.json();
+
+    expect(body).toEqual(nonStandardBody);
+  });
+});
+
+// ─── Test: handleEmbeddingsCore — provider error handling ────────────────────
+
+describe("handleEmbeddingsCore — provider error handling", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("provider 400 → returns success=false with status 400", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderErrorResponse(400, "Bad model"));
+
+    const result = await handleEmbeddingsCore(makeOptions());
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(400);
+  });
+
+  it("provider 429 → returns success=false with status 429", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderErrorResponse(429, "Rate limit exceeded"));
+
+    const result = await handleEmbeddingsCore(makeOptions());
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(429);
+  });
+
+  it("provider 500 → returns success=false with status 500", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderErrorResponse(500, "Internal error"));
+
+    const result = await handleEmbeddingsCore(makeOptions());
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(500);
+  });
+
+  it("network error (fetch throws) → returns 502 Bad Gateway", async () => {
+    vi.mocked(fetch).mockRejectedValueOnce(new Error("ECONNREFUSED"));
+
+    const result = await handleEmbeddingsCore(makeOptions());
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(502);
+    expect(result.error).toMatch(/ECONNREFUSED/);
+  });
+
+  it("invalid JSON from provider → returns 502", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response("not json }{", {
+        status: 200,
+        headers: { "Content-Type": "text/plain" },
+      })
+    );
+
+    const result = await handleEmbeddingsCore(makeOptions());
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(502);
+  });
+
+  it("error result response has OpenAI-format error body", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderErrorResponse(400, "Bad model"));
+
+    const result = await handleEmbeddingsCore(makeOptions());
+    const body = await result.response.json();
+
+    expect(body).toHaveProperty("error");
+    expect(body.error).toHaveProperty("message");
+  });
+});
+
+// ─── Test: handleEmbeddingsCore — token refresh on 401 ───────────────────────
+
+describe("handleEmbeddingsCore — token refresh on 401/403", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("on 401, attempts retry after refresh; succeeds if refresh gives new token", async () => {
+    // First call → 401 from provider
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify({ error: "unauthorized" }), {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      })
+    );
+    // Second call (retry) → success
+    vi.mocked(fetch).mockResolvedValueOnce(makeProviderResponse(VALID_EMBEDDING_RESPONSE));
+
+    // Credentials with a refreshToken so the executor can try to refresh
+    const credentials = {
+      apiKey: "sk-old",
+      accessToken: "at-old",
+      refreshToken: "rt-valid",
+    };
+
+    // Mock executor's refreshCredentials to return new creds
+    const result = await handleEmbeddingsCore(makeOptions({
+      modelInfo: { provider: "openai", model: "text-embedding-ada-002" },
+      credentials,
+      onCredentialsRefreshed: vi.fn(),
+    }));
+
+    // The handler may or may not succeed depending on whether the executor
+    // can refresh (openai executor likely can't). What we verify is that
+    // fetch was called at least once (the initial request).
+    expect(vi.mocked(fetch).mock.calls.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("on 401 with no refresh token, falls back gracefully (no crash)", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify({ error: "unauthorized" }), {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      })
+    );
+
+    const result = await handleEmbeddingsCore(makeOptions({
+      credentials: { apiKey: "sk-bad" },
+    }));
+
+    // Should return an error result, not throw
+    expect(result).toHaveProperty("success");
+    expect(result.success).toBe(false);
+  });
+});
diff --git a/tests/unit/executor-const-guard.test.js b/tests/unit/executor-const-guard.test.js
new file mode 100644
index 0000000..2c466ce
--- /dev/null
+++ b/tests/unit/executor-const-guard.test.js
@@ -0,0 +1,48 @@
+// A5 (cases #7/#9/#10): lock hardcode->config no-op values.
+import { describe, it, expect } from "vitest";
+import {
+  OPENAI_COMPAT_BASE,
+  ANTHROPIC_COMPAT_BASE,
+  ANTHROPIC_API_VERSION,
+} from "../../open-sse/providers/shared.js";
+import { DEFAULT_MAX_TOKENS, DEFAULT_MIN_TOKENS } from "../../open-sse/config/runtimeConfig.js";
+import mimoFree from "../../open-sse/providers/registry/mimo-free.js";
+import opencode from "../../open-sse/providers/registry/opencode.js";
+import antigravity from "../../open-sse/providers/registry/antigravity.js";
+
+describe("compat base URLs / version", () => {
+  it("OPENAI_COMPAT_BASE", () => {
+    expect(OPENAI_COMPAT_BASE).toBe("https://api.openai.com/v1");
+  });
+  it("ANTHROPIC_COMPAT_BASE", () => {
+    expect(ANTHROPIC_COMPAT_BASE).toBe("https://api.anthropic.com/v1");
+  });
+  it("ANTHROPIC_API_VERSION", () => {
+    expect(ANTHROPIC_API_VERSION).toBe("2023-06-01");
+  });
+});
+
+describe("default token limits", () => {
+  it("max/min", () => {
+    expect(DEFAULT_MAX_TOKENS).toBe(64000);
+    expect(DEFAULT_MIN_TOKENS).toBe(32000);
+  });
+});
+
+describe("provider baseUrl const (full path, no trailing slash)", () => {
+  it("mimo-free full path", () => {
+    expect(mimoFree.transport.baseUrl).toBe("https://api.xiaomimimo.com/api/free-ai/openai/chat");
+  });
+  it("opencode no trailing slash", () => {
+    expect(opencode.transport.baseUrl).toBe("https://opencode.ai");
+  });
+});
+
+describe("antigravity retry (intentional change: 429=6, 503=3)", () => {
+  it("429 attempts = 6", () => {
+    expect(antigravity.transport.retry["429"].attempts).toBe(6);
+  });
+  it("503 attempts = 3", () => {
+    expect(antigravity.transport.retry["503"].attempts).toBe(3);
+  });
+});
diff --git a/tests/unit/file-block-routing.test.js b/tests/unit/file-block-routing.test.js
new file mode 100644
index 0000000..71b8f9c
--- /dev/null
+++ b/tests/unit/file-block-routing.test.js
@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { convertOpenAIContentToParts } from "../../open-sse/translator/formats/gemini.js";
+import { openaiToClaudeRequest } from "../../open-sse/translator/request/openai-to-claude.js";
+import { VALID_OPENAI_CONTENT_TYPES, OPENAI_BLOCK, CLAUDE_BLOCK } from "../../open-sse/translator/schema/index.js";
+
+const PDF_DATA = "data:application/pdf;base64,JVBERi0xLjE=";
+const PNG_DATA = "data:image/png;base64,iVBORw0KGgo=";
+
+describe("file/document block support", () => {
+  it("schema: file is a valid openai content type", () => {
+    expect(VALID_OPENAI_CONTENT_TYPES).toContain(OPENAI_BLOCK.FILE);
+    expect(OPENAI_BLOCK.FILE).toBe("file");
+    expect(CLAUDE_BLOCK.DOCUMENT).toBe("document");
+  });
+
+  it("gemini: openai file block -> inlineData", () => {
+    const parts = convertOpenAIContentToParts([
+      { type: "text", text: "read this" },
+      { type: "file", file: { filename: "d.pdf", file_data: PDF_DATA } },
+    ]);
+    const inline = parts.find((p) => p.inlineData);
+    expect(inline).toBeTruthy();
+    expect(inline.inlineData.mime_type).toBe("application/pdf");
+    expect(inline.inlineData.data).toBe("JVBERi0xLjE=");
+  });
+
+  it("gemini: ignores non-data-uri file", () => {
+    const parts = convertOpenAIContentToParts([
+      { type: "file", file: { filename: "d.pdf", file_data: "https://x/d.pdf" } },
+    ]);
+    expect(parts.some((p) => p.inlineData)).toBe(false);
+  });
+
+  it("claude: openai file (pdf) -> document block", () => {
+    const out = openaiToClaudeRequest("claude-x", {
+      messages: [{ role: "user", content: [
+        { type: "text", text: "read" },
+        { type: "file", file: { filename: "d.pdf", file_data: PDF_DATA } },
+      ] }],
+    }, false);
+    const blocks = out.messages[0].content;
+    const doc = blocks.find((b) => b.type === "document");
+    expect(doc).toBeTruthy();
+    expect(doc.source.media_type).toBe("application/pdf");
+  });
+
+  it("claude: non-pdf file is dropped (not a document)", () => {
+    const out = openaiToClaudeRequest("claude-x", {
+      messages: [{ role: "user", content: [
+        { type: "text", text: "read" },
+        { type: "file", file: { filename: "i.png", file_data: PNG_DATA } },
+      ] }],
+    }, false);
+    const blocks = out.messages[0].content;
+    expect(blocks.some((b) => b.type === "document")).toBe(false);
+  });
+});
diff --git a/tests/unit/finish-reason-concern.test.js b/tests/unit/finish-reason-concern.test.js
new file mode 100644
index 0000000..d4fc471
--- /dev/null
+++ b/tests/unit/finish-reason-concern.test.js
@@ -0,0 +1,83 @@
+// A1: locks toOpenAIFinish/fromOpenAIFinish behavior changes vs open-sse.old.
+import { describe, it, expect } from "vitest";
+import { toOpenAIFinish, fromOpenAIFinish } from "../../open-sse/translator/concerns/finishReason.js";
+import { OPENAI_FINISH, CLAUDE_STOP, GEMINI_FINISH } from "../../open-sse/translator/schema/finishReasons.js";
+
+describe("toOpenAIFinish - gemini", () => {
+  it.each([
+    ["SAFETY", "content_filter"],
+    ["RECITATION", "content_filter"],
+    ["BLOCKLIST", "content_filter"],
+    ["PROHIBITED_CONTENT", "content_filter"],
+    ["OTHER", "stop"],
+    ["UNKNOWN_XYZ", "stop"],
+    ["STOP", "stop"],
+    ["MAX_TOKENS", "length"],
+  ])("%s -> %s", (input, expected) => {
+    expect(toOpenAIFinish(input, "gemini")).toBe(expected);
+  });
+});
+
+describe("toOpenAIFinish - ollama", () => {
+  it.each([
+    ["length", "length"],
+    ["max_tokens", "length"],
+    ["tool_calls", "tool_calls"],
+    ["unknown_xyz", "stop"],
+  ])("%s -> %s", (input, expected) => {
+    expect(toOpenAIFinish(input, "ollama")).toBe(expected);
+  });
+});
+
+describe("toOpenAIFinish - kiro", () => {
+  it("tool_use -> tool_calls", () => {
+    expect(toOpenAIFinish("tool_use", "kiro")).toBe("tool_calls");
+  });
+});
+
+describe("toOpenAIFinish - claude", () => {
+  it.each([
+    ["end_turn", "stop"],
+    ["max_tokens", "length"],
+    ["tool_use", "tool_calls"],
+  ])("%s -> %s", (input, expected) => {
+    expect(toOpenAIFinish(input, "claude")).toBe(expected);
+  });
+});
+
+describe("toOpenAIFinish - commandcode", () => {
+  it("tool-calls -> tool_calls", () => {
+    expect(toOpenAIFinish("tool-calls", "commandcode")).toBe("tool_calls");
+  });
+  it("unknown passthrough", () => {
+    expect(toOpenAIFinish("xyz", "commandcode")).toBe("xyz");
+  });
+});
+
+describe("fromOpenAIFinish round-trip - claude", () => {
+  it("tool_calls -> tool_use", () => {
+    expect(fromOpenAIFinish("tool_calls", "claude")).toBe("tool_use");
+  });
+  it("length -> max_tokens", () => {
+    expect(fromOpenAIFinish("length", "claude")).toBe("max_tokens");
+  });
+});
+
+describe("enum literals (catch drift)", () => {
+  it("OPENAI_FINISH literals", () => {
+    expect(OPENAI_FINISH.STOP).toBe("stop");
+    expect(OPENAI_FINISH.LENGTH).toBe("length");
+    expect(OPENAI_FINISH.TOOL_CALLS).toBe("tool_calls");
+    expect(OPENAI_FINISH.CONTENT_FILTER).toBe("content_filter");
+  });
+  it("CLAUDE_STOP literals", () => {
+    expect(CLAUDE_STOP.END_TURN).toBe("end_turn");
+    expect(CLAUDE_STOP.MAX_TOKENS).toBe("max_tokens");
+    expect(CLAUDE_STOP.TOOL_USE).toBe("tool_use");
+  });
+  it("GEMINI_FINISH literals", () => {
+    expect(GEMINI_FINISH.STOP).toBe("STOP");
+    expect(GEMINI_FINISH.MAX_TOKENS).toBe("MAX_TOKENS");
+    expect(GEMINI_FINISH.SAFETY).toBe("SAFETY");
+  });
+});
diff --git a/tests/unit/force-stream-config.test.js b/tests/unit/force-stream-config.test.js
new file mode 100644
index 0000000..ea3a1c3
--- /dev/null
+++ b/tests/unit/force-stream-config.test.js
@@ -0,0 +1,153 @@
+// Guards forceStream moved from chatCore hardcode → PROVIDERS schema (#5).
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { executeMock } = vi.hoisted(() => ({
+  executeMock: vi.fn(),
+}));
+
+vi.mock("../../open-sse/executors/index.js", () => ({
+  getExecutor: vi.fn(() => ({
+    execute: executeMock,
+    refreshCredentials: vi.fn().mockResolvedValue(null),
+  })),
+}));
+
+vi.mock("../../open-sse/utils/requestLogger.js", () => ({
+  createRequestLogger: vi.fn(async () => ({
+    logClientRawRequest: vi.fn(),
+    logRawRequest: vi.fn(),
+    logTargetRequest: vi.fn(),
+    logError: vi.fn(),
+  })),
+}));
+
+vi.mock("../../open-sse/utils/clientDetector.js", () => ({
+  detectClientTool: vi.fn(() => null),
+  isNativePassthrough: vi.fn(() => false),
+}));
+
+vi.mock("../../open-sse/utils/bypassHandler.js", () => ({
+  handleBypassRequest: vi.fn(() => null),
+}));
+
+vi.mock("../../open-sse/utils/streamHandler.js", () => ({
+  createStreamController: vi.fn(() => ({
+    signal: undefined,
+    handleComplete: vi.fn(),
+    handleError: vi.fn(),
+  })),
+}));
+
+vi.mock("../../open-sse/services/tokenRefresh.js", () => ({
+  refreshWithRetry: vi.fn(),
+}));
+
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  default: vi.fn(),
+  proxyAwareFetch: vi.fn(),
+}));
+
+vi.mock("../../open-sse/translator/formats/claude.js", () => ({
+  normalizeClaudePassthrough: vi.fn(),
+}));
+
+vi.mock("../../open-sse/utils/toolDeduper.js", () => ({
+  dedupeTools: vi.fn((tools) => ({ tools, stripped: [] })),
+}));
+
+vi.mock("../../open-sse/rtk/caveman.js", () => ({
+  injectCaveman: vi.fn(),
+}));
+
+vi.mock("../../open-sse/rtk/ponytail.js", () => ({
+  injectPonytail: vi.fn(),
+}));
+
+vi.mock("../../open-sse/rtk/index.js", () => ({
+  compressMessages: vi.fn(() => null),
+  formatRtkLog: vi.fn(() => ""),
+}));
+
+vi.mock("../../open-sse/rtk/headroom.js", () => ({
+  compressWithHeadroom: vi.fn(async () => null),
+  formatHeadroomLog: vi.fn(() => ""),
+}));
+
+vi.mock("../../open-sse/providers/capabilities.js", () => ({
+  getCapabilitiesForModel: vi.fn(() => ({})),
+}));
+
+vi.mock("../../open-sse/translator/concerns/modality.js", () => ({
+  stripUnsupportedModalities: vi.fn(() => false),
+}));
+
+vi.mock("../../open-sse/translator/concerns/prefetch.js", () => ({
+  prefetchRemoteImages: vi.fn(async () => 0),
+}));
+
+vi.mock("../../open-sse/handlers/chatCore/requestDetail.js", () => ({
+  buildRequestDetail: vi.fn((detail) => detail),
+  extractRequestConfig: vi.fn((body, stream) => ({ body, stream })),
+}));
+
+vi.mock("../../open-sse/utils/error.js", () => ({
+  createErrorResult: vi.fn((status, message) => ({ success: false, status, error: message })),
+  formatProviderError: vi.fn((error) => error.message),
+  parseUpstreamError: vi.fn(),
+}));
+
+vi.mock("@/lib/usageDb.js", () => ({
+  trackPendingRequest: vi.fn(),
+  appendRequestLog: vi.fn(() => Promise.resolve()),
+  saveRequestDetail: vi.fn(() => Promise.resolve()),
+}));
+
+const FORCED = ["openai", "codex", "commandcode"];
+
+function makeOptions(bodyStream) {
+  const body = {
+    model: "gpt-4.1",
+    messages: [{ role: "user", content: "hello" }],
+  };
+  if (bodyStream !== undefined) body.stream = bodyStream;
+
+  return {
+    body,
+    modelInfo: { provider: "openai", model: "gpt-4.1" },
+    credentials: { apiKey: "sk-test" },
+    clientRawRequest: {
+      endpoint: "/v1/chat/completions",
+      body,
+      headers: { accept: "application/json" },
+    },
+    connectionId: "test-connection",
+    log: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+  };
+}
+
+describe("forceStream provider config", () => {
+  beforeEach(() => {
+    executeMock.mockReset();
+    executeMock.mockRejectedValue(new Error("boom"));
+  });
+
+  it("only openai/codex/commandcode force streaming", async () => {
+    const { PROVIDERS } = await import("../../open-sse/config/providers.js");
+    for (const id of FORCED) {
+      expect(PROVIDERS[id]?.forceStream, `${id} forced`).toBe(true);
+    }
+    // a sample of others must NOT force
+    for (const id of ["deepseek", "claude", "gemini", "openrouter"]) {
+      expect(PROVIDERS[id]?.forceStream, `${id} not forced`).not.toBe(true);
+    }
+  });
+
+  it.each([undefined, false])( "keeps forced-stream providers streaming for JSON clients when body.stream is %s", async (bodyStream) => {
+    const { handleChatCore } = await import("../../open-sse/handlers/chatCore.js");
+
+    await handleChatCore(makeOptions(bodyStream));
+
+    expect(executeMock).toHaveBeenCalledTimes(1);
+    expect(executeMock.mock.calls[0][0].stream).toBe(true);
+  });
+});
diff --git a/tests/unit/gemini-native-endpoint.test.js b/tests/unit/gemini-native-endpoint.test.js
new file mode 100644
index 0000000..83a8716
--- /dev/null
+++ b/tests/unit/gemini-native-endpoint.test.js
@@ -0,0 +1,260 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  handleChat: vi.fn(),
+  getSettings: vi.fn(),
+  isValidApiKey: vi.fn(),
+  getProviderCredentials: vi.fn(),
+  markAccountUnavailable: vi.fn(),
+  clearAccountError: vi.fn(),
+}));
+
+vi.mock("@/sse/handlers/chat.js", () => ({
+  handleChat: mocks.handleChat,
+}));
+
+vi.mock("@/sse/services/auth.js", () => ({
+  getProviderCredentials: mocks.getProviderCredentials,
+  isValidApiKey: mocks.isValidApiKey,
+  markAccountUnavailable: mocks.markAccountUnavailable,
+  clearAccountError: mocks.clearAccountError,
+}));
+
+vi.mock("@/lib/localDb", () => ({
+  getSettings: mocks.getSettings,
+}));
+
+const { GET } = await import("../../src/app/api/v1beta/models/route.js");
+const { POST } = await import("../../src/app/api/v1beta/models/[...path]/route.js");
+
+function makeGeminiRequest(path, body, headers = {}, signal) {
+  return new Request(`https://router.test/v1beta/models/${path}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: "Bearer router-client-key",
+      ...headers,
+    },
+    body: JSON.stringify(body),
+    signal,
+  });
+}
+
+function audioBody() {
+  return {
+    contents: [{ parts: [{ text: "Speak naturally: hello" }] }],
+    generationConfig: {
+      responseModalities: ["AUDIO"],
+      speechConfig: {
+        voiceConfig: {
+          prebuiltVoiceConfig: { voiceName: "Kore" },
+        },
+      },
+      temperature: 0.01,
+      seed: 123,
+    },
+  };
+}
+
+describe("Gemini native v1beta endpoint", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getSettings.mockResolvedValue({ requireApiKey: true });
+    mocks.isValidApiKey.mockResolvedValue(true);
+    mocks.getProviderCredentials.mockResolvedValue({
+      apiKey: "real-gemini-key",
+      connectionId: "gemini-conn",
+      connectionName: "Gemini Test",
+      providerSpecificData: {},
+    });
+    mocks.markAccountUnavailable.mockResolvedValue({ shouldFallback: false });
+    global.fetch = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ candidates: [{ content: { parts: [{ text: "ok" }] } }] }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      })
+    );
+    mocks.handleChat.mockResolvedValue(
+      Response.json({ candidates: [{ content: { parts: [{ text: "chat" }] } }] })
+    );
+  });
+
+  it("lists Gemini TTS models using standard Google model names", async () => {
+    const response = await GET();
+    const body = await response.json();
+    const names = body.models.map((model) => model.name);
+
+    expect(names).toContain("models/gemini-3.1-flash-tts-preview");
+    expect(names).toContain("models/gemini-2.5-flash-preview-tts");
+    expect(names).toContain("models/gemini-2.5-pro-preview-tts");
+  });
+
+  it("passes Gemini AUDIO generateContent requests through to Google's native endpoint", async () => {
+    const body = audioBody();
+    const response = await POST(makeGeminiRequest("gemini-3.1-flash-tts-preview:generateContent", body), {
+      params: Promise.resolve({ path: ["gemini-3.1-flash-tts-preview:generateContent"] }),
+    });
+
+    expect(response.status).toBe(200);
+    expect(mocks.handleChat).not.toHaveBeenCalled();
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+    expect(global.fetch.mock.calls[0][0]).toBe(
+      "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-tts-preview:generateContent"
+    );
+
+    const options = global.fetch.mock.calls[0][1];
+    expect(options.method).toBe("POST");
+    expect(JSON.parse(options.body)).toEqual(body);
+    expect(options.headers["x-goog-api-key"]).toBe("real-gemini-key");
+    expect(options.headers.Authorization).toBeUndefined();
+  });
+
+  it("accepts Google-style client keys without forwarding them upstream", async () => {
+    const request = makeGeminiRequest(
+      "gemini-2.5-flash-preview-tts:generateContent?key=query-router-key",
+      audioBody(),
+      {
+        Authorization: "",
+        "x-goog-api-key": "client-router-key",
+      }
+    );
+    await POST(request, {
+      params: Promise.resolve({ path: ["gemini-2.5-flash-preview-tts:generateContent"] }),
+    });
+
+    expect(mocks.isValidApiKey).toHaveBeenCalledWith("client-router-key");
+    expect(global.fetch.mock.calls[0][1].headers["x-goog-api-key"]).toBe("real-gemini-key");
+    expect(global.fetch.mock.calls[0][1].headers["x-goog-api-key"]).not.toBe("client-router-key");
+  });
+
+  it("does not forward stale compression headers from native upstream responses", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Encoding": "gzip",
+          "Content-Length": "123",
+        },
+      })
+    );
+
+    const response = await POST(makeGeminiRequest("gemini-3.1-flash-tts-preview:generateContent", audioBody()), {
+      params: Promise.resolve({ path: ["gemini-3.1-flash-tts-preview:generateContent"] }),
+    });
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-encoding")).toBeNull();
+    expect(response.headers.get("content-length")).toBeNull();
+  });
+
+  it("falls back to the next Gemini credential when native fetch times out before headers", async () => {
+    const timeoutError = new TypeError("fetch failed");
+    timeoutError.cause = { code: "UND_ERR_HEADERS_TIMEOUT", name: "HeadersTimeoutError" };
+
+    mocks.getProviderCredentials
+      .mockResolvedValueOnce({
+        apiKey: "first-gemini-key",
+        connectionId: "first-conn",
+        connectionName: "First Gemini",
+        providerSpecificData: {},
+      })
+      .mockResolvedValueOnce({
+        apiKey: "second-gemini-key",
+        connectionId: "second-conn",
+        connectionName: "Second Gemini",
+        providerSpecificData: {},
+      });
+    mocks.markAccountUnavailable.mockResolvedValueOnce({ shouldFallback: true });
+    global.fetch
+      .mockRejectedValueOnce(timeoutError)
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ candidates: [{ content: { parts: [{ inlineData: { data: "pcm" } }] } }] }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        })
+      );
+
+    const response = await POST(makeGeminiRequest("gemini-3.1-flash-tts-preview:generateContent", audioBody()), {
+      params: Promise.resolve({ path: ["gemini-3.1-flash-tts-preview:generateContent"] }),
+    });
+
+    expect(response.status).toBe(200);
+    expect(global.fetch).toHaveBeenCalledTimes(2);
+    expect(global.fetch.mock.calls[0][1].headers["x-goog-api-key"]).toBe("first-gemini-key");
+    expect(global.fetch.mock.calls[1][1].headers["x-goog-api-key"]).toBe("second-gemini-key");
+    expect(mocks.markAccountUnavailable).toHaveBeenCalledWith(
+      "first-conn",
+      504,
+      expect.stringContaining("UND_ERR_HEADERS_TIMEOUT"),
+      "gemini",
+      "gemini-3.1-flash-tts-preview"
+    );
+    expect(mocks.clearAccountError).toHaveBeenCalledWith(
+      "second-conn",
+      expect.objectContaining({ apiKey: "second-gemini-key" }),
+      "gemini-3.1-flash-tts-preview"
+    );
+  });
+
+  it("returns 502 for native fetch failures when credential fallback is not allowed", async () => {
+    const networkError = new TypeError("fetch failed");
+    networkError.cause = { code: "ECONNRESET" };
+    mocks.markAccountUnavailable.mockResolvedValueOnce({ shouldFallback: false });
+    global.fetch.mockRejectedValueOnce(networkError);
+
+    const response = await POST(makeGeminiRequest("gemini-3.1-flash-tts-preview:generateContent", audioBody()), {
+      params: Promise.resolve({ path: ["gemini-3.1-flash-tts-preview:generateContent"] }),
+    });
+    const body = await response.json();
+
+    expect(response.status).toBe(502);
+    expect(body.error.message).toContain("ECONNRESET");
+    expect(mocks.markAccountUnavailable).toHaveBeenCalledWith(
+      "gemini-conn",
+      502,
+      expect.stringContaining("ECONNRESET"),
+      "gemini",
+      "gemini-3.1-flash-tts-preview"
+    );
+  });
+
+  it("does not mark Gemini credentials unavailable when the native client aborts", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    global.fetch.mockRejectedValueOnce(new DOMException("The operation was aborted", "AbortError"));
+
+    const response = await POST(
+      makeGeminiRequest("gemini-3.1-flash-tts-preview:generateContent", audioBody(), {}, controller.signal),
+      {
+        params: Promise.resolve({ path: ["gemini-3.1-flash-tts-preview:generateContent"] }),
+      }
+    );
+
+    expect(response.status).toBe(499);
+    expect(mocks.markAccountUnavailable).not.toHaveBeenCalled();
+  });
+
+  it("keeps non-audio Gemini requests on the existing chat conversion path", async () => {
+    const body = {
+      contents: [{ parts: [{ text: "hello" }] }],
+      generationConfig: { temperature: 0.3 },
+    };
+
+    await POST(makeGeminiRequest("gemini-2.5-flash:generateContent", body), {
+      params: Promise.resolve({ path: ["gemini-2.5-flash:generateContent"] }),
+    });
+
+    expect(mocks.handleChat).toHaveBeenCalledTimes(1);
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it("does not hijack provider-prefixed non-Gemini audio requests", async () => {
+    await POST(makeGeminiRequest("openai/gpt-4o-mini-tts:generateContent", audioBody()), {
+      params: Promise.resolve({ path: ["openai", "gpt-4o-mini-tts:generateContent"] }),
+    });
+
+    expect(mocks.handleChat).toHaveBeenCalledTimes(1);
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/unit/gemini-tts.test.js b/tests/unit/gemini-tts.test.js
new file mode 100644
index 0000000..25e9a47
--- /dev/null
+++ b/tests/unit/gemini-tts.test.js
@@ -0,0 +1,95 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { handleTtsCore } from "../../open-sse/handlers/ttsCore.js";
+import { buildTtsProviderModels } from "../../open-sse/config/ttsModels.js";
+
+const originalFetch = global.fetch;
+
+function mockGeminiAudioResponse() {
+  global.fetch.mockResolvedValueOnce(
+    new Response(
+      JSON.stringify({
+        candidates: [
+          {
+            content: {
+              parts: [
+                {
+                  inlineData: {
+                    mimeType: "audio/pcm",
+                    data: Buffer.from([0, 1, 2, 3]).toString("base64"),
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } }
+    )
+  );
+}
+
+describe("Gemini TTS", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("uses the default Gemini TTS model when only a voice is provided", async () => {
+    mockGeminiAudioResponse();
+
+    const result = await handleTtsCore({
+      provider: "gemini",
+      model: "Zephyr",
+      input: "Hello from Gemini",
+      credentials: { apiKey: "test-key" },
+      responseFormat: "json",
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch.mock.calls[0][0]).toBe(
+      "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-tts-preview:generateContent?key=test-key"
+    );
+
+    const sent = JSON.parse(global.fetch.mock.calls[0][1].body);
+    expect(sent.generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName).toBe("Zephyr");
+    const body = await result.response.json();
+    expect(body.format).toBe("wav");
+    expect(body.audio).toEqual(expect.any(String));
+  });
+
+  it("preserves an explicit Gemini TTS model and voice pair", async () => {
+    mockGeminiAudioResponse();
+
+    const result = await handleTtsCore({
+      provider: "gemini",
+      model: "gemini-2.5-flash-preview-tts/Puck",
+      input: "Hello from Gemini",
+      credentials: { apiKey: "test-key" },
+      responseFormat: "json",
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch.mock.calls[0][0]).toBe(
+      "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent?key=test-key"
+    );
+
+    const sent = JSON.parse(global.fetch.mock.calls[0][1].body);
+    expect(sent.generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName).toBe("Puck");
+  });
+
+  it("exposes current Gemini TTS models in the TTS catalog", () => {
+    const entries = buildTtsProviderModels();
+
+    expect(entries["gemini-tts-models"].map((model) => model.id)).toEqual([
+      "gemini-3.1-flash-tts-preview",
+      "gemini-2.5-flash-preview-tts",
+      "gemini-2.5-pro-preview-tts",
+    ]);
+    expect(entries["gemini-tts-voices"]).toContainEqual(
+      expect.objectContaining({ id: "Zephyr", type: "tts" })
+    );
+  });
+});
diff --git a/tests/unit/gemini-usage-projectid.test.js b/tests/unit/gemini-usage-projectid.test.js
new file mode 100644
index 0000000..0d06f2c
--- /dev/null
+++ b/tests/unit/gemini-usage-projectid.test.js
@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch: vi.fn(),
+}));
+
+import { proxyAwareFetch } from "../../open-sse/utils/proxyFetch.js";
+import { getUsageForProvider } from "../../open-sse/services/usage.js";
+
+function jsonResponse(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("Gemini CLI usage project id resolution", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("uses the projectId stored on the provider connection", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(jsonResponse({
+      buckets: [
+        {
+          modelId: "gemini-3-flash-preview",
+          remainingFraction: 0.75,
+          resetTime: "2026-05-25T12:00:00Z",
+        },
+      ],
+    }));
+
+    const usage = await getUsageForProvider({
+      provider: "gemini-cli",
+      accessToken: "token",
+      projectId: "cloud-code-project",
+    });
+
+    expect(proxyAwareFetch).toHaveBeenCalledTimes(1);
+    expect(proxyAwareFetch).toHaveBeenCalledWith(
+      "https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuota",
+      expect.objectContaining({
+        body: JSON.stringify({ project: "cloud-code-project" }),
+      }),
+      null
+    );
+    expect(usage.quotas["gemini-3-flash-preview"]).toMatchObject({
+      used: 250,
+      total: 1000,
+      remainingPercentage: 75,
+    });
+  });
+
+  it("normalizes project objects returned by loadCodeAssist", async () => {
+    proxyAwareFetch
+      .mockResolvedValueOnce(jsonResponse({
+        cloudaicompanionProject: { id: "project-from-load" },
+        currentTier: { name: "Free" },
+      }))
+      .mockResolvedValueOnce(jsonResponse({ buckets: [] }));
+
+    await getUsageForProvider({
+      provider: "gemini-cli",
+      accessToken: "token",
+    });
+
+    expect(proxyAwareFetch).toHaveBeenLastCalledWith(
+      "https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuota",
+      expect.objectContaining({
+        body: JSON.stringify({ project: "project-from-load" }),
+      }),
+      null
+    );
+  });
+
+  it("returns actionable guidance when no project id is available", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(jsonResponse({}));
+
+    const usage = await getUsageForProvider({
+      provider: "gemini-cli",
+      accessToken: "token",
+    });
+
+    expect(usage.message).toContain("Reconnect Gemini CLI");
+    expect(usage.message).toContain("Gemini Code Assist");
+  });
+});
diff --git a/tests/unit/github-responses-routing.test.js b/tests/unit/github-responses-routing.test.js
new file mode 100644
index 0000000..5cf847d
--- /dev/null
+++ b/tests/unit/github-responses-routing.test.js
@@ -0,0 +1,56 @@
+/**
+ * Regression test for #1062:
+ * GitHub Copilot's /responses endpoint only serves OpenAI (gpt/codex) models.
+ * Gemini/Claude models must never be routed/escalated there, otherwise they
+ * fail with a misleading 400 "does not support Responses API".
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { GithubExecutor } from "../../open-sse/executors/github.js";
+
+describe("GithubExecutor.supportsResponsesEndpoint", () => {
+  const exec = new GithubExecutor();
+
+  it("excludes Gemini models from the /responses endpoint", () => {
+    expect(exec.supportsResponsesEndpoint("gemini-3.1-pro-preview")).toBe(false);
+    expect(exec.supportsResponsesEndpoint("gemini-3.1-pro-low")).toBe(false);
+  });
+
+  it("excludes Claude models from the /responses endpoint", () => {
+    expect(exec.supportsResponsesEndpoint("claude-sonnet-4.6")).toBe(false);
+    expect(exec.supportsResponsesEndpoint("claude-opus-4.7")).toBe(false);
+  });
+
+  it("allows OpenAI/codex models on the /responses endpoint", () => {
+    expect(exec.supportsResponsesEndpoint("gpt-5.5-codex")).toBe(true);
+    expect(exec.supportsResponsesEndpoint("o4-mini")).toBe(true);
+    expect(exec.supportsResponsesEndpoint("gpt-4.1")).toBe(true);
+  });
+
+  it("is null-safe", () => {
+    expect(exec.supportsResponsesEndpoint(undefined)).toBe(true);
+    expect(exec.supportsResponsesEndpoint("")).toBe(true);
+  });
+});
+
+describe("GithubExecutor.execute cached-route guard (#1062)", () => {
+  it("does NOT use /responses for a Gemini model even if it was wrongly cached as codex", async () => {
+    const exec = new GithubExecutor();
+    // Simulate a prior misclassification that cached the Gemini model.
+    exec.knownCodexModels.add("gemini-3.1-pro-preview");
+
+    const respSpy = vi
+      .spyOn(exec, "executeWithResponsesEndpoint")
+      .mockResolvedValue({ via: "responses" });
+    // Short-circuit the /chat/completions path (BaseExecutor.execute).
+    const baseSpy = vi
+      .spyOn(Object.getPrototypeOf(Object.getPrototypeOf(exec)), "execute")
+      .mockResolvedValue({ response: { status: 200 }, via: "chat" });
+
+    const result = await exec.execute({ model: "gemini-3.1-pro-preview", body: { messages: [] }, log: null });
+
+    expect(respSpy).not.toHaveBeenCalled();
+    expect(baseSpy).toHaveBeenCalled();
+    expect(result.via).toBe("chat");
+  });
+});
diff --git a/tests/unit/grok-cli-executor.test.js b/tests/unit/grok-cli-executor.test.js
new file mode 100644
index 0000000..e7c9052
--- /dev/null
+++ b/tests/unit/grok-cli-executor.test.js
@@ -0,0 +1,288 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  GrokCliExecutor,
+  countGrokCliUserTurns,
+  resolveGrokCliTurnIdx,
+  _resetGrokCliTurnStore,
+} from "../../open-sse/executors/grok-cli.js";
+import { getExecutor, hasSpecializedExecutor } from "../../open-sse/executors/index.js";
+import { PROVIDERS, PROVIDER_OAUTH, PROVIDER_MODELS } from "../../open-sse/providers/index.js";
+import { getModelUpstreamId } from "../../open-sse/config/providerModels.js";
+import { resolveProviderAlias } from "../../open-sse/services/model.js";
+import { OAUTH_PROVIDERS } from "../../src/shared/constants/providers.js";
+
+describe("grok-cli registry", () => {
+  it("registers transport + oauth + models", () => {
+    const cfg = PROVIDERS["grok-cli"];
+    expect(cfg).toBeTruthy();
+    expect(cfg.baseUrl).toBe("https://cli-chat-proxy.grok.com/v1/responses");
+    expect(cfg.format).toBe("openai-responses");
+    expect(cfg.forceStream).toBe(true);
+    expect(cfg.tokenAuth).toBe("xai-grok-cli");
+
+    const oauth = PROVIDER_OAUTH["grok-cli"];
+    expect(oauth.clientId).toBe("b1a00492-073a-47ea-816f-4c329264a828");
+    expect(oauth.deviceCodeUrl).toContain("auth.x.ai");
+    expect(oauth.scope).toContain("grok-cli:access");
+    expect(oauth.scope).toContain("conversations:write");
+    expect(oauth.referrer).toBe("grok-build");
+
+    expect(PROVIDER_MODELS.gcli?.some((m) => m.id === "grok-4.5")).toBe(true);
+  });
+
+  it("is listed as oauth provider for dashboard", () => {
+    expect(OAUTH_PROVIDERS["grok-cli"]).toBeTruthy();
+    expect(OAUTH_PROVIDERS["grok-cli"].name).toMatch(/Grok CLI/i);
+  });
+
+  it("resolves aliases to provider id", () => {
+    expect(resolveProviderAlias("gcli")).toBe("grok-cli");
+    expect(resolveProviderAlias("gb")).toBe("grok-cli");
+    expect(resolveProviderAlias("grok-build")).toBe("grok-cli");
+    expect(resolveProviderAlias("grok-cli")).toBe("grok-cli");
+  });
+
+  it("maps effort virtual models to upstream grok-4.5", () => {
+    expect(getModelUpstreamId("gcli", "grok-4.5-high")).toBe("grok-4.5");
+    expect(getModelUpstreamId("gcli", "grok-4.5-medium")).toBe("grok-4.5");
+    expect(getModelUpstreamId("gcli", "grok-4.5-low")).toBe("grok-4.5");
+    expect(getModelUpstreamId("gcli", "grok-4.5")).toBe("grok-4.5");
+  });
+});
+
+describe("GrokCliExecutor", () => {
+  let executor;
+
+  beforeEach(() => {
+    _resetGrokCliTurnStore();
+    executor = new GrokCliExecutor();
+  });
+
+  it("is registered on executor map (id + aliases)", () => {
+    expect(hasSpecializedExecutor("grok-cli")).toBe(true);
+    expect(getExecutor("grok-cli")).toBeInstanceOf(GrokCliExecutor);
+    expect(getExecutor("gcli")).toBeInstanceOf(GrokCliExecutor);
+    expect(getExecutor("gb")).toBeInstanceOf(GrokCliExecutor);
+  });
+
+  it("buildUrl points at cli-chat-proxy responses", () => {
+    expect(executor.buildUrl()).toBe("https://cli-chat-proxy.grok.com/v1/responses");
+  });
+
+  it("buildHeaders sets CLI fingerprint + session headers", () => {
+    executor._currentSessionId = "sess-abc";
+    executor._currentReqId = "req-xyz";
+    executor._agentId = "agent-1";
+    executor._currentModel = "grok-4.5";
+    executor._currentTurnIdx = 3;
+
+    const headers = executor.buildHeaders(
+      {
+        accessToken: "tok_test",
+        providerSpecificData: { email: "u@example.com", userId: "uid-1" },
+      },
+      true
+    );
+
+    expect(headers.Authorization).toBe("Bearer tok_test");
+    expect(headers.Accept).toBe("text/event-stream");
+    expect(headers["x-xai-token-auth"]).toBe("xai-grok-cli");
+    expect(headers["x-grok-client-identifier"]).toBe("grok-pager");
+    expect(headers["x-grok-client-version"]).toBe("0.2.93");
+    expect(headers["x-grok-session-id"]).toBe("sess-abc");
+    expect(headers["x-grok-conv-id"]).toBe("sess-abc");
+    expect(headers["x-grok-req-id"]).toBe("req-xyz");
+    expect(headers["x-grok-turn-idx"]).toBe("3");
+    expect(headers["x-grok-agent-id"]).toBe("agent-1");
+    expect(headers["x-grok-model-override"]).toBe("grok-4.5");
+    expect(headers["x-compaction-at"]).toBe("400000");
+    expect(headers["x-email"]).toBe("u@example.com");
+    expect(headers["x-userid"]).toBe("uid-1");
+    expect(headers["x-authenticateresponse"]).toBe("authenticate-response");
+  });
+
+  it("buildHeaders falls back to top-level email/userId (OAuth mapTokens shape)", () => {
+    executor._currentSessionId = "sess-top";
+    executor._currentReqId = "req-top";
+
+    const headers = executor.buildHeaders(
+      {
+        accessToken: "tok_test",
+        email: "top@example.com",
+        // userId only top-level; psd has neither email nor userId
+        providerSpecificData: { authMethod: "device_code" },
+      },
+      true
+    );
+
+    expect(headers["x-email"]).toBe("top@example.com");
+    expect(headers["x-userid"]).toBeUndefined();
+  });
+
+  it("transformRequest normalizes Responses body like official CLI", () => {
+    const body = {
+      model: "grok-4.5-high",
+      messages: [{ role: "user", content: "hi" }],
+      stream: false,
+      tools: [
+        {
+          type: "function",
+          function: {
+            name: "run_terminal_command",
+            description: "Run bash",
+            parameters: { type: "object", properties: { command: { type: "string" } } },
+          },
+        },
+        { type: "web_search" },
+        { type: "x_search" },
+      ],
+      temperature: 0.7,
+      max_tokens: 100,
+      user: "cursor-user",
+    };
+
+    // Simulate translator already converting messages→input; also test messages fallback
+    const out = executor.transformRequest("grok-4.5-high", { ...body }, true, {
+      connectionId: "conn-1",
+    });
+
+    expect(out.model).toBe("grok-4.5");
+    expect(out.stream).toBe(true);
+    expect(out.store).toBe(false);
+    expect(out.include).toContain("reasoning.encrypted_content");
+    expect(out.reasoning).toEqual({ effort: "high", summary: "concise" });
+    expect(out.messages).toBeUndefined();
+    expect(out.max_tokens).toBeUndefined();
+    expect(out.user).toBeUndefined();
+    expect(Array.isArray(out.input)).toBe(true);
+    expect(out.input.length).toBeGreaterThan(0);
+    expect(executor._currentTurnIdx).toBe(1);
+
+    // tools flattened + hosted tools kept
+    expect(out.tools).toHaveLength(3);
+    expect(out.tools[0]).toMatchObject({
+      type: "function",
+      name: "run_terminal_command",
+    });
+    expect(out.tools[0].parameters).toBeTruthy();
+    expect(out.tools[0].function).toBeUndefined();
+    expect(out.tools[1]).toEqual({ type: "web_search" });
+    expect(out.tools[2]).toEqual({ type: "x_search" });
+  });
+
+  it("transformRequest keeps role:system (HAR parity) and strips server ids", () => {
+    const body = {
+      model: "grok-4.5",
+      input: [
+        { type: "message", role: "system", content: "You are Grok" },
+        { type: "message", role: "user", content: "hi", id: "msg_server_id" },
+        { type: "item_reference", id: "rs_abc" },
+        "rs_should_drop",
+      ],
+      reasoning_effort: "medium",
+    };
+
+    const out = executor.transformRequest("grok-4.5", body, true, { connectionId: "c1" });
+    expect(out.input).toHaveLength(2);
+    // Official CLI sends system, not developer (Codex converts; Grok does not)
+    expect(out.input[0].role).toBe("system");
+    expect(out.input[1].id).toBeUndefined();
+    expect(out.reasoning.effort).toBe("medium");
+  });
+
+  it("increments x-grok-turn-idx from user-message count and stays monotonic", () => {
+    const creds = {
+      connectionId: "turn-conn",
+      rawHeaders: { "x-session-id": "stable-session-xyz" },
+    };
+
+    // Turn 1: one user message
+    executor.transformRequest(
+      "grok-4.5",
+      {
+        model: "grok-4.5",
+        input: [
+          { type: "message", role: "system", content: "sys" },
+          { type: "message", role: "user", content: "hi" },
+        ],
+      },
+      true,
+      creds
+    );
+    expect(executor._currentSessionId).toBeTruthy();
+    expect(executor._currentTurnIdx).toBe(1);
+    let headers = executor.buildHeaders({ accessToken: "t" }, true);
+    expect(headers["x-grok-turn-idx"]).toBe("1");
+    expect(headers["x-grok-session-id"]).toBe(executor._currentSessionId);
+    expect(headers["x-grok-conv-id"]).toBe(executor._currentSessionId);
+
+    const sessionId = executor._currentSessionId;
+
+    // Turn 2: full history with two user messages
+    executor.transformRequest(
+      "grok-4.5",
+      {
+        model: "grok-4.5",
+        input: [
+          { type: "message", role: "system", content: "sys" },
+          { type: "message", role: "user", content: "hi" },
+          { type: "message", role: "assistant", content: "hello" },
+          { type: "message", role: "user", content: "next" },
+        ],
+      },
+      true,
+      creds
+    );
+    expect(executor._currentSessionId).toBe(sessionId);
+    expect(executor._currentTurnIdx).toBe(2);
+    headers = executor.buildHeaders({ accessToken: "t" }, true);
+    expect(headers["x-grok-turn-idx"]).toBe("2");
+
+    // Same session, payload that only has 1 user msg (delta-style client) must not go backwards
+    executor.transformRequest(
+      "grok-4.5",
+      {
+        model: "grok-4.5",
+        input: [{ type: "message", role: "user", content: "only latest" }],
+      },
+      true,
+      creds
+    );
+    expect(executor._currentTurnIdx).toBe(2);
+  });
+
+  it("countGrokCliUserTurns / resolveGrokCliTurnIdx helpers", () => {
+    expect(countGrokCliUserTurns(null)).toBe(1);
+    expect(
+      countGrokCliUserTurns([
+        { type: "message", role: "system", content: "s" },
+        { type: "message", role: "user", content: "a" },
+        { type: "message", role: "assistant", content: "b" },
+        { type: "message", role: "user", content: "c" },
+      ])
+    ).toBe(2);
+
+    expect(resolveGrokCliTurnIdx("s1", [{ role: "user", type: "message", content: "a" }])).toBe(1);
+    expect(
+      resolveGrokCliTurnIdx("s1", [
+        { role: "user", type: "message", content: "a" },
+        { role: "user", type: "message", content: "b" },
+      ])
+    ).toBe(2);
+    // monotonic
+    expect(resolveGrokCliTurnIdx("s1", [{ role: "user", type: "message", content: "a" }])).toBe(2);
+  });
+
+  it("parseError surfaces 402 spending-limit", () => {
+    const err = executor.parseError(
+      { status: 402 },
+      JSON.stringify({
+        code: "personal-team-blocked:spending-limit",
+        error: "You have run out of credits",
+      })
+    );
+    expect(err.status).toBe(402);
+    expect(err.code).toBe("personal-team-blocked:spending-limit");
+    expect(err.message).toMatch(/credits/i);
+  });
+});
diff --git a/tests/unit/grok-cli-oauth-probe.test.js b/tests/unit/grok-cli-oauth-probe.test.js
new file mode 100644
index 0000000..5cda4cd
--- /dev/null
+++ b/tests/unit/grok-cli-oauth-probe.test.js
@@ -0,0 +1,50 @@
+/**
+ * Grok CLI connection-test semantics: 402 spending-limit is soft success (auth OK).
+ */
+import { describe, it, expect } from "vitest";
+import { classifyOAuthProbeResult } from "../../src/app/api/providers/[id]/test/testUtils.js";
+import { PROVIDERS } from "../../open-sse/providers/index.js";
+
+const GROK_CLI_PROBE = {
+  url: PROVIDERS["grok-cli"]?.userUrl || "https://cli-chat-proxy.grok.com/v1/user",
+  method: "GET",
+  acceptStatuses: [402],
+  softFailMessage: {
+    402: "Connected, but Grok Build credits are exhausted (spending limit). Add credits or upgrade SuperGrok.",
+  },
+};
+
+describe("classifyOAuthProbeResult (grok-cli)", () => {
+  it("treats 200 as hard success", () => {
+    const r = classifyOAuthProbeResult({ ok: true, status: 200 }, GROK_CLI_PROBE, "");
+    expect(r).toEqual({ valid: true, error: null, soft: false });
+  });
+
+  it("treats 402 spending-limit as soft success (connected, out of credits)", () => {
+    const body = JSON.stringify({
+      code: "personal-team-blocked:spending-limit",
+      error: "You have run out of credits",
+    });
+    const r = classifyOAuthProbeResult({ ok: false, status: 402 }, GROK_CLI_PROBE, body);
+    expect(r.valid).toBe(true);
+    expect(r.soft).toBe(true);
+    expect(r.error).toMatch(/credits|SuperGrok|spending/i);
+  });
+
+  it("treats 401 as hard auth failure", () => {
+    const r = classifyOAuthProbeResult({ ok: false, status: 401 }, GROK_CLI_PROBE, "unauthorized");
+    expect(r).toEqual({ valid: false, error: "Token invalid or revoked", soft: false });
+  });
+
+  it("treats 403 as access denied", () => {
+    const r = classifyOAuthProbeResult({ ok: false, status: 403 }, GROK_CLI_PROBE, "");
+    expect(r.valid).toBe(false);
+    expect(r.error).toMatch(/Access denied/i);
+  });
+
+  it("Codex-style acceptStatuses 400 stays silent success (no soft warning)", () => {
+    const codex = { acceptStatuses: [400] };
+    const r = classifyOAuthProbeResult({ ok: false, status: 400 }, codex, "bad request");
+    expect(r).toEqual({ valid: true, error: null, soft: false });
+  });
+});
diff --git a/tests/unit/grok-cli-usage.test.js b/tests/unit/grok-cli-usage.test.js
new file mode 100644
index 0000000..49bebb7
--- /dev/null
+++ b/tests/unit/grok-cli-usage.test.js
@@ -0,0 +1,202 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch: vi.fn(),
+}));
+
+import { proxyAwareFetch } from "../../open-sse/utils/proxyFetch.js";
+import { getUsageForProvider } from "../../open-sse/services/usage.js";
+import { parseGrokCliBilling } from "../../open-sse/services/usage/grok-cli.js";
+import { USAGE_SUPPORTED_PROVIDERS } from "../../src/shared/constants/providers.js";
+import { PROVIDERS } from "../../open-sse/providers/index.js";
+import { parseQuotaData } from "../../src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.js";
+
+function jsonResponse(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const EXHAUSTED_BILLING = {
+  config: {
+    currentPeriod: {
+      type: "USAGE_PERIOD_TYPE_WEEKLY",
+      start: "2026-07-08T00:00:00+00:00",
+      end: "2026-07-15T00:00:00+00:00",
+    },
+    onDemandCap: { val: 0 },
+    onDemandUsed: { val: 0 },
+    isUnifiedBillingUser: true,
+    prepaidBalance: { val: 0 },
+    topUpMethod: "TOP_UP_METHOD_SAVED_PAYMENT_METHOD",
+    billingPeriodStart: "2026-07-08T00:00:00+00:00",
+    billingPeriodEnd: "2026-07-15T00:00:00+00:00",
+  },
+};
+
+const ACTIVE_BILLING = {
+  config: {
+    currentPeriod: {
+      type: "USAGE_PERIOD_TYPE_WEEKLY",
+      start: "2026-07-08T00:00:00+00:00",
+      end: "2026-07-15T00:00:00+00:00",
+    },
+    onDemandCap: { val: 100 },
+    onDemandUsed: { val: 35 },
+    isUnifiedBillingUser: true,
+    prepaidBalance: { val: 12.5 },
+    billingPeriodStart: "2026-07-08T00:00:00+00:00",
+    billingPeriodEnd: "2026-07-15T00:00:00+00:00",
+  },
+};
+
+const USER_PROFILE = {
+  userId: "d84768dd-224d-4052-ba49-0d336fa9160c",
+  email: "user@example.com",
+  hasGrokCodeAccess: true,
+  subscriptionTier: null,
+};
+
+describe("grok-cli registry usage flag", () => {
+  it("exposes transport.usage urls", () => {
+    const cfg = PROVIDERS["grok-cli"];
+    expect(cfg.usage?.url).toContain("/v1/billing");
+    expect(cfg.usage?.userUrl).toContain("/v1/user");
+  });
+
+  it("is listed in USAGE_SUPPORTED_PROVIDERS", () => {
+    expect(USAGE_SUPPORTED_PROVIDERS).toContain("grok-cli");
+  });
+});
+
+describe("parseGrokCliBilling", () => {
+  it("maps on-demand cap/used + prepaid balance", () => {
+    const parsed = parseGrokCliBilling(ACTIVE_BILLING, USER_PROFILE);
+    expect(parsed.plan).toBe("Grok Code");
+    expect(parsed.quotas["On-demand"]).toMatchObject({
+      used: 35,
+      total: 100,
+      remainingPercentage: 65,
+    });
+    // Prepaid is remaining-balance style: 0 used of current pot
+    expect(parsed.quotas.Prepaid).toMatchObject({
+      used: 0,
+      total: 12.5,
+      remainingPercentage: 100,
+    });
+    expect(parsed.exhausted).toBe(false);
+  });
+
+  it("marks depleted free/promo account as exhausted", () => {
+    const parsed = parseGrokCliBilling(EXHAUSTED_BILLING, USER_PROFILE);
+    expect(parsed.quotas["On-demand"].remainingPercentage).toBe(0);
+    expect(parsed.exhausted).toBe(true);
+  });
+
+  it("uses subscriptionTier for plan when present", () => {
+    const parsed = parseGrokCliBilling(ACTIVE_BILLING, {
+      ...USER_PROFILE,
+      subscriptionTier: "super_grok",
+    });
+    expect(parsed.plan).toBe("Super Grok");
+  });
+});
+
+describe("getUsageForProvider(grok-cli)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns normalized quotas from billing + user endpoints", async () => {
+    proxyAwareFetch
+      .mockResolvedValueOnce(jsonResponse(ACTIVE_BILLING))
+      .mockResolvedValueOnce(jsonResponse(USER_PROFILE));
+
+    const usage = await getUsageForProvider({
+      provider: "grok-cli",
+      accessToken: "test-token",
+      providerSpecificData: {
+        email: "user@example.com",
+        userId: "d84768dd-224d-4052-ba49-0d336fa9160c",
+      },
+    });
+
+    expect(usage.message).toBeUndefined();
+    expect(usage.plan).toBe("Grok Code");
+    expect(usage.quotas["On-demand"]).toMatchObject({
+      used: 35,
+      total: 100,
+      remainingPercentage: 65,
+    });
+    expect(usage.quotas.Prepaid).toMatchObject({
+      used: 0,
+      total: 12.5,
+      remainingPercentage: 100,
+    });
+
+    // Official CLI fingerprint headers
+    const billingCall = proxyAwareFetch.mock.calls[0];
+    expect(billingCall[0]).toContain("/v1/billing");
+    expect(billingCall[1].headers.Authorization).toBe("Bearer test-token");
+    expect(billingCall[1].headers["x-xai-token-auth"]).toBe("xai-grok-cli");
+    expect(billingCall[1].headers["x-userid"]).toBe(
+      "d84768dd-224d-4052-ba49-0d336fa9160c",
+    );
+  });
+
+  it("surfaces auth-expired message on 401", async () => {
+    proxyAwareFetch
+      .mockResolvedValueOnce(jsonResponse({ error: "unauthorized" }, 401))
+      .mockResolvedValueOnce(jsonResponse(USER_PROFILE));
+
+    const usage = await getUsageForProvider({
+      provider: "grok-cli",
+      accessToken: "expired",
+    });
+
+    expect(usage.message).toMatch(/expired|re-authorize/i);
+  });
+
+  it("returns depleted on-demand bar without blocking message when cap is zero", async () => {
+    proxyAwareFetch
+      .mockResolvedValueOnce(jsonResponse(EXHAUSTED_BILLING))
+      .mockResolvedValueOnce(jsonResponse(USER_PROFILE));
+
+    const usage = await getUsageForProvider({
+      provider: "grok-cli",
+      accessToken: "test-token",
+    });
+
+    // Dashboard hides QuotaTable when `message` is set — keep message empty
+    // so the 0% bar still renders for exhausted free/promo accounts.
+    expect(usage.message).toBeUndefined();
+    expect(usage.quotas["On-demand"].remainingPercentage).toBe(0);
+    expect(usage.quotas["On-demand"].total).toBe(1);
+  });
+});
+
+describe("parseQuotaData(grok-cli)", () => {
+  it("forwards remainingPercentage for dashboard bars", () => {
+    const rows = parseQuotaData("grok-cli", {
+      plan: "Grok Code",
+      quotas: {
+        "On-demand": {
+          used: 35,
+          total: 100,
+          remaining: 65,
+          remainingPercentage: 65,
+          resetAt: "2026-07-15T00:00:00.000Z",
+        },
+      },
+    });
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      name: "On-demand",
+      used: 35,
+      total: 100,
+      remainingPercentage: 65,
+    });
+  });
+});
diff --git a/tests/unit/headroom-chat-core.test.js b/tests/unit/headroom-chat-core.test.js
new file mode 100644
index 0000000..5c552ab
--- /dev/null
+++ b/tests/unit/headroom-chat-core.test.js
@@ -0,0 +1,253 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const { executeMock } = vi.hoisted(() => ({
+  executeMock: vi.fn(),
+}));
+
+vi.mock("../../open-sse/executors/index.js", () => ({
+  getExecutor: () => ({
+    noAuth: true,
+    execute: executeMock,
+  }),
+}));
+
+vi.mock("../../open-sse/utils/requestLogger.js", () => ({
+  createRequestLogger: async () => ({
+    logClientRawRequest: vi.fn(),
+    logRawRequest: vi.fn(),
+    logTargetRequest: vi.fn(),
+    logProviderResponse: vi.fn(),
+    logConvertedResponse: vi.fn(),
+    logError: vi.fn(),
+  }),
+}));
+
+vi.mock("../../open-sse/utils/stream.js", () => ({
+  COLORS: { red: "", reset: "" },
+  createPassthroughStreamWithLogger: vi.fn(() => new TransformStream()),
+}));
+
+vi.mock("@/lib/usageDb.js", () => ({
+  trackPendingRequest: vi.fn(),
+  appendRequestLog: vi.fn(async () => {}),
+  saveRequestDetail: vi.fn(async () => {}),
+}));
+
+const { handleChatCore } = await import("../../open-sse/handlers/chatCore.js");
+
+describe("handleChatCore Headroom diagnostics", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    global.fetch = vi.fn(async (url) => {
+      if (String(url).includes("/v1/compress")) {
+        throw Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:8787"), { code: "ECONNREFUSED" });
+      }
+      throw new Error(`unexpected fetch: ${url}`);
+    });
+    executeMock.mockResolvedValue({
+      response: new Response(JSON.stringify({
+        id: "chatcmpl-test",
+        object: "chat.completion",
+        choices: [{ message: { role: "assistant", content: "ok" }, finish_reason: "stop", index: 0 }],
+      }), { status: 200, headers: { "content-type": "application/json" } }),
+      url: "https://api.openai.com/v1/chat/completions",
+      headers: {},
+      transformedBody: null,
+    });
+  });
+
+  it("logs why Headroom was skipped on chat completions", async () => {
+    const log = { debug: vi.fn(), info: vi.fn(), warn: vi.fn() };
+
+    await handleChatCore({
+      body: { model: "gpt-4o", stream: false, messages: [{ role: "user", content: "hello" }] },
+      modelInfo: { provider: "openai", model: "gpt-4o" },
+      credentials: { apiKey: "test-key", providerSpecificData: {} },
+      log,
+      connectionId: "test-conn",
+      headroomEnabled: true,
+      headroomUrl: "http://localhost:8787",
+      headroomCompressUserMessages: false,
+      rtkEnabled: false,
+      cavemanEnabled: false,
+      ponytailEnabled: false,
+      clientRawRequest: {
+        endpoint: "/v1/chat/completions",
+        body: {},
+        headers: { accept: "application/json" },
+      },
+    });
+
+    expect(log.warn).toHaveBeenCalledWith(
+      "HEADROOM",
+      expect.stringContaining("skipped: request failed")
+    );
+    expect(log.warn).toHaveBeenCalledWith(
+      "HEADROOM",
+      expect.stringContaining("ECONNREFUSED")
+    );
+    expect(log.warn).toHaveBeenCalledWith(
+      "HEADROOM",
+      expect.stringContaining("http://localhost:8787/v1/compress")
+    );
+  });
+
+  it("scrubs credentials and query strings from Headroom fetch errors", async () => {
+    const log = { debug: vi.fn(), info: vi.fn(), warn: vi.fn() };
+
+    global.fetch = vi.fn(async () => {
+      throw new Error("failed to fetch https://user:secret@example.com:8787/proxy/v1/compress?token=abc123");
+    });
+
+    await handleChatCore({
+      body: { model: "gpt-4o", stream: false, messages: [{ role: "user", content: "hello" }] },
+      modelInfo: { provider: "openai", model: "gpt-4o" },
+      credentials: { apiKey: "test-key", providerSpecificData: {} },
+      log,
+      connectionId: "test-conn",
+      headroomEnabled: true,
+      headroomUrl: "https://user:secret@example.com:8787/proxy?token=abc123",
+      headroomCompressUserMessages: false,
+      rtkEnabled: false,
+      cavemanEnabled: false,
+      ponytailEnabled: false,
+      clientRawRequest: {
+        endpoint: "/v1/chat/completions",
+        body: {},
+        headers: { accept: "application/json" },
+      },
+    });
+
+    const logs = JSON.stringify(log.warn.mock.calls);
+    expect(logs).toContain("https://example.com:8787/proxy/v1/compress");
+    expect(logs).not.toContain("user");
+    expect(logs).not.toContain("secret");
+    expect(logs).not.toContain("abc123");
+  });
+
+  it("masks credentials and query strings in Headroom endpoint diagnostics", async () => {
+    const log = { debug: vi.fn(), info: vi.fn(), warn: vi.fn() };
+
+    await handleChatCore({
+      body: { model: "gpt-4o", stream: false, messages: [{ role: "user", content: "hello" }] },
+      modelInfo: { provider: "openai", model: "gpt-4o" },
+      credentials: { apiKey: "test-key", providerSpecificData: {} },
+      log,
+      connectionId: "test-conn",
+      headroomEnabled: true,
+      headroomUrl: "https://user:secret@example.com:8787/proxy?token=abc123",
+      headroomCompressUserMessages: false,
+      rtkEnabled: false,
+      cavemanEnabled: false,
+      ponytailEnabled: false,
+      clientRawRequest: {
+        endpoint: "/v1/chat/completions",
+        body: {},
+        headers: { accept: "application/json" },
+      },
+    });
+
+    const logs = JSON.stringify(log.warn.mock.calls);
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://user:secret@example.com:8787/proxy/v1/compress?token=abc123",
+      expect.any(Object)
+    );
+    expect(logs).toContain("https://example.com:8787/proxy/v1/compress");
+    expect(logs).not.toContain("user");
+    expect(logs).not.toContain("secret");
+    expect(logs).not.toContain("abc123");
+  });
+
+  it("sends Headroom-compressed messages to the provider executor", async () => {
+    const log = { debug: vi.fn(), info: vi.fn(), warn: vi.fn() };
+    const original = "very large context that should be replaced";
+    const compressed = "compressed context";
+
+    global.fetch = vi.fn(async (url) => {
+      if (String(url).includes("/v1/compress")) {
+        return new Response(JSON.stringify({
+          messages: [{ role: "user", content: compressed }],
+          tokens_before: 100,
+          tokens_after: 10,
+          tokens_saved: 90,
+        }), { status: 200, headers: { "content-type": "application/json" } });
+      }
+      throw new Error(`unexpected fetch: ${url}`);
+    });
+
+    await handleChatCore({
+      body: { model: "gpt-4o", stream: false, messages: [{ role: "user", content: original }] },
+      modelInfo: { provider: "openai", model: "gpt-4o" },
+      credentials: { apiKey: "test-key", providerSpecificData: {} },
+      log,
+      connectionId: "test-conn",
+      headroomEnabled: true,
+      headroomUrl: "http://localhost:8787",
+      headroomCompressUserMessages: false,
+      rtkEnabled: false,
+      cavemanEnabled: false,
+      ponytailEnabled: false,
+      clientRawRequest: {
+        endpoint: "/v1/chat/completions",
+        body: {},
+        headers: { accept: "application/json" },
+      },
+    });
+
+    expect(executeMock).toHaveBeenCalledWith(expect.objectContaining({
+      body: expect.objectContaining({
+        messages: [{ role: "user", content: compressed }],
+      }),
+    }));
+    expect(JSON.stringify(executeMock.mock.calls[0][0].body)).not.toContain(original);
+    expect(log.info).toHaveBeenCalledWith("HEADROOM", expect.stringContaining("reported token delta=90 before=100 after=10"));
+    expect(log.info).toHaveBeenCalledWith("HEADROOM", expect.stringContaining("body="));
+    expect(log.info).toHaveBeenCalledWith("HEADROOM", expect.stringContaining("messages="));
+
+    const logs = JSON.stringify([...log.info.mock.calls, ...log.warn.mock.calls]);
+    expect(logs).not.toContain("saved");
+    expect(logs).not.toContain(original);
+  });
+
+  it("warns when Headroom reports savings but outbound body barely shrinks", async () => {
+    const log = { debug: vi.fn(), info: vi.fn(), warn: vi.fn() };
+    const original = "x".repeat(1000);
+    const nearlySame = "x".repeat(990);
+
+    global.fetch = vi.fn(async (url) => {
+      if (String(url).includes("/v1/compress")) {
+        return new Response(JSON.stringify({
+          messages: [{ role: "user", content: nearlySame }],
+          tokens_before: 1000,
+          tokens_after: 100,
+          tokens_saved: 900,
+        }), { status: 200, headers: { "content-type": "application/json" } });
+      }
+      throw new Error(`unexpected fetch: ${url}`);
+    });
+
+    await handleChatCore({
+      body: { model: "gpt-4o", stream: false, messages: [{ role: "user", content: original }] },
+      modelInfo: { provider: "openai", model: "gpt-4o" },
+      credentials: { apiKey: "test-key", providerSpecificData: {} },
+      log,
+      connectionId: "test-conn",
+      headroomEnabled: true,
+      headroomUrl: "http://localhost:8787",
+      headroomCompressUserMessages: false,
+      rtkEnabled: false,
+      cavemanEnabled: false,
+      ponytailEnabled: false,
+      clientRawRequest: {
+        endpoint: "/v1/chat/completions",
+        body: {},
+        headers: { accept: "application/json" },
+      },
+    });
+
+    expect(log.warn).toHaveBeenCalledWith(
+      "HEADROOM",
+      expect.stringContaining("reported token delta, but outbound JSON shrank <5%; provider may bill near-original payload")
+    );
+  });
+});
diff --git a/tests/unit/headroom-detect.test.js b/tests/unit/headroom-detect.test.js
new file mode 100644
index 0000000..d1239a6
--- /dev/null
+++ b/tests/unit/headroom-detect.test.js
@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  execSync: vi.fn(() => { throw new Error("not found"); }),
+  execFile: vi.fn(() => ({ toString: () => "[object Object]" })),
+  execFileSync: vi.fn(() => Buffer.from(JSON.stringify([
+    { name: "headroom-ai", version: "0.26.0" },
+    { name: "tree-sitter", version: "0.25.0" },
+  ]))),
+}));
+
+vi.mock("child_process", () => ({
+  execSync: mocks.execSync,
+  execFile: mocks.execFile,
+  execFileSync: mocks.execFileSync,
+}));
+
+import { findPython310, getHeadroomStatus, getInstalledHeadroomExtras, isLoopbackHeadroomUrl } from "../../src/lib/headroom/detect.js";
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("headroom detect", () => {
+  it("detects installed headroom version and extras from pip list", () => {
+    const result = getInstalledHeadroomExtras("python3");
+
+    expect(mocks.execFileSync).toHaveBeenCalledWith(
+      "python3",
+      ["-m", "pip", "list", "--format=json", "--disable-pip-version-check"],
+      expect.objectContaining({ windowsHide: true, timeout: 8000 }),
+    );
+    expect(result).toEqual({
+      installed: true,
+      version: "0.26.0",
+      extras: { code: true, ml: false },
+    });
+  });
+
+  it("prefers the interpreter that actually has headroom-ai installed", () => {
+    // headroom binary lives in a bin dir; the python next to it has headroom-ai.
+    const binPython = "/opt/hr/bin/python3";
+    mocks.execSync.mockImplementation((cmd) => {
+      if (String(cmd).includes("where") || String(cmd).includes("which")) return Buffer.from("/opt/hr/bin/headroom\n");
+      if (String(cmd).includes("--version")) return Buffer.from("Python 3.13.0\n");
+      throw new Error("unexpected execSync");
+    });
+    mocks.execFileSync.mockImplementation((py, args) => {
+      if (args.join(" ") === "-m pip show headroom-ai") {
+        if (py === binPython) return Buffer.from("Name: headroom-ai\nVersion: 0.26.0\n");
+        throw new Error(`not installed in ${py}`);
+      }
+      throw new Error(`unexpected execFileSync: ${py} ${args.join(" ")}`);
+    });
+
+    expect(findPython310()).toBe(binPython);
+  });
+
+  it("keeps top-level installed flag true when extras are readable", async () => {
+    global.fetch = vi.fn(async () => new Response("ok", { status: 200 }));
+    mocks.execSync.mockImplementation((cmd) => {
+      if (String(cmd).includes("where") || String(cmd).includes("which")) return Buffer.from("C:/Python/Scripts/headroom.exe\n");
+      if (String(cmd).includes("python3 --version")) return Buffer.from("Python 3.13.0\n");
+      if (String(cmd).includes("python --version")) return Buffer.from("Python 3.13.0\n");
+      throw new Error("unexpected execSync");
+    });
+    mocks.execFileSync.mockImplementation((py, args) => {
+      if (py === "python3" && args.join(" ") === "-m pip show headroom-ai") throw new Error("not installed in python3");
+      if (py === "python" && args.join(" ") === "-m pip show headroom-ai") return Buffer.from("Name: headroom-ai\nVersion: 0.26.0\n");
+      if (py === "python" && args.join(" ").startsWith("-m pip list ")) return Buffer.from(JSON.stringify([
+        { name: "headroom-ai", version: "0.26.0" },
+        { name: "tree-sitter", version: "0.25.0" },
+      ]));
+      throw new Error(`unexpected execFileSync: ${py} ${args.join(" ")}`);
+    });
+
+    const status = await getHeadroomStatus("http://localhost:8787");
+
+    expect(status.installed).toBe(true);
+    expect(status.version).toBe("0.26.0");
+    expect(status.extras).toEqual({ code: true, ml: false });
+  });
+
+  it("treats a reachable external proxy as running without local CLI", async () => {
+    global.fetch = vi.fn(async () => new Response("ok", { status: 200 }));
+    mocks.execSync.mockImplementation((cmd) => {
+      if (String(cmd).includes("where") || String(cmd).includes("which")) throw new Error("not found");
+      throw new Error("unexpected execSync");
+    });
+    mocks.execFileSync.mockImplementation(() => { throw new Error("pip unavailable"); });
+
+    const status = await getHeadroomStatus("http://headroom:8787");
+
+    expect(status.installed).toBe(false);
+    expect(status.running).toBe(true);
+    expect(status.localUrl).toBe(false);
+    expect(status.canStart).toBe(false);
+    expect(global.fetch).toHaveBeenCalledWith("http://headroom:8787/health", expect.any(Object));
+  });
+
+  it("recognizes loopback URLs for managed local mode", () => {
+    expect(isLoopbackHeadroomUrl("http://localhost:8787")).toBe(true);
+    expect(isLoopbackHeadroomUrl("http://127.0.0.1:8787")).toBe(true);
+    expect(isLoopbackHeadroomUrl("http://headroom:8787")).toBe(false);
+    expect(isLoopbackHeadroomUrl("not-a-url")).toBe(false);
+  });
+});
diff --git a/tests/unit/headroom-responses-format.test.js b/tests/unit/headroom-responses-format.test.js
new file mode 100644
index 0000000..a796e16
--- /dev/null
+++ b/tests/unit/headroom-responses-format.test.js
@@ -0,0 +1,107 @@
+// #1998 — Headroom compression treated a Codex (openai-responses) body.input
+// array as OpenAI messages: it sent Responses items to /v1/compress and then
+// assigned the returned OpenAI messages back to body.input, violating the
+// Responses format contract. body.input must stay Responses-shaped.
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { compressWithHeadroom } from "../../open-sse/rtk/headroom.js";
+
+describe("compressWithHeadroom openai-responses format (#1998)", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("keeps body.input in Responses format after compressing an openai-responses request", async () => {
+    // Headroom always returns compressed OpenAI-style messages.
+    global.fetch = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        messages: [{ role: "user", content: "compressed text" }],
+        tokens_before: 100,
+        tokens_after: 90,
+        tokens_saved: 10,
+      }),
+    }));
+
+    const body = {
+      input: [
+        {
+          type: "message",
+          role: "user",
+          content: [{ type: "input_text", text: "a long original message ".repeat(20) }],
+        },
+      ],
+    };
+
+    const data = await compressWithHeadroom(body, {
+      enabled: true,
+      url: "http://headroom.test",
+      model: "gpt-5",
+      format: "openai-responses",
+    });
+
+    expect(data).not.toBeNull();
+    // body.input must remain Responses items (type:"message" + content array),
+    // NOT the raw OpenAI messages ({ role, content: "<string>" }) the bug produced.
+    expect(Array.isArray(body.input)).toBe(true);
+    expect(body.input[0]).toMatchObject({ type: "message", role: "user" });
+    expect(Array.isArray(body.input[0].content)).toBe(true);
+    expect(typeof body.input[0].content).not.toBe("string");
+  });
+
+  it("skips Responses tool/reasoning history instead of collapsing it into a message (#2132)", async () => {
+    global.fetch = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        messages: [{ role: "user", content: "compressed tool history" }],
+        tokens_saved: 10,
+      }),
+    }));
+
+    const input = [
+      {
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text: "investigate bug" }],
+      },
+      {
+        type: "function_call",
+        call_id: "call_apply_patch_123",
+        name: "apply_patch",
+        arguments: "*** Begin Patch\n*** End Patch",
+      },
+      {
+        type: "function_call_output",
+        call_id: "call_apply_patch_123",
+        output: "ok",
+      },
+      {
+        type: "reasoning",
+        summary: [{ type: "summary_text", text: "Need a plan" }],
+      },
+    ];
+    const body = {
+      input: structuredClone(input),
+      tools: [
+        {
+          type: "custom",
+          name: "apply_patch",
+          format: { type: "grammar", syntax: "lark", definition: "start: /.+/" },
+        },
+      ],
+    };
+    const diagnostics = {};
+
+    const data = await compressWithHeadroom(body, {
+      enabled: true,
+      url: "http://headroom.test",
+      model: "gpt-5",
+      format: "openai-responses",
+      diagnostics,
+    });
+
+    expect(data).toBeNull();
+    expect(global.fetch).not.toHaveBeenCalled();
+    expect(body.input).toEqual(input);
+    expect(diagnostics.reason).toBe("skipped: openai-responses tool/reasoning input is not safe to compress");
+  });
+});
diff --git a/tests/unit/headroom.test.js b/tests/unit/headroom.test.js
new file mode 100644
index 0000000..b7c414d
--- /dev/null
+++ b/tests/unit/headroom.test.js
@@ -0,0 +1,212 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { compressWithHeadroom, formatHeadroomLog } from "../../open-sse/rtk/headroom.js";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("compressWithHeadroom", () => {
+  it("no-ops when disabled", async () => {
+    global.fetch = vi.fn();
+    const body = { messages: [{ role: "user", content: "hello" }] };
+
+    const stats = await compressWithHeadroom(body, { enabled: false, url: "http://localhost:8787" });
+
+    expect(stats).toBeNull();
+    expect(global.fetch).not.toHaveBeenCalled();
+    expect(body.messages[0].content).toBe("hello");
+  });
+
+  it("compresses messages in-place", async () => {
+    global.fetch = vi.fn(async () => new Response(JSON.stringify({
+      messages: [{ role: "user", content: "short" }],
+      tokens_before: 100,
+      tokens_after: 20,
+      tokens_saved: 80,
+    }), { status: 200 }));
+    const body = { messages: [{ role: "user", content: "long" }] };
+
+    const stats = await compressWithHeadroom(body, { enabled: true, url: "http://headroom:8787/", model: "gpt-4o" });
+
+    expect(body.messages[0].content).toBe("short");
+    expect(stats.tokens_saved).toBe(80);
+    expect(global.fetch).toHaveBeenCalledWith("http://headroom:8787/v1/compress", expect.objectContaining({ method: "POST" }));
+    expect(JSON.parse(global.fetch.mock.calls[0][1].body)).toMatchObject({
+      model: "gpt-4o",
+      messages: [{ role: "user", content: "long" }],
+    });
+  });
+
+  it("compresses responses input in-place", async () => {
+    global.fetch = vi.fn(async () => new Response(JSON.stringify({
+      messages: [{ role: "user", content: "short" }],
+    }), { status: 200 }));
+    const body = { input: [{ role: "user", content: "long" }] };
+
+    await compressWithHeadroom(body, { enabled: true, url: "http://localhost:8787" });
+
+    expect(body.input[0].content).toBe("short");
+  });
+
+  it("compresses Kiro conversationState history/currentMessage in-place", async () => {
+    let requestPayload;
+    global.fetch = vi.fn(async (_url, init) => {
+      requestPayload = JSON.parse(init.body);
+      return new Response(JSON.stringify({
+        messages: [
+          { role: "user", content: "compressed earlier user" },
+          { role: "assistant", content: "compressed assistant", tool_calls: [{ id: "tool_1", type: "function", function: { name: "read_file", arguments: "{\"path\":\"a.js\"}" } }] },
+          { role: "system", content: "compressed system instruction" },
+          { role: "user", content: "compressed current user" },
+          { role: "tool", content: [{ type: "text", text: "compressed tool output" }], tool_call_id: "tool_1" },
+        ],
+        tokens_before: 100,
+        tokens_after: 40,
+        tokens_saved: 60,
+      }), { status: 200 });
+    });
+    const body = {
+      profileArn: "arn:test",
+      conversationState: {
+        chatTriggerType: "MANUAL",
+        conversationId: "conv-1",
+        history: [
+          {
+            userInputMessage: {
+              content: "earlier user",
+              modelId: "claude-sonnet-4.5",
+            },
+          },
+          {
+            assistantResponseMessage: {
+              content: "assistant response",
+              toolUses: [
+                {
+                  toolUseId: "tool_1",
+                  name: "read_file",
+                  input: { path: "a.js" },
+                },
+              ],
+            },
+          },
+        ],
+        currentMessage: {
+          userInputMessage: {
+            content: "current user",
+            modelId: "claude-sonnet-4.5",
+            systemInstruction: "native system instruction",
+            userInputMessageContext: {
+              tools: [{ toolSpecification: { name: "read_file" } }],
+              toolResults: [
+                {
+                  toolUseId: "tool_1",
+                  status: "success",
+                  content: [{ text: "long tool output" }],
+                },
+              ],
+            },
+          },
+        },
+      },
+    };
+
+    const stats = await compressWithHeadroom(body, {
+      enabled: true,
+      url: "http://localhost:8787",
+      model: "claude-sonnet-4.5",
+      format: "kiro",
+      compressUserMessages: true,
+    });
+
+    expect(stats.tokens_saved).toBe(60);
+    expect(requestPayload).toEqual({
+      model: "claude-sonnet-4.5",
+      config: { compress_user_messages: true },
+      messages: [
+        { role: "user", content: "earlier user" },
+        {
+          role: "assistant",
+          content: "assistant response",
+          tool_calls: [
+            {
+              id: "tool_1",
+              type: "function",
+              function: { name: "read_file", arguments: "{\"path\":\"a.js\"}" },
+            },
+          ],
+        },
+        { role: "system", content: "native system instruction" },
+        { role: "user", content: "current user" },
+        { role: "tool", content: "long tool output", tool_call_id: "tool_1" },
+      ],
+    });
+    expect(body.conversationState.history[0].userInputMessage.content).toBe("compressed earlier user");
+    expect(body.conversationState.history[1].assistantResponseMessage.content).toBe("compressed assistant");
+    expect(body.conversationState.currentMessage.userInputMessage.systemInstruction).toBe("compressed system instruction");
+    expect(body.conversationState.currentMessage.userInputMessage.content).toBe("compressed current user");
+    expect(body.conversationState.currentMessage.userInputMessage.userInputMessageContext.toolResults[0].content[0].text)
+      .toBe("compressed tool output");
+    expect(body.profileArn).toBe("arn:test");
+    expect(body.conversationState.currentMessage.userInputMessage.userInputMessageContext.tools)
+      .toEqual([{ toolSpecification: { name: "read_file" } }]);
+  });
+
+  it("fails open when Kiro Headroom output does not preserve message order", async () => {
+    global.fetch = vi.fn(async () => new Response(JSON.stringify({
+      messages: [{ role: "assistant", content: "wrong role" }],
+      tokens_saved: 10,
+    }), { status: 200 }));
+    const body = {
+      conversationState: {
+        currentMessage: {
+          userInputMessage: {
+            content: "original",
+            modelId: "claude-sonnet-4.5",
+          },
+        },
+        history: [],
+      },
+    };
+    const original = structuredClone(body);
+    const diagnostics = {};
+
+    const stats = await compressWithHeadroom(body, {
+      enabled: true,
+      url: "http://localhost:8787",
+      model: "claude-sonnet-4.5",
+      format: "kiro",
+      diagnostics,
+    });
+
+    expect(stats).toBeNull();
+    expect(body).toEqual(original);
+    expect(diagnostics.reason).toBe("proxy response did not preserve Kiro message order");
+  });
+
+  it("fails open on bad response", async () => {
+    global.fetch = vi.fn(async () => new Response(JSON.stringify({ error: "bad" }), { status: 500 }));
+    const body = { messages: [{ role: "user", content: "long" }] };
+
+    const stats = await compressWithHeadroom(body, { enabled: true, url: "http://localhost:8787" });
+
+    expect(stats).toBeNull();
+    expect(body.messages[0].content).toBe("long");
+  });
+
+  it("skips unknown shapes", async () => {
+    global.fetch = vi.fn();
+    const body = { contents: [{ parts: [{ text: "long" }] }] };
+
+    const stats = await compressWithHeadroom(body, { enabled: true, url: "http://localhost:8787" });
+
+    expect(stats).toBeNull();
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+});
+
+describe("formatHeadroomLog", () => {
+  it("formats reported token deltas without implying provider billing savings", () => {
+    expect(formatHeadroomLog({ tokens_before: 100, tokens_after: 25, tokens_saved: 75 }))
+      .toBe("reported token delta=75 before=100 after=25 (75.0%)");
+  });
+});
diff --git a/tests/unit/hf-model-routing.test.js b/tests/unit/hf-model-routing.test.js
new file mode 100644
index 0000000..55d95ef
--- /dev/null
+++ b/tests/unit/hf-model-routing.test.js
@@ -0,0 +1,12 @@
+import { describe, it, expect } from "vitest";
+import { parseModel } from "../../open-sse/services/model.js";
+
+describe("HuggingFace model alias parsing", () => {
+  it("resolves hf alias to huggingface provider", () => {
+    expect(parseModel("hf/black-forest-labs/FLUX.1-schnell")).toMatchObject({
+      provider: "huggingface",
+      model: "black-forest-labs/FLUX.1-schnell",
+      providerAlias: "hf",
+    });
+  });
+});
diff --git a/tests/unit/image-fetch-hardening.test.js b/tests/unit/image-fetch-hardening.test.js
new file mode 100644
index 0000000..860982d
--- /dev/null
+++ b/tests/unit/image-fetch-hardening.test.js
@@ -0,0 +1,77 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// Mock DNS lookup so we control which host resolves to what IP.
+const lookupMock = vi.fn();
+vi.mock("node:dns/promises", () => ({ lookup: (...a) => lookupMock(...a) }));
+
+import { fetchImageAsBase64 } from "../../open-sse/translator/concerns/image.js";
+
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+function mockFetchOnce(bytes, ok = true) {
+  const body = {
+    getReader() {
+      let sent = false;
+      return {
+        read: async () => sent ? { done: true } : (sent = true, { done: false, value: new Uint8Array(bytes) }),
+        cancel: async () => {},
+      };
+    },
+  };
+  globalThis.fetch = vi.fn(async () => ({ ok, body }));
+}
+
+beforeEach(() => {
+  lookupMock.mockReset();
+  lookupMock.mockResolvedValue({ address: "93.184.216.34" }); // public by default
+});
+afterEach(() => { vi.restoreAllMocks(); });
+
+describe("fetchImageAsBase64 hardening", () => {
+  it("rejects non-http url", async () => {
+    expect(await fetchImageAsBase64("ftp://x/y.png")).toBeNull();
+    expect(await fetchImageAsBase64("data:image/png;base64,xx")).toBeNull();
+  });
+
+  it("SSRF: rejects private IP (10.x)", async () => {
+    lookupMock.mockResolvedValue({ address: "10.0.0.5" });
+    expect(await fetchImageAsBase64("http://internal.example/x.png")).toBeNull();
+  });
+
+  it("SSRF: rejects cloud metadata 169.254.169.254", async () => {
+    lookupMock.mockResolvedValue({ address: "169.254.169.254" });
+    expect(await fetchImageAsBase64("http://metadata/x.png")).toBeNull();
+  });
+
+  it("SSRF: rejects blocked hostname localhost", async () => {
+    expect(await fetchImageAsBase64("http://localhost/x.png")).toBeNull();
+  });
+
+  it("SSRF: rejects IPv6 loopback", async () => {
+    lookupMock.mockResolvedValue({ address: "::1" });
+    expect(await fetchImageAsBase64("http://x/y.png")).toBeNull();
+  });
+
+  it("accepts valid PNG from public host", async () => {
+    mockFetchOnce(PNG);
+    const r = await fetchImageAsBase64("https://example.com/a.png");
+    expect(r).not.toBeNull();
+    expect(r.mimeType).toBe("image/png");
+    expect(r.url.startsWith("data:image/png;base64,")).toBe(true);
+  });
+
+  it("rejects disguised non-image payload (magic byte mismatch)", async () => {
+    mockFetchOnce(Buffer.from("<?php system($_GET[c]); ?>"));
+    expect(await fetchImageAsBase64("https://example.com/evil.png")).toBeNull();
+  });
+
+  it("rejects payload over size cap", async () => {
+    mockFetchOnce(Buffer.alloc(1024));
+    expect(await fetchImageAsBase64("https://example.com/big.png", { maxBytes: 100 })).toBeNull();
+  });
+
+  it("returns null when fetch not ok", async () => {
+    mockFetchOnce(PNG, false);
+    expect(await fetchImageAsBase64("https://example.com/404.png")).toBeNull();
+  });
+});
diff --git a/tests/unit/image-generation.test.js b/tests/unit/image-generation.test.js
new file mode 100644
index 0000000..e5504ae
--- /dev/null
+++ b/tests/unit/image-generation.test.js
@@ -0,0 +1,546 @@
+/**
+ * Unit tests for image generation handler
+ *
+ * Covers:
+ *  - OpenAI-compatible format (openai, minimax, openrouter)
+ *  - Gemini format (generateContent API)
+ *  - Provider-specific formats (nanobanana, sdwebui)
+ *  - Response normalization to OpenAI format
+ *  - Error handling (missing prompt, invalid model)
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { handleImageGenerationCore } from "../../open-sse/handlers/imageGenerationCore.js";
+
+const originalFetch = global.fetch;
+
+describe("handleImageGenerationCore", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.useRealTimers();
+  });
+
+  it("validates required prompt field", async () => {
+    const result = await handleImageGenerationCore({
+      body: { model: "openai/dall-e-3" },
+      modelInfo: { provider: "openai", model: "dall-e-3" },
+      credentials: { apiKey: "test-key" },
+      log: null,
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(400);
+    expect(result.error).toContain("Missing required field: prompt");
+  });
+
+  it("rejects unsupported provider", async () => {
+    const result = await handleImageGenerationCore({
+      body: { prompt: "test" },
+      modelInfo: { provider: "unknown-provider", model: "test" },
+      credentials: null,
+      log: null,
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(400);
+    expect(result.error).toContain("does not support image generation");
+  });
+
+  it("generates image with OpenAI format", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          created: 1234567890,
+          data: [{ url: "https://example.com/image.png" }],
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "A cute cat", n: 1, size: "1024x1024" },
+      modelInfo: { provider: "openai", model: "dall-e-3" },
+      credentials: { apiKey: "test-key" },
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://api.openai.com/v1/images/generations",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          "Content-Type": "application/json",
+          Authorization: "Bearer test-key",
+        }),
+        body: expect.stringContaining('"prompt":"A cute cat"'),
+      })
+    );
+
+    const responseBody = await result.response.json();
+    expect(responseBody.data).toHaveLength(1);
+    expect(responseBody.data[0].url).toBe("https://example.com/image.png");
+  });
+
+  it("generates image with Gemini format", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          candidates: [
+            {
+              content: {
+                parts: [
+                  { text: "Generated image" },
+                  { inlineData: { data: "base64imagedata" } },
+                ],
+              },
+            },
+          ],
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "A sunset" },
+      modelInfo: { provider: "gemini", model: "gemini-image-preview" },
+      credentials: { apiKey: "test-key" },
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      expect.stringContaining("generativelanguage.googleapis.com"),
+      expect.objectContaining({
+        method: "POST",
+        body: expect.stringContaining('"responseModalities":["TEXT","IMAGE"]'),
+      })
+    );
+
+    const responseBody = await result.response.json();
+    expect(responseBody.data).toHaveLength(1);
+    expect(responseBody.data[0].b64_json).toBe("base64imagedata");
+  });
+
+  it("generates image with Minimax format", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          created: 1234567890,
+          data: [{ url: "https://example.com/minimax.png" }],
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "A mountain", size: "1024x1024" },
+      modelInfo: { provider: "minimax", model: "minimax-image-01" },
+      credentials: { apiKey: "test-key" },
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://api.minimaxi.com/v1/images/generations",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          Authorization: "Bearer test-key",
+        }),
+      })
+    );
+  });
+
+  it("generates image with NanoBanana format", async () => {
+    vi.useFakeTimers();
+    global.fetch
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({ code: 200, data: { taskId: "task-123" } }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        )
+      )
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            data: {
+              successFlag: 1,
+              response: { resultImageUrl: "https://example.com/nanobanana.png" },
+            },
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        )
+      );
+
+    const pending = handleImageGenerationCore({
+      body: { prompt: "A robot", n: 2, size: "1024x1792" },
+      modelInfo: { provider: "nanobanana", model: "nanobanana-flash" },
+      credentials: { apiKey: "test-key" },
+      log: null,
+    });
+
+    await vi.advanceTimersByTimeAsync(1500);
+    const result = await pending;
+
+    expect(result.success).toBe(true);
+    const fetchCall = global.fetch.mock.calls[0];
+    const requestBody = JSON.parse(fetchCall[1].body);
+    expect(requestBody.type).toBe("TEXTTOIAMGE");
+    expect(requestBody.numImages).toBe(2);
+    expect(requestBody.image_size).toBe("9:16");
+    expect(global.fetch).toHaveBeenNthCalledWith(
+      2,
+      "https://api.nanobananaapi.ai/api/v1/nanobanana/record-info?taskId=task-123",
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: "Bearer test-key",
+        }),
+      })
+    );
+
+    const responseBody = await result.response.json();
+    expect(responseBody.data[0].url).toBe("https://example.com/nanobanana.png");
+  });
+
+  it("generates image with SD WebUI format", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ images: ["base64sdwebui1", "base64sdwebui2"] }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "A forest", size: "768x768", n: 2 },
+      modelInfo: { provider: "sdwebui", model: "sdxl-base-1.0" },
+      credentials: null,
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+    const fetchCall = global.fetch.mock.calls[0];
+    const requestBody = JSON.parse(fetchCall[1].body);
+    expect(requestBody.width).toBe(768);
+    expect(requestBody.height).toBe(768);
+    expect(requestBody.batch_size).toBe(2);
+
+    const responseBody = await result.response.json();
+    expect(responseBody.data).toHaveLength(2);
+  });
+
+  it("handles OpenRouter with HTTP-Referer header", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          created: 1234567890,
+          data: [{ url: "https://example.com/or.png" }],
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "A city" },
+      modelInfo: { provider: "openrouter", model: "openai/dall-e-3" },
+      credentials: { apiKey: "test-key" },
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://openrouter.ai/api/v1/images/generations",
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          "HTTP-Referer": "https://endpoint-proxy.local",
+          "X-Title": "Endpoint Proxy",
+        }),
+      })
+    );
+  });
+
+  it("handles Vercel AI Gateway image generation as OpenAI-compatible", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          created: 1234567890,
+          data: [{ url: "https://example.com/vercel-image.png" }],
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "A watercolor castle", n: 1, size: "1024x1024" },
+      modelInfo: { provider: "vercel-ai-gateway", model: "openai/gpt-image-1" },
+      credentials: { apiKey: "vag-test-key" },
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://ai-gateway.vercel.sh/v1/images/generations",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          "Content-Type": "application/json",
+          Authorization: "Bearer vag-test-key",
+        }),
+        body: expect.stringContaining('"model":"openai/gpt-image-1"'),
+      })
+    );
+  });
+
+  it("handles HuggingFace binary response", async () => {
+    const imageBuffer = new Uint8Array([0x89, 0x50, 0x4e, 0x47]); // PNG header
+    global.fetch.mockResolvedValueOnce(
+      new Response(imageBuffer, {
+        status: 200,
+        headers: { "Content-Type": "image/png" },
+      })
+    );
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "A tree" },
+      modelInfo: { provider: "huggingface", model: "black-forest-labs/FLUX.1-schnell" },
+      credentials: { apiKey: "test-key" },
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+    const responseBody = await result.response.json();
+    expect(responseBody.data[0].b64_json).toBeTruthy();
+  });
+
+  it("generates image with Codex gpt-5.5-image using current Codex version header", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        [
+          "event: response.output_item.done",
+          'data: {"item":{"type":"image_generation_call","result":"base64codeximage"}}',
+          "",
+          "",
+        ].join("\n"),
+        { status: 200, headers: { "Content-Type": "text/event-stream" } }
+      )
+    );
+
+    const result = await handleImageGenerationCore({
+      body: {
+        prompt: "A green square",
+        size: "1024x1024",
+        output_format: "png",
+      },
+      modelInfo: { provider: "codex", model: "gpt-5.5-image" },
+      credentials: {
+        accessToken: "codex-token",
+        providerSpecificData: { chatgptAccountId: "account-123" },
+      },
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://chatgpt.com/backend-api/codex/responses",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          authorization: "Bearer codex-token",
+          "chatgpt-account-id": "account-123",
+          version: "0.136.0",
+        }),
+      })
+    );
+
+    const fetchCall = global.fetch.mock.calls[0];
+    const requestBody = JSON.parse(fetchCall[1].body);
+    expect(requestBody.model).toBe("gpt-5.5");
+    expect(requestBody.tools).toEqual([
+      { type: "image_generation", output_format: "png", size: "1024x1024" },
+    ]);
+
+    const responseBody = await result.response.json();
+    expect(responseBody.data[0].b64_json).toBe("base64codeximage");
+  });
+
+  it("generates image with Cloudflare Workers AI JSON response", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          result: { image: "base64cloudflare" },
+          success: true,
+          errors: [],
+          messages: [],
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "A lighthouse", size: "1024x1536" },
+      modelInfo: { provider: "cloudflare-ai", model: "@cf/leonardo/lucid-origin" },
+      credentials: {
+        apiKey: "cf-token",
+        providerSpecificData: { accountId: "cf-account" },
+      },
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://api.cloudflare.com/client/v4/accounts/cf-account/ai/run/@cf/leonardo/lucid-origin",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          "Content-Type": "application/json",
+          Authorization: "Bearer cf-token",
+        }),
+      })
+    );
+
+    const fetchCall = global.fetch.mock.calls[0];
+    const requestBody = JSON.parse(fetchCall[1].body);
+    expect(requestBody.prompt).toBe("A lighthouse");
+    expect(requestBody.width).toBe(1024);
+    expect(requestBody.height).toBe(1536);
+
+    const responseBody = await result.response.json();
+    expect(responseBody.data[0].b64_json).toBe("base64cloudflare");
+  });
+
+  it("uses multipart form data for Cloudflare FLUX.2 models", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          result: { image: "base64flux2" },
+          success: true,
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "A mountain lake", size: "1792x1024", steps: 4 },
+      modelInfo: { provider: "cloudflare-ai", model: "@cf/black-forest-labs/flux-2-klein-9b" },
+      credentials: {
+        apiKey: "cf-token",
+        providerSpecificData: { accountId: "cf-account" },
+      },
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+
+    const fetchCall = global.fetch.mock.calls[0];
+    expect(fetchCall[1].headers).not.toHaveProperty("Content-Type");
+    expect(fetchCall[1].body).toBeInstanceOf(FormData);
+    expect(fetchCall[1].body.get("prompt")).toBe("A mountain lake");
+    expect(fetchCall[1].body.get("width")).toBe("1792");
+    expect(fetchCall[1].body.get("height")).toBe("1024");
+    expect(fetchCall[1].body.get("steps")).toBe("4");
+  });
+
+  it("resolves Cloudflare img2img and inpainting URL inputs before sending", async () => {
+    global.fetch
+      .mockResolvedValueOnce(new Response(new Uint8Array([1, 2, 3]), { status: 200, headers: { "Content-Type": "image/png" } }))
+      .mockResolvedValueOnce(new Response(new Uint8Array([4, 5, 6]), { status: 200, headers: { "Content-Type": "image/png" } }))
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({ result: { image: "base64inpaint" }, success: true }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        )
+      );
+
+    const result = await handleImageGenerationCore({
+      body: {
+        prompt: "Change to a lion",
+        image: "https://example.com/source.png",
+        mask_image: "https://example.com/mask.png",
+        size: "512x512",
+      },
+      modelInfo: { provider: "cloudflare-ai", model: "@cf/runwayml/stable-diffusion-v1-5-inpainting" },
+      credentials: {
+        apiKey: "cf-token",
+        providerSpecificData: { accountId: "cf-account" },
+      },
+      log: null,
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch).toHaveBeenNthCalledWith(1, "https://example.com/source.png");
+    expect(global.fetch).toHaveBeenNthCalledWith(2, "https://example.com/mask.png");
+
+    const providerCall = global.fetch.mock.calls[2];
+    expect(providerCall[0]).toBe("https://api.cloudflare.com/client/v4/accounts/cf-account/ai/run/@cf/runwayml/stable-diffusion-v1-5-inpainting");
+    const requestBody = JSON.parse(providerCall[1].body);
+    expect(requestBody.image).toEqual([1, 2, 3]);
+    expect(requestBody.image_b64).toBe(Buffer.from([1, 2, 3]).toString("base64"));
+    expect(requestBody.mask).toEqual([4, 5, 6]);
+    expect(requestBody.mask_image).toEqual([4, 5, 6]);
+    expect(requestBody.mask_b64).toBe(Buffer.from([4, 5, 6]).toString("base64"));
+  });
+
+  it("handles provider error responses", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ error: { message: "Rate limit exceeded" } }),
+        { status: 429, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "test" },
+      modelInfo: { provider: "openai", model: "dall-e-3" },
+      credentials: { apiKey: "test-key" },
+      log: null,
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(429);
+    expect(result.error).toContain("Rate limit exceeded");
+  });
+
+  it("handles network errors", async () => {
+    global.fetch.mockRejectedValueOnce(new Error("Network timeout"));
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "test" },
+      modelInfo: { provider: "openai", model: "dall-e-3" },
+      credentials: { apiKey: "test-key" },
+      log: null,
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(502);
+    expect(result.error).toContain("Network timeout");
+  });
+
+  it("calls onRequestSuccess callback on success", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          created: 1234567890,
+          data: [{ url: "https://example.com/success.png" }],
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const onRequestSuccess = vi.fn();
+
+    const result = await handleImageGenerationCore({
+      body: { prompt: "test" },
+      modelInfo: { provider: "openai", model: "dall-e-3" },
+      credentials: { apiKey: "test-key" },
+      log: null,
+      onRequestSuccess,
+    });
+
+    expect(result.success).toBe(true);
+    expect(onRequestSuccess).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/tests/unit/kimchi-strip-reasoning.test.js b/tests/unit/kimchi-strip-reasoning.test.js
new file mode 100644
index 0000000..0cb55df
--- /dev/null
+++ b/tests/unit/kimchi-strip-reasoning.test.js
@@ -0,0 +1,128 @@
+/**
+ * Kimchi executor: strip reasoning_content echoed by clients.
+ *
+ * Background: when 9Router streams a thinking model (deepseek-r1,
+ * minimax-m3) to a client, the response carries `reasoning_content`.
+ * Most OpenAI-compatible SDKs echo the whole history on the next turn,
+ * so Kimchi's upstream counts the scratch block as input tokens.
+ * Multi-turn conversations balloon to 100k+ input tokens and the model
+ * starts returning empty content.
+ *
+ * `stripReasoningContent` is intentionally conservative: it only strips
+ * `reasoning_content` that is clearly a real thinking block. The 1-char
+ * placeholder that `injectReasoningContent` (in `DefaultExecutor`) may
+ * insert for upstream validation is preserved — stripping it would
+ * re-trigger upstream complaints about missing reasoning on the next
+ * turn.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import KimchiExecutor, { stripReasoningContent } from "../../open-sse/executors/kimchi.js";
+import DefaultExecutor from "../../open-sse/executors/default.js";
+
+describe("kimchi stripReasoningContent", () => {
+  it("removes long reasoning_content from assistant messages but keeps content", () => {
+    const body = {
+      messages: [
+        { role: "user", content: "solve x+5=12" },
+        {
+          role: "assistant",
+          content: "x = 7",
+          reasoning_content: "subtract 5 from both sides ... (long reasoning block)",
+        },
+        { role: "user", content: "now try x+10=20" },
+      ],
+    };
+    stripReasoningContent(body);
+    assert.equal(body.messages[1].reasoning_content, undefined);
+    assert.equal(body.messages[1].content, "x = 7");
+  });
+
+  it("preserves the 1-char placeholder that injectReasoningContent sets", () => {
+    // `injectReasoningContent` may insert " " (single space) on assistant
+    // messages so the upstream's validation doesn't complain about missing
+    // reasoning. Stripping that placeholder would defeat its purpose.
+    const body = {
+      messages: [
+        { role: "user", content: "hi" },
+        { role: "assistant", content: "hello", reasoning_content: " " },
+      ],
+    };
+    stripReasoningContent(body);
+    assert.equal(body.messages[1].reasoning_content, " ");
+    assert.equal(body.messages[1].content, "hello");
+  });
+
+  it("preserves short custom reasoning under the threshold", () => {
+    // Anything ≤8 chars is treated as a placeholder-shaped value, kept
+    // verbatim. Real thinking content from a thinking model is always
+    // well above this threshold.
+    const body = {
+      messages: [
+        { role: "assistant", content: "ok", reasoning_content: "short" },
+      ],
+    };
+    stripReasoningContent(body);
+    assert.equal(body.messages[0].reasoning_content, "short");
+  });
+
+  it("leaves non-assistant messages untouched", () => {
+    const body = {
+      messages: [
+        { role: "user", content: "hi" },
+        { role: "system", content: "be helpful" },
+      ],
+    };
+    stripReasoningContent(body);
+    assert.equal(body.messages[0].content, "hi");
+    assert.equal(body.messages[1].content, "be helpful");
+  });
+
+  it("returns early on missing/empty messages array", () => {
+    assert.doesNotThrow(() => stripReasoningContent({}));
+    assert.doesNotThrow(() => stripReasoningContent({ messages: null }));
+    assert.doesNotThrow(() => stripReasoningContent({ messages: [] }));
+  });
+
+  it("ignores assistant messages that have no reasoning_content", () => {
+    const body = {
+      messages: [
+        { role: "user", content: "hi" },
+        { role: "assistant", content: "hello" },
+      ],
+    };
+    stripReasoningContent(body);
+    assert.deepEqual(body.messages[1], { role: "assistant", content: "hello" });
+  });
+
+  it("handles multi-turn: strips old turns, keeps recent one", () => {
+    const LONG = "x".repeat(1000);
+    const body = {
+      messages: [
+        { role: "user", content: "q1" },
+        { role: "assistant", content: "a1", reasoning_content: LONG },
+        { role: "user", content: "q2" },
+        { role: "assistant", content: "a2", reasoning_content: " " }, // placeholder
+      ],
+    };
+    stripReasoningContent(body);
+    assert.equal(body.messages[1].reasoning_content, undefined);
+    assert.equal(body.messages[3].reasoning_content, " ");
+  });
+});
+
+describe("kimchi executor wiring", () => {
+  it("KimchiExecutor extends DefaultExecutor via prototype chain", () => {
+    const inst = new KimchiExecutor();
+    assert.ok(
+      inst instanceof DefaultExecutor,
+      "KimchiExecutor must extend DefaultExecutor so transformRequest runs through super",
+    );
+  });
+
+  it("default export is KimchiExecutor class", () => {
+    assert.equal(typeof KimchiExecutor, "function");
+    assert.equal(KimchiExecutor.name, "KimchiExecutor");
+  });
+});
diff --git a/tests/unit/kimchi.test.js b/tests/unit/kimchi.test.js
new file mode 100644
index 0000000..1f300f8
--- /dev/null
+++ b/tests/unit/kimchi.test.js
@@ -0,0 +1,234 @@
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+
+// Load the registry entry once for the suite so a load failure is reported
+// next to the failing test instead of cascading as "undefined" in every
+// later assertion.
+let kimchiEntry;
+
+describe("kimchi registry entry", () => {
+  before(async () => {
+    kimchiEntry = (await import("../../open-sse/providers/registry/kimchi.js")).default;
+  });
+
+  it("is an oauth provider auto-listed via byCategory", () => {
+    assert.equal(kimchiEntry.id, "kimchi");
+    assert.equal(kimchiEntry.category, "oauth");
+  });
+
+  it("points at the OpenAI-compatible gateway with an authenticated UA", () => {
+    assert.equal(
+      kimchiEntry.transport.baseUrl,
+      "https://llm.kimchi.dev/openai/v1/chat/completions",
+    );
+    // UA must be a non-empty string the gateway can identify; the value
+    // itself is owned by the Kimchi CLI release and may change upstream.
+    const ua = kimchiEntry.transport.headers["User-Agent"];
+    assert.ok(typeof ua === "string" && ua.length > 0, `User-Agent missing: ${ua}`);
+  });
+
+  it("uses Bearer auth", () => {
+    assert.deepEqual(kimchiEntry.transport.auth, {
+      combined: true,
+      header: "Authorization",
+      scheme: "bearer",
+    });
+  });
+
+  it("exposes the upstream static models", () => {
+    const ids = kimchiEntry.models.map((m) => m.id);
+    assert.ok(ids.includes("kimi-k2.7"));
+    assert.ok(ids.includes("minimax-m3"));
+    assert.ok(ids.includes("nemotron-3-ultra-fp4"));
+    assert.ok(ids.length >= 5, `expected >= 5 static models, got ${ids.length}`);
+  });
+
+  it("passes through models not in the static list", () => {
+    assert.equal(kimchiEntry.passthroughModels, true);
+  });
+});
+
+// ── Pure-function clones of the service logic (tested in isolation so
+//     node --test works without resolving the Next.js Webpack "open-sse"
+//     alias that src/lib/oauth/services/kimchi.js's dependency imports). ──
+
+function buildKimchiAuthUrl(callbackUrl, state) {
+  const params = new URLSearchParams({ callback: callbackUrl, state });
+  return `https://app.kimchi.dev/cli-auth?${params.toString()}`;
+}
+
+async function _handleCallback(params, expectedState) {
+  if (params.error) {
+    throw new Error(params.error_description || params.error);
+  }
+  const candidate = params.state;
+  if (!candidate || candidate !== expectedState) {
+    throw new Error(
+      "This request isn't valid. Please restart the Kimchi login flow.",
+    );
+  }
+  const token = params.token;
+  if (!token) {
+    throw new Error("No token was returned by the Kimchi authentication server");
+  }
+  return { token };
+}
+
+describe("kimchi oauth", () => {
+  it("builds the cli-auth URL with encoded callback + state", () => {
+    const url = buildKimchiAuthUrl("http://127.0.0.1:4321/callback", "abc123");
+    const parsed = new URL(url);
+    assert.equal(parsed.origin, "https://app.kimchi.dev");
+    assert.equal(parsed.pathname, "/cli-auth");
+    assert.equal(parsed.searchParams.get("callback"), "http://127.0.0.1:4321/callback");
+    assert.equal(parsed.searchParams.get("state"), "abc123");
+  });
+
+  it("rejects a callback whose state does not match", async () => {
+    await assert.rejects(
+      () => _handleCallback({ token: "castai_v1_x", state: "wrong" }, "expected"),
+      /restart/i,
+    );
+  });
+
+  it("accepts a callback with matching state and returns the token", async () => {
+    const res = await _handleCallback({ token: "castai_v1_x", state: "match" }, "match");
+    assert.equal(res.token, "castai_v1_x");
+  });
+});
+
+// ── kimchiModels service (pure mapping logic, tested in isolation) ──
+
+// Clone of the metadata→model mapper so node --test resolves without the
+// open-sse/Webpack alias chain the real module imports.
+function mapKimchiMetadata(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.map((m) => ({
+    id: m.slug,
+    name: m.display_name || m.slug,
+    contextLength: m.limits?.context_window || null,
+    maxOutputTokens: m.limits?.max_output_tokens || null,
+    isReasoning: m.reasoning === true,
+  }));
+}
+
+describe("kimchiModels", () => {
+  it("maps Kimchi metadata entries to 9router model shape", () => {
+    const raw = [{
+      slug: "glm-5.2-fp8",
+      display_name: "GLM 5.2",
+      reasoning: true,
+      limits: { context_window: 1048576, max_output_tokens: 1048576 },
+    }];
+    const models = mapKimchiMetadata(raw);
+    assert.equal(models.length, 1);
+    assert.deepEqual(models[0], {
+      id: "glm-5.2-fp8",
+      name: "GLM 5.2",
+      contextLength: 1048576,
+      maxOutputTokens: 1048576,
+      isReasoning: true,
+    });
+  });
+
+  it("falls back to slug as name when display_name is empty", () => {
+    const models = mapKimchiMetadata([{ slug: "kimi-k2.7", display_name: "", reasoning: false, limits: {} }]);
+    assert.equal(models[0].name, "kimi-k2.7");
+    assert.equal(models[0].contextLength, null);
+    assert.equal(models[0].isReasoning, false);
+  });
+
+  it("returns empty array for non-array input", () => {
+    assert.deepEqual(mapKimchiMetadata(null), []);
+    assert.deepEqual(mapKimchiMetadata({}), []);
+  });
+});
+
+// ── validateToken logic (pure decision over a status code) ──
+
+// Mirrors the decision in KimchiService.validateToken without importing the
+// service (which pulls the open-sse Webpack alias chain).
+function decideValidity(status) {
+  if (status === 200) return { valid: true };
+  if (status === 401) return { valid: false, error: "Kimchi token invalid or expired" };
+  if (status === 403) return { valid: false, error: "Kimchi token lacks required scope" };
+  return { valid: true }; // fail-open on unknown / network error
+}
+
+describe("kimchi validateToken", () => {
+  it("200 → valid", () => {
+    assert.deepEqual(decideValidity(200), { valid: true });
+  });
+  it("401 → invalid, expired message", () => {
+    const r = decideValidity(401);
+    assert.equal(r.valid, false);
+    assert.match(r.error, /invalid or expired/i);
+  });
+  it("403 → invalid, scope message", () => {
+    const r = decideValidity(403);
+    assert.equal(r.valid, false);
+    assert.match(r.error, /scope/i);
+  });
+  it("unknown / network error → fail-open valid", () => {
+    assert.equal(decideValidity(500).valid, true);
+    assert.equal(decideValidity(0).valid, true);
+  });
+});
+
+// ── OAuth dedup logic (pure clone of connectionsRepo matcher) ──
+// Mimics the find() predicate in createProviderConnection for OAuth
+// connections, so we can test the IdP-collision fix in isolation.
+function findExistingOAuth(all, incoming) {
+  const incomingEmail = incoming.email;
+  const incomingUsername = incoming.providerSpecificData?.username;
+  const incomingWs = incoming.providerSpecificData?.chatgptAccountId;
+  return all.find((c) => {
+    if (c.authType !== "oauth" || c.email !== incomingEmail) return false;
+    const existingWs = c.providerSpecificData?.chatgptAccountId;
+    if (incomingWs && existingWs) return incomingWs === existingWs;
+    if (incomingWs && !existingWs) return false;
+    if (!incomingWs && existingWs) return false;
+    const existingUsername = c.providerSpecificData?.username;
+    if (incomingUsername && existingUsername) {
+      return incomingUsername === existingUsername;
+    }
+    if (incomingUsername || existingUsername) return false;
+    return true;
+  });
+}
+
+describe("kimchi OAuth dedup", () => {
+  const google = { authType: "oauth", email: "x@y.com", providerSpecificData: { username: "google-oauth2|123" } };
+  const hf = { authType: "oauth", email: "x@y.com", providerSpecificData: { username: "huggingface|456" } };
+  const legacy = { authType: "oauth", email: "x@y.com", providerSpecificData: {} };
+  const other = { authType: "oauth", email: "z@y.com", providerSpecificData: { username: "google-oauth2|789" } };
+
+  it("different email never matches", () => {
+    assert.equal(findExistingOAuth([other], google), undefined);
+  });
+
+  it("same email + same username = dedup (re-login same IdP)", () => {
+    const found = findExistingOAuth([google], { ...google });
+    assert.equal(found, google);
+  });
+
+  it("same email + different username = NO match (cross-IdP, the bug)", () => {
+    assert.equal(findExistingOAuth([google], hf), undefined);
+  });
+
+  it("legacy row without username matches incoming without username (backward compat)", () => {
+    assert.equal(findExistingOAuth([legacy], { ...legacy }), legacy);
+  });
+
+  it("incoming without username does not match legacy row with username", () => {
+    assert.equal(findExistingOAuth([google], { ...legacy }), undefined);
+  });
+
+  it("workspaces still dedupe on workspace ID when both sides have one", () => {
+    const ws1 = { authType: "oauth", email: "a@b.com", providerSpecificData: { chatgptAccountId: "ws1" } };
+    const ws1dup = { authType: "oauth", email: "a@b.com", providerSpecificData: { chatgptAccountId: "ws1" } };
+    const ws2 = { authType: "oauth", email: "a@b.com", providerSpecificData: { chatgptAccountId: "ws2" } };
+    assert.equal(findExistingOAuth([ws1], ws1dup), ws1);
+    assert.equal(findExistingOAuth([ws1], ws2), undefined);
+  });
+});
diff --git a/tests/unit/kiro-external-idp.test.js b/tests/unit/kiro-external-idp.test.js
new file mode 100644
index 0000000..c531d02
--- /dev/null
+++ b/tests/unit/kiro-external-idp.test.js
@@ -0,0 +1,207 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+const originalFetch = global.fetch;
+const TEST_CLIENT_ID = "00000000-0000-4000-8000-000000000000";
+const TEST_SCOPE = `api://${TEST_CLIENT_ID}/codewhisperer:conversations offline_access`;
+const TEST_EMAIL = "user@example.com";
+
+function makeJwt(payload) {
+  const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  return `header.${encoded}.signature`;
+}
+
+describe("Kiro external_idp (CLIProxyAPI) import and refresh", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+    global.fetch = originalFetch;
+  });
+
+  afterEach(() => {
+    vi.doUnmock("next/server");
+    vi.doUnmock("@/models");
+    vi.doUnmock("../../open-sse/utils/proxyFetch.js");
+    global.fetch = originalFetch;
+  });
+
+  it("refreshes Microsoft external_idp tokens with form-encoded OAuth body", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        access_token: "new-access-token",
+        refresh_token: "rotated-refresh-token",
+        expires_in: 3600,
+      }),
+    });
+    global.fetch = fetchMock;
+
+    const { refreshKiroToken } = await import("../../open-sse/services/tokenRefresh.js");
+    const result = await refreshKiroToken("old-refresh-token", {
+      authMethod: "external_idp",
+      clientId: TEST_CLIENT_ID,
+      tokenEndpoint: "https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token",
+      scope: TEST_SCOPE,
+      profileArn: "arn:aws:codewhisperer:us-east-1:123456789012:profile/ABC",
+      region: "us-east-1",
+    });
+
+    expect(result).toMatchObject({
+      accessToken: "new-access-token",
+      refreshToken: "rotated-refresh-token",
+      expiresIn: 3600,
+      providerSpecificData: {
+        profileArn: "arn:aws:codewhisperer:us-east-1:123456789012:profile/ABC",
+        authMethod: "external_idp",
+        clientId: TEST_CLIENT_ID,
+        tokenEndpoint: "https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token",
+        scope: TEST_SCOPE,
+        region: "us-east-1",
+      },
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token");
+    expect(init.method).toBe("POST");
+    expect(init.headers).toMatchObject({
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    });
+    expect(init.body).toBeInstanceOf(URLSearchParams);
+    expect(Object.fromEntries(init.body.entries())).toEqual({
+      grant_type: "refresh_token",
+      client_id: TEST_CLIENT_ID,
+      refresh_token: "old-refresh-token",
+      scope: TEST_SCOPE,
+    });
+  });
+
+  it("rejects external_idp refresh endpoints outside Microsoft login", async () => {
+    const { refreshKiroToken } = await import("../../open-sse/services/tokenRefresh.js");
+    const fetchMock = vi.fn();
+    global.fetch = fetchMock;
+
+    const result = await refreshKiroToken("old-refresh-token", {
+      authMethod: "external_idp",
+      clientId: "client-id",
+      tokenEndpoint: "https://evil.example.com/token",
+      scope: "offline_access",
+    });
+
+    expect(result).toBeNull();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("adds CodeWhisperer external IdP headers and endpoint ordering", async () => {
+    const { KiroExecutor } = await import("../../open-sse/executors/kiro.js");
+    const executor = new KiroExecutor();
+    const credentials = {
+      accessToken: "microsoft-access-token",
+      providerSpecificData: { authMethod: "external_idp" },
+    };
+
+    const headers = executor.buildHeaders(credentials, true);
+    expect(headers.Authorization).toBe("Bearer microsoft-access-token");
+    expect(headers.TokenType).toBe("EXTERNAL_IDP");
+    expect(headers.tokentype).toBeUndefined();
+
+    expect(executor.buildUrl("claude-sonnet-4.5", true, 0, credentials)).toBe(
+      "https://codewhisperer.us-east-1.amazonaws.com/generateAssistantResponse"
+    );
+  });
+
+  it("sends TokenType for external_idp Kiro usage probes", async () => {
+    const calls = [];
+    vi.doMock("../../open-sse/utils/proxyFetch.js", () => ({
+      proxyAwareFetch: vi.fn(async (url, init) => {
+        calls.push({ url, init });
+        return {
+          ok: true,
+          json: async () => ({
+            subscriptionInfo: { subscriptionTitle: "Kiro Enterprise" },
+            usageBreakdownList: [],
+          }),
+        };
+      }),
+    }));
+
+    const { getKiroUsage } = await import("../../open-sse/services/usage/kiro.js");
+    const result = await getKiroUsage("microsoft-access-token", {
+      authMethod: "external_idp",
+      profileArn: "arn:aws:codewhisperer:us-east-1:123456789012:profile/ABC",
+    });
+
+    expect(result.plan).toBe("Kiro Enterprise");
+    expect(calls).toHaveLength(1);
+    expect(calls[0].init.headers.Authorization).toBe("Bearer microsoft-access-token");
+    expect(calls[0].init.headers.TokenType).toBe("EXTERNAL_IDP");
+    expect(calls[0].init.headers.tokentype).toBeUndefined();
+  });
+
+  it("imports CLIProxyAPI external_idp JSON as a Kiro OAuth connection", async () => {
+    const createdConnections = [];
+    vi.doMock("next/server", () => ({
+      NextResponse: {
+        json(body, init = {}) {
+          return new Response(JSON.stringify(body), {
+            status: init.status || 200,
+            headers: { "Content-Type": "application/json" },
+          });
+        },
+      },
+    }));
+    vi.doMock("@/models", () => ({
+      createProviderConnection: vi.fn(async (data) => {
+        const connection = { id: "conn-1", ...data };
+        createdConnections.push(connection);
+        return connection;
+      }),
+    }));
+
+    const { POST } = await import("../../src/app/api/oauth/kiro/import-cli-proxy/route.js");
+    const accessToken = makeJwt({
+      preferred_username: TEST_EMAIL,
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    });
+    const cliProxyAuth = {
+      type: "kiro",
+      auth_method: "external_idp",
+      access_token: accessToken,
+      refresh_token: "1.AcY-refresh-token",
+      client_id: TEST_CLIENT_ID,
+      token_endpoint: "https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token",
+      profile_arn: "arn:aws:codewhisperer:us-east-1:123456789012:profile/ABC",
+      region: "us-east-1",
+      scopes: TEST_SCOPE,
+      expired: new Date(Date.now() + 3600_000).toISOString(),
+    };
+
+    const response = await POST(new Request("https://9router.local/api/oauth/kiro/import-cli-proxy", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ cliProxyAuth }),
+    }));
+    const body = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(body.success).toBe(true);
+    expect(createdConnections).toHaveLength(1);
+    expect(createdConnections[0]).toMatchObject({
+      provider: "kiro",
+      authType: "oauth",
+      accessToken,
+      refreshToken: "1.AcY-refresh-token",
+      email: TEST_EMAIL,
+      providerSpecificData: {
+        authMethod: "external_idp",
+        provider: "CLIProxyAPI",
+        profileArn: "arn:aws:codewhisperer:us-east-1:123456789012:profile/ABC",
+        region: "us-east-1",
+        clientId: TEST_CLIENT_ID,
+        tokenEndpoint: "https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token",
+        scope: TEST_SCOPE,
+      },
+      testStatus: "active",
+    });
+  });
+});
diff --git a/tests/unit/kiro-model-slots.test.js b/tests/unit/kiro-model-slots.test.js
new file mode 100644
index 0000000..ffc3e38
--- /dev/null
+++ b/tests/unit/kiro-model-slots.test.js
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { PROVIDER_MODELS } from "../../open-sse/config/providerModels.js";
+import { MITM_TOOLS } from "../../src/shared/constants/cliTools.js";
+
+// Guards Kiro model ids that still need mappable defaultModels slots. Without
+// a slot, getMappedModel (src/mitm/server.js) returns null and the request is
+// passed through to AWS instead of being routed to the user's chosen provider.
+describe("Kiro MITM model slots", () => {
+  const kiro = MITM_TOOLS.kiro;
+
+  it("exposes the kiro mitm tool", () => {
+    expect(kiro).toBeTruthy();
+    expect(kiro.configType).toBe("mitm");
+    expect(Array.isArray(kiro.defaultModels)).toBe(true);
+  });
+
+  it("offers a mappable slot for Claude Sonnet 5", () => {
+    const sonnet5 = kiro.defaultModels.find((m) => m.id === "claude-sonnet-5");
+    expect(sonnet5).toBeTruthy();
+    expect(sonnet5.alias).toBe("claude-sonnet-5");
+  });
+
+  it("offers a mappable slot for the background sub-task model id 'simple-task'", () => {
+    const simpleTask = kiro.defaultModels.find((m) => m.id === "simple-task");
+    expect(simpleTask).toBeTruthy();
+    expect(simpleTask.alias).toBe("simple-task");
+  });
+});
+
+describe("Kiro static provider models", () => {
+  it("includes Claude Sonnet 5 and its synthetic Kiro variants", () => {
+    const ids = (PROVIDER_MODELS.kr || []).map((model) => model.id);
+    expect(ids).toEqual(expect.arrayContaining([
+      "claude-sonnet-5",
+      "claude-sonnet-5-thinking",
+      "claude-sonnet-5-agentic",
+      "claude-sonnet-5-thinking-agentic",
+    ]));
+  });
+});
diff --git a/tests/unit/kiro-profile-arn.test.js b/tests/unit/kiro-profile-arn.test.js
new file mode 100644
index 0000000..1925582
--- /dev/null
+++ b/tests/unit/kiro-profile-arn.test.js
@@ -0,0 +1,63 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { KiroService } from "../../src/lib/oauth/services/kiro.js";
+
+/**
+ * Regression tests for Kiro API-key auth.
+ *
+ * KiroService.validateApiKey resolves a profileArn with the key (via
+ * CodeWhisperer ListAvailableProfiles) and returns a credential shaped for
+ * persistence with authMethod="api_key". The response profile field name
+ * varies (`arn` vs `profileArn`) — both are accepted by listAvailableProfiles.
+ *
+ * Note: OAuth (Builder ID / IDC) profileArn resolution is handled upstream by
+ * fetchKiroProfileArn in providers.js and is covered there — not here.
+ */
+describe("kiro API-key auth (KiroService.validateApiKey)", () => {
+  beforeEach(() => vi.restoreAllMocks());
+  afterEach(() => vi.restoreAllMocks());
+
+  it("validates an API key and resolves a credential with profileArn", async () => {
+    const expectedArn = "arn:aws:codewhisperer:us-east-1:444:profile/KEY";
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ profiles: [{ arn: expectedArn }] }),
+    });
+
+    const svc = new KiroService();
+    const cred = await svc.validateApiKey("  my-secret-key  ");
+
+    expect(cred).toEqual({
+      accessToken: "my-secret-key",
+      refreshToken: null,
+      profileArn: expectedArn,
+      region: "us-east-1",
+      authMethod: "api_key",
+    });
+
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://codewhisperer.us-east-1.amazonaws.com");
+    expect(init.headers.Authorization).toBe("Bearer my-secret-key");
+    expect(init.headers["x-amz-target"]).toBe(
+      "AmazonCodeWhispererService.ListAvailableProfiles"
+    );
+  });
+
+  it("rejects an empty API key without a network call", async () => {
+    const fetchMock = vi.spyOn(globalThis, "fetch");
+    const svc = new KiroService();
+    await expect(svc.validateApiKey("   ")).rejects.toThrow("API key is required");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a validation error when the key is rejected", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: false,
+      status: 401,
+      text: async () => "Unauthorized",
+    });
+    const svc = new KiroService();
+    await expect(svc.validateApiKey("bad-key")).rejects.toThrow(
+      /API key validation failed/
+    );
+  });
+});
diff --git a/tests/unit/kiro-thinking-strip.test.js b/tests/unit/kiro-thinking-strip.test.js
new file mode 100644
index 0000000..91b5009
--- /dev/null
+++ b/tests/unit/kiro-thinking-strip.test.js
@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import { KiroExecutor } from "../../open-sse/executors/kiro.js";
+
+function createMockFrame(eventType, payloadObj) {
+  const payloadStr = JSON.stringify(payloadObj);
+  const payloadBytes = new TextEncoder().encode(payloadStr);
+
+  const headerName = ":event-type";
+  const headerNameBytes = new TextEncoder().encode(headerName);
+  const headerValueBytes = new TextEncoder().encode(eventType);
+
+  // nameLen(1) + name + type(1) + valueLen(2) + value
+  const headerLength = 1 + headerNameBytes.length + 1 + 2 + headerValueBytes.length;
+  const totalLength = 12 + headerLength + payloadBytes.length + 4;
+
+  const buffer = new Uint8Array(totalLength);
+  const view = new DataView(buffer.buffer);
+
+  view.setUint32(0, totalLength, false);
+  view.setUint32(4, headerLength, false);
+
+  let offset = 12;
+  buffer[offset++] = headerNameBytes.length;
+  buffer.set(headerNameBytes, offset);
+  offset += headerNameBytes.length;
+
+  buffer[offset++] = 7; // String type
+  view.setUint16(offset, headerValueBytes.length, false);
+  offset += 2;
+  buffer.set(headerValueBytes, offset);
+  offset += headerValueBytes.length;
+
+  buffer.set(payloadBytes, offset);
+  
+  return buffer;
+}
+
+async function readAllSSE(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let result = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    result += decoder.decode(value, { stream: true });
+  }
+  return result;
+}
+
+describe("KiroExecutor thinking tag stripping", () => {
+  it("strips <thinking> tags from assistantResponseEvent", async () => {
+    const executor = new KiroExecutor();
+    
+    // Create frames
+    const f1 = createMockFrame("assistantResponseEvent", { content: "Here is my answer. <thinking>Let me think..." });
+    const f2 = createMockFrame("assistantResponseEvent", { content: "still thinking...</thinking> Yes, 42." });
+    
+    const readableStream = new ReadableStream({
+      start(controller) {
+        controller.enqueue(f1);
+        controller.enqueue(f2);
+        controller.close();
+      }
+    });
+
+    const mockResponse = { body: readableStream };
+    const transformedResponse = executor.transformEventStreamToSSE(mockResponse, "claude-test");
+    
+    const output = await readAllSSE(transformedResponse.body);
+    
+    // Check that we got chat.completion.chunk outputs
+    expect(output).toContain("chat.completion.chunk");
+    // Ensure the thinking parts are gone
+    expect(output).not.toContain("<thinking>");
+    expect(output).not.toContain("Let me think...");
+    expect(output).not.toContain("still thinking...");
+    expect(output).not.toContain("</thinking>");
+    
+    // Check that the normal content is preserved
+    // Parse the data chunks
+    const dataLines = output.split("\n").filter(line => line.startsWith("data: "));
+    const contents = dataLines.map(line => {
+      if (line.includes("[DONE]")) return "";
+      try {
+        return JSON.parse(line.slice(6)).choices[0].delta.content || "";
+      } catch {
+        return "";
+      }
+    });
+    
+    const fullText = contents.join("");
+    expect(fullText).toBe("Here is my answer.  Yes, 42.");
+  });
+
+  it("handles empty content after stripping when hasReasoningContent is true", async () => {
+    const executor = new KiroExecutor();
+    
+    const f0 = createMockFrame("reasoningContentEvent", { text: "I am reasoning" });
+    const f1 = createMockFrame("assistantResponseEvent", { content: "<thinking>purely thinking...</thinking>" });
+    
+    const readableStream = new ReadableStream({
+      start(controller) {
+        controller.enqueue(f0);
+        controller.enqueue(f1);
+        controller.close();
+      }
+    });
+
+    const mockResponse = { body: readableStream };
+    const transformedResponse = executor.transformEventStreamToSSE(mockResponse, "claude-test");
+    
+    const output = await readAllSSE(transformedResponse.body);
+    
+    const dataLines = output.split("\n").filter(line => line.startsWith("data: ") && !line.includes("[DONE]"));
+    const objects = dataLines.map(line => JSON.parse(line.slice(6)));
+    
+    // First chunk should have reasoning_content
+    expect(objects[0].choices[0].delta.reasoning_content).toBe("I am reasoning");
+    
+    // We shouldn't get an empty content chunk from f1 since it was entirely stripped and reasoning was present
+    const contentChunks = objects.filter(obj => obj.choices[0].delta.content !== undefined);
+    expect(contentChunks.length).toBe(0);
+  });
+});
diff --git a/tests/unit/mimo-free.live.test.js b/tests/unit/mimo-free.live.test.js
new file mode 100644
index 0000000..adf3e2d
--- /dev/null
+++ b/tests/unit/mimo-free.live.test.js
@@ -0,0 +1,60 @@
+/**
+ * Live repro for issue #1933: MiMo Code Free returns HTTP 502 "MiMo bootstrap failed: 403".
+ * Root cause: upstream gates on Chrome-like User-Agent. Without UA → 403 "Illegal access".
+ * Hits real endpoints — no mocks. Free provider, safe to call.
+ */
+import { describe, it, expect } from "vitest";
+import { proxyAwareFetch } from "../../open-sse/utils/proxyFetch.js";
+import { __test__ } from "../../open-sse/executors/mimo-free.js";
+
+const { BOOTSTRAP_URL, CHAT_URL, generateFingerprint, MIMO_SYSTEM_MARKER } = __test__;
+
+const CHROME_UA =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+
+async function bootstrapWith(ua) {
+  const headers = { "Content-Type": "application/json" };
+  if (ua) headers["User-Agent"] = ua;
+  const r = await proxyAwareFetch(BOOTSTRAP_URL, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ client: generateFingerprint() }),
+  });
+  const data = await r.json();
+  return { status: r.status, jwt: data.jwt };
+}
+
+async function chatWith(jwt, ua) {
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Mimo-Source": "mimocode-cli-free",
+    Authorization: `Bearer ${jwt}`,
+    Accept: "application/json",
+  };
+  if (ua) headers["User-Agent"] = ua;
+  const body = {
+    model: "mimo-auto",
+    messages: [
+      { role: "system", content: MIMO_SYSTEM_MARKER },
+      { role: "user", content: "hi" },
+    ],
+    stream: false,
+  };
+  return proxyAwareFetch(CHAT_URL, { method: "POST", headers, body: JSON.stringify(body) });
+}
+
+describe("MiMo Free bootstrap (live)", () => {
+  it("bootstrap returns 200 with JWT", async () => {
+    const { status, jwt } = await bootstrapWith(CHROME_UA);
+    expect(status).toBe(200);
+    expect(jwt).toBeTruthy();
+  });
+});
+
+describe("MiMo Free anti-abuse gate (live)", () => {
+  it("chat WITH Chrome User-Agent → 200", async () => {
+    const { jwt } = await bootstrapWith(CHROME_UA);
+    const r = await chatWith(jwt, CHROME_UA);
+    expect(r.status).toBe(200);
+  });
+});
diff --git a/tests/unit/mimo-free.test.js b/tests/unit/mimo-free.test.js
new file mode 100644
index 0000000..ae4633b
--- /dev/null
+++ b/tests/unit/mimo-free.test.js
@@ -0,0 +1,250 @@
+/**
+ * Unit tests for the MiMo Free no-auth provider.
+ *
+ * Covers the parts that would silently break the bootstrap → JWT → chat flow:
+ *   - fingerprint / session id primitives (format + determinism)
+ *   - JWT bootstrap (caching, exp parsing, error paths)
+ *   - system marker injection (the 403 anti-abuse gate)
+ *   - executor wiring (headers, transformRequest, registration)
+ *   - provider/model config registration
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock proxyAwareFetch so bootstrapJwt never hits the network.
+const fetchMock = vi.fn();
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch: (...args) => fetchMock(...args),
+}));
+
+import { MimoFreeExecutor, __test__ } from "../../open-sse/executors/mimo-free.js";
+import { getExecutor } from "../../open-sse/executors/index.js";
+import { PROVIDERS } from "../../open-sse/config/providers.js";
+import { PROVIDER_MODELS, PROVIDER_ID_TO_ALIAS } from "../../open-sse/config/providerModels.js";
+import { FREE_PROVIDERS } from "../../src/shared/constants/providers.js";
+
+const {
+  generateFingerprint, generateSessionId, bootstrapJwt, resetJwtCache, parseJwtExp,
+  injectSystemMarker, MIMO_SYSTEM_MARKER, SESSION_AFFINITY_PREFIX, BOOTSTRAP_URL, CHAT_URL,
+} = __test__;
+
+function jsonResponse(data, { ok = true, status = 200 } = {}) {
+  return { ok, status, json: async () => data };
+}
+
+// Build a fake JWT with the given exp (seconds) in the payload.
+function makeJwt(expSec) {
+  const header = Buffer.from(JSON.stringify({ alg: "HS256" })).toString("base64url");
+  const payload = Buffer.from(JSON.stringify({ exp: expSec })).toString("base64url");
+  return `${header}.${payload}.sig`;
+}
+
+beforeEach(() => {
+  fetchMock.mockReset();
+  resetJwtCache();
+});
+
+describe("generateSessionId", () => {
+  it("uses the ses_ prefix and a 24-char random suffix", () => {
+    const id = generateSessionId();
+    expect(id.startsWith(SESSION_AFFINITY_PREFIX)).toBe(true);
+    expect(id.length).toBe(SESSION_AFFINITY_PREFIX.length + 24);
+  });
+
+  it("only emits lowercase alphanumeric characters in the suffix", () => {
+    expect(generateSessionId().slice(SESSION_AFFINITY_PREFIX.length)).toMatch(/^[a-z0-9]{24}$/);
+  });
+
+  it("produces a fresh id on each call", () => {
+    expect(generateSessionId()).not.toBe(generateSessionId());
+  });
+});
+
+describe("generateFingerprint", () => {
+  it("returns a 64-char hex sha256 digest", () => {
+    expect(generateFingerprint()).toMatch(/^[a-f0-9]{64}$/);
+  });
+
+  it("is stable per machine (deterministic across calls)", () => {
+    expect(generateFingerprint()).toBe(generateFingerprint());
+  });
+});
+
+describe("parseJwtExp", () => {
+  it("derives the expiry from the JWT exp claim (ms)", () => {
+    const expSec = Math.floor(Date.now() / 1000) + 3600;
+    expect(parseJwtExp(makeJwt(expSec))).toBe(expSec * 1000);
+  });
+
+  it("falls back to a future timestamp when the JWT is unparseable", () => {
+    const before = Date.now();
+    const result = parseJwtExp("not-a-jwt");
+    expect(result).toBeGreaterThan(before);
+  });
+});
+
+describe("injectSystemMarker", () => {
+  it("prepends a system message with the marker when none is present", () => {
+    const out = injectSystemMarker({ messages: [{ role: "user", content: "hi" }] });
+    expect(out.messages[0].role).toBe("system");
+    expect(out.messages[0].content).toContain(MIMO_SYSTEM_MARKER);
+  });
+
+  it("preserves the original user message after injection", () => {
+    const out = injectSystemMarker({ messages: [{ role: "user", content: "write a haiku" }] });
+    expect(out.messages.find((m) => m.role === "user").content).toBe("write a haiku");
+  });
+
+  it("keeps a caller-provided system prompt alongside the marker", () => {
+    const out = injectSystemMarker({
+      messages: [
+        { role: "system", content: "You are a pirate." },
+        { role: "user", content: "hi" },
+      ],
+    });
+    const sys = out.messages.filter((m) => m.role === "system").map((m) => m.content).join("\n");
+    expect(sys).toContain(MIMO_SYSTEM_MARKER);
+    expect(sys).toContain("You are a pirate.");
+  });
+
+  it("does not duplicate the marker when already present", () => {
+    const out = injectSystemMarker({
+      messages: [
+        { role: "system", content: `${MIMO_SYSTEM_MARKER}\nExtra.` },
+        { role: "user", content: "hi" },
+      ],
+    });
+    const count = out.messages.filter(
+      (m) => m.role === "system" && m.content.includes(MIMO_SYSTEM_MARKER)
+    ).length;
+    expect(count).toBe(1);
+  });
+
+  it("leaves a body without a messages array untouched", () => {
+    const body = { prompt: "legacy" };
+    expect(injectSystemMarker(body)).toBe(body);
+  });
+});
+
+describe("bootstrapJwt", () => {
+  it("returns the jwt from the bootstrap response", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ jwt: makeJwt(Math.floor(Date.now() / 1000) + 3600) }));
+    const jwt = await bootstrapJwt();
+    expect(jwt).toMatch(/\./);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0][0]).toBe(BOOTSTRAP_URL);
+  });
+
+  it("sends the machine fingerprint as the bootstrap client", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ jwt: makeJwt(Math.floor(Date.now() / 1000) + 3600) }));
+    await bootstrapJwt();
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    expect(body.client).toBe(generateFingerprint());
+  });
+
+  it("caches the jwt and does not re-fetch while still valid", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ jwt: makeJwt(Math.floor(Date.now() / 1000) + 3600) }));
+    const first = await bootstrapJwt();
+    const second = await bootstrapJwt();
+    expect(first).toBe(second);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-fetches once the cached jwt is within the expiry buffer", async () => {
+    // exp 100s out < 300s buffer → treated as near-expiry.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ jwt: makeJwt(Math.floor(Date.now() / 1000) + 100) }));
+    await bootstrapJwt();
+    const fresh = makeJwt(Math.floor(Date.now() / 1000) + 3600);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ jwt: fresh }));
+    expect(await bootstrapJwt()).toBe(fresh);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("throws when the bootstrap response is not ok", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({}, { ok: false, status: 403 }));
+    await expect(bootstrapJwt()).rejects.toThrow(/bootstrap failed: 403/);
+  });
+
+  it("throws when the bootstrap response has no jwt", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ expiresIn: 3600 }));
+    await expect(bootstrapJwt()).rejects.toThrow(/no JWT/);
+  });
+});
+
+describe("MimoFreeExecutor", () => {
+  const exec = new MimoFreeExecutor();
+
+  it("buildUrl returns the free-ai chat endpoint", () => {
+    expect(exec.buildUrl()).toBe(CHAT_URL);
+  });
+
+  it("buildHeaders includes the MiMo source and session affinity", () => {
+    const h = exec.buildHeaders({}, true);
+    expect(h["X-Mimo-Source"]).toBe("mimocode-cli-free");
+    expect(h["x-session-affinity"]).toMatch(/^ses_/);
+    expect(h["Accept"]).toBe("text/event-stream");
+  });
+
+  it("transformRequest injects the system marker", () => {
+    const out = exec.transformRequest("mimo-auto", { messages: [{ role: "user", content: "hi" }] });
+    expect(out.messages[0].content).toContain(MIMO_SYSTEM_MARKER);
+  });
+
+  it("execute injects the marker and sends a Bearer JWT to the chat endpoint", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ jwt: makeJwt(Math.floor(Date.now() / 1000) + 3600) }));
+    fetchMock.mockResolvedValueOnce({ ok: true, status: 200 });
+    const { url, headers, transformedBody } = await exec.execute({
+      model: "mimo-auto",
+      body: { model: "mimo-auto", stream: true, messages: [{ role: "user", content: "hi" }] },
+      stream: true,
+      credentials: {},
+    });
+    expect(url).toBe(CHAT_URL);
+    expect(headers["Authorization"]).toMatch(/^Bearer /);
+    expect(transformedBody.messages[0].content).toContain(MIMO_SYSTEM_MARKER);
+    // first call = bootstrap, second = chat with auth header
+    const chatHeaders = fetchMock.mock.calls[1][1].headers;
+    expect(chatHeaders["Authorization"]).toMatch(/^Bearer /);
+  });
+
+  it("re-bootstraps and retries once on a 403 from the chat endpoint", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ jwt: makeJwt(Math.floor(Date.now() / 1000) + 3600) }));
+    fetchMock.mockResolvedValueOnce({ ok: false, status: 403 });
+    fetchMock.mockResolvedValueOnce(jsonResponse({ jwt: makeJwt(Math.floor(Date.now() / 1000) + 3600) }));
+    fetchMock.mockResolvedValueOnce({ ok: true, status: 200 });
+    const { response } = await exec.execute({
+      model: "mimo-auto",
+      body: { messages: [{ role: "user", content: "hi" }] },
+      stream: true,
+      credentials: {},
+    });
+    expect(response.status).toBe(200);
+    // bootstrap, chat(403), re-bootstrap, chat(200)
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+  });
+});
+
+describe("MiMo Free provider registration", () => {
+  it("registers a specialized executor for mimo-free and the mmf alias", () => {
+    expect(getExecutor("mimo-free")).toBeInstanceOf(MimoFreeExecutor);
+    expect(getExecutor("mmf")).toBeInstanceOf(MimoFreeExecutor);
+  });
+
+  it("registers mimo-free as a no-auth provider in open-sse config", () => {
+    expect(PROVIDERS["mimo-free"]?.noAuth).toBe(true);
+    expect(PROVIDERS.mmf?.noAuth).toBe(true);
+  });
+
+  it("exposes only mimo-auto (the sole free-channel model)", () => {
+    expect(PROVIDER_MODELS.mmf.map((m) => m.id)).toEqual(["mimo-auto"]);
+  });
+
+  it("maps the mimo-free alias to mmf", () => {
+    expect(PROVIDER_ID_TO_ALIAS["mimo-free"]).toBe("mmf");
+  });
+
+  it("lists mimo-free in the dashboard FREE_PROVIDERS catalog", () => {
+    expect(FREE_PROVIDERS["mimo-free"]?.alias).toBe("mmf");
+    expect(FREE_PROVIDERS["mimo-free"]?.noAuth).toBe(true);
+  });
+});
diff --git a/tests/unit/minimax-tts.test.js b/tests/unit/minimax-tts.test.js
new file mode 100644
index 0000000..ec61da2
--- /dev/null
+++ b/tests/unit/minimax-tts.test.js
@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { handleTtsCore } from "../../open-sse/handlers/ttsCore.js";
+
+const originalFetch = global.fetch;
+
+describe("MiniMax TTS", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("sends MiniMax T2A payload and converts hex audio to base64 JSON", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          data: { audio: "00010203", status: 2 },
+          extra_info: { audio_format: "mp3" },
+          base_resp: { status_code: 0, status_msg: "success" },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleTtsCore({
+      provider: "minimax",
+      model: "speech-2.8-hd/English_expressive_narrator",
+      input: "Hello from MiniMax",
+      credentials: { apiKey: "test-key" },
+      responseFormat: "json",
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://api.minimax.io/v1/t2a_v2",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          "Content-Type": "application/json",
+          Authorization: "Bearer test-key",
+        }),
+      })
+    );
+
+    const sent = JSON.parse(global.fetch.mock.calls[0][1].body);
+    expect(sent).toMatchObject({
+      model: "speech-2.8-hd",
+      text: "Hello from MiniMax",
+      stream: false,
+      language_boost: "auto",
+      output_format: "hex",
+      voice_setting: {
+        voice_id: "English_expressive_narrator",
+        speed: 1,
+        vol: 1,
+        pitch: 0,
+      },
+      audio_setting: {
+        sample_rate: 32000,
+        bitrate: 128000,
+        format: "mp3",
+        channel: 1,
+      },
+    });
+
+    const body = await result.response.json();
+    expect(body).toEqual({ audio: "AAECAw==", format: "mp3" });
+  });
+
+  it("uses the default MiniMax voice when no voice is provided", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          data: { audio: "00010203", status: 2 },
+          base_resp: { status_code: 0, status_msg: "success" },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleTtsCore({
+      provider: "minimax-cn",
+      model: "speech-2.8-turbo",
+      input: "Hello",
+      credentials: { apiKey: "test-key" },
+      responseFormat: "json",
+    });
+
+    expect(result.success).toBe(true);
+    expect(global.fetch.mock.calls[0][0]).toBe("https://api.minimaxi.com/v1/t2a_v2");
+
+    const sent = JSON.parse(global.fetch.mock.calls[0][1].body);
+    expect(sent.model).toBe("speech-2.8-turbo");
+    expect(sent.voice_setting.voice_id).toBe("English_expressive_narrator");
+  });
+
+  it("surfaces MiniMax base_resp errors", async () => {
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          base_resp: { status_code: 1008, status_msg: "insufficient quota" },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const result = await handleTtsCore({
+      provider: "minimax",
+      model: "speech-2.8-hd/English_expressive_narrator",
+      input: "Hello",
+      credentials: { apiKey: "test-key" },
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe(502);
+    expect(result.error).toContain("insufficient quota");
+  });
+});
diff --git a/tests/unit/minimax-usage.test.js b/tests/unit/minimax-usage.test.js
new file mode 100644
index 0000000..d903473
--- /dev/null
+++ b/tests/unit/minimax-usage.test.js
@@ -0,0 +1,239 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch: vi.fn(),
+}));
+
+import { proxyAwareFetch } from "../../open-sse/utils/proxyFetch.js";
+import { getUsageForProvider } from "../../open-sse/services/usage.js";
+
+function usageResponse(modelRemains) {
+  return new Response(
+    JSON.stringify({
+      base_resp: { status_code: 0, status_msg: "success" },
+      model_remains: modelRemains,
+    }),
+    { status: 200, headers: { "Content-Type": "application/json" } }
+  );
+}
+
+describe("MiniMax usage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("parses token-plan TTS quota counts as used counts", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(
+      usageResponse([
+        {
+          model_name: "text to speech hd",
+          current_interval_total_count: 4000,
+          current_interval_usage_count: 25,
+          current_weekly_total_count: 12000,
+          current_weekly_usage_count: 100,
+          end_time: "2026-05-12T10:00:00.000Z",
+          weekly_end_time: "2026-05-19T10:00:00.000Z",
+        },
+      ])
+    );
+
+    const usage = await getUsageForProvider({
+      provider: "minimax",
+      apiKey: "test-key",
+    });
+
+    expect(usage.message).toBeUndefined();
+    expect(usage.quotas["Text to Speech HD (5h)"]).toMatchObject({
+      used: 25,
+      total: 4000,
+      remaining: 3975,
+    });
+    expect(usage.quotas["Text to Speech HD (7d)"]).toMatchObject({
+      used: 100,
+      total: 12000,
+      remaining: 11900,
+    });
+  });
+
+  it("parses coding-plan TTS quota counts as remaining counts", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(
+      usageResponse([
+        {
+          modelName: "Text to Speech HD",
+          currentIntervalTotalCount: 4000,
+          currentIntervalUsageCount: 4000,
+          currentWeeklyTotalCount: 12000,
+          currentWeeklyUsageCount: 11800,
+          remainsTime: 1000,
+          weeklyRemainsTime: 2000,
+        },
+      ])
+    );
+
+    const usage = await getUsageForProvider({
+      provider: "minimax-cn",
+      apiKey: "test-key",
+    });
+
+    expect(usage.message).toBeUndefined();
+    expect(usage.quotas["Text to Speech HD (5h)"]).toMatchObject({
+      used: 0,
+      total: 4000,
+      remaining: 4000,
+    });
+    expect(usage.quotas["Text to Speech HD (7d)"]).toMatchObject({
+      used: 200,
+      total: 12000,
+      remaining: 11800,
+    });
+  });
+
+  it("keeps non-TTS MiniMax quota rows instead of filtering to text only", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(
+      usageResponse([
+        {
+          model_name: "music-2.6",
+          current_interval_total_count: 100,
+          current_interval_usage_count: 5,
+        },
+        {
+          model_name: "image-01",
+          current_interval_total_count: 50,
+          current_interval_usage_count: 2,
+        },
+      ])
+    );
+
+    const usage = await getUsageForProvider({
+      provider: "minimax",
+      apiKey: "test-key",
+    });
+
+    expect(Object.keys(usage.quotas)).toEqual(["Music 2.6 (5h)", "Image 01 (5h)"]);
+    expect(usage.quotas["Music 2.6 (5h)"].used).toBe(5);
+    expect(usage.quotas["Image 01 (5h)"].used).toBe(2);
+  });
+
+  it("includes M-series percent-only buckets that have no count totals", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(
+      usageResponse([
+        {
+          model_name: "general",
+          current_interval_remaining_percent: 70,
+          current_weekly_remaining_percent: 64,
+        },
+      ])
+    );
+
+    const usage = await getUsageForProvider({
+      provider: "minimax",
+      apiKey: "test-key",
+    });
+
+    expect(usage.message).toBeUndefined();
+    expect(usage.quotas["M-series (5h)"]).toMatchObject({
+      used: 30,
+      total: 100,
+      remaining: 70,
+      remainingPercentage: 70,
+    });
+    expect(usage.quotas["M-series (7d)"]).toMatchObject({
+      used: 36,
+      total: 100,
+      remaining: 64,
+      remainingPercentage: 64,
+    });
+  });
+
+  it("normalizes M-series percent-only buckets on the coding_plan (countMeansRemaining) endpoint too", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(
+      usageResponse([
+        {
+          model_name: "general",
+          current_interval_remaining_percent: 80,
+          current_weekly_remaining_percent: 95,
+        },
+      ])
+    );
+
+    const usage = await getUsageForProvider({
+      provider: "minimax-cn",
+      apiKey: "test-key",
+    });
+
+    expect(usage.message).toBeUndefined();
+    expect(usage.quotas["M-series (5h)"]).toMatchObject({
+      used: 20,
+      total: 100,
+      remaining: 80,
+      remainingPercentage: 80,
+    });
+    expect(usage.quotas["M-series (7d)"]).toMatchObject({
+      used: 5,
+      total: 100,
+      remaining: 95,
+      remainingPercentage: 95,
+    });
+  });
+
+  it("renders the M3-era MiniMax-M* wildcard as a friendly series label", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(
+      usageResponse([
+        {
+          modelName: "MiniMax-M*",
+          currentIntervalTotalCount: 4000,
+          currentIntervalUsageCount: 3200,
+          currentWeeklyTotalCount: 24000,
+          currentWeeklyUsageCount: 18000,
+          remainsTime: 1000,
+          weeklyRemainsTime: 2000,
+        },
+      ])
+    );
+
+    const usage = await getUsageForProvider({
+      provider: "minimax-cn",
+      apiKey: "test-key",
+    });
+
+    expect(usage.message).toBeUndefined();
+    expect(Object.keys(usage.quotas)).toEqual([
+      "M-series (5h)",
+      "M-series (7d)",
+    ]);
+    expect(usage.quotas["M-series (5h)"]).toMatchObject({
+      used: 800,
+      total: 4000,
+      remaining: 3200,
+    });
+    expect(usage.quotas["M-series (7d)"]).toMatchObject({
+      used: 6000,
+      total: 24000,
+      remaining: 18000,
+    });
+  });
+
+  it("prefers the upstream-provided remaining percent when counts are also present", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(
+      usageResponse([
+        {
+          model_name: "general",
+          current_interval_total_count: 4000,
+          current_interval_usage_count: 100,
+          current_interval_remaining_percent: 84,
+          current_weekly_total_count: 24000,
+          current_weekly_usage_count: 500,
+          current_weekly_remaining_percent: 42,
+        },
+      ])
+    );
+
+    const usage = await getUsageForProvider({
+      provider: "minimax",
+      apiKey: "test-key",
+    });
+
+    expect(usage.quotas["M-series (5h)"].remainingPercentage).toBe(84);
+    expect(usage.quotas["M-series (7d)"].remainingPercentage).toBe(42);
+  });
+});
diff --git a/tests/unit/minimax-voices.test.js b/tests/unit/minimax-voices.test.js
new file mode 100644
index 0000000..8cbb843
--- /dev/null
+++ b/tests/unit/minimax-voices.test.js
@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("../../src/lib/localDb.js", () => ({
+  getProviderConnections: vi.fn(),
+}));
+
+import { getProviderConnections } from "../../src/lib/localDb.js";
+import { GET } from "../../src/app/api/media-providers/tts/minimax/voices/route.js";
+
+const originalFetch = global.fetch;
+
+describe("MiniMax voices API", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("fetches global MiniMax voices with stored API key", async () => {
+    getProviderConnections.mockResolvedValueOnce([{ apiKey: "test-key" }]);
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          system_voice: [
+            { voice_id: "English_expressive_narrator", voice_name: "Expressive Narrator" },
+            { voice_id: "Chinese (Mandarin)_female_beijing", voice_name: "Female Beijing" },
+          ],
+          voice_cloning: [{ voice_id: "clone_123", voice_name: "My Voice" }],
+          base_resp: { status_code: 0, status_msg: "success" },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const response = await GET(new Request("http://localhost/api/media-providers/tts/minimax/voices"));
+    const body = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(getProviderConnections).toHaveBeenCalledWith({ provider: "minimax", isActive: true });
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://api.minimax.io/v1/get_voice",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          Authorization: "Bearer test-key",
+          "Content-Type": "application/json",
+        }),
+        body: JSON.stringify({ voice_type: "all" }),
+      })
+    );
+    expect(body.byLang.English.voices[0].id).toBe("English_expressive_narrator");
+    expect(body.byLang["Chinese (Mandarin)"].voices[0].id).toBe("Chinese (Mandarin)_female_beijing");
+    expect(body.byLang.Custom.voices[0]).toMatchObject({
+      id: "clone_123",
+      name: "My Voice · Cloned",
+      category: "voice_cloning",
+    });
+  });
+
+  it("fetches China MiniMax voices when provider=minimax-cn", async () => {
+    getProviderConnections.mockResolvedValueOnce([{ apiKey: "test-key" }]);
+    global.fetch.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          system_voice: [{ voice_id: "Chinese (Mandarin)_female_beijing", voice_name: "Female Beijing" }],
+          base_resp: { status_code: 0, status_msg: "success" },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    const response = await GET(new Request("http://localhost/api/media-providers/tts/minimax/voices?provider=minimax-cn"));
+    const body = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(getProviderConnections).toHaveBeenCalledWith({ provider: "minimax-cn", isActive: true });
+    expect(global.fetch.mock.calls[0][0]).toBe("https://api.minimaxi.com/v1/get_voice");
+    expect(body.byLang["Chinese (Mandarin)"].voices[0].id).toBe("Chinese (Mandarin)_female_beijing");
+  });
+});
diff --git a/tests/unit/mitm-root-ca.test.js b/tests/unit/mitm-root-ca.test.js
new file mode 100644
index 0000000..f3e3f0a
--- /dev/null
+++ b/tests/unit/mitm-root-ca.test.js
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { createRequire } from "module";
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+const require = createRequire(import.meta.url);
+
+function loadRootCAWithDataDir(dataDir) {
+  const rootCAPath = require.resolve("../../src/mitm/cert/rootCA.js");
+  const pathsPath = require.resolve("../../src/mitm/paths.js");
+  delete require.cache[rootCAPath];
+  delete require.cache[pathsPath];
+
+  const oldDataDir = process.env.DATA_DIR;
+  process.env.DATA_DIR = dataDir;
+  try {
+    return require("../../src/mitm/cert/rootCA.js");
+  } finally {
+    if (oldDataDir === undefined) delete process.env.DATA_DIR;
+    else process.env.DATA_DIR = oldDataDir;
+  }
+}
+
+describe("MITM Root CA generation", () => {
+  it("creates Root CA files synchronously for direct server startup", () => {
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "9router-mitm-ca-"));
+    const { generateRootCA } = loadRootCAWithDataDir(dataDir);
+
+    generateRootCA();
+
+    expect(fs.existsSync(path.join(dataDir, "mitm", "rootCA.key"))).toBe(true);
+    expect(fs.existsSync(path.join(dataDir, "mitm", "rootCA.crt"))).toBe(true);
+  });
+});
diff --git a/tests/unit/modality-strip.test.js b/tests/unit/modality-strip.test.js
new file mode 100644
index 0000000..0abb896
--- /dev/null
+++ b/tests/unit/modality-strip.test.js
@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest";
+import { stripUnsupportedModalities } from "../../open-sse/translator/concerns/modality.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+const NO_VISION = { vision: false, audioInput: true, pdf: true };
+const NO_AUDIO = { vision: true, audioInput: false, pdf: true };
+const NO_PDF = { vision: true, audioInput: true, pdf: false };
+const ALL = { vision: true, audioInput: true, pdf: true };
+
+describe("stripUnsupportedModalities", () => {
+  it("fast-exits when model supports all modalities", () => {
+    const body = { messages: [{ role: "user", content: [{ type: "image_url", image_url: { url: "x" } }] }] };
+    expect(stripUnsupportedModalities(body, FORMATS.OPENAI, ALL)).toBe(false);
+    expect(body.messages[0].content).toHaveLength(1);
+  });
+
+  it("openai: strips image when vision:false, leaves placeholder", () => {
+    const body = { messages: [{ role: "user", content: [
+      { type: "text", text: "hi" },
+      { type: "image_url", image_url: { url: "data:image/png;base64,xx" } },
+    ] }] };
+    stripUnsupportedModalities(body, FORMATS.OPENAI, NO_VISION);
+    const types = body.messages[0].content.map((b) => b.type);
+    expect(types).toContain("text");
+    expect(types).not.toContain("image_url");
+    expect(body.messages[0].content.some((b) => b.type === "text" && /image omitted/.test(b.text))).toBe(true);
+  });
+
+  it("openai: strips input_audio when audioInput:false", () => {
+    const body = { messages: [{ role: "user", content: [
+      { type: "input_audio", input_audio: { data: "x", format: "wav" } },
+    ] }] };
+    stripUnsupportedModalities(body, FORMATS.OPENAI, NO_AUDIO);
+    expect(body.messages[0].content.some((b) => b.type === "input_audio")).toBe(false);
+    expect(body.messages[0].content.some((b) => /audio omitted/.test(b.text || ""))).toBe(true);
+  });
+
+  it("openai: strips file when pdf:false", () => {
+    const body = { messages: [{ role: "user", content: [
+      { type: "file", file: { filename: "d.pdf", file_data: "data:application/pdf;base64,x" } },
+    ] }] };
+    stripUnsupportedModalities(body, FORMATS.OPENAI, NO_PDF);
+    expect(body.messages[0].content.some((b) => b.type === "file")).toBe(false);
+  });
+
+  it("openai: keeps image when vision:true", () => {
+    const body = { messages: [{ role: "user", content: [{ type: "image_url", image_url: { url: "x" } }] }] };
+    stripUnsupportedModalities(body, FORMATS.OPENAI, NO_AUDIO);
+    expect(body.messages[0].content.some((b) => b.type === "image_url")).toBe(true);
+  });
+
+  it("claude: strips image + document by capability", () => {
+    const body = { messages: [{ role: "user", content: [
+      { type: "text", text: "hi" },
+      { type: "image", source: { type: "base64", media_type: "image/png", data: "x" } },
+      { type: "document", source: { type: "base64", media_type: "application/pdf", data: "x" } },
+    ] }] };
+    stripUnsupportedModalities(body, FORMATS.CLAUDE, { vision: false, audioInput: true, pdf: false });
+    const types = body.messages[0].content.map((b) => b.type);
+    expect(types).not.toContain("image");
+    expect(types).not.toContain("document");
+    expect(types).toContain("text");
+  });
+
+  it("gemini: strips inlineData image by mime when vision:false", () => {
+    const body = { contents: [{ role: "user", parts: [
+      { text: "hi" },
+      { inlineData: { mimeType: "image/png", data: "x" } },
+    ] }] };
+    stripUnsupportedModalities(body, FORMATS.GEMINI, NO_VISION);
+    expect(body.contents[0].parts.some((p) => p.inlineData)).toBe(false);
+    expect(body.contents[0].parts.some((p) => /image omitted/.test(p.text || ""))).toBe(true);
+  });
+
+  it("gemini: keeps inlineData pdf when pdf:true, strips image when vision:false", () => {
+    const body = { contents: [{ role: "user", parts: [
+      { inlineData: { mimeType: "image/png", data: "x" } },
+      { inlineData: { mimeType: "application/pdf", data: "y" } },
+    ] }] };
+    stripUnsupportedModalities(body, FORMATS.GEMINI, NO_VISION);
+    const mimes = body.contents[0].parts.filter((p) => p.inlineData).map((p) => p.inlineData.mimeType);
+    expect(mimes).toEqual(["application/pdf"]);
+  });
+
+  it("antigravity: strips inside request.contents", () => {
+    const body = { request: { contents: [{ role: "user", parts: [
+      { inlineData: { mimeType: "image/png", data: "x" } },
+    ] }] } };
+    stripUnsupportedModalities(body, FORMATS.ANTIGRAVITY, NO_VISION);
+    expect(body.request.contents[0].parts.some((p) => p.inlineData)).toBe(false);
+  });
+
+  it("responses: strips input_image when vision:false", () => {
+    const body = { input: [{ role: "user", content: [
+      { type: "input_text", text: "hi" },
+      { type: "input_image", image_url: "data:image/png;base64,x" },
+    ] }] };
+    stripUnsupportedModalities(body, FORMATS.OPENAI_RESPONSES, NO_VISION);
+    expect(body.input[0].content.some((b) => b.type === "input_image")).toBe(false);
+    expect(body.input[0].content.some((b) => b.type === "input_text" && /image omitted/.test(b.text))).toBe(true);
+  });
+
+  it("handles missing/empty body safely", () => {
+    expect(stripUnsupportedModalities(null, FORMATS.OPENAI, NO_VISION)).toBe(false);
+    expect(stripUnsupportedModalities({}, FORMATS.OPENAI, null)).toBe(false);
+    expect(stripUnsupportedModalities({ messages: [] }, FORMATS.OPENAI, NO_VISION)).toBe(true);
+  });
+});
diff --git a/tests/unit/model-name-regex.test.js b/tests/unit/model-name-regex.test.js
new file mode 100644
index 0000000..49a1660
--- /dev/null
+++ b/tests/unit/model-name-regex.test.js
@@ -0,0 +1,50 @@
+// Guards C2: regex name fallback (no catalog). Terse entries derive name; existing names untouched.
+import { describe, it, expect } from "vitest";
+import { deriveModelName } from "../../open-sse/providers/models/namePatterns.js";
+import { normalizeModel, normalizeModelId } from "../../open-sse/providers/models/schema.js";
+
+describe("model name regex fallback (C2)", () => {
+  it("derives display name from id per family", () => {
+    expect(deriveModelName("kimi-k2.5")).toBe("Kimi K2.5");
+    expect(deriveModelName("glm-4.6v")).toBe("GLM 4.6V (Vision)");
+    expect(deriveModelName("minimax-m2.7")).toBe("MiniMax M2.7");
+    expect(deriveModelName("gpt-5.4-mini")).toBe("GPT 5.4 Mini");
+    expect(deriveModelName("grok-4")).toBe("Grok 4");
+  });
+
+  it("falls back to id verbatim when no pattern matches", () => {
+    expect(deriveModelName("some-unknown-model")).toBe("some-unknown-model");
+  });
+
+  it("normalizeModel: explicit name always wins over regex", () => {
+    expect(normalizeModel({ id: "kimi-k2.5", name: "Custom" }).name).toBe("Custom");
+  });
+
+  it("normalizeModel: terse string id becomes object with derived name", () => {
+    const m = normalizeModel("glm-5");
+    expect(m.id).toBe("glm-5");
+    expect(m.name).toBe("GLM 5");
+  });
+
+  it("normalizeModelId: dash between digits becomes a dot (version separator)", () => {
+    expect(normalizeModelId("claude-sonnet-4-5")).toBe("claude-sonnet-4.5");
+    expect(normalizeModelId("minimax-m2-5")).toBe("minimax-m2.5");
+    expect(normalizeModelId("deepseek-3-2")).toBe("deepseek-3.2");
+  });
+
+  it("normalizeModelId: preserves word-suffix hyphens (-thinking, -agentic)", () => {
+    expect(normalizeModelId("claude-sonnet-4-5-thinking")).toBe("claude-sonnet-4.5-thinking");
+    expect(normalizeModelId("claude-sonnet-4-5-thinking-agentic")).toBe("claude-sonnet-4.5-thinking-agentic");
+  });
+
+  it("normalizeModelId: leaves ids with no digit-digit hyphen untouched", () => {
+    expect(normalizeModelId("qwen3-coder-next")).toBe("qwen3-coder-next");
+    expect(normalizeModelId("claude-sonnet-5")).toBe("claude-sonnet-5");
+    expect(normalizeModelId("glm-5")).toBe("glm-5");
+  });
+
+  it("normalizeModelId: non-string input passes through", () => {
+    expect(normalizeModelId(undefined)).toBeUndefined();
+    expect(normalizeModelId(null)).toBeNull();
+  });
+});
diff --git a/tests/unit/model-routing.test.js b/tests/unit/model-routing.test.js
new file mode 100644
index 0000000..827e131
--- /dev/null
+++ b/tests/unit/model-routing.test.js
@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+const originalDataDir = process.env.DATA_DIR;
+
+async function setupDb() {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "9router-model-routing-"));
+  process.env.DATA_DIR = tempDir;
+  vi.resetModules();
+
+  const { createProviderNode } = await import("@/models/index.js");
+  const { getModelInfo } = await import("@/sse/services/model.js");
+
+  return {
+    createProviderNode,
+    getModelInfo,
+    cleanup() {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    },
+  };
+}
+
+describe("model routing", () => {
+  let cleanup = () => {};
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    cleanup();
+    cleanup = () => {};
+    if (originalDataDir === undefined) delete process.env.DATA_DIR;
+    else process.env.DATA_DIR = originalDataDir;
+  });
+
+  it("keeps built-in provider aliases ahead of compatible node prefixes", async () => {
+    const ctx = await setupDb();
+    cleanup = ctx.cleanup;
+
+    await ctx.createProviderNode({
+      id: "openai-compatible-chat-test",
+      type: "openai-compatible",
+      name: "Compatible CF Collision",
+      prefix: "cf",
+      apiType: "chat",
+      baseUrl: "https://compatible.test/v1",
+    });
+
+    await expect(ctx.getModelInfo("cf/@cf/black-forest-labs/flux-2-klein-9b"))
+      .resolves.toEqual({
+        provider: "cloudflare-ai",
+        model: "@cf/black-forest-labs/flux-2-klein-9b",
+      });
+  });
+
+  it("still routes non-reserved compatible node prefixes", async () => {
+    const ctx = await setupDb();
+    cleanup = ctx.cleanup;
+
+    await ctx.createProviderNode({
+      id: "openai-compatible-chat-test",
+      type: "openai-compatible",
+      name: "Compatible OCT",
+      prefix: "oct",
+      apiType: "chat",
+      baseUrl: "https://compatible.test/v1",
+    });
+
+    await expect(ctx.getModelInfo("oct/gpt-image-1"))
+      .resolves.toEqual({
+        provider: "openai-compatible-chat-test",
+        model: "gpt-image-1",
+      });
+  });
+});
diff --git a/tests/unit/model-test-routing.test.js b/tests/unit/model-test-routing.test.js
new file mode 100644
index 0000000..3eaa572
--- /dev/null
+++ b/tests/unit/model-test-routing.test.js
@@ -0,0 +1,194 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  getApiKeys: vi.fn(),
+  getConsistentMachineId: vi.fn(),
+}));
+
+vi.mock("@/lib/localDb", () => ({
+  getApiKeys: mocks.getApiKeys,
+}));
+
+vi.mock("@/shared/utils/machineId", () => ({
+  getConsistentMachineId: mocks.getConsistentMachineId,
+}));
+
+vi.mock("next/server", () => ({
+  NextResponse: {
+    json(body, init = {}) {
+      return new Response(JSON.stringify(body), {
+        status: init.status || 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    },
+  },
+}));
+
+const originalFetch = global.fetch;
+
+describe("model test route kind routing", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getApiKeys.mockResolvedValue([{ key: "sk-internal", isActive: true }]);
+    mocks.getConsistentMachineId.mockResolvedValue("cli-token");
+    global.fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+      created: 1,
+      data: [{ b64_json: "abc" }],
+    }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    }));
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("routes image model tests to /api/v1/images/generations", async () => {
+    const { POST } = await import("../../src/app/api/models/test/route.js");
+
+    const req = new Request("http://localhost/api/models/test", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "hf/black-forest-labs/FLUX.1-schnell",
+        kind: "image",
+      }),
+    });
+
+    const res = await POST(req);
+    const body = await res.json();
+
+    expect(body.ok).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      expect.stringContaining("/api/v1/images/generations"),
+      expect.objectContaining({
+        method: "POST",
+        body: JSON.stringify({
+          model: "hf/black-forest-labs/FLUX.1-schnell",
+          prompt: "test",
+        }),
+      })
+    );
+  });
+
+  it("routes embedding model tests to /api/v1/embeddings", async () => {
+    global.fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+      data: [{ embedding: [0.1, 0.2] }],
+    }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    }));
+
+    const { POST } = await import("../../src/app/api/models/test/route.js");
+
+    const req = new Request("http://localhost/api/models/test", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "voyage/voyage-3-large",
+        kind: "embedding",
+      }),
+    });
+
+    const res = await POST(req);
+    const body = await res.json();
+
+    expect(body.ok).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      expect.stringContaining("/api/v1/embeddings"),
+      expect.objectContaining({
+        method: "POST",
+        body: JSON.stringify({
+          model: "voyage/voyage-3-large",
+          input: "test",
+        }),
+      })
+    );
+  });
+
+  it("fails embedding model tests when provider returns no embedding data", async () => {
+    global.fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+      data: [{ embedding: null }],
+    }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    }));
+
+    const { POST } = await import("../../src/app/api/models/test/route.js");
+
+    const req = new Request("http://localhost/api/models/test", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "voyage/voyage-3-large",
+        kind: "embedding",
+      }),
+    });
+
+    const res = await POST(req);
+    const body = await res.json();
+
+    expect(body.ok).toBe(false);
+    expect(body.error).toBe("Provider returned no embedding data");
+  });
+
+  it("routes stt model tests to /api/v1/audio/transcriptions", async () => {
+    global.fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+      text: "test",
+    }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    }));
+
+    const { POST } = await import("../../src/app/api/models/test/route.js");
+
+    const req = new Request("http://localhost/api/models/test", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "hf/openai/whisper-small",
+        kind: "stt",
+      }),
+    });
+
+    const res = await POST(req);
+    const body = await res.json();
+
+    expect(body.ok).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      expect.stringContaining("/api/v1/audio/transcriptions"),
+      expect.objectContaining({
+        method: "POST",
+        body: expect.any(FormData),
+      })
+    );
+  });
+
+  it("returns formatted HTTP errors for non-2xx embedding responses", async () => {
+    global.fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+      error: { message: "bad upstream" },
+    }), {
+      status: 502,
+      headers: { "Content-Type": "application/json" },
+    }));
+
+    const { POST } = await import("../../src/app/api/models/test/route.js");
+
+    const req = new Request("http://localhost/api/models/test", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "voyage/voyage-3-large",
+        kind: "embedding",
+      }),
+    });
+
+    const res = await POST(req);
+    const body = await res.json();
+
+    expect(body.ok).toBe(false);
+    expect(body.status).toBe(502);
+    expect(body.error).toBe("HTTP 502: bad upstream");
+  });
+});
diff --git a/tests/unit/multimodal-drop-lock.test.js b/tests/unit/multimodal-drop-lock.test.js
new file mode 100644
index 0000000..6ad4c6e
--- /dev/null
+++ b/tests/unit/multimodal-drop-lock.test.js
@@ -0,0 +1,58 @@
+// Locks multimodal quirks flagged in docs 11 §4: image_url.detail drop + input_audio per-format.
+import { describe, it, expect } from "vitest";
+import { openaiToClaudeRequest } from "../../open-sse/translator/request/openai-to-claude.js";
+import { convertOpenAIContentToParts } from "../../open-sse/translator/formats/gemini.js";
+
+function userImage(detail) {
+  return {
+    model: "claude-sonnet-4-6",
+    messages: [{
+      role: "user",
+      content: [
+        { type: "text", text: "look" },
+        { type: "image_url", image_url: { url: "data:image/png;base64,AAAB", detail } },
+      ],
+    }],
+  };
+}
+
+describe("openai→claude: image_url.detail is dropped (docs 11 §4)", () => {
+  it("converts image to base64 source WITHOUT a detail field", () => {
+    const out = openaiToClaudeRequest("claude-sonnet-4-6", userImage("high"), false);
+    const imgBlock = out.messages[0].content.find((b) => b.type === "image");
+    expect(imgBlock).toBeTruthy();
+    expect(imgBlock.source).toEqual({ type: "base64", media_type: "image/png", data: "AAAB" });
+    expect("detail" in imgBlock).toBe(false);
+    expect("detail" in imgBlock.source).toBe(false);
+  });
+
+  it("drops input_audio entirely (claude has no audio block)", () => {
+    const body = {
+      model: "claude-sonnet-4-6",
+      messages: [{ role: "user", content: [
+        { type: "text", text: "hi" },
+        { type: "input_audio", input_audio: { data: "ZZZ", format: "wav" } },
+      ] }],
+    };
+    const out = openaiToClaudeRequest("claude-sonnet-4-6", body, false);
+    const blocks = out.messages[0].content;
+    expect(blocks.some((b) => b.type === "audio" || b.type === "input_audio")).toBe(false);
+  });
+});
+
+describe("openai→gemini: input_audio is mapped to inlineData (docs 11 §4)", () => {
+  it("maps wav → audio/wav inlineData", () => {
+    const parts = convertOpenAIContentToParts([{ type: "input_audio", input_audio: { data: "ZZZ", format: "wav" } }]);
+    expect(parts).toEqual([{ inlineData: { mime_type: "audio/wav", data: "ZZZ" } }]);
+  });
+
+  it("maps mp3 → audio/mpeg inlineData", () => {
+    const parts = convertOpenAIContentToParts([{ type: "input_audio", input_audio: { data: "ZZZ", format: "mp3" } }]);
+    expect(parts[0].inlineData.mime_type).toBe("audio/mpeg");
+  });
+
+  it("drops image_url.detail (not carried into inlineData)", () => {
+    const parts = convertOpenAIContentToParts([{ type: "image_url", image_url: { url: "data:image/png;base64,AAAB", detail: "high" } }]);
+    expect(parts).toEqual([{ inlineData: { mime_type: "image/png", data: "AAAB" } }]);
+  });
+});
diff --git a/tests/unit/oauth-cursor-auto-import.test.js b/tests/unit/oauth-cursor-auto-import.test.js
new file mode 100644
index 0000000..c5abe0d
--- /dev/null
+++ b/tests/unit/oauth-cursor-auto-import.test.js
@@ -0,0 +1,184 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as fsPromises from "fs/promises";
+
+// Mock next/server
+vi.mock("next/server", () => ({
+  NextResponse: {
+    json: vi.fn((body, init) => ({
+      status: init?.status || 200,
+      body,
+      json: async () => body,
+    })),
+  },
+}));
+
+// Mock os
+vi.mock("os", () => ({
+  default: { homedir: vi.fn(() => "/mock/home") },
+  homedir: vi.fn(() => "/mock/home"),
+}));
+
+// Mock fs/promises
+vi.mock("fs/promises", () => ({
+  access: vi.fn(),
+  constants: { R_OK: 4 },
+}));
+
+// Shared mock db instance
+const mockDbInstance = {
+  prepare: vi.fn(),
+  close: vi.fn(),
+  __throwOnConstruct: false,
+};
+
+// Mock better-sqlite3 as a class so `new Database(...)` works
+vi.mock("better-sqlite3", () => ({
+  default: class MockDatabase {
+    constructor() {
+      if (mockDbInstance.__throwOnConstruct) {
+        throw new Error("SQLITE_CANTOPEN");
+      }
+      return mockDbInstance;
+    }
+  },
+}));
+
+// We need to dynamically import after mocks are registered
+let GET;
+
+describe("GET /api/oauth/cursor/auto-import", () => {
+  const originalPlatform = process.platform;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockDbInstance.__throwOnConstruct = false;
+    // Force darwin so macOS-specific logic is exercised
+    Object.defineProperty(process, "platform", { value: "darwin", writable: true });
+    // Re-import to pick up fresh mocks each run
+    const mod = await import("../../src/app/api/oauth/cursor/auto-import/route.js");
+    GET = mod.GET;
+  });
+
+  afterEach(() => {
+    Object.defineProperty(process, "platform", { value: originalPlatform, writable: true });
+  });
+
+  // ── macOS path probing ────────────────────────────────────────────────
+
+  it("returns not-found when no macOS cursor db paths are accessible", async () => {
+    vi.mocked(fsPromises.access).mockRejectedValue(new Error("ENOENT"));
+
+    const response = await GET();
+
+    expect(response.body.found).toBe(false);
+    expect(response.body.error).toContain("Cursor database not found in known macOS locations");
+  });
+
+  it("returns descriptive error if macOS db file exists but cannot be opened", async () => {
+    vi.mocked(fsPromises.access).mockResolvedValue();
+    mockDbInstance.__throwOnConstruct = true;
+
+    const response = await GET();
+
+    expect(response.body.found).toBe(false);
+    expect(response.body.error).toContain("could not open it");
+    expect(response.body.error).toContain("SQLITE_CANTOPEN");
+  });
+
+  // ── Token extraction ──────────────────────────────────────────────────
+
+  it("extracts tokens using exact keys", async () => {
+    vi.mocked(fsPromises.access).mockResolvedValue();
+    mockDbInstance.prepare.mockReturnValue({
+      all: vi.fn().mockReturnValue([
+        { key: "cursorAuth/accessToken", value: "test-token" },
+        { key: "storage.serviceMachineId", value: "test-machine-id" },
+      ]),
+    });
+
+    const response = await GET();
+
+    expect(response.body.found).toBe(true);
+    expect(response.body.accessToken).toBe("test-token");
+    expect(response.body.machineId).toBe("test-machine-id");
+    expect(mockDbInstance.close).toHaveBeenCalled();
+  });
+
+  it("unwraps JSON-encoded string values", async () => {
+    vi.mocked(fsPromises.access).mockResolvedValue();
+    mockDbInstance.prepare.mockReturnValue({
+      all: vi.fn().mockReturnValue([
+        { key: "cursorAuth/accessToken", value: '"json-token"' },
+        { key: "storage.serviceMachineId", value: '"json-machine-id"' },
+      ]),
+    });
+
+    const response = await GET();
+
+    expect(response.body.found).toBe(true);
+    expect(response.body.accessToken).toBe("json-token");
+    expect(response.body.machineId).toBe("json-machine-id");
+  });
+
+  // ── Fuzzy fallback (macOS only) ───────────────────────────────────────
+
+  it("falls back to fuzzy key matching on macOS when exact keys are missing", async () => {
+    vi.mocked(fsPromises.access).mockResolvedValue();
+    mockDbInstance.prepare.mockImplementation((query) => {
+      if (query.includes("IN (")) {
+        return { all: vi.fn().mockReturnValue([]) };
+      }
+      // Fuzzy LIKE query
+      return {
+        all: vi.fn().mockReturnValue([
+          { key: "cursorAuth/someOtherAccessTokenKey", value: "fallback-token" },
+          { key: "storage.someMachineId", value: "fallback-machine" },
+        ]),
+      };
+    });
+
+    const response = await GET();
+
+    expect(response.body.found).toBe(true);
+    expect(response.body.accessToken).toBe("fallback-token");
+    expect(response.body.machineId).toBe("fallback-machine");
+  });
+
+  it("returns login-prompt error when tokens are missing even after fallback", async () => {
+    vi.mocked(fsPromises.access).mockResolvedValue();
+    mockDbInstance.prepare.mockReturnValue({
+      all: vi.fn().mockReturnValue([]),
+    });
+
+    const response = await GET();
+
+    expect(response.body.found).toBe(false);
+    expect(response.body.error).toContain("Please login to Cursor IDE first");
+  });
+
+  // ── Backwards-compatible: linux/win32 keep original single-path logic ─
+
+  it("linux uses single hardcoded path and original error message", async () => {
+    Object.defineProperty(process, "platform", { value: "linux", writable: true });
+    vi.mocked(fsPromises.access).mockRejectedValue(new Error("ENOENT"));
+    mockDbInstance.__throwOnConstruct = true;
+
+    const response = await GET();
+
+    expect(response.body.found).toBe(false);
+    expect(response.body.error).toBe(
+      "Cursor database not found. Make sure Cursor IDE is installed and you are logged in."
+    );
+    // fs/promises.access should NOT have been called (linux skips probing)
+    expect(fsPromises.access).not.toHaveBeenCalled();
+  });
+
+  it("unsupported platform returns 400", async () => {
+    Object.defineProperty(process, "platform", { value: "freebsd", writable: true });
+
+    const response = await GET();
+
+    expect(response.status).toBe(400);
+    expect(response.body.error).toBe("Unsupported platform");
+  });
+});
diff --git a/tests/unit/openai-responses-multiturn.test.js b/tests/unit/openai-responses-multiturn.test.js
new file mode 100644
index 0000000..bdc41dc
--- /dev/null
+++ b/tests/unit/openai-responses-multiturn.test.js
@@ -0,0 +1,182 @@
+/**
+ * Multi-turn continuity for store=false Responses backends (Grok CLI / Codex).
+ * Prior-turn reasoning (+ encrypted_content) must survive Chat Completions ↔ Responses.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  openaiToOpenAIResponsesRequest,
+  openaiResponsesToOpenAIRequest,
+} from "../../open-sse/translator/request/openai-responses.js";
+import { GrokCliExecutor, _resetGrokCliTurnStore } from "../../open-sse/executors/grok-cli.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+
+describe("openai ↔ responses multi-turn reasoning", () => {
+  it("openai→responses re-emits reasoning item with summary + encrypted_content", () => {
+    const body = {
+      model: "grok-4.5",
+      messages: [
+        { role: "user", content: "hi" },
+        {
+          role: "assistant",
+          content: "hello",
+          reasoning_content: "thinking hard about greeting",
+          encrypted_content: "enc_blob_turn1",
+        },
+        { role: "user", content: "next" },
+      ],
+    };
+
+    const out = openaiToOpenAIResponsesRequest("grok-4.5", body, true, null);
+    expect(out.store).toBe(false);
+
+    const reasoning = out.input.filter((i) => i.type === "reasoning");
+    expect(reasoning).toHaveLength(1);
+    expect(reasoning[0].encrypted_content).toBe("enc_blob_turn1");
+    expect(reasoning[0].summary?.[0]?.text).toMatch(/thinking hard/);
+
+    // Order: user → reasoning → assistant → user
+    const types = out.input.map((i) => i.type || i.role);
+    expect(types).toEqual(["message", "reasoning", "message", "message"]);
+    expect(out.input[0].role).toBe("user");
+    expect(out.input[2].role).toBe("assistant");
+    expect(out.input[3].role).toBe("user");
+  });
+
+  it("accepts reasoning_encrypted_content alias on assistant messages", () => {
+    const out = openaiToOpenAIResponsesRequest(
+      "m",
+      {
+        messages: [
+          {
+            role: "assistant",
+            content: "ok",
+            reasoning_encrypted_content: "alt_enc",
+          },
+        ],
+      },
+      true,
+      null
+    );
+    expect(out.input.find((i) => i.type === "reasoning")?.encrypted_content).toBe("alt_enc");
+  });
+
+  it("responses→openai attaches reasoning_content + encrypted_content to assistant", () => {
+    const body = {
+      model: "grok-4.5",
+      input: [
+        { type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+        {
+          type: "reasoning",
+          summary: [{ type: "summary_text", text: "plan A" }],
+          encrypted_content: "enc_xyz",
+        },
+        {
+          type: "message",
+          role: "assistant",
+          content: [{ type: "output_text", text: "hello" }],
+        },
+      ],
+    };
+
+    const out = openaiResponsesToOpenAIRequest("grok-4.5", body, true, null);
+    const assistant = out.messages.find((m) => m.role === "assistant");
+    expect(assistant).toBeTruthy();
+    expect(assistant.reasoning_content).toBe("plan A");
+    expect(assistant.encrypted_content).toBe("enc_xyz");
+  });
+
+  it("round-trips encrypted_content through openai → responses → openai", () => {
+    const original = {
+      model: "grok-4.5",
+      messages: [
+        { role: "user", content: "q1" },
+        {
+          role: "assistant",
+          content: "a1",
+          reasoning_content: "r1",
+          encrypted_content: "ENC_KEEP_ME",
+        },
+        { role: "user", content: "q2" },
+      ],
+    };
+
+    const responses = openaiToOpenAIResponsesRequest("grok-4.5", structuredClone(original), true, null);
+    const back = openaiResponsesToOpenAIRequest("grok-4.5", responses, true, null);
+    const again = openaiToOpenAIResponsesRequest("grok-4.5", back, true, null);
+
+    const enc = again.input.find((i) => i.type === "reasoning")?.encrypted_content;
+    expect(enc).toBe("ENC_KEEP_ME");
+  });
+
+  it("translateRequest openai→openai-responses preserves encrypted blob", () => {
+    const body = {
+      model: "grok-4.5",
+      messages: [
+        { role: "user", content: "hi" },
+        {
+          role: "assistant",
+          content: "yo",
+          reasoning_content: "why",
+          encrypted_content: "blob_via_registry",
+        },
+        { role: "user", content: "go" },
+      ],
+    };
+    const out = translateRequest(
+      "openai",
+      "openai-responses",
+      "grok-4.5",
+      structuredClone(body),
+      true,
+      {},
+      "grok-cli"
+    );
+    expect(out.input.some((i) => i.type === "reasoning" && i.encrypted_content === "blob_via_registry")).toBe(
+      true
+    );
+  });
+});
+
+describe("GrokCliExecutor multi-turn input", () => {
+  it("keeps reasoning items (incl. encrypted_content) and strips only server message ids", () => {
+    _resetGrokCliTurnStore();
+    const executor = new GrokCliExecutor();
+    const body = {
+      model: "grok-4.5",
+      input: [
+        { type: "message", role: "system", content: "You are Grok" },
+        { type: "message", role: "user", content: "hi", id: "msg_server_prev" },
+        {
+          type: "reasoning",
+          id: "rs_server_prev",
+          summary: [{ type: "summary_text", text: "prior plan" }],
+          encrypted_content: "enc_from_cli",
+        },
+        { type: "message", role: "assistant", content: "hello", id: "msg_server_asst" },
+        { type: "message", role: "user", content: "again" },
+      ],
+      include: ["reasoning.encrypted_content"],
+    };
+
+    const out = executor.transformRequest("grok-4.5", structuredClone(body), true, {
+      connectionId: "mt-1",
+    });
+
+    const reasoning = out.input.filter((i) => i.type === "reasoning");
+    expect(reasoning).toHaveLength(1);
+    expect(reasoning[0].encrypted_content).toBe("enc_from_cli");
+    expect(reasoning[0].summary?.[0]?.text).toBe("prior plan");
+    // server id stripped from reasoning item, content kept
+    expect(reasoning[0].id).toBeUndefined();
+
+    // system preserved (not developer)
+    expect(out.input[0].role).toBe("system");
+    // message server ids stripped
+    for (const item of out.input) {
+      if (item.type === "message") expect(item.id).toBeUndefined();
+    }
+    expect(out.include).toContain("reasoning.encrypted_content");
+    expect(out.store).toBe(false);
+    expect(executor._currentTurnIdx).toBe(2);
+  });
+});
diff --git a/tests/unit/openai-responses-terminal-event.test.js b/tests/unit/openai-responses-terminal-event.test.js
new file mode 100644
index 0000000..32ee66c
--- /dev/null
+++ b/tests/unit/openai-responses-terminal-event.test.js
@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+
+import { FORMATS } from "../../open-sse/translator/formats.js";
+import { createSSETransformStreamWithLogger } from "../../open-sse/utils/stream.js";
+
+async function runTransform(input) {
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    start(controller) {
+      controller.enqueue(encoder.encode(input));
+      controller.close();
+    },
+  });
+
+  const output = stream.pipeThrough(
+    createSSETransformStreamWithLogger(
+      FORMATS.OPENAI_RESPONSES,
+      FORMATS.OPENAI_RESPONSES,
+      "codex",
+      null,
+      null,
+      "gpt-5.5",
+    ),
+  );
+
+  const reader = output.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    text += decoder.decode(value, { stream: true });
+  }
+
+  text += decoder.decode();
+  return text;
+}
+
+describe("OpenAI Responses streaming termination", () => {
+  it("emits a response.failed event when a Responses stream closes before a terminal event", async () => {
+    const output = await runTransform([
+      `event: response.created`,
+      `data: ${JSON.stringify({ type: "response.created", response: { id: "resp_test", status: "in_progress" } })}`,
+      "",
+      `event: response.output_text.delta`,
+      `data: ${JSON.stringify({ type: "response.output_text.delta", delta: "partial" })}`,
+      "",
+    ].join("\n"));
+
+    expect(output).toContain("event: response.failed");
+    expect(output).toContain('"type":"response.failed"');
+    expect(output).not.toContain("data: null");
+    expect(output).toContain("data: [DONE]");
+  });
+
+  it("does not add response.failed when a Responses stream already completed", async () => {
+    const output = await runTransform([
+      `event: response.completed`,
+      `data: ${JSON.stringify({ type: "response.completed", response: { id: "resp_test", status: "completed" } })}`,
+      "",
+    ].join("\n"));
+
+    expect(output).toContain("event: response.completed");
+    expect(output).not.toContain("event: response.failed");
+    expect(output).not.toContain("data: null");
+    expect(output).toContain("data: [DONE]");
+  });
+
+  it("does not add response.failed when a Responses stream sends response.done", async () => {
+    const output = await runTransform([
+      `event: response.done`,
+      `data: ${JSON.stringify({ type: "response.done", response: { id: "resp_test" } })}`,
+      "",
+    ].join("\n"));
+
+    expect(output).toContain("event: response.done");
+    expect(output).not.toContain("event: response.failed");
+    expect(output).not.toContain("data: null");
+    expect(output).toContain("data: [DONE]");
+  });
+
+  it("emits response.failed before DONE when a Responses stream sends DONE without a terminal event", async () => {
+    const output = await runTransform([
+      `event: response.created`,
+      `data: ${JSON.stringify({ type: "response.created", response: { id: "resp_test", status: "in_progress" } })}`,
+      "",
+      "data: [DONE]",
+      "",
+    ].join("\n"));
+
+    expect(output.indexOf("event: response.failed")).toBeLessThan(output.indexOf("data: [DONE]"));
+    expect(output.match(/data: \[DONE\]/g)).toHaveLength(1);
+    expect(output).not.toContain("data: null");
+  });
+});
diff --git a/tests/unit/openai-to-claude-response-tools.test.js b/tests/unit/openai-to-claude-response-tools.test.js
new file mode 100644
index 0000000..51d5a0f
--- /dev/null
+++ b/tests/unit/openai-to-claude-response-tools.test.js
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { openaiToClaudeResponse } from "../../open-sse/translator/response/openai-to-claude.js";
+
+function createState() {
+  return { toolCalls: new Map(), nextBlockIndex: 0 };
+}
+
+function getInputJsonDelta(events) {
+  return events.find((event) => event.type === "content_block_delta" && event.delta?.type === "input_json_delta")?.delta.partial_json;
+}
+
+describe("openaiToClaudeResponse tool argument sanitization", () => {
+  it("drops invalid Read pages and clamps numeric bounds", () => {
+    const state = createState();
+
+    openaiToClaudeResponse({
+      id: "chatcmpl-test-read",
+      model: "test-model",
+      choices: [{ delta: { tool_calls: [{ index: 0, id: "toolu_read", function: { name: "Read" } }] } }],
+    }, state);
+
+    const events = openaiToClaudeResponse({
+      id: "chatcmpl-test-read",
+      model: "test-model",
+      choices: [{
+        delta: { tool_calls: [{ index: 0, function: { arguments: JSON.stringify({ file_path: "F:/repo/file.js", offset: -5, limit: 999999999, pages: "" }) } }] },
+        finish_reason: "tool_calls",
+      }],
+    }, state);
+
+    expect(JSON.parse(getInputJsonDelta(events))).toEqual({
+      file_path: "F:/repo/file.js",
+      offset: 0,
+      limit: 2000,
+    });
+  });
+
+  it("keeps valid PDF pages", () => {
+    const state = createState();
+
+    openaiToClaudeResponse({
+      id: "chatcmpl-test-pdf",
+      model: "test-model",
+      choices: [{ delta: { tool_calls: [{ index: 0, id: "toolu_pdf", function: { name: "proxy_Read" } }] } }],
+    }, state);
+
+    const events = openaiToClaudeResponse({
+      id: "chatcmpl-test-pdf",
+      model: "test-model",
+      choices: [{
+        delta: { tool_calls: [{ index: 0, function: { arguments: JSON.stringify({ file_path: "F:/repo/doc.pdf", pages: "1-3" }) } }] },
+        finish_reason: "tool_calls",
+      }],
+    }, state);
+
+    expect(JSON.parse(getInputJsonDelta(events))).toEqual({
+      file_path: "F:/repo/doc.pdf",
+      pages: "1-3",
+    });
+  });
+});
diff --git a/tests/unit/openai-to-claude-tools-no-type.test.js b/tests/unit/openai-to-claude-tools-no-type.test.js
new file mode 100644
index 0000000..17f0ae2
--- /dev/null
+++ b/tests/unit/openai-to-claude-tools-no-type.test.js
@@ -0,0 +1,91 @@
+/**
+ * Regression: tools WITHOUT an explicit `type:"function"` wrapper were
+ * forwarded to the upstream Claude-compatible gateway with `name:"undefined"`,
+ * because openai-to-claude only unwrapped `tool.function` when BOTH
+ * `tool.type === "function"` AND `tool.function` were truthy.
+ *
+ * Repro path (v0.5.20):
+ *   tools: [{ function: { name: "echo", parameters: {...} } }]   // no parent type
+ *   → originalName = undefined
+ *   → upstream body: { name: "undefined", description: "", input_schema: {...} }
+ *
+ * Pragmatic OpenAI clients and some library generators emit the bare
+ * `function` wrapper shape; when this lands on a strict Anthropic-compatible
+ * gateway (e.g. MiniMax's `api.minimaxi.com/anthropic/v1/messages`), the
+ * payload is rejected with an "invalid tool type" / "(2013)" error, which
+ * is the same family of failure that PR #2463 was diagnosing from the
+ * runtimeTransport side. PR #2463 fixes the combo-path transport
+ * selection; this regression closes the translator-side shape gap so
+ * single-connection OpenAI clients aren't bit by it once #2463 lands.
+ *
+ * See: #2435, follow-up to PR #2463.
+ */
+
+import { describe, it, expect } from "vitest";
+import { openaiToClaudeRequest } from "../../open-sse/translator/request/openai-to-claude.js";
+
+const baseBody = (extra = {}) => ({
+  messages: [{ role: "user", content: "hi" }],
+  ...extra,
+});
+
+describe("openai→claude: tools shape fidelity", () => {
+  it("tool WITH explicit type:'function' is rewritten to Anthropic shape", () => {
+    const out = openaiToClaudeRequest("claude-sonnet-4.5", baseBody({
+      tools: [
+        { type: "function", function: { name: "echo", parameters: { type: "object" } } },
+      ],
+    }), false);
+
+    expect(out.tools).toHaveLength(1);
+    expect(out.tools[0].name).toBe("echo");
+    expect(out.tools[0].input_schema).toEqual({ type: "object" });
+    // Anthropic-shape has no top-level `type` and no nested `function`.
+    expect(out.tools[0]).not.toHaveProperty("type");
+    expect(out.tools[0]).not.toHaveProperty("function");
+  });
+
+  it("tool WITHOUT explicit type but WITH function wrapper preserves the original name (was 'undefined' in v0.5.20)", () => {
+    const out = openaiToClaudeRequest("claude-sonnet-4.5", baseBody({
+      tools: [
+        { function: { name: "echo", parameters: { type: "object" } } },
+      ],
+    }), false);
+
+    expect(out.tools).toHaveLength(1);
+    expect(out.tools[0].name).toBe("echo");
+    expect(out.tools[0].input_schema).toEqual({ type: "object" });
+    // The Anthropic-shape envelope strips the OpenAI `function` wrapper entirely.
+    expect(out.tools[0]).not.toHaveProperty("function");
+    expect(out.tools[0]).not.toHaveProperty("type");
+  });
+
+  it("flat Anthropic-shape tool (no function wrapper) is passed through with name preserved", () => {
+    const out = openaiToClaudeRequest("claude-sonnet-4.5", baseBody({
+      tools: [
+        { name: "echo", description: "echo input", input_schema: { type: "object" } },
+      ],
+    }), false);
+
+    expect(out.tools).toHaveLength(1);
+    expect(out.tools[0].name).toBe("echo");
+    expect(out.tools[0].description).toBe("echo input");
+    expect(out.tools[0].input_schema).toEqual({ type: "object" });
+  });
+
+  it("non-function built-in tool types are passed through (cache_control tag is OK)", () => {
+    // 9router adds a `cache_control` tag to the last tool for prompt caching;
+    // the test asserts the original shape is preserved alongside it rather
+    // than checking strict equality. This is the existing buildHeaders /
+    // cache_control behavior unchanged by this fix.
+    const out = openaiToClaudeRequest("claude-sonnet-4.5", baseBody({
+      tools: [
+        { type: "web_search_20250305", name: "web_search" },
+      ],
+    }), false);
+
+    expect(out.tools).toHaveLength(1);
+    expect(out.tools[0].type).toBe("web_search_20250305");
+    expect(out.tools[0].name).toBe("web_search");
+  });
+});
diff --git a/tests/unit/openai-to-claude.test.js b/tests/unit/openai-to-claude.test.js
new file mode 100644
index 0000000..45b67fb
--- /dev/null
+++ b/tests/unit/openai-to-claude.test.js
@@ -0,0 +1,206 @@
+/**
+ * Unit tests for open-sse/translator/request/openai-to-claude.js
+ *
+ * Tests cover:
+ *  - openaiToClaudeRequest() - OpenAI to Claude request translation
+ *  - Response format handling (json_schema, json_object)
+ */
+
+import { describe, it, expect } from "vitest";
+import { openaiToClaudeRequest } from "../../open-sse/translator/request/openai-to-claude.js";
+import { openaiToClaudeResponse } from "../../open-sse/translator/response/openai-to-claude.js";
+
+describe("openaiToClaudeRequest", () => {
+  describe("response_format handling", () => {
+    it("should inject JSON schema instructions for json_schema type", () => {
+      const body = {
+        messages: [{ role: "user", content: "What is 2+2?" }],
+        response_format: {
+          type: "json_schema",
+          json_schema: {
+            name: "math_response",
+            schema: {
+              type: "object",
+              properties: {
+                answer: { type: "number" },
+                explanation: { type: "string" }
+              },
+              required: ["answer", "explanation"]
+            }
+          }
+        }
+      };
+
+      const result = openaiToClaudeRequest("claude-sonnet-4.5", body, false);
+
+      // Should have system array with instructions
+      expect(result.system).toBeDefined();
+      expect(Array.isArray(result.system)).toBe(true);
+      
+      // Check that system prompt includes schema
+      const systemText = result.system
+        .filter(s => s.type === "text")
+        .map(s => s.text)
+        .join("\n");
+      
+      expect(systemText).toContain("You must respond with valid JSON");
+      expect(systemText).toContain("\"answer\"");
+      expect(systemText).toContain("\"explanation\"");
+      expect(systemText).toContain("Respond ONLY with the JSON object");
+    });
+
+    it("should inject basic JSON instructions for json_object type", () => {
+      const body = {
+        messages: [{ role: "user", content: "Give me a JSON object" }],
+        response_format: {
+          type: "json_object"
+        }
+      };
+
+      const result = openaiToClaudeRequest("claude-sonnet-4.5", body, false);
+
+      // Should have system array with instructions
+      expect(result.system).toBeDefined();
+      expect(Array.isArray(result.system)).toBe(true);
+      
+      const systemText = result.system
+        .filter(s => s.type === "text")
+        .map(s => s.text)
+        .join("\n");
+      
+      expect(systemText).toContain("You must respond with valid JSON");
+      expect(systemText).toContain("Respond ONLY with a JSON object");
+    });
+
+    it("should not modify system prompt when response_format is missing", () => {
+      const body = {
+        messages: [{ role: "user", content: "Hello" }]
+      };
+
+      const result = openaiToClaudeRequest("claude-sonnet-4.5", body, false);
+
+      // Should have system but without JSON instructions
+      expect(result.system).toBeDefined();
+      
+      const systemText = result.system
+        .filter(s => s.type === "text")
+        .map(s => s.text)
+        .join("\n");
+      
+      // Should NOT contain JSON-specific instructions
+      expect(systemText).not.toContain("You must respond with valid JSON");
+    });
+
+    it("should preserve existing system messages when adding response_format", () => {
+      const body = {
+        messages: [
+          { role: "system", content: "You are a helpful math tutor." },
+          { role: "user", content: "What is 2+2?" }
+        ],
+        response_format: {
+          type: "json_schema",
+          json_schema: {
+            schema: {
+              type: "object",
+              properties: {
+                result: { type: "number" }
+              }
+            }
+          }
+        }
+      };
+
+      const result = openaiToClaudeRequest("claude-sonnet-4.5", body, false);
+
+      // Should preserve original system message
+      const systemText = result.system
+        .filter(s => s.type === "text")
+        .map(s => s.text)
+        .join("\n");
+      
+      expect(systemText).toContain("You are a helpful math tutor");
+      expect(systemText).toContain("You must respond with valid JSON");
+    });
+  });
+
+  describe("tool_choice handling", () => {
+    const baseBody = {
+      messages: [{ role: "user", content: "add a todo" }],
+      tools: [{
+        type: "function",
+        function: { name: "todo_write", description: "write todos", parameters: { type: "object", properties: {} } }
+      }]
+    };
+
+    const choiceOf = (tc) =>
+      openaiToClaudeRequest("claude-sonnet-4.5", { ...baseBody, tool_choice: tc }, false).tool_choice;
+
+    it("converts OpenAI forced tool ({type:'function'}) to Claude {type:'tool'}", () => {
+      // Must NOT leak the OpenAI "function" type — Claude only accepts auto|any|tool|none.
+      expect(choiceOf({ type: "function", function: { name: "todo_write" } }))
+        .toEqual({ type: "tool", name: "todo_write" });
+    });
+
+    it("maps string tool_choice values", () => {
+      expect(choiceOf("auto")).toEqual({ type: "auto" });
+      expect(choiceOf("none")).toEqual({ type: "auto" });
+      expect(choiceOf("required")).toEqual({ type: "any" });
+    });
+
+    it("passes through Claude-native tool_choice objects unchanged", () => {
+      expect(choiceOf({ type: "tool", name: "todo_write" })).toEqual({ type: "tool", name: "todo_write" });
+      expect(choiceOf({ type: "any" })).toEqual({ type: "any" });
+      expect(choiceOf({ type: "none" })).toEqual({ type: "none" });
+    });
+
+    it("never leaks an invalid type (falls back to auto)", () => {
+      // Malformed forced choice with no tool name, and unknown types, must not
+      // pass an invalid `type` through to Claude.
+      expect(choiceOf({ type: "function", function: {} })).toEqual({ type: "auto" });
+      expect(choiceOf({ type: "function" })).toEqual({ type: "auto" });
+      expect(choiceOf({ type: "bogus" })).toEqual({ type: "auto" });
+    });
+
+    it("omits tool_choice entirely when the request has none", () => {
+      const result = openaiToClaudeRequest("claude-sonnet-4.5", baseBody, false);
+      expect(result.tool_choice).toBeUndefined();
+    });
+  });
+});
+
+describe("openaiToClaudeResponse", () => {
+  it("omits empty Read pages tool argument before emitting Claude input deltas", () => {
+    const state = { toolCalls: new Map() };
+    const chunk = {
+      id: "chatcmpl-test",
+      model: "gpt-test",
+      choices: [{
+        delta: {
+          tool_calls: [{
+            index: 0,
+            id: "call_read",
+            function: {
+              name: "Read",
+              arguments: JSON.stringify({
+                file_path: "/tmp/example.txt",
+                offset: 0,
+                limit: 120,
+                pages: ""
+              })
+            }
+          }]
+        }
+      }]
+    };
+
+    const result = openaiToClaudeResponse(chunk, state);
+    const inputDelta = result.find(event => event.delta?.type === "input_json_delta");
+
+    expect(inputDelta).toBeDefined();
+    expect(JSON.parse(inputDelta.delta.partial_json)).toEqual({
+      file_path: "/tmp/example.txt",
+      offset: 0,
+      limit: 120
+    });
+  });
+});
diff --git a/tests/unit/openai-to-commandcode.test.js b/tests/unit/openai-to-commandcode.test.js
new file mode 100644
index 0000000..7f12dc8
--- /dev/null
+++ b/tests/unit/openai-to-commandcode.test.js
@@ -0,0 +1,181 @@
+/**
+ * Unit tests for open-sse/translator/request/openai-to-commandcode.js
+ *
+ * Verified live against upstream `/alpha/generate` (curl, 2026-05-07):
+ *  - params.system: STRING at top level (Anthropic-style; "system" role NOT in messages[])
+ *  - params.messages[*].role ∈ {"user","assistant","tool"}
+ *  - params.messages[*].content: Array<content_block> (NEVER string)
+ *  - tools[*]: Anthropic plain {name, description, input_schema}
+ */
+
+import { describe, it, expect } from "vitest";
+import { openaiToCommandCodeRequest } from "../../open-sse/translator/request/openai-to-commandcode.js";
+
+const MODEL = "moonshotai/Kimi-K2.6";
+
+describe("openaiToCommandCodeRequest — basic envelope", () => {
+  it("returns the expected top-level envelope shape", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [{ role: "user", content: "hi" }],
+    }, true);
+
+    expect(out).toHaveProperty("threadId");
+    expect(out).toHaveProperty("memory");
+    expect(out).toHaveProperty("config");
+    expect(out).toHaveProperty("params");
+    expect(out.params.model).toBe(MODEL);
+    expect(out.params.stream).toBe(true);
+  });
+});
+
+describe("openaiToCommandCodeRequest — system handling", () => {
+  it("hoists system messages to params.system (string), not messages[]", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [
+        { role: "system", content: "You are concise." },
+        { role: "user", content: "hi" },
+      ],
+    }, true);
+
+    expect(typeof out.params.system).toBe("string");
+    expect(out.params.system).toBe("You are concise.");
+    const roles = out.params.messages.map((m) => m.role);
+    expect(roles).not.toContain("system");
+  });
+
+  it("joins multiple system messages with blank line", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [
+        { role: "system", content: "A" },
+        { role: "system", content: "B" },
+        { role: "user", content: "hi" },
+      ],
+    }, true);
+
+    expect(out.params.system).toBe("A\n\nB");
+  });
+
+  it("omits params.system when no system messages", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [{ role: "user", content: "hi" }],
+    }, true);
+    expect(out.params.system).toBeUndefined();
+  });
+});
+
+describe("openaiToCommandCodeRequest — content shape", () => {
+  it("MUST always emit content as Array (never string) for user", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [{ role: "user", content: "hello" }],
+    }, true);
+
+    const u = out.params.messages[0];
+    expect(Array.isArray(u.content)).toBe(true);
+    expect(u.content[0]).toEqual({ type: "text", text: "hello" });
+  });
+
+  it("MUST always emit content as Array for assistant", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [
+        { role: "user", content: "a" },
+        { role: "assistant", content: "b" },
+      ],
+    }, true);
+    const a = out.params.messages[1];
+    expect(Array.isArray(a.content)).toBe(true);
+    expect(a.content[0]).toEqual({ type: "text", text: "b" });
+  });
+});
+
+describe("openaiToCommandCodeRequest — tool role / tool-result (AI SDK)", () => {
+  it("converts role:\"tool\" to role:\"tool\" with tool-result block; output is {type:\"text\",value}", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [
+        { role: "user", content: "run X" },
+        {
+          role: "assistant",
+          content: null,
+          tool_calls: [
+            { id: "call_1", type: "function", function: { name: "do_x", arguments: "{\"a\":1}" } },
+          ],
+        },
+        { role: "tool", tool_call_id: "call_1", name: "do_x", content: "RESULT_OK" },
+      ],
+    }, true);
+
+    const toolMsg = out.params.messages[out.params.messages.length - 1];
+    expect(toolMsg.role).toBe("tool");
+    const block = toolMsg.content[0];
+    expect(block.type).toBe("tool-result");
+    expect(block.toolCallId).toBe("call_1");
+    expect(block.toolName).toBe("do_x");
+    expect(block.output).toEqual({ type: "text", value: "RESULT_OK" });
+  });
+});
+
+describe("openaiToCommandCodeRequest — assistant tool_calls / tool-call", () => {
+  it("converts assistant.tool_calls[] into content blocks of type tool-call", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [
+        { role: "user", content: "go" },
+        {
+          role: "assistant",
+          content: null,
+          tool_calls: [
+            { id: "call_42", type: "function", function: { name: "search", arguments: "{\"q\":\"hi\"}" } },
+          ],
+        },
+      ],
+    }, true);
+
+    const asst = out.params.messages[1];
+    expect(asst.role).toBe("assistant");
+    const tc = asst.content.find((b) => b.type === "tool-call");
+    expect(tc).toBeDefined();
+    expect(tc.toolCallId).toBe("call_42");
+    expect(tc.toolName).toBe("search");
+    expect(tc.input).toEqual({ q: "hi" });
+  });
+});
+
+describe("openaiToCommandCodeRequest — tools schema conversion", () => {
+  it("converts OpenAI {type:\"function\", function:{...}} to Anthropic plain {name, input_schema}", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [{ role: "user", content: "hi" }],
+      tools: [
+        {
+          type: "function",
+          function: {
+            name: "weather",
+            description: "Get weather",
+            parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
+          },
+        },
+      ],
+    }, true);
+
+    const t = out.params.tools[0];
+    expect(t.name).toBe("weather");
+    expect(t.input_schema).toBeDefined();
+    expect(t.input_schema.type).toBe("object");
+    expect(t.function).toBeUndefined();
+    expect(t.parameters).toBeUndefined();
+  });
+
+  it("preserves description on converted tool", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [{ role: "user", content: "hi" }],
+      tools: [
+        { type: "function", function: { name: "ping", description: "Ping the server", parameters: { type: "object" } } },
+      ],
+    }, true);
+    expect(out.params.tools[0].description).toBe("Ping the server");
+  });
+
+  it("does not include tools field when input has none", () => {
+    const out = openaiToCommandCodeRequest(MODEL, {
+      messages: [{ role: "user", content: "hi" }],
+    }, true);
+    expect(out.params.tools).toBeUndefined();
+  });
+});
diff --git a/tests/unit/openai-to-kiro.test.js b/tests/unit/openai-to-kiro.test.js
new file mode 100644
index 0000000..ddda87a
--- /dev/null
+++ b/tests/unit/openai-to-kiro.test.js
@@ -0,0 +1,365 @@
+/**
+ * Unit tests for open-sse/translator/request/openai-to-kiro.js
+ *
+ * Tests cover:
+ *  - openaiToKiroRequest() - basic message conversion
+ *  - Image forwarding fix: images in currentMessage must be included in payload
+ */
+
+import { describe, it, expect } from "vitest";
+import { openaiToKiroRequest } from "../../open-sse/translator/request/openai-to-kiro.js";
+
+const contentOf = (result) =>
+  result.conversationState.currentMessage.userInputMessage.content;
+
+describe("openaiToKiroRequest", () => {
+  describe("basic message conversion", () => {
+    it("should convert a simple text message", () => {
+      const body = {
+        messages: [{ role: "user", content: "Hello" }]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      const currentMsg = result.conversationState.currentMessage;
+      expect(currentMsg.userInputMessage.content).toContain("Hello");
+      expect(currentMsg.userInputMessage.modelId).toBe("claude-sonnet-4.6");
+      expect(currentMsg.userInputMessage.origin).toBe("AI_EDITOR");
+    });
+
+    it("should not include images field when no images are present", () => {
+      const body = {
+        messages: [{ role: "user", content: "No images here" }]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      const currentMsg = result.conversationState.currentMessage;
+      expect(currentMsg.userInputMessage.images).toBeUndefined();
+    });
+  });
+
+  describe("image forwarding", () => {
+    it("should forward base64 image from image_url content part", () => {
+      const fakeBase64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
+      const body = {
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "text", text: "Describe this image" },
+              { type: "image_url", image_url: { url: `data:image/png;base64,${fakeBase64}` } }
+            ]
+          }
+        ]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      const currentMsg = result.conversationState.currentMessage;
+      expect(currentMsg.userInputMessage.images).toBeDefined();
+      expect(currentMsg.userInputMessage.images).toHaveLength(1);
+      expect(currentMsg.userInputMessage.images[0].format).toBe("png");
+      expect(currentMsg.userInputMessage.images[0].source.bytes).toBe(fakeBase64);
+    });
+
+    it("should forward multiple base64 images", () => {
+      const fakeBase64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
+      const body = {
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "text", text: "Compare these images" },
+              { type: "image_url", image_url: { url: `data:image/jpeg;base64,${fakeBase64}` } },
+              { type: "image_url", image_url: { url: `data:image/png;base64,${fakeBase64}` } }
+            ]
+          }
+        ]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      const currentMsg = result.conversationState.currentMessage;
+      expect(currentMsg.userInputMessage.images).toHaveLength(2);
+      expect(currentMsg.userInputMessage.images[0].format).toBe("jpeg");
+      expect(currentMsg.userInputMessage.images[1].format).toBe("png");
+    });
+
+    it("should not include images field when images array is empty", () => {
+      const body = {
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "text", text: "Just text" }
+            ]
+          }
+        ]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      const currentMsg = result.conversationState.currentMessage;
+      expect(currentMsg.userInputMessage.images).toBeUndefined();
+    });
+
+    it("should include both images and text content together", () => {
+      const fakeBase64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
+      const body = {
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "text", text: "What is in this image?" },
+              { type: "image_url", image_url: { url: `data:image/jpeg;base64,${fakeBase64}` } }
+            ]
+          }
+        ]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      const currentMsg = result.conversationState.currentMessage;
+      expect(currentMsg.userInputMessage.content).toContain("What is in this image?");
+      expect(currentMsg.userInputMessage.images).toHaveLength(1);
+    });
+
+    it("should treat http image URLs as text fallback (Kiro only supports base64)", () => {
+      const body = {
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "text", text: "Look at this" },
+              { type: "image_url", image_url: { url: "https://example.com/photo.jpg" } }
+            ]
+          }
+        ]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      const currentMsg = result.conversationState.currentMessage;
+      // HTTP URLs are not supported by Kiro — converted to text placeholder
+      expect(currentMsg.userInputMessage.images).toBeUndefined();
+      expect(currentMsg.userInputMessage.content).toContain("[Image: https://example.com/photo.jpg]");
+    });
+  });
+
+  describe("tool interaction without client-provided tools", () => {
+    // When the client omits `tools` (e.g. after compaction), structured tool
+    // content must be flattened to text so Kiro's "tools required" 400 never
+    // fires and no phantom tool-calling capability is advertised.
+
+    it("should flatten OpenAI tool_calls + tool result into history text with no tools array", () => {
+      const body = {
+        messages: [
+          { role: "user", content: "Read the file" },
+          {
+            role: "assistant",
+            content: null,
+            tool_calls: [
+              { id: "call_1", type: "function", function: { name: "read_file", arguments: '{"path":"a.txt"}' } }
+            ]
+          },
+          { role: "tool", tool_call_id: "call_1", content: "file contents here" },
+          { role: "user", content: "Summarize it" }
+        ]
+        // note: no `tools`
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+      const cs = result.conversationState;
+
+      // No structured tool content anywhere
+      expect(cs.currentMessage.userInputMessage.userInputMessageContext).toBeUndefined();
+      const allJson = JSON.stringify(cs);
+      expect(allJson).not.toContain("toolUses");
+      expect(allJson).not.toContain("toolResults");
+
+      // Tool call + result preserved as readable text (call lands in history,
+      // result merges into the final currentMessage — assert across both)
+      expect(allJson).toContain("[Tool call: read_file(");
+      expect(allJson).toContain("[Tool result: file contents here]");
+    });
+
+    it("should flatten Claude tool_use / tool_result blocks with no tools array", () => {
+      const body = {
+        messages: [
+          { role: "user", content: "Do it" },
+          {
+            role: "assistant",
+            content: [
+              { type: "text", text: "Calling tool" },
+              { type: "tool_use", id: "tu_1", name: "search", input: { q: "kiro" } }
+            ]
+          },
+          {
+            role: "user",
+            content: [
+              { type: "tool_result", tool_use_id: "tu_1", content: "result text" }
+            ]
+          }
+        ]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+      const cs = result.conversationState;
+
+      const allJson = JSON.stringify(cs);
+      expect(allJson).not.toContain("toolUses");
+      expect(allJson).not.toContain("toolResults");
+      expect(allJson).toContain("[Tool call: search(");
+      expect(allJson).toContain("[Tool result: result text]");
+    });
+
+    it("should keep structured tools when the client DOES provide a tools array", () => {
+      const body = {
+        messages: [
+          { role: "user", content: "Read the file" },
+          {
+            role: "assistant",
+            content: null,
+            tool_calls: [
+              { id: "call_1", type: "function", function: { name: "read_file", arguments: '{"path":"a.txt"}' } }
+            ]
+          },
+          { role: "tool", tool_call_id: "call_1", content: "file contents here" },
+          { role: "user", content: "Summarize it" }
+        ],
+        tools: [
+          {
+            type: "function",
+            function: { name: "read_file", description: "Read a file", parameters: { type: "object", properties: { path: { type: "string" } }, required: ["path"] } }
+          }
+        ]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+      const cs = result.conversationState;
+
+      // Structured tool spec carried on currentMessage
+      const tools = cs.currentMessage.userInputMessage.userInputMessageContext?.tools;
+      expect(tools).toBeDefined();
+      expect(tools[0].toolSpecification.name).toBe("read_file");
+
+      // Structured tool history preserved (not flattened to text)
+      const allJson = JSON.stringify(cs);
+      expect(allJson).toContain("toolUses");
+      expect(allJson).not.toContain("[Tool call:");
+    });
+
+    it("should salvage orphaned tool_result content as text instead of discarding it", () => {
+      // Client provides tools, but compaction removed the assistant tool_use
+      // message, leaving a tool_result whose tool_use_id matches nothing.
+      const body = {
+        messages: [
+          { role: "user", content: "Start" },
+          // (assistant tool_use for "orphan_call" was compacted away)
+          {
+            role: "user",
+            content: [
+              { type: "tool_result", tool_use_id: "orphan_call", content: "important orphaned output" }
+            ]
+          },
+          { role: "user", content: "Now continue" }
+        ],
+        tools: [
+          {
+            type: "function",
+            function: { name: "some_tool", description: "x", parameters: { type: "object", properties: {}, required: [] } }
+          }
+        ]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+      const cs = result.conversationState;
+      const allJson = JSON.stringify(cs);
+
+      // The dangling structured reference is gone (would trigger Kiro 400)...
+      expect(allJson).not.toContain("orphan_call");
+      // ...but the content is preserved as salvaged text, not discarded.
+      expect(allJson).toContain("[Tool result: important orphaned output]");
+    });
+  });
+
+  describe("thinking budget", () => {
+    it("maps reasoning_effort low to max_thinking_length 1024", () => {
+      const body = {
+        reasoning_effort: "low",
+        messages: [{ role: "user", content: "Think lightly" }]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      expect(contentOf(result)).toContain("<max_thinking_length>1024</max_thinking_length>");
+    });
+
+    it("maps reasoning_effort high to max_thinking_length 24576", () => {
+      const body = {
+        reasoning_effort: "high",
+        messages: [{ role: "user", content: "Think deeply" }]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      expect(contentOf(result)).toContain("<max_thinking_length>24576</max_thinking_length>");
+    });
+
+    it("clamps reasoning_effort max to Kiro max_thinking_length 32000", () => {
+      const body = {
+        reasoning_effort: "max",
+        messages: [{ role: "user", content: "Think as much as possible" }]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      expect(contentOf(result)).toContain("<max_thinking_length>32000</max_thinking_length>");
+    });
+
+    it("clamps OpenAI Responses reasoning.effort xhigh to max_thinking_length 32000", () => {
+      const body = {
+        reasoning: { effort: "xhigh" },
+        messages: [{ role: "user", content: "Think extra deeply" }]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      expect(contentOf(result)).toContain("<max_thinking_length>32000</max_thinking_length>");
+    });
+
+    it("uses Claude thinking.budget_tokens as max_thinking_length", () => {
+      const body = {
+        thinking: { type: "enabled", budget_tokens: 4096 },
+        messages: [{ role: "user", content: "Use a fixed budget" }]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      expect(contentOf(result)).toContain("<max_thinking_length>4096</max_thinking_length>");
+    });
+
+    it("uses the default budget for synthetic -thinking models with no explicit config", () => {
+      const body = {
+        messages: [{ role: "user", content: "Think by model suffix" }]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6-thinking", body, true, {});
+
+      expect(contentOf(result)).toContain("<max_thinking_length>16000</max_thinking_length>");
+    });
+
+    it("does not inject thinking prefix for reasoning_effort none", () => {
+      const body = {
+        reasoning_effort: "none",
+        messages: [{ role: "user", content: "Do not think" }]
+      };
+
+      const result = openaiToKiroRequest("claude-sonnet-4.6", body, true, {});
+
+      expect(contentOf(result)).not.toContain("<thinking_mode>enabled</thinking_mode>");
+      expect(contentOf(result)).not.toContain("<max_thinking_length>");
+    });
+  });
+});
diff --git a/tests/unit/openai-to-ollama-malformed.test.js b/tests/unit/openai-to-ollama-malformed.test.js
new file mode 100644
index 0000000..064731c
--- /dev/null
+++ b/tests/unit/openai-to-ollama-malformed.test.js
@@ -0,0 +1,30 @@
+// A4 (case #10): malformed tool_calls args must not throw -> safeParseJSON returns {}.
+import { describe, it, expect } from "vitest";
+import { openaiToOllamaRequest } from "../../open-sse/translator/request/openai-to-ollama.js";
+
+function reqWith(args) {
+  return {
+    messages: [
+      {
+        role: "assistant",
+        content: "",
+        tool_calls: [{ id: "c1", type: "function", function: { name: "get_weather", arguments: args } }],
+      },
+    ],
+  };
+}
+
+describe("openaiToOllamaRequest - tool_calls arguments parsing", () => {
+  it("malformed JSON args -> {} (no throw)", () => {
+    let out;
+    expect(() => {
+      out = openaiToOllamaRequest("m", reqWith("{invalid json"), true);
+    }).not.toThrow();
+    expect(out.messages[0].tool_calls[0].function.arguments).toEqual({});
+  });
+
+  it("valid JSON args -> parsed object", () => {
+    const out = openaiToOllamaRequest("m", reqWith('{"a":1}'), true);
+    expect(out.messages[0].tool_calls[0].function.arguments).toEqual({ a: 1 });
+  });
+});
diff --git a/tests/unit/opencode-go-models.test.js b/tests/unit/opencode-go-models.test.js
new file mode 100644
index 0000000..10946ab
--- /dev/null
+++ b/tests/unit/opencode-go-models.test.js
@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { PROVIDER_MODELS, getModelTargetFormat } from "../../open-sse/config/providerModels.js";
+import { OpenCodeGoExecutor } from "../../open-sse/executors/opencode-go.js";
+
+const CHAT_MODELS = [
+  "glm-5.2",
+  "glm-5.1",
+  // OpenCode Go docs' endpoint table currently says kimi-k2.7, but its
+  // config example and the live API use kimi-k2.7-code.
+  "kimi-k2.7-code",
+  "kimi-k2.6",
+  "deepseek-v4-pro",
+  "deepseek-v4-flash",
+  "mimo-v2.5",
+  "mimo-v2.5-pro",
+];
+
+const MESSAGES_MODELS = [
+  "minimax-m3",
+  "minimax-m2.7",
+  "minimax-m2.5",
+  "qwen3.7-max",
+  "qwen3.7-plus",
+  "qwen3.6-plus",
+];
+
+describe("OpenCode Go official model catalog", () => {
+  it("matches the documented OpenCode Go model IDs", () => {
+    const ids = (PROVIDER_MODELS["opencode-go"] || []).map((model) => model.id);
+
+    expect(ids).toEqual([...CHAT_MODELS, ...MESSAGES_MODELS]);
+  });
+
+  it("marks documented Qwen and MiniMax models as Anthropic messages format", () => {
+    for (const model of MESSAGES_MODELS) {
+      expect(getModelTargetFormat("opencode-go", model)).toBe("claude");
+    }
+  });
+
+  it("keeps GLM, Kimi, DeepSeek, and MiMo on OpenAI-compatible chat format", () => {
+    for (const model of CHAT_MODELS) {
+      expect(getModelTargetFormat("opencode-go", model)).toBeNull();
+    }
+  });
+});
+
+describe("OpenCode Go endpoint routing", () => {
+  it("routes Qwen and MiniMax models to the messages endpoint with x-api-key auth", () => {
+    const executor = new OpenCodeGoExecutor();
+
+    for (const model of MESSAGES_MODELS) {
+      expect(executor.buildUrl(model)).toBe("https://opencode.ai/zen/go/v1/messages");
+      const headers = executor.buildHeaders({ apiKey: "sk-test" }, false);
+      expect(headers["x-api-key"]).toBe("sk-test");
+      expect(headers["anthropic-version"]).toBeDefined();
+      expect(headers.Authorization).toBeUndefined();
+    }
+  });
+
+  it("routes GLM, Kimi, DeepSeek, and MiMo models to chat/completions with bearer auth", () => {
+    const executor = new OpenCodeGoExecutor();
+
+    for (const model of CHAT_MODELS) {
+      expect(executor.buildUrl(model)).toBe("https://opencode.ai/zen/go/v1/chat/completions");
+      const headers = executor.buildHeaders({ apiKey: "sk-test" }, false);
+      expect(headers.Authorization).toBe("Bearer sk-test");
+      expect(headers["x-api-key"]).toBeUndefined();
+      expect(headers["anthropic-version"]).toBeUndefined();
+    }
+  });
+});
diff --git a/tests/unit/param-support.test.js b/tests/unit/param-support.test.js
new file mode 100644
index 0000000..c54d132
--- /dev/null
+++ b/tests/unit/param-support.test.js
@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+
+import { stripUnsupportedParams } from "../../open-sse/translator/concerns/paramSupport.js";
+
+describe("stripUnsupportedParams", () => {
+  it("flattens Cloudflare AI OpenAI content-part arrays", () => {
+    const body = {
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: "hello " },
+            { type: "image_url", image_url: { url: "data:image/png;base64,xx" } },
+            { type: "text", text: "world" },
+          ],
+        },
+      ],
+    };
+
+    expect(() => stripUnsupportedParams("cloudflare-ai", "@cf/meta/llama-3.1-8b-instruct", body)).not.toThrow();
+    expect(body.messages[0].content).toBe("hello world");
+  });
+
+  it("still drops unsupported GitHub model params", () => {
+    const body = { temperature: 0.7, top_p: 1 };
+
+    stripUnsupportedParams("github", "gpt-5.4", body);
+
+    expect(body).toEqual({ top_p: 1 });
+  });
+
+  it("clamps VolcEngine Ark GLM max token fields to the model output ceiling", () => {
+    const body = {
+      max_tokens: 131072,
+      max_completion_tokens: 131072,
+      max_output_tokens: 131072,
+    };
+
+    stripUnsupportedParams("volcengine-ark", "GLM-5.2", body);
+
+    expect(body).toEqual({
+      max_tokens: 128000,
+      max_completion_tokens: 128000,
+      max_output_tokens: 128000,
+    });
+  });
+
+  it("keeps VolcEngine Ark GLM max tokens when already under the ceiling", () => {
+    const body = { max_tokens: 64000 };
+
+    stripUnsupportedParams("volcengine-ark", "GLM-5.2", body);
+
+    expect(body.max_tokens).toBe(64000);
+  });
+});
diff --git a/tests/unit/perplexity-web.test.js b/tests/unit/perplexity-web.test.js
new file mode 100644
index 0000000..0b1a415
--- /dev/null
+++ b/tests/unit/perplexity-web.test.js
@@ -0,0 +1,306 @@
+/**
+ * Unit tests for perplexity-web executor
+ *
+ * Covers:
+ *  - Message parsing (system/user/assistant/developer, multi-part content)
+ *  - Query building for first turn vs follow-up (session continuity)
+ *  - Tools injection into instructions
+ *  - Request body shape (dual query_str top-level + params.query_str is required by upstream)
+ *  - Auth header construction (apiKey → Cookie, accessToken → Bearer)
+ *  - Model mapping (normal + thinking)
+ *  - Error handling (401, 429)
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  parseOpenAIMessages,
+  buildQuery,
+  buildPplxRequestBody,
+  formatToolsHint,
+  PerplexityWebExecutor,
+} from "../../open-sse/executors/perplexity-web.js";
+
+const originalFetch = global.fetch;
+
+function mockPplxStream(events) {
+  const chunks = events.map((e) => `data: ${JSON.stringify(e)}\n\n`).join("") + "data: [DONE]\n\n";
+  return new Response(new Blob([chunks]).stream(), {
+    status: 200,
+    headers: { "Content-Type": "text/event-stream" },
+  });
+}
+
+describe("parseOpenAIMessages", () => {
+  it("extracts system + history + current msg", () => {
+    const parsed = parseOpenAIMessages([
+      { role: "system", content: "Be helpful" },
+      { role: "user", content: "Q1" },
+      { role: "assistant", content: "A1" },
+      { role: "user", content: "Q2" },
+    ]);
+    expect(parsed.systemMsg.trim()).toBe("Be helpful");
+    expect(parsed.history).toEqual([
+      { role: "user", content: "Q1" },
+      { role: "assistant", content: "A1" },
+    ]);
+    expect(parsed.currentMsg).toBe("Q2");
+  });
+
+  it("treats developer role as system", () => {
+    const parsed = parseOpenAIMessages([
+      { role: "developer", content: "Be concise" },
+      { role: "user", content: "hi" },
+    ]);
+    expect(parsed.systemMsg.trim()).toBe("Be concise");
+    expect(parsed.currentMsg).toBe("hi");
+  });
+
+  it("handles multi-part content (array of text blocks)", () => {
+    const parsed = parseOpenAIMessages([
+      { role: "user", content: [{ type: "text", text: "part1" }, { type: "text", text: "part2" }] },
+    ]);
+    expect(parsed.currentMsg).toBe("part1 part2");
+  });
+
+  it("skips empty content messages", () => {
+    const parsed = parseOpenAIMessages([
+      { role: "user", content: "   " },
+      { role: "user", content: "real" },
+    ]);
+    expect(parsed.currentMsg).toBe("real");
+  });
+});
+
+describe("buildQuery", () => {
+  it("first turn: returns JSON with instructions + query", () => {
+    const parsed = { systemMsg: "Be helpful\n", history: [], currentMsg: "Hello" };
+    const q = buildQuery(parsed, null);
+    const obj = JSON.parse(q);
+    expect(obj.query).toBe("Hello");
+    expect(obj.instructions).toContain("Be helpful");
+    expect(obj.instructions.some((s) => s.includes("web search"))).toBe(true);
+  });
+
+  it("follow-up (with backendUuid): returns plain currentMsg, no JSON", () => {
+    const parsed = {
+      systemMsg: "Be helpful",
+      history: [{ role: "user", content: "Q1" }, { role: "assistant", content: "A1" }],
+      currentMsg: "Follow up",
+    };
+    const q = buildQuery(parsed, "uuid-abc-123");
+    expect(q).toBe("Follow up");
+  });
+
+  it("includes history when present on first turn", () => {
+    const parsed = {
+      systemMsg: "",
+      history: [{ role: "user", content: "earlier" }],
+      currentMsg: "now",
+    };
+    const obj = JSON.parse(buildQuery(parsed, null));
+    expect(obj.history).toEqual([{ role: "user", content: "earlier" }]);
+    expect(obj.query).toBe("now");
+  });
+
+  it("injects tools into instructions on first turn", () => {
+    const parsed = { systemMsg: "", history: [], currentMsg: "hi" };
+    const tools = [
+      { function: { name: "Shell", description: "Run bash" } },
+      { function: { name: "Read", description: "Read file" } },
+    ];
+    const obj = JSON.parse(buildQuery(parsed, null, tools));
+    const hint = obj.instructions.find((s) => s.includes("Available tools"));
+    expect(hint).toBeDefined();
+    expect(hint).toContain("- Shell: Run bash");
+    expect(hint).toContain("- Read: Read file");
+  });
+
+  it("ignores tools on follow-up turn (uses session)", () => {
+    const parsed = { systemMsg: "", history: [{ role: "user", content: "x" }], currentMsg: "y" };
+    const tools = [{ function: { name: "Shell", description: "d" } }];
+    const q = buildQuery(parsed, "uuid", tools);
+    expect(q).toBe("y");
+  });
+
+  it("truncates query if JSON exceeds 96000 chars", () => {
+    const big = "x".repeat(100000);
+    const parsed = { systemMsg: big, history: [], currentMsg: "hi" };
+    const q = buildQuery(parsed, null);
+    expect(q.length).toBeLessThanOrEqual(96000);
+  });
+});
+
+describe("formatToolsHint", () => {
+  it("returns empty string for no tools", () => {
+    expect(formatToolsHint()).toBe("");
+    expect(formatToolsHint([])).toBe("");
+  });
+
+  it("handles OpenAI tool schema (function wrapper)", () => {
+    const out = formatToolsHint([{ function: { name: "Foo", description: "does foo" } }]);
+    expect(out).toContain("- Foo: does foo");
+  });
+
+  it("handles flat tool schema", () => {
+    const out = formatToolsHint([{ name: "Bar", description: "does bar" }]);
+    expect(out).toContain("- Bar: does bar");
+  });
+
+  it("truncates long descriptions to first line, max 200 chars", () => {
+    const longDesc = "line1\nline2\nline3";
+    const out = formatToolsHint([{ function: { name: "X", description: longDesc } }]);
+    expect(out).toContain("- X: line1");
+    expect(out).not.toContain("line2");
+  });
+});
+
+describe("buildPplxRequestBody", () => {
+  it("sets query_str at both top-level AND params (required by upstream API)", () => {
+    const body = buildPplxRequestBody("hello world", "concise", "pplx_pro", null);
+    expect(body.query_str).toBe("hello world");
+    expect(body.params.query_str).toBe("hello world");
+  });
+
+  it("includes required params", () => {
+    const body = buildPplxRequestBody("q", "copilot", "claude46sonnet", "uuid-xyz");
+    expect(body.params.search_focus).toBe("internet");
+    expect(body.params.mode).toBe("copilot");
+    expect(body.params.model_preference).toBe("claude46sonnet");
+    expect(body.params.sources).toEqual(["web"]);
+    expect(body.params.use_schematized_api).toBe(true);
+    expect(body.params.is_incognito).toBe(true);
+    expect(body.params.last_backend_uuid).toBe("uuid-xyz");
+    expect(body.params.version).toBe("2.18");
+  });
+});
+
+describe("PerplexityWebExecutor.execute", () => {
+  let capturedUrl;
+  let capturedOpts;
+  let capturedBody;
+
+  beforeEach(() => {
+    capturedUrl = null;
+    capturedOpts = null;
+    capturedBody = null;
+    global.fetch = vi.fn(async (url, opts) => {
+      capturedUrl = url;
+      capturedOpts = opts;
+      capturedBody = JSON.parse(opts.body);
+      return mockPplxStream([
+        {
+          blocks: [{ intended_usage: "markdown", markdown_block: { chunks: ["answer"], progress: "DONE" } }],
+          status: "COMPLETED",
+          backend_uuid: "resp-uuid-1",
+        },
+      ]);
+    });
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("maps pplx-auto → mode=concise, pref=pplx_pro", async () => {
+    const exec = new PerplexityWebExecutor();
+    await exec.execute({
+      model: "pplx-auto",
+      body: { messages: [{ role: "user", content: "hi" }], stream: false },
+      stream: false,
+      credentials: { apiKey: "cookie-abc" },
+    });
+    expect(capturedBody.params.mode).toBe("concise");
+    expect(capturedBody.params.model_preference).toBe("pplx_pro");
+  });
+
+  it("applies THINKING_MAP when reasoning_effort is set", async () => {
+    const exec = new PerplexityWebExecutor();
+    await exec.execute({
+      model: "pplx-opus",
+      body: { messages: [{ role: "user", content: "hi" }], stream: false, reasoning_effort: "high" },
+      stream: false,
+      credentials: { apiKey: "cookie-abc" },
+    });
+    expect(capturedBody.params.mode).toBe("copilot");
+    expect(capturedBody.params.model_preference).toBe("claude46opusthinking");
+  });
+
+  it("sends Cookie header when credentials.apiKey provided", async () => {
+    const exec = new PerplexityWebExecutor();
+    await exec.execute({
+      model: "pplx-auto",
+      body: { messages: [{ role: "user", content: "hi" }], stream: false },
+      stream: false,
+      credentials: { apiKey: "my-session-token" },
+    });
+    expect(capturedOpts.headers.Cookie).toBe("__Secure-next-auth.session-token=my-session-token");
+    expect(capturedOpts.headers.Authorization).toBeUndefined();
+  });
+
+  it("sends Bearer header when credentials.accessToken provided", async () => {
+    const exec = new PerplexityWebExecutor();
+    await exec.execute({
+      model: "pplx-auto",
+      body: { messages: [{ role: "user", content: "hi" }], stream: false },
+      stream: false,
+      credentials: { accessToken: "tok-1" },
+    });
+    expect(capturedOpts.headers.Authorization).toBe("Bearer tok-1");
+  });
+
+  it("injects body.tools into query_str instructions", async () => {
+    const exec = new PerplexityWebExecutor();
+    await exec.execute({
+      model: "pplx-auto",
+      body: {
+        messages: [{ role: "user", content: "what tools do you have?" }],
+        tools: [{ function: { name: "Shell", description: "Execute commands" } }],
+        stream: false,
+      },
+      stream: false,
+      credentials: { apiKey: "c" },
+    });
+    const queryObj = JSON.parse(capturedBody.query_str);
+    const toolsHint = queryObj.instructions.find((s) => s.includes("Available tools"));
+    expect(toolsHint).toContain("- Shell: Execute commands");
+  });
+
+  it("returns 400 on missing messages", async () => {
+    const exec = new PerplexityWebExecutor();
+    const { response } = await exec.execute({
+      model: "pplx-auto",
+      body: {},
+      stream: false,
+      credentials: { apiKey: "c" },
+    });
+    expect(response.status).toBe(400);
+  });
+
+  it("surfaces upstream 401 with friendly auth message", async () => {
+    global.fetch = vi.fn(async () => new Response(JSON.stringify({ error: "bad" }), { status: 401 }));
+    const exec = new PerplexityWebExecutor();
+    const { response } = await exec.execute({
+      model: "pplx-auto",
+      body: { messages: [{ role: "user", content: "hi" }] },
+      stream: false,
+      credentials: { apiKey: "bad-cookie" },
+    });
+    expect(response.status).toBe(401);
+    const j = await response.json();
+    expect(j.error.message).toMatch(/auth failed|expired/i);
+  });
+
+  it("surfaces 429 with rate-limit message", async () => {
+    global.fetch = vi.fn(async () => new Response("", { status: 429 }));
+    const exec = new PerplexityWebExecutor();
+    const { response } = await exec.execute({
+      model: "pplx-auto",
+      body: { messages: [{ role: "user", content: "hi" }] },
+      stream: false,
+      credentials: { apiKey: "c" },
+    });
+    expect(response.status).toBe(429);
+    const j = await response.json();
+    expect(j.error.message).toMatch(/rate limited/i);
+  });
+});
diff --git a/tests/unit/prefetch-images.test.js b/tests/unit/prefetch-images.test.js
new file mode 100644
index 0000000..2289697
--- /dev/null
+++ b/tests/unit/prefetch-images.test.js
@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("../../open-sse/translator/concerns/image.js", async (orig) => {
+  const actual = await orig();
+  return {
+    ...actual,
+    fetchImageAsBase64: vi.fn(async () => ({ url: "data:image/png;base64,QUJD", mimeType: "image/png" })),
+  };
+});
+
+import { prefetchRemoteImages } from "../../open-sse/translator/concerns/prefetch.js";
+import { fetchImageAsBase64 } from "../../open-sse/translator/concerns/image.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+beforeEach(() => { fetchImageAsBase64.mockClear(); });
+afterEach(() => { vi.restoreAllMocks(); });
+
+describe("prefetchRemoteImages", () => {
+  it("no-op for targets that accept remote URLs (openai)", async () => {
+    const body = { messages: [{ role: "user", content: [{ type: "image_url", image_url: { url: "https://x/a.png" } }] }] };
+    const n = await prefetchRemoteImages(body, FORMATS.OPENAI, FORMATS.OPENAI);
+    expect(n).toBe(0);
+    expect(body.messages[0].content[0].image_url.url).toBe("https://x/a.png");
+  });
+
+  it("openai source -> ollama target: converts remote URL to base64", async () => {
+    const body = { messages: [{ role: "user", content: [{ type: "image_url", image_url: { url: "https://x/a.png" } }] }] };
+    const n = await prefetchRemoteImages(body, FORMATS.OPENAI, FORMATS.OLLAMA);
+    expect(n).toBe(1);
+    expect(body.messages[0].content[0].image_url.url.startsWith("data:image/png;base64,")).toBe(true);
+  });
+
+  it("skips data URI (already inline)", async () => {
+    const body = { messages: [{ role: "user", content: [{ type: "image_url", image_url: { url: "data:image/png;base64,xx" } }] }] };
+    const n = await prefetchRemoteImages(body, FORMATS.OPENAI, FORMATS.OLLAMA);
+    expect(n).toBe(0);
+    expect(fetchImageAsBase64).not.toHaveBeenCalled();
+  });
+
+  it("gemini source -> gemini target: fileData URL -> inlineData base64", async () => {
+    const body = { contents: [{ role: "user", parts: [
+      { fileData: { mimeType: "image/png", fileUri: "https://x/a.png" } },
+    ] }] };
+    const n = await prefetchRemoteImages(body, FORMATS.GEMINI, FORMATS.GEMINI);
+    expect(n).toBe(1);
+    expect(body.contents[0].parts[0].inlineData).toBeTruthy();
+    expect(body.contents[0].parts[0].fileData).toBeUndefined();
+  });
+
+  it("claude source -> kiro target: source.url -> base64", async () => {
+    const body = { messages: [{ role: "user", content: [
+      { type: "image", source: { type: "url", url: "https://x/a.png" } },
+    ] }] };
+    const n = await prefetchRemoteImages(body, FORMATS.CLAUDE, FORMATS.KIRO);
+    expect(n).toBe(1);
+    expect(body.messages[0].content[0].source.type).toBe("base64");
+  });
+});
diff --git a/tests/unit/provider-custom-models.test.js b/tests/unit/provider-custom-models.test.js
new file mode 100644
index 0000000..ef40120
--- /dev/null
+++ b/tests/unit/provider-custom-models.test.js
@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import { getProviderCustomModelRows } from "@/shared/utils/providerCustomModels.js";
+
+describe("provider custom model rows", () => {
+  it("keeps identical model IDs separate per provider", () => {
+    const customModels = [
+      { providerAlias: "ollama", id: "minimax-m2.5", type: "llm", name: "MiniMax M2.5" },
+      { providerAlias: "opencode-go", id: "minimax-m2.5", type: "llm", name: "MiniMax M2.5" },
+    ];
+
+    expect(getProviderCustomModelRows({ customModels, providerAlias: "ollama" })).toEqual([
+      {
+        id: "minimax-m2.5",
+        name: "MiniMax M2.5",
+        fullModel: "ollama/minimax-m2.5",
+        source: "custom",
+        type: "llm",
+      },
+    ]);
+    expect(getProviderCustomModelRows({ customModels, providerAlias: "opencode-go" })).toEqual([
+      {
+        id: "minimax-m2.5",
+        name: "MiniMax M2.5",
+        fullModel: "opencode-go/minimax-m2.5",
+        source: "custom",
+        type: "llm",
+      },
+    ]);
+  });
+
+  it("keeps legacy alias-backed models visible without duplicating custom models", () => {
+    const rows = getProviderCustomModelRows({
+      customModels: [
+        { providerAlias: "ollama", id: "custom-a", type: "llm", name: "Custom A" },
+      ],
+      modelAliases: {
+        "custom-a": "ollama/custom-a",
+        "legacy-b": "ollama/legacy-b",
+        "other-provider": "opencode-go/legacy-b",
+      },
+      providerAlias: "ollama",
+    });
+
+    expect(rows).toEqual([
+      {
+        id: "custom-a",
+        name: "Custom A",
+        fullModel: "ollama/custom-a",
+        source: "custom",
+        type: "llm",
+      },
+      {
+        id: "legacy-b",
+        alias: "legacy-b",
+        fullModel: "ollama/legacy-b",
+        source: "legacyAlias",
+        type: "llm",
+      },
+    ]);
+  });
+
+  it("filters built-in models and typed custom models", () => {
+    const rows = getProviderCustomModelRows({
+      customModels: [
+        { providerAlias: "ollama", id: "llama3", type: "llm", name: "Llama 3" },
+        { providerAlias: "ollama", id: "custom-image", type: "image", name: "Custom Image" },
+        { providerAlias: "ollama", id: "custom-llm", type: "llm", name: "Custom LLM" },
+      ],
+      providerAlias: "ollama",
+      builtInModels: [{ id: "llama3" }],
+      type: "llm",
+    });
+
+    expect(rows).toEqual([
+      {
+        id: "custom-llm",
+        name: "Custom LLM",
+        fullModel: "ollama/custom-llm",
+        source: "custom",
+        type: "llm",
+      },
+    ]);
+  });
+});
diff --git a/tests/unit/provider-display-split.test.js b/tests/unit/provider-display-split.test.js
new file mode 100644
index 0000000..e28963b
--- /dev/null
+++ b/tests/unit/provider-display-split.test.js
@@ -0,0 +1,34 @@
+// Guards E1: display fields live in providersDisplay.js, merged back into AI_PROVIDERS (shape unchanged).
+import { describe, it, expect } from "vitest";
+
+const DISPLAY_FIELDS = ["name", "icon", "color"];
+
+describe("provider display split (E1)", () => {
+  it("AI_PROVIDERS entries still carry merged display + transport", async () => {
+    const { AI_PROVIDERS } = await import("../../src/shared/constants/providers.js");
+    const kiro = AI_PROVIDERS.kiro;
+    // display merged
+    expect(kiro.name).toBe("Kiro AI");
+    expect(kiro.icon).toBe("psychology_alt");
+    // transport kept
+    expect(kiro.id).toBe("kiro");
+    expect(kiro.alias).toBe("kr");
+    // transport-heavy provider keeps its config
+    expect(AI_PROVIDERS.gemini.serviceKinds).toContain("tts");
+    expect(AI_PROVIDERS.gemini.ttsConfig).toBeTruthy();
+  });
+
+  it("display fields source from providersDisplay.js", async () => {
+    const { PROVIDER_DISPLAY } = await import("../../src/shared/constants/providersDisplay.js");
+    const { AI_PROVIDERS } = await import("../../src/shared/constants/providers.js");
+    for (const f of DISPLAY_FIELDS) {
+      expect(PROVIDER_DISPLAY.kiro[f]).toBe(AI_PROVIDERS.kiro[f]);
+    }
+  });
+
+  it("helpers still work after split", async () => {
+    const m = await import("../../src/shared/constants/providers.js");
+    expect(m.ALIAS_TO_ID.kr).toBe("kiro");
+    expect(m.getProvidersByKind("tts").length).toBeGreaterThan(0);
+  });
+});
diff --git a/tests/unit/provider-models-minimax-m3.test.js b/tests/unit/provider-models-minimax-m3.test.js
new file mode 100644
index 0000000..8ad55d1
--- /dev/null
+++ b/tests/unit/provider-models-minimax-m3.test.js
@@ -0,0 +1,52 @@
+/**
+ * Unit tests verifying MiniMax-M3 is registered as a first-class
+ * built-in model for both the `minimax` (international) and
+ * `minimax-cn` (China) providers, with `targetFormat: "claude"`.
+ *
+ * Run: cd tests && NODE_PATH=/tmp/node_modules /tmp/node_modules/.bin/vitest run tests/unit/provider-models-minimax-m3.test.js --reporter=verbose
+ */
+
+import { describe, it, expect } from "vitest";
+import { PROVIDER_MODELS, getModelsByProviderId } from "../../open-sse/config/providerModels.js";
+
+describe("MiniMax-M3 model registration", () => {
+  it("includes MiniMax-M3 in PROVIDER_MODELS.minimax", () => {
+    const models = PROVIDER_MODELS.minimax || [];
+    const m3 = models.find((m) => m.id === "MiniMax-M3");
+    expect(m3).toBeDefined();
+    expect(m3).toMatchObject({
+      id: "MiniMax-M3",
+      name: "MiniMax M3",
+      targetFormat: "claude",
+    });
+  });
+
+  it("includes MiniMax-M3 in PROVIDER_MODELS['minimax-cn']", () => {
+    const models = PROVIDER_MODELS["minimax-cn"] || [];
+    const m3 = models.find((m) => m.id === "MiniMax-M3");
+    expect(m3).toBeDefined();
+    expect(m3).toMatchObject({
+      id: "MiniMax-M3",
+      name: "MiniMax M3",
+      targetFormat: "claude",
+    });
+  });
+
+  it("exposes MiniMax-M3 through getModelsByProviderId for both provider IDs", () => {
+    const intlModels = getModelsByProviderId("minimax");
+    const cnModels = getModelsByProviderId("minimax-cn");
+
+    expect(intlModels.some((m) => m.id === "MiniMax-M3")).toBe(true);
+    expect(cnModels.some((m) => m.id === "MiniMax-M3")).toBe(true);
+  });
+
+  it("does not regress the existing M2.7 / M2.5 / M2.1 entries", () => {
+    const intlIds = (PROVIDER_MODELS.minimax || []).map((m) => m.id);
+    const cnIds = (PROVIDER_MODELS["minimax-cn"] || []).map((m) => m.id);
+
+    for (const id of ["MiniMax-M2.7", "MiniMax-M2.5", "MiniMax-M2.1"]) {
+      expect(intlIds).toContain(id);
+      expect(cnIds).toContain(id);
+    }
+  });
+});
diff --git a/tests/unit/provider-pricing-minimax-m3.test.js b/tests/unit/provider-pricing-minimax-m3.test.js
new file mode 100644
index 0000000..0f4ee93
--- /dev/null
+++ b/tests/unit/provider-pricing-minimax-m3.test.js
@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { MODEL_PRICING } from "../../open-sse/providers/pricing.js";
+
+describe("MiniMax-M3 pricing", () => {
+  it("includes MiniMax-M3 in MODEL_PRICING", () => {
+    expect(MODEL_PRICING["MiniMax-M3"]).toBeDefined();
+  });
+
+  it("MiniMax-M3 pricing has numeric shape (input, output, cached)", () => {
+    const pricing = MODEL_PRICING["MiniMax-M3"];
+    expect(pricing).toMatchObject({
+      input: expect.any(Number),
+      output: expect.any(Number),
+      cached: expect.any(Number),
+    });
+  });
+
+  it("MiniMax-M3 input price matches the design spec (0.30)", () => {
+    expect(MODEL_PRICING["MiniMax-M3"].input).toBe(0.30);
+  });
+
+  it("MiniMax-M3 output price matches the design spec (1.20)", () => {
+    expect(MODEL_PRICING["MiniMax-M3"].output).toBe(1.20);
+  });
+
+  it("MiniMax-M3 cached price matches the design spec (0.06)", () => {
+    expect(MODEL_PRICING["MiniMax-M3"].cached).toBe(0.06);
+  });
+});
\ No newline at end of file
diff --git a/tests/unit/provider-test-models-routing.test.js b/tests/unit/provider-test-models-routing.test.js
new file mode 100644
index 0000000..00f3a73
--- /dev/null
+++ b/tests/unit/provider-test-models-routing.test.js
@@ -0,0 +1,83 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  getProviderConnectionById: vi.fn(),
+  getApiKeys: vi.fn(),
+  getConsistentMachineId: vi.fn(),
+}));
+
+vi.mock("@/lib/localDb", () => ({
+  getProviderConnectionById: mocks.getProviderConnectionById,
+  getApiKeys: mocks.getApiKeys,
+}));
+
+vi.mock("@/shared/utils/machineId", () => ({
+  getConsistentMachineId: mocks.getConsistentMachineId,
+}));
+
+vi.mock("next/server", () => ({
+  NextResponse: {
+    json(body, init = {}) {
+      return new Response(JSON.stringify(body), {
+        status: init.status || 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    },
+  },
+}));
+
+const originalFetch = global.fetch;
+
+describe("provider test-models route kind routing", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getProviderConnectionById.mockResolvedValue({
+      id: "conn-hf",
+      provider: "huggingface",
+    });
+    mocks.getApiKeys.mockResolvedValue([{ key: "sk-internal", isActive: true }]);
+    mocks.getConsistentMachineId.mockResolvedValue("cli-token");
+    global.fetch = vi.fn((url) => {
+      if (String(url).includes("/api/v1/images/generations")) {
+        return Promise.resolve(new Response(JSON.stringify({
+          created: 1,
+          data: [{ b64_json: "abc" }],
+        }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }));
+      }
+      return Promise.resolve(new Response(JSON.stringify({
+        choices: [{ message: { role: "assistant", content: "ok" } }],
+      }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }));
+    });
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("routes huggingface image models to /api/v1/images/generations", async () => {
+    const { POST } = await import("../../src/app/api/providers/[id]/test-models/route.js");
+
+    const req = new Request("http://localhost/api/providers/conn-hf/test-models", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+    });
+
+    const res = await POST(req, { params: Promise.resolve({ id: "conn-hf" }) });
+    const body = await res.json();
+
+    expect(body.provider).toBe("huggingface");
+    expect(body.results.some((r) => r.modelId === "black-forest-labs/FLUX.1-schnell" && r.ok)).toBe(true);
+    expect(global.fetch).toHaveBeenCalledWith(
+      expect.stringContaining("/api/v1/images/generations"),
+      expect.objectContaining({
+        method: "POST",
+      })
+    );
+  });
+});
diff --git a/tests/unit/provider-thinking-config.test.js b/tests/unit/provider-thinking-config.test.js
new file mode 100644
index 0000000..d21cc6f
--- /dev/null
+++ b/tests/unit/provider-thinking-config.test.js
@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest";
+import { normalizeThinkingConfig } from "../../open-sse/services/provider.js";
+
+describe("normalizeThinkingConfig", () => {
+  it("keeps openai reasoning_effort on non-user turns", () => {
+    const body = {
+      messages: [{ role: "assistant", content: "ok" }],
+      reasoning_effort: "xhigh",
+      thinking: { type: "enabled" },
+    };
+
+    normalizeThinkingConfig(body);
+
+    expect(body.reasoning_effort).toBe("xhigh");
+    expect(body.thinking).toBeUndefined();
+  });
+});
diff --git a/tests/unit/provider-validation.test.js b/tests/unit/provider-validation.test.js
new file mode 100644
index 0000000..9484580
--- /dev/null
+++ b/tests/unit/provider-validation.test.js
@@ -0,0 +1,271 @@
+/**
+ * Unit tests for /api/provider-nodes/validate endpoint
+ *
+ * Tests cover:
+ *  - OpenAI-compatible validation via /models
+ *  - Anthropic-compatible validation via /models
+ *  - Fallback to /chat/completions when modelId provided
+ *  - Error message handling
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// Mock fetch globally
+const originalFetch = global.fetch;
+
+describe("Provider Validation API", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  describe("OpenAI Compatible", () => {
+    it("should return valid:true when /models succeeds", async () => {
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ data: [] }),
+      });
+
+      // Simulate the validation logic
+      const baseUrl = "https://api.openai.com/v1";
+      const apiKey = "test-key";
+      const modelsUrl = `${baseUrl}/models`;
+
+      const res = await fetch(modelsUrl, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+      });
+
+      expect(res.ok).toBe(true);
+      expect(fetch).toHaveBeenCalledWith(modelsUrl, expect.objectContaining({
+        headers: { Authorization: `Bearer ${apiKey}` },
+      }));
+    });
+
+    it("should fallback to chat/completions when /models fails and modelId provided", async () => {
+      const modelsCall = vi.fn().mockResolvedValue({ ok: false, status: 404 });
+      const chatCall = vi.fn().mockResolvedValue({ ok: true });
+
+      global.fetch = vi.fn().mockImplementation((url) => {
+        if (url.includes("/models")) return modelsCall();
+        if (url.includes("/chat/completions")) return chatCall();
+        return Promise.reject(new Error("Unknown URL"));
+      });
+
+      // Simulate validation flow
+      const baseUrl = "https://custom-provider.com/v1";
+      const modelsRes = await fetch(`${baseUrl}/models`);
+      expect(modelsRes.ok).toBe(false);
+
+      // Fallback to chat
+      const chatRes = await fetch(`${baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          model: "gpt-4",
+          messages: [{ role: "user", content: "ping" }],
+          max_tokens: 1,
+        }),
+      });
+      expect(chatRes.ok).toBe(true);
+    });
+
+    it("should return error when /models fails and no modelId", async () => {
+      global.fetch = vi.fn().mockResolvedValue({ ok: false, status: 404 });
+
+      const baseUrl = "https://custom-provider.com/v1";
+      const res = await fetch(`${baseUrl}/models`);
+
+      expect(res.ok).toBe(false);
+      // Expected error: "/models unavailable - provide model ID for chat validation"
+    });
+  });
+
+  describe("Anthropic Compatible", () => {
+    it("should normalize URL by removing /messages suffix", () => {
+      const normalizeUrl = (url) => {
+        let normalized = url.trim().replace(/\/$/, "");
+        if (normalized.endsWith("/messages")) {
+          normalized = normalized.slice(0, -9);
+        }
+        return normalized;
+      };
+
+      expect(normalizeUrl("https://api.anthropic.com/v1/messages")).toBe("https://api.anthropic.com/v1");
+      expect(normalizeUrl("https://api.anthropic.com/v1/messages/")).toBe("https://api.anthropic.com/v1");
+      expect(normalizeUrl("https://api.anthropic.com/v1")).toBe("https://api.anthropic.com/v1");
+    });
+
+    it("should send correct headers for Anthropic API", async () => {
+      global.fetch = vi.fn().mockResolvedValue({ ok: true });
+
+      const baseUrl = "https://api.anthropic.com/v1";
+      const apiKey = "test-key";
+
+      await fetch(`${baseUrl}/models`, {
+        method: "GET",
+        headers: {
+          "x-api-key": apiKey,
+          "anthropic-version": "2023-06-01",
+          Authorization: `Bearer ${apiKey}`,
+        },
+      });
+
+      expect(fetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+        headers: expect.objectContaining({
+          "x-api-key": apiKey,
+          "anthropic-version": "2023-06-01",
+        }),
+      }));
+    });
+  });
+
+  describe("Error Messages - Network", () => {
+    it("should map ECONNREFUSED to user-friendly message", () => {
+      const getErrorMessage = (error) => {
+        if (error.cause?.code === "ECONNREFUSED") return "Connection refused - provider node offline or unreachable";
+        return "Unknown error";
+      };
+
+      const error = { cause: { code: "ECONNREFUSED" } };
+      expect(getErrorMessage(error)).toBe("Connection refused - provider node offline or unreachable");
+    });
+
+    it("should map ENOTFOUND to user-friendly message", () => {
+      const getErrorMessage = (error) => {
+        if (error.cause?.code === "ENOTFOUND") return "DNS lookup failed - invalid domain or network issue";
+        return "Unknown error";
+      };
+
+      const error = { cause: { code: "ENOTFOUND" } };
+      expect(getErrorMessage(error)).toBe("DNS lookup failed - invalid domain or network issue");
+    });
+
+    it("should map timeout to user-friendly message", () => {
+      const getErrorMessage = (error) => {
+        if (error.message.includes("timeout")) return "Request timeout (>10s) - provider node not responding";
+        return "Unknown error";
+      };
+
+      const error = { message: "Request timeout" };
+      expect(getErrorMessage(error)).toBe("Request timeout (>10s) - provider node not responding");
+    });
+
+    it("should map CERT_HAS_EXPIRED to user-friendly message", () => {
+      const getErrorMessage = (error) => {
+        if (error.cause?.code === "CERT_HAS_EXPIRED") return "SSL certificate expired";
+        return "Unknown error";
+      };
+
+      const error = { cause: { code: "CERT_HAS_EXPIRED" } };
+      expect(getErrorMessage(error)).toBe("SSL certificate expired");
+    });
+  });
+
+  describe("URL Validation", () => {
+    it("should validate correct URL format", () => {
+      const isValidUrl = (url) => {
+        try {
+          new URL(url);
+          return true;
+        } catch {
+          return false;
+        }
+      };
+
+      expect(isValidUrl("https://api.openai.com/v1")).toBe(true);
+      expect(isValidUrl("http://localhost:8080")).toBe(true);
+      expect(isValidUrl("not-a-url")).toBe(false);
+      expect(isValidUrl("")).toBe(false);
+    });
+  });
+
+  describe("Error Messages - /models Status Codes", () => {
+    const getModelsErrorMessage = (status) => {
+      if (status === 401 || status === 403) return "API key unauthorized";
+      if (status === 404) return "/models endpoint not found - try chat validation with model ID";
+      if (status >= 500) return "Server error - try again later";
+      return `Unexpected response (${status})`;
+    };
+
+    it("should return auth error for 401", () => {
+      expect(getModelsErrorMessage(401)).toBe("API key unauthorized");
+    });
+
+    it("should return auth error for 403", () => {
+      expect(getModelsErrorMessage(403)).toBe("API key unauthorized");
+    });
+
+    it("should return not found for 404", () => {
+      expect(getModelsErrorMessage(404)).toBe("/models endpoint not found - try chat validation with model ID");
+    });
+
+    it("should return server error for 500", () => {
+      expect(getModelsErrorMessage(500)).toBe("Server error - try again later");
+    });
+
+    it("should return server error for 502", () => {
+      expect(getModelsErrorMessage(502)).toBe("Server error - try again later");
+    });
+
+    it("should return unexpected for other codes", () => {
+      expect(getModelsErrorMessage(418)).toBe("Unexpected response (418)");
+    });
+  });
+
+  describe("Error Messages - /chat/completions Status Codes", () => {
+    const getChatErrorMessage = (status) => {
+      if (status === 401 || status === 403) return "API key unauthorized";
+      if (status === 400) return "Invalid model or bad request";
+      if (status === 404) return "Chat endpoint not found";
+      if (status >= 500) return "Server error - try again later";
+      return `Chat request failed (${status})`;
+    };
+
+    it("should return auth error for 401", () => {
+      expect(getChatErrorMessage(401)).toBe("API key unauthorized");
+    });
+
+    it("should return invalid model for 400", () => {
+      expect(getChatErrorMessage(400)).toBe("Invalid model or bad request");
+    });
+
+    it("should return not found for 404", () => {
+      expect(getChatErrorMessage(404)).toBe("Chat endpoint not found");
+    });
+
+    it("should return server error for 503", () => {
+      expect(getChatErrorMessage(503)).toBe("Server error - try again later");
+    });
+
+    it("should return failed for other codes", () => {
+      expect(getChatErrorMessage(429)).toBe("Chat request failed (429)");
+    });
+  });
+
+  describe("Response Format", () => {
+    it("should return correct format for success via /models", () => {
+      const response = { valid: true };
+      expect(response).toEqual({ valid: true });
+    });
+
+    it("should return correct format for success via chat", () => {
+      const response = { valid: true, error: null, method: "chat" };
+      expect(response.valid).toBe(true);
+      expect(response.method).toBe("chat");
+      expect(response.error).toBeNull();
+    });
+
+    it("should return correct format for failure with error", () => {
+      const response = {
+        valid: false,
+        error: "API key unauthorized or model unavailable",
+        method: "chat"
+      };
+      expect(response.valid).toBe(false);
+      expect(response.error).toBeDefined();
+    });
+  });
+});
diff --git a/tests/unit/pxpipe.test.js b/tests/unit/pxpipe.test.js
new file mode 100644
index 0000000..5c49f12
--- /dev/null
+++ b/tests/unit/pxpipe.test.js
@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from "vitest";
+import { compressWithPxpipe, formatPxpipeLog } from "../../open-sse/rtk/pxpipe.js";
+
+const bigText = "x".repeat(30000);
+const claudeBody = () => ({
+  model: "claude-fable-5",
+  max_tokens: 100,
+  messages: [{ role: "user", content: bigText }],
+});
+
+// A transform double mimicking pxpipe-proxy/transform's contract.
+const appliedTransform = (outBody) => async () => ({
+  applied: true,
+  reason: "applied",
+  body: new TextEncoder().encode(JSON.stringify(outBody)),
+  info: { compressedChars: 25000, imageCount: 2, imageBytes: 5000, imagePixels: 1500000 },
+  cache: { ownsCacheControl: true, markerCount: 1 },
+});
+
+describe("compressWithPxpipe gates", () => {
+  it("skips when disabled", async () => {
+    const { body, summary } = await compressWithPxpipe(claudeBody(), { enabled: false });
+    expect(body).toBeNull();
+    expect(summary.reason).toBe("disabled");
+  });
+
+  it("skips when transform is unavailable (not installed)", async () => {
+    const { body, summary } = await compressWithPxpipe(claudeBody(), { enabled: true, format: "claude", transform: null });
+    expect(body).toBeNull();
+    expect(summary.reason).toBe("not_installed");
+  });
+
+  it("skips non-Claude formats", async () => {
+    const transform = vi.fn();
+    const { body, summary } = await compressWithPxpipe(claudeBody(), { enabled: true, format: "openai", transform });
+    expect(body).toBeNull();
+    expect(summary.reason).toBe("unsupported_format");
+    expect(transform).not.toHaveBeenCalled();
+  });
+
+  it("bypasses small prompts below minChars", async () => {
+    const transform = vi.fn();
+    const small = { model: "claude-fable-5", messages: [{ role: "user", content: "hi" }] };
+    const { body, summary } = await compressWithPxpipe(small, { enabled: true, format: "claude", minChars: 25000, transform });
+    expect(body).toBeNull();
+    expect(summary.reason).toBe("below_threshold");
+    expect(transform).not.toHaveBeenCalled();
+  });
+
+  it("applies the transform and reports savings", async () => {
+    const compressed = { model: "claude-fable-5", messages: [{ role: "user", content: "imaged" }] };
+    const { body, summary } = await compressWithPxpipe(claudeBody(), {
+      enabled: true, format: "claude", minChars: 1000, transform: appliedTransform(compressed),
+    });
+    expect(body).toEqual(compressed);
+    expect(summary.applied).toBe(true);
+    expect(summary.imageCount).toBe(2);
+    expect(summary.tokensBeforeEst).toBeGreaterThan(summary.tokensAfterEst);
+    expect(summary.savedPct).toBeGreaterThan(0);
+    expect(formatPxpipeLog(summary)).toContain("2 image(s)");
+  });
+
+  it("passes through when the transform declines (not_profitable)", async () => {
+    const transform = async () => ({ applied: false, reason: "not_profitable", body: new Uint8Array(), info: {} });
+    const { body, summary } = await compressWithPxpipe(claudeBody(), {
+      enabled: true, format: "claude", minChars: 1000, transform,
+    });
+    expect(body).toBeNull();
+    expect(summary.reason).toBe("not_profitable");
+  });
+
+  it("fails open when the transform throws", async () => {
+    const transform = async () => { throw new Error("boom"); };
+    const { body, summary } = await compressWithPxpipe(claudeBody(), {
+      enabled: true, format: "claude", minChars: 1000, transform,
+    });
+    expect(body).toBeNull();
+    expect(summary.reason).toBe("transform_error");
+    expect(summary.detail).toBe("boom");
+  });
+
+  it("fails open on timeout", async () => {
+    const transform = () => new Promise(() => {}); // never resolves
+    const { body, summary } = await compressWithPxpipe(claudeBody(), {
+      enabled: true, format: "claude", minChars: 1000, timeoutMs: 50, transform,
+    });
+    expect(body).toBeNull();
+    expect(summary.reason).toBe("timeout");
+  });
+
+  it("does not log skipped requests as savings", () => {
+    expect(formatPxpipeLog({ applied: false, reason: "below_threshold" })).toBeNull();
+    expect(formatPxpipeLog(null)).toBeNull();
+  });
+});
diff --git a/tests/unit/qoder.test.js b/tests/unit/qoder.test.js
new file mode 100644
index 0000000..fc5f20a
--- /dev/null
+++ b/tests/unit/qoder.test.js
@@ -0,0 +1,469 @@
+/**
+ * Unit tests for Qoder encoding + COSY signing primitives.
+ *
+ * These cover the parts that would silently produce wrong-but-plausible
+ * output if logic regressed:
+ *   - body encoder boundary cases (empty input, lengths not divisible by 3)
+ *   - COSY header production (signature deterministic given fixed inputs,
+ *     all required headers present, sigPath correctly stripped)
+ *   - device flow URL construction
+ */
+
+import { describe, it, expect } from "vitest";
+import crypto from "crypto";
+
+import { qoderEncodeBody } from "../../src/lib/qoder/encoding.js";
+import { buildCosyHeaders } from "../../src/lib/qoder/cosy.js";
+import { QoderService } from "../../src/lib/oauth/services/qoder.js";
+import {
+  QODER_CHAT_URL_ENCODED,
+  QODER_MODEL_LIST_URL,
+  QODER_MODEL_MAP,
+} from "../../src/lib/qoder/constants.js";
+import { PROVIDER_MODELS } from "../../open-sse/config/providerModels.js";
+import { __test__ as qoderExecutorInternals } from "../../open-sse/executors/qoder.js";
+
+// Convenience aliases — tests were originally written against module-level
+// helpers; the QoderService class wraps them so each test creates its own
+// instance to avoid hidden state.
+const generatePkcePair = () => new QoderService().generatePkcePair();
+const initiateDeviceFlow = () => new QoderService().initiateDeviceFlow();
+const parseExpiry = QoderService.parseExpiry;
+
+describe("QODER_MODEL_MAP", () => {
+  it("allows Qoder's latest model key", () => {
+    expect(QODER_MODEL_MAP.qmodel_latest).toBe("qmodel_latest");
+  });
+
+  it("exposes Qoder's latest model in the static provider catalog", () => {
+    expect(PROVIDER_MODELS.qd.some((model) => model.id === "qmodel_latest")).toBe(true);
+  });
+});
+
+describe("qoderEncodeBody", () => {
+  it("preserves base64 length (input length divisible by 3)", () => {
+    const input = Buffer.from("abcdef", "utf8"); // 6 bytes → 8 base64 chars
+    const encoded = qoderEncodeBody(input);
+    expect(encoded.length).toBe(8);
+  });
+
+  it("preserves base64 length (input length not divisible by 3)", () => {
+    const input = Buffer.from("hello", "utf8"); // 5 bytes → 8 base64 chars (with padding)
+    const encoded = qoderEncodeBody(input);
+    expect(encoded.length).toBe(8);
+  });
+
+  it("handles empty input without throwing", () => {
+    const encoded = qoderEncodeBody(Buffer.alloc(0));
+    expect(encoded).toBe("");
+  });
+
+  it("accepts string and Buffer inputs equivalently", () => {
+    const a = qoderEncodeBody("hello");
+    const b = qoderEncodeBody(Buffer.from("hello", "utf8"));
+    expect(a).toBe(b);
+  });
+
+  it("only emits characters from the custom alphabet", () => {
+    // The custom alphabet is "_doRTgHZBKcGVjlvpC,@aFSx#DPuNJme&i*MzLOEn)sUrthbf%Y^w.(kIQyXqWA!"
+    // plus "$" for the padding char. If the substitution step regresses,
+    // characters outside that set would leak into the output.
+    const allowed = new Set(
+      "_doRTgHZBKcGVjlvpC,@aFSx#DPuNJme&i*MzLOEn)sUrthbf%Y^w.(kIQyXqWA!$",
+    );
+    const encoded = qoderEncodeBody(
+      "hello world this is a longer string for testing 0123456789",
+    );
+    for (const ch of encoded) {
+      expect(allowed.has(ch), `unexpected char in output: ${JSON.stringify(ch)}`).toBe(true);
+    }
+  });
+
+  it("is deterministic for identical input", () => {
+    const a = qoderEncodeBody("abc");
+    const b = qoderEncodeBody("abc");
+    expect(a).toBe(b);
+  });
+
+  it("produces different output for different input", () => {
+    const a = qoderEncodeBody("abc");
+    const b = qoderEncodeBody("xyz");
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("generatePkcePair", () => {
+  it("produces base64url-safe verifier and challenge of the right length", () => {
+    const { verifier, challenge } = generatePkcePair();
+    // 32 bytes → 43 base64url chars (no padding)
+    expect(verifier.length).toBe(43);
+    expect(challenge.length).toBe(43);
+    expect(verifier).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(challenge).toMatch(/^[A-Za-z0-9_-]+$/);
+  });
+
+  it("verifier and challenge are different (challenge is sha256 of verifier)", () => {
+    const { verifier, challenge } = generatePkcePair();
+    expect(verifier).not.toBe(challenge);
+    // S256: challenge should be base64url(sha256(verifier))
+    const expected = crypto
+      .createHash("sha256")
+      .update(verifier)
+      .digest("base64")
+      .replace(/=/g, "")
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_");
+    expect(challenge).toBe(expected);
+  });
+
+  it("returns codeVerifier (not verifier) on the higher-level helper", () => {
+    // Regression: the providers.js qoder entry once read flow.verifier (undefined)
+    // because initiateDeviceFlow returns the field as `codeVerifier`.
+    const flow = initiateDeviceFlow();
+    expect(typeof flow.codeVerifier).toBe("string");
+    expect(flow.codeVerifier.length).toBe(43);
+    expect(flow.verifier).toBeUndefined();
+  });
+});
+
+describe("initiateDeviceFlow", () => {
+  it("produces a verification URL pointing at qoder.com/device/selectAccounts", () => {
+    const flow = initiateDeviceFlow();
+    expect(flow.verificationUriComplete).toMatch(
+      /^https:\/\/qoder\.com\/device\/selectAccounts\?/,
+    );
+    expect(flow.verificationUriComplete).toContain("challenge_method=S256");
+    expect(flow.verificationUriComplete).toContain(`nonce=${flow.nonce}`);
+    expect(flow.verificationUriComplete).toContain(`machine_id=${flow.machineId}`);
+  });
+
+  it("returns nonce and machineId as UUIDs", () => {
+    const flow = initiateDeviceFlow();
+    const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+    expect(flow.nonce).toMatch(uuidRe);
+    expect(flow.machineId).toMatch(uuidRe);
+  });
+});
+
+describe("buildCosyHeaders", () => {
+  const creds = {
+    userId: "test-user-id",
+    authToken: "dt-test-token",
+    name: "Test",
+    email: "test@example.com",
+    machineId: "fixed-machine-id",
+  };
+
+  it("produces all required Cosy-* headers", () => {
+    const headers = buildCosyHeaders(Buffer.alloc(0), QODER_MODEL_LIST_URL, creds);
+    const required = [
+      "Authorization",
+      "Cosy-Key",
+      "Cosy-User",
+      "Cosy-Date",
+      "Cosy-Version",
+      "Cosy-Machineid",
+      "Cosy-Machinetoken",
+      "Cosy-Machinetype",
+      "Cosy-Machineos",
+      "Cosy-Clienttype",
+      "Cosy-Clientip",
+      "Cosy-Bodyhash",
+      "Cosy-Bodylength",
+      "Cosy-Sigpath",
+      "Cosy-Data-Policy",
+      "Login-Version",
+      "X-Request-Id",
+    ];
+    for (const key of required) {
+      expect(headers[key], `missing header ${key}`).toBeDefined();
+    }
+  });
+
+  it("Authorization is a Bearer COSY token with payload+sig", () => {
+    const headers = buildCosyHeaders(Buffer.alloc(0), QODER_MODEL_LIST_URL, creds);
+    expect(headers.Authorization).toMatch(/^Bearer COSY\.[A-Za-z0-9+/=]+\.[a-f0-9]{32}$/);
+  });
+
+  it("Cosy-Sigpath strips the leading /algo prefix", () => {
+    const headers = buildCosyHeaders(Buffer.alloc(0), QODER_MODEL_LIST_URL, creds);
+    expect(headers["Cosy-Sigpath"]).toBe("/api/v2/model/list");
+  });
+
+  it("Cosy-Sigpath also handles the encoded chat URL", () => {
+    const headers = buildCosyHeaders(Buffer.from("body", "utf8"), QODER_CHAT_URL_ENCODED, creds);
+    expect(headers["Cosy-Sigpath"]).toBe(
+      "/api/v2/service/pro/sse/agent_chat_generation",
+    );
+  });
+
+  it("Cosy-Bodyhash is the MD5 of the request body, Cosy-Bodylength is the length", () => {
+    const body = Buffer.from("hello qoder", "utf8");
+    const headers = buildCosyHeaders(body, QODER_MODEL_LIST_URL, creds);
+    const expectedHash = crypto.createHash("md5").update(body).digest("hex");
+    expect(headers["Cosy-Bodyhash"]).toBe(expectedHash);
+    expect(headers["Cosy-Bodylength"]).toBe(String(body.length));
+  });
+
+  it("empty body produces the canonical empty-MD5 hash", () => {
+    const headers = buildCosyHeaders(Buffer.alloc(0), QODER_MODEL_LIST_URL, creds);
+    expect(headers["Cosy-Bodyhash"]).toBe("d41d8cd98f00b204e9800998ecf8427e");
+    expect(headers["Cosy-Bodylength"]).toBe("0");
+  });
+
+  it("Cosy-Machineid + Cosy-Machinetoken match the supplied machineId", () => {
+    const headers = buildCosyHeaders(Buffer.alloc(0), QODER_MODEL_LIST_URL, creds);
+    expect(headers["Cosy-Machineid"]).toBe("fixed-machine-id");
+    expect(headers["Cosy-Machinetoken"]).toBe("fixed-machine-id");
+  });
+
+  it("auto-generates a machineId when none is supplied", () => {
+    const headers = buildCosyHeaders(Buffer.alloc(0), QODER_MODEL_LIST_URL, {
+      ...creds,
+      machineId: "",
+    });
+    expect(headers["Cosy-Machineid"]).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+  });
+
+  it("throws when userId is missing", () => {
+    expect(() =>
+      buildCosyHeaders(Buffer.alloc(0), QODER_MODEL_LIST_URL, { ...creds, userId: "" }),
+    ).toThrow(/user id is empty/);
+  });
+
+  it("throws when authToken is missing", () => {
+    expect(() =>
+      buildCosyHeaders(Buffer.alloc(0), QODER_MODEL_LIST_URL, { ...creds, authToken: "" }),
+    ).toThrow(/auth token is empty/);
+  });
+
+  it("Cosy-User reflects the supplied userId verbatim", () => {
+    const headers = buildCosyHeaders(Buffer.alloc(0), QODER_MODEL_LIST_URL, creds);
+    expect(headers["Cosy-User"]).toBe("test-user-id");
+  });
+
+  it("two calls with identical inputs differ only in fields that include fresh randomness", () => {
+    // The signature fingerprints a fresh AES key + UUID per call, so the
+    // signature, Cosy-Key, X-Request-Id, and Cosy-Date (1s resolution)
+    // can differ — but Cosy-User, Cosy-Bodyhash, Cosy-Bodylength,
+    // Cosy-Sigpath, and the machineId-derived headers must be stable.
+    const a = buildCosyHeaders(Buffer.from("payload", "utf8"), QODER_CHAT_URL_ENCODED, creds);
+    const b = buildCosyHeaders(Buffer.from("payload", "utf8"), QODER_CHAT_URL_ENCODED, creds);
+    expect(a["Cosy-User"]).toBe(b["Cosy-User"]);
+    expect(a["Cosy-Bodyhash"]).toBe(b["Cosy-Bodyhash"]);
+    expect(a["Cosy-Bodylength"]).toBe(b["Cosy-Bodylength"]);
+    expect(a["Cosy-Sigpath"]).toBe(b["Cosy-Sigpath"]);
+    expect(a["Cosy-Machineid"]).toBe(b["Cosy-Machineid"]);
+    expect(a["X-Request-Id"]).not.toBe(b["X-Request-Id"]);
+  });
+});
+
+describe("parseExpiry", () => {
+  // Regression for review finding #2: numeric expires_at was silently
+  // dropped because the function only inspected strings.
+  it("accepts ms-epoch as a JSON number", () => {
+    const future = Date.now() + 60_000;
+    expect(parseExpiry(future, undefined)).toBe(future);
+  });
+
+  it("accepts ms-epoch as a numeric string", () => {
+    const future = Date.now() + 60_000;
+    expect(parseExpiry(String(future), undefined)).toBe(future);
+  });
+
+  it("accepts RFC3339 strings", () => {
+    const iso = "2030-01-02T03:04:05Z";
+    expect(parseExpiry(iso, undefined)).toBe(Date.parse(iso));
+  });
+
+  // Regression for review finding #5: Date.parse("2026") returns Jan 1 2026,
+  // so a short numeric string like "2026" used to be interpreted as a year
+  // instead of falling through to the integer-ms branch. We now try the
+  // pure-numeric path first so this can't happen again.
+  it("does not interpret short numeric strings as a year", () => {
+    // "1700000000" (Unix seconds) should NOT come out as Date.parse("1700000000")
+    const result = parseExpiry("1700000000", undefined);
+    // 1.7e9 ms = 1970-01-20 — the function's contract is ms, so we expect
+    // exactly that value, not a year interpretation.
+    expect(result).toBe(1_700_000_000);
+  });
+
+  it("falls back to expiresInSeconds when expiresAt is missing", () => {
+    const before = Date.now();
+    const result = parseExpiry(undefined, 60);
+    const after = Date.now();
+    expect(result).toBeGreaterThanOrEqual(before + 60_000);
+    expect(result).toBeLessThanOrEqual(after + 60_000);
+  });
+
+  // Regression for review finding #7: expiresInSeconds=0 used to be treated
+  // as missing and silently fabricated 30-day default. We now honor 0 as
+  // "already expired".
+  it("treats expires_in: 0 as already expired (now), not 30-day fallback", () => {
+    const before = Date.now();
+    const result = parseExpiry(undefined, 0);
+    const after = Date.now();
+    expect(result).toBeGreaterThanOrEqual(before);
+    expect(result).toBeLessThanOrEqual(after);
+  });
+
+  it("falls back to ~30 days when both inputs are missing", () => {
+    const before = Date.now();
+    const result = parseExpiry(undefined, undefined);
+    const expected = before + 30 * 24 * 60 * 60 * 1000;
+    // Allow a small skew to absorb test runtime.
+    expect(result).toBeGreaterThanOrEqual(expected - 5_000);
+    expect(result).toBeLessThanOrEqual(expected + 5_000);
+  });
+
+  it("falls back to ~30 days when both inputs are unparseable", () => {
+    const before = Date.now();
+    const result = parseExpiry("not-a-date", -5);
+    const expected = before + 30 * 24 * 60 * 60 * 1000;
+    expect(result).toBeGreaterThanOrEqual(expected - 5_000);
+    expect(result).toBeLessThanOrEqual(expected + 5_000);
+  });
+});
+
+describe("normalizeMessages", () => {
+  const { normalizeMessages } = qoderExecutorInternals;
+
+  it("hoists role:system out of messages into systemText", () => {
+    const result = normalizeMessages([
+      { role: "system", content: "you are helpful" },
+      { role: "user", content: "hi" },
+    ]);
+    expect(result.systemText).toBe("you are helpful");
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].role).toBe("user");
+  });
+
+  it("flattens multipart text content into a string", () => {
+    const result = normalizeMessages([
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "part1" },
+          { type: "text", text: "part2" },
+        ],
+      },
+    ]);
+    expect(result.messages[0].content).toBe("part1\npart2");
+  });
+
+  it("joins multiple system messages with a blank line", () => {
+    const result = normalizeMessages([
+      { role: "system", content: "rule 1" },
+      { role: "system", content: "rule 2" },
+      { role: "user", content: "hi" },
+    ]);
+    expect(result.systemText).toBe("rule 1\n\nrule 2");
+  });
+
+  it("returns empty results for empty input", () => {
+    const result = normalizeMessages([]);
+    expect(result.messages).toEqual([]);
+    expect(result.systemText).toBe("");
+  });
+});
+
+describe("wrapQoderSSE", () => {
+  const { wrapQoderSSE } = qoderExecutorInternals;
+
+  // Helper: build a fake Response carrying the given lines as the body.
+  function makeResponse(lines, { status = 200 } = {}) {
+    const body = new ReadableStream({
+      start(controller) {
+        const encoder = new TextEncoder();
+        for (const line of lines) controller.enqueue(encoder.encode(line));
+        controller.close();
+      },
+    });
+    return new Response(body, { status });
+  }
+
+  // Helper: drain a wrapped response into an array of decoded SSE events.
+  async function drain(response) {
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+    }
+    buf += decoder.decode();
+    return buf;
+  }
+
+  it("forwards an OpenAI envelope chunk and emits [DONE] in flush", async () => {
+    const inner = JSON.stringify({ choices: [{ delta: { content: "hi" } }] });
+    const upstream = `data: ${JSON.stringify({ statusCodeValue: 200, body: inner })}\n\n`;
+    const wrapped = wrapQoderSSE(makeResponse([upstream]), "qoder/auto");
+    const out = await drain(wrapped);
+    expect(out).toContain(`data: ${inner}\n\n`);
+    expect(out).toContain("data: [DONE]\n\n");
+  });
+
+  // Regression for review finding #4: a final data: line without a trailing
+  // newline used to be silently dropped from `buffer` in flush().
+  it("drains a trailing partial line without a newline in flush()", async () => {
+    const inner = JSON.stringify({ choices: [{ delta: { content: "tail" } }], finish_reason: "stop" });
+    // Note: NO trailing \n on the final line.
+    const upstream = `data: ${JSON.stringify({ statusCodeValue: 200, body: inner })}`;
+    const wrapped = wrapQoderSSE(makeResponse([upstream]), "qoder/auto");
+    const out = await drain(wrapped);
+    expect(out).toContain(`data: ${inner}\n\n`);
+  });
+
+  // Regression for review finding #3: chunks could leak past [DONE] when
+  // the success branch had no doneEmitted guard. We synthesize an error
+  // envelope (which sets doneEmitted=true) followed by a valid envelope
+  // and assert the second envelope is NOT forwarded.
+  it("does not forward chunks after [DONE] has been emitted", async () => {
+    const errorEnv = JSON.stringify({ statusCodeValue: 500, body: "boom" });
+    const validInner = JSON.stringify({ choices: [{ delta: { content: "leak" } }] });
+    const validEnv = JSON.stringify({ statusCodeValue: 200, body: validInner });
+    const wrapped = wrapQoderSSE(
+      makeResponse([`data: ${errorEnv}\n\ndata: ${validEnv}\n\n`]),
+      "qoder/auto",
+    );
+    const out = await drain(wrapped);
+    expect(out).not.toContain("leak");
+    // Should still have a single [DONE].
+    const doneCount = (out.match(/data: \[DONE\]/g) || []).length;
+    expect(doneCount).toBe(1);
+  });
+
+  // Regression for review finding #6: literal newlines inside the inner
+  // OpenAI body would split the SSE frame across multiple data: lines.
+  // We now strip them so the frame stays a single event.
+  it("strips embedded newlines from inner body before forwarding", async () => {
+    const innerWithNewlines = '{"choices":[{"delta":{"content":"a\nb"}}]}';
+    const env = JSON.stringify({ statusCodeValue: 200, body: innerWithNewlines });
+    const wrapped = wrapQoderSSE(makeResponse([`data: ${env}\n\n`]), "qoder/auto");
+    const out = await drain(wrapped);
+    // The forwarded data: line should be a single event terminated by \n\n
+    // and contain no internal \n other than the trailing pair.
+    const dataLine = out.split("\n\n").find((l) => l.startsWith("data: ") && !l.includes("[DONE]"));
+    expect(dataLine).toBeDefined();
+    // Body sans "data: " prefix should be valid JSON.
+    expect(() => JSON.parse(dataLine.slice("data: ".length))).not.toThrow();
+  });
+
+  it("upstream error envelope produces an error chunk + [DONE]", async () => {
+    const env = JSON.stringify({ statusCodeValue: 503, body: "service unavailable" });
+    const wrapped = wrapQoderSSE(makeResponse([`data: ${env}\n\n`]), "qoder/lite");
+    const out = await drain(wrapped);
+    expect(out).toContain("[qoder error 503");
+    expect(out).toContain("data: [DONE]\n\n");
+  });
+
+  it("non-ok responses are returned unchanged (no transform)", () => {
+    const r = new Response("not ok", { status: 500 });
+    const wrapped = wrapQoderSSE(r, "qoder/auto");
+    expect(wrapped).toBe(r);
+  });
+});
diff --git a/tests/unit/quota-auto-ping.test.js b/tests/unit/quota-auto-ping.test.js
new file mode 100644
index 0000000..de601df
--- /dev/null
+++ b/tests/unit/quota-auto-ping.test.js
@@ -0,0 +1,351 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("open-sse/index.js", () => ({}), { virtual: true });
+
+vi.mock("@/lib/localDb", () => ({
+  getSettings: vi.fn(),
+  getProviderConnections: vi.fn(),
+  updateProviderConnection: vi.fn(),
+}));
+
+vi.mock("@/lib/network/connectionProxy", () => ({
+  resolveConnectionProxyConfig: vi.fn(),
+}));
+
+vi.mock("@/app/api/usage/[connectionId]/route.js", () => ({
+  refreshAndUpdateCredentials: vi.fn(),
+}));
+
+vi.mock("@/shared/constants/config", () => ({
+  QUOTA_AUTOPING_CONFIG: {
+    tickIntervalMs: 60000,
+    pingLeadMs: 5000,
+    refreshAheadMs: 300000,
+    failureCooldownMs: 900000,
+    providers: {
+      claude: {
+        settingsKey: "claudeAutoPing",
+        quotaKey: "session (5h)",
+        pingModel: "claude-haiku-4-5-20251001",
+        pingText: "hi",
+        pingMaxTokens: 1,
+      },
+      codex: {
+        settingsKey: "codexAutoPing",
+        quotaKey: "session",
+        pingWhenResetAtSlides: true,
+        resetAtDriftMs: 30000,
+        minPingIntervalMs: 600000,
+        skipWhenBlockingQuotaExhausted: true,
+        pingModel: "gpt-5.5",
+        pingText: "hi",
+        pingInstructions: "Reply with OK.",
+        pingReasoningEffort: "none",
+      },
+    },
+  },
+}));
+
+vi.mock("open-sse/providers/shared.js", () => ({
+  CLAUDE_CLI_SPOOF_HEADERS: { "anthropic-version": "2023-06-01" },
+}));
+
+vi.mock("open-sse/services/usage/shared.js", () => ({
+  U: () => ({ baseUrl: "https://chatgpt.com/backend-api/codex/responses" }),
+}));
+
+vi.mock("open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch: vi.fn(),
+}));
+
+vi.mock("open-sse/services/usage/claude.js", () => ({
+  getClaudeUsage: vi.fn(),
+}));
+
+vi.mock("open-sse/services/usage/codex.js", () => ({
+  getCodexUsage: vi.fn(),
+}));
+
+vi.mock("open-sse/executors/index.js", () => ({
+  getExecutor: vi.fn(),
+}));
+
+describe("quota auto-ping", () => {
+  let runQuotaAutoPingTick;
+  let deps;
+  let state;
+  let getCodexUsage;
+  let getClaudeUsage;
+  let getExecutor;
+  let codexResponseText;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    vi.useRealTimers();
+
+    ({ getCodexUsage } = await import("open-sse/services/usage/codex.js"));
+    ({ getClaudeUsage } = await import("open-sse/services/usage/claude.js"));
+    ({ getExecutor } = await import("open-sse/executors/index.js"));
+    ({ runQuotaAutoPingTick } = await import("../../src/shared/services/quotaAutoPing.js"));
+
+    deps = {
+      getSettings: vi.fn(),
+      getProviderConnections: vi.fn(),
+      updateProviderConnection: vi.fn(),
+      resolveConnectionProxyConfig: vi.fn().mockResolvedValue({}),
+      refreshAndUpdateCredentials: vi.fn(async (connection) => ({ connection, refreshed: false })),
+      proxyAwareFetch: vi.fn().mockResolvedValue({ ok: true }),
+      getExecutor: vi.fn(() => ({
+        execute: vi.fn().mockResolvedValue({ response: { ok: true, text: codexResponseText } }),
+      })),
+    };
+    codexResponseText = vi.fn().mockResolvedValue("");
+    getExecutor.mockReturnValue({
+      execute: vi.fn().mockResolvedValue({ response: { ok: true, text: codexResponseText } }),
+    });
+    state = { running: false, resetCache: {}, failureCache: {} };
+    vi.setSystemTime(new Date("2026-01-01T12:00:00.000Z"));
+  });
+
+  it("does not ping Codex when setting is absent", async () => {
+    deps.getSettings.mockResolvedValue({});
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(deps.getProviderConnections).not.toHaveBeenCalled();
+    expect(deps.proxyAwareFetch).not.toHaveBeenCalled();
+  });
+
+  it("does not ping Codex on the first resetAt observation", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex" ? [{ id: "codex-1", provider: "codex", authType: "oauth", accessToken: "token" }] : []
+    ));
+    getCodexUsage.mockResolvedValue({
+      quotas: { session: { used: 1, resetAt: "2026-01-01T13:00:00.000Z" } },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(deps.getExecutor).not.toHaveBeenCalled();
+    expect(deps.updateProviderConnection).not.toHaveBeenCalled();
+    expect(state.resetCache["codex:codex-1"]).toBe("2026-01-01T13:00:00.000Z");
+  });
+
+  it("sends Codex ping when session resetAt slides", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex" ? [{ id: "codex-1", provider: "codex", authType: "oauth", accessToken: "token" }] : []
+    ));
+    state.resetCache["codex:codex-1"] = "2026-01-01T17:00:00.000Z";
+    getCodexUsage.mockResolvedValue({
+      quotas: { session: { used: 1, total: 100, remaining: 99, resetAt: "2026-01-01T17:01:00.000Z" } },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    const executor = deps.getExecutor.mock.results[0].value;
+    expect(executor.execute).toHaveBeenCalledTimes(1);
+    expect(deps.updateProviderConnection).toHaveBeenCalledWith("codex-1", expect.objectContaining({
+      lastPingedResetAt: "2026-01-01T17:01:00.000Z",
+      lastPingedResetKey: "2026-01-01T17:01:00.000Z",
+    }));
+  });
+
+  it("does not ping Codex when resetAt is stable", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex" ? [{ id: "codex-1", provider: "codex", authType: "oauth", accessToken: "token" }] : []
+    ));
+    state.resetCache["codex:codex-1"] = "2026-01-01T17:00:00.000Z";
+    getCodexUsage.mockResolvedValue({
+      quotas: { session: { used: 1, total: 100, remaining: 99, resetAt: "2026-01-01T17:00:00.000Z" } },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(deps.getExecutor).not.toHaveBeenCalled();
+    expect(deps.updateProviderConnection).not.toHaveBeenCalled();
+  });
+
+  it("does not repeat Codex ping inside the minimum ping interval", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex"
+        ? [{ id: "codex-1", provider: "codex", authType: "oauth", accessToken: "token", lastPingAt: "2026-01-01T11:55:00.000Z" }]
+        : []
+    ));
+    state.resetCache["codex:codex-1"] = "2026-01-01T17:00:00.000Z";
+    getCodexUsage.mockResolvedValue({
+      quotas: { session: { used: 1, total: 100, remaining: 99, resetAt: "2026-01-01T17:01:00.000Z" } },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(deps.getExecutor).not.toHaveBeenCalled();
+    expect(deps.updateProviderConnection).not.toHaveBeenCalled();
+  });
+
+  it("does not ping Codex just because reported usage is zero", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex" ? [{ id: "codex-1", provider: "codex", authType: "oauth", accessToken: "token" }] : []
+    ));
+    getCodexUsage.mockResolvedValue({
+      quotas: { session: { used: 0, resetAt: "2026-01-01T17:00:00.000Z" } },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(deps.getExecutor).not.toHaveBeenCalled();
+    expect(deps.updateProviderConnection).not.toHaveBeenCalled();
+    expect(state.resetCache["codex:codex-1"]).toBe("2026-01-01T17:00:00.000Z");
+  });
+
+  it("does not ping Codex when weekly quota is exhausted", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex" ? [{ id: "codex-1", provider: "codex", authType: "oauth", accessToken: "token" }] : []
+    ));
+    state.resetCache["codex:codex-1"] = "2026-01-01T17:00:00.000Z";
+    getCodexUsage.mockResolvedValue({
+      quotas: {
+        session: { used: 0, total: 100, remaining: 100, resetAt: "2026-01-01T17:01:00.000Z" },
+        weekly: { used: 100, total: 100, remaining: 0, resetAt: "2026-01-03T12:00:00.000Z" },
+      },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(deps.getExecutor).not.toHaveBeenCalled();
+    expect(deps.updateProviderConnection).not.toHaveBeenCalled();
+  });
+
+  it("does not ping Codex when monthly quota is exhausted", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex" ? [{ id: "codex-1", provider: "codex", authType: "oauth", accessToken: "token" }] : []
+    ));
+    state.resetCache["codex:codex-1"] = "2026-01-01T17:00:00.000Z";
+    getCodexUsage.mockResolvedValue({
+      quotas: {
+        session: { used: 0, total: 100, remaining: 100, resetAt: "2026-01-01T17:01:00.000Z" },
+        monthly: { used: 100, total: 100, remaining: 0, resetAt: "2026-02-01T00:00:00.000Z" },
+      },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(deps.getExecutor).not.toHaveBeenCalled();
+    expect(deps.updateProviderConnection).not.toHaveBeenCalled();
+  });
+
+  it("does not ping Codex when session quota is exhausted", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex" ? [{ id: "codex-1", provider: "codex", authType: "oauth", accessToken: "token" }] : []
+    ));
+    state.resetCache["codex:codex-1"] = "2026-01-01T17:00:00.000Z";
+    getCodexUsage.mockResolvedValue({
+      quotas: { session: { used: 100, total: 100, remaining: 0, resetAt: "2026-01-01T17:01:00.000Z" } },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(deps.getExecutor).not.toHaveBeenCalled();
+    expect(deps.updateProviderConnection).not.toHaveBeenCalled();
+  });
+
+  it("sends one tiny gpt-5.5 Codex request through the executor", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex"
+        ? [{ id: "codex-1", provider: "codex", authType: "oauth", accessToken: "token", providerSpecificData: { workspaceId: "ws-1" } }]
+        : []
+    ));
+    state.resetCache["codex:codex-1"] = "2026-01-01T17:00:00.000Z";
+    getCodexUsage.mockResolvedValue({
+      quotas: { session: { used: 1, total: 100, remaining: 99, resetAt: "2026-01-01T17:01:00.000Z" } },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    const executor = deps.getExecutor.mock.results[0].value;
+    expect(deps.getExecutor).toHaveBeenCalledWith("codex");
+    expect(executor.execute).toHaveBeenCalledWith(expect.objectContaining({
+      model: "gpt-5.5",
+      stream: true,
+      credentials: expect.objectContaining({
+        accessToken: "token",
+        connectionId: "codex-1",
+        providerSpecificData: { workspaceId: "ws-1" },
+      }),
+      body: {
+        model: "gpt-5.5",
+        input: [{
+          type: "message",
+          role: "user",
+          content: [{ type: "input_text", text: "hi" }],
+        }],
+        instructions: "Reply with OK.",
+        reasoning: { effort: "none", summary: "auto" },
+        store: false,
+        stream: true,
+      },
+    }));
+    expect(codexResponseText).toHaveBeenCalledTimes(1);
+    expect(deps.updateProviderConnection).toHaveBeenCalledWith("codex-1", expect.objectContaining({
+      lastPingedResetAt: "2026-01-01T17:01:00.000Z",
+      lastPingedResetKey: "2026-01-01T17:01:00.000Z",
+    }));
+  });
+
+  it("does not ping same Codex reset twice when seconds drift", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex"
+        ? [{ id: "codex-1", provider: "codex", authType: "oauth", accessToken: "token", lastPingedResetAt: "2026-01-01T11:59:44.000Z" }]
+        : []
+    ));
+    state.resetCache["codex:codex-1"] = "2026-01-01T11:59:44.000Z";
+    getCodexUsage.mockResolvedValue({
+      quotas: { session: { used: 0, total: 100, remaining: 100, resetAt: "2026-01-01T11:59:47.000Z" } },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(deps.getExecutor).not.toHaveBeenCalled();
+  });
+
+  it("skips non-OAuth Codex connections", async () => {
+    deps.getSettings.mockResolvedValue({ codexAutoPing: { connections: { "codex-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "codex" ? [{ id: "codex-1", provider: "codex", authType: "apikey", accessToken: "token" }] : []
+    ));
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(getCodexUsage).not.toHaveBeenCalled();
+    expect(deps.getExecutor).not.toHaveBeenCalled();
+  });
+
+  it("keeps Claude session quota key behavior", async () => {
+    deps.getSettings.mockResolvedValue({ claudeAutoPing: { connections: { "claude-1": true } } });
+    deps.getProviderConnections.mockImplementation(async ({ provider }) => (
+      provider === "claude" ? [{ id: "claude-1", provider: "claude", authType: "oauth", accessToken: "token" }] : []
+    ));
+    getClaudeUsage.mockResolvedValue({
+      quotas: { "session (5h)": { resetAt: "2026-01-01T11:59:00.000Z" } },
+    });
+
+    await runQuotaAutoPingTick(deps, state);
+
+    expect(deps.proxyAwareFetch).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(deps.proxyAwareFetch.mock.calls[0][1].body)).toMatchObject({
+      model: "claude-haiku-4-5-20251001",
+      max_tokens: 1,
+      messages: [{ role: "user", content: "hi" }],
+    });
+  });
+});
diff --git a/tests/unit/reasoningContentInjector.test.js b/tests/unit/reasoningContentInjector.test.js
new file mode 100644
index 0000000..b0e360c
--- /dev/null
+++ b/tests/unit/reasoningContentInjector.test.js
@@ -0,0 +1,160 @@
+/**
+ * Unit tests for reasoningContentInjector (issue #1543).
+ *
+ * DeepSeek V4 thinking mode rejects follow-up requests whose assistant
+ * messages omit `reasoning_content` ("The `reasoning_content` in the thinking
+ * mode must be passed back to the API."). OpenAI-format clients strip it, so
+ * the injector echoes a placeholder back. These tests lock that behavior and
+ * guard that the OpenCode executor (which routes deepseek-v4-flash-free)
+ * actually runs the injector.
+ */
+
+import { describe, it, expect } from "vitest";
+import { injectReasoningContent } from "../../open-sse/utils/reasoningContentInjector.js";
+import { OpenCodeExecutor } from "../../open-sse/executors/opencode.js";
+
+const assistantWithToolCall = {
+  role: "assistant",
+  content: "",
+  tool_calls: [{ id: "call_x", type: "function", function: { name: "get_weather", arguments: "{}" } }],
+};
+
+function bodyWith(messages) {
+  return { model: "deepseek-v4-flash", messages, reasoning_effort: "medium" };
+}
+
+describe("injectReasoningContent — DeepSeek thinking round-trip", () => {
+  it("injects reasoning_content on a deepseek- assistant message that lacks it", () => {
+    const out = injectReasoningContent({
+      provider: "opencode",
+      model: "deepseek-v4-flash-free",
+      body: bodyWith([{ role: "user", content: "hi" }, assistantWithToolCall]),
+    });
+    const assistant = out.messages.find((m) => m.role === "assistant");
+    expect(typeof assistant.reasoning_content).toBe("string");
+    expect(assistant.reasoning_content.length).toBeGreaterThan(0);
+  });
+
+  it("preserves an existing reasoning_content instead of overwriting it", () => {
+    const original = "model's real chain of thought";
+    const out = injectReasoningContent({
+      provider: "opencode",
+      model: "deepseek-v4-flash-free",
+      body: bodyWith([{ ...assistantWithToolCall, reasoning_content: original }]),
+    });
+    expect(out.messages[0].reasoning_content).toBe(original);
+  });
+
+  it("applies provider-level rule for provider 'deepseek' (scope all)", () => {
+    const out = injectReasoningContent({
+      provider: "deepseek",
+      model: "deepseek-chat",
+      body: bodyWith([{ role: "assistant", content: "answer" }]),
+    });
+    expect(out.messages[0].reasoning_content).toBeDefined();
+  });
+
+  it("matches deepseek model id case-insensitively for custom providers (#1543)", () => {
+    const out = injectReasoningContent({
+      provider: "openai-compatible-custom",
+      model: "DeepSeek-V4-Flash",
+      body: bodyWith([assistantWithToolCall]),
+    });
+    expect(out.messages[0].reasoning_content).toBeDefined();
+  });
+
+  it("does not touch non-deepseek providers/models", () => {
+    const out = injectReasoningContent({
+      provider: "openai",
+      model: "gpt-5.5",
+      body: bodyWith([{ role: "assistant", content: "answer" }]),
+    });
+    expect(out.messages[0].reasoning_content).toBeUndefined();
+  });
+
+  it("maps deepseek-v4-pro-none alias to disabled thinking and strips reasoning_effort", () => {
+    const out = injectReasoningContent({
+      provider: "deepseek",
+      model: "deepseek-v4-pro-none",
+      body: bodyWith([{ role: "user", content: "hi" }]),
+    });
+    expect(out.model).toBe("deepseek-v4-pro");
+    expect(out.extra_body.thinking.type).toBe("disabled");
+    expect(out.reasoning_effort).toBeUndefined();
+  });
+});
+
+describe("injectReasoningContent — MiniMax thinking round-trip", () => {
+  const minimaxAssistantMsg = { role: "assistant", content: "here is a response", reasoning_content: "" };
+  const minimaxAssistantWithToolCall = {
+    role: "assistant",
+    content: "",
+    tool_calls: [{ id: "call_x", type: "function", function: { name: "get_weather", arguments: "{}" } }],
+    reasoning_content: "",
+  };
+
+  it("injects reasoning_content on a minimax assistant message that lacks it", () => {
+    const out = injectReasoningContent({
+      provider: "minimax",
+      model: "MiniMax-M2.7",
+      body: bodyWith([{ role: "user", content: "hi" }, minimaxAssistantMsg]),
+    });
+    const assistant = out.messages.find((m) => m.role === "assistant");
+    expect(typeof assistant.reasoning_content).toBe("string");
+    expect(assistant.reasoning_content.length).toBeGreaterThan(0);
+  });
+
+  it("injects reasoning_content on minimax assistant message with tool_calls but no reasoning_content", () => {
+    const out = injectReasoningContent({
+      provider: "minimax",
+      model: "MiniMax-M2.7",
+      body: bodyWith([{ role: "user", content: "hi" }, minimaxAssistantWithToolCall]),
+    });
+    const assistant = out.messages.find((m) => m.role === "assistant");
+    expect(typeof assistant.reasoning_content).toBe("string");
+    expect(assistant.reasoning_content.length).toBeGreaterThan(0);
+  });
+
+  it("applies provider-level rule for provider 'minimax-cn' (scope all)", () => {
+    const out = injectReasoningContent({
+      provider: "minimax-cn",
+      model: "MiniMax-M2.5",
+      body: bodyWith([{ role: "assistant", content: "answer" }]),
+    });
+    expect(out.messages[0].reasoning_content).toBeDefined();
+  });
+
+  it("preserves an existing reasoning_content on minimax instead of overwriting", () => {
+    const original = "MiniMax chain of thought reasoning";
+    const out = injectReasoningContent({
+      provider: "minimax",
+      model: "MiniMax-M2.7",
+      body: bodyWith([{ ...minimaxAssistantMsg, reasoning_content: original }]),
+    });
+    expect(out.messages[0].reasoning_content).toBe(original);
+  });
+
+  it("DefaultExecutor transformRequest runs the injector for minimax", () => {
+    const { DefaultExecutor } = require("../../open-sse/executors/default.js");
+    const executor = new DefaultExecutor("minimax");
+    const out = executor.transformRequest(
+      "MiniMax-M2.7",
+      bodyWith([{ role: "user", content: "hi" }, minimaxAssistantMsg]),
+    );
+    const assistant = out.messages.find((m) => m.role === "assistant");
+    expect(typeof assistant.reasoning_content).toBe("string");
+    expect(assistant.reasoning_content.length).toBeGreaterThan(0);
+  });
+});
+
+describe("OpenCodeExecutor — issue #1543 regression", () => {
+  it("runs the injector so deepseek-v4-flash-free round-trips reasoning_content", () => {
+    const executor = new OpenCodeExecutor();
+    const out = executor.transformRequest(
+      "deepseek-v4-flash-free",
+      bodyWith([{ role: "user", content: "hi" }, assistantWithToolCall]),
+    );
+    const assistant = out.messages.find((m) => m.role === "assistant");
+    expect(assistant.reasoning_content).toBeDefined();
+  });
+});
diff --git a/tests/unit/request-details-tab.test.js b/tests/unit/request-details-tab.test.js
new file mode 100644
index 0000000..6b05650
--- /dev/null
+++ b/tests/unit/request-details-tab.test.js
@@ -0,0 +1,252 @@
+// Backend logic behind /dashboard/usage?tab=details.
+// Covers crash-risk edge cases in getRequestDetails() used by
+// /api/usage/request-details and /api/usage/providers.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
+
+const originalDataDir = process.env.DATA_DIR;
+let tempDir;
+let db;
+let adapter;
+
+async function saveDetail(detail) {
+  await db.saveRequestDetail(detail);
+  await new Promise((r) => setTimeout(r, 120));
+}
+
+beforeAll(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "9router-details-tab-"));
+  process.env.DATA_DIR = tempDir;
+  vi.resetModules();
+  db = await import("@/lib/db/index.js");
+  await db.initDb();
+  await db.updateSettings({ enableObservability2: true, observabilityBatchSize: 1 });
+
+  const { getAdapter } = await import("@/lib/db/driver.js");
+  adapter = await getAdapter();
+});
+
+afterAll(() => {
+  if (tempDir) fs.rmSync(tempDir, { recursive: true, force: true });
+  if (originalDataDir === undefined) delete process.env.DATA_DIR;
+  else process.env.DATA_DIR = originalDataDir;
+});
+
+describe("request details — tab crash-risk cases", () => {
+  it("corrupt data column → parseJson fallback {}, no throw", async () => {
+    // Inject a row with invalid JSON directly, bypassing save path
+    adapter.run(
+      `INSERT INTO requestDetails(id, timestamp, provider, model, connectionId, status, data) VALUES(?, ?, ?, ?, ?, ?, ?)`,
+      ["corrupt-1", new Date().toISOString(), "openai", "gpt-4", null, "ok", "{not-valid-json"]
+    );
+
+    const res = await db.getRequestDetails({ provider: "openai" });
+    expect(Array.isArray(res.details)).toBe(true);
+    const corrupt = res.details.find((d) => Object.keys(d).length === 0);
+    expect(corrupt).toEqual({});
+  });
+
+  it("pagination beyond last page → empty details, valid meta", async () => {
+    const res = await db.getRequestDetails({ page: 9999, pageSize: 20 });
+    expect(res.details).toEqual([]);
+    expect(res.pagination.page).toBe(9999);
+    expect(res.pagination.hasNext).toBe(false);
+    expect(res.pagination.totalItems).toBeGreaterThanOrEqual(0);
+  });
+
+  it("invalid startDate → Invalid Date ISO throws inside getRequestDetails is caught upstream", async () => {
+    // new Date("bad").toISOString() throws RangeError; verify it surfaces
+    // so the API route's try/catch returns 500 rather than silent corruption.
+    await expect(db.getRequestDetails({ startDate: "not-a-date" })).rejects.toThrow();
+  });
+
+  it("valid date filter range → no throw", async () => {
+    const res = await db.getRequestDetails({
+      startDate: "2020-01-01T00:00:00",
+      endDate: "2999-01-01T00:00:00",
+    });
+    expect(Array.isArray(res.details)).toBe(true);
+  });
+
+  it("large pageSize (providers route uses 9999) → returns all, no crash", async () => {
+    await saveDetail({
+      id: "big-1", provider: "anthropic", model: "claude-3",
+      status: "ok", tokens: { input_tokens: 5 },
+      request: { method: "POST" }, response: { content: "hi" },
+    });
+
+    const res = await db.getRequestDetails({ pageSize: 9999 });
+    expect(res.details.length).toBeGreaterThanOrEqual(1);
+    expect(res.pagination.pageSize).toBe(9999);
+  });
+
+  it("oversized field → stored truncated + reparseable (no circular)", async () => {
+    const huge = "x".repeat(20 * 1024);
+    await saveDetail({
+      id: "trunc-1", provider: "openai", model: "gpt-4",
+      status: "ok", tokens: {},
+      request: { blob: huge }, response: { content: "ok" },
+    });
+
+    const got = await db.getRequestDetailById("trunc-1");
+    expect(got).toBeDefined();
+    // Truncated field is a plain object safe for JSON.stringify in the drawer
+    expect(() => JSON.stringify(got)).not.toThrow();
+    expect(got.request._truncated).toBe(true);
+  });
+
+  it("missing tokens/timestamp on row → getInputTokens-style access safe", async () => {
+    adapter.run(
+      `INSERT INTO requestDetails(id, timestamp, provider, model, connectionId, status, data) VALUES(?, ?, ?, ?, ?, ?, ?)`,
+      ["sparse-1", new Date().toISOString(), "openai", null, null, null, JSON.stringify({ id: "sparse-1" })]
+    );
+    const got = await db.getRequestDetailById("sparse-1");
+    expect(got.tokens).toBeUndefined();
+    // Drawer reads tokens?.prompt_tokens — optional chaining tolerates undefined
+    expect(got.tokens?.prompt_tokens || 0).toBe(0);
+  });
+});
+
+// Mirror of RequestDetailsTab token helpers (component is "use client",
+// helpers are not exported). Keep in sync with the component.
+function getCachedTokens(tokens) {
+  return tokens?.cached_tokens || tokens?.cache_read_input_tokens || 0;
+}
+function getCacheCreationTokens(tokens) {
+  return tokens?.cache_creation_input_tokens || 0;
+}
+function getInputTokens(tokens) {
+  const prompt = tokens?.prompt_tokens || tokens?.input_tokens || 0;
+  const cache = getCachedTokens(tokens);
+  return prompt < cache ? cache : prompt;
+}
+
+describe("backupDbLite — excludes requestDetails, keeps critical data", () => {
+  it("backup file omits requestDetails rows but keeps other tables", async () => {
+    const { backupDbLite } = await import("@/lib/db/backup.js");
+    await saveDetail({ id: "bk-1", provider: "openai", model: "m", status: "ok", tokens: {}, request: {}, response: {} });
+
+    const backupDir = fs.mkdtempSync(path.join(os.tmpdir(), "9router-bklite-"));
+    const dest = backupDbLite(adapter, backupDir);
+    expect(fs.existsSync(dest)).toBe(true);
+
+    // Open backup and assert requestDetails is empty, settings present
+    const Database = (await import("better-sqlite3")).default;
+    const bak = new Database(dest);
+    try {
+      // requestDetails is fully excluded — table must not exist in the backup
+      const rdTable = bak.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='requestDetails'").get();
+      expect(rdTable).toBeUndefined();
+      // Critical data preserved
+      const st = bak.prepare("SELECT COUNT(*) c FROM settings").get();
+      expect(st.c).toBeGreaterThanOrEqual(1);
+    } finally {
+      bak.close();
+      fs.rmSync(backupDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("getDistinctProviders — providers route (no full-row parse)", () => {
+  it("returns unique provider list without parsing data blobs", async () => {
+    await saveDetail({ id: "dp-1", provider: "openai", model: "m", status: "ok", tokens: {}, request: {}, response: {} });
+    await saveDetail({ id: "dp-2", provider: "anthropic", model: "m", status: "ok", tokens: {}, request: {}, response: {} });
+    await saveDetail({ id: "dp-3", provider: "openai", model: "m", status: "ok", tokens: {}, request: {}, response: {} });
+
+    const list = await db.getDistinctProviders();
+    expect(Array.isArray(list)).toBe(true);
+    expect(list).toContain("openai");
+    expect(list).toContain("anthropic");
+    // No duplicates
+    expect(new Set(list).size).toBe(list.length);
+  });
+
+  it("skips null providers, returns sorted", async () => {
+    const list = await db.getDistinctProviders();
+    expect(list.every((p) => p !== null)).toBe(true);
+    const sorted = [...list].sort();
+    expect(list).toEqual(sorted);
+  });
+});
+
+describe("token helpers — render-time crash safety", () => {
+  it("undefined/null tokens → 0, no throw", () => {
+    expect(getInputTokens(undefined)).toBe(0);
+    expect(getInputTokens(null)).toBe(0);
+    expect(getCachedTokens(undefined)).toBe(0);
+    expect(getCacheCreationTokens(null)).toBe(0);
+  });
+
+  it("empty object → 0 across all helpers", () => {
+    expect(getInputTokens({})).toBe(0);
+    expect(getCachedTokens({})).toBe(0);
+    expect(getCacheCreationTokens({})).toBe(0);
+  });
+
+  it("prompt_tokens preferred, falls back to input_tokens", () => {
+    expect(getInputTokens({ prompt_tokens: 100 })).toBe(100);
+    expect(getInputTokens({ input_tokens: 50 })).toBe(50);
+  });
+
+  it("legacy Claude row (prompt < cache) → returns cache", () => {
+    expect(getInputTokens({ prompt_tokens: 10, cached_tokens: 200 })).toBe(200);
+  });
+
+  it("cached via cache_read_input_tokens alias", () => {
+    expect(getCachedTokens({ cache_read_input_tokens: 42 })).toBe(42);
+  });
+
+  it("toLocaleString on helper result never throws", () => {
+    expect(() => getInputTokens(undefined).toLocaleString()).not.toThrow();
+  });
+});
+
+describe("API route contract — validation boundary", () => {
+  let GET;
+  beforeAll(async () => {
+    ({ GET } = await import("@/app/api/usage/request-details/route.js"));
+  });
+
+  function makeReq(query) {
+    return new Request(`http://localhost/api/usage/request-details?${query}`);
+  }
+
+  it("page=0 → 400 (guard now reachable after NaN-check fix)", async () => {
+    const res = await GET(makeReq("page=0"));
+    expect(res.status).toBe(400);
+  });
+
+  it("page=-5 → 400", async () => {
+    const res = await GET(makeReq("page=-5"));
+    expect(res.status).toBe(400);
+  });
+
+  it("pageSize=101 → 400", async () => {
+    const res = await GET(makeReq("pageSize=101"));
+    expect(res.status).toBe(400);
+  });
+
+  it("pageSize=abc (NaN) → defaults to 20, returns 200", async () => {
+    const res = await GET(makeReq("pageSize=abc"));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.pagination.pageSize).toBe(20);
+  });
+
+  it("invalid startDate → route catches, returns 500 (not thrown)", async () => {
+    const res = await GET(makeReq("startDate=not-a-date"));
+    expect(res.status).toBe(500);
+    const body = await res.json();
+    expect(body.error).toBeDefined();
+  });
+
+  it("valid request → 200 with details + pagination shape", async () => {
+    const res = await GET(makeReq("page=1&pageSize=20"));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(Array.isArray(body.details)).toBe(true);
+    expect(body.pagination).toMatchObject({ page: 1, pageSize: 20 });
+  });
+});
diff --git a/tests/unit/responses-abort-terminal.test.js b/tests/unit/responses-abort-terminal.test.js
new file mode 100644
index 0000000..10af584
--- /dev/null
+++ b/tests/unit/responses-abort-terminal.test.js
@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+
+import { createDisconnectAwareStream } from "../../open-sse/utils/streamHandler.js";
+import { buildAbortedResponsesTerminalBytes } from "../../open-sse/utils/responsesStreamHelpers.js";
+
+// Minimal stream controller stub
+function makeController() {
+  let connected = true;
+  return {
+    signal: new AbortController().signal,
+    startTime: Date.now(),
+    isConnected: () => connected,
+    handleComplete: () => { connected = false; },
+    handleError: () => { connected = false; },
+    handleDisconnect: () => { connected = false; },
+    abort: () => { connected = false; },
+  };
+}
+
+async function readAll(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    text += decoder.decode(value, { stream: true });
+  }
+  text += decoder.decode();
+  return text;
+}
+
+describe("Responses abort terminal synthesis", () => {
+  it("emits response.failed + [DONE] when upstream errors (abort/stall)", async () => {
+    // Upstream readable that errors mid-stream (simulates fetch abort on stall)
+    const upstream = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode("event: response.created\ndata: {}\n\n"));
+        controller.error(new Error("stream stall timeout"));
+      },
+    });
+
+    const out = createDisconnectAwareStream(
+      { readable: upstream, writable: { getWriter: () => ({ abort: () => Promise.resolve() }) } },
+      makeController(),
+      buildAbortedResponsesTerminalBytes
+    );
+
+    const text = await readAll(out);
+    expect(text).toContain("event: response.failed");
+    expect(text).toContain("data: [DONE]");
+  });
+
+  it("does not synthesize terminal for non-Responses streams (callback null)", async () => {
+    const upstream = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode("data: hi\n\n"));
+        controller.error(new Error("socket hang up"));
+      },
+    });
+
+    const out = createDisconnectAwareStream(
+      { readable: upstream, writable: { getWriter: () => ({ abort: () => Promise.resolve() }) } },
+      makeController(),
+      null
+    );
+
+    const text = await readAll(out);
+    expect(text).not.toContain("response.failed");
+    expect(text).not.toContain("[DONE]");
+  });
+});
diff --git a/tests/unit/rtk.e2e.test.js b/tests/unit/rtk.e2e.test.js
new file mode 100644
index 0000000..a7d4268
--- /dev/null
+++ b/tests/unit/rtk.e2e.test.js
@@ -0,0 +1,136 @@
+// End-to-end integration test: hit live local proxy and verify [RTK] behavior.
+// Run with: RUN_E2E=1 RTK_E2E_PORT=... RTK_E2E_KEY=... RTK_E2E_LOG=<absolute path to server stdout file> npm test rtk.e2e.test.js
+// Requires: dev server running, rtkEnabled=true, API key present.
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+
+const PORT = process.env.RTK_E2E_PORT || "20128";
+const BASE = `http://localhost:${PORT}`;
+const API_KEY = process.env.RTK_E2E_KEY || "";
+const LOG_FILE = process.env.RTK_E2E_LOG || "";
+
+const RUN = process.env.RUN_E2E === "1";
+const maybe = RUN ? describe : describe.skip;
+
+function readLogTail(bytes = 8192) {
+  if (!LOG_FILE || !fs.existsSync(LOG_FILE)) return "";
+  const stat = fs.statSync(LOG_FILE);
+  const start = Math.max(0, stat.size - bytes);
+  const fd = fs.openSync(LOG_FILE, "r");
+  const buf = Buffer.alloc(stat.size - start);
+  fs.readSync(fd, buf, 0, buf.length, start);
+  fs.closeSync(fd);
+  return buf.toString("utf8");
+}
+
+// Read new bytes appended to log since `offset`. Returns text + new offset.
+function readLogSince(offset) {
+  if (!LOG_FILE || !fs.existsSync(LOG_FILE)) return { text: "", next: offset };
+  const stat = fs.statSync(LOG_FILE);
+  if (stat.size <= offset) return { text: "", next: stat.size };
+  const fd = fs.openSync(LOG_FILE, "r");
+  const buf = Buffer.alloc(stat.size - offset);
+  fs.readSync(fd, buf, 0, buf.length, offset);
+  fs.closeSync(fd);
+  return { text: buf.toString("utf8"), next: stat.size };
+}
+
+function logOffset() {
+  if (!LOG_FILE || !fs.existsSync(LOG_FILE)) return 0;
+  return fs.statSync(LOG_FILE).size;
+}
+
+async function sendChat(body) {
+  return fetch(`${BASE}/v1/chat/completions`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "authorization": `Bearer ${API_KEY}` },
+    body: JSON.stringify(body)
+  });
+}
+
+function makeBigDiff(fileCount = 3, linesPerFile = 80) {
+  const out = [];
+  for (let f = 0; f < fileCount; f++) {
+    out.push(`diff --git a/src/file${f}.js b/src/file${f}.js`);
+    out.push(`index abc${f}..def${f} 100644`);
+    out.push(`--- a/src/file${f}.js`);
+    out.push(`+++ b/src/file${f}.js`);
+    out.push(`@@ -1,${linesPerFile} +1,${linesPerFile} @@`);
+    for (let i = 0; i < linesPerFile; i++) {
+      out.push(`-const old${f}_${i} = "removed value ${i} padding padding padding";`);
+      out.push(`+const new${f}_${i} = "added value ${i} padding padding padding padding";`);
+    }
+  }
+  return out.join("\n");
+}
+
+maybe("RTK end-to-end", () => {
+  it("server is reachable", async () => {
+    const res = await fetch(`${BASE}/api/health`);
+    expect(res.ok).toBe(true);
+  });
+
+  it("rtkEnabled flag is true (user must enable via dashboard)", async () => {
+    const res = await fetch(`${BASE}/api/settings`);
+    const data = await res.json();
+    expect(data.rtkEnabled).toBe(true);
+  });
+
+  it("compresses git diff tool_result and writes [RTK] savings to log", async () => {
+    const diff = makeBigDiff(2, 60);
+    expect(diff.length).toBeGreaterThan(500);
+
+    const offset = logOffset();
+    const res = await sendChat({
+      model: "cc/claude-opus-4-7",
+      stream: false,
+      max_tokens: 64,
+      messages: [
+        { role: "user", content: "run git diff" },
+        { role: "assistant", content: null, tool_calls: [{ id: "call_1", type: "function", function: { name: "Bash", arguments: JSON.stringify({ command: "git diff" }) } }] },
+        { role: "tool", tool_call_id: "call_1", content: diff },
+        { role: "user", content: "summarize in 10 words" }
+      ]
+    });
+    expect([200, 400, 401, 402, 500]).toContain(res.status);
+
+    if (!LOG_FILE) return;
+    await new Promise(r => setTimeout(r, 500));
+    const { text } = readLogSince(offset);
+    const matches = [...text.matchAll(/\[RTK\] saved (\d+)B \/ (\d+)B \([\d.]+%\) via \[([\w,-]+)\] hits=(\d+)/g)];
+    // Find the log line that corresponds to OUR request (total ≥ diff.length and contains git-diff)
+    const mine = matches.find(m => Number(m[2]) >= diff.length && m[3].includes("git-diff"));
+    expect(mine, `no matching [RTK] line for our request (diff=${diff.length}B) in ${matches.length} log entries`).toBeTruthy();
+    expect(Number(mine[1])).toBeGreaterThan(500);
+    expect(mine[3]).toContain("git-diff");
+    expect(Number(mine[4])).toBeGreaterThanOrEqual(1);
+  });
+
+  it("compresses grep-style tool_result", async () => {
+    const lines = [];
+    for (let i = 1; i <= 30; i++) lines.push(`src/lib/foo.js:${i}:const v${i} = "matching content with enough padding to exceed threshold";`);
+    const grepOut = lines.join("\n");
+    expect(grepOut.length).toBeGreaterThan(500);
+
+    const offset = logOffset();
+    const res = await sendChat({
+      model: "cc/claude-opus-4-7",
+      stream: false,
+      max_tokens: 32,
+      messages: [
+        { role: "user", content: "grep" },
+        { role: "assistant", content: null, tool_calls: [{ id: "c3", type: "function", function: { name: "Bash", arguments: "{}" } }] },
+        { role: "tool", tool_call_id: "c3", content: grepOut },
+        { role: "user", content: "ok" }
+      ]
+    });
+    expect([200, 400, 401, 402, 500]).toContain(res.status);
+
+    if (!LOG_FILE) return;
+    await new Promise(r => setTimeout(r, 500));
+    const { text } = readLogSince(offset);
+    const matches = [...text.matchAll(/\[RTK\] saved (\d+)B \/ (\d+)B \([\d.]+%\) via \[([\w,-]+)\] hits=(\d+)/g)];
+    const mine = matches.find(m => Number(m[2]) >= grepOut.length && m[3].includes("grep"));
+    expect(mine, `no matching [RTK] line for grep payload`).toBeTruthy();
+  });
+});
diff --git a/tests/unit/rtk.multi-provider.e2e.test.js b/tests/unit/rtk.multi-provider.e2e.test.js
new file mode 100644
index 0000000..69da14b
--- /dev/null
+++ b/tests/unit/rtk.multi-provider.e2e.test.js
@@ -0,0 +1,137 @@
+// E2E test: verify RTK compression runs for every configured provider/route.
+// Each test covers a different source→target translator path.
+// Run with: RUN_E2E=1 RTK_E2E_PORT=... RTK_E2E_KEY=... RTK_E2E_LOG=<server stdout file> npm test rtk.multi-provider.e2e.test.js
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+
+const PORT = process.env.RTK_E2E_PORT || "20128";
+const BASE = `http://localhost:${PORT}`;
+const API_KEY = process.env.RTK_E2E_KEY || "";
+const LOG_FILE = process.env.RTK_E2E_LOG || "";
+
+const RUN = process.env.RUN_E2E === "1";
+const maybe = RUN ? describe : describe.skip;
+
+function logOffset() {
+  if (!LOG_FILE || !fs.existsSync(LOG_FILE)) return 0;
+  return fs.statSync(LOG_FILE).size;
+}
+
+function readLogSince(offset) {
+  if (!LOG_FILE || !fs.existsSync(LOG_FILE)) return "";
+  const stat = fs.statSync(LOG_FILE);
+  if (stat.size <= offset) return "";
+  const fd = fs.openSync(LOG_FILE, "r");
+  const buf = Buffer.alloc(stat.size - offset);
+  fs.readSync(fd, buf, 0, buf.length, offset);
+  fs.closeSync(fd);
+  return buf.toString("utf8");
+}
+
+function makeBigDiff(fileCount = 2, linesPerFile = 60) {
+  const out = [];
+  for (let f = 0; f < fileCount; f++) {
+    out.push(`diff --git a/src/file${f}.js b/src/file${f}.js`);
+    out.push(`index abc${f}..def${f} 100644`);
+    out.push(`--- a/src/file${f}.js`);
+    out.push(`+++ b/src/file${f}.js`);
+    out.push(`@@ -1,${linesPerFile} +1,${linesPerFile} @@`);
+    for (let i = 0; i < linesPerFile; i++) {
+      out.push(`-const old${f}_${i} = "removed value ${i} padding padding padding";`);
+      out.push(`+const new${f}_${i} = "added value ${i} padding padding padding padding";`);
+    }
+  }
+  return out.join("\n");
+}
+
+async function sendChat(body) {
+  return fetch(`${BASE}/v1/chat/completions`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "authorization": `Bearer ${API_KEY}` },
+    body: JSON.stringify(body)
+  });
+}
+
+// Wait for server to emit a matching [RTK] log line (race-safe against concurrent traffic).
+async function waitForRtkLine({ minBytes, filterName, timeoutMs = 5000 }) {
+  const start = Date.now();
+  const startOffset = logOffset();
+  while (Date.now() - start < timeoutMs) {
+    const text = readLogSince(startOffset);
+    const matches = [...text.matchAll(/\[RTK\] saved (\d+)B \/ (\d+)B \(([\d.]+)%\) via \[([\w,-]+)\] hits=(\d+)/g)];
+    const mine = matches.find(m => Number(m[2]) >= minBytes && m[4].includes(filterName));
+    if (mine) {
+      return {
+        saved: Number(mine[1]),
+        total: Number(mine[2]),
+        pct: Number(mine[3]),
+        filters: mine[4],
+        hits: Number(mine[5])
+      };
+    }
+    await new Promise(r => setTimeout(r, 200));
+  }
+  return null;
+}
+
+// Build a chat request with OpenAI-style tool_result carrying large content.
+function chatBodyWithDiff(model, diff) {
+  return {
+    model,
+    stream: false,
+    max_tokens: 16,
+    messages: [
+      { role: "user", content: "run git diff" },
+      {
+        role: "assistant",
+        content: null,
+        tool_calls: [{ id: "call_1", type: "function", function: { name: "Bash", arguments: JSON.stringify({ command: "git diff" }) } }]
+      },
+      { role: "tool", tool_call_id: "call_1", content: diff },
+      { role: "user", content: "ok" }
+    ]
+  };
+}
+
+// Matrix of routes to cover — one entry per translator target format.
+const ROUTES = [
+  { name: "claude (cc/* → openai→claude)",        model: "cc/claude-opus-4-7" },
+  { name: "codex (cx/* → openai→openai-responses)", model: "cx/gpt-5.4" },
+  { name: "antigravity (ag/* → openai→antigravity)", model: "ag/gemini-3-flash" },
+  { name: "cursor (cu/* → openai→cursor)",         model: "cu/claude-4.5-sonnet" },
+  { name: "kiro (kr/* → openai→kiro)",             model: "kr/claude-sonnet-4.5" },
+  { name: "gemini (gemini/* → openai→gemini)",     model: "gemini/gemini-2.5-flash" },
+  { name: "deepseek (deepseek/* → openai, passthrough)", model: "deepseek/deepseek-chat" },
+  { name: "ollama (ollama/* → openai→ollama)",     model: "ollama/gpt-oss:120b" },
+];
+
+maybe("RTK multi-provider E2E", () => {
+  it("server reachable and rtkEnabled=true", async () => {
+    const health = await fetch(`${BASE}/api/health`);
+    expect(health.ok).toBe(true);
+    const settings = await fetch(`${BASE}/api/settings`).then(r => r.json());
+    expect(settings.rtkEnabled).toBe(true);
+  });
+
+  for (const route of ROUTES) {
+    it(`compresses git diff for ${route.name}`, async () => {
+      const diff = makeBigDiff();
+      expect(diff.length).toBeGreaterThan(500);
+
+      const res = await sendChat(chatBodyWithDiff(route.model, diff));
+      // Provider may respond with 200/400/401/402/404/429/500 depending on account state.
+      // The important thing: proxy must NOT crash (we just need status code).
+      expect(res.status).toBeGreaterThanOrEqual(200);
+      expect(res.status).toBeLessThan(600);
+
+      if (!LOG_FILE) return;
+      const hit = await waitForRtkLine({ minBytes: diff.length, filterName: "git-diff" });
+      expect(hit, `[RTK] git-diff log line not found for ${route.name}`).toBeTruthy();
+      expect(hit.saved).toBeGreaterThan(500);
+      expect(hit.filters).toContain("git-diff");
+
+      // Log actual savings for visibility
+      console.log(`  ✓ ${route.name}: saved ${hit.saved}B / ${hit.total}B (${hit.pct}%) filters=${hit.filters}`);
+    }, 20000);
+  }
+});
diff --git a/tests/unit/rtk.test.js b/tests/unit/rtk.test.js
new file mode 100644
index 0000000..c8009df
--- /dev/null
+++ b/tests/unit/rtk.test.js
@@ -0,0 +1,525 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { compressMessages, formatRtkLog } from "../../open-sse/rtk/index.js";
+import { gitDiff } from "../../open-sse/rtk/filters/gitDiff.js";
+import { gitStatus } from "../../open-sse/rtk/filters/gitStatus.js";
+import { grep } from "../../open-sse/rtk/filters/grep.js";
+import { find } from "../../open-sse/rtk/filters/find.js";
+import { dedupLog } from "../../open-sse/rtk/filters/dedupLog.js";
+import { ls } from "../../open-sse/rtk/filters/ls.js";
+import { tree } from "../../open-sse/rtk/filters/tree.js";
+import { smartTruncate } from "../../open-sse/rtk/filters/smartTruncate.js";
+import { readNumbered } from "../../open-sse/rtk/filters/readNumbered.js";
+import { searchList } from "../../open-sse/rtk/filters/searchList.js";
+import { gitLog } from "../../open-sse/rtk/filters/gitLog.js";
+import { autoDetectFilter } from "../../open-sse/rtk/autodetect.js";
+import { safeApply } from "../../open-sse/rtk/applyFilter.js";
+
+function makeLongDiff() {
+  const lines = ["diff --git a/foo.js b/foo.js", "index abc..def 100644", "--- a/foo.js", "+++ b/foo.js", "@@ -1,3 +1,200 @@"];
+  for (let i = 0; i < 200; i++) lines.push(`+added line ${i} ${"x".repeat(20)}`);
+  return lines.join("\n");
+}
+
+function makeGitStatus() {
+  return [
+    "On branch main",
+    "Your branch is up to date with 'origin/main'.",
+    "",
+    "Changes not staged for commit:",
+    "  (use \"git add <file>...\" to update what will be committed)",
+    "\tmodified:   src/a.js",
+    "\tmodified:   src/b.js",
+    "\tnew file:   src/c.js",
+    "\tdeleted:    src/old.js",
+    "",
+    "Untracked files:",
+    "\tnotes.txt",
+    "",
+    "no changes added to commit"
+  ].join("\n");
+}
+
+function makeGrepOutput() {
+  const lines = [];
+  for (let i = 1; i <= 40; i++) lines.push(`src/foo.js:${i}:const x${i} = "some value here with padding text padding text"`);
+  for (let i = 1; i <= 10; i++) lines.push(`src/bar.js:${i}:const y${i} = "another value here with padding padding padding"`);
+  return lines.join("\n");
+}
+
+function makeFindOutput() {
+  const lines = [];
+  for (let i = 0; i < 30; i++) lines.push(`./src/a/${i}.js`);
+  for (let i = 0; i < 20; i++) lines.push(`./src/b/${i}.js`);
+  for (let i = 0; i < 5; i++) lines.push(`./top${i}.md`);
+  return lines.join("\n");
+}
+
+function makeGitLogOneline() {
+  return [
+    "abc1234 Add auth middleware",
+    "def5678 Fix token refresh race",
+    "fedcba9 Update docs"
+  ].join("\n");
+}
+
+function makeGitLogDefault() {
+  return [
+    "commit abc1234def5678abc1234def5678abc1234def5",
+    "Author: Dev One <dev1@example.com>",
+    "Date:   Sun Jul 6 10:00:00 2026 +0700",
+    "",
+    "    Add auth middleware",
+    "",
+    "    More body detail should be dropped.",
+    "    This is padding that consumes tokens."
+  ].join("\n");
+}
+
+function makeGitLogGraph() {
+  return [
+    "* abc1234 Add auth middleware",
+    "| * def5678 Fix token refresh race",
+    "|/",
+    "* fedcba9 Update docs"
+  ].join("\n");
+}
+
+function makeGitLogGraphDefault() {
+  return [
+    "*   commit abc1234def5678abc1234def5678abc1234def5",
+    "|\\",
+    "| * commit def5678abc1234def5678abc1234def5678abc1",
+    "|/",
+    "|",
+    "* commit fedcba9abc1234fedcba9abc1234fedcba9abc1234",
+    "Author: Dev One <dev1@example.com>",
+    "Date:   Sun Jul 6 10:00:00 2026 +0700",
+    "",
+    "    Add auth middleware",
+    ""
+  ].join("\n");
+}
+
+function makeGitLogWithMerge() {
+  return [
+    "commit abc1234def5678abc1234def5678abc1234def5",
+    "Merge: abc1234 def5678",
+    "Author: Dev One <dev1@example.com>",
+    "Date:   Sun Jul 6 10:00:00 2026 +0700",
+    "",
+    "    Merge branch 'feature'"
+  ].join("\n");
+}
+
+function makeGitLogWithStats() {
+  return [
+    "commit abc1234def5678abc1234def5678abc1234def5",
+    "Author: Dev One <dev1@example.com>",
+    "Date:   Sun Jul 6 10:00:00 2026 +0700",
+    "",
+    "    Fix typo",
+    "",
+    " 2 files changed, 15 insertions(+), 3 deletions(-)"
+  ].join("\n");
+}
+
+function makeGitLogWithEmbeddedDiff() {
+  return [
+    "commit abc1234def5678abc1234def5678abc1234def5",
+    "Author: Dev One <dev1@example.com>",
+    "Date:   Sun Jul 6 10:00:00 2026 +0700",
+    "",
+    "    Fix typo",
+    "",
+    "diff --git a/src/main.js b/src/main.js"
+  ].join("\n");
+}
+
+describe("gitLog filter", () => {
+  it("compresses git log --oneline without losing commit subjects", () => {
+    const input = makeGitLogOneline();
+    const out = gitLog(input);
+    expect(out).toContain("abc1234");
+    expect(out).toContain("Add auth middleware");
+    expect(out.length).toBeLessThanOrEqual(input.length);
+  });
+
+  it("keeps commit header + subject in default git log, drops body detail", () => {
+    const input = makeGitLogDefault();
+    const out = gitLog(input);
+    expect(out).toContain("commit abc1234def5678abc1234def5678abc1234def5");
+    expect(out).toContain("Add auth middleware");
+    expect(out).not.toContain("More body detail should be dropped.");
+  });
+
+  it("strips graph-only decoration but keeps commit subjects", () => {
+    const input = makeGitLogGraph();
+    const out = gitLog(input);
+    expect(out).toContain("abc1234 Add auth middleware");
+    expect(out).toContain("def5678 Fix token refresh race");
+    expect(out).not.toContain("|/");
+  });
+
+  it("returns empty string for empty input", () => {
+    expect(gitLog("")).toBe("");
+  });
+
+  it("returns empty string for null/undefined input", () => {
+    expect(gitLog(null)).toBe("");
+    expect(gitLog(undefined)).toBe("");
+  });
+
+  it("handles git log --graph without --oneline (graph-prefixed commit headers)", () => {
+    const input = makeGitLogGraphDefault();
+    const out = gitLog(input);
+    expect(out).toContain("commit abc1234def5678abc1234def5678abc1234def5");
+    expect(out).toContain("Add auth middleware");
+    // graph decoration dropped, pure-graph branch connectors dropped
+    expect(out).not.toContain("|\\");
+    expect(out).not.toContain("|/");
+  });
+
+  it("drops merge commit line ('Merge: abc1234 def5678')", () => {
+    const input = makeGitLogWithMerge();
+    const out = gitLog(input);
+    expect(out).toContain("commit abc1234def5678abc1234def5678abc1234def5");
+    expect(out).toContain("Merge branch 'feature'");
+    // "Merge:" line should be dropped (not in output)
+    expect(out).not.toContain("Merge:");
+  });
+
+  it("keeps stat-summary lines verbatim", () => {
+    const input = makeGitLogWithStats();
+    const out = gitLog(input);
+    expect(out).toContain("2 files changed, 15 insertions(+), 3 deletions(-)");
+  });
+
+  it("replaces embedded diff markers with '... diff body omitted'", () => {
+    const input = makeGitLogWithEmbeddedDiff();
+    const out = gitLog(input);
+    expect(out).toContain("diff body omitted");
+    // Original diff line replaced
+    expect(out).not.toContain("diff --git a/src/main.js b/src/main.js");
+  });
+
+  it("truncates beyond maxLines and reports skipped count", () => {
+    // Generate 50 commit lines but cap at 20
+    const lines = [];
+    for (let i = 0; i < 50; i++) {
+      lines.push(`commit ${String(i).padStart(40, "0")}`);
+    }
+    const input = lines.join("\n");
+    const out = gitLog(input, 20);
+    const outLines = out.split("\n").filter(l => l.length > 0);
+    expect(outLines.length).toBeLessThanOrEqual(21); // 20 commits + optional skipped note
+    expect(out).toContain("more lines");
+  });
+
+  it("preserves input when compressed output inflates", () => {
+    // Input shorter than output would be — e.g. tiny log
+    const input = "abc\ndef";
+    const out = gitLog(input, 10);
+    expect(out).toBe(input);
+  });
+});
+
+describe("RTK filters", () => {
+  it("gitDiff truncates hunks beyond 100 lines and preserves file header", () => {
+    const input = makeLongDiff();
+    const out = gitDiff(input, 500);
+    expect(out).toContain("foo.js");
+    expect(out).toContain("lines truncated");
+    expect(out.length).toBeLessThan(input.length);
+  });
+
+  it("gitStatus groups by kind and produces compact output (Rust format)", () => {
+    const input = makeGitStatus();
+    const out = gitStatus(input);
+    expect(out).toContain("* main");
+    expect(out).toMatch(/~ Modified: \d+ files/);
+    expect(out).toContain("src/a.js");
+    expect(out.length).toBeLessThan(input.length);
+  });
+
+  it("grep groups matches by file and caps per-file lines (Rust format)", () => {
+    const input = makeGrepOutput();
+    const out = grep(input);
+    expect(out).toContain("50 matches in 2F:");
+    expect(out).toContain("[file] src/foo.js (40):");
+    expect(out).toContain("[file] src/bar.js (10):");
+    expect(out).toMatch(/\+\d+/); // overflow marker
+    expect(out.length).toBeLessThan(input.length);
+  });
+
+  it("find groups paths by parent dir, shows basenames (Rust format)", () => {
+    const input = makeFindOutput();
+    const out = find(input);
+    expect(out).toContain("55 files in 3 dirs:");
+    expect(out).toContain("./src/a/  (30)");
+    expect(out).toContain("./src/b/  (20)");
+    expect(out).toContain("./  (5)");
+    expect(out.length).toBeLessThan(input.length);
+  });
+
+  it("dedupLog collapses consecutive duplicates", () => {
+    const input = Array(20).fill("repeated log line A").join("\n") + "\nunique\n" + Array(10).fill("another dup").join("\n");
+    const out = dedupLog(input);
+    expect(out).toContain("repeated log line A");
+    expect(out).toContain("duplicate lines");
+    expect(out.length).toBeLessThan(input.length);
+  });
+});
+
+describe("autoDetectFilter", () => {
+  it("detects git diff", () => {
+    expect(autoDetectFilter("diff --git a/x b/x\n@@ -1 +1 @@\n+a").filterName).toBe("git-diff");
+  });
+  it("detects git status", () => {
+    expect(autoDetectFilter("On branch main\n  modified:   x.js\n").filterName).toBe("git-status");
+  });
+  it("detects grep", () => {
+    expect(autoDetectFilter("a.js:1:hello\nb.js:2:world\nc.js:3:foo").filterName).toBe("grep");
+  });
+  it("detects find", () => {
+    expect(autoDetectFilter("./a/b.js\n./a/c.js\n./a/d.js").filterName).toBe("find");
+  });
+  it("detects git log via commit header", () => {
+    const input = [
+      "commit abc1234def5678abc1234def5678abc1234def5",
+      "Author: Dev One <dev1@example.com>",
+      "Date:   Sun Jul 6 10:00:00 2026 +0700",
+      "",
+      "    Add auth middleware"
+    ].join("\n");
+    expect(autoDetectFilter(input).filterName).toBe("git-log");
+  });
+  it("falls back to dedupLog for generic text", () => {
+    const txt = "line1\nline2\nline3\nline4\nline5\nline6\n";
+    expect(autoDetectFilter(txt).filterName).toBe("dedup-log");
+  });
+});
+
+describe("RTK filters (extras)", () => {
+  it("ls: compact_ls strips perms/owner, keeps name + size", () => {
+    const input = [
+      "total 48",
+      "drwxr-xr-x  2 user staff   64 Jan  1 12:00 .",
+      "drwxr-xr-x  2 user staff   64 Jan  1 12:00 ..",
+      "drwxr-xr-x  2 user staff   64 Jan  1 12:00 src",
+      "-rw-r--r--  1 user staff 1234 Jan  1 12:00 Cargo.toml",
+      "-rw-r--r--  1 user staff 5678 Jan  1 12:00 README.md"
+    ].join("\n");
+    const out = ls(input);
+    expect(out).toContain("src/");
+    expect(out).toContain("Cargo.toml");
+    expect(out).toContain("1.2K");
+    expect(out).toContain("5.5K");
+    expect(out).not.toContain("drwx");
+    expect(out).toContain("Summary: 2 files, 1 dirs");
+  });
+
+  it("ls: filters noise dirs", () => {
+    const input = [
+      "total 8",
+      "drwxr-xr-x  2 user staff 64 Jan  1 12:00 node_modules",
+      "drwxr-xr-x  2 user staff 64 Jan  1 12:00 .git",
+      "drwxr-xr-x  2 user staff 64 Jan  1 12:00 src",
+      "-rw-r--r--  1 user staff 100 Jan  1 12:00 main.js"
+    ].join("\n");
+    const out = ls(input);
+    expect(out).not.toContain("node_modules");
+    expect(out).not.toContain(".git");
+    expect(out).toContain("src/");
+    expect(out).toContain("main.js");
+  });
+
+  it("tree: removes summary, keeps structure", () => {
+    const input = ".\n├── src\n│   └── main.rs\n└── Cargo.toml\n\n2 directories, 3 files\n";
+    const out = tree(input);
+    expect(out).not.toContain("directories");
+    expect(out).toContain("├──");
+    expect(out).toContain("main.rs");
+  });
+
+  it("smartTruncate: keeps head+tail, drops middle", () => {
+    const input = Array.from({ length: 400 }, (_, i) => `line ${i}`).join("\n");
+    const out = smartTruncate(input);
+    expect(out).toContain("line 0");
+    expect(out).toContain("line 399");
+    expect(out).toContain("lines truncated");
+    expect(out.length).toBeLessThan(input.length);
+  });
+
+  it("smartTruncate: passes through small input", () => {
+    const input = Array.from({ length: 10 }, (_, i) => `line ${i}`).join("\n");
+    expect(smartTruncate(input)).toBe(input);
+  });
+
+  it("readNumbered: compacts very long line-numbered dump", () => {
+    const lines = [];
+    for (let i = 1; i <= 400; i++) lines.push(`  ${i}|content ${i}`);
+    const input = lines.join("\n");
+    const out = readNumbered(input);
+    expect(out).toContain("1|content 1");
+    expect(out).toContain("400|content 400");
+    expect(out).toContain("lines truncated");
+    expect(out.length).toBeLessThan(input.length);
+  });
+
+  it("searchList: groups Cursor Glob output by parent dir", () => {
+    const paths = [];
+    for (let i = 0; i < 30; i++) paths.push(`- src/a/f${i}.js`);
+    for (let i = 0; i < 10; i++) paths.push(`- src/b/g${i}.js`);
+    const input = [
+      "Result of search in '/Users/x' (total 40 files):",
+      ...paths
+    ].join("\n");
+    const out = searchList(input);
+    expect(out).toContain("Result of search in");
+    expect(out).toContain("40 files in 2 dirs:");
+    expect(out).toContain("src/a/ (30):");
+    expect(out).toContain("src/b/ (10):");
+    expect(out).toMatch(/\+\d+/);
+    expect(out.length).toBeLessThan(input.length);
+  });
+});
+
+describe("autoDetectFilter (extras)", () => {
+  it("detects tree via box-drawing glyphs", () => {
+    expect(autoDetectFilter(".\n├── src\n│   └── main.rs\n└── Cargo.toml\n").filterName).toBe("tree");
+  });
+  it("detects ls via total + perms rows", () => {
+    const input = [
+      "total 48",
+      "drwxr-xr-x  2 user staff   64 Jan  1 12:00 src",
+      "-rw-r--r--  1 user staff 1234 Jan  1 12:00 main.js",
+      "-rw-r--r--  1 user staff 5678 Jan  1 12:00 README.md"
+    ].join("\n");
+    expect(autoDetectFilter(input).filterName).toBe("ls");
+  });
+  it("detects Cursor search list", () => {
+    const input = "Result of search in '/x' (total 3 files):\n- a/b.js\n- a/c.js\n- a/d.js";
+    expect(autoDetectFilter(input).filterName).toBe("search-list");
+  });
+});
+
+describe("safeApply", () => {
+  it("returns input if filter throws", () => {
+    const out = safeApply(() => { throw new Error("boom"); }, "hello");
+    expect(out).toBe("hello");
+  });
+  it("returns input if filter returns non-string", () => {
+    const out = safeApply(() => 42, "hello");
+    expect(out).toBe("hello");
+  });
+});
+
+describe("compressMessages (disabled)", () => {
+  it("returns null when disabled", () => {
+    const body = { messages: [{ role: "tool", tool_call_id: "x", content: makeLongDiff() }] };
+    expect(compressMessages(body, false)).toBeNull();
+  });
+});
+
+describe("compressMessages (enabled)", () => {
+  it("compresses OpenAI tool message (string content)", () => {
+    const big = makeLongDiff();
+    const body = { messages: [{ role: "tool", tool_call_id: "call_1", content: big }] };
+    const stats = compressMessages(body, true);
+    expect(stats.hits.length).toBeGreaterThan(0);
+    expect(body.messages[0].content.length).toBeLessThan(big.length);
+    expect(stats.bytesBefore).toBeGreaterThan(stats.bytesAfter);
+  });
+
+  it("compresses Claude string-form tool_result", () => {
+    const big = makeLongDiff();
+    const body = {
+      messages: [{
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: "toolu_1", content: big }]
+      }]
+    };
+    const stats = compressMessages(body, true);
+    expect(stats.hits.length).toBeGreaterThan(0);
+    expect(body.messages[0].content[0].content.length).toBeLessThan(big.length);
+  });
+
+  it("compresses Claude array-form tool_result text parts", () => {
+    const big = makeLongDiff();
+    const body = {
+      messages: [{
+        role: "user",
+        content: [{
+          type: "tool_result",
+          tool_use_id: "toolu_1",
+          content: [{ type: "text", text: big }, { type: "text", text: "unchanged short" }]
+        }]
+      }]
+    };
+    const stats = compressMessages(body, true);
+    expect(stats.hits.length).toBeGreaterThan(0);
+    expect(body.messages[0].content[0].content[0].text.length).toBeLessThan(big.length);
+    // short part unchanged
+    expect(body.messages[0].content[0].content[1].text).toBe("unchanged short");
+  });
+
+  it("skips is_error tool_result", () => {
+    const big = makeLongDiff();
+    const body = {
+      messages: [{
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: "toolu_1", content: big, is_error: true }]
+      }]
+    };
+    const stats = compressMessages(body, true);
+    expect(stats.hits.length).toBe(0);
+    expect(body.messages[0].content[0].content).toBe(big);
+  });
+
+  it("skips below MIN_COMPRESS_SIZE (<500 bytes)", () => {
+    const small = "diff --git a/x b/x\n@@ -1 +1 @@\n+a";
+    const body = { messages: [{ role: "tool", tool_call_id: "x", content: small }] };
+    const stats = compressMessages(body, true);
+    expect(stats.hits.length).toBe(0);
+    expect(body.messages[0].content).toBe(small);
+  });
+
+  it("never produces empty content (R14 guard)", () => {
+    const input = "a".repeat(1000);
+    const body = { messages: [{ role: "tool", tool_call_id: "x", content: input }] };
+    compressMessages(body, true);
+    expect(body.messages[0].content.length).toBeGreaterThan(0);
+  });
+
+  it("skips when body has no messages", () => {
+    expect(compressMessages({})).toBeNull();
+    expect(compressMessages({ messages: null })).toBeNull();
+  });
+
+  it("handles mix of messages without crashing", () => {
+    const body = {
+      messages: [
+        { role: "system", content: "you are" },
+        { role: "user", content: "hi" },
+        { role: "assistant", content: null, tool_calls: [{ id: "c1", function: { name: "x", arguments: "{}" } }] },
+        { role: "tool", tool_call_id: "c1", content: makeGrepOutput() },
+        { role: "user", content: [{ type: "text", text: "next" }] }
+      ]
+    };
+    const stats = compressMessages(body, true);
+    expect(stats).not.toBeNull();
+    expect(stats.hits.length).toBeGreaterThan(0);
+  });
+});
+
+describe("formatRtkLog", () => {
+  it("returns null when no hits", () => {
+    expect(formatRtkLog({ bytesBefore: 0, bytesAfter: 0, hits: [] })).toBeNull();
+  });
+  it("formats savings line with percentage", () => {
+    const line = formatRtkLog({ bytesBefore: 1000, bytesAfter: 400, hits: [{ filter: "git-diff" }] });
+    expect(line).toContain("saved 600B");
+    expect(line).toContain("60.0%");
+    expect(line).toContain("git-diff");
+  });
+});
diff --git a/tests/unit/rtkFindWindows.test.js b/tests/unit/rtkFindWindows.test.js
new file mode 100644
index 0000000..05b7b58
--- /dev/null
+++ b/tests/unit/rtkFindWindows.test.js
@@ -0,0 +1,62 @@
+// Tests for Windows path support in the `find` filter + autodetect
+// Windows absolute paths ("C:\Users\me\src\a.js") carry a drive-letter
+// separator that the Unix-only colon check used to reject, so no compaction
+// happened for Windows `find`-style dumps. See fix(rtk/find).
+import { describe, it, expect } from "vitest";
+import { autoDetectFilter } from "../../open-sse/rtk/autodetect.js";
+import { find } from "../../open-sse/rtk/filters/find.js";
+import { grep } from "../../open-sse/rtk/filters/grep.js";
+
+const WIN_PATHS = [
+  "C:\\Users\\me\\project\\src\\a.js",
+  "C:\\Users\\me\\project\\src\\b.js",
+  "C:\\Users\\me\\project\\src\\c.js"
+].join("\n");
+
+const UNIX_PATHS = [
+  "./src/a.js",
+  "./src/b.js",
+  "./src/c.js"
+].join("\n");
+
+describe("Windows find-path detection", () => {
+  it("detects Windows drive-letter paths as `find`", () => {
+    expect(autoDetectFilter(WIN_PATHS)).toBe(find);
+  });
+
+  it("still detects Unix paths as `find` (no regression)", () => {
+    expect(autoDetectFilter(UNIX_PATHS)).toBe(find);
+  });
+
+  it("still routes a Windows file:line dump to a compacting filter", () => {
+    const input = [
+      "C:\\Users\\me\\project\\src\\a.js:10:const x = 1",
+      "C:\\Users\\me\\project\\src\\b.js:20:const y = 2",
+      "C:\\Users\\me\\project\\src\\c.js:30:const z = 3"
+    ].join("\n");
+    // Each line is grep-shaped (file:line:content), so it routes to `grep`
+    // — but a drive-letter-only dump would route to `find`. Both are
+    // compaction-positive, so either is acceptable here.
+    const f = autoDetectFilter(input);
+    expect(f).not.toBeNull();
+    expect([find, grep]).toContain(f);
+  });
+});
+
+describe("Windows find-path grouping", () => {
+  it("groups Windows backslash paths and normalizes to forward slashes", () => {
+    const out = find(WIN_PATHS);
+    expect(out).toContain("3 files in 1 dirs");
+    expect(out).toContain("C:/Users/me/project/src/");
+    expect(out).toContain("a.js");
+    expect(out).toContain("b.js");
+    expect(out).toContain("c.js");
+    // backslashes must not leak into output
+    expect(out).not.toContain("\\");
+  });
+
+  it("compresses the dump (output shorter than input)", () => {
+    const out = find(WIN_PATHS);
+    expect(out.length).toBeLessThan(WIN_PATHS.length);
+  });
+});
diff --git a/tests/unit/rtkKiro.test.js b/tests/unit/rtkKiro.test.js
new file mode 100644
index 0000000..012de12
--- /dev/null
+++ b/tests/unit/rtkKiro.test.js
@@ -0,0 +1,291 @@
+// Tests for Kiro format RTK support
+// Verifies that RTK compression works with Kiro's conversationState format
+import { describe, it, expect } from "vitest";
+import { compressMessages } from "../../open-sse/rtk/index.js";
+
+describe("Kiro format RTK support", () => {
+  it("compresses tool results in Kiro conversationState.currentMessage", () => {
+    const kiroBody = {
+      conversationState: {
+        chatTriggerType: "MANUAL",
+        conversationId: "test-123",
+        currentMessage: {
+          userInputMessage: {
+            content: "Install express",
+            modelId: "claude-sonnet-4.5",
+            userInputMessageContext: {
+              toolResults: [
+                {
+                  toolUseId: "tool_1",
+                  status: "success",
+                  content: [
+                    {
+                      text: [
+                        "npm warn deprecated har-validator@5.1.5: this library is no longer supported",
+                        "npm warn deprecated uuid@3.4.0: uuid@10 and below is no longer supported",
+                        "npm warn deprecated request@2.88.2: request has been deprecated",
+                        "npm warn deprecated inflight@1.0.6: This module is not supported",
+                        "npm warn deprecated glob@7.2.3: Glob versions prior to v9 are no longer supported",
+                        "npm warn deprecated rimraf@2.7.1: Rimraf versions prior to v4 are no longer supported",
+                        "",
+                        "added 47 packages, and audited 48 packages in 13s",
+                        "",
+                        "3 packages are looking for funding",
+                        "  run `npm fund` for details",
+                        "",
+                        "4 vulnerabilities (2 moderate, 2 critical)",
+                        "",
+                        "Some issues need review, and may require choosing",
+                        "a different dependency.",
+                        "",
+                        "Run `npm audit` for details."
+                      ].join("\n")
+                    }
+                  ]
+                }
+              ]
+            }
+          }
+        },
+        history: []
+      }
+    };
+
+    const stats = compressMessages(kiroBody, true);
+
+    expect(stats).not.toBeNull();
+    expect(stats.bytesBefore).toBeGreaterThan(500);
+    expect(stats.bytesAfter).toBeLessThan(stats.bytesBefore);
+    expect(stats.hits.length).toBe(1);
+    expect(stats.hits[0].filter).toBe("build-output");
+    expect(stats.hits[0].shape).toBe("kiro-tool-result");
+
+    // Verify compression happened
+    const savedBytes = stats.bytesBefore - stats.bytesAfter;
+    expect(savedBytes).toBeGreaterThan(0);
+    const savedPercent = (savedBytes / stats.bytesBefore) * 100;
+    expect(savedPercent).toBeGreaterThan(10); // At least 10% savings
+  });
+
+  it("compresses tool results in Kiro conversationState.history", () => {
+    // Need >500 bytes for compression to trigger
+    const compilingLines = [];
+    for (let i = 1; i <= 20; i++) {
+      compilingLines.push(`   Compiling package-${i} v1.0.${i}`);
+    }
+    compilingLines.push("    Finished `dev` profile [unoptimized + debuginfo] target(s) in 12.34s");
+
+    const kiroBody = {
+      conversationState: {
+        chatTriggerType: "MANUAL",
+        conversationId: "test-456",
+        currentMessage: {
+          userInputMessage: {
+            content: "What happened?",
+            modelId: "claude-sonnet-4.5"
+          }
+        },
+        history: [
+          {
+            userInputMessage: {
+              content: "Run cargo build",
+              modelId: "claude-sonnet-4.5",
+              userInputMessageContext: {
+                toolResults: [
+                  {
+                    toolUseId: "tool_2",
+                    status: "success",
+                    content: [
+                      {
+                        text: compilingLines.join("\n")
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
+          }
+        ]
+      }
+    };
+
+    const stats = compressMessages(kiroBody, true);
+
+    expect(stats).not.toBeNull();
+    expect(stats.hits.length).toBe(1);
+    expect(stats.hits[0].filter).toBe("build-output");
+    expect(stats.bytesAfter).toBeLessThan(stats.bytesBefore);
+  });
+
+  it("handles multiple tool results across history and currentMessage", () => {
+    // Need >500 bytes for each tool result to trigger compression
+    const deprecations1 = [];
+    const deprecations2 = [];
+    for (let i = 1; i <= 10; i++) {
+      deprecations1.push(`npm warn deprecated package-${i}@1.0.0: This version is deprecated`);
+      deprecations2.push(`npm warn deprecated lib-${i}@2.0.0: This library is no longer supported`);
+    }
+    deprecations1.push("added 50 packages in 5s");
+    deprecations2.push("added 1 package in 2s");
+
+    const kiroBody = {
+      conversationState: {
+        chatTriggerType: "MANUAL",
+        conversationId: "test-789",
+        currentMessage: {
+          userInputMessage: {
+            content: "Install lodash",
+            modelId: "claude-sonnet-4.5",
+            userInputMessageContext: {
+              toolResults: [
+                {
+                  toolUseId: "tool_3",
+                  status: "success",
+                  content: [
+                    {
+                      text: deprecations2.join("\n")
+                    }
+                  ]
+                }
+              ]
+            }
+          }
+        },
+        history: [
+          {
+            userInputMessage: {
+              content: "Install express",
+              modelId: "claude-sonnet-4.5",
+              userInputMessageContext: {
+                toolResults: [
+                  {
+                    toolUseId: "tool_4",
+                    status: "success",
+                    content: [
+                      {
+                        text: deprecations1.join("\n")
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
+          }
+        ]
+      }
+    };
+
+    const stats = compressMessages(kiroBody, true);
+
+    expect(stats).not.toBeNull();
+    expect(stats.hits.length).toBe(2); // Both tool results compressed
+    expect(stats.hits.every(h => h.filter === "build-output")).toBe(true);
+  });
+
+  it("preserves error tool results without compression", () => {
+    const kiroBody = {
+      conversationState: {
+        chatTriggerType: "MANUAL",
+        conversationId: "test-error",
+        currentMessage: {
+          userInputMessage: {
+            content: "Install invalid-package",
+            modelId: "claude-sonnet-4.5",
+            userInputMessageContext: {
+              toolResults: [
+                {
+                  toolUseId: "tool_5",
+                  status: "error",
+                  content: [
+                    {
+                      text: "npm error code E404\nnpm error 404 Not Found - GET https://registry.npmjs.org/invalid-package"
+                    }
+                  ]
+                }
+              ]
+            }
+          }
+        },
+        history: []
+      }
+    };
+
+    const originalText = kiroBody.conversationState.currentMessage.userInputMessage.userInputMessageContext.toolResults[0].content[0].text;
+    const stats = compressMessages(kiroBody, true);
+
+    expect(stats).not.toBeNull();
+    expect(stats.hits.length).toBe(0); // Error not compressed
+    
+    // Verify error text unchanged
+    const afterText = kiroBody.conversationState.currentMessage.userInputMessage.userInputMessageContext.toolResults[0].content[0].text;
+    expect(afterText).toBe(originalText);
+  });
+
+  it("returns null when RTK is disabled", () => {
+    const kiroBody = {
+      conversationState: {
+        chatTriggerType: "MANUAL",
+        conversationId: "test-disabled",
+        currentMessage: {
+          userInputMessage: {
+            content: "Test",
+            modelId: "claude-sonnet-4.5",
+            userInputMessageContext: {
+              toolResults: [
+                {
+                  toolUseId: "tool_6",
+                  status: "success",
+                  content: [{ text: "npm install express\nadded 50 packages" }]
+                }
+              ]
+            }
+          }
+        },
+        history: []
+      }
+    };
+
+    const stats = compressMessages(kiroBody, false); // RTK disabled
+    expect(stats).toBeNull();
+  });
+
+  it("handles Kiro body with no tool results gracefully", () => {
+    const kiroBody = {
+      conversationState: {
+        chatTriggerType: "MANUAL",
+        conversationId: "test-no-tools",
+        currentMessage: {
+          userInputMessage: {
+            content: "Hello",
+            modelId: "claude-sonnet-4.5"
+          }
+        },
+        history: []
+      }
+    };
+
+    const stats = compressMessages(kiroBody, true);
+
+    expect(stats).not.toBeNull();
+    expect(stats.hits.length).toBe(0);
+    expect(stats.bytesBefore).toBe(0);
+    expect(stats.bytesAfter).toBe(0);
+  });
+
+  it("handles malformed Kiro body without crashing", () => {
+    const malformedBodies = [
+      { conversationState: null },
+      { conversationState: {} },
+      { conversationState: { history: null, currentMessage: null } },
+      { conversationState: { history: "not-an-array" } }
+    ];
+
+    for (const body of malformedBodies) {
+      const stats = compressMessages(body, true);
+      // Malformed bodies may return null (caught by try-catch) or empty stats
+      if (stats !== null) {
+        expect(stats.hits.length).toBe(0);
+      }
+    }
+  });
+});
diff --git a/tests/unit/searxng-provider-config.test.js b/tests/unit/searxng-provider-config.test.js
new file mode 100644
index 0000000..18ab335
--- /dev/null
+++ b/tests/unit/searxng-provider-config.test.js
@@ -0,0 +1,30 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const originalSearxngUrl = process.env.SEARXNG_URL;
+
+async function loadProvider(url) {
+  if (url === undefined) delete process.env.SEARXNG_URL;
+  else process.env.SEARXNG_URL = url;
+  vi.resetModules();
+  return (await import("../../open-sse/providers/registry/searxng.js")).default;
+}
+
+afterEach(() => {
+  if (originalSearxngUrl === undefined) delete process.env.SEARXNG_URL;
+  else process.env.SEARXNG_URL = originalSearxngUrl;
+  vi.resetModules();
+});
+
+describe("SearXNG provider configuration", () => {
+  it("uses SEARXNG_URL when the deployment config supplies one", async () => {
+    const provider = await loadProvider("http://searxng:8080/search");
+
+    expect(provider.searchConfig.baseUrl).toBe("http://searxng:8080/search");
+  });
+
+  it("preserves the loopback default when SEARXNG_URL is unset", async () => {
+    const provider = await loadProvider(undefined);
+
+    expect(provider.searchConfig.baseUrl).toBe("http://localhost:8888/search");
+  });
+});
diff --git a/tests/unit/security-audit.test.js b/tests/unit/security-audit.test.js
new file mode 100644
index 0000000..954751c
--- /dev/null
+++ b/tests/unit/security-audit.test.js
@@ -0,0 +1,289 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import fs from "fs";
+import path from "path";
+
+// ============================================================
+// AUDIT-002 (#1962): API key masking in usage stats
+// ============================================================
+describe("AUDIT-002: API key masking", () => {
+  it("source should contain maskApiKey function", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/lib/db/repos/usageRepo.js"),
+      "utf-8"
+    );
+    expect(source).toContain("function maskApiKey");
+  });
+
+  it("getUsageHistory should use apiKeyMasked instead of apiKey", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/lib/db/repos/usageRepo.js"),
+      "utf-8"
+    );
+    // The REST response should use apiKeyMasked
+    expect(source).toContain("apiKeyMasked: maskApiKey(r.apiKey)");
+    // The return mapping in getUsageHistory should not have raw apiKey
+    // (The internal ring buffer still uses apiKey: r.apiKey for internal state - that's fine)
+    const historyReturn = source.match(/return rows\.map\(\(r\)\s*=>\s*\(\{[\s\S]*?\}\)\);/);
+    expect(historyReturn).not.toBeNull();
+    expect(historyReturn[0]).toContain("apiKeyMasked");
+    expect(historyReturn[0]).not.toContain("apiKey: r.apiKey");
+  });
+
+  it("getUsageStats should use apiKeyMasked in byApiKey entries", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/lib/db/repos/usageRepo.js"),
+      "utf-8"
+    );
+    // Both code paths (daily summary + 24h live) should use apiKeyMasked
+    const maskedCount = (source.match(/apiKeyMasked/g) || []).length;
+    expect(maskedCount).toBeGreaterThanOrEqual(4); // function def + 3 usage sites
+
+    // The byApiKey stats entries should use apiKeyMasked, not raw apiKey
+    // Check the daily summary path
+    const dailyPath = source.match(/stats\.byApiKey\[akKey\] = \{[^}]*apiKeyMasked[^}]*\}/);
+    expect(dailyPath).not.toBeNull();
+    // Check the 24h live path
+    const livePath = source.match(/stats\.byApiKey\[akKey\] = \{[^}]*apiKeyMasked[^}]*\}/g);
+    expect(livePath).not.toBeNull();
+    expect(livePath.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("byApiKey object keys should use masked key, not raw key", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/lib/db/repos/usageRepo.js"),
+      "utf-8"
+    );
+    // The 24h path should use apiKeyMasked in the akKey template
+    expect(source).toContain("${apiKeyMasked}|${r.model}|${r.provider");
+    // Should NOT use raw r.apiKey in the key
+    expect(source).not.toContain("${r.apiKey}|${r.model}|${r.provider");
+  });
+});
+
+// ============================================================
+// AUDIT-003 (#1961): Proxy URL validation
+// ============================================================
+describe("AUDIT-003: Proxy URL validation", () => {
+  beforeEach(() => {
+    delete process.env.HTTP_PROXY;
+    delete process.env.HTTPS_PROXY;
+    delete process.env.ALL_PROXY;
+    delete process.env.NINE_ROUTER_PROXY_MANAGED;
+    delete process.env.NINE_ROUTER_PROXY_URL;
+    delete process.env.NINE_ROUTER_NO_PROXY;
+    delete process.env.NO_PROXY;
+  });
+
+  it("source should contain validateProxyUrl function", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/lib/network/outboundProxy.js"),
+      "utf-8"
+    );
+    expect(source).toContain("function validateProxyUrl");
+    expect(source).toContain("ALLOWED_PROXY_SCHEMES");
+  });
+
+  it("should accept valid http proxy URLs", async () => {
+    vi.resetModules();
+    const { applyOutboundProxyEnv } = await import("../../src/lib/network/outboundProxy.js");
+    applyOutboundProxyEnv({
+      outboundProxyEnabled: true,
+      outboundProxyUrl: "http://proxy.example.com:8080",
+    });
+    // new URL().href normalizes (adds trailing slash)
+    expect(process.env.HTTP_PROXY).toContain("http://proxy.example.com:8080");
+    expect(process.env.HTTPS_PROXY).toContain("http://proxy.example.com:8080");
+  });
+
+  it("should accept valid https proxy URLs", async () => {
+    vi.resetModules();
+    const { applyOutboundProxyEnv } = await import("../../src/lib/network/outboundProxy.js");
+    applyOutboundProxyEnv({
+      outboundProxyEnabled: true,
+      outboundProxyUrl: "https://proxy.example.com:443",
+    });
+    // new URL().href normalizes (drops default port 443, adds trailing slash)
+    expect(process.env.HTTP_PROXY).toContain("https://proxy.example.com");
+  });
+
+  it("should accept valid socks5 proxy URLs", async () => {
+    vi.resetModules();
+    const { applyOutboundProxyEnv } = await import("../../src/lib/network/outboundProxy.js");
+    applyOutboundProxyEnv({
+      outboundProxyEnabled: true,
+      outboundProxyUrl: "socks5://proxy.example.com:1080",
+    });
+    expect(process.env.ALL_PROXY).toBe("socks5://proxy.example.com:1080");
+  });
+
+  it("should reject URLs with shell metacharacters (newline)", async () => {
+    vi.resetModules();
+    const { applyOutboundProxyEnv } = await import("../../src/lib/network/outboundProxy.js");
+    applyOutboundProxyEnv({
+      outboundProxyEnabled: true,
+      outboundProxyUrl: "http://proxy.example.com:8080\nmalicious",
+    });
+    expect(process.env.HTTP_PROXY).toBeUndefined();
+  });
+
+  it("should reject URLs with shell metacharacters (backtick)", async () => {
+    vi.resetModules();
+    const { applyOutboundProxyEnv } = await import("../../src/lib/network/outboundProxy.js");
+    applyOutboundProxyEnv({
+      outboundProxyEnabled: true,
+      outboundProxyUrl: "http://`whoami`.example.com:8080",
+    });
+    expect(process.env.HTTP_PROXY).toBeUndefined();
+  });
+
+  it("should reject URLs with shell metacharacters (dollar)", async () => {
+    vi.resetModules();
+    const { applyOutboundProxyEnv } = await import("../../src/lib/network/outboundProxy.js");
+    applyOutboundProxyEnv({
+      outboundProxyEnabled: true,
+      outboundProxyUrl: "http://$(whoami).example.com:8080",
+    });
+    expect(process.env.HTTP_PROXY).toBeUndefined();
+  });
+
+  it("should reject non-allowed schemes (file://)", async () => {
+    vi.resetModules();
+    const { applyOutboundProxyEnv } = await import("../../src/lib/network/outboundProxy.js");
+    applyOutboundProxyEnv({
+      outboundProxyEnabled: true,
+      outboundProxyUrl: "file:///etc/passwd",
+    });
+    expect(process.env.HTTP_PROXY).toBeUndefined();
+  });
+
+  it("should reject non-allowed schemes (javascript:)", async () => {
+    vi.resetModules();
+    const { applyOutboundProxyEnv } = await import("../../src/lib/network/outboundProxy.js");
+    applyOutboundProxyEnv({
+      outboundProxyEnabled: true,
+      outboundProxyUrl: "javascript:alert(1)",
+    });
+    expect(process.env.HTTP_PROXY).toBeUndefined();
+  });
+});
+
+// ============================================================
+// AUDIT-018 (#1972): XSS escaping in OAuth callback
+// ============================================================
+describe("AUDIT-018: XSS escaping in OAuth callback", () => {
+  it("source should contain escapeHtml function", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/lib/oauth/utils/server.js"),
+      "utf-8"
+    );
+    expect(source).toContain("function escapeHtml");
+  });
+
+  it("should escape ampersand, angle brackets, and quotes", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/lib/oauth/utils/server.js"),
+      "utf-8"
+    );
+    expect(source).toContain("&amp;");
+    expect(source).toContain("&lt;");
+    expect(source).toContain("&gt;");
+    expect(source).toContain("&quot;");
+    expect(source).toContain("&#39;");
+  });
+
+  it("should use safeMessage in rendered HTML, not raw message", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/lib/oauth/utils/server.js"),
+      "utf-8"
+    );
+    expect(source).toContain("safeMessage");
+    expect(source).toContain("${safeMessage}");
+    // Should NOT use raw message in HTML body
+    expect(source).not.toContain("<p>${message}</p>");
+  });
+});
+
+// ============================================================
+// AUDIT-004 (#1963): TOCTOU race - atomic lock file
+// ============================================================
+describe("AUDIT-004: Atomic lock file for MITM startup", () => {
+  it("manager.js should define LOCK_FILE constant", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/mitm/manager.js"),
+      "utf-8"
+    );
+    expect(source).toContain("LOCK_FILE");
+    expect(source).toContain(".mitm.lock");
+  });
+
+  it("should use O_EXCL flag (wx) for atomic creation", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/mitm/manager.js"),
+      "utf-8"
+    );
+    expect(source).toContain('"wx"');
+    expect(source).toContain("EEXIST");
+  });
+
+  it("should clean up lock file on all exit paths", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/mitm/manager.js"),
+      "utf-8"
+    );
+    const matches = source.match(/unlinkSync\(LOCK_FILE\)/g);
+    expect(matches).not.toBeNull();
+    expect(matches.length).toBeGreaterThanOrEqual(4);
+  });
+});
+
+// ============================================================
+// AUDIT-001 (#1965): Race condition in retry tracking
+// ============================================================
+describe("AUDIT-001: Synchronous restart guard", () => {
+  it("mitmIsRestarting should be set before first await expression", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/mitm/manager.js"),
+      "utf-8"
+    );
+
+    const funcStart = source.indexOf("async function scheduleMitmRestart");
+    expect(funcStart).toBeGreaterThan(-1);
+
+    const funcBody = source.substring(funcStart, funcStart + 2000);
+
+    const guardCheckIdx = funcBody.indexOf("if (mitmIsRestarting) return;");
+    expect(guardCheckIdx).toBeGreaterThan(-1);
+
+    const afterGuard = funcBody.substring(guardCheckIdx);
+
+    // Strip line comments to avoid matching "await" in comment text
+    const noComments = afterGuard.replace(/\/\/.*$/gm, "");
+
+    // Find the first actual await expression
+    const firstAwaitIdx = noComments.search(/\bawait\s+/);
+    expect(firstAwaitIdx).toBeGreaterThan(-1);
+
+    // Find mitmIsRestarting = true
+    const setFlagIdx = noComments.indexOf("mitmIsRestarting = true");
+
+    expect(setFlagIdx).toBeGreaterThan(-1);
+    expect(firstAwaitIdx).toBeGreaterThan(-1);
+    expect(setFlagIdx).toBeLessThan(firstAwaitIdx);
+  });
+
+  it("mitmIsRestarting should be reset on max-restarts early return", () => {
+    const source = fs.readFileSync(
+      path.resolve("src/mitm/manager.js"),
+      "utf-8"
+    );
+
+    const funcStart = source.indexOf("async function scheduleMitmRestart");
+    const funcBody = source.substring(funcStart, funcStart + 2000);
+
+    const maxRestartsIdx = funcBody.indexOf("Max restart attempts reached");
+    expect(maxRestartsIdx).toBeGreaterThan(-1);
+
+    const afterMax = funcBody.substring(maxRestartsIdx, maxRestartsIdx + 200);
+    expect(afterMax).toContain("mitmIsRestarting = false");
+  });
+});
diff --git a/tests/unit/session-manager.test.js b/tests/unit/session-manager.test.js
new file mode 100644
index 0000000..3747481
--- /dev/null
+++ b/tests/unit/session-manager.test.js
@@ -0,0 +1,62 @@
+// A2: locks resolveSessionId priority/stickiness (codex/kiro/antigravity centralization).
+import { describe, it, expect, beforeEach } from "vitest";
+import { resolveSessionId, deriveSessionId, clearSessionStore } from "../../open-sse/utils/sessionManager.js";
+
+// Assistant text must reach ASSISTANT_MIN_LEN (80) to use assistant anchor; else first user message.
+const longAssistant = "x".repeat(80);
+const bodyWithAssistant = { messages: [{ role: "assistant", content: longAssistant }] };
+const bodyWithUserOnly = { messages: [{ role: "user", content: "hello from first user message anchor" }] };
+
+beforeEach(() => clearSessionStore());
+
+describe("resolveSessionId", () => {
+  it("stickiness: same body+connectionId+scope -> same id", () => {
+    const opts = { body: bodyWithAssistant, connectionId: "conn1", scope: "codex" };
+    expect(resolveSessionId(opts)).toBe(resolveSessionId(opts));
+  });
+
+  it("different connectionId -> different id", () => {
+    const a = resolveSessionId({ body: bodyWithAssistant, connectionId: "connA", scope: "codex" });
+    const b = resolveSessionId({ body: bodyWithAssistant, connectionId: "connB", scope: "codex" });
+    expect(a).not.toBe(b);
+  });
+
+  it("different scope -> different id", () => {
+    const a = resolveSessionId({ body: bodyWithAssistant, connectionId: "conn1", scope: "codex" });
+    const b = resolveSessionId({ body: bodyWithAssistant, connectionId: "conn1", scope: "kiro" });
+    expect(a).not.toBe(b);
+  });
+
+  it("first user message anchor when assistant text below cap", () => {
+    const opts = { body: bodyWithUserOnly, connectionId: "conn1", scope: "codex" };
+    expect(resolveSessionId(opts)).toBe(resolveSessionId(opts));
+  });
+
+  it("assistant anchor wins once assistant text reaches cap", () => {
+    const shortAssistant = { messages: [{ role: "user", content: "same user" }, { role: "assistant", content: "y".repeat(80) }] };
+    const a = resolveSessionId({ body: shortAssistant, connectionId: "conn1", scope: "codex" });
+    const b = resolveSessionId({ body: shortAssistant, connectionId: "conn1", scope: "codex" });
+    expect(a).toBe(b);
+  });
+
+  it("fallback: empty body+no header+no workspaceId -> deriveSessionId(connectionId)", () => {
+    const got = resolveSessionId({ body: {}, connectionId: "connFallback" });
+    expect(got).toBe(deriveSessionId("connFallback"));
+  });
+
+  it("client override: x-session-id header wins, skips later steps", () => {
+    const got = resolveSessionId({
+      headers: { "x-session-id": "client-sess-123" },
+      body: bodyWithAssistant,
+      connectionId: "conn1",
+      workspaceId: "ws1",
+      scope: "codex",
+    });
+    expect(got).toBe("client-sess-123");
+  });
+
+  it("workspaceId path: empty body + workspaceId set -> normalized workspaceId", () => {
+    const got = resolveSessionId({ body: {}, connectionId: "conn1", workspaceId: "ws-abc" });
+    expect(got).toBe("ws-abc");
+  });
+});
diff --git a/tests/unit/thinking-effort-openai-max-clamp.test.js b/tests/unit/thinking-effort-openai-max-clamp.test.js
new file mode 100644
index 0000000..23917fd
--- /dev/null
+++ b/tests/unit/thinking-effort-openai-max-clamp.test.js
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { applyThinking } from "../../open-sse/translator/concerns/thinkingUnified.js";
+import { FORMATS } from "../../open-sse/translator/formats.js";
+
+// Regression: Claude Code sends thinking effort "max" (its top level). When
+// 9router routes to an OpenAI-format provider, applyThinking() case "openai"
+// must clamp "max"→"xhigh" because OpenAI's reasoning_effort enum has no "max"
+// (L.openai caps at "xhigh"). Without the clamp, upstream returns HTTP 400
+// "max effort not support". See open-sse/providers/thinkingLevels.js:10.
+describe("applyThinking (openai): clamp max effort to xhigh", () => {
+  it("client output_config.effort:\"max\" → reasoning_effort:\"xhigh\" (not \"max\")", () => {
+    const body = { output_config: { effort: "max" } };
+    const out = applyThinking(FORMATS.OPENAI, "gpt-5", body, "openai");
+    expect(out.reasoning_effort).toBe("xhigh");
+  });
+
+  it("direct reasoning_effort:\"max\" clamped to \"xhigh\"", () => {
+    const body = { reasoning_effort: "max" };
+    const out = applyThinking(FORMATS.OPENAI, "gpt-5", body, "openai");
+    expect(out.reasoning_effort).toBe("xhigh");
+  });
+
+  it("\"xhigh\" passes through unchanged (highest valid OpenAI level)", () => {
+    const body = { reasoning_effort: "xhigh" };
+    const out = applyThinking(FORMATS.OPENAI, "gpt-5", body, "openai");
+    expect(out.reasoning_effort).toBe("xhigh");
+  });
+
+  it("\"high\" passes through unchanged", () => {
+    const body = { reasoning_effort: "high" };
+    const out = applyThinking(FORMATS.OPENAI, "gpt-5", body, "openai");
+    expect(out.reasoning_effort).toBe("high");
+  });
+
+  it("max budget (thinking.budget_tokens:128000) → reasoning_effort:\"xhigh\" (budgetToLevel caps at xhigh)", () => {
+    const body = { thinking: { type: "enabled", budget_tokens: 128000 } };
+    const out = applyThinking(FORMATS.OPENAI, "gpt-5", body, "openai");
+    expect(out.reasoning_effort).toBe("xhigh");
+  });
+});
\ No newline at end of file
diff --git a/tests/unit/thinking-levels-gpt56-sol.test.js b/tests/unit/thinking-levels-gpt56-sol.test.js
new file mode 100644
index 0000000..1a5a3ce
--- /dev/null
+++ b/tests/unit/thinking-levels-gpt56-sol.test.js
@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest";
+import { getThinkingLevels } from "../../open-sse/providers/thinkingLevels.js";
+
+describe("getThinkingLevels", () => {
+  it("adds max for gpt-5.6-sol on codex", () => {
+    const levels = getThinkingLevels("codex", "gpt-5.6-sol");
+    expect(levels).toContain("max");
+    expect(levels).toContain("xhigh");
+    expect(levels).not.toContain("ultra");
+  });
+
+  it("does not add max for other codex models", () => {
+    const levels = getThinkingLevels("codex", "gpt-5.3-codex");
+    expect(levels).toEqual(["low", "medium", "high", "xhigh"]);
+  });
+
+  it("does not add max for other gpt-5.6 models", () => {
+    const levels = getThinkingLevels("codex", "gpt-5.5");
+    expect(levels || []).not.toContain("max");
+  });
+});
diff --git a/tests/unit/token-refresh-dispatch.test.js b/tests/unit/token-refresh-dispatch.test.js
new file mode 100644
index 0000000..8a1aa06
--- /dev/null
+++ b/tests/unit/token-refresh-dispatch.test.js
@@ -0,0 +1,22 @@
+// Guards the refactored REFRESH_HANDLERS dispatch: null-guards + the two different defaults.
+import { describe, it, expect } from "vitest";
+
+const load = () => import("../../open-sse/services/tokenRefresh.js");
+
+describe("tokenRefresh dispatch", () => {
+  it("getAccessToken returns null for missing/invalid refreshToken", async () => {
+    const mod = await load();
+    expect(await mod.getAccessToken("claude", {}, null)).toBeNull();
+    expect(await mod.getAccessToken("claude", { refreshToken: 123 }, null)).toBeNull();
+  });
+
+  it("getAccessToken default: unsupported provider → null", async () => {
+    const mod = await load();
+    expect(await mod.getAccessToken("totally-unknown", { refreshToken: "x" }, null)).toBeNull();
+  });
+
+  it("refreshTokenByProvider returns null without refreshToken", async () => {
+    const mod = await load();
+    expect(await mod.refreshTokenByProvider("claude", {}, null)).toBeNull();
+  });
+});
diff --git a/tests/unit/translator-custom-prefix.test.js b/tests/unit/translator-custom-prefix.test.js
new file mode 100644
index 0000000..b38a620
--- /dev/null
+++ b/tests/unit/translator-custom-prefix.test.js
@@ -0,0 +1,55 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock getModelInfo to simulate custom provider prefix resolution
+vi.mock("@/sse/services/model.js", () => ({
+  getModelInfo: vi.fn(async (modelId) => {
+    // Simulate prefix resolution for custom providers
+    if (modelId.startsWith("my-prefix/")) {
+      return {
+        provider: "openai-compatible-chat-abc123",
+        model: modelId.replace("my-prefix/", "")
+      };
+    }
+    if (modelId.startsWith("acme/")) {
+      return {
+        provider: "anthropic-compatible-claude-xyz",
+        model: modelId.replace("acme/", "")
+      };
+    }
+    // Default: no prefix
+    return {
+      provider: modelId.split("/")[1] || "unknown",
+      model: modelId.split("/")[1] || modelId
+    };
+  })
+}));
+
+describe("Translator custom provider prefix resolution", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should resolve OpenAI-compatible provider prefix via getModelInfo", async () => {
+    const { getModelInfo } = await import("@/sse/services/model.js");
+    const result = await getModelInfo("my-prefix/gpt-4");
+
+    expect(result.provider).toBe("openai-compatible-chat-abc123");
+    expect(result.model).toBe("gpt-4");
+  });
+
+  it("should resolve Anthropic-compatible provider prefix via getModelInfo", async () => {
+    const { getModelInfo } = await import("@/sse/services/model.js");
+    const result = await getModelInfo("acme/claude-3");
+
+    expect(result.provider).toBe("anthropic-compatible-claude-xyz");
+    expect(result.model).toBe("claude-3");
+  });
+
+  it("should handle model ID without prefix", async () => {
+    const { getModelInfo } = await import("@/sse/services/model.js");
+    const result = await getModelInfo("openai/gpt-4");
+
+    expect(result.provider).toBeDefined();
+    expect(result.model).toBe("gpt-4");
+  });
+});
diff --git a/tests/unit/translator-helpers-edge.test.js b/tests/unit/translator-helpers-edge.test.js
new file mode 100644
index 0000000..06dcecf
--- /dev/null
+++ b/tests/unit/translator-helpers-edge.test.js
@@ -0,0 +1,47 @@
+// Locks edge cases flagged in docs 11 §1/§4 that were only covered indirectly.
+import { describe, it, expect } from "vitest";
+import { normalizeClaudePassthrough } from "../../open-sse/translator/formats/claude.js";
+import { parseDataUri, encodeDataUri } from "../../open-sse/translator/concerns/image.js";
+
+describe("normalizeClaudePassthrough — haiku adaptive thinking (docs 11 §1)", () => {
+  it("downgrades adaptive thinking to enabled+budget for haiku models", () => {
+    const out = normalizeClaudePassthrough({ thinking: { type: "adaptive" } }, "claude-haiku-4-5");
+    expect(out.thinking).toEqual({ type: "enabled", budget_tokens: 10000 });
+  });
+
+  it("keeps adaptive thinking for sonnet/opus", () => {
+    const out = normalizeClaudePassthrough({ thinking: { type: "adaptive" } }, "claude-sonnet-4-6");
+    expect(out.thinking).toEqual({ type: "adaptive" });
+  });
+
+  it("hoists mid-conversation system messages into top-level system", () => {
+    const out = normalizeClaudePassthrough({
+      messages: [
+        { role: "user", content: "hi" },
+        { role: "system", content: "be brief" },
+      ],
+    });
+    expect(out.system).toEqual([{ type: "text", text: "be brief" }]);
+    expect(out.messages.every((m) => m.role !== "system")).toBe(true);
+  });
+});
+
+describe("parseDataUri / encodeDataUri (docs 11 §4)", () => {
+  it("parses a base64 data uri", () => {
+    expect(parseDataUri("data:image/png;base64,AAAB")).toEqual({ mimeType: "image/png", base64: "AAAB" });
+  });
+
+  it("tolerates newlines inside base64 payload", () => {
+    expect(parseDataUri("data:image/jpeg;base64,AA\nBB")?.base64).toBe("AA\nBB");
+  });
+
+  it("returns null for http urls and non-strings", () => {
+    expect(parseDataUri("https://x/y.png")).toBeNull();
+    expect(parseDataUri(null)).toBeNull();
+  });
+
+  it("encode/parse roundtrip", () => {
+    const uri = encodeDataUri("image/webp", "ZZZ");
+    expect(parseDataUri(uri)).toEqual({ mimeType: "image/webp", base64: "ZZZ" });
+  });
+});
diff --git a/tests/unit/translator-request-normalization.test.js b/tests/unit/translator-request-normalization.test.js
new file mode 100644
index 0000000..de791fc
--- /dev/null
+++ b/tests/unit/translator-request-normalization.test.js
@@ -0,0 +1,186 @@
+import { describe, it, expect } from "vitest";
+
+import { FORMATS } from "../../open-sse/translator/formats.js";
+import { translateRequest } from "../../open-sse/translator/index.js";
+import { claudeToOpenAIRequest } from "../../open-sse/translator/request/claude-to-openai.js";
+import { filterToOpenAIFormat } from "../../open-sse/translator/formats/openai.js";
+import { parseSSELine } from "../../open-sse/utils/streamHelpers.js";
+
+describe("request normalization", () => {
+  it("claudeToOpenAIRequest flattens text-only content arrays into string", () => {
+    const body = {
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: "hi" },
+            { type: "text", text: "there" },
+          ],
+        },
+      ],
+    };
+
+    const result = claudeToOpenAIRequest("gpt-oss:120b", body, true);
+    expect(result.messages[0].content).toBe("hi\nthere");
+  });
+
+  it("claudeToOpenAIRequest preserves multimodal arrays", () => {
+    const body = {
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: "describe" },
+            {
+              type: "image",
+              source: {
+                type: "base64",
+                media_type: "image/png",
+                data: "ZmFrZQ==",
+              },
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = claudeToOpenAIRequest("gpt-4o", body, true);
+    expect(Array.isArray(result.messages[0].content)).toBe(true);
+  });
+
+  it("filterToOpenAIFormat flattens text-only arrays to string", () => {
+    const body = {
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: "a" },
+            { type: "text", text: "b" },
+          ],
+        },
+      ],
+    };
+
+    const result = filterToOpenAIFormat(JSON.parse(JSON.stringify(body)));
+    expect(result.messages[0].content).toBe("a\nb");
+  });
+
+  it("translateRequest keeps /v1/messages Claude->OpenAI text payloads string-safe", () => {
+    const body = {
+      model: "ollama/gpt-oss:120b",
+      system: [{ type: "text", text: "You are helpful." }],
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: "hello" },
+            { type: "text", text: "world" },
+          ],
+        },
+      ],
+      stream: true,
+    };
+
+    const result = translateRequest(
+      FORMATS.CLAUDE,
+      FORMATS.OPENAI,
+      "gpt-oss:120b",
+      JSON.parse(JSON.stringify(body)),
+      true,
+      null,
+      "ollama",
+    );
+
+    const userMessage = result.messages.find((m) => m.role === "user");
+    expect(typeof userMessage.content).toBe("string");
+    expect(userMessage.content).toBe("hello\nworld");
+  });
+
+  it("translateRequest strips unsupported Anthropic output_config for MiniMax Claude-compatible endpoints", () => {
+    const body = {
+      model: "MiniMax-M2.7",
+      system: [{ type: "text", text: "You are helpful." }],
+      messages: [
+        {
+          role: "user",
+          content: [{ type: "text", text: "continue" }],
+        },
+      ],
+      max_tokens: 1024,
+      output_config: {
+        effort: "medium",
+        format: {
+          type: "json_schema",
+          schema: {
+            type: "object",
+            properties: { title: { type: "string" } },
+            required: ["title"],
+            additionalProperties: false,
+          },
+        },
+      },
+    };
+
+    const result = translateRequest(
+      FORMATS.CLAUDE,
+      FORMATS.CLAUDE,
+      "MiniMax-M2.7",
+      JSON.parse(JSON.stringify(body)),
+      true,
+      null,
+      "minimax",
+    );
+
+    expect(result.output_config).toBeUndefined();
+    expect(result.messages[0].content[0].text).toBe("continue");
+  });
+
+  it("translateRequest preserves output_config for Anthropic Claude", () => {
+    const body = {
+      model: "claude-sonnet-4.5",
+      system: [{ type: "text", text: "You are helpful." }],
+      messages: [
+        {
+          role: "user",
+          content: [{ type: "text", text: "continue" }],
+        },
+      ],
+      max_tokens: 1024,
+      output_config: {
+        format: { type: "json_schema", schema: { type: "object" } },
+      },
+    };
+
+    const result = translateRequest(
+      FORMATS.CLAUDE,
+      FORMATS.CLAUDE,
+      "claude-sonnet-4.5",
+      JSON.parse(JSON.stringify(body)),
+      true,
+      null,
+      "claude",
+    );
+
+    expect(result.output_config).toEqual(body.output_config);
+  });
+
+  it("parseSSELine supports provider raw NDJSON stream lines", () => {
+    const raw = JSON.stringify({
+      model: "gpt-oss:120b",
+      message: { role: "assistant", content: "hello" },
+      done: false,
+    });
+
+    const parsed = parseSSELine(raw);
+    expect(parsed).toEqual({
+      model: "gpt-oss:120b",
+      message: { role: "assistant", content: "hello" },
+      done: false,
+    });
+  });
+
+  it("parseSSELine still supports SSE data lines", () => {
+    const parsed = parseSSELine('data: {"choices":[{"delta":{"content":"hi"}}]}');
+    expect(parsed.choices[0].delta.content).toBe("hi");
+  });
+});
diff --git a/tests/unit/usage-concern.test.js b/tests/unit/usage-concern.test.js
new file mode 100644
index 0000000..1c5fe57
--- /dev/null
+++ b/tests/unit/usage-concern.test.js
@@ -0,0 +1,69 @@
+// A3: locks toOpenAIUsage per-provider token math (claude/gemini/kiro/ollama/commandcode).
+import { describe, it, expect } from "vitest";
+import { toOpenAIUsage } from "../../open-sse/translator/concerns/usage.js";
+
+describe("toOpenAIUsage", () => {
+  it("claude: folds cache read+create into prompt, exposes details", () => {
+    const u = toOpenAIUsage(
+      { input_tokens: 100, output_tokens: 20, cache_read_input_tokens: 30, cache_creation_input_tokens: 10 },
+      "claude"
+    );
+    expect(u.prompt_tokens).toBe(140);
+    expect(u.completion_tokens).toBe(20);
+    expect(u.total_tokens).toBe(160);
+    expect(u.prompt_tokens_details.cached_tokens).toBe(30);
+    expect(u.prompt_tokens_details.cache_creation_tokens).toBe(10);
+  });
+
+  it("claude: no cache -> no prompt_tokens_details", () => {
+    const u = toOpenAIUsage({ input_tokens: 50, output_tokens: 5 }, "claude");
+    expect(u.prompt_tokens).toBe(50);
+    expect(u.prompt_tokens_details).toBeUndefined();
+  });
+
+  it("gemini: full fields, completion = candidates + thoughts", () => {
+    const u = toOpenAIUsage(
+      { promptTokenCount: 100, candidatesTokenCount: 40, thoughtsTokenCount: 10, totalTokenCount: 150 },
+      "gemini"
+    );
+    expect(u.prompt_tokens).toBe(100);
+    expect(u.completion_tokens).toBe(50);
+    expect(u.total_tokens).toBe(150);
+    expect(u.completion_tokens_details.reasoning_tokens).toBe(10);
+  });
+
+  it("gemini fallback: candidates=0 -> derive from total - prompt - thoughts", () => {
+    const u = toOpenAIUsage(
+      { promptTokenCount: 100, candidatesTokenCount: 0, thoughtsTokenCount: 10, totalTokenCount: 150 },
+      "gemini"
+    );
+    // candidates derived = 150 - 100 - 10 = 40 ; completion = 40 + 10
+    expect(u.completion_tokens).toBe(50);
+  });
+
+  it("kiro: input/output straight", () => {
+    const u = toOpenAIUsage({ inputTokens: 12, outputTokens: 3 }, "kiro");
+    expect(u.prompt_tokens).toBe(12);
+    expect(u.completion_tokens).toBe(3);
+    expect(u.total_tokens).toBe(15);
+  });
+
+  it("ollama: prompt_eval_count/eval_count", () => {
+    const u = toOpenAIUsage({ prompt_eval_count: 7, eval_count: 4 }, "ollama");
+    expect(u.prompt_tokens).toBe(7);
+    expect(u.completion_tokens).toBe(4);
+    expect(u.total_tokens).toBe(11);
+  });
+
+  it("commandcode: keeps totalTokens fallback", () => {
+    const u = toOpenAIUsage({ inputTokens: 8, outputTokens: 2, totalTokens: 99 }, "commandcode");
+    expect(u.prompt_tokens).toBe(8);
+    expect(u.completion_tokens).toBe(2);
+    expect(u.total_tokens).toBe(99);
+  });
+
+  it("unknown kind / null raw -> null", () => {
+    expect(toOpenAIUsage({}, "nope")).toBeNull();
+    expect(toOpenAIUsage(null, "claude")).toBeNull();
+  });
+});
diff --git a/tests/unit/usage-dispatch.test.js b/tests/unit/usage-dispatch.test.js
new file mode 100644
index 0000000..75096d7
--- /dev/null
+++ b/tests/unit/usage-dispatch.test.js
@@ -0,0 +1,39 @@
+// Guards the refactored USAGE_HANDLERS dispatch: unsupported → message, supported → routed.
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Stub network so handlers don't hit real APIs; each call resolves an empty 200.
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch: vi.fn(async () => ({
+    ok: true,
+    status: 200,
+    json: async () => ({}),
+    text: async () => "{}",
+  })),
+}));
+
+const load = () => import("../../open-sse/services/usage.js");
+const SUPPORTED = [
+  "github", "gemini-cli", "antigravity", "claude", "codex", "kiro",
+  "qoder", "qwen", "iflow", "ollama", "glm", "glm-cn",
+  "minimax", "minimax-cn", "vercel-ai-gateway", "grok-cli",
+];
+
+describe("usage dispatch", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("unsupported provider → not-implemented message", async () => {
+    const { getUsageForProvider } = await load();
+    const res = await getUsageForProvider({ provider: "totally-unknown" });
+    expect(res).toEqual({ message: "Usage API not implemented for totally-unknown" });
+  });
+
+  it("every supported provider routes to its handler (no fallback message)", async () => {
+    const { getUsageForProvider } = await load();
+    for (const provider of SUPPORTED) {
+      const res = await getUsageForProvider({ provider, accessToken: "t", apiKey: "k" });
+      // Routed handler must return an object and never the unsupported fallback
+      expect(res, `${provider} routed`).toBeTypeOf("object");
+      expect(res?.message).not.toBe(`Usage API not implemented for ${provider}`);
+    }
+  });
+});
diff --git a/tests/unit/venice-provider.test.js b/tests/unit/venice-provider.test.js
new file mode 100644
index 0000000..d31a0ae
--- /dev/null
+++ b/tests/unit/venice-provider.test.js
@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+
+import REGISTRY from "../../open-sse/providers/registry/index.js";
+import { PROVIDERS, PROVIDER_MODELS } from "../../open-sse/providers/index.js";
+
+describe("Venice AI provider", () => {
+  const venice = REGISTRY.find((e) => e.id === "venice");
+
+  it("is registered as an OpenAI-compatible apikey provider", () => {
+    expect(venice).toBeDefined();
+    expect(venice.category).toBe("apikey");
+    expect(venice.transport.baseUrl).toBe("https://api.venice.ai/api/v1/chat/completions");
+    expect(venice.alias).toBe("venice");
+    expect(venice.aliases).toContain("vn");
+  });
+
+  it("enables dynamic model discovery and passthrough", () => {
+    expect(venice.passthroughModels).toBe(true);
+    expect(venice.modelsFetcher).toMatchObject({
+      url: "https://api.venice.ai/api/v1/models",
+      type: "openai",
+    });
+  });
+
+  it("builds into the runtime PROVIDERS map with the openai format default", () => {
+    expect(PROVIDERS.venice).toBeDefined();
+    expect(PROVIDERS.venice.format).toBe("openai");
+    expect(PROVIDERS.venice.baseUrl).toBe("https://api.venice.ai/api/v1/chat/completions");
+  });
+
+  it("exposes its seed models (incl. the signature uncensored model)", () => {
+    const ids = (PROVIDER_MODELS.venice || []).map((m) => m.id);
+    expect(ids.length).toBeGreaterThan(0);
+    expect(ids).toContain("venice-uncensored-1-2");
+  });
+
+  it("keeps every registry id unique after adding venice", () => {
+    const ids = REGISTRY.map((e) => e.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+});
diff --git a/tests/unit/web-cookie-validation.test.js b/tests/unit/web-cookie-validation.test.js
new file mode 100644
index 0000000..960f509
--- /dev/null
+++ b/tests/unit/web-cookie-validation.test.js
@@ -0,0 +1,187 @@
+/**
+ * Unit tests for grok-web & perplexity-web cookie validation logic
+ *
+ * Covers:
+ *  - Cookie prefix stripping (sso=, __Secure-next-auth.session-token=)
+ *  - 401/403 → invalid with error message
+ *  - Non-auth responses (200, 400, 429) → valid (Cloudflare-bypass probe)
+ *  - Required browser-fingerprint headers sent to Grok
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+const originalFetch = global.fetch;
+
+// Replicates the validation logic from app/src/app/api/providers/validate/route.js
+async function validateGrokWeb(apiKey) {
+  const token = apiKey.startsWith("sso=") ? apiKey.slice(4) : apiKey;
+  const randomHex = (n) => {
+    const a = new Uint8Array(n);
+    crypto.getRandomValues(a);
+    return Array.from(a, (b) => b.toString(16).padStart(2, "0")).join("");
+  };
+  const statsigId = Buffer.from("e:TypeError: Cannot read properties of null (reading 'children')").toString("base64");
+  const traceId = randomHex(16);
+  const spanId = randomHex(8);
+  const res = await fetch("https://grok.com/rest/app-chat/conversations/new", {
+    method: "POST",
+    headers: {
+      Accept: "*/*",
+      "Content-Type": "application/json",
+      Cookie: `sso=${token}`,
+      Origin: "https://grok.com",
+      Referer: "https://grok.com/",
+      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
+      "x-statsig-id": statsigId,
+      "x-xai-request-id": crypto.randomUUID(),
+      traceparent: `00-${traceId}-${spanId}-00`,
+    },
+    body: JSON.stringify({ temporary: true, modelName: "grok-4", message: "ping" }),
+  });
+  if (res.status === 401 || res.status === 403) {
+    return { valid: false, error: "Invalid SSO cookie — re-paste from grok.com DevTools → Cookies → sso" };
+  }
+  return { valid: true, error: null };
+}
+
+async function validatePerplexityWeb(apiKey) {
+  let sessionToken = apiKey;
+  if (sessionToken.startsWith("__Secure-next-auth.session-token=")) {
+    sessionToken = sessionToken.slice("__Secure-next-auth.session-token=".length);
+  }
+  const res = await fetch("https://www.perplexity.ai/rest/sse/perplexity_ask", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "text/event-stream",
+      Origin: "https://www.perplexity.ai",
+      Referer: "https://www.perplexity.ai/",
+      Cookie: `__Secure-next-auth.session-token=${sessionToken}`,
+    },
+    body: JSON.stringify({ query_str: "ping" }),
+  });
+  if (res.status === 401 || res.status === 403) {
+    return { valid: false, error: "Invalid session cookie — re-paste __Secure-next-auth.session-token from perplexity.ai" };
+  }
+  return { valid: true, error: null };
+}
+
+describe("grok-web validation", () => {
+  beforeEach(() => vi.clearAllMocks());
+  afterEach(() => { global.fetch = originalFetch; });
+
+  it("should return valid:true when response is 200", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 200 });
+    const result = await validateGrokWeb("test-token");
+    expect(result.valid).toBe(true);
+    expect(result.error).toBeNull();
+  });
+
+  it("should return valid:true when response is 400 (auth accepted but bad body)", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 400 });
+    const result = await validateGrokWeb("test-token");
+    expect(result.valid).toBe(true);
+  });
+
+  it("should return valid:true when response is 429 (rate limited but auth ok)", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 429 });
+    const result = await validateGrokWeb("test-token");
+    expect(result.valid).toBe(true);
+  });
+
+  it("should return valid:false with error when response is 401", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 401 });
+    const result = await validateGrokWeb("bad-token");
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("Invalid SSO cookie");
+  });
+
+  it("should return valid:false with error when response is 403", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 403 });
+    const result = await validateGrokWeb("bad-token");
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("Invalid SSO cookie");
+  });
+
+  it("should strip sso= prefix from apiKey", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 200 });
+    await validateGrokWeb("sso=abc123");
+    const callArgs = global.fetch.mock.calls[0][1];
+    expect(callArgs.headers.Cookie).toBe("sso=abc123");
+  });
+
+  it("should accept raw token without sso= prefix", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 200 });
+    await validateGrokWeb("abc123");
+    const callArgs = global.fetch.mock.calls[0][1];
+    expect(callArgs.headers.Cookie).toBe("sso=abc123");
+  });
+
+  it("should POST to /rest/app-chat/conversations/new", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 200 });
+    await validateGrokWeb("token");
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://grok.com/rest/app-chat/conversations/new",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+
+  it("should send Cloudflare-bypass headers", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 200 });
+    await validateGrokWeb("token");
+    const headers = global.fetch.mock.calls[0][1].headers;
+    expect(headers.Origin).toBe("https://grok.com");
+    expect(headers.Referer).toBe("https://grok.com/");
+    expect(headers["User-Agent"]).toContain("Chrome");
+    expect(headers["x-statsig-id"]).toBeTruthy();
+    expect(headers["x-xai-request-id"]).toBeTruthy();
+    expect(headers.traceparent).toMatch(/^00-[0-9a-f]{32}-[0-9a-f]{16}-00$/);
+  });
+});
+
+describe("perplexity-web validation", () => {
+  beforeEach(() => vi.clearAllMocks());
+  afterEach(() => { global.fetch = originalFetch; });
+
+  it("should return valid:true when response is 200", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 200 });
+    const result = await validatePerplexityWeb("test-token");
+    expect(result.valid).toBe(true);
+  });
+
+  it("should return valid:false when response is 401", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 401 });
+    const result = await validatePerplexityWeb("bad-token");
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("Invalid session cookie");
+  });
+
+  it("should return valid:false when response is 403", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 403 });
+    const result = await validatePerplexityWeb("bad-token");
+    expect(result.valid).toBe(false);
+  });
+
+  it("should strip __Secure-next-auth.session-token= prefix", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 200 });
+    await validatePerplexityWeb("__Secure-next-auth.session-token=xyz789");
+    const headers = global.fetch.mock.calls[0][1].headers;
+    expect(headers.Cookie).toBe("__Secure-next-auth.session-token=xyz789");
+  });
+
+  it("should accept raw token without prefix", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 200 });
+    await validatePerplexityWeb("xyz789");
+    const headers = global.fetch.mock.calls[0][1].headers;
+    expect(headers.Cookie).toBe("__Secure-next-auth.session-token=xyz789");
+  });
+
+  it("should POST to /rest/sse/perplexity_ask", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ status: 200 });
+    await validatePerplexityWeb("token");
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://www.perplexity.ai/rest/sse/perplexity_ask",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+});
diff --git a/tests/unit/xai-oauth-service.test.js b/tests/unit/xai-oauth-service.test.js
new file mode 100644
index 0000000..83f3b4d
--- /dev/null
+++ b/tests/unit/xai-oauth-service.test.js
@@ -0,0 +1,125 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("xai/oauth service", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.restoreAllMocks();
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  it("validates discovered endpoints are https x.ai URLs", async () => {
+    const { validateOAuthEndpoint } = await import("../../src/lib/oauth/services/xai.js");
+
+    expect(validateOAuthEndpoint("https://auth.x.ai/oauth2/authorize", "authorization_endpoint")).toBe(
+      "https://auth.x.ai/oauth2/authorize"
+    );
+    expect(() => validateOAuthEndpoint("http://auth.x.ai/oauth2/authorize", "authorization_endpoint")).toThrow(
+      /must use https/
+    );
+    expect(() => validateOAuthEndpoint("https://example.com/oauth2/authorize", "authorization_endpoint")).toThrow(
+      /is not on x\.ai/
+    );
+  });
+
+  it("discovers endpoints without custom user-agent headers", async () => {
+    fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        authorization_endpoint: "https://auth.x.ai/oauth2/authorize",
+        token_endpoint: "https://auth.x.ai/oauth2/token",
+      }),
+    });
+
+    const { discoverEndpoints } = await import("../../src/lib/oauth/services/xai.js");
+    await expect(discoverEndpoints()).resolves.toEqual({
+      authorizeUrl: "https://auth.x.ai/oauth2/authorize",
+      tokenUrl: "https://auth.x.ai/oauth2/token",
+    });
+    expect(fetch).toHaveBeenCalledWith(
+      "https://auth.x.ai/.well-known/openid-configuration",
+      expect.objectContaining({ headers: { Accept: "application/json" } })
+    );
+  });
+
+  it("builds authorize URLs with CLIProxyAPI query extras", async () => {
+    const { XaiService } = await import("../../src/lib/oauth/services/xai.js");
+    const authUrl = new XaiService().buildXaiAuthUrl(
+      "http://127.0.0.1:56121/callback",
+      "state-1",
+      "challenge-1",
+      "https://auth.x.ai/oauth2/authorize"
+    );
+    const parsed = new URL(authUrl);
+
+    expect(parsed.origin + parsed.pathname).toBe("https://auth.x.ai/oauth2/authorize");
+    expect(parsed.searchParams.get("response_type")).toBe("code");
+    expect(parsed.searchParams.get("client_id")).toBe("b1a00492-073a-47ea-816f-4c329264a828");
+    expect(parsed.searchParams.get("redirect_uri")).toBe("http://127.0.0.1:56121/callback");
+    expect(parsed.searchParams.get("code_challenge")).toBe("challenge-1");
+    expect(parsed.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(parsed.searchParams.get("state")).toBe("state-1");
+    expect(parsed.searchParams.get("nonce")).toMatch(/^[a-f0-9]{32}$/);
+    expect(parsed.searchParams.get("plan")).toBe("generic");
+    expect(parsed.searchParams.get("referrer")).toBe("cli-proxy-api");
+  });
+
+  it("generates dashboard auth data with CLIProxyAPI PKCE size and discovered endpoints", async () => {
+    fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        authorization_endpoint: "https://auth.x.ai/oauth2/authorize-from-discovery",
+        token_endpoint: "https://auth.x.ai/oauth2/token-from-discovery",
+      }),
+    });
+
+    const { generateAuthData } = await import("../../src/lib/oauth/providers.js");
+    const data = await generateAuthData("xai", "http://127.0.0.1:56121/callback");
+    const parsed = new URL(data.authUrl);
+
+    expect(data.codeVerifier).toHaveLength(128);
+    expect(parsed.origin + parsed.pathname).toBe("https://auth.x.ai/oauth2/authorize-from-discovery");
+    expect(parsed.searchParams.get("redirect_uri")).toBe("http://127.0.0.1:56121/callback");
+    expect(parsed.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(parsed.searchParams.get("plan")).toBe("generic");
+    expect(parsed.searchParams.get("referrer")).toBe("cli-proxy-api");
+  });
+
+  it("exchanges dashboard codes against the discovered xAI token endpoint", async () => {
+    const fetchMock = fetch;
+    fetchMock
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          authorization_endpoint: "https://auth.x.ai/oauth2/authorize",
+          token_endpoint: "https://auth.x.ai/oauth2/token-from-discovery",
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          access_token: "access-token",
+          refresh_token: "refresh-token",
+          expires_in: 3600,
+        }),
+      });
+
+    const { exchangeTokens } = await import("../../src/lib/oauth/providers.js");
+    const tokens = await exchangeTokens(
+      "xai",
+      "auth-code",
+      "http://127.0.0.1:56121/callback",
+      "verifier-1",
+      "state-1"
+    );
+
+    expect(fetchMock.mock.calls[1][0]).toBe("https://auth.x.ai/oauth2/token-from-discovery");
+    expect(fetchMock.mock.calls[1][1].body.get("grant_type")).toBe("authorization_code");
+    expect(fetchMock.mock.calls[1][1].body.get("code")).toBe("auth-code");
+    expect(fetchMock.mock.calls[1][1].body.get("code_verifier")).toBe("verifier-1");
+    expect(tokens).toMatchObject({
+      accessToken: "access-token",
+      refreshToken: "refresh-token",
+      expiresIn: 3600,
+    });
+  });
+});
diff --git a/tests/unit/xai-tokenRefresh.test.js b/tests/unit/xai-tokenRefresh.test.js
new file mode 100644
index 0000000..48cb278
--- /dev/null
+++ b/tests/unit/xai-tokenRefresh.test.js
@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from "vitest";
+
+// We can't easily import the open-sse switch logic without real PROVIDERS config,
+// so verify the wrapper function shape directly via dynamic import.
+
+describe("xai/token-refresh wrapper", () => {
+  it("refreshXaiToken module loads without throwing", async () => {
+    // Just verify the file imports cleanly. The actual wrapper is internal.
+    const mod = await import("../../open-sse/services/tokenRefresh.js");
+    expect(typeof mod.refreshTokenByProvider).toBe("function");
+    expect(typeof mod.formatProviderCredentials).toBe("function");
+  });
+
+  it("formatProviderCredentials returns Bearer-shape for xai", async () => {
+    const mod = await import("../../open-sse/services/tokenRefresh.js");
+    const out = mod.formatProviderCredentials(
+      "xai",
+      { apiKey: "k", accessToken: "t", refreshToken: "r" },
+      null
+    );
+    expect(out).toEqual({ apiKey: "k", accessToken: "t" });
+  });
+
+  it("refreshTokenByProvider returns null when refreshToken missing", async () => {
+    const mod = await import("../../open-sse/services/tokenRefresh.js");
+    const out = await mod.refreshTokenByProvider("xai", { refreshToken: "" }, null);
+    expect(out).toBeNull();
+  });
+
+  it("refreshTokenByProvider returns expiresIn for refreshed xai tokens", async () => {
+    vi.resetModules();
+    vi.doMock("../../src/lib/oauth/services/xai.js", () => ({
+      XaiService: class {
+        async refreshAccessToken(refreshToken) {
+          return {
+            access_token: "new-access",
+            refresh_token: `${refreshToken}-rotated`,
+            expires_in: 900,
+            id_token: "id-token",
+          };
+        }
+      },
+    }));
+
+    const mod = await import("../../open-sse/services/tokenRefresh.js");
+    const out = await mod.refreshTokenByProvider(
+      "xai",
+      { refreshToken: "old-refresh" },
+      null
+    );
+
+    expect(out).toEqual({
+      accessToken: "new-access",
+      refreshToken: "old-refresh-rotated",
+      expiresIn: 900,
+      idToken: "id-token",
+    });
+    expect(out).not.toHaveProperty("expiresAt");
+
+    vi.doUnmock("../../src/lib/oauth/services/xai.js");
+    vi.resetModules();
+  });
+});
diff --git a/tests/vitest.config.js b/tests/vitest.config.js
new file mode 100644
index 0000000..d53d85e
--- /dev/null
+++ b/tests/vitest.config.js
@@ -0,0 +1,29 @@
+import { defineConfig } from "vitest/config";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: true,
+    include: ["**/*.test.js"],
+    // Don't scan into git worktrees nested under .claude/ — they carry their
+    // own copies of the test files but lack an installed node_modules (open-sse,
+    // etc.), which makes provider imports fail during collection.
+    exclude: ["**/node_modules/**", "**/.claude/**", "**/dist/**"],
+    // Allow many it.concurrent cases (real provider smoke runs ~50 providers in parallel)
+    maxConcurrency: 60,
+    // Suppress noisy console output from handlers under test
+    silent: false,
+  },
+  resolve: {
+    // Use array form so subpath aliases (e.g. "@/lib/db/index.js") resolve correctly.
+    alias: [
+      { find: /^open-sse\//, replacement: resolve(__dirname, "../open-sse") + "/" },
+      { find: "open-sse", replacement: resolve(__dirname, "../open-sse") },
+      { find: /^@\//, replacement: resolve(__dirname, "../src") + "/" },
+    ],
+  },
+});